Skip to main content

User-Managed Access (UMA) Profile of OAuth 2.0
draft-hardjono-oauth-umacore-06

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Author Thomas Hardjono
Last updated 2012-12-27
RFC stream (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-hardjono-oauth-umacore-06
Network Working Group                                   T. Hardjono, Ed.
Internet-Draft                                                       MIT
Intended status: Standards Track                       December 27, 2012
Expires: June 30, 2013

             User-Managed Access (UMA) Profile of OAuth 2.0
                    draft-hardjono-oauth-umacore-06

Abstract

   User-Managed Access (UMA) is a profile of OAuth 2.0.  UMA defines how
   resource owners can control access to their protected resources made
   by clients operated by arbitrary rquesting parties, where the
   resources reside on any number of resource servers, and where a
   centralized authorization server governs access based on resource
   owner policy.

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 30, 2013.

Copyright Notice

   Copyright (c) 2012 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

Hardjono                  Expires June 30, 2013                 [Page 1]
Internet-Draft                  UMA Core                   December 2012

   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.1.  Notational Conventions . . . . . . . . . . . . . . . . . .  7
     1.2.  Basic Terminology  . . . . . . . . . . . . . . . . . . . .  7
     1.3.  Endpoints, Endpoint Protection, and Tokens . . . . . . . .  8
     1.4.  Scope Types, Resource Sets, Permissions, and
           Authorization  . . . . . . . . . . . . . . . . . . . . . . 10
     1.5.  Authorization Server Configuration Data  . . . . . . . . . 12
   2.  Protecting a Resource  . . . . . . . . . . . . . . . . . . . . 15
     2.1.  Resource Server Obtains PAT  . . . . . . . . . . . . . . . 15
     2.2.  Resource Server Registers Sets of Resources to Be
           Protected  . . . . . . . . . . . . . . . . . . . . . . . . 16
   3.  Getting Authorization and Accessing a Resource . . . . . . . . 16
     3.1.  Client Attempts to Access Protected Resource . . . . . . . 18
       3.1.1.  Client Presents No RPT . . . . . . . . . . . . . . . . 19
       3.1.2.  Client Presents an RPT That Has Insufficient
               Authorization Data . . . . . . . . . . . . . . . . . . 19
       3.1.3.  Client Presents a Valid RPT with Sufficient
               Authorization Data . . . . . . . . . . . . . . . . . . 20
     3.2.  Resource Server Registers a Permission With
           Authorization Server . . . . . . . . . . . . . . . . . . . 20
     3.3.  Resource Server Determines the RPT Status  . . . . . . . . 22
       3.3.1.  UMA Bearer Token Profile . . . . . . . . . . . . . . . 22
     3.4.  Client Asks Authorization Server for RPT and
           Authorization Data . . . . . . . . . . . . . . . . . . . . 24
       3.4.1.  Client Obtains AAT . . . . . . . . . . . . . . . . . . 25
       3.4.2.  Client Obtains RPT . . . . . . . . . . . . . . . . . . 26
       3.4.3.  Client Asks for Authorization Data . . . . . . . . . . 27
     3.5.  Claims-Gathering Flows . . . . . . . . . . . . . . . . . . 29
       3.5.1.  Claims-Gathering Flow for Clients Operated by
               End-Users  . . . . . . . . . . . . . . . . . . . . . . 30
         3.5.1.1.  OpenID Connect Claim Profile . . . . . . . . . . . 31
   4.  Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 32
     4.1.  OAuth Error Responses  . . . . . . . . . . . . . . . . . . 32
     4.2.  UMA Error Responses  . . . . . . . . . . . . . . . . . . . 32
   5.  Specification of Additional Profiles . . . . . . . . . . . . . 33
     5.1.  Specifying Profiles of UMA . . . . . . . . . . . . . . . . 34
     5.2.  Specifying RPT Profiles  . . . . . . . . . . . . . . . . . 34
     5.3.  Specifying Claim Profiles  . . . . . . . . . . . . . . . . 35
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 36
   7.  Privacy Considerations . . . . . . . . . . . . . . . . . . . . 37
   8.  Conformance  . . . . . . . . . . . . . . . . . . . . . . . . . 37
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 37
   10. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 37

Hardjono                  Expires June 30, 2013                 [Page 2]
Internet-Draft                  UMA Core                   December 2012

   11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
   12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38
     12.1. Normative References . . . . . . . . . . . . . . . . . . . 38
     12.2. Informative References . . . . . . . . . . . . . . . . . . 39
   Appendix A.  Document History  . . . . . . . . . . . . . . . . . . 40
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 41

Hardjono                  Expires June 30, 2013                 [Page 3]
Internet-Draft                  UMA Core                   December 2012

1.  Introduction

   User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2].  UMA
   defines how resource owners can control access to their protected
   resources made by clients operated by arbitrary requesting parties,
   where the resources reside on any number of resource servers, and
   where a centralized authorization server governs access based on
   resource owner policy.  Resource owners configure authorization
   servers with access policies that serve as implicit authorization
   grants.  Thus, the UMA profile of OAuth includes an authorization
   grant flow.

   UMA serves numerous use cases where a resource owner outsources
   authorization for access to their resources, potentially even without
   the run-time presence of the resource owner.  A typical example is
   the following: a web user (an end-user resource owner) can authorize
   a web app (client) to gain one-time or ongoing access to a protected
   resource containing his home address stored at a "personal data
   store" service (resource server), by telling the resource server to
   respect access entitlements issued by his authorization service
   (authorization server).  The requesting party operating the client
   might be the resource owner himself, using a web or native app run by
   an e-commerce company that needs to know where to ship a purchased
   item, or it might be his friend who is using an online address book
   service to collect contact information, or it might be a survey
   company that uses an autonomous web service to compile population
   demographics.  A variety of scenarios and use cases can be found in
   [UMA-usecases] and [UMA-casestudies].

   Practical control of access among loosely coupled parties requires
   more than just messaging protocols.  This specification defines only
   the technical "contract" between UMA-conforming entities; its
   companion Binding Obligations specification [UMA-obligations] defines
   the expected behaviors of parties operating and using these entities.
   Parties operating entities that claim to be UMA-conforming MUST
   provide documentation affirmatively stating their acceptance of the
   binding obligations contractual framework defined in the Binding
   Obligations specification.

   In enterprise settings, application access management often involves
   letting back-office applications serve only as policy enforcement
   points (PEPs), depending entirely on access decisions coming from a
   central policy decision point (PDP) to govern the access they give to
   requesters.  This separation eases auditing and allows policy
   administration to scale in several dimensions.  UMA makes use of a
   separation similar to this, letting the resource owner serve as a
   policy administrator crafting authorization strategies for resources
   under their control.

Hardjono                  Expires June 30, 2013                 [Page 4]
Internet-Draft                  UMA Core                   December 2012

   The UMA protocol can be considered an advanced profile of [OAuth2].
   In order to increase interoperable communication among the
   authorization server, resource server, and client, it defines several
   purpose-built APIs related to the outsourcing of authorization,
   themselves protected by OAuth in embedded fashion.

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

               The Three Phases of the UMA Profile of OAuth
                                              +--------------+
                                              |   resource   |
             +---------manage (A)------------ |     owner    |
             |                                +--------------+
             |         Phase 1:                      |
             |         protect a                control (B)
             |         resource                      |
             v                                       v
      +------------+               +----------+--------------+
      |            |               |protection|              |
      |  resource  |               |   API    | authorization|
      |   server   |<-protect (C)--|  (needs  |    server    |
      |            |               |   PAT)   |              |
      +------------+               +----------+--------------+
      | protected  |                          | authorization|
      | resource   |                          |     API      |
      |(needs RPT) |                          |  (needs AAT) |
      +------------+                          +--------------+
             ^                                       |
             |         Phases 2 and 3:         authorize (D)
             |         get authorization,            |
             |         access a resource             v
             |                                +--------------+
             +---------access (E)-------------|    client    |
                                              +--------------+

                                              requesting party

                                 Figure 1

   In broad strokes, the phases are as follows:

   1.  Protect a resource (described in Section 2).

   2.  Get authorization (described in Section 3).

   3.  Access a resource (described along with Phase 2 in Section 3).

   In more detail, the phases work as follows:

