Abstract 

This document is a non-normative set of auxiliary material produced by the User-Managed Access Work Group. It provides advice to, and discussions relevant to, developers and deployers of UMA-enabled software systems, services, and applications.

Status

This document is currently under active development. It focuses primarily on UMA V2.0, which is currently at the WG draft stage; every attempt will be made to mark content that applies to specific versions.

Editors

Eve Maler, Maciej Machulak

Copyright Notice

Patent & Copyright: Reciprocal Royalty Free with Opt-Out to Reasonable And Non-discriminatory (RAND) (HTML version)

Copyright: The content of this document is copyright of Kantara Initiative. © 2017 Kantara Initiative

Table of Contents 

...

This document is a non-normative set of auxiliary material produced by the User-Managed Access Work Group. It provides advice to, and discussions relevant to, developers and deployers of UMA-enabled software systems, services, and applications.

...

Abstract 

This document is a non-normative set of auxiliary material produced by the User-Managed Access Work Group. It provides advice to, and discussions relevant to, developers and deployers of UMA-enabled software systems, services, and applications.

Status

This document will have material added to it as warranted. It focuses primarily on UMA V2.0; every attempt will be made to mark content that applies to specific versions.

Editors

Eve Maler, Maciej Machulak

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 

...

Anchor
intro intro

Introduction

This document is a non-normative set of auxiliary material produced by the User-Managed Access Work Group. It provides advice to, and discussions relevant to, developers and deployers of UMA-enabled software systems, services, and applications.

This document uses terms and abbreviations defined in the UMA V2.0 specifications, and presumes understanding of UMA concepts.

...

Anchor
front-channel-security front-channel-security

Security Considerations Regarding Interactive Claims Gathering Flows

When the requesting party is redirected to the authorization server for interactive claims gathering, there are several possible attacks identified by the OAuth 2.0 Security Best Current Practice. The OAuth 2.0 authorization code flow is substantially similar to UMA interactive claims gathering: the `claims_redirect_uri` parameter is similar to the OAuth `redirect_uri` parameter, the incoming ticket is similar to OAuth scopes, and the returned ticket is similar to the OAuth authorization code; both flows require a client_id and recommend a state parameter. Therefore, these attacks can be mitigated through the countermeasures described in the OAuth 2.0 Security Best Current Practice. Two such attacks are Cross Site Request Forgery (Section 4.1), recommending application of PKCE, and the Mix-Up attack (Section 4.4), which has several possible mitigations.

One consideration specific to UMA is the possibility for the client to repeatedly invoke interactive claims gathering redirection before use of the token endpoint. This is possible since each ICG cycle results in a new UMA ticket to be issued to the client. This possibility requires additional security analysis and profiling of PKCE to ensure it still effectively provides the desired client authentication outcome. Another potential mechanism to mitigate these attacks is the use of client DPOP. Instead of a PKCE code challenge/verifier, the client is registered with a public key, possibly through DCR, and dynamic client authentication is the required at the token endpoint. Another direct resolution is for an AS profile to explicitly require a call to the token endpoint with the UMA ticket received through ICG redirection. This effectively ensures the PKCE flow is performed as designed.

...

Anchor
why-the-pat why-the-pat

Motivations for the Design of the PAT

Some developers and deployers studying UMA 2.0 have asked questions about the protection API access token, known as the PAT. What is it? Why does it exist? When does it need to be used?

The PAT is simply an OAuth access token with a particular scope, standardized by UMA with the name uma_protection. It represents the resource owner's (Alice’s) authorization for the resource server, acting as an OAuth client, to use the protection API presented by the authorization server.

This API is defined by the optional UMA Federated Authorization specification that is referenced by the UMA Grant specification; these sequence diagrams may be of interest. This API is what allows the resource server, on resource owner Alice’s behalf, to outsource resource protection to the authorization server in a formally defined fashion. In the FedAuthz specification, OAuth and the PAT are being used just as they would be for any other OAuth-protected API -- Facebook, Feedly, whatever. (This writeup assumes FedAuthz is in use. Otherwise there is no point talking about the PAT.)

Keep in mind that Alice could need resource protection from more than one resource server at a single authorization server, or could be using more than one authorization server -- or both. OAuth is a classic choice for ensuring both security and Alice’s authorization for these trusted app-to-service connections. It’s just that, in this case, the “app” is a resource server and the “service” is an authorization server.

To achieve resource protection, the protection API offers three endpoints. Alice’s permission is required for the resource server to make calls to any of these; hence the resource server must present a valid PAT for any of these calls to be allowed:

• Resource registration, so that the authorization server knows what resources to protect and how to let Alice give it the policy conditions under which to grant access (various CRUD operations for managing registration and deregistration).

• Permission requests on behalf of the client app used by a requesting party (such as Bob), so that the authorization server can correlate the originally attempted resource request with the client’s later request for an access token (the resource server gets back a permission ticket that it hands right over to the client).

• Access token introspection, so when Bob’s client finally makes a resource request toting an RPT (requesting party token), the resource server can look up at the authorization server what resource and scope access was actually granted and enforce that grant.

The protection API is an “offline” type of API, meaning the resource server generally needs to make API calls to the authorization server when Alice does not currently have a session. In practice, this typically requires a way for the resource server to store a longer-lived refresh token persistently so that it can refresh a shorter-lived PAT on an ongoing basis. (For some thoughts on resource server error handling when the PAT is invalid, see this section.)

Here are "offline" use cases for each of the endpoints. None of these situations require Alice's current availability, vs. some other condition for the resource server to make the API call to the protection API.

