/dev/posts/

UMA 2.0 diagrams

Published:

Updated:

Some diagrams (mostly sequence diagrams) about UMA 2.0.

Table of content

Overview

User-Managed Access (UMA) 2.0 is an extensions of OAuth 2.0 where a requesting party (RqP) requests access to some protected resources, belonging to some resource owner (RO). The requesting party might be the resource owner theirselves but it is generally a third-party. The authorization server (AS) may authorize the access by applying a policy defined by the RO. The authorization server might be unrelated to the resource server. A resource owner could use a common authorization server to control the access to resources from several unrelated resource servers (from different domains).

One goal of UMA is to allow the owner of one or more protected resources (on the resource server) to give granular access to these resources to other users (or other third parties such as organizations) and define/manage the policy for accessing to these resources in a privacy-preserving way. An example of intented usage of UMA is for patient-centric data sharing.

The authorization is issued:

Compared to plain OAuth, UMA brings the following features:

UMA 2.0 is split into two specifications:

Component diagram

UMA 2.0 components diagram

Sequence diagrams

Registration of the RO's protected resources on the AS:

  1. The RO authorizes (using an OAuth grant) the RS to declare the RO's protected resources to the AS. This authorization takes the form on an OAuth acces token, the PAT (Protection API Token).
  2. Using the PAT, the RS declares the RO's protected resources (and associated scopes) to the AS.
  3. The RO may then define policies for accessing their protected resources using the AS's user interface.

Access to the RO's resource(s) by the RqP (using some client application):

  1. A RqP tries to access the one (or more) protected resource(s) on the RS
  2. The RS replies with the address of the AS to use and a permission ticket repreensting the authorization request.
  3. The client proceed with the authorization process which may include,
    • interactive claim-gathering: the RqP interacts with the AS using its user interface (frontend) in order to comply with the policy. This may include user authentication, CAPTCHA, etc.
    • pushed claims: the RS directly pushes RqP claims[2] to the AS;
    • asynchronous authorization (using the request_submitted error): The client must wait for manual validation by the RO.
  4. The AS issues the RPT (an access token) to the client application.
  5. The client uses the RPT for accessing the protected resources.

Simplified Sequence diagrams

In the following diagrams, the users (RO and RqP) and user agent are not represented explicitly. Different colors are used to highlight different important parameters (tokens, tickets, etc.).

UMA 2.0 simplified sequence diagram when using interactive claims-gathering

UMA 2.0 simplified sequence diagram (general)

Detailed sequence diagrams

In the following diagrams, the arrows in brown can be considered to be implementations details and are not really required by the protocol.

UMA 2.0 resource registration sequence diagram
UMA 2.0 grant sequence diagram

Comments

UMA defines two methods for gathering claims about the requesting-party: interactive claims-gathering (i.e. interaction with a web brower) and pushed claims (SAML, OpenID Connect ID tokens, JWTs, etc.). Without additional profiles defining how pushed claims should be used, only interactive claims-gathering is really interoperable.

Note: Pushed claims in the HEART profile

One example of such profile is the HEART profile (intended for healthcare applications). In this profile, the client may directly use an OpenID Connect ID token as a mean for pushing claims. This can only be used when:

the authorization server is also the IdP or there is another closely bound relationship between the AS and IdP.

Alternatively (and in other cases), interactive claims gathering can be used.

Appendix: Tokens, tickets, etc.

Name Flow Content
Protection API Token (PAT) AS → RS → AS opaque (access token)
Requesting party token (RPT) AS → client → RS opaque (access token)
Persisted Claims Token (PCT) AS → client → AS opaque
Permission Ticket AS → RS → client → AS; AS → client → AS opaque
Claim token … → Client → AS usually some assertion (might be a SAML assertion, a JWT, a ID Token, a SD-JWT, etc.)
Resource ID AS → RS → AS opaque

Appendix, policies

The AS could implement support for a wide variety of policies such as:

UMA does not define any protocol or language for defining the policies. The way theyr are configured is left at the discretion of the AS. Usually, the AS will provide a user interface for letting the RO configure the policy of its protected resources.

References

UMA 2.0:

UMA 1.0:

Misc UMA material

UMA and healthcare:

Implementations:


  1. In plain OAuth, the authorization are usually more coarse-grained. The resource indicator extensions may be used by the client to request access to target resource. However, it is typically used to indicate the base address of some API (resource=https://rs/api/):

    The client SHOULD use the base URI of the API as the resource parameter value unless specific knowledge of the resource dictates otherwise. For example, the value https://api.example.com/ would be used for a resource that is the exclusive application on that host; however, if the resource is one of many applications on that host, something like https://api.example.com/app/ would be used as a more specific value. Another example is when an API has multiple endpoints, e.g., when System for Cross-domain Identity Management (SCIM) [RFC 7644] has endpoints such as https://apps.example.com/scim/Users, https://apps.example.com/scim/Groups, and https://apps.example.com/scim/Schemas. The client would use https://apps.example.com/scim/ as the resource so that the issued access token is valid for all the endpoints of the SCIM API.

    While the resource indicator extensions could be used to request an authorization for specific protected resource, this usually requires knowledge of the RS's API.

    In addition, in plain OAuth, the client must generally know which scope it needs to request because the requested scope is chosen by the client. In UMA, the client does need to known the scope because the requested scope is chosen by the RS. ↩︎

  2. These claims take the form of assertions. For example SAML assertsion, JWT, ID Token, SD-JWT, CWT, etc. ↩︎