Hardjono                  Expires June 30, 2013                 [Page 5]
Internet-Draft                  UMA Core                   December 2012

   1.  _Protect a resource:_ This phase accomplishes trust establishment
       among the resource owner, resource server, and authorization
       server, as well as enabling the resource server to register with
       the authorization server descriptions of the resources to be
       protected.  This specification uses [OAuth-resource-reg] to
       enable dynamic introduction and resource registration.  In these
       circumstances, where the resource owner has chosen to use a
       resource server for managing online resources ("A"), the resource
       owner introduces this resource server to an authorization server
       using an OAuth-mediated interaction that results in the
       authorization server giving the resource server a protection API
       token (PAT).  The resource server then uses the authorization
       server's protection API to register sets of resources for which
       protection is being outsourced ("C").  (Out of band of the UMA
       protocol, the resource owner instructs the authorization server
       what policies to associated with the registered resource sets
       ("B").)

   2.  _Get authorization:_ This phase involves the client (along with
       its operator, the "requesting party") for the first time.  The
       client approaches the resource server seeking access to a
       protected resource ("E").  In order to access it, the client must
       first obtain a requesting party token (RPT) from the
       authorization server on behalf of its requesting party.  The
       client and requesting party are then redirected to the
       authorization server to ask for appropriate authorization data
       (the form of this data depends on the RPT profile in use).  In
       doing so, the requesting party must demonstrate to the
       authorization server that it satisfies the resource owner's
       policy governing the sought-for resource and scope ("D").  To use
       the authorization server's authorization API in the first place,
       the requesting party has to agree to communication with this
       server for the purpose of seeking authorization, which results in
       the client obtaining an authorization API token (AAT).

   3.  _Access a resource:_ This phase involves the client successfully
       presenting an RPT that has sufficient authorization data
       associated with it to the resource server in order to gain access
       to the desired resource ("E").  In this sense, it is the "happy
       path" within phase 2.

   In deploying UMA, implementers are expected to develop one or more
   profiles of UMA (described in Section 5) that specify and restrict
   the various UMA protocol options, according to the deployment
   conditions.

Hardjono                  Expires June 30, 2013                 [Page 6]
Internet-Draft                  UMA Core                   December 2012

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].

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

1.2.  Basic Terminology

   UMA introduces the following new terms and enhancements of OAuth term
   definitions.

   resource owner
         The "user" in User-Managed Access; an OAuth resource owner.
         This is typically an end-user (a natural person) but it can
         also be a corporation or other legal person.

   requesting party
         An end-user, or a corporation or other legal person, that uses
         a client to seek access to a protected resource.  The
         requesting party may or may not be the same party as the
         resource owner.

   client
         An application making protected resource requests with the
         resource owner's authorization and on the requesting party's
         behalf.

   claim
         A statement of the value or values of one or more identity
         attributes of a requesting party.  A requesting party may need
         to provide claims to an authorization server in order to
         satisfy policy and gain permission for access to a protected
         resource.

   resource set  A set of one or more protected resources.  In
         authorization policy terminology, a resource set is the
         "object" being protected.

   scope type  A bounded extent of access that is possible to perform on
         a resource set.  In authorization policy terminology, a scope
         type is one of the potentially many "verbs" that can logically
         apply to a resource set ("object").  UMA associates scope types
         with labeled resource sets.

Hardjono                  Expires June 30, 2013                 [Page 7]
Internet-Draft                  UMA Core                   December 2012

   authorization data  Data associated with a requesting party token
         that enables some combination of the authorization server and
         resource server to determine the correct extent of access to
         allow to a client.  Authorization data is a key part of the
         definition of an RPT profile.

   permission  A scope of access over a particular resource set at a
         particular resource server that is being asked for by, or being
         granted to, a requesting party.  In authorization policy
         terminology, a permission is an entitlement that includes a
         "subject" (requesting party), "verbs" (one or more scopes of
         access), and an "object" (resource set).  A permission is one
         example of authorization data that an authorization server may
         grant.

   permission ticket  A correlation handle that is conveyed from an
         authorization server to a resource server, from a resource
         server to a client, and ultimately from a client to an
         authorization server, to enable the authorization server to
         assess the correct resource owner policies to apply to a
         request for an authorization grant.

1.3.  Endpoints, Endpoint Protection, and Tokens

   Various UMA entities present protected APIs for other entities to
   use.  These APIs are as follows:

   o  The authorization server presents a _protection API_ to the
      resource server, which encompasses the resource registration API
      defined by the OAuth introduction specification
      [OAuth-resource-reg], as well as additional functions standardized
      by this specification.  This API is OAuth-protected, requiring a
      resource server to obtain from the authorization server an OAuth
      access token called a _protection API token (PAT)_.

   o  The authorization server presents an _authorization API_ to the
      client, as defined wholly by this specification.  This API is
      OAuth-protected, requiring a client and its requesting party to
      obtain from the authorization server an OAuth access token,
      referred to in this specification as an _authorization API token
      (AAT)_ to distinguish it from other tokens with other purposes.

   o  The resource server presents a _protected resource_ to the client,
      which can be considered an application-specific or proprietary
      API.  This API is protected by the UMA profile of OAuth, requiring
      a client to obtain from the authorization server an OAuth access
      token, referred to in this specification as a _requesting party
      token (RPT)_ to distinguish it from other tokens with other

Hardjono                  Expires June 30, 2013                 [Page 8]
Internet-Draft                  UMA Core                   December 2012

      purposes.

   The authorization server presents standard OAuth endpoints for token
   issuance and resource owner authorization in protecting its own UMA
   APIs, as follows.  Resource servers asking to use the protection API
   would be issued a PAT.  Clients and requesting parties asking to use
   the authorization API would be issued an AAT.

   token endpoint  Part of standard OAuth, as profiled by UMA.  The
         endpoint at which the resource server asks for a PAT on the
         resource owner's behalf.  Also the endpoint at which the client
         asks for an AAT on the requesting party's behalf.  (The
         authorization server may also choose to issue a refresh token.)
         This specification makes the OAuth token profile "bearer"
         mandatory for the authorization server to implement.  It can
         declare its ability to handle other token profiles.

   user authorization endpoint  Part of standard OAuth, as profiled by
         UMA; used when the authorization code grant type (REQUIRED for
         the authorization server to implement) is being used.  The
         endpoint to which the resource server redirects an end-user
         resource owner to authorize the former to use this
         authorization server in outsourcing resource protection.  Also
         the endpoint to which the client redirects the end-user
         requesting party to authorize the former to use this
         authorization server in seeking access.

   The authorization server presents the following endpoints to the
   resource server as part of its protection API; these endpoints MUST
   be OAuth-protected and require a PAT for access, for which the
   "http://docs.kantarainitiative.org/uma/scopes/prot.json" OAuth scope
   is required:

   resource set registration endpoint  The endpoint at which the
         resource server registers resource sets it wants the
         authorization server to protect, as defined by
         [OAuth-resource-reg].  The
         "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope
         is a superset of the scope that governs usage of the resource
         set registration endpoint.

   permission registration endpoint  The endpoint at which the resource
         server registers permissions that it anticipates a client will
         shortly be asking for from the authorization server.

Hardjono                  Expires June 30, 2013                 [Page 9]
Internet-Draft                  UMA Core                   December 2012

   introspection endpoint  The endpoint at which the resource server
         forwards an RPT that has accompanied an access request to learn
         what authorization data is associated with it, as defined by
         [OAuth-introspection].  This specification defines an RPT
         profile, "bearer", which is mandatory for the authorization
         server to implement and which, if used, REQUIRES the resource
         server to use this endpoint (see Section 3.3).  The
         "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope
         is a superset of the scope that governs usage of the token
         introspection endpoint.

   The authorization server presents the following endpoints to the
   client as part of its authorization API; these endpoints are OAuth-
   protected and require an AAT for access, for which the
   "http://docs.kantarainitiative.org/uma/scopes/authorization" OAuth
   scope is required:

   RPT endpoint  The endpoint at which the client asks the authorization
         server for the issuance of an RPT relating to this requesting
         party, resource server, and authorization server.

   permission request endpoint  The endpoint at which the client asks
         for authorization data to be associated with an RPT to enable
         authorized access.

   The resource server presents one or more protected resource endpoints
   to the client; these endpoints are protected by the UMA profile of
   OAuth and require an RPT with sufficient authorization data to permit
   access:

   protected resource endpoint  An application-specific endpoint at
         which a client attempts to access resources.  This can be a
         singular API endpoint, one of a set of API endpoints, a URI
         corresponding to an HTML document, or any other URI.

   The authorization server has the opportunity to manage the validity
   periods of the access tokens, the corresponding refresh tokens where
   applicable, and even the client credentials that it issues.
   Different lifetime strategies may be suitable for different resources
   and scopes of access, and the authorization server has the
   opportunity to give the resource owner control through policy.  These
   options are all outside the scope of this specification.

1.4.  Scope Types, Resource Sets, Permissions, and Authorization

   UMA extends the OAuth concept of a "scope" by defining scope types as
   applying to labeled resource sets, rather than leaving the relevant
   resources (such as API endpoints or URIs) implicit.  A resource set

