Child pages
  • UMA Implementer's Guide

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added the Why The PAT? section


When the requesting party is redirected to the authorization server for interactive claims gathering, a man in the middle/man in the browser can manipulate messages, impacting the claims_redirect_uri parameter (in what is called the Mix-Up attack in the case of a OAuth security analysis) and potentially more elements of the front-channel messages involved. The claims_redirect_uri parameter is similar to the OAuth redirect_uri parameter and some attacks may be able to be mitigated through approaches described in the OAuth Security Topics Internet-Draft (at revision 04 at the time of writing), Section 4.4. If the syntactic mitigation approach described is taken, the authorization server's redirection response back to the client would need to be extended with additional parameters as described in the OAuth 2.0 Mix-Up Mitigation Internet-Draft (at revision 01 at the time of writing). If the client-side mitigation approach described is taken, the client would have to perform a number of coordinating and tracking actions in addition to choosing authorization server-specific URLs. The client could additionally use the state parameter and choose a specific type of value that carries enough application state to enable it to match the value with its callback.


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 RS to make calls to any of these; hence the RS 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 the UMA Implementer's Guide.)

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.


Considerations Regarding Resource Server Permission Requests