UMA Implementer's Guide

Abstract 

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

Status

This document is currently under active development.

Editors
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

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.


Organizations as Resource Owners and Requesting Parties

TBS - when two-legged pattern for PAT/AAT (client credentials) grant is appropriate; autonomous web service clients


Managing Resource Registration Revisions 

Regarding the resource set registration API, it is common practice when using NoSQL databases to replicate entity tag (ETag HTTP header) revision information in the body of the response message as well, in a _rev property. The API does not mandate this property, however.


Ensuring Resource Server Access to an Authorization Server When the Resource Owner Is Offline

A protection API token (PAT) is an OAuth access token that needs to work in a number of circumstances when the resource owner is offline. When a client attempts access to a protected resource, requiring the resource server to use runtime portions of the protection API, the resource owner is not assumed to be present. At this point, any interactions with the resource owner, for example, access approval workflows, are conducted out of band of the protocol.

Many use cases assume that the resource owner is explicitly "offline", for example, unconscious in a hospital emergency room. Some anticipate that the resource owner may end up "permanently offline" after having asked for the PAT to be issued (such as "digital death" scenarios, which perhaps raise other long-term issues).

The authorization server thus needs to manage the issuance and expiration of the PAT and and any corresponding refresh token appropriately to ensure that the resource server has access when it needs it.


Handling Optional and Extension Properties

The UMA specifications (Section 1.1 in both) say "Any entity receiving or retrieving a JSON data structure SHOULD ignore extension properties it is unable to understand. Extension names that are unprotected from collisions are outside the scope of this specification." And in some cases, properties defined in the specifications are optional to supply (but, of course, required to be handled by the receiving entity).

This section recommends how to deal with optional and extension properties. It is helpful for handling behavior to be consistent because UMA flows involve loosely coupled entities. Typically, an extension property would appear if one of the entities has implemented some agreed extension to the specification that might not apply to this particular transaction.

In the event that an unrecognized property is received, we recommend logging the property and its value, taking normal precautions regarding safe methods of logging potentially dangerous properties in order to avoid injection attacks or similar. This will help with any troubleshooting or auditing that may be required, while allowing normal processing to continue. Finally, we also recommend logging any property that is malformed (for example, where a Boolean value is expected, but a text value is received), taking the same precautions regarding safe methods of logging.

Following are specific comments on optional properties that appear in the UMA specifications.

PropertyRecommendations
Core 1.4: Authorization server configuration data
claim_token_profiles_supportedProvided as a hint; no significant impact if ignored by any party.  Should be logged if ignored to help with troubleshooting.
uma_profiles_supportedProvided as a hint; no significant impact if ignored by any party.  Should be logged if ignored to help with troubleshooting.
dynamic_client_endpointAuthorization Server: implementations should take care to provide this parameter if support for the dynamic client registration feature is provided.  Failing to provide it (or providing it erroneously) can induce incorrect handling by clients or resource servers.
Clients, Resource Servers: if the parameter is not provided, clients and resources servers must assume that dynamic client registration is not possible, and should therefore not attempt such registration.
requesting_party_claims_endpointAuthorization Server: to avoid confusion, should provide this parameter if end-user RP claims gathering capability exists.
Core 3.3.2: RPT "Bearer" profile
exp

Authorization Server: since not providing this property implicitly means that the permission does not expire, the AS should take care only to ignore the parameter if a non-expiring permission is desired.  It may be sensible to consider always providing a value, even if far in the future, to avoid inadvertently granting permanent permissions.
Resource Server: if the parameter is provided, it must be adhered to.  If it is not, it may be sensible to consider applying an expiry date anyway, to avoid inadvertently allowing permanent access to a given resources.  It may also be sensible to log if this parameter is not provided (and, hence, long or permanent permission is given) for audit purposes.

iatAuthorization Server: Not providing the issued-at time introduces the potential for confusion at the RS about whether the token is valid or not.
Resource Server: RS should consider whether the issued-at time is reasonable (allowing for potential clock skew).  Ignoring the parameter, if provided, could introduce a risk of incorrectly processing a 'bad' token.
nbfAuthorization Server: failure to provide this parameter might result in access to a resource being granted earlier than intended.  The AS should consider providing a value to avoid any potential confusion.
Resource Server: if the parameter is provided, it must be adhered to. If a value is not provided, the RS should assume 'now' as the nbf, and log accordingly for audit purposes.
Core 3.4.1.2: Claims-gathering flows
nameAuthorization Server: not providing a value might cause processing confusion later.  The AS should consider providing this.
Client: the client should consider using this value when returning any eventual results to the AS, in order to avoid confusion.
friendly_nameAuthorization Server: no significant impact; although not providing a value means that the client will have to make assumptions about how to present the claim requirement to the user.
Client: no significant impact; although the client should consider using this value to help provide improved communication to the user.
claim_typeAuthorization Server: no significant impact.
Client: no significant impact.
claim_token_formatAuthorization Server: failing to provide this parameter might result in a token format being return that the AS cannot then process.  AS should consider providing this parameter to avoid confusion at the Client.
Client: if provided, client should take account of the acceptable token formats when it returns a token to the AS. Ignoring this parameter might result in a token being returned in a format which the AS cannot process.
issuerAuthorization Server: no significant impact.
Client: ignoring this parameter, if provided, might result in a token being returned from an issuing authority which is not acceptable to the AS (and so lead to a poor user experience).
Core 3.4.1.2.2: Client redirects requesting party to authorization server
redirect_uriAuthorization Server: no significant impact; although not providing a value means that the client will have to make assumptions about how to present the claim requirement to the user.
Client: no significant impact; although the client should consider using this value to help provide improved communication to the user.
stateAs noted in the spec, it is highly recommended that this parameter be included in order to avoid cross-site request forgery.
ticket (response)There are no circumstances in which this parameter can reasonably be ignored.
state (response)There are no circumstances in which this parameter can reasonably be ignored.
Core 4.2: UMA error responses
error_descriptionNo significant impact.
error_uriNo significant impact.
RSR 2.1: Scope descriptions
icon_uriResource Server: no significant impact
Authorization Server: should log that it is ignoring for troubleshooting purposes.
RSR 2.2: Resource set descriptions
uriResource Server: in many deployments, the network location for the resource set being registered will be provided by (or inferable from) the 'scope' parameter (which is required).  If not, however, the resource server will most likely use the 'uri' parameter to provide the network location.
Authorization Server: if the parameter is ignored, this should be logged for troubleshooting.  It is unlikely to be ignored in most common scenarios.
typeResource Server: this can be a helpful hint to provide to the AS.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
icon_uriResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
RSR 3: Error messages
error_descriptionResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.
error_uriResource Server: no significant impact.
Authorization Server: should log that it is ignoring for troubleshooting purposes.

 


