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
perm-request-patterns perm-request-patterns

Permission Request Patterns

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

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.

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

Organizations as Resource Owners and Requesting Parties

...