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:
- by an authorization server;
- to a client application
- representing (on behalf of) a requesting party
- for using one or more protected resource(s)
- owned by a resouce owner
- on a resource server (RS)
- for one or more scopes (for each protected resource)
- in the form of an OAuth access token, the Requesting Party Token (RPT)
Compared to plain OAuth, UMA brings the following features:
- An (optional) API can be used by the RS to declare/configure some RO's resources (and scopes) to the authorization server. These protected resources and scopes can then appear in the AS's user interface and the RO can configure about a policy for them.
- A way for the resource server to request fine-grained authorizations (for the resources and scopes required to complete a given request) and for the client to obtain them from the authorization server without the client having to have any knowledge on the granularity of the resources and the different scopes[1].
UMA 2.0 is split into two specifications:
- UMA Grant describes the interaction between the client and the RS and the client and the AS. This is the part of the specification required to implement a client application.
- Federated Authorization describes the direct interactions between the AS and the RS. This part is therefore not needed to implement a client. Moreover, it may be not be needed when the AS and the RS are tightly integrated (such as when they are part of the same application).
Component diagram
Sequence diagrams
Registration of the RO's protected resources on the AS:
- 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).
- Using the PAT, the RS declares the RO's protected resources (and associated scopes) to the AS.
- 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):
- A RqP tries to access the one (or more) protected resource(s) on the RS
- The RS replies with the address of the AS to use and a permission ticket repreensting the authorization request.
- 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.
- The AS issues the RPT (an access token) to the client application.
- 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.).
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.
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:
- anyone can access the resource (anonymous access);
- anyone can access the resource but the AS asks the RqP's email address and verifies it by sending a confirmation code;
- only members of a group can access the resource;
- the RqP must first fill a form and the authorization request is then manually approved by the RO;
- a CAPTCHA is needed;
- the RqP must complete a sudoku;
- the RqP must convince a LLM-based chatbot that it should have access to the resource;
- a payment is needed;
- access is allowed during the night;
- access is allowed after 2045;
- access is allowed only from a specific client;
- the authorization must be validated by at least 3 people from a group of 5 people;
- a combination thereof.
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 2.0 Grant for OAuth 2.0 Authorization
- Federated Authorization for UMA 2.0
- UMA 2.0 Grant for OAuth 2.0 Authorization, IETF draft
- Federated Authorization for UMA 2.0, IETF draft
UMA 1.0:
Misc UMA material
UMA and healthcare:
- HEART for OAuth 2.0
- HEART forFHIR) OAuth 2.0 Scopes
- HEART for OpenID Connect 1.0
- HEART for UMA 2.0
- HEART for FHIR UMA 2 Resources
- Patient-Centric Data Sharing with UMA
Implementations:
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 likehttps://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 ashttps://apps.example.com/scim/Users
,https://apps.example.com/scim/Groups
, andhttps://apps.example.com/scim/Schemas
. The client would usehttps://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 requestedscope
is chosen by the client. In UMA, the client does need to known thescope
because the requestedscope
is chosen by the RS. ↩︎These claims take the form of assertions. For example SAML assertsion, JWT, ID Token, SD-JWT, CWT, etc. ↩︎