identity 1.0 documentation

User-Managed Access (UMA) Profile of OAuth 2.0

«  OpenID Connect Session Management 1.0   ::   Contents   ::   Binding Obligations on User-Managed Access (UMA) Participants  »

User-Managed Access (UMA) Profile of OAuth 2.0

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.

(draft 06)

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.

Note

access policies を定義しておくと(PDP)、認可が勝手にでる(PEP)

ユースケース

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.

PDP/PEP

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.

OAuth2

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.

Protocol

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:

リソース保護(PAT API)
  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”).)

認可発行(RPT発行)
  1. _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).

リソースアクセス
  1. _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.

(draft 06 : http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-1 )

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.

( draft 06 http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-1.1 )

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

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-1.2 )

orphan:

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.

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-1.3 )

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

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-1.3.1 )

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

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-1.3.2 )

1.4. Scopes, 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 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 parties) 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.

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-1.4 )

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 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 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 properties that are not defined in this specification. Extension names that are unprotected from collisions are outside the scope of the current specification.

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-1.5 )

orphan:

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):

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

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

  • The resource server registers any resource sets with the authorization server that are intended to be protected.

    See Section 2.2 for additional details.

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-2 )

orphan:

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.

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

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-2.1 )

orphan:

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.

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-2.2 )

2.3. Host Obtains Protection API Token

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

The host MUST use OAuth 2.0 [OAuth2] to obtain the protection API token. Here the host acts in the role of an OAuth client requesting the “http://docs.kantarainitiative.org/uma/scopes/prot.json” scope; the authorizing user acts in the role of an OAuth end-user resource owner; and the AM acts in the role of an OAuth authorization server. Once the host has obtained its PAT, it presents it to the AM at various protection API endpoints; in presenting these endpoints the AM acts in the role of a resource server.

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

The host has completed this step successfully when it possesses a PAT it can use to get access to the AM’s protection API on this user’s behalf.

(draft 05)

2.4. Host Registers Sets of Resources to Be Protected

Once the host has received a PAT, for any of the user’s sets of resources that are to be protected by this AM, it MUST register these resource sets at the AM’s registration endpoint.

Note that the host is free to offer the option to protect any subset of the user’s resources using different AMs or other means entirely, or to protect some resources and not others. Additionally, the choice of protection regimes can be made explicitly by the user or implicitly by the host. Any such partitioning by the host or user is outside the scope of this specification.

See Section 10 for an extended example of registering resource sets.

(draft 05)

2.4.1. Scope Descriptions

A scope is a bounded extent of access that is possible to perform on a resource set. A scope description is a JSON document with the following properties and a Content-Type of application/uma-scope+json:

name

REQUIRED.

A human-readable string describing some scope (extent) of access.

This name is intended for ultimate use in the AM’s user interface to assist the user in setting policies for protected resource sets that have this available scope.

Note

  • 「三井住友銀行:普通預金口座」とか、「三井住友銀号:お客様情報」とか
icon_uri

OPTIONAL.

A URI for a graphic icon representing the scope.

The referenced icon is intended for ultimate use in the AM’s user interface to assist the user in setting policies for protected resource sets that have this available scope.

For example, this description characterizes a scope that involves reading or viewing resources (vs. creating them or editing them in some fashion):

{
  "name": "View",
  "icon_uri": "http://www.example.com/icons/reading-glasses"
}

Scope descriptions MAY contain extension properties that are not defined in this specification. Extension names that are unprotected from collisions are outside the scope of the current specification.

A host MUST list a resource set‘s available scopes using URI references (as defined in Section 2.4.2).

The scopes available for use at any one host MUST have unique URI references so that the host’s scope descriptions are uniquely distinguishable. A scope URI reference MAY include a fragment identifier. Scope descriptions MAY reside anywhere. The host is not required to self-host scope descriptions and may wish to point to standardized scope descriptions residing elsewhere. Scope description documents MUST be accessible to AMs through GET calls made to these URI references.

See Section 1.4 for further discussion of scope-related concepts, and Section 10 for a long-form example of scopes used in resource set registration.

(draft 05)

2.4.2. Resource Set Descriptions

The host defines a resource set that needs protection by registering a resource set description at the AM. The host registers the description and manages its lifecycle at the AM’s host resource set registration endpoint by using the resource set registration API, as defined in Section 2.4.3.

A resource set description is a JSON document with the following properties and a Content-Type of application/uma-resource-set+json:

name

REQUIRED.

A human-readable string describing a set of one or more resources. The AM SHOULD use the name in its user interface to assist the user in setting policies for protecting this resource set.

Note

  • 「三井住友銀号:総合口座」とか
icon_uri

