Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This document includes final release notes for the UMA V1.0.1 Recommendations and incomplete draft release notes for the UMA V2.0 Draft Recommendations. Please see the Disposition of Comments document for additional changes made to UMA V2.0.

Editor
  • Eve Maler
Intellectual Property Notice

...

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. Please see the Disposition of Comments document for additional changes made to UMA V2.0; these changes will be incorporated into this document as well as time allows. (tbs: complete all "tbs:" tasks throughout once the specifications reach Recommendation status)

NOTE: Reading the release note 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.

The UMA specifications use Semantic Versioning:

...

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. 

The following shorthand terms and abbreviations are used in this document (see also the terminology, including abbreviations, defined in the specifications):

...

Where a change relates to a GitHub issue, the linked issue number is provided.

...

Anchor
to-v20
to-v20
From UMA1 to UMA V2.0 (

...

Draft Recommendations, revs 08)

The UMA V2.0 specifications (GrantFedAuthz – 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. Differences and changes noted are between V2.0 and V1.0.n generally; note that internal revision differences between UMA2 revisions are not tracked. (You may find it helpful to refer to the Disposition of Comments document, a record of specification changes during the Public Comment period.) Where the distinction between V1.0 and V1.0.1 is important, it will be noted; otherwise the label "UMA1" is used. Please see the Disposition of Comments document for additional changes made to UMA2. (tbs: add links to final spec sections throughout)

The following sequence diagrams may be of assistance as brief summaries of changes made:

...

  • 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

...

The two specifications were divided differently until late April 2017Core and RSR were recombined into Grant and FedAuthz (tbs: link to final specs)Grant and FedAuthz, as follows:

  • 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 https://docs.kantarainitiative.org/uma/profiles/prot-ext-1.0https://docs.kantarainitiative.org/uma/profiles/authz-ext-1.0, and https://docs.kantarainitiative.org/uma/profiles/rsrc-ext-1.0 were removed and replaced with recommendations (Grant Sec 4 and FedAuthz Sec 1.3) to define profiles as needed and to use uma_profiles_supported metadata (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.)

Note that until late April 2017, drafts of UMA2 still used the UMA1 organizing principle.

Anchor
terminology-changes
terminology-changes
Terminology Changes

Note the following terminology changes made throughout the specifications. (256) See also Summary of API and Endpoint Changes below for naming changes made to some of the endpoints.

V1.0.1V2.0UMA1UMA2Comments
configuration datametadata, discovery documentFor better clarity and OAuth alignment
policiesauthorization grant rules, policy conditionsFor better consistency
protection API token (PAT)protection API access token (PAT)For better clarity and OAuth alignment

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 subsectionsee Token Endpoint Replaces RPT Endpoint; Client-Side Communications Defined as Extension Grant)
authorization API token (AAT)goes away; a new related token is persisted claims token (PCT)Result of redesign (tbs: point to 154/264 subsectionsee AAT Removed in Favor of PCT)

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 subsectionsee Authorization Assessment Gains Precision)

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 subsectionsee AAT Removed in Favor of PCT andAuthorization Assessment Gains Precision)

RPT as an UMA access token

RPT as an OAuth access token

Result of redesign (tbs: point to 153/165 subsectionsee Token Endpoint Replaces RPT Endpoint; Client-Side Communications Defined as Extension Grant)

Anchor
api-endpoint-changes
api-endpoint-changes
API and Endpoint Changes

These design changes include naming changes made to some of the endpoints.

V1.0.1V2.0UMA1UMA2Comments
.well-known/uma-configuration.well-known/uma2-configurationThe same authorization server can have two different discovery endpoints, one serving UMA1 metadata and one serving UMA V2.0 UMA2 metadata.

OAuth endpoints:

  • authorization endpoint
  • token endpoint

OAuth endpoints:

  • authorization endpoint
  • token endpoint
Previously, the token endpoint issued both PATs and AATs. In V2.0, Now 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:

  • resource set registration endpoint/API
  • permission registration endpoint
  • token introspection endpoint

Protection API (now OPTIONAL):

  • resource registration endpoint/API
  • permission endpoint
  • token introspection endpoint
In the case of the first two endpoints, there are both design (primarily syntax) and naming differences, which also affects their corresponding metadata in the authorization server discovery document.

Authorization API:

  • RPT endpoint
-In V2.0UMA2, there is no authorization API. The prior function of the RPT endpoint is served by the existing OAuth token endpoint.
Requesting party claims endpointClaims interaction endpointThis is just a naming difference.

...

UMA1's endpoint and feature discovery mechanism was defined in total by its Core specification. UMA2 makes use of the OAuth discovery mechanism instead, 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)

Definition of OAuth Dynamic Client Registration Metadata Field

The new metadata field claims_redirect_uris enables the client to pre-register claims redirection URIs. (Grant Sec 2, Sec 3.3.2, Sec 7.3) (337 sub-issues c and d)

permissions Claim and Sub-Claims in Token Introspection Object Not Requested to Be IANA-Registered as JWT Claims

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)

...

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)

Anchor
aat-vs-pct
aat-vs-pct
AAT Removed in Favor of PCT

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)

...

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

An optional interval parameter was added to the request_submitted error to enable the AS to inform the client about appropriate polling intervals. (Grant Sec 3.3.6) (341)

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 (Grant Sec 3.3.5, Sec 3.6). (238, 284)

Anchor
authz-assessment
authz-assessment
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 (Grant Sec 3.3.4). (266, 310, 317)

...

The scopes parameter in the resource description document has been renamed to resource_scopes (FedAuthz Sec 3.1). (318)

New HTTP 400 and invalid_request Error

For a typical variety of malformed-request errors, a response of an HTTP 400 (Bad Request) status code and an optional invalid_request error code is now defined. (FedAuthz Sec 3.2) (354-1)

Permission Endpoint

Requesting Multiple Permissions and Permissions With Zero Scopes

...

If token introspection is used (see Options Not to Use Token Introspection Explicitly Allowed), the introspection object can no longer be extended to replace the permissions claim with an entirely different structure. (322)

permissions Claim and Sub-Claims in Token Introspection Object Not Requested to Be IANA-Registered as JWT Claims

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. (334)

permission Claim exp Sub-Claim's Meaning If Absent Removed

...