Hardjono                  Expires June 30, 2013                [Page 10]
Internet-Draft                  UMA Core                   December 2012

   can have any number of scope types, which together describe the
   universe of actions that _can be_ taken on this protected resource
   set.  For example, a resource set representing a status update API
   might have scopes that include adding an update or reading updates.
   A resource set representing a photo album might have scopes that
   include viewing a slideshow or printing the album.  Resource servers
   register resource sets and their scope types when there is not yet
   any particular requesting party or client in the picture.

   Resource sets and scope types have meaning only to resource servers
   and their users, in the same way that application-specific protected
   resource APIs have meaning only to these entities.  The authorization
   server is merely a conveyor of labels and descriptions for these
   constructs, to help the resource owner set policies that guide
   eventual authorization processes.

   A permission, in contrast to a scope type, reflects an _actual_
   entitlement to access a resource set using one or more scope types,
   as the result of an authorization process undergone by a specific
   requesting party.  A resource server registers a permission request
   with an authorization server on behalf of a client (and its
   requesting partie) that has attempted access, and transmits the
   resulting permission ticket to the client.  The client subsequently
   asks the authorization server for authorization data to be associated
   with its RPT.  If the RPT profile is in use, the authorization server
   grants (or denies) the permission to the requesting party.  (If
   another token profile is in use, the authorization server might
   generate a different type of authorization data, such as an
   authorization decision or a package of the claims it has collected.)

   An RPT is bound to a requesting party, the client being used by that
   party, the resource server at which protected resources of interest
   reside, and the authorization server that protects those resources.
   It becomes associated with as many pieces of authorization data as
   are appropriate for gaining authorized access to resources protected
   at that resource server by any single authorization server (even if
   that data applies to resources managed by two or more different
   resource owners at the same resource server using the same
   authorization server).

   In the case of the UMA "bearer" token profile, each individual
   permission is associated with the resource owner whose policies drove
   the authorization process.  This enables meaningful, auditable, and
   potentially legally enforceable authorization for access (see
   [UMA-obligations]).  Permissions have a validity period that the
   authorization server has the opportunity to control (independently or
   with input from the resource owner).  These control options are
   outside the scope of this specification.

Hardjono                  Expires June 30, 2013                [Page 11]
Internet-Draft                  UMA Core                   December 2012

1.5.  Authorization Server Configuration Data

   The authorization server MUST provide configuration data to other
   entities it interacts with in aJSON [RFC4627] document that resides
   in an /uma-configuration directory at at its hostmeta [RFC6415]
   location.  The configuration data documents major conformance options
   supported by the authorization server (described further in
   Section 8) and protection and authorization API endpoints (as
   described in Section 1.3).  (At the appropriate time, this section
   will instead profile whatever self-describing metadata specification
   OAuth adopts, for example, [OAuth-linktypes] or [OAuth-meta].)

   The configuration data has the following properties.  All endpoint
   URIs supplied SHOULD require the use of a transport-layer security
   mechanism such as TLS.

   version
         REQUIRED.  The version of the UMA core protocol to which this
         authorization server conforms.  The value MUST be the string
         "1.0".

   issuer
         REQUIRED.  A URI indicating the party operating the
         authorization server.

   dynamic_client_endpoint
         OPTIONAL.  The endpoint to use for performing dynamic client
         registration through . [DynClientReg]

   oauth_token_profiles_supported
         REQUIRED.  PAT and AAT profiles produced by this authorization
         server.  The property value is an array of string values.
         Currently the only string value for this property defined by
         this specification is "bearer", corresponding to the OAuth
         bearer token profile [OAuth-bearer].  The authorization server
         is REQUIRED to support this profile, and to supply this string
         value explicitly.  The authorization server MAY declare its
         support for additional access token profiles by providing a
         unique absolute URI in a string value in the array for each
         one.

   uma_token_profiles_supported
         REQUIRED.  RPT types produced by this authorization server.
         The property value is an array of string values.  Currently the
         only string value for this property defined by this
         specification is "bearer", whose associations the resource
         server MUST determine through a token introspection interaction
         with the authorization server (see Section 3.3 for the

Hardjono                  Expires June 30, 2013                [Page 12]
Internet-Draft                  UMA Core                   December 2012

         definition of this profile).  The authorization server is
         REQUIRED to support the UMA bearer token profile, and to supply
         this string value explicitly.  The authorization server MAY
         declare its support for RPTs using additional RPT profiles by
         providing a unique absolute URI in a string value in the array
         for each one.

   oauth_grant_types_supported
         REQUIRED.  OAuth grant types supported by this authorization
         server in issuing PATs and AATs.  The property value is an
         array of string values.  Each string value MUST be one of the
         grant_type values defined in [OAuth2], or alternatively an
         extension grant type indicated by a unique absolute URI.

   claim_profiles_supported
         OPTIONAL.  Claim formats and associated sub-protocols for
         gathering claims from requesting parties, as supported by this
         authorization server.  The property value is an array of string
         values.  Currently the only string value for this property
         defined by this specification is "openid", for which details
         are supplied in Section 3.5.1.1.  The authorization server MAY
         declare its support for additional claim profiles by assigning
         a unique absolute URI in a string value in the array for each
         one.

   token_endpoint
         REQUIRED.  The endpoint URI at which the resource server or
         client asks the authorization server for a PAT or AAT,
         respectively.  A requested scope of
         "http://docs.kantarainitiative.org/uma/scopes/prot.json"
         results in a PAT.  A requested scope of
         "http://docs.kantarainitiative.org/uma/scopes/authorization"
         results in an AAT.  Available HTTP methods are as defined by
         [OAuth2] for a token endpoint.

   user_endpoint
         REQUIRED.  The endpoint URI at which the resource server
         gathers the consent of the end-user resource owner or the
         client gathers the consent of the end-user requesting party, if
         the "authorization_code" grant type is used.  Available HTTP
         methods are as defined by [OAuth2] for an end-user
         authorization endpoint.

   permission_registration_endpoint
         REQUIRED.  The endpoint URI at which the resource server
         registers permissions with the authorization server for which a
         client will be seeking authorization on its requesting party's
         behalf (see Section 3.2).  A PAT MUST accompany requests to

Hardjono                  Expires June 30, 2013                [Page 13]
Internet-Draft                  UMA Core                   December 2012

         this protected endpoint.

   rpt_endpoint
         REQUIRED.  The endpoint URI at which the client ask the
         authorization server for an RPT.  An AAT token MUST accompany
         requests to this protected endpoint.

   rpt_status_endpoint
         REQUIRED.  The endpoint URI at which the resource server
         introspects an RPT presented to it by a client (see
         Section 3.3).  A PAT MUST accompany requests to this protected
         endpoint.

   permission_request_endpoint
         REQUIRED.  The endpoint URI at which the client asks, on its
         requesting party's behalf, to have authorization data
         associated with its RPT.  An AAT MUST accompany requests to
         this protected endpoint.

   Example of authorization server configuration data that resides at
   https://example.com/.well-known/uma-configuration (note the use of
   https: for endpoints throughout):
{
"version":"1.0",
"issuer":"https://example.com",
"dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
"oauth_token_profiles_supported":[
  "bearer"
],
"uma_token_profiles_supported":[
  "bearer"
],
"oauth_grant_types_supported":[
  "authorization_code"
],
"claim_profiles_supported":[
  "openid"
],
"token_endpoint":"https://as.example.com/token_uri",
"user_endpoint":"https://as.example.com/user_uri",
"resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
"rpt_status_endpoint":"https://as.example.com/rs/status_uri",
"permission_registration_endpoint":"https://as.example.com/rs/perm_uri",
"rpt_endpoint":"https://as.example.com/client/rpt_uri",
"permission_request_endpoint":"https://as.example.com/client/perm_uri"
}

   Authorization server configuration data MAY contain extension

Hardjono                  Expires June 30, 2013                [Page 14]
Internet-Draft                  UMA Core                   December 2012

   properties that are not defined in this specification.  Extension
   names that are unprotected from collisions are outside the scope of
   the current specification.

2.  Protecting a Resource

   Phase 1 of UMA is protecting a resource.  The resource owner,
   resource server, and authorization server perform the following steps
   to successfully complete Phase 1 (assuming that the resource server
   has discovered the authorization server's configuration data and
   endpoints as needed):

   o  The resource server and authorization server establish mutual
      trust through the issuance of client credentials to the resource
      server.  It is OPTIONAL for the client credentials to be provided
      dynamically through [DynClientReg]); alternatively, they MAY use a
      static process.

   o  The resource owner, resource server, and authorization server
      establish three-way trust through the issuance of a PAT.  See
      Section 2.1 for additional details.

   o  The resource server registers any resource sets with the
      authorization server that are intended to be protected.  See
      Section 2.2 for additional details.

