Network Working Group T. Hardjono, Ed.
Internet-Draft MIT
Intended status: Standards Track June 29, 2013
Expires: December 31, 2013
User-Managed Access (UMA) Profile of OAuth 2.0
draft-hardjono-oauth-umacore-07
Abstract
User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how
resource owners can control protected-resource access 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.
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 December 31, 2013.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Hardjono Expires December 31, 2013 [Page 1]
Internet-Draft UMA Core June 2013
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. APIs and Protection . . . . . . . . . . . . . . . . . . . 7
1.3.1. Protection and Authorization APIs at the
Authorization Server . . . . . . . . . . . . . . . . 7
1.3.2. API at the Resource Server . . . . . . . . . . . . . 8
1.4. Authorization Server Configuration Data . . . . . . . . . 9
2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 12
3. Getting Authorization and Accessing a Resource . . . . . . . 13
3.1. Client Attempts to Access Protected Resource . . . . . . 15
3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 15
3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 16
3.2. Resource Server Registers Requested Permission With
Authorization Server . . . . . . . . . . . . . . . . . . 17
3.3. Resource Server Determines RPT's Status . . . . . . . . . 19
3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 19
3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 20
3.4. Client Seeks Authorization for Access . . . . . . . . . . 22
3.4.1. Client Obtains RPT . . . . . . . . . . . . . . . . . 23
3.4.2. Client Asks for Authorization Data . . . . . . . . . 23
3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . 25
3.5.1. Claims-Gathering Flow for Clients Operated by End-
Users . . . . . . . . . . . . . . . . . . . . . . . . 25
3.5.1.1. OpenID Connect Claim Profile . . . . . . . . . . 26
4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 27
4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 28
4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 28
5. Specificying Additional Profiles . . . . . . . . . . . . . . 29
5.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 29
5.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 30
5.3. Specifying Claim Profiles . . . . . . . . . . . . . . . . 31
6. Security Considerations . . . . . . . . . . . . . . . . . . . 31
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33
8. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 33
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33
11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
12.1. Normative References . . . . . . . . . . . . . . . . . . 34
12.2. Informative References . . . . . . . . . . . . . . . . . 35
Appendix A. Document History . . . . . . . . . . . . . . . . . . 36
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36
1. Introduction
Hardjono Expires December 31, 2013 [Page 2]
Internet-Draft UMA Core June 2013
User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA
defines how resource owners can control protected-resource access 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 can be considered to encompass 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 chosen cloud-based
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 sometimes
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.
In order to increase interoperable communication among the
authorization server, resource server, and client, UMA defines
Hardjono Expires December 31, 2013 [Page 3]
Internet-Draft UMA Core June 2013
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
The phases work as follows:
Protect a resource (Described in Section 2.) The resource owner,
who manages online resources at the resource server ("A"),
introduces it to the authorization server so that the latter can
begin controlling the resources' protection. To accomplish this
protection, the authorization server presents a protection API
("C") to the resource server. This API is OAuth-protected and
requires a protection API token (PAT) for access. The API
consists of an OAuth resource set registration endpoint as defined
by [OAuth-resource-reg], an endpoint for registering client-
Hardjono Expires December 31, 2013 [Page 4]
Internet-Draft UMA Core June 2013
requested permissions, and an OAuth token introspection endpoint
as defined by [OAuth-introspection]. Out of band, the resource
owner configures the authorization server with policies associated
with the registered resource sets ("B").
Get authorization (Described in Section 3.) The client approaches
the resource server seeking access to a protected resource. In
order to access it successfully, the client must first use the
authorization server's authorization API ("D") to obtain a
requesting party token (RPT) on behalf of its requesting party,
and the requesting party must supply to the authorization server
any identity claims needed in order for the server to associate
sufficient authorization data with that RPT. The API is OAuth-
protected and requires an authorization API token (AAT) for
access. The API consists of an RPT issuance endpoint and an
authorization request endpoint.
Access a resource (Described along with Phase 2 in Section 3.) The
client successfully presents an RPT that has sufficient
authorization data associated with it to the resource server,
gaining access to the desired resource ("E"). In this sense, this
phase is the "happy path" within phase 2. The nature of the
authorization data varies according to the RPT profile in use.
Implementers are anticipated to develop profiles (see Section 5) that
specify and restrict various UMA protocol, RPT, and identity claim
options, according to deployment and usage conditions.
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. Terminology
UMA introduces the following new terms and enhancements of OAuth term
definitions.
resource owner
An OAuth resource that is the "user" in User-Managed Access.
This is typically an end-user (a natural person) but it can
also be a corporation or other legal person.
requesting party
Hardjono Expires December 31, 2013 [Page 5]
Internet-Draft UMA Core June 2013
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 A bounded extent of access that is possible to perform on a
resource set. In authorization policy terminology, a scope is
one of the potentially many "verbs" that can logically apply to
a resource set ("object"). UMA associates scopes with labeled
resource sets.
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 requested by, or
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
issue.
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.
Hardjono Expires December 31, 2013 [Page 6]
Internet-Draft UMA Core June 2013
1.3. APIs and Protection
UMA involves three APIs, all of which are protected.
The authorization server has the opportunity to manage the validity
periods of access tokens that it issues, their corresponding refresh
tokens where applicable, the individual data components associated
with RPTs where applicable, and even the client credentials that it
issues. Different time-to-live strategies may be suitable for
different resources and scopes of access, and the authorization
server has the opportunity to give the resource owner control over
lifetimes of tokens and authorization data issued on their behalf
through policy. These options are all outside the scope of this
specification.
1.3.1. Protection and Authorization APIs at the Authorization Server
The authorization server presents a protection API to the resource
server and an authorization API to the client. These APIs MUST be
OAuth-protected; thus, the authorization server has an OAuth token
endpoint and user authorization endpoint, and has the option to issue
an OAuth refresh token along with any access tokens issued for these
APIs.
The protection API consists of an OAuth resource set registration
endpoint as defined by [OAuth-resource-reg], an endpoint for
registering client-requested permissions, and an OAuth token
introspection endpoint as defined by [OAuth-introspection]. This
specification profiles the endpoints defined by these other
specifications.
The authorization API consists of an RPT issuance endpoint and an
authorization request endpoint.
All endpoint URIs SHOULD require the use of a transport-layer
security mechanism such as TLS. The authorization server MUST
declare all of its endpoints in its configuration data (see
Section 1.4).
An entity seeking protection API access MUST request the scope "http:
//docs.kantarainitiative.org/uma/scopes/prot.json", and an access
token with at least this scope is called a protection API token
(PAT). An entity seeking authorization API access MUST request the
scope "http://docs.kantarainitiative.org/uma/scopes/authz.json", and
an access token with at least this scope is called an authorization
API token (AAT). The same entity can serve in both roles, so that an
OAuth access token might be considered both a PAT and an AAT if it
has both scopes. If a request to an endpoint fails due to an
Hardjono Expires December 31, 2013 [Page 7]
Internet-Draft UMA Core June 2013
invalid, missing, or expired PAT or AAT, or requires higher
privileges at this endpoint than provided by the PAT or AAT, the
authorization server responds with an OAuth error.
Note: These scope keywords are URIs that resolve to JSON-encoded
scope descriptions, as defined in [OAuth-resource-reg]. These scope
descriptions are non-normative for the purposes of PATs and AATs.
The authorization server is REQUIRED to support the OAuth bearer
token profile for PAT and AAT issuance, and MAY support other OAuth
token profiles for these purposes. It MUST declare all supported
token profiles for PAT and AAT issuance in its configuration data.
The authorization server MAY support the use of any OAuth grant type
for PAT and 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 entities that are operating in environments
where the use of SAML is prevalent. It MUST declare its supported
grant types for PAT and AAT issuance in its configuration data.
A PAT binds a resource owner, a resource server the owner uses for
resource management, and an authorization server the owner uses for
protection of resources at this resource server. It is not specific
to any client or requesting party. The issuance of a PAT represents
the approval of the resource owner for this resource server to trust
this authorization server for protecting its resources belonging to
this resource owner.
An AAT binds a requesting party, a client being used by that party,
and an authorization server that protects resources this client is
seeking access to on this requesting party's behalf. It is not
specific to any resource server or resource owner. The issuance of
an AAT 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. The authorization server is able to
manage future processes of authorization and claims-caching
efficiently for this client/requesting party pair across all resource
servers they try to access. These management processes are outside
the scope of this specification, however.
1.3.2. API at the Resource Server
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 a requesting party token (RPT) with sufficient
authorization data for access. This specification defines one RPT
Hardjono Expires December 31, 2013 [Page 8]
Internet-Draft UMA Core June 2013
profile, call "bearer" (see Section 3.3.2), which is REQUIRED for the
authorization server to support. It MAY support additional RPT
profiles. It MUST declare all supported RPT profiles in its
configuration data.
An RPT represents a binding of 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 is not specific to a single resource owner, though its
internal components are likely to be bound to individual resource
owners, depending on the RPT profile in use.
1.4. Authorization Server Configuration Data
The authorization server MUST provide configuration data in a JSON
[RFC4627] document that resides in an /uma-configuration directory at
at its hostmeta [hostmeta] location. The configuration data
documents conformance options and endpoints supported by the
authorization server. (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.
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.
pat_profiles_supported
REQUIRED. Access token profiles supported by this
authorization server for PAT issuance. The property value is
an array of string values, where each string value is either a
reserved keyword defined in this specification or a URI
identifying an access token profile defined elsewhere. The
reserved keyword "bearer" as a value for this property stands
for 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 for PATs.
aat_profiles_supported
Hardjono Expires December 31, 2013 [Page 9]
Internet-Draft UMA Core June 2013
REQUIRED. Access token profiles supported by this
authorization server for AAT issuance. The property value is
an array of string values, where each string value is either a
reserved keyword defined in this specification or a URI
identifying an access token profile defined elsewhere. The
reserved keyword "bearer" as a value for this property stands
for 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 for AATs.
rpt_profiles_supported
REQUIRED. Access token profiles supported by this
authorization server for RPT issuance. The property value is
an array of string values, where each string value is either a
reserved keyword defined in this specification or a URI
identifying an access token profile defined elsewhere. The
reserved keyword "bearer" as a value for this property stands
for the UMA bearer RPT profile defined in [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 for RPTs.
pat_grant_types_supported
REQUIRED. OAuth grant types supported by this authorization
server in issuing PATs. 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 a URI identifying
a grant type defined elsewhere.
aat_grant_types_supported
REQUIRED. OAuth grant types supported by this authorization
server in issuing 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 a URI identifying
a grant type defined elsewhere.
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, which each string value is either a reserved keyword
defined in this specification or a URI identifying a claim
profile defined elsewhere. The reserved keyword "openid" as a
value for this property stands for the UMA OpenID Connect claim
profile defined in Section 3.5.1.1.
Hardjono Expires December 31, 2013 [Page 10]
Internet-Draft UMA Core June 2013
dynamic_client_endpoint
OPTIONAL. The endpoint to use for performing dynamic client
registration. Usage is defined by [DynClientReg]. The
presence of this property indicates authorization server
support for the dynamic client registration feature and its
absent indicates a lack of support.
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. Usage is defined
by [OAuth2].
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. Usage is defined
by [OAuth2].
introspection_endpoint
REQUIRED. The endpoint URI at which the resource server
introspects an RPT presented to it by a client. Usage is
defined by [OAuth-introspection] and Section 3.3.1. A valid
PAT MUST accompany requests to this protected endpoint.
resource_set_registration_endpoint
REQUIRED. The endpoint URI at which the resource server
registers resource sets to put them under authorization manager
protection. Usage is defined by [OAuth-resource-reg] and
Section 2. A valid PAT MUST accompany requests to this
protected endpoint.
permission_registration_endpoint
REQUIRED. The endpoint URI at which the resource server
registers a client-requested permission with the authorization
server. Usage is defined by Section 3.2. A valid PAT MUST
accompany requests to this protected endpoint.
rpt_endpoint
REQUIRED. The endpoint URI at which the client asks the
authorization server for an RPT. Usage is defined by
Section 3.4.1. A valid AAT MUST accompany requests to this
protected endpoint.
Hardjono Expires December 31, 2013 [Page 11]
Internet-Draft UMA Core June 2013
authorization_request_endpoint
REQUIRED. The endpoint URI at which the client asks to have
authorization data associated with its RPT. Usage is defined
in Section 3.4.2. A valid 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",
"pat_profiles_supported":["bearer"],
"aat_profiles_supported":["bearer"],
"rpt_profiles_supported":["bearer"],
"pat_grant_types_supported":["authorization_code"],
"aat_grant_types_supported":["authorization_code"],
"claim_profiles_supported":["openid"],
"dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
"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",
"introspection_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",
"authorization_request_endpoint":"https://as.example.com/client/perm_uri"
}
Authorization server configuration data MAY contain extension
properties that are not defined in this specification. Extension
names that are unprotected from collisions are outside the scope of
this specification.
2. Protecting a Resource
The resource owner, resource server, and authorization server perform
the following actions to put resources under protection. This list
assumes that the resource server has discovered the authorization
server's configuration data and endpoints as needed.
1. The authorization server issues 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.
Hardjono Expires December 31, 2013 [Page 12]
Internet-Draft UMA Core June 2013
2. The resource server acquires a PAT from the authorization server
in order to use the resource set registration endpoint (and
later, other protection API endpoints). It is OPTIONAL for the
resource owner to introduce the resource server to the
authorization server dynamically (for example, through a
"NASCAR"-style user interface where the resource owner selects a
chosen authorization server); alternatively, they MAY use a
static process that may or may not directly involve the resource
owner at introduction time.
3. In an ongoing fashion, the resource server registers any resource
sets with the authorization server for which it intends to
outsource protection, using the process defined by
[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.
Once a resource set has been placed under authorization server
protection through the registration of a resource set description for
it, and until such a description's deletion by the resource server,
the resource server MUST limit access to corresponding resources,
respecting authorization data associated with client-presented RPTs
by the authorization server as appropriate (see Section 3.1.2).
3. Getting Authorization and Accessing a Resource
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.
The process of getting authorization and accessing a resource 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 with
whatever its application-specific interface defines as a success
response, either immediately or having first performed one or more
Hardjono Expires December 31, 2013 [Page 13]
Internet-Draft UMA Core June 2013
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 requesting party 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.
o The client attempts to access a protected resource.
* 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.
* If the access attempt was accompanied by an RPT, the resource
server checks the RPT's status.
+ If the RPT is invalid, the resource server responds with an
HTTP 401 (Unauthorized) response and instructions on where
to go to obtain a token.
+ If the RPT is valid but has insufficient authorization data,
the resource server registers a suitable requested
permission on the client's behalf at the authorization
server, and then responds to the client with an HTTP 403
(Forbidden) response and instructions on where to go to ask
for authorization.
+ If the RPT is valid, and if the authorization data
associated with the token is sufficient for allowing access,
the resource server responds with an HTTP 2xx (Success)
response and a representation of the resource.
o If the client (possessing no RPT or an invalid RPT) received a 401
response and an authorization server's location, after looking up
its configuration data and endpoints as necessary, it requests an
RPT from the RPT endpoint.
o If the client (posessing a valid RPT) received a 403 response and
a permission ticket, it asks the authorization server for
authorization data that matches the ticket. 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.
Hardjono Expires December 31, 2013 [Page 14]
Internet-Draft UMA Core June 2013
* If the client does not already have an AAT at the appropriate
authorization server to be able to use its authorization API,
it first obtains one.
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 one or more resource sets that correspond to the resource
to which access is being attempted.
The client attempts to access a protected resource (for example, when
an end-user requesting party clicks on a thumbnail representation of
the resource to retrieve a larger version). It 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.
The access attempt either is or is not accompanied by an RPT.
3.1.1. Client Presents No RPT
Example of a request carrying no RPT:
GET /album/photo.jpg HTTP/1.1
Host: photoz.example.com
...
If the client does not present an RPT 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.1).
Hardjono Expires December 31, 2013 [Page 15]
Internet-Draft UMA Core June 2013
For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="example",
host_id="photoz.example.com",
as_uri="https://as.example.com"
...
3.1.2. Client Presents RPT
Example of a request carrying an RPT using the UMA bearer RPT
profile:
GET /album/photo.jpg HTTP/1.1
Authorization: Bearer vF9dft4qmT
Host: photoz.example.com
...
If the client presents an RPT with its request, the resource server
MUST determine the RPT's status (see Section 3.3) before responding.
If the RPT is invalid, the resource server MUST return an HTTP 401
(Unauthorized) status code, along with providing the authorization
server's URI in an "as_uri" property in the header, similarly to the
case where no RPT was presented.
If the RPT is valid but has insufficient authorization data for the
type of access sought, the resource server SHOULD register a
requested permission with the authorization server that would suffice
for that scope of access (see Section 3.2), and then respond with the
HTTP 403 (Forbidden) status code, along with providing the
authorization server's URI in an "as_uri" property in the header, and
the permission ticket it just received from the AM in the body in a
JSON-encoded "ticket" property.
Example of the host's response after having registered a requested
permission and received a ticket:
Hardjono Expires December 31, 2013 [Page 16]
Internet-Draft UMA Core June 2013
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
host_id="photoz.example.com",
as_uri="https://as.example.com"
error="insufficient_scope"
{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
If the RPT's status is associated with authorization data that is
consistent with authorized access of the scope sought by the client,
the resource server MUST give access to the desired resource.
Example of the resource server's response after having determineed
that the RPT is valid and associated with sufficient authorization
data:
HTTP/1.1 200 OK
Content-Type: image/jpeg
...
/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
/bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
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 Requested Permission With Authorization
Server
In response to receiving an access request accompanied by an RPT that
has insufficient authorization data, the resource server registers 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 resource server MUST provide its valid PAT in order to get access
to this endpoint. Note that this PAT implicitly identifies the
resource owner ("subject") to which the permission applies.
Hardjono Expires December 31, 2013 [Page 17]
Internet-Draft UMA Core June 2013
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
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 requested 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 object providing the requested permission, using a
format derived from the scope description format specified in
[OAuth-resource-reg], as follows. The object has 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
scopes to which access is needed for this resource set. Each
scope identifier MUST correspond to a scope that was registered by
this resource server for the referenced resource set.
Example of an HTTP request that registers a requested 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: as.example.com
{
"resource_set_id": "112210f47de98100",
"scopes": [
"http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"
]
}
Hardjono Expires December 31, 2013 [Page 18]
Internet-Draft UMA Core June 2013
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.
For example:
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://as.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 RPT's Status
The resource server determines a received RPT's status, including
both its validity and, if valid, its associated authorization data,
before giving or refusing 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 determine 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.
This specification makes one type of RPT mandatory to implement: the
UMA bearer token profile, as defined in Section 3.3.2. Implementers
MAY define and use other RPT profiles.
3.3.1. Token Introspection
Hardjono Expires December 31, 2013 [Page 19]
Internet-Draft UMA Core June 2013
Within any RPT profile, when a resource server needs to introspect a
token in a non-self-contained way to determine its status, it MUST
use the authorization server's OAuth introspection endpoint, defined
by [OAuth-introspection]. Any UMA token profile MAY require, allow,
or prohibit use of the token introspection endpoint, and MAY profile
its usage. The authorization server MUST OAuth-protect this endpoint
and require a PAT from the resource server for access to it. The
resource server MUST use the POST method in interacting with the
endpoint, not the GET method also defined by [OAuth-introspection].
3.3.2. RPT Profile: Bearer
This section defines the UMA bearer token profile. Following is a
summary:
o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/
uma-token-bearer-1.0
o Profile author and contact information: Thomas Hardjono
(hardjono@mit.edu)
o Updates or obsoletes: None; this profile is new.
o Keyword in HTTP Authorization header: "Bearer".
o Syntax and semantics of token data: As defined below. The token
data format mainly involves time-bounded permissions.
o Token data association: The data associated to the on-the-wire
token by reference and retrieved at run time by the resource
server through profiled use of the OAuth token introspection
endpoint [OAuth-introspection], as defined below.
o Token data processing: As defined in this section and throughout
Section 3 of this specification.
o Grant type restrictions: None.
o Error states: As defined below.
o Security and privacy considerations: As defined in this section
and throughout Section 3 of this specification.
o Binding obligations: Because this RPT profile is mandatory for
authorization servers to implement, binding obligations related to
the use of this token profile are documented in [UMA-obligations].
Hardjono Expires December 31, 2013 [Page 20]
Internet-Draft UMA Core June 2013
On receiving an RPT of the "Bearer" type in an authorization header
from a client making an access attempt, the resource server MUST
introspect the token by using the authorization server's token
introspection endpoint. The PAT used by the resource server to make
the introspection request provides resource-owner context to the
authorization server.
The authorization server responds with a JSON object with the
structure dictated by [OAuth-introspection]. If the valid property
has a "true" value, then the JSON object MUST also contain an
extension property with the name "permissions" that contains an array
of zero or more values, each of which is an object consisting of
these properties:
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.
expires_at REQUIRED. Integer timestamp, measured in the number of
seconds since January 1 1970 UTC, indicating when this permission
will expire.
issued_at OPTIONAL. Integer timestamp, measured in the number of
seconds since January 1 1970 UTC, indicating when this permission
was originally issued.
Example:
Hardjono Expires December 31, 2013 [Page 21]
Internet-Draft UMA Core June 2013
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"valid": true,
"expires_at": "1256953732",
"issued_at": "1256912345",
"permissions": [
{
"resource_set_id": "112210f47de98100",
"scopes": [
"http://photoz.example.com/dev/actions/view",
"http://photoz.example.com/dev/actions/all"
],
"expires_at" : "1256923456"
}
]
}
3.4. Client Seeks Authorization for Access
In order to access a protected resource successfully, a client needs
to present a valid RPT with sufficient authorization data for access.
To get to this stage requires a number of previously successful
steps:
1. The authorization server issues 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.
2. The client acquires an AAT. This enables it to use authorization
API endpoints.
3. The client acquires an RPT from the RPT endpoint. See
Section 3.4.1 for more detail.
4. The client asks for authorization at the authorization request
endpoint, providing the permission ticket it got from the
resource server. The authorization server associates
authorization data with the client's RPT based on the permission
ticket, the resource owner's operative policies, and the results
of any claims-gathering flows with the requesting party. See
Section 3.4.2 for more detail.
Hardjono Expires December 31, 2013 [Page 22]
Internet-Draft UMA Core June 2013
3.4.1. Client Obtains RPT
The client might need an RPT if it has never before requested an RPT
for this combination of requesting party, resource server, and
authorization server, or if it has lost control of a previously
issued RPT and needs a refreshed one. It obtains an RPT by
performing a POST on the RPT endpoint. It MUST provide its own valid
AAT in the header.
Example of a request message containing an AAT:
POST /rpt HTTP/1.1
Host: as.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/json
{
"rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
}
If the AAT provided in the header is the same as one provided for a
previously issued still-valid RPT by this authorization server, the
authorization server invalidates the old RPT and issues a new one.
On first issuance, the RPT is associated with no authorization data
and thus does not convey any authorizations for access.
3.4.2. 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. It performs a POST on the authorization
request endpoint, supplying its own AAT in the header and its RPT and
the permission ticket in a JSON object with properties "rpt" and
ticket", respectively.
Hardjono Expires December 31, 2013 [Page 23]
Internet-Draft UMA Core June 2013
Example of a request message containing an AAT, an RPT, and a
permission ticket:
POST /token_status HTTP/1.1
Host: as.example.com
Authorization: Bearer jwfLG53^sad$#f
...
{
"rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
The authorization server uses the ticket to look up the details of
the previously registered requested permission, maps the requested
permission to operative resource owner policies based on the resource
set identifier and scopes in it, undergoes any claims-gathering flows
required (see Section 3.5), and ultimately responds to the request.
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
the resource owner to set policies that require the owner to provide
a run-time authorization grant in the form of a consent interaction,
mediated by the authorization server. This setting of policies and
gathering of consent is outside the scope of this specification.)
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). Such requesting-party features can potentially be
collected in a claims-gathering flow. If the authorization server
does not add the requested authorization data, it responds using the
appropriate HTTP status code and UMA error code (see Section 4.2):
invalid_ticket The provided ticket was not found at the
authorization server. The authorization server SHOULD respond
with the HTTP 400 (Bad Request) status code.
expired_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.
Hardjono Expires December 31, 2013 [Page 24]
Internet-Draft UMA Core June 2013
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 continue
seeking authorization.
For example:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...
{
"status": "error",
"error": "expired_ticket"
}
3.5. Claims-Gathering Flows
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).
This specification provides a framework for handling end-user-driven
clients and an optional "openid" claim profile, based on OpenID
Connect, for gathering standardized claims from such an end-user. It
also allows for the definition of additional claim profiles. The
authorization server MAY support any number of claim profiles, and
SHOULD document the claim profiles it supports its configuration
data. For the business-level and legal implications of different
claim profiles, 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
Hardjono Expires December 31, 2013 [Page 25]
Internet-Draft UMA Core June 2013
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 fill in a questionnaire, or complete a purchase. It could even
require several of these operations, where the order is treated as
significant for evaluating resource owner policies. 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 in order to continue the process of seeking
authorization, including 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.
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.
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.
Hardjono Expires December 31, 2013 [Page 26]
Internet-Draft UMA Core June 2013
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]
o Be able to utilize at least all of the reserved claims defined in
[OCMessages] in evaluating policy and adding authorization data to
RPTs
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 for
access may depend.
4. Error Messages
Hardjono Expires December 31, 2013 [Page 27]
Internet-Draft UMA Core June 2013
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.
This specification defines additional UMA-specific 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 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.2.
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 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:
error REQUIRED. A single error code. Values for this property are
defined throughout this specification.
error_description OPTIONAL. Human-readable text providing
additional information.
error_uri OPTIONAL. A URI identifying a human-readable web page
with information about the error.
The following is a common error code that applies to several UMA-
specified request messages:
Hardjono Expires December 31, 2013 [Page 28]
Internet-Draft UMA Core June 2013
invalid_request The request is missing a required parameter,
includes an invalid parameter value, includes a parameter more
than once, 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/json
Cache-Control: no-store
...
{
"status": "error",
"error": "invalid_request",
"error_description": "There is already a resource with this identifier.",
"error_uri": "http://as.example.com/errors/resource_exists"
}
5. Specificying Additional Profiles
This specification defines a protocol that has optional features.
For interoperability and to serve particular deployment scenarios,
including sector-specific ones such as healthcare or e-government,
third parties may want to define profiles of UMA that restrict these
options.
Further, this specification creates extensibility points for RPT
profiles and claim profiles, and third parties may likewise want to
define their own. Different RPT profile could be used, for example,
to change the dividing line between authorization server and resource
server responsibilities in controlling access. Different claim
profiles could be used to customize sector-specific or population-
specific (individual vs. employee) claim types that drive the types
of policies resource owners could set.
It is not practical for this specification to standardize all desired
profiles. However, to serve overall interoperability goals, the
following sections provide guidelines for third parties that wish to
specify UMA-related profiles.
5.1. Specifying Profiles of UMA
It is RECOMMENDED that profiles of UMA document the following
information:
1. Specify a URI that uniquely identifies the profile.
Hardjono Expires December 31, 2013 [Page 29]
Internet-Draft UMA Core June 2013
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 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.
5. Identify the legally responsible parties involved in each
interaction and any new obligations imposed, in the fashion of
[UMA-obligations].
6. Define any additional or changed error states.
7. Supply any additional security and privacy considerations,
including analysis of threats and description of countermeasures.
5.2. Specifying RPT Profiles
It is 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.
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 the syntax and semantics of the data that the
authorization server associates with the token.
6. Specify how the token data is associated with, contained within,
and/or retrieved by means of, the on-the-wire token string.
7. Specify processing rules for token data.
8. Identify any restrictions on grant types to be used with the
token profile.
9. Define any additional or changed error states.
Hardjono Expires December 31, 2013 [Page 30]
Internet-Draft UMA Core June 2013
10. Supply any additional security and privacy considerations.
11. Specify any obligations specific to the token profile, in the
fashion of [UMA-obligations].
See Section 3.3.2 for an example.
5.3. Specifying Claim Profiles
It is 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 the syntax and semantics of claim data and requests for
claim data.
5. Specify how an authorization server gathers the claims.
6. Define any additional or changed error states.
7. Supply any additional security and privacy considerations.
8. 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 as well
as transport-level encryption for protecting the protection and
authorization API endpoints. Most PATs and AATs are likely to use
OAuth bearer tokens. See [OAuth-threat] for more information.
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.
Hardjono Expires December 31, 2013 [Page 31]
Internet-Draft UMA Core June 2013
The issue of impersonation is a crucial aspect in UMA, particularly
when entities are wielding bearer tokens that preclude proof-of-
possession (of a secret or a cryptographic key). As such, one way to
mitigate this risk is for the resource owner to require stronger
claims to accompany any access request. For example, consider the
case where Alice sets policies at the authorization server governing
access to her resources by Bob. When Bob first seeks access and must
obtain an RPT (for which the default RPT profile specifies a bearer
token), Alice could set policies demanding that Bob prove his
identity by providing a set of strong claims issued by a trusted
attrribute provider in order to get authorization data associated
with that token.
Another issue concerns the use of the [OAuth2] implicit flow. In
this case, Bob will have exposure to the token, and may maliciously
pass the token to an unauthorized party. To mitigate this weakness
and others, we recommend considering the following steps:
o Require that the Requesting Party (as defined in
[UMA-obligations]) legitimately represent the wielder of the
bearer token. This solution is based on a legal or contractual
approach, and therefore does not reduce the risk from the
technical perspective.
o The authorization server, possibly with input from the resource
owner, can implement tighter time-to-live (TTL) strategies around
the authorization data in RPTs. This is a classic approach with
bearer tokens that helps to limit a malicious party's ability to
intercept and use the bearer token. In the same vein, the
authorization server could require claims to have a reasonable
degree of freshness (which would require a custom claims profile).
o The strongest strategy is to disallow bearer-type RPTs within the
UMA profile being deployed, by providing or requiring an RPT
profile that requires use of a holder-of-key (HOK) approach. In
this way, the wielder of the token must engage in a live session
for proof-of-possession.
For information about the additional technical, operational, and
legal elements of trust establishment between UMA entities and
parties, which affects security considerations, see
[UMA-obligations].
Hardjono Expires December 31, 2013 [Page 32]
Internet-Draft UMA Core June 2013
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 resource owner, which the authorization server's trust
relationship with the resource server is assumed to accommodate.
However, the client is a less-trusted party -- in fact, entirely
untrustworthy until authorization data is associated with its RPT.
This specification depends on [OAuth-resource-reg], which recommends
obscuring resource set identifiers in order to avoid leaking
personally identifiable information to clients through the scope
mechanism.
(More privacy considerations information to come.)
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 or supports. 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.4
for information about providing and extending the configuration data.
9. IANA Considerations
This document makes no request of IANA.
10. Acknowledgments
Hardjono Expires December 31, 2013 [Page 33]
Internet-Draft UMA Core June 2013
The current editor of this specification is Thomas Hardjono of MIT.
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 ([1]).
12. References
12.1. Normative References
[DynClientReg]
Richer, J., "OAuth Dynamic Client Registration Protocol",
March 2013, <https://datatracker.ietf.org/doc/draft-ietf-
oauth-dyn-reg/>.
[OAuth-SAML]
Campbell, B., "SAML 2.0 Bearer Assertion Profiles for
OAuth 2.0", March 2013, <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>.
[OAuth-introspection]
Hardjono Expires December 31, 2013 [Page 34]
Internet-Draft UMA Core June 2013
Richer, J., "OAuth Token Introspection", February 2013,
<http://tools.ietf.org/html/draft-richer-oauth-
introspection>.
[OAuth-resource-reg]
Hardjono, T., "OAuth 2.0 Resource Set Registration",
December 2012, <https://tools.ietf.org/html/draft-
hardjono-oauth-resource-reg>.
[OAuth-threat]
Lodderstedt, T., "OAuth 2.0 Threat Model and Security
Considerations", January 2013,
<http://tools.ietf.org/html/rfc6819>.
[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", March 2013,
<http://openid.net/specs/openid-connect-messages-
1_0.html>.
[OCStandard]
Sakimura, N., "OpenID Connect Standard 1.0", March 2013,
<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.
[UMA-obligations]
Maler, E., "Binding Obligations on UMA Participants",
January 2013, <http://kantarainitiative.org/confluence/
display/uma/UMA+Trust+Model>.
[hostmeta]
Hammer-Lahav, E., "Web Host Metadata", October 2011,
<http://tools.ietf.org/html/rfc6415>.
12.2. Informative References
[OAuth-linktypes]
Mills, W., "Link Type Registrations for OAuth 2", February
2013,
<http://tools.ietf.org/html/draft-wmills-oauth-lrdd>.
Hardjono Expires December 31, 2013 [Page 35]
Internet-Draft UMA Core June 2013
[OAuth-meta]
Sakimura, N., "JSON Metadata for OAuth Responses",
February 2013,
<http://tools.ietf.org/html/draft-sakimura-oauth-meta>.
[UMA-casestudies]
Maler, E., "UMA Case Studies", March 2013, <http://
kantarainitiative.org/confluence/display/uma/
Case+Studies>.
[UMA-usecases]
Maler, E., "UMA Scenarios and Use Cases", October 2010,
<http://kantarainitiative.org/confluence/display/uma/
UMA+Scenarios+and+Use+Cases>.
[UMAnitarians]
Maler, E., "UMA Participant Roster", April 2013, <http://
kantarainitiative.org/confluence/display/uma/
Participant+Roster>.
Appendix A. Document History
NOTE: To be removed by RFC editor before publication as an RFC.
See [2] for a list of code-breaking and other major changes made to
this specification at various revision points.
Author's Address
Thomas Hardjono (editor)
MIT
Email: hardjono@mit.edu
Hardjono Expires December 31, 2013 [Page 36]