User Role and Permission Management

[nrjadkry]

As we are in the verge of implementing user roles and permissions in fmtm. This GitHub discussion is an open forum to dive into the world of user role management. Our goal is to collectively refine the roles assigned within the system for optimal efficiency, access control, and collaboration.

User Roles Overview:

1. Super Admin: Highest level of access and control over the entire system.

2. Organisation Admin: Manages settings and permissions at the organizational level.

3. Project Admin: Oversees settings and permissions specific to individual projects.

4. Associate Project Admin: Assists Project Admins in managing project-specific configurations.

5. Validator: Responsible for validating and ensuring data accuracy.

6. Mapper: Focuses on the creation and editing of data within projects.

What are the other possible user roles?

This link has the details of the user roles and permission drafted.

https://docs.google.com/spreadsheets/d/1crWztvXvuewE8Zv-qxbv0t_-eYHUqSlrJQgeto8kmf4/edit#gid=1497569844

Discussion Point

How do we handle the user permissions from the backend, do we maintain a seperate table controlling those user permissions.
Do the backend provide the permissions for controlling the UI elements or it is okay if we control them from the frontend itself.
We should also think about the object level permissions.

Potential Solution 1

We can maintain a table with the permissions added for different roles and same for the object level permission. For example: Whenever a user is assigned to a NAXA organisation as an organisation admin. We store that as a row in the database table.

[manjitapandey]

we can control few features from frontend like managing users and providing access to edit projects through buttons which would only be available for roles upto project manager.

[nrjadkry]

There is already an existing issue for discussing user roles and permissions.

• Implement support for roles in the backend #243

[spwoodcock]

I think the proposed permission levels are good.

Authentication

Related to this we need to consider a proper authentication mechanism.

Current

• We currently authenticate once with OSM via osm-login-python on the backend.
• Essentially this is a temporary login that does not persist (authentication is done every time the /me endpoint is called).
• The user details are returned, and the only form of 'persistence' we have is keeping the user details (usename, user id, picture) stored on the frontend via local storage.

Future Requirements

• To persist the user login, we need to use a cookie.
• The cookie should be httpOnly, secure, domain specific.
• We have two options
  • Store the OSM JWT access token in the cookie, then authenticate with OSM for each endpoint.
  • Use our own JWT for authentication that is provided on successful login via OSM (reducing calls to OSM).

Authorisation

Once the user is authenticated, we can gather their authorisation details.

Database Structue

• We should consider options, but the approach I would suggest for now is using a link table.
• User_Table <--> User_Role_Table <--> Role table
  • User_Role_Table would link the user to a role, for a specific project.

FastAPI (Backend) Implementation

• The authorisations for a user should be extracted.
• We should use Depends dependency injection to manage auth on endpoints.
• The levels described above are mostly in a hierarchy order.
• The minimum required auth level is appended to an endpoint via Depends.
  • This prevents a huge amount of code duplication.
  • All auth logic is in a separate file and only accessed via Depends.
• If the user does not have the required auth level, access to the endpoint is blocked.

Frontend

• Restriction of URLs / pages is much easier than restricting specific components on a page.
• Code is client-side, so in theory they can manipulate it however they like. Disabled button can be easily re-enabled.
• The auth should be handled mostly via the backend, so either if frontend restriction fails, the user cannot trigger an endpoint.

I will update this comment as needed

[spwoodcock]

Conditional rendering of components can be done if needed (although view / URL based restriction is easier and cleaner IMO).

I think we should probably update the /me/ endpoint to also include the role in the response.

[varun2948]

yeah adding the role would make it easier to control roles instead of again hitting another API.
Are we not going to have permission for smaller things like maybe someone could add user, someone couldn't;
we are going to look out for roles only ? not specific permission right ?

[spwoodcock]

Until we have a good reason for fine grained permissions, let's stick with roles & keep it simple 😃

[spwoodcock]

I just looked at adding the role to the response.

The issue is there are two types of roles.

• One is assigned to a user: admin, mapper, read_only.
• One is for a user/project pair, so to provide this we also need to send the project_id in the request.

I will add the site-wide user specific role to the response on the /me endpoint.
This will pretty much just let us know if the user is admin, a standard user, or is blocked.

For the project specific role, we need to determine that via an API call unfortunately, as it's dynamic to whatever project we are accessing.

