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. UMA V2.0 is currently under development, so 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
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 (currently in draft) Core and OAuth Resource Registration specifications, and presumes understanding of UMA concepts.
Organizations as Resource Owners and Requesting Parties
A resource owner can be a human end-user (natural person) or an organization (legal person). The same is true of a requesting party. Using a client credentials grant to issue the PAT is appropriate when the resource owner is an organization and policy conditions are set either by an administrator or autonomously in some fashion. If the requesting party is an organization, then the client is typically an autonomously running web service, service account, or similar.
See the UMA Legal page for information on ongoing work to connect the technical UMA entities to contracts and trust frameworks that define "access federations" (in contrast to identity federations).
Managing Resource Registration Revisions
Regarding the resource 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 Asynchronous Resource Server Access to an Authorization Server
The protection API generally requires "offline" access, that is, when the resource owner is not available. Thus, the authorization server needs to manage the lifetime of the protection API access token (PAT) for this outcome.
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.
| Property (V1.0 references) | Recommendations |
|---|---|
| Core Sec 1.4: Authorization server configuration data | |
| claim_token_profiles_supported | Provided as a hint; no significant impact if ignored by any party. Should be logged if ignored to help with troubleshooting. |
| uma_profiles_supported | Provided as a hint; no significant impact if ignored by any party. Should be logged if ignored to help with troubleshooting. |
| dynamic_client_endpoint | Authorization 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_endpoint | Authorization Server: to avoid confusion, should provide this parameter if end-user RP claims gathering capability exists. |
| Core Sec 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. |
| iat | Authorization 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. |
| nbf | Authorization 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 Sec 3.4.1.2: Claims-gathering flows | |
| name | Authorization 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_name | Authorization 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_type | Authorization Server: no significant impact. Client: no significant impact. |
| claim_token_format | Authorization 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. |
| issuer | Authorization 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 Sec 3.4.1.2.2: Client redirects requesting party to authorization server | |
| redirect_uri | Authorization 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. |
| state | As 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 Sec 4.2: UMA error responses | |
| error_description | No significant impact. |
| error_uri | No significant impact. |
| RSR Sec 2.1: Scope descriptions | |
| icon_uri | Resource Server: no significant impact Authorization Server: should log that it is ignoring for troubleshooting purposes. |
| RSR Sec 2.2: Resource set descriptions | |
| uri | Resource 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. |
| type | Resource Server: this can be a helpful hint to provide to the AS. Authorization Server: should log that it is ignoring for troubleshooting purposes. |
| icon_uri | Resource Server: no significant impact. Authorization Server: should log that it is ignoring for troubleshooting purposes. |
| RSR Sec 3: Error messages | |
| error_description | Resource Server: no significant impact. Authorization Server: should log that it is ignoring for troubleshooting purposes. |
| error_uri | Resource 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. 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.
Resource Server API Constraints
An API that is designed as follows, counting on an OAuth access token to give all the necessary context, would be problematic. This is because UMA has a client-to-resource-first flow, with permission ticket passing, in order to enable party-to-party delegation:
POST /doctors/me HTTP/1.1
In the UMA grant flow, the client first attempts access to a protected resource with no token, and the resource server next requests permissions on behalf of that client at the authorization server. In order for the resource server to know which authorization server to approach and which PAT (representing a resource owner) and resource identifier to supply in that request, the API being accessed by the client needs to be structured in such a way that the resource server can derive this information from the client's token-free access attempt. Commonly, this information can be passed through the URI, headers, or body of the client's request. Alternatively, the entire interface could be dedicated to the use of a single resource owner and protected by a single authorization server.
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 client:
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.
Resource Registration Timing and Mechanism
No specific timing of initial resource registration is mandated. Three stages suggest themselves as natural resource registration times:
- On initial resource creation (say, the resource owner uploads a photo to the resource server)
- On need for policy creation (say, the resource owner wants to apply policy constraints to the photo)
- On resource access attempt (say, the client attempts to view the photo)
The first stage may result in registering more resources than need to be managed by the authorization server in practical terms. The third stage may forbid the use of certain flows. For example, it would not allow "Alice-to-Bob" sharing flows where Alice is able to put proactive policy conditions in place before Bob attempts access. Thus, the second stage may provide the greatest utility for the greatest number of use cases if it is necessary to pick one choice only. However, any of the stages is viable for different use cases.
Note that in current versions of UMA, the registration mechanism is limited to individual rather than bulk registration. It is possible to imagine use cases at all three stages outlined above where bulk registration could be helpful. However, in the interest of avoiding overly complex design and premature optimization for very large numbers of resources as opposed to manageably small numbers, the Work Group has currently decided to keep only the individual mechanism. Sample use cases include the following:
- 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 permission requests for various APIs gives us a way of imagining finite numbers.)
Scope Discovery
Rather than the resource description document pointing to a series of scope URIs that must be dereferenced (as was the case in UMA V1.0.x), the resource server in UMA V2.0 can instead make use of the OpenID Connect discovery document and its scopes_supported metadata item, which, when filled with (the same) scope description document URIs, allows for development-time discovery of the necessary scope information.