Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

UMA Release Notes

Abstract 

This document contains non-normative release notes produced by the User-Managed Access Work Group for various versions of the UMA specifications.

Status

This document is currently under active development.

Editor
  • 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.

Table of Contents 

Introduction

This document contains non-normative release notes produced by the User-Managed Access Work Group for various versions of the UMA specifications.

The Work Group uses Semantic Versioning for its specification version numbers:

Given a version number MAJOR.MINOR.PATCH, increment the:

  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.

From V1.0 to V1.0.1 (draft)

The UMA V1.0 specifications (Core, RSR) were approved in March 2015. The UMA V1.0.1 specifications (Core, RSR) are currently (Sep 2015) in draft form; the Work Group's goal is to see their finalization by the end of 2015. The following release notes are therefore also in draft form. They are catalogued by their impact on software entities, with references to relevant GitHub issues. Where possible, specific section numbers are referenced; they link to discussions and related commits.

The following themes animated the V1.0.1 release process:

  • Account for V1.0 lessons learned out of the gate
  • Achieve timeline predictability and minimization of disruption for V1.0 implementers
  • Achieve efficiency, speed, and accuracy in specification revisions
  • Achieve issue solution consistency with OAuth 2.0 and OpenID Connect where possible
  • Within the allotted time, prioritize first blocking and critical bug fixes, then low-impact specification and implementation changes

Changes Affecting Authorization Server (+Client) Implementations

Following are specification changes in V1.0.1 that affect authorization servers, and possibly clients that interact with them as well (denoted with (+Client) in the title).

AS Now Has Unique Redirect URI Endpoint for Claims Gathering (+Client)

Previously, the client was instructed to present the ordinary OAuth redirect_uri endpoint to which the AS should redirect requesting parties back after claims gathering, but this was ambiguously specified and incorrect. Now the client has a unique endpoint, claims_redirect_uri, that it needs to register. (144)

Permission Ticket Lifecycle Management (+Client)

Previously, little guidance was offered on how to manage permission tickets. Now some implications are explored, particularly as they relate to client interaction. (172) (Core Sec 3.2.2)

Requested Permission and Permission Ticket Matching

Previously, the matching of the "extents of access" of the requested permission registered by the RS and the permission ticket issued by the AS was implicit. Now it is spelled out. (175) (Core Sec 3.2)

Permission Ticket on Redirect Back to Client (+Client)

Previously, the AS was required to repeat the client’s permission ticket back to it in a ticket property when offering a redirect_user hint in error_details. Now this is optional and the client is encouraged to ignore the property's value, preparatory to removing the property entirely in a future UMA version. The reason is that the value can't be guaranteed good; repeating the value was in order to save the client work; and having the client check the value would ultimately have caused both sides work for no gain. (205) (Core Sec 3.5.4.2)

PUT Means Complete Replacement

Previously, the requirement for an Update method in resource set registration to completely replace the previous resource set description was implicit. Now it is spelled out. (177) (RSR Sec 2.2.3)

Default-Deny for Authorization Data Issuance

Previously, a naive implementation could have resulted in accidental default-permit authorization data issuance in some cases. Now a default-deny authorization assessment model has been made explicit, with an example given of how implementations could get into trouble. (194) (Core Sec 3.5.2)

base64url-Encoded Claims (+Client)

Previously, the wording about base64url-encoding pushed claims was ambiguous about whether double-encoding was necessary in the case of claim formats that were already base64url-encoded. Now it has been clarified that double-encoding should not be performed. (206) (Core Sec 3.6.2)

Enhanced Security Considerations

Previously, the security considerations around accepting policy-setting context information from an incompletely trusted RS only covered "bad icon URIs". Now they cover all such policy-setting context information, following roughly the OAuth example. (151) (RSR Sec 4)

Previously, the security considerations around client-pushed claims were explored only in a very cursory fashion in the body of the text. Now they are treated at length in a new subsection. (160) (Core Sec 7.4.1)

