UMA Scoped Access Proposal
draft-uma-scoped-access

Abstract

This specification proposes a method for achieving scoped access with User-Managed Access (UMA). This method assumes that, as currently specified in the UMA core protocol, a host must outsource the validation of requester access tokens to the authorization manager (AM) when access is attempted on a protected resource.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on June 24, 2011.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Introduction
    1.1.  Notational Conventions
    1.2.  Terminology
2.  Host tells requester resource set identifier
3.  Requester supplies desired resource set and action(s) to AM
4.  AM registers scope description
5.  AM provides the token's scope identifier
6.  Host looks up token's scope description
7.  Security Considerations
8.  Privacy Considerations
9.  TODOs
10.  Acknowledgments
11.  Document History
12.  Normative References
§  Authors' Addresses

1.  Introduction

This specification proposes a method for achieving scoped access with User-Managed Access (UMA). This method assumes that, as currently specified in the UMA core protocol, a host must outsource the validation of requester access tokens to the authorization manager (AM) when access is attempted on a protected resource.

After a host registers resource set identifiers and the identifiers of permissible actions on those resource sets, the authorization manager (AM) is responsible for following the authorizing user's instructions in mapping authorization constraints to particular combinations of these identifiers. The triple of a set of constraints, a resource set, and a list of actions can be considered a "policy", and its latter two-thirds, the resource set/actions portion, can be considered a "permission", granted by the AM on the user's behalf when the requesting party meets the constraints.

In order to enable communication about scopes and permissions in the process of granting and controlling access, this specification defines a JSON-formatted data structure that describes a set of one or more permissions, called a scope description, and defines how to use a unique scope identifier that refers to this description.

Following is the flow of scope communications:

1. Step 1:

   A.

   Host registers resource set descriptions and action descriptions with AM (described in [[draft-uma-resource-reg]]).

   B.

   AM maps authorization constraints to permissions according to the user's instructions (out of band).

2. Step 2:

   A.

   Requester attempts to access protected resource at host, allowing host to infer the requester's desired resource set and action.

   B.

   Host tells requester the identifier of a resource set that would suffice for access to the resource, and redirects requester to AM (defined in this specification for now). It is assumed that the requester has out-of-band knowledge of possible actions on the resource to which it had attempted access, through host API documentation.

   C.

   Requester asks AM for an access token, specifying the identifiers of the desired resource set and action(s) (defined in this specification for now).

   D.

   AM looks up the authorization constraints associated with these identifiers and asks for claims as required to satisfy the constraints.

   E.

   Assuming the constraints are satisfied, AM issues an access token and optional refresh token to requester.

   F.

   AM registers, in the user-specific portion of the host registration area, a scope description that lists the permissions corresponding to the issued access token (defined in this specification for now).

3. Step 3:

   A.

   Requester attempts to access the resource again, this time presenting its requester access token.

   B.

   Host conveys token to AM for validation.

   C.

   AM responds saying if the token is still valid (not expired) and providing the token's scope identifier (defined in this specification for now).

   D.

   Host looks up scope description and confirms that the attempted access matches the permissions granted for this token (defined in this specification for now).

1.1.  Notational Conventions

The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

Unless otherwise noted, all the protocol parameter names and values are case sensitive.

1.2.  Terminology

See the core UMA protocol spec [[draft-uma-core]] and the UMA resource registration spec [[draft-uma-resource-reg]] for additional term definitions.

scope description

A JSON-formatted data structure that represents a set of one or more permissions that have been granted to a requesting party.

scope identifier

A unique identifier representing a scope description. (The word "scope" may be used to represent either this identifier or the corresponding description, depending on context.)

permission

A resource set identifier and a list of action identifiers, which together represent a range of access abilities that an authorizing user is willing to grant.

2.  Host tells requester resource set identifier

TBS (see item 2b in flow list above)

3.  Requester supplies desired resource set and action(s) to AM

TBS (see item 2c in flow list above)

4.  AM registers scope description

(See item 2f in flow list above)