2.1.  Resource Server Obtains PAT

   In this step, the resource server acquires a PAT from the
   authorization server.  The token represents the approval of the
   resource owner for this resource server to trust this authorization
   server for protecting resources belonging to this resource owner.  It
   is OPTIONAL for the resource owner to introduce the resource server
   to the authorization server dynamically through the process defined
   in [OAuth-resource-reg]); alternatively, they MAY use a static
   process that may or may not directly involve the resource owner at
   introduction time.

   The resource server MUST use OAuth 2.0 [OAuth2] to obtain the PAT.
   Here the resource server acts in the role of an OAuth client
   requesting the
   "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope, which
   authorizes it to use the authorization server's resource set
   registration endpoint (as defined in [OAuth-resource-reg]) as well as
   additional protection API endpoints.  Once the resource server has
   obtained its PAT, it presents it to the authorization server at
   various protection API endpoints.

Hardjono                  Expires June 30, 2013                [Page 15]
Internet-Draft                  UMA Core                   December 2012

   (NOTE: The "http://docs.kantarainitiative.org/uma/scopes/prot.json"
   scope keyword is a URI that resolves to a JSON-encoded scope
   description, in the fashion of UMA scope types.  This scope
   description is non-normative.)

   The authorization server MAY support the use of any OAuth grant type
   for PAT issuance, but MUST support the authorization_code grant type,
   and SHOULD support the SAML bearer token grant type [OAuth-SAML]
   (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates
   working with resource servers that are operating in environments
   where the use of SAML is prevalent.  The authorization server MUST
   indicate all grant types it supports for PAT issuance in its
   configuration data.

2.2.  Resource Server Registers Sets of Resources to Be Protected

   Once the resource server has received a PAT, for any of the resource
   owner's sets of resources that are to be protected by this
   authorization server, it registers these resource sets in a timely
   fashion.  To do this, the resource server uses the resource set
   registration API defined in [OAuth-resource-reg].

   Note: The resource server is free to offer the option to protect any
   subset of the resource owner's resources using different
   authorization servers or other means entirely, or to protect some
   resources and not others.  Additionally, the choice of protection
   regimes can be made explicitly by the resource owner or implicitly by
   the resource server.  Any such partitioning by the resource server or
   owner is outside the scope of this specification.

   On successfully registering a resource set, the RS MUST use access
   control mechanisms to limit access to any resources corresponding to
   this resource set, relying on the AS to supply currently valid
   permissions for authorized access.  The RS MUST outsource protection
   to the AS according to the currently registered state of a resource
   set.  This requirement holds true so long as the RS has one or more
   registsred resource sets.

3.  Getting Authorization and Accessing a Resource

   Phase 2 of UMA is getting authorization, and phase 3 is accessing a
   resource.  In these phases, an authorization server orchestrates and
   controls clients' access (on their requesting parties' behalf) to a
   resource owner's protected resources at a resource server, under
   conditions dictated by that resource owner.

   Phase 3 is merely the successful completion of a client's access

Hardjono                  Expires June 30, 2013                [Page 16]
Internet-Draft                  UMA Core                   December 2012

   attempt that initially involved several embedded interactions among
   the client, requesting party, authorization server, and resource
   server in phase 2.  Phase 2 always begins with the client attempting
   access at a protected resource endpoint at the resource server.  How
   the client came to learn about this endpoint is out of scope for this
   specification.  The resource owner might, for example, have
   advertised its availability publicly on a blog or other website,
   listed it in a discovery service, or emailed a link to a particular
   intended requesting party.

   The resource server responds to the client's access request in one of
   several ways depending on the circumstances of the request, either
   immediately or having first performed one or more embedded
   interactions with the authorization server.  Depending on the nature
   of the resource server's response to an failed access attempt, the
   client and its operator engage in embedded interactions with the
   authorization server before re-attempting access.

   The interactions are as follows.  Each interaction MAY be the last,
   if the client chooses not to continue pursuing the access attempt or
   the resource server chooses not to continue facilitating it.

   1.  The client attempts access at a particular protected resource at
       a resource server (see Section 3.1).

       A.  If the access attempt is unaccompanied by an RPT, the
           resource server responds immediately with an HTTP 401
           (Unauthorized) response and instructions on where to go to
           obtain one (see Section 3.4.2).

       B.  If the access attempt was accompanied by an RPT, the resource
           server checks the RPT's status (see Section 3.3).

           1.  If the RPT is invalid (for example, it is not applicable
               to this resource server), the resource server responds to
               the client with an HTTP 401 (Unauthorized) response and
               instructions on where to go to obtain a token (see
               Section 3.4.2).

           2.  If the RPT is valid but has insufficient permission, the
               resource server registers a suitable permission request
               on the client's behalf at the authorization server (see
               Section 3.2), and then responds to the client with an
               HTTP 403 (Forbidden) response and instructions on where
               to go to ask for authorization (see Section 3.1.2).

           3.  If the RPT is valid, and if the authorization data
               associated with the token is consistent with allowing

Hardjono                  Expires June 30, 2013                [Page 17]
Internet-Draft                  UMA Core                   December 2012

               access, the resource server responds to the client's
               access attempt with an HTTP 200 (OK) response and a
               representation of the resource (see Section 3.1.3).

   2.  If the client (possessing no RPT or an invalid RPT) received a
       401 response and an RPT endpoint, it then requests an RPT from
       that endpoint (see Section 3.4.2).

   3.  If the client (posessing a valid RPT) received a 403 response and
       a permission ticket, it then asks the authorization server for
       authorization data that matches the ticket (Section 3.4.3).  If
       the authorization server needs requesting party claims in order
       to assess this client's authorization, it engages in a claims-
       gathering flow with the requesting party (see Section 3.5).

       A.  If the client does not already have an AAT at the appropriate
           authorization server to be able to use its permission request
           endpoint, it first obtains one (see Section 3.4.1).

   The interactions are described in detail in the following sections.

3.1.  Client Attempts to Access Protected Resource

   This interaction assumes that the resource server has previously
   registered with an authorization server one or more resource sets
   that correspond to the resource to which access is being attempted,
   such that the resource server considers this resource to be protected
   by a particular authorization server.

   The client typically attempts to access the desired resource at the
   resource server directly (for example, when an end-user requesting
   party clicks on a thumbnail representation of the resource).  The
   client is expected to discover, or be provisioned or configured with,
   knowledge of the protected resource and its location out of band.
   Further, the client is expected to acquire its own knowledge about
   the application-specific methods made available by the resource
   server for operating on this protected resource (such as viewing it
   with a GET method, or transforming it with some complex API call) and
   the possible scopes of access.

   Example of a request carrying no RPT:

   GET /album/photo.jpg HTTP/1.1
   Host: photoz.example.com
   ...

Hardjono                  Expires June 30, 2013                [Page 18]
Internet-Draft                  UMA Core                   December 2012

   Example of a request carrying an RPT using the UMA "bearer" token
   profile:

   GET /album/photo.jpg HTTP/1.1
   Authorization: Bearer vF9dft4qmT
   Host: photoz.example.com
   ...

   The resource server responds in one of the following ways.

3.1.1.  Client Presents No RPT

   If the client does not present any access token with the request, the
   resource server MUST return an HTTP 401 (Unauthorized) status code,
   along with providing the authorization server's URI in an "as_uri"
   property to facilitate authorization server configuration data
   discovery, including discovery of the endpoint where the client can
   request an RPT (Section 3.4.2).

   For example:

   HTTP/1.1 401 Unauthorized
      WWW-Authenticate: UMA realm="example",
       host_id="photoz.example.com",
       as_uri="http://am.example.com"
      ...

3.1.2.  Client Presents an RPT That Has Insufficient Authorization Data

   If the client presents an RPT with its request, the resource server
   SHOULD determine the RPT's status (see Section 3.3).  If the RPT is
   invalid, the resource server redirects the client to the RPT endpoint
   at the authorization server to obtain a correct RPT (see
   Section 3.4.2).

   If the RPT is valid but has insufficient permission for the type of
   access sought, the resource server SHOULD register a permission with
   the authorization server that would suffice for that scope of access
   (see Section 3.2), and then respond to the client with the HTTP 403
   (Forbidden) status code, along with providing the authorization
   server's URI in the header of the message and the permission ticket
   it just received from the authorization server in the body in JSON
   form.

Hardjono                  Expires June 30, 2013                [Page 19]
Internet-Draft                  UMA Core                   December 2012

   Example of the host's response:

   HTTP/1.1 403 Forbidden
   WWW-Authenticate: UMA realm="example",
     host_id="photoz.example.com",
     as_uri="http://am.example.com"
     error="insufficient_scope"

   {
   "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
   }

