idnits 2.17.1
draft-hardjono-oauth-umacore-01.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 7 instances of too long lines in the document, the longest one
being 24 characters in excess of 72.
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 (October 16, 2011) is 4577 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)
-- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth-SAML'
== Outdated reference: A later version (-23) exists of
draft-ietf-oauth-v2-bearer-06
-- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth2'
-- Possible downref: Non-RFC (?) normative reference: ref. 'OCDynClientReg'
-- 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)
Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 6 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 October 16, 2011
5 Expires: April 18, 2012
7 User-Managed Access (UMA) Core Protocol
8 draft-hardjono-oauth-umacore-01
10 Abstract
12 This specification defines the User-Managed Access (UMA) core
13 protocol. This protocol provides a method for users to control
14 access to their protected resources, residing on any number of host
15 sites, through an authorization manager that governs access decisions
16 based on user 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 April 18, 2012.
35 Copyright Notice
37 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4
53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 6
54 1.2. Basic Terminology . . . . . . . . . . . . . . . . . . . . 6
55 1.3. Endpoints, Endpoint Protection, and Tokens . . . . . . . . 8
56 1.4. Scopes, Resource Sets, Permissions, and Authorization . . 10
57 1.5. AM Metadata . . . . . . . . . . . . . . . . . . . . . . . 10
58 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 13
59 2.1. Host Looks Up AM Metadata . . . . . . . . . . . . . . . . 13
60 2.2. Host Registers with AM . . . . . . . . . . . . . . . . . . 14
61 2.3. Host Obtains Host Access Token . . . . . . . . . . . . . . 14
62 2.4. Host Registers Sets of Resources to Be Protected . . . . . 14
63 2.4.1. Scope Descriptions . . . . . . . . . . . . . . . . . . 15
64 2.4.2. Resource Set Descriptions . . . . . . . . . . . . . . 16
65 2.4.3. Resource Set Registration API . . . . . . . . . . . . 17
66 3. Getting Authorization and Accessing a Resource . . . . . . . . 24
67 3.1. Requester-Host: Attempt Access at Protected Resource . . . 26
68 3.1.1. Requester's Request Is Ambiguous . . . . . . . . . . . 26
69 3.1.2. Requester Presents No Access Token . . . . . . . . . . 27
70 3.1.3. Requester Presents an Invalid Access Token . . . . . . 27
71 3.1.4. Requester's Token Has Insufficient Permission . . . . 28
72 3.1.5. Requester's Token Has Sufficient Permission . . . . . 28
73 3.2. Requester-AM: Requester Obtains Access Token . . . . . . . 29
74 3.3. Host-AM: Ask for Requester's Presented Access Token
75 Status . . . . . . . . . . . . . . . . . . . . . . . . . . 29
76 3.3.1. AM Returns a Token Status Description . . . . . . . . 30
77 3.3.2. AM Returns a Token Invalid Response . . . . . . . . . 31
78 3.4. Host-AM: Register a Permission . . . . . . . . . . . . . . 32
79 3.4.1. AM Returns a Permission Registration Success
80 Response . . . . . . . . . . . . . . . . . . . . . . . 33
81 3.4.2. AM Returns a Permission Registration Error Response . 33
82 3.5. Requester-AM: Request Authorization to Add Permission . . 34
83 3.5.1. AM Returns an Add Permission Success Response . . . . 35
84 3.5.2. AM Returns an Add Permission Error Response . . . . . 35
85 3.6. AM-Requester Authorization Flows . . . . . . . . . . . . . 36
86 3.6.1. Authorization Flow for Requester Apps Operated by
87 End-Users . . . . . . . . . . . . . . . . . . . . . . 37
88 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 38
89 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 38
90 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 38
91 5. Security Considerations . . . . . . . . . . . . . . . . . . . 39
92 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 40
93 7. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 40
94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41
95 9. AM Metadata Example . . . . . . . . . . . . . . . . . . . . . 41
96 10. Example of Registering Resource Sets . . . . . . . . . . . . . 43
97 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
98 12. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
99 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46
100 13.1. Normative References . . . . . . . . . . . . . . . . . . . 46
101 13.2. Informative References . . . . . . . . . . . . . . . . . . 47
102 Appendix A. Document History . . . . . . . . . . . . . . . . . . 48
103 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 48
105 1. Introduction
107 The User-Managed Access (UMA) core protocol provides a method based
108 on [OAuth2] (currently draft 16) for users to control access to their
109 protected resources, residing on any number of host sites, through a
110 single authorization manager (AM) that governs access decisions based
111 on user policy.
113 There are numerous use cases for UMA, where a resource owner
114 nominates a third party to control access to these resources
115 potentially without the real-time presence of the resource owner. A
116 typical example is the following. A web user (authorizing user) can
117 authorize a web app (requester) to gain one-time or ongoing access to
118 a resource containing his home address stored at a "personal data
119 store" service (host), by telling the host to act on access decisions
120 made by his authorization decision-making service (authorization
121 manager or AM). The requesting party might be an e-commerce company
122 whose site is acting on behalf of the user himself to assist him/her
123 in arranging for shipping a purchased item, or it might be his friend
124 who is using an online address book service to collect addresses, or
125 it might be a survey company that uses an online service to compile
126 population demographics. Other scenarios and use cases for UMA usage
127 can be found in [UMA-usecases] and [UMA-userstories].
129 In enterprise settings, application access management often involves
130 letting back-office applications serve only as policy enforcement
131 points (PEPs), depending entirely on access decisions coming from a
132 central policy decision point (PDP) to govern the access they give to
133 requesters. This separation eases auditing and allows policy
134 administration to scale in several dimensions. UMA makes use of a
135 separation similar to this, letting the authorizing user serve as a
136 policy administrator crafting authorization strategies on his or her
137 own behalf.
139 The UMA protocol profiles, extends, and embeds [OAuth2] in various
140 ways. An AM can be thought of as an enhanced OAuth authorization
141 server; a host as an enhanced resource server; and a requester as an
142 enhanced client, acquiring an access token and the requisite
143 authorization to access a protected resource at the host.
145 The UMA protocol has three broad phases, as shown in Figure 1.
147 The Three Phases of the UMA Protocol
148 +-----+----------------+
149 | UA | authorizing |
150 +-------Manage (A)--| | user |
151 | +-----+----------------+
152 | Phase 1: | UA |
153 | protect a +----------------+
154 | resource |
155 | Control (B)
156 | |
157 v v
158 +-----------+ +-----+----------------+
159 | host |<-Protect-(C)-|prot | authorization |
160 | | | API | manager (AM) |
161 +-----------+ +-----+----------------+
162 | protected | | authorization |
163 | resource | | API |
164 +-----------+ +----------------+
165 ^ |
166 | Phases 2 and 3: Authorize (D)
167 | get authz and |
168 | access a resource v
169 | +----------------+
170 +-------Access (E)--------| requester |
171 +----------------+
172 (requesting party)
174 Figure 1
176 In broad strokes, the phases are as follows:
178 1. Protect a resource (described in Section 2).
180 2. Get authorization (described in Section 3).
182 3. Access a resource (described along with Phase 2 in Section 3).
184 In more detail, the phases work as follows:
186 1. _Protect a resource:_ The authorizing user has chosen to use a
187 host for managing online resources ("A"), and introduces this
188 host to an AM using an OAuth-mediated interaction that results in
189 the AM giving the host an access token. The host uses AM's
190 protection API to tell the AM what sets of resources to protect
191 ("C"). Out of band of the UMA protocol, the authorizing user
192 instructs the AM what policies to attach to the registered
193 resource sets ("B"). Requesters are not yet in the picture.
195 2. _Get authorization:_ This phase involves the requester, host, and
196 AM. It may also involve synchronous action by the authorizing
197 user if this person is the same person as the requesting party.
198 This phase is dominated by a loop of activity in which the
199 requester approaches the host seeking access to a protected
200 resource ("E"), is sent to obtain an access token from the AM if
201 it does not have one, and then must demonstrate to the AM that it
202 satisfies the user's authorization policy governing the sought-
203 for resource and scope of access if it does not already have the
204 required access permission ("D").
206 3. _Access a resource:_ This phase involves the requester
207 successfully presenting an access token that has sufficient
208 permission associated with it to the host in order to gain access
209 to the desired resource ("E"). In this sense, it is the "happy
210 path" within phase 2.
212 1.1. Notational Conventions
214 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
215 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
216 document are to be interpreted as described in [RFC2119].
218 Unless otherwise noted, all the protocol parameter names and values
219 are case sensitive.
221 The assignment in this document of URI labels is temporary, awaiting
222 final standardization in the eventual standards body within which
223 this specification is taken up as a work item.
225 1.2. Basic Terminology
227 UMA introduces the following terms, utilizing OAuth and other
228 identity and access management concepts.
230 authorizing user
231 An UMA-defined variant of an OAuth end-user resource owner; a
232 web user who configures an authorization manager with policies
233 that control how it assigns access permissions to requesters
234 for a protected resource.
236 authorization manager (AM)
237 An UMA-defined variant of an OAuth authorization server that
238 carries out an authorizing user's policies governing access to
239 a protected resource.
241 protected resource
242 An access-restricted resource at a host, which is being policy-
243 protected by an AM.
245 host
246 An UMA-defined variant of an OAuth resource server that
247 enforces access to the protected resources it hosts, as
248 governed by an authorization manager.
250 host access token
251 An access token representing the authorizing user's consent for
252 a host to trust a particular authorization manager for control
253 over authorizations to access protected resources hosted there.
255 claim
256 A statement of the value or values of one or more identity
257 attributes of a requesting party. A requesting party may need
258 to provide claims to an authorization manager in order to
259 satisfy policy and gain permission for access to a protected
260 resource.
262 requester
263 An UMA-defined variant of an OAuth client that seeks access to
264 a protected resource.
266 requester access token
267 An access token that can be associated with permissions to
268 access particular resources at a host on behalf of a particular
269 requesting party.
271 requesting party
272 A web user, or a corporation or other legal person, that uses a
273 requester to seek access to a protected resource. If the
274 requesting party is a natural person, it may or may not be the
275 same person as the authorizing user.
277 resource set description
278 A JSON-formatted document that represents a set of one or more
279 resources to be AM-protected and maps available scopes to them.
280 The host registers a resource set by providing this document to
281 the AM.
283 scope description A JSON-formatted document that represents a
284 bounded scope (extent) of access on a particular resource set.
285 The host refers to this type of document from within its
286 registered resource set descriptions and permissions.
288 token status description A JSON-formatted document that represents
289 the currently valid permissions for access associated with a
290 requester access token.
292 permission A scope of access over a particular resource set at a
293 particular host that is being asked for by a requester (a
294 requested permission) or that has been granted by an AM (a
295 granted permission).
297 1.3. Endpoints, Endpoint Protection, and Tokens
299 As indicated in Section 1, various UMA entities present APIs for
300 other UMA entities to use. These APIs are as follows:
302 o The AM presents a _protection API_ to the host, as standardized by
303 this specification. This API is OAuth-protected, requiring a host
304 access token (issued by the AM) for successful access (see
305 Section 2.3 for this issuance process).
307 o The AM presents an _authorization API_ to the requester, as
308 standardized by this specification. This API is OAuth-protected,
309 requiring a requester access token (issued by the AM) for
310 successful access (see Section 3.2 for this issuance process).
312 o The host presents a _protected resource_ to the requester, which
313 can be considered -- and may in fact be -- an application-specific
314 or proprietary API. This API is UMA-protected, requiring a
315 requester access token (issued by the AM) and sufficient
316 permissions (also issued by the AM) for successful access (see
317 Section 3.5 for this latter issuance process).
319 The AM presents the following endpoints to the host as part of its
320 protection API:
322 host access token endpoint Part of standard OAuth, as profiled by
323 UMA. The endpoint at which the host asks for a host access
324 token on the authorizing user's behalf. (The AM may also
325 choose to issue a refresh token.) It will use this token to
326 gain access to the other protection API endpoints.
328 host user authorization endpoint Part of standard OAuth, as profiled
329 by UMA. The endpoint to which the host redirects the
330 authorizing user to authorize the host to use this AM for
331 protecting resources, if the OAuth authorization code grant
332 type is being used.
334 resource set registration endpoint The endpoint at which the host
335 registers resource sets it wants the AM to protect.
337 permission registration endpoint The endpoint at which the host
338 registers permissions that it anticipates a requester will
339 shortly be asking for from the AM.
341 token status endpoint The endpoint at which the host submits
342 requester access tokens that have accompanied an access
343 request, to learn what currently valid permissions are
344 associated with them.
346 The AM presents the following endpoints to the requester as part of
347 its authorization API:
349 requester access token endpoint Part of standard OAuth, as profiled
350 by UMA. The endpoint at which the requester asks for a
351 requester access token. (The AM may also choose to issue a
352 refresh token.) It will use this token to gain access to the
353 other authorization API endpoint.
355 permission endpoint The endpoint at which the requester asks for
356 authorization to have a new permission associated with its
357 requester access token.
359 Finally, the host presents one or more protected resource endpoints
360 to the requester:
362 protected resource endpoint An endpoint at which a requester
363 attempts to access resources. This can be a singular API
364 endpoint, one of a set of API endpoints, a URI corresponding to
365 an HTML document, or any other URI. The requester needs to
366 present a requester access token associated with sufficient
367 permissions in order to gain access.
369 Similarly to OAuth authorization servers, an UMA AM has the
370 opportunity to manage the validity periods of the access tokens, the
371 corresponding refresh tokens, and even the client credentials that it
372 issues. Different lifetime strategies may be suitable for different
373 resources and scopes of access, and the AM has the opportunity to
374 give the authorizing user control through policy.
376 Access tokens are currently assumed to be merely opaque strings (as
377 discussed in Section 1.5 and Section 7). Thus, when an AM associates
378 a permission with a requester access token, a host cannot
379 subsequently inspect such a token locally to assess whether a needed
380 permission has been granted. It must instead ask the AM to provide
381 the token's status.
383 1.4. Scopes, Resource Sets, Permissions, and Authorization
385 UMA extends the OAuth concept of a "scope" by defining scopes as
386 applying to particular labeled resource sets, rather than leaving the
387 relevant resources (such as API endpoints or URIs) implicit. A
388 resource set can have any number of scopes, which together describe
389 the universe of actions that _can be_ taken on this protected
390 resource set. For example, a resource set representing a status
391 update API might have scopes that include adding an update or reading
392 updates. A resource set representing a photo album might have scopes
393 that include viewing a slideshow or printing the album. Hosts
394 register resource sets and their scopes without there being a
395 requester in the picture.
397 Resource sets and scopes have meaning only to hosts and their users,
398 in the same way that application-specific host APIs have meaning only
399 to these entities. The AM is merely a conveyor of labels and
400 descriptions for these constructs, to help the authorizing user set
401 policies that guide eventual authorization processes.
403 In contrast to an UMA scope, an UMA permission reflects an _actual_
404 authorization process for a requester to access a particular resource
405 set in a scoped (bounded) manner. Hosts register permission requests
406 on behalf of requesters that have attempted access. Requesters
407 subsequently ask AMs for permissions to be associated with their
408 tokens. AMs grant (or deny) permissions to requesters.
410 In order to represent meaningful, auditable, and potentially legally
411 enforceable authorization (see [UMA-trustmodel]), a permission is
412 bound to a particular set of UMA entities and parties. This includes
413 the requesting party, the requester (so that the same requesting
414 party would have to go through the authorization process for each
415 client application they use), the host, the resource set on which
416 access is being attempted, and therefore also the AM protecting it
417 and the authorizing user who is controlling access.
419 Unlike scopes (but similarly to tokens themselves; see Section 1.3),
420 permissions have a validity period.
422 1.5. AM Metadata
424 The AM MUST provide an XRD 1.0-formatted document at the hostmeta
425 location (see hostmeta [hostmeta]), documenting the following:
427 o Major conformance options supported by the AM (described further
428 in Section 7)
430 o Protection and authorization API endpoints (as described in
431 Section 1.3)
433 See Section 9 for a full example of AM metadata.
435 XRD property type values for conformance options:
437 http://docs.kantarainitiative.org/uma/1.0/client_reg
438 OPTIONAL (zero or one). Whether dynamic client registration,
439 such as through [OCDynClientReg], is supported for both hosts
440 and requesters. The only options currently available are "yes"
441 (dynamic registration is supported, using an unspecified
442 method) and "no" (it is not supported; hosts and requesters are
443 required to pre-register). The default is currently AM-
444 specific. (This conformance option is largely a placeholder
445 for now.)
447 http://docs.kantarainitiative.org/uma/1.0/token_formats
448 REQUIRED (one or more). Access token format produced by this
449 AM. Currently the only option defined by this specification is
450 "artifact", meaning an opaque token string as supported
451 natively by the UMA protocol, and the AM is REQUIRED to support
452 this option (and supply this value). The AM MAY provide
453 support for additional access token formats, indicated by
454 extension values that MUST begin with "X-" or "x-".
456 http://docs.kantarainitiative.org/uma/1.0/claim_formats
457 OPTIONAL (zero or more). Claim formats and associated claims-
458 gathering sub-protocols supported by this AM. Currently the
459 only option defined by this specification is "openid", for
460 which details are supplied in Section 3.6.1.1. The AM MAY
461 provide support for additional claim formats, indicated by
462 extension values that MUST begin with "X-" or "x-". If the AM
463 is capable of requesting and accepting any claim formats at
464 all, it MUST declare them.
466 XRD link relationship rel values for protection API endpoints:
468 http://docs.kantarainitiative.org/uma/1.0/host_token_uri
469 REQUIRED. The host access token endpoint. Available HTTP
470 methods are as defined by [OAuth2] for a token endpoint.
471 Supplies the endpoint the host uses to ask for a host access
472 token.
474 http://docs.kantarainitiative.org/uma/1.0/host_user_uri
475 REQUIRED. The host user authorization endpoint. AAvailable
476 HTTP methods are as defined by [OAuth2] for an end-user
477 authorization endpoint. Supplies the endpoint the host uses to
478 gather the consent of the authorizing user for a host-AM
479 relationship if it is using the authorization code grant type.
480 The AM MUST support the authorization code grant type method of
481 obtaining the authorizing user's consent.
483 http://docs.kantarainitiative.org/uma/1.0/host_resource_reg_uri
484 REQUIRED. The resource set registration endpoint. Requests to
485 this endpoint require a host access token to be present.
486 Supplies the endpoint the host uses for registering resource
487 sets with the AM to be protected (see Section 2.4.3). This
488 endpoint SHOULD require the use of a transport-layer security
489 mechanism such as TLS.
491 http://docs.kantarainitiative.org/uma/1.0/host_token_status_uri
492 REQUIRED. The token status endpoint. Requests to this
493 endpoint require a host access token to be present. Supplies
494 the endpoint the host uses to request the status of access
495 tokens presented to them by requesters with respect to
496 currently valid permissions. This endpoint SHOULD require the
497 use of a transport-layer security mechanism such as TLS.
499 http://docs.kantarainitiative.org/uma/1.0/host_perm_reg_uri
500 REQUIRED. The permission registration endpoint. Requests to
501 this endpoint require a host access token to be present.
502 Supplies the endpoint the host uses for registering permissions
503 with the AM for which a requester will be seeking authorization
504 (see Section 3.4). This endpoint SHOULD require the use of a
505 transport-layer security mechanism such as TLS.
507 XRD link relationship rel values for authorization API endpoints:
509 http://docs.kantarainitiative.org/uma/1.0/req_token_uri
510 REQUIRED. The requester access token endpoint. Available HTTP
511 methods are as defined by [OAuth2] for a token issuance
512 endpoint. Supplies the endpoint the requester uses to ask for
513 an access token. This endpoint SHOULD require the use of a
514 transport-layer security mechanism such as TLS.
516 http://docs.kantarainitiative.org/uma/1.0/req_perm_uri
517 REQUIRED. The permission endpoint. Supplies the endpoint the
518 requester uses to ask for authorization to have a new
519 permission associated with its existing requester access token,
520 which MUST accompany the request. This endpoint SHOULD require
521 the use of a transport-layer security mechanism such as TLS.
523 2. Protecting a Resource
525 Phase 1 of UMA is protecting a resource. For a host to be able to
526 delegate authorization of protected-resource access to an AM, the
527 authorizing user must first introduce the host to the AM. This phase
528 is concluded successfuly when:
530 o The host has received metadata about the AM, such as endpoints it
531 needs to use in interacting with the AM.
533 o The host has received an OAuth host access token that represents
534 the authorizing user's approval for the host to work with the AM
535 in protecting resources. This host access token is later used
536 when the host makes other requests at the AM's protection API.
538 o The AM has acquired information about resource sets on the host it
539 is supposed to protect on behalf of the authorizing user.
541 The user, host, and AM perform the following steps in order to
542 successfully complete Phase 1:
544 1. The host looks up the AM's metadata and learns about its
545 protection API endpoints and supported formats.
547 2. If the host has not yet obtained a unique OAuth client identifier
548 and optional secret from the AM, it registers with the AM as
549 required. It MAY do this using [OCDynClientReg], if the AM
550 supports it.
552 3. The host obtains a host access token from the AM with the
553 authorizing user's consent, using either the authorization code
554 grant type or the SAML bearer assertion grant type.
556 4. The host registers any resource sets with the AM that are
557 intended to be protected.
559 2.1. Host Looks Up AM Metadata
561 The host needs to learn the AM's protection API endpoints before they
562 can begin interacting. The authorizing user might provide the AM's
563 location to get the host started in this process, for example by
564 typing a URL into a web form field or clicking a button.
565 Alternatively, the host might already be configured to work with a
566 single AM without requiring any user input. The exact process is
567 beyond the scope of this specification, and it is up to the host to
568 choose a method to learn the AM's location.
570 From the data provided, discovered, or configured, the host MUST use
571 the process described in Section 2 of hostmeta [hostmeta] to retrieve
572 the AM hostmeta document. For example, if the user supplied
573 "am.example.com" as the Authorization Manager's domain, the host
574 creates the URL "https://am.example.com/.well-known/host-meta" and
575 performs a GET request on it. The AM MUST return content that
576 includes UMA protection API endpoints as defined in Section 1.5 (see
577 Section 9 for an example).
579 2.2. Host Registers with AM
581 If the host has not already obtained a unique client identifier and
582 optional secret from this AM, in this step it MUST do so in order to
583 engage in OAuth-based interactions with the AM. It MAY do this using
584 [OCDynClientReg], if the AM supports it (see Section 1.5 for how the
585 AM MAY indicate support). The AM MUST issue a unique client
586 identifier to every host. This is to ensure that individual hosts
587 can be unambiguously identified in resource set registration, where
588 the client identifier is used as a URI component.
590 2.3. Host Obtains Host Access Token
592 In this step, the host acquires a host access token from the AM that
593 represents the approval of the authorizing user for the host to trust
594 the AM for protecting resources belonging to the user.
596 The host MUST use the OAuth2 [OAuth2] authorization code grant type
597 or the SAML bearer token grant type [OAuth-SAML], utilizing the end-
598 user authorization and token endpoints as appropriate. Here the host
599 acts in the role of an OAuth client; the authorizing user acts in the
600 role of an OAuth end-user resource owner; and the AM acts in the role
601 of an OAuth authorization server. (Once the host has obtained an
602 access token, it presents it to the AM at various protection API
603 endpoints, at which point the AM acts in the role of a resource
604 server.)
606 The host has completed this step successfully when it possesses a
607 host access token it can use at the AM's protection API.
609 2.4. Host Registers Sets of Resources to Be Protected
611 Once the host has received a host access token, for any of the user's
612 sets of resources that are to be protected by this AM, it MUST
613 register these resource sets at the AM's registration endpoint.
615 Note that the host is free to offer the option to protect any subset
616 of the user's resources using different AMs or other means entirely,
617 or to protect some resources and not others. Additionally, the
618 choice of protection regimes can be made explicitly by the user or
619 implicitly by the host. Any such partitioning by the host or user is
620 outside the scope of this specification.
622 See Section 10 for an extended example of registering resource sets.
624 2.4.1. Scope Descriptions
626 The host defines a scope of access that is available for use with
627 resources it manages in a document accessible to the AM that contains
628 a scope description. The scopes available for use at any one host
629 MUST have unique URI references so that the host's scope descriptions
630 are distinguishable by URI reference; the URI reference MAY include a
631 fragment identifier. Scope descriptions MAY reside anywhere; the
632 host is not required to self-host scope descriptions and may wish to
633 point to standardized scope descriptions residing elsewhere. (See
634 Section 1.4 for further discussion of scope-related concepts, and
635 Section 10 for a long-form example of scopes used in resource set
636 registration.)
638 A scope description is a JSON [RFC4627] object with the name "scope"
639 and with the following parameters:
641 _id REQUIRED. A string that uniquely identifies the scope across
642 all scopes available at this host.
644 name REQUIRED. A human-readable string describing the scope of
645 access. The AM SHOULD use the name in its user interface to
646 assist the user in setting policies for protected resource sets
647 that have this available scope.
649 icon_uri OPTIONAL. A URI for a graphic icon representing the scope.
650 If this is provided, the AM SHOULD use the referenced icon in its
651 user interface to assist the user in setting policies for
652 protected resource sets that have this available scope.
654 For example, this description characterizes a scope that involves
655 reading or viewing resources (vs. creating them or editing them in
656 some fashion):
657 {
658 "scope":
659 {
660 "_id": "view"
661 "name": "Read-only",
662 "icon_uri": "http://www.example.com/icons/reading-glasses"
663 }
664 }
666 Scope descriptions MAY contain extension parameters that are not
667 defined in this specification. The names of extension parameters
668 MUST begin with "x-" or "X-".
670 2.4.2. Resource Set Descriptions
672 The host defines a resource set that needs protection by registering
673 a resource set description at the AM. The host registers the
674 description and manages its lifecycle at the AM's host resource set
675 registration endpoint by using the resource set registration API, as
676 defined in Section 2.4.3.
678 The resource set description is a JSON [RFC4627] object with the name
679 "resource_set" and with the following parameters:
681 _id REQUIRED. A string that uniquely identifies the resource set.
682 The resource set identifier has meaning only to the host. The AM
683 merely maps this resource set description to a particular user by
684 reference to the host access token that was used to access the
685 resource set registration API. The host MAY use any identifier
686 scheme to represent resource sets, for example, making its
687 identifiers unique across all users of this host or allowing for
688 the sharing of resource set identifiers among users. However, for
689 privacy reasons, it is RECOMMENDED that the host assign an
690 identifier that is obscured with respect to any human-readable
691 resource set label used at this host. Further, this identifier
692 MUST match the resource set identifier path component of the URI
693 used to manage this description in the resource set registration
694 API; see Section 2.4.3 for more information. (Typically this
695 matching is achieved through automatically populating the
696 parameter value on initial registration of the description.)
698 name REQUIRED. A human-readable string describing a set of one or
699 more resources. The AM SHOULD use the name in its user interface
700 to assist the user in setting policing for protecting this
701 resource set.
703 icon_uri OPTIONAL. A URI for a graphic icon representing the
704 resource set. If provided, the AM SHOULD use the referenced icon
705 in its user interface to assist the user in setting policies for
706 protecting this resource set.
708 scopes REQUIRED. An array referencing one or more URI references of
709 scope descriptions that are available for this resource set.
711 For example, this description characterizes a resource set (a photo
712 album) that can potentially be only viewed, or alternatively to which
713 full access can be granted; the URIs point to scopes descriptions as
714 defined in Section 2.4.1:
715 {
716 "resource_set":
717 {
718 "_id": "112210f47de98100",
719 "name": "Photo album",
720 "icon_uri": "http://www.example.com/icons/flower.png",
721 "scopes":
722 ["http://photoz.example.com/dev/scopes/view",
723 "http://photoz.example.com/dev/scopes/all"]
724 }
725 }
727 Resource set descriptions MAY contain extension parameters that are
728 not defined in this specification. The names of extension parameters
729 MUST begin with "x-" or "X-".
731 When a host creates or updates a resource set description (see
732 Section 2.4.3), the AM MUST attempt to retrieve the referenced scope
733 descriptions. It MAY cache such descriptions as long as indicated in
734 the HTTP cache-control header for the scope description resource
735 unless the resource set description is subsequently updated within
736 the validity period. At the beginning of an authorizing user's login
737 session at the AM, the AM MUST attempt to re-retrieve scope
738 descriptions applying to that user whose cached versions have
739 expired.
741 2.4.3. Resource Set Registration API
743 The host uses a RESTful API at the AM's resource set registration
744 endpoint to create, read, update, and delete resource set
745 descriptions, along with listing groups of such descriptions. The
746 host MUST use its valid host access token obtained previously to gain
747 access to this endpoint.
749 (Note carefully the similar but distinct senses in which the word
750 "resource" is used in this section. UMA resource set descriptions
751 are themselves managed as web resources at the AM through this API.)
753 The AM MUST present an API for registering resource set descriptions
754 at a set of URIs with this structure: "{rsreguri}/host/{hostid}/
755 resource_set/{rsid}"
757 The components of these URIs are defined as follows:
759 {rsreguri} The AM's resource set registration endpoint as advertised
760 in its metadata (see Section 1.5).
762 {hostid} A registration area at the AM that is specific to this
763 host. The host MUST use the unique OAuth client identifier it was
764 assigned by this AM as its host identifier. If the host
765 identifier does not match the host access token used at the host
766 registration endpoint, the AM MUST report an HTTP 403 Forbidden
767 error and fail to act on the request.
769 {rsid} An identifier for a resource set description. The identifier
770 MUST match the "_id" parameter value in the description itself.
772 Without a specific resource set identifier path component, the URI
773 applies to the set of resource set descriptions already registered.
775 Following is a summary of the five registration operations the AM is
776 REQUIRED to support. Each is defined in its own section below. All
777 other methods are unsupported.
779 o Create resource set description: PUT /host/{hostid}/resource_set/
780 {rsid}
782 o Read resource set description: GET /host/{hostid}/resource_set/
783 {rsid}
785 o Update resource set description: PUT /host/{hostid}/resource_set/
786 {rsid}
788 o Delete resource set description: DELETE /host/{hostid}/
789 resource_set/{rsid}
791 o List resource set descriptions: GET /host/{hostid}/resource_set/
793 If the request to the resource set registration endpoint is
794 incorrect, then the AM responds with an error message (see
795 Section 4.2) by including one of the following error codes with the
796 response:
798 unsupported_method_type The host request used an unsupported HTTP
799 method. The AM MUST respond with the HTTP 403 (Forbidden) status
800 code and MUST fail to act on the request.
802 hostid_access_token_mismatch The hostid does not match the presented
803 host access token. The AM MUST respond with the HTTP 403
804 (Forbidden) status code.
806 ambiguous_resource_set_id The resourcesetid provided in the resource
807 set description does not match the one provided in the URI. The
808 AM MUST respond with the HTTP 400 (Bad Request) status code and
809 MUST fail to act on the request.
811 resource_set_not_found The resource set requested from the AM cannot
812 be found. The AM MUST respond with HTTP 404 (Not Found) status
813 code.
815 resource_set_mismatch The resource set that was requested to be
816 deleted or updated at the AM did not match the ETag value present
817 in the request. The AM MUST respond with HTTP 412 (Precondition
818 Failed) status code and MUST fail to act on the request.
820 For example:
822 HTTP/1.1 403 Forbidden
823 Content-Type: application/json
824 Cache-Control: no-store
825 {
826 "error":"unsupported_method_type"
827 }
829 2.4.3.1. Create Resource Set Description
831 Adds a new resource set description using the PUT method, thereby
832 putting it under the AM's protection. The host is free to use its
833 own methods of identifying and describing resource sets; the AM MUST
834 treat them as opaque for the purpose of authorizing access, other
835 than associating them with the authorizing user represented by the
836 host access token used to access the API. On successfully
837 registering a resource set, the host MUST use UMA mechanisms to limit
838 access to any resources corresponding to this resource set, relying
839 on the AM to supply currently valid permissions for authorized
840 access.
842 HTTP request:
843 PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1
844 Content-Type: application/json
845 ...
847 (Body contains JSON representation of resource set description to be created)
848 Example of an HTTP request that creates a resource set description at
849 the AM:
850 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
851 Content-Type: application/json
852 Host: am.example.com
854 {
855 "resource_set":
856 {
857 "_id": "112210f47de98100",
858 "name": "Photo album",
859 "icon_uri": "http://www.example.com/icons/flower.png",
860 "scopes":
861 ["http://photoz.example.com/dev/scopes/view",
862 "http://photoz.example.com/dev/scopes/all"]
863 }
864 }
866 HTTP response (success):
867 HTTP/1.1 201 Created
868 Content-Type: application/json
869 Location: (URL of created resource, same as in the PUT request)
870 ETag: (entity tag of resource artifact)
871 ...
873 (Body contains JSON representation of created resource set description)
875 Example of an HTTP response confirming the created resource set
876 description:
877 HTTP/1.1 201 Created
878 Content-Type: application/json
879 Location: https://am.example.com/rsreg_uri/host/photoz.example.com/resource_set/112210f47de98100
880 ETag: "1234sdbdDX"
881 ...
883 {
884 "resource_set":
885 {
886 "_id": "112210f47de98100",
887 "name": "Photo album",
888 "icon_uri": "http://www.example.com/icons/flower.png",
889 "scopes":
890 ["http://photoz.example.com/dev/scopes/view",
891 "http://photoz.example.com/dev/scopes/all"]
892 }
893 }
894 2.4.3.2. Read Resource Set Description
896 Reads a previously registered resource set description using the GET
897 method.
899 HTTP request:
900 GET /host/{hostid}/resource_set/{rsid} HTTP/1.1
901 ...
903 Example of an HTTP request that reads a resource set description from
904 the AM:
905 GET /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
906 Host: am.example.com
907 ...
909 HTTP response (success):
910 HTTP/1.1 200 OK
911 Content-Type: application/json
912 ETag: (entity tag of resource artifact)
913 ...
915 (Body contains JSON representation of resource set description)
917 Example of an HTTP response message containing a resource set
918 description from the AM:
919 HTTP/1.1 200 OK
920 Content-Type: application/json
921 ETag: "1234sdbdDX"
922 ...
924 {
925 "resource_set":
926 {
927 "_id": "112210f47de98100",
928 "name": "Photo album",
929 "icon_uri": "http://www.example.com/icons/flower.png",
930 "scopes":
931 ["http://photoz.example.com/dev/scopes/view",
932 "http://photoz.example.com/dev/scopes/all"]
933 }
935 HTTP response (not found):
936 HTTP/1.1 404 Not Found
937 Content-Type: application/json
938 ...
940 {
941 "error":"resource_set_not_found"
942 }
944 2.4.3.3. Update Resource Set Description
946 Updates a previously registered resource set description using the
947 PUT method, thereby changing the resource set's protection
948 characteristics.
950 This operation is different from the operation to create a new
951 resource set description (Section 2.4.3.1) because it assumes that
952 prior registration of the resource set in question has occurred.
954 HTTP request:
955 PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1
956 Content-Type: application/json
957 If-Match: (entity tag of resource if operation is to be idempotent)
958 ...
960 (Body contains JSON representation of resource set description to be updated)
962 Example of an HTTP request that updates a resource set description at
963 AM:
964 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
965 Content-Type: application/json
966 Host: am.example.com
967 If-Match: "1234sdbdDX"
969 {
970 "resource_set":
971 {
972 "_id": "112210f47de98100",
973 "name": "Updated Photo album",
974 "icon_uri": "http://www.example.com/icons/sun.png",
975 "scopes":
976 ["http://photoz.example.com/dev/scopes/view",
977 "http://photoz.example.com/dev/scopes/all"]
978 }
979 }
980 HTTP response (success):
981 HTTP/1.1 204 No Content
982 ETag: "54223dfda"
983 ...
985 HTTP response (entity tag does not match):
986 HTTP/1.1 412 Precondition failed
987 Content-Type: application/json
988 ...
990 {
991 "error":"resource_set_mismatch"
992 }
994 2.4.3.4. Delete Resource Set Description
996 Deletes a previously registered resource set description using the
997 DELETE method, thereby removing it from the AM's protection regime.
999 HTTP request:
1000 DELETE /host/{hostid}/resource_set/{rsid}
1001 If-Match: (entity tag of resource if operation is to be idempotent)
1002 ...
1004 Example of an HTTP request that deletes a resource set description
1005 from the AM:
1006 DELETE /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
1007 Host: am.example.com
1008 If-Match: "1234sdbdDX"
1010 HTTP response (success):
1011 HTTP/1.1 204 No content
1012 ...
1014 HTTP response (not found):
1015 HTTP/1.1 404 Not Found
1016 Content-Type: application/json
1017 ...
1019 {
1020 "error":"resource_set_not_found"
1021 }
1022 HTTP response (entity tag does not match):
1023 HTTP/1.1 412 Precondition failed
1024 Content-Type: application/json
1025 ...
1027 {
1028 "error":"resource_set_mismatch"
1029 }
1031 2.4.3.5. List Resource Set Descriptions
1033 Lists all previously registered resource set identifiers for this
1034 user using the GET method. The list is in the form of a JSON array
1035 of {rsid} values.
1037 HTTP request:
1038 GET /host/{hostid}/resource_set HTTP/1.1
1039 ...
1041 Example of an HTTP request that lists registered resource set
1042 descriptions at the AM:
1043 GET /host/photoz.example.com/resource_set HTTP/1.1
1044 Host: am.example.com
1045 ...
1047 HTTP response:
1048 HTTP/1.1 200 OK
1049 Content-Type: application/json
1050 ...
1052 (Body contains JSON array of {rsid} values)
1054 Example of an HTTP response with the list of registered resource set
1055 identifiers:
1056 HTTP/1.1 200 OK
1057 Content-Type: application/json
1058 ...
1060 {
1061 "resource_set_id_list": [ "112210f47de98100", "34234df47eL95300" ]
1062 }
1064 3. Getting Authorization and Accessing a Resource
1066 Phase 2 of UMA is getting authorization, and Phase 3 is accessing a
1067 resource. In these phases, an AM orchestrates and controls
1068 requesting parties' access to a user's protected resources at a host,
1069 under conditions dictated by that user.
1071 Phase 3 is merely the successful completion of a requester's access
1072 attempt (see Section 3.1.5) that initially involved several embedded
1073 interactions among the requester, AM, and host in Phase 2. Phase 2
1074 always begins with the requester attempting access at a protected
1075 resource endpoint at the host. How the requester came to learn about
1076 this endpoint is out of scope for UMA; the authorizing user might,
1077 for example, have advertised its availability publicly on a blog or
1078 other website, listed it in a discovery service, or emailed a link to
1079 a particular intended requesting party.
1081 The host responds to the requester's access request in one of several
1082 ways depending on the circumstances of the request, either
1083 immediately or having first performed one or more embedded
1084 interactions with the AM. Depending on the nature of the host's
1085 response to an failed access attempt, the requester itself engages in
1086 embedded interactions with the AM before re-attempting access.
1088 The interactions are as follows. The interaction summarized in each
1089 top-level list item MAY be the last interaction engaged in, if the
1090 requester chooses not to continue pursuing access to the resource.
1092 o The requester attempts access at a particular protected resource
1093 at a host (see Section 3.1).
1095 * If the user corresponding to the protected resource URI is
1096 ambiguous: host responds immediately with an error (see
1097 Section 3.1.1).
1099 * If the user is unambiguous but the access attempt is
1100 unaccompanied by a requester access token: host responds
1101 immediately with instructions on where to go to obtain one (see
1102 Section 3.1.2).
1104 o If the access attempt was accompanied by a requester access token,
1105 the host checks the token's status at the AM (see Section 3.3).
1107 * If the AM reports that the requester access token is invalid
1108 (see Section 3.3.2), the host responds to the requester with
1109 instructions on where to go to obtain a token (see
1110 Section 3.1.2).
1112 o If the AM supplies a token status description for a valid
1113 requester access token (see Section 3.3.1) but none of the
1114 permissions associated with the token match the scope of attempted
1115 access, the host registers a suitable permission on the
1116 requester's behalf at the AM (see Section 3.4) and then responds
1117 to the requester with instructions on where to go to request
1118 authorization to associate that permission with its token (see
1119 Section 3.1.4).
1121 o If the requester received instructions on where to get a token, it
1122 requests a token from the appropriate AM (see Section 3.2).
1124 o If the requester received instructions on where to get
1125 authorization for access permission, it requests permission from
1126 the appropriate AM (see Section 3.5).
1128 o If the AM gave status back on a valid requester access token, and
1129 at least one of the permissions associated with the token match
1130 the scope of attempted access, the host responds to the
1131 requester's access attempt with success (see Section 3.1.5).
1133 The interactions are described in detail in the following sections.
1135 3.1. Requester-Host: Attempt Access at Protected Resource
1137 This interaction assumes that the host has previously registered with
1138 an AM one or more resource sets that correspond to the resource to
1139 which access is being attempted, such that the host considers this
1140 resource to be protected by a particular AM.
1142 The requester typically attempts to access the desired resource at
1143 the host directly (for example, when a human operator of the
1144 requester software clicks on a thumbnail representation of the
1145 resource). The requester is expected to discover, or be provisioned
1146 with, knowledge of the protected resource and its location out of
1147 band. Further, the requester is expected to acquire its own
1148 knowledge about the methods made available by the host for operating
1149 on this resource (such as viewing it with a GET method, or
1150 transforming it with some complex API call) and the possible scopes
1151 of access.
1153 The host responds in one of five ways.
1155 3.1.1. Requester's Request Is Ambiguous
1157 By the nature of the requester's request for access (for example,
1158 through a URI parameter specifying a username or other identifier),
1159 the host needs to be able to detect uniquely which one of its users
1160 has the operative control over access to this resource. Without
1161 this, the host will be unable to interact with the correct AM using
1162 the correct host access token in protecting the resource.
1164 If the requester's request is ambiguous with respect to the specific
1165 user at the host, the host immediately responds with an "ambiguous-
1166 user" error message (see Section 4.2).
1168 For example:
1169 HTTP/1.1 403 Forbidden
1170 Content-Type: application/json
1171 Cache-Control: no-store
1173 {
1174 "error":"ambiguous-user"
1175 }
1177 3.1.2. Requester Presents No Access Token
1179 If the host is able to detect uniquely which one of its users has the
1180 operative control over access to the resource (see Section 3.1.1),
1181 but the requester does not present any access token with the request,
1182 the host MUST return an HTTP 400 (Bad Request) status code indicating
1183 it is an "invalid_request" (see Section 2.4.1 of [OAuth-bearer]),
1184 along with providing the AM's URI. This error indicates to the
1185 requester that the request is missing a required parameter, includes
1186 an unsupported parameter or parameter value, repeats the same
1187 parameter, uses more than one method for including an access token,
1188 or is otherwise malformed.
1190 For example:
1191 HTTP/1.1 400 Bad Request
1192 WWW-Authenticate: UMA realm="example"
1193 host_id="photoz.example.com",
1194 am_uri="http://am.example.com"
1196 3.1.3. Requester Presents an Invalid Access Token
1198 If the requester presents an access token with its request, the host
1199 asks the AM to give it the requester access token's status (see
1200 Section 3.3). If the AM reports that the token is invalid, the Host
1201 MUST return an HTTP 401 (Unauthorized) status code indicating it is
1202 an "invalid_token" (see Section 2.4.1 of [OAuth-bearer]), along with
1203 providing the AM's URI.
1205 For example:
1206 HTTP/1.1 401 Unauthorized
1207 WWW-Authenticate: UMA realm="example"
1208 host_id="photoz.example.com",
1209 am_uri="http://am.example.com"
1211 3.1.4. Requester's Token Has Insufficient Permission
1213 If the requester presents an access token with its request, the host
1214 SHOULD ask the AM to give it the requester access token's status (see
1215 Section 3.3). If the AM supplies a token status description for a
1216 valid requester access token, the host examines the token status
1217 description. If the token status is not associated with any
1218 currently valid permission that applies to the scope of access
1219 attempted by the requester, the Host SHOULD register the desired
1220 permission with the AM (see Section 3.4) and then respond to the
1221 requester with the HTTP 403 (Forbidden) status code indicating that
1222 the token has "insufficient_scope" (see Section 2.4.1 of
1223 [OAuth-bearer]), along with providing the AM's URI and the permission
1224 ticket it just received from the AM.
1226 For example:
1227 HTTP/1.1 403 Forbidden
1228 WWW-Authenticate: UMA realm="example"
1229 host_id="photoz.example.com"
1230 am_uri="http://am.example.com",
1231 ticket="5454345rdsaa4543"
1233 3.1.5. Requester's Token Has Sufficient Permission
1235 If the requester presents an access token with its request, the host
1236 SHOULD ask the AM to give it the requester access token's status (see
1237 Section 3.3) If the AM supplies a token status description for a
1238 valid requester access token, the host examines the token status
1239 description. If the token status is associated with at least one
1240 currently valid permission that applies to the scope of access
1241 attempted by the requester, the host SHOULD give access to the
1242 desired resource.
1244 For example:
1245 HTTP/1.1 200 OK
1246 Content-Type: image/jpeg
1247 ...
1249 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
1250 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
1251 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
1252 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
1254 This response constitutes the conclusion of Phase 3 of UMA.
1256 3.2. Requester-AM: Requester Obtains Access Token
1258 When a requester does not possess a valid access token to access
1259 resources of a particular user at a particular host, it requests one
1260 from the AM's requester token endpoint.
1262 The requester learns about this endpoint by retrieving the AM's
1263 hostmeta document (see Section 1.5) based on the "am_uri" information
1264 that was provided by the host in its previous response, as described
1265 in Section 2 of hostmeta [hostmeta]. For example, if the "am_uri" is
1266 "am.example.com", the requester creates the URI
1267 "https://am.example.com/.well-known/host-meta" and performs a GET
1268 request on it.
1270 Each such token represents the set of permissions for that requesting
1271 party to access potentially many different resource sets (all
1272 controlled by a single authorizing user), with a variety of scopes,
1273 at that same host, on behalf of the same requesting party.
1275 The requester SHOULD use the OAuth 2.0 client credentials
1276 authorization grant type (see Section 4.4 of [OAuth2]).
1278 In UMA, unlike in plain OAuth, obtaining an access token does not
1279 automatically convey permission for access to any protected resource.
1280 The token must first be associated with at least one suitable
1281 permission for scoped access in order for the requester to succeed in
1282 accessing the resource.
1284 If the requester does not yet have a client identifier and optional
1285 client secret, it MAY request these using [OCDynClientReg], if the AM
1286 supports it (see Section 1.5 for how the AM MAY indicate support).
1288 3.3. Host-AM: Ask for Requester's Presented Access Token Status
1290 On receiving a requester access token in an access attempt, the host
1291 asks the AM for the token's status. If it has a cached token status
1292 description available that has not expired yet, it MAY use it
1293 instead.
1295 The host makes the request to the AM with a POST to the AM's token
1296 status endpoint. The body of the HTTP request message contains a
1297 JSON [RFC4627] document providing the requester access token and the
1298 IP address of the requester's request. The host MAY, at its
1299 discretion, instead supply the originating IP address indicated in
1300 the requester's X-Forwarded-For: header value. The IP address or
1301 originating IP address is advisory only; the AM MAY ignore it for
1302 purposes of its own token validation process.
1304 The host gains access to the token status endpoint by presenting its
1305 own host access token in the request. The host access token also
1306 allows the host and AM to uniquely identify the user they have in
1307 common, and therefore allows the AM to look up the correct
1308 authorizing user's policies and settings.
1310 Example of a request to the token validation endpoint that provides
1311 the host access token in the header:
1312 POST /token_status HTTP/1.1
1313 Host: am.example.com
1314 Authorization: Bearer vF9dft4qmT
1315 Content-Type: application/json
1317 {
1318 "token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
1319 "resource_set_id":"112210f47de98100"
1320 "host_id":"photoz.example.com"
1321 "ipaddr":"192.168.1.1"
1322 }
1324 3.3.1. AM Returns a Token Status Description
1326 If the the AM finds the requester's access token to be valid, it
1327 returns the token's status in an HTTP response using the 200 OK
1328 status code, containing a JSON [RFC4627] document supplying the token
1329 status description. The token status description contains all of the
1330 permissions that are currently valid for this requester access token
1331 (and thus for the requesting party on whose behalf it is acting).
1332 The AM MAY set a cache period for the returned token status
1333 description that allows the host to reuse it over some period of time
1334 when it later sees the same requester access token.
1336 The token status description is a JSON object with the name
1337 "token_status" containing an array of zero or more permission
1338 objects, each with the following parameters:
1340 resource_set_id REQUIRED. A string that uniquely identifies the
1341 resource set, access to which has been granted to this requester
1342 on behalf of this requesting party. The identifier MUST
1343 correspond to a resource set that was previously registered as
1344 protected.
1346 scopes REQUIRED. An array referencing one or more URIs of scopes to
1347 which access was granted for this resource set. Each scope MUST
1348 correspond to a scope that was registered by this host for the
1349 referenced resource set.
1351 exp REQUIRED. An integer representing the expiration time on or
1352 after which the permission MUST NOT be accepted for authorized
1353 access. The processing of the exp parameter requires that the
1354 current date/time MUST be before the expiration date/time listed
1355 in the exp claim. Host implementers MAY provide for some small
1356 leeway, usually no more than a few minutes, to account for clock
1357 skew.
1359 Example:
1360 HTTP/1.1 200 OK
1361 Content-Type: application/json
1362 Cache-Control: no-store
1364 {
1365 "token_status":
1366 [
1367 {
1368 "resource_set_id": "112210f47de98100",
1369 "scopes":
1370 ["http://photoz.example.com/dev/actions/view",
1371 "http://photoz.example.com/dev/actions/all"],
1372 "exp": 1300819380
1373 }
1374 ]
1375 }
1377 3.3.2. AM Returns a Token Invalid Response
1379 If the the AM finds the requester's access token to be invalid, it
1380 returns an UMA error message.
1382 The AM includes one of the following error codes in the error
1383 response: (see Section 4.2) and responds with the HTTP 400 status
1384 code:
1386 invalid_requester_token AM determined that the requester access
1387 token was not valid.
1389 expired_requester_token AM determined that the requester access
1390 token has expired.
1392 For example:
1393 HTTP/1.1 400 Bad Request
1394 Content-Type: application/json
1395 Cache-Control: no-store
1396 {
1397 "error":"invalid_requester_token"
1398 }
1400 3.4. Host-AM: Register a Permission
1402 If the permissions returned by the AM from a token status request are
1403 insufficient to allow this requester's access attempt, the host
1404 registers a permission with the AM that it believes would be
1405 sufficient for the type of access sought. As a result of the host
1406 registering a permission to the AM, the AM returns a permission
1407 ticket for the host to give to the requester in its response (see
1408 Section 3.1.4).
1410 The permissions ticket is a short-lived opaque structure whose
1411 contents is determined by the AM. Later when the requester asks the
1412 AM to add permissions to the requester's token (see Section 3.5 it
1413 will submit this ticket to the AM. It is therefore the task of the
1414 AM to perform binding of this ticket to the requester and its token.
1416 The host registers the permission using the POST method at the AM's
1417 permission registration endpoint, providing its host access token to
1418 get authorized access to this endpoint. The body of the HTTP request
1419 message contains a JSON [RFC4627] document providing the requester's
1420 access token and the requested permission.
1422 The requested scope is an object with the name "requested_permission"
1423 and the following parameters:
1425 resource_set_id REQUIRED. A string that uniquely identifies a
1426 resource set, access to which this requester is seeking access.
1427 The identifier MUST correspond to a resource set that was
1428 previously registered as protected.
1430 scopes REQUIRED. An array referencing one or more identifiers of
1431 scopes to which access is needed for this resource set. Each
1432 scope identifier MUST correspond to a scope that was registered by
1433 this host for the referenced resource set.
1435 Example of an HTTP request that registers a permission at the AM's
1436 permission registration endpoint:
1437 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
1438 Content-Type: application/json
1439 Host: am.example.com
1441 {
1442 "requested_permission":
1443 {
1444 "resource_set_id": "112210f47de98100",
1445 "scopes": ["http://photoz.example.com/dev/actions/view",
1446 "http://photoz.example.com/dev/actions/all"]
1447 }
1448 }
1450 On receiving the scope registration request from the Host, the AM
1451 issues a response message that has one of the possible following
1452 outputs:
1454 o A permission ticket and its expiration time (typically very
1455 short).
1457 o Error message indicating a malformed scope registration request.
1459 3.4.1. AM Returns a Permission Registration Success Response
1461 The AM responds with an HTTP 201 (Created) status code and includes
1462 the Location header in its response as well as the "ticket" parameter
1463 in the JSON-formatted body:
1465 For example:
1466 HTTP/1.1 201 Created
1467 Content-Type: application/json
1468 Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543
1470 {
1471 "ticket":"5454345rdsaa4543"
1472 }
1474 3.4.2. AM Returns a Permission Registration Error Response
1476 The AM responds with an HTTP 400 (Bad Request) status code and
1477 includes one of the following error codes with the error response
1478 (see Section 4.2):
1480 invalid_resource_set_id The provided resource set identifier was not
1481 found at the AM.
1483 invalid_scope At least one of the scopes included in the request was
1484 not registered previously by this host.
1486 invalid_requester_token The requester access token was not
1487 recognized by the AM.
1489 expired_requester_token The requester access token has expired.
1491 For example:
1492 HTTP/1.1 400 Bad Request
1493 Content-Type: application/json
1494 Cache-Control: no-store
1495 ...
1497 {
1498 "error":"invalid_resource_set_id"
1499 }
1501 3.5. Requester-AM: Request Authorization to Add Permission
1503 In this interaction, the requester asks the AM to grant it permission
1504 for access. It does this at the AM's permission endpoint by
1505 supplying the permission ticket it got from the host, along with its
1506 requester access token and other pertinent information. The AM uses
1507 the ticket to look up the previously registered permission, uses the
1508 token to confirm that the correct requester is asking for it, maps
1509 the requested permission to operative user policies, and ultimately
1510 responds to the request positively or negatively.
1512 The requester learns about this endpoint by retrieving the AM's
1513 hostmeta document (see Section 1.5) based on the "am_uri" information
1514 that was provided by the host in its previous response, as described
1515 in Section 2 of hostmeta [hostmeta]. For example, if the "am_uri" is
1516 "am.example.com", the requester creates the URI
1517 "https://am.example.com/.well-known/host-meta" and performs a GET
1518 request on it.
1520 The requester performs a GET or POST on the permission endpoint,
1521 supplying:
1523 o The permission ticket it received from the host
1525 o Its own requester access token
1526 o A state parameter (to help avoid replay attacks)
1528 o A redirect URL
1530 o A callback URL
1532 The AM MUST support GET requests to this endpoint and MAY support
1533 POST requests; if it supports POST, the endpoint MUST use SSL/TLS.
1534 (Requesters will tend to prefer POST when they want to sign the
1535 request message and preserve certain URL information; however, GET
1536 typically provides a smoother user experience.)
1538 The AM responds with a successful or unsuccessful permission
1539 response.
1541 3.5.1. AM Returns an Add Permission Success Response
1543 If the AM determines that the requesting party meets the
1544 authorization criteria set out by the authorizing user's policy (see
1545 Section 3.6), it responds with an HTTP 201 (Created) status code and
1546 provides an updated token:
1548 For example:
1549 HTTP/1.1 201 Created
1550 Content-Type: application/json
1552 {
1553 "token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
1554 }
1556 3.5.2. AM Returns an Add Permission Error Response
1558 If the content-type of the request is not recognized by the AM, the
1559 AM MUST produce an HTTP error.
1561 If the request fails due to missing or invalid parameters, or is
1562 otherwise malformed, the AM SHOULD inform the requester of the error
1563 by sending an HTTP error response.
1565 3.5.2.1. AM Returns an Add Permission OAuth Error Response
1567 If the request fails due to an invalid, missing, or expired requester
1568 access token or requires higher privileges at this endpoint than
1569 provided by the access token, the AM responds with an OAuth error
1570 (see Section 4.1).
1572 For example:
1573 HTTP/1.1 401 Unauthorized
1574 WWW-Authenticate: Bearer realm="example",
1575 error="invalid_token",
1576 error_description="The access token expired"
1578 3.5.2.2. AM Returns an Add Permission UMA Error Response
1580 The AM responds responds using the appropriate HTTP status code
1581 (typically 400 or 403), and includes one of the following error codes
1582 in the response: (see Section 4.2):
1584 invalid_requester_ticket The provided ticket was not found at the
1585 AM. The AM SHOULD respond with the HTTP 400 (Bad Request) status
1586 code.
1588 expired_requester_ticket The provided ticket has expired. The AM
1589 SHOULD respond with the HTTP 400 (Bad Request) status code.
1591 not_authorized_permission The requester is definitively not
1592 authorized for this permission according to user policy. The AM
1593 SHOULD respond with the HTTP 403 (Forbidden) status code.
1595 For example:
1596 HTTP/1.1 400 Bad Request
1597 Content-Type: application/json
1598 Cache-Control: no-store
1599 ...
1601 {
1602 "error":"expired_requester_ticket"
1603 }
1605 3.6. AM-Requester Authorization Flows
1607 The AM MUST base its decisions to add permissions to requester access
1608 tokens on user policies. The nature of these policies is outside the
1609 scope of UMA, but generally speaking, they can be thought of as
1610 either independent of requesting-party features (for example, time of
1611 day) or dependent on requesting-party features (for example, whether
1612 they are over 18). This latter case requires the requesting party to
1613 transmit identity claims to the AM in some fashion.
1615 The process for requesting and providing claims is extensible and may
1616 have a variety of dependencies on the type of requesting party (for
1617 example, natural person or legal person) and the type of requester
1618 application (for example, browser, native app, or autonomously
1619 running web service). UMA currently provides a framework for
1620 handling human-driven requester apps and an optional solution for
1621 gathering standardized claims from that end-user, and allows for
1622 extensions to support other solutions for this use case and other use
1623 cases. The AM SHOULD document its claims-handling ability in its XRD
1624 metadata through the claim_formats parameter (see Section 1.5). For
1625 the business-level and legal implications of different technical
1626 authorization flows, see [UMA-trustmodel].
1628 3.6.1. Authorization Flow for Requester Apps Operated by End-Users
1630 A natural person might be operating a requester app (whether a
1631 browser or a native app) in one of two typical situations:
1633 o The requesting party is a natural person (for example, a friend of
1634 the authorizing user); the requesting party may even be the
1635 authorizing user herself.
1637 o The requesting party is a legal person such as a corporation, and
1638 the human being operating the requester app is acting as an agent
1639 of that legal person (for example, a customer support specialist
1640 representing a credit card company).
1642 The AM has a variety of options at this point for satisfying the
1643 authorizing user's policy; this specification does not dictate a
1644 single answer. For example, the AM could require the end-user
1645 requesting party to register for or log in to a local AM account, or
1646 fill in a questionnaire, or complete a purchase.
1648 An end-user-driven requester app MUST redirect the end-user
1649 requesting party to the AM to complete the process of authorization.
1650 If the AM succeeds in adding the requested permission, it MUST
1651 redirect the end-user requesting party back to the requester app when
1652 reporting success.
1654 3.6.1.1. Gathering Claims from End-Users with OpenID Connect
1656 An AM MAY use OpenID Connect as one means of gathering claims from an
1657 end-user requesting party, leveraging OpenID Connect mechanisms to
1658 transmit claims from distributed sources. If it supports this
1659 option, the AM MUST supply the "openid" value for one of its
1660 "claim_formats" parameters in its AM metadata (see Section 1.5 for
1661 how to formulate this metadata).
1663 To conform to this option, the AM MUST do the following:
1665 o Serve as a conforming OpenID Relying Party and Claims Client
1666 according to [OCStandard]
1668 o Be able to utilize at least all of the reserved claims defined in
1669 [OCMessages] in assessing policy and granting permissions
1671 The AM can then use any conforming OpenID Connect mechanisms and
1672 typical user interfaces for engaging with the UserInfo endpoints of
1673 OpenID Providers and Claims Providers, potentially allowing for the
1674 delivery of "trusted claims" (such as a verified email address or a
1675 date or birth) on which authorization policy may depend.
1677 4. Error Messages
1679 Ultimately the host is responsible for either granting the access the
1680 requester attempted, or returning an error response to the requester
1681 with a reason for the failure. [OAuth2] defines several error
1682 responses for a resource server to return. UMA makes use of these
1683 error responses, but requires the host to "outsource" the
1684 determination of some error conditions to the AM. UMA defines its
1685 own additional error responses that the AM may give to the host and
1686 requester as they interact with it, and that the host may give to the
1687 requester.
1689 4.1. OAuth Error Responses
1691 When a client (host or requester) attempts to access one of the AM
1692 endpoints Section 1.5 or a client (requester) attempts to access a
1693 protected resource at the host, it has to make an authenticated
1694 request by including an OAuth access token in the HTTP request as
1695 described in [OAuth2] Section 7.
1697 If the client's request failed authentication, the AM or the host
1698 responds with an OAuth error message as described throughout
1699 Section 2 and Section 3.
1701 4.2. UMA Error Responses
1703 When a client (host or requester) attempts to access one of the AM
1704 endpoints Section 1.5 or a client (requester) attempts to access a
1705 protected resource at the host, if the client request is successfully
1706 authenticated by OAuth means, but is invalid for another reason, the
1707 AM or host responds with an UMA error response by adding the
1708 following parameters to the entity body of the HTTP response using
1709 the "application/json" media type:
1711 error REQUIRED. A single error code. Value for this parameter is
1712 defined in the specific AM endpoint description.
1714 error_description OPTIONAL. A human-readable text providing
1715 additional information, used to assist in the understanding and
1716 resolution of the error occurred.
1718 error_uri OPTIONAL. A URI identifying a human-readable web page
1719 with information about the error, used to provide the end-user
1720 with additional information about the error.
1722 Common error codes:
1724 invalid_request The request is missing a required parameter or is
1725 otherwise malformed. The AM MUST respond with the HTTP 400 (Bad
1726 Request) status code.
1728 For example:
1729 HTTP/1.1 400 Bad Request
1730 Content-Type: application/json
1731 Cache-Control: no-store
1732 ...
1734 {
1735 "error":"invalid_request",
1736 "error_description":"There is already a resource with this identifier.",
1737 "error_uri":"http://am.example.com/errors/resource_exists"
1738 }
1740 5. Security Considerations
1742 This specification relies mainly on OAuth security mechanisms for
1743 protecting the host registration endpoint at the AM so that only a
1744 properly authorized host can access it on behalf of the intended
1745 user. For example, the host needs to use a valid host access token
1746 issued through a user authorization process at the endpoint, and the
1747 interaction SHOULD take place over TLS. It is expected that the host
1748 will protect its client secret (if it was issued one) and its host
1749 access token, particularly if used in "bearer token" fashion.
1751 In addition, this specification dictates a binding between the host
1752 access token and the host-specific registration area on the AM to
1753 prevent a host from interacting with a registration area not its own.
1755 For information about the technical, operational, and legal elements
1756 of trust establishment between UMA entities and parties, which
1757 affects security considerations, see [UMA-trustmodel].
1759 6. Privacy Considerations
1761 The AM comes to be in possession of resource set information (such as
1762 names and icons) that may reveal information about the user, which
1763 the AM's trust relationship with the host is assumed to accommodate.
1764 However, the requester is a less-trusted party (in fact, entirely
1765 untrustworthy until it acquires permissions for a requester access
1766 token in UMA protocol step 2). This specification recommends
1767 obscuring resource set identifiers in order to avoid leaking
1768 personally identifiable information to requesters through the "scope"
1769 mechanism.
1771 For information about the technical, operational, and legal elements
1772 of trust establishment between UMA entities and parties, which
1773 affects privacy considerations, see [UMA-trustmodel].
1775 7. Conformance
1777 This section outlines conformance requirements for various entities
1778 implementing UMA endpoints.
1780 This specification has dependencies on other specifications, as
1781 follows:
1783 o OAuth 2.0: AMs, hosts, and requesters MUST support [OAuth2]
1784 features named in this specification for conformance. For
1785 example, AMs MUST support the authorization code grant type for
1786 being introduced to hosts by authorizing users.
1788 o hostmeta: AMs, hosts, and requesters MUST support the [hostmeta]
1789 features named in this specification.
1791 o OpenID Connect: AMs MAY support [OCDynClientReg], and MAY choose
1792 to conform to the "openid" claim format option corresponding to
1793 the OpenID Connect RP role and support for OpenID Connect reserved
1794 claims.
1796 The AM's XRD metadata provides a machine-readable method for an AM to
1797 indicate certain of the conformance options it has chosen. Several
1798 of the metadata fields allow for extensibility. It is RECOMMENDED
1799 that UMA developers and deployers document any profiled or extended
1800 features formally and use XRD metadata to indicate their usage. See
1801 Section 1.5 for information about providing and extending AM
1802 metadata.
1804 8. IANA Considerations
1806 BD
1808 9. AM Metadata Example
1810 For example:
1812
1814 artifact
1816
1817 openid
1819
1821
1823
1824
1827
1828
1831
1833
1834
1837
1838
1841
1842
1845
1847
1849
1850
1853
1855
1856
1859
1860 10. Example of Registering Resource Sets
1862 The following example illustrates the intent and usage of resource
1863 set registration.
1865 This example contains some steps that are exclusively in the realm of
1866 user experience rather than web protocol, to achieve realistic
1867 illustration; these steps are labeled "User experience only". Some
1868 other steps are exclusively internal to the operation of the entity
1869 being discussed; these are labeled "Internal only".
1871 An authorizing user, Alice Adams, has just uploaded a photo of her
1872 new puppy to a host, Photoz.example.com, and wants to ensure that
1873 this specific photo is not publicly accessible.
1875 Alice has already introduced this host to her AM,
1876 CopMonkey.example.com, and thus Photoz has already obtained a host
1877 access token from CopMonkey. However, Alice has not previously
1878 instructed Photoz to use CopMonkey to protect any other photos of
1879 hers.
1881 Alice has previously visited CopMonkey to map a default "do not share
1882 with anyone" policy to any resource sets registered by Photoz, until
1883 such time as she maps some other less-draconian policies to those
1884 resources. (User experience only. This may have been done at the
1885 time Alice introduced the host to the AM, and/or it could have been a
1886 global or host-specific preference setting. A different constraint
1887 or no constraint at all might be associated with newly protected
1888 resources.) Other kinds of policies she may eventually map to
1889 particular photos or albums might be "Share only with
1890 husband@email.example.net" or "Share only with people in my 'family'
1891 group".
1893 Photoz itself has a publicly documented API that offers two dozen
1894 different methods that apply to single photos, such as "addTags" and
1895 "getSizes", but rolls them up into two photo-related scopes of
1896 access: "viewing" (consisting of various read-only operations) and
1897 "all" (consisting of various reading, editing, and printing
1898 operations). It defines two Web-accessible JSON-encoded documents
1899 called scope descriptions that represent these scopes, which it is
1900 able to reuse for all of its users (not just Alice).
1902 The "name" parameter values are intended to be seen by Alice when she
1903 maps authorization constraints to specific resource sets and actions
1904 while visiting CopMonkey, such that Alice would see the strings "View
1905 Photo and Related Info" and "All Actions", likely accompanied by the
1906 referenced icons, in the CopMonkey interface. (Other users of Photoz
1907 might similarly see the same labels at CopMonkey or whatever other AM
1908 they use. Photoz could distinguish natural-language labels per user
1909 if it wishes, by pointing to scopes with differently translated
1910 names.)
1912 Example of the "view" scope ,which description is a Web-accessible
1913 resource at http://photoz.example.com/dev/scopes/view:
1914 {
1915 "scope":
1916 {
1917 "_id": "view"
1918 "name": "View Photo and Related Info",
1919 "icon_uri": "http://www.example.com/icons/reading-glasses.png"
1920 }
1921 }
1923 Example of the "all" scope, which description is a Web-accessible
1924 resource at http://photoz.example.com/dev/scopes/all:
1925 {
1926 "scope":
1927 {
1928 "_id": "all"
1929 "name": "All Actions",
1930 "icon_uri": "http://www.example.com/icons/galaxy.png"
1931 }
1932 }
1934 While visiting Photoz, Alice selects a link or button that instructs
1935 the site to "Protect" or "Share" this single photo (user experience
1936 only; Photoz could have made this a default or preference setting).
1938 As a result, Photoz defines for itself a resource set that represents
1939 this photo (internal only; Photoz is the only application that knows
1940 how to map a particular photo to a particular resource set). Photoz
1941 also prepares the following resource set description, which is
1942 specific to Alice and her photo. The "name" parameter value is
1943 intended to be seen by Alice in mapping authorization constraints to
1944 specific resource sets and actions when she visits CopMonkey, such
1945 that Alice would see the string "Steve the puppy!", likely
1946 accompanied by the referenced icon, in the CopMonkey interface. The
1947 possible scopes of access on this resource set are indicated with URI
1948 references to the scope descriptions, as defined just above.
1950 {
1951 "resource_set":
1952 {
1953 "_id": "112210f47de98100"
1954 "name": "Steve the puppy!",
1955 "icon_uri": "http://www.example.com/icons/flower",
1956 "scopes":
1957 ["http://photoz.example.com/dev/scopes/view",
1958 "http://photoz.example.com/dev/scopes/all"]
1959 }
1960 }
1962 Photoz uses the "create resource set description" method of
1963 CopMonkey's standard UMA resource set registration API, presenting
1964 its Alice-specific host access token there, to register and assign an
1965 identifier to the resource set description. The resource set
1966 identifier path component of the URL matches the "_id" parameter
1967 value in the description.
1968 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1
1969 Content-Type: application/json
1970 ...
1972 {
1973 "resource_set":
1974 {
1975 "_id": "112210f47de98100"
1976 "name": "Steve the puppy!",
1977 "icon_uri": "http://www.example.com/icons/flower.png",
1978 "scopes":
1979 ["http://photoz.example.com/dev/scopes/view",
1980 "http://photoz.example.com/dev/scopes/all"]
1981 }
1982 }
1984 Once this description has been successfully registered, Photoz is
1985 responsible for responding to requesters' attempts to access this
1986 photo in a way that is consistent with the authorizing user's
1987 policies, achieving protection of the resource by "outsourcing" this
1988 task to CopMonkey.
1990 At the time Alice indicates she would like this photo protected,
1991 Photoz can choose to redirect Alice to CopMonkey for further policy
1992 setting, access auditing, and other AM-related tasks (user experience
1993 only).
1995 Over time, as Alice uploads other photos and creates and organizes
1996 photo albums, and as Photoz makes new action functionality available,
1997 Photoz can use additional methods of the resource set registration
1998 API to ensure that CopMonkey's understanding of Alice's protected
1999 resources matches its own.
2001 11. Acknowledgments
2003 The current editor of this specification is Thomas Hardjono of MIT.
2004 The following people have additionally served as co-authors:
2006 o Paul Bryan, ForgeRock (former editor)
2008 o Domenico Catalano, Oracle Corp.
2010 o Maciej Machulak, Newcastle University
2012 o Eve Maler, XMLgrrl.com
2014 o Lukasz Moren, Newcastle University
2016 o Christian Scholz, COMlounge GmbH (former editor)
2018 Contributors to this specification include the Kantara UMA Work Group
2019 participants, a list of whom can be found at [UMAnitarians].
2021 12. Issues
2023 All issues are now captured at the project's GitHub site
2024 ().
2026 13. References
2028 13.1. Normative References
2030 [OAuth-SAML]
2031 Campbell, B., "SAML 2.0 Bearer Assertion Grant Type
2032 Profile for OAuth 2.0", February 2011, .
2035 [OAuth-bearer]
2036 Jones, M., "The OAuth 2.0 Protocol: Bearer Tokens",
2037 June 2011,
2038 .
2041 [OAuth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", 2010,
2042 .
2044 [OCDynClientReg]
2045 Sakimura, N., "OpenID Connect Dynamic Client Registration
2046 1.0", September 2011, .
2049 [OCMessages]
2050 Sakimura, N., "OpenID Connect Messages 1.0",
2051 September 2011,
2052 .
2055 [OCStandard]
2056 Sakimura, N., "OpenID Connect Standard 1.0",
2057 September 2011,
2058 .
2061 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2062 Requirement Levels", BCP 14, RFC 2119, March 1997.
2064 [RFC4627] Crockford, D., "The application/json Media Type for
2065 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
2067 [hostmeta]
2068 Hammer-Lahav, E., "Web Host Metadata", May 2011,
2069 .
2071 13.2. Informative References
2073 [UMA-trustmodel]
2074 Maler, E., "UMA Trust Model", February 2011, .
2078 [UMA-usecases]
2079 Maler, E., "UMA Scenarios and Use Cases", October 2010, .
2083 [UMA-userstories]
2084 Maler, E., "UMA User Stories", November 2010, .
2088 [UMAnitarians]
2089 Maler, E., "UMA Participant Roster", 2011, .
2093 Appendix A. Document History
2095 NOTE: To be removed by RFC editor before publication as an RFC.
2097 Author's Address
2099 Thomas Hardjono (editor)
2100 MIT
2102 Email: hardjono@mit.edu