diff --git a/User-Managed Access (UMA) Core Protocol.html b/User-Managed Access (UMA) Core Protocol.html index 366052b..51a272d 100755 --- a/User-Managed Access (UMA) Core Protocol.html +++ b/User-Managed Access (UMA) Core Protocol.html @@ -143,7 +143,7 @@ -
 TOC 
+  TOC  @@ -163,7 +163,7 @@
Expires: June 2, 2012  


User-Managed Access (UMA) Core -Protocol
draft-hardjono-oauth-umacore-02

+Protocol
draft-hardjono-oauth-umacore-03

Abstract

This specification defines the User-Managed Access (UMA) core protocol. This protocol provides a method for users to control access to their protected @@ -195,68 +195,68 @@

Copyright Notice

Table of Contents

-

1.  - Introduction
    1.1.  - Notational Conventions
    1.2.  - Basic Terminology
    1.3.  - Endpoints, Endpoint Protection, and Tokens
    1.4.  +

1.  + Introduction
    1.1.  + Notational Conventions
    1.2.  + Basic Terminology
    1.3.  + Endpoints, Endpoint Protection, and Tokens
    1.4.  Scopes, Resource Sets, Permissions, and Authorization
-    1.5.  - AM Metadata
2.  - Protecting a Resource
    2.1.  - Host Looks Up AM Metadata
    2.2.  - Host Registers with AM
    2.3.  - Host Obtains Host Access Token
    2.4.  +    1.5.  + AM Metadata
2.  + Protecting a Resource
    2.1.  + Host Looks Up AM Metadata
    2.2.  + Host Registers with AM
    2.3.  + Host Obtains Host Access Token
    2.4.  Host Registers Sets of Resources to Be Protected
-        2.4.1.  - Scope Descriptions
        2.4.2.  +        2.4.1.  + Scope Descriptions
        2.4.2.  Resource Set Descriptions
        2.4.3.  - Resource Set Registration API
3.  +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#reg-api">2.4.3.  + Resource Set Registration API
3.  Getting Authorization and Accessing a Resource
    3.1.  +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#r-h-attempt-access">3.1.  Requester-Host: Attempt Access at Protected Resource
-        3.1.1.  +        3.1.1.  Requester Presents No Access Token
-        3.1.2.  +        3.1.2.  Requester Presents an Invalid Access Token
-        3.1.3.  - Requester Presents a Valid Access Token
    3.2.  +        3.1.3.  + Requester Presents a Valid Access Token
    3.2.  Requester-AM: Requester Obtains Access Token
    3.3.  +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#h-am-token-validation">3.3.  Host-AM: Ask for Requester Access Token Status
    3.4.  - Host-AM: Register a Permission
    3.5.  +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#h-am-register-scope">3.4.  + Host-AM: Register a Permission
    3.5.  Requester-AM: Request Authorization to Add Permission
-    3.6.  - Authorization Flows
        3.6.1.  - Authorization Flow for Requester Apps Operated by End-Users
4.  - Error Messages
    4.1.  - OAuth Error Responses
    4.2.  - UMA Error Responses
5.  - Security Considerations
6.  - Privacy Considerations
7.  - Conformance
8.  - IANA Considerations
9.  - AM Metadata Example
10.  - Example of Registering Resource Sets
11.  - Acknowledgments
12.  - Issues
13.  - References
    13.1.  - Normative References
    13.2.  - Informative References
Appendix A.  - Document History
§  +    3.6.  + Authorization Flows
        3.6.1.  + Authorization Flow for Requester Apps Operated by End-Users
4.  + Error Messages
    4.1.  + OAuth Error Responses
    4.2.  + UMA Error Responses
5.  + Security Considerations
6.  + Privacy Considerations
7.  + Conformance
8.  + IANA Considerations
9.  + AM Metadata Example
10.  + Example of Registering Resource Sets
11.  + Acknowledgments
12.  + Issues
13.  + References
    13.1.  + Normative References
    13.2.  + Informative References
Appendix A.  + Document History
§  Author's Address



-
 TOC 
+  TOC 

1.  Introduction

The User-Managed Access (UMA) core protocol provides a method based on [OAuth2] +class="info" href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#OAuth2">[OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) (currently draft 16) for users to control access to their protected resources, residing on any number of host @@ -274,9 +274,9 @@

1.  Introduction

shipping a purchased item, or it might be his friend who is using an online address book service to collect addresses, or it might be a survey company that uses an online service to compile population demographics. Other scenarios and -use cases for UMA usage can be found in [UMA‑usecases] +use cases for UMA usage can be found in [UMA‑usecases] (Maler, E., “UMA Scenarios and Use Cases,” -October 2010.) and [UMA‑userstories] +October 2010.) and [UMA‑userstories] (Maler, E., “UMA User Stories,” November 2010.).

In enterprise settings, application access management often involves letting @@ -288,14 +288,14 @@

1.  Introduction

a policy administrator crafting authorization strategies on his or her own behalf.

