User-Managed Access

User-Managed Access (UMA 2.0) is an OAuth-based access management protocol standard for managing authorization to resources. It's the main security standard used by the security framework to control accessibility and permissions to datasets. Since the scope of the project requires policy enforced access to resources, access management is a crucial aspect to consider. It is important to properly identify Data Stewards (Data Managers) who can manage permissions to their resources and define who can access their resources (Data Consumers). UMA is a protocol that enables this kind of management, by giving users responsible for managing data the ability to regulate access. These resources may be anything from AIRR-seq data sets, a study, or even a whole iReceptor Plus repository.

Each piece of data to protect must be related to a resource on the Authorization Server. When trying to access a resource there are two possible ways of doing it:

• Listing: Data requested by type as a list
• By ID: Data requested by type and by ID (returns only one element)

By default, a user has access to nothing. When a resource owner gives a user access to a resource, a new permission will be created, connecting a resource with a user.

                              security
researcher        Keycloak    framework    repository
  |                  |          |             |
  |  OpenID Connect authentication            |
  |--- (1) --------->|          |             |
  |  OpenID Connect token       |             |
  |<-- (1) ----------|          |             |
  |                  |          |             |
  |  no RPT token    |          |             |
  |--- (2) -------------------->|             |
  |                  |Request permissions     |
  |                  |<-- (3) --|             |
  |                  |Permissions ticket      |
  |                  |--- (3) ->|             |
  |  permissions ticket         |             |
  |<-- (4) ---------------------|             |
  |  permissions ticket, OIDC token           |
  |--- (5) --------->|          |             |
  |       validation |          |             |
  |       +-- (6) -->|          |             |
  |       +-- (6) -->|          |             |
  |  RPT token       |          |             |
  |<-- (7) ----------|          |             |
  |                  |          |             |
  |  RPT token       |          |             |
  |--- (8) -------------------->|             |
  |                  |RPT introspection       |
  |                  |<-- (9) --|             |
  |                  |RPT metadata            |
  |                  |--- (9) ->|             |
  |                  |          | validation  |
  |                  |          |<- (9) -+    |
  |                  |          |<- (9) -+    |
  |                  |          | forwarded request
  |                  |          |--- (10) --> |
  |                  |          | resource(s) |
  |                  |          |<-- (10) --- |
  |  resource(s)     |          |             |
  |<-- (11) --------------------|             |
  |                  |          |             |

1. The researcher authenticates using the OpenID Connect protocol with Keycloak (which may involve authenticating with a third party OIDC IdP) and is issued an Access Token. This token contains an ID to uniquely identify the researcher and some additional claims that prove that the token holder is the user is legitimate.
2. The researcher attempts to access a resource by sending a request without an RPT to the resource server which is protected by the security framework (access is denied).
3. The security framework sends a request to the authorization server (Keycloak), specifying the resource ID (a study, for example) and the scopes (associated with an access level) and returns a permission ticket. The security framework determines the access to a request into the corresponding resources and scopes by keeping an internal database that maps between a resource ID and the corresponding UMA resource ID present in Keycloak.
4. The security framework then denies access and returns the location of the authorization server along with a permission ticket that works as a pointer to the resource that the researcher tried to access.
5. The researcher's client needs to request an RPT token from the authorization server by sending the permission ticket from the previous step, along with the OIDC Access Token from step 1, and optionally any additional scopes the researcher wants access to.
6. Keycloak validates the token and the ticket, finds the resources and their scopes, in order to determine if the researcher has been given permission to access them. It then performs an intersection between the granted resources and scopes and the requested resources and scopes as specified in the ticket.
7. Keycloak returns an RPT token which is the resulting intersection of the resources and their scopes, that allows the client to access these resources. If the intersection is null no token is returned.
8. The researcher attempts to access the same resource from step 2 using the new RPT token.
9. The security framework validates the token and obtains the associated scopes and resources for the token from the authorization server, which also involves translating the UMA resource IDs to the study IDs, and validates that the RPT token grants access to the requested resource.
10. If validation passes, the security framework gathers the resource from the repository.
11. The resource is returned to the researcher.

To see UMA in action, check out How to use a secured API: Authorization

Resources are the representation of what needs to be protected by the authorization service. When a resource is requested to the Resource Server, the server transforms/drills down the requested entity to match the resources on Keycloak, allowing the comparison between them.

When a user tries to access a given resource, the client will send a request to the Resource Server without any Authorization token. The Resource Server will then process the respective resource name and query the Authorization Server for a ticket representing the access to said resource. The ticket is returned to the client.

When it receives a ticket, the client will send a request to the Authorization Server, which will assess whether the user has permission to access the resource. If the user has access, an RPT is issued with the permission for the requested resource. If the user doesn't have access, an unauthorized response is sent, and the resource owner is notified of the request attempt and can opt to allow or deny the access to that resource to the requesting user. If the resource owner allows access to the resource, the next time the user requests the same resource, an RPT will be issued allowing said access.

When successfully issued with an RPT token, the user repeats the request from “Ticket request”, only this time the RPT token will be sent as Bearer. When the Resource Server receives a request with the RPT it will query the Authorization Server for its introspection and will, once again, check the RPT permission field against the data field that relates to the resource representation and, if it matches, the data will be returned.