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 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: The content of this document is copyright of Kantara Initiative. © 2015 2017 Kantara Initiative
...
Table of Contents
...
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
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).
...
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."
...
| Anchor |
|---|
...
|
...
|
...
|
...
TBS - additional text not used in spec (where did it go?)
...
The core specification requires the authorization server to use a default-deny authorization assessment model in adding authorization data to RPTs. Default-deny is always a safe position for an authorization server to take, in that it enables "failing closed". Access control systems can be implemented where a default-permit regime applies at a top level, and then an instruction to deny at a lower level. However, it is very difficult to guarantee denial in all necessary cases in such systems. Starting from a position of no access and then granting access rights selectively is a much more rational approach.
...
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.
...
|
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.
...
| Anchor | ||||
|---|---|---|---|---|
|
No specific timing of initial resource registration is mandated. There is a continuum of choices:
- 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 case may result in registering more resources than need to be managed by the authorization server in practical terms. The third case 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 case probably provides the greatest utility for the greatest number of use cases.