This document includes final release notes for the all versions of UMA V1.0.1 Recommendations and draft release notes for the UMA V2.0 Draft Recommendations.
- Eve Maler
Intellectual Property Notice
The User-Managed Access Work Group operates under Kantara IPR Policy - Option Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non discriminatory (RAND) (HTML version) and the publication of this document is governed by the policies outlined in this option.
The content of this document is copyright of Kantara Initiative. © 2018 Kantara Initiative
Table of Contents
|Table of Contents|
NOTE: Reading the release note notes is not a substitute for reading the specifications carefully. In each specification release, much work is typically done to improve clarity and applicability for implementers and others. See the UMA Implementer's Guide for additional commentary.
Where a change relates to a GitHub issue, the linked issue number is provided.
The UMA V2.0 specifications (Grant, FedAuthz – currently these links go to revisions 08) (tbs: link to final specs, and to final spec sections throughout) are in Draft Recommendation form. This section will be completed, and updated as required, as the specifications progress to Recommendation status. Recommendations are User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization (known as "Grant") and Federated Authorization for User-Managed Access (UMA) 2.0 (known as "FedAuthz"). The official versions are downloadable from the Kantara Reports & Recommendations page; this document links to specific sections within the HTML versions.
Differences and changes noted are between V2.0 and V1.0.n generally; note that internal revision differences between UMA2 revisions are not tracked here. (You may find it helpful to refer to the Disposition of Comments document, a record of specification changes during the Public Comment periodperiods late in their final review cycle, and the GitHub repository where the specifications are managed.) Where the distinction between V1.0 and V1.0.1 is important, it will be noted; otherwise the label "UMA1" is used.
The following sequence diagrams may be of assistance as brief summaries of changes made:
- Sequence diagram for UMA Grant, highlighting key changes from UMA1
- Sequence diagram for FedAuthz, highlighting key changes from UMA1
- Increase OAuth 2.0 alignment
- Improve Internet of Things readiness
- Improve readiness for "wide ecosystems", where the requesting party and the resource owner's AS have no pre-established relationship
- All communications of the client and requesting party with the AS appear in Grant. This specification formally defines an extension OAuth grant.
- All communications of the resource owner and resource server with the AS appear in FedAuthz. This includes:
- Policy setting (outside the scope of UMA)
- PAT definition and issuance
- Protection API
- Resource registration (previously, RSR specified only this endpoint/API and Core specified everything else)
- The RS's permission requests at the AS
- The RS's token introspection at the AS
- The formal profiles for API extensibility URIs
were removed and replaced with recommendations (Grant Sec 4 and FedAuthz Sec 1.3) to define profiles as needed and to use
uma_profiles_supportedmetadata (Grant Sec 2) to declare them.
It is now optional to implement the features appearing in FedAuthz; thus, this specification effectively defines a conformance level. (Note: To receive the full benefits of "user-managed access", it is best to implement and use the features of both specifications.)
UMA1's endpoint and feature discovery mechanism was defined in total by its Core specification. UMA2 makes use of the OAuth discovery Authorization Server Discovery mechanism instead (still in Internet-Draft form at the time of UMA2 publication), eliminating 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)
Previously, it was intended to make an IANA registration request of the claims inside the introspection object as independent JWT claims. This would enable them to be formally used in RPTs, such that an RS can validate the access token locally with these claims packed inside it. Because of potential security and privacy considerations, it was determined not to define this token format for now. (FedAuthz Sec 9) (334)
Changes to AS-Client, RS-Client, and AS-Requesting Party Interfaces (Now UMA Grant Specification)
Authorization Server Rotates Permission Ticket
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 the need for the UMA Claims-Gathering Extension for Enhanced Security specification (see this explanation of that specification for more information).
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 for the client to request scopes and to authenticate using its own client credentials 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). Note that 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)
More Discretionary Permission Requests
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) (Grant Sec 3.3.6). (237, 308)
not_authorized Error Renamed to request_denied
The UMA1 error
not_authorized has been renamed to
request_denied. Note that this error was re-added only in a later revision of UMA2. See the UMA Implementer's Guide section called Understanding Authorization Server Response Options From the Token Endpoint to understand AS error semantics. (Grant Sec 3.3.6) (340)
Added interval parameter to request_submitted Error
New Refresh Token Clarity
Permission Ticket Ecosystem Rationalized
The permission ticket generation ecosystem 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
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)
Only One Pushed Claim Token Now Allowed at a Time
In UMA1, the mechanism for claim token pushing was a JSON-encoded request message sent to the RPT endpoint, optionally including with a
claim_tokens array each of whose objects had a
format parameter and a
token parameter. In UMA2 (Grant Sec 3.3.4), , due to increased alignment with OAuth, this structure was flattened and the request message – now sent to the token endpoint as
application/x-www-form-urlencoded format – contains each of the inner parameters only once. (If it is desired to send multiple claim tokens in a single request message, a compound claim token format could be defined.)
RPT Upgrading Logic Improved
Token Revocation Clarifications
Refresh Token Grant and Downscoping Logic Clarifications
UMA2 ensures that the logic of downscoping during token refreshing is properly defined given that UMA scopes are bound to resources, and clarifies that the AS does not perform authorization assessment in this context (Grant Sec 3.6). (306)
Changes to AS-RS Interface/Protection API (Now Federated Authorization Specification)
Resource Registration Endpoint
Scope Description Documents No Longer Expected to Resolve at Run Time When Scopes Are URLs
Resource Descriptions Lose uri Parameter
Resource and Scope Description Documents Gain Description Parameters
New HTTP 400 and invalid_request Error
It is now possible for the RS to request multiple permissions on the client's behalf, not just one; this enables the RS to request "packages" of multiple resources that are likely to need to be accessed together. It is also possible for the RS to supply zero scopes on a requested permission (FedAuthz Sec 4.1); this is because the client can request its own scopes directly from the AS (for more discussion see Token Endpoint Replaces RPT Endpoint; Client-Side Communications Defined as Extension Grant). (317)
In UMA2, the RPT is explicitly a type of OAuth access token, and it has been clarified that the token can be self-contained and valided locally by the RS, or introspected at the AS at run time, or its cached value used as appropriate (FedAuthz Sec 5). (261)
permissions Claim in Token Introspection Object Must Be Used
- We decided not to progress this specification in its current form, so we will let it expire and will not reference it from Core.