The UMA protocol can be considered an advanced application of [OAuth2] +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#OAuth2">[OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) in that it profiles, extends, and embeds OAuth in various ways. An AM can be thought of as an enhanced OAuth authorization server; a host as an enhanced resource server; and a requester as an enhanced client, acquiring an access token and the requisite authorization to access a protected resource at the host.

-

The UMA protocol has three broad phases, as shown in Figure 1. +

The UMA protocol has three broad phases, as shown in Figure 1.


@@ -334,13 +334,13 @@

1.  Introduction

In broad strokes, the phases are as follows:

    -
  1. Protect a resource (described in Section 2 +
  2. Protect a resource (described in Section 2 (Protecting a Resource)).
    3. -
  3. Get authorization (described in Section 3 +
  4. Get authorization (described in Section 3 (Getting Authorization and Accessing a Resource)).
    5. -
  5. Access a resource (described along with Phase 2 in Section 3 +
  6. Access a resource (described along with Phase 2 in Section 3 (Getting Authorization and Accessing a Resource)).

In more detail, the phases work as follows:

@@ -370,12 +370,12 @@

1.  Introduction

-
 TOC 
+  TOC 

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] +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 properties and values are case @@ -388,7 +388,7 @@

1.1.  Notational Conventions

-
 TOC 
+  TOC 

1.2.  Basic Terminology

UMA introduces the following terms, utilizing OAuth and other identity and @@ -445,7 +445,7 @@

1.2.  Basic Terminology

-
 TOC 
+  TOC 

1.3.  Endpoints, Endpoint Protection, and Tokens

Various UMA entities present APIs for other UMA entities to use. These APIs @@ -453,20 +453,20 @@

1.3.  Endpoints, Endpoint Protection, and Tokens

The AM presents the following endpoints to the host as part of its protection @@ -521,9 +521,9 @@

1.3.  Endpoints, Endpoint Protection, and Tokens

strategies may be suitable for different resources and scopes of access, and the AM has the opportunity to give the authorizing user control through policy.

Access tokens are currently assumed to be merely opaque strings (as discussed -in Section 1.5 +in Section 1.5 (AM Metadata) and Section 7 +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#conformance">Section 7 (Conformance)). Thus, when an AM associates a permission with a requester access token, a host cannot subsequently inspect such a token locally to assess whether a needed permission @@ -534,7 +534,7 @@

1.3.  Endpoints, Endpoint Protection, and Tokens

-
 TOC 
+  TOC 

1.4.  Scopes, Resource Sets, Permissions, and Authorization

UMA extends the OAuth concept of a "scope" by defining scopes as applying to @@ -559,7 +559,7 @@

1.4.  Scopes, Resource Sets, Permissions, and Authorization

permissions to be associated with their tokens. AMs grant (or deny) permissions to requesters.

In order to represent meaningful, auditable, and potentially legally -enforceable authorization (see [UMA‑trustmodel] +enforceable authorization (see [UMA‑trustmodel] (Maler, E., “UMA Trust Model,” February 2011.)), a permission is bound to a particular set of UMA entities and parties. This includes the requesting party, @@ -567,7 +567,7 @@

1.4.  Scopes, Resource Sets, Permissions, and Authorization

authorization process for each client application they use), the host, the resource set on which access is being attempted, and therefore also the AM protecting it and the authorizing user who is controlling access.

-

Unlike scopes (but similarly to tokens themselves; see Section 1.3 +

Unlike scopes (but similarly to tokens themselves; see Section 1.3 (Endpoints, Endpoint Protection, and Tokens)), permissions have a validity period.


@@ -576,23 +576,23 @@

1.4.  Scopes, Resource Sets, Permissions, and Authorization

-
 TOC 
+  TOC 

1.5.  AM Metadata

The AM MUST provide an XRD 1.0-formatted document at the hostmeta location -(see hostmeta +(see hostmeta (Hammer-Lahav, E., “Web Host Metadata,” May 2011.) [hostmeta]), documenting the following:

-

See Section 9 +

See Section 9 (AM Metadata Example) for a full example of AM metadata.

XRD property type values for conformance options:

@@ -600,7 +600,7 @@

1.5.  AM Metadata

http://docs.kantarainitiative.org/uma/1.0/client_reg
OPTIONAL (zero or one). Whether dynamic client registration, such as - through [OCDynClientReg] + through [OCDynClientReg] (Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0,” September 2011.), is supported for both hosts and requesters. The only values for this property @@ -614,7 +614,7 @@

1.5.  AM Metadata

Currently the only value for this property defined by this specification is "artifact", meaning an opaque token string whose associations the host MUST determine through a token status interaction with the AM (see Section 3.3 + href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#h-am-token-validation">Section 3.3 (Host-AM: Ask for Requester Access Token Status)). The AM is REQUIRED to support the artifact token type, and to supply this value explicitly in the metadata. The AM MAY @@ -622,7 +622,7 @@

1.5.  AM Metadata

a unique absolute URI as the value of this property.
http://docs.kantarainitiative.org/uma/1.0/host_authz_grant_types
REQUIRED (one or more). An OAuth grant type supported by this AM. The - value MUST be one of the grant_type values defined in [OAuth2] + value MUST be one of the grant_type values defined in [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.), or alternatively an extension grant type indicated by a unique absolute URI. The AM is REQUIRED to support @@ -634,7 +634,7 @@

1.5.  AM Metadata

OPTIONAL (zero or more). A claim format and associated sub-protocol for gathering claims from requesting parties, as supported by this AM. Currently the only value for this property defined by this specification is "openid", - for which details are supplied in Section 3.6.1.1 + for which details are supplied in Section 3.6.1.1 (Gathering Claims from Requesting End-Users with OpenID Connect). The AM MAY declare its support for claim types other than "openid" by assigning each one a unique absolute URI @@ -644,13 +644,13 @@

1.5.  AM Metadata

http://docs.kantarainitiative.org/uma/1.0/host_token_uri
REQUIRED. The host access token endpoint. Available HTTP methods are as - defined by [OAuth2] + defined by [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) for a token endpoint. Supplies the endpoint the host uses to ask for a host access token.
http://docs.kantarainitiative.org/uma/1.0/host_user_uri
REQUIRED. The host user authorization endpoint. Available HTTP methods - are as defined by [OAuth2] + are as defined by [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) for an end-user authorization endpoint. Supplies the endpoint the host uses to gather the consent of the @@ -661,7 +661,7 @@

1.5.  AM Metadata

REQUIRED. The resource set registration endpoint. Requests to this endpoint require a host access token to be present. Supplies the endpoint the host uses for registering resource sets with the AM to be protected (see - Section 2.4.3 + Section 2.4.3 (Resource Set Registration API)). This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
@@ -675,7 +675,7 @@

1.5.  AM Metadata

REQUIRED. The permission registration endpoint. Requests to this endpoint require a host access token to be present. Supplies the endpoint the host uses for registering permissions with the AM for which a requester - will be seeking authorization (see Section 3.4 + will be seeking authorization (see Section 3.4 (Host-AM: Register a Permission)). This endpoint SHOULD require the use of a transport-layer security mechanism such as TLS.
@@ -684,7 +684,7 @@

1.5.  AM Metadata

http://docs.kantarainitiative.org/uma/1.0/req_token_uri
REQUIRED. The requester access token endpoint. Available HTTP methods - are as defined by [OAuth2] + are as defined by [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) for a token issuance endpoint. Supplies the endpoint the requester uses to ask for an access token. This @@ -701,7 +701,7 @@

1.5.  AM Metadata

-
 TOC 
+  TOC 

2.  Protecting a Resource

Phase 1 of UMA is protecting a resource. The user, host, and AM perform the @@ -712,7 +712,7 @@

2.  Protecting a Resource

and supported formats.
  • If the host has not yet obtained a unique OAuth client identifier and optional secret from the AM, it registers with the AM as required. It MAY do - this using [OCDynClientReg] + this using [OCDynClientReg] (Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0,” September 2011.), if the AM supports it.
    • @@ -735,7 +735,7 @@

    2.  Protecting a Resource

    -
     TOC 
    +  TOC 

    2.1.  Host Looks Up AM Metadata

    The host needs to learn the AM's protection API endpoints before they can @@ -746,29 +746,29 @@

    2.1.  Host Looks Up AM Metadata

    process is beyond the scope of this specification, and it is up to the host to choose a method to learn the AM's general location.

    From the data provided, discovered, or configured, the host MUST use the -process described in Section 2 of hostmeta +process described in Section 2 of hostmeta (Hammer-Lahav, E., “Web Host Metadata,” May 2011.) [hostmeta] to retrieve the AM hostmeta document. For example, if the user supplied "am.example.com" as the Authorization Manager's domain, the host creates the URL "https://am.example.com/.well-known/host-meta" and performs a GET request on it. The AM MUST return content that includes UMA protection API endpoints as defined -in Section 1.5 +in Section 1.5 (AM Metadata).


    -
     TOC 
    +  TOC 

    2.2.  Host Registers with AM

    If the host has not already obtained an OAuth client identifier and optional secret from this AM, in this step it MUST do so in order to engage in -OAuth-based interactions with the AM. It MAY do this using [OCDynClientReg] +OAuth-based interactions with the AM. It MAY do this using [OCDynClientReg] (Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0,” September 2011.), if the AM -supports it (see Section 1.5 +supports it (see Section 1.5 (AM Metadata) for how the AM MAY indicate support).


    @@ -776,13 +776,13 @@

    2.2.  Host Registers with AM

    -
     TOC 
    +  TOC 

    2.3.  Host Obtains Host Access Token

    In this step, the host acquires a host access token from the AM. The token represents the approval of the authorizing user for this host to trust this AM for protecting resources belonging to this user.

    -

    The host MUST use OAuth2 +

    The host MUST use OAuth2 (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) [OAuth2] to obtain the host access token. Here the host acts in the role of an OAuth client; the authorizing user @@ -792,13 +792,13 @@

    2.3.  Host Obtains Host Access Token

    presenting these endpoints the AM acts in the role of a resource server.

    The AM MAY support the use of any grant type, but MUST support the authorization_code grant type, and SHOULD support the SAML bearer token grant -type [OAuth‑SAML] +type [OAuth‑SAML] (Campbell, B., “SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0,” August 2011.) (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates working with hosts that are operating in environments where the use of SAML is prevalent. The AM MUST indicate all grant types it supports in its metadata, as defined in Section 1.5 +class="info" href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#am-endpoints">Section 1.5 (AM Metadata).

    The host has completed this step successfully when it possesses a host access token it can use at the AM's protection API.


    @@ -807,7 +807,7 @@

    2.3.  Host Obtains Host Access Token

    -
     TOC 
    +  TOC 

    2.4.  Host Registers Sets of Resources to Be Protected

    Once the host has received a host access token, for any of the user's sets of @@ -818,7 +818,7 @@

    2.4.  Host Registers Sets of Resources to Be Protected

    resources and not others. Additionally, the choice of protection regimes can be made explicitly by the user or implicitly by the host. Any such partitioning by the host or user is outside the scope of this specification.

    -

    See Section 10 +

    See Section 10 (Example of Registering Resource Sets) for an extended example of registering resource sets.


    @@ -827,11 +827,11 @@

    2.4.  Host Registers Sets of Resources to Be Protected

    -
     TOC 
    +  TOC 

    2.4.1.  Scope Descriptions

    A scope is a bounded extent of access that is possible to perform on a -resource set. A scope description is a JSON +resource set. A scope description is a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] document with the following properties and a Content-Type of @@ -859,7 +859,7 @@

    2.4.1.  Scope Descriptions

    this specification. The names of extension properties MUST consist of a fully qualified URL, or begin with "x-" or "X-".

    A host MUST list a resource set's available scopes using URI references (as -defined in Section 2.4.2 +defined in Section 2.4.2 (Resource Set Descriptions)). The scopes available for use at any one host MUST have unique URI references so that the host's scope descriptions are uniquely distinguishable. A scope URI @@ -868,10 +868,10 @@

    2.4.1.  Scope Descriptions

    to point to standardized scope descriptions residing elsewhere. Scope description documents MUST be accessible to AMs through GET calls made to these URI references

    -

    See Section 1.4 +

    See Section 1.4 (Scopes, Resource Sets, Permissions, and Authorization) for further discussion of scope-related -concepts, and Section 10 +concepts, and Section 10 (Example of Registering Resource Sets) for a long-form example of scopes used in resource set registration.


    @@ -880,16 +880,16 @@

    2.4.1.  Scope Descriptions

    -
     TOC 
    +  TOC 

    2.4.2.  Resource Set Descriptions

    The host defines a resource set that needs protection by registering a resource set description at the AM. The host registers the description and manages its lifecycle at the AM's host resource set registration endpoint by -using the resource set registration API, as defined in Section 2.4.3 +using the resource set registration API, as defined in Section 2.4.3 (Resource Set Registration API).

    -

    A resource set description is a JSON +

    A resource set description is a JSON (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) [RFC4627] document with the following properties and a Content-Type of @@ -913,7 +913,7 @@

    2.4.2.  Resource Set Descriptions

    For example, this description characterizes a resource set (a photo album) that can potentially be only viewed, or alternatively to which full access can be granted; the URIs point to scope descriptions as defined in Section 2.4.1 +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#action-desc">Section 2.4.1 (Scope Descriptions):

    {
   "name": "Photo Album",
@@ -928,7 +928,7 @@ 
    2.4.2.  Resource Set Descriptions
    
 defined in this specification. The names of extension properties MUST consist of 
 a fully qualified URL or begin with "x-" or "X-".
    
 
    When a host creates or updates a resource set description (see Section 2.4.3 
+href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#reg-api">Section 2.4.3 
 (Resource Set Registration 
 API)), the AM MUST attempt to retrieve the referenced 
 scope descriptions. It MAY cache such descriptions as long as indicated in the 
@@ -942,7 +942,7 @@ 
    2.4.2.  Resource Set Descriptions
    
 
-    
    
   
   
     TOC 
    
+     TOC 
 
 
    2.4.3.  Resource Set Registration API
    
 
    The host uses the RESTful API at the AM's resource set registration endpoint 
@@ -961,7 +961,7 @@ 
    2.4.3.  Resource Set Registration API
    
   
    
     
    {rsreguri}
    
     
    The AM's resource set registration endpoint as advertised in its 
-    metadata (see Section 1.5 
+    metadata (see Section 1.5 
     (AM Metadata)).
    
     
    {rsid}
    
     
    An identifier for a resource set description.
    
@@ -979,7 +979,7 @@ 
    2.4.3.  Resource Set Registration API
    
   
  • Delete resource set description: DELETE /resource_set/{rsid}
    • 
   
  • List resource set descriptions: GET /resource_set/ with If-Match
    • 
 
    If the request to the resource set registration endpoint is incorrect, then 
-the AM responds with an error message (see Section 4.2 
+the AM responds with an error message (see Section 4.2 
 (UMA Error Responses)) by 
 including one of the following error codes with the response: 
    
 
    
@@ -1001,7 +1001,7 @@ 
    2.4.3.  Resource Set Registration API
    
 
-    
    
   
   
     TOC 
    
+     TOC 
 
 
    2.4.3.1.  Create Resource Set Description
    
 
    Adds a new resource set description using the PUT method, thereby putting it 
@@ -1057,7 +1057,7 @@ 
    2.4.3.1.  Create Resource Set Description
    
 
-    
    
   
   
     TOC 
    
+     TOC 
 
 
    2.4.3.2.  Read Resource Set Description
    
 
    Reads a previously registered resource set description using the GET method. 
@@ -1077,7 +1077,7 @@ 
    2.4.3.2.  Read Resource Set Description

    If the referenced resource does not exist, the AM MUST produce an error response with an error property value of "not_found", as defined in Section 2.4.3 +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#reg-api">Section 2.4.3 (Resource Set Registration API).


    @@ -1085,7 +1085,7 @@

    2.4.3.2.  Read Resource Set Description

    -
     TOC 
    +  TOC 

    2.4.3.3.  Update Resource Set Description

    Updates a previously registered resource set description using the PUT @@ -1108,7 +1108,7 @@

    2.4.3.3.  Update Resource Set Description

    If the entity tag does not match, the AM MUST produce an error response with an error property value of "precondition_failed", as defined in Section 2.4.3 +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#reg-api">Section 2.4.3 (Resource Set Registration API).


    @@ -1116,7 +1116,7 @@

    2.4.3.3.  Update Resource Set Description

    -
     TOC 
    +  TOC 

    2.4.3.4.  Delete Resource Set Description

    Deletes a previously registered resource set description using the DELETE @@ -1130,7 +1130,7 @@

    2.4.3.4.  Delete Resource Set Description

    HTTP/1.1 204 No content
 ...
    -

    As defined in Section 2.4.3 +

    As defined in Section 2.4.3 (Resource Set Registration API), if the referenced resource does not exist the AM MUST produce an error response with an error property value of "not_found", and @@ -1142,7 +1142,7 @@

    2.4.3.4.  Delete Resource Set Description

    -
     TOC 
    +  TOC 

    2.4.3.5.  List Resource Set Descriptions

    Lists all previously registered resource set identifiers for this user using @@ -1168,7 +1168,7 @@

    2.4.3.5.  List Resource Set Descriptions

    -
     TOC 
    +  TOC 

    3.  Getting Authorization and Accessing a Resource

    Phase 2 of UMA is getting authorization, and Phase 3 is accessing a resource. @@ -1176,7 +1176,7 @@

    3.  Getting Authorization and Accessing a Resource

    user's protected resources at a host, under conditions dictated by that user.

    Phase 3 is merely the successful completion of a requester's access attempt -(see Section 3.1.3.2 +(see Section 3.1.3.2 (Requester's Token Has Sufficient Permission)) that initially involved several embedded interactions among the requester, AM, and host in Phase 2. Phase 2 always begins @@ -1196,60 +1196,60 @@

    3.  Getting Authorization and Accessing a Resource

    facilitating it.

    The interactions are described in detail in the following sections.

    3.  Getting Authorization and Accessing a Resource -
     TOC 
    +      TOC 

    3.1.  Requester-Host: Attempt Access at Protected Resource

    This interaction assumes that the host has previously registered with an AM @@ -1282,7 +1282,7 @@

    3.1.  Requester-Host: Attempt Access at Protected Resource

    -
     TOC 
    +  TOC 

    3.1.1.  Requester Presents No Access Token

    If the requester does not present any access token with the request, the host @@ -1301,11 +1301,11 @@

    3.1.1.  Requester Presents No Access Token

    -
     TOC 
    +  TOC 

    3.1.2.  Requester Presents an Invalid Access Token

    If the requester presents an access token with its request, the host asks the -AM to give it the requester access token's status (see Section 3.3 +AM to give it the requester access token's status (see Section 3.3 (Host-AM: Ask for Requester Access Token Status)). If the AM reports that the token is invalid, the host MUST return an HTTP 401 (Unauthorized) status code, along with @@ -1323,31 +1323,35 @@

    3.1.2.  Requester Presents an Invalid Access Token

    -
     TOC 
    +  TOC 

    3.1.3.  Requester Presents a Valid Access Token

    If the requester presents an access token with its request, the host SHOULD ask the AM to give it the requester access token's status (see Section 3.3 +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#h-am-token-validation">Section 3.3 (Host-AM: Ask for Requester Access Token Status)). If the AM supplies a token status description for a valid requester access token, the host examines the token status -description.


    +description.

    +

    When a requester presents a valid access token, the host SHOULD provide the +requester with access to the desired resource. Note that that access to +resources at a host remains at the discretion of the host, even in cases where +the requester has presented a valid access token.


    -
     TOC 
    +  TOC 

    3.1.3.1.  Requester's Token Has Insufficient Permission

    If the token status is not associated with any currently valid permission that applies to the scope of access attempted by the requester, the Host SHOULD -register the desired permission with the AM (see Section 3.4 +register the desired permission with the AM (see Section 3.4 (Host-AM: Register a Permission)) and then respond to the requester with the HTTP 403 (Forbidden) status code indicating that the token has -"insufficient_scope" (see Section 2.4.1 of [OAuth‑bearer] +"insufficient_scope" (see Section 2.4.1 of [OAuth‑bearer] (Jones, M., “The OAuth 2.0 Protocol: Bearer Tokens,” June 2011.)), along with providing the AM's URI to facilitate AM metadata discovery by the requester, and the permission ticket it @@ -1368,7 +1372,7 @@

    3.1.3.1.  Requester's Token Has Insufficient Permission

    -
     TOC 
    +  TOC 

    3.1.3.2.  Requester's Token Has Sufficient Permission

    If the token status is associated with at least one currently valid @@ -1393,17 +1397,17 @@

    3.1.3.2.  Requester's Token Has Sufficient Permission

    -
     TOC 
    +  TOC 

    3.2.  Requester-AM: Requester Obtains Access Token

    When a requester does not possess a valid access token for accessing resources of a particular user at a particular host, it requests one from the AM's requester token endpoint.

    The requester learns about this endpoint by retrieving the AM's hostmeta -document (see Section 1.5 +document (see Section 1.5 (AM Metadata)) based on the "am_uri" information that was provided by the host in its previous response, as -described in Section 2 of hostmeta +described in Section 2 of hostmeta (Hammer-Lahav, E., “Web Host Metadata,” May 2011.) [hostmeta]. For example, if the "am_uri" is "am.example.com", the requester creates the URI @@ -1414,15 +1418,15 @@

    3.2.  Requester-AM: Requester Obtains Access Token

    authorizing user), with a variety of scopes, at that same host, on behalf of the same requesting party.

    The requester SHOULD use the OAuth 2.0 client_credentials authorization grant -type (see Section 4.4 of [OAuth2] +type (see Section 4.4 of [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.)).

    If the requester does not yet have a client identifier and optional client secret prior to requesting an access token, it MAY request these using [OCDynClientReg] +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#OCDynClientReg">[OCDynClientReg] (Sakimura, N., “OpenID Connect Dynamic Client Registration 1.0,” September 2011.), if the AM -supports it (see Section 1.5 +supports it (see Section 1.5 (AM Metadata) for how the AM MAY indicate support).

    (Note that in UMA, unlike in plain OAuth, obtaining an access token does not @@ -1434,7 +1438,7 @@

    3.2.  Requester-AM: Requester Obtains Access Token

    -
     TOC 
    +  TOC 

    3.3.  Host-AM: Ask for Requester Access Token Status

    On receiving a requester access token in an access attempt, the host asks the @@ -1442,7 +1446,7 @@

    3.3.  Host-AM: Ask for Requester Access Token Status

    available that has not expired yet, it MAY use it instead.

    The host makes the request to the AM with a POST request to the AM's token status endpoint. The body of the HTTP request message contains a JSON [RFC4627] +href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#RFC4627">[RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) document providing the requester access token and the IP address of the @@ -1468,7 +1472,7 @@

    3.3.  Host-AM: Ask for Requester Access Token Status

    }

    The AM returns the token's status in an HTTP response using the 200 OK status -code, containing a JSON [RFC4627] +code, containing a JSON [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) document supplying the token status description. The token status description @@ -1530,7 +1534,7 @@

    3.3.  Host-AM: Ask for Requester Access Token Status

    -
     TOC 
    +  TOC 

    3.4.  Host-AM: Register a Permission

    If the permissions returned by the AM from a token status request are @@ -1538,7 +1542,7 @@

    3.4.  Host-AM: Register a Permission

    permission with the AM that it believes would be sufficient for the type of access sought. As a result of the host registering a permission to the AM, the AM returns a permission ticket for the host to give to the requester in its -response (see Section 3.1.3.1 +response (see Section 3.1.3.1 (Requester's Token Has Insufficient Permission)).

    The permission ticket is a short-lived opaque structure whose form is @@ -1546,7 +1550,7 @@

    3.4.  Host-AM: Register a Permission

    merely part of a predictable sequential series), to avoid denial-of-service attacks.

    Later, when the requester asks the AM to add permissions to the requester's -token (see Section 3.5 +token (see Section 3.5 (Requester-AM: Request Authorization to Add Permission) it will submit this ticket to the AM. It is therefore the task of the AM to perform binding of this ticket to the requester @@ -1554,7 +1558,7 @@

    3.4.  Host-AM: Register a Permission

    The host registers the permission using the POST method at the AM's permission registration endpoint, providing its host access token to get authorized access to this endpoint. The body of the HTTP request message -contains a JSON [RFC4627] +contains a JSON [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.) document providing the requester's access token and the requested permission. @@ -1601,7 +1605,7 @@

    3.4.  Host-AM: Register a Permission

    If the registration request fails, the AM responds with an HTTP 400 (Bad Request) status code and includes one of the following error codes (see Section 4.2 +class="info" href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#uma-error-response">Section 4.2 (UMA Error Responses)):

    @@ -1619,7 +1623,7 @@

    3.4.  Host-AM: Register a Permission

    -
     TOC 
    +  TOC 

    3.5.  Requester-AM: Request Authorization to Add Permission

    In this interaction, the requester asks the AM to grant it permission for @@ -1627,14 +1631,14 @@

    3.5.  Requester-AM: Request Authorization to Add Permission

    ticket it got from the host, along with its requester access token and other pertinent information. The AM uses the ticket to look up the previously registered permission, maps the requested permission to operative user policies, -undergoes any authorization flows required (see Section 3.6 +undergoes any authorization flows required (see Section 3.6 (Authorization Flows)), and ultimately responds to the request positively or negatively.

    The requester learns about this endpoint by retrieving the AM's hostmeta -document (see Section 1.5 +document (see Section 1.5 (AM Metadata)) based on the "am_uri" information that was provided by the host in its previous response, as -described in Section 2 of hostmeta +described in Section 2 of hostmeta (Hammer-Lahav, E., “Web Host Metadata,” May 2011.) [hostmeta]. For example, if the "am_uri" is "am.example.com", the requester creates the URI @@ -1654,7 +1658,7 @@

    3.5.  Requester-AM: Request Authorization to Add Permission

    certain URL information; however, GET typically provides a smoother user experience.)

    If the AM determines that the requesting party meets the authorization -criteria set out by the authorizing user's policy (see Section 3.6 +criteria set out by the authorizing user's policy (see Section 3.6 (Authorization Flows)), it responds with an HTTP 201 (Created) status code and provides an updated token:

    @@ -1673,7 +1677,7 @@

    3.5.  Requester-AM: Request Authorization to Add Permission

    error response.

    If the request fails due to an invalid, missing, or expired requester access token or requires higher privileges at this endpoint than provided by the access -token, the AM responds with an OAuth error (see Section 4.1 +token, the AM responds with an OAuth error (see Section 4.1 (OAuth Error Responses)).

    For example:

    HTTP/1.1 401 Unauthorized
@@ -1683,7 +1687,7 @@ 
    3.5.  Requester-AM: Request Authorization to Add Permission

    If the AM ultimately does not add the requested permission, it responds using the appropriate HTTP status code (typically 400 or 403), and includes one of the -following error codes in the response: (see Section 4.2 +following error codes in the response: (see Section 4.2 (UMA Error Responses)):

    @@ -1714,7 +1718,7 @@

    3.5.  Requester-AM: Request Authorization to Add Permission

    -
     TOC 
    +  TOC 

    3.6.  Authorization Flows

    The AM MUST base its decisions to add permissions to requester access tokens @@ -1732,10 +1736,10 @@

    3.6.  Authorization Flows

    solution for gathering standardized claims from that end-user, and allows for extensions to support other solutions for this use case and other use cases. The AM SHOULD document its claims-handling ability in its XRD metadata through the -claim_types property (see Section 1.5 +claim_types property (see Section 1.5 (AM Metadata)). For the business-level and legal implications of different technical authorization -flows, see [UMA‑trustmodel] +flows, see [UMA‑trustmodel] (Maler, E., “UMA Trust Model,” February 2011.).


    @@ -1743,7 +1747,7 @@

    3.6.  Authorization Flows

    -
     TOC 
    +  TOC 

    3.6.1.  Authorization Flow for Requester Apps Operated by End-Users

    @@ -1772,7 +1776,7 @@

    3.6.1.  Authorization Flow for Requester Apps Operated by -
     TOC 
    +  TOC 

    3.6.1.1.  Gathering Claims from Requesting End-Users with OpenID Connect

    @@ -1780,17 +1784,17 @@

    3.6.1.1.  Gathering Claims from Requesting End-Users with OpenID end-user requesting party, leveraging OpenID Connect mechanisms to transmit claims from distributed sources. If it supports this option, the AM MUST supply the "openid" value for one of its claim_types properties in its AM metadata (see -Section 1.5 +Section 1.5 (AM Metadata) for how to formulate this metadata).

    To conform to this option, the AM MUST do the following:

    @@ -1804,12 +1808,12 @@

    3.6.1.1.  Gathering Claims from Requesting End-Users with OpenID -
     TOC 
    +  TOC 

    4.  Error Messages

    Ultimately the host is responsible for either granting the access the requester attempted, or returning an error response to the requester with a -reason for the failure. [OAuth2] +reason for the failure. [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) defines several error responses for a resource server to return. UMA makes use of these error responses, but @@ -1822,21 +1826,21 @@

    4.  Error Messages

    -
     TOC 
    +  TOC 

    4.1.  OAuth Error Responses

    When a client (host or requester) attempts to access one of the AM endpoints -Section 1.5 +Section 1.5 (AM Metadata) or a client (requester) attempts to access a protected resource at the host, it has to make an authenticated request by including an OAuth access token in the HTTP request -as described in [OAuth2] +as described in [OAuth2] (Hammer-Lahav, E., “The OAuth 2.0 Protocol,” September 2011.) Section 7.

    If the client's request failed authentication, the AM or the host responds -with an OAuth error message as described throughout Section 2 +with an OAuth error message as described throughout Section 2 (Protecting a Resource) and Section 3 +class="info" href="file:///C:/Users/Thomas%20Hardjono/AppData/Local/Temp/xml2rfc-xxe-2902385992034798178.html#getting-authz-accessing-resource">Section 3 (Getting Authorization and Accessing a Resource).


    @@ -1844,11 +1848,11 @@

    4.1.  OAuth Error Responses

    -
     TOC 
    +  TOC 

    4.2.  UMA Error Responses

    When a client (host or requester) attempts to access one of the AM endpoints -Section 1.5 +Section 1.5 (AM Metadata) or a client (requester) attempts to access a protected resource at the host, if the client request is successfully authenticated by OAuth means, but is invalid for another @@ -1893,7 +1897,7 @@

    4.2.  UMA Error Responses

    -
     TOC 
    +  TOC 

    5.  Security Considerations

    This specification relies mainly on OAuth security mechanisms for protecting @@ -1908,7 +1912,7 @@

    5.  Security Considerations

    interacting with a registration area not its own.

    For information about the technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects security -considerations, see [UMA‑trustmodel] +considerations, see [UMA‑trustmodel] (Maler, E., “UMA Trust Model,” February 2011.).


    @@ -1916,7 +1920,7 @@

    5.  Security Considerations

    -
     TOC 
    +  TOC 

    6.  Privacy Considerations

    The AM comes to be in possession of resource set information (such as names @@ -1929,7 +1933,7 @@

    6.  Privacy Considerations

    mechanism.

    For information about the technical, operational, and legal elements of trust establishment between UMA entities and parties, which affects privacy -considerations, see [UMA‑trustmodel] +considerations, see [UMA‑trustmodel] (Maler, E., “UMA Trust Model,” February 2011.).


    @@ -1937,24 +1941,24 @@

    6.  Privacy Considerations

    -
     TOC 
    +  TOC 

    7.  Conformance

    This section outlines conformance requirements for various entities implementing UMA endpoints.

    This specification has dependencies on other specifications, as follows:

    Additional contributors to this specification include the Kantara UMA Work -Group participants, a list of whom can be found at [UMAnitarians] +Group participants, a list of whom can be found at [UMAnitarians] (Maler, E., “UMA Participant Roster,” 2011.).


    @@ -2277,7 +2281,7 @@

    11.  Acknowledgments

    -
     TOC 
    +  TOC 

    12.  Issues

    All issues are now captured at the project's GitHub site (https://github.com/xmlgrrl/UMA-Specifications/issues). @@ -2287,7 +2291,7 @@

    12.  Issues

    -
     TOC 
    +  TOC 

    13.  References


    @@ -2295,7 +2299,7 @@

    13.  References


    -
     TOC 
    +  TOC 

    13.1. Normative References

    @@ -2352,7 +2356,7 @@

    13.1. Normative References

    -
     TOC 
    +  TOC 

    13.2. Informative References

    @@ -2382,7 +2386,7 @@

    13.2. Informative References

    -
     TOC 
    +  TOC 

    Appendix A.  Document History

    NOTE: To be removed by RFC editor before publication as an RFC.


    @@ -2391,7 +2395,7 @@

    Appendix A.  Document History

    -
     TOC 
    +  TOC 

    Author's Address

    diff --git a/draft-uma-core.xml b/draft-uma-core.xml index bb5f82a..81efbbc 100755 --- a/draft-uma-core.xml +++ b/draft-uma-core.xml @@ -8,7 +8,7 @@ ]> - @@ -840,17 +840,15 @@ ETag: (matches "_rev" property in returned object) } ]]> - - - Optionally, upon successful registration by the host, - the AM may return a redirect policy URI to the host. - This policy URI allows the user to set access policies - at the AM for the resource set that was successfully registered by the Host. - - + + Optionally, upon successful registration by the host, the AM + may return a redirect policy URI to the host. This policy URI + allows the user to set access policies at the AM for the resource + set that was successfully registered by the Host. +
    Form of a successful HTTP response: - +
    - - -
    Reads a previously registered resource set description using @@ -1162,6 +1157,12 @@ WWW-Authenticate: UMA realm="example", supplies a token status description for a valid requester access token, the host examines the token status description. + When a requester presents a valid access token, the host SHOULD + provide the requester with access to the desired resource. Note that + that access to resources at a host remains at the discretion of the + host, even in cases where the requester has presented a valid access + token. +
    If the token status is not associated with any currently valid