3.1.3.  Client Presents a Valid RPT with Sufficient Authorization Data

   If the RPT's status is associated with authorization data that is
   consistent with authorized access of the scope sought by the client
   (see Section 3.3), the resource server MUST give access to the
   desired resource.

   Example of the resource server's response:

   HTTP/1.1 200 OK
   Content-Type: image/jpeg
   ...

   /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
   3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
   /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
   KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb

   This response constitutes the conclusion of [hase 3 of UMA.

   The resource server MUST NOT give access where the token's status is
   not associated with sufficient authorization data for the attempted
   scope of access.

3.2.  Resource Server Registers a Permission With Authorization Server

   In response to receiving an access request accompanied by an RPT that
   is invalid or has insufficient authorization data, the resource
   server SHOULD register a permission with the authorization server
   that would be sufficient for the type of access sought.  The
   authorization server returns a permission ticket for the resource
   server to give to the client in its response.

   The permission ticket is a short-lived opaque structure whose form is
   determined by the authorization server.  The ticket value MUST be
   securely random (for example, not merely part of a predictable

Hardjono                  Expires June 30, 2013                [Page 20]
Internet-Draft                  UMA Core                   December 2012

   sequential series), to avoid denial-of-service attacks.  Since the
   ticket is an opaque structure from the point of view of the client,
   the authorization server is free to include information regarding
   expiration time within the opaque ticket for its own consumption.
   When the client subsequently asks the authorization server for
   authorization data to be associated with its RPT, it will submit this
   ticket to the authorization server.

   The resource server registers the permission using the POST method at
   the authorization server's permission registration endpoint.  The
   resource server MUST provide its valid PAT in order to get access to
   this endpoint.  The body of the HTTP request message contains a JSON
   document providing the requested permission.

   The requested scope is an object with the name "requested_permission"
   and the following properties:

   resource_set_id  REQUIRED.  The identifier for a resource set, access
      to which this client is seeking access.  The identifier MUST
      correspond to a resource set that was previously registered.

   scopes  REQUIRED.  An array referencing one or more identifiers of
      scope types to which access is needed for this resource set.  Each
      scope type identifier MUST correspond to a scope type that was
      registered by this resource server for the referenced resource
      set.

   Example of an HTTP request that registers a permission at the
   authorization server's permission registration endpoint:

   POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
   Content-Type: application/json
   Host: am.example.com

   {
     "resource_set_id": "112210f47de98100",
     "scopes": [
         "http://photoz.example.com/dev/actions/view",
         "http://photoz.example.com/dev/actions/all"
     ]
   }

   If the registration request is successful, the authorization server
   responds with an HTTP 201 (Created) status code and includes the
   Location header in its response as well as the "ticket" property in
   the JSON-formatted body.

Hardjono                  Expires June 30, 2013                [Page 21]
Internet-Draft                  UMA Core                   December 2012

   For example:

HTTP/1.1 201 Created
Content-Type: application/uma-permission-ticket+json
Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543
...

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}

   If the registration request is authenticated properly but fails due
   to other reasons, the authorization server responds with an HTTP 400
   (Bad Request) status code and includes one of the following UMA error
   codes (see Section 4.2):

   invalid_resource_set_id  The provided resource set identifier was not
      found at the authorization server.

   invalid_scope  At least one of the scopes included in the request was
      not registered previously by this resource server.

3.3.  Resource Server Determines the RPT Status

   On receiving an RPT, the resource server MUST ascertain its status
   before granting or denying access to the client.  An RPT is
   associated with a set of authorization data that governs whether the
   client is authorized for access.  The token's nature and format are
   dictated by its profile; the profile might allow it to be self-
   contained, such that the resource server is able to ascertain its
   status locally, or might require or allow the resource server to make
   a run-time introspection request of the authorization server that
   issued the token using [OAuth-introspection].

   This specification makes one type of RPT mandatory to implement: the
   UMA bearer token profile, as defined in Section 3.3.1.  Alternate RPT
   profiles MAY define their own unique token formats and MAY require,
   allow, or prohibit use of the token introspection endpoint.

3.3.1.  UMA Bearer Token Profile

   This section defines the format and protocol requirements for the UMA
   bearer token profile.  An authorization server MUST support the UMA
   bearer token profile and MUST indicate its support in the
   "uma_token_profiles_supported" property in its configuration data
   (see Section 1.5).

   On receiving an RPT of the "Bearer" type in an authorization header

Hardjono                  Expires June 30, 2013                [Page 22]
Internet-Draft                  UMA Core                   December 2012

   from a client making an access attempt, the resource server MUST use
   the authorization server's token introspection endpoint
   [OAuth-introspection] to retrieve the RPT's associated authorization
   data.  In order to ask the authorization server for an RPT's status,
   the host makes the request to the authorization server with a POST
   request to the authorization server's token introspection endpoint.
   The body of the HTTP request message contains a JSON document
   providing the RPT.  The host MUST provide its own PAT in the request
   in order to gain access to the RPT status endpoint.

   Example of a request to the RPT status endpoint that provides the PAT
   in the header:

   POST /token_status HTTP/1.1
   Host: am.example.com
   Authorization: Bearer vF9dft4qmT
   ...

   {
     "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
     "resource_set_id": "112210f47de98100",
     "host_id": "photoz.example.com"
   }

   The authorization server returns the RPT's status in an HTTP response
   using the 200 OK status code, containing a JSON document supplying
   the RPT's associated permissions.  The RPT status description either
   contains all of the permissions that are currently valid for this RPT
   or indicates that the RPT is invalid (see Section 1.4).  The
   authorization server MAY set a cache period for the returned RPT
   status description that allows the host to reuse it over some period
   of time when it later sees the same RPT.

   The status description for a valid RPT is a JSON array of zero or
   more permission objects, each with the following properties (this
   needs to be synced up with the token introspection spec):

   resource_set_id  REQUIRED.  A string that uniquely identifies the
      resource set, access to which has been granted to this client on
      behalf of this requesting party.  The identifier MUST correspond
      to a resource set that was previously registered as protected.

   scopes  REQUIRED.  An array referencing one or more URIs of scopes to
      which access was granted for this resource set.  Each scope MUST
      correspond to a scope that was registered by this host for the
      referenced resource set.

Hardjono                  Expires June 30, 2013                [Page 23]
Internet-Draft                  UMA Core                   December 2012

   exp  REQUIRED.  An integer representing the expiration time on or
      after which the permission MUST NOT be accepted for authorized
      access.  The processing of the exp property requires that the
      current date/time MUST be before the expiration date/time listed
      in the exp claim.  Host implementers MAY provide for some small
      leeway, usually no more than a few minutes, to account for clock
      skew.

   Example:

   HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store
   ...

   [
     {
       "resource_set_id": "112210f47de98100",
       "scopes": [
         "http://photoz.example.com/dev/actions/view",
         "http://photoz.example.com/dev/actions/all"
       ],
       "exp": 1300819380
     }
   ]

   The token status description for an invalid RPT is a JSON structure,
   as follows.

   HTTP/1.1 200 OK
   Content-Type: application/json
   ...

   {
     "rpt_status": "invalid"
   }

3.4.  Client Asks Authorization Server for RPT and Authorization Data

   A client making an access attempt accompanied by no RPT or by an
   invalid RPT will receive a 401 response back from the resource
   server, along with the authorization server's location from which it
   can learn the RPT endpoint.  In this case, the client must obtain a
   valid RPT from the authorization server's RPT endpoint provided in
   the response (see Section 3.4.2).

   A client making an access attempt with a valid RPT that has
   insufficient authorization data associated with it will receive a 403

Hardjono                  Expires June 30, 2013                [Page 24]
Internet-Draft                  UMA Core                   December 2012

   response back from the resource server, along with a permission
   ticket and the authorization server's location from which it can
   learn the permission request endpoint.  In this case, the client uses
   the permission ticket to ask for the necessary authorization data to
   be associated with its RPT.  This process necessarily involves the
   requesting party because the authorization is sought on this party's
   behalf.

   The client takes action in the following ways (assuming that it has
   discovered the authorization server's configuration data and
   endpoints as required):

   o  The client and authorization server establish mutual trust through
      the issuance of client credentials to the client.  It is OPTIONAL
      for the client credentials to be provided dynamically through
      [DynClientReg]); alternatively, they MAY use a static process.

   o  The requesting party, client, and authorization server establish
      three-way trust through the issuance of an AAT.  See Section 3.4.1
      for additional details.

   o  The client obtains an RPT.  See Section 3.4.2 for additional
      details.

