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.
...
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Considerations Regarding Resource Server Permission Requests
Because access attempts on resources by clients are resource identifier-unaware, the process of making a permission request also requires interpretation by the resource server in order to establish a suitable resource identifier, resource owner, and authorization server. It is recommended for the resource server to document its intended pattern of permission requests in order to assist the client in pre-registering for and requesting appropriate scopes at the authorization server. Following are some scenarios.
...
This would mean that the AS would fail the client with an invalid_scope error at the token endpoint if the client requested it (and presumably pre-registered for it). The RS, too, would receive an invalid_scope error if it tried to request a permission it hadn't first registered as part of a resource.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Although authorization assessment is an internal process performed by the authorization server, in UMA V2.0 it gains a large degree of normative precision. This section explains, using symbolic set math. (tbs – NEEDS REVIEW)
...
Proceed with the authorization results calculation based on CandidateGrantedScopes.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Considerations Regarding 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).
...
| Anchor |
|---|
...
When a client redirects a requesting party to an authorization server for claims gathering, there is the potential for crosssite 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.
...
|
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:
...
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Considerations Regarding Resource Registration Timing and Mechanism
No specific timing of initial resource registration is mandated. Three stages suggest themselves as natural resource registration times:
...
- 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.)
...
- .g., each of the use cases in the GDoc imagining RS permission requests for various APIs gives us a way of imagining finite numbers.)
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Considerations Regarding 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 authorization 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.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Considerations Regarding Using Alternate Communications Protocols Between UMA Entities
...
In some circumstances, it may be desirable to couple UMA software entity roles tightly. For example, an authorization server application might also need to act as a client application in order to retrieve protected resources so that it can present to resource owners a dashboard-like user interface that accurately guides the setting of policy; it might need to access itself-as-authorization server for that purpose. For another example, the same organization might operate both an authorization server and a resource server that communicate only with each other behind a firewall, and it might seek more efficient communication methods between them.
...
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).
...
| Anchor | ||||
|---|---|---|---|---|
|
(This section is specific to UMA V1.0.1.)
...