idnits 2.17.1 draft-ietf-gnap-core-protocol-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 83 instances of too long lines in the document, the longest one being 285 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (2 November 2020) is 1271 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 4611, 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: 2 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 A. Parecki 5 Expires: 6 May 2021 Okta 6 F. Imbault 7 acert.io 8 2 November 2020 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-01 13 Abstract 15 This document defines a mechanism for delegating authorization to a 16 piece of software, and conveying that delegation to the software. 17 This delegation can include access to a set of APIs as well as 18 information passed directly to the software. 20 This document has been prepared by the GNAP working group design team 21 of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and 22 Justin Richer. This document is intended as a starting point for the 23 working group and includes decision points for discussion and 24 agreement. Many of the features in this proposed protocol can be 25 accomplished in a number of ways. Where possible, the editor has 26 included notes and discussion from the design team regarding the 27 options as understood. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 6 May 2021. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 7 66 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 67 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 10 68 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 12 69 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 14 70 1.4.4. Software-only Authorization . . . . . . . . . . . . . 16 71 1.4.5. Refreshing an Expired Access Token . . . . . . . . . 16 72 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 17 73 2.1. Requesting Resources . . . . . . . . . . . . . . . . . . 19 74 2.1.1. Requesting a Single Access Token . . . . . . . . . . 20 75 2.1.2. Requesting Resources By Reference . . . . . . . . . . 21 76 2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 23 77 2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 25 78 2.2. Requesting User Information . . . . . . . . . . . . . . . 27 79 2.3. Identifying the RC . . . . . . . . . . . . . . . . . . . 28 80 2.3.1. Identifying the RC Instance . . . . . . . . . . . . . 30 81 2.3.2. Identifying the RC Key . . . . . . . . . . . . . . . 31 82 2.3.3. Providing Displayable RC Information . . . . . . . . 32 83 2.3.4. Authenticating the RC . . . . . . . . . . . . . . . . 33 84 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33 85 2.4.1. Identifying the User by Reference . . . . . . . . . . 34 86 2.5. Interacting with the User . . . . . . . . . . . . . . . . 35 87 2.5.1. Redirect to an Arbitrary URL . . . . . . . . . . . . 37 88 2.5.2. Open an Application-specific URL . . . . . . . . . . 37 89 2.5.3. Receive a Callback After Interaction . . . . . . . . 38 90 2.5.4. Display a Short User Code . . . . . . . . . . . . . . 42 91 2.5.5. Indicate Desired Interaction Locales . . . . . . . . 42 92 2.5.6. Extending Interaction Modes . . . . . . . . . . . . . 42 93 2.6. Declaring RC Capabilities . . . . . . . . . . . . . . . . 43 94 2.7. Referencing an Existing Grant Request . . . . . . . . . . 43 95 2.8. Requesting OpenID Connect Claims . . . . . . . . . . . . 43 96 2.9. Extending The Grant Request . . . . . . . . . . . . . . . 44 97 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 45 98 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 46 99 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 100 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 48 101 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 50 102 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 51 103 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 51 104 3.3.2. Launch of an application URL . . . . . . . . . . . . 52 105 3.3.3. Post-interaction Callback to an RC URL . . . . . . . 52 106 3.3.4. Display of a Short User Code . . . . . . . . . . . . 53 107 3.3.5. Extending Interaction Mode Responses . . . . . . . . 54 108 3.4. Returning User Information . . . . . . . . . . . . . . . 54 109 3.5. Returning Dynamically-bound Reference Handles . . . . . . 56 110 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 58 111 3.7. Extending the Response . . . . . . . . . . . . . . . . . 58 112 4. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 58 113 4.1. Interaction at a Redirected URI . . . . . . . . . . . . . 59 114 4.2. Interaction at the User Code URI . . . . . . . . . . . . 59 115 4.3. Interaction through an Application URI . . . . . . . . . 60 116 4.4. Post-Interaction Completion . . . . . . . . . . . . . . . 60 117 4.4.1. Completing Interaction with a Browser Redirect to the 118 Callback URI . . . . . . . . . . . . . . . . . . . . 61 119 4.4.2. Completing Interaction with a Direct HTTP Request 120 Callback . . . . . . . . . . . . . . . . . . . . . . 62 121 4.4.3. Calculating the interaction hash . . . . . . . . . . 62 122 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 64 123 5.1. Continuing After a Completed Interaction . . . . . . . . 66 124 5.2. Continuing During Pending Interaction . . . . . . . . . . 67 125 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69 126 5.4. Getting the Current State of a Grant Request . . . . . . 74 127 5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 128 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75 129 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76 130 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78 131 7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 79 132 8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 133 8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 81 134 8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 84 135 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 89 136 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 91 137 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 92 138 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 93 139 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 95 140 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 96 141 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 97 142 10.2. Deriving a downstream token . . . . . . . . . . . . . . 98 143 10.3. Registering a Resource Handle . . . . . . . . . . . . . 100 144 10.4. Requesting a Resources With Insufficient Access . . . . 101 145 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 101 146 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102 147 13. Security Considerations . . . . . . . . . . . . . . . . . . . 102 148 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 102 149 15. Normative References . . . . . . . . . . . . . . . . . . . . 102 150 Appendix A. Document History . . . . . . . . . . . . . . . . . . 104 151 Appendix B. Component Data Models . . . . . . . . . . . . . . . 105 152 Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 105 153 C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 105 154 C.2. Secondary Device Interaction . . . . . . . . . . . . . . 109 155 Appendix D. No User Involvement . . . . . . . . . . . . . . . . 112 156 D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 113 157 D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 116 158 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 117 159 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 118 161 1. Introduction 163 This protocol allows a piece of software, the resource client, to 164 request delegated authorization to resource servers and direct 165 information. This delegation is facilitated by an authorization 166 server usually on behalf of a resource owner. The requesting party 167 operating the software may interact with the authorization server to 168 authenticate, provide consent, and authorize the request. 170 The process by which the delegation happens is known as a grant, and 171 the GNAP protocol allows for the negotiation of the grant process 172 over time by multiple parties acting in distinct roles. 174 This protocol solves many of the same use cases as OAuth 2.0 175 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 176 have grown up around that ecosystem. However, GNAP is not an 177 extension of OAuth 2.0 and is not intended to be directly compatible 178 with OAuth 2.0. GNAP seeks to provide functionality and solve use 179 cases that OAuth 2.0 cannot easily or cleanly address. Even so, GNAP 180 and OAuth 2.0 will exist in parallel for many deployments, and 181 considerations have been taken to facilitate the mapping and 182 transition from legacy systems to GNAP. Some examples of these can 183 be found in Appendix D.2. 185 1.1. Terminology 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 189 "OPTIONAL" in this document are to be interpreted as described in 190 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 191 capitals, as shown here. 193 1.2. Roles 195 The parties in the GNAP protocol perform actions under different 196 roles. Roles are defined by the actions taken and the expectations 197 leveraged on the role by the overall protocol. 199 Authorization Server (AS) Manages the requested delegations for the 200 RO. The AS issues tokens and directly delegated information to 201 the RC. The AS is defined by its grant endpoint, a single URL 202 that accepts a POST request with a JSON payload. The AS could 203 also have other endpoints, including interaction endpoints and 204 user code endpoints, and these are introduced to the RC as needed 205 during the delegation process. 207 Resource Client (RC, aka "client") Requests tokens from the AS and 208 uses tokens at the RS. An instance of the RC software is 209 identified by its key, which can be known to the AS prior to the 210 first request. The AS determines which policies apply to a given 211 RC, including what it can request and on whose behalf. 213 Resource Server (RS, aka "API") Accepts tokens from the RC issued by 214 the AS and serves delegated resources on behalf of the RO. There 215 could be multiple RSs protected by the AS that the RC will call. 217 Resource Owner (RO) Authorizes the request from the RC to the RS, 218 often interactively at the AS. 220 Requesting Party (RQ, aka "user") Operates and interacts with the 221 RC. 223 The GNAP protocol design does not assume any one deployment 224 architecture, but instead attempts to define roles that can be 225 fulfilled in a number of different ways for different use cases. As 226 long as a given role fulfills all of its obligations and behaviors as 227 defined by the protocol, GNAP does not make additional requirements 228 on its structure or setup. 230 Multiple roles can be fulfilled by the same party, and a given party 231 can switch roles in different instances of the protocol. For 232 example, the RO and RQ in many instances are the same person, where a 233 user is authorizing the RC to act on their own behalf at the RS. In 234 this case, one party fulfills both of the RO and RQ roles, but the 235 roles themselves are still defined separately from each other to 236 allow for other use cases where they are fulfilled by different 237 parties. 239 For another example, in some complex scenarios, an RS receiving 240 requests from one RC can act as an RC for a downstream secondary RS 241 in order to fulfill the original request. In this case, one piece of 242 software is both an RS and an RC from different perspectives, and it 243 fulfills these roles separately as far as the overall protocol is 244 concerned. 246 A single role need not be deployed as a monolithic service. For 247 example, An RC could have components that are installed on the RQ's 248 device as well as a back-end system that it communicates with. If 249 both of these components participate in the delegation protocol, they 250 are both considered part of the RC. 252 For another example, an AS could likewise be built out of many 253 constituent components in a distributed architecture. The component 254 that the RC calls directly could be different from the component that 255 the the RO interacts with to drive consent, since API calls and user 256 interaction have different security considerations in many 257 environments. Furthermore, the AS could need to collect identity 258 claims about the RO from one system that deals with user attributes 259 while generating access tokens at another system that deals with 260 security rights. From the perspective of GNAP, all of these are 261 pieces of the AS and together fulfill the role of the AS as defined 262 by the protocol. 264 [[ Editor's note: The names for the roles are an area of ongoing 265 discussion within the working group, as is the appropriate precision 266 of what activities and expectations a particular role covers. In 267 particular, the AS might be formally decomposed into delegation 268 components, that the client talks to, and interaction components, 269 that the user talks to. Several alternative names have been proposed 270 for different roles and components, including: 272 * Grant Server (for Authorization Server) 274 * Grant Client (for Resource Client) 276 * Operator (for Requesting Party) 278 ]] 280 1.3. Elements 282 In addition to the roles above, the protocol also involves several 283 elements that are acted upon by the roles throughout the process. 285 Access Token A credential representing a set of access rights 286 delegated to the RC. The access token is created by the AS, 287 consumed and verified by the RS, and issued to and carried by the 288 RC. The contents and format of the access token are opaque to the 289 RC. 291 Grant The process by which the RC requests and is given delegated 292 access to the RS by the AS through the authority of the RO. 294 Cryptographic Key A cryptographic element binding a request to a 295 holder of the key. Access tokens and RC instances can be 296 associated with specific keys. 298 Resource A protected API served by the RS and accessed by the RC. 299 Access to this resource is delegated by the RO as part of the 300 grant process. 302 Subject Information Information about the RO that is returned 303 directly to the RC from the AS without the RC making a separate 304 call to an RS. Access to this information is delegated by the RO 305 as part of the grant process. 307 [[ Editor's note: What other core elements need an introduction here? 308 These aren't roles to be taken on by different parties, nor are they 309 descriptions of the possible configurations of parties, but these are 310 still important moving parts within the protocol. ]] 312 1.4. Sequences 314 The GNAP protocol can be used in a variety of ways to allow the core 315 delegation process to take place. Many portions of this process are 316 conditionally present depending on the context of the deployments, 317 and not every step in this overview will happen in all circumstances. 319 Note that a connection between roles in this process does not 320 necessarily indicate that a specific protocol message is sent across 321 the wire between the components fulfilling the roles in question, or 322 that a particular step is required every time. For example, for an 323 RC interested in only getting subject information directly, and not 324 calling an RS, all steps involving the RS below do not apply. 326 In some circumstances, the information needed at a given stage is 327 communicated out-of-band or is pre-configured between the components 328 or entities performing the roles. For example, one entity can fulfil 329 multiple roles, and so explicit communication between the roles is 330 not necessary within the protocol flow. 332 +------------+ +------------+ 333 | Requesting | ~ ~ ~ ~ ~ ~ | Resource | 334 | Party (RQ) | | Owner (RO) | 335 +------------+ +------------+ 336 + + 337 + + 338 (A) (B) 339 + + 340 + + 341 +--------+ + +------------+ 342 |Resource|--------------(1)------+------>| Resource | 343 | Client | + | Server | 344 | (RC) | +---------------+ | (RS) | 345 | |--(2)->| Authorization | | | 346 | |<-(3)--| Server | | | 347 | | | (AS) | | | 348 | |--(4)->| | | | 349 | |<-(5)--| | | | 350 | |--------------(6)------------->| | 351 | | | |<~(7)~~| | 352 | |<-------------(8)------------->| | 353 | |--(9)->| | | | 354 | |<-(10)-| | | | 355 | |--------------(11)------------>| | 356 | | | |<~(12)~| | 357 | |-(13)->| | | | 358 | | | | | | 359 +--------+ +---------------+ +------------+ 361 Legend 362 + + + indicates a possible interaction with a human 363 ----- indicates an interaction between protocol roles 364 ~ ~ ~ indicates a potential equivalence or out-of-band communication between roles 366 * (A) The RQ interacts with the RC to indicate a need for resources 367 on behalf of the RO. This could identify the RS the RC needs to 368 call, the resources needed, or the RO that is needed to approve 369 the request. Note that the RO and RQ are often the same entity in 370 practice. 372 * (1) The RC attempts to call the RS (Section 10.4) to determine 373 what access is needed. The RS informs the RC that access can be 374 granted through the AS. Note that for most situations, the RC 375 already knows which AS to talk to and which kinds of access it 376 needs. 378 * (2) The RC requests access at the AS (Section 2). 380 * (3) The AS processes the request and determines what is needed to 381 fulfill the request. The AS sends its response to the RC 382 (Section 3). 384 * (B) If interaction is required, the AS interacts with the RO 385 (Section 4) to gather authorization. The interactive component of 386 the AS can function using a variety of possible mechanisms 387 including web page redirects, applications, challenge/response 388 protocols, or other methods. The RO approves the request for the 389 RC being operated by the RQ. Note that the RO and RQ are often 390 the same entity in practice. 392 * (4) The RC continues the grant at the AS (Section 5). 394 * (5) If the AS determines that access can be granted, it returns a 395 response to the RC (Section 3) including an access token 396 (Section 3.2) for calling the RS and any directly returned 397 information (Section 3.4) about the RO. 399 * (6) The RC uses the access token (Section 7) to call the RS. 401 * (7) The RS determines if the token is sufficient for the request 402 by examining the token, potentially calling the AS (Section 10.1). 403 Note that the RS could also examine the token directly, call an 404 internal data store, execute a policy engine request, or any 405 number of alternative methods for validating the token and its 406 fitness for the request. 408 * (8) The RC to call the RS (Section 7) using the access token until 409 the RS or RC determine that the token is no longer valid. 411 * (9) When the token no longer works, the RC fetches an updated 412 access token (Section 6.1) based on the rights granted in (5). 414 * (10) The AS issues a new access token (Section 3.2) to the RC. 416 * (11) The RC uses the new access token (Section 7) to call the RS. 418 * (12) The RS determines if the new token is sufficient for the 419 request by examining the token, potentially calling the AS 420 (Section 10.1). 422 * (13) The RC disposes of the token (Section 6.2) once the RC has 423 completed its access of the RS and no longer needs the token. 425 The following sections and Appendix C contain specific guidance on 426 how to use the GNAP protocol in different situations and deployments. 428 1.4.1. Redirect-based Interaction 430 In this example flow, the RC is a web application that wants access 431 to resources on behalf of the current user, who acts as both the 432 requesting party (RQ) and the resource owner (RO). Since the RC is 433 capable of directing the user to an arbitrary URL and receiving 434 responses from the user's browser, interaction here is handled 435 through front-channel redirects using the user's browser. The RC 436 uses a persistent session with the user to ensure the same user that 437 is starting the interaction is the user that returns from the 438 interaction. 440 +--------+ +--------+ +------+ 441 | RC | | AS | | RO | 442 | | | | | + | 443 | |< (1) + Start Session + + + + + + + + + + + + + + + +| RQ | 444 | | | | |(User)| 445 | |--(2)--- Request Access --------->| | | | 446 | | | | | | 447 | |<-(3)-- Interaction Needed -------| | | | 448 | | | | | | 449 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 450 | | | | | | 451 | | | |<+ (5) +>| | 452 | | | | AuthN | | 453 | | | | | | 454 | | | |<+ (6) +>| | 455 | | | | AuthZ | | 456 | | | | | | 457 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 458 | | | | +------+ 459 | |--(8)--- Continue Request ------->| | 460 | | | | 461 | |<-(9)----- Grant Access ----------| | 462 | | | | 463 +--------+ +--------+ 465 1. The RC establishes a verifiable session to the user, in the role 466 of the RQ. 468 2. The RC requests access to the resource (Section 2). The RC 469 indicates that it can redirect to an arbitrary URL 470 (Section 2.5.1) and receive a callback from the browser 471 (Section 2.5.3). The RC stores verification information for its 472 callback in the session created in (1). 474 3. The AS determines that interaction is needed and responds 475 (Section 3) with a URL to send the user to (Section 3.3.1) and 476 information needed to verify the callback (Section 3.3.3) in (7). 477 The AS also includes information the RC will need to continue the 478 request (Section 3.1) in (8). The AS associates this 479 continuation information with an ongoing request that will be 480 referenced in (4), (6), and (8). 482 4. The RC stores the verification and continuation information from 483 (3) in the session from (1). The RC then redirects the user to 484 the URL (Section 4.1) given by the AS in (3). The user's browser 485 loads the interaction redirect URL. The AS loads the pending 486 request based on the incoming URL generated in (3). 488 5. The user authenticates at the AS, taking on the role of the RO. 490 6. As the RO, the user authorizes the pending request from the RC. 492 7. When the AS is done interacting with the user, the AS redirects 493 the user back (Section 4.4.1) to the RC using the callback URL 494 provided in (2). The callback URL is augmented with an 495 interaction reference that the AS associates with the ongoing 496 request created in (2) and referenced in (4). The callback URL 497 is also augmented with a hash of the security information 498 provided in (2) and (3). The RC loads the verification 499 information from (2) and (3) from the session created in (1). 500 The RC calculates a hash (Section 4.4.3) based on this 501 information and continues only if the hash validates. Note that 502 the RC needs to ensure that the parameters for the incoming 503 request match those that it is expecting from the session created 504 in (1). The RC also needs to be prepared for the RQ never being 505 returned to the RC and handle time outs appropriately. 507 8. The RC loads the continuation information from (3) and sends the 508 interaction reference from (7) in a request to continue the 509 request (Section 5.1). The AS validates the interaction 510 reference ensuring that the reference is associated with the 511 request being continued. 513 9. If the request has been authorized, the AS grants access to the 514 information in the form of access tokens (Section 3.2) and direct 515 subject information (Section 3.4) to the RC. 517 An example set of protocol messages for this method can be found in 518 Appendix C.1. 520 1.4.2. User-code Interaction 522 In this example flow, the RC is a device that is capable of 523 presenting a short, human-readable code to the user and directing the 524 user to enter that code at a known URL. The RC is not capable of 525 presenting an arbitrary URL to the user, nor is it capable of 526 accepting incoming HTTP requests from the user's browser. The RC 527 polls the AS while it is waiting for the RO to authorize the request. 528 The user's interaction is assumed to occur on a secondary device. In 529 this example it is assumed that the user is both the RQ and RO, 530 though the user is not assumed to be interacting with the RC through 531 the same web browser used for interaction at the AS. 533 +--------+ +--------+ +------+ 534 | RC | | AS | | RO | 535 | |--(1)--- Request Access --------->| | | + | 536 | | | | | RQ | 537 | |<-(2)-- Interaction Needed -------| | |(User)| 538 | | | | | | 539 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 540 | | | | | | 541 | | | |<+ (4) + | | 542 | | | |Open URI | | 543 | | | | | | 544 | | | |<+ (5) +>| | 545 | | | | AuthN | | 546 | |--(9)--- Continue Request (A) --->| | | | 547 | | | |<+ (6) +>| | 548 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 549 | | | | | | 550 | | | |<+ (7) +>| | 551 | | | | AuthZ | | 552 | | | | | | 553 | | | |<+ (8) +>| | 554 | | | |Completed| | 555 | | | | | | 556 | |--(11)-- Continue Request (B) --->| | +------+ 557 | | | | 558 | |<-(12)----- Grant Access ---------| | 559 | | | | 560 +--------+ +--------+ 562 1. The RC requests access to the resource (Section 2). The RC 563 indicates that it can display a user code (Section 2.5.4). 565 2. The AS determines that interaction is needed and responds 566 (Section 3) with a user code to communicate to the user 567 (Section 3.3.4). This could optionally include a URL to direct 568 the user to, but this URL should be static and so could be 569 configured in the RC's documentation. The AS also includes 570 information the RC will need to continue the request 571 (Section 3.1) in (8) and (10). The AS associates this 572 continuation information with an ongoing request that will be 573 referenced in (4), (6), (8), and (10). 575 3. The RC stores the continuation information from (2) for use in 576 (8) and (10). The RC then communicates the code to the user 577 (Section 4.1) given by the AS in (2). 579 4. The user's directs their browser to the user code URL. This URL 580 is stable and can be communicated via the RC's documentation, 581 the AS documentation, or the RC software itself. Since it is 582 assumed that the RO will interact with the AS through a 583 secondary device, the RC does not provide a mechanism to launch 584 the RO's browser at this URL. 586 5. The RQ authenticates at the AS, taking on the role of the RO. 588 6. The RO enters the code communicated in (3) to the AS. The AS 589 validates this code against a current request in process. 591 7. As the RO, the user authorizes the pending request from the RC. 593 8. When the AS is done interacting with the user, the AS indicates 594 to the RO that the request has been completed. 596 9. Meanwhile, the RC loads the continuation information stored at 597 (3) and continues the request (Section 5). The AS determines 598 which ongoing access request is referenced here and checks its 599 state. 601 10. If the access request has not yet been authorized by the RO in 602 (6), the AS responds to the RC to continue the request 603 (Section 3.1) at a future time through additional polled 604 continuation requests. This response can include updated 605 continuation information as well as information regarding how 606 long the RC should wait before calling again. The RC replaces 607 its stored continuation information from the previous response 608 (2). Note that the AS may need to determine that the RO has not 609 approved the request in a sufficient amount of time and return 610 an appropriate error to the RC. 612 11. The RC continues to poll the AS (Section 5.2) with the new 613 continuation information in (9). 615 12. If the request has been authorized, the AS grants access to the 616 information in the form of access tokens (Section 3.2) and 617 direct subject information (Section 3.4) to the RC. 619 An example set of protocol messages for this method can be found in 620 Appendix C.2. 622 1.4.3. Asynchronous Authorization 624 In this example flow, the RQ and RO roles are fulfilled by different 625 parties, and the RO does not interact with the RC. The AS reaches 626 out asynchronously to the RO during the request process to gather the 627 RO's authorization for the RC's request. The RC polls the AS while 628 it is waiting for the RO to authorize the request. 630 +--------+ +--------+ +------+ 631 | RC | | AS | | RO | 632 | |--(1)--- Request Access --------->| | | | 633 | | | | | | 634 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 635 | | | |<+ (3) +>| | 636 | | | | AuthN | | 637 | |--(6)--- Continue Request (A) --->| | | | 638 | | | |<+ (4) +>| | 639 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 640 | | | | | | 641 | | | |<+ (5) +>| | 642 | | | |Completed| | 643 | | | | | | 644 | |--(8)--- Continue Request (B) --->| | +------+ 645 | | | | 646 | |<-(9)------ Grant Access ---------| | 647 | | | | 648 +--------+ +--------+ 650 1. The RC requests access to the resource (Section 2). The RC does 651 not send any interactions modes to the server, indicating that it 652 does not expect to interact with the RO. The RC can also signal 653 which RO it requires authorization from, if known, by using the 654 user request section (Section 2.4). 656 2. The AS determines that interaction is needed, but the RC cannot 657 interact with the RO. The AS responds (Section 3) with the 658 information the RC will need to continue the request 659 (Section 3.1) in (6) and (8), including a signal that the RC 660 should wait before checking the status of the request again. The 661 AS associates this continuation information with an ongoing 662 request that will be referenced in (3), (4), (5), (6), and (8). 664 3. The AS determines which RO to contact based on the request in 665 (1), through a combination of the user request (Section 2.4), the 666 resources request (Section 2.1), and other policy information. 667 The AS contacts the RO and authenticates them. 669 4. The RO authorizes the pending request from the RC. 671 5. When the AS is done interacting with the RO, the AS indicates to 672 the RO that the request has been completed. 674 6. Meanwhile, the RC loads the continuation information stored at 675 (3) and continues the request (Section 5). The AS determines 676 which ongoing access request is referenced here and checks its 677 state. 679 7. If the access request has not yet been authorized by the RO in 680 (6), the AS responds to the RC to continue the request 681 (Section 3.1) at a future time through additional polling. This 682 response can include refreshed credentials as well as information 683 regarding how long the RC should wait before calling again. The 684 RC replaces its stored continuation information from the previous 685 response (2). Note that the AS may need to determine that the RO 686 has not approved the request in a sufficient amount of time and 687 return an appropriate error to the RC. 689 8. The RC continues to poll the AS (Section 5.2) with the new 690 continuation information from (7). 692 9. If the request has been authorized, the AS grants access to the 693 information in the form of access tokens (Section 3.2) and direct 694 subject information (Section 3.4) to the RC. 696 An example set of protocol messages for this method can be found in 697 Appendix D.1. 699 1.4.4. Software-only Authorization 701 In this example flow, the AS policy allows the RC to make a call on 702 its own behalf, without the need for a RO to be involved at runtime 703 to approve the decision. Since there is no explicit RO, the RC does 704 not interact with an RO. 706 +--------+ +--------+ 707 | RC | | AS | 708 | |--(1)--- Request Access --------->| | 709 | | | | 710 | |<-(2)---- Grant Access -----------| | 711 | | | | 712 +--------+ +--------+ 714 1. The RC requests access to the resource (Section 2). The RC does 715 not send any interactions modes to the server. 717 2. The AS determines that the request is been authorized, the AS 718 grants access to the information in the form of access tokens 719 (Section 3.2) and direct subject information (Section 3.4) to the 720 RC. 722 An example set of protocol messages for this method can be found in 723 Appendix D. 725 1.4.5. Refreshing an Expired Access Token 727 In this example flow, the RC receives an access token to access a 728 resource server through some valid GNAP process. The RC uses that 729 token at the RS for some time, but eventually the access token 730 expires. The RC then gets a new access token by rotating the expired 731 access token at the AS using the token's management URL. 733 +--------+ +--------+ 734 | RC | | AS | 735 | |--(1)--- Request Access ----------------->| | 736 | | | | 737 | |<-(2)--- Grant Access --------------------| | 738 | | | | 739 | | +--------+ | | 740 | |--(3)--- Access Resource --->| RS | | | 741 | | | | | | 742 | |<-(4)--- Error Response -----| | | | 743 | | +--------+ | | 744 | | | | 745 | |--(5)--- Rotate Token ------------------->| | 746 | | | | 747 | |<-(6)--- Rotated Token -------------------| | 748 | | | | 749 +--------+ +--------+ 751 1. The RC requests access to the resource (Section 2). 753 2. The AS grants access to the resource (Section 3) with an access 754 token (Section 3.2) usable at the RS. The access token response 755 includes a token management URI. 757 3. The RC presents the token (Section 7) to the RS. The RS 758 validates the token and returns an appropriate response for the 759 API. 761 4. When the access token is expired, the RS responds to the RC with 762 an error. 764 5. The RC calls the token management URI returned in (2) to rotate 765 the access token (Section 6.1). The RC presents the access token 766 as well as the appropriate key. 768 6. The AS validates the rotation request including the signature and 769 keys presented in (5) and returns a new access token 770 (Section 3.2.1). The response includes a new access token and 771 can also include updated token management information, which the 772 RC will store in place of the values returned in (2). 774 2. Requesting Access 776 To start a request, the RC sends JSON [RFC8259] document with an 777 object as its root. Each member of the request object represents a 778 different aspect of the RC's request. Each field is described in 779 detail in a section below. 781 resources Describes the rights that the RC is requesting for one or 782 more access tokens to be used at RS's. Section 2.1 784 subject Describes the information about the RO that the RC is 785 requesting to be returned directly in the response from the AS. 786 Section 2.2 788 client Describes the RC that is making this request, including the 789 key that the RC will use to protect this request and any 790 continuation requests at the AS and any user-facing information 791 about the RC used in interactions at the AS. Section 2.3 793 user Identifies the RQ to the AS in a manner that the AS can verify, 794 either directly or by interacting with the RQ to determine their 795 status as the RO. Section 2.4 797 interact Describes the modes that the RC has for allowing the RO to 798 interact with the AS and modes for the RC to receive updates when 799 interaction is complete. Section 2.5 801 capabilities Identifies named extension capabilities that the RC can 802 use, signaling to the AS which extensions it can use. Section 2.6 804 existing_grant Identifies a previously-existing grant that the RC is 805 extending with this request. Section 2.7 807 claims Identifies the identity claims to be returned as part of an 808 OpenID Connect claims request. Section 2.8 810 Additional members of this request object can be defined by 811 extensions to this protocol as described in Section 2.9 813 A non-normative example of a grant request is below: 815 { 816 "resources": [ 817 { 818 "type": "photo-api", 819 "actions": [ 820 "read", 821 "write", 822 "dolphin" 823 ], 824 "locations": [ 825 "https://server.example.net/", 826 "https://resource.local/other" 827 ], 828 "datatypes": [ 829 "metadata", 830 "images" 831 ] 832 }, 833 "dolphin-metadata" 834 ], 835 "client": { 836 "display": { 837 "name": "My Client Display Name", 838 "uri": "https://example.net/client" 839 }, 840 "key": { 841 "proof": "jwsd", 842 "jwk": { 843 "kty": "RSA", 844 "e": "AQAB", 845 "kid": "xyz-1", 846 "alg": "RS256", 847 "n": "kOB5rR4Jv0GMeL...." 848 } 849 } 850 }, 851 "interact": { 852 "redirect": true, 853 "callback": { 854 "method": "redirect", 855 "uri": "https://client.example.net/return/123455", 856 "nonce": "LKLTI25DK82FX4T4QFZC" 857 } 858 }, 859 "capabilities": ["ext1", "ext2"], 860 "subject": { 861 "sub_ids": ["iss-sub", "email"], 862 "assertions": ["id_token"] 863 } 864 } 866 The request MUST be sent as a JSON object in the body of the HTTP 867 POST request with Content-Type "application/json", unless otherwise 868 specified by the signature mechanism. 870 2.1. Requesting Resources 872 If the RC is requesting one or more access tokens for the purpose of 873 accessing an API, the RC MUST include a "resources" field. This 874 field MUST be an array (for a single access token (Section 2.1.1)) or 875 an object (for multiple access tokens (Section 2.1.3)), as described 876 in the following sections. 878 2.1.1. Requesting a Single Access Token 880 When requesting an access token, the RC MUST send a "resources" field 881 containing a JSON array. The elements of the JSON array represent 882 rights of access that the RC is requesting in the access token. The 883 requested access is the sum of all elements within the array. 885 The RC declares what access it wants to associated with the resulting 886 access token using objects that describe multiple dimensions of 887 access. Each object contains a "type" property that determines the 888 type of API that the RC is calling. 890 type The type of resource request as a string. This field MAY 891 define which other fields are allowed in the request object. This 892 field is REQUIRED. 894 The value of this field is under the control of the AS. This field 895 MUST be compared using an exact byte match of the string value 896 against known types by the AS. The AS MUST ensure that there is no 897 collision between different authorization data types that it 898 supports. The AS MUST NOT do any collation or normalization of data 899 types during comparison. It is RECOMMENDED that designers of 900 general-purpose APIs use a URI for this field to avoid collisions 901 between multiple API types protected by a single AS. 903 While it is expected that many APIs will have its own properties, a 904 set of common properties are defined here. Specific API 905 implementations SHOULD NOT re-use these fields with different 906 semantics or syntax. The available values for these properties are 907 determined by the API being protected at the RS. 909 [[ Editor's note: this will align with OAuth 2 RAR, but the details 910 of exactly how it aligns are TBD. Since RAR needs to work in the 911 confines of OAuth 2, RAR has to define how to interact with "scope", 912 "resource", and other existing OAuth 2 mechanisms that don't exist in 913 GNAP. ]]. 915 actions The types of actions the RC will take at the RS as an array 916 of strings. For example, an RC asking for a combination of "read" 917 and "write" access. 919 locations The location of the RS as an array of strings. These 920 strings are typically URIs identifying the location of the RS. 922 datatypes The kinds of data available to the RC at the RS's API as 923 an array of strings. For example, an RC asking for access to raw 924 "image" data and "metadata" at a photograph API. 926 identifier A string identifier indicating a specific resource at the 927 RS. For example, a patient identifier for a medical API or a bank 928 account number for a financial API. 930 The following non-normative example shows the use of both common and 931 API-specific fields as part of two different access "type" values. 933 "resources": [ 934 { 935 "type": "photo-api", 936 "actions": [ 937 "read", 938 "write", 939 "dolphin" 940 ], 941 "locations": [ 942 "https://server.example.net/", 943 "https://resource.local/other" 944 ], 945 "datatypes": [ 946 "metadata", 947 "images" 948 ] 949 }, 950 { 951 "type": "financial-transaction", 952 "actions": [ 953 "withdraw" 954 ], 955 "identifier": "account-14-32-32-3", 956 "currency": "USD" 957 } 958 ] 960 If this request is approved, the resulting access token 961 (Section 3.2.1) will include the sum of both of the requested types 962 of access. 964 2.1.2. Requesting Resources By Reference 966 Instead of sending an object describing the requested resource 967 (Section 2.1.1), a RC MAY send a string known to the AS or RS 968 representing the access being requested. Each string SHOULD 969 correspond to a specific expanded object representation at the AS. 971 [[ Editor's note: we could describe more about how the expansion 972 would work. For example, expand into an object where the value of 973 the "type" field is the value of the string. Or we could leave it 974 open and flexible, since it's really up to the AS/RS to interpret. ]] 976 "resources": [ 977 "read", "dolphin-metadata", "some other thing" 978 ] 980 This value is opaque to the RC and MAY be any valid JSON string, and 981 therefore could include spaces, unicode characters, and properly 982 escaped string sequences. However, in some situations the value is 983 intended to be seen and understood be the RC developer. In such 984 cases, the API designer choosing any such human-readable strings 985 SHOULD take steps to ensure the string values are not easily confused 986 by a developer 988 This functionality is similar in practice to OAuth 2's "scope" 989 parameter [RFC6749], where a single string represents the set of 990 access rights requested by the RC. As such, the reference string 991 could contain any valid OAuth 2 scope value as in Appendix D.2. Note 992 that the reference string here is not bound to the same character 993 restrictions as in OAuth 2's "scope" definition. 995 A single "resources" array MAY include both object-type and string- 996 type resource items. 998 "resources": [ 999 { 1000 "type": "photo-api", 1001 "actions": [ 1002 "read", 1003 "write", 1004 "dolphin" 1005 ], 1006 "locations": [ 1007 "https://server.example.net/", 1008 "https://resource.local/other" 1009 ], 1010 "datatypes": [ 1011 "metadata", 1012 "images" 1013 ] 1014 }, 1015 "read", 1016 "dolphin-metadata", 1017 { 1018 "type": "financial-transaction", 1019 "actions": [ 1020 "withdraw" 1021 ], 1022 "identifier": "account-14-32-32-3", 1023 "currency": "USD" 1024 }, 1025 "some other thing" 1026 ] 1028 [[ Editor's note: passing resource requests by reference really is 1029 akin to a "scope", and we have many years of experience showing us 1030 that the simplicity of giving a developer a set of strings to send is 1031 a simple and powerful pattern. We could always require objects and 1032 just use the "type" field as a scope value, but that's a lot of 1033 complexity to pay for the simple case. Client developers will always 1034 know which kind they need to send, because they're picking from the 1035 API's documentation. ]] 1037 2.1.3. Requesting Multiple Access Tokens 1039 When requesting multiple access tokens, the resources field is a JSON 1040 object. The names of the JSON object fields are token identifiers 1041 chosen by the RC, and MAY be any valid string. The values of the 1042 JSON object fields are JSON arrays representing a single access token 1043 request, as specified in requesting a single access token 1044 (Section 2.1.1). 1046 The following non-normative example shows a request for two separate 1047 access tokens, "token1" and "token2". 1049 "resources": { 1050 "token1": [ 1051 { 1052 "type": "photo-api", 1053 "actions": [ 1054 "read", 1055 "write", 1056 "dolphin" 1057 ], 1058 "locations": [ 1059 "https://server.example.net/", 1060 "https://resource.local/other" 1061 ], 1062 "datatypes": [ 1063 "metadata", 1064 "images" 1065 ] 1066 }, 1067 "dolphin-metadata" 1068 ], 1069 "token2": [ 1070 { 1071 "type": "walrus-access", 1072 "actions": [ 1073 "foo", 1074 "bar" 1075 ], 1076 "locations": [ 1077 "https://resource.other/" 1078 ], 1079 "datatypes": [ 1080 "data", 1081 "pictures", 1082 "walrus whiskers" 1083 ] 1084 } 1085 ] 1086 } 1088 Any approved access requests are returned in the multiple access 1089 token response (Section 3.2.2) structure using the token identifiers 1090 in the request. 1092 2.1.4. Signaling Token Behavior 1094 While the AS is ultimately in control of how tokens are returned and 1095 bound to the RC, sometimes the RC has context about what it can 1096 support that can affect the AS's response. This specification 1097 defines several flags that are passed as resource reference strings 1098 (Section 2.1.2). 1100 Each flag applies only to the single resource request in which it 1101 appears. 1103 Support of all flags is optional, such as any other resource 1104 reference value. 1106 multi_token The RC wishes to support multiple simultaneous access 1107 tokens through the token rotation process. When the RC rotates an 1108 access token (Section 6.1), the AS does not invalidate the 1109 previous access token. The old access token continues to remain 1110 valid until such time as it expires or is revoked through other 1111 means. 1113 split_token The RC is capable of receiving multiple access tokens 1114 (Section 3.2.2) in response to any single token request 1115 (Section 2.1.1), or receiving a different number of tokens than 1116 specified in the multiple token request (Section 2.1.3). The 1117 labels of the returned additional tokens are chosen by the AS. 1118 The RC MUST be able to tell from the token response where and how 1119 it can use each of the access tokens. [[ Editor's note: This 1120 functionality is controversial at best as it requires 1121 significantly more complexity on the client in order to solve one 1122 class of AS/RS deployment choices. ]] 1124 bind_token The RC wants the issued access token to be bound to the 1125 key the RC used (Section 2.3.2) to make the request. The 1126 resulting access token MUST be bound using the same "proof" 1127 mechanism used by the client with a "key" value of "true", 1128 indicating the client's presented key is to be used for binding. 1129 [[ Editor's note: should there be a different flag and mechanism 1130 for the client to explicitly indicate which binding method it 1131 wants to use, especially if the client wants to use a different 1132 method at the AS than the RS? ]] 1134 The AS MUST respond with any applied flags in the token response 1135 (Section 3.2) "resources" section. 1137 In this non-normative example, the requested access token is to be 1138 bound to the client's key and should be kept during rotation. 1140 "resources": [ 1141 { 1142 "type": "photo-api", 1143 "actions": [ 1144 "read", 1145 "write", 1146 "dolphin" 1147 ], 1148 "locations": [ 1149 "https://server.example.net/", 1150 "https://resource.local/other" 1151 ], 1152 "datatypes": [ 1153 "metadata", 1154 "images" 1155 ] 1156 }, 1157 "read", 1158 "bind_token", 1159 "multi_token" 1160 ] 1162 Additional flags can be registered in a registry TBD (Section 12). 1164 [[ Editor's note: while these reference values are "reserved", the 1165 ultimate decider for what a reference means is the AS, which means an 1166 AS could arguably decide that one of these values means something 1167 else. Also, this kind of reservation potentially steps on API 1168 namespaces, which OAuth 2 is careful not to do but common extensions 1169 like OIDC do with their own scope definitions. However, in OIDC, 1170 several "scope" values have behavior similar to what's defined here, 1171 particularly "openid" turns on ID tokens in the response and 1172 "offline_access" signals for the return of a refresh token, and these 1173 can be used outside of OpenID Connect itself. However, to keep these 1174 flags out of the general API namespace, we could use a different 1175 syntax for sending them. In particular, they could be defined under 1176 a GNAP-specific "type" object, where all the flags are fields on the 1177 object. 1179 resources: [ 1180 { 1181 type: "gnap-flags", 1182 flag1: true, 1183 flag2: false, 1184 flag3: true ... 1185 }, 1186 "reference1", 1187 "scope2", ... 1188 ] 1190 Alternatively, all the flags could be sent in an array separate from 1191 the rest of the request. 1193 resources: [ 1194 "reference1", 1195 "scope2", 1196 ["flag1", "flag2", "flag3"] ... 1197 ] 1199 This whole thing might also belong in an extension, as it's advanced 1200 behavior signaling for very specific cases. However, it seems other 1201 extensions would be likely to extend this kind of thing, like OIDC 1202 did with "offline_access". ]] 1204 2.2. Requesting User Information 1206 If the RC is requesting information about the RO from the AS, it 1207 sends a "subject" field as a JSON object. This object MAY contain 1208 the following fields (or additional fields defined in a registry TBD 1209 (Section 12)). 1211 sub_ids An array of subject identifier subject types requested for 1212 the RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 1214 assertions An array of requested assertion formats. Possible values 1215 include "id_token" for an [OIDC] ID Token and "saml2" for a SAML 2 1216 assertion. Additional assertion values are defined by a registry 1217 TBD (Section 12). [[ Editor's note: These values are lifted from 1218 [RFC8693]'s "token type identifiers" list, but is there a better 1219 source?]] 1221 "subject": { 1222 "sub_ids": [ "iss-sub", "email" ], 1223 "assertions": [ "id_token", "saml2" ] 1224 } 1225 The AS can determine the RO's identity and permission for releasing 1226 this information through interaction with the RO (Section 4), AS 1227 policies, or assertions presented by the RC (Section 2.4). If this 1228 is determined positively, the AS MAY return the RO's information in 1229 its response (Section 3.4) as requested. 1231 Subject identifiers requested by the RC serve only to identify the RO 1232 in the context of the AS and can't be used as communication channels 1233 by the RC, as discussed in Section 3.4. One method of requesting 1234 communication channels and other identity claims are discussed in 1235 Section 2.8. 1237 The AS SHOULD NOT re-use subject identifiers for multiple different 1238 ROs. 1240 [[ Editor's Note: What we're really saying here is that "even if the 1241 AS gives you an email address to identify the user, that isn't a 1242 claim that this is a valid email address for that current user, so 1243 don't try to email them." In order to get a workable email address, 1244 or anything that you can use to contact them, you'd need a full 1245 identity protocol and not just this. Also, subject identifiers are 1246 asserted by the AS and therefore naturally scoped to the AS. Would 1247 changing the name to "as_sub_ids" or "local_sub_ids" help convey that 1248 point? ]] 1250 Note: the "sub_ids" and "assertions" request fields are independent 1251 of each other, and a returned assertion MAY omit a requested subject 1252 identifier. 1254 [[ Editor's note: we're potentially conflating these two types in the 1255 same structure, so perhaps these should be split. There's also a 1256 difference between user information and authentication event 1257 information. ]] 1259 2.3. Identifying the RC 1261 When sending a non-continuation request to the AS, the RC MUST 1262 identify itself by including the "client" field of the request and by 1263 signing the request as described in Section 8. Note that for a 1264 continuation request (Section 5), the RC instance is identified by 1265 its association with the request being continued and so this field is 1266 not sent under those circumstances. 1268 When RC information is sent by value, the "client" field of the 1269 request consists of a JSON object with the following fields. 1271 key The public key of the RC to be used in this request as described 1272 in Section 2.3.2. This field is REQUIRED. 1274 class_id An identifier string that the AS can use to identify the 1275 software comprising this instance of the RC. The contents and 1276 format of this field are up to the AS. This field is OPTIONAL. 1278 display An object containing additional information that the AS MAY 1279 display to the RO during interaction, authorization, and 1280 management. This field is OPTIONAL. 1282 "client": { 1283 "key": { 1284 "proof": "httpsig", 1285 "jwk": { 1286 "kty": "RSA", 1287 "e": "AQAB", 1288 "kid": "xyz-1", 1289 "alg": "RS256", 1290 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1291 }, 1292 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1293 }, 1294 "class_id": "web-server-1234", 1295 "display": { 1296 "name": "My Client Display Name", 1297 "uri": "https://example.net/client" 1298 } 1299 } 1301 Additional fields are defined in a registry TBD (Section 12). 1303 The RC MUST prove possession of any presented key by the "proof" 1304 mechanism associated with the key in the request. Proof types are 1305 defined in a registry TBD (Section 12) and an initial set of methods 1306 is described in Section 8. 1308 Note that the AS MAY know the RC's public key ahead of time, and the 1309 AS MAY apply different policies to the request depending on what has 1310 been registered against that key. If the same public key is sent by 1311 value on subsequent access requests, the AS SHOULD treat these 1312 requests as coming from the same RC software instance for purposes of 1313 identification, authentication, and policy application. If the AS 1314 does not know the RC's public key ahead of time, the AS MAY accept or 1315 reject the request based on AS policy, attestations within the client 1316 request, and other mechanisms. 1318 [[ Editor's note: additional client attestation frameworks will 1319 eventually need to be addressed here. For example, the organization 1320 the client represents, or a family of client software deployed in a 1321 cluster, or the posture of the device the client is installed on. 1322 These all need to be separable from the client's key and potentially 1323 the instance identifier. ]] 1325 2.3.1. Identifying the RC Instance 1327 If the RC has an instance identifier that the AS can use to determine 1328 appropriate key information, the RC can send this value in the 1329 "instance_id" field. The instance identifier MAY be assigned to an 1330 RC instance at runtime through the Section 3.5 or MAY be obtained in 1331 another fashion, such as a static registration process at the AS. 1333 instance_id An identifier string that the AS can use to identify the 1334 particular instance of this RC. The content and structure of this 1335 identifier is opaque to the RC. 1337 "client": { 1338 "instance_id": "client-541-ab" 1339 } 1341 If there are no additional fields to send, the RC MAY send the 1342 instance identifier as a direct reference value in lieu of the 1343 object. 1345 "client": "client-541-ab" 1347 When the AS receives a request with an instance identifier, the AS 1348 MUST ensure that the key used to sign the request (Section 8) is 1349 associated with the instance identifier. 1351 If the "instance_id" field is sent, it MUST NOT be accompanied by 1352 other fields unless such fields are explicitly marked safe for 1353 inclusion alongside the instance identifier. 1355 [[ Editor's note: It seems clear that an instance identifier is 1356 mutually exclusive with most of the fields in the request (eg, we 1357 don't want an attacker being able to swap out a client's registered 1358 key just by accessing the identifier). However, some proposed 1359 concepts might fit alongside an instance identifier that change at 1360 runtime, such as device posture or another dynamic attestation. 1361 Should these be sent in the "client" block alongside the instance 1362 identifier, should there be a separate top-level block for runtime 1363 attestations, or some other mechanism? ]] 1364 If the AS does not recognize the instance identifier, the request 1365 MUST be rejected with an error. 1367 If the RC instance is identified in this manner, the registered key 1368 for the RC MAY be a symmetric key known to the AS. The RC MUST NOT 1369 send a symmetric key by value in the request, as doing so would 1370 expose the key directly instead of proving possession of it. 1372 [[ Editor's note: In many ways, passing an instance identifier is 1373 analogous to OAuth 2's "client_id" parameter [RFC6749], especially 1374 when coupled with a confidential client's registration and 1375 authentication process. See Appendix D.2 for an example. Something 1376 like this is required to make things easier for client developers in 1377 the common case where the AS already knows the client's key, and to 1378 allow symmetric keys. ]] 1380 2.3.2. Identifying the RC Key 1382 The RC key MUST be a public key in at least one supported format and 1383 MUST be applicable to the proofing mechanism used in the request. If 1384 the key is sent in multiple formats, all the keys MUST be the same. 1385 The key presented in this field MUST be the key used to sign the 1386 request. 1388 proof The form of proof that the RC will use when presenting the key 1389 to the AS. The valid values of this field and the processing 1390 requirements for each are detailed in Section 8. This field is 1391 REQUIRED. 1393 jwk Value of the public key as a JSON Web Key. MUST contain an "alg" 1394 field which is used to validate the signature. MUST contain the 1395 "kid" field to identify the key in the signed object. 1397 cert PEM serialized value of the certificate used to sign the 1398 request, with optional internal whitespace. 1400 cert#256 The certificate thumbprint calculated as per OAuth-MTLS 1401 [RFC8705] in base64 URL encoding. 1403 Additional key types are defined in a registry TBD (Section 12). 1405 [[ Editor's note: we will eventually want to have fetchable keys, I 1406 would guess. Things like DID for key identification are going to be 1407 important. ]] 1409 This non-normative example shows a single key presented in multiple 1410 formats using a single proofing mechanism. 1412 "key": { 1413 "proof": "jwsd", 1414 "jwk": { 1415 "kty": "RSA", 1416 "e": "AQAB", 1417 "kid": "xyz-1", 1418 "alg": "RS256", 1419 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1420 }, 1421 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1422 } 1424 Continuation requests (Section 5) MUST use the same key (or its most 1425 recent rotation) and proof method as the initial request. 1427 2.3.3. Providing Displayable RC Information 1429 If the RC has additional information to display to the RO during any 1430 interactions at the AS, it MAY send that information in the "display" 1431 field. This field is a JSON object that declares information to 1432 present to the RO during any interactive sequences. 1434 name Display name of the RC software 1436 uri User-facing web page of the RC software 1438 logo_uri Display image to represent the RC software 1440 "display": { 1441 "name": "My Client Display Name", 1442 "uri": "https://example.net/client" 1443 } 1445 [[ Editor's note: would we want to support pushing a display logo by 1446 value? On the upside it allows for more dynamic detached clients and 1447 doesn't require the AS to fetch information. On the downside, this 1448 is harder for the AS to enforce a policy about and could lead to 1449 potential exploits caused by sending binary image files. ]] 1451 Additional display fields are defined by a registry TBD (Section 12). 1453 The AS SHOULD use these values during interaction with the RO. The 1454 values are for informational purposes only and MUST NOT be taken as 1455 authentic proof of the RC's identity or source. The AS MAY restrict 1456 display values to specific RC instances, as identified by their keys 1457 in Section 2.3. 1459 2.3.4. Authenticating the RC 1461 If the presented key is known to the AS and is associated with a 1462 single instance of the RC software, the process of presenting a key 1463 and proving possession of that key is sufficient to authenticate the 1464 RC to the AS. The AS MAY associate policies with the RC software 1465 identified by this key, such as limiting which resources can be 1466 requested and which interaction methods can be used. For example, 1467 only specific RCs with certain known keys might be trusted with 1468 access tokens without the AS interacting directly with the RO as in 1469 Appendix D. 1471 The presentation of a key allows the AS to strongly associate 1472 multiple successive requests from the same RC with each other. This 1473 is true when the AS knows the key ahead of time and can use the key 1474 to authenticate the RC software, but also if the key is ephemeral and 1475 created just for this series of requests. As such the AS MAY allow 1476 for RCs to make requests with unknown keys. This pattern allows for 1477 ephemeral RCs, such as single-page applications, and RCs with many 1478 individual instances, such as mobile applications, to generate their 1479 own key pairs and use them within the protocol without having to go 1480 through a separate registration step. The AS MAY limit which 1481 capabilities are made available to RCs with unknown keys. For 1482 example, the AS could have a policy saying that only previously- 1483 registered RCs can request particular resources, or that all RCs with 1484 unknown keys have to be interactively approved by an RO. 1486 2.4. Identifying the User 1488 If the RC knows the identity of the RQ through one or more 1489 identifiers or assertions, the RC MAY send that information to the AS 1490 in the "user" field. The RC MAY pass this information by value or by 1491 reference. 1493 sub_ids An array of subject identifiers for the RQ, as defined by 1494 [I-D.ietf-secevent-subject-identifiers]. 1496 assertions An object containing assertions as values keyed on the 1497 assertion type defined by a registry TBD (Section 12). Possible 1498 keys include "id_token" for an [OIDC] ID Token and "saml2" for a 1499 SAML 2 assertion. Additional assertion values are defined by a 1500 registry TBD (Section 12). [[ Editor's note: These keys are 1501 lifted from [RFC8693]'s "token type identifiers" list, but is 1502 there a better source? Additionally: should this be an array of 1503 objects with internal typing like the sub_ids? Do we expect more 1504 than one assertion per user anyway? ]] 1506 "user": { 1507 "sub_ids": [ { 1508 "subject_type": "email", 1509 "email": "user@example.com" 1510 } ], 1511 "assertions": { 1512 "id_token": "eyj..." 1513 } 1514 } 1516 Subject identifiers are hints to the AS in determining the RO and 1517 MUST NOT be taken as declarative statements that a particular RO is 1518 present at the RC and acting as the RQ. Assertions SHOULD be 1519 validated by the AS. [[ editor's note: is this a MUST? Assertion 1520 validation is extremely specific to the kind of assertion in place, 1521 what other guidance and requirements can we put in place here? ]] 1523 If the identified RQ does not match the RO present at the AS during 1524 an interaction step, the AS SHOULD reject the request with an error. 1526 [[ Editor's note: we're potentially conflating identification 1527 (sub_ids) and provable presence (assertions and a trusted reference 1528 handle) in the same structure, so perhaps these should be split. The 1529 security parameters are pretty different here. ]] 1531 If the AS trusts the RC to present verifiable assertions, the AS MAY 1532 decide, based on its policy, to skip interaction with the RO, even if 1533 the RC provides one or more interaction modes in its request. 1535 2.4.1. Identifying the User by Reference 1537 User reference identifiers can be dynamically issued by the AS 1538 (Section 3.5) to allow the RC to represent the same RQ to the AS over 1539 subsequent requests. 1541 If the RC has a reference for the RQ at this AS, the RC MAY pass that 1542 reference as a string. The format of this string is opaque to the 1543 RC. 1545 "user": "XUT2MFM1XBIKJKSDU8QM" 1547 User reference identifiers are not intended to be human-readable user 1548 identifiers or structured assertions. For the RC to send either of 1549 these, use the full user request object (Section 2.4) instead. 1551 [[ Editor's note: we might be able to fold this function into an 1552 unstructured user assertion reference issued by the AS to the RC. We 1553 could put it in as an assertion type of "gnap_reference" or something 1554 like that. Downside: it's more verbose and potentially confusing to 1555 the client developer to have an assertion-like thing that's internal 1556 to the AS and not an assertion. ]] 1558 If the AS does not recognize the user reference, it MUST return an 1559 error. 1561 2.5. Interacting with the User 1563 Many times, the AS will require interaction with the RO in order to 1564 approve a requested delegation to the RC for both resources and 1565 direct claim information. Many times the RQ using the RC is the same 1566 person as the RO, and the RC can directly drive interaction with the 1567 AS by redirecting the RQ on the same device, or by launching an 1568 application. Other times, the RC can provide information to start 1569 the RO's interaction on a secondary device, or the RC will wait for 1570 the RO to approve the request asynchronously. The RC could also be 1571 signaled that interaction has completed by the AS making callbacks. 1572 To facilitate all of these modes, the RC declares the means that it 1573 can interact using the "interact" field. 1575 The "interact" field is a JSON object with keys that declare 1576 different interaction modes. A RC MUST NOT declare an interaction 1577 mode it does not support. The RC MAY send multiple modes in the same 1578 request. There is no preference order specified in this request. An 1579 AS MAY respond to any, all, or none of the presented interaction 1580 modes (Section 3.3) in a request, depending on its capabilities and 1581 what is allowed to fulfill the request. This specification defines 1582 the following interaction modes: 1584 redirect Indicates that the RC can direct the RQ to an arbitrary URL 1585 at the AS for interaction. Section 2.5.1 1587 app Indicates that the RC can launch an application on the RQ's 1588 device for interaction. Section 2.5.2 1590 callback Indicates that the RC can receive a callback from the AS 1591 after interaction with the RO has concluded. Section 2.5.3 1593 user_code Indicates that the RC can communicate a human-readable 1594 short code to the RQ for use with a stable URL at the AS. 1595 Section 2.5.4 1597 ui_locales Indicates the RQ's preferred locales that the AS can use 1598 during interaction, particularly before the RO has authenticated. 1599 Section 2.5.5 1601 The following sections detail requests for interaction modes. 1602 Additional interaction modes are defined in a registry TBD 1603 (Section 12). 1605 [[ Editor's note: there need to be more examples (Appendix C) that 1606 knit together the interaction modes into common flows, like an authz- 1607 code equivalent. But it's important for the protocol design that 1608 these are separate pieces to allow such knitting to take place. ]] 1610 In this non-normative example, the RC is indicating that it can 1611 redirect (Section 2.5.1) the RQ to an arbitrary URL and can receive a 1612 callback (Section 2.5.3) through a browser request. 1614 "interact": { 1615 "redirect": true, 1616 "callback": { 1617 "method": "redirect", 1618 "uri": "https://client.example.net/return/123455", 1619 "nonce": "LKLTI25DK82FX4T4QFZC" 1620 } 1621 } 1623 In this non-normative example, the RC is indicating that it can 1624 display a user code (Section 2.5.4) and direct the RQ to an arbitrary 1625 URL of maximum length (Section 2.5.1.1) 255 characters, but it cannot 1626 accept a callback. 1628 "interact": { 1629 "redirect": 255, 1630 "user_code": true 1631 } 1633 If the RC does not provide a suitable interaction mechanism, the AS 1634 cannot contact the RO asynchronously, and the AS determines that 1635 interaction is required, then the AS SHOULD return an error since the 1636 RC will be unable to complete the request without authorization. 1638 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1639 provided, including user codes and redirection URLs. The RC SHOULD 1640 apply suitable timeouts to any callback URLs. 1642 2.5.1. Redirect to an Arbitrary URL 1644 If the RC is capable of directing the RQ to a URL defined by the AS 1645 at runtime, the RC indicates this by sending the "redirect" field 1646 with the boolean value "true". The means by which the RC will 1647 activate this URL is out of scope of this specification, but common 1648 methods include an HTTP redirect, launching a browser on the RQ's 1649 device, providing a scannable image encoding, and printing out a URL 1650 to an interactive console. 1652 "interact": { 1653 "redirect": true 1654 } 1656 If this interaction mode is supported for this RC and request, the AS 1657 returns a redirect interaction response Section 3.3.1. 1659 2.5.1.1. Redirect to an Arbitrary Shortened URL 1661 If the RC would prefer to redirect to a shortened URL defined by the 1662 AS at runtime, the RC indicates this by sending the "redirect" field 1663 with an integer indicating the maximum character length of the 1664 returned URL. The AS MAY use this value to decide whether to return 1665 a shortened form of the response URL. If the AS cannot shorten its 1666 response URL enough to fit in the requested size, the AS SHOULD 1667 return an error. [[ Editor's note: Or maybe just ignore this part of 1668 the interaction request? ]] 1670 "interact": { 1671 "redirect": 255 1672 } 1674 If this interaction mode is supported for this RC and request, the AS 1675 returns a redirect interaction response with short URL Section 3.3.1. 1677 2.5.2. Open an Application-specific URL 1679 If the RC can open a URL associated with an application on the RQ's 1680 device, the RC indicates this by sending the "app" field with boolean 1681 value "true". The means by which the RC determines the application 1682 to open with this URL are out of scope of this specification. 1684 "interact": { 1685 "app": true 1686 } 1687 If this interaction mode is supported for this RC and request, the AS 1688 returns an app interaction response with an app URL payload 1689 Section 3.3.2. 1691 [[ Editor's note: this is similar to the "redirect" above today as 1692 most apps use captured URLs, but there seems to be a desire for 1693 splitting the web-based interaction and app-based interaction into 1694 different URIs. There's also the possibility of wanting more in the 1695 payload than can be reasonably put into the URL, or at least having 1696 separate payloads. ]] 1698 2.5.3. Receive a Callback After Interaction 1700 If the RC is capable of receiving a message from the AS indicating 1701 that the RO has completed their interaction, the RC indicates this by 1702 sending the "callback" field. The value of this field is an object 1703 containing the following members. 1705 uri REQUIRED. Indicates the URI to send the RO to after 1706 interaction. This URI MAY be unique per request and MUST be 1707 hosted by or accessible by the RC. This URI MUST NOT contain any 1708 fragment component. This URI MUST be protected by HTTPS, be 1709 hosted on a server local to the RO's browser ("localhost"), or use 1710 an application-specific URI scheme. If the RC needs any state 1711 information to tie to the front channel interaction response, it 1712 MUST use a unique callback URI to link to that ongoing state. The 1713 allowable URIs and URI patterns MAY be restricted by the AS based 1714 on the RC's presented key information. The callback URI SHOULD be 1715 presented to the RO during the interaction phase before redirect. 1716 [[ Editor's note: should we enforce the callback URI to be unique 1717 per request? That helps with some fixation attacks, but not with 1718 others, and it would be problematic for an AS that wants to lock 1719 down each client instance to a single callback instead of a 1720 family/pattern of callbacks. ]] 1722 nonce REQUIRED. Unique value to be used in the calculation of the 1723 "hash" query parameter sent to the callback URL, must be 1724 sufficiently random to be unguessable by an attacker. MUST be 1725 generated by the RC as a unique value for this request. 1727 method REQUIRED. The callback method that the AS will use to 1728 contact the RC. Valid values include "redirect" Section 2.5.3.1 1729 and "push" Section 2.5.3.2, with other values defined by a 1730 registry TBD (Section 12). 1732 hash_method OPTIONAL. The hash calculation mechanism to be used for 1733 the callback hash in Section 4.4.3. Can be one of "sha3" or 1734 "sha2". If absent, the default value is "sha3". [[ Editor's 1735 note: This should be expandable via a registry of cryptographic 1736 options, and it would be good if we didn't define our own 1737 identifiers here. See also note about cryptographic functions in 1738 Section 4.4.3. ]] 1740 "interact": { 1741 "callback": { 1742 "method": "redirect", 1743 "uri": "https://client.example.net/return/123455", 1744 "nonce": "LKLTI25DK82FX4T4QFZC" 1745 } 1746 } 1748 If this interaction mode is supported for this RC and request, the AS 1749 returns a nonce for use in validating the callback response 1750 (Section 3.3.3). Requests to the callback URI MUST be processed as 1751 described in Section 4.4, and the AS MUST require presentation of an 1752 interaction callback reference as described in Section 5.1. 1754 [[ Editor's note: There has been some call for a post-interaction 1755 redirect that is not tied to the underlying security model - 1756 specifically, sending the user over to a client-hosted page with 1757 client-specific instructions on how to continue. This would be 1758 something hosted externally to the client instance, so the client 1759 instance would never see this incoming call. We could accomplish 1760 that using this "callback" post-redirect mechanism but with "method": 1761 "static" or "nonce": false or some other signal to indicate that the 1762 client won't see the incoming request. ]] 1764 [[ Editor's note: The callback information could alternatively be 1765 combined with other methods like "redirect", essentially putting 1766 everything in the "callback" object into the field for the other 1767 objects. However, this would require each method to define its own 1768 set of rules about how callbacks can be used, and we would want them 1769 all to be consistent with each other with clear information about how 1770 the AS is supposed to respond to all of these. 1772 "interact" { 1773 "redirect": { 1774 "method": "redirect", 1775 "uri": "https://client.example.net/return/123455", 1776 "nonce": "LKLTI25DK82FX4T4QFZC" 1777 } 1778 } 1779 So if the object is there, you do the redirect on completion, if the 1780 object isn't there (it's a boolean, like today), you don't redirect 1781 when you're done. Previous versions of this specification used this 1782 structure, but it was abandoned in favor of the current setup to 1783 allow for different combinations of user interaction methods at the 1784 same time while still keeping a consistent security model. OAuth 2's 1785 "grant_type" model has proved to be limiting in unanticipated ways 1786 since it requires an entirely new grant type to be invented any time 1787 there is a new combination of aspects, or it requires each grant type 1788 to have many of the same optionalities. Combining these fields back 1789 into one, in this way, would allow a client to declare that it 1790 expects a callback in response to one kind of interaction method but 1791 not others, and include multiple combinations at once. For example, 1792 if a client wants to allow a user to redirect to the AS and back on 1793 the same device, or to use a usercode on a secondary device without a 1794 callback, and the client wants to offer both modes simultaneously. 1795 This could alternately be accomplished by allowing the client to 1796 "bundle" interaction parameters together, if desirable - for example, 1797 if "interact" were an array, the client would accept any combination 1798 represented by one object. This example binds the "callback" only to 1799 the first "redirect" method, and second (short) "redirect" and 1800 "user_code" method do not use a callback. 1802 "interact": [ 1803 { 1804 "redirect": true, 1805 "callback": { 1806 "method": "redirect", 1807 "uri": "https://client.example.net/return/123455", 1808 "nonce": "LKLTI25DK82FX4T4QFZC" 1809 } 1810 }, 1811 { 1812 "redirect": 255, 1813 "user_code": true 1814 } 1815 ] 1817 It's not clear what a response to such an array would be. Would the 1818 AS pick one of these bundles? Would it be allowed to respond to any 1819 or all of them? Could an AS use different URIs for each bundle? 1820 (This seems likely, at least.) Would there be a security problem if 1821 the AS used the same URI for both bundles, since one requires a front 1822 channel redirect and the other does not? 1824 ]] 1826 2.5.3.1. Receive an HTTP Callback Through the Browser 1828 A callback "method" value of "redirect" indicates that the RC will 1829 expect a call from the RO's browser using the HTTP method GET as 1830 described in Section 4.4.1. 1832 "interact": { 1833 "callback": { 1834 "method": "redirect", 1835 "uri": "https://client.example.net/return/123455", 1836 "nonce": "LKLTI25DK82FX4T4QFZC" 1837 } 1838 } 1840 Requests to the callback URI MUST be processed by the RC as described 1841 in Section 4.4.1. 1843 Since the incoming request to the callback URL is from the RO's 1844 browser, this method is usually used when the RO and RQ are the same 1845 entity. As such, the RC MUST ensure the RQ is present on the request 1846 to prevent substitution attacks. 1848 2.5.3.2. Receive an HTTP Direct Callback 1850 A callback "method" value of "push" indicates that the RC will expect 1851 a call from the AS directly using the HTTP method POST as described 1852 in Section 4.4.2. 1854 "interact": { 1855 "callback": { 1856 "method": "push", 1857 "uri": "https://client.example.net/return/123455", 1858 "nonce": "LKLTI25DK82FX4T4QFZC" 1859 } 1860 } 1862 Requests to the callback URI MUST be processed by the RC as described 1863 in Section 4.4.2. 1865 Since the incoming request to the callback URL is from the AS and not 1866 from the RO's browser, the RC MUST NOT require the RQ to be present 1867 on the incoming HTTP request. 1869 [[ Editor's note: This post-interaction method can be used in 1870 advanced use cases like asynchronous authorization, or simply to 1871 signal the client that it should move to the next part of the 1872 protocol, even when there is no user present at the client. As such 1873 it can feel a little odd being inside the "interact" block of the 1874 protocol, but it does align with the redirect-based "callback" method 1875 and it seems they really should be mutually-exclusive. Additionally, 1876 should there be a method for simply pushing the updated response 1877 directly to the client, instead? ]] 1879 2.5.4. Display a Short User Code 1881 If the RC is capable of displaying or otherwise communicating a 1882 short, human-entered code to the RO, the RC indicates this by sending 1883 the "user_code" field with the boolean value "true". This code is to 1884 be entered at a static URL that does not change at runtime, as 1885 described in Section 3.3.4. 1887 "interact": { 1888 "user_code": true 1889 } 1891 If this interaction mode is supported for this RC and request, the AS 1892 returns a user code and interaction URL as specified in Section 4.2. 1894 2.5.5. Indicate Desired Interaction Locales 1896 If the RC knows the RQ's locale and language preferences, the RC can 1897 send this information to the AS using the "ui_locales" field with an 1898 array of locale strings as defined by [RFC5646]. 1900 "interact": { 1901 "ui_locales": ["en-US", "fr-CA"] 1902 } 1904 If possible, the AS SHOULD use one of the locales in the array, with 1905 preference to the first item in the array supported by the AS. If 1906 none of the given locales are supported, the AS MAY use a default 1907 locale. 1909 2.5.6. Extending Interaction Modes 1911 Additional interaction modes are defined in a registry TBD 1912 (Section 12). 1914 [[ Editor's note: we should have guidance in here about how to define 1915 other interaction modes. There's already interest in defining 1916 message-based protocols like DIDCOMM and challenge-response protocols 1917 like FIDO, for example. ]] 1919 2.6. Declaring RC Capabilities 1921 If the RC supports extension capabilities, it MAY present them to the 1922 AS in the "capabilities" field. This field is an array of strings 1923 representing specific extensions and capabilities, as defined by a 1924 registry TBD (Section 12). 1926 "capabilities": ["ext1", "ext2"] 1928 2.7. Referencing an Existing Grant Request 1930 If the RC has a reference handle from a previously granted request, 1931 it MAY send that reference in the "existing_grant" field. This field 1932 is a single string consisting of the "value" of the "access_token" 1933 returned in a previous request's continuation response (Section 3.1). 1935 "existing_grant": "80UPRY5NM33OMUKMKSKU" 1937 The AS MUST dereference the grant associated with the reference and 1938 process this request in the context of the referenced one. The AS 1939 MUST NOT alter the existing grant associated with the reference. 1941 [[ Editor's note: this basic capability is to allow for both step-up 1942 authorization and downscoped authorization, but by explicitly 1943 creating a new request and not modifying an existing one. What's the 1944 best guidance for how an AS should process this? What are the use 1945 cases that help differentiate this from modification of an existing 1946 request? ]] 1948 2.8. Requesting OpenID Connect Claims 1950 If the RC and AS both support OpenID Connect's claims query language 1951 as defined in [OIDC] Section 5.5, the RC sends the value of the 1952 OpenID Connect "claims" authorization request parameter as a JSON 1953 object under the name "claims" in the root of the request. 1955 "claims": { 1956 "id_token" : { 1957 "email" : { "essential" : true }, 1958 "email_verified" : { "essential" : true } 1959 }, 1960 "userinfo" : { 1961 "name" : { "essential" : true }, 1962 "picture" : null 1963 } 1964 } 1966 The contents of the "claims" parameter have the same semantics as 1967 they do in OpenID Connect's "claims" authorization request parameter, 1968 including all extensions such as [OIDC4IA]. The AS MUST process the 1969 claims object in the same way that it would with an OAuth 2 based 1970 authorization request. 1972 Note that because this is an independent query object, the "claims" 1973 value can augment or alter other portions of the request, namely the 1974 "resources" and "subject" fields. This query language uses the 1975 fields in the top level of the object to indicate the target for any 1976 requested claims. For instance, the "userinfo" target indicates that 1977 a returned access token would grant access to the given claims at the 1978 UserInfo Endpoint, while the "id_token" target indicates that the 1979 claims would be returned in an ID Token as described in Section 3.4. 1981 [[ Editor's note: in order to use the "claims" parameter as defined 1982 in OIDC, we have to violate the principle of orthogonality in 1983 Section 2.9. An alternative approach would be to split up the 1984 portions of the claims request, so that "id_token" claims would go 1985 into the "subject" field and "userinfo" claims would go into the 1986 "resources" request, but this violates the original field definition 1987 from OIDC and gets into the territory of defining an identity schema 1988 request. This approach would also invalidate extensions to the 1989 "claims" standard as each "target" would need to have its own 1990 separate mapping to some part of the GNAP protocol. ]] 1992 [[ Editor's note: I'm not a fan of GNAP defining how OIDC would work 1993 at all and would rather that work be done by the OIDF in an 1994 extension. However, I think it is important for discussion to see 1995 this kind of thing in context with the rest of the protocol, for now. 1996 In the future, I would anticipate this would be defined by the OIDF 1997 as a relatively small but robust identity layer on top of GNAP. ]] 1999 2.9. Extending The Grant Request 2001 The request object MAY be extended by registering new items in a 2002 registry TBD (Section 12). Extensions SHOULD be orthogonal to other 2003 parameters. Extensions MUST document any aspects where the extension 2004 item affects or influences the values or behavior of other request 2005 and response objects. 2007 [[ Editor's note: we should have more guidance and examples on what 2008 possible top-level extensions would look like. ]] 2010 3. Grant Response 2012 In response to a RC's request, the AS responds with a JSON object as 2013 the HTTP entity body. Each possible field is detailed in the 2014 sections below 2016 continue Indicates that the RC can continue the request by making an 2017 additional request using these parameters. Section 3.1 2019 access_token A single access token that the RC can use to call the 2020 RS on behalf of the RO. Section 3.2.1 2022 multiple_access_token Multiple named access tokens that the RC can 2023 use to call the RS on behalf of the RO. Section 3.2.2 2025 interact Indicates that interaction through some set of defined 2026 mechanisms needs to take place. Section 3.3 2028 subject Claims about the RO as known and declared by the AS. 2029 Section 3.4 2031 instance_id An identifier this RC instance can use to identify 2032 itself when making future requests. Section 3.5 2034 user_handle An identifier this RC instance can use to identify its 2035 current RQ when making future requests. Section 3.5 2037 error An error code indicating that something has gone wrong. 2038 Section 3.6 2040 In this example, the AS is returning an interaction URL 2041 (Section 3.3.1), a callback nonce (Section 3.3.3), and a continuation 2042 handle (Section 3.1). 2044 { 2045 "interact": { 2046 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 2047 "callback": "MBDOFXG4Y5CVJCX821LH" 2048 }, 2049 "continue": { 2050 "access_token": { 2051 "value": "80UPRY5NM33OMUKMKSKU", 2052 "key": true 2053 }, 2054 "uri": "https://server.example.com/tx" 2055 } 2056 } 2057 In this example, the AS is returning a bearer access token 2058 (Section 3.2.1) with a management URL and a subject identifier 2059 (Section 3.4) in the form of an email address. 2061 { 2062 "access_token": { 2063 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2064 "key": false, 2065 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2066 }, 2067 "subject": { 2068 "sub_ids": [ { 2069 "subject_type": "email", 2070 "email": "user@example.com", 2071 } ] 2072 } 2073 } 2075 3.1. Request Continuation 2077 If the AS determines that the request can be continued with 2078 additional requests, it responds with the "continue" field. This 2079 field contains a JSON object with the following properties. 2081 uri REQUIRED. The URI at which the RC can make continuation 2082 requests. This URI MAY vary per request, or MAY be stable at the 2083 AS if the AS includes an access token. The RC MUST use this value 2084 exactly as given when making a continuation request (Section 5). 2086 wait RECOMMENDED. The amount of time in integer seconds the RC 2087 SHOULD wait after receiving this continuation handle and calling 2088 the URI. 2090 access_token RECOMMENDED. A unique access token for continuing the 2091 request, in the format specified in Section 3.2.1. This access 2092 token MUST be bound to the RC's key used in the request and MUST 2093 NOT be a "bearer" token. This access token MUST NOT be usable at 2094 resources outside of the AS. [[ Editor's note: Is this a 2095 restriction we want to enforce? ]] If the AS includes an access 2096 token, the RC MUST present the access token in all requests to the 2097 continuation URI as described in Section 7. 2099 { 2100 "continue": { 2101 "access_token": { 2102 "value": "80UPRY5NM33OMUKMKSKU", 2103 "key": true 2104 }, 2105 "uri": "https://server.example.com/continue", 2106 "wait": 60 2107 } 2108 } 2110 The RC can use the values of this field to continue the request as 2111 described in Section 5. Note that the RC MUST sign all continuation 2112 requests with its key as described in Section 8. If the AS includes 2113 an "access_token", the RC MUST present the access token in its 2114 continuation request. 2116 This field SHOULD be returned when interaction is expected, to allow 2117 the RC to follow up after interaction has been concluded. 2119 [[ Editor's note: The AS can use the optional "access_token" as a 2120 credential for the client to manage the grant request itself over 2121 time. This is in parallel with access token management as well as RS 2122 access in general. If the AS uses the access token, the continuation 2123 URL can be static, and potentially even the same as the initial 2124 request URL. If the AS does not use an access token here, it needs 2125 to use unique URLs in its response and bind the client's key to 2126 requests to those URLs - or potentially only allow one request per 2127 client at a time. The optionality adds a layer of complexity, but 2128 the client behavior is deterministic in all possible cases and it re- 2129 uses existing functions and structures instead of inventing something 2130 special just to talk to the AS. The optional access token represents 2131 a design compromise, but the working group can decide to either 2132 require the access token on all requests or to remove the access 2133 token functionality and require the security of the continuation 2134 requests be based on unique URLs. ]] 2136 3.2. Access Tokens 2138 If the AS has successfully granted one or more access tokens to the 2139 RC, the AS responds with either the "access_token" or the 2140 "multiple_access_token" field. The AS MUST NOT respond with both the 2141 "access_token" and "multiple_access_token" fields. 2143 [[ Editor's note: I really don't like the dichotomy between 2144 "access_token" and "multiple_access_tokens" and their being mutually 2145 exclusive, and I think we should design away from this pattern toward 2146 something less error-prone. ]] 2148 3.2.1. Single Access Token 2150 If the RC has requested a single access token and the AS has granted 2151 that access token, the AS responds with the "access_token" field. 2152 The value of this field is an object with the following properties. 2154 value REQUIRED. The value of the access token as a string. The 2155 value is opaque to the RC. The value SHOULD be limited to ASCII 2156 characters to facilitate transmission over HTTP headers within 2157 other protocols without requiring additional encoding. 2159 manage OPTIONAL. The management URI for this access token. If 2160 provided, the RC MAY manage its access token as described in 2161 Section 6. This management URI is a function of the AS and is 2162 separate from the RS the RC is requesting access to. This URI 2163 MUST NOT include the access token value and SHOULD be different 2164 for each access token issued in a request. 2166 resources RECOMMENDED. A description of the rights associated with 2167 this access token, as defined in Section 2.1.1. If included, this 2168 MUST reflect the rights associated with the issued access token. 2169 These rights MAY vary from what was requested by the RC. 2171 expires_in OPTIONAL. The number of seconds in which the access will 2172 expire. The RC MUST NOT use the access token past this time. An 2173 RS MUST NOT accept an access token past this time. Note that the 2174 access token MAY be revoked by the AS or RS at any point prior to 2175 its expiration. 2177 key REQUIRED. The key that the token is bound to. If the boolean 2178 value "true" is used, the token is bound to the key used by the RC 2179 (Section 2.3.2) in its request for access. If the boolean value 2180 "false" is used, the token is a bearer token with no key bound to 2181 it. Otherwise, the key MUST be an object or string in a format 2182 described in Section 2.3.2, describing a public key to which the 2183 RC can use the associated private key. The RC MUST be able to 2184 dereference or process the key information in order to be able to 2185 sign the request. 2187 The following non-normative example shows a single bearer token with 2188 a management URL that has access to three described resources. 2190 "access_token": { 2191 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2192 "key": false, 2193 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 2194 "resources": [ 2195 { 2196 "type": "photo-api", 2197 "actions": [ 2198 "read", 2199 "write", 2200 "dolphin" 2201 ], 2202 "locations": [ 2203 "https://server.example.net/", 2204 "https://resource.local/other" 2205 ], 2206 "datatypes": [ 2207 "metadata", 2208 "images" 2209 ] 2210 }, 2211 "read", "dolphin-metadata" 2212 ] 2213 } 2215 The following non-normative example shows a single access token bound 2216 to the RC's key, which was presented using the detached JWS 2217 (Section 8.1) binding method. 2219 "access_token": { 2220 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2221 "key": true, 2222 "resources": [ 2223 "finance", "medical" 2224 ] 2225 } 2227 If the RC requested multiple access tokens (Section 2.1.3), the AS 2228 MUST NOT respond with a single access token structure unless the RC 2229 sends the "split_token" flag as described in Section 2.1.4. 2231 [[ Editor's note: There has been interest in describing a way for the 2232 AS to tell the client both how and where to use the token. This kind 2233 of directed access token could allow for some interesting deployment 2234 patterns where the client doesn't know much]] 2236 3.2.2. Multiple Access Tokens 2238 If the RC has requested multiple access tokens and the AS has granted 2239 at least one of them, the AS responds with the 2240 "multiple_access_tokens" field. The value of this field is a JSON 2241 object, and the property names correspond to the token identifiers 2242 chosen by the RC in the multiple access token request 2243 (Section 2.1.3). The values of the properties of this object are 2244 access tokens as described in Section 3.2.1. 2246 In this non-normative example, two bearer tokens are issued under the 2247 names "token1" and "token2", and only the first token has a 2248 management URL associated with it. 2250 "multiple_access_tokens": { 2251 "token1": { 2252 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2253 "key": false, 2254 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2255 }, 2256 "token2": { 2257 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2258 "key": false 2259 } 2260 } 2262 Each access token corresponds to the named resources arrays in the 2263 RC's request (Section 2.1.3). 2265 The multiple access token response MUST be used when multiple access 2266 tokens are requested, even if only one access token is issued as a 2267 result of the request. The AS MAY refuse to issue one or more of the 2268 requested access tokens, for any reason. In such cases the refused 2269 token is omitted from the response and all of the other issued access 2270 tokens are included in the response the requested names appropriate 2271 names. 2273 If the RC requested a single access token (Section 2.1.1), the AS 2274 MUST NOT respond with the multiple access token structure unless the 2275 RC sends the "split_token" flag as described in Section 2.1.4. 2277 Each access token MAY have different proofing mechanisms. If 2278 management is allowed, each access token SHOULD have different 2279 management URIs. 2281 [[ Editor's note: Do we need to specify that the management URIs are 2282 different if we require the token to be presented? ]] 2284 3.3. Interaction Modes 2286 If the RC has indicated a capability to interact with the RO in its 2287 request (Section 2.5), and the AS has determined that interaction is 2288 both supported and necessary, the AS responds to the RC with any of 2289 the following values in the "interact" field of the response. There 2290 is no preference order for interaction modes in the response, and it 2291 is up to the RC to determine which ones to use. All supported 2292 interaction methods are included in the same "interact" object. 2294 redirect Redirect to an arbitrary URL. Section 3.3.1 2296 app Launch of an application URL. Section 3.3.2 2298 callback Callback to an RC URL after interaction is completed. 2299 Section 3.3.3 2301 user_code Display a short user code. Section 3.3.4 2303 Additional interaction mode responses can be defined in a registry 2304 TBD (Section 12). 2306 The AS MUST NOT respond with any interaction mode that the RC did not 2307 indicate in its request. The AS MUST NOT respond with any 2308 interaction mode that the AS does not support. Since interaction 2309 responses include secret or unique information, the AS SHOULD respond 2310 to each interaction mode only once in an ongoing request, 2311 particularly if the RC modifies its request (Section 5.3). 2313 3.3.1. Redirection to an arbitrary URL 2315 If the RC indicates that it can redirect to an arbitrary URL 2316 (Section 2.5.1) and the AS supports this mode for the RC's request, 2317 the AS responds with the "redirect" field, which is a string 2318 containing the URL to direct the RQ to. This URL MUST be unique for 2319 the request and MUST NOT contain any security-sensitive information. 2321 "interact": { 2322 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2323 } 2325 The interaction URL returned represents a function of the AS but MAY 2326 be completely distinct from the URL the RC uses to request access 2327 (Section 2), allowing an AS to separate its user-interactive 2328 functionality from its back-end security functionality. 2330 [[ Editor's note: This is one aspect where the AS might actually be 2331 two separate roles. Namely, a delegation server (back end) and 2332 interaction server (user-facing).]] 2334 The RC sends the RQ to the URL to interact with the AS. The RC MUST 2335 NOT alter the URL in any way. The means for the RC to send the RQ to 2336 this URL is out of scope of this specification, but common methods 2337 include an HTTP redirect, launching the system browser, displaying a 2338 scannable code, or printing out the URL in an interactive console. 2340 3.3.2. Launch of an application URL 2342 If the RC indicates that it can launch an application URL 2343 (Section 2.5.2) and the AS supports this mode for the RC's request, 2344 the AS responds with the "app" field, which is a string containing 2345 the URL to direct the RQ to. This URL MUST be unique for the request 2346 and MUST NOT contain any security-sensitive information. 2348 "interact": { 2349 "app": "https://app.example.com/launch?tx=4CF492MLV" 2350 } 2352 The RC launches the URL as appropriate on its platform, and the means 2353 for the RC to launch this URL is out of scope of this specification. 2354 The RC MUST NOT alter the URL in any way. The RC MAY attempt to 2355 detect if an installed application will service the URL being sent 2356 before attempting to launch the application URL. 2358 [[ Editor's note: This will probably need to be expanded to an object 2359 to account for other parameters needed in app2app use cases, like 2360 addresses for distributed storage systems, server keys, and the like. 2361 Details TBD as people build this out. ]] 2363 3.3.3. Post-interaction Callback to an RC URL 2365 If the RC indicates that it can receive a post-interaction callback 2366 on a URL (Section 2.5.3) and the AS supports this mode for the RC's 2367 request, the AS responds with a "callback" field containing a nonce 2368 that the RC will use in validating the callback as defined in 2369 Section 4.4.1. 2371 "interact": { 2372 "callback": "MBDOFXG4Y5CVJCX821LH" 2373 } 2375 [[ Editor's note: This is fairly parallel to the request but it kinda 2376 hides the fact that this is a nonce from the AS, not the client. ]] 2377 When the RO completes interaction at the AS, the AS MUST call the 2378 RC's callback URL using the method indicated in the callback request 2379 (Section 2.5.3) as described in Section 4.4.1. 2381 If the AS returns a "callback" nonce, the RC MUST NOT continue a 2382 grant request before it receives the associated interaction reference 2383 on the callback URI. 2385 3.3.4. Display of a Short User Code 2387 If the RC indicates that it can display a short user-typeable code 2388 (Section 2.5.4) and the AS supports this mode for the RC's request, 2389 the AS responds with a "user_code" field. This field is an object 2390 that contains the following members. 2392 code REQUIRED. A unique short code that the user can type into an 2393 authorization server. This string MUST be case-insensitive, MUST 2394 consist of only easily typeable characters (such as letters or 2395 numbers). The time in which this code will be accepted SHOULD be 2396 short lived, such as several minutes. It is RECOMMENDED that this 2397 code be no more than eight characters in length. 2399 url RECOMMENDED. The interaction URL that the RC will direct the RO 2400 to. This URL MUST be stable at the AS such that RCs can be 2401 statically configured with it. 2403 "interact": { 2404 "user_code": { 2405 "code": "A1BC-3DFF", 2406 "url": "https://srv.ex/device" 2407 } 2408 } 2410 The RC MUST communicate the "code" to the RQ in some fashion, such as 2411 displaying it on a screen or reading it out audibly. The "code" is a 2412 one-time-use credential that the AS uses to identify the pending 2413 request from the RC. When the RO enters this code (Section 4.2) into 2414 the AS, the AS MUST determine the pending request that it was 2415 associated with. If the AS does not recognize the entered code, the 2416 AS MUST display an error to the user. If the AS detects too many 2417 unrecognized codes entered, it SHOULD display an error to the user. 2419 The RC SHOULD also communicate the URL if possible to facilitate user 2420 interaction, but since the URL should be stable, the RC should be 2421 able to safely decide to not display this value. As this interaction 2422 mode is designed to facilitate interaction via a secondary device, it 2423 is not expected that the RC redirect the RQ to the URL given here at 2424 runtime. Consequently, the URL needs to be stable enough that a RC 2425 could be statically configured with it, perhaps referring the RQ to 2426 the URL via documentation instead of through an interactive means. 2427 If the RC is capable of communicating an arbitrary URL to the RQ, 2428 such as through a scannable code, the RC can use the "redirect" 2429 (Section 2.5.1) mode for this purpose instead of or in addition to 2430 the user code mode. 2432 The interaction URL returned represents a function of the AS but MAY 2433 be completely distinct from the URL the RC uses to request access 2434 (Section 2), allowing an AS to separate its user-interactive 2435 functionality from its back-end security functionality. 2437 [[ Editor's note: This is one aspect where the AS might actually be 2438 two separate roles. Namely, a delegation server (back end) and 2439 interaction server (user-facing).]] 2441 3.3.5. Extending Interaction Mode Responses 2443 Extensions to this specification can define new interaction mode 2444 responses in a registry TBD (Section 12). Extensions MUST document 2445 the corresponding interaction request. 2447 3.4. Returning User Information 2449 If information about the RO is requested and the AS grants the RC 2450 access to that data, the AS returns the approved information in the 2451 "subject" response field. This field is an object with the following 2452 OPTIONAL properties. 2454 sub_ids An array of subject identifiers for the RO, as defined by 2455 [I-D.ietf-secevent-subject-identifiers]. [[ Editor's note: privacy 2456 considerations are needed around returning identifiers. ]] 2458 assertions An object containing assertions as values keyed on the 2459 assertion type defined by a registry TBD (Section 12). [[ 2460 Editor's note: should this be an array of objects with internal 2461 typing like the sub_ids? Do we expect more than one assertion per 2462 user anyway? ]] 2464 updated_at Timestamp as an ISO8610 date string, indicating when the 2465 identified account was last updated. The RC MAY use this value to 2466 determine if it needs to request updated profile information 2467 through an identity API. The definition of such an identity API 2468 is out of scope for this specification. 2470 "subject": { 2471 "sub_ids": [ { 2472 "subject_type": "email", 2473 "email": "user@example.com", 2474 } ], 2475 "assertions": { 2476 "id_token": "eyj..." 2477 } 2478 } 2480 The AS MUST return the "subject" field only in cases where the AS is 2481 sure that the RO and the RQ are the same party. This can be 2482 accomplished through some forms of interaction with the RO 2483 (Section 4). 2485 Subject identifiers returned by the AS SHOULD uniquely identify the 2486 RO at the AS. Some forms of subject identifier are opaque to the RC 2487 (such as the subject of an issuer and subject pair), while others 2488 forms (such as email address and phone number) are intended to allow 2489 the RC to correlate the identifier with other account information at 2490 the RC. The RC MUST NOT request or use any returned subject 2491 identifiers for communication purposes (see Section 2.2). That is, a 2492 subject identifier returned in the format of an email address or a 2493 phone number only identifies the RO to the AS and does not indicate 2494 that the AS has validated that the represented email address or phone 2495 number in the identifier is suitable for communication with the 2496 current user. To get such information, the RC MUST use an identity 2497 protocol to request and receive additional identity claims. While 2498 Section 2.8 specifies one such method, other identity protocols could 2499 also be used on top of GNAP to convey this information and the 2500 details of an identity protocol and associated schema are outside the 2501 scope of this specification. 2503 [[ Editor's note: subject identifiers here are naturally scoped to 2504 the AS; even though using an external identifier like an email 2505 address or phone number implies a global namespace in use, the 2506 association of that identifier to the current user is still under the 2507 view of the AS. Would changing the name to "as_sub_ids" or 2508 "local_sub_ids" help convey that point? Would it also be desirable 2509 to have an identifier that's globally unique by design? The 2510 "iss_sub" type almost gets us there by explicitly calling out the 2511 issuer URL, but tuples are hard to deal with in practice and so tend 2512 to get ignored in practice in the OIDC space. ]] 2514 [[ Editor's note: This will need substantial privacy considerations, 2515 as this is releasing information about the current user that could be 2516 tied to other information at the RC or elsewhere. To facilitate 2517 this, should we have another form of identifier that's a globally 2518 unique identifier of some form? DIDs could facilitate that kind of 2519 namespace. ]] 2521 Extensions to this specification MAY define additional response 2522 properties in a registry TBD (Section 12). 2524 3.5. Returning Dynamically-bound Reference Handles 2526 Many parts of the RC's request can be passed as either a value or a 2527 reference. The use of a reference in place of a value allows for a 2528 client to optimize requests to the AS. 2530 Some references, such as for the RC instance's identity 2531 (Section 2.3.1) or the requested resources (Section 2.1.2), can be 2532 managed statically through an admin console or developer portal 2533 provided by the AS or RS. The developer of the RC can include these 2534 values in their code for a more efficient and compact request. 2536 If desired, the AS MAY also generate and return some of these 2537 references dynamically to the RC in its response to facilitate 2538 multiple interactions with the same software. The RC SHOULD use 2539 these references in future requests in lieu of sending the associated 2540 data value. These handles are intended to be used on future 2541 requests. 2543 Dynamically generated handles are string values that MUST be 2544 protected by the RC as secrets. Handle values MUST be unguessable 2545 and MUST NOT contain any sensitive information. Handle values are 2546 opaque to the RC. 2548 [[ Editor's note: these constructs used to be objects to allow for 2549 expansion to future fields, like a management URI or different 2550 presentation types or expiration, but those weren't used in practice. 2551 Is that desirable anymore or is collapsing them like this the right 2552 direction? ]] 2554 All dynamically generated handles are returned as fields in the root 2555 JSON object of the response. This specification defines the 2556 following dynamic handle returns, additional handles can be defined 2557 in a registry TBD (Section 12). 2559 instance_id A string value used to represent the information in the 2560 "client" object that the RC can use in a future request, as 2561 described in Section 2.3.1. 2563 user_handle A string value used to represent the current user. The 2564 RC can use in a future request, as described in Section 2.4.1. 2566 This non-normative example shows two handles along side an issued 2567 access token. 2569 { 2570 "user_handle": "XUT2MFM1XBIKJKSDU8QM", 2571 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2572 "access_token": { 2573 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2574 "key": false 2575 } 2576 } 2578 [[ Editor's note: the ability to dynamically return reference handles 2579 allows for an inline version of dynamic registration without needing 2580 to go through a discrete registration step, for clients where that 2581 makes sense. Currently this is entirely up to the AS to decide when 2582 to issue these, but maybe the client should signal that it can 2583 receive these handles as part of the request? The new "token flags" 2584 construct in Section 2.1.4 almost gets at that, but for a different 2585 part of the request structure. Since the client is the component 2586 that will know if it's in a position to make use of such reference 2587 handles in the future (like a mobile app) or if it's just going to 2588 evaporate at the end of a session (like an SPA). Ultimately we need 2589 to deal with a range of dynamism, not just the "pre-registered" vs. 2590 "non-registered" use cases that OAuth forces us in to. ]] 2592 [[ Editor's note: The client-bound "instance_id" could serve as the 2593 hook we would need for RFC7592 style dynamic client management, 2594 including additional components like key rotation. If the AS returns 2595 an object instead of a string here, that could include everything 2596 that the client would need in order to make REST-style management 2597 calls, similar to token management. 2599 { 2600 "client": { 2601 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2602 "manage": "https://example.server.com/client/7C7C4AZ9KHRS6X63AJAO", 2603 "access_token": { 2604 "value": "4TB8N6BW7OZB8CDFONP219RP1LT0OS9M2PMHKUR6", 2605 "key": true 2606 } 2607 } 2608 } 2609 The client would sign all requests with its key and use the presented 2610 access token. A "POST" or "PATCH" request would update client 2611 information, including having a method for key rotation using nested 2612 signatures. A "DELETE" request would un-register the client, etc. ]] 2614 3.6. Error Response 2616 If the AS determines that the request cannot be issued for any 2617 reason, it responds to the RC with an error message. 2619 error The error code. 2621 { 2623 "error": "user_denied" 2625 } 2627 The error code is one of the following, with additional values 2628 available in a registry TBD (Section 12): 2630 user_denied The RO denied the request. 2632 too_fast The RC did not respect the timeout in the wait response. 2634 unknown_request The request referenced an unknown ongoing access 2635 request. 2637 [[ Editor's note: I think we will need a more robust error mechanism, 2638 and we need to be more clear about what error states are allowed in 2639 what circumstances. Additionally, is the "error" parameter exclusive 2640 with others in the return? ]] 2642 3.7. Extending the Response 2644 Extensions to this specification MAY define additional fields for the 2645 grant response in a registry TBD (Section 12). 2647 [[ Editor's note: what guidance should we give to designers on this? 2648 ]] 2650 4. Interaction at the AS 2652 If the RC indicates that it is capable of driving interaction with 2653 the RO in its request (Section 2.5), and the AS determines that 2654 interaction is required and responds to one or more of the RC's 2655 interaction modes, the RC SHOULD initiate one of the returned 2656 interaction modes in the response (Section 3.3). 2658 When the RO is interacting with the AS, the AS MAY perform whatever 2659 actions it sees fit, including but not limited to: 2661 * authenticate the current user (who may be the RQ) as the RO 2663 * gather consent and authorization from the RO for access to 2664 requested resources and direct information 2666 * allow the RO to modify the parameters of the request (such as 2667 disallowing some requested resources or specifying an account or 2668 record) 2670 * provide warnings to the RO about potential attacks or negative 2671 effects of the requested information 2673 [[ Editor's note: there are some privacy and security considerations 2674 here but for the most part we don't want to be overly prescriptive 2675 about the UX, I think. ]] 2677 4.1. Interaction at a Redirected URI 2679 When the RO is directed to the AS through the "redirect" 2680 (Section 3.3.1) mode, the AS can interact with the RO through their 2681 web browser to authenticate the user as an RO and gather their 2682 consent. Note that since the RC does not add any parameters to the 2683 URL, the AS MUST determine the grant request being referenced from 2684 the URL value itself. If the URL cannot be associated with a 2685 currently active request, the AS MUST display an error to the RO and 2686 MUST NOT attempt to redirect the RO back to any RC even if a callback 2687 is supplied (Section 2.5.3). 2689 The interaction URL MUST be reachable from the RO's browser, though 2690 note that the RO MAY open the URL on a separate device from the RC 2691 itself. The interaction URL MUST be accessible from an HTTP GET 2692 request, and MUST be protected by HTTPS or equivalent means. 2694 With this method, it is common for the RO to be the same party as the 2695 RQ, since the RC has to communicate the redirection URI to the RQ. 2697 4.2. Interaction at the User Code URI 2699 When the RO is directed to the AS through the "user_code" 2700 (Section 3.3.4) mode, the AS can interact with the RO through their 2701 web browser to collect the user code, authenticate the user as an RO, 2702 and gather their consent. Note that since the URL itself is static, 2703 the AS MUST determine the grant request being referenced from the 2704 user code value itself. If the user code cannot be associated with a 2705 currently active request, the AS MUST display an error to the RO and 2706 MUST NOT attempt to redirect the RO back to any RC even if a callback 2707 is supplied (Section 2.5.3). 2709 The user code URL MUST be reachable from the RO's browser, though 2710 note that the RO MAY open the URL on a separate device from the RC 2711 itself. The user code URL MUST be accessible from an HTTP GET 2712 request, and MUST be protected by HTTPS or equivalent means. 2714 While it is common for the RO to be the same party as the RQ, since 2715 the RC has to communicate the user code to someone, there are cases 2716 where the RQ and RO are separate parties and the authorization 2717 happens asynchronously. 2719 4.3. Interaction through an Application URI 2721 When the RC successfully launches an application through the "app" 2722 mode (Section 3.3.2), the AS interacts with the RO through that 2723 application to authenticate the user as the RO and gather their 2724 consent. The details of this interaction are out of scope for this 2725 specification. 2727 [[ Editor's note: Should we have anything to say about an app sending 2728 information to a back-end to get details on the pending request? ]] 2730 4.4. Post-Interaction Completion 2732 Upon completing an interaction with the RO, if a "callback" 2733 (Section 3.3.3) mode is available with the current request, the AS 2734 MUST follow the appropriate method at the end of interaction to allow 2735 the RC to continue. If this mode is not available, the AS SHOULD 2736 instruct the RO to return to their RC software upon completion. Note 2737 that these steps still take place in most error cases, such as when 2738 the RO has denied access. This pattern allows the RC to potentially 2739 recover from the error state without restarting the request from 2740 scratch by modifying its request or providing additional information 2741 directly to the AS. 2743 [[ Editor's note: there might be some other kind of push-based 2744 notification or callback that the client can use, or an out-of-band 2745 non-HTTP protocol. The AS would know about this if supported and 2746 used, but the guidance here should be written in such a way as to not 2747 be too restrictive in the next steps that it can take. Still, it's 2748 important that the AS not expect or even allow clients to poll if the 2749 client has stated it can take a callback of some form, otherwise that 2750 sets up a potential session fixation attack vector that the client is 2751 trying to and able to avoid. There has also been a call for post- 2752 interaction that doesn't tie into the security of the protocol, like 2753 redirecting to a static webpage hosted by the client's company. 2754 Would this fit here? ]] 2756 The AS MUST create an interaction reference and associate that 2757 reference with the current interaction and the underlying pending 2758 request. This value MUST be sufficiently random so as not to be 2759 guessable by an attacker. The interaction reference MUST be one- 2760 time-use. 2762 The AS MUST calculate a hash value based on the RC and AS nonces and 2763 the interaction reference, as described in Section 4.4.3. The RC 2764 will use this value to validate the return call from the AS. 2766 The AS then MUST send the hash and interaction reference based on the 2767 interaction finalization mode as described in the following sections. 2769 4.4.1. Completing Interaction with a Browser Redirect to the Callback 2770 URI 2772 When using the "callback" interaction mode (Section 3.3.3) with the 2773 "redirect" method, the AS signals to the RC that interaction is 2774 complete and the request can be continued by directing the RO (in 2775 their browser) back to the RC's callback URL sent in the callback 2776 request (Section 2.5.3.1). 2778 The AS secures this callback by adding the hash and interaction 2779 reference as query parameters to the RC's callback URL. 2781 hash REQUIRED. The interaction hash value as described in 2782 Section 4.4.3. 2784 interact_ref REQUIRED. The interaction reference generated for this 2785 interaction. 2787 The means of directing the RO to this URL are outside the scope of 2788 this specification, but common options include redirecting the RO 2789 from a web page and launching the system browser with the target URL. 2791 https://client.example.net/return/123455 2792 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2793 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2795 When receiving the request, the RC MUST parse the query parameters to 2796 calculate and validate the hash value as described in Section 4.4.3. 2797 If the hash validates, the RC sends a continuation request to the AS 2798 as described in Section 5.1 using the interaction reference value 2799 received here. 2801 4.4.2. Completing Interaction with a Direct HTTP Request Callback 2803 When using the "callback" interaction mode (Section 3.3.3) with the 2804 "push" method, the AS signals to the RC that interaction is complete 2805 and the request can be continued by sending an HTTP POST request to 2806 the RC's callback URL sent in the callback request (Section 2.5.3.2). 2808 The entity message body is a JSON object consisting of the following 2809 two fields: 2811 hash REQUIRED. The interaction hash value as described in 2812 Section 4.4.3. 2814 interact_ref REQUIRED. The interaction reference generated for this 2815 interaction. 2817 POST /push/554321 HTTP/1.1 2818 Host: client.example.net 2819 Content-Type: application/json 2821 { 2822 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2823 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2824 } 2826 When receiving the request, the RC MUST parse the JSON object and 2827 validate the hash value as described in Section 4.4.3. If the hash 2828 validates, the RC sends a continuation request to the AS as described 2829 in Section 5.1 using the interaction reference value received here. 2831 4.4.3. Calculating the interaction hash 2833 The "hash" parameter in the request to the RC's callback URL ties the 2834 front channel response to an ongoing request by using values known 2835 only to the parties involved. This security mechanism allows the RC 2836 to protect itself against several kinds of session fixation and 2837 injection attacks. The AS MUST always provide this hash, and the RC 2838 MUST validate the hash when received. 2840 [[ Editor's note: If the client uses a unique callback URL per 2841 request, that prevents some of the same attacks, but without the same 2842 cryptographic binding between the interaction and delegation 2843 channels. A unique URI would allow the client to differentiate 2844 inputs, but it would not prevent an attacker from injecting an 2845 unrelated interaction reference into this channel. ]] 2847 To calculate the "hash" value, the party doing the calculation first 2848 takes the "nonce" value sent by the RC in the interaction section of 2849 the initial request (Section 2.5.3), the AS's nonce value from the 2850 callback response (Section 3.3.3), and the "interact_ref" sent to the 2851 RC's callback URL. These three values are concatenated to each other 2852 in this order using a single newline character as a separator between 2853 the fields. There is no padding or whitespace before or after any of 2854 the lines, and no trailing newline character. 2856 VJLO6A4CAYLBXHTR0KRO 2857 MBDOFXG4Y5CVJCX821LH 2858 4IFWWIKYBC2PQ6U56NL1 2860 The party then hashes this string with the appropriate algorithm 2861 based on the "hash_method" parameter of the "callback". If the 2862 "hash_method" value is not present in the RC's request, the algorithm 2863 defaults to "sha3". 2865 [[ Editor's note: these hash algorithms should be pluggable, and 2866 ideally we shouldn't redefine yet another crypto registry for this 2867 purpose, but I'm not convinced an appropriate one already exists. 2868 Furthermore, we should be following best practices here whether it's 2869 a plain hash, a keyed MAC, an HMAC, or some other form of 2870 cryptographic function. I'm not sure what the defaults and options 2871 ought to be, but SHA512 and SHA3 were picked based on what was 2872 available to early developers. ]] 2874 4.4.3.1. SHA3-512 2876 The "sha3" hash method consists of hashing the input string with the 2877 512-bit SHA3 algorithm. The byte array is then encoded using URL 2878 Safe Base64 with no padding. The resulting string is the hash value. 2880 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2882 4.4.3.2. SHA2-512 2884 The "sha2" hash method consists of hashing the input string with the 2885 512-bit SHA2 algorithm. The byte array is then encoded using URL 2886 Safe Base64 with no padding. The resulting string is the hash value. 2888 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bpj84rh4mC9aE9x7HPBFcIHw 2890 5. Continuing a Grant Request 2892 While it is possible for the AS to return a Section 3 with all the 2893 RC's requested information (including access tokens (Section 3.2) and 2894 direct user information (Section 3.4)), it's more common that the AS 2895 and the RC will need to communicate several times over the lifetime 2896 of an access grant. This is often part of facilitating interaction 2897 (Section 4), but it could also be used to allow the AS and RC to 2898 continue negotiating the parameters of the original grant request 2899 (Section 2). 2901 To enable this ongoing negotiation, the AS returns a "continue" field 2902 in the response (Section 3.1) that contains information the RC needs 2903 to continue this process with another request, including a URI to 2904 access as well as an optional access token to use during the 2905 continued requests. 2907 When the RC makes any calls to the continuation URL, the RC MUST 2908 present proof of the most recent key associated with this ongoing 2909 request by signing the request as described in Section 8. The key in 2910 use will be either the key from the initial request (Section 2.3.2) 2911 or its most recent rotation. [[ Editor's note: we need to have a 2912 secure way to rotate the key used for the continuation here. In most 2913 cases this will be a rotation for the client instance, since a client 2914 without an instance record would likely just present a new key for a 2915 new request. In that case it could go with the client management, 2916 above - but it doesn't necessarily have to be. ]] 2918 For example, here the RC makes a POST request and signs with detached 2919 JWS: 2921 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 2922 Host: server.example.com 2923 Detached-JWS: ejy0... 2925 If the AS includes an "access_token" in the "continue" response in 2926 Section 3.1, the RC MUST include the access token the request as 2927 described in Section 7. Note that the access token is always bound 2928 to the RC's presented key (or its most recent rotation). 2930 For example, here the RC makes a POST request with the interaction 2931 reference, includes the access token, and signs with detached JWS: 2933 POST /continue HTTP/1.1 2934 Host: server.example.com 2935 Content-type: application/json 2936 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2937 Detached-JWS: ejy0... 2939 { 2940 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2941 } 2943 The AS MUST be able to tell from the RC's request which specific 2944 ongoing request is being accessed. Common methods for doing so 2945 include using a unique, unguessable URL for each continuation 2946 response, associating the request with the provided access token, or 2947 allowing only a single ongoing grant request for a given RC instance 2948 at a time. If the AS cannot determine a single active grant request 2949 to map the continuation request to, the AS MUST return an error. 2951 The ability to continue an already-started request allows the RC to 2952 perform several important functions, including presenting additional 2953 information from interaction, modifying the initial request, and 2954 getting the current state of the request. 2956 If a "wait" parameter was included in the continuation response 2957 (Section 3.1), the RC MUST NOT call the continuation URI prior to 2958 waiting the number of seconds indicated. If no "wait" period is 2959 indicated, the RC SHOULD wait at least 5 seconds [[ Editor's note: 2960 what's a reasonable amount of time so as not to DOS the server?? ]]. 2961 If the RC does not respect the given wait period, the AS MUST return 2962 an error. 2964 The response from the AS is a JSON object and MAY contain any of the 2965 fields described in Section 3, as described in more detail in the 2966 sections below. 2968 If the AS determines that the RC can make a further continuation 2969 request, the AS MUST include a new "continue" response (Section 3.1). 2970 If the continuation was previously bound to an access token, the new 2971 "continue" response MUST include a bound access token as well, and 2972 this token SHOULD be a new access token. [[ Editor's note: this used 2973 to be a MUST, but is it safe to back off that requirement? ]] If the 2974 AS does not return a new "continue" response, the RC MUST NOT make an 2975 additional continuation request. If a RC does so, the AS MUST return 2976 an error. 2978 For continuation functions that require the RC to send a message 2979 body, the body MUST be a JSON object. 2981 5.1. Continuing After a Completed Interaction 2983 When the AS responds to the RC's "callback" parameter as in 2984 Section 4.4.1, this response includes an interaction reference. The 2985 RC MUST include that value as the field "interact_ref" in a POST 2986 request to the continuation URI. 2988 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 2989 Host: server.example.com 2990 Content-type: application/json 2991 Detached-JWS: ejy0... 2993 { 2994 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2995 } 2997 Since the interaction reference is a one-time-use value as described 2998 in Section 4.4.1, if the RC needs to make additional continuation 2999 calls after this request, the RC MUST NOT include the interaction 3000 reference. If the AS detects an RC submitting the same interaction 3001 reference multiple times, the AS MUST return an error and SHOULD 3002 invalidate the ongoing request. 3004 The Section 3 MAY contain any newly-created access tokens 3005 (Section 3.2) or newly-released subject claims (Section 3.4). The 3006 response MAY contain a new "continue" response (Section 3.1) as 3007 described above. The response SHOULD NOT contain any interaction 3008 responses (Section 3.3). [[ Editor's note: This last one might be 3009 overly restrictive, since some kinds of interaction could require 3010 multiple round trips. We need more examples and experience beyond 3011 redirect-based interaction here. ]] 3013 For example, if the request is successful in causing the AS to issue 3014 access tokens and release subject claims, the response could look 3015 like this: 3017 { 3018 "access_token": { 3019 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3020 "key": false, 3021 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 3022 }, 3023 "subject": { 3024 "sub_ids": [ { 3025 "subject_type": "email", 3026 "email": "user@example.com", 3027 } ] 3028 } 3029 } 3031 With this example, the RC can not make an additional continuation 3032 request because a "continue" field is not included. 3034 [[ Editor's note: other interaction methods, such as a challenge- 3035 response cryptographic protocol, would use a similar construct as 3036 here, but have different rules. Would it be reasonable to allow them 3037 to be combined? Could this be combined further with the "update" 3038 method in Section 5.3? ]] 3040 5.2. Continuing During Pending Interaction 3042 When the RC does not include a "callback" parameter, the RC will 3043 often need to poll the AS until the RO has authorized the request. 3044 To do so, the RC makes a POST request to the continuation URI as in 3045 Section 5.1, but does not include a message body. 3047 POST /continue HTTP/1.1 3048 Host: server.example.com 3049 Content-type: application/json 3050 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3051 Detached-JWS: ejy0... 3053 The Section 3 MAY contain any newly-created access tokens 3054 (Section 3.2) or newly-released subject claims (Section 3.4). The 3055 response MAY contain a new "continue" response (Section 3.1) as 3056 described above. If a "continue" field is included, it SHOULD 3057 include a "wait" field to facilitate a reasonable polling rate by the 3058 RC. The response SHOULD NOT contain interaction responses 3059 (Section 3.3). 3061 For example, if the request has not yet been authorized by the RO, 3062 the AS could respond by telling the RC to make another continuation 3063 request in the future. In this example, a new, unique access token 3064 has been issued for the call, which the RC will use in its next 3065 continuation request. 3067 { 3068 "continue": { 3069 "access_token": { 3070 "value": "33OMUKMKSKU80UPRY5NM", 3071 "key": true 3072 }, 3073 "uri": "https://server.example.com/continue", 3074 "wait": 30 3075 } 3076 } 3078 [[ Editor's note: Do we want to be more precise about what's expected 3079 inside the "continue" object? I think that at least the URI is 3080 required, access token required IF used, etc. This is even if they 3081 haven't changed since last time, and the client will use whatever 3082 value comes back. ]] 3084 [[ Editor's note: extensions to this might need to communicate to the 3085 client what the current state of the user interaction is. This has 3086 been done in similar proprietary protocols, but the details of that 3087 information tend to be highly application specific. Like "user 3088 hasn't logged in yet", "user has logged in but is still sitting at 3089 the page", or "user seems to have wandered off". We might be able to 3090 provide a decent framework for hanging this kind of stuff on. ]] 3092 If the request is successful in causing the AS to issue access tokens 3093 and release subject claims, the response could look like this 3094 example: 3096 { 3097 "access_token": { 3098 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3099 "key": false, 3100 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 3101 }, 3102 "subject": { 3103 "sub_ids": [ { 3104 "subject_type": "email", 3105 "email": "user@example.com", 3106 } ] 3107 } 3108 } 3109 5.3. Modifying an Existing Request 3111 The RC might need to modify an ongoing request, whether or not tokens 3112 have already been issued or claims have already been released. In 3113 such cases, the RC makes an HTTP PATCH request to the continuation 3114 URI and includes any fields it needs to modify. Fields that aren't 3115 included in the request are considered unchanged from the original 3116 request. 3118 The RC MAY include the "resources" and "subject" fields as described 3119 in Section 2.1 and Section 2.2. Inclusion of these fields override 3120 any values in the initial request, which MAY trigger additional 3121 requirements and policies by the AS. For example, if the RC is 3122 asking for more access, the AS could require additional interaction 3123 with the RO to gather additional consent. If the RC is asking for 3124 more limited access, the AS could determine that sufficient 3125 authorization has been granted to the RC and return the more limited 3126 access rights immediately. [[ Editor's note: We could state 3127 something like "resources and subject MUST NOT be the same as in the 3128 initial or previous request" to enforce that this really is a change, 3129 but is there value in calling that out here? Somehow we do probably 3130 want to tell the AS to not let a client simply post the same request 3131 here to rotate access tokens now that we've got an explicit function 3132 for that, right? ]] 3134 The RC MAY include the "interact" field as described in Section 2.5. 3135 Inclusion of this field indicates that the RC is capable of driving 3136 interaction with the RO, and this field replaces any values from a 3137 previous request. The AS MAY respond to any of the interaction 3138 responses as described in Section 3.3, just like it would to a new 3139 request. 3141 The RC MAY include the "user" field as described in Section 2.4 to 3142 present new assertions or information about the RQ. [[ Editor's note: 3143 This would allow the client to do things like gather the user's 3144 identifiers post-request, or gather an assertion from an on-device 3145 element that the AS can verify. It opens up potential avenues for 3146 trouble if the user here is different from the RO that's already 3147 showed up at the AS or race conditions if the RQ's identity changes 3148 mid-stream. But that said, this seems important for multi-log-in 3149 cases and the like, probably. ]] 3151 The RC MUST NOT include the "client" section of the request. [[ 3152 Editor's note: We do not want the client to be able to get swapped 3153 out from underneath the user, especially post-consent. However, 3154 including this field in a PATCH update request might be the place to 3155 define key rotation for the grant request itself, but we'd need to be 3156 very careful of how that works. And it feels like it might have 3157 consequences outside of the request, such as rotating the key for all 3158 ongoing grants for a given client instance, which isn't really 3159 desirable here. We need a lot more discussion and engineering on 3160 this before including it. ]] 3162 The RC MAY include post-interaction responses such as described in 3163 Section 5.1. [[ Editor's note: it seems a little odd to include this 3164 in a request but I can't see a reason to not allow it. ]] 3166 Modification requests MUST NOT alter previously-issued access tokens. 3167 Instead, any access tokens issued from a continuation are considered 3168 new, separate access tokens. The AS MAY revoke existing access 3169 tokens after a modification has occurred. [[ Editor's note: this 3170 might be subject to the "multi_token" flag, but since we're creating 3171 a NEW access token and not rotating an existing one, this seems to be 3172 a different use case. ]] 3174 Modification requests MAY result in previously-issued access tokens 3175 being revoked. [[ Editor's note: there is a solid argument to be made 3176 for always revoking old access tokens here, but we need more 3177 discussion on the boundaries for such a requirement. If they stick 3178 around, it does make a "read" request weird because now we've got 3179 multiple access tokens sticking around associated with a grant 3180 request and no good place to put them. ]] 3182 If the modified request can be granted immediately by the AS, the 3183 Section 3 MAY contain any newly-created access tokens (Section 3.2) 3184 or newly-released subject claims (Section 3.4). The response MAY 3185 contain a new "continue" response (Section 3.1) as described above. 3186 If interaction can occur, the response SHOULD contain interaction 3187 responses (Section 3.3) as well. 3189 For example, an RC initially requests a set of resources using 3190 references: 3192 POST /tx HTTP/1.1 3193 Host: server.example.com 3194 Content-type: application/json 3195 Detached-JWS: ejy0... 3197 { 3198 "resources": [ 3199 "read", "write" 3200 ], 3201 "interact": { 3202 "redirect": true, 3203 "callback": { 3204 "method": "redirect", 3205 "uri": "https://client.example.net/return/123455", 3206 "nonce": "LKLTI25DK82FX4T4QFZC" 3207 } 3208 }, 3209 "client": "987YHGRT56789IOLK" 3210 } 3212 Access is granted by the RO, and a token is issued by the AS. In its 3213 final response, the AS includes a "continue" field: 3215 { 3216 "continue": { 3217 "access_token": { 3218 "value": "80UPRY5NM33OMUKMKSKU", 3219 "key": true 3220 }, 3221 "uri": "https://server.example.com/continue", 3222 "wait": 30 3223 }, 3224 "access_token": ... 3225 } 3227 This allows the RC to make an eventual continuation call. The RC 3228 realizes that it no longer needs "write" access and therefore 3229 modifies its ongoing request, here asking for just "read" access 3230 instead of both "read" and "write" as before. 3232 PATCH /continue HTTP/1.1 3233 Host: server.example.com 3234 Content-type: application/json 3235 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3236 Detached-JWS: ejy0... 3238 { 3239 "resources": [ 3240 "read" 3241 ] 3242 ... 3243 } 3245 The AS replaces the previous "resources" from the first request, 3246 allowing the AS to determine if any previously-granted consent 3247 already applies. In this case, the AS would likely determine that 3248 reducing the breadth of the requested access means that new access 3249 tokens can be issued to the RC. The AS would likely revoke 3250 previously-issued access tokens that had the greater access rights 3251 associated with them. 3253 { 3254 "continue": { 3255 "access_token": { 3256 "value": "M33OMUK80UPRY5NMKSKU", 3257 "key": true 3258 }, 3259 "uri": "https://server.example.com/continue", 3260 "wait": 30 3261 }, 3262 "access_token": ... 3263 } 3265 For another example, the RC initially requests read-only access but 3266 later needs to step up its access. The initial request could look 3267 like this example. 3269 POST /tx HTTP/1.1 3270 Host: server.example.com 3271 Content-type: application/json 3272 Detached-JWS: ejy0... 3274 { 3275 "resources": [ 3276 "read" 3277 ], 3278 "interact": { 3279 "redirect": true, 3280 "callback": { 3281 "method": "redirect", 3282 "uri": "https://client.example.net/return/123455", 3283 "nonce": "LKLTI25DK82FX4T4QFZC" 3284 } 3285 }, 3286 "client": "987YHGRT56789IOLK" 3287 } 3289 Access is granted by the RO, and a token is issued by the AS. In its 3290 final response, the AS includes a "continue" field: 3292 { 3293 "continue": { 3294 "access_token": { 3295 "value": "80UPRY5NM33OMUKMKSKU", 3296 "key": true 3297 }, 3298 "uri": "https://server.example.com/continue", 3299 "wait": 30 3300 }, 3301 "access_token": ... 3302 } 3304 This allows the RC to make an eventual continuation call. The RC 3305 later realizes that it now needs "write" access in addition to the 3306 "read" access. Since this is an expansion of what it asked for 3307 previously, the RC also includes a new interaction section in case 3308 the AS needs to interact with the RO again to gather additional 3309 authorization. Note that the RC's nonce and callback are different 3310 from the initial request. Since the original callback was already 3311 used in the initial exchange, and the callback is intended for one- 3312 time-use, a new one needs to be included in order to use the callback 3313 again. 3315 [[ Editor's note: the net result of this is that interaction requests 3316 are really only meant to be responded to exactly once by the AS. 3317 This isn't spelled out explicitly, but could be included in 3318 Section 2.5 and/or Section 3.3. ]] 3320 PATCH /continue HTTP/1.1 3321 Host: server.example.com 3322 Content-type: application/json 3323 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3324 Detached-JWS: ejy0... 3326 { 3327 "resources": [ 3328 "read", "write" 3329 ], 3330 "interact": { 3331 "redirect": true, 3332 "callback": { 3333 "method": "redirect", 3334 "uri": "https://client.example.net/return/654321", 3335 "nonce": "K82FX4T4LKLTI25DQFZC" 3336 } 3337 } 3338 } 3340 From here, the AS can determine that the RC is asking for more than 3341 it was previously granted, but since the RC has also provided a 3342 mechanism to interact with the RO, the AS can use that to gather the 3343 additional consent. The protocol continues as it would with a new 3344 request. Since the old access tokens are good for a subset of the 3345 rights requested here, the AS might decide to not revoke them. 3346 However, any access tokens granted after this update process are new 3347 access tokens and do not modify the rights of existing access tokens. 3349 5.4. Getting the Current State of a Grant Request 3351 If the RC needs to get the current state of an ongoing grant request, 3352 it makes an HTTP GET request to the continuation URI. This request 3353 MUST NOT alter the grant request in any fashion, including causing 3354 the issuance of new access tokens or modification of interaction 3355 parameters. 3357 The AS MAY include existing access tokens and previously-released 3358 subject claims in the response. The AS MUST NOT issue a new access 3359 token or release a new subject claim in response to this request. 3361 GET /continue HTTP/1.1 3362 Host: server.example.com 3363 Content-type: application/json 3364 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3365 Detached-JWS: ejy0... 3367 The response MAY include any fields described Section 3 that are 3368 applicable to this ongoing request, including the most recently 3369 issued access tokens, any released subject claims, and any currently 3370 active interaction modes. The response MAY contain a new "continue" 3371 response (Section 3.1) as described above. 3373 [[ Editor's note: I'm a little dubious about the need for this 3374 particular function in reality, but including it for completeness 3375 sake. There are a lot of questions we need to answer, such as 3376 whether it's safe to include access tokens and claims in the response 3377 of this kind of "read" at all, and whether it makes sense to include 3378 items like interaction nonces in the response. This discussion 3379 should be driven by the use cases calling for this "read" 3380 functionality. There have been similar functions within proprietary 3381 protocols where the client calls an endpoint at the AS to figure out 3382 where the user is in the interaction process at the AS, letting the 3383 client provide a smarter UI. It doesn't seem like we could do that 3384 in depth here since it would be highly application specific, but that 3385 might be a good example of how to extend a response and give a client 3386 extra information. ]] 3388 5.5. Canceling a Grant Request 3390 If the RC wishes to cancel an ongoing grant request, it makes an HTTP 3391 DELETE request to the continuation URI. 3393 DELETE /continue HTTP/1.1 3394 Host: server.example.com 3395 Content-type: application/json 3396 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3397 Detached-JWS: ejy0... 3399 If the request is successfully cancelled, the AS responds with an 3400 HTTP 202. The AS MUST revoke all associated access tokens, if 3401 possible. 3403 6. Token Management 3405 If an access token response includes the "manage" parameter as 3406 described in Section 3.2.1, the RC MAY call this URL to manage the 3407 access token with any of the actions defined in the following 3408 sections. Other actions are undefined by this specification. 3410 The access token being managed acts as the access element for its own 3411 management API. The RC MUST present proof of an appropriate key 3412 along with the access token. 3414 If the token is sender-constrained (i.e., not a bearer token), it 3415 MUST be sent with the appropriate binding for the access token 3416 (Section 7). 3418 If the token is a bearer token, the RC MUST present proof of the same 3419 key identified in the initial request (Section 2.3.2) as described in 3420 Section 8. 3422 The AS MUST validate the proof and assure that it is associated with 3423 either the token itself or the RC the token was issued to, as 3424 appropriate for the token's presentation type. 3426 [[ Editor's note: Should we allow for "update" to an access token by 3427 the client posting new information from a "request"? It seems this 3428 might make things weird since an access token is generally considered 3429 an unchanging thing, and the client could always request a new access 3430 token if they're allowed to continue the grant request post-issuance 3431 as in Section 5.3. There's also a possibility of being able to 3432 "read" a token's state with a GET, much like token introspection but 3433 using the token's/client's key instead of the RS key. But would a 3434 client need to "read" a token state after issuance? Is there a 3435 security risk to offering that functionality? Introspection is 3436 nearly always relegated to RS calls in practice since the client is 3437 focused on using the token at the RS. The client can always read the 3438 state of the grant itself, separately. ]] 3440 6.1. Rotating the Access Token 3442 The RC makes an HTTP POST to the token management URI, sending the 3443 access token in the appropriate header and signing the request with 3444 the appropriate key. 3446 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3447 Host: server.example.com 3448 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3449 Detached-JWS: eyj0.... 3451 [[ Editor's note: This could alternatively be an HTTP PUT verb, since 3452 we are telling the AS that we want to replace the token. However, we 3453 are not providing the information we want to replace the token with, 3454 and in fact that's up to the AS entirely, not the client. For that 3455 reason, I think a POST still makes the most sense. ]] 3456 The AS validates that the token presented is associated with the 3457 management URL, that the AS issued the token to the given RC, and 3458 that the presented key is appropriate to the token. 3460 If the access token has expired, the AS SHOULD honor the rotation 3461 request to the token management URL since it is likely that the RC is 3462 attempting to refresh the expired token. To support this, the AS MAY 3463 apply different lifetimes for the use of the token in management vs. 3464 its use at an RS. An AS MUST NOT honor a rotation request for an 3465 access token that has been revoked, either by the AS or by the RC 3466 through the token management URI (Section 6.2). 3468 If the token is validated and the key is appropriate for the request, 3469 the AS MUST invalidate the current access token associated with this 3470 URL, if possible, and return a new access token response as described 3471 in Section 3.2.1, unless the "multi_token" flag is specified in the 3472 request. [[ Editor's note: We could also use different verbs to 3473 signal whether or not the old token should be kept around or not, 3474 instead of using a token flag to do this. ]] The value of the access 3475 token MUST NOT be the same as the current value of the access token 3476 used to access the management API. The response MAY include an 3477 updated access token management URL as well, and if so, the RC MUST 3478 use this new URL to manage the new access token. 3480 [[ Editor's note: the net result is that the client's always going to 3481 use the management URL that comes back. But should we let the server 3482 omit it from the response if it doesn't change? That seems like an 3483 odd optimization that doesn't help the client. ]] 3485 { 3486 "access_token": { 3487 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3488 "key": false, 3489 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 3490 "resources": [ 3491 { 3492 "type": "photo-api", 3493 "actions": [ 3494 "read", 3495 "write", 3496 "dolphin" 3497 ], 3498 "locations": [ 3499 "https://server.example.net/", 3500 "https://resource.local/other" 3501 ], 3502 "datatypes": [ 3503 "metadata", 3504 "images" 3505 ] 3506 }, 3507 "read", "dolphin-metadata" 3508 ] 3509 } 3510 } 3512 [[ Editor's note: If the client is using its own key as the proof, 3513 like with a bearer access token, the AS is going to need to know if 3514 the client's key has been rotated. We don't have a mechanism for 3515 rotating the token's key or the client's key yet either - so that 3516 could occur through this management function as well. ]] 3518 6.2. Revoking the Access Token 3520 If the RC wishes to revoke the access token proactively, such as when 3521 a user indicates to the RC that they no longer wish for it to have 3522 access or the RC application detects that it is being uninstalled, 3523 the RC can use the token management URI to indicate to the AS that 3524 the AS should invalidate the access token for all purposes. 3526 The RC makes an HTTP DELETE request to the token management URI, 3527 presenting the access token and signing the request with the 3528 appropriate key. 3530 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3531 Host: server.example.com 3532 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3533 Detached-JWS: eyj0.... 3535 If the key presented is associated with the token (or the RC, in the 3536 case of a bearer token), the AS MUST invalidate the access token, if 3537 possible, and return an HTTP 204 response code. 3539 204 No Content 3541 Though the AS MAY revoke an access token at any time for any reason, 3542 the token management function is specifically for the RC's use. If 3543 the access token has already expired or has been revoked through 3544 other means, the AS SHOULD honor the revocation request to the token 3545 management URL as valid, since the end result is still the token not 3546 being usable. 3548 7. Using Access Tokens 3550 The method the RC uses to send an access token to the RS depends on 3551 the value of the "key" and "proof" parameters in the access token 3552 response (Section 3.2.1). 3554 If the key value is the boolean "false", the access token is a bearer 3555 token sent using the HTTP Header method defined in [RFC6750]. 3557 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3559 The form parameter and query parameter methods of [RFC6750] MUST NOT 3560 be used. 3562 If the "key" value is the boolean "true", the access token MUST be 3563 sent to the RS using the same key and proofing mechanism that the RC 3564 used in its initial request. 3566 If the "key" value is an object, the value of the "proof" field 3567 within the key indicates the particular proofing mechanism to use. 3568 The access token is sent using the HTTP authorization scheme "GNAP" 3569 along with a key proof as described in Section 8 for the key bound to 3570 the access token. For example, a "jwsd"-bound access token is sent 3571 as follows: 3573 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3574 Detached-JWS: eyj0.... 3576 [[ Editor's note: I don't actually like the idea of using only one 3577 header type for differently-bound access tokens. Perhaps instead 3578 these values should somehow reflect the key binding types. Maybe 3579 there can be multiple fields after the "GNAP" keyword using 3580 structured headers? Or a set of derived headers like GNAP-mtls? 3581 This might also be better as a separate specification, like it was in 3582 OAuth 2. However, access tokens should be able to use any key 3583 binding mechanisms here, plus bearer. ]] 3585 8. Binding Keys 3587 Any keys presented by the RC to the AS or RS MUST be validated as 3588 part of the request in which they are presented. The type of binding 3589 used is indicated by the proof parameter of the key section in the 3590 initial request Section 2.3.2. Values defined by this specification 3591 are as follows: 3593 jwsd A detached JWS signature header 3595 jws Attached JWS payload 3597 mtls Mutual TLS certificate verification 3599 dpop OAuth Demonstration of Proof-of-Possession key proof header 3601 httpsig HTTP Signing signature header 3603 oauthpop OAuth PoP key proof authentication header 3605 Additional proofing methods are defined by a registry TBD 3606 (Section 12). 3608 All key binding methods used by this specification MUST cover all 3609 relevant portions of the request, including anything that would 3610 change the nature of the request, to allow for secure validation of 3611 the request by the AS. Relevant aspects include the URI being 3612 called, the HTTP method being used, any relevant HTTP headers and 3613 values, and the HTTP message body itself. The recipient of the 3614 signed message MUST validate all components of the signed message to 3615 ensure that nothing has been tampered with or substituted in a way 3616 that would change the nature of the request. 3618 When used in the GNAP delegation protocol, these key binding 3619 mechanisms allow the AS to ensure that the keys presented by the RC 3620 in the initial request are in control of the party calling any 3621 follow-up or continuation requests. To facilitate this requirement, 3622 all keys in the initial request Section 2.3.2 MUST be proved in all 3623 continuation requests Section 5 and token management requests 3624 Section 6, modulo any rotations on those keys over time that the AS 3625 knows about. The AS MUST validate all keys presented by the RC 3626 (Section 2.3.2) or referenced in an ongoing request for each call 3627 within that request. 3629 [[ Editor's note: We are going to need a way for a client to rotate 3630 its keys securely, even while an ongoing grant is in effect. ]] 3632 When used to bind to an access token, the 3634 8.1. Detached JWS 3636 This method is indicated by "jwsd" in the "proof" field. A JWS 3637 [RFC7515] signature object is created as follows: 3639 The header of the JWS MUST contain the "kid" field of the key bound 3640 to this RC for this request. The JWS header MUST contain an "alg" 3641 field appropriate for the key identified by kid and MUST NOT be 3642 "none". The "b64" field MUST be set to "false" and the "crit" field 3643 MUST contain at least "b64" as specified in [RFC7797] 3645 To protect the request, the JWS header MUST contain the following 3646 additional fields. 3648 htm The HTTP Method used to make this request, as an uppercase ASCII 3649 string. 3651 htu The HTTP URI used for this request, including all path and query 3652 components. 3654 ts A timestamp of the request in integer seconds 3656 at_hash When to bind a request to an access token, the access token 3657 hash value. Its value is the base64url encoding of the left-most 3658 half of the hash of the octets of the ASCII representation of the 3659 "access_token" value, where the hash algorithm used is the hash 3660 algorithm used in the "alg" header parameter of the JWS's JOSE 3661 Header. For instance, if the "alg" is "RS256", hash the 3662 "access_token" value with SHA-256, then take the left-most 128 3663 bits and base64url encode them. 3665 [[ Editor's note: It's not the usual practice to put additional 3666 information into the header of a JWS, but this keeps us from having 3667 to normalize the body serialization. Alternatively, we could add all 3668 these fields to the body of the request, but then it gets awkward for 3669 non-body requests like GET/DELETE. ]] 3670 The payload of the JWS object is the serialized body of the request, 3671 and the object is signed according to detached JWS [RFC7797]. 3673 The RC presents the signature in the Detached-JWS HTTP Header field. 3674 [[ Editor's Note: this is a custom header field, do we need this? It 3675 seems like the best place to put this. ]] 3677 POST /tx HTTP/1.1 3678 Host: server.example.com 3679 Content-Type: application/json 3680 Detached-JWS: eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0. 3681 .Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJnDtD0VuUlVjLfwne8AuUY3U7e8 3682 9zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN5_ysveQnYt9Dqi32w6IOtAywkNUD 3683 ZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK57003WJu-wFn2TJUmAbHuqvUsyTb-nz 3684 YOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_vGbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbL 3685 C18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUbntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVW 3686 peQ 3688 { 3689 "resources": [ 3690 "dolphin-metadata" 3691 ], 3692 "interact": { 3693 "redirect": true, 3694 "callback": { 3695 "method": "redirect", 3696 "uri": "https://client.foo", 3697 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3698 } 3699 }, 3700 "client": { 3701 "proof": "jwsd", 3702 "key": { 3703 "jwk": { 3704 "kty": "RSA", 3705 "e": "AQAB", 3706 "kid": "xyz-1", 3707 "alg": "RS256", 3708 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8 3709 xYJCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPF 3710 vpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyD 3711 SWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS 3712 63WYPHi_Ap2B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFe 3713 kpdfWdiPQddQ6Y1cK2U3obvUg7w" 3714 } 3715 } 3716 "display": { 3717 "name": "My Client Display Name", 3718 "uri": "https://example.net/client" 3719 }, 3720 } 3721 } 3722 If the request being made does not have a message body, such as an 3723 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3724 over an empty payload. 3726 When the server (AS or RS) receives the Detached-JWS header, it MUST 3727 parse its contents as a detached JWS object. The HTTP Body is used 3728 as the payload for purposes of validating the JWS, with no 3729 transformations. 3731 [[ Editor's note: this is a potentially fragile signature mechanism. 3732 It doesn't protect arbitrary headers or other specific aspects of the 3733 request, but it's simple to calculate and useful for body-driven 3734 requests, like the client to the AS. Additionally it is potentially 3735 fragile since a multi-tier system could parse the payload and pass 3736 the parsed payload downstream with potential transformations, making 3737 downstream signature validation impossible. We might want to remove 3738 this in favor of general-purpose HTTP signing, or at least provide 3739 guidance on its use. ]] 3741 8.2. Attached JWS 3743 This method is indicated by "jws" in the "proof" field. A JWS 3744 [RFC7515] signature object is created as follows: 3746 The header of the JWS MUST contain the "kid" field of the key bound 3747 to this RC for this request. The JWS header MUST contain an "alg" 3748 field appropriate for the key identified by kid and MUST NOT be 3749 "none". 3751 To protect the request, the JWS header MUST contain the following 3752 additional fields. 3754 htm The HTTP Method used to make this request, as an uppercase ASCII 3755 string. 3757 htu The HTTP URI used for this request, including all path and query 3758 components. 3760 ts A timestamp of the request in integer seconds 3762 at_hash When to bind a request to an access token, the access token 3763 hash value. Its value is the base64url encoding of the left-most 3764 half of the hash of the octets of the ASCII representation of the 3765 "access_token" value, where the hash algorithm used is the hash 3766 algorithm used in the "alg" header parameter of the JWS's JOSE 3767 Header. For instance, if the "alg" is "RS256", hash the 3768 "access_token" value with SHA-256, then take the left-most 128 3769 bits and base64url encode them. 3771 [[ Editor's note: It's not the usual practice to put additional 3772 information into the header of a JWS, but this keeps us from having 3773 to modify the body to use this signature method. Alternatively, we 3774 could add all these fields to the body of the request, but then it 3775 gets awkward for non-body requests like GET/DELETE. ]] 3777 The payload of the JWS object is the JSON serialized body of the 3778 request, and the object is signed according to JWS and serialized 3779 into compact form [RFC7515]. 3781 The RC presents the JWS as the body of the request along with a 3782 content type of "application/jose". The AS MUST extract the payload 3783 of the JWS and treat it as the request body for further processing. 3785 POST /tx HTTP/1.1 3786 Host: server.example.com 3787 Content-Type: application/jose 3789 eyJhbGciOiJSUzI1NiIsImtpZCI6IktBZ05wV2JSeXk5T 3790 WYycmlrbDQ5OExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLC 3791 JodG0iOiJwb3N0IiwiaHR1IjoiL3R4IiwidHMiOjE2MDM 3792 4MDA3ODN9.eyJjYXBhYmlsaXRpZXMiOltdLCJjbGllbnQ 3793 iOnsia2V5Ijp7Imp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi 3794 QVFBQiIsImtpZCI6IktBZ05wV2JSeXk5TWYycmlrbDQ5O 3795 ExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLCJuIjoibGxXbU 3796 hGOFhBMktOTGRteE9QM2t4RDlPWTc2cDBTcjM3amZoejk 3797 0YTkzeG0yRk5xb1NQY1JaQVBkMGxxRFM4TjNVaWE1M2RC 3798 MjNaNTlPd1k0YnBNX1ZmOEdKdnZwdExXbnhvMVB5aG1Qc 3799 i1lY2RTQ1JRZFRjX1pjTUY0aFJWNDhxcWx2dUQwbXF0Y0 3800 RiSWtTQkR2Y2NKbVpId2ZUcERIaW5UOHR0dmNWUDhWa0F 3801 NQXE0a1ZhenhPcE1vSVJzb3lFcF9lQ2U1cFN3cUhvMGRh 3802 Q1dOS1ItRXBLbTZOaU90ZWRGNE91bXQ4TkxLVFZqZllnR 3803 khlQkRkQ2JyckVUZDR2Qk13RHRBbmpQcjNDVkN3d3gyYk 3804 FRVDZTbHhGSjNmajJoaHlJcHE3cGM4clppYjVqTnlYS3d 3805 mQnVrVFZZWm96a3NodC1Mb2h5QVNhS3BZVHA4THROWi13 3806 In0sInByb29mIjoiandzIn0sIm5hbWUiOiJNeSBGaXN0I 3807 ENsaWVudCIsInVyaSI6Imh0dHA6Ly9sb2NhbGhvc3QvY2 3808 xpZW50L2NsaWVudElEIn0sImludGVyYWN0Ijp7ImNhbGx 3809 iYWNrIjp7Im1ldGhvZCI6InJlZGlyZWN0Iiwibm9uY2Ui 3810 OiJkOTAyMTM4ODRiODQwOTIwNTM4YjVjNTEiLCJ1cmkiO 3811 iJodHRwOi8vbG9jYWxob3N0L2NsaWVudC9yZXF1ZXN0LW 3812 RvbmUifSwicmVkaXJlY3QiOnRydWV9LCJyZXNvdXJjZXM 3813 iOnsiYWN0aW9ucyI6WyJyZWFkIiwicHJpbnQiXSwibG9j 3814 YXRpb25zIjpbImh0dHA6Ly9sb2NhbGhvc3QvcGhvdG9zI 3815 l0sInR5cGUiOiJwaG90by1hcGkifSwic3ViamVjdCI6ey 3816 JzdWJfaWRzIjpbImlzcy1zdWIiLCJlbWFpbCJdfX0.LUy 3817 Z8_fERmxbYARq8kBYMwzcd8GnCAKAlo2ZSYLRRNAYWPrp 3818 2XGLJOvg97WK1idf_LB08OJmLVsCXxCvn9mgaAkYNL_Zj 3819 HcusBvY1mNo0E1sdTEr31CVKfC-6WrZCscb8YqE4Ayhh0 3820 Te8kzSng3OkLdy7xN4xeKuHzpF7yGsM52JZ0cBcTo6WrY 3821 EfGdr08AWQJ59ht72n3jTsmYNy9A6I4Wrvfgj3TNxmwYo 3822 jpBAicfjnzA1UVcNm9F_xiSz1_y2tdH7j5rVqBMQife-k 3823 9Ewk95vr3lurthenliYSNiUinVfoW1ybnaIBcTtP1_YCx 3824 g_h1y-B5uZEvYNGCuoCqa6IQ 3826 This example's JWS header decodes to: 3828 { 3829 "alg": "RS256", 3830 "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", 3831 "htm": "post", 3832 "htu": "/tx", 3833 "ts": 1603800783 3834 } 3836 And the JWS body decodes to: 3838 { 3839 "capabilities": [], 3840 "client": { 3841 "key": { 3842 "jwk": { 3843 "kty": "RSA", 3844 "e": "AQAB", 3845 "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", 3846 "n": "llWmHF8XA2KNLdmxOP3kxD9OY76p0Sr37jfhz94a93xm2FNqoSPcRZAPd0lqDS8N3Uia53dB23Z59OwY4bpM_Vf8GJvvptLWnxo1PyhmPr-ecdSCRQdTc_ZcMF4hRV48qqlvuD0mqtcDbIkSBDvccJmZHwfTpDHinT8ttvcVP8VkAMAq4kVazxOpMoIRsoyEp_eCe5pSwqHo0daCWNKR-EpKm6NiOtedF4Oumt8NLKTVjfYgFHeBDdCbrrETd4vBMwDtAnjPr3CVCwwx2bAQT6SlxFJ3fj2hhyIpq7pc8rZib5jNyXKwfBukTVYZozksht-LohyASaKpYTp8LtNZ-w" 3847 }, 3848 "proof": "jws" 3849 }, 3850 "name": "My Fist Client", 3851 "uri": "http://localhost/client/clientID" 3852 }, 3853 "interact": { 3854 "callback": { 3855 "method": "redirect", 3856 "nonce": "d90213884b840920538b5c51", 3857 "uri": "http://localhost/client/request-done" 3858 }, 3859 "redirect": true 3860 }, 3861 "resources": { 3862 "actions": [ 3863 "read", 3864 "print" 3865 ], 3866 "locations": [ 3867 "http://localhost/photos" 3868 ], 3869 "type": "photo-api" 3870 }, 3871 "subject": { 3872 "sub_ids": [ 3873 "iss-sub", 3874 "email" 3875 ] 3876 } 3877 } 3879 If the request being made does not have a message body, such as an 3880 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3881 over an empty payload and passed in the "Detached-JWS" header as 3882 described in Section 8.1. 3884 [[ Editor's note: A downside to this method is that it requires the 3885 content type to be something other than application/json, and it 3886 doesn't work against an RS without additional profiling since it 3887 takes over the request body - plus we have to specify different 3888 delivery locations for a GET vs. a POST, for example. Additionally 3889 it is potentially fragile like a detached JWS since a multi-tier 3890 system could parse the payload and pass the parsed payload downstream 3891 with potential transformations. We might want to remove this in 3892 favor of general-purpose HTTP signing, or at least provide guidance 3893 on its use. ]] 3895 8.3. Mutual TLS 3897 This method is indicated by "mtls" in the "proof" field. The RC 3898 presents its client certificate during TLS negotiation with the 3899 server (either AS or RS). The AS or RS takes the thumbprint of the 3900 client certificate presented during mutual TLS negotiation and 3901 compares that thumbprint to the thumbprint presented by the RC 3902 application as described in [RFC8705] section 3. 3904 POST /tx HTTP/1.1 3905 Host: server.example.com 3906 Content-Type: application/json 3907 SSL_CLIENT_CERT: MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3MDUGA1UEAwwuQmVz 3908 cG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTELMAkG 3909 A1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFgpjYUBic3BrLmlv 3910 MRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQLDANNVEkwHhcN 3911 MTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQDDAlsb2NhbGhv 3912 c3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3DQEJARYRdGxz 3913 Y2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZXJpbmcxDDAK 3914 BgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMmaXQHb 3915 s/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77OmJ4bQLokq 3916 sd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYNDOmCdHww 3917 UjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+aOJytk 3918 vj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nqsmZQc 3919 jfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8puLW 3920 aD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DBs 3921 BgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdGxz 3922 Y2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGxz 3923 Y2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3924 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe 3925 2573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboX 3926 hufHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb 3927 907/p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3k 3928 lwLW9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh 3930 { 3931 "resources": [ 3932 "dolphin-metadata" 3933 ], 3934 "interact": { 3935 "redirect": true, 3936 "callback": { 3937 "method": "redirect", 3938 "uri": "https://client.foo", 3939 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3940 } 3941 }, 3942 "client": { 3943 "display": { 3944 "name": "My Client Display Name", 3945 "uri": "https://example.net/client" 3946 }, 3947 "key": { 3948 "proof": "mtls", 3949 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3 3950 MDUGA1UEAwwuQmVzcG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1d 3951 Ghvcml0eTELMAkGA1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFg 3952 pjYUBic3BrLmlvMRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQ 3953 LDANNVEkwHhcNMTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQD 3954 DAlsb2NhbGhvc3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3D 3955 QEJARYRdGxzY2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZX 3956 JpbmcxDDAKBgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggE 3957 BAMmaXQHbs/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77Om 3958 J4bQLokqsd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYND 3959 OmCdHwwUjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+ 3960 aOJytkvj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nq 3961 smZQcjfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8 3962 puLWaD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4 3963 DBsBgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdG 3964 xzY2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGx 3965 zY2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3966 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe2 3967 573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboXhu 3968 fHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb907 3969 /p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3klwLW 3970 9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh" 3971 } 3972 } 3974 [[ Editor's note: This method requires no changes to the HTTP message 3975 itself, since the security relies on the TLS layer. However, the 3976 application level will need to validate that the certificate key used 3977 in the request is the one expected for the specific request. ]] 3979 8.4. Demonstration of Proof-of-Possession (DPoP) 3981 This method is indicated by "dpop" in the "proof" field. The RC 3982 creates a Demonstration of Proof-of-Possession signature header as 3983 described in [I-D.ietf-oauth-dpop] section 2. In addition to the 3984 required fields, the DPoP body MUST also contain a digest of the 3985 request body: 3987 digest Digest of the request body as the value of the Digest header 3988 defined in [RFC3230]. 3990 POST /tx HTTP/1.1 3991 Host: server.example.com 3992 Content-Type: application/json 3993 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6Il 3994 JTQSIsImUiOiJBUUFCIiwia2lkIjoieHl6LWNsaWVudCIsImFsZyI6IlJTMjU2Iiwibi 3995 I6Inp3Q1RfM2J4LWdsYmJIcmhlWXBZcFJXaVk5SS1uRWFNUnBablJySWpDczZiX2VteV 3996 RrQmtEREVqU3lzaTM4T0M3M2hqMS1XZ3hjUGRLTkdaeUlvSDNRWmVuMU1LeXloUXBMSk 3997 cxLW9MTkxxbTdwWFh0ZFl6U2RDOU8zLW9peXk4eWtPNFlVeU5aclJSZlBjaWhkUUNiT1 3998 9PQzhRdWdtZzlyZ05ET1NxcHBkYU5lYXMxb3Y5UHhZdnhxcnoxLThIYTdna0QwMFlFQ1 3999 hIYUIwNXVNYVVhZEhxLU9fV0l2WVhpY2c2STVqNlM0NFZOVTY1VkJ3dS1BbHluVHhRZE 4000 1BV1AzYll4VlZ5NnAzLTdlVEpva3ZqWVRGcWdEVkRaOGxVWGJyNXlDVG5SaG5oSmd2Zj 4001 NWakRfbWFsTmU4LXRPcUs1T1NEbEhUeTZnRDlOcWRHQ20tUG0zUSJ9fQ.eyJodHRwX21 4002 ldGhvZCI6IlBPU1QiLCJodHRwX3VyaSI6Imh0dHA6XC9cL2hvc3QuZG9ja2VyLmludGV 4003 ybmFsOjk4MzRcL2FwaVwvYXNcL3RyYW5zYWN0aW9uIiwiaWF0IjoxNTcyNjQyNjEzLCJ 4004 qdGkiOiJIam9IcmpnbTJ5QjR4N2pBNXl5RyJ9.aUhftvfw2NoW3M7durkopReTvONng1 4005 fOzbWjAlKNSLL0qIwDgfG39XUyNvwQ23OBIwe6IuvTQ2UBBPklPAfJhDTKd8KHEAfidN 4006 B-LzUOzhDetLg30yLFzIpcEBMLCjb0TEsmXadvxuNkEzFRL-Q-QCg0AXSF1h57eAqZV8 4007 SYF4CQK9OUV6fIWwxLDd3cVTx83MgyCNnvFlG_HDyim1Xx-rxV4ePd1vgDeRubFb6QWj 4008 iKEO7vj1APv32dsux67gZYiUpjm0wEZprjlG0a07R984KLeK1XPjXgViEwEdlirUmpVy 4009 T9tyEYqGrTfm5uautELgMls9sgSyE929woZ59elg 4011 { 4012 "resources": [ 4013 "dolphin-metadata" 4014 ], 4015 "interact": { 4016 "redirect": true, 4017 "callback": { 4018 "method": "redirect", 4019 "uri": "https://client.foo", 4020 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4021 } 4022 }, 4023 "client": { 4024 "display": { 4025 "name": "My Client Display Name", 4026 "uri": "https://example.net/client" 4028 }, 4029 "proof": "dpop", 4030 "key": { 4031 "jwk": { 4032 "kty": "RSA", 4033 "e": "AQAB", 4034 "kid": "xyz-1", 4035 "alg": "RS256", 4036 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xYJ 4037 CCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPFvpkTM 4038 8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCH 4039 e5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2 4040 B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6Y 4041 1cK2U3obvUg7w" 4042 } 4043 } 4044 } 4045 } 4047 [[ Editor's note: this method requires duplication of the key in the 4048 header and the request body, which is redundant and potentially 4049 awkward. The signature also doesn't protect the body of the request. 4050 ]] 4052 8.5. HTTP Signing 4054 This method is indicated by "httpsig" in the "proof" field. The RC 4055 creates an HTTP Signature header as described in 4056 [I-D.ietf-httpbis-message-signatures] section 4. The RC MUST 4057 calculate and present the Digest header as defined in [RFC3230] and 4058 include this header in the signature. 4060 POST /tx HTTP/1.1 4061 Host: server.example.com 4062 Content-Type: application/json 4063 Content-Length: 716 4064 Signature: keyId="xyz-client", algorithm="rsa-sha256", 4065 headers="(request-target) digest content-length", 4066 signature="TkehmgK7GD/z4jGkmcHS67cjVRgm3zVQNlNrrXW32Wv7d 4067 u0VNEIVI/dMhe0WlHC93NP3ms91i2WOW5r5B6qow6TNx/82/6W84p5jqF 4068 YuYfTkKYZ69GbfqXkYV9gaT++dl5kvZQjVk+KZT1dzpAzv8hdk9nO87Xi 4069 rj7qe2mdAGE1LLc3YvXwNxuCQh82sa5rXHqtNT1077fiDvSVYeced0UEm 4070 rWwErVgr7sijtbTohC4FJLuJ0nG/KJUcIG/FTchW9rd6dHoBnY43+3Dzj 4071 CIthXpdH5u4VX3TBe6GJDO6Mkzc6vB+67OWzPwhYTplUiFFV6UZCsDEeu 4072 Sa/Ue1yLEAMg=="]} 4073 Digest: SHA=oZz2O3kg5SEFAhmr0xEBbc4jEfo= 4075 { 4076 "resources": [ 4077 "dolphin-metadata" 4078 ], 4079 "interact": { 4080 "redirect": true, 4081 "callback": { 4082 "method": "push", 4083 "uri": "https://client.foo", 4084 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4085 } 4086 }, 4087 "client": { 4088 "display": { 4089 "name": "My Client Display Name", 4090 "uri": "https://example.net/client" 4091 }, 4092 "proof": "httpsig", 4093 "key": { 4094 "jwk": { 4095 "kty": "RSA", 4096 "e": "AQAB", 4097 "kid": "xyz-1", 4098 "alg": "RS256", 4099 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 4100 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 4101 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 4102 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 4103 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 4104 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 4105 Y1cK2U3obvUg7w" 4106 } 4107 } 4108 } 4109 } 4111 When used to present an access token as in Section 7, the 4112 Authorization header MUST be included in the signature. 4114 8.6. OAuth Proof of Possession (PoP) 4116 This method is indicated by "oauthpop" in the "proof" field. The RC 4117 creates an HTTP Authorization PoP header as described in 4118 [I-D.ietf-oauth-signed-http-request] section 4, with the following 4119 additional requirements: 4121 * The at (access token) field MUST be omitted unless this method is 4122 being used in conjunction with an access token as in Section 7. 4123 [[ Editor's note: this is in contradiction to the referenced spec 4124 which makes this field mandatory. ]] 4126 * The b (body hash) field MUST be calculated and supplied, unless 4127 there is no entity body (such as a GET, OPTIONS, or DELETE 4128 request). 4130 * All components of the URL MUST be calculated and supplied 4132 * The m (method) field MUST be supplied 4134 POST /tx HTTP/1.1 4135 Host: server.example.com 4136 Content-Type: application/json 4137 PoP: eyJhbGciOiJSUzI1NiIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi 4138 QVFBQiIsImtpZCI6Inh5ei1jbGllbnQiLCJhbGciOiJSUzI1NiIsIm4iO 4139 iJ6d0NUXzNieC1nbGJiSHJoZVlwWXBSV2lZOUktbkVhTVJwWm5ScklqQ3 4140 M2Yl9lbXlUa0JrRERFalN5c2kzOE9DNzNoajEtV2d4Y1BkS05HWnlJb0g 4141 zUVplbjFNS3l5aFFwTEpHMS1vTE5McW03cFhYdGRZelNkQzlPMy1vaXl5 4142 OHlrTzRZVXlOWnJSUmZQY2loZFFDYk9fT0M4UXVnbWc5cmdORE9TcXBwZ 4143 GFOZWFzMW92OVB4WXZ4cXJ6MS04SGE3Z2tEMDBZRUNYSGFCMDV1TWFVYW 4144 RIcS1PX1dJdllYaWNnNkk1ajZTNDRWTlU2NVZCd3UtQWx5blR4UWRNQVd 4145 QM2JZeFZWeTZwMy03ZVRKb2t2allURnFnRFZEWjhsVVhicjV5Q1RuUmhu 4146 aEpndmYzVmpEX21hbE5lOC10T3FLNU9TRGxIVHk2Z0Q5TnFkR0NtLVBtM 4147 1EifX0.eyJwIjoiXC9hcGlcL2FzXC90cmFuc2FjdGlvbiIsImIiOiJxa0 4148 lPYkdOeERhZVBTZnc3NnFjamtqSXNFRmxDb3g5bTU5NFM0M0RkU0xBIiw 4149 idSI6Imhvc3QuZG9ja2VyLmludGVybmFsIiwiaCI6W1siQWNjZXB0Iiwi 4150 Q29udGVudC1UeXBlIiwiQ29udGVudC1MZW5ndGgiXSwiVjQ2OUhFWGx6S 4151 k9kQTZmQU5oMmpKdFhTd3pjSGRqMUloOGk5M0h3bEVHYyJdLCJtIjoiUE 4152 9TVCIsInRzIjoxNTcyNjQyNjEwfQ.xyQ47qy8bu4fyK1T3Ru1Sway8wp6 4153 5rfAKnTQQU92AUUU07I2iKoBL2tipBcNCC5zLH5j_WUyjlN15oi_lLHym 4154 fPdzihtt8_Jibjfjib5J15UlifakjQ0rHX04tPal9PvcjwnyZHFcKn-So 4155 Y3wsARn-gGwxpzbsPhiKQP70d2eG0CYQMA6rTLslT7GgdQheelhVFW29i 4156 27NcvqtkJmiAG6Swrq4uUgCY3zRotROkJ13qo86t2DXklV-eES4-2dCxf 4157 cWFkzBAr6oC4Qp7HnY_5UT6IWkRJt3efwYprWcYouOVjtRan3kEtWkaWr 4158 G0J4bPVnTI5St9hJYvvh7FE8JirIg 4160 { 4161 "resources": [ 4162 "dolphin-metadata" 4163 ], 4164 "interact": { 4165 "redirect": true, 4166 "callback": { 4167 "method": "redirect", 4168 "uri": "https://client.foo", 4169 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4170 } 4171 }, 4172 "client": { 4173 "display": { 4174 "name": "My Client Display Name", 4175 "uri": "https://example.net/client" 4176 }, 4177 "proof": "oauthpop", 4178 "key": { 4179 "jwk": { 4180 "kty": "RSA", 4181 "e": "AQAB", 4182 "kid": "xyz-1", 4183 "alg": "RS256", 4184 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 4185 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 4186 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 4187 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 4188 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 4189 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 4190 Y1cK2U3obvUg7w" 4191 } 4192 } 4193 } 4194 } 4196 [[ Editor's note: This is a stale draft from the OAuth working group, 4197 but it does at least provide some basic functionality for protecting 4198 HTTP messages with a signature. This work is likely to be subsumed 4199 by the general-purpose HTTP message signature mechanism in 4200 Section 8.5. ]] 4202 9. Discovery 4204 By design, the protocol minimizes the need for any pre-flight 4205 discovery. To begin a request, the RC only needs to know the 4206 endpoint of the AS and which keys it will use to sign the request. 4207 Everything else can be negotiated dynamically in the course of the 4208 protocol. 4210 However, the AS can have limits on its allowed functionality. If the 4211 RC wants to optimize its calls to the AS before making a request, it 4212 MAY send an HTTP OPTIONS request to the grant request endpoint to 4213 retrieve the server's discovery information. The AS MUST respond 4214 with a JSON document containing the following information: 4216 grant_request_endpoint REQUIRED. The full URL of the AS's grant 4217 request endpoint. This MUST match the URL the RC used to make the 4218 discovery request. 4220 capabilities OPTIONAL. A list of the AS's capabilities. The values 4221 of this result MAY be used by the RC in the capabilities section 4222 (Section 2.6) of the request. 4224 interaction_methods OPTIONAL. A list of the AS's interaction 4225 methods. The values of this list correspond to the possible 4226 fields in the interaction section (Section 2.5) of the request. 4228 key_proofs OPTIONAL. A list of the AS's supported key proofing 4229 mechanisms. The values of this list correspond to possible values 4230 of the "proof" field of the key section (Section 2.3.2) of the 4231 request. 4233 sub_ids OPTIONAL. A list of the AS's supported identifiers. The 4234 values of this list correspond to possible values of the subject 4235 identifier section (Section 2.2) of the request. 4237 assertions OPTIONAL. A list of the AS's supported assertion 4238 formats. The values of this list correspond to possible values of 4239 the subject assertion section (Section 2.2) of the request. 4241 The information returned from this method is for optimization 4242 purposes only. The AS MAY deny any request, or any portion of a 4243 request, even if it lists a capability as supported. For example, a 4244 given RC can be registered with the "mtls" key proofing mechanism, 4245 but the AS also returns other proofing methods, then the AS will deny 4246 a request from that RC using a different proofing mechanism. 4248 10. Resource Servers 4250 In some deployments, a resource server will need to be able to call 4251 the AS for a number of functions. 4253 [[ Editor's note: This section is for discussion of possible advanced 4254 functionality. It seems like it should be a separate document or set 4255 of documents, and it's not even close to being well-baked. This also 4256 adds additional endpoints to the AS, as this is separate from the 4257 token request process, and therefore would require RS-facing 4258 discovery or configuration information to make it work. Also-also, 4259 it does presume the RS can sign requests in the same way that a 4260 client does, but hopefully we can be more consistent with this than 4261 RFC7662 was able to do. ]] 4263 10.1. Introspecting a Token 4265 When the RS receives an access token, it can call the introspection 4266 endpoint at the AS to get token information. [[ Editor's note: this 4267 isn't super different from the token management URIs, but the RS has 4268 no way to get that URI, and it's bound to the RS's keys instead of 4269 the RC's or token's keys. ]] 4271 +------+ +------+ +------+ 4272 | RC |--(1)->| RS | | AS | 4273 | | | |--(2)->| | 4274 | | | |<-(3)--| | 4275 | | | | +------+ 4276 | |<-(4)--| | 4277 +------+ +------+ 4279 1. The RC calls the RS with its access token. 4281 2. The RS introspects the access token value at the AS. The RS 4282 signs the request with its own key (not the RC's key or the 4283 token's key). 4285 3. The AS validates the token value and the RC's request and returns 4286 the introspection response for the token. 4288 4. The RS fulfills the request from the RC. 4290 The RS signs the request with its own key and sends the access token 4291 as the body of the request. 4293 POST /introspect HTTP/1.1 4294 Host: server.example.com 4295 Content-type: application/json 4296 Detached-JWS: ejy0... 4298 { 4299 "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4300 } 4302 The AS responds with a data structure describing the token's current 4303 state and any information the RS would need to validate the token's 4304 presentation, such as its intended proofing mechanism and key 4305 material. 4307 Content-type: application/json 4309 { 4310 "active": true, 4311 "resources": [ 4312 "dolphin-metadata", "some other thing" 4313 ], 4314 "client": { 4315 "key": { 4316 "proof": "httpsig", 4317 "jwk": { 4318 "kty": "RSA", 4319 "e": "AQAB", 4320 "kid": "xyz-1", 4321 "alg": "RS256", 4322 "n": "kOB5rR4Jv0GMeL...." 4323 } 4324 } 4325 } 4326 } 4328 10.2. Deriving a downstream token 4330 Some architectures require an RS to act as an RC and request a 4331 derived access token for a secondary RS. This internal token is 4332 issued in the context of the incoming access token. 4334 +------+ +-------+ +------+ +-------+ 4335 | RC |--(1)->| RS1 | | AS | | RS2 | 4336 | | | |--(2)->| | | | 4337 | | | |<-(3)--| | | | 4338 | | | | +------+ | | 4339 | | | | | | 4340 | | | |-----------(4)------->| | 4341 | | | |<----------(5)--------| | 4342 | |<-(6)--| | | | 4343 +------+ +-------+ +-------+ 4345 1. The RC calls RS1 with an access token. 4347 2. RS1 presents that token to the AS to get a derived token for use 4348 at RS2. RS1 indicates that it has no ability to interact with 4349 the RO. RS1 signs its request with its own key, not the token's 4350 key or the RC's key. 4352 3. The AS returns a derived token to RS1 for use at RS2. 4354 4. RS1 calls RS2 with the token from (3). 4356 5. RS2 fulfills the call from RS1. 4358 6. RS1 fulfills the call from RC. 4360 If the RS needs to derive a token from one presented to it, it can 4361 request one from the AS by making a token request as described in 4362 Section 2 and presenting the existing access token's value in the 4363 "existing_access_token" field. 4365 The RS MUST identify itself with its own key and sign the request. 4367 [[ Editor's note: this is similar to Section 2.7 but based on the 4368 access token and not the grant. We might be able to re-use that 4369 function: the fact that the keys presented are not the ones used for 4370 the access token should indicate that it's a different party and a 4371 different kind of request, but there might be some subtle security 4372 issues there. ]] 4374 POST /tx HTTP/1.1 4375 Host: server.example.com 4376 Content-type: application/json 4377 Detached-JWS: ejy0... 4379 { 4380 "resources": [ 4381 { 4382 "actions": [ 4383 "read", 4384 "write", 4385 "dolphin" 4386 ], 4387 "locations": [ 4388 "https://server.example.net/", 4389 "https://resource.local/other" 4390 ], 4391 "datatypes": [ 4392 "metadata", 4393 "images" 4394 ] 4395 }, 4396 "dolphin-metadata" 4397 ], 4398 "client": "7C7C4AZ9KHRS6X63AJAO", 4399 "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 4400 } 4402 The AS responds with a token as described in Section 3. 4404 10.3. Registering a Resource Handle 4406 If the RS needs to, it can post a set of resources as described in 4407 Section 2.1.1 to the AS's resource registration endpoint. 4409 The RS MUST identify itself with its own key and sign the request. 4411 POST /resource HTTP/1.1 4412 Host: server.example.com 4413 Content-type: application/json 4414 Detached-JWS: ejy0... 4416 { 4417 "resources": [ 4418 { 4419 "actions": [ 4420 "read", 4421 "write", 4422 "dolphin" 4423 ], 4424 "locations": [ 4425 "https://server.example.net/", 4426 "https://resource.local/other" 4427 ], 4428 "datatypes": [ 4429 "metadata", 4430 "images" 4431 ] 4432 }, 4433 "dolphin-metadata" 4434 ], 4435 "client": "7C7C4AZ9KHRS6X63AJAO" 4437 } 4439 The AS responds with a handle appropriate to represent the resources 4440 list that the RS presented. 4442 Content-type: application/json 4444 { 4445 "resource_handle": "FWWIKYBQ6U56NL1" 4446 } 4448 The RS MAY make this handle available as part of a response 4449 (Section 10.4) or as documentation to developers. 4451 [[ Editor's note: It's not an exact match here because the 4452 "resource_handle" returned now represents a collection of objects 4453 instead of a single one. Perhaps we should let this return a list of 4454 strings instead? Or use a different syntax than the resource 4455 request? Also, this borrows heavily from UMA 2's "distributed 4456 authorization" model and, like UMA, might be better suited to an 4457 extension than the core protocol. ]] 4459 10.4. Requesting a Resources With Insufficient Access 4461 If the RC calls an RS without an access token, or with an invalid 4462 access token, the RS MAY respond to the RC with an authentication 4463 header indicating that GNAP needs to be used to access the resource. 4464 The address of the GNAP endpoint MUST be sent in the "as_uri" 4465 parameter. The RS MAY additionally return a resource reference that 4466 the RC MAY use in its resource request (Section 2.1). This resource 4467 reference handle SHOULD be sufficient for at least the action the RC 4468 was attempting to take at the RS. The RS MAY use the dynamic 4469 resource handle request (Section 10.3) to register a new resource 4470 handle, or use a handle that has been pre-configured to represent 4471 what the AS is protecting. The content of this handle is opaque to 4472 the RS and the RC. 4474 WWW-Authenticate: GNAP as_uri=http://server.example/tx,resource=FWWIKYBQ6U56NL1 4476 The RC then makes a call to the "as_uri" as described in Section 2, 4477 with the value of "resource" as one of the members of a "resources" 4478 array Section 2.1.1. The RC MAY request additional resources and 4479 other information, and MAY request multiple access tokens. 4481 [[ Editor's note: this borrows heavily from UMA 2's "distributed 4482 authorization" model and, like UMA, might be better suited to an 4483 extension than the core protocol. ]] 4485 11. Acknowledgements 4487 The author would like to thank the feedback of the following 4488 individuals for their reviews, implementations, and contributions: 4489 Aaron Parecki, Annabelle Backman, Dick Hardt, Dmitri Zagidulin, 4490 Dmitry Barinov, Fabien Imbault, Francis Pouatcha, George Fletcher, 4491 Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan, Kathleen 4492 Moriarty, Mike Jones, Mike Varley, Nat Sakimura, Takahiko Kawasaki, 4493 Takahiro Tsuchiya. 4495 In particular, the author would like to thank Aaron Parecki and Mike 4496 Jones for insights into how to integrate identity and authentication 4497 systems into the core protocol, and to Dick Hardt for the use cases, 4498 diagrams, and insights provided in the XAuth proposal that have been 4499 incorporated here. The author would like to especially thank Mike 4500 Varley and the team at SecureKey for feedback and development of 4501 early versions of the XYZ protocol that fed into this standards work. 4503 12. IANA Considerations 4505 [[ TBD: There are a lot of items in the document that are expandable 4506 through the use of value registries. ]] 4508 13. Security Considerations 4510 [[ TBD: There are a lot of security considerations to add. ]] 4512 All requests have to be over TLS or equivalent as per [BCP195]. Many 4513 handles act as shared secrets, though they can be combined with a 4514 requirement to provide proof of a key as well. 4516 14. Privacy Considerations 4518 [[ TBD: There are a lot of privacy considerations to add. ]] 4520 Handles are passed between parties and therefore should not contain 4521 any private data. 4523 When user information is passed to the RC, the AS needs to make sure 4524 that it has the permission to do so. 4526 15. Normative References 4528 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 4529 "Recommendations for Secure Use of Transport Layer 4530 Security (TLS) and Datagram Transport Layer Security 4531 (DTLS)", May 2015, 4532 . 4534 [I-D.ietf-httpbis-message-signatures] 4535 Backman, A., Richer, J., and M. Sporny, "Signing HTTP 4536 Messages", Work in Progress, Internet-Draft, draft-ietf- 4537 httpbis-message-signatures-00, 10 April 2020, 4538 . 4541 [I-D.ietf-oauth-dpop] 4542 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 4543 Jones, M., and D. Waite, "OAuth 2.0 Demonstration of 4544 Proof-of-Possession at the Application Layer (DPoP)", Work 4545 in Progress, Internet-Draft, draft-ietf-oauth-dpop-01, 1 4546 May 2020, . 4549 [I-D.ietf-oauth-signed-http-request] 4550 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 4551 Signing HTTP Requests for OAuth", Work in Progress, 4552 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 4553 August 2016, . 4556 [I-D.ietf-secevent-subject-identifiers] 4557 Backman, A. and M. Scurtescu, "Subject Identifiers for 4558 Security Event Tokens", Work in Progress, Internet-Draft, 4559 draft-ietf-secevent-subject-identifiers-06, 4 September 4560 2020, . 4563 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 4564 C. Mortimore, "OpenID Connect Core 1.0 incorporating 4565 errata set 1", November 2014, 4566 . 4568 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 4569 Assurance 1.0", October 2019, . 4572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4573 Requirement Levels", BCP 14, RFC 2119, 4574 DOI 10.17487/RFC2119, March 1997, 4575 . 4577 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 4578 RFC 3230, DOI 10.17487/RFC3230, January 2002, 4579 . 4581 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 4582 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 4583 September 2009, . 4585 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 4586 RFC 6749, DOI 10.17487/RFC6749, October 2012, 4587 . 4589 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 4590 Framework: Bearer Token Usage", RFC 6750, 4591 DOI 10.17487/RFC6750, October 2012, 4592 . 4594 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4595 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4596 2015, . 4598 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 4599 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 4600 . 4602 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4603 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4604 May 2017, . 4606 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4607 Interchange Format", STD 90, RFC 8259, 4608 DOI 10.17487/RFC8259, December 2017, 4609 . 4611 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 4612 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 4613 DOI 10.17487/RFC8693, January 2020, 4614 . 4616 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 4617 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 4618 and Certificate-Bound Access Tokens", RFC 8705, 4619 DOI 10.17487/RFC8705, February 2020, 4620 . 4622 Appendix A. Document History 4624 * -01 4626 - "updated_at" subject info timestamp now in ISO 8601 string 4627 format. 4629 - Editorial fixes. 4631 - Added Aaron and Fabien as document authors. 4633 * -00 4635 - Initial working group draft. 4637 Appendix B. Component Data Models 4639 While different implementations of this protocol will have different 4640 realizations of all the components and artifacts enumerated here, the 4641 nature of the protocol implies some common structures and elements 4642 for certain components. This appendix seeks to enumerate those 4643 common elements. 4645 TBD: Client has keys, allowed requested resources, identifier(s), 4646 allowed requested subjects, allowed 4648 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 4649 client keys, policies 4651 TBD: Token has RO, user, client, resource list, RS list, 4653 Appendix C. Example Protocol Flows 4655 The protocol defined in this specification provides a number of 4656 features that can be combined to solve many different kinds of 4657 authentication scenarios. This section seeks to show examples of how 4658 the protocol would be applied for different situations. 4660 Some longer fields, particularly cryptographic information, have been 4661 truncated for display purposes in these examples. 4663 C.1. Redirect-Based User Interaction 4665 In this scenario, the user is the RO and has access to a web browser, 4666 and the client can take front-channel callbacks on the same device as 4667 the user. This combination is analogous to the OAuth 2 Authorization 4668 Code grant type. 4670 The client initiates the request to the AS. Here the client 4671 identifies itself using its public key. 4673 POST /tx HTTP/1.1 4674 Host: server.example.com 4675 Content-type: application/json 4676 Detached-JWS: ejy0... 4678 { 4679 "resources": [ 4680 { 4681 "actions": [ 4682 "read", 4683 "write", 4684 "dolphin" 4685 ], 4686 "locations": [ 4687 "https://server.example.net/", 4688 "https://resource.local/other" 4689 ], 4690 "datatypes": [ 4691 "metadata", 4692 "images" 4693 ] 4694 } 4695 ], 4696 "client": { 4697 "key": { 4698 "proof": "jwsd", 4699 "jwk": { 4700 "kty": "RSA", 4701 "e": "AQAB", 4702 "kid": "xyz-1", 4703 "alg": "RS256", 4704 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 4705 } 4706 } 4707 }, 4708 "interact": { 4709 "redirect": true, 4710 "callback": { 4711 "method": "redirect", 4712 "uri": "https://client.example.net/return/123455", 4713 "nonce": "LKLTI25DK82FX4T4QFZC" 4714 } 4715 } 4716 } 4717 The AS processes the request and determines that the RO needs to 4718 interact. The AS returns the following response giving the client 4719 the information it needs to connect. The AS has also indicated to 4720 the client that it can use the given instance identifier to identify 4721 itself in future requests (Section 2.3.1). 4723 Content-type: application/json 4725 { 4726 "interact": { 4727 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 4728 "callback": "MBDOFXG4Y5CVJCX821LH" 4729 } 4730 "continue": { 4731 "access_token": { 4732 "value": "80UPRY5NM33OMUKMKSKU", 4733 "key": true 4734 }, 4735 "uri": "https://server.example.com/continue" 4736 }, 4737 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 4738 } 4740 The client saves the response and redirects the user to the 4741 interaction_url by sending the following HTTP message to the user's 4742 browser. 4744 HTTP 302 Found 4745 Location: https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ 4747 The user's browser fetches the AS's interaction URL. The user logs 4748 in, is identified as the RO for the resource being requested, and 4749 approves the request. Since the AS has a callback parameter, the AS 4750 generates the interaction reference, calculates the hash, and 4751 redirects the user back to the client with these additional values 4752 added as query parameters. 4754 HTTP 302 Found 4755 Location: https://client.example.net/return/123455 4756 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 4757 &interact_ref=4IFWWIKYBC2PQ6U56NL1 4758 The client receives this request from the user's browser. The client 4759 ensures that this is the same user that was sent out by validating 4760 session information and retrieves the stored pending request. The 4761 client uses the values in this to validate the hash parameter. The 4762 client then calls the continuation URL and presents the handle and 4763 interaction reference in the request body. The client signs the 4764 request as above. 4766 POST /continue HTTP/1.1 4767 Host: server.example.com 4768 Content-type: application/json 4769 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 4770 Detached-JWS: ejy0... 4772 { 4773 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 4774 } 4776 The AS retrieves the pending request based on the handle and issues a 4777 bearer access token and returns this to the client. 4779 Content-type: application/json 4781 { 4782 "access_token": { 4783 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4784 "key": false, 4785 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4786 "resources": [{ 4787 "actions": [ 4788 "read", 4789 "write", 4790 "dolphin" 4791 ], 4792 "locations": [ 4793 "https://server.example.net/", 4794 "https://resource.local/other" 4795 ], 4796 "datatypes": [ 4797 "metadata", 4798 "images" 4799 ] 4800 }] 4801 }, 4802 "continue": { 4803 "access_token": { 4804 "value": "80UPRY5NM33OMUKMKSKU", 4805 "key": true 4806 }, 4807 "uri": "https://server.example.com/continue" 4808 } 4809 } 4811 C.2. Secondary Device Interaction 4813 In this scenario, the user does not have access to a web browser on 4814 the device and must use a secondary device to interact with the AS. 4815 The client can display a user code or a printable QR code. The 4816 client prefers a short URL if one is available, with a maximum of 255 4817 characters in length. The is not able to accept callbacks from the 4818 AS and needs to poll for updates while waiting for the user to 4819 authorize the request. 4821 The client initiates the request to the AS. 4823 POST /tx HTTP/1.1 4824 Host: server.example.com 4825 Content-type: application/json 4826 Detached-JWS: ejy0... 4828 { 4829 "resources": [ 4830 "dolphin-metadata", "some other thing" 4831 ], 4832 "client": "7C7C4AZ9KHRS6X63AJAO", 4833 "interact": { 4834 "redirect": 255, 4835 "user_code": true 4836 } 4837 } 4839 The AS processes this and determines that the RO needs to interact. 4840 The AS supports both long and short redirect URIs for interaction, so 4841 it includes both. Since there is no "callback" the AS does not 4842 include a nonce, but does include a "wait" parameter on the 4843 continuation section because it expects the client to poll for 4844 results. 4846 Content-type: application/json 4848 { 4849 "interact": { 4850 "redirect": "https://srv.ex/MXKHQ", 4851 "user_code": { 4852 "code": "A1BC-3DFF", 4853 "url": "https://srv.ex/device" 4854 } 4855 }, 4856 "continue": { 4857 "uri": "https://server.example.com/continue/80UPRY5NM33OMUKMKSKU", 4858 "wait": 60 4859 } 4860 } 4862 The client saves the response and displays the user code visually on 4863 its screen along with the static device URL. The client also 4864 displays the short interaction URL as a QR code to be scanned. 4866 If the user scans the code, they are taken to the interaction 4867 endpoint and the AS looks up the current pending request based on the 4868 incoming URL. If the user instead goes to the static page and enters 4869 the code manually, the AS looks up the current pending request based 4870 on the value of the user code. In both cases, the user logs in, is 4871 identified as the RO for the resource being requested, and approves 4872 the request. Once the request has been approved, the AS displays to 4873 the user a message to return to their device. 4875 Meanwhile, the client periodically polls the AS every 60 seconds at 4876 the continuation URL. The client signs the request using the same 4877 key and method that it did in the first request. 4879 POST /continue/80UPRY5NM33OMUKMKSKU HTTP/1.1 4880 Host: server.example.com 4881 Detached-JWS: ejy0... 4883 The AS retrieves the pending request based on the handle and 4884 determines that it has not yet been authorized. The AS indicates to 4885 the client that no access token has yet been issued but it can 4886 continue to call after another 60 second timeout. 4888 Content-type: application/json 4890 { 4891 "continue": { 4892 "uri": "https://server.example.com/continue/BI9QNW6V9W3XFJK4R02D", 4893 "wait": 60 4894 } 4895 } 4897 Note that the continuation URL has been rotated since it was used by 4898 the client to make this call. The client polls the continuation URL 4899 after a 60 second timeout using the new handle. 4901 POST /continue/BI9QNW6V9W3XFJK4R02D HTTP/1.1 4902 Host: server.example.com 4903 Authorization: GNAP 4904 Detached-JWS: ejy0... 4906 The AS retrieves the pending request based on the URL, determines 4907 that it has been approved, and issues an access token. 4909 Content-type: application/json 4911 { 4912 "access_token": { 4913 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4914 "key": false, 4915 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4916 "resources": [ 4917 "dolphin-metadata", "some other thing" 4918 ] 4919 } 4920 } 4922 Appendix D. No User Involvement 4924 In this scenario, the client is requesting access on its own behalf, 4925 with no user to interact with. 4927 The client creates a request to the AS, identifying itself with its 4928 public key and using MTLS to make the request. 4930 POST /tx HTTP/1.1 4931 Host: server.example.com 4932 Content-type: application/json 4934 { 4935 "resources": [ 4936 "backend service", "nightly-routine-3" 4937 ], 4938 "client": { 4939 "key": { 4940 "proof": "mtls", 4941 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 4942 } 4943 } 4944 } 4946 The AS processes this and determines that the client can ask for the 4947 requested resources and issues an access token. 4949 Content-type: application/json 4951 { 4952 "access_token": { 4953 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4954 "key": true, 4955 "manage": "https://server.example.com/token", 4956 "resources": [ 4957 "backend service", "nightly-routine-3" 4958 ] 4959 } 4960 } 4962 D.1. Asynchronous Authorization 4964 In this scenario, the client is requesting on behalf of a specific 4965 RO, but has no way to interact with the user. The AS can 4966 asynchronously reach out to the RO for approval in this scenario. 4968 The client starts the request at the AS by requesting a set of 4969 resources. The client also identifies a particular user. 4971 POST /tx HTTP/1.1 4972 Host: server.example.com 4973 Content-type: application/json 4974 Detached-JWS: ejy0... 4976 { 4977 "resources": [ 4978 { 4979 "type": "photo-api", 4980 "actions": [ 4981 "read", 4982 "write", 4983 "dolphin" 4984 ], 4985 "locations": [ 4986 "https://server.example.net/", 4987 "https://resource.local/other" 4988 ], 4989 "datatypes": [ 4990 "metadata", 4991 "images" 4992 ] 4993 }, 4994 "read", "dolphin-metadata", 4995 { 4996 "type": "financial-transaction", 4997 "actions": [ 4998 "withdraw" 4999 ], 5000 "identifier": "account-14-32-32-3", 5001 "currency": "USD" 5002 }, 5003 "some other thing" 5004 ], 5005 "client": "7C7C4AZ9KHRS6X63AJAO", 5006 "user": { 5007 "sub_ids": [ { 5008 "subject_type": "email", 5009 "email": "user@example.com" 5010 } ] 5011 } 5012 } 5014 The AS processes this and determines that the RO needs to interact. 5015 The AS determines that it can reach the identified user 5016 asynchronously and that the identified user does have the ability to 5017 approve this request. The AS indicates to the client that it can 5018 poll for continuation. 5020 Content-type: application/json 5022 { 5023 "continue": { 5024 "access_token": { 5025 "value": "80UPRY5NM33OMUKMKSKU", 5026 "key": true 5027 }, 5028 "uri": "https://server.example.com/continue", 5029 "wait": 60 5030 } 5031 } 5033 The AS reaches out to the RO and prompts them for consent. In this 5034 example, the AS has an application that it can push notifications in 5035 to for the specified account. 5037 Meanwhile, the client periodically polls the AS every 60 seconds at 5038 the continuation URL. 5040 POST /continue HTTP/1.1 5041 Host: server.example.com 5042 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5043 Detached-JWS: ejy0... 5045 The AS retrieves the pending request based on the handle and 5046 determines that it has not yet been authorized. The AS indicates to 5047 the client that no access token has yet been issued but it can 5048 continue to call after another 60 second timeout. 5050 Content-type: application/json 5052 { 5053 "continue": { 5054 "access_token": { 5055 "value": "BI9QNW6V9W3XFJK4R02D", 5056 "key": true 5057 }, 5058 "uri": "https://server.example.com/continue", 5059 "wait": 60 5060 } 5061 } 5063 Note that the continuation handle has been rotated since it was used 5064 by the client to make this call. The client polls the continuation 5065 URL after a 60 second timeout using the new handle. 5067 POST /continue HTTP/1.1 5068 Host: server.example.com 5069 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 5070 Detached-JWS: ejy0... 5072 The AS retrieves the pending request based on the handle and 5073 determines that it has been approved and it issues an access token. 5075 Content-type: application/json 5077 { 5078 "access_token": { 5079 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5080 "key": false, 5081 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 5082 "resources": [ 5083 "dolphin-metadata", "some other thing" 5084 ] 5085 } 5086 } 5088 D.2. Applying OAuth 2 Scopes and Client IDs 5090 While the GNAP protocol is not designed to be directly compatible 5091 with OAuth 2 [RFC6749], considerations have been made to enable the 5092 use of OAuth 2 concepts and constructs more smoothly within the GNAP 5093 protocol. 5095 In this scenario, the client developer has a "client_id" and set of 5096 "scope" values from their OAuth 2 system and wants to apply them to 5097 the new protocol. Traditionally, the OAuth 2 client developer would 5098 put their "client_id" and "scope" values as parameters into a 5099 redirect request to the authorization endpoint. 5101 HTTP 302 Found 5102 Location: https://server.example.com/authorize 5103 ?client_id=7C7C4AZ9KHRS6X63AJAO 5104 &scope=read%20write%20dolphin 5105 &redirect_uri=https://client.example.net/return 5106 &response_type=code 5107 &state=123455 5109 Now the developer wants to make an analogous request to the AS using 5110 the new protocol. To do so, the client makes an HTTP POST and places 5111 the OAuth 2 values in the appropriate places. 5113 POST /tx HTTP/1.1 5114 Host: server.example.com 5115 Content-type: application/json 5116 Detached-JWS: ejy0... 5118 { 5119 "resources": [ 5120 "read", "write", "dolphin" 5121 ], 5122 "client": "7C7C4AZ9KHRS6X63AJAO", 5123 "interact": { 5124 "redirect": true, 5125 "callback": { 5126 "method": "redirect", 5127 "uri": "https://client.example.net/return?state=123455", 5128 "nonce": "LKLTI25DK82FX4T4QFZC" 5129 } 5130 } 5131 } 5133 The client_id can be used to identify the client's keys that it uses 5134 for authentication, the scopes represent resources that the client is 5135 requesting, and the "redirect_uri" and "state" value are pre-combined 5136 into a "callback" URI that can be unique per request. The client 5137 additionally creates a nonce to protect the callback, separate from 5138 the state parameter that it has added to its return URL. 5140 From here, the protocol continues as above. 5142 Appendix E. JSON Structures and Polymorphism 5144 The GNAP protocol makes use of polymorphism within the JSON [RFC8259] 5145 structures used for the protocol. Each portion of this protocol is 5146 defined in terms of the JSON data type that its values can take, 5147 whether it's a string, object, array, boolean, or number. For some 5148 fields, different data types offer different descriptive capabilities 5149 and are used in different situations for the same field. Each data 5150 type provides a different syntax to express the same underlying 5151 semantic protocol element, which allows for optimization and 5152 simplification in many common cases. 5154 Even though JSON is often used to describe strongly typed structures, 5155 JSON on its own is naturally polymorphic. In JSON, the named members 5156 of an object have no type associated with them, and any data type can 5157 be used as the value for any member. In practice, each member has a 5158 semantic type that needs to make sense to the parties creating and 5159 consuming the object. Within this protocol, each object member is 5160 defined in terms of its semantic content, and this semantic content 5161 might have expressions in different concrete data types for different 5162 specific purposes. Since each object member has exactly one value in 5163 JSON, each data type for an object member field is naturally mutually 5164 exclusive with other data types within a single JSON object. 5166 For example, a resource request for a single access token is composed 5167 of an array of resource request descriptions while a request for 5168 multiple access tokens is composed of an object whose member values 5169 are all arrays. Both of these represent requests for access, but the 5170 difference in syntax allows the RC and AS to differentiate between 5171 the two request types in the same request. 5173 Another form of polymorphism in JSON comes from the fact that the 5174 values within JSON arrays need not all be of the same JSON data type. 5175 However, within this protocol, each element within the array needs to 5176 be of the same kind of semantic element for the collection to make 5177 sense, even when the data types are different from each other. 5179 For example, each aspect of a resource request can be described using 5180 an object with multiple dimensional components, or the aspect can be 5181 requested using a string. In both cases, the resource request is 5182 being described in a way that the AS needs to interpret, but with 5183 different levels of specificity and complexity for the RC to deal 5184 with. An API designer can provide a set of common access scopes as 5185 simple strings but still allow RC developers to specify custom access 5186 when needed for more complex APIs. 5188 Extensions to this specification can use different data types for 5189 defined fields, but each extension needs to not only declare what the 5190 data type means, but also provide justification for the data type 5191 representing the same basic kind of thing it extends. For example, 5192 an extension declaring an "array" representation for a field would 5193 need to explain how the array represents something akin to the non- 5194 array element that it is replacing. 5196 Authors' Addresses 5198 Justin Richer (editor) 5199 Bespoke Engineering 5201 Email: ietf@justin.richer.org 5202 URI: https://bspk.io/ 5204 Aaron Parecki 5205 Okta 5207 Email: aaron@parecki.com 5208 URI: https://aaronparecki.com 5210 Fabien Imbault 5211 acert.io 5213 Email: fabien.imbault@acert.io 5214 URI: https://acert.io/