Redirecting the Requesting Party to the Client After Claims Gathering 

When a client redirects a requesting party to an authorization server for claims gathering, there is the potential for cross-site request forgery (CSRF) through an open redirect if the authorization server did not force the client to pre-register its redirection endpoint, as well as server-side artifact tampering. Using the state parameter to send the ticket value (ideally encrypted) enables the client to check that the ticket parameter ultimately returned by the authorization server has not been maliciously changed, for example by a man in the browser (MITB), once the value is returned. This method also has the benefit of enabling the client not to have to keep state during the interaction period.


RPT Refreshing 

TBS - V1.0 Core Sec 3.4.1: discuss implications of this: "Once the authorization server adds the requested authorization data, it returns an HTTP 200 (OK) status code with a response body containing the RPT with which it associates the requested authorization data. If the client did not present an RPT in the request for authorization data, the authorization server creates and returns a new RPT. If the client did present an RPT in the request, the authorization server returns the RPT with which it associated the requested authorization data, which MAY be either the RPT that was in the request or a new one. Note: It is entirely an implementation issue whether the returned RPT is the same one that appeared in the request or a new RPT, and it is also an implementation issue whether the AS chooses to invalidate or retain the validity of the original RPT or any authorization data that was previously added to that RPT; to assist in client interoperability and token caching expectations, it is RECOMMENDED that authorization servers document their practices."


Permission Ticket Management

TBS - additional text not used in spec (where did it go?)


Default-Deny Policy Decision-Making Behavior

TBS - discuss implications of this from V1.0.1 Core Sec 3.5.2: "The authorization server MUST use a default-deny authorization assessment model in adding authorization data to RPTs, that is, "everything that is not expressly allowed is forbidden" for resource sets that resource servers have registered. Exercise caution in implementing default-deny because corner cases can inadvertently result in default-permit behavior. For example, it is insufficient simply to assume that all resource sets have some non-zero set of claims required for access, and then accept an empty set of supplied claims as sufficient for access. See [UMA-Impl] for further discussion."


Resource Server API Constraints

The first step in the process of gaining access authorization is for a client to attempt access to the resource server's API without an RPT, and the second is for the resource server to register a requested permission on the client's behalf at the authorization server. This second step requires a PAT.

In order for the resource server to know which authorization server to approach and which PAT (representing a resource owner) and resource set identifier to supply, the resource server's API needs be structured in such a way that it can derive this information from the client's RPT-free access attempt. In practice, this information likely needs to be passed through the URI, headers, or body of the client's request.

Resource orientation, that is, an API design that uses resource-specific endpoints rather than a single endpoint for all calls of widely differing sorts (level 1 on the Richardson Maturity Model), is a classic way of achieving sufficient context. For example, the following call by a client would be sufficient to indicate that the operation was targeted at a child resource mjones (presumably a specific resource owner) associated with a parent resource doctors, and if the resource server had previously registered a resource set corresponding to this child resource at authorization server ABC and received back a resource set ID of ABC123, it could unambiguously select the correct authorization server, PAT, and resource set ID in order to register a requested permission for that clieint:

POST /doctors/mjones HTTP/1.1

However, if a resource server has an API that is completely generic per resource owner, such as a singular endpoint that if OAuth-protected would have depended entirely on an OAuth token to convey the user context, a different approach would be needed. It is possible for the resource server to register the singular resource set over and over for each of its many users (each using a different PAT) at an authorization server, getting a unique resource set ID for each in turn. However, the resource server must be prepared to associate some query attribute, HTTP header value, body field, or other artifact coming from the client in a call to the otherwise generic endpoint that can be matched up with the PAT. And the resource server must, of course, provision the necessary API context cue method and the specific resource owner context needed out of band, just as it would have had to provision (or make discoverable) the same information in a more "resource-oriented" form.

It is possible for the resource server to seed discoverability of the resource owner context by populating the uri property of the resource set description with a network location that includes, say, a query parameter identifying the resource owner in some fashion. Then the authorization server application would need to either transmit the parameter value to a discovery service, or function as a discovery service itself, or perform some other mapping. If the authorization server application is able to map the network location to a substitute value, such as a one-time code or equivalent, and then report that value back to the resource server application, then they each can provision the code to the requesting party (say, in an email message) or client (say, in an error message) for it to be returned somewhere in the initial access attempt.


Change History