Enhanced Privacy Considerations

Previously, little was said about privacy implications of requesting party claims being transmitted to the AS. Now this section has been greatly expanded. (211) (Core Sec 8.2)

Changes Affecting Resource Server (+Client) Implementations

Following are specification changes in V1.0.1 that affect resource servers, and possibly clients that interact with them as well (denoted with (+Client) in the title).

Caveat About Protected Resource API Constraint

Previously, the specification was missing an important caveat: Based on a client's initial RPT-free resource request, the RS needs to know the correct AS, PAT, and resource set ID to include in its follow-on call to the permission request endpoint at the AS. Thus, the API of the RS needs be structured so that it can derive this information from the client's request. Now this caveat appears in several locations. (161, 162, 225)

Adjustment of Other Protected Resource API Constraints (+Client)

Previously, the specification wording was inconsistent and problematic regarding how the RS responds to a client request accompanied by no RPT or an RPT with insufficient authorization data (assuming permission request success). Now the ability not to respond at all is more fully acknowledged; all responses intended to be interpreted in an UMA fashion are required to be accompanied by a WWW-Authenticate: UMA header; the permission ticket is required to be returned in a new ticket parameter in that header; complete freedom is given regarding the RS's choice of HTTP status code; and only in the case of a 403 choice is a ticket in a JSON-encoded body suggested, preparatory to removing the body option in a future UMA version. The rationale for this somewhat dramatic set of changes is that the original prescription to return HTTP status code 403 was incorrect; the specification gave too little guidance about responses other than 403 responses to be useful for client interoperability; and its requirement to return the permission ticket in a JSON-encoded body regardless of expected content type was an issue. (163, 164, 168) (Core Sec 3.3.1)

Solution for Permission Registration Failure (+Client)

Previously, the specification gave no guidance on how the RS should respond to the client in case of permission registration failure at the AS. Now, if the RS responds at all, it is required to substitute a Warning: 199 - "UMA Authorization Server Unreachable" header for WWW-Authenticate: UMA. (176) (Core Sec 3.3.2)

Authorization Server URI to Return to Client (+Client)

Previously, the value of the as_uri property that the RS returns to the client was described somewhat vaguely as the authorization server's URI. Now it has been clarified to be the issuer URI as it appears in the AS configuration data of the AS. (199) (Core Sec 3.3.1)

New Security Considerations

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:

  • Several “commentary” subsections were added, such as Core Sec 3.2.2 discussing permission ticket creation and management, and RSR Sec 2.1.2 discussing scope interpretation.
  • A new section, Core Sec 9.2, registers the permissions property in the new OAuth token introspection IANA registry (this is in addition to its registration in the JWT claims registry).
  • Core Sec 7.4.1 breaks out the new, more extensive security considerations discussion of pushed claims.
  • Core Sec 8 now has subsections to make privacy considerations easier to find and understand.

V1.0 sections (black) are presented in original Table of Contents order, mapped to their corresponding draft V1.0.1 sections (green).

 Core Specification Reorganization

Found in Core V1.0 (go)
Find in Core draft V1.0.1 (go)

3.1 Client Attempts Access to Protected Resource (go)
3.1 Client Attempts Access to Protected Resource (go)

3.1.1 Client Request to Resource Server With No RPT (go)
3.1.1 Client Request to Resource Server With No RPT
3.3 Resource Server Responds to Client
3.3.1 Resource Server Response to Client on Permission Registration Success
3.3.2 Resource Server Response to Client on Permission Registration Failure

3.1.2. Client Presents RPT (go)
3.1.2 Client Request to Resource Server With RPT (go)
3.3 Resource Server Responds to Client (go)
3.3.1 Resource Server Response to Client on Permission Registration Success
3.3.2 Resource Server Response to Client on Permission Registration Failure
3.3.3 Resource Server Response to Client on Sufficiency of Authorization

