Abstract
This document contains non-normative release notes produced by the User-Managed Access Work Group explaining how new versions of the UMA specifications differ from previous ones.
...
See also Summary of API and Endpoint Changes for some endpoint naming changes made to some of the endpoints.
| V1.0.1 | V2.0 | Comments |
|---|---|---|
| configuration data | metadata, discovery document | For better clarity and OAuth alignment |
| policies | authorization grant rules, policy conditions | For better consistency |
| protection API token (PAT) | protection API access token (PAT) | For better clarity |
resource set, resource set registration | resource, resource registration (protected while registered) | For better clarity and OAuth alignment |
authorization API | UMA grant (an extension OAuth grant) | Result of redesign (tbs: point to 153/165 subsection) |
| authorization API token (AAT) | goes away; a new related token is persisted claims token (PCT) | Result of redesign (tbs: point to 154/264 subsection) |
register a permission (for permission ticket) | request (one or more) permission(s) (on behalf of a client) | For better clarity |
trust elevation | authorization process and authorization assessment | Result of redesign (tbs: point to 266/310/317 subsection) |
claims pushing + claims gathering = (n/a) | claims pushing + claims gathering = claims collection | For better consistency |
step-up authentication | (n/a); just authorization process | Result of redesign (tbs: point to 154/264 subsection and 266/310/317 subsection) |
RPT as an UMA access token | RPT as an OAuth access token | Result of redesign (tbs: point to 153/165 subsection) |
...
These design changes include some endpoint naming changes made to some of the endpoints.
| V1.0.1 | V2.0 | Comments |
|---|---|---|
.well-known/uma-configuration | .well-known/uma2-configuration | The same authorization server can have two different discovery endpoints, one serving UMA1 metadata and one serving UMA V2.0 metadata. |
OAuth endpoints:
| OAuth endpoints:
| Previously, the token endpoint issued both PATs and AATs. In V2.0, the token endpoint issues PATs, and now RPTs as well; there are no AATs. (Note that the authorization endpoint is used for authenticating resource owners only, not requesting parties.) |
Protection API:
| Protection API:
| In the case of the first two endpoints, there are both design (primarily syntax (tbs: link to section(s))) and naming differences, which also affects their corresponding metadata in the authorization discovery document. |
Authorization API:
| - | The prior function of the RPT endpoint is served by the OAuth token endpoint. |
| Requesting party claims endpoint | Claims interaction endpoint |
...
Discovery Document and Metadata Simplification
UMAUMA1's endpoint and feature discovery mechanism was defined in total by its Core specification. V2.0 makes use of the OAuth discovery mechanism instead. V2.0 also eliminates metadata fields already defined by the OAuth discovery or OpenID Connect specification. The Grant (Sec 2) and FedAuthz (Sec 2) specifications each define only the metadata fields they require. (59, 157, 159, 305)
...
After the AS initially generates the permission ticket and the RS conveys it to the client, whenever the client subsequently approaches the AS token endpoint or redirects the requesting party to the AS claims gathering endpoint, the AS is required to rotate the value of the permission ticket every time it hands a permission ticket value back to the client (Grant Sec 3.3.3, Sec 3.3.6). This action obsoletes any need for the UMA Claims-Gathering Extension specification for Enhanced Security specification (see this explanation of that specification for more information).
| Anchor | ||||
|---|---|---|---|---|
|
...
; Client-Side Communications Defined as Extension Grant
The specialized RPT endpoint was removed in favor of using the standard OAuth token endpoint (Grant Sec 3.3.1). A formal extension OAuth grant was defined (same section), working with regular OAuth capabilities and OAuth error codes to the extent possible (Sec 3.3.6). This enabled reuse of large portions of the threat model , and the client type model, along with the ability to use client credentials to be authenticated at the token endpoint (see the next section for additional discussion). (153, 165)
...
An end-user requesting party no longer needs to mediate issuance of an AAT at the AS, and the client no longer needs to use an AAT in order to request a token; it simply uses its own client credentials at the OAuth token endpoint as in a normal grant (see Token Endpoint Replaces RPT Endpoint and Client-Side Communications Defined as Grant). Thus, the first time the requesting party needs to interact with the AS, if at all, is to provide claims interactively when redirected by the client as part of claims collection. This is in contrast to UMA1, where an end-user requesting party would have been expected to engage in an interactive OAuth flow to log in and then authorize AAT issuance at the AS's authorization endpoint. In UMA1, the (required) AAT could have been used by the AS as a reminder of claims about the current requesting party. In UMA2, the (optional) PCT is available to serve in this capacity instead, without the OAuth mechanism being involved (Grant Sec 3.3.1). UMA2 does not require the AS to involve the requesting party in an interactive flow authorizing PCT issuance (Grant Sec 3.3.3). (154, 264)
Deprecated Response-Body Permission Ticket Return Option By RS Removed
...
In UMA V1.0.1 the AS was able to return the permission ticket to the client along with the redirect_user hint, but the client was not supposed to depend on ticket accuracy, and the supply of this ticket was deprecated. Now all permission tickets directly supplied by the AS are rotated and the value is safe for the client to depend on (Grant Sec 3.3.6). (233)
need_info Response Structured Flattened
The JSON nested object structure of the need_info error response from the AS has been flattened. Now it directly contains a permission ticket and either a required_claims or a redirect_user hint (or both) . See (Grant Sec 3.3.6). (237, 308)
New Refresh Token Clarity
It has been clarified that the AS can issue a refresh token and the client can use the refresh token grant to attempt to get a new RPT with it . See (Grant Sec 3.3.5 and , Sec 3.6). (238, 284)
Authorization Assessment Gains Precision
Inputs to authorization assessment and results calculation are more normative and precise. It is also now possible for permissions with zero scopes to be granted . See (Grant Sec 3.3.4). (266, 310, 317)
Permission Ticket Ecosystem Rationalized
The permission ticket generation ecosystem is has been rationalized. In UMA2, a permission ticket is always generated, and the value rotated, in cases of a redirect back from the claims interaction endpoint and in cases of need_info and request_submitted errors from token endpoint requests, and never in cases of other errors. An authorization process is still ongoing while the authorization server is still generating permission tickets. (275, 279, 298)
...
UMA2 includes more comprehensive and normative logic around RPT upgrading (Grant Sec 3.3.5, 3.3.5.1). (281)
Token Revocation Clarifications
tbs: Clarified that token revocation is viable UMA2 includes more comprehensive and normative text around token revocation, and defines a token type hint for PCTs (Grant Sec 3.7). (295)
...
Refresh Token Grant and Downscoping Logic Clarifications
tbs: Ensured UMA2 ensures that the logic of downscoping during token refreshing is properly defined given that UMA scopes are bound to resources; clarified , and clarifies that the AS does not perform authorization assessment in this context (Grant Sec 3.6). (306)
Changes to AS-RS Interface, the Protection API (Now Federated Authorization)
...
Previously, the security considerations around accepting policy-setting context information from an incompletely trusted AS were not covered. Now they cover the user_access_policy_uri property, which is the only policy-setting context information passed from AS to RS. (185) (RSR Sec 4)
Specification Reorganizations
The specifications, particularly Core Sec 3, were reorganized in the fashion of OpenID Connect, with the goal of giving a subsection to every request and response message. Other notable changes include:
...
| Anchor | ||||
|---|---|---|---|---|
|
Following is a catalog of notable changes to the specifications in the pre-V1.0 timeframe.
Core Changes
Internet-Draft Rev 11 to Rev 12
...