OPTIONAL.

A URI for a graphic icon representing the resource set. If provided, the AM SHOULD use the referenced icon in its user interface to assist the user in setting policies for protecting this resource set.

scopes

REQUIRED.

An array providing the URI references of scope descriptions that are available for this resource set.

The AM SHOULD use the scope names and any icons defined as part of the referenced scopes in its user interface to assist the user in setting policies for protecting this resource set.

Note

  • 「三井住友銀行:普通預金口座」、「三井住友銀行:お客様情報」、、、、、

For example, this description characterizes a resource set (a photo album) that can potentially be only viewed, or alternatively to which full access can be granted; the URIs point to scope descriptions as defined in Section 2.4.1:

{
  "name": "Photo Album",
  "icon_uri": "http://www.example.com/icons/flower.png",
  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

Resource set descriptions MAY contain extension properties that are not defined in this specification. Extension names that are unprotected from collisions are outside the scope of the current specification.

When a host creates or updates a resource set description (see Section 2.4.3), the AM MUST attempt to retrieve the referenced scope descriptions. It MAY cache such descriptions as long as indicated in the HTTP cache-control header for the scope description resource unless the resource set description is subsequently updated within the validity period. At the beginning of an authorizing user’s login session at the AM, the AM MUST attempt to re-retrieve scope descriptions applying to that user whose cached versions have expired.

(draft 05)

Note

  • For Connect Aggreated Claims, following additional claims may be provided for the AM to fetch resources in charge of the resource owner.

    • refresh_token(required)
    • access_token(potional)
    • token endpoint
    • resource endpoint
  • And, if aother API call is lengthy, following claims should be returned for the client authentication to the token endpoint.

    • client identfiier
    • client secret
  • Tokens’ scope MUST be any in scopes of this resource set description.

2.4.3. Resource Set Registration API

The host uses the RESTful API at the AM’s resource set registration endpoint to create, read, update, and delete resource set descriptions, along with listing groups of such descriptions. The host MUST use its valid PAT obtained previously to gain access to this endpoint. The resource set registration API is a subset of the protection API.

The host is free to use its own methods of identifying and describing resource sets. The AM MUST treat them as opaque for the purpose of authorizing access, other than associating them with the authorizing user (as represented by the PAT used to access the API). On successfully registering a resource set, the host MUST use UMA mechanisms to limit access to any resources corresponding to this resource set, relying on the AM to supply currently valid permissions for authorized access. The host MUST outsource protection to the AM according to the currently registered state of a resource set. This requirement holds true so long as the host has one or more registsred resource sets.

(Note carefully the similar but distinct senses in which the word “resource” is used in this section. UMA resource set descriptions are themselves managed as web resources at the AM through this API.)

The AM MUST present an API for registering resource set descriptions at a set of URIs with the structure “{rsreguri}/resource_set/{rsid}”, where the PAT provides sufficient context to distinguish between identical resource set identifiers assigned by different hosts.

The components of these URIs are defined as follows:

{rsreguri}
The AM’s resource set registration endpoint as advertised in its configuration data (see Section 1.5).
{rsid}
An identifier for a resource set description.

Without a specific resource set identifier path component, the URI applies to the set of resource set descriptions already registered.

Following is a summary of the five registration operations the AM is REQUIRED to support. Each is defined in its own section below. All other methods are unsupported. This API uses ETag and If-Match to ensure the desired resource at the AM is targeted.

If the request to the resource set registration endpoint is incorrect, then the AM responds with an error message (see Section 4.2) by including one of the following error codes with the response:

unsupported_method_type
The host request used an unsupported HTTP method. The AM MUST respond with the HTTP 405 (Method Not Allowed) status code and MUST fail to act on the request.
not_found
The resource set requested from the AM cannot be found. The AM MUST respond with HTTP 404 (Not Found) status code.
precondition_failed
The resource set that was requested to be deleted or updated at the AM did not match the If-Match value present in the request. The AM MUST respond with HTTP 412 (Precondition Failed) status code and MUST fail to act on the request.

(draft 05)

2.4.3.1. Create Resource Set Description

Adds a new resource set description using the PUT method, thereby putting it under the AM’s protection. If the request is successful, the AM MUST respond with a status message that includes an ETag header and _id and _rev properties for managing resource set description versioning.

Form of a “create resource set description” HTTP request:

PUT /resource_set/{rsid} HTTP/1.1
Content-Type: application/uma-resource-set+json
...

(body contains JSON resource set description to be created)

Form of a successful HTTP response:

HTTP/1.1 201 Created
Content-Type: application/uma-status+json
ETag: (matches "_rev" property in returned object)
...

{
  "status": "created",
  "_id": (id of created resource set),
  "_rev": (ETag of created resource set)
}

On successful registration, the AM MAY return a redirect policy URI to the host in a property with the name “policy_uri”. This URI allows the host to redirect the user to a specific user interface within the AM where the user can immediately set or modify access policies for the resource set that was just registered.

Form of a successful HTTP response:

HTTP/1.1 201 Created
Content-Type: application/uma-status+json
ETag: (matches "_rev" property in returned object)
...

{
  "status": "created",
  "_id": (id of created resource set),
  "_rev": (ETag of created resource set)
  "policy_uri":"http://am.example.com/host/222/resource/333/policy"
}

(draft 05)

2.4.3.2. Read Resource Set Description

Reads a previously registered resource set description using the GET method. If the request is successful, the AM MUST respond with a status message that includes an ETag header and _id and _rev properties for managing resource set description versioning.

Form of a “read resource set description” HTTP request:

GET /resource_set/{rsid} HTTP/1.1
...

Form of a successful HTTP response:

HTTP/1.1 200 OK
Content-Type: application/uma-resource-set+json
...

(body contains JSON resource set description, including _id and _rev)

If the referenced resource does not exist, the AM MUST produce an error response with an error property value of “not_found”, as defined in Section 2.4.3.

On successful read, the AM MAY return a redirect policy URI to the host in a property with the name “policy_uri”. This URI allows the host to redirect the user to a specific user interface within the AM where the user can immediately set or modify access policies for the resource set that was read.

Note

  • policy_uri seems to be a part of scope description JSON.....

(draft 05)

2.4.3.3. Update Resource Set Description

Updates a previously registered resource set description using the PUT method, thereby changing the resource set’s protection characteristics. If the request is successful, the AM MUST respond with a status message that includes an ETag header and _id and _rev properties for managing resource set description versioning.

Form of an “update resource set description” HTTP request:

PUT /resource_set/{rsid} HTTP/1.1
Content-Type: application/resource-set+json
If-Match: (entity tag of resource)
...

(body contains JSON resource set description to be updated)

Form of a successful HTTP response:

HTTP/1.1 204 No Content
ETag: "2"
...

If the entity tag does not match, the AM MUST produce an error response with an error property value of “precondition_failed”, as defined in Section 2.4.3.

On successful update, the AM MAY return a redirect policy URI to the host in a property with the name “policy_uri”. This URI allows the host to redirect the user to a specific user interface within the AM where the user can immediately set or modify access policies for the resource set that was just updated.

Note

  • It is unclear where policy_uri should be returned. in header or paylaod ?

(draft 05)

2.4.3.4. Delete Resource Set Description

Deletes a previously registered resource set description using the DELETE method, thereby removing it from the AM’s protection regime.

Form of a “delete resource set description” HTTP request:

DELETE /resource_set/{rsid}
If-Match: (entity tag of resource)
...

Form of a successful HTTP response:

HTTP/1.1 204 No content
...

As defined in Section 2.4.3, if the referenced resource does not exist the AM MUST produce an error response with an error property value of “not_found”, and if the entity tag does not match the AM MUST produce an error response with an error property value of “precondition_failed”.

(draft 05)

2.4.3.5. List Resource Set Descriptions

Lists all previously registered resource set identifiers for this user using the GET method. The AM MUST return the list in the form of a JSON array of {rsid} values.

The host uses this method as a first step in checking whether its understanding of protected resources is in full synchronization with the AM’s understanding.

Form of a “list resource set descriptions” HTTP request:

GET /resource_set HTTP/1.1
...

HTTP response:

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

(body contains JSON array of {rsid} values)

(draft 05)

orphan:

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.

Note

  • ディスカバリをどうやるか?
  • 「リソース名」でリソースエンドポイントをディスカバる?

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

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.

    Note

    • リソースなし 401
  • 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.

      Note

      • 不正なRPT 401
    • 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.

      Note

      • パーミッションがない 403
    • 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.

      Note

      • リソース返答 200
  • 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.

    Note

    • 401 をもらったらクライアントは RPT をAuthz Serverに要求
  • 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.

    Note

    • 403 をもらったらクライアントはAuthz ServerにRPTへのパーミッションを要求
    • 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.

      Note

      • AATがなかったら、クライアントはAATの取得から始める

The interactions are described in detail in the following sections.

(draft 07 , http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3 )

orphan:

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 cover, 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.

Note

  • リソースはなんとかしてみつけろ(ディスカバリ?)

  • 取得手順は互いに取り決めろ

  • リソースに対してのRPTが既にあったら指定してもいいし、無しでも良い

    • 無いと 401

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.1 )

