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 | ||||
---|---|---|---|---|
|
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.
RESTful API Controlled by One Scope
Access to an endpoint with the following design:
- Create some web resource: POST endpoint/
- Read web resource: GET endpoint/server_assigned_id
- Update web resource: PUT endpoint/server_assigned_id
- Delete web resource: DELETE endpoint/server_assigned_id
- List all web resources: GET endpoint/
...is controlled through a single scope rest_api
. Any one of the five calls attempted by the client would be a signal that rest_api
is being sought.
IoT Device Functions Enabled by Scopes
Access to a person’s smart-home front door camera has the following functions and scopes:
- Doing anything at the endpoint (bound to a single resource owner): POST /camera?...
- On/off control:
power
scope - Specific camera-direction coordinates:
pan
scope
- On/off control:
An attempt to turn the power off would be interpreted as a need for power
scope. An attempt to move the camera position would be interpreted as a need for pan
scope.
RPC-Style API endpoint Enabled by Finer-Grained Scopes
Access to a person’s calendar management service has the following functions and scopes:
- Doing anything at the endpoint: POST /cal_service
- Request message in XML or JSON contains the particulars (including some indication of the target individual’s identifier in it somewhere):
- See free vs. busy times:
freebusy
scope - Read whole calendars:
calendar-read
scope - Edit whole calendars:
calendar-edit
scope - etc.
- See free vs. busy times:
- Request message in XML or JSON contains the particulars (including some indication of the target individual’s identifier in it somewhere):
To the extent that there are hybrid request messages, there may be ambiguity in the purpose of any incoming access attempt. However, the presumption is that the purpose of each attempt would generally be clear and mappable.
Ambiguous Role-Based Scopes
An API uses scopes to manage access per role as follows (assume the API calls themselves are unambiguous for this example):
- Read and write access:
user
scope - Read, write, execute, superuser access:
admin
scope
If a client attempts read or write access, it is ambiguous whether user
scope or admin
scope is sought.
This is a good example of where the client would want to exercise its option to pre-register for and then dynamically request admin
scope if the requesting party’s immediate need were only for the two actions also available within user
scope. It’s also a good example of where the RS would potentially want to have a strategy of "parsimonious" rather than "generous" permission requests (either requesting user
scope rather than admin
scope and not requesting additional resource identifiers, or even requesting no scopes at all and let the client take on the burden of expressing its needs).
Scopes for Ambiguous API Calls
An API for photo retrieval and usage uses scopes to manage access for a single API call that has two different functions as follows:
- GET low-resolution version for the purpose of viewing:
view
scope - GET high-resolution version for the purpose of downloading:
download
scope
A GET call doesn’t distinguish between the two possible functions. The RS can request zero scopes, which may be the wisest choice for (say) a paid service or just in the name of least privilege and minimal disclosure.
Resource Owner-Affected/Influenced Scopes
Assume the same example as above. Because the RO-RS interface is private (beyond the issuance of the PAT), and the details of which resources are centrally protected and how are allowed to be variable, the resource server could make an option available to the resource owner to keep the the download
scope "private" – that is, never registered for any of the RO's resources (meaning, never advertised by the RS as part of the universe of possible scopes on this resource).
In this scenario, the RS should first look at the RO-designated scopes before requesting permissions.
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 | ||||
---|---|---|---|---|
|
...