Add basic user role support to backend

[spwoodcock]

What type of PR is this? (check all applicable)

• 🍕 Feature
• 🐛 Bug Fix
• 📝 Documentation Update
• 🎨 Style
• 🧑‍💻 Code Refactor
• 🔥 Performance Improvements
• ✅ Test
• 🤖 Build
• 🔁 CI
• 📦 Chore (Release)
• ⏩ Revert

Related Issue

Fixes #243

Describe this PR

This PR anticipates the merge of #1091 ✅ as it relies on the auth.
Also anticipates merge of #1096 ✅.

As described in discussion #1083 we are in the process of figuring out user roles.

I have implemented a basic configuration as such (this can change as needed):

class UserRole(IntEnum, Enum):
    """Available roles assigned to a user site-wide in FMTM.

    Can be used for global user permissions:
        - READ_ONLY = write access blocked (i.e. banned)
        - MAPPER = default for all
        - ADMIN = super admin with access to everything
    """

    READ_ONLY = -1
    MAPPER = 0
    ADMIN = 1


class ProjectRole(IntEnum, Enum):
    """Available roles assigned to a user for a specific project.

    Invitation is required for a MAPPER to join a project.
    All roles must be assigned by someone higher in the hierarchy:
        - MAPPER = default for all (invitation required)
        - 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
        - ORGANIZATION_ADMIN = has project manager permissions for all projects in org
    """

    MAPPER = 0
    VALIDATOR = 1
    FIELD_MANAGER = 2
    ASSOCIATE_PROJECT_MANAGER = 3
    PROJECT_MANAGER = 4
    ORGANIZATION_ADMIN = 5

Above I have divided roles into two types.

• UserRole is one of three types and is used for site-wide permissions.
• ProjectRole is related to project specific permissions.

Next Steps

• Implement the remaining auth levels.
• Add to endpoints as required.
  • UserRole probably won't be used much, except for granting site-wide admin access or blocking users.
  • ProjectRole endpoints will require the project_id to passed as a param (as part of the dependency injection).

Examples:

@router.get("/superadmin/")
async def superadmin(
    db: Session = Depends(database.get_db),
    user: AuthUser = Depends(super_admin),
):
    return user

@router.get("/validator/")
async def validator(
    db: Session = Depends(database.get_db),
    user: AuthUser = Depends(validator),
):
    return user

Checklist before requesting a review

• 📖 Read the FMTM Contributing Guide: https://github.com/hotosm/fmtm/blob/main/CONTRIBUTING.md
• 📖 Read the FMTM Code of Conduct: https://github.com/hotosm/fmtm/blob/main/CODE_OF_CONDUCT.md
• 👷‍♀️ Create small PRs. In most cases, this will be possible.
• ✅ Provide tests for your changes.
• 📝 Use descriptive commit messages.
• 📗 Update any related documentation and include any relevant screenshots.

[optional] What gif best describes this PR or how it makes you feel?

[nrjadkry]

1. I think we need to login_required function for invalid access-token. As of now, it throws an error, if invalid access-token is passed.
2. You have removed organisations from user role table. We might need to have a user having an organisation level clearance, who will have all the access to every projects within that organisations. My thought is we need to save that data in the db too. What do you think?

[spwoodcock]

1. Excellent find - I'll make a minor commit to handle that.
2. My thinking was that a project can only be in one organization, so the information is redundant in user_roles, as it is already present in the project table. But you are completely right, for the organization_admin role, we actually need the organization_id present in the user_roles table.

Either project_id is used or organization_id, so we could do one of:

• convert project_id --> id and use the field for the project or org id, depending on what the role is.
• add organization_id back in, and use one or the other.

Then in roles.py we we make org_admin we would still be receiving a project_id from and endpoint, so would first need filter DbProject to get the org_id, then filter DbUserRole to check if they are org admin for that org.

[nrjadkry]

I think we need to add organization_id back in.
My guess is only super admin can create an organisation and then Organization admin role can be assigned to the users, probably by super admin only.
It seems that, in the beginning, the organization may not have any projects. Then, only assigned organisation admin can create a project within that organisation.
In this case, backtracking from project might not be feasible.

[spwoodcock]

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

Not a problem for organisation specific instances, 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).

Could we possibly allow anyone to create a new organosation, then that person immediately becomes org admin (as the first user in the org). It's not a perfect solution, so perhaps there are other ideas too.

[spwoodcock]

Perhaps part of the solution is to have an organization called other that is generated by default (along with the super admin being automatically generated on first start).

Then an user that wants to make a project, but does not have an organization, can get started and create one in the other org (the project could perhaps be moved if they request a organization be made for them too).

[nrjadkry]

Hi @spwoodcock
What is the purpose of this function?
Does this check if the user is super_admin or not? If that is the case, we might need to do something like
user.role == UserRole.ADMIN after we get the user from db.
How does this work?

[spwoodcock]

Doesn't this line do that?

fmtm/src/backend/app/auth/roles.py

Line 55 in 35eaa0d

match = db.query(DbUser).filter_by(id=user_id, role=UserRole.ADMIN).first()

I definitely could have got something wrong here though - thanks for the sanity check!

[nrjadkry]

@spwoodcock my understanding is that this line filters data from user role with id=user_id and role=admin.
But, we need to do this.

user_role = db.query(DbUser).filter_by(id=user_id,).first().role

if user_role == UserRole.ADMIN:
    return True
else:
    return False

[spwoodcock]

They are basically the same thing.

The line further down does a check if not match:.

• If no user with the user id and role admin exists, then return a HTTPException.
• If a user exists and has the role admin, then continue to return the user details.

Does that make sense?

[nrjadkry]

Can a user be a project admin in one project and be just a mapper in other. Likewise, an organisation admin in one organisation, project admin in the project of some other organisation and just a mapper for another?

If this can be true, we might need to think differently?

[spwoodcock]

Yes they can definitely be all of the above.

I have divided roles into two types:

UserRole:

• One of three types and is used for site-wide permissions.
  • ADMIN (super admin)
  • MAPPER (most users)
  • READ_ONLY (write access blocked)
• This is used for user.role in the database.

ProjectRole:

• Related to project specific permissions.
• Stored in user_roles link table, with the project_id and user_id being a composite primary key.
  • This means the user can multiple roles across projects (multiple entries in the table).
  • BUT, can only have one role within a project.
• This is where we define the roles like org admin, project admin, validator, etc.

The role types are used differently.
The role user.role is only used to designate super admin & block users.
The roles under user_roles are specific to projects.

[spwoodcock]

Should we merge this, so we can get the linting fixes in, then continue in another PR?

[nrjadkry]

@spwoodcock let's merge this. If we encounter any issues or lag, then we can obviously fix them in another PR.