idnits 2.17.1 draft-ietf-gnap-core-protocol-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 82 instances of too long lines in the document, the longest one being 27 characters in excess of 72. ** The abstract seems to contain references ([RFC2119], [RFC8174]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (17 October 2020) is 1285 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) == Unused Reference: 'RFC8693' is defined on line 4539, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-00 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-01 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-06 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GNAP J. Richer, Ed. 3 Internet-Draft Bespoke Engineering 4 Intended status: Standards Track 17 October 2020 5 Expires: 20 April 2021 7 Grant Negotiation and Authorization Protocol 8 draft-ietf-gnap-core-protocol-00 10 Abstract 12 This document defines a mechanism for delegating authorization to a 13 piece of software, and conveying that delegation to the software. 14 This delegation can include access to a set of APIs as well as 15 information passed directly to the software. 17 This document has been prepared by the GNAP working group design team 18 of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and 19 Justin Richer. This document is intended as a starting point for the 20 working group and includes decision points for discussion and 21 agreement. Many of the features in this proposed protocol can be 22 accomplished in a number of ways. Where possible, the editor has 23 included notes and discussion from the design team regarding the 24 options as understood. 26 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 27 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 28 "OPTIONAL" in this document are to be interpreted as described in 29 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 30 capitals, as shown here. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 20 April 2021. 49 Copyright Notice 51 Copyright (c) 2020 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.2. Elements . . . . . . . . . . . . . . . . . . . . . . . . 6 68 1.3. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 69 1.3.1. Redirect-based Interaction . . . . . . . . . . . . . 10 70 1.3.2. User-code Interaction . . . . . . . . . . . . . . . . 12 71 1.3.3. Asynchronous Authorization . . . . . . . . . . . . . 14 72 1.3.4. Software-only Authorization . . . . . . . . . . . . . 15 73 1.3.5. Refreshing an Expired Access Token . . . . . . . . . 16 74 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 17 75 2.1. Requesting Resources . . . . . . . . . . . . . . . . . . 19 76 2.1.1. Requesting a Single Access Token . . . . . . . . . . 19 77 2.1.2. Requesting Resources By Reference . . . . . . . . . . 21 78 2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 23 79 2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 25 80 2.2. Requesting User Information . . . . . . . . . . . . . . . 27 81 2.3. Identifying the RC . . . . . . . . . . . . . . . . . . . 28 82 2.3.1. Identifying the RC Instance . . . . . . . . . . . . . 30 83 2.3.2. Identifying the RC Key . . . . . . . . . . . . . . . 31 84 2.3.3. Providing Displayable RC Information . . . . . . . . 32 85 2.3.4. Authenticating the RC . . . . . . . . . . . . . . . . 33 86 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33 87 2.4.1. Identifying the User by Reference . . . . . . . . . . 34 88 2.5. Interacting with the User . . . . . . . . . . . . . . . . 35 89 2.5.1. Redirect to an Arbitrary URL . . . . . . . . . . . . 37 90 2.5.2. Open an Application-specific URL . . . . . . . . . . 37 91 2.5.3. Receive a Callback After Interaction . . . . . . . . 38 92 2.5.4. Display a Short User Code . . . . . . . . . . . . . . 42 93 2.5.5. Indicate Desired Interaction Locales . . . . . . . . 42 94 2.5.6. Extending Interaction Modes . . . . . . . . . . . . . 42 95 2.6. Declaring RC Capabilities . . . . . . . . . . . . . . . . 43 96 2.7. Referencing an Existing Grant Request . . . . . . . . . . 43 97 2.8. Requesting OpenID Connect Claims . . . . . . . . . . . . 43 98 2.9. Extending The Grant Request . . . . . . . . . . . . . . . 44 99 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 45 100 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 46 101 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 102 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 48 103 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 50 104 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 51 105 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 51 106 3.3.2. Launch of an application URL . . . . . . . . . . . . 52 107 3.3.3. Post-interaction Callback to an RC URL . . . . . . . 52 108 3.3.4. Display of a Short User Code . . . . . . . . . . . . 53 109 3.3.5. Extending Interaction Mode Responses . . . . . . . . 54 110 3.4. Returning User Information . . . . . . . . . . . . . . . 54 111 3.5. Returning Dynamically-bound Reference Handles . . . . . . 56 112 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 58 113 3.7. Extending the Response . . . . . . . . . . . . . . . . . 58 114 4. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 58 115 4.1. Interaction at a Redirected URI . . . . . . . . . . . . . 59 116 4.2. Interaction at the User Code URI . . . . . . . . . . . . 59 117 4.3. Interaction through an Application URI . . . . . . . . . 60 118 4.4. Post-Interaction Completion . . . . . . . . . . . . . . . 60 119 4.4.1. Completing Interaction with a Browser Redirect to the 120 Callback URI . . . . . . . . . . . . . . . . . . . . 61 121 4.4.2. Completing Interaction with a Direct HTTP Request 122 Callback . . . . . . . . . . . . . . . . . . . . . . 62 123 4.4.3. Calculating the interaction hash . . . . . . . . . . 62 124 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 64 125 5.1. Continuing After a Completed Interaction . . . . . . . . 66 126 5.2. Continuing During Pending Interaction . . . . . . . . . . 67 127 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69 128 5.4. Getting the Current State of a Grant Request . . . . . . 74 129 5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 130 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75 131 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76 132 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78 133 7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 79 134 8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 135 8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 81 136 8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 84 137 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 86 138 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 88 139 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 89 140 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 91 141 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 92 142 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 93 143 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 94 144 10.2. Deriving a downstream token . . . . . . . . . . . . . . 95 145 10.3. Registering a Resource Handle . . . . . . . . . . . . . 97 146 10.4. Requesting a Resources With Insufficient Access . . . . 98 147 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 98 148 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99 149 13. Security Considerations . . . . . . . . . . . . . . . . . . . 99 150 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 99 151 15. Normative References . . . . . . . . . . . . . . . . . . . . 99 152 Appendix A. Document History . . . . . . . . . . . . . . . . . . 101 153 Appendix B. Component Data Models . . . . . . . . . . . . . . . 105 154 Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 105 155 C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 106 156 C.2. Secondary Device Interaction . . . . . . . . . . . . . . 110 157 Appendix D. No User Involvement . . . . . . . . . . . . . . . . 113 158 D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 114 159 D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 117 160 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 118 161 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 119 163 1. Protocol 165 This protocol allows a piece of software, the resource client, to 166 request delegated authorization to resource servers and direct 167 information. This delegation is facilitated by an authorization 168 server usually on behalf of a resource owner. The requesting party 169 operating the software may interact with the authorization server to 170 authenticate, provide consent, and authorize the request. 172 The process by which the delegation happens is known as a grant, and 173 the GNAP protocol allows for the negotiation of the grant process 174 over time by multiple parties acting in distinct roles. 176 This protocol solves many of the same use cases as OAuth 2.0 177 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 178 have grown up around that ecosystem. However, GNAP is not an 179 extension of OAuth 2.0 and is not intended to be directly compatible 180 with OAuth 2.0. GNAP seeks to provide functionality and solve use 181 cases that OAuth 2.0 cannot easily or cleanly address. Even so, GNAP 182 and OAuth 2.0 will exist in parallel for many deployments, and 183 considerations have been taken to facilitate the mapping and 184 transition from legacy systems to GNAP. Some examples of these can 185 be found in Appendix D.2. 187 1.1. Roles 189 The parties in the GNAP protocol perform actions under different 190 roles. Roles are defined by the actions taken and the expectations 191 leveraged on the role by the overall protocol. 193 Authorization Server (AS) Manages the requested delegations for the 194 RO. The AS issues tokens and directly delegated information to 195 the RC. The AS is defined by its grant endpoint, a single URL 196 that accepts a POST request with a JSON payload. The AS could 197 also have other endpoints, including interaction endpoints and 198 user code endpoints, and these are introduced to the RC as needed 199 during the delegation process. 201 Resource Client (RC, aka "client") Requests tokens from the AS and 202 uses tokens at the RS. An instance of the RC software is 203 identified by its key, which can be known to the AS prior to the 204 first request. The AS determines which policies apply to a given 205 RC, including what it can request and on whose behalf. 207 Resource Server (RS, aka "API") Accepts tokens from the RC issued by 208 the AS and serves delegated resources on behalf of the RO. There 209 could be multiple RSs protected by the AS that the RC will call. 211 Resource Owner (RO) Authorizes the request from the RC to the RS, 212 often interactively at the AS. 214 Requesting Party (RQ, aka "user") Operates and interacts with the 215 RC. 217 The GNAP protocol design does not assume any one deployment 218 architecture, but instead attempts to define roles that can be 219 fulfilled in a number of different ways for different use cases. As 220 long as a given role fulfills all of its obligations and behaviors as 221 defined by the protocol, GNAP does not make additional requirements 222 on its structure or setup. 224 Multiple roles can be fulfilled by the same party, and a given party 225 can switch roles in different instances of the protocol. For 226 example, the RO and RQ in many instances are the same person, where a 227 user is authorizing the RC to act on their own behalf at the RS. In 228 this case, one party fulfills both of the RO and RQ roles, but the 229 roles themselves are still defined separately from each other to 230 allow for other use cases where they are fulfilled by different 231 parties. 233 For another example, in some complex scenarios, an RS receiving 234 requests from one RC can act as an RC for a downstream secondary RS 235 in order to fulfill the original request. In this case, one piece of 236 software is both an RS and an RC from different perspectives, and it 237 fulfills these roles separately as far as the overall protocol is 238 concerned. 240 A single role need not be deployed as a monolithic service. For 241 example, An RC could have components that are installed on the RQ's 242 device as well as a back-end system that it communicates with. If 243 both of these components participate in the delegation protocol, they 244 are both considered part of the RC. 246 For another example, an AS could likewise be built out of many 247 constituent components in a distributed architecture. The component 248 that the RC calls directly could be different from the component that 249 the the RO interacts with to drive consent, since API calls and user 250 interaction have different security considerations in many 251 environments. Furthermore, the AS could need to collect identity 252 claims about the RO from one system that deals with user attributes 253 while generating access tokens at another system that deals with 254 security rights. From the perspective of GNAP, all of these are 255 pieces of the AS and together fulfill the role of the AS as defined 256 by the protocol. 258 [[ Editor's note: The names for the roles are an area of ongoing 259 discussion within the working group, as is the appropriate precision 260 of what activities and expectations a particular role covers. In 261 particular, the AS might be formally decomposed into delegation 262 components, that the client talks to, and interaction components, 263 that the user talks to. Several alternative names have been proposed 264 for different roles and components, including: 266 * Grant Server (for Authorization Server) 268 * Grant Client (for Resource Client) 270 * Operator (for Requesting Party) 272 ]] 274 1.2. Elements 276 In addition to the roles above, the protocol also involves several 277 elements that are acted upon by the roles throughout the process. 279 Access Token A credential representing a set of access rights 280 delegated to the RC. The access token is created by the AS, 281 consumed and verified by the RS, and issued to and carried by the 282 RC. The contents and format of the access token are opaque to the 283 RC. 285 Grant The process by which a the RC requests and is given delegated 286 access to the RS by the AS through the authority of the RO. 288 Key A cryptographic element binding a request to the holder of the 289 key. Access tokens and RC instances can be associated with 290 specific keys. 292 Resource A protected API served by the RS and accessed by the RC. 293 Access to this resource is delegated by the RO as part of the 294 grant process. 296 Subject Information Information about the RO that is returned 297 directly to the RC from the AS without the RC making a separate 298 call to an RS. Access to this information is delegated by the RO 299 as part of the grant process. 301 [[ Editor's note: What other core elements need an introduction here? 302 These aren't roles to be taken on by different parties, nor are they 303 descriptions of the possible configurations of parties, but these are 304 still important moving parts within the protocol. ]] 306 1.3. Sequences 308 The GNAP protocol can be used in a variety of ways to allow the core 309 delegation process to take place. Many portions of this process are 310 conditionally present depending on the context of the deployments, 311 and not every step in this overview will happen in all circumstances. 313 Note that a connection between roles in this process does not 314 necessarily indicate that a specific protocol message is sent across 315 the wire between the components fulfilling the roles in question, or 316 that a particular step is required every time. For example, for an 317 RC interested in only getting subject information directly, and not 318 calling an RS, all steps involving the RS below do not apply. 320 In some circumstances, the information needed at a given stage is 321 communicated out-of-band or is pre-configured between the components 322 or entities performing the roles. For example, one entity can fulfil 323 multiple roles, and so explicit communication between the roles is 324 not necessary within the protocol flow. 326 +------------+ +------------+ 327 | Requesting | ~ ~ ~ ~ ~ ~ | Resource | 328 | Party (RQ) | | Owner (RO) | 329 +------------+ +------------+ 330 + + 331 + + 332 (A) (B) 333 + + 334 + + 335 +--------+ + +------------+ 336 |Resource|--------------(1)------+------>| Resource | 337 | Client | + | Server | 338 | (RC) | +---------------+ | (RS) | 339 | |--(2)->| Authorization | | | 340 | |<-(3)--| Server | | | 341 | | | (AS) | | | 342 | |--(4)->| | | | 343 | |<-(5)--| | | | 344 | |--------------(6)------------->| | 345 | | | |<~(7)~~| | 346 | |<-------------(8)------------->| | 347 | |--(9)->| | | | 348 | |<-(10)-| | | | 349 | |--------------(11)------------>| | 350 | | | |<~(12)~| | 351 | |-(13)->| | | | 352 | | | | | | 353 +--------+ +---------------+ +------------+ 355 Legend 356 + + + indicates a possible interaction with a human 357 ----- indicates an interaction between protocol roles 358 ~ ~ ~ indicates a potential equivalence or out-of-band communication between roles 360 * (A) The RQ interacts with the RC to indicate a need for resources 361 on behalf of the RO. This could identify the RS the RC needs to 362 call, the resources needed, or the RO that is needed to approve 363 the request. Note that the RO and RQ are often the same entity in 364 practice. 366 * (1) The RC attempts to call the RS (Section 10.4) to determine 367 what access is needed. The RS informs the RC that access can be 368 granted through the AS. Note that for most situations, the RC 369 already knows which AS to talk to and which kinds of access it 370 needs. 372 * (2) The RC requests access at the AS (Section 2). 374 * (3) The AS processes the request and determines what is needed to 375 fulfill the request. The AS sends its response to the RC 376 (Section 3). 378 * (B) If interaction is required, the AS interacts with the RO 379 (Section 4) to gather authorization. The interactive component of 380 the AS can function using a variety of possible mechanisms 381 including web page redirects, applications, challenge/response 382 protocols, or other methods. The RO approves the request for the 383 RC being operated by the RQ. Note that the RO and RQ are often 384 the same entity in practice. 386 * (4) The RC continues the grant at the AS (Section 5). 388 * (5) If the AS determines that access can be granted, it returns a 389 response to the RC (Section 3) including an access token 390 (Section 3.2) for calling the RS and any directly returned 391 information (Section 3.4) about the RO. 393 * (6) The RC uses the access token (Section 7) to call the RS. 395 * (7) The RS determines if the token is sufficient for the request 396 by examining the token, potentially calling the AS (Section 10.1). 397 Note that the RS could also examine the token directly, call an 398 internal data store, execute a policy engine request, or any 399 number of alternative methods for validating the token and its 400 fitness for the request. 402 * (8) The RC to call the RS (Section 7) using the access token until 403 the RS or RC determine that the token is no longer valid. 405 * (9) When the token no longer works, the RC fetches an updated 406 access token (Section 6.1) based on the rights granted in (5). 408 * (10) The AS issues a new access token (Section 3.2) to the RC. 410 * (11) The RC uses the new access token (Section 7) to call the RS. 412 * (12) The RS determines if the new token is sufficient for the 413 request by examining the token, potentially calling the AS 414 (Section 10.1). 416 * (13) The RC disposes of the token (Section 6.2) once the RC has 417 completed its access of the RS and no longer needs the token. 419 The following sections and Appendix C contain specific guidance on 420 how to use the GNAP protocol in different situations and deployments. 422 1.3.1. Redirect-based Interaction 424 In this example flow, the RC is a web application that wants access 425 to resources on behalf of the current user, who acts as both the 426 requesting party (RQ) and the resource owner (RO). Since the RC is 427 capable of directing the user to an arbitrary URL and receiving 428 responses from the user's browser, interaction here is handled 429 through front-channel redirects using the user's browser. The RC 430 uses a persistent session with the user to ensure the same user that 431 is starting the interaction is the user that returns from the 432 interaction. 434 +--------+ +--------+ +------+ 435 | RC | | AS | | RO | 436 | | | | | + | 437 | |< (1) + Start Session + + + + + + + + + + + + + + + +| RQ | 438 | | | | |(User)| 439 | |--(2)--- Request Access --------->| | | | 440 | | | | | | 441 | |<-(3)-- Interaction Needed -------| | | | 442 | | | | | | 443 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 444 | | | | | | 445 | | | |<+ (5) +>| | 446 | | | | AuthN | | 447 | | | | | | 448 | | | |<+ (6) +>| | 449 | | | | AuthZ | | 450 | | | | | | 451 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 452 | | | | +------+ 453 | |--(8)--- Continue Request ------->| | 454 | | | | 455 | |<-(9)----- Grant Access ----------| | 456 | | | | 457 +--------+ +--------+ 459 1. The RC establishes a verifiable session to the user, in the role 460 of the RQ. 462 2. The RC requests access to the resource (Section 2). The RC 463 indicates that it can redirect to an arbitrary URL 464 (Section 2.5.1) and receive a callback from the browser 465 (Section 2.5.3). The RC stores verification information for its 466 callback in the session created in (1). 468 3. The AS determines that interaction is needed and responds 469 (Section 3) with a URL to send the user to (Section 3.3.1) and 470 information needed to verify the callback (Section 3.3.3) in (7). 471 The AS also includes information the RC will need to continue the 472 request (Section 3.1) in (8). The AS associates this 473 continuation information with an ongoing request that will be 474 referenced in (4), (6), and (8). 476 4. The RC stores the verification and continuation information from 477 (3) in the session from (1). The RC then redirects the user to 478 the URL (Section 4.1) given by the AS in (3). The user's browser 479 loads the interaction redirect URL. The AS loads the pending 480 request based on the incoming URL generated in (3). 482 5. The user authenticates at the AS, taking on the role of the RO. 484 6. As the RO, the user authorizes the pending request from the RC. 486 7. When the AS is done interacting with the user, the AS redirects 487 the user back (Section 4.4.1) to the RC using the callback URL 488 provided in (2). The callback URL is augmented with an 489 interaction reference that the AS associates with the ongoing 490 request created in (2) and referenced in (4). The callback URL 491 is also augmented with a hash of the security information 492 provided in (2) and (3). The RC loads the verification 493 information from (2) and (3) from the session created in (1). 494 The RC calculates a hash (Section 4.4.3) based on this 495 information and continues only if the hash validates. Note that 496 the RC needs to ensure that the parameters for the incoming 497 request match those that it is expecting from the session created 498 in (1). The RC also needs to be prepared for the RQ never being 499 returned to the RC and handle time outs appropriately. 501 8. The RC loads the continuation information from (3) and sends the 502 interaction reference from (7) in a request to continue the 503 request (Section 5.1). The AS validates the interaction 504 reference ensuring that the reference is associated with the 505 request being continued. 507 9. If the request has been authorized, the AS grants access to the 508 information in the form of access tokens (Section 3.2) and direct 509 subject information (Section 3.4) to the RC. 511 An example set of protocol messages for this method can be found in 512 Appendix C.1. 514 1.3.2. User-code Interaction 516 In this example flow, the RC is a device that is capable of 517 presenting a short, human-readable code to the user and directing the 518 user to enter that code at a known URL. The RC is not capable of 519 presenting an arbitrary URL to the user, nor is it capable of 520 accepting incoming HTTP requests from the user's browser. The RC 521 polls the AS while it is waiting for the RO to authorize the request. 522 The user's interaction is assumed to occur on a secondary device. In 523 this example it is assumed that the user is both the RQ and RO, 524 though the user is not assumed to be interacting with the RC through 525 the same web browser used for interaction at the AS. 527 +--------+ +--------+ +------+ 528 | RC | | AS | | RO | 529 | |--(1)--- Request Access --------->| | | + | 530 | | | | | RQ | 531 | |<-(2)-- Interaction Needed -------| | |(User)| 532 | | | | | | 533 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 534 | | | | | | 535 | | | |<+ (4) + | | 536 | | | |Open URI | | 537 | | | | | | 538 | | | |<+ (5) +>| | 539 | | | | AuthN | | 540 | |--(9)--- Continue Request (A) --->| | | | 541 | | | |<+ (6) +>| | 542 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 543 | | | | | | 544 | | | |<+ (7) +>| | 545 | | | | AuthZ | | 546 | | | | | | 547 | | | |<+ (8) +>| | 548 | | | |Completed| | 549 | | | | | | 550 | |--(11)-- Continue Request (B) --->| | +------+ 551 | | | | 552 | |<-(12)----- Grant Access ---------| | 553 | | | | 554 +--------+ +--------+ 556 1. The RC requests access to the resource (Section 2). The RC 557 indicates that it can display a user code (Section 2.5.4). 559 2. The AS determines that interaction is needed and responds 560 (Section 3) with a user code to communicate to the user 561 (Section 3.3.4). This could optionally include a URL to direct 562 the user to, but this URL should be static and so could be 563 configured in the RC's documentation. The AS also includes 564 information the RC will need to continue the request 565 (Section 3.1) in (8) and (10). The AS associates this 566 continuation information with an ongoing request that will be 567 referenced in (4), (6), (8), and (10). 569 3. The RC stores the continuation information from (2) for use in 570 (8) and (10). The RC then communicates the code to the user 571 (Section 4.1) given by the AS in (2). 573 4. The user's directs their browser to the user code URL. This URL 574 is stable and can be communicated via the RC's documentation, 575 the AS documentation, or the RC software itself. Since it is 576 assumed that the RO will interact with the AS through a 577 secondary device, the RC does not provide a mechanism to launch 578 the RO's browser at this URL. 580 5. The RQ authenticates at the AS, taking on the role of the RO. 582 6. The RO enters the code communicated in (3) to the AS. The AS 583 validates this code against a current request in process. 585 7. As the RO, the user authorizes the pending request from the RC. 587 8. When the AS is done interacting with the user, the AS indicates 588 to the RO that the request has been completed. 590 9. Meanwhile, the RC loads the continuation information stored at 591 (3) and continues the request (Section 5). The AS determines 592 which ongoing access request is referenced here and checks its 593 state. 595 10. If the access request has not yet been authorized by the RO in 596 (6), the AS responds to the RC to continue the request 597 (Section 3.1) at a future time through additional polled 598 continuation requests. This response can include updated 599 continuation information as well as information regarding how 600 long the RC should wait before calling again. The RC replaces 601 its stored continuation information from the previous response 602 (2). Note that the AS may need to determine that the RO has not 603 approved the request in a sufficient amount of time and return 604 an appropriate error to the RC. 606 11. The RC continues to poll the AS (Section 5.2) with the new 607 continuation information in (9). 609 12. If the request has been authorized, the AS grants access to the 610 information in the form of access tokens (Section 3.2) and 611 direct subject information (Section 3.4) to the RC. 613 An example set of protocol messages for this method can be found in 614 Appendix C.2. 616 1.3.3. Asynchronous Authorization 618 In this example flow, the RQ and RO roles are fulfilled by different 619 parties, and the RO does not interact with the RC. The AS reaches 620 out asynchronously to the RO during the request process to gather the 621 RO's authorization for the RC's request. The RC polls the AS while 622 it is waiting for the RO to authorize the request. 624 +--------+ +--------+ +------+ 625 | RC | | AS | | RO | 626 | |--(1)--- Request Access --------->| | | | 627 | | | | | | 628 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 629 | | | |<+ (3) +>| | 630 | | | | AuthN | | 631 | |--(6)--- Continue Request (A) --->| | | | 632 | | | |<+ (4) +>| | 633 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 634 | | | | | | 635 | | | |<+ (5) +>| | 636 | | | |Completed| | 637 | | | | | | 638 | |--(8)--- Continue Request (B) --->| | +------+ 639 | | | | 640 | |<-(9)------ Grant Access ---------| | 641 | | | | 642 +--------+ +--------+ 644 1. The RC requests access to the resource (Section 2). The RC does 645 not send any interactions modes to the server, indicating that it 646 does not expect to interact with the RO. The RC can also signal 647 which RO it requires authorization from, if known, by using the 648 user request section (Section 2.4). 650 2. The AS determines that interaction is needed, but the RC cannot 651 interact with the RO. The AS responds (Section 3) with the 652 information the RC will need to continue the request 653 (Section 3.1) in (6) and (8), including a signal that the RC 654 should wait before checking the status of the request again. The 655 AS associates this continuation information with an ongoing 656 request that will be referenced in (3), (4), (5), (6), and (8). 658 3. The AS determines which RO to contact based on the request in 659 (1), through a combination of the user request (Section 2.4), the 660 resources request (Section 2.1), and other policy information. 661 The AS contacts the RO and authenticates them. 663 4. The RO authorizes the pending request from the RC. 665 5. When the AS is done interacting with the RO, the AS indicates to 666 the RO that the request has been completed. 668 6. Meanwhile, the RC loads the continuation information stored at 669 (3) and continues the request (Section 5). The AS determines 670 which ongoing access request is referenced here and checks its 671 state. 673 7. If the access request has not yet been authorized by the RO in 674 (6), the AS responds to the RC to continue the request 675 (Section 3.1) at a future time through additional polling. This 676 response can include refreshed credentials as well as information 677 regarding how long the RC should wait before calling again. The 678 RC replaces its stored continuation information from the previous 679 response (2). Note that the AS may need to determine that the RO 680 has not approved the request in a sufficient amount of time and 681 return an appropriate error to the RC. 683 8. The RC continues to poll the AS (Section 5.2) with the new 684 continuation information from (7). 686 9. If the request has been authorized, the AS grants access to the 687 information in the form of access tokens (Section 3.2) and direct 688 subject information (Section 3.4) to the RC. 690 An example set of protocol messages for this method can be found in 691 Appendix D.1. 693 1.3.4. Software-only Authorization 695 In this example flow, the AS policy allows the RC to make a call on 696 its own behalf, without the need for a RO to be involved at runtime 697 to approve the decision. Since there is no explicit RO, the RC does 698 not interact with an RO. 700 +--------+ +--------+ 701 | RC | | AS | 702 | |--(1)--- Request Access --------->| | 703 | | | | 704 | |<-(2)---- Grant Access -----------| | 705 | | | | 706 +--------+ +--------+ 708 1. The RC requests access to the resource (Section 2). The RC does 709 not send any interactions modes to the server. 711 2. The AS determines that the request is been authorized, the AS 712 grants access to the information in the form of access tokens 713 (Section 3.2) and direct subject information (Section 3.4) to the 714 RC. 716 An example set of protocol messages for this method can be found in 717 Appendix D. 719 1.3.5. Refreshing an Expired Access Token 721 In this example flow, the RC receives an access token to access a 722 resource server through some valid GNAP process. The RC uses that 723 token at the RS for some time, but eventually the access token 724 expires. The RC then gets a new access token by rotating the expired 725 access token at the AS using the token's management URL. 727 +--------+ +--------+ 728 | RC | | AS | 729 | |--(1)--- Request Access ----------------->| | 730 | | | | 731 | |<-(2)--- Grant Access --------------------| | 732 | | | | 733 | | +--------+ | | 734 | |--(3)--- Access Resource --->| RS | | | 735 | | | | | | 736 | |<-(4)--- Error Response -----| | | | 737 | | +--------+ | | 738 | | | | 739 | |--(5)--- Rotate Token ------------------->| | 740 | | | | 741 | |<-(6)--- Rotated Token -------------------| | 742 | | | | 743 +--------+ +--------+ 745 1. The RC requests access to the resource (Section 2). 747 2. The AS grants access to the resource (Section 3) with an access 748 token (Section 3.2) usable at the RS. The access token response 749 includes a token management URI. 751 3. The RC presents the token (Section 7) to the RS. The RS 752 validates the token and returns an appropriate response for the 753 API. 755 4. When the access token is expired, the RS responds to the RC with 756 an error. 758 5. The RC calls the token management URI returned in (2) to rotate 759 the access token (Section 6.1). The RC presents the access token 760 as well as the appropriate key. 762 6. The AS validates the rotation request including the signature and 763 keys presented in (5) and returns a new access token 764 (Section 3.2.1). The response includes a new access token and 765 can also include updated token management information, which the 766 RC will store in place of the values returned in (2). 768 2. Requesting Access 770 To start a request, the RC sends JSON [RFC8259] document with an 771 object as its root. Each member of the request object represents a 772 different aspect of the RC's request. Each field is described in 773 detail in a section below. 775 resources Describes the rights that the RC is requesting for one or 776 more access tokens to be used at RS's. Section 2.1 778 subject Describes the information about the RO that the RC is 779 requesting to be returned directly in the response from the AS. 780 Section 2.2 782 client Describes the RC that is making this request, including the 783 key that the RC will use to protect this request and any 784 continuation requests at the AS and any user-facing information 785 about the RC used in interactions at the AS. Section 2.3 787 user Identifies the RQ to the AS in a manner that the AS can verify, 788 either directly or by interacting with the RQ to determine their 789 status as the RO. Section 2.4 791 interact Describes the modes that the RC has for allowing the RO to 792 interact with the AS and modes for the RC to receive updates when 793 interaction is complete. Section 2.5 795 capabilities Identifies named extension capabilities that the RC can 796 use, signaling to the AS which extensions it can use. Section 2.6 798 existing_grant Identifies a previously-existing grant that the RC is 799 extending with this request. Section 2.7 801 claims Identifies the identity claims to be returned as part of an 802 OpenID Connect claims request. Section 2.8 804 Additional members of this request object can be defined by 805 extensions to this protocol as described in Section 2.9 807 A non-normative example of a grant request is below: 809 { 810 "resources": [ 811 { 812 "type": "photo-api", 813 "actions": [ 814 "read", 815 "write", 816 "dolphin" 817 ], 818 "locations": [ 819 "https://server.example.net/", 820 "https://resource.local/other" 821 ], 822 "datatypes": [ 823 "metadata", 824 "images" 825 ] 826 }, 827 "dolphin-metadata" 828 ], 829 "client": { 830 "display": { 831 "name": "My Client Display Name", 832 "uri": "https://example.net/client" 833 }, 834 "key": { 835 "proof": "jwsd", 836 "jwk": { 837 "kty": "RSA", 838 "e": "AQAB", 839 "kid": "xyz-1", 840 "alg": "RS256", 841 "n": "kOB5rR4Jv0GMeL...." 842 } 844 } 845 }, 846 "interact": { 847 "redirect": true, 848 "callback": { 849 "method": "redirect", 850 "uri": "https://client.example.net/return/123455", 851 "nonce": "LKLTI25DK82FX4T4QFZC" 852 } 853 }, 854 "capabilities": ["ext1", "ext2"], 855 "subject": { 856 "sub_ids": ["iss-sub", "email"], 857 "assertions": ["id_token"] 858 } 859 } 861 The request MUST be sent as a JSON object in the body of the HTTP 862 POST request with Content-Type "application/json", unless otherwise 863 specified by the signature mechanism. 865 2.1. Requesting Resources 867 If the RC is requesting one or more access tokens for the purpose of 868 accessing an API, the RC MUST include a "resources" field. This 869 field MUST be an array (for a single access token (Section 2.1.1)) or 870 an object (for multiple access tokens (Section 2.1.3)), as described 871 in the following sections. 873 2.1.1. Requesting a Single Access Token 875 When requesting an access token, the RC MUST send a "resources" field 876 containing a JSON array. The elements of the JSON array represent 877 rights of access that the RC is requesting in the access token. The 878 requested access is the sum of all elements within the array. 880 The RC declares what access it wants to associated with the resulting 881 access token using objects that describe multiple dimensions of 882 access. Each object contains a "type" property that determines the 883 type of API that the RC is calling. 885 type The type of resource request as a string. This field MAY 886 define which other fields are allowed in the request object. This 887 field is REQUIRED. 889 The value of this field is under the control of the AS. This field 890 MUST be compared using an exact byte match of the string value 891 against known types by the AS. The AS MUST ensure that there is no 892 collision between different authorization data types that it 893 supports. The AS MUST NOT do any collation or normalization of data 894 types during comparison. It is RECOMMENDED that designers of 895 general-purpose APIs use a URI for this field to avoid collisions 896 between multiple API types protected by a single AS. 898 While it is expected that many APIs will have its own properties, a 899 set of common properties are defined here. Specific API 900 implementations SHOULD NOT re-use these fields with different 901 semantics or syntax. The available values for these properties are 902 determined by the API being protected at the RS. 904 [[ Editor's note: this will align with OAuth 2 RAR, but the details 905 of exactly how it aligns are TBD. Since RAR needs to work in the 906 confines of OAuth 2, RAR has to define how to interact with "scope", 907 "resource", and other existing OAuth 2 mechanisms that don't exist in 908 GNAP. ]]. 910 actions The types of actions the RC will take at the RS as an array 911 of strings. For example, an RC asking for a combination of "read" 912 and "write" access. 914 locations The location of the RS as an array of strings. These 915 strings are typically URIs identifying the location of the RS. 917 datatypes The kinds of data available to the RC at the RS's API as 918 an array of strings. For example, an RC asking for access to raw 919 "image" data and "metadata" at a photograph API. 921 identifier A string identifier indicating a specific resource at the 922 RS. For example, a patient identifier for a medical API or a bank 923 account number for a financial API. 925 The following non-normative example shows the use of both common and 926 API-specific fields as part of two different access "type" values. 928 "resources": [ 929 { 930 "type": "photo-api", 931 "actions": [ 932 "read", 933 "write", 934 "dolphin" 935 ], 936 "locations": [ 937 "https://server.example.net/", 938 "https://resource.local/other" 939 ], 940 "datatypes": [ 941 "metadata", 942 "images" 943 ] 944 }, 945 { 946 "type": "financial-transaction", 947 "actions": [ 948 "withdraw" 949 ], 950 "identifier": "account-14-32-32-3", 951 "currency": "USD" 952 } 953 ] 955 If this request is approved, the resulting access token 956 (Section 3.2.1) will include the sum of both of the requested types 957 of access. 959 2.1.2. Requesting Resources By Reference 961 Instead of sending an object describing the requested resource 962 (Section 2.1.1), a RC MAY send a string known to the AS or RS 963 representing the access being requested. Each string SHOULD 964 correspond to a specific expanded object representation at the AS. 966 [[ Editor's note: we could describe more about how the expansion 967 would work. For example, expand into an object where the value of 968 the "type" field is the value of the string. Or we could leave it 969 open and flexible, since it's really up to the AS/RS to interpret. ]] 971 "resources": [ 972 "read", "dolphin-metadata", "some other thing" 973 ] 975 This value is opaque to the RC and MAY be any valid JSON string, and 976 therefore could include spaces, unicode characters, and properly 977 escaped string sequences. However, in some situations the value is 978 intended to be seen and understood be the RC developer. In such 979 cases, the API designer choosing any such human-readable strings 980 SHOULD take steps to ensure the string values are not easily confused 981 by a developer 983 This functionality is similar in practice to OAuth 2's "scope" 984 parameter [RFC6749], where a single string represents the set of 985 access rights requested by the RC. As such, the reference string 986 could contain any valid OAuth 2 scope value as in Appendix D.2. Note 987 that the reference string here is not bound to the same character 988 restrictions as in OAuth 2's "scope" definition. 990 A single "resources" array MAY include both object-type and string- 991 type resource items. 993 "resources": [ 994 { 995 "type": "photo-api", 996 "actions": [ 997 "read", 998 "write", 999 "dolphin" 1000 ], 1001 "locations": [ 1002 "https://server.example.net/", 1003 "https://resource.local/other" 1004 ], 1005 "datatypes": [ 1006 "metadata", 1007 "images" 1008 ] 1009 }, 1010 "read", 1011 "dolphin-metadata", 1012 { 1013 "type": "financial-transaction", 1014 "actions": [ 1015 "withdraw" 1016 ], 1017 "identifier": "account-14-32-32-3", 1018 "currency": "USD" 1019 }, 1020 "some other thing" 1021 ] 1023 [[ Editor's note: passing resource requests by reference really is 1024 akin to a "scope", and we have many years of experience showing us 1025 that the simplicity of giving a developer a set of strings to send is 1026 a simple and powerful pattern. We could always require objects and 1027 just use the "type" field as a scope value, but that's a lot of 1028 complexity to pay for the simple case. Client developers will always 1029 know which kind they need to send, because they're picking from the 1030 API's documentation. ]] 1032 2.1.3. Requesting Multiple Access Tokens 1034 When requesting multiple access tokens, the resources field is a JSON 1035 object. The names of the JSON object fields are token identifiers 1036 chosen by the RC, and MAY be any valid string. The values of the 1037 JSON object fields are JSON arrays representing a single access token 1038 request, as specified in requesting a single access token 1039 (Section 2.1.1). 1041 The following non-normative example shows a request for two separate 1042 access tokens, "token1" and "token2". 1044 "resources": { 1045 "token1": [ 1046 { 1047 "type": "photo-api", 1048 "actions": [ 1049 "read", 1050 "write", 1051 "dolphin" 1052 ], 1053 "locations": [ 1054 "https://server.example.net/", 1055 "https://resource.local/other" 1056 ], 1057 "datatypes": [ 1058 "metadata", 1059 "images" 1060 ] 1061 }, 1062 "dolphin-metadata" 1063 ], 1064 "token2": [ 1065 { 1066 "type": "walrus-access", 1067 "actions": [ 1068 "foo", 1069 "bar" 1070 ], 1071 "locations": [ 1072 "https://resource.other/" 1073 ], 1074 "datatypes": [ 1075 "data", 1076 "pictures", 1077 "walrus whiskers" 1078 ] 1079 } 1080 ] 1081 } 1083 Any approved access requests are returned in the multiple access 1084 token response (Section 3.2.2) structure using the token identifiers 1085 in the request. 1087 2.1.4. Signaling Token Behavior 1089 While the AS is ultimately in control of how tokens are returned and 1090 bound to the RC, sometimes the RC has context about what it can 1091 support that can affect the AS's response. This specification 1092 defines several flags that are passed as resource reference strings 1093 (Section 2.1.2). 1095 Each flag applies only to the single resource request in which it 1096 appears. 1098 Support of all flags is optional, such as any other resource 1099 reference value. 1101 multi_token The RC wishes to support multiple simultaneous access 1102 tokens through the token rotation process. When the RC rotates an 1103 access token (Section 6.1), the AS does not invalidate the 1104 previous access token. The old access token continues to remain 1105 valid until such time as it expires or is revoked through other 1106 means. 1108 split_token The RC is capable of receiving multiple access tokens 1109 (Section 3.2.2) in response to any single token request 1110 (Section 2.1.1), or receiving a different number of tokens than 1111 specified in the multiple token request (Section 2.1.3). The 1112 labels of the returned additional tokens are chosen by the AS. 1113 The client MUST be able to tell from the token response where and 1114 how it can use the each access tokens. [[ Editor's note: This 1115 functionality is controversial at best as it requires 1116 significantly more complexity on the client in order to solve one 1117 class of AS/RS deployment choices. ]] 1119 bind_token The RC wants the issued access token to be bound to the 1120 key the RC used (Section 2.3.2) to make the request. The 1121 resulting access token MUST be bound using the same "proof" 1122 mechanism used by the client with a "key" value of "true", 1123 indicating the client's presented key is to be used for binding. 1124 [[ Editor's note: should there be a different flag and mechanism 1125 for the client to explicitly indicate which binding method it 1126 wants to use, especially if the client wants to use a different 1127 method at the AS than the RS? ]] 1129 The AS MUST respond with any applied flags in the token response 1130 (Section 3.2) "resources" section. 1132 In this non-normative example, the requested access token is to be 1133 bound to the client's key and should be kept during rotation. 1135 "resources": [ 1136 { 1137 "type": "photo-api", 1138 "actions": [ 1139 "read", 1140 "write", 1141 "dolphin" 1142 ], 1143 "locations": [ 1144 "https://server.example.net/", 1145 "https://resource.local/other" 1146 ], 1147 "datatypes": [ 1148 "metadata", 1149 "images" 1150 ] 1151 }, 1152 "read", 1153 "bind_token", 1154 "multi_token" 1155 ] 1157 Additional flags can be registered in a registry TBD (Section 12). 1159 [[ Editor's note: while these reference values are "reserved", the 1160 ultimate decider for what a reference means is the AS, which means an 1161 AS could arguably decide that one of these values means something 1162 else. Also, this kind of reservation potentially steps on API 1163 namespaces, which OAuth 2 is careful not to do but common extensions 1164 like OIDC do with their own scope definitions. However, in OIDC, 1165 several "scope" values have behavior similar to what's defined here, 1166 particularly "openid" turns on ID tokens in the response and 1167 "offline_access" signals for the return of a refresh token, and these 1168 can be used outside of OpenID Connect itself. However, to keep these 1169 flags out of the general API namespace, we could use a different 1170 syntax for sending them. In particular, they could be defined under 1171 a GNAP-specific "type" object, where all the flags are fields on the 1172 object. 1174 resources: [ 1175 { 1176 type: "gnap-flags", 1177 flag1: true, 1178 flag2: false, 1179 flag3: true ... 1180 }, 1181 "reference1", 1182 "scope2", ... 1183 ] 1185 Alternatively, all the flags could be sent in an array separate from 1186 the rest of the request. 1188 resources: [ 1189 "reference1", 1190 "scope2", 1191 ["flag1", "flag2", "flag3"] ... 1192 ] 1194 This whole thing might also belong in an extension, as it's advanced 1195 behavior signaling for very specific cases. However, it seems other 1196 extensions would be likely to extend this kind of thing, like OIDC 1197 did with "offline_access". ]] 1199 2.2. Requesting User Information 1201 If the RC is requesting information about the RO from the AS, it 1202 sends a "subject" field as a JSON object. This object MAY contain 1203 the following fields (or additional fields defined in a registry TBD 1204 (Section 12)). 1206 sub_ids An array of subject identifier subject types requested for 1207 the RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 1209 assertions An array of requested assertion formats. Possible values 1210 include "id_token" for an [OIDC] ID Token and "saml2" for a SAML 2 1211 assertion. Additional assertion values are defined by a registry 1212 TBD (Section 12). [[ Editor's note: These values are lifted from 1213 [RFC8693]'s "token type identifiers" list, but is there a better 1214 source?]] 1216 "subject": { 1217 "sub_ids": [ "iss-sub", "email" ], 1218 "assertions": [ "id_token", "saml2" ] 1219 } 1220 The AS can determine the RO's identity and permission for releasing 1221 this information through interaction with the RO (Section 4), AS 1222 policies, or assertions presented by the RC (Section 2.4). If this 1223 is determined positively, the AS MAY return the RO's information in 1224 its response (Section 3.4) as requested. 1226 Subject identifiers requested by the RC serve only to identify the RO 1227 in the context of the AS and can't be used as communication channels 1228 by the RC, as discussed in Section 3.4. One method of requesting 1229 communication channels and other identity claims are discussed in 1230 Section 2.8. 1232 The AS SHOULD NOT re-use subject identifiers for multiple different 1233 ROs. 1235 [[ Editor's Note: What we're really saying here is that "even if the 1236 AS gives you an email address to identify the user, that isn't a 1237 claim that this is a valid email address for that current user, so 1238 don't try to email them." In order to get a workable email address, 1239 or anything that you can use to contact them, you'd need a full 1240 identity protocol and not just this. Also, subject identifiers are 1241 asserted by the AS and therefore naturally scoped to the AS. Would 1242 changing the name to "as_sub_ids" or "local_sub_ids" help convey that 1243 point? ]] 1245 Note: the "sub_ids" and "assertions" request fields are independent 1246 of each other, and a returned assertion MAY omit a requested subject 1247 identifier. 1249 [[ Editor's note: we're potentially conflating these two types in the 1250 same structure, so perhaps these should be split. There's also a 1251 difference between user information and authentication event 1252 information. ]] 1254 2.3. Identifying the RC 1256 When sending a non-continuation request to the AS, the RC MUST 1257 identify itself by including the "client" field of the request and by 1258 signing the request as described in Section 8. Note that for a 1259 continuation request (Section 5), the RC instance is identified by 1260 its association with the request being continued and so this field is 1261 not sent under those circumstances. 1263 When RC information is sent by value, the "client" field of the 1264 request consists of a JSON object with the following fields. 1266 key The public key of the RC to be used in this request as described 1267 in Section 2.3.2. This field is REQUIRED. 1269 class_id An identifier string that the AS can use to identify the 1270 software comprising this instance of the RC. The contents and 1271 format of this field are up to the AS. This field is OPTIONAL. 1273 display An object containing additional information that the AS MAY 1274 display to the RO during interaction, authorization, and 1275 management. This field is OPTIONAL. 1277 "client": { 1278 "key": { 1279 "proof": "httpsig", 1280 "jwk": { 1281 "kty": "RSA", 1282 "e": "AQAB", 1283 "kid": "xyz-1", 1284 "alg": "RS256", 1285 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1286 }, 1287 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1288 }, 1289 "class_id": "web-server-1234", 1290 "display": { 1291 "name": "My Client Display Name", 1292 "uri": "https://example.net/client" 1293 } 1294 } 1296 Additional fields are defined in a registry TBD (Section 12). 1298 The RC MUST prove possession of any presented key by the "proof" 1299 mechanism associated with the key in the request. Proof types are 1300 defined in a registry TBD (Section 12) and an initial set of methods 1301 is described in Section 8. 1303 Note that the AS MAY know the RC's public key ahead of time, and the 1304 AS MAY apply different policies to the request depending on what has 1305 been registered against that key. If the same public key is sent by 1306 value on subsequent access requests, the AS SHOULD treat these 1307 requests as coming from the same RC software instance for purposes of 1308 identification, authentication, and policy application. If the AS 1309 does not know the RC's public key ahead of time, the AS MAY accept or 1310 reject the request based on AS policy, attestations within the client 1311 request, and other mechanisms. 1313 [[ Editor's note: additional client attestation frameworks will 1314 eventually need to be addressed here. For example, the organization 1315 the client represents, or a family of client software deployed in a 1316 cluster, or the posture of the device the client is installed on. 1317 These all need to be separable from the client's key and potentially 1318 the instance identifier. ]] 1320 2.3.1. Identifying the RC Instance 1322 If the RC has an instance identifier that the AS can use to determine 1323 appropriate key information, the RC can send this value in the 1324 "instance_id" field. The instance identifier MAY be assigned to an 1325 RC instance at runtime through the Section 3.5 or MAY be obtained in 1326 another fashion, such as a static registration process at the AS. 1328 instance_id An identifier string that the AS can use to identify the 1329 particular instance of this RC. The content and structure of this 1330 identifier is opaque to the RC. 1332 "client": { 1333 "instance_id": "client-541-ab" 1334 } 1336 If there are no additional fields to send, the RC MAY send the 1337 instance identifier as a direct reference value in lieu of the 1338 object. 1340 "client": "client-541-ab" 1342 When the AS receives a request with an instance identifier, the AS 1343 MUST ensure that the key used to sign the request (Section 8) is 1344 associated with the instance identifier. 1346 If the "instance_id" field is sent, it MUST NOT be accompanied by 1347 other fields unless such fields are explicitly marked safe for 1348 inclusion alongside the instance identifier. 1350 [[ Editor's note: It seems clear that an instance identifier is 1351 mutually exclusive with most of the fields in the request (eg, we 1352 don't want an attacker being able to swap out a client's registered 1353 key just by accessing the identifier). However, some proposed 1354 concepts might fit alongside an instance identifier that change at 1355 runtime, such as device posture or another dynamic attestation. 1356 Should these be sent in the "client" block alongside the instance 1357 identifier, should there be a separate top-level block for runtime 1358 attestations, or some other mechanism? ]] 1359 If the AS does not recognize the instance identifier, the request 1360 MUST be rejected with an error. 1362 If the RC instance is identified in this manner, the registered key 1363 for the RC MAY be a symmetric key known to the AS. The RC MUST NOT 1364 send a symmetric key by value in the request, as doing so would 1365 expose the key directly instead of proving possession of it. 1367 [[ Editor's note: In many ways, passing an instance identifier is 1368 analogous to OAuth 2's "client_id" parameter [RFC6749], especially 1369 when coupled with a confidential client's registration and 1370 authentication process. See Appendix D.2 for an example. Something 1371 like this is required to make things easier for client developers in 1372 the common case where the AS already knows the client's key, and to 1373 allow symmetric keys. ]] 1375 2.3.2. Identifying the RC Key 1377 The RC key MUST be a public key in at least one supported format and 1378 MUST be applicable to the proofing mechanism used in the request. If 1379 the key is sent in multiple formats, all the keys MUST be the same. 1380 The key presented in this field MUST be the key used to sign the 1381 request. 1383 proof The form of proof that the RC will use when presenting the key 1384 to the AS. The valid values of this field and the processing 1385 requirements for each are detailed in Section 8. This field is 1386 REQUIRED. 1388 jwk Value of the public key as a JSON Web Key. MUST contain an "alg" 1389 field which is used to validate the signature. MUST contain the 1390 "kid" field to identify the key in the signed object. 1392 cert PEM serialized value of the certificate used to sign the 1393 request, with optional internal whitespace. 1395 cert#256 The certificate thumbprint calculated as per OAuth-MTLS 1396 [RFC8705] in base64 URL encoding. 1398 Additional key types are defined in a registry TBD (Section 12). 1400 [[ Editor's note: we will eventually want to have fetchable keys, I 1401 would guess. Things like DID for key identification are going to be 1402 important. ]] 1404 This non-normative example shows a single key presented in multiple 1405 formats using a single proofing mechanism. 1407 "key": { 1408 "proof": "jwsd", 1409 "jwk": { 1410 "kty": "RSA", 1411 "e": "AQAB", 1412 "kid": "xyz-1", 1413 "alg": "RS256", 1414 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1415 }, 1416 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1417 } 1419 Continuation requests (Section 5) MUST use the same key (or its most 1420 recent rotation) and proof method as the initial request. 1422 2.3.3. Providing Displayable RC Information 1424 If the RC has additional information to display to the RO during any 1425 interactions at the AS, it MAY send that information in the "display" 1426 field. This field is a JSON object that declares information to 1427 present to the RO during any interactive sequences. 1429 name Display name of the RC software 1431 uri User-facing web page of the RC software 1433 logo_uri Display image to represent the RC software 1435 "display": { 1436 "name": "My Client Display Name", 1437 "uri": "https://example.net/client" 1438 } 1440 [[ Editor's note: would we want to support pushing a display logo by 1441 value? On the upside it allows for more dynamic detached clients and 1442 doesn't require the AS to fetch information. On the downside, this 1443 is harder for the AS to enforce a policy about and could lead to 1444 potential exploits caused by sending binary image files. ]] 1446 Additional display fields are defined by a registry TBD (Section 12). 1448 The AS SHOULD use these values during interaction with the RO. The 1449 values are for informational purposes only and MUST NOT be taken as 1450 authentic proof of the RC's identity or source. The AS MAY restrict 1451 display values to specific RC instances, as identified by their keys 1452 in Section 2.3. 1454 2.3.4. Authenticating the RC 1456 If the presented key is known to the AS and is associated with a 1457 single instance of the RC software, the process of presenting a key 1458 and proving possession of that key is sufficient to authenticate the 1459 RC to the AS. The AS MAY associate policies with the RC software 1460 identified by this key, such as limiting which resources can be 1461 requested and which interaction methods can be used. For example, 1462 only specific RCs with certain known keys might be trusted with 1463 access tokens without the AS interacting directly with the RO as in 1464 Appendix D. 1466 The presentation of a key allows the AS to strongly associate 1467 multiple successive requests from the same RC with each other. This 1468 is true when the AS knows the key ahead of time and can use the key 1469 to authenticate the RC software, but also if the key is ephemeral and 1470 created just for this request. As such the AS MAY allow for RCs to 1471 make requests with unknown keys. This pattern allows for ephemeral 1472 RCs, such as single-page applications, and RCs with many individual 1473 instances, such as mobile applications, to generate their own key 1474 pairs and use them within the protocol without having to go through a 1475 separate registration step. The AS MAY limit which capabilities are 1476 made available to RCs with unknown keys. For example, the AS could 1477 have a policy saying that only previously-registered RCs can request 1478 particular resources, or that all RCs with unknown keys have to be 1479 interactively approved by an RO. 1481 2.4. Identifying the User 1483 If the RC knows the identity of the RQ through one or more 1484 identifiers or assertions, the RC MAY send that information to the AS 1485 in the "user" field. The RC MAY pass this information by value or by 1486 reference. 1488 sub_ids An array of subject identifiers for the RQ, as defined by 1489 [I-D.ietf-secevent-subject-identifiers]. 1491 assertions An object containing assertions as values keyed on the 1492 assertion type defined by a registry TBD (Section 12). Possible 1493 keys include "id_token" for an [OIDC] ID Token and "saml2" for a 1494 SAML 2 assertion. Additional assertion values are defined by a 1495 registry TBD (Section 12). [[ Editor's note: These keys are 1496 lifted from [RFC8693]'s "token type identifiers" list, but is 1497 there a better source? Additionally: should this be an array of 1498 objects with internal typing like the sub_ids? Do we expect more 1499 than one assertion per user anyway? ]] 1501 "user": { 1502 "sub_ids": [ { 1503 "subject_type": "email", 1504 "email": "user@example.com" 1505 } ], 1506 "assertions": { 1507 "id_token": "eyj..." 1508 } 1509 } 1511 Subject identifiers are hints to the AS in determining the RO and 1512 MUST NOT be taken as declarative statements that a particular RO is 1513 present at the RC and acting as the RQ. Assertions SHOULD be 1514 validated by the AS. [[ editor's note: is this a MUST? Assertion 1515 validation is extremely specific to the kind of assertion in place, 1516 what other guidance and requirements can we put in place here? ]] 1518 If the identified RQ does not match the RO present at the AS during 1519 an interaction step, the AS SHOULD reject the request with an error. 1521 [[ Editor's note: we're potentially conflating identification 1522 (sub_ids) and provable presence (assertions and a trusted reference 1523 handle) in the same structure, so perhaps these should be split. The 1524 security parameters are pretty different here. ]] 1526 If the AS trusts the RC to present verifiable assertions, the AS MAY 1527 decide, based on its policy, to skip interaction with the RO, even if 1528 the RC provides one or more interaction modes in its request. 1530 2.4.1. Identifying the User by Reference 1532 User reference identifiers can be dynamically issued by the AS 1533 (Section 3.5) to allow the RC to represent the same RQ to the AS over 1534 subsequent requests. 1536 If the RC has a reference for the RQ at this AS, the RC MAY pass that 1537 reference as a string. The format of this string is opaque to the 1538 RC. 1540 "user": "XUT2MFM1XBIKJKSDU8QM" 1542 User reference identifiers are not intended to be human-readable user 1543 identifiers or structured assertions. For the RC to send either of 1544 these, use the full user request object (Section 2.4) instead. 1546 [[ Editor's note: we might be able to fold this function into an 1547 unstructured user assertion reference issued by the AS to the RC. We 1548 could put it in as an assertion type of "gnap_reference" or something 1549 like that. Downside: it's more verbose and potentially confusing to 1550 the client developer to have an assertion-like thing that's internal 1551 to the AS and not an assertion. ]] 1553 If the AS does not recognize the user reference, it MUST return an 1554 error. 1556 2.5. Interacting with the User 1558 Many times, the AS will require interaction with the RO in order to 1559 approve a requested delegation to the RC for both resources and 1560 direct claim information. Many times the RQ using the RC is the same 1561 person as the RO, and the RC can directly drive interaction with the 1562 AS by redirecting the RQ on the same device, or by launching an 1563 application. Other times, the RC can provide information to start 1564 the RO's interaction on a secondary device, or the RC will wait for 1565 the RO to approve the request asynchronously. The RC could also be 1566 signaled that interaction has completed by the AS making callbacks. 1567 To facilitate all of these modes, the RC declares the means that it 1568 can interact using the "interact" field. 1570 The "interact" field is a JSON object with keys that declare 1571 different interaction modes. A RC MUST NOT declare an interaction 1572 mode it does not support. The RC MAY send multiple modes in the same 1573 request. There is no preference order specified in this request. An 1574 AS MAY respond to any, all, or none of the presented interaction 1575 modes (Section 3.3) in a request, depending on its capabilities and 1576 what is allowed to fulfill the request. This specification defines 1577 the following interaction modes: 1579 redirect Indicates that the RC can direct the RQ to an arbitrary URL 1580 at the AS for interaction. Section 2.5.1 1582 app Indicates that the RC can launch an application on the RQ's 1583 device for interaction. Section 2.5.2 1585 callback Indicates that the RC can receive a callback from the AS 1586 after interaction with the RO has concluded. Section 2.5.3 1588 user_code Indicates that the RC can communicate a human-readable 1589 short code to the RQ for use with a stable URL at the AS. 1590 Section 2.5.4 1592 ui_locales Indicates the RQ's preferred locales that the AS can use 1593 during interaction, particularly before the RO has authenticated. 1594 Section 2.5.5 1596 The following sections detail requests for interaction modes. 1597 Additional interaction modes are defined in a registry TBD 1598 (Section 12). 1600 [[ Editor's note: there need to be more examples (Appendix C) that 1601 knit together the interaction modes into common flows, like an authz- 1602 code equivalent. But it's important for the protocol design that 1603 these are separate pieces to allow such knitting to take place. ]] 1605 In this non-normative example, the RC is indicating that it can 1606 redirect (Section 2.5.1) the RQ to an arbitrary URL and can receive a 1607 callback (Section 2.5.3) through a browser request. 1609 "interact": { 1610 "redirect": true, 1611 "callback": { 1612 "method": "redirect", 1613 "uri": "https://client.example.net/return/123455", 1614 "nonce": "LKLTI25DK82FX4T4QFZC" 1615 } 1616 } 1618 In this non-normative example, the RC is indicating that it can 1619 display a use code (Section 2.5.4) and direct the RQ to an arbitrary 1620 URL of maximum length (Section 2.5.1.1) 255 characters, but it cannot 1621 accept a callback. 1623 "interact": { 1624 "redirect": 255, 1625 "user_code": true 1626 } 1628 If the RC does not provide a suitable interaction mechanism, the AS 1629 cannot contact the RO asynchronously, and the AS determines that 1630 interaction is required, then the AS SHOULD return an error since the 1631 RC will be unable to complete the request without authorization. 1633 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1634 provided, including user codes and redirection URLs. The RC SHOULD 1635 apply suitable timeouts to any callback URLs. 1637 2.5.1. Redirect to an Arbitrary URL 1639 If the RC is capable of directing the RQ to a URL defined by the AS 1640 at runtime, the RC indicates this by sending the "redirect" field 1641 with the boolean value "true". The means by which the RC will 1642 activate this URL is out of scope of this specification, but common 1643 methods include an HTTP redirect, launching a browser on the RQ's 1644 device, providing a scannable image encoding, and printing out a URL 1645 to an interactive console. 1647 "interact": { 1648 "redirect": true 1649 } 1651 If this interaction mode is supported for this RC and request, the AS 1652 returns a redirect interaction response Section 3.3.1. 1654 2.5.1.1. Redirect to an Arbitrary Shortened URL 1656 If the RC would prefer to redirect to a shortened URL defined by the 1657 AS at runtime, the RC indicates this by sending the "redirect" field 1658 with an integer indicating the maximum character length of the 1659 returned URL. The AS MAY use this value to decide whether to return 1660 a shortened form of the response URL. If the AS cannot shorten its 1661 response URL enough to fit in the requested size, the AS SHOULD 1662 return an error. [[ Editor's note: Or maybe just ignore this part of 1663 the interaction request? ]] 1665 "interact": { 1666 "redirect": 255 1667 } 1669 If this interaction mode is supported for this RC and request, the AS 1670 returns a redirect interaction response with short URL Section 3.3.1. 1672 2.5.2. Open an Application-specific URL 1674 If the RC can open a URL associated with an application on the RQ's 1675 device, the RC indicates this by sending the "app" field with boolean 1676 value "true". The means by which the RC determines the application 1677 to open with this URL are out of scope of this specification. 1679 "interact": { 1680 "app": true 1681 } 1682 If this interaction mode is supported for this RC and request, the AS 1683 returns an app interaction response with an app URL payload 1684 Section 3.3.2. 1686 [[ Editor's note: this is similar to the "redirect" above today as 1687 most apps use captured URLs, but there seems to be a desire for 1688 splitting the web-based interaction and app-based interaction into 1689 different URIs. There's also the possibility of wanting more in the 1690 payload than can be reasonably put into the URL, or at least having 1691 separate payloads. ]] 1693 2.5.3. Receive a Callback After Interaction 1695 If the RC is capable of receiving a message from the AS indicating 1696 that the RO has completed their interaction, the RC indicates this by 1697 sending the "callback" field. The value of this field is an object 1698 containing the following members. 1700 uri REQUIRED. Indicates the URI to send the RO to after 1701 interaction. This URI MAY be unique per request and MUST be 1702 hosted by or accessible by the RC. This URI MUST NOT contain any 1703 fragment component. This URI MUST be protected by HTTPS, be 1704 hosted on a server local to the RO's browser ("localhost"), or use 1705 an application-specific URI scheme. If the RC needs any state 1706 information to tie to the front channel interaction response, it 1707 MUST use a unique callback URI to link to that ongoing state. The 1708 allowable URIs and URI patterns MAY be restricted by the AS based 1709 on the RC's presented key information. The callback URI SHOULD be 1710 presented to the RO during the interaction phase before redirect. 1711 [[ Editor's note: should we enforce the callback URI to be unique 1712 per request? That helps with some fixation attacks, but not with 1713 others, and it would be problematic for an AS that wants to lock 1714 down each client instance to a single callback instead of a 1715 family/pattern of callbacks. ]] 1717 nonce REQUIRED. Unique value to be used in the calculation of the 1718 "hash" query parameter sent to the callback URL, must be 1719 sufficiently random to be unguessable by an attacker. MUST be 1720 generated by the RC as a unique value for this request. 1722 method REQUIRED. The callback method that the AS will use to 1723 contact the RC. Valid values include "redirect" Section 2.5.3.1 1724 and "push" Section 2.5.3.2, with other values defined by a 1725 registry TBD (Section 12). 1727 hash_method OPTIONAL. The hash calculation mechanism to be used for 1728 the callback hash in Section 4.4.3. Can be one of "sha3" or 1729 "sha2". If absent, the default value is "sha3". [[ Editor's 1730 note: This should be expandable via a registry of cryptographic 1731 options, and it would be good if we didn't define our own 1732 identifiers here. See also note about cryptographic functions in 1733 Section 4.4.3. ]] 1735 "interact": { 1736 "callback": { 1737 "method": "redirect", 1738 "uri": "https://client.example.net/return/123455", 1739 "nonce": "LKLTI25DK82FX4T4QFZC" 1740 } 1741 } 1743 If this interaction mode is supported for this RC and request, the AS 1744 returns a nonce for use in validating the callback response 1745 (Section 3.3.3). Requests to the callback URI MUST be processed as 1746 described in Section 4.4, and the AS MUST require presentation of an 1747 interaction callback reference as described in Section 5.1. 1749 [[ Editor's note: There has been some call for a post-interaction 1750 redirect that is not tied to the underlying security model - 1751 specifically, sending the user over to a client-hosted page with 1752 client-specific instructions on how to continue. This would be 1753 something hosted externally to the client instance, so the client 1754 instance would never see this incoming call. We could accomplish 1755 that using this "callback" post-redirect mechanism but with "method": 1756 "static" or "nonce": false or some other signal to indicate that the 1757 client won't see the incoming request. ]] 1759 [[ Editor's note: The callback information could alternatively be 1760 combined with other methods like "redirect", essentially putting 1761 everything in the "callback" object into the field for the other 1762 objects. However, this would require each method to define its own 1763 set of rules about how callbacks can be used, and we would want them 1764 all to be consistent with each other with clear information about how 1765 the AS is supposed to respond to all of these. 1767 "interact" { 1768 "redirect": { 1769 "method": "redirect", 1770 "uri": "https://client.example.net/return/123455", 1771 "nonce": "LKLTI25DK82FX4T4QFZC" 1772 } 1773 } 1774 So if the object is there, you do the redirect on completion, if the 1775 object isn't there (it's a boolean, like today), you don't redirect 1776 when you're done. Previous versions of this specification used this 1777 structure, but it was abandoned in favor of the current setup to 1778 allow for different combinations of user interaction methods at the 1779 same time while still keeping a consistent security model. OAuth 2's 1780 "grant_type" model has proved to be limiting in unanticipated ways 1781 since it requires an entirely new grant type to be invented any time 1782 there is a new combination of aspects, or it requires each grant type 1783 to have many of the same optionalities. Combining these fields back 1784 into one, in this way, would allow a client to declare that it 1785 expects a callback in response to one kind of interaction method but 1786 not others, and include multiple combinations at once. For example, 1787 if a client wants to allow a user to redirect to the AS and back on 1788 the same device, or to use a usercode on a secondary device without a 1789 callback, and the client wants to offer both modes simultaneously. 1790 This could alternately be accomplished by allowing the client to 1791 "bundle" interaction parameters together, if desirable - for example, 1792 if "interact" were an array, the client would accept any combination 1793 represented by one object. This example binds the "callback" only to 1794 the first "redirect" method, and second (short) "redirect" and 1795 "user_code" method do not use a callback. 1797 "interact": [ 1798 { 1799 "redirect": true, 1800 "callback": { 1801 "method": "redirect", 1802 "uri": "https://client.example.net/return/123455", 1803 "nonce": "LKLTI25DK82FX4T4QFZC" 1804 } 1805 }, 1806 { 1807 "redirect": 255, 1808 "user_code": true 1809 } 1810 ] 1812 It's not clear what a response to such an array would be. Would the 1813 AS pick one of these bundles? Would it be allowed to respond to any 1814 or all of them? Could an AS use different URIs for each bundle? 1815 (This seems likely, at least.) Would there be a security problem if 1816 the AS used the same URI for both bundles, since one requires a front 1817 channel redirect and the other does not? 1819 ]] 1821 2.5.3.1. Receive an HTTP Callback Through the Browser 1823 A callback "method" value of "redirect" indicates that the RC will 1824 expect a call from the RO's browser using the HTTP method GET as 1825 described in Section 4.4.1. 1827 "interact": { 1828 "callback": { 1829 "method": "redirect", 1830 "uri": "https://client.example.net/return/123455", 1831 "nonce": "LKLTI25DK82FX4T4QFZC" 1832 } 1833 } 1835 Requests to the callback URI MUST be processed by the RC as described 1836 in Section 4.4.1. 1838 Since the incoming request to the callback URL is from the RO's 1839 browser, this method is usually used when the RO and RQ are the same 1840 entity. As such, the RC MUST ensure the RQ is present on the request 1841 to prevent substitution attacks. 1843 2.5.3.2. Receive an HTTP Direct Callback 1845 A callback "method" value of "push" indicates that the RC will expect 1846 a call from the AS directly using the HTTP method POST as described 1847 in Section 4.4.2. 1849 "interact": { 1850 "callback": { 1851 "method": "push", 1852 "uri": "https://client.example.net/return/123455", 1853 "nonce": "LKLTI25DK82FX4T4QFZC" 1854 } 1855 } 1857 Requests to the callback URI MUST be processed by the RC as described 1858 in Section 4.4.2. 1860 Since the incoming request to the callback URL is from the AS and not 1861 from the RO's browser, the RC MUST NOT require the RQ to be present 1862 on incoming HTTP the request. 1864 [[ Editor's note: This post-interaction method can be used in 1865 advanced use cases like asynchronous authorization, or simply to 1866 signal the client that it should move to the next part of the 1867 protocol, even when there is no user present at the client. As such 1868 it can feel a little odd being inside the "interact" block of the 1869 protocol, but it does align with the redirect-based "callback" method 1870 and it seems they really should be mutually-exclusive. Additionally, 1871 should there be a method for simply pushing the updated response 1872 directly to the client, instead? ]] 1874 2.5.4. Display a Short User Code 1876 If the RC is capable of displaying or otherwise communicating a 1877 short, human-entered code to the RO, the RC indicates this by sending 1878 the "user_code" field with the boolean value "true". This code is to 1879 be entered at a static URL that does not change at runtime, as 1880 described in Section 3.3.4. 1882 "interact": { 1883 "user_code": true 1884 } 1886 If this interaction mode is supported for this RC and request, the AS 1887 returns a user code and interaction URL as specified in Section 4.2. 1889 2.5.5. Indicate Desired Interaction Locales 1891 If the RC knows the RQ's locale and language preferences, the RC can 1892 send this information to the AS using the "ui_locales" field with an 1893 array of locale strings as defined by [RFC5646]. 1895 "interact": { 1896 "ui_locales": ["en-US", "fr-CA"] 1897 } 1899 If possible, the AS SHOULD use one of the locales in the array, with 1900 preference to the first item in the array supported by the AS. If 1901 none of the given locales are supported, the AS MAY use a default 1902 locale. 1904 2.5.6. Extending Interaction Modes 1906 Additional interaction modes are defined in a registry TBD 1907 (Section 12). 1909 [[ Editor's note: we should have guidance in here about how to define 1910 other interaction modes. There's already interest in defining 1911 message-based protocols like DIDCOMM and challenge-response protocols 1912 like FIDO, for example. ]] 1914 2.6. Declaring RC Capabilities 1916 If the RC supports extension capabilities, it MAY present them to the 1917 AS in the "capabilities" field. This field is an array of strings 1918 representing specific extensions and capabilities, as defined by a 1919 registry TBD (Section 12). 1921 "capabilities": ["ext1", "ext2"] 1923 2.7. Referencing an Existing Grant Request 1925 If the RC has a reference handle from a previously granted request, 1926 it MAY send that reference in the "existing_grant" field. This field 1927 is a single string consisting of the "value" of the "access_token" 1928 returned in a previous request's continuation response (Section 3.1). 1930 "existing_grant": "80UPRY5NM33OMUKMKSKU" 1932 The AS MUST dereference the grant associated with the reference and 1933 process this request in the context of the referenced one. The AS 1934 MUST NOT alter the existing grant associated with the reference. 1936 [[ Editor's note: this basic capability is to allow for both step-up 1937 authorization and downscoped authorization, but by explicitly 1938 creating a new request and not modifying an existing one. What's the 1939 best guidance for how an AS should process this? What are the use 1940 cases that help differentiate this from modification of an existing 1941 request? ]] 1943 2.8. Requesting OpenID Connect Claims 1945 If the RC and AS both support OpenID Connect's claims query language 1946 as defined in [OIDC] Section 5.5, the RC sends the value of the 1947 OpenID Connect "claims" authorization request parameter as a JSON 1948 object under the name "claims" in the root of the request. 1950 "claims": { 1951 "id_token" : { 1952 "email" : { "essential" : true }, 1953 "email_verified" : { "essential" : true } 1954 }, 1955 "userinfo" : { 1956 "name" : { "essential" : true }, 1957 "picture" : null 1958 } 1959 } 1961 The contents of the "claims" parameter have the same semantics as 1962 they do in OpenID Connect's "claims" authorization request parameter, 1963 including all extensions such as [OIDC4IA]. The AS MUST process the 1964 claims object in the same way that it would with an OAuth 2 based 1965 authorization request. 1967 Note that because this is an independent query object, the "claims" 1968 value can augment or alter other portions of the request, namely the 1969 "resources" and "subject" fields. This query language uses the 1970 fields in the top level of the object to indicate the target for any 1971 requested claims. For instance, the "userinfo" target indicates that 1972 a returned access token would grant access to the given claims at the 1973 UserInfo Endpoint, while the "id_token" target indicates that the 1974 claims would be returned in an ID Token as described in Section 3.4. 1976 [[ Editor's note: in order to use the "claims" parameter as defined 1977 in OIDC, we have to violate the principle of orthogonality in 1978 Section 2.9. An alternative approach would be to split up the 1979 portions of the claims request, so that "id_token" claims would go 1980 into the "subject" field and "userinfo" claims would go into the 1981 "resources" request, but this violates the original field definition 1982 from OIDC and gets into the territory of defining an identity schema 1983 request. This approach would also invalidate extensions to the 1984 "claims" standard as each "target" would need to have its own 1985 separate mapping to some part of the GNAP protocol. ]] 1987 [[ Editor's note: I'm not a fan of GNAP defining how OIDC would work 1988 at all and would rather that work be done by the OIDF in an 1989 extension. However, I think it is important for discussion to see 1990 this kind of thing in context with the rest of the protocol, for now. 1991 In the future, I would anticipate this would be defined by the OIDF 1992 as a relatively small but robust identity layer on top of GNAP. ]] 1994 2.9. Extending The Grant Request 1996 The request object MAY be extended by registering new items in a 1997 registry TBD (Section 12). Extensions SHOULD be orthogonal to other 1998 parameters. Extensions MUST document any aspects where the extension 1999 item affects or influences the values or behavior of other request 2000 and response objects. 2002 [[ Editor's note: we should have more guidance and examples on what 2003 possible top-level extensions would look like. ]] 2005 3. Grant Response 2007 In response to a RC's request, the AS responds with a JSON object as 2008 the HTTP entity body. Each possible field is detailed in the 2009 sections below 2011 continue Indicates that the RC can continue the request by making an 2012 additional request using these parameters. Section 3.1 2014 access_token A single access token that the RC can use to call the 2015 RS on behalf of the RO. Section 3.2.1 2017 multiple_access_token Multiple named access tokens that the RC can 2018 use to call the RS on behalf of the RO. Section 3.2.2 2020 interact Indicates that interaction through some set of defined 2021 mechanisms needs to take place. Section 3.3 2023 subject Claims about the RO as known and declared by the AS. 2024 Section 3.4 2026 instance_id An identifier this RC instance can use to identify 2027 itself when making future requests. Section 3.5 2029 user_handle An identifier this RC instance can use to identify its 2030 current RQ when making future requests. Section 3.5 2032 error An error code indicating that something has gone wrong. 2033 Section 3.6 2035 In this example, the AS is returning an interaction URL 2036 (Section 3.3.1), a callback nonce (Section 3.3.3), and a continuation 2037 handle (Section 3.1). 2039 { 2040 "interact": { 2041 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 2042 "callback": "MBDOFXG4Y5CVJCX821LH" 2043 }, 2044 "continue": { 2045 "access_token": { 2046 "value": "80UPRY5NM33OMUKMKSKU", 2047 "key": true 2048 }, 2049 "uri": "https://server.example.com/tx" 2050 } 2051 } 2052 In this example, the AS is returning a bearer access token 2053 (Section 3.2.1) with a management URL and a subject identifier 2054 (Section 3.4) in the form of an email address. 2056 { 2057 "access_token": { 2058 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2059 "key": false, 2060 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2061 }, 2062 "subject": { 2063 "sub_ids": [ { 2064 "subject_type": "email", 2065 "email": "user@example.com", 2066 } ] 2067 } 2068 } 2070 3.1. Request Continuation 2072 If the AS determines that the request can be continued with 2073 additional requests, it responds with the "continue" field. This 2074 field contains a JSON object with the following properties. 2076 uri REQUIRED. The URI at which the RC can make continuation 2077 requests. This URI MAY vary request, or MAY be stable at the AS 2078 if the AS includes an access token. The RC MUST use this value 2079 exactly as given when making a continuation request (Section 5). 2081 wait RECOMMENDED. The amount of time in integer seconds the RC 2082 SHOULD wait after receiving this continuation handle and calling 2083 the URI. 2085 access_token RECOMMENDED. A unique access token for continuing the 2086 request, in the format specified in Section 3.2.1. This access 2087 token MUST be bound to the RC's key used in the request and MUST 2088 NOT be a "bearer" token. This access token MUST NOT be usable at 2089 resources outside of the AS. [[ Editor's note: Is this a 2090 restriction we want to enforce? ]] If the AS includes an access 2091 token, the RC MUST present the access token in all requests to the 2092 continuation URI as described in Section 7. 2094 { 2095 "continue": { 2096 "access_token": { 2097 "value": "80UPRY5NM33OMUKMKSKU", 2098 "key": true 2099 }, 2100 "uri": "https://server.example.com/continue", 2101 "wait": 60 2102 } 2103 } 2105 The RC can use the values of this field to continue the request as 2106 described in Section 5. Note that the RC MUST sign all continuation 2107 requests with its key as described in Section 8. If the AS includes 2108 an "access_token", the RC MUST present the access token in its 2109 continuation request. 2111 This field SHOULD be returned when interaction is expected, to allow 2112 the RC to follow up after interaction has been concluded. 2114 [[ Editor's note: The AS can use the optional "access_token" as a 2115 credential for the client to manage the grant request itself over 2116 time. This is in parallel with access token management as well as RS 2117 access in general. If the AS uses the access token, the continuation 2118 URL can be static, and potentially even the same as the initial 2119 request URL. If the AS does not use an access token here, it needs 2120 to use unique URLs in its response and bind the client's key to 2121 requests to those URLs - or potentially only allow one request per 2122 client at a time. The optionality adds a layer of complexity, but 2123 the client behavior is deterministic in all possible cases and it re- 2124 uses existing functions and structures instead of inventing something 2125 special just to talk to the AS. The optional access token represents 2126 a design compromise, but the working group can decide to either 2127 require the access token on all requests or to remove the access 2128 token functionality and require the security of the continuation 2129 requests be based on unique URLs. ]] 2131 3.2. Access Tokens 2133 If the AS has successfully granted one or more access tokens to the 2134 RC, the AS responds with either the "access_token" or the 2135 "multiple_access_token" field. The AS MUST NOT respond with both the 2136 "access_token" and "multiple_access_token" fields. 2138 [[ Editor's note: I really don't like the dichotomy between 2139 "access_token" and "multiple_access_tokens" and their being mutually 2140 exclusive, and I think we should design away from this pattern toward 2141 something less error-prone. ]] 2143 3.2.1. Single Access Token 2145 If the RC has requested a single access token and the AS has granted 2146 that access token, the AS responds with the "access_token" field. 2147 The value of this field is an object with the following properties. 2149 value REQUIRED. The value of the access token as a string. The 2150 value is opaque to the RC. The value SHOULD be limited to ASCII 2151 characters to facilitate transmission over HTTP headers within 2152 other protocols without requiring additional encoding. 2154 manage OPTIONAL. The management URI for this access token. If 2155 provided, the RC MAY manage its access token as described in 2156 Section 6. This management URI is a function of the AS and is 2157 separate from the RS the RC is requesting access to. This URI 2158 MUST NOT include the access token value and SHOULD be different 2159 for each access token issued in a request. 2161 resources RECOMMENDED. A description of the rights associated with 2162 this access token, as defined in Section 3.2.1. If included, this 2163 MUST reflect the rights associated with the issued access token. 2164 These rights MAY vary from what was requested by the RC. 2166 expires_in OPTIONAL. The number of seconds in which the access will 2167 expire. The RC MUST NOT use the access token past this time. An 2168 RS MUST NOT accept an access token past this time. Note that the 2169 access token MAY be revoked by the AS or RS at any point prior to 2170 its expiration. 2172 key REQUIRED. The key that the token is bound to. If the boolean 2173 value "true" is used, the token is bound to the key used by the RC 2174 (Section 2.3.2) in its request for access. If the boolean value 2175 "false" is used, the token is a bearer token with no key bound to 2176 it. Otherwise, the key MUST be an object or string in a format 2177 described in Section 2.3.2, describing a public key to which the 2178 RC can use the associated private key. The RC MUST be able to 2179 dereference or process the key information in order to be able to 2180 sign the request. 2182 The following non-normative example shows a single bearer token with 2183 a management URL that has access to three described resources. 2185 "access_token": { 2186 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2187 "key": false, 2188 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 2189 "resources": [ 2190 { 2191 "type": "photo-api", 2192 "actions": [ 2193 "read", 2194 "write", 2195 "dolphin" 2196 ], 2197 "locations": [ 2198 "https://server.example.net/", 2199 "https://resource.local/other" 2200 ], 2201 "datatypes": [ 2202 "metadata", 2203 "images" 2204 ] 2205 }, 2206 "read", "dolphin-metadata" 2207 ] 2208 } 2210 The following non-normative example shows a single access token bound 2211 to the RC's key, which was presented using the detached JWS 2212 (Section 8.1) binding method. 2214 "access_token": { 2215 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2216 "key": true, 2217 "resources": [ 2218 "finance", "medical" 2219 ] 2220 } 2222 If the RC requested multiple access tokens (Section 2.1.3), the AS 2223 MUST NOT respond with a single access token structure unless the RC 2224 sends the "split_token" flag as described in Section 2.1.4. 2226 [[ Editor's note: There has been interest in describing a way for the 2227 AS to tell the client both how and where to use the token. This kind 2228 of directed access token could allow for some interesting deployment 2229 patterns where the client doesn't know much]] 2231 3.2.2. Multiple Access Tokens 2233 If the RC has requested multiple access tokens and the AS has granted 2234 at least one of them, the AS responds with the 2235 "multiple_access_tokens" field. The value of this field is a JSON 2236 object, and the property names correspond to the token identifiers 2237 chosen by the RC in the multiple access token request 2238 (Section 2.1.3). The values of the properties of this object are 2239 access tokens as described in Section 3.2.1. 2241 In this non-normative example, two bearer tokens are issued under the 2242 names "token1" and "token2", and only the first token has a 2243 management URL associated with it. 2245 "multiple_access_tokens": { 2246 "token1": { 2247 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2248 "key": false, 2249 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2250 }, 2251 "token2": { 2252 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2253 "key": false 2254 } 2255 } 2257 Each access token corresponds to the named resources arrays in the 2258 RC's request (Section 2.1.3). 2260 The multiple access token response MUST be used when multiple access 2261 tokens are requested, even if only one access token is issued as a 2262 result of the request. The AS MAY refuse to issue one or more of the 2263 requested access tokens, for any reason. In such cases the refused 2264 token is omitted from the response and all of the other issued access 2265 tokens are included in the response the requested names appropriate 2266 names. 2268 If the RC requested a single access token (Section 2.1.1), the AS 2269 MUST NOT respond with the multiple access token structure unless the 2270 RC sends the "split_token" flag as described in Section 2.1.4. 2272 Each access token MAY have different proofing mechanisms. If 2273 management is allowed, each access token SHOULD have different 2274 management URIs. 2276 [[ Editor's note: Do we need to specify that the management URIs are 2277 different if we require the token to be presented? ]] 2279 3.3. Interaction Modes 2281 If the RC has indicated a capability to interact with the RO in its 2282 request (Section 2.5), and the AS has determined that interaction is 2283 both supported and necessary, the AS responds to the RC with any of 2284 the following values in the "interact" field of the response. There 2285 is no preference order for interaction modes in the response, and it 2286 is up to the RC to determine which ones to use. All supported 2287 interaction methods are included in the same "interact" object. 2289 redirect Redirect to an arbitrary URL. Section 3.3.1 2291 app Launch of an application URL. Section 3.3.2 2293 callback Callback to an RC URL after interaction is completed. 2294 Section 3.3.3 2296 user_code Display a short user code. Section 3.3.4 2298 Additional interaction mode responses can be defined in a registry 2299 TBD (Section 12). 2301 The AS MUST NOT respond with any interaction mode that the RC did not 2302 indicate in its request. The AS MUST NOT respond with any 2303 interaction mode that the AS does not support. Since interaction 2304 responses include secret or unique information, the AS SHOULD respond 2305 to each interaction mode only once in an ongoing request, 2306 particularly if the RC modifies its request (Section 5.3). 2308 3.3.1. Redirection to an arbitrary URL 2310 If the RC indicates that it can redirect to an arbitrary URL 2311 (Section 2.5.1) and the AS supports this mode for the RC's request, 2312 the AS responds with the "redirect" field, which is a string 2313 containing the URL to direct the RQ to. This URL MUST be unique for 2314 the request and MUST NOT contain any security-sensitive information. 2316 "interact": { 2317 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2318 } 2320 The interaction URL returned represents a function of the AS but MAY 2321 be completely distinct from the URL the RC uses to request access 2322 (Section 2), allowing an AS to separate its user-interactive 2323 functionality from its back-end security functionality. 2325 [[ Editor's note: This is one aspect where the AS might actually be 2326 two separate roles. Namely, a delegation server (back end) and 2327 interaction server (user-facing).]] 2329 The RC sends the RQ to the URL to interact with the AS. The RC MUST 2330 NOT alter the URL in any way. The means for the RC to send the RQ to 2331 this URL is out of scope of this specification, but common methods 2332 include an HTTP redirect, launching the system browser, displaying a 2333 scannable code, or printing out the URL in an interactive console. 2335 3.3.2. Launch of an application URL 2337 If the RC indicates that it can launch an application URL 2338 (Section 2.5.2) and the AS supports this mode for the RC's request, 2339 the AS responds with the "app" field, which is a string containing 2340 the URL to direct the RQ to. This URL MUST be unique for the request 2341 and MUST NOT contain any security-sensitive information. 2343 "interact": { 2344 "app": "https://app.example.com/launch?tx=4CF492MLV" 2345 } 2347 The RC launches the URL as appropriate on its platform, and the means 2348 for the RC to launch this URL is out of scope of this specification. 2349 The RC MUST NOT alter the URL in any way. The RC MAY attempt to 2350 detect if an installed application will service the URL being sent 2351 before attempting to launch the application URL. 2353 [[ Editor's note: This will probably need to be expanded to an object 2354 to account for other parameters needed in app2app use cases, like 2355 addresses for distributed storage systems, server keys, and the like. 2356 Details TBD as people build this out. ]] 2358 3.3.3. Post-interaction Callback to an RC URL 2360 If the RC indicates that it can receive a post-interaction callback 2361 on a URL (Section 2.5.3) and the AS supports this mode for the RC's 2362 request, the AS responds with a "callback" field containing a nonce 2363 that the RC will use in validating the callback as defined in 2364 Section 4.4.1. 2366 "interact": { 2367 "callback": "MBDOFXG4Y5CVJCX821LH" 2368 } 2370 [[ Editor's note: This is fairly parallel to the request but it kinda 2371 hides the fact that this is a nonce from the AS, not the client. ]] 2372 When the RO completes interaction at the AS, the AS MUST call the 2373 RC's callback URL using the method indicated in the callback request 2374 (Section 2.5.3) as described in Section 4.4.1. 2376 If the AS returns a "callback" nonce, the RC MUST NOT continue a 2377 grant request before it receives the associated interaction reference 2378 on the callback URI. 2380 3.3.4. Display of a Short User Code 2382 If the RC indicates that it can display a short user-typeable code 2383 (Section 2.5.4) and the AS supports this mode for the RC's request, 2384 the AS responds with a "user_code" field. This field is an object 2385 that contains the following members. 2387 code REQUIRED. A unique short code that the user can type into an 2388 authorization server. This string MUST be case-insensitive, MUST 2389 consist of only easily typeable characters (such as letters or 2390 numbers). The time in which this code will be accepted SHOULD be 2391 short lived, such as several minutes. It is RECOMMENDED that this 2392 code be no more than eight characters in length. 2394 url RECOMMENDED. The interaction URL that the RC will direct the RO 2395 to. This URL MUST be stable at the AS such that RCs can be 2396 statically configured with it. 2398 "interact": { 2399 "user_code": { 2400 "code": "A1BC-3DFF", 2401 "url": "https://srv.ex/device" 2402 } 2403 } 2405 The RC MUST communicate the "code" to the RQ in some fashion, such as 2406 displaying it on a screen or reading it out audibly. The "code" is a 2407 one-time-use credential that the AS uses to identify the pending 2408 request from the RC. When the RO enters this code (Section 4.2) into 2409 the AS, the AS MUST determine the pending request that it was 2410 associated with. If the AS does not recognize the entered code, the 2411 AS MUST display an error to the user. If the AS detects too many 2412 unrecognized codes entered, it SHOULD display an error to the user. 2414 The RC SHOULD also communicate the URL if possible to facilitate user 2415 interaction, but since the URL should be stable, the RC should be 2416 able to safely decide to not display this value. As this interaction 2417 mode is designed to facilitate interaction via a secondary device, it 2418 is not expected that the RC redirect the RQ to the URL given here at 2419 runtime. Consequently, the URL needs to be stable enough that a RC 2420 could be statically configured with it, perhaps referring the RQ to 2421 the URL via documentation instead of through an interactive means. 2422 If the RC is capable of communicating an arbitrary URL to the RQ, 2423 such as through a scannable code, the RC can use the "redirect" 2424 (Section 2.5.1) mode for this purpose instead of or in addition to 2425 the user code mode. 2427 The interaction URL returned represents a function of the AS but MAY 2428 be completely distinct from the URL the RC uses to request access 2429 (Section 2), allowing an AS to separate its user-interactive 2430 functionality from its back-end security functionality. 2432 [[ Editor's note: This is one aspect where the AS might actually be 2433 two separate roles. Namely, a delegation server (back end) and 2434 interaction server (user-facing).]] 2436 3.3.5. Extending Interaction Mode Responses 2438 Extensions to this specification can define new interaction mode 2439 responses in a registry TBD (Section 12). Extensions MUST document 2440 the corresponding interaction request. 2442 3.4. Returning User Information 2444 If information about the RO is requested and the AS grants the RC 2445 access to that data, the AS returns the approved information in the 2446 "subject" response field. This field is an object with the following 2447 OPTIONAL properties. 2449 sub_ids An array of subject identifiers for the RO, as defined by 2450 [I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy 2451 considerations are needed around returning identifiers. ]] 2453 assertions An object containing assertions as values keyed on the 2454 assertion type defined by a registry TBD (Section 12). [[ 2455 Editor's note: should this be an array of objects with internal 2456 typing like the sub_ids? Do we expect more than one assertion per 2457 user anyway? ]] 2459 updated_at Timestamp in integer seconds indicating when the 2460 identified account was last updated. The RC MAY use this value to 2461 determine if it needs to request updated profile information 2462 through an identity API. The definition of such an identity API 2463 is out of scope for this specification. 2465 "subject": { 2466 "sub_ids": [ { 2467 "subject_type": "email", 2468 "email": "user@example.com", 2469 } ], 2470 "assertions": { 2471 "id_token": "eyj..." 2472 } 2473 } 2475 The AS MUST return the "subject" field only in cases where the AS is 2476 sure that the RO and the RQ are the same party. This can be 2477 accomplished through some forms of interaction with the RO 2478 (Section 4). 2480 Subject identifiers returned by the AS SHOULD uniquely identify the 2481 RO at the AS. Some forms of subject identifier are opaque to the RC 2482 (such as the subject of an issuer and subject pair), while others 2483 forms (such as email address and phone number) are intended to allow 2484 the RC to correlate the identifier with other account information at 2485 the RC. The RC MUST NOT request or use any returned subject 2486 identifiers for communication purposes (see Section 2.2). That is, a 2487 subject identifier returned in the format of an email address or a 2488 phone number only identifies the RO to the AS and does not indicate 2489 that the AS has validated that the represented email address or phone 2490 number in the identifier is suitable for communication with the 2491 current user. To get such information, the RC MUST use an identity 2492 protocol to request and receive additional identity claims. While 2493 Section 2.8 specifies one such method, other identity protocols could 2494 also be used on top of GNAP to convey this information and the 2495 details of an identity protocol and associated schema are outside the 2496 scope of this specification. 2498 [[ Editor's note: subject identifiers here are naturally scoped to 2499 the AS; even though using an external identifier like an email 2500 address or phone number implies a global namespace in use, the 2501 association of that identifier to the current user is still under the 2502 view of the AS. Would changing the name to "as_sub_ids" or 2503 "local_sub_ids" help convey that point? Would it also be desirable 2504 to have an identifier that's globally unique by design? The 2505 "iss_sub" type almost gets us there by explicitly calling out the 2506 issuer URL, but tuples are hard to deal with in practice and so tend 2507 to get ignored in practice in the OIDC space. ]] 2509 [[ Editor's note: This will need substantial privacy considerations, 2510 as this is releasing information about the current user that could be 2511 tied to other information at the RC or elsewhere. To facilitate 2512 this, should we have another form of identifier that's a globally 2513 unique identifier of some form? DIDs could facilitate that kind of 2514 namespace. ]] 2516 Extensions to this specification MAY define additional response 2517 properties in a registry TBD (Section 12). 2519 3.5. Returning Dynamically-bound Reference Handles 2521 Many parts of the RC's request can be passed as either a value or a 2522 reference. The use of a reference in place of a value allows for a 2523 client to optimize requests to the AS. 2525 Some references, such as for the RC instance's identity 2526 (Section 2.3.1) or the requested resources (Section 2.1.2), can be 2527 managed statically through an admin console or developer portal 2528 provided by the AS or RS. The developer of the RC can include these 2529 values in their code for a more efficient and compact request. 2531 If desired, the AS MAY also generate and return some of these 2532 references dynamically to the RC in its response to facilitate 2533 multiple interactions with the same software. The RC SHOULD use 2534 these references in future requests in lieu of sending the associated 2535 data value. These handles are intended to be used on future 2536 requests. 2538 Dynamically generated handles are string values that MUST be 2539 protected by the RC as secrets. Handle values MUST be unguessable 2540 and MUST NOT contain any sensitive information. Handle values are 2541 opaque to the RC. 2543 [[ Editor's note: these constructs used to be objects to allow for 2544 expansion to future fields, like a management URI or different 2545 presentation types or expiration, but those weren't used in practice. 2546 Is that desirable anymore or is collapsing them like this the right 2547 direction? ]] 2549 All dynamically generated handles are returned as fields in the root 2550 JSON object of the response. This specification defines the 2551 following dynamic handle returns, additional handles can be defined 2552 in a registry TBD (Section 12). 2554 instance_id A string value used to represent the information in the 2555 "client" object that the RC can use in a future request, as 2556 described in Section 2.3.1. 2558 user_handle A string value used to represent the current user. The 2559 RC can use in a future request, as described in Section 2.4.1. 2561 This non-normative example shows two handles along side an issued 2562 access token. 2564 { 2565 "user_handle": "XUT2MFM1XBIKJKSDU8QM", 2566 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2567 "access_token": { 2568 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2569 "key": false 2570 } 2571 } 2573 [[ Editor's note: the ability to dynamically return reference handles 2574 allows for an inline version of dynamic registration without needing 2575 to go through a discrete registration step, for clients where that 2576 makes sense. Currently this is entirely up to the AS to decide when 2577 to issue these, but maybe the client should signal that it can 2578 receive these handles as part of the request? The new "token flags" 2579 construct in Section 2.1.4 almost gets at that, but for a different 2580 part of the request structure. Since the client is the component 2581 that will know if it's in a position to make use of such reference 2582 handles in the future (like a mobile app) or if it's just going to 2583 evaporate at the end of a session (like an SPA). Ultimately we need 2584 to deal with a range of dynamism, not just the "pre-registered" vs. 2585 "non-registered" use cases that OAuth forces us in to. ]] 2587 [[ Editor's note: The client-bound "instance_id" could serve as the 2588 hook we would need for RFC7592 style dynamic client management, 2589 including additional components like key rotation. If the AS returns 2590 an object instead of a string here, that could include everything 2591 that the client would need in order to make REST-style management 2592 calls, similar to token management. 2594 { 2595 "client": { 2596 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2597 "manage": "https://example.server.com/client/7C7C4AZ9KHRS6X63AJAO", 2598 "access_token": { 2599 "value": "4TB8N6BW7OZB8CDFONP219RP1LT0OS9M2PMHKUR6", 2600 "key": true 2601 } 2602 } 2603 } 2604 The client would sign all requests with its key and use the presented 2605 access token. A "POST" or "PATCH" request would update client 2606 information, including having a method for key rotation using nested 2607 signatures. A "DELETE" request would un-register the client, etc. ]] 2609 3.6. Error Response 2611 If the AS determines that the request cannot be issued for any 2612 reason, it responds to the RC with an error message. 2614 error The error code. 2616 { 2618 "error": "user_denied" 2620 } 2622 The error code is one of the following, with additional values 2623 available in a registry TBD (Section 12): 2625 user_denied The RO denied the request. 2627 too_fast The RC did not respect the timeout in the wait response. 2629 unknown_request The request referenced an unknown ongoing access 2630 request. 2632 [[ Editor's note: I think we will need a more robust error mechanism, 2633 and we need to be more clear about what error states are allowed in 2634 what circumstances. Additionally, is the "error" parameter exclusive 2635 with others in the return? ]] 2637 3.7. Extending the Response 2639 Extensions to this specification MAY define additional fields for the 2640 grant response in a registry TBD (Section 12). 2642 [[ Editor's note: what guidance should we give to designers on this? 2643 ]] 2645 4. Interaction at the AS 2647 If the RC indicates that it is capable of driving interaction with 2648 the RO in its request (Section 2.5), and the AS determines that 2649 interaction is required and responds to one or more of the RC's 2650 interaction modes, the RC SHOULD initiate one of the returned 2651 interaction modes in the response (Section 3.3). 2653 When the RO is interacting with the AS, the AS MAY perform whatever 2654 actions it sees fit, including but not limited to: 2656 * authenticate the current user (who may be the RQ) as the RO 2658 * gather consent and authorization from the RO for access to 2659 requested resources and direct information 2661 * allow the RO to modify the parameters of the request (such as 2662 disallowing some requested resources or specifying an account or 2663 record) 2665 * provide warnings to the RO about potential attacks or negative 2666 effects of the requested information 2668 [[ Editor's note: there are some privacy and security considerations 2669 here but for the most part we don't want to be overly prescriptive 2670 about the UX, I think. ]] 2672 4.1. Interaction at a Redirected URI 2674 When the RO is directed to the AS through the "redirect" 2675 (Section 3.3.1) mode, the AS can interact with the RO through their 2676 web browser to authenticate the user as an RO and gather their 2677 consent. Note that since the RC does not add any parameters to the 2678 URL, the AS MUST determine the grant request being referenced from 2679 the URL value itself. If the URL cannot be associated with a 2680 currently active request, the AS MUST display an error to the RO and 2681 MUST NOT attempt to redirect the RO back to any RC even if a callback 2682 is supplied (Section 2.5.3). 2684 The interaction URL MUST be reachable from the RO's browser, though 2685 note that the RO MAY open the URL on a separate device from the RC 2686 itself. The interaction URL MUST be accessible from an HTTP GET 2687 request, and MUST be protected by HTTPS or equivalent means. 2689 With this method, it is common for the RO to be the same party as the 2690 RQ, since the RC has to communicate the redirection URI to the RQ. 2692 4.2. Interaction at the User Code URI 2694 When the RO is directed to the AS through the "user_code" 2695 (Section 3.3.4) mode, the AS can interact with the RO through their 2696 web browser to collect the user code, authenticate the user as an RO, 2697 and gather their consent. Note that since the URL itself is static, 2698 the AS MUST determine the grant request being referenced from the 2699 user code value itself. If the user code cannot be associated with a 2700 currently active request, the AS MUST display an error to the RO and 2701 MUST NOT attempt to redirect the RO back to any RC even if a callback 2702 is supplied (Section 2.5.3). 2704 The user code URL MUST be reachable from the RO's browser, though 2705 note that the RO MAY open the URL on a separate device from the RC 2706 itself. The user code URL MUST be accessible from an HTTP GET 2707 request, and MUST be protected by HTTPS or equivalent means. 2709 While it is common for the RO to be the same party as the RQ, since 2710 the RC has to communicate the user code to someone, there are cases 2711 where the RQ and RO are separate parties and the authorization 2712 happens asynchronously. 2714 4.3. Interaction through an Application URI 2716 When the RC successfully launches an application through the "app" 2717 mode (Section 3.3.2), the AS interacts with the RO through that 2718 application to authenticate the user as the RO and gather their 2719 consent. The details of this interaction are out of scope for this 2720 specification. 2722 [[ Editor's note: Should we have anything to say about an app sending 2723 information to a back-end to get details on the pending request? ]] 2725 4.4. Post-Interaction Completion 2727 Upon completing an interaction with the RO, if a "callback" 2728 (Section 3.3.3) mode is available with the current request, the AS 2729 MUST follow the appropriate method at the end of interaction to allow 2730 the RC to continue. If this mode is not available, the AS SHOULD 2731 instruct the RO to return to their RC software upon completion. Note 2732 that these steps still take place in most error cases, such as when 2733 the RO has denied access. This pattern allows the RC to potentially 2734 recover from the error state without restarting the request from 2735 scratch by modifying its request or providing additional information 2736 directly to the AS. 2738 [[ Editor's note: there might be some other kind of push-based 2739 notification or callback that the client can use, or an out-of-band 2740 non-HTTP protocol. The AS would know about this if supported and 2741 used, but the guidance here should be written in such a way as to not 2742 be too restrictive in the next steps that it can take. Still, it's 2743 important that the AS not expect or even allow clients to poll if the 2744 client has stated it can take a callback of some form, otherwise that 2745 sets up a potential session fixation attack vector that the client is 2746 trying to and able to avoid. There has also been a call for post- 2747 interaction that doesn't tie into the security of the protocol, like 2748 redirecting to a static webpage hosted by the client's company. 2749 Would this fit here? ]] 2751 The AS MUST create an interaction reference and associate that 2752 reference with the current interaction and the underlying pending 2753 request. This value MUST be sufficiently random so as not to be 2754 guessable by an attacker. The interaction reference MUST be one- 2755 time-use. 2757 The AS MUST calculate a hash value based on the RC and AS nonces and 2758 the interaction reference, as described in Section 4.4.3. The RC 2759 will use this value to validate the return call from the AS. 2761 The AS then MUST send the hash and interaction reference based on the 2762 interaction finalization mode as described in the following sections. 2764 4.4.1. Completing Interaction with a Browser Redirect to the Callback 2765 URI 2767 When using the "callback" interaction mode (Section 3.3.3) with the 2768 "redirect" method, the AS signals to the RC that interaction is 2769 complete and the request can be continued by directing the RO (in 2770 their browser) back to the RC's callback URL sent in the callback 2771 request (Section 2.5.3.1). 2773 The AS secures this callback by adding the hash and interaction 2774 reference as query parameters to the RC's callback URL. 2776 hash REQUIRED. The interaction hash value as described in 2777 Section 4.4.3. 2779 interact_ref REQUIRED. The interaction reference generated for this 2780 interaction. 2782 The means of directing the RO to this URL are outside the scope of 2783 this specification, but common options include redirecting the RO 2784 from a web page and launching the system browser with the target URL. 2786 https://client.example.net/return/123455 2787 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2788 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2790 When receiving the request, the RC MUST parse the query parameters to 2791 calculate and validate the hash value as described in Section 4.4.3. 2792 If the hash validates, the RC sends a continuation request to the AS 2793 as described in Section 5.1 using the interaction reference value 2794 received here. 2796 4.4.2. Completing Interaction with a Direct HTTP Request Callback 2798 When using the "callback" interaction mode (Section 3.3.3) with the 2799 "push" method, the AS signals to the RC that interaction is complete 2800 and the request can be continued by sending an HTTP POST request to 2801 the RC's callback URL sent in the callback request (Section 2.5.3.2). 2803 The entity message body is a JSON object consisting of the following 2804 two fields: 2806 hash REQUIRED. The interaction hash value as described in 2807 Section 4.4.3. 2809 interact_ref REQUIRED. The interaction reference generated for this 2810 interaction. 2812 POST /push/554321 HTTP/1.1 2813 Host: client.example.net 2814 Content-Type: application/json 2816 { 2817 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2818 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2819 } 2821 When receiving the request, the RC MUST parse the JSON object and 2822 validate the hash value as described in Section 4.4.3. If the hash 2823 validates, the RC sends a continuation request to the AS as described 2824 in Section 5.1 using the interaction reference value received here. 2826 4.4.3. Calculating the interaction hash 2828 The "hash" parameter in the request to the RC's callback URL ties the 2829 front channel response to an ongoing request by using values known 2830 only to the parties involved. This security mechanism allows the RC 2831 to protect itself against several kinds of session fixation and 2832 injection attacks. The AS MUST always provide this hash, and the RC 2833 MUST validate the hash when received. 2835 [[ Editor's note: If the client uses a unique callback URL per 2836 request, that prevents some of the same attacks, but without the same 2837 cryptographic binding between the interaction and delegation 2838 channels. A unique URI would allow the client to differentiate 2839 inputs, but it would not prevent an attacker from injecting an 2840 unrelated interaction reference into this channel. ]] 2842 To calculate the "hash" value, the party doing the calculation first 2843 takes the "nonce" value sent by the RC in the interaction section of 2844 the initial request (Section 2.5.3), the AS's nonce value from the 2845 callback response (Section 3.3.3), and the "interact_ref" sent to the 2846 RC's callback URL. These three values are concatenated to each other 2847 in this order using a single newline character as a separator between 2848 the fields. There is no padding or whitespace before or after any of 2849 the lines, and no trailing newline character. 2851 VJLO6A4CAYLBXHTR0KRO 2852 MBDOFXG4Y5CVJCX821LH 2853 4IFWWIKYBC2PQ6U56NL1 2855 The party then hashes this string with the appropriate algorithm 2856 based on the "hash_method" parameter of the "callback". If the 2857 "hash_method" value is not present in the RC's request, the algorithm 2858 defaults to "sha3". 2860 [[ Editor's note: these hash algorithms should be pluggable, and 2861 ideally we shouldn't redefine yet another crypto registry for this 2862 purpose, but I'm not convinced an appropriate one already exists. 2863 Furthermore, we should be following best practices here whether it's 2864 a plain hash, a keyed MAC, an HMAC, or some other form of 2865 cryptographic function. I'm not sure what the defaults and options 2866 ought to be, but SHA512 and SHA3 were picked based on what was 2867 available to early developers. ]] 2869 4.4.3.1. SHA3-512 2871 The "sha3" hash method consists of hashing the input string with the 2872 512-bit SHA3 algorithm. The byte array is then encoded using URL 2873 Safe Base64 with no padding. The resulting string is the hash value. 2875 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2877 4.4.3.2. SHA2-512 2879 The "sha2" hash method consists of hashing the input string with the 2880 512-bit SHA2 algorithm. The byte array is then encoded using URL 2881 Safe Base64 with no padding. The resulting string is the hash value. 2883 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bpj84rh4mC9aE9x7HPBFcIHw 2885 5. Continuing a Grant Request 2887 While it is possible for the AS to return a Section 3 with all the 2888 RC's requested information (including access tokens (Section 3.2) and 2889 direct user information (Section 3.4)), it's more common that the AS 2890 and the RC will need to communicate several times over the lifetime 2891 of an access grant. This is often part of facilitating interaction 2892 (Section 4), but it could also be used to allow the AS and RC to 2893 continue negotiating the parameters of the original grant request 2894 (Section 2). 2896 To enable this ongoing negotiation, the AS returns a "continue" field 2897 in the response (Section 3.1) that contains information the RC needs 2898 to continue this process with another request, including a URI to 2899 access as well as an optional access token to use during the 2900 continued requests. 2902 When the RC makes any calls to the continuation URL, the RC MUST 2903 present proof of the most recent key associated with this ongoing 2904 request by signing the request as described in Section 8. The key in 2905 use will be either the key from the initial request (Section 2.3.2) 2906 or its most recent rotation. [[ Editor's note: we need to have a 2907 secure way to rotate the key used for the continuation here. In most 2908 cases this will be a rotation for the client instance, since a client 2909 without an instance record would likely just present a new key for a 2910 new request. In that case it could go with the client management, 2911 above - but it doesn't necessarily have to be. ]] 2913 For example, here the RC makes a POST request and signs with detached 2914 JWS: 2916 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 2917 Host: server.example.com 2918 Detached-JWS: ejy0... 2920 If the AS includes an "access_token" in the "continue" response in 2921 Section 3.1, the RC MUST include the access token the request as 2922 described in Section 7. Note that the access token is always bound 2923 to the RC's presented key (or its most recent rotation). 2925 For example, here the RC makes a POST request with the interaction 2926 reference, includes the access token, and signs with detached JWS: 2928 POST /continue HTTP/1.1 2929 Host: server.example.com 2930 Content-type: application/json 2931 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2932 Detached-JWS: ejy0... 2934 { 2935 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2936 } 2938 The AS MUST be able to tell from the RC's request which specific 2939 ongoing request is being accessed. Common methods for doing so 2940 include using a unique, unguessable URL for each continuation 2941 response, associating the request with the provided access token, or 2942 allowing only a single ongoing grant request for a given RC instance 2943 at a time. If the AS cannot determine a single active grant request 2944 to map the continuation request to, the AS MUST return an error. 2946 The ability to continue an already-started request allows the RC to 2947 perform several important functions, including presenting additional 2948 information from interaction, modifying the initial request, and 2949 getting the current state of the request. 2951 If a "wait" parameter was included in the continuation response 2952 (Section 3.1), the RC MUST NOT call the continuation URI prior to 2953 waiting the number of seconds indicated. If no "wait" period is 2954 indicated, the RC SHOULD wait at least 5 seconds [[ Editor's note: 2955 what's a reasonable amount of time so as not to DOS the server?? ]]. 2956 If the RC does not respect the given wait period, the AS MUST return 2957 an error. 2959 The response from the AS is a JSON object and MAY contain any of the 2960 fields described in Section 3, as described in more detail in the 2961 sections below. 2963 If the AS determines that the RC can make a further continuation 2964 request, the AS MUST include a new "continue" response (Section 3.1). 2965 If the continuation was previously bound to an access token, the new 2966 "continue" response MUST include a bound access token as well, and 2967 this token SHOULD be a new access token. [[ Editor's note: this used 2968 to be a MUST, but is it safe to back off that requirement? ]] If the 2969 AS does not return a new "continue" response, the RC MUST NOT make an 2970 additional continuation request. If a RC does so, the AS MUST return 2971 an error. 2973 For continuation functions that require the RC to send a message 2974 body, the body MUST be a JSON object. 2976 5.1. Continuing After a Completed Interaction 2978 When the AS responds to the RC's "callback" parameter as in 2979 Section 4.4.1, this response includes an interaction reference. The 2980 RC MUST include that value as the field "interact_ref" in a POST 2981 request to the continuation URI. 2983 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 2984 Host: server.example.com 2985 Content-type: application/json 2986 Detached-JWS: ejy0... 2988 { 2989 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2990 } 2992 Since the interaction reference is a one-time-use value as described 2993 in Section 4.4.1, if the RC needs to make additional continuation 2994 calls after this request, the RC MUST NOT include the interaction 2995 reference. If the AS detects an RC submitting the same interaction 2996 reference multiple times, the AS MUST return an error and SHOULD 2997 invalidate the ongoing request. 2999 The Section 3 MAY contain any newly-created access tokens 3000 (Section 3.2) or newly-released subject claims (Section 3.4). The 3001 response MAY contain a new "continue" response (Section 3.1) as 3002 described above. The response SHOULD NOT contain any interaction 3003 responses (Section 3.3). [[ Editor's note: This last one might be 3004 overly restrictive, since some kinds of interaction could require 3005 multiple round trips. We need more examples and experience beyond 3006 redirect-based interaction here. ]] 3008 For example, if the request is successful in causing the AS to issue 3009 access tokens and release subject claims, the response could look 3010 like this: 3012 { 3013 "access_token": { 3014 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3015 "key": false, 3016 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 3017 }, 3018 "subject": { 3019 "sub_ids": [ { 3020 "subject_type": "email", 3021 "email": "user@example.com", 3022 } ] 3023 } 3024 } 3026 With this example, the RC can not make an additional continuation 3027 request because a "continue" field is not included. 3029 [[ Editor's note: other interaction methods, such as a challenge- 3030 response cryptographic protocol, would use a similar construct as 3031 here, but have different rules. Would it be reasonable to allow them 3032 to be combined? Could this be combined further with the "update" 3033 method in Section 5.3? ]] 3035 5.2. Continuing During Pending Interaction 3037 When the RC does not include a "callback" parameter, the RC will 3038 often need to poll the AS until the RO has authorized the request. 3039 To do so, the RC makes a POST request to the continuation URI as in 3040 Section 5.1, but does not include a message body. 3042 POST /continue HTTP/1.1 3043 Host: server.example.com 3044 Content-type: application/json 3045 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3046 Detached-JWS: ejy0... 3048 The Section 3 MAY contain any newly-created access tokens 3049 (Section 3.2) or newly-released subject claims (Section 3.4). The 3050 response MAY contain a new "continue" response (Section 3.1) as 3051 described above. If a "continue" field is included, it SHOULD 3052 include a "wait" field to facilitate a reasonable polling rate by the 3053 RC. The response SHOULD NOT contain interaction responses 3054 (Section 3.3). 3056 For example, if the request has not yet been authorized by the RO, 3057 the AS could respond by telling the RC to make another continuation 3058 request in the future. In this example, a new, unique access token 3059 has been issued for the call, which the RC will use in its next 3060 continuation request. 3062 { 3063 "continue": { 3064 "access_token": { 3065 "value": "33OMUKMKSKU80UPRY5NM", 3066 "key": true 3067 }, 3068 "uri": "https://server.example.com/continue", 3069 "wait": 30 3070 } 3071 } 3073 [[ Editor's note: Do we want to be more precise about what's expected 3074 inside the "continue" object? I think that at least the URI is 3075 required, access token required IF used, etc. This is even if they 3076 haven't changed since last time, and the client will use whatever 3077 value comes back. ]] 3079 [[ Editor's note: extensions to this might need to communicate to the 3080 client what the current state of the user interaction is. This has 3081 been done in similar proprietary protocols, but the details of that 3082 information tend to be highly application specific. Like "user 3083 hasn't logged in yet", "user has logged in but is still sitting at 3084 the page", or "user seems to have wandered off". We might be able to 3085 provide a decent framework for hanging this kind of stuff on. ]] 3087 If the request is successful in causing the AS to issue access tokens 3088 and release subject claims, the response could look like this 3089 example: 3091 { 3092 "access_token": { 3093 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3094 "key": false, 3095 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 3096 }, 3097 "subject": { 3098 "sub_ids": [ { 3099 "subject_type": "email", 3100 "email": "user@example.com", 3101 } ] 3102 } 3103 } 3104 5.3. Modifying an Existing Request 3106 The RC might need to modify an ongoing request, whether or not tokens 3107 have already been issued or claims have already been released. In 3108 such cases, the RC makes an HTTP PATCH request to the continuation 3109 URI and includes any fields it needs to modify. Fields that aren't 3110 included in the request are considered unchanged from the original 3111 request. 3113 The RC MAY include the "resources" and "subject" fields as described 3114 in Section 2.1 and Section 2.2. Inclusion of these fields override 3115 any values in the initial request, which MAY trigger additional 3116 requirements and policies by the AS. For example, if the RC is 3117 asking for more access, the AS could require additional interaction 3118 with the RO to gather additional consent. If the RC is asking for 3119 more limited access, the AS could determine that sufficient 3120 authorization has been granted to the RC and return the more limited 3121 access rights immediately. [[ Editor's note: We could state 3122 something like "resources and subject MUST NOT be the same as in the 3123 initial or previous request" to enforce that this really is a change, 3124 but is there value in calling that out here? Somehow we do probably 3125 want to tell the AS to not let a client simply post the same request 3126 here to rotate access tokens now that we've got an explicit function 3127 for that, right? ]] 3129 The RC MAY include the "interact" field as described in Section 2.5. 3130 Inclusion of this field indicates that the RC is capable of driving 3131 interaction with the RO, and this field replaces any values from a 3132 previous request. The AS MAY respond to any of the interaction 3133 responses as described in Section 3.3, just like it would to a new 3134 request. 3136 The RC MAY include the "user" field as described in Section 2.4 to 3137 present new assertions or information about the RQ. [[ Editor's note: 3138 This would allow the client to do things like gather the user's 3139 identifiers post-request, or gather an assertion from an on-device 3140 element that the AS can verify. It opens up potential avenues for 3141 trouble if the user here is different from the RO that's already 3142 showed up at the AS or race conditions if the RQ's identity changes 3143 mid-stream. But that said, this seems important for multi-log-in 3144 cases and the like, probably. ]] 3146 The RC MUST NOT include the "client" section of the request. [[ 3147 Editor's note: We do not want the client to be able to get swapped 3148 out from underneath the user, especially post-consent. However, 3149 including this field in a PATCH update request might be the place to 3150 define key rotation for the grant request itself, but we'd need to be 3151 very careful of how that works. And it feels like it might have 3152 consequences outside of the request, such as rotating the key for all 3153 ongoing grants for a given client instance, which isn't really 3154 desirable here. We need a lot more discussion and engineering on 3155 this before including it. ]] 3157 The RC MAY include post-interaction responses such as described in 3158 Section 5.1. [[ Editor's note: it seems a little odd to include this 3159 in a request but I can't see a reason to not allow it. ]] 3161 Modification requests MUST NOT alter previously-issued access tokens. 3162 Instead, any access tokens issued from a continuation are considered 3163 new, separate access tokens. The AS MAY revoke existing access 3164 tokens after a modification has occurred. [[ Editor's note: this 3165 might be subject to the "multi_token" flag, but since we're creating 3166 a NEW access token and not rotating an existing one, this seems to be 3167 a different use case. ]] 3169 Modification requests MAY result in previously-issued access tokens 3170 being revoked. [[ Editor's note: there is a solid argument to be made 3171 for always revoking old access tokens here, but we need more 3172 discussion on the boundaries for such a requirement. If they stick 3173 around, it does make a "read" request weird because now we've got 3174 multiple access tokens sticking around associated with a grant 3175 request and no good place to put them. ]] 3177 If the modified request can be granted immediately by the AS, the 3178 Section 3 MAY contain any newly-created access tokens (Section 3.2) 3179 or newly-released subject claims (Section 3.4). The response MAY 3180 contain a new "continue" response (Section 3.1) as described above. 3181 If interaction can occur, the response SHOULD contain interaction 3182 responses (Section 3.3) as well. 3184 For example, an RC initially requests a set of resources using 3185 references: 3187 POST /tx HTTP/1.1 3188 Host: server.example.com 3189 Content-type: application/json 3190 Detached-JWS: ejy0... 3192 { 3193 "resources": [ 3194 "read", "write" 3195 ], 3196 "interact": { 3197 "redirect": true, 3198 "callback": { 3199 "method": "redirect", 3200 "uri": "https://client.example.net/return/123455", 3201 "nonce": "LKLTI25DK82FX4T4QFZC" 3202 } 3203 }, 3204 "client": "987YHGRT56789IOLK" 3205 } 3207 Access is granted by the RO, and a token is issued by the AS. In its 3208 final response, the AS includes a "continue" field: 3210 { 3211 "continue": { 3212 "access_token": { 3213 "value": "80UPRY5NM33OMUKMKSKU", 3214 "key": true 3215 }, 3216 "uri": "https://server.example.com/continue", 3217 "wait": 30 3218 }, 3219 "access_token": ... 3220 } 3222 This allows the RC to make an eventual continuation call. The RC 3223 realizes that it no longer needs "write" access and therefore 3224 modifies its ongoing request, here asking for just "read" access 3225 instead of both "read" and "write" as before. 3227 PATCH /continue HTTP/1.1 3228 Host: server.example.com 3229 Content-type: application/json 3230 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3231 Detached-JWS: ejy0... 3233 { 3234 "resources": [ 3235 "read" 3236 ] 3237 ... 3238 } 3240 The AS replaces the previous "resources" from the first request, 3241 allowing the AS to determine if any previously-granted consent 3242 already applies. In this case, the AS would likely determine that 3243 reducing the breadth of the requested access means that new access 3244 tokens can be issued to the RC. The AS would likely revoke 3245 previously-issued access tokens that had the greater access rights 3246 associated with them. 3248 { 3249 "continue": { 3250 "access_token": { 3251 "value": "M33OMUK80UPRY5NMKSKU", 3252 "key": true 3253 }, 3254 "uri": "https://server.example.com/continue", 3255 "wait": 30 3256 }, 3257 "access_token": ... 3258 } 3260 For another example, the RC initially requests read-only access but 3261 later needs to step up its access. The initial request could look 3262 like this example. 3264 POST /tx HTTP/1.1 3265 Host: server.example.com 3266 Content-type: application/json 3267 Detached-JWS: ejy0... 3269 { 3270 "resources": [ 3271 "read" 3272 ], 3273 "interact": { 3274 "redirect": true, 3275 "callback": { 3276 "method": "redirect", 3277 "uri": "https://client.example.net/return/123455", 3278 "nonce": "LKLTI25DK82FX4T4QFZC" 3279 } 3280 }, 3281 "client": "987YHGRT56789IOLK" 3282 } 3284 Access is granted by the RO, and a token is issued by the AS. In its 3285 final response, the AS includes a "continue" field: 3287 { 3288 "continue": { 3289 "access_token": { 3290 "value": "80UPRY5NM33OMUKMKSKU", 3291 "key": true 3292 }, 3293 "uri": "https://server.example.com/continue", 3294 "wait": 30 3295 }, 3296 "access_token": ... 3297 } 3299 This allows the RC to make an eventual continuation call. The RC 3300 later realizes that it now needs "write" access in addition to the 3301 "read" access. Since this is an expansion of what it asked for 3302 previously, the RC also includes a new interaction section in case 3303 the AS needs to interact with the RO again to gather additional 3304 authorization. Note that the RC's nonce and callback are different 3305 from the initial request. Since the original callback was already 3306 used in the initial exchange, and the callback is intended for one- 3307 time-use, a new one needs to be included in order to use the callback 3308 again. 3310 [[ Editor's note: the net result of this is that interaction requests 3311 are really only meant to be responded to exactly once by the AS. 3312 This isn't spelled out explicitly, but could be included in 3313 Section 2.5 and/or Section 3.3. ]] 3315 PATCH /continue HTTP/1.1 3316 Host: server.example.com 3317 Content-type: application/json 3318 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3319 Detached-JWS: ejy0... 3321 { 3322 "resources": [ 3323 "read", "write" 3324 ], 3325 "interact": { 3326 "redirect": true, 3327 "callback": { 3328 "method": "redirect", 3329 "uri": "https://client.example.net/return/654321", 3330 "nonce": "K82FX4T4LKLTI25DQFZC" 3331 } 3332 } 3333 } 3335 From here, the AS can determine that the RC is asking for more than 3336 it was previously granted, but since the RC has also provided a 3337 mechanism to interact with the RO, the AS can use that to gather the 3338 additional consent. The protocol continues as it would with a new 3339 request. Since the old access tokens are good for a subset of the 3340 rights requested here, the AS might decide to not revoke them. 3341 However, any access tokens granted after this update process are new 3342 access tokens and do not modify the rights of existing access tokens. 3344 5.4. Getting the Current State of a Grant Request 3346 If the RC needs to get the current state of an ongoing grant request, 3347 it makes an HTTP GET request to the continuation URI. This request 3348 MUST NOT alter the grant request in any fashion, including causing 3349 the issuance of new access tokens or modification of interaction 3350 parameters. 3352 The AS MAY include existing access tokens and previously-released 3353 subject claims in the response. The AS MUST NOT issue a new access 3354 token or release a new subject claim in response to this request. 3356 GET /continue HTTP/1.1 3357 Host: server.example.com 3358 Content-type: application/json 3359 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3360 Detached-JWS: ejy0... 3362 The response MAY include any fields described Section 3 that are 3363 applicable to this ongoing request, including the most recently 3364 issued access tokens, any released subject claims, and any currently 3365 active interaction modes. The response MAY contain a new "continue" 3366 response (Section 3.1) as described above. 3368 [[ Editor's note: I'm a little dubious about the need for this 3369 particular function in reality, but including it for completeness 3370 sake. There are a lot of questions we need to answer, such as 3371 whether it's safe to include access tokens and claims in the response 3372 of this kind of "read" at all, and whether it makes sense to include 3373 items like interaction nonces in the response. This discussion 3374 should be driven by the use cases calling for this "read" 3375 functionality. There have been similar functions within proprietary 3376 protocols where the client calls an endpoint at the AS to figure out 3377 where the user is in the interaction process at the AS, letting the 3378 client provide a smarter UI. It doesn't seem like we could do that 3379 in depth here since it would be highly application specific, but that 3380 might be a good example of how to extend a response and give a client 3381 extra information. ]] 3383 5.5. Canceling a Grant Request 3385 If the RC wishes to cancel an ongoing grant request, it makes an HTTP 3386 DELETE request to the continuation URI. 3388 DELETE /continue HTTP/1.1 3389 Host: server.example.com 3390 Content-type: application/json 3391 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3392 Detached-JWS: ejy0... 3394 If the request is successfully cancelled, the AS responds with an 3395 HTTP 202. The AS MUST revoke all associated access tokens, if 3396 possible. 3398 6. Token Management 3400 If an access token response includes the "manage" parameter as 3401 described in Section 3.2.1, the RC MAY call this URL to manage the 3402 access token with any of the actions defined in the following 3403 sections. Other actions are undefined by this specification. 3405 The access token being managed acts as the access element for its own 3406 management API. The RC MUST present proof of an appropriate key 3407 along with the access token. 3409 If the token is sender-constrained (i.e., not a bearer token), it 3410 MUST be sent with the appropriate binding for the access token 3411 (Section 7). 3413 If the token is a bearer token, the RC MUST present proof of the same 3414 key identified in the initial request (Section 2.3.2) as described in 3415 Section 8. 3417 The AS MUST validate the proof and assure that it is associated with 3418 either the token itself or the RC the token was issued to, as 3419 appropriate for the token's presentation type. 3421 [[ Editor's note: Should we allow for "update" to an access token by 3422 the client posting new information from a "request"? It seems this 3423 might make things weird since an access token is generally considered 3424 an unchanging thing, and the client could always request a new access 3425 token if they're allowed to continue the grant request post-issuance 3426 as in Section 5.3. There's also a possibility of being able to 3427 "read" a token's state with a GET, much like token introspection but 3428 using the token's/client's key instead of the RS key. But would a 3429 client need to "read" a token state after issuance? Is there a 3430 security risk to offering that functionality? Introspection is 3431 nearly always relegated to RS calls in practice since the client is 3432 focused on using the token at the RS. The client can always read the 3433 state of the grant itself, separately. ]] 3435 6.1. Rotating the Access Token 3437 The RC makes an HTTP POST to the token management URI, sending the 3438 access token in the appropriate header and signing the request with 3439 the appropriate key. 3441 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3442 Host: server.example.com 3443 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3444 Detached-JWS: eyj0.... 3446 [[ Editor's note: This could alternatively be an HTTP PUT verb, since 3447 we are telling the AS that we want to replace the token. However, we 3448 are not providing the information we want to replace the token with, 3449 and in fact that's up to the AS entirely, not the client. For that 3450 reason, I think a POST still makes the most sense. ]] 3451 The AS validates that the token presented is associated with the 3452 management URL, that the AS issued the token to the given RC, and 3453 that the presented key is appropriate to the token. 3455 If the access token has expired, the AS SHOULD honor the rotation 3456 request to the token management URL since it is likely that the RC is 3457 attempting to refresh the expired token. To support this, the AS MAY 3458 apply different lifetimes for the use of the token in management vs. 3459 its use at an RS. An AS MUST NOT honor a rotation request for an 3460 access token that has been revoked, either by the AS or by the RC 3461 through the token management URI (Section 6.2). 3463 If the token is validated and the key is appropriate for the request, 3464 the AS MUST invalidate the current access token associated with this 3465 URL, if possible, and return a new access token response as described 3466 in Section 3.2.1, unless the "multi_token" flag is specified in the 3467 request. [[ Editor's note: We could also use different verbs to 3468 signal whether or not the old token should be kept around or not, 3469 instead of using a token flag to do this. ]] The value of the access 3470 token MUST NOT be the same as the current value of the access token 3471 used to access the management API. The response MAY include an 3472 updated access token management URL as well, and if so, the RC MUST 3473 use this new URL to manage the new access token. 3475 [[ Editor's note: the net result is that the client's always going to 3476 use the management URL that comes back. But should we let the server 3477 omit it from the response if it doesn't change? That seems like an 3478 odd optimization that doesn't help the client. ]] 3480 { 3481 "access_token": { 3482 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3483 "key": false, 3484 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 3485 "resources": [ 3486 { 3487 "type": "photo-api", 3488 "actions": [ 3489 "read", 3490 "write", 3491 "dolphin" 3492 ], 3493 "locations": [ 3494 "https://server.example.net/", 3495 "https://resource.local/other" 3496 ], 3497 "datatypes": [ 3498 "metadata", 3499 "images" 3500 ] 3501 }, 3502 "read", "dolphin-metadata" 3503 ] 3504 } 3505 } 3507 [[ Editor's note: If the client is using its own key as the proof, 3508 like with a bearer access token, the AS is going to need to know if 3509 the client's key has been rotated. We don't have a mechanism for 3510 rotating the token's key or the client's key yet either - so that 3511 could occur through this management function as well. ]] 3513 6.2. Revoking the Access Token 3515 If the RC wishes to revoke the access token proactively, such as when 3516 a user indicates to the RC that they no longer wish for it to have 3517 access or the RC application detects that it is being uninstalled, 3518 the RC can use the token management URI to indicate to the AS that 3519 the AS should invalidate the access token for all purposes. 3521 The RC makes an HTTP DELETE request to the token management URI, 3522 presenting the access token and signing the request with the 3523 appropriate key. 3525 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3526 Host: server.example.com 3527 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3528 Detached-JWS: eyj0.... 3530 If the key presented is associated with the token (or the RC, in the 3531 case of a bearer token), the AS MUST invalidate the access token, if 3532 possible, and return an HTTP 204 response code. 3534 204 No Content 3536 Though the AS MAY revoke an access token at any time for any reason, 3537 the token management function is specifically for the RC's use. If 3538 the access token has already expired or has been revoked through 3539 other means, the AS SHOULD honor the revocation request to the token 3540 management URL as valid, since the end result is still the token not 3541 being usable. 3543 7. Using Access Tokens 3545 The method the RC uses to send an access token to the RS depends on 3546 the value of the "key" and "proof" parameters in the access token 3547 response (Section 3.2.1). 3549 If the key value is the boolean "false", the access token is a bearer 3550 token sent using the HTTP Header method defined in [RFC6750]. 3552 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3554 The form parameter and query parameter methods of [RFC6750] MUST NOT 3555 be used. 3557 If the "key" value is the boolean "true", the access token MUST be 3558 sent to the RS using the same key and proofing mechanism that the RC 3559 used in its initial request. 3561 If the "key" value is an object, the value of the "proof" field 3562 within the key indicates the particular proofing mechanism to use. 3563 The access token is sent using the HTTP authorization scheme "GNAP" 3564 along with a key proof as described in Section 8 for the key bound to 3565 the access token. For example, a "jwsd"-bound access token is sent 3566 as follows: 3568 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3569 Detached-JWS: eyj0.... 3571 [[ Editor's note: I don't actually like the idea of using only one 3572 header type for differently-bound access tokens. Perhaps instead 3573 these values should somehow reflect the key binding types. Maybe 3574 there can be multiple fields after the "GNAP" keyword using 3575 structured headers? Or a set of derived headers like GNAP-mtls? 3576 This might also be better as a separate specification, like it was in 3577 OAuth 2. However, access tokens should be able to use any key 3578 binding mechanisms here, plus bearer. ]] 3580 8. Binding Keys 3582 Any keys presented by the RC to the AS or RS MUST be validated as 3583 part of the request in which they are presented. The type of binding 3584 used is indicated by the proof parameter of the key section in the 3585 initial request Section 2.3.2. Values defined by this specification 3586 are as follows: 3588 jwsd A detached JWS signature header 3590 jws Attached JWS payload 3592 mtls Mutual TLS certificate verification 3594 dpop OAuth Demonstration of Proof-of-Possession key proof header 3596 httpsig HTTP Signing signature header 3598 oauthpop OAuth PoP key proof authentication header 3600 Additional proofing methods are defined by a registry TBD 3601 (Section 12). 3603 All key binding methods used by this specification MUST cover all 3604 relevant portions of the request, including anything that would 3605 change the nature of the request, to allow for secure validation of 3606 the request by the AS. Relevant aspects include the URI being 3607 called, the HTTP method being used, any relevant HTTP headers and 3608 values, and the HTTP message body itself. The recipient of the 3609 signed message MUST validate all components of the signed message to 3610 ensure that nothing has been tampered with or substituted in a way 3611 that would change the nature of the request. 3613 When used in the GNAP delegation protocol, these key binding 3614 mechanisms allow the AS to ensure that the keys presented by the RC 3615 in the initial request are in control of the party calling any 3616 follow-up or continuation requests. To facilitate this requirement, 3617 all keys in the initial request Section 2.3.2 MUST be proved in all 3618 continuation requests Section 5 and token management requests 3619 Section 6, modulo any rotations on those keys over time that the AS 3620 knows about. The AS MUST validate all keys presented by the RC 3621 (Section 2.3.2) or referenced in an ongoing request for each call 3622 within that request. 3624 [[ Editor's note: We are going to need a way for a client to rotate 3625 its keys securely, even while an ongoing grant is in effect. ]] 3627 When used to bind to an access token, the 3629 8.1. Detached JWS 3631 This method is indicated by "jwsd" in the "proof" field. A JWS 3632 [RFC7515] signature object is created as follows: 3634 The header of the JWS MUST contain the "kid" field of the key bound 3635 to this RC for this request. The JWS header MUST contain an "alg" 3636 field appropriate for the key identified by kid and MUST NOT be 3637 "none". The "b64" field MUST be set to "false" and the "crit" field 3638 MUST contain at least "b64" as specified in [RFC7797] 3640 To protect the request, the JWS header MUST contain the following 3641 additional fields. 3643 htm The HTTP Method used to make this request, as an uppercase ASCII 3644 string. 3646 htu The HTTP URI used for this request, including all path and query 3647 components. 3649 ts A timestamp of the request in integer seconds 3651 at_hash When to bind a request to an access token, the access token 3652 hash value. Its value is the base64url encoding of the left-most 3653 half of the hash of the octets of the ASCII representation of the 3654 "access_token" value, where the hash algorithm used is the hash 3655 algorithm used in the "alg" header parameter of the JWS's JOSE 3656 Header. For instance, if the "alg" is "RS256", hash the 3657 "access_token" value with SHA-256, then take the left-most 128 3658 bits and base64url encode them. 3660 [[ Editor's note: It's not the usual practice to put additional 3661 information into the header of a JWS, but this keeps us from having 3662 to normalize the body serialization. Alternatively, we could add all 3663 these fields to the body of the request, but then it gets awkward for 3664 non-body requests like GET/DELETE. ]] 3665 The payload of the JWS object is the serialized body of the request, 3666 and the object is signed according to detached JWS [RFC7797]. 3668 The RC presents the signature in the Detached-JWS HTTP Header field. 3669 [[ Editor's Note: this is a custom header field, do we need this? It 3670 seems like the best place to put this. ]] 3672 POST /tx HTTP/1.1 3673 Host: server.example.com 3674 Content-Type: application/json 3675 Detached-JWS: eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0. 3676 .Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJnDtD0VuUlVjLfwne8AuUY3U7e8 3677 9zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN5_ysveQnYt9Dqi32w6IOtAywkNUD 3678 ZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK57003WJu-wFn2TJUmAbHuqvUsyTb-nz 3679 YOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_vGbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbL 3680 C18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUbntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVW 3681 peQ 3683 { 3684 "resources": [ 3685 "dolphin-metadata" 3686 ], 3687 "interact": { 3688 "redirect": true, 3689 "callback": { 3690 "method": "redirect", 3691 "uri": "https://client.foo", 3692 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3693 } 3694 }, 3695 "client": { 3696 "proof": "jwsd", 3697 "key": { 3698 "jwk": { 3699 "kty": "RSA", 3700 "e": "AQAB", 3701 "kid": "xyz-1", 3702 "alg": "RS256", 3703 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8 3704 xYJCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPF 3705 vpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyD 3706 SWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS 3707 63WYPHi_Ap2B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFe 3708 kpdfWdiPQddQ6Y1cK2U3obvUg7w" 3709 } 3710 } 3711 "display": { 3712 "name": "My Client Display Name", 3713 "uri": "https://example.net/client" 3714 }, 3715 } 3716 } 3717 If the request being made does not have a message body, such as an 3718 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3719 over an empty payload. 3721 When the server (AS or RS) receives the Detached-JWS header, it MUST 3722 parse its contents as a detached JWS object. The HTTP Body is used 3723 as the payload for purposes of validating the JWS, with no 3724 transformations. 3726 [[ Editor's note: this is a potentially fragile signature mechanism. 3727 It doesn't protect arbitrary headers or other specific aspects of the 3728 request, but it's simple to calculate and useful for body-driven 3729 requests, like the client to the AS. Additionally it is potentially 3730 fragile since a multi-tier system could parse the payload and pass 3731 the parsed payload downstream with potential transformations, making 3732 downstream signature validation impossible. We might want to remove 3733 this in favor of general-purpose HTTP signing, or at least provide 3734 guidance on its use. ]] 3736 8.2. Attached JWS 3738 This method is indicated by "jws" in the "proof" field. A JWS 3739 [RFC7515] signature object is created as follows: 3741 The header of the JWS MUST contain the "kid" field of the key bound 3742 to this RC for this request. The JWS header MUST contain an "alg" 3743 field appropriate for the key identified by kid and MUST NOT be 3744 "none". 3746 To protect the request, the JWS header MUST contain the following 3747 additional fields. 3749 htm The HTTP Method used to make this request, as an uppercase ASCII 3750 string. 3752 htu The HTTP URI used for this request, including all path and query 3753 components. 3755 ts A timestamp of the request in integer seconds 3757 at_hash When to bind a request to an access token, the access token 3758 hash value. Its value is the base64url encoding of the left-most 3759 half of the hash of the octets of the ASCII representation of the 3760 "access_token" value, where the hash algorithm used is the hash 3761 algorithm used in the "alg" header parameter of the JWS's JOSE 3762 Header. For instance, if the "alg" is "RS256", hash the 3763 "access_token" value with SHA-256, then take the left-most 128 3764 bits and base64url encode them. 3766 [[ Editor's note: It's not the usual practice to put additional 3767 information into the header of a JWS, but this keeps us from having 3768 to modify the body to use this signature method. Alternatively, we 3769 could add all these fields to the body of the request, but then it 3770 gets awkward for non-body requests like GET/DELETE. ]] 3772 The payload of the JWS object is the JSON serialized body of the 3773 request, and the object is signed according to JWS and serialized 3774 into compact form [RFC7515]. 3776 The RC presents the JWS as the body of the request along with a 3777 content type of "application/jose". The AS MUST extract the payload 3778 of the JWS and treat it as the request body for further processing. 3780 POST /tx HTTP/1.1 3781 Host: server.example.com 3782 Content-Type: application/jose 3784 eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0.ewogICAgIm 3785 NsaWVudCI6IHsKICAgICAgICAibmFtZSI6ICJNeSBDbGllbnQgRGlzcGxheSBOYW1l 3786 IiwKICAgICAgICAidXJpIjogImh0dHBzOi8vZXhhbXBsZS5uZXQvY2xpZW50IgogIC 3787 AgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgICAgImRvbHBoaW4tbWV0YWRhdGEi 3788 CiAgICBdLAogICAgImludGVyYWN0IjogewogICAgICAgICJyZWRpcmVjdCI6IHRydW 3789 UsCiAgICAgICAgImNhbGxiYWNrIjogewogICAgCQkidXJpIjogImh0dHBzOi8vY2xp 3790 ZW50LmZvbyIsCiAgICAJCSJub25jZSI6ICJWSkxPNkE0Q0FZTEJYSFRSMEtSTyIKIC 3791 AgIAl9CiAgICB9LAogICAgImtleXMiOiB7CgkJInByb29mIjogImp3c2QiLAogICAg 3792 ICAgICJqd2tzIjogewogICAgICAgICAgICAia2V5cyI6IFsKICAgICAgICAgICAgIC 3793 AgIHsKICAgICAgICAgICAgICAgICAgICAia3R5IjogIlJTQSIsCiAgICAgICAgICAg 3794 ICAgICAgICAgImUiOiAiQVFBQiIsCiAgICAgICAgICAgICAgICAgICAgImtpZCI6IC 3795 J4eXotMSIsCiAgICAgICAgICAgICAgICAgICAgImFsZyI6ICJSUzI1NiIsCiAgICAg 3796 ICAgICAgICAgICAgICAgIm4iOiAia09CNXJSNEp2MEdNZUxhWTZfSXRfcjNPUndkZj 3797 hjaV9KdGZmWHlhU3g4eFlKQ0NOYU9LTkpuX096MFloZEhiWFRlV081QW95c3BEV0pi 3798 TjV3XzdiZFdEeGdwRC15NmpuRDF1OVloQk9DV09iTlBGdnBrVE04TEM3U2RYR1JLeD 3799 JrOE1lMnJfR3NzWWx5UnBxdnBCbFk1LWVqQ3l3S1JCZmN0UmNuaFRUR056dGJiREJV 3800 eURTV21GTVZDSGU1bVhUNGNMMEJ3clpDNlMtdXUtTEF4MDZhS3dRT1B3WU9HT3NsSz 3801 hXUG0xeUdka2FBMXVGX0ZwUzZMUzYzV1lQSGlfQXAyQjdfOFdidzR0dHpiTVNfZG9K 3802 dnVEYWdXOEExSXAzZlhGQUh0UkFjS3c3cmRJNF9YbG42NmhKeEZla3BkZldkaVBRZG 3803 RRNlkxY0syVTNvYnZVZzd3IgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBd 3804 CiAgICAgICAgfQogICAgfQp9.Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJ 3805 nDtD0VuUlVjLfwne8AuUY3U7e89zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN 3806 5_ysveQnYt9Dqi32w6IOtAywkNUDZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK5 3807 7003WJu-wFn2TJUmAbHuqvUsyTb-nzYOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_v 3808 GbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbLC18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUb 3809 ntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVWpeQ 3810 If the request being made does not have a message body, such as an 3811 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3812 over an empty payload and passed in the "Detached-JWS" header as 3813 described in Section 8.1. 3815 [[ Editor's note: A downside to this method is that it requires the 3816 content type to be something other than application/json, and it 3817 doesn't work against an RS without additional profiling since it 3818 takes over the request body - plus we have to specify different 3819 delivery locations for a GET vs. a POST, for example. Additionally 3820 it is potentially fragile like a detached JWS since a multi-tier 3821 system could parse the payload and pass the parsed payload downstream 3822 with potential transformations. We might want to remove this in 3823 favor of general-purpose HTTP signing, or at least provide guidance 3824 on its use. ]] 3826 8.3. Mutual TLS 3828 This method is indicated by "mtls" in the "proof" field. The RC 3829 presents its client certificate during TLS negotiation with the 3830 server (either AS or RS). The AS or RS takes the thumbprint of the 3831 client certificate presented during mutual TLS negotiation and 3832 compares that thumbprint to the thumbprint presented by the RC 3833 application as described in [RFC8705] section 3. 3835 POST /tx HTTP/1.1 3836 Host: server.example.com 3837 Content-Type: application/json 3838 SSL_CLIENT_CERT: MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3MDUGA1UEAwwuQmVz 3839 cG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTELMAkG 3840 A1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFgpjYUBic3BrLmlv 3841 MRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQLDANNVEkwHhcN 3842 MTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQDDAlsb2NhbGhv 3843 c3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3DQEJARYRdGxz 3844 Y2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZXJpbmcxDDAK 3845 BgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMmaXQHb 3846 s/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77OmJ4bQLokq 3847 sd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYNDOmCdHww 3848 UjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+aOJytk 3849 vj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nqsmZQc 3850 jfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8puLW 3851 aD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DBs 3852 BgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdGxz 3853 Y2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGxz 3854 Y2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3855 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe 3856 2573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboX 3857 hufHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb 3858 907/p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3k 3859 lwLW9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh 3861 { 3862 "resources": [ 3863 "dolphin-metadata" 3864 ], 3865 "interact": { 3866 "redirect": true, 3867 "callback": { 3868 "method": "redirect", 3869 "uri": "https://client.foo", 3870 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3871 } 3872 }, 3873 "client": { 3874 "display": { 3875 "name": "My Client Display Name", 3876 "uri": "https://example.net/client" 3877 }, 3878 "key": { 3879 "proof": "mtls", 3880 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3 3881 MDUGA1UEAwwuQmVzcG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1d 3882 Ghvcml0eTELMAkGA1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFg 3883 pjYUBic3BrLmlvMRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQ 3884 LDANNVEkwHhcNMTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQD 3885 DAlsb2NhbGhvc3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3D 3886 QEJARYRdGxzY2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZX 3887 JpbmcxDDAKBgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggE 3888 BAMmaXQHbs/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77Om 3889 J4bQLokqsd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYND 3890 OmCdHwwUjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+ 3891 aOJytkvj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nq 3892 smZQcjfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8 3893 puLWaD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4 3894 DBsBgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdG 3895 xzY2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGx 3896 zY2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3897 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe2 3898 573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboXhu 3899 fHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb907 3900 /p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3klwLW 3901 9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh" 3902 } 3903 } 3905 [[ Editor's note: This method requires no changes to the HTTP message 3906 itself, since the security relies on the TLS layer. However, the 3907 application level will need to validate that the certificate key used 3908 in the request is the one expected for the specific request. ]] 3910 8.4. Demonstration of Proof-of-Possession (DPoP) 3912 This method is indicated by "dpop" in the "proof" field. The RC 3913 creates a Demonstration of Proof-of-Possession signature header as 3914 described in [I-D.ietf-oauth-dpop] section 2. In addition to the 3915 required fields, the DPoP body MUST also contain a digest of the 3916 request body: 3918 digest Digest of the request body as the value of the Digest header 3919 defined in [RFC3230]. 3921 POST /tx HTTP/1.1 3922 Host: server.example.com 3923 Content-Type: application/json 3924 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6Il 3925 JTQSIsImUiOiJBUUFCIiwia2lkIjoieHl6LWNsaWVudCIsImFsZyI6IlJTMjU2Iiwibi 3926 I6Inp3Q1RfM2J4LWdsYmJIcmhlWXBZcFJXaVk5SS1uRWFNUnBablJySWpDczZiX2VteV 3927 RrQmtEREVqU3lzaTM4T0M3M2hqMS1XZ3hjUGRLTkdaeUlvSDNRWmVuMU1LeXloUXBMSk 3928 cxLW9MTkxxbTdwWFh0ZFl6U2RDOU8zLW9peXk4eWtPNFlVeU5aclJSZlBjaWhkUUNiT1 3929 9PQzhRdWdtZzlyZ05ET1NxcHBkYU5lYXMxb3Y5UHhZdnhxcnoxLThIYTdna0QwMFlFQ1 3930 hIYUIwNXVNYVVhZEhxLU9fV0l2WVhpY2c2STVqNlM0NFZOVTY1VkJ3dS1BbHluVHhRZE 3931 1BV1AzYll4VlZ5NnAzLTdlVEpva3ZqWVRGcWdEVkRaOGxVWGJyNXlDVG5SaG5oSmd2Zj 3932 NWakRfbWFsTmU4LXRPcUs1T1NEbEhUeTZnRDlOcWRHQ20tUG0zUSJ9fQ.eyJodHRwX21 3933 ldGhvZCI6IlBPU1QiLCJodHRwX3VyaSI6Imh0dHA6XC9cL2hvc3QuZG9ja2VyLmludGV 3934 ybmFsOjk4MzRcL2FwaVwvYXNcL3RyYW5zYWN0aW9uIiwiaWF0IjoxNTcyNjQyNjEzLCJ 3935 qdGkiOiJIam9IcmpnbTJ5QjR4N2pBNXl5RyJ9.aUhftvfw2NoW3M7durkopReTvONng1 3936 fOzbWjAlKNSLL0qIwDgfG39XUyNvwQ23OBIwe6IuvTQ2UBBPklPAfJhDTKd8KHEAfidN 3937 B-LzUOzhDetLg30yLFzIpcEBMLCjb0TEsmXadvxuNkEzFRL-Q-QCg0AXSF1h57eAqZV8 3938 SYF4CQK9OUV6fIWwxLDd3cVTx83MgyCNnvFlG_HDyim1Xx-rxV4ePd1vgDeRubFb6QWj 3939 iKEO7vj1APv32dsux67gZYiUpjm0wEZprjlG0a07R984KLeK1XPjXgViEwEdlirUmpVy 3940 T9tyEYqGrTfm5uautELgMls9sgSyE929woZ59elg 3942 { 3943 "resources": [ 3944 "dolphin-metadata" 3945 ], 3946 "interact": { 3947 "redirect": true, 3948 "callback": { 3949 "method": "redirect", 3950 "uri": "https://client.foo", 3951 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3952 } 3954 }, 3955 "client": { 3956 "display": { 3957 "name": "My Client Display Name", 3958 "uri": "https://example.net/client" 3959 }, 3960 "proof": "dpop", 3961 "key": { 3962 "jwk": { 3963 "kty": "RSA", 3964 "e": "AQAB", 3965 "kid": "xyz-1", 3966 "alg": "RS256", 3967 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xYJ 3968 CCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPFvpkTM 3969 8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCH 3970 e5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2 3971 B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6Y 3972 1cK2U3obvUg7w" 3973 } 3974 } 3975 } 3976 } 3978 [[ Editor's note: this method requires duplication of the key in the 3979 header and the request body, which is redundant and potentially 3980 awkward. The signature also doesn't protect the body of the request. 3981 ]] 3983 8.5. HTTP Signing 3985 This method is indicated by "httpsig" in the "proof" field. The RC 3986 creates an HTTP Signature header as described in 3987 [I-D.ietf-httpbis-message-signatures] section 4. The RC MUST 3988 calculate and present the Digest header as defined in [RFC3230] and 3989 include this header in the signature. 3991 POST /tx HTTP/1.1 3992 Host: server.example.com 3993 Content-Type: application/json 3994 Content-Length: 716 3995 Signature: keyId="xyz-client", algorithm="rsa-sha256", 3996 headers="(request-target) digest content-length", 3997 signature="TkehmgK7GD/z4jGkmcHS67cjVRgm3zVQNlNrrXW32Wv7d 3998 u0VNEIVI/dMhe0WlHC93NP3ms91i2WOW5r5B6qow6TNx/82/6W84p5jqF 3999 YuYfTkKYZ69GbfqXkYV9gaT++dl5kvZQjVk+KZT1dzpAzv8hdk9nO87Xi 4000 rj7qe2mdAGE1LLc3YvXwNxuCQh82sa5rXHqtNT1077fiDvSVYeced0UEm 4001 rWwErVgr7sijtbTohC4FJLuJ0nG/KJUcIG/FTchW9rd6dHoBnY43+3Dzj 4002 CIthXpdH5u4VX3TBe6GJDO6Mkzc6vB+67OWzPwhYTplUiFFV6UZCsDEeu 4003 Sa/Ue1yLEAMg=="]} 4004 Digest: SHA=oZz2O3kg5SEFAhmr0xEBbc4jEfo= 4006 { 4007 "resources": [ 4008 "dolphin-metadata" 4009 ], 4010 "interact": { 4011 "redirect": true, 4012 "callback": { 4013 "method": "push", 4014 "uri": "https://client.foo", 4015 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4016 } 4017 }, 4018 "client": { 4019 "display": { 4020 "name": "My Client Display Name", 4021 "uri": "https://example.net/client" 4022 }, 4023 "proof": "httpsig", 4024 "key": { 4025 "jwk": { 4026 "kty": "RSA", 4027 "e": "AQAB", 4028 "kid": "xyz-1", 4029 "alg": "RS256", 4030 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 4031 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 4032 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 4033 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 4034 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 4035 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 4036 Y1cK2U3obvUg7w" 4037 } 4038 } 4039 } 4040 } 4042 When used to present an access token as in Section 7, the 4043 Authorization header MUST be included in the signature. 4045 8.6. OAuth Proof of Possession (PoP) 4047 This method is indicated by "oauthpop" in the "proof" field. The RC 4048 creates an HTTP Authorization PoP header as described in 4049 [I-D.ietf-oauth-signed-http-request] section 4, with the following 4050 additional requirements: 4052 * The at (access token) field MUST be omitted unless this method is 4053 being used in conjunction with an access token as in Section 7. 4054 [[ Editor's note: this is in contradiction to the referenced spec 4055 which makes this field mandatory. ]] 4057 * The b (body hash) field MUST be calculated and supplied, unless 4058 there is no entity body (such as a GET, OPTIONS, or DELETE 4059 request). 4061 * All components of the URL MUST be calculated and supplied 4063 * The m (method) field MUST be supplied 4065 POST /tx HTTP/1.1 4066 Host: server.example.com 4067 Content-Type: application/json 4068 PoP: eyJhbGciOiJSUzI1NiIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi 4069 QVFBQiIsImtpZCI6Inh5ei1jbGllbnQiLCJhbGciOiJSUzI1NiIsIm4iO 4070 iJ6d0NUXzNieC1nbGJiSHJoZVlwWXBSV2lZOUktbkVhTVJwWm5ScklqQ3 4071 M2Yl9lbXlUa0JrRERFalN5c2kzOE9DNzNoajEtV2d4Y1BkS05HWnlJb0g 4072 zUVplbjFNS3l5aFFwTEpHMS1vTE5McW03cFhYdGRZelNkQzlPMy1vaXl5 4073 OHlrTzRZVXlOWnJSUmZQY2loZFFDYk9fT0M4UXVnbWc5cmdORE9TcXBwZ 4074 GFOZWFzMW92OVB4WXZ4cXJ6MS04SGE3Z2tEMDBZRUNYSGFCMDV1TWFVYW 4075 RIcS1PX1dJdllYaWNnNkk1ajZTNDRWTlU2NVZCd3UtQWx5blR4UWRNQVd 4076 QM2JZeFZWeTZwMy03ZVRKb2t2allURnFnRFZEWjhsVVhicjV5Q1RuUmhu 4077 aEpndmYzVmpEX21hbE5lOC10T3FLNU9TRGxIVHk2Z0Q5TnFkR0NtLVBtM 4078 1EifX0.eyJwIjoiXC9hcGlcL2FzXC90cmFuc2FjdGlvbiIsImIiOiJxa0 4079 lPYkdOeERhZVBTZnc3NnFjamtqSXNFRmxDb3g5bTU5NFM0M0RkU0xBIiw 4080 idSI6Imhvc3QuZG9ja2VyLmludGVybmFsIiwiaCI6W1siQWNjZXB0Iiwi 4081 Q29udGVudC1UeXBlIiwiQ29udGVudC1MZW5ndGgiXSwiVjQ2OUhFWGx6S 4082 k9kQTZmQU5oMmpKdFhTd3pjSGRqMUloOGk5M0h3bEVHYyJdLCJtIjoiUE 4083 9TVCIsInRzIjoxNTcyNjQyNjEwfQ.xyQ47qy8bu4fyK1T3Ru1Sway8wp6 4084 5rfAKnTQQU92AUUU07I2iKoBL2tipBcNCC5zLH5j_WUyjlN15oi_lLHym 4085 fPdzihtt8_Jibjfjib5J15UlifakjQ0rHX04tPal9PvcjwnyZHFcKn-So 4086 Y3wsARn-gGwxpzbsPhiKQP70d2eG0CYQMA6rTLslT7GgdQheelhVFW29i 4087 27NcvqtkJmiAG6Swrq4uUgCY3zRotROkJ13qo86t2DXklV-eES4-2dCxf 4088 cWFkzBAr6oC4Qp7HnY_5UT6IWkRJt3efwYprWcYouOVjtRan3kEtWkaWr 4089 G0J4bPVnTI5St9hJYvvh7FE8JirIg 4091 { 4092 "resources": [ 4093 "dolphin-metadata" 4094 ], 4095 "interact": { 4096 "redirect": true, 4097 "callback": { 4098 "method": "redirect", 4099 "uri": "https://client.foo", 4100 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4101 } 4102 }, 4103 "client": { 4104 "display": { 4105 "name": "My Client Display Name", 4106 "uri": "https://example.net/client" 4107 }, 4108 "proof": "oauthpop", 4109 "key": { 4110 "jwk": { 4111 "kty": "RSA", 4112 "e": "AQAB", 4113 "kid": "xyz-1", 4114 "alg": "RS256", 4115 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 4116 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 4117 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 4118 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 4119 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 4120 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 4121 Y1cK2U3obvUg7w" 4122 } 4123 } 4124 } 4125 } 4127 [[ Editor's note: This is a stale draft from the OAuth working group, 4128 but it does at least provide some basic functionality for protecting 4129 HTTP messages with a signature. This work is likely to be subsumed 4130 by the general-purpose HTTP message signature mechanism in 4131 Section 8.5. ]] 4133 9. Discovery 4135 By design, the protocol minimizes the need for any pre-flight 4136 discovery. To begin a request, the RC only needs to know the 4137 endpoint of the AS and which keys it will use to sign the request. 4138 Everything else can be negotiated dynamically in the course of the 4139 protocol. 4141 However, the AS can have limits on its allowed functionality. If the 4142 RC wants to optimize its calls to the AS before making a request, it 4143 MAY send an HTTP OPTIONS request to the grant request endpoint to 4144 retrieve the server's discovery information. The AS MUST respond 4145 with a JSON document containing the following information: 4147 grant_request_endpoint REQUIRED. The full URL of the AS's grant 4148 request endpoint. This MUST match the URL the RC used to make the 4149 discovery request. 4151 capabilities OPTIONAL. A list of the AS's capabilities. The values 4152 of this result MAY be used by the RC in the capabilities section 4153 (Section 2.6) of the request. 4155 interaction_methods OPTIONAL. A list of the AS's interaction 4156 methods. The values of this list correspond to the possible 4157 fields in the interaction section (Section 2.5) of the request. 4159 key_proofs OPTIONAL. A list of the AS's supported key proofing 4160 mechanisms. The values of this list correspond to possible values 4161 of the "proof" field of the key section (Section 2.3.2) of the 4162 request. 4164 sub_ids OPTIONAL. A list of the AS's supported identifiers. The 4165 values of this list correspond to possible values of the subject 4166 identifier section (Section 2.2) of the request. 4168 assertions OPTIONAL. A list of the AS's supported assertion 4169 formats. The values of this list correspond to possible values of 4170 the subject assertion section (Section 2.2) of the request. 4172 The information returned from this method is for optimization 4173 purposes only. The AS MAY deny any request, or any portion of a 4174 request, even if it lists a capability as supported. For example, a 4175 given RC can be registered with the "mtls" key proofing mechanism, 4176 but the AS also returns other proofing methods, then the AS will deny 4177 a request from that RC using a different proofing mechanism. 4179 10. Resource Servers 4181 In some deployments, a resource server will need to be able to call 4182 the AS for a number of functions. 4184 [[ Editor's note: This section is for discussion of possible advanced 4185 functionality. It seems like it should be a separate document or set 4186 of documents, and it's not even close to being well-baked. This also 4187 adds additional endpoints to the AS, as this is separate from the 4188 token request process, and therefore would require RS-facing 4189 discovery or configuration information to make it work. Also-also, 4190 it does presume the RS can sign requests in the same way that a 4191 client does, but hopefully we can be more consistent with this than 4192 RFC7662 was able to do. ]] 4194 10.1. Introspecting a Token 4196 When the RS receives an access token, it can call the introspection 4197 endpoint at the AS to get token information. [[ Editor's note: this 4198 isn't super different from the token management URIs, but the RS has 4199 no way to get that URI, and it's bound to the RS's keys instead of 4200 the RC's or token's keys. ]] 4202 +------+ +------+ +------+ 4203 | RC |--(1)->| RS | | AS | 4204 | | | |--(2)->| | 4205 | | | |<-(3)--| | 4206 | | | | +------+ 4207 | |<-(4)--| | 4208 +------+ +------+ 4210 1. The RC calls the RS with its access token. 4212 2. The RS introspects the access token value at the AS. The RS 4213 signs the request with its own key (not the RC's key or the 4214 token's key). 4216 3. The AS validates the token value and the RC's request and returns 4217 the introspection response for the token. 4219 4. The RS fulfills the request from the RC. 4221 The RS signs the request with its own key and sends the access token 4222 as the body of the request. 4224 POST /introspect HTTP/1.1 4225 Host: server.example.com 4226 Content-type: application/json 4227 Detached-JWS: ejy0... 4229 { 4230 "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4231 } 4233 The AS responds with a data structure describing the token's current 4234 state and any information the RS would need to validate the token's 4235 presentation, such as its intended proofing mechanism and key 4236 material. 4238 Content-type: application/json 4240 { 4241 "active": true, 4242 "resources": [ 4243 "dolphin-metadata", "some other thing" 4244 ], 4245 "client": { 4246 "key": { 4247 "proof": "httpsig", 4248 "jwk": { 4249 "kty": "RSA", 4250 "e": "AQAB", 4251 "kid": "xyz-1", 4252 "alg": "RS256", 4253 "n": "kOB5rR4Jv0GMeL...." 4254 } 4255 } 4256 } 4257 } 4259 10.2. Deriving a downstream token 4261 Some architectures require an RS to act as an RC and request a 4262 derived access token for a secondary RS. This internal token is 4263 issued in the context of the incoming access token. 4265 +------+ +-------+ +------+ +-------+ 4266 | RC |--(1)->| RS1 | | AS | | RS2 | 4267 | | | |--(2)->| | | | 4268 | | | |<-(3)--| | | | 4269 | | | | +------+ | | 4270 | | | | | | 4271 | | | |-----------(4)------->| | 4272 | | | |<----------(5)--------| | 4273 | |<-(6)--| | | | 4274 +------+ +-------+ +-------+ 4276 1. The RC calls RS1 with an access token. 4278 2. RS1 presents that token to the AS to get a derived token for use 4279 at RS2. RS1 indicates that it has no ability to interact with 4280 the RO. RS1 signs its request with its own key, not the token's 4281 key or the RC's key. 4283 3. The AS returns a derived token to RS1 for use at RS2. 4285 4. RS1 calls RS2 with the token from (3). 4287 5. RS2 fulfills the call from RS1. 4289 6. RS1 fulfills the call from RC. 4291 If the RS needs to derive a token from one presented to it, it can 4292 request one from the AS by making a token request as described in 4293 Section 2 and presenting the existing access token's value in the 4294 "existing_access_token" field. 4296 The RS MUST identify itself with its own key and sign the request. 4298 [[ Editor's note: this is similar to Section 2.7 but based on the 4299 access token and not the grant. We might be able to re-use that 4300 function: the fact that the keys presented are not the ones used for 4301 the access token should indicate that it's a different party and a 4302 different kind of request, but there might be some subtle security 4303 issues there. ]] 4305 POST /tx HTTP/1.1 4306 Host: server.example.com 4307 Content-type: application/json 4308 Detached-JWS: ejy0... 4310 { 4311 "resources": [ 4312 { 4313 "actions": [ 4314 "read", 4315 "write", 4316 "dolphin" 4317 ], 4318 "locations": [ 4319 "https://server.example.net/", 4320 "https://resource.local/other" 4321 ], 4322 "datatypes": [ 4323 "metadata", 4324 "images" 4325 ] 4326 }, 4327 "dolphin-metadata" 4328 ], 4329 "client": "7C7C4AZ9KHRS6X63AJAO", 4330 "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 4331 } 4333 The AS responds with a token as described in Section 3. 4335 10.3. Registering a Resource Handle 4337 If the RS needs to, it can post a set of resources as described in 4338 Section 2.1.1 to the AS's resource registration endpoint. 4340 The RS MUST identify itself with its own key and sign the request. 4342 POST /resource HTTP/1.1 4343 Host: server.example.com 4344 Content-type: application/json 4345 Detached-JWS: ejy0... 4347 { 4348 "resources": [ 4349 { 4350 "actions": [ 4351 "read", 4352 "write", 4353 "dolphin" 4354 ], 4355 "locations": [ 4356 "https://server.example.net/", 4357 "https://resource.local/other" 4358 ], 4359 "datatypes": [ 4360 "metadata", 4361 "images" 4362 ] 4363 }, 4364 "dolphin-metadata" 4365 ], 4366 "client": "7C7C4AZ9KHRS6X63AJAO" 4368 } 4370 The AS responds with a handle appropriate to represent the resources 4371 list that the RS presented. 4373 Content-type: application/json 4375 { 4376 "resource_handle": "FWWIKYBQ6U56NL1" 4377 } 4379 The RS MAY make this handle available as part of a response 4380 (Section 10.4) or as documentation to developers. 4382 [[ Editor's note: It's not an exact match here because the 4383 "resource_handle" returned now represents a collection of objects 4384 instead of a single one. Perhaps we should let this return a list of 4385 strings instead? Or use a different syntax than the resource 4386 request? Also, this borrows heavily from UMA 2's "distributed 4387 authorization" model and, like UMA, might be better suited to an 4388 extension than the core protocol. ]] 4390 10.4. Requesting a Resources With Insufficient Access 4392 If the RC calls an RS without an access token, or with an invalid 4393 access token, the RS MAY respond to the RC with an authentication 4394 header indicating that GNAP. The address of the GNAP endpoint MUST 4395 be sent in the "as_uri" parameter. The RS MAY additionally return a 4396 resource reference that the RC MAY use in its resource request 4397 (Section 2.1). This resource reference handle SHOULD be sufficient 4398 for at least the action the RC was attempting to take at the RS. The 4399 RS MAY use the dynamic resource handle request (Section 10.3) to 4400 register a new resource handle, or use a handle that has been pre- 4401 configured to represent what the AS is protecting. The content of 4402 this handle is opaque to the RS and the RC. 4404 WWW-Authenticate: GNAP as_uri=http://server.example/tx,resource=FWWIKYBQ6U56NL1 4406 The RC then makes a call to the "as_uri" as described in Section 2, 4407 with the value of "resource" as one of the members of a "resources" 4408 array Section 2.1.1. The RC MAY request additional resources and 4409 other information, and MAY request multiple access tokens. 4411 [[ Editor's note: this borrows heavily from UMA 2's "distributed 4412 authorization" model and, like UMA, might be better suited to an 4413 extension than the core protocol. ]] 4415 11. Acknowledgements 4417 The author would like to thank the feedback of the following 4418 individuals for their reviews, implementations, and contributions: 4419 Aaron Parecki, Annabelle Backman, Dick Hardt, Dmitri Zagidulin, 4420 Dmitry Barinov, Fabien Imbault, Francis Pouatcha, George Fletcher, 4421 Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan, Kathleen 4422 Moriarty, Mike Jones, Mike Varley, Nat Sakimura, Takahiko Kawasaki, 4423 Takahiro Tsuchiya. 4425 In particular, the author would like to thank Aaron Parecki and Mike 4426 Jones for insights into how to integrate identity and authentication 4427 systems into the core protocol, and to Dick Hardt for the use cases, 4428 diagrams, and insights provided in the XAuth proposal that have been 4429 incorporated here. The author would like to especially thank Mike 4430 Varley and the team at SecureKey for feedback and development of 4431 early versions of the XYZ protocol that fed into this standards work. 4433 12. IANA Considerations 4435 [[ TBD: There are a lot of items in the document that are expandable 4436 through the use of value registries. ]] 4438 13. Security Considerations 4440 [[ TBD: There are a lot of security considerations to add. ]] 4442 All requests have to be over TLS or equivalent as per [BCP195]. Many 4443 handles act as shared secrets, though they can be combined with a 4444 requirement to provide proof of a key as well. 4446 14. Privacy Considerations 4448 [[ TBD: There are a lot of privacy considerations to add. ]] 4450 Handles are passed between parties and therefore should not contain 4451 any private data. 4453 When user information is passed to the RC, the AS needs to make sure 4454 that it has the permission to do so. 4456 15. Normative References 4458 [BCP195] "Recommendations for Secure Use of Transport Layer 4459 Security (TLS) and Datagram Transport Layer Security 4460 (DTLS)", 2015, . 4462 [I-D.ietf-httpbis-message-signatures] 4463 Backman, A., Richer, J., and M. Sporny, "Signing HTTP 4464 Messages", Work in Progress, Internet-Draft, draft-ietf- 4465 httpbis-message-signatures-00, 10 April 2020, 4466 . 4469 [I-D.ietf-oauth-dpop] 4470 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 4471 Jones, M., and D. Waite, "OAuth 2.0 Demonstration of 4472 Proof-of-Possession at the Application Layer (DPoP)", Work 4473 in Progress, Internet-Draft, draft-ietf-oauth-dpop-01, 1 4474 May 2020, . 4477 [I-D.ietf-oauth-signed-http-request] 4478 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 4479 Signing HTTP Requests for OAuth", Work in Progress, 4480 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 4481 August 2016, . 4484 [I-D.ietf-secevent-subject-identifiers] 4485 Backman, A. and M. Scurtescu, "Subject Identifiers for 4486 Security Event Tokens", Work in Progress, Internet-Draft, 4487 draft-ietf-secevent-subject-identifiers-06, 4 September 4488 2020, . 4491 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 4492 C. Mortimore, "OpenID Connect Core 1.0 incorporating 4493 errata set 1", November 2014, 4494 . 4496 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 4497 Assurance 1.0", October 2019, . 4500 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4501 Requirement Levels", BCP 14, RFC 2119, 4502 DOI 10.17487/RFC2119, March 1997, 4503 . 4505 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 4506 RFC 3230, DOI 10.17487/RFC3230, January 2002, 4507 . 4509 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 4510 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 4511 September 2009, . 4513 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 4514 RFC 6749, DOI 10.17487/RFC6749, October 2012, 4515 . 4517 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 4518 Framework: Bearer Token Usage", RFC 6750, 4519 DOI 10.17487/RFC6750, October 2012, 4520 . 4522 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4523 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4524 2015, . 4526 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 4527 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 4528 . 4530 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4531 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4532 May 2017, . 4534 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4535 Interchange Format", STD 90, RFC 8259, 4536 DOI 10.17487/RFC8259, December 2017, 4537 . 4539 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 4540 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 4541 DOI 10.17487/RFC8693, January 2020, 4542 . 4544 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 4545 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 4546 and Certificate-Bound Access Tokens", RFC 8705, 4547 DOI 10.17487/RFC8705, February 2020, 4548 . 4550 Appendix A. Document History 4552 * -14 4554 - Editorial clarification from design team meetings. 4556 - Added "at_hash" to both JWS methods for use with an access 4557 token. 4559 - Allow attached-JWS method to defer to detached-JWS method for 4560 presentation on a non-body request. 4562 * -13 4564 - Clarified that "subject" request and response aren't for 4565 identity claims, just identifiers. 4567 - Reworked continuation definition in terms of endpoint actions. 4569 - Defined concrete methods for updating an ongoing grant request 4570 using PATCH. 4572 - Defined method for reading current status of grant request 4573 using GET. 4575 - Expanded editorial comments and strawman examples for 4576 alternatives. 4578 * -12 4580 - Collapsed "key" and "display" fields into "client" field. 4582 - Changed continuation to use optional access token. 4584 - Defined flags for special behavior of tokens. 4586 - Defined "key": true to mean access token is bound to client's 4587 key. 4589 - Defined "key": false to indicate an access token. 4591 - Added "Elements" section to list and discuss non-role parts of 4592 the protocol. 4594 * -11 4596 - Updated based on Design Team feedback and reviews. 4598 - Removed oidc_ prefix from several values and used RFC8693 4599 assertion types. 4601 - Changed "client" to "RC" throughout. 4603 - Changed "user" to "RQ" or "RO" as appropriate. 4605 - Added expansions for request and response section 4606 introductions. 4608 - Added refresh examples. 4610 - Added diagrams to RS examples. 4612 - Added ui_locales hint to interaction block. 4614 - Added section on JSON polymorphism. 4616 - Added numerous editorial notes to describe why elements are in 4617 place. 4619 - Added discussion on composition of roles. 4621 - Added requirements for signature methods to cover all aspects 4622 of request and mechanisms to do so. 4624 * -10 4626 - Switched to xml2rfc v3 and markdown source. 4628 - Updated based on Design Team feedback and reviews. 4630 - Added acknowledgements list. 4632 - Added sequence diagrams and explanations. 4634 - Collapsed "short_redirect" into regular redirect request. 4636 - Separated pass-by-reference into subsections. 4638 - Collapsed "callback" and "pushback" into a single mode-switched 4639 method. 4641 - Add OIDC Claims request object example. 4643 * -09 4645 - Major document refactoring based on request and response 4646 capabilities. 4648 - Changed from "claims" language to "subject identifier" 4649 language. 4651 - Added "pushback" interaction capability. 4653 - Removed DIDCOMM interaction (better left to extensions). 4655 - Excised "transaction" language in favor of "Grant" where 4656 appropriate. 4658 - Added token management URLs. 4660 - Added separate continuation URL to use continuation handle 4661 with. 4663 - Added RS-focused functionality section. 4665 - Added notion of extending a grant request based on a previous 4666 grant. 4668 - Simplified returned handle structures. 4670 * -08 4672 - Added attached JWS signature method. 4674 - Added discovery methods. 4676 * -07 4678 - Marked sections as being controlled by a future registry TBD. 4680 * -06 4682 - Added multiple resource requests and multiple access token 4683 response. 4685 * -05 4687 - Added "claims" request and response for identity support. 4689 - Added "capabilities" request for inline discovery support. 4691 * -04 4693 - Added crypto agility for callback return hash. 4695 - Changed "interaction_handle" to "interaction_ref". 4697 * -03 4699 - Removed "state" in favor of "nonce". 4701 - Created signed return parameter for front channel return. 4703 - Changed "client" section to "display" section, as well as 4704 associated handle. 4706 - Changed "key" to "keys". 4708 - Separated key proofing from key presentation. 4710 - Separated interaction methods into booleans instead of "type" 4711 field. 4713 * -02 4715 - Minor editorial cleanups. 4717 * -01 4719 - Made JSON multimodal for handle requests. 4721 - Major updates to normative language and references throughout 4722 document. 4724 - Allowed interaction to split between how the user gets to the 4725 AS and how the user gets back. 4727 * -00 4729 - Initial submission. 4731 Appendix B. Component Data Models 4733 While different implementations of this protocol will have different 4734 realizations of all the components and artifacts enumerated here, the 4735 nature of the protocol implies some common structures and elements 4736 for certain components. This appendix seeks to enumerate those 4737 common elements. 4739 TBD: Client has keys, allowed requested resources, identifier(s), 4740 allowed requested subjects, allowed 4742 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 4743 client keys, policies 4745 TBD: Token has RO, user, client, resource list, RS list, 4747 Appendix C. Example Protocol Flows 4749 The protocol defined in this specification provides a number of 4750 features that can be combined to solve many different kinds of 4751 authentication scenarios. This section seeks to show examples of how 4752 the protocol would be applied for different situations. 4754 Some longer fields, particularly cryptographic information, have been 4755 truncated for display purposes in these examples. 4757 C.1. Redirect-Based User Interaction 4759 In this scenario, the user is the RO and has access to a web browser, 4760 and the client can take front-channel callbacks on the same device as 4761 the user. This combination is analogous to the OAuth 2 Authorization 4762 Code grant type. 4764 The client initiates the request to the AS. Here the client 4765 identifies itself using its public key. 4767 POST /tx HTTP/1.1 4768 Host: server.example.com 4769 Content-type: application/json 4770 Detached-JWS: ejy0... 4772 { 4773 "resources": [ 4774 { 4775 "actions": [ 4776 "read", 4777 "write", 4778 "dolphin" 4779 ], 4780 "locations": [ 4781 "https://server.example.net/", 4782 "https://resource.local/other" 4783 ], 4784 "datatypes": [ 4785 "metadata", 4786 "images" 4787 ] 4788 } 4789 ], 4790 "client": { 4791 "key": { 4792 "proof": "jwsd", 4793 "jwk": { 4794 "kty": "RSA", 4795 "e": "AQAB", 4796 "kid": "xyz-1", 4797 "alg": "RS256", 4798 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 4799 } 4800 } 4801 }, 4802 "interact": { 4803 "redirect": true, 4804 "callback": { 4805 "method": "redirect", 4806 "uri": "https://client.example.net/return/123455", 4807 "nonce": "LKLTI25DK82FX4T4QFZC" 4808 } 4809 } 4810 } 4811 The AS processes the request and determines that the RO needs to 4812 interact. The AS returns the following response giving the client 4813 the information it needs to connect. The AS has also indicated to 4814 the client that it can use the given instance identifier to identify 4815 itself in future requests (Section 2.3.1). 4817 Content-type: application/json 4819 { 4820 "interact": { 4821 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 4822 "callback": "MBDOFXG4Y5CVJCX821LH" 4823 } 4824 "continue": { 4825 "access_token": { 4826 "value": "80UPRY5NM33OMUKMKSKU", 4827 "key": true 4828 }, 4829 "uri": "https://server.example.com/continue" 4830 }, 4831 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 4832 } 4834 The client saves the response and redirects the user to the 4835 interaction_url by sending the following HTTP message to the user's 4836 browser. 4838 HTTP 302 Found 4839 Location: https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ 4841 The user's browser fetches the AS's interaction URL. The user logs 4842 in, is identified as the RO for the resource being requested, and 4843 approves the request. Since the AS has a callback parameter, the AS 4844 generates the interaction reference, calculates the hash, and 4845 redirects the user back to the client with these additional values 4846 added as query parameters. 4848 HTTP 302 Found 4849 Location: https://client.example.net/return/123455 4850 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 4851 &interact_ref=4IFWWIKYBC2PQ6U56NL1 4852 The client receives this request from the user's browser. The client 4853 ensures that this is the same user that was sent out by validating 4854 session information and retrieves the stored pending request. The 4855 client uses the values in this to validate the hash parameter. The 4856 client then calls the continuation URL and presents the handle and 4857 interaction reference in the request body. The client signs the 4858 request as above. 4860 POST /continue HTTP/1.1 4861 Host: server.example.com 4862 Content-type: application/json 4863 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 4864 Detached-JWS: ejy0... 4866 { 4867 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 4868 } 4870 The AS retrieves the pending request based on the handle and issues a 4871 bearer access token and returns this to the client. 4873 Content-type: application/json 4875 { 4876 "access_token": { 4877 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4878 "key": false, 4879 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4880 "resources": [{ 4881 "actions": [ 4882 "read", 4883 "write", 4884 "dolphin" 4885 ], 4886 "locations": [ 4887 "https://server.example.net/", 4888 "https://resource.local/other" 4889 ], 4890 "datatypes": [ 4891 "metadata", 4892 "images" 4893 ] 4894 }] 4895 }, 4896 "continue": { 4897 "access_token": { 4898 "value": "80UPRY5NM33OMUKMKSKU", 4899 "key": true 4900 }, 4901 "uri": "https://server.example.com/continue" 4902 } 4903 } 4905 C.2. Secondary Device Interaction 4907 In this scenario, the user does not have access to a web browser on 4908 the device and must use a secondary device to interact with the AS. 4909 The client can display a user code or a printable QR code. The 4910 client prefers a short URL if one is available, with a maximum of 255 4911 characters in length. The is not able to accept callbacks from the 4912 AS and needs to poll for updates while waiting for the user to 4913 authorize the request. 4915 The client initiates the request to the AS. 4917 POST /tx HTTP/1.1 4918 Host: server.example.com 4919 Content-type: application/json 4920 Detached-JWS: ejy0... 4922 { 4923 "resources": [ 4924 "dolphin-metadata", "some other thing" 4925 ], 4926 "client": "7C7C4AZ9KHRS6X63AJAO", 4927 "interact": { 4928 "redirect": 255, 4929 "user_code": true 4930 } 4931 } 4933 The AS processes this and determines that the RO needs to interact. 4934 The AS supports both long and short redirect URIs for interaction, so 4935 it includes both. Since there is no "callback" the AS does not 4936 include a nonce, but does include a "wait" parameter on the 4937 continuation section because it expects the client to poll for 4938 results. 4940 Content-type: application/json 4942 { 4943 "interact": { 4944 "redirect": "https://srv.ex/MXKHQ", 4945 "user_code": { 4946 "code": "A1BC-3DFF", 4947 "url": "https://srv.ex/device" 4948 } 4949 }, 4950 "continue": { 4951 "uri": "https://server.example.com/continue/80UPRY5NM33OMUKMKSKU", 4952 "wait": 60 4953 } 4954 } 4956 The client saves the response and displays the user code visually on 4957 its screen along with the static device URL. The client also 4958 displays the short interaction URL as a QR code to be scanned. 4960 If the user scans the code, they are taken to the interaction 4961 endpoint and the AS looks up the current pending request based on the 4962 incoming URL. If the user instead goes to the static page and enters 4963 the code manually, the AS looks up the current pending request based 4964 on the value of the user code. In both cases, the user logs in, is 4965 identified as the RO for the resource being requested, and approves 4966 the request. Once the request has been approved, the AS displays to 4967 the user a message to return to their device. 4969 Meanwhile, the client periodically polls the AS every 60 seconds at 4970 the continuation URL. The client signs the request using the same 4971 key and method that it did in the first request. 4973 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 4974 Host: server.example.com 4975 Detached-JWS: ejy0... 4977 The AS retrieves the pending request based on the handle and 4978 determines that it has not yet been authorized. The AS indicates to 4979 the client that no access token has yet been issued but it can 4980 continue to call after another 60 second timeout. 4982 Content-type: application/json 4984 { 4985 "continue": { 4986 "uri": "https://server.example.com/continue/BI9QNW6V9W3XFJK4R02D", 4987 "wait": 60 4988 } 4989 } 4991 Note that the continuation URL has been rotated since it was used by 4992 the client to make this call. The client polls the continuation URL 4993 after a 60 second timeout using the new handle. 4995 POST /continue/BI9QNW6V9W3XFJK4R02D HTTP/1.1 4996 Host: server.example.com 4997 Authorization: GNAP 4998 Detached-JWS: ejy0... 5000 The AS retrieves the pending request based on the URL, determines 5001 that it has been approved, and issues an access token. 5003 Content-type: application/json 5005 { 5006 "access_token": { 5007 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5008 "key": false, 5009 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 5010 "resources": [ 5011 "dolphin-metadata", "some other thing" 5012 ] 5013 } 5014 } 5016 Appendix D. No User Involvement 5018 In this scenario, the client is requesting access on its own behalf, 5019 with no user to interact with. 5021 The client creates a request to the AS, identifying itself with its 5022 public key and using MTLS to make the request. 5024 POST /tx HTTP/1.1 5025 Host: server.example.com 5026 Content-type: application/json 5028 { 5029 "resources": [ 5030 "backend service", "nightly-routine-3" 5031 ], 5032 "client": { 5033 "key": { 5034 "proof": "mtls", 5035 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 5036 } 5037 } 5038 } 5040 The AS processes this and determines that the client can ask for the 5041 requested resources and issues an access token. 5043 Content-type: application/json 5045 { 5046 "access_token": { 5047 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5048 "key": true, 5049 "manage": "https://server.example.com/token", 5050 "resources": [ 5051 "backend service", "nightly-routine-3" 5052 ] 5053 } 5054 } 5056 D.1. Asynchronous Authorization 5058 In this scenario, the client is requesting on behalf of a specific 5059 RO, but has no way to interact with the user. The AS can 5060 asynchronously reach out to the RO for approval in this scenario. 5062 The client starts the request at the AS by requesting a set of 5063 resources. The client also identifies a particular user. 5065 POST /tx HTTP/1.1 5066 Host: server.example.com 5067 Content-type: application/json 5068 Detached-JWS: ejy0... 5070 { 5071 "resources": [ 5072 { 5073 "type": "photo-api", 5074 "actions": [ 5075 "read", 5076 "write", 5077 "dolphin" 5078 ], 5079 "locations": [ 5080 "https://server.example.net/", 5081 "https://resource.local/other" 5082 ], 5083 "datatypes": [ 5084 "metadata", 5085 "images" 5086 ] 5087 }, 5088 "read", "dolphin-metadata", 5089 { 5090 "type": "financial-transaction", 5091 "actions": [ 5092 "withdraw" 5093 ], 5094 "identifier": "account-14-32-32-3", 5095 "currency": "USD" 5096 }, 5097 "some other thing" 5098 ], 5099 "client": "7C7C4AZ9KHRS6X63AJAO", 5100 "user": { 5101 "sub_ids": [ { 5102 "subject_type": "email", 5103 "email": "user@example.com" 5104 } ] 5105 } 5106 } 5108 The AS processes this and determines that the RO needs to interact. 5109 The AS determines that it can reach the identified user 5110 asynchronously and that the identified user does have the ability to 5111 approve this request. The AS indicates to the client that it can 5112 poll for continuation. 5114 Content-type: application/json 5116 { 5117 "continue": { 5118 "access_token": { 5119 "value": "80UPRY5NM33OMUKMKSKU", 5120 "key": true 5121 }, 5122 "uri": "https://server.example.com/continue", 5123 "wait": 60 5124 } 5125 } 5127 The AS reaches out to the RO and prompts them for consent. In this 5128 example, the AS has an application that it can push notifications in 5129 to for the specified account. 5131 Meanwhile, the client periodically polls the AS every 60 seconds at 5132 the continuation URL. 5134 POST /continue HTTP/1.1 5135 Host: server.example.com 5136 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5137 Detached-JWS: ejy0... 5139 The AS retrieves the pending request based on the handle and 5140 determines that it has not yet been authorized. The AS indicates to 5141 the client that no access token has yet been issued but it can 5142 continue to call after another 60 second timeout. 5144 Content-type: application/json 5146 { 5147 "continue": { 5148 "access_token": { 5149 "value": "BI9QNW6V9W3XFJK4R02D", 5150 "key": true 5151 }, 5152 "uri": "https://server.example.com/continue", 5153 "wait": 60 5154 } 5155 } 5157 Note that the continuation handle has been rotated since it was used 5158 by the client to make this call. The client polls the continuation 5159 URL after a 60 second timeout using the new handle. 5161 POST /continue HTTP/1.1 5162 Host: server.example.com 5163 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 5164 Detached-JWS: ejy0... 5166 The AS retrieves the pending request based on the handle and 5167 determines that it has been approved and it issues an access token. 5169 Content-type: application/json 5171 { 5172 "access_token": { 5173 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5174 "key": false, 5175 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 5176 "resources": [ 5177 "dolphin-metadata", "some other thing" 5178 ] 5179 } 5180 } 5182 D.2. Applying OAuth 2 Scopes and Client IDs 5184 While the GNAP protocol is not designed to be directly compatible 5185 with OAuth 2 [RFC6749], considerations have been made to enable the 5186 use of OAuth 2 concepts and constructs more smoothly within the GNAP 5187 protocol. 5189 In this scenario, the client developer has a "client_id" and set of 5190 "scope" values from their OAuth 2 system and wants to apply them to 5191 the new protocol. Traditionally, the OAuth 2 client developer would 5192 put their "client_id" and "scope" values as parameters into a 5193 redirect request to the authorization endpoint. 5195 HTTP 302 Found 5196 Location: https://server.example.com/authorize 5197 ?client_id=7C7C4AZ9KHRS6X63AJAO 5198 &scope=read%20write%20dolphin 5199 &redirect_uri=https://client.example.net/return 5200 &response_type=code 5201 &state=123455 5203 Now the developer wants to make an analogous request to the AS using 5204 the new protocol. To do so, the client makes an HTTP POST and places 5205 the OAuth 2 values in the appropriate places. 5207 POST /tx HTTP/1.1 5208 Host: server.example.com 5209 Content-type: application/json 5210 Detached-JWS: ejy0... 5212 { 5213 "resources": [ 5214 "read", "write", "dolphin" 5215 ], 5216 "client": "7C7C4AZ9KHRS6X63AJAO", 5217 "interact": { 5218 "redirect": true, 5219 "callback": { 5220 "method": "redirect", 5221 "uri": "https://client.example.net/return?state=123455", 5222 "nonce": "LKLTI25DK82FX4T4QFZC" 5223 } 5224 } 5225 } 5227 The client_id can be used to identify the client's keys that it uses 5228 for authentication, the scopes represent resources that the client is 5229 requesting, and the "redirect_uri" and "state" value are pre-combined 5230 into a "callback" URI that can be unique per request. The client 5231 additionally creates a nonce to protect the callback, separate from 5232 the state parameter that it has added to its return URL. 5234 From here, the protocol continues as above. 5236 Appendix E. JSON Structures and Polymorphism 5238 The GNAP protocol makes use of polymorphism within the JSON [RFC8259] 5239 structures used for the protocol. Each portion of this protocol is 5240 defined in terms of the JSON data type that its values can take, 5241 whether it's a string, object, array, boolean, or number. For some 5242 fields, different data types offer different descriptive capabilities 5243 and are used in different situations for the same field. Each data 5244 type provides a different syntax to express the same underlying 5245 semantic protocol element, which allows for optimization and 5246 simplification in many common cases. 5248 Even though JSON is often used to describe strongly typed structures, 5249 JSON on its own is naturally polymorphic. In JSON, the named members 5250 of an object have no type associated with them, and any data type can 5251 be used as the value for any member. In practice, each member has a 5252 semantic type that needs to make sense to the parties creating and 5253 consuming the object. Within this protocol, each object member is 5254 defined in terms of its semantic content, and this semantic content 5255 might have expressions in different concrete data types for different 5256 specific purposes. Since each object member has exactly one value in 5257 JSON, each data type for an object member field is naturally mutually 5258 exclusive with other data types within a single JSON object. 5260 For example, a resource request for a single access token is composed 5261 of an array of resource request descriptions while a request for 5262 multiple access tokens is composed of an object whose member values 5263 are all arrays. Both of these represent requests for access, but the 5264 difference in syntax allows the RC and AS to differentiate between 5265 the two request types in the same request. 5267 Another form of polymorphism in JSON comes from the fact that the 5268 values within JSON arrays need not all be of the same JSON data type. 5269 However, within this protocol, each element within the array needs to 5270 be of the same kind of semantic element for the collection to make 5271 sense, even when the data types are different from each other. 5273 For example, each aspect of a resource request can be described using 5274 an object with multiple dimensional components, or the aspect can be 5275 requested using a string. In both cases, the resource request is 5276 being described in a way that the AS needs to interpret, but with 5277 different levels of specificity and complexity for the RC to deal 5278 with. An API designer can provide a set of common access scopes as 5279 simple strings but still allow RC developers to specify custom access 5280 when needed for more complex APIs. 5282 Extensions to this specification can use different data types for 5283 defined fields, but each extension needs to not only declare what the 5284 data type means, but also provide justification for the data type 5285 representing the same basic kind of thing it extends. For example, 5286 an extension declaring an "array" representation for a field would 5287 need to explain how the array represents something akin to the non- 5288 array element that it is replacing. 5290 Author's Address 5292 Justin Richer (editor) 5293 Bespoke Engineering 5295 Email: ietf@justin.richer.org 5296 URI: https://bspk.io/