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.
...
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.
...
REST-Style API Controlled by
...
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):
...
Scopes
For example, the FHIR API has a sophisticated set of resource types, with each resource (say, of Condition
, Medication
, and Observation
types) having these operational options:
- Create = POST /path/resourceType
- Read = GET /path/resourceType/id
- Update = PUT /path/resourceType/id
- Delete = DELETE /path/resourceType/id
- Search = GET /path/resourceType?parameters...
- History = GET /path/resourceType/id/_history
- Transaction = POST/path/ (POST a transaction bundle to the system)
- Operation = GET /path/resourceType/id/$opname
As of this writing, there are two scopes, mapping to a subset of the options:
read
scope (for Read and Search)write
scope (for Delete, Create, and Update)
Since there is a many-to-one relationship between API calls and the scopes they map to, the RS can distinguish the desired scope from the client's access attempt and request it that scope if it sees fit.
Ambiguous Role-Based Scopes
...
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-
...
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).
...
- E = RequestedScopes = PermissionTicket ∪ (ClientRegistered ∩ ClientRequested);
- E = C ∪ (A ∩ B);
Define the set SatisfiedPolicyConditions (F) as the set of all scopes for which the client satisfies all relevant policy conditions at the AS.
...
- G = CandidateGrantedScopes = RequestedScopes ∩ SatisfiedPolicyConditions;
- G = E ∩ F;
Proceed with the authorization results calculation based on CandidateGrantedScopes.
...
Anchor | ||||
---|---|---|---|---|
|
...