orphan:

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

For example:

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

Note

  • scheme : “UMA”
  • realm : レルム
  • host_id : Resource Server 識別子
  • as_uri : Authz Server

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.1.1 )

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:

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.

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.1.2 )

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

( draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.1.3 )

3.1.3.1. Requester’s Token Has Insufficient Permission

If the token status is not associated with any currently valid permission that applies to the scope of access attempted by the requester, the Host SHOULD register a permission with the AM (see Section 3.4) that would suffice for that scope of access, and then respond to the requester with the HTTP 403 (Forbidden) status code, along with providing the AM’s URI in the header of the message and the permission ticket it just received from the AM in the body of the JSON form.

For example:

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

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

Note

  • Host register a permmision. (uma_core.3.4 )

  • Host get a ticket from AM for a permission registration. ( ticket is a JSON in response body from AM )

  • Host return the ticket to the request in HTTP 403 for the resource request. ( described in this section)

  • Requester ask AM to get access token with the ticket and other information(3.5. Claims-Gathering Flows )

Note

  • “A Requester has a valid access token” means that “Authrizing User allowed the reuqester to access a resource in the Host”
  • So “Host” may register permission to the scope on “AM” for the “Requester”. This is proved by the “Ticket”
  • If the “Requester” provides a valid “Ticket” for the “Token”. the “AM” issues a new token (Updated Token)