• Resource registration endpoint: The resource server needs to update all of Alice's resources when its API is versioned. For example, the API couldn't tag photos before, but now it's able to, and this corresponds to a new available scope.

• Permission endpoint: The resource server needs to request one or more permissions on Bob's client's behalf at (tokenless) resource request time.

• Token introspection: The resource server needs to introspect the RPT that Bob's client brings it at (token-carrying) resource request time.

The question has been posed: Why doesn’t the design of UMA2 call for the resource server (as an OAuth client) to switch to using its own client credentials, rather than the PAT, for the permission and token introspection endpoints of the protection API? It’s possible for the authorization server to derive the resource server’s intended resource owner from a resource ID passed in the request if client credentials were used. (see UMA GitHub issue #352)

The Work Group chose not to switch to a different construct for the following reasons:

• It would be inefficient. What if Alice the resource owner had revoked her PAT before Bob's client made a tokenless resource request (requiring the resource server to use the permission endpoint) or an RPT-bearing resource request (requiring the resource server to use the token introspection endpoint), say, because Alice doesn't “like” the resource server anymore? Now the authorization server would have to keep track of whenever she did this and then prevent any client credentials flows from happening. It wouldn't get this tracking "for free" from an invalid PAT.

• It would disrupt the higher-order trust relationship. Along with this loss of tracking comes the loss of the resource owner’s trust relationship with and delegation to the authorization server (properly stated, to the Authorization Server Operator) of its authorization function. The work by the UMA Legal subgroup to develop an UMA legal framework/business model includes the mapping of legal devices, such as contracts (including trust frameworks) and licenses, to the various UMA technical artifacts and messages, including the PAT. So this mapping capability might be lost if the PAT gets overtaken by a different mechanism.

• It would make the design inelegant. It’s weird for the authorization server to have to derive resource owner context this way. Both the permission request message and the token introspection response can contain multiple resource IDs. The spec then might need a new error condition to check whether they all match the same resource owner.

Thanks to UMAnitarians James Philpotts, Domenico Catalano, and Andi Hindle for contributing to this writeup.

...

Anchor
perm-request-patterns perm-request-patterns

Considerations Regarding Resource Server Permission Requests

...

Since there is a many-to-one relationship between API calls and the scopes they map to, the RS resource server can distinguish the desired scope from the client's access attempt and request it that scope if it sees fit.

...

This is a good example of where the client would want to exercise its option to pre-register for and then dynamically request admin scope if the requesting party’s immediate need were only for the two actions also available within user scope. It’s also a good example of where the RS resource server would potentially want to have a strategy of "parsimonious" rather than "generous" permission requests (either requesting user scope rather than admin scope and not requesting additional resource identifiers, or even requesting no scopes at all and let the client take on the burden of expressing its needs).

...

A GET call doesn’t distinguish between the two possible functions. The RS resource server can request zero scopes, which may be the wisest choice for (say) a paid service or just in the name of least privilege and minimal disclosure.

...

Assume the same example as above. Because the ROresource owner-RS resource server interface is private (beyond the issuance of the PAT), and the details of which resources are centrally protected and how are allowed to be variable, the resource server could make an option available to the resource owner to keep the the download scope "private" – that is, never registered for any of the ROresource owner's resources (meaning, never advertised by the RS resource server as part of the universe of possible scopes on this resource).

In this scenario, the RS resource server should first look at the ROresource owner-designated scopes before requesting permissions.

This would mean that the AS authorization server would fail the client with an invalid_scope error at the token endpoint if the client requested it (and presumably pre-registered for it). The RSresource server, too, would receive an invalid_scope error if it tried to request a permission it hadn't first registered as part of a resource.

...

Anchor
pat-invalid pat-invalid

Resource Server Error Handling When the PAT Is Invalid

If the RS resource server can't get a permission ticket, it issues a 403 Forbidden HTTP error and Warning: 199 - "UMA Authorization Server Unreachable". One reason for being unable to get a permission ticket is that the resource owner's PAT has expired or is otherwise invalid, and it has no way of refreshing the PAT. In this case, the RS resource server could take this opportunity to initiate some refreshing action such as send a notification to the resource owner and ask them to re-consent to the pairing with the AS authorization server as required.

...

Anchor
RO-RqP-org RO-RqP-org

Considerations Regarding Resource Owners and Requesting Parties

...

• The resource server treats a "wildcarded" URI as being a single complex resource for authorization server purposes; this translates to individual registration.
• To enable a human resource owner to share out resources one at a time using a Share button, the resource server would probably need individual registration at stage 2. But to enable "relationship-driven sharing" of (say) multiple smart device resources at once, the resource server might want to register as many resources as are available in a household. For industrial IoT use cases, the number of resources to register could climb
• In discussions about the FHIR API for healthcare, resource registrations might "pair" with patterns of permission requests that anticipate a need for the requesting side to gain access to certain clusters of resources, say, three related resources if ever a client attempts to access one of them. (E.g., each of the use cases in the GDoc imagining RS resource server permission requests for various APIs gives us a way of imagining finite numbers.)

...

Anchor
ignored ignored

Handling Optional and Extension Properties (V1.0.1)

(This section is specific to UMA V1.0.1.)

Any entity receiving or retrieving a JSON data structure is supposed to ignore extension properties it is unable to understand, and manage property namespaces on its own to avoid collisions. Properties defined in the specifications that are optional to supply, however, are nonetheless required to be handled by the receiving entity.

...

...

Anchor
change-history change-history

Change History