idnits 2.17.1 draft-hardjono-oauth-umacore-00.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 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 (July 2, 2011) is 4679 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) == Outdated reference: A later version (-03) exists of draft-hardjono-oauth-dynreg-00 -- 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' ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 3 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 C. Scholz 5 Expires: January 3, 2012 COM.lounge GmbH 6 P. Bryan 7 pbryan.net 8 M. Machulak 9 Newcastle University 10 E. Maler 11 XMLgrrl.com 12 L. Moren 13 Newcastle University 14 July 2, 2011 16 User-Managed Access (UMA) Core Protocol 17 draft-hardjono-oauth-umacore-00 19 Abstract 21 This specification defines the User-Managed Access (UMA) core 22 protocol. This protocol provides a method for users to control 23 access to their protected resources, residing on any number of host 24 sites, through an authorization manager that governs access decisions 25 based on user policy. 27 This document is an approved Report of the User-Managed Access Work 28 Group of the Kantara Initiative. The User-Managed Access Work Group 29 operates under Kantara IPR Policy - Option Patent and Copyright: 30 Reciprocal Royalty Free with Opt-Out to Reasonable And Non 31 discriminatory (RAND) and the publication of this document is 32 governed by the policies outlined in this option. 34 Status of this Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 3, 2012. 50 Copyright Notice 52 Copyright (c) 2011 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 7 69 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 70 1.3. Endpoint Names . . . . . . . . . . . . . . . . . . . . . . 8 71 2. Protecting a Resource . . . . . . . . . . . . . . . . . . . . 9 72 2.1. Host Looks Up AM Metadata . . . . . . . . . . . . . . . . 10 73 2.1.1. AM Endpoints . . . . . . . . . . . . . . . . . . . . . 10 74 2.1.2. Example AM Metadata . . . . . . . . . . . . . . . . . 12 75 2.2. Host Registers with AM . . . . . . . . . . . . . . . . . . 14 76 2.3. Host Obtains Host Access Token . . . . . . . . . . . . . . 14 77 2.4. Host Registers Sets of Resources to Be Protected . . . . . 14 78 2.4.1. Example of Registering Resource Sets . . . . . . . . . 14 79 2.4.2. Scope Descriptions . . . . . . . . . . . . . . . . . . 17 80 2.4.3. Resource Set Descriptions . . . . . . . . . . . . . . 18 81 2.4.4. Resource Set Registration API . . . . . . . . . . . . 20 82 3. Getting Authorization and Accessing a Resource . . . . . . . . 27 83 3.1. Requester-Host: Attempt Access at Protected Resource . . . 29 84 3.1.1. Requester's Request Is Ambiguous . . . . . . . . . . . 29 85 3.1.2. Requester Presents No Access Token . . . . . . . . . . 30 86 3.1.3. Requester Presents an Invalid Access Token . . . . . . 30 87 3.1.4. Requester's Token Has Insufficient Permission . . . . 31 88 3.1.5. Requester's Token Has Sufficient Permission . . . . . 31 89 3.2. Requester-AM: Requester Obtains Access Token . . . . . . . 32 90 3.3. Host-AM: Ask for Requester's Presented Access Token 91 Status . . . . . . . . . . . . . . . . . . . . . . . . . . 32 92 3.3.1. AM Returns a Token Status Description . . . . . . . . 33 93 3.3.2. AM Returns a Token Invalid Response . . . . . . . . . 34 94 3.4. Host-AM: Register a Permission . . . . . . . . . . . . . . 35 95 3.4.1. AM Returns a Permission Registration Success 96 Response . . . . . . . . . . . . . . . . . . . . . . . 36 97 3.4.2. AM Returns a Permission Registration Error Response . 36 98 3.5. Requester-AM: Request Authorization to Add Permission . . 37 99 3.5.1. Trusted Claims with OpenID Connect . . . . . . . . . . 39 100 4. Error Messages . . . . . . . . . . . . . . . . . . . . . . . . 39 101 4.1. OAuth Error Responses . . . . . . . . . . . . . . . . . . 39 102 4.2. UMA Error Responses . . . . . . . . . . . . . . . . . . . 40 103 5. Security Considerations . . . . . . . . . . . . . . . . . . . 40 104 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 41 105 7. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 41 106 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 107 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 108 10. Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 109 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 44 110 11.1. Normative References . . . . . . . . . . . . . . . . . . . 44 111 11.2. Informative References . . . . . . . . . . . . . . . . . . 44 112 Appendix A. Document History . . . . . . . . . . . . . . . . . . 45 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 115 1. Introduction 117 The User-Managed Access (UMA) core protocol provides a method based 118 on [OAuth2] (currently draft 16) for users to control access to their 119 protected resources, residing on any number of host sites, through a 120 single authorization manager (AM) that governs access decisions based 121 on user policy. 123 There are numerous use cases for UMA, where a resource owner 124 nominates a third party to control access to these resources 125 potentially without the real-time presence of the resource owner. A 126 typical example is the following. A web user (authorizing user) can 127 authorize a web app (requester) to gain one-time or ongoing access to 128 a resource containing his home address stored at a "personal data 129 store" service (host), by telling the host to act on access decisions 130 made by his authorization decision-making service (authorization 131 manager or AM). The requesting party might be an e-commerce company 132 whose site is acting on behalf of the user himself to assist him/her 133 in arranging for shipping a purchased item, or it might be his friend 134 who is using an online address book service to collect addresses, or 135 it might be a survey company that uses an online service to compile 136 population demographics. Other scenarios and use cases for UMA usage 137 can be found in [UMA-usecases] and [UMA-userstories]. 139 In enterprise settings, application access management often involves 140 letting back-office applications serve only as policy enforcement 141 points (PEPs), depending entirely on access decisions coming from a 142 central policy decision point (PDP) to govern the access they give to 143 requesters. This separation eases auditing and allows policy 144 administration to scale in several dimensions. UMA makes use of a 145 separation similar to this, letting the authorizing user serve as a 146 policy administrator crafting authorization strategies on his or her 147 own behalf. 149 The UMA protocol profiles and extends [OAuth2]. An AM serves as an 150 enhanced OAuth authorization server; a host serves as an enhanced 151 resource server; and a requester serves as an enhanced client, 152 acquiring an access token and the requisite authorization to access a 153 protected resource at the host. 155 UMA defines an interoperable protection API between the AM and host, 156 allowing them to reside in separate domains and allowing the host to 157 establish mutual trust with an AM on behalf of a particular user. 158 This API is itself OAuth-protected. Thus, the overall UMA flow has a 159 second embedded OAuth-based interaction within it governing the 160 host-AM relationship. 162 The UMA protocol has three broad phases (see Figure 1). 164 The Three Phases of the UMA Protocol 165 +-----+----------------+ 166 | UA | authorizing | 167 +-------Manage (A)--| | user | 168 | +-----+----------------+ 169 | Phase 1: | UA | 170 | protect a +----------------+ 171 | resource | 172 | Control (B) 173 | | 174 v v 175 +-----------+ +-----+----------------+ 176 | host |<-Protect-(C)-|prot | authorization | 177 | | | API | manager (AM) | 178 +-----------+ +-----+----------------+ 179 | protected | | authorization | 180 | resource | | API | 181 +-----------+ +----------------+ 182 ^ | 183 | Phases 2 and 3: Authorize (D) 184 | get authz and | 185 | access a resource v 186 | +----------------+ 187 +-------Access (E)--------| requester | 188 +----------------+ 189 (requesting party) 191 Figure 1 193 The phases work as follows: 195 1. Protect a resource: This phase involves the authorizing user, 196 host, and AM. The authorizing user has chosen to use a host for 197 managing online resources ("A"), and introduces this host to an 198 AM using an OAuth-mediated interaction that results in the AM 199 giving the host an access token. The host uses AM's protection 200 API to tell the AM what sets of resources to protect ("C"). Out 201 of band of the UMA protocol, the authorizing user instructs the 202 AM what policies to attach to the registered resource sets ("B"). 203 This phase is described in Section 2. 205 2. Get authorization: This phase involves the requester, host, and 206 AM. It may also involve synchronous involvement by the 207 authorizing user if this person is synonymous with the requesting 208 party. This phase is dominated by a loop of activity in which 209 the requester approaches the host seeking access to a protected 210 resource ("E"), is sent to obtain an access token from the AM if 211 it does not have one, and then must demonstrate to the AM that it 212 satisfies the user's authorization policy governing the sought- 213 for resource and scope of access if the host discovers that it 214 does not have the requisite authorization ("D"). This phase is 215 described in Section 3. 217 3. Access a resource: This phase involves the requester successfully 218 presenting an access token that has sufficient permission 219 associated with it to the host in order to gain access to the 220 desired resource ("E"). This phase is described along with Phase 221 2 in Section 3. 223 1.1. Notational Conventions 225 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 226 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 227 document are to be interpreted as described in [RFC2119]. 229 Unless otherwise noted, all the protocol parameter names and values 230 are case sensitive. 232 1.2. Terminology 234 authorizing user 235 An UMA-defined variant of an OAuth resource owner; a web user 236 who configures an authorization manager with policies that 237 control how it governs access decisions when a requester 238 attempts to access a protected resource at a host. 240 authorization manager (AM) 241 An UMA-defined variant of an OAuth authorization server that 242 carries out an authorizing user's policies governing access to 243 a protected resource. 245 protected resource 246 An access-restricted resource at a host, which is being policy- 247 protected by the AM. 249 host 250 An UMA-defined variant of an OAuth resource server that 251 enforces access to the protected resources it hosts, as 252 governed by an authorization manager. 254 host access token 255 An access token representing the authorizing user's consent for 256 a host to trust a particular authorization manager for control 257 over authorizations to access protected resources hosted there. 259 claim 260 A statement of the value or values of one or more identity 261 attributes of a requesting party. Claims are conveyed by a 262 requester on behalf of a requesting party to an authorization 263 manager in an attempt to satisfy an authorizing user's policy. 265 requester 266 An UMA-defined variant of an OAuth client that seeks access to 267 a protected resource. 269 requester access token 270 An access token that can be associated with permissions to 271 access particular resources at a host on behalf of a particular 272 requesting party. 274 requesting party 275 A web user, or a corporation or other legal person, that uses a 276 requester to seek access to a protected resource. If the 277 requesting party is a natural person, it may or may not be the 278 same person as the authorizing user. 280 resource set description 281 A JSON-formatted document that represents a set of one or more 282 resources to be AM-protected and maps available scopes to them. 283 The host registers a resource set by giving this document to 284 the AM. 286 scope description A JSON-formatted document that represents a scope 287 of access on a particular resource set. The host refers to 288 this type of document from within resource set descriptions and 289 permissions that it registers. 291 token status description A JSON-formatted document that represents 292 the currently valid permissions for authorized access 293 associated with a requester access token. 295 permission A scope of access over a particular resource set at a 296 particular host that is being asked for by a requester or that 297 has been granted by an AM. 299 1.3. Endpoint Names 301 host access token endpoint Part of the protection API at the AM used 302 by the host (and part of standard OAuth). The endpoint at the 303 AM at which the host asks for a host access token on the 304 authorizing user's behalf. 306 host user authorization endpoint Part of the protection API at the 307 AM used by the host (and part of standard OAuth). The endpoint 308 at the AM to which the host redirects the authorizing user to 309 authorize the host to use this AM for protecting resources, if 310 the authorization code grant type is being used. 312 resource set registration endpoint Part of the protection API at the 313 AM used by the host. The endpoint at the AM at which the host 314 registers resource sets which it wants the AM to protect. 316 permission registration endpoint Part of the protection API at the 317 AM used by the host. The endpoint at the AM at which the host 318 registers permissions that a requester will be asking for. 320 token status endpoint Part of the protection API at the AM used by 321 the host. The endpoint at the AM at which the host submits 322 requester access tokens to learn what currently valid 323 permissions are associated with them. 325 protected resource endpoint An endpoint at the host at which a 326 requester attempts to access resources. This can be a singular 327 API endpoint, one of a set of API endpoints, a URI 328 corresponding to an HTML document, or any other Web-accessible 329 URI. 331 requester access token endpoint Part of the authorization API at the 332 AM used by the requester (and part of standard OAuth). The 333 endpoint at the AM at which the requester asks for a requester 334 access token. 336 permission endpoint Part of the authorization API at the AM used by 337 the requester. The endpoint at the AM at which the requester 338 asks for authorization to have a new permission associated with 339 its requester access token. 341 2. Protecting a Resource 343 Phase 1 of UMA is protecting a resource. For a host to be able to 344 delegate authorization of protected-resource access to an AM, the 345 authorizing user must first introduce the host to the AM. This phase 346 is concluded successfuly when: 348 o The host has received metadata about the AM, such as endpoints it 349 needs to use in interacting with the AM. 351 o The host has received an OAuth host access token that represents 352 the authorizing user's approval for the host to work with the AM 353 in protecting resources. This host access token is later used 354 when the host makes other requests at the AM's protection API. 356 o The AM has acquired information about resource sets on the host it 357 is supposed to protect on behalf of the authorizing user. 359 The user, host, and AM perform the following steps in order to 360 successfully complete Phase 1: 362 1. The host looks up the AM's metadata and learns about its 363 protection API endpoints and supported formats. 365 2. If the host has not yet obtained a unique OAuth client identifier 366 and optional secret from the AM, it registers with the AM as 367 required. It MAY do this using the OAuth dynamic registration 368 protocol (see [Dyn-Reg]) proposed by UMA WG participants, if the 369 AM supports it. 371 3. The host obtains a host access token from the AM with the 372 authorizing user's consent, using either the authorization code 373 grant type or the SAML bearer assertion grant type. 375 4. The host registers any resource sets with the AM that are 376 intended to be protected. 378 2.1. Host Looks Up AM Metadata 380 The host needs to learn the OAuth- and UMA-related endpoints of the 381 AM before they can begin interacting. The authorizing user might 382 provide the AM's location to get the host started in this process, 383 for example by typing a URL into a web form field or clicking a 384 button. Alternatively, the host might already be configured to work 385 with a single AM without requiring any user input. The exact process 386 is beyond the scope of this specification, and it is up to the host 387 to choose a method to learn the AM's location. 389 From the data provided, discovered, or configured, the host MUST 390 retrieve the hostmeta document as described in Section 2 of hostmeta 391 [hostmeta]. For example, if the user supplied "am.example.com" as 392 the Authorization Manager's domain, the host creates the URL 393 "https://am.example.com/.well-known/host-meta" and performs a GET 394 request on it. 396 2.1.1. AM Endpoints 398 The AM MUST provide an XRD 1.0-formatted document at the hostmeta 399 location, documenting the following: 401 o A set of protection API endpoints for the host to use 403 o A set of authorization API endpoints for the requester to use 405 o At least one access token format the AM produces 407 o Any claim formats the AM supports 409 Property type values for access token and claim format information: 411 http://kantarainitiative.org/ns/uma/1.0/token_formats 412 REQUIRED (one or more). Access token format produced by this 413 AM. Currently the only option is "artifact". 415 http://kantarainitiative.org/ns/uma/1.0/claim_formats 416 OPTIONAL (zero or more). Claim format supported by this AM. 417 Currently the options are "openid-connect" and "claims2". If 418 the AM is capable of requesting and accepting any claim formats 419 at all, it MUST declare them. 421 Link relationship rel values for the protection API endpoints for the 422 host to use: 424 http://kantarainitiative.org/ns/uma/1.0/host_token_uri 425 REQUIRED. The host access token endpoint. Available HTTP 426 methods are as defined by [OAuth2] for a token endpoint. 427 Supplies the endpoint the host uses to ask for a host access 428 token. 430 http://kantarainitiative.org/ns/uma/1.0/host_user_uri 431 REQUIRED. The host user authorization endpoint. Available 432 HTTP methods are as defined by OAuth for an authorization 433 endpoint. Supplies the endpoint the host uses to gather the 434 consent of the authorizing user for a host-AM relationship if 435 it is using the authorization code grant type. The AM MUST 436 support the authorization code grant type method of obtaining 437 the authorizing user's consent. 439 http://kantarainitiative.org/ns/uma/1.0/host_resource_reg_uri 440 REQUIRED. The resource set registration endpoint. Requests to 441 this endpoint require a host access token to be present. 442 Supplies the endpoint the host uses for registering resource 443 sets with the AM to be protected (see Section 2.4.4). This 444 endpoint SHOULD require the use of a transport-layer security 445 mechanism such as TLS. 447 http://kantarainitiative.org/ns/uma/1.0/host_token_status_uri 448 REQUIRED. The token status endpoint. Requests to this 449 endpoint require a host access token to be present. Supplies 450 the endpoint the host uses to request the status of access 451 tokens presented to them by requesters with respect to 452 currently valid permissions. This endpoint SHOULD require the 453 use of a transport-layer security mechanism such as TLS. 455 http://kantarainitiative.org/ns/uma/1.0/host_perm_reg_uri 456 REQUIRED. The permission registration endpoint. Requests to 457 this endpoint require a host access token to be present. 458 Supplies the endpoint the host uses for registering permissions 459 with the AM for which a requester will be seeking authorization 460 (see Section 3.4). This endpoint SHOULD require the use of a 461 transport-layer security mechanism such as TLS. 463 Link relationship rel values for the authorization API endpoints for 464 the requester to use: 466 http://kantarainitiative.org/ns/uma/1.0/req_token_uri 467 REQUIRED. The requester access token endpoint. Available HTTP 468 methods are as defined by [OAuth2] for a token issuance 469 endpoint. Supplies the endpoint the requester uses to ask for 470 an access token. This endpoint SHOULD require the use of a 471 transport-layer security mechanism such as TLS. 473 http://kantarainitiative.org/ns/uma/1.0/req_perm_uri 474 REQUIRED. The permission endpoint. Supplies the endpoint the 475 requester uses to ask for authorization to have a new 476 permission associated with its existing requester access token, 477 which MUST accompany the request. This endpoint SHOULD require 478 the use of a transport-layer security mechanism such as TLS. 480 2.1.2. Example AM Metadata 482 For example: 484 486 artifact 488 489 claims2 491 493 495 496 499 500 503 505 506 509 510 513 514 517 519 521 522 525 527 528 531 533 2.2. Host Registers with AM 535 If the host has not already obtained a unique client identifier and 536 optional secret from this AM, in this step it MUST do so in order to 537 engage in OAuth-based interactions with the AM. It MAY do this using 538 the OAuth dynamic registration protocol (see [Dyn-Reg]) proposed by 539 UMA WG participants, if the AM supports it. The AM MUST issue a 540 unique client identifier to every host. This is to ensure that 541 individual hosts can be unambiguously identified in resource set 542 registration, where the client identifier is used as a URI component. 544 2.3. Host Obtains Host Access Token 546 In this step, the host acquires a host access token from the AM that 547 represents the approval of the authorizing user for the host to trust 548 the AM for protecting resources belonging to the user. 550 The host MUST use the OAuth2 [OAuth2] authorization code grant type 551 or the SAML bearer token grant type [OAuth-SAML], utilizing the end- 552 user authorization and token endpoints as appropriate. Here the host 553 acts in the role of an OAuth client; the authorizing user acts in the 554 role of an OAuth end-user resource owner; and the AM acts in the role 555 of an OAuth authorization server. (Once the host has obtained an 556 access token, it presents it to the AM at various protection API 557 endpoints, at which point the AM acts in the role of a resource 558 server.) 560 The host has completed this step successfully when it possesses a 561 host access token it can use at the AM's protection API. 563 2.4. Host Registers Sets of Resources to Be Protected 565 Once the host has received a host access token, for any of the user's 566 sets of resources that are to be protected by this AM, it MUST 567 register these resource sets at the AM's registration endpoint. 569 Note that the host is free to offer the option to protect any subset 570 of the user's resources using different AMs or other means entirely, 571 or to protect some resources and not others. Additionally, the 572 choice of protection regimes can be made explicitly by the user or 573 implicitly by the host. Any such partitioning by the host or user is 574 outside the scope of this specification. 576 2.4.1. Example of Registering Resource Sets 578 The following example illustrates the intent and usage of resource 579 set registration. 581 This example contains some steps that are exclusively in the realm of 582 user experience rather than web protocol, to achieve realistic 583 illustration; these steps are labeled "User experience only". Some 584 other steps are exclusively internal to the operation of the entity 585 being discussed; these are labeled "Internal only". 587 An authorizing user, Alice Adams, has just uploaded a photo of her 588 new puppy to a host, Photoz.example.com, and wants to ensure that 589 this specific photo is not publicly accessible. 591 Alice has already introduced this host to her AM, 592 CopMonkey.example.com, and thus Photoz has already obtained a host 593 access token from CopMonkey. However, Alice has not previously 594 instructed Photoz to use CopMonkey to protect any other photos of 595 hers. 597 Alice has previously visited CopMonkey to map a default "do not share 598 with anyone" policy to any resource sets registered by Photoz, until 599 such time as she maps some other less-draconian policies to those 600 resources. (User experience only. This may have been done at the 601 time Alice introduced the host to the AM, and/or it could have been a 602 global or host-specific preference setting. A different constraint 603 or no constraint at all might be associated with newly protected 604 resources.) Other kinds of policies she may eventually map to 605 particular photos or albums might be "Share only with 606 husband@email.example.net" or "Share only with people in my 'family' 607 group". 609 Photoz itself has a publicly documented API that offers two dozen 610 different methods that apply to single photos, such as "addTags" and 611 "getSizes", but rolls them up into two photo-related scopes of 612 access: "viewing" (consisting of various read-only operations) and 613 "all" (consisting of various reading, editing, and printing 614 operations). It defines two Web-accessible JSON-encoded documents 615 called scope descriptions that represent these scopes, which it is 616 able to reuse for all of its users (not just Alice). 618 The "name" parameter values are intended to be seen by Alice when she 619 maps authorization constraints to specific resource sets and actions 620 while visiting CopMonkey, such that Alice would see the strings "View 621 Photo and Related Info" and "All Actions", likely accompanied by the 622 referenced icons, in the CopMonkey interface. (Other users of Photoz 623 might similarly see the same labels at CopMonkey or whatever other AM 624 they use. Photoz could distinguish natural-language labels per user 625 if it wishes, by pointing to scopes with differently translated 626 names.) 628 Example of the "view" scope ,which description is a Web-accessible 629 resource at http://photoz.example.com/dev/scopes/view: 630 { 631 "scope": 632 { 633 "_id": "view" 634 "name": "View Photo and Related Info", 635 "icon_uri": "http://www.example.com/icons/reading-glasses.png" 636 } 637 } 639 Example of the "all" scope, which description is a Web-accessible 640 resource at http://photoz.example.com/dev/scopes/all: 641 { 642 "scope": 643 { 644 "_id": "all" 645 "name": "All Actions", 646 "icon_uri": "http://www.example.com/icons/galaxy.png" 647 } 648 } 650 While visiting Photoz, Alice selects a link or button that instructs 651 the site to "Protect" or "Share" this single photo (user experience 652 only; Photoz could have made this a default or preference setting). 654 As a result, Photoz defines for itself a resource set that represents 655 this photo (internal only; Photoz is the only application that knows 656 how to map a particular photo to a particular resource set). Photoz 657 also prepares the following resource set description, which is 658 specific to Alice and her photo. The "name" parameter value is 659 intended to be seen by Alice in mapping authorization constraints to 660 specific resource sets and actions when she visits CopMonkey, such 661 that Alice would see the string "Steve the puppy!", likely 662 accompanied by the referenced icon, in the CopMonkey interface. The 663 possible scopes of access on this resource set are indicated with URI 664 references to the scope descriptions, as defined just above. 665 { 666 "resource_set": 667 { 668 "_id": "112210f47de98100" 669 "name": "Steve the puppy!", 670 "icon_uri": "http://www.example.com/icons/flower", 671 "scopes": 672 ["http://photoz.example.com/dev/scopes/view", 673 "http://photoz.example.com/dev/scopes/all"] 674 } 675 } 676 Photoz uses the "create resource set description" method of 677 CopMonkey's standard UMA resource set registration API, presenting 678 its Alice-specific host access token there, to register and assign an 679 identifier to the resource set description. The resource set 680 identifier path component of the URL matches the "_id" parameter 681 value in the description. 682 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1 683 Content-Type: application/json 684 ... 686 { 687 "resource_set": 688 { 689 "_id": "112210f47de98100" 690 "name": "Steve the puppy!", 691 "icon_uri": "http://www.example.com/icons/flower.png", 692 "scopes": 693 ["http://photoz.example.com/dev/scopes/view", 694 "http://photoz.example.com/dev/scopes/all"] 695 } 696 } 698 Once this description has been successfully registered, Photoz is 699 responsible for responding correctly to requesters' attempts to 700 access this photo, achieving protection of the resource by 701 "outsourcing" this task to CopMonkey. 703 At the time Alice indicates she would like this photo protected, 704 Photoz can choose to redirect Alice to CopMonkey for further policy 705 setting, access auditing, and other AM-related tasks (user experience 706 only). 708 Over time, as Alice uploads other photos and creates and organizes 709 photo albums, and as Photoz makes new action functionality available, 710 Photoz can use additional methods of the resource set registration 711 API to ensure that CopMonkey's understanding of Alice's protected 712 resources matches its own. 714 2.4.2. Scope Descriptions 716 The host defines a scope of access that is available for use with 717 resources it manages in a publicly Web-accessible document containing 718 a scope description. The scopes available for use at any one host 719 MUST have unique URI references so that the host's scope descriptions 720 are distinguishable by URI reference; the URI reference MAY include a 721 fragment identifier. Scope descriptions MAY reside anywhere; the 722 host is not required to self-host scope descriptions and may wish to 723 point to standardized scope descriptions residing elsewhere. 725 A scope description is a JSON [RFC4627] object with the name "scope" 726 and with the following parameters: 728 _id REQUIRED. A string that uniquely identifies the scope across 729 all scopes available at this host. 731 name REQUIRED. A human-readable string describing the scope of 732 access. The AM SHOULD use the name in its user interface to 733 assist the user in setting policies for protected resource sets 734 that have this available scope. 736 icon_uri OPTIONAL. A URI for a graphic icon representing the scope. 737 If this is provided, the AM SHOULD use the referenced icon in its 738 user interface to assist the user in setting policies for 739 protected resource sets that have this available scope. 741 For example, this description characterizes a scope that involves 742 reading or viewing resources (vs. creating them or editing them in 743 some fashion): 744 { 745 "scope": 746 { 747 "_id": "view" 748 "name": "Read-only", 749 "icon_uri": "http://www.example.com/icons/reading-glasses" 750 } 751 } 753 Scope descriptions MAY contain extension parameters that are not 754 defined in this specification. The names of extension parameters 755 MUST begin with "x-" or "X-". 757 2.4.3. Resource Set Descriptions 759 The host defines a resource set that needs protection by registering 760 a resource set description at the AM. The host registers the 761 description and manages its lifecycle at the AM's host resource set 762 registration endpoint by using the resource set registration API (see 763 Section 2.4.4). The resource set description is a JSON [RFC4627] 764 object with the name "resource_set" and with the following 765 parameters: 767 _id REQUIRED. A string that uniquely identifies the resource set. 768 The resource set identifier has meaning only to the host, except 769 insofar as the AM is able to map this resource set description to 770 a particular user by virtue of the particular host access token 771 used to access the resource set registration API. The host MAY 772 use any identifier scheme to represent resource sets, for example, 773 making its identifiers unique across all users of this host or 774 allowing for the sharing of resource set identifiers among users. 775 However, for privacy reasons, it is RECOMMENDED that the host 776 assign an identifier that is obscured with respect to any human- 777 readable resource set label used at this host. Further, this 778 identifier MUST match the resource set identifier path component 779 of the URI used to manage this description in the resource set 780 registration API; see Section 2.4.4 for more information. 781 (Typically this matching is achieved through automatically 782 populating the parameter value on initial registration of the 783 description.) 785 name REQUIRED. A human-readable string describing a set of one or 786 more resources. The AM SHOULD use the name in its user interface 787 to assist the user in setting policing for protecting this 788 resource set. 790 icon_uri OPTIONAL. A URI for a graphic icon representing the 791 resource set. If provided, the AM SHOULD use the referenced icon 792 in its user interface to assist the user in setting policies for 793 protecting this resource set. 795 scopes REQUIRED. An array referencing one or more URI references of 796 scope descriptions that are available for this resource set. 798 For example, this description characterizes a resource set (a photo 799 album) that can potentially be only viewed, or alternatively to which 800 full access can be granted; the URIs point to scopes descriptions as 801 defined in Section 2.4.2: 802 { 803 "resource_set": 804 { 805 "_id": "112210f47de98100", 806 "name": "Photo album", 807 "icon_uri": "http://www.example.com/icons/flower.png", 808 "scopes": 809 ["http://photoz.example.com/dev/scopes/view", 810 "http://photoz.example.com/dev/scopes/all"] 811 } 812 } 814 Resource set descriptions MAY contain extension parameters that are 815 not defined in this specification. The names of extension parameters 816 MUST begin with "x-" or "X-". 818 When a host creates or updates a resource set description (see 819 Section 2.4.4), the AM MUST attempt to retrieve the referenced scope 820 descriptions. It MAY cache such descriptions as long as indicated in 821 the HTTP header for the scope description resource unless the 822 resource set description is subsequently updated within the validity 823 period. At the beginning of an authorizing user's login session at 824 the AM, the AM MUST attempt to re-retrieve scope descriptions 825 applying to that user whose cached versions have expired. 827 2.4.4. Resource Set Registration API 829 The host uses a RESTful API at the AM's resource set registration 830 endpoint to create, read, update, and delete resource set 831 descriptions, along with listing groups of such descriptions. The 832 host MUST use its valid host access token obtained previously to gain 833 access to this endpoint. 835 (Note carefully the similar but distinct senses in which the word 836 "resource" is used in this section. UMA resource set descriptions 837 are themselves managed as web resources at the AM through this API.) 839 Individual resource set descriptions are managed at URIs with this 840 structure: "{rsreguri}/host/{hostid}/resource_set/{rsid}" 842 The components of these URIs are defined as follows: 844 {rsreguri} The AM's resource set registration endpoint as advertised 845 in its metadata (see Section 2.1.1). 847 {hostid} A registration area at the AM that is specific to this 848 host. The host MUST use the unique OAuth client identifier it was 849 assigned by this AM as its host identifier. If the host 850 identifier does not match the host access token used at the host 851 registration endpoint, the AM MUST report an HTTP 403 Forbidden 852 error and fail to act on the request. 854 {rsid} An identifier for a resource set description. The identifier 855 MUST match the "_id" parameter value in the description itself. 857 Without a specific resource set identifier path component, the URI 858 applies to the set of resource set descriptions already registered. 860 Following is a summary of the five registration operations the AM is 861 REQUIRED to support. Each is defined in its own section below. All 862 other methods are unsupported. 864 o Create resource set description: PUT /host/{hostid}/resource_set/ 865 {rsid} 867 o Read resource set description: GET /host/{hostid}/resource_set/ 868 {rsid} 870 o Update resource set description: PUT /host/{hostid}/resource_set/ 871 {rsid} 873 o Delete resource set description: DELETE /host/{hostid}/ 874 resource_set/{rsid} 876 o List resource set descriptions: GET /host/{hostid}/resource_set/ 878 If the request to the resource set registration endpoint is 879 incorrect, then the AM responds with an error message (see 880 Section 4.2) by including one of the following error codes with the 881 response: 883 unsupported_method_type The host request used an unsupported HTTP 884 method. The AM MUST respond with the HTTP 403 (Forbidden) status 885 code and MUST fail to act on the request. 887 hostid_access_token_mismatch The hostid does not match the presented 888 host access token. The AM MUST respond with the HTTP 403 889 (Forbidden) status code. 891 ambiguous_resource_set_id The resourcesetid provided in the resource 892 set description does not match the one provided in the URI. The 893 AM MUST respond with the HTTP 400 (Bad Request) status code and 894 MUST fail to act on the request. 896 resource_set_not_found The resource set requested from the AM cannot 897 be found. The AM MUST respond with HTTP 404 (Not Found) status 898 code. 900 resource_set_mismatch The resource set that was requested to be 901 deleted or updated at the AM did not match the ETag value present 902 in the request. The AM MUST respond with HTTP 412 (Precondition 903 Failed) status code and MUST fail to act on the request. 905 For example: 907 HTTP/1.1 403 Forbidden 908 Content-Type: application/json 909 Cache-Control: no-store 910 { 911 "error":"unsupported_method_type" 912 } 914 2.4.4.1. Create Resource Set Description 916 Adds a new resource set description using the PUT method, thereby 917 putting it under the AM's protection. The host is free to use its 918 own methods of identifying and describing resource sets; the AM MUST 919 treat them as opaque for the purpose of authorizing access, other 920 than associating them with the authorizing user represented by the 921 host access token used to access the API. On successfully 922 registering a resource set, the host MUST use UMA mechanisms to limit 923 access to any resources corresponding to this resource set, relying 924 on the AM to supply currently valid permissions for authorized 925 access. 927 HTTP request: 928 PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1 929 Content-Type: application/json 930 ... 932 (Body contains JSON representation of resource set description to be created) 934 Example of an HTTP request that creates a resource set description at 935 the AM: 936 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1 937 Content-Type: application/json 938 Host: am.example.com 940 { 941 "resource_set": 942 { 943 "_id": "112210f47de98100", 944 "name": "Photo album", 945 "icon_uri": "http://www.example.com/icons/flower.png", 946 "scopes": 947 ["http://photoz.example.com/dev/scopes/view", 948 "http://photoz.example.com/dev/scopes/all"] 949 } 950 } 952 HTTP response (success): 953 HTTP/1.1 201 Created 954 Content-Type: application/json 955 Location: (URL of created resource, same as in the PUT request) 956 ETag: (entity tag of resource artifact) 957 ... 959 (Body contains JSON representation of created resource set description) 960 Example of an HTTP response confirming the created resource set 961 description: 962 HTTP/1.1 201 Created 963 Content-Type: application/json 964 Location: https://am.example.com/rsreg_uri/host/photoz.example.com/resource_set/112210f47de98100 965 ETag: "1234sdbdDX" 966 ... 968 { 969 "resource_set": 970 { 971 "_id": "112210f47de98100", 972 "name": "Photo album", 973 "icon_uri": "http://www.example.com/icons/flower.png", 974 "scopes": 975 ["http://photoz.example.com/dev/scopes/view", 976 "http://photoz.example.com/dev/scopes/all"] 977 } 978 } 980 2.4.4.2. Read Resource Set Description 982 Reads a previously registered resource set description using the GET 983 method. 985 HTTP request: 986 GET /host/{hostid}/resource_set/{rsid} HTTP/1.1 987 ... 989 Example of an HTTP request that reads a resource set description from 990 the AM: 991 GET /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1 992 Host: am.example.com 993 ... 995 HTTP response (success): 996 HTTP/1.1 200 OK 997 Content-Type: application/json 998 ETag: (entity tag of resource artifact) 999 ... 1001 (Body contains JSON representation of resource set description) 1002 Example of an HTTP response message containing a resource set 1003 description from the AM: 1004 HTTP/1.1 200 OK 1005 Content-Type: application/json 1006 ETag: "1234sdbdDX" 1007 ... 1009 { 1010 "resource_set": 1011 { 1012 "_id": "112210f47de98100", 1013 "name": "Photo album", 1014 "icon_uri": "http://www.example.com/icons/flower.png", 1015 "scopes": 1016 ["http://photoz.example.com/dev/scopes/view", 1017 "http://photoz.example.com/dev/scopes/all"] 1018 } 1020 HTTP response (not found): 1021 HTTP/1.1 404 Not Found 1022 Content-Type: application/json 1023 ... 1025 { 1026 "error":"resource_set_not_found" 1027 } 1029 2.4.4.3. Update Resource Set Description 1031 Updates a previously registered resource set description using the 1032 PUT method, thereby changing the resource set's protection 1033 characteristics. 1035 This operation is different from the operation to create a new 1036 resource set description (Section 2.4.4.1) because it assumes that 1037 prior registration of the resource set in question has occurred. 1039 HTTP request: 1040 PUT /host/{hostid}/resource_set/{rsid} HTTP/1.1 1041 Content-Type: application/json 1042 If-Match: (entity tag of resource if operation is to be idempotent) 1043 ... 1045 (Body contains JSON representation of resource set description to be updated) 1046 Example of an HTTP request that updates a resource set description at 1047 AM: 1048 PUT /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1 1049 Content-Type: application/json 1050 Host: am.example.com 1051 If-Match: "1234sdbdDX" 1053 { 1054 "resource_set": 1055 { 1056 "_id": "112210f47de98100", 1057 "name": "Updated Photo album", 1058 "icon_uri": "http://www.example.com/icons/sun.png", 1059 "scopes": 1060 ["http://photoz.example.com/dev/scopes/view", 1061 "http://photoz.example.com/dev/scopes/all"] 1062 } 1063 } 1065 HTTP response (success): 1066 HTTP/1.1 204 No Content 1067 ETag: "54223dfda" 1068 ... 1070 HTTP response (entity tag does not match): 1071 HTTP/1.1 412 Precondition failed 1072 Content-Type: application/json 1073 ... 1075 { 1076 "error":"resource_set_mismatch" 1077 } 1079 2.4.4.4. Delete Resource Set Description 1081 Deletes a previously registered resource set description using the 1082 DELETE method, thereby removing it from the AM's protection regime. 1084 HTTP request: 1085 DELETE /host/{hostid}/resource_set/{rsid} 1086 If-Match: (entity tag of resource if operation is to be idempotent) 1087 ... 1089 Example of an HTTP request that deletes a resource set description 1090 from the AM: 1091 DELETE /host/photoz.example.com/resource_set/112210f47de98100 HTTP/1.1 1092 Host: am.example.com 1093 If-Match: "1234sdbdDX" 1094 HTTP response (success): 1095 HTTP/1.1 204 No content 1096 ... 1098 HTTP response (not found): 1099 HTTP/1.1 404 Not Found 1100 Content-Type: application/json 1101 ... 1103 { 1104 "error":"resource_set_not_found" 1105 } 1107 HTTP response (entity tag does not match): 1108 HTTP/1.1 412 Precondition failed 1109 Content-Type: application/json 1110 ... 1112 { 1113 "error":"resource_set_mismatch" 1114 } 1116 2.4.4.5. List Resource Set Descriptions 1118 Lists all previously registered resource set identifiers for this 1119 user using the GET method. The list is in the form of a JSON array 1120 of {rsid} values. 1122 HTTP request: 1123 GET /host/{hostid}/resource_set HTTP/1.1 1124 ... 1126 Example of an HTTP request that lists registered resource set 1127 descriptions at the AM: 1128 GET /host/photoz.example.com/resource_set HTTP/1.1 1129 Host: am.example.com 1130 ... 1132 HTTP response: 1133 HTTP/1.1 200 OK 1134 Content-Type: application/json 1135 ... 1137 (Body contains JSON array of {rsid} values) 1138 Example of an HTTP response with the list of registered resource set 1139 identifiers: 1140 HTTP/1.1 200 OK 1141 Content-Type: application/json 1142 ... 1144 { 1145 "resource_set_id_list": [ "112210f47de98100", "34234df47eL95300" ] 1146 } 1148 3. Getting Authorization and Accessing a Resource 1150 Phase 2 of UMA is getting authorization, and Phase 3 is accessing a 1151 resource. In these phases, an AM orchestrates and controls 1152 requesting parties' access to a user's protected resources at a host, 1153 under conditions dictated by that user. 1155 Phase 3 is merely the successful completion of a requester's access 1156 attempt (see Section 3.1.5) that initially involved several embedded 1157 interactions among the requester, AM, and host in Phase 2. Phase 2 1158 always begins with the requester attempting access at a protected 1159 resource endpoint at the host. How the requester came to learn about 1160 this endpoint is out of scope for UMA; the authorizing user might, 1161 for example, have advertised its availability publicly on a blog or 1162 other website, listed it in a discovery service, or emailed a link to 1163 a particular intended requesting party. 1165 The host responds to the requester's access request in one of several 1166 ways depending on the circumstances of the request, either 1167 immediately or having first performed one or more embedded 1168 interactions with the AM. Depending on the nature of the host's 1169 response to an failed access attempt, the requester itself engages in 1170 embedded interactions with the AM before re-attempting access. 1172 The interactions are as follows. The interaction summarized in each 1173 top-level list item MAY be the last interaction engaged in, if the 1174 requester chooses not to continue pursuing access to the resource. 1176 o The requester attempts access at a particular protected resource 1177 at a host (see Section 3.1). 1179 * If the user corresponding to the protected resource URI is 1180 ambiguous: host responds immediately with an error (see 1181 Section 3.1.1). 1183 * If the user is unambiguous but the access attempt is 1184 unaccompanied by a requester access token: host responds 1185 immediately with instructions on where to go to obtain one (see 1186 Section 3.1.2). 1188 o If the access attempt was accompanied by a requester access token, 1189 the host checks the token's status at the AM (see Section 3.3). 1191 * If the AM reports that the requester access token is invalid 1192 (see Section 3.3.2), the host responds to the requester with 1193 instructions on where to go to obtain a token (see 1194 Section 3.1.2). 1196 o If the AM supplies a token status description for a valid 1197 requester access token (see Section 3.3.1) but none of the 1198 permissions associated with the token match the scope of attempted 1199 access, the host registers a suitable permission on the 1200 requester's behalf at the AM (see Section 3.4) and then responds 1201 to the requester with instructions on where to go to request 1202 authorization to associate that permission with its token (see 1203 Section 3.1.4). 1205 o If the requester received instructions on where to get a token, it 1206 requests a token from the appropriate AM (see Section 3.2). 1208 o If the requester received instructions on where to get 1209 authorization for access permission, it requests permission from 1210 the appropriate AM (see Section 3.5). 1212 o If the AM gave status back on a valid requester access token, and 1213 at least one of the permissions associated with the token match 1214 the scope of attempted access, the host responds to the 1215 requester's access attempt with success (see Section 3.1.5). 1217 This process extends OAuth in several notable ways: 1219 o The requester access token signifies only a binding of this 1220 requester, the requesting party on whose behalf it is acting, this 1221 host, this authorizing user, and this AM, to be reused for all 1222 permissions to access any of the user's protected resources at 1223 this host that are protected by this AM. 1225 o Any real-time authorizing user (resource owner) consent required 1226 by policy is gathered at the time of claim requests, rather than 1227 at the time of token issuance; the flow does not distinguish 1228 between policies for "person-to-person" sharing and policies for 1229 "person-to-self" sharing. 1231 o The process of seeking authorization does not just rely on the 1232 requester's ability to authenticate as the (or a) resource owner, 1233 but admits a wide-ranging set of policy options based on 1234 attributes of the requesting party. This model could be called 1235 claims-based authorization. 1237 o The host is (for now) required to check with the AM in real time 1238 about the status of all tokens unseen before or whose cached 1239 status has expired. Eventually, this specification will define an 1240 interoperable way to use of structured tokens to allow AMs the 1241 opportunity to give out requester access tokens whose status hosts 1242 can check "locally". 1244 The interactions are described in detail in the following sections. 1246 3.1. Requester-Host: Attempt Access at Protected Resource 1248 This interaction assumes that the host has previously registered with 1249 an AM one or more resource sets that correspond to the resource to 1250 which access is being attempted, such that the host considers this 1251 resource to be protected by a particular AM. 1253 The requester typically attempts to access the desired resource at 1254 the host directly (for example, when a human operator of the 1255 requester software clicks on a thumbnail representation of the 1256 resource). The requester is expected to discover, or be provisioned 1257 with, knowledge of the protected resource and its location out of 1258 band. Further, the requester is expected to acquire its own 1259 knowledge about the methods made available by the host for operating 1260 on this resource (such as viewing it with a GET method, or 1261 transforming it with some complex API call) and the possible scopes 1262 of access. 1264 The host responds in one of five ways. 1266 3.1.1. Requester's Request Is Ambiguous 1268 By the nature of the requester's request for access (for example, 1269 through a URI parameter specifying a username or other identifier), 1270 the host needs to be able to detect uniquely which one of its users 1271 has the operative control over access to this resource. Without 1272 this, the host will be unable to interact with the correct AM using 1273 the correct host access token in protecting the resource. 1275 If the requester's request is ambiguous with respect to the specific 1276 user at the host, the host immediately responds with an "ambiguous- 1277 user" error message (see Section 4.2). 1279 For example: 1280 HTTP/1.1 403 Forbidden 1281 Content-Type: application/json 1282 Cache-Control: no-store 1284 { 1285 "error":"ambiguous-user" 1286 } 1288 3.1.2. Requester Presents No Access Token 1290 If the host is able to detect uniquely which one of its users has the 1291 operative control over access to the resource (see Section 3.1.1), 1292 but the requester does not present any access token with the request, 1293 the host MUST return an HTTP 400 (Bad Request) status code indicating 1294 it is an "invalid_request" (see Section 2.4.1 of [OAuth-bearer]), 1295 along with providing the AM's URI. This error indicates to the 1296 requester that the request is missing a required parameter, includes 1297 an unsupported parameter or parameter value, repeats the same 1298 parameter, uses more than one method for including an access token, 1299 or is otherwise malformed. 1301 For example: 1302 HTTP/1.1 400 Bad Request 1303 WWW-Authenticate: UMA realm="example" 1304 host_id="photoz.example.com", 1305 am_uri="http://am.example.com" 1307 3.1.3. Requester Presents an Invalid Access Token 1309 If the requester presents an access token with its request, the host 1310 asks the AM to give it the requester access token's status (see 1311 Section 3.3). If the AM reports that the token is invalid, the Host 1312 SHOULD return an HTTP 401 (Unauthorized) status code indicating it is 1313 an "invalid_token" (see Section 2.4.1 of [OAuth-bearer]), along with 1314 providing the AM's URI. This error indicates to the requester that 1315 the access token provided is expired, revoked, malformed, or invalid 1316 for other reasons. 1318 For example: 1319 HTTP/1.1 401 Unauthorized 1320 WWW-Authenticate: UMA realm="example" 1321 host_id="photoz.example.com", 1322 am_uri="http://am.example.com" 1324 3.1.4. Requester's Token Has Insufficient Permission 1326 If the requester presents an access token with its request, the host 1327 asks the AM to give it the requester access token's status (see 1328 Section 3.3). If the AM supplies a token status description for a 1329 valid requester access token, the host examines the token status 1330 description. If the token status is not, in the host's judgment, 1331 associated with any currently valid permission that applies to the 1332 scope of access attempted by the requester, the Host SHOULD register 1333 the desired permission with the AM (see Section 3.4) and then respond 1334 to the requester with the HTTP 403 (Forbidden) status code indicating 1335 that the token has "insufficient_scope" (see Section 2.4.1 of 1336 [OAuth-bearer]), along with providing the AM's URI and the permission 1337 ticket it just received from the AM. 1339 For example: 1340 HTTP/1.1 403 Forbidden 1341 WWW-Authenticate: UMA realm="example" 1342 host_id="photoz.example.com" 1343 am_uri="http://am.example.com", 1344 ticket="5454345rdsaa4543" 1346 3.1.5. Requester's Token Has Sufficient Permission 1348 If the requester presents an access token with its request, the host 1349 asks the AM to give it the requester access token's status (see 1350 Section 3.3) If the AM supplies a token status description for a 1351 valid requester access token, the host examines the token status 1352 description. If the token status, in the host's judgment, is 1353 associated with at least one currently valid permission that applies 1354 to the scope of access attempted by the requester, the host gives 1355 access to the desired resource. 1357 For example: 1358 HTTP/1.1 200 OK 1359 Content-Type: image/jpeg 1360 ... 1362 /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja 1363 3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf 1364 /bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo 1365 KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb 1367 This response constitutes the conclusion of Phase 3 of UMA. 1369 3.2. Requester-AM: Requester Obtains Access Token 1371 When a requester does not possess a valid access token to access 1372 resources of a particular user at a particular host, it requests one 1373 from the AM's requester token endpoint. 1375 The requester learns about this endpoint by retrieving the AM's 1376 hostmeta document (see Section 2.1.1) based on the "am_uri" 1377 information that was provided by the host in its previous response, 1378 as described in Section 2 of hostmeta [hostmeta]. For example, if 1379 the "am_uri" is "am.example.com", the requester creates the URI 1380 "https://am.example.com/.well-known/host-meta" and performs a GET 1381 request on it. 1383 Each such token is unique per requester; requesting party on whose 1384 behalf the requester software is operating; authorizing user; AM; and 1385 host. It is not unique per protected resource or resource set; the 1386 token represents the set of permissions for that requesting party to 1387 access potentially a large set of different resource sets with a 1388 variety of scopes. 1390 The requester SHOULD use the OAuth 2.0 client credentials 1391 authorization grant type (see Section 4.4 of [OAuth2]). 1393 In UMA, unlike in plain OAuth, obtaining an access token does not 1394 automatically convey permission for access to any protected resource. 1395 The token must first be associated with at least one suitable 1396 permission for scoped access in order for the requester to succeed in 1397 accessing the resource. 1399 If the requester does not yet have a client identifier and the AM 1400 demands requesters to have unique client identifiers, the requester 1401 MAY use the dynamic OAuth registration protocol (see [Dyn-Reg]) 1402 proposed by the UMA participants, if the AM supports it. 1404 3.3. Host-AM: Ask for Requester's Presented Access Token Status 1406 On receiving a requester access token in an access attempt, the host 1407 asks the AM for the token's status. If it has a cached token status 1408 description available that has not expired yet, it MAY use it 1409 instead. 1411 The host makes the request to the AM with a POST to the AM's token 1412 status endpoint. The body of the HTTP request message contains a 1413 JSON [RFC4627] document providing the requester access token and the 1414 IP address of the requester's request. The host MAY, at its 1415 discretion, instead supply the originating IP address indicated in 1416 the requester's X-Forwarded-For: header value. The IP address or 1417 originating IP address is advisory only; the AM MAY ignore it for 1418 purposes of its own token validation process. 1420 The host gains access to the token status endpoint by presenting its 1421 own host access token in the request. The host access token also 1422 allows the host and AM to uniquely identify the user they have in 1423 common, and therefore allows the AM to look up the correct 1424 authorizing user's policies and settings. 1426 Example of a request to the token validation endpoint that provides 1427 the host access token in the header: 1428 POST /token_status HTTP/1.1 1429 Host: am.example.com 1430 Authorization: Bearer vF9dft4qmT 1431 Content-Type: application/json 1433 { 1434 "token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" 1435 "resource_set_id":"112210f47de98100" 1436 "host_id":"photoz.example.com" 1437 "ipaddr":"192.168.1.1" 1438 } 1440 3.3.1. AM Returns a Token Status Description 1442 If the the AM finds the requester's access token to be valid, it 1443 returns the token's status in an HTTP response using the 200 OK 1444 status code, containing a JSON [RFC4627] document supplying the token 1445 status description. The token status description contains all of the 1446 permissions that are currently valid for this requester access token 1447 (and thus for the requesting party on whose behalf it is acting). 1448 The AM MAY set a cache period for the returned token status 1449 description that allows the host to reuse it over some period of time 1450 when it later sees the same requester access token. 1452 The token status description is a JSON object with the name 1453 "token_status" containing an array of zero or more permission 1454 objects, each with the following parameters: 1456 resource_set_id REQUIRED. A string that uniquely identifies the 1457 resource set, access to which has been granted to this requester 1458 on behalf of this requesting party. The identifier MUST 1459 correspond to a resource set that was previously registered as 1460 protected. 1462 scopes REQUIRED. An array referencing one or more URIs of scopes to 1463 which access was granted for this resource set. Each scope MUST 1464 correspond to a scope that was registered by this host for the 1465 referenced resource set. 1467 exp REQUIRED. An integer representing the expiration time on or 1468 after which the permission MUST NOT be accepted for authorized 1469 access. The processing of the exp parameter requires that the 1470 current date/time MUST be before the expiration date/time listed 1471 in the exp claim. Host implementers MAY provide for some small 1472 leeway, usually no more than a few minutes, to account for clock 1473 skew. 1475 Example: 1476 HTTP/1.1 200 OK 1477 Content-Type: application/json 1478 Cache-Control: no-store 1480 { 1481 "token_status": 1482 [ 1483 { 1484 "resource_set_id": "112210f47de98100", 1485 "scopes": 1486 ["http://photoz.example.com/dev/actions/view", 1487 "http://photoz.example.com/dev/actions/all"], 1488 "exp": 1300819380 1489 } 1490 ] 1491 } 1493 3.3.2. AM Returns a Token Invalid Response 1495 If the the AM finds the requester's access token to be invalid, it 1496 returns an UMA error message. 1498 The AM includes one of the following error codes in the error 1499 response: (see Section 4.2) and responds with the HTTP 400 status 1500 code: 1502 invalid_requester_token AM determined that the requester access 1503 token was not valid. 1505 expired_requester_token AM determined that the requester access 1506 token has expired. 1508 For example: 1509 HTTP/1.1 400 Bad Request 1510 Content-Type: application/json 1511 Cache-Control: no-store 1512 { 1513 "error":"invalid_requester_token" 1514 } 1516 3.4. Host-AM: Register a Permission 1518 If, in the host's judgment, the permissions returned by the AM from a 1519 token status request are insufficient to allow this requester's 1520 access attempt, the host registers a permission with the AM that it 1521 believes would be sufficient for the type of access sought. The AM 1522 returns a permission ticket for the host to give to the requester in 1523 its response (see Section 3.1.4). 1525 The host registers the permission using the POST method at the AM's 1526 permission registration endpoint, providing its host access token to 1527 get authorized access to this endpoint. The body of the HTTP request 1528 message contains a JSON [RFC4627] document providing the requester's 1529 access token and the requested permission. 1531 The requested scope is an object with the name "requested_permission" 1532 and the following parameters: 1534 resource_set_id REQUIRED. A string that uniquely identifies a 1535 resource set, access to which this requester is seeking access. 1536 The identifier MUST correspond to a resource set that was 1537 previously registered as protected. 1539 scopes REQUIRED. An array referencing one or more identifiers of 1540 scopes to which access is needed for this resource set. Each 1541 scope identifier MUST correspond to a scope that was registered by 1542 this host for the referenced resource set. 1544 Example of an HTTP request that registers a permission at the AM's 1545 permission registration endpoint: 1546 POST /host/scope_reg_uri/photoz.example.com HTTP/1.1 1547 Content-Type: application/json 1548 Host: am.example.com 1550 { 1551 "requested_permission": 1552 { 1553 "resource_set_id": "112210f47de98100", 1554 "scopes": ["http://photoz.example.com/dev/actions/view", 1555 "http://photoz.example.com/dev/actions/all"] 1556 } 1557 } 1559 On receiving the scope registration request from the Host, the AM 1560 issues a response message that has one of the possible following 1561 outputs: 1563 o A permission ticket and its expiration time (typically very 1564 short). 1566 o Error message indicating a malformed scope registration request. 1568 3.4.1. AM Returns a Permission Registration Success Response 1570 The AM responds with an HTTP 201 (Created) status code and includes 1571 the Location header in its response as well as the "ticket" parameter 1572 in the JSON-formatted body: 1574 For example: 1575 HTTP/1.1 201 Created 1576 Content-Type: application/json 1577 Location: https://am.example.com/permreg/host/photoz.example.com/5454345rdsaa4543 1579 { 1580 "ticket":"5454345rdsaa4543" 1581 } 1583 3.4.2. AM Returns a Permission Registration Error Response 1585 The AM responds with an HTTP 400 (Bad Request) status code and 1586 includes one of the following error codes with the error response 1587 (see Section 4.2): 1589 invalid_resource_set_id The provided resource set identifier was not 1590 found at the AM. 1592 invalid_scope At least one of the scopes included in the request was 1593 not registered previously by this host. 1595 invalid_requester_token The requester access token was not 1596 recognized by the AM. 1598 expired_requester_token The requester access token has expired. 1600 For example: 1601 HTTP/1.1 400 Bad Request 1602 Content-Type: application/json 1603 Cache-Control: no-store 1604 ... 1606 { 1607 "error":"invalid_resource_set_id" 1608 } 1610 3.5. Requester-AM: Request Authorization to Add Permission 1612 In this interaction, the requester asks the AM to grant authorization 1613 to associate a new permission to its access token for use at a 1614 particular host. It does this at the AM's permission endpoint by 1615 supplying the permission ticket it got from the host, along with its 1616 requester access token. The AM uses this information to look up the 1617 previously registered permission, confirm that the correct requester 1618 is asking for it, map the requested permission to operative user 1619 policies, and demand in turn that the requester convey any claims 1620 needed to support its request. 1622 The requester learns about this endpoint by retrieving the AM's 1623 hostmeta document (see Section 2.1.1) based on the "am_uri" 1624 information that was provided by the host in its previous response, 1625 as described in Section 2 of hostmeta [hostmeta]. For example, if 1626 the "am_uri" is "am.example.com", the requester creates the URI 1627 "https://am.example.com/.well-known/host-meta" and performs a GET 1628 request on it. 1630 The requester performs a GET on the permission endpoint, using the 1631 standard HTTP "Accept" header to express the acceptable media type(s) 1632 of any claims-requested response. 1634 The AM responds in one of three ways: 1636 o If the AM requires no claims (or no further claims) from the 1637 requester in order to grant authorization for the asked-for 1638 permission based on user policy, it gives a success response, 1639 indicating that the requested scope has been associated with the 1640 requester's token. 1642 o If the requester is definitively not authorized for this 1643 permission according to user policy, the AM responds with a 1644 failure response and the authorization request phase ends. 1646 o If user policy demands more information from the requester, the AM 1647 responds with a claims-requested response. The list SHOULD use 1648 the claim format media type that was indicated by the requester as 1649 acceptable. 1651 The claims-requested list MAY contain internal logic that gives a 1652 choice or other variability around the sets of claims that will 1653 satisfy the request. This potentially allows the requester to select 1654 a subset of claims to supply in order to obtain the needed 1655 permission. 1657 If claims are requested and the requester wishes to provide them, it 1658 POSTs another permission request, providing one or more claims or 1659 references to one or more locations where the AM can go to retrieve 1660 claims. 1662 The AM responds with a successful or unsuccessful access token 1663 response, or with another claims-requested response. This loop can 1664 be run through as many times as necessary for the AM to request 1665 further claims and the requester to supply them, re-asking for 1666 authorization to get the needed permission at every juncture. 1668 If the content-type of the request is not recognized by the AM, the 1669 AM MUST reject the document. 1671 This specification does not define the formats of claims-requested 1672 lists and appropriate responses. It may ultimately put minimum 1673 conformance requirements on requesters and AMs to handle particular 1674 claim formats defined in other specifications, as well as specifying 1675 requirements that claim formats seeking consideration for use in UMA 1676 must meet. Two candidate solutions, corresponding to claim formats 1677 the AM can declare in its metadata (Section 2.1.1), are: 1679 o [OpenID-Connect-Fmwk] (see Section 3.5.1 below for further 1680 context). 1682 o [Claims2.0] and [SAAC]. 1684 3.5.1. Trusted Claims with OpenID Connect 1686 It is hoped that UMA can profile the emerging OpenID Connect protocol 1687 as a mechanism to support access control to enable specific use cases 1688 in which the decision to grant access is made based on trusted (often 1689 third-party-asserted) claims about the requesting party, such as 1690 name, age, email address, role, and location. 1692 OpenID Connect provides authentication, authorization, and attribute 1693 transmission capability. The integration approach would treat the 1694 claims-seeking UMA AM as an OpenID relying party and OpenID Connect 1695 claims client, leveraging OpenID Connect mechanisms to transmit 1696 claims from distributed sources. 1698 In this scenario, the relying party interface is responsible for 1699 authenticating the subject (the UMA requesting party) and 1700 initializing the OpenID Connect protocol. The claims client 1701 interface is responsible for requesting claims based on OpenID 1702 Connect protocol, in order to satisfy the UMA authorizing user's 1703 policy. The client interacts with the OpenID Connect authorization 1704 server to obtain a specific access token to access to the subject's 1705 (UMA requesting party's) UserInfo endpoint (trusted claims provider). 1707 4. Error Messages 1709 Ultimately the host is responsible for either granting the access the 1710 requester attempted, or returning an error response to the requester 1711 with a reason for the failure. [OAuth2] defines several error 1712 responses for a resource server to return. UMA makes use of these 1713 error responses, but requires the host to "outsource" the 1714 determination of some error conditions to the AM. UMA defines its 1715 own additional error responses that the AM may give to the host and 1716 requester as they interact with it, and that the host may give to the 1717 requester. 1719 4.1. OAuth Error Responses 1721 When a client (host or requester) attempts to access one of the AM 1722 endpoints Section 2.1.1 or a client (requester) attempts to access a 1723 protected resource at the host, it has to make an authenticated 1724 request by including an OAuth access token in the HTTP request as 1725 described in [OAuth2] Section 7. 1727 If the client's request failed authentication, the AM or the host 1728 responds with an OAuth error message as described throughout 1729 Section 2 and Section 3. 1731 4.2. UMA Error Responses 1733 When a client (host or requester) attempts to access one of the AM 1734 endpoints Section 2.1.1 or a client (requester) attempts to access a 1735 protected resource at the host, if the client request is successfully 1736 authenticated by OAuth means, but is invalid for another reason, the 1737 AM or host responds with an UMA error response by adding the 1738 following parameters to the entity body of the HTTP response using 1739 the "application/json" media type: 1741 error REQUIRED. A single error code. Value for this parameter is 1742 defined in the specific AM endpoint description. 1744 error_description OPTIONAL. A human-readable text providing 1745 additional information, used to assist in the understanding and 1746 resolution of the error occurred. 1748 error_uri OPTIONAL. A URI identifying a human-readable web page 1749 with information about the error, used to provide the end-user 1750 with additional information about the error. 1752 Common error codes: 1754 invalid_request The request is missing a required parameter or is 1755 otherwise malformed. The AM MUST respond with the HTTP 400 (Bad 1756 Request) status code. 1758 For example: 1759 HTTP/1.1 400 Bad Request 1760 Content-Type: application/json 1761 Cache-Control: no-store 1762 ... 1764 { 1765 "error":"invalid_request", 1766 "error_description":"There is already a resource with this identifier.", 1767 "error_uri":"http://am.example.com/errors/resource_exists" 1768 } 1770 5. Security Considerations 1772 This specification relies mainly on OAuth security mechanisms for 1773 protecting the host registration endpoint at the AM so that only a 1774 properly authorized host can access it on behalf of the intended 1775 user. For example, the host needs to use a valid host access token 1776 issued through a user authorization process at the endpoint, and the 1777 interaction SHOULD take place over TLS. It is expected that the host 1778 will protect its client secret (if it was issued one) and its host 1779 access token, particularly if used in "bearer token" fashion. 1781 In addition, this specification dictates a binding between the host 1782 access token and the host-specific registration area on the AM to 1783 prevent a host from interacting with a registration area not its own. 1785 For information about the technical, operational, and legal elements 1786 of trust establishment between UMA entities and parties, which 1787 affects security considerations, see [UMA-trustmodel]. 1789 6. Privacy Considerations 1791 The AM comes to be in possession of resource set information (such as 1792 names and icons) that may reveal information about the user, which 1793 the AM's trust relationship with the host is assumed to accommodate. 1794 However, the requester is a less-trusted party (in fact, entirely 1795 untrustworthy until it acquires a requester access token in UMA 1796 protocol step 2). This specification recommends obscuring resource 1797 set identifiers in order to avoid leaking personally identifiable 1798 information to requesters through the "scope" mechanism. 1800 For information about the technical, operational, and legal elements 1801 of trust establishment between UMA entities and parties, which 1802 affects privacy considerations, see [UMA-trustmodel]. 1804 7. Conformance 1806 This section outlines conformance requirements for various entities 1807 implementing UMA endpoints. 1809 This specification has dependencies on other specifications, as 1810 follows: 1812 o OAuth 2.0: AMs, hosts, and requesters MUST support OAuth 2.0 1813 features named in this specification for conformance. For 1814 example, AMs MUST support the authorization code grant type for 1815 being introduced to hosts by authorizing users. 1817 o hostmeta: AMs, hosts, and requesters MUST support the hostmeta 1818 features named in this specification for conformance. 1820 8. IANA Considerations 1822 TBD 1824 9. Acknowledgments 1826 The contributors to this specification include the Kantara UMA Work 1827 Group participants, a list of whom can be found at [UMAnitarians]. 1829 10. Issues 1831 Catalog of currently known issues. 1833 o ISSUE#14: Need to unify the request for authorization with the 1834 providing of claims, so that this can be a single request-response 1835 pattern that can loop as required. 1837 o ISSUE#15: If the content-type (of the claims response document) is 1838 not recognized by the AM, what happens then? Should be an error 1839 from the AM. We need to create an error for this. 1841 o ISSUE#16: Need to profile for specific claims-requested lists and 1842 claim responses. 1844 o ISSUE#17: Need to say what claims formats are supported. 1846 o ISSUE#18: Provide commentary on any requirements layered on the 1847 forthcoming OAuth security considerations section; discuss UMA- 1848 layer implications for more meaningful authentication of 1849 requesters/requesting parties; discuss implications of user- 1850 mediated AM/host trust model; discuss short-lived token technique 1851 for lightweight requester correlation... 1853 o ISSUE#19: More privacy considerations. 1855 o ISSUE#24: From Lukasz email 6/6/2011: Rev8 Section 4.1: Empty 1856 response body? In SAM we return 'resource_id' and 'policy_uri' so 1857 that the host can redirect the user to the policy definition page 1858 (sharing setting screen) on AM. 1860 o ISSUE#25: From Lukasz email 6/6/2011: Section 4.1 - what happens 1861 when a resource (being registered) already exists? 1863 o ISSUE#27: Can Update Resource Set Description API mistakenly 1864 overwrite/destroy an existing resource description? 1866 o ISSUE #32: RESOLVED in Rev 13: Need to add back detail on how the 1867 host tells the requester which AM to go to so that it can discover 1868 the token endpoint and authorization endpoint. Lukasz and Maciej 1869 will flesh this out with their own message examples. I think we 1870 still need to explain explicitly how the requester has to 1871 construct the hostmeta URI. 1873 o ISSUE #33: Should it be possible to have an "implicit resource 1874 set" somehow that (in syntactic-sugar fashion) allows permissions 1875 to be passed around much as scopes already are passed around in 1876 plain OAuth? 1878 o ISSUE #35: Consider allowing the host to provide a filter in the 1879 token validation request to indicate the particular resource sets/ 1880 scopes it would find acceptable, so that the AM can provide only 1881 permissions that potentially match any of them. This approaches a 1882 PDP/PEP model. 1884 o ISSUE #36: Okay to use the made-up URI 1885 "http://kantarainitiative.org/ns/uma/1.0/..." for labeling the AM 1886 endpoints and other identifying URIs? Should these actually 1887 resolve to anything? 1889 o ISSUE #37: Okay to cache token status as now explained? Do we 1890 need to add examples if so? 1892 o ISSUE #38: Does the returned permission ticket need an expiration 1893 field? 1895 o ISSUE #39: Examine all MAYs/SHOULDs throughout the spec to see 1896 what conformance instructions/levels may be necessary. E.g., in 1897 Section 3.1.3, why is the host's 401 Unauthorized response to a 1898 requester with an invalid token a SHOULD instead of a MUST? When 1899 would it ever do something different? Similarly, Section 3.1.4, 1900 why are the host's actions in the case of insufficient permission 1901 a SHOULD instead of a MUST? Is it a case of the host deciding to 1902 just not respond at all? In Section 3.2, why do we say the 1903 requester SHOULD use the client credentials authorization grant 1904 type instead of MUST? 1906 o ISSUE #40: MUST the host give access if the requester has suitable 1907 permission? 1909 o ISSUE #41: MUST the host register a permission? If it doesn't 1910 want to, or doesn't succeed in doing so, MUST it respond to the 1911 requester, and if so, should the ticket (and even the am_uri) 1912 field be optional? 1914 11. References 1916 11.1. Normative References 1918 [Dyn-Reg] Scholz, C., "OAuth Dynamic Client Registration Protocol", 1919 2010, . 1922 [OAuth-SAML] 1923 Campbell, B., "SAML 2.0 Bearer Assertion Grant Type 1924 Profile for OAuth 2.0", February 2011, . 1927 [OAuth-bearer] 1928 Jones, M., "The OAuth 2.0 Protocol: Bearer Tokens", 1929 June 2011, 1930 . 1933 [OAuth2] Hammer-Lahav, E., "The OAuth 2.0 Protocol", 2010, 1934 . 1936 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1937 Requirement Levels", BCP 14, RFC 2119, March 1997. 1939 [RFC4627] Crockford, D., "The application/json Media Type for 1940 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1942 [hostmeta] 1943 Hammer-Lahav, E., "Web Host Metadata", May 2011, 1944 . 1946 11.2. Informative References 1948 [Claims2.0] 1949 Maler, E., "Claims 2.0", 2010, . 1952 [OpenID-Connect-Fmwk] 1953 Sakimura, N., "OpenID Connect Framework 1.0", June 2011, < 1954 http://openid.net/specs/ 1955 openid-connect-framework-1_0.html>. 1957 [SAAC] Maler, E., "Simple Access Authorization Claims", 1958 April 2010, . 1961 [UMA-trustmodel] 1962 Maler, E., "UMA Trust Model", February 2011, . 1966 [UMA-usecases] 1967 Maler, E., "UMA Scenarios and Use Cases", October 2010, . 1971 [UMA-userstories] 1972 Maler, E., "UMA User Stories", November 2010, . 1976 [UMAnitarians] 1977 Maler, E., "UMA Participant Roster", 2011, . 1981 Appendix A. Document History 1983 NOTE: To be removed by RFC editor before publication as an RFC 1985 Authors' Addresses 1987 Thomas Hardjono (editor) 1988 MIT 1990 Email: hardjono@mit.edu 1992 Christian Scholz 1993 COM.lounge GmbH 1995 Email: cs@comlounge.net 1996 URI: http://comlounge.net 1998 Paul Bryan 1999 pbryan.net 2001 Email: email@pbryan.net 2002 URI: http://pbryan.net 2003 Maciej Machulak 2004 Newcastle University 2006 Email: m.p.machulak@ncl.ac.uk 2007 URI: http://ncl.ac.uk/ 2009 Eve Maler 2010 XMLgrrl.com 2012 Email: eve@xmlgrrl.com 2013 URI: http://www.xmlgrrl.com/ 2015 Lukasz Moren 2016 Newcastle University 2018 Email: lukasz.moren@ncl.ac.uk 2019 URI: http://ncl.ac.uk/