(draft 03)

3.1.3.2. Requester’s Token Has Sufficient Permission

If the token status is associated with at least one currently valid permission that applies to the scope of access attempted by the requester, the host MUST give access to the desired resource.

For example:

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

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

This response constitutes the conclusion of Phase 3 of UMA.

The host MUST NOT give access where the token’s status is not associated with at least one currently active permission hat suffices for that scope of access.

orphan:

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.

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"
  ]
}

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.

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.2 )

orphan:

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.

( draft7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.3 )

orphan:

3.3.1. Token Introspection

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

( draft 7, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.3.1 )

orphan:

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.

( draft 07, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07 )

orphan:

3.4.1. Client Obtains AAT

Note

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

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.

( draft 06 : http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.4.1 )

orphan:

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.

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.
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"
}

( draft 07, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-07#section-3.4.2 )

3.4.3. Client Asks for Authorization Data

Note

  • パーミションを要求
  • 成功したら 200 OK が返る、って書いた方がいいんじゃない?

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.

Note

  • Permission Request Endpoint でパーミッション要求する

    • AAT
    • RPT
    • permission ticket ( uma_core.3.2 )

The client performs a POST on the permission request endpoint, supplying the items below.

The client MUST provide its own AAT in the header.

  • The permission ticket it received from the resource server
  • Its RPT for this resource server
  • Its own AAT in the header

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.

Note

  • OK(200)かNG(401,400)を返す

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.
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"
}

(draft 06 : http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.4.3 )

3.4.4. Requester Obtains Requester Permission Token

Note

  • RPT

In this step, if the requester needs an RPT that applies to this requesting party for this host and this AM, the requester obtains an RPT from the AM.

On first issuance the RPT is associated with no permissions and thus does not convey any authorizations for access.

Once the requester obtains an RPT from the AM, it can ask the AM for authorization to have permissions associated with the RPT (see Section 3.4.5).

The requester performs a POST on the RPT endpoint. In doing so the requester MUST provide its own AAT in the header in order to gain access to the RPT endpoint.

Example of a request message containing an AAT:

POST /rpt HTTP/1.1
Host: am.example.com
Authorization: Bearer jwfLG53^sad$#f
Content-Type: application/json
...

The AM 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 AM, the AM MUST produce an HTTP error.

The requester might need an RPT if it has never before requested an RPT for this combination of requesting party, host, and AM, or if it has lost control of a previous 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 AM, the AM invalidates the old RPT and its permissions and issues a new RPT.

If the request fails due to missing or invalid parameters, or is otherwise malformed, the AM SHOULD inform the requester 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 AM 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"

(draft 05)

3.4.5. Requester Asks for Authorization to Add Permission

Once in possession of an AAT for this AM, an RPT that applies to this requesting party for this host and this AM, and a permission ticket, the requester asks the AM to give it a permission for the sought-for access. The requester performs a POST on the permission request endpoint at the AM, supplying the items below. In doing so the requester MUST provide its own AAT in order to gain access to the permission request endpoint.

  • The permission ticket it received from the host
  • Its RPT for this host
  • Its own AAT in the header

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
Content-Type: application/json
...

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

In this interaction, the requester uses the AM’s permission request endpoint. The AM uses the ticket to look up the previously registered permission, maps the requested permission to operative user policies, undergoes any authorization flows required (see Section 3.5), and ultimately responds to the request positively or negatively.

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 AM 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 AM does not add the requested permission, it responds using the appropriate HTTP status code (typically 400 or 403), and includes one of the following error codes in the response (see Section 4.2):

