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

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

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) 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 access token freshness and refresh token issuance 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.

Giving Non-RPT-Bearing Clients Success Responses 

TBS - what do do when responding with other than a 403

Redirects 

If the client is concerned about HTTP parameter substitution of the ticket value after an end-user requesting party is redirected back after claims gathering, it can verify that the ticket initially sent to the authorization server is the same value that is subsequently returned by the authorization server. To verify that the ticket is the same in a stateless fashion, the client can send the ticket value in the state parameter, ideally in encrypted form, and then compare them on receiving the response from the authorization server.

RPT Refreshing 

TBS - 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."

Change History