3.4.1.  Client Obtains AAT

   In this step, the client acquires an AAT from the authorization
   server on the requesting party's behalf.  The token represents the
   approval of this requesting party for this client to engage with this
   authorization server to supply claims, ask for authorization, and
   perform any other tasks needed for obtaining authorization for access
   to resources at all resource servers that use this authorization
   server.  It is OPTIONAL for the requesting party to introduce the
   client to the authorization server dynamically through the process
   defined in [OAuth-resource-reg]); alternatively, they MAY use a
   static process that does not directly involve the requesting party.

   The client MUST use OAuth 2.0 [OAuth2] to obtain the AAT.  Here the
   client requests the
   "http://docs.kantarainitiative.org/uma/scopes/authz.json" scope.
   Once the client has obtained its AAT, it presents it to the
   authorization server at the permission request endpoint.

   (NOTE: The "http://docs.kantarainitiative.org/uma/scopes/authz.json"
   scope keyword is a URI that resolves to a JSON-encoded scope
   description, in the fashion of UMA scope types.  This scope
   description is non-normative.)

Hardjono                  Expires June 30, 2013                [Page 25]
Internet-Draft                  UMA Core                   December 2012

   The authorization server MAY support the use of any OAuth grant type
   for AAT issuance, but MUST support the authorization_code grant type,
   and SHOULD support the SAML bearer token grant type [OAuth-SAML]
   (urn:ietf:params:oauth:grant-type:saml2-bearer) if it anticipates
   working with clients that are operating in environments where the use
   of SAML is prevalent.  The authorization server MUST indicate all
   grant types it supports for AAT issuance in its configuration data.

   By virtue of being able to identify this client/requesting party pair
   uniquely across all resource servers whose resources it protects, the
   authorization server is able to manage the process of authorization
   and claims-gathering efficiently.  These management processes are
   outside the scope of this specification.

3.4.2.  Client Obtains RPT

   In this step, if the client needs an RPT that applies to this
   requesting party for this resource server and this authorization
   server, it obtains an RPT.  On first issuance the RPT is associated
   with no authorization data and thus does not convey any
   authorizations for access.

   The clieint performs a POST on the RPT endpoint.  It MUST provide its
   own AAT in the header.

   Example of a request message containing an AAT:
   POST /rpt HTTP/1.1
   Host: am.example.com
   Authorization: Bearer jwfLG53^sad$#f
   ...

   The authorization server responds with an HTTP 201 (Created) status
   code and provides a new RPT.

   For example:

   HTTP/1.1 201 Created
   Content-Type: application/uma-rpt+json

   {
     "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
   }

   If the content-type of the request is not recognized by the
   authorization server, the latter MUST produce an HTTP error.

   The client might need an RPT if it has never before requested an RPT
   for this combination of requesting party, resource server, and

Hardjono                  Expires June 30, 2013                [Page 26]
Internet-Draft                  UMA Core                   December 2012

   authorization server, or if it has lost control of a previously
   issued RPT and needs a refreshed one.  If the AAT provided in the
   header is the same as one provided for a previously issued RPT by
   this authorization server, the authorization server invalidates the
   old RPT and issues a new one.

   If the request fails due to missing or invalid parameters, or is
   otherwise malformed, the authorization server SHOULD inform the
   client of the error by sending an HTTP error response.

   If the request fails due to an invalid, missing, or expired AAT or
   requires higher privileges at this endpoint than provided by the AAT,
   the authorization server responds with an OAuth error (see
   Section 4.1).

   For example:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer realm="example",
     error="invalid_token",
     error_description="The access token expired"

3.4.3.  Client Asks for Authorization Data

   Once in possession of an AAT for this authorization server, an RPT
   that applies to this requesting party for this resource server and
   this authorization server, and a permission ticket, the client asks
   the authorization server to give it suitable authorization data for
   the sought-for access.  The client performs a POST on the permission
   request endpoint, supplying the items below.  The client MUST provide
   its own AAT in the header.

   o  The permission ticket it received from the resource server

   o  Its RPT for this resource server

   o  Its own AAT in the header

Hardjono                  Expires June 30, 2013                [Page 27]
Internet-Draft                  UMA Core                   December 2012

   Example of a request message containing a permission ticket and RPT:
   POST /token_status HTTP/1.1
   Host: am.example.com
   Authorization: Bearer jwfLG53^sad$#f
   ...

   {
    "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
    "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
   }

   In this interaction, the client uses the authorization server's
   permission request endpoint.

   The authorization server uses the ticket to look up the details of
   the previously registered permission, maps the requested permission
   to operative resource owner policies, undergoes any authorization
   flows required (see Section 3.5), and ultimately responds to the
   request positively or negatively.  The resource owner's policies at
   the authorization server amount to an implicit authorization grant in
   governing the issuance of authorization data.  (The authorization
   server is also free to enable resource owners to set policies that
   require them to provide a run-time explicit authorization grant
   mediated by the authorization server.  This setting of policies and
   gathering of authorization grants is outside the scope of this
   specification.)

   If the request fails due to an invalid, missing, or expired AAT (or
   RPT) or requires higher privileges at this endpoint than provided by
   the AAT, the authorization server responds with an OAuth error (see
   Section 4.1).

   For example:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer realm="example",
     error="invalid_token",
     error_description="The access token expired"

   If the authorization server does not add the requested authorization
   data, 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):

   invalid_requester_ticket  The provided ticket was not found at the
      authorization server.  The authorization server SHOULD respond
      with the HTTP 400 (Bad Request) status code.

Hardjono                  Expires June 30, 2013                [Page 28]
Internet-Draft                  UMA Core                   December 2012

   expired_requester_ticket  The provided ticket has expired.  The
      authorization server SHOULD respond with the HTTP 400 (Bad
      Request) status code.

   not_authorized_permission  The client is definitively not authorized
      for this authorization according to user policy.  The
      authorization server SHOULD respond with the HTTP 403 (Forbidden)
      status code.

   need_claims  The authorization server is unable to determine whether
      the client is authorized for this permission without gathering
      claims from the requesting party.  The authorization server SHOULD
      respond with the HTTP 403 (Forbidden) status code.  The client is
      therefore not authorized, but has the opportunity to engage its
      operator -- the requesting party -- in a claims-gathering flow
      with the authorization server (see Section 3.5) to potentially
      become authorized.

   For example:

   HTTP/1.1 400 Bad Request
   Content-Type: application/uma-status+json
   Cache-Control: no-store
   ...

   {
     "status": "error",
     "error": "expired_requester_ticket"
   }

3.5.  Claims-Gathering Flows

   The authorization server MUST base the addition of authorization data
   to RPTs on user policies.  The nature of these policies is outside
   the scope of UMA, but generally speaking, they can be thought of as
   either independent of requesting-party features (for example, time of
   day) or dependent on requesting-party features (for example, whether
   they are over 18).  This latter case requires the requesting party to
   transmit identity claims to the AM in some fashion.

   The process for requesting and providing claims is extensible and may
   have a variety of dependencies on the type of requesting party (for
   example, natural person or legal person) and the type of client (for
   example, browser, native app, or autonomously running web service).
   UMA provides a framework for handling end-user-driven clients and an
   optional solution for gathering standardized claims from such an end-
   user, and allows for extensions to support other solutions for this
   use case and other use cases.  The authorization server SHOULD

Hardjono                  Expires June 30, 2013                [Page 29]
Internet-Draft                  UMA Core                   December 2012

   document its claims-handling ability in its configuration data
   through the claim_profiles_supported property (see Section 1.5).  For
   the business-level and legal implications of different technical
   authorization flows, see [UMA-obligations].

3.5.1.  Claims-Gathering Flow for Clients Operated by End-Users

   A client, whether web-based or native, is operated by an end-user in
   one of two typical situations:

   o  The requesting party is a natural person (for example, a friend of
      the resource owner); the requesting party may even be the resource
      owner herself.

   o  The requesting party is a legal person such as a corporation, and
      the end-user operating the client is acting as an agent of that
      legal person (for example, a customer support specialist
      representing a credit card company).

   For convenience, this specification refers to the end-user as a
   "requesting end-user" to cover both cases, which differ only at the
   level of business agreements (and potentially law), rather than
   technology.  The authorization server has a variety of options at
   this point for satisfying the resource owner's policy; this
   specification does not dictate a single answer.  For example, the
   authorization server could require the requesting end-user to
   register for and/or log in to a local authorization server account,
   or to fill in a questionnaire, or to complete a purchase.  It could
   even require several of these operations, where the order is treated
   as significant.  A variety of claim profiling can be defined to
   achieve these effects.

   An end-user-driven client MUST redirect the requesting end-user to
   the authorization server to complete the process of authorization.
   The redirection MUST include a URI query parameter with the name
   "ticket" whose value conveys the permission ticket for which the
   need_claims error was received; for example, "ticket=016f84e8-f9b9-
   11e0-bd6f-0021cc6004de".  Each claim profile MUST provide the
   following capabilities:

   redirect URI  A means by which the client MUST supply the URI to
      which the authorization server MUST redirect the requesting end-
      user at the end of the claims-gathering process.

   callback URI  A means by which the client OPTIONALLY supplies a
      callback URI for the authorization server to use.