invalid_requester_ticket
The provided ticket was not found at the AM. The AM SHOULD respond with the HTTP 400 (Bad Request) status code.
expired_requester_ticket
The provided ticket has expired. The AM SHOULD respond with the HTTP 400 (Bad Request) status code.
not_authorized_permission
The requester is definitively not authorized for this permission according to user policy. The AM SHOULD respond with the HTTP 403 (Forbidden) status code.
need_claims
The AM is unable to determine whether the requester is authorized for this permission without gathering claims from the requesting party. The AM SHOULD respond with the HTTP 403 (Forbidden) status code. The requester is therefore not authorized, but has the opportunity to engage the requesting party in a claims-gathering flow with the AM (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"
}

(draft 05)

3.5. Claims-Gathering Flows

Note

  • クレームを要求したり、渡したりする必要がある場合が考えられる
  • Requesting Party 固有のクレームと、それに依存しないクレームがある
  • Requesting Partyは個人、とそれ以外(ブラウザ、App、Bot...)

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

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.5 )

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

Note

  • 自然人
  • 組織人

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

  • 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.
  • 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.
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).

(defat 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.5.1 )

3.5.1.1. OpenID Connect Claim Profile

This section defines the OpenID Connect claim profile for UMA.

Following is a summary:

  • Identifying URI:

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

  • Profile author and contact information:

    Thomas Hardjono (hardjono@mit.edu)

  • Updates or obsoletes:

    None; this profile is new.

  • Authorization server configuration data:

    To indicate support, supply the keyword “openid” in the “claim_profiles_supported” property value.

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

  • Claims gathering method:

    As defined below.

  • Error states:

    None additional.

  • Security and privacy considerations:

    None additional.

  • 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:

  • Serve as a conforming OpenID Relying Party and Claims Client according to [OCStandard]
  • Be able to utilize at least all of the reserved claims defined in [OCMessages] in assessing policy and granting permissions
  • 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.

( draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-3.5.1.1 )

3.6. Authorization Flows

The AM MUST base its decisions to add permissions to requester access tokens 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 requester application (for example, browser, native app, or autonomously running web service). UMA currently provides a framework for handling human-driven requester apps and an optional solution for gathering standardized claims from that end-user, and allows for extensions to support other solutions for this use case and other use cases. The AM SHOULD document its claims-handling ability in its XRD configuration data through the claim_types_supported property (see Section 1.5). For the business-level and legal implications of different technical authorization flows, see [UMA-trustmodel].

(draft 03)

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

A requester app, whether browser-based or native, is operated by a natural person (human end-user) in one of two typical situations:

  • The requesting party is a natural person (for example, a friend of the authorizing user); the requesting party may even be the authorizing user herself.
  • The requesting party is a legal person such as a corporation, and the human being operating the requester app is acting as an agent of that legal person (for example, a customer support specialist representing a credit card company).

The AM has a variety of options at this point for satisfying the authorizing user’s policy; this specification does not dictate a single answer. For example, the AM could require the end-user operating the requester app to register for and/or log in to a local AM account, or to fill in a questionnaire, or to complete a purchase. It could even require several of these operations, where the order is significant.

An end-user-driven requester app MUST redirect the end-user to the AM to complete the process of authorization. If the AM succeeds in adding the requested permission, it MUST redirect the end-user requesting party back to the requester app when reporting success.

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

An AM MAY use OpenID Connect as one means of gathering claims from an end-user requesting party, leveraging OpenID Connect mechanisms to transmit claims from distributed sources. If it supports this option, the AM MUST supply the “openid” value for one of its claim_types_supported values in its AM configuration data (see Section 1.5 for how to formulate this data).

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

  • 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 assessing policy and granting permissions

The AM 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 host is responsible for either granting the access the requester attempted, or returning an error response to the requester with a reason for the failure. [OAuth2] defines several error responses for a resource server to return. UMA makes use of these error responses, but requires the host to “outsource” the determination of some error conditions to the AM. UMA defines its own additional error responses that the AM may give to the host and requester as they interact with it, and that the host may give to the requester.

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.

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-4.1 )

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:

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"
}

(draft 06, http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-4.2 )

5. Specification of Additional Profiles

This specification defines a selected set of profiles, but others will possibly be developed in the future. It is not possible for this specification to standardize all of these additional profiles. The following sections define rules for third parties that specify UMA profiles.

