...
...
...
...
...
Abstract
This document contains non-normative release notes produced by the User-Managed Access Work Group for various explaining how new versions of the UMA specifications differ from previous ones.
Status
This document contains includes final release notes for the final UMA V1.0 and V1.0.1 Recommendations and has a fledgling section for incomplete draft release notes for the UMA V2.0 draft technical specificationsDraft Recommendations.
Editor
- Eve Maler
Intellectual Property Notice
...
This document contains non-normative release notes produced by the User-Managed Access Work Group for various explaining how new versions of the UMA specifications differ from previous ones. The Work Group uses Semantic Versioning for its specification version numbers(tbs: complete all "tbs:" tasks throughout)
The UMA specifications use Semantic Versioning:
Given a version number MAJOR.MINOR.PATCH, increment the:
...
- AS: authorization server
- RS: resource server
- Core: UMA Core specification (applies to versions 1.0 and 1.0.1)
- RSR: OAuth Resource Set Registration specification (applies to versions 1.0 and 1.0.1)
- Grant: UMA Grant for OAuth Authorization (applies to version 2.0)
- FedAuthz: Federated Authorization for UMA (applies to version 2.0)
- I-D: IETF Internet-Draft specification
- Sec: section
...
The UMA V2.0 specifications (Grant, FedAuthz) are in draft technical specification Where a change relates to an issue recorded in GitHub, the linked number is provided.
Differences and changes noted are between V2.0 and V1.0.x generally. Where the distinction between V1.0 and V1.0.1 is important, it will be noted; otherwise "UMA1" is used.
...
| Anchor | ||||
|---|---|---|---|---|
|
The UMA V2.0 specifications (Grant, FedAuthz) (tbs: link to final) are in Draft Recommendation form. This section will be completed, and updated as required, as the specifications progress to Recommendation status.
Version Themes
The themes of this major version are to:
...
The two specifications were divided differently. Core and RSR were recombined into Grant (tbs: link to final) and FedAuthz (tbs: link to final), divided in this way:
- All communications of the client and requesting party with the AS moved to Grant. This specification formally defines an extension OAuth grant.
- The communications of the resource owner and resource server with the AS moved to FedAuthz. This includes:
- Policy setting (outside the scope of UMA)
- PAT issuance
- Protection API
- Resource registration (formerly in RSR)
- The RS's permission requests at the AS (formerly in Core)
- The RS's token introspection at the AS (formerly in Core)
...
(Note that drafts of 2.0 prior to late April 2017 used the 1.0.1 organizing principle.)
Summary of Terminology Changes
...
(256)
See also the next section for some endpoint naming changes.
| 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 registration, resource set registration | resource registration, resource registration (protected while registered) | For better clarity and OAuth alignment | |
authorization API | UMA grant (an extension OAuth grant)register a permission ( | 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) | “policies” (colloquial) | access grants, access grant rules, policy conditionsFor 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 | ||
authorization API token (AAT) | goes away; a new related token is persisted claims token (PCT) | ||
| 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 | ||
protection API token (PAT) | protection API access token (PAT) |
...
| Result of redesign (tbs: point to 153/165 subsection) |
Summary of API and Endpoint Changes
These design changes include some endpoint naming changes.
| V1.0.1 | V2.0 | Comments |
|---|---|---|
.well-known/uma-configuration | .well-known/uma2-configuration | |
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:
| |
Authorization API:
| n/a | The prior function of the RPT endpoint is served by the token endpoint. |
| Requesting party claims endpoint | Claims interaction endpoint |
Authorization Server Discovery Document and Metadata Changes
Discovery Document and Metadata Simplification
UMA's endpoint and feature discovery mechanism was defined in total by its V1.0.1 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 and FedAuthz specifications each define only the metadata fields they require. (59, 157, 159, 305)
Changes to AS-Client and RS-Client Interfaces (Including Requesting Party Interactions): Now the UMA Grant
All client-involved interfaces were codified in V2.0 as the UMA grant, an OAuth extension grant.
Permission Ticket Rotation
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 ticket value back to the client. This action obsoletes any need for the Claims-Gathering Extension specification (see this explanation).
RPT Endpoint Removed and Extension Grant Defined
The specialized RPT endpoint was removed in favor of using the standard OAuth token endpoint. A formal extension OAuth grant was defined, working with regular OAuth capabilities and OAuth error codes to the extent possible. This enabled reuse of large portions of the threat model, the client type model, the ability to use client credentials to be authenticated at the token endpoint (see the next section for additional discussion). (153, 165)
tbs: to be continued...
Changes to the AS-RS Interface (Protection API): Now Federated Authorization
tbs: to be continued...
...
| Anchor | ||||
|---|---|---|---|---|
|
...
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
...