[spwoodcock]

role is now returned in the response from /me.
ADMIN=1
MAPPER=0
READ_ONLY=-1

You can create a reverse enum on the frontend 👍

[spwoodcock]

Currently we have

    'MAPPER',
    'ADMIN',
    'VALIDATOR',
    'FIELD_ADMIN',
    'ORGANIZATION_ADMIN',
    'READ_ONLY'

Associated Project Admin

As for the Associate Project Admin, is that what we decided on finally?
I thought we suggested Field Admin instead, but have forgotten now.
I actually quite like Associated Project Admin - it's quite clear.

Read Only

TM has a READ_ONLY role, for users that are blocked for example. I think we should use it too.

[spwoodcock]

I made a start here: #1094

This show one way we could implement the roles, giving us a base to develop further and discuss in our next team meeting.

[spwoodcock]

I'm hoping we can get by with simple roles and a hierarchy.

If we need more fine grained permission control for roles, we could do something like this: https://itnext.io/fastapi-jwt-authentication-with-scope-permissions-per-route-a42457fc85ca

[nrjadkry]

This link is only for members. 😄

[spwoodcock]

You just need to sign up, it's quick

[nrjadkry]

A quick question as @spwoodcock mentioned a roles hierarchy:
Who has the permission to create an organisation? Is it only to super admin ?

[spwoodcock]

Copying my comment from a PR discussion

It's a bit of a pain to need one person (admin) to approve all organisations.

Not a problem for organisation specific instances of FMTM, but for the HOT maintained one it's extra work and may put off users if it's a slow process (we also need a mechanism for org admins to request creation too).

Two ideas:

• Create a default other organisation, so that users can get started making a project there. Anyone not in an organisation can use this, plus we could possibly move a project created here to an organisation once it is approved and created by super admin.
• Allow anyone to create a new organisation, then that person immediately becomes org admin (as the first user in the org).

while writing this, I also thought, we probably want to also create the super admin user automatically on first FastAPI start (via the entrypoint).

[spwoodcock]

Extra info

@susmina94

Super admin vs web admin

• I think the super admin role is theoretical
  • They are the person that created the FMTM instance and has access to the databases / infrastructure.
  • They don't have a role assigned in the database specifically.
• What we have called super admin until now is actually web admin.
  • These users are assigned user.role=ADMIN in the database.
  • They have access to all routes via the API / frontend.

Organization admin flow

1. Org admin clicks 'create new organization' button.
2. Redirected to login via OSM before they can access the form (this creates a user in the FMTM database).
3. User fills out a form and submits. The submission includes their OSM User ID & an email is sent to web admin.
4. Web admin approves
   • We could probably do this via an email link to an API endpoint.
   • We need a simple endpoint that takes a user OSM ID and organization details from the form as query parameters.
   • The link in the email is like api.fmtm.hotosm.org/organization/create_admin?osm_id=4645&name=naxa&url=https://naxa.com.np...
   • The only issue I can see doing this is how to include the organization image? Perhaps as an attachment in the email to admin??
5. The organization is created, with the user being assigned role organization admin.

Project editing

• The project detail page needs an edit button.
• There is a tab for editing users and roles, only available to org admins at the start.

Project creation (org admin vs project manager)

• Only org admins can create projects.
• To the life of the org admin easier, we want the project manager to create projects.
• To do this, we create a flow where the org admin can assign an OSM user to manage their project (in the first page of project creation).
  • The calls the create_project endpoint.
  • We need to add an extra param to the endpoint to accept the osm user id to assign project manager role.
• The project manager then logs in and sees the project on the dashboard.
  • The project is displayed with minimal info / is a stub.
• When the project manager clicks the project, then are authenticated and can continue with the creation workflow.
  • To determine this, we check if the project has a bbox / location.
    • If it does, the project is already created, direct to project detail page.
    • If it doesn't, then continue the project creation flow.

[spwoodcock]

• With this in mind, the first approach using user_role for org admins doesn't work well.
• We found that the organization_managers table was included in FMTM from TM 🤦‍♂️
• We can use that instead.

[spwoodcock]

Prompt that we need to discuss the MAPPER role in FMTM.

OSM vs regular users