(Get text from http://docs.oasis-open.org/security/saml/v2.0/ saml-profiles-2.0-os.pdf .)

(Put references to this section in the appropriate places above, and add a discussion of profiles somewhere in the intro.)

(draft 05)

5.1. Specifying UMA Profiles

This section provides a checklist of issues that MUST be addressed by each profile.

  1. Specify a URI that uniquely identifies the profile, postal or electronic contact information for the author, and provide reference to previously defined profiles that the new profile updates or obsoletes.
  2. Specify the set of interactions between parties involved in the profile. Any restrictions on applications used by each party and the protocols involved in each interaction must be explicitly called out.
  3. Identify the parties involved in each interaction, including how many parties are involved and whether intermediaries may be involved.
  4. Specify the method of authentication of parties involved in each interaction, including whether authentication is required and acceptable authentication types.
  5. Identify the level of support for message integrity, including the mechanisms used to ensure message integrity.
  6. Identify the level of support for confidentiality, including whether a third party may view the contents of UMA messages, whether the profile requires confidentiality, and the mechanisms recommended for achieving confidentiality.
  7. Identify the error states, including the error states at each participant, especially those that receive and process UMA messages.
  8. Identify security considerations, including analysis of threats and description of countermeasures.
  9. Identify relevant UMA metadata defined and/or utilized by the profile.

(draft 05)

5.2. Specifying UMA Token Profiles

This section provides a checklist of items that MUST in particular be addressed by attribute profiles.

  1. Specify a URI that uniquely identifies the profile, postal or electronic contact information for the author, and provide reference to previously defined profiles that the new profile updates or obsoletes.
  2. Identify the syntax and restrictions on the acceptable values for the token profile.
  3. Identify namespace restrictions that are meaningful in the profile deployment scenario.
  4. Identify rules in the processing of the fields within the token profile.
  5. Identify the scopes that are defined in the token profile (e.g. grant types in JWT Bearer Token Profile).
  6. Identify the error states, including the error states at each participant, especially those that receive and process claims or assertions expressed within the tokens.

(draft 05)

6. Security Considerations

This specification relies mainly on OAuth security mechanisms for protecting the host registration endpoint at the AM 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 AM 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-trustmodel].

(draft 05)

7. Privacy Considerations

The AM comes to be in possession of resource set information (such as names and icons) that may reveal information about the user, which the AM’s trust relationship with the host is assumed to accommodate. However, the requester 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 requesters 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-trustmodel].

(draft 05)

8. Conformance

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

This specification has dependencies on other specifications, as follows:

  • OAuth 2.0: AMs, hosts, and requesters MUST support [OAuth2] features named in this specification for conformance. For example, AMs MUST support the authorization_code and client_credentials grant types.
  • hostmeta: AMs, hosts, and requesters MUST support the [RFC6415] features named in this specification.
  • OpenID Connect: AMs MAY support [DynClientReg], and MAY choose to conform to the “openid” claim format option, corresponding to the OpenID Connect RP role defined in [OCStandard] and support for OpenID Connect reserved claims defined in [OCMessages].

The AM’s configuration data provides a machine-readable method for an AM to indicate certain of the conformance options it has chosen. Several of the data properties allow for extensibility. Where this specification does not already require optional features to be documented, it is RECOMMENDED that AM 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 AM configuration data.

(draft 05)

9. IANA Considerations

Several UMA-specific JSON-based media types are being proposed, as follows: (TBS)

(draft 05)

10. Example of Registering Resource Sets

The following example illustrates the intent and usage of resource set descriptions and scope descriptions as part of resource set registration.

This example contains some steps that are exclusively in the realm of user experience rather than web protocol, to achieve realistic illustration. These steps are labeled “User experience only”. Some other steps are exclusively internal to the operation of the entity being discussed. These are labeled “Internal only”.

An authorizing user, Alice Adams, has just uploaded a photo of her new puppy to a host, Photoz.example.com, and wants to ensure that this specific photo is not publicly accessible.

Alice has already introduced this host to her AM, CopMonkey.example.com, and thus Photoz has already obtained a PAT from CopMonkey. However, Alice has not previously instructed Photoz to use CopMonkey to protect any other photos of hers.

Alice has previously visited CopMonkey to map a default “do not share with anyone” policy to any resource sets registered by Photoz, until such time as she maps some other more permissive policies to those resources. (User experience only. This may have been done at the time Alice introduced the host to the AM, and/or it could have been a global or host-specific preference setting. A different constraint or no constraint at all might be associated with newly protected resources.) Other kinds of policies she may eventually map to particular photos or albums might be “Share only with husband@email.example.net” or “Share only with people in my ‘family’ group”.

