idnits 2.17.1
draft-hardjono-oauth-umacore-07.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 6 instances of too long lines in the document, the longest one
being 12 characters in excess of 72.
== There are 1 instance of lines with non-RFC2606-compliant FQDNs in the
document.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document seems to lack the recommended RFC 2119 boilerplate, even if
it appears to use RFC 2119 keywords.
(The document does seem to have the reference to RFC 2119 which the
ID-Checklist requires).
-- The document date (June 29, 2013) is 3953 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
-- Looks like a reference, but probably isn't: '1' on line 1541
-- Looks like a reference, but probably isn't: '2' on line 1636
-- Possible downref: Non-RFC (?) normative reference: ref. 'DynClientReg'
-- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-SAML'
-- Possible downref: Non-RFC (?) normative reference: ref.
'OAuth-introspection'
-- Possible downref: Non-RFC (?) normative reference: ref.
'OAuth-resource-reg'
** Downref: Normative reference to an Informational RFC: RFC 6819 (ref.
'OAuth-threat')
-- Possible downref: Non-RFC (?) normative reference: ref. 'OCMessages'
-- Possible downref: Non-RFC (?) normative reference: ref. 'OCStandard'
** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159)
-- Possible downref: Non-RFC (?) normative reference: ref. 'UMA-obligations'
Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 10 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group T. Hardjono, Ed.
3 Internet-Draft MIT
4 Intended status: Standards Track June 29, 2013
5 Expires: December 31, 2013
7 User-Managed Access (UMA) Profile of OAuth 2.0
8 draft-hardjono-oauth-umacore-07
10 Abstract
12 User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how
13 resource owners can control protected-resource access by clients
14 operated by arbitrary requesting parties, where the resources reside
15 on any number of resource servers, and where a centralized
16 authorization server governs access based on resource owner policy.
18 Status of This Memo
20 This Internet-Draft is submitted in full conformance with the
21 provisions of BCP 78 and BCP 79.
23 Internet-Drafts are working documents of the Internet Engineering
24 Task Force (IETF). Note that other groups may also distribute
25 working documents as Internet-Drafts. The list of current Internet-
26 Drafts is at http://datatracker.ietf.org/drafts/current/.
28 Internet-Drafts are draft documents valid for a maximum of six months
29 and may be updated, replaced, or obsoleted by other documents at any
30 time. It is inappropriate to use Internet-Drafts as reference
31 material or to cite them other than as "work in progress."
33 This Internet-Draft will expire on December 31, 2013.
35 Copyright Notice
37 Copyright (c) 2013 IETF Trust and the persons identified as the
38 document authors. All rights reserved.
40 This document is subject to BCP 78 and the IETF Trust's Legal
41 Provisions Relating to IETF Documents
42 (http://trustee.ietf.org/license-info) in effect on the date of
43 publication of this document. Please review these documents
44 carefully, as they describe your rights and restrictions with respect
45 to this document. Code Components extracted from this document must
46 include Simplified BSD License text as described in Section 4.e of
47 the Trust Legal Provisions and are provided without warranty as
48 described in the Simplified BSD License.
50 Table of Contents
52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5
54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
55 1.3. APIs and Protection . . . . . . . . . . . . . . . . . . . 7
56 1.3.1. Protection and Authorization APIs at the
57 Authorization Server . . . . . . . . . . . . . . . . 7
58 1.3.2. API at the Resource Server . . . . . . . . . . . . . 8
59 1.4. Authorization Server Configuration Data . . . . . . . . . 9
60 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 12
61 3. Getting Authorization and Accessing a Resource . . . . . . . 13
62 3.1. Client Attempts to Access Protected Resource . . . . . . 15
63 3.1.1. Client Presents No RPT . . . . . . . . . . . . . . . 15
64 3.1.2. Client Presents RPT . . . . . . . . . . . . . . . . . 16
65 3.2. Resource Server Registers Requested Permission With
66 Authorization Server . . . . . . . . . . . . . . . . . . 17
67 3.3. Resource Server Determines RPT's Status . . . . . . . . . 19
68 3.3.1. Token Introspection . . . . . . . . . . . . . . . . . 19
69 3.3.2. RPT Profile: Bearer . . . . . . . . . . . . . . . . . 20
70 3.4. Client Seeks Authorization for Access . . . . . . . . . . 22
71 3.4.1. Client Obtains RPT . . . . . . . . . . . . . . . . . 23
72 3.4.2. Client Asks for Authorization Data . . . . . . . . . 23
73 3.5. Claims-Gathering Flows . . . . . . . . . . . . . . . . . 25
74 3.5.1. Claims-Gathering Flow for Clients Operated by End-
75 Users . . . . . . . . . . . . . . . . . . . . . . . . 25
76 3.5.1.1. OpenID Connect Claim Profile . . . . . . . . . . 26
77 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 27
78 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 28
79 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 28
80 5. Specificying Additional Profiles . . . . . . . . . . . . . . 29
81 5.1. Specifying Profiles of UMA . . . . . . . . . . . . . . . 29
82 5.2. Specifying RPT Profiles . . . . . . . . . . . . . . . . . 30
83 5.3. Specifying Claim Profiles . . . . . . . . . . . . . . . . 31
84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 31
85 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 33
86 8. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 33
87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
88 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33
89 11. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
90 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
91 12.1. Normative References . . . . . . . . . . . . . . . . . . 34
92 12.2. Informative References . . . . . . . . . . . . . . . . . 35
93 Appendix A. Document History . . . . . . . . . . . . . . . . . . 36
94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36
96 1. Introduction
97 User-Managed Access (UMA) is a profile of OAuth 2.0 [OAuth2]. UMA
98 defines how resource owners can control protected-resource access by
99 clients operated by arbitrary requesting parties, where the resources
100 reside on any number of resource servers, and where a centralized
101 authorization server governs access based on resource owner policy.
102 Resource owners configure authorization servers with access policies
103 that serve as implicit authorization grants. Thus, the UMA profile
104 of OAuth can be considered to encompass an authorization grant flow.
106 UMA serves numerous use cases where a resource owner outsources
107 authorization for access to their resources, potentially even without
108 the run-time presence of the resource owner. A typical example is
109 the following: a web user (an end-user resource owner) can authorize
110 a web app (client) to gain one-time or ongoing access to a protected
111 resource containing his home address stored at a "personal data
112 store" service (resource server), by telling the resource server to
113 respect access entitlements issued by his chosen cloud-based
114 authorization service (authorization server). The requesting party
115 operating the client might be the resource owner himself, using a web
116 or native app run by an e-commerce company that needs to know where
117 to ship a purchased item, or it might be his friend who is using an
118 online address book service to collect contact information, or it
119 might be a survey company that uses an autonomous web service to
120 compile population demographics. A variety of scenarios and use
121 cases can be found in [UMA-usecases] and [UMA-casestudies].
123 Practical control of access among loosely coupled parties requires
124 more than just messaging protocols. This specification defines only
125 the technical "contract" between UMA-conforming entities; its
126 companion Binding Obligations specification [UMA-obligations] defines
127 the expected behaviors of parties operating and using these entities.
128 Parties operating entities that claim to be UMA-conforming MUST
129 provide documentation affirmatively stating their acceptance of the
130 binding obligations contractual framework defined in the Binding
131 Obligations specification.
133 In enterprise settings, application access management sometimes
134 involves letting back-office applications serve only as policy
135 enforcement points (PEPs), depending entirely on access decisions
136 coming from a central policy decision point (PDP) to govern the
137 access they give to requesters. This separation eases auditing and
138 allows policy administration to scale in several dimensions. UMA
139 makes use of a separation similar to this, letting the resource owner
140 serve as a policy administrator crafting authorization strategies for
141 resources under their control.
143 In order to increase interoperable communication among the
144 authorization server, resource server, and client, UMA defines
145 several purpose-built APIs related to the outsourcing of
146 authorization, themselves protected by OAuth in embedded fashion.
148 The UMA protocol has three broad phases, as shown in Figure 1.
150 The Three Phases of the UMA Profile of OAuth
152 +--------------+
153 | resource |
154 +---------manage (A)------------ | owner |
155 | +--------------+
156 | Phase 1: |
157 | protect a control (B)
158 | resource |
159 v v
160 +------------+ +----------+--------------+
161 | | |protection| |
162 | resource | | API | authorization|
163 | server |<-protect (C)--| (needs | server |
164 | | | PAT) | |
165 +------------+ +----------+--------------+
166 | protected | | authorization|
167 | resource | | API |
168 |(needs RPT) | | (needs AAT) |
169 +------------+ +--------------+
170 ^ |
171 | Phases 2 and 3: authorize (D)
172 | get authorization, |
173 | access a resource v
174 | +--------------+
175 +---------access (E)-------------| client |
176 +--------------+
178 requesting party
180 Figure 1
182 The phases work as follows:
184 Protect a resource (Described in Section 2.) The resource owner,
185 who manages online resources at the resource server ("A"),
186 introduces it to the authorization server so that the latter can
187 begin controlling the resources' protection. To accomplish this
188 protection, the authorization server presents a protection API
189 ("C") to the resource server. This API is OAuth-protected and
190 requires a protection API token (PAT) for access. The API
191 consists of an OAuth resource set registration endpoint as defined
192 by [OAuth-resource-reg], an endpoint for registering client-
193 requested permissions, and an OAuth token introspection endpoint
194 as defined by [OAuth-introspection]. Out of band, the resource
195 owner configures the authorization server with policies associated
196 with the registered resource sets ("B").
198 Get authorization (Described in Section 3.) The client approaches
199 the resource server seeking access to a protected resource. In
200 order to access it successfully, the client must first use the
201 authorization server's authorization API ("D") to obtain a
202 requesting party token (RPT) on behalf of its requesting party,
203 and the requesting party must supply to the authorization server
204 any identity claims needed in order for the server to associate
205 sufficient authorization data with that RPT. The API is OAuth-
206 protected and requires an authorization API token (AAT) for
207 access. The API consists of an RPT issuance endpoint and an
208 authorization request endpoint.
210 Access a resource (Described along with Phase 2 in Section 3.) The
211 client successfully presents an RPT that has sufficient
212 authorization data associated with it to the resource server,
213 gaining access to the desired resource ("E"). In this sense, this
214 phase is the "happy path" within phase 2. The nature of the
215 authorization data varies according to the RPT profile in use.
217 Implementers are anticipated to develop profiles (see Section 5) that
218 specify and restrict various UMA protocol, RPT, and identity claim
219 options, according to deployment and usage conditions.
221 1.1. Notational Conventions
223 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
224 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
225 document are to be interpreted as described in [RFC2119].
227 Unless otherwise noted, all the protocol properties and values are
228 case sensitive.
230 1.2. Terminology
232 UMA introduces the following new terms and enhancements of OAuth term
233 definitions.
235 resource owner
236 An OAuth resource that is the "user" in User-Managed Access.
237 This is typically an end-user (a natural person) but it can
238 also be a corporation or other legal person.
240 requesting party
241 An end-user, or a corporation or other legal person, that uses
242 a client to seek access to a protected resource. The
243 requesting party may or may not be the same party as the
244 resource owner.
246 client
247 An application making protected resource requests with the
248 resource owner's authorization and on the requesting party's
249 behalf.
251 claim
252 A statement of the value or values of one or more identity
253 attributes of a requesting party. A requesting party may need
254 to provide claims to an authorization server in order to
255 satisfy policy and gain permission for access to a protected
256 resource.
258 resource set A set of one or more protected resources. In
259 authorization policy terminology, a resource set is the
260 "object" being protected.
262 scope A bounded extent of access that is possible to perform on a
263 resource set. In authorization policy terminology, a scope is
264 one of the potentially many "verbs" that can logically apply to
265 a resource set ("object"). UMA associates scopes with labeled
266 resource sets.
268 authorization data Data associated with a requesting party token
269 that enables some combination of the authorization server and
270 resource server to determine the correct extent of access to
271 allow to a client. Authorization data is a key part of the
272 definition of an RPT profile.
274 permission A scope of access over a particular resource set at a
275 particular resource server that is being requested by, or
276 granted to, a requesting party. In authorization policy
277 terminology, a permission is an entitlement that includes a
278 "subject" (requesting party), "verbs" (one or more scopes of
279 access), and an "object" (resource set). A permission is one
280 example of authorization data that an authorization server may
281 issue.
283 permission ticket A correlation handle that is conveyed from an
284 authorization server to a resource server, from a resource
285 server to a client, and ultimately from a client to an
286 authorization server, to enable the authorization server to
287 assess the correct resource owner policies to apply to a
288 request for an authorization grant.
290 1.3. APIs and Protection
292 UMA involves three APIs, all of which are protected.
294 The authorization server has the opportunity to manage the validity
295 periods of access tokens that it issues, their corresponding refresh
296 tokens where applicable, the individual data components associated
297 with RPTs where applicable, and even the client credentials that it
298 issues. Different time-to-live strategies may be suitable for
299 different resources and scopes of access, and the authorization
300 server has the opportunity to give the resource owner control over
301 lifetimes of tokens and authorization data issued on their behalf
302 through policy. These options are all outside the scope of this
303 specification.
305 1.3.1. Protection and Authorization APIs at the Authorization Server
307 The authorization server presents a protection API to the resource
308 server and an authorization API to the client. These APIs MUST be
309 OAuth-protected; thus, the authorization server has an OAuth token
310 endpoint and user authorization endpoint, and has the option to issue
311 an OAuth refresh token along with any access tokens issued for these
312 APIs.
314 The protection API consists of an OAuth resource set registration
315 endpoint as defined by [OAuth-resource-reg], an endpoint for
316 registering client-requested permissions, and an OAuth token
317 introspection endpoint as defined by [OAuth-introspection]. This
318 specification profiles the endpoints defined by these other
319 specifications.
321 The authorization API consists of an RPT issuance endpoint and an
322 authorization request endpoint.
324 All endpoint URIs SHOULD require the use of a transport-layer
325 security mechanism such as TLS. The authorization server MUST
326 declare all of its endpoints in its configuration data (see
327 Section 1.4).
329 An entity seeking protection API access MUST request the scope "http:
330 //docs.kantarainitiative.org/uma/scopes/prot.json", and an access
331 token with at least this scope is called a protection API token
332 (PAT). An entity seeking authorization API access MUST request the
333 scope "http://docs.kantarainitiative.org/uma/scopes/authz.json", and
334 an access token with at least this scope is called an authorization
335 API token (AAT). The same entity can serve in both roles, so that an
336 OAuth access token might be considered both a PAT and an AAT if it
337 has both scopes. If a request to an endpoint fails due to an
338 invalid, missing, or expired PAT or AAT, or requires higher
339 privileges at this endpoint than provided by the PAT or AAT, the
340 authorization server responds with an OAuth error.
342 Note: These scope keywords are URIs that resolve to JSON-encoded
343 scope descriptions, as defined in [OAuth-resource-reg]. These scope
344 descriptions are non-normative for the purposes of PATs and AATs.
346 The authorization server is REQUIRED to support the OAuth bearer
347 token profile for PAT and AAT issuance, and MAY support other OAuth
348 token profiles for these purposes. It MUST declare all supported
349 token profiles for PAT and AAT issuance in its configuration data.
350 The authorization server MAY support the use of any OAuth grant type
351 for PAT and AAT issuance, but MUST support the authorization_code
352 grant type, and SHOULD support the SAML bearer token grant type
353 [OAuth-SAML] (urn:ietf:params:oauth:grant-type:saml2-bearer) if it
354 anticipates working with entities that are operating in environments
355 where the use of SAML is prevalent. It MUST declare its supported
356 grant types for PAT and AAT issuance in its configuration data.
358 A PAT binds a resource owner, a resource server the owner uses for
359 resource management, and an authorization server the owner uses for
360 protection of resources at this resource server. It is not specific
361 to any client or requesting party. The issuance of a PAT represents
362 the approval of the resource owner for this resource server to trust
363 this authorization server for protecting its resources belonging to
364 this resource owner.
366 An AAT binds a requesting party, a client being used by that party,
367 and an authorization server that protects resources this client is
368 seeking access to on this requesting party's behalf. It is not
369 specific to any resource server or resource owner. The issuance of
370 an AAT represents the approval of this requesting party for this
371 client to engage with this authorization server to supply claims, ask
372 for authorization, and perform any other tasks needed for obtaining
373 authorization for access to resources at all resource servers that
374 use this authorization server. The authorization server is able to
375 manage future processes of authorization and claims-caching
376 efficiently for this client/requesting party pair across all resource
377 servers they try to access. These management processes are outside
378 the scope of this specification, however.
380 1.3.2. API at the Resource Server
382 The resource server presents one or more protected resource endpoints
383 to the client; these endpoints are protected by the UMA profile of
384 OAuth and require a requesting party token (RPT) with sufficient
385 authorization data for access. This specification defines one RPT
386 profile, call "bearer" (see Section 3.3.2), which is REQUIRED for the
387 authorization server to support. It MAY support additional RPT
388 profiles. It MUST declare all supported RPT profiles in its
389 configuration data.
391 An RPT represents a binding of a requesting party, the client being
392 used by that party, the resource server at which protected resources
393 of interest reside, and the authorization server that protects those
394 resources. It is not specific to a single resource owner, though its
395 internal components are likely to be bound to individual resource
396 owners, depending on the RPT profile in use.
398 1.4. Authorization Server Configuration Data
400 The authorization server MUST provide configuration data in a JSON
401 [RFC4627] document that resides in an /uma-configuration directory at
402 at its hostmeta [hostmeta] location. The configuration data
403 documents conformance options and endpoints supported by the
404 authorization server. (At the appropriate time, this section will
405 instead profile whatever self-describing metadata specification OAuth
406 adopts, for example, [OAuth-linktypes] or [OAuth-meta].)
408 The configuration data has the following properties.
410 version
411 REQUIRED. The version of the UMA core protocol to which this
412 authorization server conforms. The value MUST be the string
413 "1.0".
415 issuer
416 REQUIRED. A URI indicating the party operating the
417 authorization server.
419 pat_profiles_supported
420 REQUIRED. Access token profiles supported by this
421 authorization server for PAT issuance. The property value is
422 an array of string values, where each string value is either a
423 reserved keyword defined in this specification or a URI
424 identifying an access token profile defined elsewhere. The
425 reserved keyword "bearer" as a value for this property stands
426 for the OAuth bearer token profile [OAuth-bearer]. The
427 authorization server is REQUIRED to support this profile, and
428 to supply this string value explicitly. The authorization
429 server MAY declare its support for additional access token
430 profiles for PATs.
432 aat_profiles_supported
433 REQUIRED. Access token profiles supported by this
434 authorization server for AAT issuance. The property value is
435 an array of string values, where each string value is either a
436 reserved keyword defined in this specification or a URI
437 identifying an access token profile defined elsewhere. The
438 reserved keyword "bearer" as a value for this property stands
439 for the OAuth bearer token profile [OAuth-bearer]. The
440 authorization server is REQUIRED to support this profile, and
441 to supply this string value explicitly. The authorization
442 server MAY declare its support for additional access token
443 profiles for AATs.
445 rpt_profiles_supported
446 REQUIRED. Access token profiles supported by this
447 authorization server for RPT issuance. The property value is
448 an array of string values, where each string value is either a
449 reserved keyword defined in this specification or a URI
450 identifying an access token profile defined elsewhere. The
451 reserved keyword "bearer" as a value for this property stands
452 for the UMA bearer RPT profile defined in [OAuth-bearer]. The
453 authorization server is REQUIRED to support this profile, and
454 to supply this string value explicitly. The authorization
455 server MAY declare its support for additional access token
456 profiles for RPTs.
458 pat_grant_types_supported
459 REQUIRED. OAuth grant types supported by this authorization
460 server in issuing PATs. The property value is an array of
461 string values. Each string value MUST be one of the grant_type
462 values defined in [OAuth2], or alternatively a URI identifying
463 a grant type defined elsewhere.
465 aat_grant_types_supported
466 REQUIRED. OAuth grant types supported by this authorization
467 server in issuing AATs. The property value is an array of
468 string values. Each string value MUST be one of the grant_type
469 values defined in [OAuth2], or alternatively a URI identifying
470 a grant type defined elsewhere.
472 claim_profiles_supported
473 OPTIONAL. Claim formats and associated sub-protocols for
474 gathering claims from requesting parties, as supported by this
475 authorization server. The property value is an array of string
476 values, which each string value is either a reserved keyword
477 defined in this specification or a URI identifying a claim
478 profile defined elsewhere. The reserved keyword "openid" as a
479 value for this property stands for the UMA OpenID Connect claim
480 profile defined in Section 3.5.1.1.
482 dynamic_client_endpoint
483 OPTIONAL. The endpoint to use for performing dynamic client
484 registration. Usage is defined by [DynClientReg]. The
485 presence of this property indicates authorization server
486 support for the dynamic client registration feature and its
487 absent indicates a lack of support.
489 token_endpoint
490 REQUIRED. The endpoint URI at which the resource server or
491 client asks the authorization server for a PAT or AAT,
492 respectively. A requested scope of "http://
493 docs.kantarainitiative.org/uma/scopes/prot.json" results in a
494 PAT. A requested scope of "http://docs.kantarainitiative.org/
495 uma/scopes/authorization" results in an AAT. Usage is defined
496 by [OAuth2].
498 user_endpoint
499 REQUIRED. The endpoint URI at which the resource server
500 gathers the consent of the end-user resource owner or the
501 client gathers the consent of the end-user requesting party, if
502 the "authorization_code" grant type is used. Usage is defined
503 by [OAuth2].
505 introspection_endpoint
506 REQUIRED. The endpoint URI at which the resource server
507 introspects an RPT presented to it by a client. Usage is
508 defined by [OAuth-introspection] and Section 3.3.1. A valid
509 PAT MUST accompany requests to this protected endpoint.
511 resource_set_registration_endpoint
512 REQUIRED. The endpoint URI at which the resource server
513 registers resource sets to put them under authorization manager
514 protection. Usage is defined by [OAuth-resource-reg] and
515 Section 2. A valid PAT MUST accompany requests to this
516 protected endpoint.
518 permission_registration_endpoint
519 REQUIRED. The endpoint URI at which the resource server
520 registers a client-requested permission with the authorization
521 server. Usage is defined by Section 3.2. A valid PAT MUST
522 accompany requests to this protected endpoint.
524 rpt_endpoint
525 REQUIRED. The endpoint URI at which the client asks the
526 authorization server for an RPT. Usage is defined by
527 Section 3.4.1. A valid AAT MUST accompany requests to this
528 protected endpoint.
530 authorization_request_endpoint
531 REQUIRED. The endpoint URI at which the client asks to have
532 authorization data associated with its RPT. Usage is defined
533 in Section 3.4.2. A valid AAT MUST accompany requests to this
534 protected endpoint.
536 Example of authorization server configuration data that resides at
537 https://example.com/.well-known/uma-configuration (note the use of
538 https: for endpoints throughout):
540 {
541 "version":"1.0",
542 "issuer":"https://example.com",
543 "pat_profiles_supported":["bearer"],
544 "aat_profiles_supported":["bearer"],
545 "rpt_profiles_supported":["bearer"],
546 "pat_grant_types_supported":["authorization_code"],
547 "aat_grant_types_supported":["authorization_code"],
548 "claim_profiles_supported":["openid"],
549 "dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
550 "token_endpoint":"https://as.example.com/token_uri",
551 "user_endpoint":"https://as.example.com/user_uri",
552 "resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
553 "introspection_endpoint":"https://as.example.com/rs/status_uri",
554 "permission_registration_endpoint":"https://as.example.com/rs/perm_uri",
555 "rpt_endpoint":"https://as.example.com/client/rpt_uri",
556 "authorization_request_endpoint":"https://as.example.com/client/perm_uri"
557 }
559 Authorization server configuration data MAY contain extension
560 properties that are not defined in this specification. Extension
561 names that are unprotected from collisions are outside the scope of
562 this specification.
564 2. Protecting a Resource
566 The resource owner, resource server, and authorization server perform
567 the following actions to put resources under protection. This list
568 assumes that the resource server has discovered the authorization
569 server's configuration data and endpoints as needed.
571 1. The authorization server issues client credentials to the
572 resource server. It is OPTIONAL for the client credentials to be
573 provided dynamically through [DynClientReg]); alternatively, they
574 MAY use a static process.
576 2. The resource server acquires a PAT from the authorization server
577 in order to use the resource set registration endpoint (and
578 later, other protection API endpoints). It is OPTIONAL for the
579 resource owner to introduce the resource server to the
580 authorization server dynamically (for example, through a
581 "NASCAR"-style user interface where the resource owner selects a
582 chosen authorization server); alternatively, they MAY use a
583 static process that may or may not directly involve the resource
584 owner at introduction time.
586 3. In an ongoing fashion, the resource server registers any resource
587 sets with the authorization server for which it intends to
588 outsource protection, using the process defined by
589 [OAuth-resource-reg].
591 Note: The resource server is free to offer the option to protect any
592 subset of the resource owner's resources using different
593 authorization servers or other means entirely, or to protect some
594 resources and not others. Additionally, the choice of protection
595 regimes can be made explicitly by the resource owner or implicitly by
596 the resource server. Any such partitioning by the resource server or
597 owner is outside the scope of this specification.
599 Once a resource set has been placed under authorization server
600 protection through the registration of a resource set description for
601 it, and until such a description's deletion by the resource server,
602 the resource server MUST limit access to corresponding resources,
603 respecting authorization data associated with client-presented RPTs
604 by the authorization server as appropriate (see Section 3.1.2).
606 3. Getting Authorization and Accessing a Resource
608 An authorization server orchestrates and controls clients' access (on
609 their requesting parties' behalf) to a resource owner's protected
610 resources at a resource server, under conditions dictated by that
611 resource owner.
613 The process of getting authorization and accessing a resource always
614 begins with the client attempting access at a protected resource
615 endpoint at the resource server. How the client came to learn about
616 this endpoint is out of scope for this specification. The resource
617 owner might, for example, have advertised its availability publicly
618 on a blog or other website, listed it in a discovery service, or
619 emailed a link to a particular intended requesting party.
621 The resource server responds to the client's access request with
622 whatever its application-specific interface defines as a success
623 response, either immediately or having first performed one or more
624 embedded interactions with the authorization server. Depending on
625 the nature of the resource server's response to an failed access
626 attempt, the client and its requesting party engage in embedded
627 interactions with the authorization server before re-attempting
628 access.
630 The interactions are as follows. Each interaction MAY be the last,
631 if the client chooses not to continue pursuing the access attempt or
632 the resource server chooses not to continue facilitating it.
634 o The client attempts to access a protected resource.
636 * If the access attempt is unaccompanied by an RPT, the resource
637 server responds immediately with an HTTP 401 (Unauthorized)
638 response and instructions on where to go to obtain one.
640 * If the access attempt was accompanied by an RPT, the resource
641 server checks the RPT's status.
643 + If the RPT is invalid, the resource server responds with an
644 HTTP 401 (Unauthorized) response and instructions on where
645 to go to obtain a token.
647 + If the RPT is valid but has insufficient authorization data,
648 the resource server registers a suitable requested
649 permission on the client's behalf at the authorization
650 server, and then responds to the client with an HTTP 403
651 (Forbidden) response and instructions on where to go to ask
652 for authorization.
654 + If the RPT is valid, and if the authorization data
655 associated with the token is sufficient for allowing access,
656 the resource server responds with an HTTP 2xx (Success)
657 response and a representation of the resource.
659 o If the client (possessing no RPT or an invalid RPT) received a 401
660 response and an authorization server's location, after looking up
661 its configuration data and endpoints as necessary, it requests an
662 RPT from the RPT endpoint.
664 o If the client (posessing a valid RPT) received a 403 response and
665 a permission ticket, it asks the authorization server for
666 authorization data that matches the ticket. If the authorization
667 server needs requesting party claims in order to assess this
668 client's authorization, it engages in a claims-gathering flow with
669 the requesting party.
671 * If the client does not already have an AAT at the appropriate
672 authorization server to be able to use its authorization API,
673 it first obtains one.
675 The interactions are described in detail in the following sections.
677 3.1. Client Attempts to Access Protected Resource
679 This interaction assumes that the resource server has previously
680 registered one or more resource sets that correspond to the resource
681 to which access is being attempted.
683 The client attempts to access a protected resource (for example, when
684 an end-user requesting party clicks on a thumbnail representation of
685 the resource to retrieve a larger version). It is expected to
686 discover, or be provisioned or configured with, knowledge of the
687 protected resource and its location out of band. Further, the client
688 is expected to acquire its own knowledge about the application-
689 specific methods made available by the resource server for operating
690 on this protected resource (such as viewing it with a GET method, or
691 transforming it with some complex API call) and the possible scopes
692 of access.
694 The access attempt either is or is not accompanied by an RPT.
696 3.1.1. Client Presents No RPT
698 Example of a request carrying no RPT:
700 GET /album/photo.jpg HTTP/1.1
701 Host: photoz.example.com
702 ...
704 If the client does not present an RPT with the request, the resource
705 server MUST return an HTTP 401 (Unauthorized) status code, along with
706 providing the authorization server's URI in an "as_uri" property to
707 facilitate authorization server configuration data discovery,
708 including discovery of the endpoint where the client can request an
709 RPT (Section 3.4.1).
711 For example:
713 HTTP/1.1 401 Unauthorized
714 WWW-Authenticate: UMA realm="example",
715 host_id="photoz.example.com",
716 as_uri="https://as.example.com"
717 ...
719 3.1.2. Client Presents RPT
721 Example of a request carrying an RPT using the UMA bearer RPT
722 profile:
724 GET /album/photo.jpg HTTP/1.1
725 Authorization: Bearer vF9dft4qmT
726 Host: photoz.example.com
727 ...
729 If the client presents an RPT with its request, the resource server
730 MUST determine the RPT's status (see Section 3.3) before responding.
732 If the RPT is invalid, the resource server MUST return an HTTP 401
733 (Unauthorized) status code, along with providing the authorization
734 server's URI in an "as_uri" property in the header, similarly to the
735 case where no RPT was presented.
737 If the RPT is valid but has insufficient authorization data for the
738 type of access sought, the resource server SHOULD register a
739 requested permission with the authorization server that would suffice
740 for that scope of access (see Section 3.2), and then respond with the
741 HTTP 403 (Forbidden) status code, along with providing the
742 authorization server's URI in an "as_uri" property in the header, and
743 the permission ticket it just received from the AM in the body in a
744 JSON-encoded "ticket" property.
746 Example of the host's response after having registered a requested
747 permission and received a ticket:
749 HTTP/1.1 403 Forbidden
750 WWW-Authenticate: UMA realm="example",
751 host_id="photoz.example.com",
752 as_uri="https://as.example.com"
753 error="insufficient_scope"
755 {
756 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
757 }
759 If the RPT's status is associated with authorization data that is
760 consistent with authorized access of the scope sought by the client,
761 the resource server MUST give access to the desired resource.
763 Example of the resource server's response after having determineed
764 that the RPT is valid and associated with sufficient authorization
765 data:
767 HTTP/1.1 200 OK
768 Content-Type: image/jpeg
769 ...
771 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
772 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
773 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
774 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
776 The resource server MUST NOT give access where the token's status is
777 not associated with sufficient authorization data for the attempted
778 scope of access.
780 3.2. Resource Server Registers Requested Permission With Authorization
781 Server
783 In response to receiving an access request accompanied by an RPT that
784 has insufficient authorization data, the resource server registers a
785 permission with the authorization server that would be sufficient for
786 the type of access sought. The authorization server returns a
787 permission ticket for the resource server to give to the client in
788 its response.
790 The resource server MUST provide its valid PAT in order to get access
791 to this endpoint. Note that this PAT implicitly identifies the
792 resource owner ("subject") to which the permission applies.
794 The permission ticket is a short-lived opaque structure whose form is
795 determined by the authorization server. The ticket value MUST be
796 securely random (for example, not merely part of a predictable
797 sequential series), to avoid denial-of-service attacks. Since the
798 ticket is an opaque structure from the point of view of the client,
799 the authorization server is free to include information regarding
800 expiration time within the opaque ticket for its own consumption.
801 When the client subsequently asks the authorization server for
802 authorization data to be associated with its RPT, it will submit this
803 ticket to the authorization server.
805 The resource server registers the requested permission using the POST
806 method at the authorization server's permission registration
807 endpoint. The resource server MUST provide its valid PAT in order to
808 get access to this endpoint. The body of the HTTP request message
809 contains a JSON object providing the requested permission, using a
810 format derived from the scope description format specified in
811 [OAuth-resource-reg], as follows. The object has the following
812 properties:
814 resource_set_id REQUIRED. The identifier for a resource set, access
815 to which this client is seeking access. The identifier MUST
816 correspond to a resource set that was previously registered.
818 scopes REQUIRED. An array referencing one or more identifiers of
819 scopes to which access is needed for this resource set. Each
820 scope identifier MUST correspond to a scope that was registered by
821 this resource server for the referenced resource set.
823 Example of an HTTP request that registers a requested permission at
824 the authorization server's permission registration endpoint:
826 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
827 Content-Type: application/json
828 Host: as.example.com
830 {
831 "resource_set_id": "112210f47de98100",
832 "scopes": [
833 "http://photoz.example.com/dev/actions/view",
834 "http://photoz.example.com/dev/actions/all"
835 ]
836 }
837 If the registration request is successful, the authorization server
838 responds with an HTTP 201 (Created) status code and includes the
839 Location header in its response as well as the "ticket" property in
840 the JSON-formatted body.
842 For example:
844 HTTP/1.1 201 Created
845 Content-Type: application/json
846 Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543
847 ...
849 {
850 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
851 }
853 If the registration request is authenticated properly but fails due
854 to other reasons, the authorization server responds with an HTTP 400
855 (Bad Request) status code and includes one of the following UMA error
856 codes (see Section 4.2):
858 invalid_resource_set_id The provided resource set identifier was not
859 found at the authorization server.
861 invalid_scope At least one of the scopes included in the request was
862 not registered previously by this resource server.
864 3.3. Resource Server Determines RPT's Status
866 The resource server determines a received RPT's status, including
867 both its validity and, if valid, its associated authorization data,
868 before giving or refusing access to the client. An RPT is associated
869 with a set of authorization data that governs whether the client is
870 authorized for access. The token's nature and format are dictated by
871 its profile; the profile might allow it to be self-contained, such
872 that the resource server is able to determine its status locally, or
873 might require or allow the resource server to make a run-time
874 introspection request of the authorization server that issued the
875 token.
877 This specification makes one type of RPT mandatory to implement: the
878 UMA bearer token profile, as defined in Section 3.3.2. Implementers
879 MAY define and use other RPT profiles.
881 3.3.1. Token Introspection
882 Within any RPT profile, when a resource server needs to introspect a
883 token in a non-self-contained way to determine its status, it MUST
884 use the authorization server's OAuth introspection endpoint, defined
885 by [OAuth-introspection]. Any UMA token profile MAY require, allow,
886 or prohibit use of the token introspection endpoint, and MAY profile
887 its usage. The authorization server MUST OAuth-protect this endpoint
888 and require a PAT from the resource server for access to it. The
889 resource server MUST use the POST method in interacting with the
890 endpoint, not the GET method also defined by [OAuth-introspection].
892 3.3.2. RPT Profile: Bearer
894 This section defines the UMA bearer token profile. Following is a
895 summary:
897 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/
898 uma-token-bearer-1.0
900 o Profile author and contact information: Thomas Hardjono
901 (hardjono@mit.edu)
903 o Updates or obsoletes: None; this profile is new.
905 o Keyword in HTTP Authorization header: "Bearer".
907 o Syntax and semantics of token data: As defined below. The token
908 data format mainly involves time-bounded permissions.
910 o Token data association: The data associated to the on-the-wire
911 token by reference and retrieved at run time by the resource
912 server through profiled use of the OAuth token introspection
913 endpoint [OAuth-introspection], as defined below.
915 o Token data processing: As defined in this section and throughout
916 Section 3 of this specification.
918 o Grant type restrictions: None.
920 o Error states: As defined below.
922 o Security and privacy considerations: As defined in this section
923 and throughout Section 3 of this specification.
925 o Binding obligations: Because this RPT profile is mandatory for
926 authorization servers to implement, binding obligations related to
927 the use of this token profile are documented in [UMA-obligations].
929 On receiving an RPT of the "Bearer" type in an authorization header
930 from a client making an access attempt, the resource server MUST
931 introspect the token by using the authorization server's token
932 introspection endpoint. The PAT used by the resource server to make
933 the introspection request provides resource-owner context to the
934 authorization server.
936 The authorization server responds with a JSON object with the
937 structure dictated by [OAuth-introspection]. If the valid property
938 has a "true" value, then the JSON object MUST also contain an
939 extension property with the name "permissions" that contains an array
940 of zero or more values, each of which is an object consisting of
941 these properties:
943 resource_set_id REQUIRED. A string that uniquely identifies the
944 resource set, access to which has been granted to this client on
945 behalf of this requesting party. The identifier MUST correspond
946 to a resource set that was previously registered as protected.
948 scopes REQUIRED. An array referencing one or more URIs of scopes to
949 which access was granted for this resource set. Each scope MUST
950 correspond to a scope that was registered by this host for the
951 referenced resource set.
953 expires_at REQUIRED. Integer timestamp, measured in the number of
954 seconds since January 1 1970 UTC, indicating when this permission
955 will expire.
957 issued_at OPTIONAL. Integer timestamp, measured in the number of
958 seconds since January 1 1970 UTC, indicating when this permission
959 was originally issued.
961 Example:
963 HTTP/1.1 200 OK
964 Content-Type: application/json
965 Cache-Control: no-store
967 {
968 "valid": true,
969 "expires_at": "1256953732",
970 "issued_at": "1256912345",
971 "permissions": [
972 {
973 "resource_set_id": "112210f47de98100",
974 "scopes": [
975 "http://photoz.example.com/dev/actions/view",
976 "http://photoz.example.com/dev/actions/all"
977 ],
978 "expires_at" : "1256923456"
979 }
980 ]
981 }
983 3.4. Client Seeks Authorization for Access
985 In order to access a protected resource successfully, a client needs
986 to present a valid RPT with sufficient authorization data for access.
987 To get to this stage requires a number of previously successful
988 steps:
990 1. The authorization server issues client credentials to the client.
991 It is OPTIONAL for the client credentials to be provided
992 dynamically through [DynClientReg]); alternatively, they MAY use
993 a static process.
995 2. The client acquires an AAT. This enables it to use authorization
996 API endpoints.
998 3. The client acquires an RPT from the RPT endpoint. See
999 Section 3.4.1 for more detail.
1001 4. The client asks for authorization at the authorization request
1002 endpoint, providing the permission ticket it got from the
1003 resource server. The authorization server associates
1004 authorization data with the client's RPT based on the permission
1005 ticket, the resource owner's operative policies, and the results
1006 of any claims-gathering flows with the requesting party. See
1007 Section 3.4.2 for more detail.
1009 3.4.1. Client Obtains RPT
1011 The client might need an RPT if it has never before requested an RPT
1012 for this combination of requesting party, resource server, and
1013 authorization server, or if it has lost control of a previously
1014 issued RPT and needs a refreshed one. It obtains an RPT by
1015 performing a POST on the RPT endpoint. It MUST provide its own valid
1016 AAT in the header.
1018 Example of a request message containing an AAT:
1020 POST /rpt HTTP/1.1
1021 Host: as.example.com
1022 Authorization: Bearer jwfLG53^sad$#f
1023 ...
1025 The authorization server responds with an HTTP 201 (Created) status
1026 code and provides a new RPT.
1028 For example:
1030 HTTP/1.1 201 Created
1031 Content-Type: application/json
1033 {
1034 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
1035 }
1037 If the AAT provided in the header is the same as one provided for a
1038 previously issued still-valid RPT by this authorization server, the
1039 authorization server invalidates the old RPT and issues a new one.
1041 On first issuance, the RPT is associated with no authorization data
1042 and thus does not convey any authorizations for access.
1044 3.4.2. Client Asks for Authorization Data
1046 Once in possession of an AAT for this authorization server, an RPT
1047 that applies to this requesting party for this resource server and
1048 this authorization server, and a permission ticket, the client asks
1049 the authorization server to give it suitable authorization data for
1050 the sought-for access. It performs a POST on the authorization
1051 request endpoint, supplying its own AAT in the header and its RPT and
1052 the permission ticket in a JSON object with properties "rpt" and
1053 ticket", respectively.
1055 Example of a request message containing an AAT, an RPT, and a
1056 permission ticket:
1058 POST /token_status HTTP/1.1
1059 Host: as.example.com
1060 Authorization: Bearer jwfLG53^sad$#f
1061 ...
1063 {
1064 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
1065 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
1066 }
1068 The authorization server uses the ticket to look up the details of
1069 the previously registered requested permission, maps the requested
1070 permission to operative resource owner policies based on the resource
1071 set identifier and scopes in it, undergoes any claims-gathering flows
1072 required (see Section 3.5), and ultimately responds to the request.
1073 The resource owner's policies at the authorization server amount to
1074 an implicit authorization grant in governing the issuance of
1075 authorization data. (The authorization server is also free to enable
1076 the resource owner to set policies that require the owner to provide
1077 a run-time authorization grant in the form of a consent interaction,
1078 mediated by the authorization server. This setting of policies and
1079 gathering of consent is outside the scope of this specification.)
1081 The authorization server MUST base the addition of authorization data
1082 to RPTs on user policies. The nature of these policies is outside
1083 the scope of UMA, but generally speaking, they can be thought of as
1084 either independent of requesting-party features (for example, time of
1085 day) or dependent on requesting-party features (for example, whether
1086 they are over 18). Such requesting-party features can potentially be
1087 collected in a claims-gathering flow. If the authorization server
1088 does not add the requested authorization data, it responds using the
1089 appropriate HTTP status code and UMA error code (see Section 4.2):
1091 invalid_ticket The provided ticket was not found at the
1092 authorization server. The authorization server SHOULD respond
1093 with the HTTP 400 (Bad Request) status code.
1095 expired_ticket The provided ticket has expired. The authorization
1096 server SHOULD respond with the HTTP 400 (Bad Request) status code.
1098 not_authorized_permission The client is definitively not authorized
1099 for this authorization according to user policy. The
1100 authorization server SHOULD respond with the HTTP 403 (Forbidden)
1101 status code.
1103 need_claims The authorization server is unable to determine whether
1104 the client is authorized for this permission without gathering
1105 claims from the requesting party. The authorization server SHOULD
1106 respond with the HTTP 403 (Forbidden) status code. The client is
1107 therefore not authorized, but has the opportunity to engage its
1108 operator -- the requesting party -- in a claims-gathering flow
1109 with the authorization server (see Section 3.5) to continue
1110 seeking authorization.
1112 For example:
1114 HTTP/1.1 400 Bad Request
1115 Content-Type: application/json
1116 Cache-Control: no-store
1117 ...
1119 {
1120 "status": "error",
1121 "error": "expired_ticket"
1122 }
1124 3.5. Claims-Gathering Flows
1126 The process for requesting and providing claims is extensible and may
1127 have a variety of dependencies on the type of requesting party (for
1128 example, natural person or legal person) and the type of client (for
1129 example, browser, native app, or autonomously running web service).
1130 This specification provides a framework for handling end-user-driven
1131 clients and an optional "openid" claim profile, based on OpenID
1132 Connect, for gathering standardized claims from such an end-user. It
1133 also allows for the definition of additional claim profiles. The
1134 authorization server MAY support any number of claim profiles, and
1135 SHOULD document the claim profiles it supports its configuration
1136 data. For the business-level and legal implications of different
1137 claim profiles, see [UMA-obligations].
1139 3.5.1. Claims-Gathering Flow for Clients Operated by End-Users
1141 A client, whether web-based or native, is operated by an end-user in
1142 one of two typical situations:
1144 o The requesting party is a natural person (for example, a friend of
1145 the resource owner); the requesting party may even be the resource
1146 owner herself.
1148 o The requesting party is a legal person such as a corporation, and
1149 the end-user operating the client is acting as an agent of that
1150 legal person (for example, a customer support specialist
1151 representing a credit card company).
1153 For convenience, this specification refers to the end-user as a
1154 "requesting end-user" to cover both cases, which differ only at the
1155 level of business agreements (and potentially law), rather than
1156 technology. The authorization server has a variety of options at
1157 this point for satisfying the resource owner's policy; this
1158 specification does not dictate a single answer. For example, the
1159 authorization server could require the requesting end-user to
1160 register for and/or log in to a local authorization server account,
1161 or fill in a questionnaire, or complete a purchase. It could even
1162 require several of these operations, where the order is treated as
1163 significant for evaluating resource owner policies. A variety of
1164 claim profiling can be defined to achieve these effects.
1166 An end-user-driven client MUST redirect the requesting end-user to
1167 the authorization server in order to continue the process of seeking
1168 authorization, including a URI query parameter with the name "ticket"
1169 whose value conveys the permission ticket for which the need_claims
1170 error was received; for example, "ticket=016f84e8-f9b9-11e0-bd6f-
1171 0021cc6004de".
1173 Each claim profile MUST provide the following capabilities:
1175 redirect URI A means by which the client MUST supply the URI to
1176 which the authorization server MUST redirect the requesting end-
1177 user at the end of the claims-gathering process.
1179 callback URI A means by which the client OPTIONALLY supplies a
1180 callback URI for the authorization server to use.
1182 state A means by which the client SHOULD supply an opaque value used
1183 to maintain state between the request and the callback; this
1184 serves as a protection against XSRF attacks.
1186 3.5.1.1. OpenID Connect Claim Profile
1188 This section defines the OpenID Connect claim profile for UMA.
1189 Following is a summary:
1191 o Identifying URI: http://docs.kantarainitiative.org/uma/profiles/
1192 uma-claim-openid-1.0
1194 o Profile author and contact information: Thomas Hardjono
1195 (hardjono@mit.edu)
1197 o Updates or obsoletes: None; this profile is new.
1199 o Syntax and semantics of claim data: As defined below. The claim
1200 data format leverages the OpenID Connect protocol and the reserved
1201 claims defined in that specification.
1203 o Claims gathering method: As defined below.
1205 o Error states: None additional.
1207 o Security and privacy considerations: None additional.
1209 o Binding obligations: Binding obligations that apply to the use of
1210 this claim profile are documented in [UMA-obligations].
1212 If an authorization server supports the OpenID Connect claim profile,
1213 it MUST supply the "openid" value for one of its
1214 "claim_profiles_supported" values in its configuration data.
1216 To conform to this option, the authorization server MUST do the
1217 following:
1219 o Serve as a conforming OpenID Relying Party and Claims Client
1220 according to [OCStandard]
1222 o Be able to utilize at least all of the reserved claims defined in
1223 [OCMessages] in evaluating policy and adding authorization data to
1224 RPTs
1226 o Use the OpenID Connect "redirect_uri" and "state" request
1227 parameters as appropriate
1229 The authorization server can then use any conforming OpenID Connect
1230 mechanisms and typical user interfaces for engaging with the UserInfo
1231 endpoints of OpenID Providers and Claims Providers, potentially
1232 allowing for the delivery of "trusted claims" (such as a verified
1233 email address or a date or birth) on which authorization policy for
1234 access may depend.
1236 4. Error Messages
1237 Ultimately the resource server is responsible for either granting the
1238 access the client attempted, or returning an error response to the
1239 client with a reason for the failure. [OAuth2] defines several error
1240 responses for a resource server to return. UMA makes use of these
1241 error responses, but requires the resource server to "outsource" the
1242 determination of some error conditions to the authorization server.
1243 This specification defines additional UMA-specific error responses
1244 that the authorization server may give to the resource server and
1245 client as they interact with it, and that the resource server may
1246 give to the client.
1248 4.1. OAuth Error Responses
1250 When a resource server or client attempts to access one of the
1251 authorization server endpoints or a client attempts to access a
1252 protected resource at the resource server, it has to make an
1253 authenticated request by including an OAuth access token in the HTTP
1254 request as described in [OAuth2] Section 7.2.
1256 If the request failed authentication, the authorization server or the
1257 resource server responds with an OAuth error message as described
1258 throughout Section 2 and Section 3.
1260 4.2. UMA Error Responses
1262 When a resource server or client attempts to access one of the
1263 authorization server endpoints or a client attempts to access a
1264 protected resource at the resource server, if the request is
1265 successfully authenticated by OAuth means, but is invalid for another
1266 reason, the authorization server or resource server responds with an
1267 UMA error response by adding the following properties to the entity
1268 body of the HTTP response:
1270 error REQUIRED. A single error code. Values for this property are
1271 defined throughout this specification.
1273 error_description OPTIONAL. Human-readable text providing
1274 additional information.
1276 error_uri OPTIONAL. A URI identifying a human-readable web page
1277 with information about the error.
1279 The following is a common error code that applies to several UMA-
1280 specified request messages:
1282 invalid_request The request is missing a required parameter,
1283 includes an invalid parameter value, includes a parameter more
1284 than once, or is otherwise malformed. The authorization server
1285 MUST respond with the HTTP 400 (Bad Request) status code.
1287 For example:
1289 HTTP/1.1 400 Bad Request
1290 Content-Type: application/json
1291 Cache-Control: no-store
1292 ...
1294 {
1295 "status": "error",
1296 "error": "invalid_request",
1297 "error_description": "There is already a resource with this identifier.",
1298 "error_uri": "http://as.example.com/errors/resource_exists"
1299 }
1301 5. Specificying Additional Profiles
1303 This specification defines a protocol that has optional features.
1304 For interoperability and to serve particular deployment scenarios,
1305 including sector-specific ones such as healthcare or e-government,
1306 third parties may want to define profiles of UMA that restrict these
1307 options.
1309 Further, this specification creates extensibility points for RPT
1310 profiles and claim profiles, and third parties may likewise want to
1311 define their own. Different RPT profile could be used, for example,
1312 to change the dividing line between authorization server and resource
1313 server responsibilities in controlling access. Different claim
1314 profiles could be used to customize sector-specific or population-
1315 specific (individual vs. employee) claim types that drive the types
1316 of policies resource owners could set.
1318 It is not practical for this specification to standardize all desired
1319 profiles. However, to serve overall interoperability goals, the
1320 following sections provide guidelines for third parties that wish to
1321 specify UMA-related profiles.
1323 5.1. Specifying Profiles of UMA
1325 It is RECOMMENDED that profiles of UMA document the following
1326 information:
1328 1. Specify a URI that uniquely identifies the profile.
1330 2. Identify the responsible author and provide postal or electronic
1331 contact information.
1333 3. Supply references to previously defined profiles that the profile
1334 updates or obsoletes.
1336 4. Specify the set of interactions between endpoint entites involved
1337 in the profile, calling out any restrictions on ordinary UMA-
1338 conformant operations and any extension properties used in
1339 message formats.
1341 5. Identify the legally responsible parties involved in each
1342 interaction and any new obligations imposed, in the fashion of
1343 [UMA-obligations].
1345 6. Define any additional or changed error states.
1347 7. Supply any additional security and privacy considerations,
1348 including analysis of threats and description of countermeasures.
1350 5.2. Specifying RPT Profiles
1352 It is RECOMMENDED that RPT profiles document the following
1353 information:
1355 1. Specify a URI that uniquely identifies the token profile.
1357 2. Identify the responsible author and provide postal or electronic
1358 contact information.
1360 3. Supply references to previously defined token profiles that the
1361 token profile updates or obsoletes.
1363 4. Specify the keyword to be used in HTTP Authorization headers
1364 with tokens conforming to this profile.
1366 5. Specify the syntax and semantics of the data that the
1367 authorization server associates with the token.
1369 6. Specify how the token data is associated with, contained within,
1370 and/or retrieved by means of, the on-the-wire token string.
1372 7. Specify processing rules for token data.
1374 8. Identify any restrictions on grant types to be used with the
1375 token profile.
1377 9. Define any additional or changed error states.
1379 10. Supply any additional security and privacy considerations.
1381 11. Specify any obligations specific to the token profile, in the
1382 fashion of [UMA-obligations].
1384 See Section 3.3.2 for an example.
1386 5.3. Specifying Claim Profiles
1388 It is RECOMMENDED that claim profiles document the following
1389 information:
1391 1. Specify a URI that uniquely identifies the claim profile.
1393 2. Identify the responsible author and provide postal or electronic
1394 contact information.
1396 3. Supply references to previously defined claim profiles that the
1397 claim profile updates or obsoletes.
1399 4. Specify the syntax and semantics of claim data and requests for
1400 claim data.
1402 5. Specify how an authorization server gathers the claims.
1404 6. Define any additional or changed error states.
1406 7. Supply any additional security and privacy considerations.
1408 8. Specify any obligations specific to the claim profile, in the
1409 fashion of [UMA-obligations].
1411 See Section 3.5.1.1 for an example.
1413 6. Security Considerations
1415 This specification relies mainly on OAuth security mechanisms as well
1416 as transport-level encryption for protecting the protection and
1417 authorization API endpoints. Most PATs and AATs are likely to use
1418 OAuth bearer tokens. See [OAuth-threat] for more information.
1420 This specification defines a number of JSON-based data formats. As a
1421 subset of the JavaScript scripting language, JSON data SHOULD be
1422 consumed through a process that does not dynamically execute it as
1423 code, to avoid malicious code execution. One way to achieve this is
1424 to use a JavaScript interpreter rather than the built-in JavaScript
1425 eval() function.
1427 The issue of impersonation is a crucial aspect in UMA, particularly
1428 when entities are wielding bearer tokens that preclude proof-of-
1429 possession (of a secret or a cryptographic key). As such, one way to
1430 mitigate this risk is for the resource owner to require stronger
1431 claims to accompany any access request. For example, consider the
1432 case where Alice sets policies at the authorization server governing
1433 access to her resources by Bob. When Bob first seeks access and must
1434 obtain an RPT (for which the default RPT profile specifies a bearer
1435 token), Alice could set policies demanding that Bob prove his
1436 identity by providing a set of strong claims issued by a trusted
1437 attrribute provider in order to get authorization data associated
1438 with that token.
1440 Another issue concerns the use of the [OAuth2] implicit flow. In
1441 this case, Bob will have exposure to the token, and may maliciously
1442 pass the token to an unauthorized party. To mitigate this weakness
1443 and others, we recommend considering the following steps:
1445 o Require that the Requesting Party (as defined in
1446 [UMA-obligations]) legitimately represent the wielder of the
1447 bearer token. This solution is based on a legal or contractual
1448 approach, and therefore does not reduce the risk from the
1449 technical perspective.
1451 o The authorization server, possibly with input from the resource
1452 owner, can implement tighter time-to-live (TTL) strategies around
1453 the authorization data in RPTs. This is a classic approach with
1454 bearer tokens that helps to limit a malicious party's ability to
1455 intercept and use the bearer token. In the same vein, the
1456 authorization server could require claims to have a reasonable
1457 degree of freshness (which would require a custom claims profile).
1459 o The strongest strategy is to disallow bearer-type RPTs within the
1460 UMA profile being deployed, by providing or requiring an RPT
1461 profile that requires use of a holder-of-key (HOK) approach. In
1462 this way, the wielder of the token must engage in a live session
1463 for proof-of-possession.
1465 For information about the additional technical, operational, and
1466 legal elements of trust establishment between UMA entities and
1467 parties, which affects security considerations, see
1468 [UMA-obligations].
1470 7. Privacy Considerations
1472 The authorization server comes to be in possession of resource set
1473 information (such as names and icons) that may reveal information
1474 about the resource owner, which the authorization server's trust
1475 relationship with the resource server is assumed to accommodate.
1476 However, the client is a less-trusted party -- in fact, entirely
1477 untrustworthy until authorization data is associated with its RPT.
1478 This specification depends on [OAuth-resource-reg], which recommends
1479 obscuring resource set identifiers in order to avoid leaking
1480 personally identifiable information to clients through the scope
1481 mechanism.
1483 (More privacy considerations information to come.)
1485 For information about the technical, operational, and legal elements
1486 of trust establishment between UMA entities and parties, which
1487 affects privacy considerations, see [UMA-obligations].
1489 8. Conformance
1491 This section outlines conformance requirements for various entities
1492 implementing UMA endpoints.
1494 This specification has dependencies on other specifications, as
1495 referenced under the normative references listed in this
1496 specification. Its dependencies on some specifications, such as
1497 OpenID Connect ([OCStandard] and [OCMessages]), are optional
1498 depending on whether the feature in question is used in the
1499 implementation.
1501 The authorization server's configuration data provides a machine-
1502 readable method for it to indicate certain of the conformance options
1503 it has chosen or supports. Several of the configuration data
1504 properties allow for indicating extension features. Where this
1505 specification does not already require optional features to be
1506 documented, it is RECOMMENDED that authorization server developers
1507 and deployers document any profiled or extended features explicitly
1508 and use configuration data to indicate their usage. See Section 1.4
1509 for information about providing and extending the configuration data.
1511 9. IANA Considerations
1513 This document makes no request of IANA.
1515 10. Acknowledgments
1516 The current editor of this specification is Thomas Hardjono of MIT.
1517 The following people are co-authors:
1519 o Paul C. Bryan, ForgeRock US, Inc. (former editor)
1521 o Domenico Catalano, Oracle Corp.
1523 o George Fletcher, AOL
1525 o Maciej Machulak, Newcastle University
1527 o Eve Maler, XMLgrrl.com
1529 o Lukasz Moren, Newcastle University
1531 o Christian Scholz, COMlounge GmbH (former editor)
1533 o Jacek Szpot, Newcastle University
1535 Additional contributors to this specification include the Kantara UMA
1536 Work Group participants, a list of whom can be found at
1537 [UMAnitarians].
1539 11. Issues
1541 All issues are now captured at the project's GitHub site ([1]).
1543 12. References
1545 12.1. Normative References
1547 [DynClientReg]
1548 Richer, J., "OAuth Dynamic Client Registration Protocol",
1549 March 2013, .
1552 [OAuth-SAML]
1553 Campbell, B., "SAML 2.0 Bearer Assertion Profiles for
1554 OAuth 2.0", March 2013, .
1557 [OAuth-bearer]
1558 , "The OAuth 2.0 Authorization Framework: Bearer Token
1559 Usage", October 2012,
1560 .
1562 [OAuth-introspection]
1563 Richer, J., "OAuth Token Introspection", February 2013,
1564 .
1567 [OAuth-resource-reg]
1568 Hardjono, T., "OAuth 2.0 Resource Set Registration",
1569 December 2012, .
1572 [OAuth-threat]
1573 Lodderstedt, T., "OAuth 2.0 Threat Model and Security
1574 Considerations", January 2013,
1575 .
1577 [OAuth2] Hardt, D., "The OAuth 2.0 Authorization Framework",
1578 October 2012, .
1580 [OCMessages]
1581 Sakimura, N., "OpenID Connect Messages 1.0", March 2013,
1582 .
1585 [OCStandard]
1586 Sakimura, N., "OpenID Connect Standard 1.0", March 2013,
1587 .
1590 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1591 Requirement Levels", BCP 14, RFC 2119, March 1997.
1593 [RFC4627] Crockford, D., "The application/json Media Type for
1594 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
1596 [UMA-obligations]
1597 Maler, E., "Binding Obligations on UMA Participants",
1598 January 2013, .
1601 [hostmeta]
1602 Hammer-Lahav, E., "Web Host Metadata", October 2011,
1603 .
1605 12.2. Informative References
1607 [OAuth-linktypes]
1608 Mills, W., "Link Type Registrations for OAuth 2", February
1609 2013,
1610 .
1612 [OAuth-meta]
1613 Sakimura, N., "JSON Metadata for OAuth Responses",
1614 February 2013,
1615 .
1617 [UMA-casestudies]
1618 Maler, E., "UMA Case Studies", March 2013, .
1622 [UMA-usecases]
1623 Maler, E., "UMA Scenarios and Use Cases", October 2010,
1624 .
1627 [UMAnitarians]
1628 Maler, E., "UMA Participant Roster", April 2013, .
1632 Appendix A. Document History
1634 NOTE: To be removed by RFC editor before publication as an RFC.
1636 See [2] for a list of code-breaking and other major changes made to
1637 this specification at various revision points.
1639 Author's Address
1641 Thomas Hardjono (editor)
1642 MIT
1644 Email: hardjono@mit.edu