• Based on field feedback we have determined that not every user is necessarily an OSM user.
• We need to account for the use case that anyone can go an project page on FMTM and generate a QR code for mapping.
• I think organisation managers and project managers should always be OSM users - we can enforce this to make our lives easier @ivangayton is that ok?
• Then we can potentially remove the role of MAPPER entirely, as that is the default for all users (it is still present in users.role field as MAPPER by default anyway).

Possible Idea

• Remove requirement for any login at all from:
  • Frontend: home page, project page.
  • Backend: listing projects, displaying specific project.
  • Should we also remove the auth for updating the task_status? Having a POST endpoint open to the public is not ideal. Any thoughts?
  • Are there other endpoints or frontend pages the user may need to access without login?
• Remove role of MAPPER from user_roles.
• If a user creates a QR code without being logged in, we provide the org or project manager OSM username for the submission (not ideal, but no other way).
• If the project is private, prevent public access.
• If the user has role: VALIDATOR and above, they can access other specific pages and endpoints too.

@susmina94 @manjitapandey @robsavoye @nrjadkry @Sujanadh @varun2948 @NSUWAL123

Edit: scratch the idea of removing the mapper role, as we need it for private projects still...

[manjitapandey]

We already have project cards page(homepage) available for every users irrespective of login requirement.
However, Removing the login requirement may cause difficulties on determining task activities as per now, we are providing the list of tasks status changes (along with who did the change) to the users.
also are we providing them the access for downloading tasks, forms or data extracts?
there are other features too which a login mapper can access non login user doesn't like viewing the submissions, downloading it and downloading mbtiles etc.
Do you think removing mapper role will be good thing to do?

[spwoodcock]

There is a distinction here between being logged in and having a role of mapper for a project.

We already have the ability to put routes behind a login requirement.

I'm not saying open all routes up like submissions etc - those can require login.

But the specific routes that are required to view a QR code and actually map should not require login (for public projects).

Private projects are a different thing, so perhaps we actually need the mapper role specifically for private project access as a mapper

[robsavoye]

Here's another thought on roles. TM has been incorporating OSM Teams, and teams have roles in projects different than users. I doubt FMTM mappers would use OSM Teams to be honest, however, I do see possible field mapping teams. We already see this, often a few mappers will map a task together for mutual tech support after training. I could see FMTM teams that have little to do with OSM teams. So in TM, their are team roles, and user roles, and they are different, although I'd like to merge them into a single Roles Enum.

I think of this, cause right now I'm working on project & team support in tm-admin. Do we think in the future we'll want FMTM field teams ? If so, we need to sort out the roles between TM and FMTM to be consistent.

[manjitapandey]

I agree with needing the teams on FMTM for future. Since for private projects, it would be so easier for project managers to assign a team rather than assigning each individuals everytime.

[spwoodcock]

The distinction here is public and private projects.

Teams would be useful for private project for sure. Perhaps there could also be a team of validators assigned to public projects too?

Our dilemma is how can we not require login for private projects, if the mappers for example works for a census bureau and is not an OSM user, but the data still needs to be private?

Should we enforce OSM registration for private projects to make our lives easier and their lives more difficult?

If we don't want to do this, the only solution I can see to this for now is to provide other login methods:

• We could have another OAuth login provider, which is pretty easy to do, such as Google. The advantage here is that we capture at least some user information to identify them.

• We could have a simple passwordless based login, where login tokens are emailed to the user, but we capture no user information other than email.

Edit: considering this more, is signing up to OSM any worse than signing up to another platform? I don't see it as much of a barrier & worth the technical loopholes required to bypass. If the project is private, I think we should enforce OSM login personally. This might encourage orgs to create more public projects anyway (if the mapping process is easier)

[robsavoye]

Kristen found out a long time ago that having new users sign up for an OSM account for mobile field data collection was actually a big impediment, and took a ridiculous amount of time. You wouldn't think this would be the case, but imagine having a group of 30 people trying to do this with poor connectivity.

[spwoodcock]

Update to the above comment: we already decided to go ahead with optional email based sign up (+osm) in other threads - I forgot to update the discussion here 👍

The rationale was exactly as Rob is saying, that OSM is a barrier to some. Many mapping communities are entirely outside OSM, but are very competent and want to use FMTM.

[spwoodcock]

Based on in person discussion with the team, this is the current structure of roles on FMTM:

