add backend ability to scope API keys to a particular Role

[czue]

#28388

SUMMARY

This adds backend support for attaching a role_id to an API key, and then limiting the access of that key to the associated roles.

I ended up going with Roles as the mapping layer because it was the easiest way to bundle a collection of permissions, and also because it will be the easiest thing to support in the (yet to be added) UI. Any other model would have required either very granular scopes (at the permission level) or creating PermissionCollection abstraction that is basically the exact same thing as a Role. This way we can leverage all the Role editing stuff we have and just add a dropdown in the API key UI.

You can review either way (might be easier all at once). The change itself is rather small and the meat of it is in 854638d. I'm open to other ways of rolling it out that are backwards compatible and safe. Most of the rest of the PR is tests and fixes related to that change.

As advertised on the CEP, this only affects tasty pie APIs and those that use either RequirePermissionAuthentication or LoginAndDomainAuthentication, though am hoping to extend support in other places.

RISK ASSESSMENT / QA PLAN

It's core authentication code so there is always a risk there. I added substantial test coverage and manually tested various APIs with various types of auth locally. Due to they way it is implemmented, this should not affect any non-API-based auth in any way.

There is also a small DB migration to add role_id to the API key model

PRODUCT DESCRIPTION

Not user-facing yet, but hopefully will be soon.

[ctsims]

This approach seems consistent to me.

Just as a check for my understanding, the assumption is that for "mixed auth" endpoints like

commcare-hq/corehq/apps/case_importer/views.py

Line 277 in 20c3962

@api_auth

Any required permissions check would use the universal "require_api_permission" check which will fall back to the normal has_permissions logic if there's no API key, rather than bifurcating, right? Am wondering whether it's possible to chain the @api_access decorator in some way that lets future permissions requests know to apply the api permissions layer 2 check without forcing both a

@require_can_edit_data
and an
@require_can_edit_data_api

wrapper around require_permission and require_api_permission respectively,

[czue]

@ctsims I'm hoping the eventual future state will be that you add @require_can_edit_data to a view, and then the logic goes something like:

if authed_with_api_key():
  ensure_api_key_has_right_permission()
else:
  ensure_user_has_right_permission()

Is that the same as you're suggesting?

(This is already how it works with the APIs in this PR, but I didn't yet touch the @api_auth decorator.)

[ctsims]

@czue Yeah, that's the same as what I'm suggesting, just making sure that my reading was correct that this approach wouldn't extend the need to differentiate between the permissions granted by the allowable auth types.