Photoz itself has a publicly documented application-specific API that offers two dozen different methods that apply to single photos, such as “addTags” and “getSizes”, but rolls them up into two photo-related scopes of access: “view” (consisting of various read-only operations) and “all” (consisting of various reading, editing, and printing operations). It defines two scope descriptions that represent these scopes, which it is able to reuse for all of its users (not just Alice), and ensures that these scope description documents are available through HTTP GET requests that may be made by AMs.

The “name” property values are intended to be seen by Alice when she maps authorization constraints to specific resource sets and actions while visiting CopMonkey, such that Alice would see the strings “View Photo and Related Info” and “All Actions”, likely accompanied by the referenced icons, in the CopMonkey interface. (Other users of Photoz might similarly see the same labels at CopMonkey or whatever other AM they use. Photoz could distinguish natural-language labels per user if it wishes, by pointing to scopes with differently translated names.)

Example of the viewing-related scope description document available at http://photoz.example.com/dev/scopes/view with a Content-Type of application/uma-scope+json:

{
  "name": "View Photo and Related Info",
  "icon_uri": "http://www.example.com/icons/reading-glasses.png"
}

Example of the broader scope description document available at http://photoz.example.com/dev/scopes/all, likewise with a Content- Type of application/uma-scope+json:

{
  "name": "All Actions",
  "icon_uri": "http://www.example.com/icons/galaxy.png"
}

While visiting Photoz, Alice selects a link or button that instructs the site to “Protect” or “Share” this single photo (user experience only; Photoz could have made this a default or preference setting).

As a result, Photoz defines for itself a resource set that represents this photo (internal only; Photoz is the only application that knows how to map a particular photo to a particular resource set). Photoz also prepares the following resource set description, which is specific to Alice and her photo. The “name” property value is intended to be seen by Alice in mapping authorization policies to specific resource sets and actions when she visits CopMonkey. Alice would see the string “Steve the puppy!”, likely accompanied by the referenced icon, in the CopMonkey interface. The possible scopes of access on this resource set are indicated with URI references to the scope descriptions, as shown just above.