User Specific Roles

Defined in the db under users.role.

• READ_ONLY = write access blocked (i.e. banned)
• MAPPER = default for all
• ADMIN = super admin with access to everything (also called Web Admin in some docs - the admin/web admin distinction has been dropped).

Organisation Roles

Defined in the db under organisation_managers join table, linking UserID:OrgID to grant manager permission.
(in tm-admin, this may be moved from a table to a single field in the user table).

Project Specific Roles

Defined in the db under user_roles join table, linking UserID:ProjectID:Role to grant a user specific permission for a project.
(in tm-admin, this may be moved from a table to a single field in the user table).

• MAPPER = default for all
• VALIDATOR = can validate the mappers output
• FIELD_MANAGER = can invite mappers and organise people
• ASSOCIATE_PROJECT_MANAGER = helps the project manager, cannot delete project
• PROJECT_MANAGER = has all permissions to manage a project, including delete

Incorporating Tasking Manager Teams

• Tasking Manager has the concept of Teams (in TM this is OSM Teams, a feature that FMTM will not need).
• However, FMTM may possibly require mapping teams, so we can reuse the database fields for this.
• In FMTM, projects have a one-to-many relationship to users:
  • Many individual users can be associated with with a project, having a specific access role.
  • This mapping could also be valid for project:team, where an entire team may have MAPPER or VALIDATOR permission.
  • So in the future FMTM could theoretically incorporate teams without any change to the db structure. Permissions are granted on a team level, moving the project:user mapping to a project:team mapping.
• In summary: FMTM should be compatible with the TM schema.

Mapping Teams

• It is still undecided if the concept of mapping teams is a useful one.
• It doesn't work as well as it does in Tasking Manager, where remote teams can work on multiple projects around the world.
• Mappers in one city and unlikely to map another city.
• However, given the size of the city/area, it may be useful to subdivide the into multiple projects and assign mapping teams to a project.
• In summary, we will likely implement this in future only if we see it as adding value / it's a requested feature from project managers.

Is this summary correct @susmina94 @manjitapandey feel free to correct me anywhere
Also cc @robsavoye who is working on roles in tm-admin currently.

[robsavoye]

TM has two sets of roles, user roles and team roles. Right now I'm using a jsonb column ie,.. {"team_id": id, "role": FOO} for example. Experience has shown that field mappers often form informal teams. They'll be done training, but then a few people will map together for mutual support.

[spwoodcock]

So the jsonb could substitute user id with team id without an issues, to map a team with a project role instead if a user 👍

For informal teams, we need to decide if this is something worth tracking. If they map once for a project, but then don't map in the same configuration for another project, then teams aren't very useful.

If they keep the configuration the same, I.e. are a more formalised team across projects, then it could be worth it.

[robsavoye]

a field mapping project may last a week or more, but other than mutual support, it's a bit of a social media thing. Often sometimes there will be several universities involved, each would be a team. In that case it'd be handled by organization, but since that table has no concept of member, it'd have to be a team. For FMTM this may not be that useful, so it's good we're discussing it.

[robsavoye]

Here's a shot at a simple config file to define roles for FMTM. By default, anyone can view any public project. This is a gross simplification of the spreadsheet.

• mapper:

  • download

• validator:

  • modify

• field_manager:

  • modify

• project_manager:

  • create
  • delete
  • upload

• associate_manager:

  • modify
  • upload

• org_admin:

  • create
  • modify
  • upload

• super_admin:

  • create
  • modify
  • delete
  • upload

[robsavoye]

I'm not sure is SUPER_ADMIN is really needed, because if you have direct access to the database, you probably have root access anyway, so it's not really needed in FMTM.

[spwoodcock]

I'm inclined to agree & thought the same before.

We encountered one use case when the admin role is useful however: organisation approval.

It's much nicer user experience to approve organisations via an API / frontend, instead of having to delve into the DB!

[robsavoye]

Hum, if the super admin is only to create an organization, maybe we need to think of a simpler way to do that.

[spwoodcock]

(copied from Slack)
Based on discussion today, I can foresee needing 4 project access levels:

• Public: anyone contribute, anyone view
• Private: restricted contribution, restricted viewing
• Invite only: restricted contribution, anyone view
• Sensitive: anyone contribute, restricted viewing

@manjitapandey