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

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.

...

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
RO-RqP-org RO-RqP-org

Organizations as Resource Owners and Requesting Parties

...