3.2. Resource Server Registers Requested Permission With Authorization Server (go)
3.2 Resource Server Registers Requested Permission With Authorization Server (go)
3.2.1 Resource Server Request to Permission Registration Endpoint
3.2.2 Permission Ticket Creation and Management
3.2.3 Authorization Server Response to Resource Server on Permission Registration Success
3.2.4 Authorization Server Response to Resource Server on Permission Registration Failure

3.3. Resource Server Determines RPT's Status (go)
3.3.1. Token Introspection
3.3.2. RPT Profile: Bearer
3.4 Resource Server Determines RPT Status (go)
3.4.1 Token Introspection Process
3.4.2 RPT Profile: Bearer

3.4. Client Seeks Authorization for Access (go)
3.5 Client Seeks Authorization for Access (go)

3.4.1. Client Requests Authorization Data (go)
3.5.1 Client Request to Authorization Server for Authorization Data (go)
3.5.2 Authorization Assessment Process
3.5.3 Authorization Server Response to Client on Authorization Success
3.5.4 Authorization Server Response to Client on Authorization Failure

3.4.1.1. Authentication Context Flows (go)
3.6 Client Responds to Authorization Server's Request for Additional Information (go)
3.6.1 Client Redirects Requesting Party to Authorization Server for Authentication

3.4.1.2. Claims-Gathering Flows (go)
3.6 Client Responds to Authorization Server's Request for Additional Information (go)
3.6.2 Client Pushes Claim Tokens to Authorization Server (go)
3.6.3 Client Redirects Requesting Party to Authorization Server for Claims-Gathering

4. Error Messages (go)
4.1. OAuth Error Responses
4.2. UMA Error Responses
4. Error Messages (go)
4.1 OAuth Error Responses
4.2 UMA Error Responses

5. Profiles for API Extensibility (go)
5.1. Protection API Extensibility Profile
5.2. Authorization API Extensibility Profile
5.3. Resource Interface Extensibility Profile
5. Profiles for API Extensibility (go)
5.1 Protection API Extensibility Profile
5.2 Authorization API Extensibility Profile
5.3 Resource Interface Extensibility Profile

6. Specifying Additional Profiles (go)
6.1. Specifying Profiles of UMA
6.2. Specifying RPT Profiles
6.3. Specifying Claim Token Format Profiles
6. Specifying Additional Profiles (go)
6.1 Specifying Profiles of UMA
6.2 Specifying RPT Profiles
6.3 Specifying Claim Token Format Profiles

7. Compatibility Notes (go)
n/a

8. Security Considerations (go)
7. Security Considerations (go)

8.1. Redirection and Impersonation Threats (go)
7.1 Requesting Party Redirection and Impersonation Threats (go)

8.2. Client Authentication (go)
7.2 Client Authentication (go)

8.3. JSON Usage (go)
7.3 JSON Usage (go)

8.4. Profiles, Binding Obligations, and Trust Establishment (go)
7.4 Profiles and Trust Establishment (go)

n/a
7.4.1 Requirements for Trust When Clients Push Claim Tokens (go)

9. Privacy Considerations (go)
8. Privacy Considerations (go)
8.1 Resource Set Information at the Authorization Server
8.2 Requesting Party Information at the Authorization Server
8.3 Profiles and Trust Establishment

10. IANA Considerations (go)
9. IANA Considerations (go)

10.1. JSON Web Token Claims Registration (go)
10.1.1. Registry Contents
9.1 JSON Web Token Claims Registration (go)
9.1.1 Registry Contents

n/a
9.2 OAuth Token Introspection Response Registration (go)
9.2.1 Registry Contents

10.2. Well-Known URI Registration (go)
10.2.1. Registry Contents
9.3 Well-Known URI Registration (go)
9.3.1 Registry Contents

11. Acknowledgments (go)
10. Acknowledgments (go)

12. References (go)
12.1. Normative References
12.2. Informative References
11. References (go)
11.1 Normative References
11.2 Informative References

  • No labels