{
  "name": "Steve the puppy!",
  "icon_uri": "http://www.example.com/icons/flower",
  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

Photoz uses the “create resource set description” method of CopMonkey’s standard UMA resource set registration API, presenting its Alice-specific PAT there, to register and assign an identifier to the resource set description.

PUT /resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/uma-resource-set+json
...

{
  "name": "Steve the puppy!",
  "icon_uri": "http://www.example.com/icons/flower.png",
  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

If the registration attempt succeeds, CopMonkey responds in the following fashion.

HTTP/1.1 201 Created
Content-Type: application/uma-status+json
ETag: "1"
...

{
  "status": "created",
  "_id":  "112210f47de98100",
  "_rev": "1"
}

At the time Alice indicates she would like this photo protected, Photoz can choose to redirect Alice to CopMonkey for further policy setting, access auditing, and other AM-related tasks (user experience only).

Once it has successfully registered this description, Photoz is responsible for outsourcing to CopMonkey all questions of authorization for access attempts made to this photo.

Over time, as Alice uploads other photos and creates and organizes photo albums, and as Photoz makes new action functionality available, Photoz can use additional methods of the resource set registration API to ensure that CopMonkey’s understanding of Alice’s protected resources matches its own.

For example, if Photoz suspects that somehow its understanding of the resource set has gotten out of sync with CopMonkey’s, it can ask to read the resource set description as follows.

GET /resource_set/112210f47de98100 HTTP/1.1
Host: am.example.com
...

CopMonkey responds with the full content of the resource set description, including its _id and its current _rev, as follows:

Example of an HTTP response to a “read resource set description” request, containing a resource set description from the AM:

HTTP/1.1 200 OK
Content-Type: application/uma-resource-set+json
ETag: "1"
...

{
  "_id":  "112210f47de98100",
  "_rev": "1",
  "name": "Photo album",
  "icon_uri": "http://www.example.com/icons/flower.png",
  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

If for some reason Photoz and CopMonkey have gotten dramatically out of sync, Photoz can ask for the list of resource set identifiers CopMonkey currently knows about:

GET /resource_set HTTP/1.1
Host: am.example.com
...

CopMonkey’s response might look as follows:

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

[ "112210f47de98100", "34234df47eL95300" ]

If Alice later changes the photo’s title (user experience only) on Photoz from “Steve the puppy!” to “Steve on October 14, 2011”, Photoz would use the “update resource set description” method to ensure that Alice’s experience of policy-setting at CopMonkey remains consistent with what she sees at Photoz. Following is an example of this request.

PUT /resource_set/112210f47de98100 HTTP/1.1
Content-Type: application/uma-resource-set+json
Host: am.example.com
If-Match: "1"
...

{
  "name": "Steve on October 14, 2011",
  "icon_uri": "http://www.example.com/icons/flower.png",
  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ]
}

CopMonkey would respond as follows.

HTTP/1.1 201 Created
Content-Type: application/uma-status+json
ETag: "2"
...

{
  "status": "updated",
  "_id":  "112210f47de98100",
  "_rev": "2"
}

There are other reasons Photoz might want to update resource set descriptions, having nothing to do with Alice’s actions or wishes. For example, it might extend its API to include new features, and want to add new scopes to all of Alice’s and other users’ resource set descriptions.

if Alice later decides to entirely remove sharing protection (user experience only) on this photo while visiting Photoz, ensuring that the public can get access without any UMA-based protection, Photoz is responsible for deleting the relevant resource set registration, as follows:

DELETE /resource_set/112210f47de98100 HTTP/1.1
Host: am.example.com
If-Match: "2"
...

(draft 05)

11. Acknowledgments

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

(draft 05)

12. Issues

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

(draft 05)

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

(draft 06 : http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-12.1 )

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, <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, <http://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>.

( draft 06 : http://tools.ietf.org/html/draft-hardjono-oauth-umacore-06#section-12.2 )

13. References

(draft 05)

13.1. Normative References

[DynClientReg]
Hardjono, T., “OAuth Dynamic Client Registration Protocol”, May 2012, <https://datatracker.ietf.org/doc/ draft-ietf-oauth-dyn-reg/>.
[OAuth-SAML]
Campbell, B., “SAML 2.0 Bearer Assertion Grant Type Profile for OAuth 2.0”, August 2011, <http://tools.ietf.org/html/ draft-ietf-oauth-saml2-bearer>.
[OAuth-bearer]
“The OAuth 2.0 Authorization Protocol: Bearer Tokens”, March 2012, <http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer>.
[OAuth2] Hammer-Lahav, E., “The OAuth 2.0 Protocol”,
September 2011, <http://tools.ietf.org/html/draft-ietf-oauth-v2>.
[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-trustmodel]
Maler, E., “UMA Trust Model”, April 2012, <http:// kantarainitiative.org/confluence/display/uma/ UMA+Trust+Model>.

(draft 05)

13.2. Informative References

[UMA-usecases]
Maler, E., “UMA Scenarios and Use Cases”, October 2010, <h ttp://kantarainitiative.org/confluence/display/uma/ UMA+Scenarios+and+Use+Cases>.
[UMA-userstories]
Maler, E., “UMA User Stories”, November 2010, <http:// kantarainitiative.org/confluence/display/uma/ User+Stories>.
[UMAnitarians]
Maler, E., “UMA Participant Roster”, 2012, <http:// kantarainitiative.org/confluence/display/uma/ Participant+Roster>.

(draft 05)

Resource Set Descriptor for OpenID Connect

If an OpenID Connect OP works as an UMA AM, the OP can return the UserInfo in which Users’ resource at Host are included as an Aggregated Claim , or OAuth Access Tokens to the Host endpoint are includde.

To make OpenID Connet OP as a middle man, the Host gives extra parameters in UMA Resoure Set Description for Protection API.

token_endpoint
Connect OP ask the Host to issue an access token and an refresh token at this endpoint. Requests are authenticated by OAuth Bear Token Profile with credentai_token.
credential_token
Token for the Token Endpoint request authtentiction
refresh_token
Token to refresh an access token and the other reflesh token.
resource_endpoint
Users resource is returned from this endpoint in exchange for access token.

The following JSON is an non-normative sample to be put by Host to Connect OP as AM for Protecttion API.

{
  "name": "Photo Album",

  "icon_uri": "http://www.example.com/icons/flower.png",

  "scopes": [
    "http://photoz.example.com/dev/scopes/view",
    "http://photoz.example.com/dev/scopes/all"
  ],

  "token_endpoint": "https://photoz.example.com/dev/token/",
  "credential_token" : "fdsafdsafdsafa",
  "refresh_token" : "432gsafgds9",
  "resource_endpoint": "https://photoz.example.com/dev/resource/",
}

If the User configure to return his UserInfo including resource at Host, the OP refreshes an access token in exchange for the refresh_tokne first, then get the resource at token_endpoint in exchange for the access token.

After the resource is returned in JWT form to the OP, OP include it as an Aggregated Claim in the UserInfo( which is to be returnd to the other RP).

If the User configure to return an access token to the Host in UserInfo, OP includes the access token given by Host’ token_endpoint in the UserInfo.

«  OpenID Connect Session Management 1.0   ::   Contents   ::   Binding Obligations on User-Managed Access (UMA) Participants  »