The AM registers scope descriptions as a way to record the permissions associated with a requester access token in a persistent fashion. A scope description is in JSON [[cite]] form. It is an object with the following parameters:

An action description is an object with the name "scope" and the following parameters:

_id

REQUIRED. An identifier that MUST be identical to the {scopeid} path component of the scope description URI (see below). Some RESTful database technologies provide special features for populating this parameter automatically.

permissions

REQUIRED. Contains an array of at least one object that has "resource_set" and "actions" parameters:

resource_set

REQUIRED. The identifier of a resource set. The identifier MUST correspond to a resource set registered by this host for this user at this AM.

actions

REQUIRED. An array referencing one or more identifiers of actions that are authorized on this resource set. Each action identifier MUST correspond to an action registered by this host for this user at this AM.

For example, this description characterizes a scope whose single permission involves reading and updating a resource set representing "all" resources being protected for this user at this host:

{
   "scope": {
       "_id": 1234afbd,
       "permissions": [
           {
               "resource_set": "all",
               "actions": [ "read", "update" ]
           }, ...
       ]
   }
}

Scope descriptions MAY contain extension parameters that are not defined in this specification. The names of extension parameters MUST begin with "x-".

5.  AM provides the token's scope identifier

TBS (see item 3c in flow list above)

6.  Host looks up token's scope description

(See item 3d in flow list above)

The host uses a RESTful API at the AM's host_registration_uri to read scope descriptions at the time of token validation. The host MUST use its valid host access token obtained previously in UMA protocol step 1 to gain access to the API.

Individual scope descriptions are managed at URIs with this structure: "{reguri}/host/{hostid}/user/{userid}/scope/{scopeid}"

The components of these URIs are defined as follows:

{reguri}

The AM's host_registration_uri as advertised in its metadata. This endpoint, its security requirements, and its requirements around advertisement in metadata are defined in UMA protocol step 1 [[uma-draft-core]].

{hostid}

A registration area at the AM that is specific to this host. The host MUST use the OAuth client identifier it was assigned by this AM as its host identifier. If the host identifier does not match the host access token used at the host registration endpoint, the AM MUST report an error and fail to act on the request (see Section [[Error Responses]] below).

{userid}

The portion of the host's registration area at this AM that is specific to this user, assigned during registration of resource information for this user.

{scopeid}

An identifier for a scope description, assigned during initial registration of this description.

The only allowed scope lookup API operation is:

• Read scope description: GET /host/{hostid}/user/{userid}/scope/{scopeid}

With this operation, a host reads a previously registered scope description at the AM using the GET method. If any other HTTP method is attempted, the AM MUST respond with a 403 Forbidden message and fail to take any other action.

HTTP request:

GET /host/{hostid}/user/{userid}/scope/{scopeid} HTTP/1.1
...

HTTP response (success):

HTTP/1.1 200 OK
Content-Type: application/json
ETag: (entity tag of the scope artifact)
...

(Body contains JSON representation of scope description.)

HTTP response (not found):

HTTP/1.1 404 Not Found
...

(Body provides user-readable explanation of the error.)

HTTP response to any method other than GET or to a {hostid} path component that does not match the presented host access token (forbidden):

HTTP/1.1 403 Forbidden
...

(Body provides user-readable explanation of the error.)

7.  Security Considerations

TBS

8.  Privacy Considerations

TBS

9.  TODOs

• ISSUE: How is the {userid} established at the point when an AM needs to register a scope description? (See item 2f in the flow list in the introduction, above.)
• Should the AM respond to a token validation request by returning the applicable scope structure rather than by pointing to it through a scope identifier? Alternatively, is the scope description mechanism needed at all? If the host were to supply candidate resource sets and actions when asking for validation, the AM could perform the lookup and matching operation itself, and return a simple "YES" or "NO". However, if we chose this option, the host could not cache the token/scope mapping, and the scope description mechanism would not be available for other uses (such as eventual token scope upgrading).

10.  Acknowledgments

• [TBS]

11.  Document History

[[ to be removed by RFC editor before publication as an RFC ]]

12. Normative References

Authors' Addresses