Hardjono                  Expires June 30, 2013                [Page 30]
Internet-Draft                  UMA Core                   December 2012

   state  A means by which the client SHOULD supply an opaque value used
      to maintain state between the request and the callback; this
      serves as a protection against XSRF attacks.

   An authorization server MAY support any number of claim profiles.
   One potential such profile is defined in this specification: the
   "openid" claim profile, which leverages OpenID Connect for gathering
   generally useful identity claims (see Section 3.5.1.1).

3.5.1.1.  OpenID Connect Claim Profile

   This section defines the OpenID Connect claim profile for UMA.
   Following is a summary:

   o  Identifying URI: http://docs.kantarainitiative.org/uma/profiles/
      uma-claim-openid-1.0

   o  Profile author and contact information: Thomas Hardjono
      (hardjono@mit.edu)

   o  Updates or obsoletes: None; this profile is new.

   o  Authorization server configuration data: To indicate support,
      supply the keyword "openid" in the "claim_profiles_supported"
      property value.

   o  Syntax and semantics of claim data: As defined below.  The claim
      data format leverages the OpenID Connect protocol and the reserved
      claims defined in that specification.

   o  Claims gathering method: As defined below.

   o  Error states: None additional.

   o  Security and privacy considerations: None additional.

   o  Binding obligations: Binding obligations that apply to the use of
      this claim profile are documented in [UMA-obligations].

   If an authorization server supports the OpenID Connect claim profile,
   it MUST supply the "openid" value for one of its
   "claim_profiles_supported" values in its configuration data.

   To conform to this option, the authorization server MUST do the
   following:

   o  Serve as a conforming OpenID Relying Party and Claims Client
      according to [OCStandard]

Hardjono                  Expires June 30, 2013                [Page 31]
Internet-Draft                  UMA Core                   December 2012

   o  Be able to utilize at least all of the reserved claims defined in
      [OCMessages] in assessing policy and granting permissions

   o  Use the OpenID Connect "redirect_uri" and "state" request
      parameters as appropriate

   The authorization server can then use any conforming OpenID Connect
   mechanisms and typical user interfaces for engaging with the UserInfo
   endpoints of OpenID Providers and Claims Providers, potentially
   allowing for the delivery of "trusted claims" (such as a verified
   email address or a date or birth) on which authorization policy may
   depend.

4.  Error Messages

   Ultimately the resource server is responsible for either granting the
   access the client attempted, or returning an error response to the
   client with a reason for the failure.  [OAuth2] defines several error
   responses for a resource server to return.  UMA makes use of these
   error responses, but requires the resource server to "outsource" the
   determination of some error conditions to the authorization server.
   UMA defines its own additional error responses that the authorization
   server may give to the resource server and client as they interact
   with it, and that the resource server may give to the client.

4.1.  OAuth Error Responses

   When a resource server or client attempts to access one of the
   authorization server endpoints Section 1.5 or a client attempts to
   access a protected resource at the resource server, it has to make an
   authenticated request by including an OAuth access token in the HTTP
   request as described in [OAuth2] Section 7.

   If the request failed authentication, the authorization server or the
   resource server responds with an OAuth error message as described
   throughout Section 2 and Section 3.

4.2.  UMA Error Responses

   When a resource server or client attempts to access one of the
   authorization server endpoints Section 1.5 or a client attempts to
   access a protected resource at the resource server, if the request is
   successfully authenticated by OAuth means, but is invalid for another
   reason, the authorization server or resource server responds with an
   UMA error response by adding the following properties to the entity
   body of the HTTP response:

Hardjono                  Expires June 30, 2013                [Page 32]
Internet-Draft                  UMA Core                   December 2012

   error  REQUIRED.  A single error code.  Value for this property is
      defined in the specific authorization server endpoint description.

   error_description  OPTIONAL.  Human-readable text providing
      additional information, used to assist in the understanding and
      resolution of the error occurred.

   error_uri  OPTIONAL.  A URI identifying a human-readable web page
      with information about the error, used to provide the end-user
      with additional information about the error.

   Common error codes:

   invalid_request  The request is missing a required parameter or is
      otherwise malformed.  The authorization server MUST respond with
      the HTTP 400 (Bad Request) status code.

   For example:

HTTP/1.1 400 Bad Request
Content-Type: application/uma-status+json
Cache-Control: no-store
...

{
  "status": "error",
  "error": "invalid_request",
  "error_description": "There is already a resource with this identifier.",
  "error_uri": "http://am.example.com/errors/resource_exists"
}

5.  Specification of Additional Profiles

   This specification defines a protocol that has optional features in
   it.  For interoperability and deployment purposes to serve particular
   use cases, third parties may want to define profiles of the UMA core
   protocol that restrict these options.

   Further, this specification has two modular and extensible elements
   of its design that are specified in terms of specific kinds of
   profiles:

   o  RPT token formats and associated sub-protocol flows: These are
      specified in terms of RPT profiles.

   o  Claims-gathering sub-protocol flows and specific claim types:
      These are specified in terms of claim profiles.

Hardjono                  Expires June 30, 2013                [Page 33]
Internet-Draft                  UMA Core                   December 2012

   Likewise, third parties may want to define additional token and claim
   profiles to achieve interoperability and deployment success for
   particular use cases.  It is not practical for this specification to
   standardize all of these additional profiles.  However, to serve
   overall interoperability goals, the following sections provide
   guidelines for third parties that wish to specify profiles of UMA.

5.1.  Specifying Profiles of UMA

   It is STRONGLY RECOMMENDED that profiles of UMA document the
   following information:

   1.  Specify a URI that uniquely identifies the profile.

   2.  Identify the responsible author and provide postal or electronic
       contact information.

   3.  Supply references to previously defined profiles that the profile
       updates or obsoletes.

   4.  Specify relevant authorization server configuration data defined
       and/or utilized by the profile.

   5.  Specify the set of interactions between endpoint entites involved
       in the profile, calling out any restrictions on ordinary UMA-
       conformant operations and any extension properties used in
       message formats.

   6.  Identify the legally responsible parties involved in each
       interaction and any new obligations imposed, in the fashion of
       [UMA-obligations].

   7.  Define any additional or changed error states.

   8.  Supply any additional security and privacy considerations,
       including analysis of threats and description of countermeasures.

5.2.  Specifying RPT Profiles

   It is STRONGLY RECOMMENDED that RPT profiles document the following
   information:

   1.   Specify a URI that uniquely identifies the token profile.

   2.   Identify the responsible author and provide postal or electronic
        contact information.

Hardjono                  Expires June 30, 2013                [Page 34]
Internet-Draft                  UMA Core                   December 2012

   3.   Supply references to previously defined token profiles that the
        token profile updates or obsoletes.

   4.   Specify the keyword to be used in HTTP Authorization headers
        with tokens conforming to this profile.

   5.   Specify relevant authorization server configuration data defined
        and/or utilized by the token profile.  At a minimum, specify the
        keyword for an authorization server to supply in the value of
        the "uma_token_profiles_supported" property to advertise its
        support for this token profile.

   6.   Specify the syntax and semantics of the data that the
        authorization server associates with the token.

   7.   Specify how the token data is associated with, contained within,
        and/or retrieved by means of, the on-the-wire token string.

   8.   Specify processing rules for token data.

   9.   Identify any restrictions on grant types to be used with the
        token profile.

   10.  Define any additional or changed error states.

   11.  Supply any additional security and privacy considerations.

   12.  Specify any obligations specific to the token profile, in the
        fashion of [UMA-obligations].

   See Section 3.3.1 for an example.

5.3.  Specifying Claim Profiles

   It is STRONGLY RECOMMENDED that claim profiles document the following
   information:

   1.  Specify a URI that uniquely identifies the claim profile.

   2.  Identify the responsible author and provide postal or electronic
       contact information.

   3.  Supply references to previously defined claim profiles that the
       claim profile updates or obsoletes.

   4.  Specify relevant authorization server configuration data defined
       and/or utilized by the claim profile.  At a minimum, specify the
       keyword for an authorization server to supply in the value of the

Hardjono                  Expires June 30, 2013                [Page 35]
Internet-Draft                  UMA Core                   December 2012

       "claim_profiles_supported" property to advertise its support for
       this claim profile.

   5.  Specify the syntax and semantics of claim data and requests for
       claim data.

   6.  Specify how an authorization server gathers the claims.

   7.  Define any additional or changed error states.

   8.  Supply any additional security and privacy considerations.

   9.  Specify any obligations specific to the claim profile, in the
       fashion of [UMA-obligations].

   See Section 3.5.1.1 for an example.

