AM as the UMA Authorization Server
In the role of the User-Managed Access (UMA) authorization server, AM grants delegated consent to a requesting party on behalf of the resource owner to authorize who and what can get access to their data and for how long.
Tip
Before configuring UMA in your environment, ensure you are familiar with the OAuth 2.0 standards and AM's implementation of OAuth 2.0.
UMA 2.0 is a lightweight access control protocol that defines a centralized workflow to let an entity (user or corporation) manage access to their resources.
It extends the OAuth 2.0 protocol and gives resource owners granular management of their protected resources by creating authorization policies on a centralized authorization server, such as AM.
UMA is part of the Kantara Initiative.
UMA 2.0 uses the OAuth 2.0 actors in slightly extended ways and introduces one new actor:
- resource owner
The resource owner is a user or legal entity that is capable of granting access to a protected resource.
- client
The client is an application that is capable of making requests with the resource owner's authorization and on the requesting party's behalf.
- resource server
The resource server hosts resources on a resource owner's behalf and is capable of accepting and responding to requests for protected resources.
You can configure ForgeRock Identity Gateway 6 or later as an UMA resource server. For more information, see ForgeRock Identity Gateway 7 Gateway Guide.
- authorization server
The authorization server protects resources hosted on a resource server on behalf of resource owners.
You can set up AM to fully function as an authorization server in an UMA 2.0 deployment. AM provides an UMA provider service, an UMA grant type handler, and endpoints for resource registration, permission ticket generation, and UMA token introspection. AM also uses its OAuth Provider Service to generate OIDC ID tokens, and to provide claim tokens and its policy engine for UMA resource management.
- requesting party
The requesting party is a user or legal entity that uses a client to access a protected resource. The requesting party may or may not be the same as the resource owner. This actor is specific to the UMA protocol.
- 1. Manage
The resource owner manages their resources on the resource server.
- 2. Protect
The authorization server and the resource server are loosely coupled elements in an UMA deployment. Because of this, the authorization server can onboard multiple resource servers in any domain. To onboard multiple resource servers, the authorization server exposes a protection API that provides resource registration, permission tickets, and token inspection endpoints to bind the resource server and authorization server.
The API endpoints are protected by a protection API access token (PAT)—an OAuth 2.0 token with a specific scope of
uma_protection—which establishes a trust relationship between the two components.For more information, see Managing UMA Resources.
- 3. Control
The resource owner controls who has access to their registered resources by creating policies on the authorization server. This allows the resource owner to grant consent asynchronously, rather than at resource request time. As a result, the requesting party can access data using an RPT.
For more information, see Managing UMA Policies.
- 4. Authorize
The client, acting on behalf of the requesting party, uses the authorization server's UMA Grant Flow to acquire an RPT, which is a token unique to the requesting party, client, authorization server, resource server, and resource owner. The requesting party and the resource owner can interact with their applications at any time they want [1]. This interaction allows for party-to-party data sharing and access authorization delegation. The resource owner can grant consent by policy using the authorization server, rather than issue a token at runtime; thus, allowing for the asynchronous granting of consent.
- 5. Access
The client presents the RPT to the resource server, which verifies its validity with the authorization server. If the token is valid and contains the sufficient permissions, the resource server returns the protected resource to the requesting party. The RPT is a claims token with time-limited scoped permisions.
The UMA 2.0 process largely involves the UMA 2.0 Grant flow, in which a requesting party obtains an RPT to access the resource, and resource registration which can occur at various stages through the UMA process by the resource owner. These stages could occur at initial resource creation, when needed for policy creation, and at resource access attempt.
See the section, "Considerations Regarding Resource Registration Timing and Mechanism" in the UMA Implementer's Guide for information.
AM supports the following UMA grants and specifications:
User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization
This specification defines an OAuth 2.0 extension grant, allowing a party-to-party authorization mechanism where entities in a requesting party role can access protected resources authorized by the resource owner using authorization policies. The specification also defines how a resource owner can configure an authorization server with authorization grant rules to run asynchronously with the resource server using an RPT versus granting consent at runtime.
Note
The User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization specification also discusses the use of the authorization server's claims interaction endpoint for interactive claims gathering during the UMA grant flow. AM does not currently support interactive claims gathering. Claims gathering is accomplished by having the client acquire an OpenID Connect (OIDC) ID token[2].
The specification also discusses the optional issuance of a persisted claims token (PCT), which is a correlation handle issued by the authorization server, representing a set of claims collected during one authorization process to be used in later ones. AM does not currently support PCTs, because AM uses an OIDC ID token for its claims.
For more information, see The UMA Grant Flow.
Federated Authorization for User-Managed Access (UMA) 2.0
This specification defines the loosely coupled federation of the authorization process by means of multiple resource servers in different domains that communicate with the centralized authorization server and acts on behalf of a resource owner. The authorization server can reside locally or in another domain from the resource server(s).
Tip
See the complete list of supported OpenID Connect and OAuth 2.0 standards.
UMA 2.0 Example Use Case
A resource owner, Alice, is a patient who plans to undergo a medical procedure at a surgery center. Dr. Bob is a specialist surgeon who needs read access (for example, read scope) to Alice's electronic health records in order to operate, and write access (for example, write scope) in order to add new entries related to the surgery. These records are a resource whose contents have built up over time and to which Alice's regular physician, Dr. Carol, has access already.
Alice, or some party representing Alice, registers her medical health records and sets up permissions using authorization policies, allowing Dr. Bob and Dr. Carol access to her health data. On an online healthcare application, Alice can easily grant consent by clicking a "Share" button to her data, or decline access by clicking a "Deny" button.
UMA also solves managed consent for IoT deployments. For example, Alice will need to be monitored after her operation. Dr. Bob prescribes a smart medical device for Alice, such as a clinical-grade blood pressure monitor, which must be registered by the resource server to place it under the authorization server's protection. The blood pressure monitor sends data to a server that aggregates and transmits the data to external devices, allowing Dr. Bob and Dr. Carol access to Alice's data on their tablets or mobile apps.
AM supports a one-to-many policy that can be shared with many entities, not just targeting a single requesting party. Thus, Alice is able to share her data with Dr. Bob, Dr. Carol, as well as with the clinical and operational employees at the surgery center.
To view other Case Studies, see the Kantara Initiative.