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.

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. © 2015 Kantara Initiative

Table of Contents 

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 Core and OAuth Resource Set Registration specifications, and presumes understanding of UMA terms and concepts.

Organizations as Resource Owners and Requesting Parties

TBS - when client credentials grant (two-legged pattern) for PAT/AAT is appropriate; e.g., autonomous web service clients, "non-person entities" (NPEs) such as organizations represented by "service accounts".

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 (though an early pre-V1.0 draft did include this property).

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

The PAT 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 RS 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

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.

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, it's a good idea to log 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, it's also recommended to log 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 defined in the specifications.

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. Encrypting the value also has the benefit of enabling the client not to have to keep state during the interaction period when it checks the returned value.

RPT Refreshing 

TBS - V1.0 Core Sec 3.4.1: provide advice around 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 other examples 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