6.  Security Considerations

   This specification relies mainly on OAuth security mechanisms for
   protecting the host registration endpoint at the authorization server
   so that only a properly authorized host can access it on behalf of
   the intended user.  For example, the host needs to use a valid
   protection API token (PAT) issued through a user authorization
   process at the endpoint, and the interaction SHOULD take place over
   TLS.  It is expected that the host will protect its client secret (if
   it was issued one) and its PAT, particularly if used in "bearer
   token" fashion.

   In addition, this specification dictates a binding between the PAT
   and the host-specific registration area on the authorization server
   to prevent a host from interacting with a registration area not its
   own.

   This specification defines a number of JSON-based data formats.  As a
   subset of the JavaScript scripting language, JSON data SHOULD be
   consumed through a process that does not dynamically execute it as
   code, to avoid malicious code execution.  One way to achieve this is
   to use a JavaScript interpreter rather than the built-in JavaScript
   eval() function.

   For information about the technical, operational, and legal elements
   of trust establishment between UMA entities and parties, which
   affects security considerations, see [UMA-obligations].

Hardjono                  Expires June 30, 2013                [Page 36]
Internet-Draft                  UMA Core                   December 2012

7.  Privacy Considerations

   The authorization server comes to be in possession of resource set
   information (such as names and icons) that may reveal information
   about the user, which the authorization server's trust relationship
   with the host is assumed to accommodate.  However, the client is a
   less-trusted party (in fact, entirely untrustworthy until it acquires
   permissions for an RPT in UMA protocol phase 2.  This specification
   recommends obscuring resource set identifiers in order to avoid
   leaking personally identifiable information to clients through the
   "scope" mechanism.

   For information about the technical, operational, and legal elements
   of trust establishment between UMA entities and parties, which
   affects privacy considerations, see [UMA-obligations].

8.  Conformance

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

   This specification has dependencies on other specifications, as
   referenced under the normative references listed in this
   specification.  Its dependencies on some specifications, such as
   OpenID Connect ([OCStandard] and [OCMessages]), are optional
   depending on whether the feature in question is used in the
   implementation.

   The authorization server's configuration data provides a machine-
   readable method for it to indicate certain of the conformance options
   it has chosen.  Several of the configuration data properties allow
   for indicating extension features.  Where this specification does not
   already require optional features to be documented, it is RECOMMENDED
   that authorization server developers and deployers document any
   profiled or extended features explicitly and use configuration data
   to indicate their usage.  See Section 1.5 for information about
   providing and extending the configuration data.

9.  IANA Considerations

   This document makes no request of IANA.

10.  Acknowledgments

   The current editor of this specification is Thomas Hardjono of MIT.

Hardjono                  Expires June 30, 2013                [Page 37]
Internet-Draft                  UMA Core                   December 2012

   The following people are co-authors:

   o  Paul C. Bryan, ForgeRock US, Inc. (former editor)

   o  Domenico Catalano, Oracle Corp.

   o  George Fletcher, AOL

   o  Maciej Machulak, Newcastle University

   o  Eve Maler, XMLgrrl.com

   o  Lukasz Moren, Newcastle University

   o  Christian Scholz, COMlounge GmbH (former editor)

   o  Jacek Szpot, Newcastle University

   Additional contributors to this specification include the Kantara UMA
   Work Group participants, a list of whom can be found at
   [UMAnitarians].

11.  Issues

   All issues are now captured at the project's GitHub site
   (<https://github.com/xmlgrrl/UMA-Specifications/issues>).

12.  References

12.1.  Normative References

   [DynClientReg]
              Richer, J., "OAuth Dynamic Client Registration Protocol",
              November 2012, <https://datatracker.ietf.org/doc/
              draft-ietf-oauth-dyn-reg/>.

   [OAuth-SAML]
              Campbell, B., "SAML 2.0 Bearer Assertion Profiles for
              OAuth 2.0", November 2012,
              <http://tools.ietf.org/html/
              draft-ietf-oauth-saml2-bearer>.

   [OAuth-bearer]
              "The OAuth 2.0 Authorization Framework: Bearer Token
              Usage", October 2012,
              <http://tools.ietf.org/html/rfc6750>.

Hardjono                  Expires June 30, 2013                [Page 38]
Internet-Draft                  UMA Core                   December 2012

   [OAuth-introspection]
              Richer, J., "OAuth Token Introspection", November 2012, <h
              ttp://tools.ietf.org/html/
              draft-richer-oauth-introspection>.

   [OAuth-resource-reg]
              Hardjono, T., "OAuth 2.0 Resource Set Registration",
              December 2012.

   [OAuth2]   Hardt, D., "The OAuth 2.0 Authorization Framework",
              October 2012, <http://tools.ietf.org/html/rfc6749>.

   [OCMessages]
              Sakimura, N., "OpenID Connect Messages 1.0",
              September 2011,
              <http://openid.net/specs/
              openid-connect-messages-1_0.html>.

   [OCStandard]
              Sakimura, N., "OpenID Connect Standard 1.0",
              September 2011,
              <http://openid.net/specs/
              openid-connect-standard-1_0.html>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC4627]  Crockford, D., "The application/json Media Type for
              JavaScript Object Notation (JSON)", RFC 4627, July 2006.

   [RFC6415]  Hammer-Lahav, E., "Web Host Metadata", October 2011,
              <http://tools.ietf.org/html/rfc6415>.

   [UMA-obligations]
              Maler, E., "Binding Obligations on UMA Participants",
              April 2012, <http://kantarainitiative.org/confluence/
              display/uma/UMA+Trust+Model>.

12.2.  Informative References

   [OAuth-linktypes]
              Mills, W., "Link Type Registrations for OAuth 2",
              October 2012,
              <http://tools.ietf.org/html/draft-wmills-oauth-lrdd>.

   [OAuth-meta]
              Sakimura, N., "JSON Metadata for OAuth Responses",
              December 2012,

Hardjono                  Expires June 30, 2013                [Page 39]
Internet-Draft                  UMA Core                   December 2012

              <http://tools.ietf.org/html/draft-sakimura-oauth-meta>.

   [UMA-casestudies]
              Maler, E., "UMA Case Studies", December 2012, <http://
              kantarainitiative.org/confluence/display/uma/
              Case+Studies>.

   [UMA-usecases]
              Maler, E., "UMA Scenarios and Use Cases", October 2010, <h
              ttp://kantarainitiative.org/confluence/display/uma/
              UMA+Scenarios+and+Use+Cases>.

   [UMAnitarians]
              Maler, E., "UMA Participant Roster", 2012, <http://
              kantarainitiative.org/confluence/display/uma/
              Participant+Roster>.

Appendix A.  Document History

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

   From I-D rev 03 to rev 04, the following major changes have been
   made:

   o  The requirement to support the client_credentials flow has been
      removed.

   o  The requester access token has been split into two tokens, and all
      of the tokens have been renamed.  The host access token is now the
      PAT.  The requester access token used at the AM's API is now the
      AAT, and consists of vanilla OAuth.  The requester access token
      used at the host is now the RPT.

   o  The token and user authorization endpoints for the different APIs
      at the AM have been joined together, and are now distinguished
      through the
      "http://docs.kantarainitiative.org/uma/scopes/prot.json" scope
      (for the protection API) and the
      "http://docs.kantarainitiative.org/uma/scopes/authz.json" scope
      (for the authorization API).

   o  The token status description format and JSON media type, and the
      RPT/permission delivery response, have been updated to reflect the
      RPT naming.

   o  The configuration data format has changed to reflect the changes
      above.

Hardjono                  Expires June 30, 2013                [Page 40]
Internet-Draft                  UMA Core                   December 2012

   o  The Phase 2/3 flow has changed and been simplified to match the
      requirements of the new AAT and RPT.

   o  Token types are now called token profiles, and this is reflected
      in the configuration parameter names.  Claim types are now called
      claim profiles, and this is also reflected in the configuration
      parameter name.

   o  The requester now asks for permission in a back-channel
      interaction, and the AM now produces a need_claims error that
      instructs the requester to use a claims-gathering flow (renamed
      from "authorization flow").

   o  Named subsections for token and claim profiles have been added so
      that they show up in the TOC.

   From I-D rev 04 to rev 05, the following major changes have been
   made:

   o  The RPT-getting flow and the permission-requesting flow have been
      separated back out, with two distinct endpoints, RPT and
      permission request.

   o  The configuration data format has changed to reflect the changes
      above.

Author's Address

   Thomas Hardjono (editor)
   MIT

   Email: hardjono@mit.edu

Hardjono                  Expires June 30, 2013                [Page 41]