idnits 2.17.1 draft-ietf-gnap-core-protocol-03.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 79 instances of too long lines in the document, the longest one being 27 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 (6 January 2021) is 1199 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 4282, 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-01 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-02 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-06 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' ** 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: 10 July 2021 Okta 6 F. Imbault 7 acert.io 8 6 January 2021 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-03 13 Abstract 15 GNAP defines a mechanism for delegating authorization to a piece of 16 software, and conveying that delegation to the software. This 17 delegation can include access to a set of APIs as well as information 18 passed directly to the software. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on 10 July 2021. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 7 58 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 10 59 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 12 60 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 15 61 1.4.4. Software-only Authorization . . . . . . . . . . . . . 16 62 1.4.5. Refreshing an Expired Access Token . . . . . . . . . 17 63 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 18 64 2.1. Requesting Resources . . . . . . . . . . . . . . . . . . 20 65 2.1.1. Requesting a Single Access Token . . . . . . . . . . 20 66 2.1.2. Requesting Resources By Reference . . . . . . . . . . 24 67 2.1.3. Requesting Multiple Access Tokens . . . . . . . . . . 26 68 2.1.4. Signaling Token Behavior . . . . . . . . . . . . . . 28 69 2.2. Requesting User Information . . . . . . . . . . . . . . . 29 70 2.3. Identifying the Client Instance . . . . . . . . . . . . . 30 71 2.3.1. Identifying the Client Instance . . . . . . . . . . . 32 72 2.3.2. Identifying the Client Instance Key . . . . . . . . . 33 73 2.3.3. Providing Displayable Client Instance Information . . 34 74 2.3.4. Authenticating the Client Instance . . . . . . . . . 34 75 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 35 76 2.4.1. Identifying the User by Reference . . . . . . . . . . 36 77 2.5. Interacting with the User . . . . . . . . . . . . . . . . 36 78 2.5.1. Redirect to an Arbitrary URL . . . . . . . . . . . . 38 79 2.5.2. Open an Application-specific URL . . . . . . . . . . 38 80 2.5.3. Receive a Callback After Interaction . . . . . . . . 39 81 2.5.4. Display a Short User Code . . . . . . . . . . . . . . 41 82 2.5.5. Indicate Desired Interaction Locales . . . . . . . . 41 83 2.5.6. Extending Interaction Modes . . . . . . . . . . . . . 41 84 2.6. Declaring Client Capabilities . . . . . . . . . . . . . . 42 85 2.7. Referencing an Existing Grant Request . . . . . . . . . . 42 86 2.8. Extending The Grant Request . . . . . . . . . . . . . . . 42 87 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 42 88 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 44 89 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 45 90 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 45 91 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 48 92 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 49 93 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 49 94 3.3.2. Launch of an application URL . . . . . . . . . . . . 50 95 3.3.3. Post-interaction Callback to a Client Instance 96 Accessible URL . . . . . . . . . . . . . . . . . . . 50 97 3.3.4. Display of a Short User Code . . . . . . . . . . . . 51 98 3.3.5. Extending Interaction Mode Responses . . . . . . . . 52 99 3.4. Returning User Information . . . . . . . . . . . . . . . 52 100 3.5. Returning Dynamically-bound Reference Handles . . . . . . 53 101 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 55 102 3.7. Extending the Response . . . . . . . . . . . . . . . . . 55 103 4. Interaction at the AS . . . . . . . . . . . . . . . . . . . . 55 104 4.1. Interaction at a Redirected URI . . . . . . . . . . . . . 56 105 4.2. Interaction at the User Code URI . . . . . . . . . . . . 56 106 4.3. Interaction through an Application URI . . . . . . . . . 57 107 4.4. Post-Interaction Completion . . . . . . . . . . . . . . . 57 108 4.4.1. Completing Interaction with a Browser Redirect to the 109 Callback URI . . . . . . . . . . . . . . . . . . . . 57 110 4.4.2. Completing Interaction with a Direct HTTP Request 111 Callback . . . . . . . . . . . . . . . . . . . . . . 58 112 4.4.3. Calculating the interaction hash . . . . . . . . . . 59 113 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 60 114 5.1. Continuing After a Completed Interaction . . . . . . . . 62 115 5.2. Continuing During Pending Interaction . . . . . . . . . . 63 116 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 64 117 5.4. Getting the Current State of a Grant Request . . . . . . 69 118 5.5. Canceling a Grant Request . . . . . . . . . . . . . . . . 70 119 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 70 120 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 71 121 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 72 122 7. Using Access Tokens . . . . . . . . . . . . . . . . . . . . . 73 123 8. Binding Keys . . . . . . . . . . . . . . . . . . . . . . . . 74 124 8.1. Detached JWS . . . . . . . . . . . . . . . . . . . . . . 75 125 8.2. Attached JWS . . . . . . . . . . . . . . . . . . . . . . 77 126 8.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . . . 81 127 8.4. Demonstration of Proof-of-Possession (DPoP) . . . . . . . 83 128 8.5. HTTP Signing . . . . . . . . . . . . . . . . . . . . . . 84 129 8.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . . . 85 130 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 87 131 10. Resource Servers . . . . . . . . . . . . . . . . . . . . . . 88 132 10.1. Introspecting a Token . . . . . . . . . . . . . . . . . 88 133 10.2. Deriving a downstream token . . . . . . . . . . . . . . 90 134 10.3. Registering a Resource Handle . . . . . . . . . . . . . 91 135 10.4. Requesting Resources With Insufficient Access . . . . . 93 136 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 93 137 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 94 138 13. Security Considerations . . . . . . . . . . . . . . . . . . . 94 139 14. Privacy Considerations . . . . . . . . . . . . . . . . . . . 94 140 15. Normative References . . . . . . . . . . . . . . . . . . . . 94 141 Appendix A. Document History . . . . . . . . . . . . . . . . . . 96 142 Appendix B. Component Data Models . . . . . . . . . . . . . . . 97 143 Appendix C. Example Protocol Flows . . . . . . . . . . . . . . . 97 144 C.1. Redirect-Based User Interaction . . . . . . . . . . . . . 97 145 C.2. Secondary Device Interaction . . . . . . . . . . . . . . 101 146 Appendix D. No User Involvement . . . . . . . . . . . . . . . . 104 147 D.1. Asynchronous Authorization . . . . . . . . . . . . . . . 105 148 D.2. Applying OAuth 2 Scopes and Client IDs . . . . . . . . . 108 149 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 109 150 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 110 152 1. Introduction 154 This protocol allows a piece of software, the client instance, to 155 request delegated authorization to resource servers and to request 156 direct information. This delegation is facilitated by an 157 authorization server usually on behalf of a resource owner. The 158 requesting party operating the software may interact with the 159 authorization server to authenticate, provide consent, and authorize 160 the request. 162 The process by which the delegation happens is known as a grant, and 163 GNAP allows for the negotiation of the grant process over time by 164 multiple parties acting in distinct roles. 166 This protocol solves many of the same use cases as OAuth 2.0 167 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 168 have grown up around that ecosystem. However, GNAP is not an 169 extension of OAuth 2.0 and is not intended to be directly compatible 170 with OAuth 2.0. GNAP seeks to provide functionality and solve use 171 cases that OAuth 2.0 cannot easily or cleanly address. Even so, GNAP 172 and OAuth 2.0 will exist in parallel for many deployments, and 173 considerations have been taken to facilitate the mapping and 174 transition from legacy systems to GNAP. Some examples of these can 175 be found in Appendix D.2. 177 1.1. Terminology 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 181 "OPTIONAL" in this document are to be interpreted as described in 182 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 183 capitals, as shown here. 185 1.2. Roles 187 The parties in GNAP perform actions under different roles. Roles are 188 defined by the actions taken and the expectations leveraged on the 189 role by the overall protocol. 191 Authorization Server (AS) Manages the requested delegations for the 192 RO. The AS issues tokens and directly delegated information to an 193 instance of the client. The AS is defined by its grant endpoint, 194 a single URL that accepts a POST request with a JSON payload. The 195 AS could also have other endpoints, including interaction 196 endpoints and user code endpoints, and these are introduced to the 197 RC as needed during the delegation process. 199 Client Requests tokens and directly delegated information from the 200 AS, and uses tokens at the RS. For some kinds of client software, 201 there could be many instances of a single piece of client 202 software. This specification differentiates between a specific 203 instance (the client instance) and the software running the 204 instance (the client software). A client instance is identified 205 by its unique key, which can be known to the AS prior to the first 206 request or introduced to the AS as part of the protocol. The AS 207 determines which policies apply to a given client instance, 208 including what it can request and on whose behalf. 210 Resource Server (RS, aka "API") Accepts tokens from the client 211 instance issued by the AS and serves delegated resources on behalf 212 of the RO. There could be multiple RSs protected by the AS that 213 the client instance will call. 215 Resource Owner (RO) Authorizes the request from the client instance 216 to the RS, often interactively at the AS. 218 Requesting Party (RQ, aka "user") Operates and interacts with the 219 client instance. 221 The design of GNAP does not assume any one deployment architecture, 222 but instead attempts to define roles that can be fulfilled in a 223 number of different ways for different use cases. As long as a given 224 role fulfills all of its obligations and behaviors as defined by the 225 protocol, GNAP does not make additional requirements on its structure 226 or setup. 228 Multiple roles can be fulfilled by the same party, and a given party 229 can switch roles in different instances of the protocol. For 230 example, the RO and RQ in many instances are the same person, where a 231 user is authorizing the client instance to act on their own behalf at 232 the RS. In this case, one party fulfills both of the RO and RQ 233 roles, but the roles themselves are still defined separately from 234 each other to allow for other use cases where they are fulfilled by 235 different parties. 237 For another example, in some complex scenarios, an RS receiving 238 requests from one client instance can act as a client instance for a 239 downstream secondary RS in order to fulfill the original request. In 240 this case, one piece of software is both an RS and a client instance 241 from different perspectives, and it fulfills these roles separately 242 as far as the overall protocol is concerned. 244 A single role need not be deployed as a monolithic service. For 245 example, A client instance could have components that are installed 246 on the RQ's device as well as a back-end system that it communicates 247 with. If both of these components participate in the delegation 248 protocol, they are both considered part of the client instance. If 249 there are several copies of the client software that run separately 250 but all share the same key material, such as a deployed cluster, then 251 this cluster is considered a single client instance. 253 For another example, an AS could likewise be built out of many 254 constituent components in a distributed architecture. The component 255 that the client instance calls directly could be different from the 256 component that the the RO interacts with to drive consent, since API 257 calls and user interaction have different security considerations in 258 many environments. Furthermore, the AS could need to collect 259 identity claims about the RO from one system that deals with user 260 attributes while generating access tokens at another system that 261 deals with security rights. From the perspective of GNAP, all of 262 these are pieces of the AS and together fulfill the role of the AS as 263 defined by the protocol. 265 [[ See issue #29 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 266 issues/29) ]] 268 1.3. Elements 270 In addition to the roles above, the protocol also involves several 271 elements that are acted upon by the roles throughout the process. 273 Access Token A credential representing a set of access rights 274 delegated to the client instance. The access token is created by 275 the AS, consumed and verified by the RS, and issued to and carried 276 by the client instance. The contents and format of the access 277 token are opaque to the client. 279 Grant The process by which the client instance requests and is given 280 delegated access to the RS by the AS through the authority of the 281 RO. 283 Cryptographic Key A cryptographic element binding a request to a 284 holder of the key. Access tokens and client instances can be 285 associated with specific keys. 287 Resource A protected API served by the RS and accessed by the client 288 instance. Access to this resource is delegated by the RO as part 289 of the grant process. 291 Subject Information Information about the RO that is returned 292 directly to the client instance from the AS without the client 293 instance making a separate call to an RS. Access to this 294 information is delegated by the RO as part of the grant process. 296 1.4. Sequences 298 GNAP can be used in a variety of ways to allow the core delegation 299 process to take place. Many portions of this process are 300 conditionally present depending on the context of the deployments, 301 and not every step in this overview will happen in all circumstances. 303 Note that a connection between roles in this process does not 304 necessarily indicate that a specific protocol message is sent across 305 the wire between the components fulfilling the roles in question, or 306 that a particular step is required every time. For example, for a 307 client instance interested in only getting subject information 308 directly, and not calling an RS, all steps involving the RS below do 309 not apply. 311 In some circumstances, the information needed at a given stage is 312 communicated out of band or is preconfigured between the components 313 or entities performing the roles. For example, one entity can fulfil 314 multiple roles, and so explicit communication between the roles is 315 not necessary within the protocol flow. 317 +------------+ +------------+ 318 | Requesting | ~ ~ ~ ~ ~ ~ | Resource | 319 | Party (RQ) | | Owner (RO) | 320 +------------+ +------------+ 321 + + 322 + + 323 (A) (B) 324 + + 325 + + 326 +--------+ + +------------+ 327 | Client |--------------(1)------+------>| Resource | 328 |Instance| + | Server | 329 | | +---------------+ | (RS) | 330 | |--(2)->| Authorization | | | 331 | |<-(3)--| Server | | | 332 | | | (AS) | | | 333 | |--(4)->| | | | 334 | |<-(5)--| | | | 335 | |--------------(6)------------->| | 336 | | | |<~(7)~~| | 337 | |<-------------(8)------------->| | 338 | |--(9)->| | | | 339 | |<-(10)-| | | | 340 | |--------------(11)------------>| | 341 | | | |<~(12)~| | 342 | |-(13)->| | | | 343 | | | | | | 344 +--------+ +---------------+ +------------+ 346 Legend 347 + + + indicates a possible interaction with a human 348 ----- indicates an interaction between protocol roles 349 ~ ~ ~ indicates a potential equivalence or out-of-band communication between roles 351 * (A) The RQ interacts with the client instance to indicate a need 352 for resources on behalf of the RO. This could identify the RS the 353 client instance needs to call, the resources needed, or the RO 354 that is needed to approve the request. Note that the RO and RQ 355 are often the same entity in practice. 357 * (1) The client instance attempts to call the RS (Section 10.4) to 358 determine what access is needed. The RS informs the client 359 instance that access can be granted through the AS. Note that for 360 most situations, the client instance already knows which AS to 361 talk to and which kinds of access it needs. 363 * (2) The client instance requests access at the AS (Section 2). 365 * (3) The AS processes the request and determines what is needed to 366 fulfill the request. The AS sends its response to the client 367 instance (Section 3). 369 * (B) If interaction is required, the AS interacts with the RO 370 (Section 4) to gather authorization. The interactive component of 371 the AS can function using a variety of possible mechanisms 372 including web page redirects, applications, challenge/response 373 protocols, or other methods. The RO approves the request for the 374 client instance being operated by the RQ. Note that the RO and RQ 375 are often the same entity in practice. 377 * (4) The client instance continues the grant at the AS (Section 5). 379 * (5) If the AS determines that access can be granted, it returns a 380 response to the client instance (Section 3) including an access 381 token (Section 3.2) for calling the RS and any directly returned 382 information (Section 3.4) about the RO. 384 * (6) The client instance uses the access token (Section 7) to call 385 the RS. 387 * (7) The RS determines if the token is sufficient for the request 388 by examining the token, potentially calling the AS (Section 10.1). 389 Note that the RS could also examine the token directly, call an 390 internal data store, execute a policy engine request, or any 391 number of alternative methods for validating the token and its 392 fitness for the request. 394 * (8) The client instance calls the RS (Section 7) using the access 395 token until the RS or client instance determine that the token is 396 no longer valid. 398 * (9) When the token no longer works, the client instance fetches an 399 updated access token (Section 6.1) based on the rights granted in 400 (5). 402 * (10) The AS issues a new access token (Section 3.2) to the client 403 instance. 405 * (11) The client instance uses the new access token (Section 7) to 406 call the RS. 408 * (12) The RS determines if the new token is sufficient for the 409 request by examining the token, potentially calling the AS 410 (Section 10.1). 412 * (13) The client instance disposes of the token (Section 6.2) once 413 the client instance has completed its access of the RS and no 414 longer needs the token. 416 The following sections and Appendix C contain specific guidance on 417 how to use GNAP in different situations and deployments. 419 1.4.1. Redirect-based Interaction 421 In this example flow, the client instance is a web application that 422 wants access to resources on behalf of the current user, who acts as 423 both the requesting party (RQ) and the resource owner (RO). Since 424 the client instance is capable of directing the user to an arbitrary 425 URL and receiving responses from the user's browser, interaction here 426 is handled through front-channel redirects using the user's browser. 427 The client instance uses a persistent session with the user to ensure 428 the same user that is starting the interaction is the user that 429 returns from the interaction. 431 +--------+ +--------+ +------+ 432 | Client | | AS | | RO | 433 |Instance| | | | + | 434 | |< (1) + Start Session + + + + + + + + + + + + + + + +| RQ | 435 | | | | |(User)| 436 | |--(2)--- Request Access --------->| | | | 437 | | | | | | 438 | |<-(3)-- Interaction Needed -------| | | | 439 | | | | | | 440 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 441 | | | | | | 442 | | | |<+ (5) +>| | 443 | | | | AuthN | | 444 | | | | | | 445 | | | |<+ (6) +>| | 446 | | | | AuthZ | | 447 | | | | | | 448 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 449 | | | | +------+ 450 | |--(8)--- Continue Request ------->| | 451 | | | | 452 | |<-(9)----- Grant Access ----------| | 453 | | | | 454 +--------+ +--------+ 456 1. The client instance establishes a verifiable session to the user, 457 in the role of the RQ. 459 2. The client instance requests access to the resource (Section 2). 460 The client instance indicates that it can redirect to an 461 arbitrary URL (Section 2.5.1) and receive a callback from the 462 browser (Section 2.5.3). The client instance stores verification 463 information for its callback in the session created in (1). 465 3. The AS determines that interaction is needed and responds 466 (Section 3) with a URL to send the user to (Section 3.3.1) and 467 information needed to verify the callback (Section 3.3.3) in (7). 468 The AS also includes information the client instance will need to 469 continue the request (Section 3.1) in (8). The AS associates 470 this continuation information with an ongoing request that will 471 be referenced in (4), (6), and (8). 473 4. The client instance stores the verification and continuation 474 information from (3) in the session from (1). The client 475 instance then redirects the user to the URL (Section 4.1) given 476 by the AS in (3). The user's browser loads the interaction 477 redirect URL. The AS loads the pending request based on the 478 incoming URL generated in (3). 480 5. The user authenticates at the AS, taking on the role of the RO. 482 6. As the RO, the user authorizes the pending request from the 483 client instance. 485 7. When the AS is done interacting with the user, the AS redirects 486 the user back (Section 4.4.1) to the client instance using the 487 callback URL provided in (2). The callback URL is augmented with 488 an interaction reference that the AS associates with the ongoing 489 request created in (2) and referenced in (4). The callback URL 490 is also augmented with a hash of the security information 491 provided in (2) and (3). The client instance loads the 492 verification information from (2) and (3) from the session 493 created in (1). The client instance calculates a hash 494 (Section 4.4.3) based on this information and continues only if 495 the hash validates. Note that the client instance needs to 496 ensure that the parameters for the incoming request match those 497 that it is expecting from the session created in (1). The client 498 instance also needs to be prepared for the RQ never being 499 returned to the client instance and handle time outs 500 appropriately. 502 8. The client instance loads the continuation information from (3) 503 and sends the interaction reference from (7) in a request to 504 continue the request (Section 5.1). The AS validates the 505 interaction reference ensuring that the reference is associated 506 with the request being continued. 508 9. If the request has been authorized, the AS grants access to the 509 information in the form of access tokens (Section 3.2) and direct 510 subject information (Section 3.4) to the client instance. 512 An example set of protocol messages for this method can be found in 513 Appendix C.1. 515 1.4.2. User-code Interaction 517 In this example flow, the client instance is a device that is capable 518 of presenting a short, human-readable code to the user and directing 519 the user to enter that code at a known URL. The client instance is 520 not capable of presenting an arbitrary URL to the user, nor is it 521 capable of accepting incoming HTTP requests from the user's browser. 522 The client instance polls the AS while it is waiting for the RO to 523 authorize the request. The user's interaction is assumed to occur on 524 a secondary device. In this example it is assumed that the user is 525 both the RQ and RO, though the user is not assumed to be interacting 526 with the client instance through the same web browser used for 527 interaction at the AS. 529 +--------+ +--------+ +------+ 530 | Client | | AS | | RO | 531 |Instance|--(1)--- Request Access --------->| | | + | 532 | | | | | RQ | 533 | |<-(2)-- Interaction Needed -------| | |(User)| 534 | | | | | | 535 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 536 | | | | | | 537 | | | |<+ (4) + | | 538 | | | |Open URI | | 539 | | | | | | 540 | | | |<+ (5) +>| | 541 | | | | AuthN | | 542 | |--(9)--- Continue Request (A) --->| | | | 543 | | | |<+ (6) +>| | 544 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 545 | | | | | | 546 | | | |<+ (7) +>| | 547 | | | | AuthZ | | 548 | | | | | | 549 | | | |<+ (8) +>| | 550 | | | |Completed| | 551 | | | | | | 552 | |--(11)-- Continue Request (B) --->| | +------+ 553 | | | | 554 | |<-(12)----- Grant Access ---------| | 555 | | | | 556 +--------+ +--------+ 558 1. The client instance requests access to the resource (Section 2). 559 The client instance indicates that it can display a user code 560 (Section 2.5.4). 562 2. The AS determines that interaction is needed and responds 563 (Section 3) with a user code to communicate to the user 564 (Section 3.3.4). This could optionally include a URL to direct 565 the user to, but this URL should be static and so could be 566 configured in the client instance's documentation. The AS also 567 includes information the client instance will need to continue 568 the request (Section 3.1) in (8) and (10). The AS associates 569 this continuation information with an ongoing request that will 570 be referenced in (4), (6), (8), and (10). 572 3. The client instance stores the continuation information from (2) 573 for use in (8) and (10). The client instance then communicates 574 the code to the user (Section 4.1) given by the AS in (2). 576 4. The user's directs their browser to the user code URL. This URL 577 is stable and can be communicated via the client software's 578 documentation, the AS documentation, or the client software 579 itself. Since it is assumed that the RO will interact with the 580 AS through a secondary device, the client instance does not 581 provide a mechanism to launch the RO's browser at this URL. 583 5. The RQ authenticates at the AS, taking on the role of the RO. 585 6. The RO enters the code communicated in (3) to the AS. The AS 586 validates this code against a current request in process. 588 7. As the RO, the user authorizes the pending request from the 589 client instance. 591 8. When the AS is done interacting with the user, the AS indicates 592 to the RO that the request has been completed. 594 9. Meanwhile, the client instance loads the continuation 595 information stored at (3) and continues the request (Section 5). 596 The AS determines which ongoing access request is referenced 597 here and checks its state. 599 10. If the access request has not yet been authorized by the RO in 600 (6), the AS responds to the client instance to continue the 601 request (Section 3.1) at a future time through additional polled 602 continuation requests. This response can include updated 603 continuation information as well as information regarding how 604 long the client instance should wait before calling again. The 605 client instance replaces its stored continuation information 606 from the previous response (2). Note that the AS may need to 607 determine that the RO has not approved the request in a 608 sufficient amount of time and return an appropriate error to the 609 client instance. 611 11. The client instance continues to poll the AS (Section 5.2) with 612 the new continuation information in (9). 614 12. If the request has been authorized, the AS grants access to the 615 information in the form of access tokens (Section 3.2) and 616 direct subject information (Section 3.4) to the client instance. 618 An example set of protocol messages for this method can be found in 619 Appendix C.2. 621 1.4.3. Asynchronous Authorization 623 In this example flow, the RQ and RO roles are fulfilled by different 624 parties, and the RO does not interact with the client instance. The 625 AS reaches out asynchronously to the RO during the request process to 626 gather the RO's authorization for the client instance's request. The 627 client instance polls the AS while it is waiting for the RO to 628 authorize the request. 630 +--------+ +--------+ +------+ 631 | Client | | AS | | RO | 632 |Instance|--(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 client instance requests access to the resource (Section 2). 651 The client instance does not send any interactions modes to the 652 server, indicating that it does not expect to interact with the 653 RO. The client instance can also signal which RO it requires 654 authorization from, if known, by using the user request section 655 (Section 2.4). 657 2. The AS determines that interaction is needed, but the client 658 instance cannot interact with the RO. The AS responds 659 (Section 3) with the information the client instance will need to 660 continue the request (Section 3.1) in (6) and (8), including a 661 signal that the client instance should wait before checking the 662 status of the request again. The AS associates this continuation 663 information with an ongoing request that will be referenced in 664 (3), (4), (5), (6), and (8). 666 3. The AS determines which RO to contact based on the request in 667 (1), through a combination of the user request (Section 2.4), the 668 resources request (Section 2.1), and other policy information. 669 The AS contacts the RO and authenticates them. 671 4. The RO authorizes the pending request from the client instance. 673 5. When the AS is done interacting with the RO, the AS indicates to 674 the RO that the request has been completed. 676 6. Meanwhile, the client instance loads the continuation information 677 stored at (3) and continues the request (Section 5). The AS 678 determines which ongoing access request is referenced here and 679 checks its state. 681 7. If the access request has not yet been authorized by the RO in 682 (6), the AS responds to the client instance to continue the 683 request (Section 3.1) at a future time through additional 684 polling. This response can include refreshed credentials as well 685 as information regarding how long the client instance should wait 686 before calling again. The client instance replaces its stored 687 continuation information from the previous response (2). Note 688 that the AS may need to determine that the RO has not approved 689 the request in a sufficient amount of time and return an 690 appropriate error to the client instance. 692 8. The client instance continues to poll the AS (Section 5.2) with 693 the new continuation information from (7). 695 9. If the request has been authorized, the AS grants access to the 696 information in the form of access tokens (Section 3.2) and direct 697 subject information (Section 3.4) to the client instance. 699 An example set of protocol messages for this method can be found in 700 Appendix D.1. 702 1.4.4. Software-only Authorization 704 In this example flow, the AS policy allows the client instance to 705 make a call on its own behalf, without the need for a RO to be 706 involved at runtime to approve the decision. Since there is no 707 explicit RO, the client instance does not interact with an RO. 709 +--------+ +--------+ 710 | Client | | AS | 711 |Instance|--(1)--- Request Access --------->| | 712 | | | | 713 | |<-(2)---- Grant Access -----------| | 714 | | | | 715 +--------+ +--------+ 717 1. The client instance requests access to the resource (Section 2). 718 The client instance does not send any interactions modes to the 719 server. 721 2. The AS determines that the request is been authorized, the AS 722 grants access to the information in the form of access tokens 723 (Section 3.2) and direct subject information (Section 3.4) to the 724 client instance. 726 An example set of protocol messages for this method can be found in 727 Appendix D. 729 1.4.5. Refreshing an Expired Access Token 731 In this example flow, the client instance receives an access token to 732 access a resource server through some valid GNAP process. The client 733 instance uses that token at the RS for some time, but eventually the 734 access token expires. The client instance then gets a new access 735 token by rotating the expired access token at the AS using the 736 token's management URL. 738 +--------+ +--------+ 739 | Client | | AS | 740 |Instance|--(1)--- Request Access ----------------->| | 741 | | | | 742 | |<-(2)--- Grant Access --------------------| | 743 | | | | 744 | | +--------+ | | 745 | |--(3)--- Access Resource --->| RS | | | 746 | | | | | | 747 | |<-(4)--- Error Response -----| | | | 748 | | +--------+ | | 749 | | | | 750 | |--(5)--- Rotate Token ------------------->| | 751 | | | | 752 | |<-(6)--- Rotated Token -------------------| | 753 | | | | 754 +--------+ +--------+ 756 1. The client instance requests access to the resource (Section 2). 758 2. The AS grants access to the resource (Section 3) with an access 759 token (Section 3.2) usable at the RS. The access token response 760 includes a token management URI. 762 3. The client instance presents the token (Section 7) to the RS. 763 The RS validates the token and returns an appropriate response 764 for the API. 766 4. When the access token is expired, the RS responds to the client 767 instance with an error. 769 5. The client instance calls the token management URI returned in 770 (2) to rotate the access token (Section 6.1). The client 771 instance presents the access token as well as the appropriate 772 key. 774 6. The AS validates the rotation request including the signature and 775 keys presented in (5) and returns a new access token 776 (Section 3.2.1). The response includes a new access token and 777 can also include updated token management information, which the 778 client instance will store in place of the values returned in 779 (2). 781 2. Requesting Access 783 To start a request, the client instance sends JSON [RFC8259] document 784 with an object as its root. Each member of the request object 785 represents a different aspect of the client instance's request. Each 786 field is described in detail in a section below. 788 resources (object / array of objects/strings) Describes the rights 789 that the client instance is requesting for one or more access 790 tokens to be used at RS's. Section 2.1 792 subject (object) Describes the information about the RO that the 793 client instance is requesting to be returned directly in the 794 response from the AS. Section 2.2 796 client (object / string) Describes the client instance that is 797 making this request, including the key that the client instance 798 will use to protect this request and any continuation requests at 799 the AS and any user-facing information about the client instance 800 used in interactions at the AS. Section 2.3 802 user (object / string) Identifies the RQ to the AS in a manner that 803 the AS can verify, either directly or by interacting with the RQ 804 to determine their status as the RO. Section 2.4 806 interact (object) Describes the modes that the client instance has 807 for allowing the RO to interact with the AS and modes for the 808 client instance to receive updates when interaction is complete. 809 Section 2.5 811 capabilities (array of strings) Identifies named extension 812 capabilities that the client instance can use, signaling to the AS 813 which extensions it can use. Section 2.6 815 existing_grant (string) Identifies a previously-existing grant that 816 the client instance is extending with this request. Section 2.7 818 Additional members of this request object can be defined by 819 extensions to this protocol as described in Section 2.8 821 A non-normative example of a grant request is below: 823 { 824 "resources": [ 825 { 826 "type": "photo-api", 827 "actions": [ 828 "read", 829 "write", 830 "dolphin" 831 ], 832 "locations": [ 833 "https://server.example.net/", 834 "https://resource.local/other" 835 ], 836 "datatypes": [ 837 "metadata", 838 "images" 839 ] 840 }, 841 "dolphin-metadata" 842 ], 843 "client": { 844 "display": { 845 "name": "My Client Display Name", 846 "uri": "https://example.net/client" 847 }, 848 "key": { 849 "proof": "jwsd", 850 "jwk": { 851 "kty": "RSA", 852 "e": "AQAB", 853 "kid": "xyz-1", 854 "alg": "RS256", 855 "n": "kOB5rR4Jv0GMeL...." 856 } 857 } 858 }, 859 "interact": { 860 "redirect": true, 861 "callback": { 862 "method": "redirect", 863 "uri": "https://client.example.net/return/123455", 864 "nonce": "LKLTI25DK82FX4T4QFZC" 865 } 866 }, 867 "capabilities": ["ext1", "ext2"], 868 "subject": { 869 "sub_ids": ["iss_sub", "email"], 870 "assertions": ["id_token"] 871 } 872 } 874 The request MUST be sent as a JSON object in the body of the HTTP 875 POST request with Content-Type "application/json", unless otherwise 876 specified by the signature mechanism. 878 2.1. Requesting Resources 880 If the client instance is requesting one or more access tokens for 881 the purpose of accessing an API, the client instance MUST include a 882 "resources" field. This field MUST be an array (for a single access 883 token (Section 2.1.1)) or an object (for multiple access tokens 884 (Section 2.1.3)), as described in the following sections. 886 2.1.1. Requesting a Single Access Token 888 When requesting an access token, the client instance MUST send a 889 "resources" field containing a JSON array. The elements of the JSON 890 array represent rights of access that the client instance is 891 requesting in the access token. The requested access is the union of 892 all elements within the array. 894 The client instance declares what access it wants to associate with 895 the resulting access token using objects that describe multiple 896 dimensions of access. Each object contains a "type" property that 897 determines the type of API that the client instance is calling. 899 type (string) The type of resource request as a string. This field 900 MAY define which other fields are allowed in the request object. 901 This field is REQUIRED. 903 The value of this field is under the control of the AS. This field 904 MUST be compared using an exact byte match of the string value 905 against known types by the AS. The AS MUST ensure that there is no 906 collision between different authorization data types that it 907 supports. The AS MUST NOT do any collation or normalization of data 908 types during comparison. It is RECOMMENDED that designers of 909 general-purpose APIs use a URI for this field to avoid collisions 910 between multiple API types protected by a single AS. 912 While it is expected that many APIs will have its own properties, a 913 set of common properties are defined here. Specific API 914 implementations SHOULD NOT re-use these fields with different 915 semantics or syntax. The available values for these properties are 916 determined by the API being protected at the RS. 918 actions (array of strings) The types of actions the client instance 919 will take at the RS as an array of strings. For example, a client 920 instance asking for a combination of "read" and "write" access. 922 locations (array of strings) The location of the RS as an array of 923 strings. These strings are typically URIs identifying the 924 location of the RS. 926 datatypes (array of strings) The kinds of data available to the 927 client instance at the RS's API as an array of strings. For 928 example, a client instance asking for access to raw "image" data 929 and "metadata" at a photograph API. 931 identifier (string) A string identifier indicating a specific 932 resource at the RS. For example, a patient identifier for a 933 medical API or a bank account number for a financial API. 935 The following non-normative example is asking for three kinds of 936 access (read, write, delete) to each of two different locations and 937 two different data types (metadata, images) for a single access token 938 using the fictitious "photo-api" type definition. 940 "resources": [ 941 { 942 "type": "photo-api", 943 "actions": [ 944 "read", 945 "write", 946 "delete" 947 ], 948 "locations": [ 949 "https://server.example.net/", 950 "https://resource.local/other" 951 ], 952 "datatypes": [ 953 "metadata", 954 "images" 955 ] 956 } 957 ] 959 The access requested for a given object when using these fields is 960 the cross-product of all fields of the object. That is to say, the 961 object represents a request for all "action" values listed within the 962 object to be used at all "locations" values listed within the object 963 for all "datatype" values listed within the object. Assuming the 964 request above was granted, the RC could assume that it would be able 965 to do a "read" action against the "images" on the first server as 966 well as a "delete" action on the "metadata" of the second server, or 967 any other combination of these fields, using the same access token. 969 To request a different combination of access, such as requesting one 970 "action" against one "location" and a different "action" against a 971 different "location", the RC can include multiple separate objects in 972 the "resources" array. The following non-normative example uses the 973 same fictitious "photo-api" type definition to request a single 974 access token with more specifically targeted access rights by using 975 two discrete objects within the request. 977 "resources": [ 978 { 979 "type": "photo-api", 980 "actions": [ 981 "read" 982 ], 983 "locations": [ 984 "https://server.example.net/" 985 ], 986 "datatypes": [ 987 "images" 988 ] 989 }, 990 { 991 "type": "photo-api", 992 "actions": [ 993 "write", 994 "delete" 995 ], 996 "locations": [ 997 "https://resource.local/other" 998 ], 999 "datatypes": [ 1000 "metadata" 1001 ] 1002 } 1003 ] 1005 The access requested here is for "read" access to "images" on one 1006 server while simultaneously requesting "write" and "delete" access 1007 for "metadata" on a different server, but importantly without 1008 requesting "write" or "delete" access to "images" on the first 1009 server. 1011 It is anticipated that API designers will use a combination of common 1012 fields defined in this specification as well as fields specific to 1013 the API itself. The following non-normative example shows the use of 1014 both common and API-specific fields as part of two different 1015 fictitious API "type" values. The first access request includes the 1016 "actions", "locations", and "datatypes" fields specified here as well 1017 as the API-specific "geolocation" field. The second access request 1018 includes the "actions" and "identifier" fields specified here as well 1019 as the API-specific "currency" field. 1021 "resources": [ 1022 { 1023 "type": "photo-api", 1024 "actions": [ 1025 "read", 1026 "write" 1027 ], 1028 "locations": [ 1029 "https://server.example.net/", 1030 "https://resource.local/other" 1031 ], 1032 "datatypes": [ 1033 "metadata", 1034 "images" 1035 ], 1036 "geolocation": [ 1037 { lat: -32.364, lng: 153.207 }, 1038 { lat: -35.364, lng: 158.207 } 1039 ] 1040 }, 1041 { 1042 "type": "financial-transaction", 1043 "actions": [ 1044 "withdraw" 1045 ], 1046 "identifier": "account-14-32-32-3", 1047 "currency": "USD" 1048 } 1049 ] 1051 If this request is approved, the resulting access token 1052 (Section 3.2.1)'s access rights will be the union of the requested 1053 types of access for each of the two APIs, just as above. 1055 2.1.2. Requesting Resources By Reference 1057 Instead of sending an object describing the requested resource 1058 (Section 2.1.1), a client instance MAY send a string known to the AS 1059 or RS representing the access being requested. Each string SHOULD 1060 correspond to a specific expanded object representation at the AS. 1062 "resources": [ 1063 "read", "dolphin-metadata", "some other thing" 1064 ] 1066 This value is opaque to the client instance and MAY be any valid JSON 1067 string, and therefore could include spaces, unicode characters, and 1068 properly escaped string sequences. However, in some situations the 1069 value is intended to be seen and understood by the client software's 1070 developer. In such cases, the API designer choosing any such human- 1071 readable strings SHOULD take steps to ensure the string values are 1072 not easily confused by a developer, such as by limiting the strings 1073 to easily disambiguated characters. 1075 This functionality is similar in practice to OAuth 2's "scope" 1076 parameter [RFC6749], where a single string represents the set of 1077 access rights requested by the client instance. As such, the 1078 reference string could contain any valid OAuth 2 scope value as in 1079 Appendix D.2. Note that the reference string here is not bound to 1080 the same character restrictions as in OAuth 2's "scope" definition. 1082 A single "resources" array MAY include both object-type and string- 1083 type resource items. In this non-normative example, the RC is 1084 requesting access to a "photo-api" and "financial-transaction" API 1085 type as well as the reference values of "read", "dolphin-metadata", 1086 and "some other thing". 1088 "resources": [ 1089 { 1090 "type": "photo-api", 1091 "actions": [ 1092 "read", 1093 "write", 1094 "delete" 1095 ], 1096 "locations": [ 1097 "https://server.example.net/", 1098 "https://resource.local/other" 1099 ], 1100 "datatypes": [ 1101 "metadata", 1102 "images" 1103 ] 1104 }, 1105 "read", 1106 "dolphin-metadata", 1107 { 1108 "type": "financial-transaction", 1109 "actions": [ 1110 "withdraw" 1111 ], 1112 "identifier": "account-14-32-32-3", 1113 "currency": "USD" 1114 }, 1115 "some other thing" 1116 ] 1118 The requested access is the union of all elements of the array, 1119 including both objects and reference strings. 1121 2.1.3. Requesting Multiple Access Tokens 1123 When requesting multiple access tokens, the resources field is a JSON 1124 object. The names of the JSON object fields are token identifiers 1125 chosen by the client instance, and MAY be any valid string. The 1126 values of the JSON object fields are JSON arrays representing a 1127 single access token request, as specified in requesting a single 1128 access token (Section 2.1.1). 1130 The following non-normative example shows a request for two separate 1131 access tokens, "token1" and "token2". 1133 "resources": { 1134 "token1": [ 1135 { 1136 "type": "photo-api", 1137 "actions": [ 1138 "read", 1139 "write", 1140 "dolphin" 1141 ], 1142 "locations": [ 1143 "https://server.example.net/", 1144 "https://resource.local/other" 1145 ], 1146 "datatypes": [ 1147 "metadata", 1148 "images" 1149 ] 1150 }, 1151 "dolphin-metadata" 1152 ], 1153 "token2": [ 1154 { 1155 "type": "walrus-access", 1156 "actions": [ 1157 "foo", 1158 "bar" 1159 ], 1160 "locations": [ 1161 "https://resource.other/" 1162 ], 1163 "datatypes": [ 1164 "data", 1165 "pictures", 1166 "walrus whiskers" 1167 ] 1168 } 1169 ] 1170 } 1172 Any approved access requests are returned in the multiple access 1173 token response (Section 3.2.2) structure using the token identifiers 1174 in the request. 1176 2.1.4. Signaling Token Behavior 1178 While the AS is ultimately in control of how tokens are returned and 1179 bound to the client instance, sometimes the client instance has 1180 context about what it can support that can affect the AS's response. 1181 This specification defines several flags that are passed as resource 1182 reference strings (Section 2.1.2). 1184 Each flag applies only to the single resource request in which it 1185 appears. 1187 Support of all flags is optional, such as any other resource 1188 reference value. 1190 multi_token The client instance wishes to support multiple 1191 simultaneous access tokens through the token rotation process. 1192 When the client instance rotates an access token (Section 6.1), 1193 the AS does not invalidate the previous access token. The old 1194 access token continues to remain valid until such time as it 1195 expires or is revoked through other means. 1197 split_token The client instance is capable of receiving multiple 1198 access tokens (Section 3.2.2) in response to any single token 1199 request (Section 2.1.1), or receiving a different number of tokens 1200 than specified in the multiple token request (Section 2.1.3). The 1201 labels of the returned additional tokens are chosen by the AS. 1202 The client instance MUST be able to tell from the token response 1203 where and how it can use each of the access tokens. [[ See issue 1204 #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/37) 1205 ]] 1207 bind_token The client instance wants the issued access token to be 1208 bound to the key the client instance used (Section 2.3.2) to make 1209 the request. The resulting access token MUST be bound using the 1210 same "proof" mechanism used by the client instance with a "key" 1211 value of "true", indicating the client instance's presented key is 1212 to be used for binding. [[ See issue #38 (https://github.com/ 1213 ietf-wg-gnap/gnap-core-protocol/issues/38) ]] 1215 The AS MUST respond with any applied flags in the token response 1216 (Section 3.2) "resources" section. 1218 In this non-normative example, the requested access token is to be 1219 bound to the client instance's key and should be kept during 1220 rotation. 1222 "resources": [ 1223 { 1224 "type": "photo-api", 1225 "actions": [ 1226 "read", 1227 "write", 1228 "dolphin" 1229 ], 1230 "locations": [ 1231 "https://server.example.net/", 1232 "https://resource.local/other" 1233 ], 1234 "datatypes": [ 1235 "metadata", 1236 "images" 1237 ] 1238 }, 1239 "read", 1240 "bind_token", 1241 "multi_token" 1242 ] 1244 Additional flags can be registered in a registry TBD (Section 12). 1246 [[ See issue #39 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1247 issues/39) ]] 1249 2.2. Requesting User Information 1251 If the client instance is requesting information about the RO from 1252 the AS, it sends a "subject" field as a JSON object. This object MAY 1253 contain the following fields (or additional fields defined in a 1254 registry TBD (Section 12)). 1256 sub_ids (array of strings) An array of subject identifier subject 1257 types requested for the RO, as defined by 1258 [I-D.ietf-secevent-subject-identifiers]. 1260 assertions (array of strings) An array of requested assertion 1261 formats. Possible values include "id_token" for an [OIDC] ID 1262 Token and "saml2" for a SAML 2 assertion. Additional assertion 1263 values are defined by a registry TBD (Section 12). [[ See issue 1264 #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) 1265 ]] 1267 "subject": { 1268 "sub_ids": [ "iss_sub", "email" ], 1269 "assertions": [ "id_token", "saml2" ] 1270 } 1272 The AS can determine the RO's identity and permission for releasing 1273 this information through interaction with the RO (Section 4), AS 1274 policies, or assertions presented by the client instance 1275 (Section 2.4). If this is determined positively, the AS MAY return 1276 the RO's information in its response (Section 3.4) as requested. 1278 Subject identifiers requested by the client instance serve only to 1279 identify the RO in the context of the AS and can't be used as 1280 communication channels by the client instance, as discussed in 1281 Section 3.4. 1283 The AS SHOULD NOT re-use subject identifiers for multiple different 1284 ROs. 1286 [[ See issue #42 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1287 issues/42) ]] 1289 Note: the "sub_ids" and "assertions" request fields are independent 1290 of each other, and a returned assertion MAY omit a requested subject 1291 identifier. 1293 [[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1294 issues/43) ]] 1296 2.3. Identifying the Client Instance 1298 When sending a non-continuation request to the AS, the client 1299 instance MUST identify itself by including the "client" field of the 1300 request and by signing the request as described in Section 8. Note 1301 that for a continuation request (Section 5), the client instance is 1302 identified by its association with the request being continued and so 1303 this field is not sent under those circumstances. 1305 When client instance information is sent by value, the "client" field 1306 of the request consists of a JSON object with the following fields. 1308 key (object / string) The public key of the client instance to be 1309 used in this request as described in Section 2.3.2. This field is 1310 REQUIRED. 1312 class_id (string) An identifier string that the AS can use to 1313 identify the client software comprising this client instance. The 1314 contents and format of this field are up to the AS. This field is 1315 OPTIONAL. 1317 display (object) An object containing additional information that 1318 the AS MAY display to the RO during interaction, authorization, 1319 and management. This field is OPTIONAL. 1321 "client": { 1322 "key": { 1323 "proof": "httpsig", 1324 "jwk": { 1325 "kty": "RSA", 1326 "e": "AQAB", 1327 "kid": "xyz-1", 1328 "alg": "RS256", 1329 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1330 }, 1331 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1332 }, 1333 "class_id": "web-server-1234", 1334 "display": { 1335 "name": "My Client Display Name", 1336 "uri": "https://example.net/client" 1337 } 1338 } 1340 Additional fields are defined in a registry TBD (Section 12). 1342 The client instance MUST prove possession of any presented key by the 1343 "proof" mechanism associated with the key in the request. Proof 1344 types are defined in a registry TBD (Section 12) and an initial set 1345 of methods is described in Section 8. 1347 Note that the AS MAY know the client instance's public key ahead of 1348 time, and the AS MAY apply different policies to the request 1349 depending on what has been registered against that key. If the same 1350 public key is sent by value on subsequent access requests, the AS 1351 SHOULD treat these requests as coming from the same client instance 1352 for purposes of identification, authentication, and policy 1353 application. If the AS does not know the client instance's public 1354 key ahead of time, the AS MAY accept or reject the request based on 1355 AS policy, attestations within the "client" request, and other 1356 mechanisms. 1358 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1359 issues/44) ]] 1361 2.3.1. Identifying the Client Instance 1363 If the client instance has an instance identifier that the AS can use 1364 to determine appropriate key information, the client instance can 1365 send this value in the "instance_id" field. The instance identifier 1366 MAY be assigned to a client instance at runtime through the 1367 Section 3.5 or MAY be obtained in another fashion, such as a static 1368 registration process at the AS. 1370 instance_id (string) An identifier string that the AS can use to 1371 identify the particular instance of this client software. The 1372 content and structure of this identifier is opaque to the client 1373 instance. 1375 "client": { 1376 "instance_id": "client-541-ab" 1377 } 1379 If there are no additional fields to send, the client instance MAY 1380 send the instance identifier as a direct reference value in lieu of 1381 the object. 1383 "client": "client-541-ab" 1385 When the AS receives a request with an instance identifier, the AS 1386 MUST ensure that the key used to sign the request (Section 8) is 1387 associated with the instance identifier. 1389 If the "instance_id" field is sent, it MUST NOT be accompanied by 1390 other fields unless such fields are explicitly marked safe for 1391 inclusion alongside the instance identifier. 1393 [[ See issue #45 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1394 issues/45) ]] 1396 If the AS does not recognize the instance identifier, the request 1397 MUST be rejected with an error. 1399 If the client instance is identified in this manner, the registered 1400 key for the client instance MAY be a symmetric key known to the AS. 1401 The client instance MUST NOT send a symmetric key by value in the 1402 request, as doing so would expose the key directly instead of proving 1403 possession of it. 1405 2.3.2. Identifying the Client Instance Key 1407 The client instance key MUST be a public key in at least one 1408 supported format and MUST be applicable to the proofing mechanism 1409 used in the request. If the key is sent in multiple formats, all the 1410 keys MUST be the same. The key presented in this field MUST be the 1411 key used to sign the request. 1413 proof (string) The form of proof that the client instance will use 1414 when presenting the key to the AS. The valid values of this field 1415 and the processing requirements for each are detailed in 1416 Section 8. This field is REQUIRED. 1418 jwk (object) Value of the public key as a JSON Web Key. MUST contain 1419 an "alg" field which is used to validate the signature. MUST 1420 contain the "kid" field to identify the key in the signed object. 1422 cert (string) PEM serialized value of the certificate used to sign 1423 the request, with optional internal whitespace. 1425 cert#S256 (string) The certificate thumbprint calculated as per 1426 OAuth-MTLS [RFC8705] in base64 URL encoding. 1428 Additional key types are defined in a registry TBD (Section 12). 1430 This non-normative example shows a single key presented in multiple 1431 formats using a single proofing mechanism. 1433 "key": { 1434 "proof": "jwsd", 1435 "jwk": { 1436 "kty": "RSA", 1437 "e": "AQAB", 1438 "kid": "xyz-1", 1439 "alg": "RS256", 1440 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 1441 }, 1442 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1443 } 1445 Continuation requests (Section 5) MUST use the same key (or its most 1446 recent rotation) and proof method as the initial request. 1448 2.3.3. Providing Displayable Client Instance Information 1450 If the client instance has additional information to display to the 1451 RO during any interactions at the AS, it MAY send that information in 1452 the "display" field. This field is a JSON object that declares 1453 information to present to the RO during any interactive sequences. 1455 name (string) Display name of the client software 1457 uri (string) User-facing web page of the client software 1459 logo_uri (string) Display image to represent the client software 1461 "display": { 1462 "name": "My Client Display Name", 1463 "uri": "https://example.net/client" 1464 } 1466 [[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1467 issues/48) ]] 1469 Additional display fields are defined by a registry TBD (Section 12). 1471 The AS SHOULD use these values during interaction with the RO. The 1472 values are for informational purposes only and MUST NOT be taken as 1473 authentic proof of the client instance's identity or source. The AS 1474 MAY restrict display values to specific client instances, as 1475 identified by their keys in Section 2.3. 1477 2.3.4. Authenticating the Client Instance 1479 If the presented key is known to the AS and is associated with a 1480 single instance of the client software, the process of presenting a 1481 key and proving possession of that key is sufficient to authenticate 1482 the client instance to the AS. The AS MAY associate policies with 1483 the client instance identified by this key, such as limiting which 1484 resources can be requested and which interaction methods can be used. 1485 For example, only specific client instances with certain known keys 1486 might be trusted with access tokens without the AS interacting 1487 directly with the RO as in Appendix D. 1489 The presentation of a key allows the AS to strongly associate 1490 multiple successive requests from the same client instance with each 1491 other. This is true when the AS knows the key ahead of time and can 1492 use the key to authenticate the client instance, but also if the key 1493 is ephemeral and created just for this series of requests. As such 1494 the AS MAY allow for client instances to make requests with unknown 1495 keys. This pattern allows for ephemeral client instances, such as 1496 single-page applications, and client software with many individual 1497 long-lived instances, such as mobile applications, to generate key 1498 pairs per instance and use the keys within the protocol without 1499 having to go through a separate registration step. The AS MAY limit 1500 which capabilities are made available to client instances with 1501 unknown keys. For example, the AS could have a policy saying that 1502 only previously-registered client instances can request particular 1503 resources, or that all client instances with unknown keys have to be 1504 interactively approved by an RO. 1506 2.4. Identifying the User 1508 If the client instance knows the identity of the RQ through one or 1509 more identifiers or assertions, the client instance MAY send that 1510 information to the AS in the "user" field. The client instance MAY 1511 pass this information by value or by reference. 1513 sub_ids (array of strings) An array of subject identifiers for the 1514 RQ, as defined by [I-D.ietf-secevent-subject-identifiers]. 1516 assertions (object) An object containing assertions as values keyed 1517 on the assertion type defined by a registry TBD (Section 12). 1518 Possible keys include "id_token" for an [OIDC] ID Token and 1519 "saml2" for a SAML 2 assertion. Additional assertion values are 1520 defined by a registry TBD (Section 12). [[ See issue #41 1521 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] 1523 "user": { 1524 "sub_ids": [ { 1525 "subject_type": "email", 1526 "email": "user@example.com" 1527 } ], 1528 "assertions": { 1529 "id_token": "eyj..." 1530 } 1531 } 1533 Subject identifiers are hints to the AS in determining the RO and 1534 MUST NOT be taken as declarative statements that a particular RO is 1535 present at the client instance and acting as the RQ. Assertions 1536 SHOULD be validated by the AS. [[ See issue #49 (https://github.com/ 1537 ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1539 If the identified RQ does not match the RO present at the AS during 1540 an interaction step, the AS SHOULD reject the request with an error. 1542 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1543 issues/50) ]] 1544 If the AS trusts the client instance to present verifiable 1545 assertions, the AS MAY decide, based on its policy, to skip 1546 interaction with the RO, even if the client instance provides one or 1547 more interaction modes in its request. 1549 2.4.1. Identifying the User by Reference 1551 User reference identifiers can be dynamically issued by the AS 1552 (Section 3.5) to allow the client instance to represent the same RQ 1553 to the AS over subsequent requests. 1555 If the client instance has a reference for the RQ at this AS, the 1556 client instance MAY pass that reference as a string. The format of 1557 this string is opaque to the client instance. 1559 "user": "XUT2MFM1XBIKJKSDU8QM" 1561 User reference identifiers are not intended to be human-readable user 1562 identifiers or structured assertions. For the client instance to 1563 send either of these, use the full user request object (Section 2.4) 1564 instead. 1566 [[ See issue #51 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1567 issues/51) ]] 1569 If the AS does not recognize the user reference, it MUST return an 1570 error. 1572 2.5. Interacting with the User 1574 Many times, the AS will require interaction with the RO in order to 1575 approve a requested delegation to the client instance for both 1576 resources and direct claim information. Many times the RQ using the 1577 client instance is the same person as the RO, and the client instance 1578 can directly drive interaction with the AS by redirecting the RQ on 1579 the same device, or by launching an application. Other times, the 1580 client instance can provide information to start the RO's interaction 1581 on a secondary device, or the client instance will wait for the RO to 1582 approve the request asynchronously. The client instance could also 1583 be signaled that interaction has completed by the AS making 1584 callbacks. To facilitate all of these modes, the client instance 1585 declares the means that it can interact using the "interact" field. 1587 The "interact" field is a JSON object with keys that declare 1588 different interaction modes. A client instance MUST NOT declare an 1589 interaction mode it does not support. The client instance MAY send 1590 multiple modes in the same request. There is no preference order 1591 specified in this request. An AS MAY respond to any, all, or none of 1592 the presented interaction modes (Section 3.3) in a request, depending 1593 on its capabilities and what is allowed to fulfill the request. This 1594 specification defines the following interaction modes: 1596 redirect (boolean) Indicates that the client instance can direct the 1597 RQ to an arbitrary URL at the AS for interaction. Section 2.5.1 1599 app (boolean) Indicates that the client instance can launch an 1600 application on the RQ's device for interaction. Section 2.5.2 1602 callback (object) Indicates that the client instance can receive a 1603 callback from the AS after interaction with the RO has concluded. 1604 Section 2.5.3 1606 user_code (boolean) Indicates that the client instance can 1607 communicate a human-readable short code to the RQ for use with a 1608 stable URL at the AS. Section 2.5.4 1610 ui_locales (array of strings) Indicates the RQ's preferred locales 1611 that the AS can use during interaction, particularly before the RO 1612 has authenticated. Section 2.5.5 1614 The following sections detail requests for interaction modes. 1615 Additional interaction modes are defined in a registry TBD 1616 (Section 12). 1618 In this non-normative example, the client instance is indicating that 1619 it can redirect (Section 2.5.1) the RQ to an arbitrary URL and can 1620 receive a callback (Section 2.5.3) through a browser request. 1622 "interact": { 1623 "redirect": true, 1624 "callback": { 1625 "method": "redirect", 1626 "uri": "https://client.example.net/return/123455", 1627 "nonce": "LKLTI25DK82FX4T4QFZC" 1628 } 1629 } 1631 In this non-normative example, the client instance is indicating that 1632 it can display a user code (Section 2.5.4) and direct the RQ to an 1633 arbitrary URL (Section 2.5.1) on a secondary device, but it cannot 1634 accept a callback. 1636 "interact": { 1637 "redirect": true, 1638 "user_code": true 1639 } 1641 If the client instance does not provide a suitable interaction 1642 mechanism, the AS cannot contact the RO asynchronously, and the AS 1643 determines that interaction is required, then the AS SHOULD return an 1644 error since the client instance will be unable to complete the 1645 request without authorization. 1647 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1648 provided, including user codes and redirection URLs. The client 1649 instance SHOULD apply suitable timeouts to any callback URLs. 1651 2.5.1. Redirect to an Arbitrary URL 1653 If the client instance is capable of directing the RQ to a URL 1654 defined by the AS at runtime, the client instance indicates this by 1655 sending the "redirect" field with the boolean value "true". The 1656 means by which the client instance will activate this URL is out of 1657 scope of this specification, but common methods include an HTTP 1658 redirect, launching a browser on the RQ's device, providing a 1659 scannable image encoding, and printing out a URL to an interactive 1660 console. 1662 "interact": { 1663 "redirect": true 1664 } 1666 If this interaction mode is supported for this client instance and 1667 request, the AS returns a redirect interaction response 1668 Section 3.3.1. 1670 2.5.2. Open an Application-specific URL 1672 If the client instance can open a URL associated with an application 1673 on the RQ's device, the client instance indicates this by sending the 1674 "app" field with boolean value "true". The means by which the client 1675 instance determines the application to open with this URL are out of 1676 scope of this specification. 1678 "interact": { 1679 "app": true 1680 } 1682 If this interaction mode is supported for this client instance and 1683 request, the AS returns an app interaction response with an app URL 1684 payload Section 3.3.2. 1686 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1687 issues/54) ]] 1689 2.5.3. Receive a Callback After Interaction 1691 If the client instance is capable of receiving a message from the AS 1692 indicating that the RO has completed their interaction, the client 1693 instance indicates this by sending the "callback" field. The value 1694 of this field is an object containing the following members. 1696 uri (string) REQUIRED. Indicates the URI to send the RO to after 1697 interaction. This URI MAY be unique per request and MUST be 1698 hosted by or accessible by the client instance. This URI MUST NOT 1699 contain any fragment component. This URI MUST be protected by 1700 HTTPS, be hosted on a server local to the RO's browser 1701 ("localhost"), or use an application-specific URI scheme. If the 1702 client instance needs any state information to tie to the front 1703 channel interaction response, it MUST use a unique callback URI to 1704 link to that ongoing state. The allowable URIs and URI patterns 1705 MAY be restricted by the AS based on the client instance's 1706 presented key information. The callback URI SHOULD be presented 1707 to the RO during the interaction phase before redirect. [[ See 1708 issue #55 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1709 issues/55) ]] 1711 nonce (string) REQUIRED. Unique value to be used in the calculation 1712 of the "hash" query parameter sent to the callback URL, must be 1713 sufficiently random to be unguessable by an attacker. MUST be 1714 generated by the client instance as a unique value for this 1715 request. 1717 method (string) REQUIRED. The callback method that the AS will use 1718 to contact the client instance. Valid values include "redirect" 1719 Section 2.5.3.1 and "push" Section 2.5.3.2, with other values 1720 defined by a registry TBD (Section 12). 1722 hash_method (string) OPTIONAL. The hash calculation mechanism to be 1723 used for the callback hash in Section 4.4.3. Can be one of "sha3" 1724 or "sha2". If absent, the default value is "sha3". [[ See issue 1725 #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) 1726 ]] 1728 "interact": { 1729 "callback": { 1730 "method": "redirect", 1731 "uri": "https://client.example.net/return/123455", 1732 "nonce": "LKLTI25DK82FX4T4QFZC" 1733 } 1734 } 1735 If this interaction mode is supported for this client instance and 1736 request, the AS returns a nonce for use in validating the callback 1737 response (Section 3.3.3). Requests to the callback URI MUST be 1738 processed as described in Section 4.4, and the AS MUST require 1739 presentation of an interaction callback reference as described in 1740 Section 5.1. 1742 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1743 issues/58) ]] 1745 [[ See issue #59 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1746 issues/59) ]] 1748 2.5.3.1. Receive an HTTP Callback Through the Browser 1750 A callback "method" value of "redirect" indicates that the client 1751 instance will expect a call from the RO's browser using the HTTP 1752 method GET as described in Section 4.4.1. 1754 "interact": { 1755 "callback": { 1756 "method": "redirect", 1757 "uri": "https://client.example.net/return/123455", 1758 "nonce": "LKLTI25DK82FX4T4QFZC" 1759 } 1760 } 1762 Requests to the callback URI MUST be processed by the client instance 1763 as described in Section 4.4.1. 1765 Since the incoming request to the callback URL is from the RO's 1766 browser, this method is usually used when the RO and RQ are the same 1767 entity. As such, the client instance MUST ensure the RQ is present 1768 on the request to prevent substitution attacks. 1770 2.5.3.2. Receive an HTTP Direct Callback 1772 A callback "method" value of "push" indicates that the client 1773 instance will expect a call from the AS directly using the HTTP 1774 method POST as described in Section 4.4.2. 1776 "interact": { 1777 "callback": { 1778 "method": "push", 1779 "uri": "https://client.example.net/return/123455", 1780 "nonce": "LKLTI25DK82FX4T4QFZC" 1781 } 1782 } 1783 Requests to the callback URI MUST be processed by the client instance 1784 as described in Section 4.4.2. 1786 Since the incoming request to the callback URL is from the AS and not 1787 from the RO's browser, the client instance MUST NOT require the RQ to 1788 be present on the incoming HTTP request. 1790 [[ See issue #60 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1791 issues/60) ]] 1793 2.5.4. Display a Short User Code 1795 If the client instance is capable of displaying or otherwise 1796 communicating a short, human-entered code to the RO, the client 1797 instance indicates this by sending the "user_code" field with the 1798 boolean value "true". This code is to be entered at a static URL 1799 that does not change at runtime, as described in Section 3.3.4. 1801 "interact": { 1802 "user_code": true 1803 } 1805 If this interaction mode is supported for this client instance and 1806 request, the AS returns a user code and interaction URL as specified 1807 in Section 4.2. 1809 2.5.5. Indicate Desired Interaction Locales 1811 If the client instance knows the RQ's locale and language 1812 preferences, the client instance can send this information to the AS 1813 using the "ui_locales" field with an array of locale strings as 1814 defined by [RFC5646]. 1816 "interact": { 1817 "ui_locales": ["en-US", "fr-CA"] 1818 } 1820 If possible, the AS SHOULD use one of the locales in the array, with 1821 preference to the first item in the array supported by the AS. If 1822 none of the given locales are supported, the AS MAY use a default 1823 locale. 1825 2.5.6. Extending Interaction Modes 1827 Additional interaction modes are defined in a registry TBD 1828 (Section 12). 1830 2.6. Declaring Client Capabilities 1832 If the client software supports extension capabilities, the client 1833 instance MAY present them to the AS in the "capabilities" field. 1834 This field is an array of strings representing specific extensions 1835 and capabilities, as defined by a registry TBD (Section 12). 1837 "capabilities": ["ext1", "ext2"] 1839 2.7. Referencing an Existing Grant Request 1841 If the client instance has a reference handle from a previously 1842 granted request, it MAY send that reference in the "existing_grant" 1843 field. This field is a single string consisting of the "value" of 1844 the "access_token" returned in a previous request's continuation 1845 response (Section 3.1). 1847 "existing_grant": "80UPRY5NM33OMUKMKSKU" 1849 The AS MUST dereference the grant associated with the reference and 1850 process this request in the context of the referenced one. The AS 1851 MUST NOT alter the existing grant associated with the reference. 1853 [[ See issue #62 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1854 issues/62) ]] 1856 2.8. Extending The Grant Request 1858 The request object MAY be extended by registering new items in a 1859 registry TBD (Section 12). Extensions SHOULD be orthogonal to other 1860 parameters. Extensions MUST document any aspects where the extension 1861 item affects or influences the values or behavior of other request 1862 and response objects. 1864 3. Grant Response 1866 In response to a client instance's request, the AS responds with a 1867 JSON object as the HTTP entity body. Each possible field is detailed 1868 in the sections below 1870 continue (object) Indicates that the client instance can continue 1871 the request by making one or more continuation requests. 1872 Section 3.1 1874 access_token (object) A single access token that the client instance 1875 can use to call the RS on behalf of the RO. Section 3.2.1 1877 multiple_access_token (object) Multiple named access tokens that the 1878 client instance can use to call the RS on behalf of the RO. 1879 Section 3.2.2 1881 interact (object) Indicates that interaction through some set of 1882 defined mechanisms needs to take place. Section 3.3 1884 subject (object) Claims about the RO as known and declared by the 1885 AS. Section 3.4 1887 instance_id (string) An identifier this client instance instance can 1888 use to identify itself when making future requests. Section 3.5 1890 user_handle (string) An identifier this client instance instance can 1891 use to identify its current RQ when making future requests. 1892 Section 3.5 1894 error (object) An error code indicating that something has gone 1895 wrong. Section 3.6 1897 In this example, the AS is returning an interaction URL 1898 (Section 3.3.1), a callback nonce (Section 3.3.3), and a continuation 1899 response (Section 3.1). 1901 { 1902 "interact": { 1903 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 1904 "callback": "MBDOFXG4Y5CVJCX821LH" 1905 }, 1906 "continue": { 1907 "access_token": { 1908 "value": "80UPRY5NM33OMUKMKSKU", 1909 "key": true 1910 }, 1911 "uri": "https://server.example.com/tx" 1912 } 1913 } 1915 In this example, the AS is returning a bearer access token 1916 (Section 3.2.1) with a management URL and a subject identifier 1917 (Section 3.4) in the form of an email address. 1919 { 1920 "access_token": { 1921 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 1922 "key": false, 1923 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 1924 }, 1925 "subject": { 1926 "sub_ids": [ { 1927 "subject_type": "email", 1928 "email": "user@example.com", 1929 } ] 1930 } 1931 } 1933 3.1. Request Continuation 1935 If the AS determines that the request can be continued with 1936 additional requests, it responds with the "continue" field. This 1937 field contains a JSON object with the following properties. 1939 uri (string) REQUIRED. The URI at which the client instance can 1940 make continuation requests. This URI MAY vary per request, or MAY 1941 be stable at the AS if the AS includes an access token. The 1942 client instance MUST use this value exactly as given when making a 1943 continuation request (Section 5). 1945 wait (integer) RECOMMENDED. The amount of time in integer seconds 1946 the client instance SHOULD wait after receiving this continuation 1947 handle and calling the URI. 1949 access_token (object) REQUIRED. A unique access token for 1950 continuing the request, in the format specified in Section 3.2.1. 1951 This access token MUST be bound to the client instance's key used 1952 in the request and MUST NOT be a "bearer" token. As a 1953 consequence, the "key" field of this access token is always the 1954 boolean value "true". This access token MUST NOT be usable at 1955 resources outside of the AS. The client instance MUST present the 1956 access token in all requests to the continuation URI as described 1957 in Section 7. [[ See issue #66 (https://github.com/ietf-wg-gnap/ 1958 gnap-core-protocol/issues/66) ]] 1960 { 1961 "continue": { 1962 "access_token": { 1963 "value": "80UPRY5NM33OMUKMKSKU", 1964 "key": true 1965 }, 1966 "uri": "https://server.example.com/continue", 1967 "wait": 60 1968 } 1969 } 1971 The client instance can use the values of this field to continue the 1972 request as described in Section 5. Note that the client instance 1973 MUST sign all continuation requests with its key as described in 1974 Section 8 and MUST present the access token in its continuation 1975 request. 1977 This field SHOULD be returned when interaction is expected, to allow 1978 the client instance to follow up after interaction has been 1979 concluded. 1981 3.2. Access Tokens 1983 If the AS has successfully granted one or more access tokens to the 1984 client instance, the AS responds with either the "access_token" or 1985 the "multiple_access_token" field. The AS MUST NOT respond with both 1986 the "access_token" and "multiple_access_token" fields. 1988 [[ See issue #68 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1989 issues/68) ]] 1991 3.2.1. Single Access Token 1993 If the client instance has requested a single access token and the AS 1994 has granted that access token, the AS responds with the 1995 "access_token" field. The value of this field is an object with the 1996 following properties. 1998 value (string) REQUIRED. The value of the access token as a string. 1999 The value is opaque to the client instance. The value SHOULD be 2000 limited to ASCII characters to facilitate transmission over HTTP 2001 headers within other protocols without requiring additional 2002 encoding. 2004 manage (string) OPTIONAL. The management URI for this access token. 2006 If provided, the client instance MAY manage its access token as 2007 described in Section 6. This management URI is a function of the 2008 AS and is separate from the RS the client instance is requesting 2009 access to. This URI MUST NOT include the access token value and 2010 SHOULD be different for each access token issued in a request. 2012 resources (array of objects/strings) RECOMMENDED. A description of 2013 the rights associated with this access token, as defined in 2014 Section 2.1.1. If included, this MUST reflect the rights 2015 associated with the issued access token. These rights MAY vary 2016 from what was requested by the client instance. 2018 expires_in (integer) OPTIONAL. The number of seconds in which the 2019 access will expire. The client instance MUST NOT use the access 2020 token past this time. An RS MUST NOT accept an access token past 2021 this time. Note that the access token MAY be revoked by the AS or 2022 RS at any point prior to its expiration. 2024 key (object / string / boolean) REQUIRED. The key that the token is 2025 bound to. If the boolean value "true" is used, the token is bound 2026 to the key used by the client instance (Section 2.3.2) in its 2027 request for access. If the boolean value "false" is used, the 2028 token is a bearer token with no key bound to it. Otherwise, the 2029 key MUST be an object or string in a format described in 2030 Section 2.3.2, describing a public key to which the client 2031 instance can use the associated private key. The client instance 2032 MUST be able to dereference or process the key information in 2033 order to be able to sign the request. 2035 The following non-normative example shows a single bearer token with 2036 a management URL that has access to three described resources. 2038 "access_token": { 2039 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2040 "key": false, 2041 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 2042 "resources": [ 2043 { 2044 "type": "photo-api", 2045 "actions": [ 2046 "read", 2047 "write", 2048 "dolphin" 2049 ], 2050 "locations": [ 2051 "https://server.example.net/", 2052 "https://resource.local/other" 2053 ], 2054 "datatypes": [ 2055 "metadata", 2056 "images" 2057 ] 2058 }, 2059 "read", "dolphin-metadata" 2060 ] 2061 } 2063 The following non-normative example shows a single access token bound 2064 to the client instance's key, which was presented using the detached 2065 JWS (Section 8.1) binding method. 2067 "access_token": { 2068 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2069 "key": true, 2070 "resources": [ 2071 "finance", "medical" 2072 ] 2073 } 2075 If the client instance requested multiple access tokens 2076 (Section 2.1.3), the AS MUST NOT respond with a single access token 2077 structure unless the client instance sends the "split_token" flag as 2078 described in Section 2.1.4. 2080 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2081 issues/69) ]] 2083 3.2.2. Multiple Access Tokens 2085 If the client instance has requested multiple access tokens and the 2086 AS has granted at least one of them, the AS responds with the 2087 "multiple_access_tokens" field. The value of this field is a JSON 2088 object, and the property names correspond to the token identifiers 2089 chosen by the client instance in the multiple access token request 2090 (Section 2.1.3). The values of the properties of this object are 2091 access tokens as described in Section 3.2.1. 2093 In this non-normative example, two bearer tokens are issued under the 2094 names "token1" and "token2", and only the first token has a 2095 management URL associated with it. 2097 "multiple_access_tokens": { 2098 "token1": { 2099 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2100 "key": false, 2101 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2102 }, 2103 "token2": { 2104 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2105 "key": false 2106 } 2107 } 2109 Each access token corresponds to the named resources arrays in the 2110 client instance's request (Section 2.1.3). 2112 The multiple access token response MUST be used when multiple access 2113 tokens are requested, even if only one access token is issued as a 2114 result of the request. The AS MAY refuse to issue one or more of the 2115 requested access tokens, for any reason. In such cases the refused 2116 token is omitted from the response and all of the other issued access 2117 tokens are included in the response the requested names appropriate 2118 names. 2120 If the client instance requested a single access token 2121 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2122 token structure unless the client instance sends the "split_token" 2123 flag as described in Section 2.1.4. 2125 Each access token MAY have different proofing mechanisms. If 2126 management is allowed, each access token SHOULD have different 2127 management URIs. 2129 [[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2130 issues/70) ]] 2132 3.3. Interaction Modes 2134 If the client instance has indicated a capability to interact with 2135 the RO in its request (Section 2.5), and the AS has determined that 2136 interaction is both supported and necessary, the AS responds to the 2137 client instance with any of the following values in the "interact" 2138 field of the response. There is no preference order for interaction 2139 modes in the response, and it is up to the client instance to 2140 determine which ones to use. All supported interaction methods are 2141 included in the same "interact" object. 2143 redirect (string) Redirect to an arbitrary URL. Section 3.3.1 2145 app (string) Launch of an application URL. Section 3.3.2 2147 callback (string) Callback to a client instance accessible URL after 2148 interaction is completed. Section 3.3.3 2150 user_code (object) Display a short user code. Section 3.3.4 2152 Additional interaction mode responses can be defined in a registry 2153 TBD (Section 12). 2155 The AS MUST NOT respond with any interaction mode that the client 2156 instance did not indicate in its request. The AS MUST NOT respond 2157 with any interaction mode that the AS does not support. Since 2158 interaction responses include secret or unique information, the AS 2159 SHOULD respond to each interaction mode only once in an ongoing 2160 request, particularly if the client instance modifies its request 2161 (Section 5.3). 2163 3.3.1. Redirection to an arbitrary URL 2165 If the client instance indicates that it can redirect to an arbitrary 2166 URL (Section 2.5.1) and the AS supports this mode for the client 2167 instance's request, the AS responds with the "redirect" field, which 2168 is a string containing the URL to direct the RQ to. This URL MUST be 2169 unique for the request and MUST NOT contain any security-sensitive 2170 information. 2172 "interact": { 2173 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2174 } 2176 The interaction URL returned represents a function of the AS but MAY 2177 be completely distinct from the URL the client instance uses to 2178 request access (Section 2), allowing an AS to separate its user- 2179 interactive functionality from its back-end security functionality. 2181 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2182 issues/72) ]] 2184 The client instance sends the RQ to the URL to interact with the AS. 2185 The client instance MUST NOT alter the URL in any way. The means for 2186 the client instance to send the RQ to this URL is out of scope of 2187 this specification, but common methods include an HTTP redirect, 2188 launching the system browser, displaying a scannable code, or 2189 printing out the URL in an interactive console. 2191 3.3.2. Launch of an application URL 2193 If the client instance indicates that it can launch an application 2194 URL (Section 2.5.2) and the AS supports this mode for the client 2195 instance's request, the AS responds with the "app" field, which is a 2196 string containing the URL to direct the RQ to. This URL MUST be 2197 unique for the request and MUST NOT contain any security-sensitive 2198 information. 2200 "interact": { 2201 "app": "https://app.example.com/launch?tx=4CF492MLV" 2202 } 2204 The client instance launches the URL as appropriate on its platform, 2205 and the means for the client instance to launch this URL is out of 2206 scope of this specification. The client instance MUST NOT alter the 2207 URL in any way. The client instance MAY attempt to detect if an 2208 installed application will service the URL being sent before 2209 attempting to launch the application URL. 2211 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2212 issues/71) ]] 2214 3.3.3. Post-interaction Callback to a Client Instance Accessible URL 2216 If the client instance indicates that it can receive a 2217 post-interaction callback on a URL (Section 2.5.3) and the AS 2218 supports this mode for the client instance's request, the AS responds 2219 with a "callback" field containing a nonce that the client instance 2220 will use in validating the callback as defined in Section 4.4.1. 2222 "interact": { 2223 "callback": "MBDOFXG4Y5CVJCX821LH" 2224 } 2226 When the RO completes interaction at the AS, the AS MUST call the 2227 client instance's callback URL using the method indicated in the 2228 callback request (Section 2.5.3) as described in Section 4.4.1. 2230 If the AS returns a "callback" nonce, the client instance MUST NOT 2231 continue a grant request before it receives the associated 2232 interaction reference on the callback URI. 2234 3.3.4. Display of a Short User Code 2236 If the client instance indicates that it can display a short 2237 user-typeable code (Section 2.5.4) and the AS supports this mode for 2238 the client instance's request, the AS responds with a "user_code" 2239 field. This field is an object that contains the following members. 2241 code (string) REQUIRED. A unique short code that the user can type 2242 into an authorization server. This string MUST be case- 2243 insensitive, MUST consist of only easily typeable characters (such 2244 as letters or numbers). The time in which this code will be 2245 accepted SHOULD be short lived, such as several minutes. It is 2246 RECOMMENDED that this code be no more than eight characters in 2247 length. 2249 url (string) RECOMMENDED. The interaction URL that the client 2250 instance will direct the RO to. This URL MUST be stable at the AS 2251 such that client instance's can be statically configured with it. 2253 "interact": { 2254 "user_code": { 2255 "code": "A1BC-3DFF", 2256 "url": "https://srv.ex/device" 2257 } 2258 } 2260 The client instance MUST communicate the "code" to the RQ in some 2261 fashion, such as displaying it on a screen or reading it out audibly. 2262 The "code" is a one-time-use credential that the AS uses to identify 2263 the pending request from the client instance. When the RO enters 2264 this code (Section 4.2) into the AS, the AS MUST determine the 2265 pending request that it was associated with. If the AS does not 2266 recognize the entered code, the AS MUST display an error to the user. 2267 If the AS detects too many unrecognized codes entered, it SHOULD 2268 display an error to the user. 2270 The client instance SHOULD also communicate the URL if possible to 2271 facilitate user interaction, but since the URL should be stable, the 2272 client instance should be able to safely decide to not display this 2273 value. As this interaction mode is designed to facilitate 2274 interaction via a secondary device, it is not expected that the 2275 client instance redirect the RQ to the URL given here at runtime. 2276 Consequently, the URL needs to be stable enough that a client 2277 instance could be statically configured with it, perhaps referring 2278 the RQ to the URL via documentation instead of through an interactive 2279 means. If the client instance is capable of communicating an 2280 arbitrary URL to the RQ, such as through a scannable code, the client 2281 instance can use the "redirect" (Section 2.5.1) mode for this purpose 2282 instead of or in addition to the user code mode. 2284 The interaction URL returned represents a function of the AS but MAY 2285 be completely distinct from the URL the client instance uses to 2286 request access (Section 2), allowing an AS to separate its user- 2287 interactive functionality from its back-end security functionality. 2289 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2290 issues/72) ]] 2292 3.3.5. Extending Interaction Mode Responses 2294 Extensions to this specification can define new interaction mode 2295 responses in a registry TBD (Section 12). Extensions MUST document 2296 the corresponding interaction request. 2298 3.4. Returning User Information 2300 If information about the RO is requested and the AS grants the client 2301 instance access to that data, the AS returns the approved information 2302 in the "subject" response field. This field is an object with the 2303 following OPTIONAL properties. 2305 sub_ids (array of objects) An array of subject identifiers for the 2306 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2308 assertions (object) An object containing assertions as values keyed 2309 on the assertion type defined by a registry TBD (Section 12). [[ 2310 See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2311 issues/41) ]] 2313 updated_at (string) Timestamp as an ISO8610 date string, indicating 2314 when the identified account was last updated. The client instance 2315 MAY use this value to determine if it needs to request updated 2316 profile information through an identity API. The definition of 2317 such an identity API is out of scope for this specification. 2319 "subject": { 2320 "sub_ids": [ { 2321 "subject_type": "email", 2322 "email": "user@example.com", 2323 } ], 2324 "assertions": { 2325 "id_token": "eyj..." 2326 } 2327 } 2329 The AS MUST return the "subject" field only in cases where the AS is 2330 sure that the RO and the RQ are the same party. This can be 2331 accomplished through some forms of interaction with the RO 2332 (Section 4). 2334 Subject identifiers returned by the AS SHOULD uniquely identify the 2335 RO at the AS. Some forms of subject identifier are opaque to the 2336 client instance (such as the subject of an issuer and subject pair), 2337 while others forms (such as email address and phone number) are 2338 intended to allow the client instance to correlate the identifier 2339 with other account information at the client instance. The client 2340 instance MUST NOT request or use any returned subject identifiers for 2341 communication purposes (see Section 2.2). That is, a subject 2342 identifier returned in the format of an email address or a phone 2343 number only identifies the RO to the AS and does not indicate that 2344 the AS has validated that the represented email address or phone 2345 number in the identifier is suitable for communication with the 2346 current user. To get such information, the client instance MUST use 2347 an identity protocol to request and receive additional identity 2348 claims. The details of an identity protocol and associated schema 2349 are outside the scope of this specification. 2351 [[ See issue #75 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2352 issues/75) ]] 2354 Extensions to this specification MAY define additional response 2355 properties in a registry TBD (Section 12). 2357 3.5. Returning Dynamically-bound Reference Handles 2359 Many parts of the client instance's request can be passed as either a 2360 value or a reference. The use of a reference in place of a value 2361 allows for a client instance to optimize requests to the AS. 2363 Some references, such as for the client instance's identity 2364 (Section 2.3.1) or the requested resources (Section 2.1.2), can be 2365 managed statically through an admin console or developer portal 2366 provided by the AS or RS. The developer of the client software can 2367 include these values in their code for a more efficient and compact 2368 request. 2370 If desired, the AS MAY also generate and return some of these 2371 references dynamically to the client instance in its response to 2372 facilitate multiple interactions with the same software. The client 2373 instance SHOULD use these references in future requests in lieu of 2374 sending the associated data value. These handles are intended to be 2375 used on future requests. 2377 Dynamically generated handles are string values that MUST be 2378 protected by the client instance as secrets. Handle values MUST be 2379 unguessable and MUST NOT contain any sensitive information. Handle 2380 values are opaque to the client instance. 2382 All dynamically generated handles are returned as fields in the root 2383 JSON object of the response. This specification defines the 2384 following dynamic handle returns, additional handles can be defined 2385 in a registry TBD (Section 12). 2387 instance_id (string) A string value used to represent the 2388 information in the "client" object that the client instance can 2389 use in a future request, as described in Section 2.3.1. 2391 user_handle (string) A string value used to represent the current 2392 user. The client instance can use in a future request, as 2393 described in Section 2.4.1. 2395 This non-normative example shows two handles along side an issued 2396 access token. 2398 { 2399 "user_handle": "XUT2MFM1XBIKJKSDU8QM", 2400 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2401 "access_token": { 2402 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2403 "key": false 2404 } 2405 } 2407 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2408 issues/77) ]] 2410 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2411 issues/78) ]] 2413 3.6. Error Response 2415 If the AS determines that the request cannot be issued for any 2416 reason, it responds to the client instance with an error message. 2418 error (string) The error code. 2420 { 2422 "error": "user_denied" 2424 } 2426 The error code is one of the following, with additional values 2427 available in a registry TBD (Section 12): 2429 user_denied The RO denied the request. 2431 too_fast The client instance did not respect the timeout in the wait 2432 response. 2434 unknown_request The request referenced an unknown ongoing access 2435 request. 2437 [[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2438 issues/79) ]] 2440 3.7. Extending the Response 2442 Extensions to this specification MAY define additional fields for the 2443 grant response in a registry TBD (Section 12). 2445 4. Interaction at the AS 2447 If the client instance indicates that it is capable of driving 2448 interaction with the RO in its request (Section 2.5), and the AS 2449 determines that interaction is required and responds to one or more 2450 of the client instance's interaction modes, the client instance 2451 SHOULD initiate one of the returned interaction modes in the response 2452 (Section 3.3). 2454 When the RO is interacting with the AS, the AS MAY perform whatever 2455 actions it sees fit, including but not limited to: 2457 * authenticate the current user (who may be the RQ) as the RO 2458 * gather consent and authorization from the RO for access to 2459 requested resources and direct information 2461 * allow the RO to modify the parameters of the request (such as 2462 disallowing some requested resources or specifying an account or 2463 record) 2465 * provide warnings to the RO about potential attacks or negative 2466 effects of the requested information 2468 4.1. Interaction at a Redirected URI 2470 When the RO is directed to the AS through the "redirect" 2471 (Section 3.3.1) mode, the AS can interact with the RO through their 2472 web browser to authenticate the user as an RO and gather their 2473 consent. Note that since the client instance does not add any 2474 parameters to the URL, the AS MUST determine the grant request being 2475 referenced from the URL value itself. If the URL cannot be 2476 associated with a currently active request, the AS MUST display an 2477 error to the RO and MUST NOT attempt to redirect the RO back to any 2478 client instance even if a callback is supplied (Section 2.5.3). 2480 The interaction URL MUST be reachable from the RO's browser, though 2481 note that the RO MAY open the URL on a separate device from the 2482 client instance itself. The interaction URL MUST be accessible from 2483 an HTTP GET request, and MUST be protected by HTTPS or equivalent 2484 means. 2486 With this method, it is common for the RO to be the same party as the 2487 RQ, since the client instance has to communicate the redirection URI 2488 to the RQ. 2490 4.2. Interaction at the User Code URI 2492 When the RO is directed to the AS through the "user_code" 2493 (Section 3.3.4) mode, the AS can interact with the RO through their 2494 web browser to collect the user code, authenticate the user as an RO, 2495 and gather their consent. Note that since the URL itself is static, 2496 the AS MUST determine the grant request being referenced from the 2497 user code value itself. If the user code cannot be associated with a 2498 currently active request, the AS MUST display an error to the RO and 2499 MUST NOT attempt to redirect the RO back to any client instance even 2500 if a callback is supplied (Section 2.5.3). 2502 The user code URL MUST be reachable from the RO's browser, though 2503 note that the RO MAY open the URL on a separate device from the 2504 client instance itself. The user code URL MUST be accessible from an 2505 HTTP GET request, and MUST be protected by HTTPS or equivalent means. 2507 While it is common for the RO to be the same party as the RQ, since 2508 the client instance has to communicate the user code to someone, 2509 there are cases where the RQ and RO are separate parties and the 2510 authorization happens asynchronously. 2512 4.3. Interaction through an Application URI 2514 When the client instance successfully launches an application through 2515 the "app" mode (Section 3.3.2), the AS interacts with the RO through 2516 that application to authenticate the user as the RO and gather their 2517 consent. The details of this interaction are out of scope for this 2518 specification. 2520 4.4. Post-Interaction Completion 2522 Upon completing an interaction with the RO, if a "callback" 2523 (Section 3.3.3) mode is available with the current request, the AS 2524 MUST follow the appropriate method at the end of interaction to allow 2525 the client instance to continue. If this mode is not available, the 2526 AS SHOULD instruct the RO to return to their client instance upon 2527 completion. Note that these steps still take place in most error 2528 cases, such as when the RO has denied access. This pattern allows 2529 the client instance to potentially recover from the error state 2530 without restarting the request from scratch by modifying its request 2531 or providing additional information directly to the AS. 2533 The AS MUST create an interaction reference and associate that 2534 reference with the current interaction and the underlying pending 2535 request. This value MUST be sufficiently random so as not to be 2536 guessable by an attacker. The interaction reference MUST be one- 2537 time-use. 2539 The AS MUST calculate a hash value based on the client instance and 2540 AS nonces and the interaction reference, as described in 2541 Section 4.4.3. The client instance will use this value to validate 2542 the return call from the AS. 2544 The AS then MUST send the hash and interaction reference based on the 2545 interaction finalization mode as described in the following sections. 2547 4.4.1. Completing Interaction with a Browser Redirect to the Callback 2548 URI 2550 When using the "callback" interaction mode (Section 3.3.3) with the 2551 "redirect" method, the AS signals to the client instance that 2552 interaction is complete and the request can be continued by directing 2553 the RO (in their browser) back to the client instance's callback URL 2554 sent in the callback request (Section 2.5.3.1). 2556 The AS secures this callback by adding the hash and interaction 2557 reference as query parameters to the client instance's callback URL. 2559 hash REQUIRED. The interaction hash value as described in 2560 Section 4.4.3. 2562 interact_ref REQUIRED. The interaction reference generated for this 2563 interaction. 2565 The means of directing the RO to this URL are outside the scope of 2566 this specification, but common options include redirecting the RO 2567 from a web page and launching the system browser with the target URL. 2569 https://client.example.net/return/123455 2570 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2571 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2573 When receiving the request, the client instance MUST parse the query 2574 parameters to calculate and validate the hash value as described in 2575 Section 4.4.3. If the hash validates, the client instance sends a 2576 continuation request to the AS as described in Section 5.1 using the 2577 interaction reference value received here. 2579 4.4.2. Completing Interaction with a Direct HTTP Request Callback 2581 When using the "callback" interaction mode (Section 3.3.3) with the 2582 "push" method, the AS signals to the client instance that interaction 2583 is complete and the request can be continued by sending an HTTP POST 2584 request to the client instance's callback URL sent in the callback 2585 request (Section 2.5.3.2). 2587 The entity message body is a JSON object consisting of the following 2588 two fields: 2590 hash (string) REQUIRED. The interaction hash value as described in 2591 Section 4.4.3. 2593 interact_ref (string) REQUIRED. The interaction reference generated 2594 for this interaction. 2596 POST /push/554321 HTTP/1.1 2597 Host: client.example.net 2598 Content-Type: application/json 2600 { 2601 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2602 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2603 } 2604 When receiving the request, the client instance MUST parse the JSON 2605 object and validate the hash value as described in Section 4.4.3. If 2606 the hash validates, the client instance sends a continuation request 2607 to the AS as described in Section 5.1 using the interaction reference 2608 value received here. 2610 4.4.3. Calculating the interaction hash 2612 The "hash" parameter in the request to the client instance's callback 2613 URL ties the front channel response to an ongoing request by using 2614 values known only to the parties involved. This security mechanism 2615 allows the client instance to protect itself against several kinds of 2616 session fixation and injection attacks. The AS MUST always provide 2617 this hash, and the client instance MUST validate the hash when 2618 received. 2620 To calculate the "hash" value, the party doing the calculation first 2621 takes the "nonce" value sent by the client instance in the 2622 interaction section of the initial request (Section 2.5.3), the AS's 2623 nonce value from the callback response (Section 3.3.3), and the 2624 "interact_ref" sent to the client instance's callback URL. These 2625 three values are concatenated to each other in this order using a 2626 single newline character as a separator between the fields. There is 2627 no padding or whitespace before or after any of the lines, and no 2628 trailing newline character. 2630 VJLO6A4CAYLBXHTR0KRO 2631 MBDOFXG4Y5CVJCX821LH 2632 4IFWWIKYBC2PQ6U56NL1 2634 The party then hashes this string with the appropriate algorithm 2635 based on the "hash_method" parameter of the "callback". If the 2636 "hash_method" value is not present in the client instance's request, 2637 the algorithm defaults to "sha3". 2639 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2640 issues/56) ]] 2642 4.4.3.1. SHA3-512 2644 The "sha3" hash method consists of hashing the input string with the 2645 512-bit SHA3 algorithm. The byte array is then encoded using URL 2646 Safe Base64 with no padding. The resulting string is the hash value. 2648 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 2649 4.4.3.2. SHA2-512 2651 The "sha2" hash method consists of hashing the input string with the 2652 512-bit SHA2 algorithm. The byte array is then encoded using URL 2653 Safe Base64 with no padding. The resulting string is the hash value. 2655 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bpj84rh4mC9aE9x7HPBFcIHw 2657 5. Continuing a Grant Request 2659 While it is possible for the AS to return a Section 3 with all the 2660 client instance's requested information (including access tokens 2661 (Section 3.2) and direct user information (Section 3.4)), it's more 2662 common that the AS and the client instance will need to communicate 2663 several times over the lifetime of an access grant. This is often 2664 part of facilitating interaction (Section 4), but it could also be 2665 used to allow the AS and client instance to continue negotiating the 2666 parameters of the original grant request (Section 2). 2668 To enable this ongoing negotiation, the AS provides a continuation 2669 API to the client software. The AS returns a "continue" field in the 2670 response (Section 3.1) that contains information the client instance 2671 needs to access this API, including a URI to access as well as an 2672 access token to use during the continued requests. 2674 The access token is initially bound to the same key and method the 2675 client instance used to make the initial request. As a consequence, 2676 when the client instance makes any calls to the continuation URL, the 2677 client instance MUST present the access token as described in 2678 Section 7 and present proof of the client instance's key (or its most 2679 recent rotation) by signing the request as described in Section 8. 2681 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2682 issues/85) ]] 2684 For example, here the client instance makes a POST request to a 2685 unique URI and signs the request with detached JWS: 2687 POST /continue/KSKUOMUKM HTTP/1.1 2688 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2689 Host: server.example.com 2690 Detached-JWS: ejy0... 2692 The AS MUST be able to tell from the client instance's request which 2693 specific ongoing request is being accessed, using a combination of 2694 the continuation URL, the provided access token, and the client 2695 instance identified by the key signature. If the AS cannot determine 2696 a single active grant request to map the continuation request to, the 2697 AS MUST return an error. 2699 The ability to continue an already-started request allows the client 2700 instance to perform several important functions, including presenting 2701 additional information from interaction, modifying the initial 2702 request, and getting the current state of the request. 2704 All requests to the continuation API are protected by this bound 2705 access token. For example, here the client instance makes a POST 2706 request to a stable continuation endpoint URL with the interaction 2707 reference (Section 5.1), includes the access token, and signs with 2708 detached JWS: 2710 POST /continue HTTP/1.1 2711 Host: server.example.com 2712 Content-type: application/json 2713 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2714 Detached-JWS: ejy0... 2716 { 2717 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2718 } 2720 If a "wait" parameter was included in the continuation response 2721 (Section 3.1), the client instance MUST NOT call the continuation URI 2722 prior to waiting the number of seconds indicated. If no "wait" 2723 period is indicated, the client instance SHOULD wait at least 5 2724 seconds. If the client instance does not respect the given wait 2725 period, the AS MUST return an error. [[ See issue #86 2726 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/86) ]] 2728 The response from the AS is a JSON object and MAY contain any of the 2729 fields described in Section 3, as described in more detail in the 2730 sections below. 2732 If the AS determines that the client instance can make a further 2733 continuation request, the AS MUST include a new "continue" response 2734 (Section 3.1). The new "continue" response MUST include a bound 2735 access token as well, and this token SHOULD be a new access token, 2736 invalidating the previous access token. If the AS does not return a 2737 new "continue" response, the client instance MUST NOT make an 2738 additional continuation request. If a client instance does so, the 2739 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 2740 wg-gnap/gnap-core-protocol/issues/87) ]] 2742 For continuation functions that require the client instance to send a 2743 message body, the body MUST be a JSON object. 2745 5.1. Continuing After a Completed Interaction 2747 When the AS responds to the client instance's "callback" parameter as 2748 in Section 4.4.1, this response includes an interaction reference. 2749 The client instance MUST include that value as the field 2750 "interact_ref" in a POST request to the continuation URI. 2752 POST /continue HTTP/1.1 2753 Host: server.example.com 2754 Content-type: application/json 2755 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2756 Detached-JWS: ejy0... 2758 { 2759 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2760 } 2762 Since the interaction reference is a one-time-use value as described 2763 in Section 4.4.1, if the client instance needs to make additional 2764 continuation calls after this request, the client instance MUST NOT 2765 include the interaction reference. If the AS detects a client 2766 instance submitting the same interaction reference multiple times, 2767 the AS MUST return an error and SHOULD invalidate the ongoing 2768 request. 2770 The Section 3 MAY contain any newly-created access tokens 2771 (Section 3.2) or newly-released subject claims (Section 3.4). The 2772 response MAY contain a new "continue" response (Section 3.1) as 2773 described above. The response SHOULD NOT contain any interaction 2774 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 2775 wg-gnap/gnap-core-protocol/issues/89) ]] 2777 For example, if the request is successful in causing the AS to issue 2778 access tokens and release subject claims, the response could look 2779 like this: 2781 { 2782 "access_token": { 2783 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2784 "key": false, 2785 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2786 }, 2787 "subject": { 2788 "sub_ids": [ { 2789 "subject_type": "email", 2790 "email": "user@example.com", 2791 } ] 2792 } 2793 } 2795 With this example, the client instance can not make an additional 2796 continuation request because a "continue" field is not included. 2798 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2799 issues/88) ]] 2801 5.2. Continuing During Pending Interaction 2803 When the client instance does not include a "callback" parameter, the 2804 client instance will often need to poll the AS until the RO has 2805 authorized the request. To do so, the client instance makes a POST 2806 request to the continuation URI as in Section 5.1, but does not 2807 include a message body. 2809 POST /continue HTTP/1.1 2810 Host: server.example.com 2811 Content-type: application/json 2812 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2813 Detached-JWS: ejy0... 2815 The Section 3 MAY contain any newly-created access tokens 2816 (Section 3.2) or newly-released subject claims (Section 3.4). The 2817 response MAY contain a new "continue" response (Section 3.1) as 2818 described above. If a "continue" field is included, it SHOULD 2819 include a "wait" field to facilitate a reasonable polling rate by the 2820 client instance. The response SHOULD NOT contain interaction 2821 responses (Section 3.3). 2823 For example, if the request has not yet been authorized by the RO, 2824 the AS could respond by telling the client instance to make another 2825 continuation request in the future. In this example, a new, unique 2826 access token has been issued for the call, which the client instance 2827 will use in its next continuation request. 2829 { 2830 "continue": { 2831 "access_token": { 2832 "value": "33OMUKMKSKU80UPRY5NM", 2833 "key": true 2834 }, 2835 "uri": "https://server.example.com/continue", 2836 "wait": 30 2837 } 2838 } 2840 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2841 issues/90) ]] 2843 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2844 issues/91) ]] 2846 If the request is successful in causing the AS to issue access tokens 2847 and release subject claims, the response could look like this 2848 example: 2850 { 2851 "access_token": { 2852 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2853 "key": false, 2854 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L" 2855 }, 2856 "subject": { 2857 "sub_ids": [ { 2858 "subject_type": "email", 2859 "email": "user@example.com", 2860 } ] 2861 } 2862 } 2864 5.3. Modifying an Existing Request 2866 The client instance might need to modify an ongoing request, whether 2867 or not tokens have already been issued or claims have already been 2868 released. In such cases, the client instance makes an HTTP PATCH 2869 request to the continuation URI and includes any fields it needs to 2870 modify. Fields that aren't included in the request are considered 2871 unchanged from the original request. 2873 The client instance MAY include the "resources" and "subject" fields 2874 as described in Section 2.1 and Section 2.2. Inclusion of these 2875 fields override any values in the initial request, which MAY trigger 2876 additional requirements and policies by the AS. For example, if the 2877 client instance is asking for more access, the AS could require 2878 additional interaction with the RO to gather additional consent. If 2879 the client instance is asking for more limited access, the AS could 2880 determine that sufficient authorization has been granted to the 2881 client instance and return the more limited access rights 2882 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 2883 core-protocol/issues/92) ]] 2885 The client instance MAY include the "interact" field as described in 2886 Section 2.5. Inclusion of this field indicates that the client 2887 instance is capable of driving interaction with the RO, and this 2888 field replaces any values from a previous request. The AS MAY 2889 respond to any of the interaction responses as described in 2890 Section 3.3, just like it would to a new request. 2892 The client instance MAY include the "user" field as described in 2893 Section 2.4 to present new assertions or information about the RQ. 2894 [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2895 issues/93) ]] 2897 The client instance MUST NOT include the "client" section of the 2898 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 2899 protocol/issues/94) ]] 2901 The client instance MAY include post-interaction responses such as 2902 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 2903 wg-gnap/gnap-core-protocol/issues/95) ]] 2905 Modification requests MUST NOT alter previously-issued access tokens. 2906 Instead, any access tokens issued from a continuation are considered 2907 new, separate access tokens. The AS MAY revoke existing access 2908 tokens after a modification has occurred. [[ See issue #96 2909 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 2911 If the modified request can be granted immediately by the AS, the 2912 Section 3 MAY contain any newly-created access tokens (Section 3.2) 2913 or newly-released subject claims (Section 3.4). The response MAY 2914 contain a new "continue" response (Section 3.1) as described above. 2915 If interaction can occur, the response SHOULD contain interaction 2916 responses (Section 3.3) as well. 2918 For example, a client instance initially requests a set of resources 2919 using references: 2921 POST /tx HTTP/1.1 2922 Host: server.example.com 2923 Content-type: application/json 2924 Detached-JWS: ejy0... 2926 { 2927 "resources": [ 2928 "read", "write" 2929 ], 2930 "interact": { 2931 "redirect": true, 2932 "callback": { 2933 "method": "redirect", 2934 "uri": "https://client.example.net/return/123455", 2935 "nonce": "LKLTI25DK82FX4T4QFZC" 2936 } 2937 }, 2938 "client": "987YHGRT56789IOLK" 2939 } 2941 Access is granted by the RO, and a token is issued by the AS. In its 2942 final response, the AS includes a "continue" field, which includes a 2943 separate access token for accessing the continuation API: 2945 { 2946 "continue": { 2947 "access_token": { 2948 "value": "80UPRY5NM33OMUKMKSKU", 2949 "key": true 2950 }, 2951 "uri": "https://server.example.com/continue", 2952 "wait": 30 2953 }, 2954 "access_token": { 2955 "value": "RP1LT0-OS9M2P_R64TB", 2956 "key": false, 2957 "resources": [ 2958 "read", "write" 2959 ] 2960 } 2961 } 2963 This "continue" field allows the client instance to make an eventual 2964 continuation call. In the future, the client instance realizes that 2965 it no longer needs "write" access and therefore modifies its ongoing 2966 request, here asking for just "read" access instead of both "read" 2967 and "write" as before. 2969 PATCH /continue HTTP/1.1 2970 Host: server.example.com 2971 Content-type: application/json 2972 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2973 Detached-JWS: ejy0... 2975 { 2976 "resources": [ 2977 "read" 2978 ] 2979 ... 2980 } 2982 The AS replaces the previous "resources" from the first request, 2983 allowing the AS to determine if any previously-granted consent 2984 already applies. In this case, the AS would likely determine that 2985 reducing the breadth of the requested access means that new access 2986 tokens can be issued to the client instance. The AS would likely 2987 revoke previously-issued access tokens that had the greater access 2988 rights associated with them. 2990 { 2991 "continue": { 2992 "access_token": { 2993 "value": "M33OMUK80UPRY5NMKSKU", 2994 "key": true 2995 }, 2996 "uri": "https://server.example.com/continue", 2997 "wait": 30 2998 }, 2999 "access_token": { 3000 "value": "0EVKC7-2ZKwZM_6N760", 3001 "key": false, 3002 "resources": [ 3003 "read" 3004 ] 3005 } 3006 } 3008 For another example, the client instance initially requests read-only 3009 access but later needs to step up its access. The initial request 3010 could look like this example. 3012 POST /tx HTTP/1.1 3013 Host: server.example.com 3014 Content-type: application/json 3015 Detached-JWS: ejy0... 3017 { 3018 "resources": [ 3019 "read" 3020 ], 3021 "interact": { 3022 "redirect": true, 3023 "callback": { 3024 "method": "redirect", 3025 "uri": "https://client.example.net/return/123455", 3026 "nonce": "LKLTI25DK82FX4T4QFZC" 3027 } 3028 }, 3029 "client": "987YHGRT56789IOLK" 3030 } 3032 Access is granted by the RO, and a token is issued by the AS. In its 3033 final response, the AS includes a "continue" field: 3035 { 3036 "continue": { 3037 "access_token": { 3038 "value": "80UPRY5NM33OMUKMKSKU", 3039 "key": true 3040 }, 3041 "uri": "https://server.example.com/continue", 3042 "wait": 30 3043 }, 3044 "access_token": { 3045 "value": "RP1LT0-OS9M2P_R64TB", 3046 "key": false, 3047 "resources": [ 3048 "read" 3049 ] 3050 } 3051 } 3053 This allows the client instance to make an eventual continuation 3054 call. The client instance later realizes that it now needs "write" 3055 access in addition to the "read" access. Since this is an expansion 3056 of what it asked for previously, the client instance also includes a 3057 new interaction section in case the AS needs to interact with the RO 3058 again to gather additional authorization. Note that the client 3059 instance's nonce and callback are different from the initial request. 3061 Since the original callback was already used in the initial exchange, 3062 and the callback is intended for one-time-use, a new one needs to be 3063 included in order to use the callback again. 3065 [[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3066 issues/97) ]] 3068 PATCH /continue HTTP/1.1 3069 Host: server.example.com 3070 Content-type: application/json 3071 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3072 Detached-JWS: ejy0... 3074 { 3075 "resources": [ 3076 "read", "write" 3077 ], 3078 "interact": { 3079 "redirect": true, 3080 "callback": { 3081 "method": "redirect", 3082 "uri": "https://client.example.net/return/654321", 3083 "nonce": "K82FX4T4LKLTI25DQFZC" 3084 } 3085 } 3086 } 3088 From here, the AS can determine that the client instance is asking 3089 for more than it was previously granted, but since the client 3090 instance has also provided a mechanism to interact with the RO, the 3091 AS can use that to gather the additional consent. The protocol 3092 continues as it would with a new request. Since the old access 3093 tokens are good for a subset of the rights requested here, the AS 3094 might decide to not revoke them. However, any access tokens granted 3095 after this update process are new access tokens and do not modify the 3096 rights of existing access tokens. 3098 5.4. Getting the Current State of a Grant Request 3100 If the client instance needs to get the current state of an ongoing 3101 grant request, it makes an HTTP GET request to the continuation URI. 3102 This request MUST NOT alter the grant request in any fashion, 3103 including causing the issuance of new access tokens or modification 3104 of interaction parameters. 3106 The AS MAY include existing access tokens and previously-released 3107 subject claims in the response. The AS MUST NOT issue a new access 3108 token or release a new subject claim in response to this request. 3110 GET /continue HTTP/1.1 3111 Host: server.example.com 3112 Content-type: application/json 3113 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3114 Detached-JWS: ejy0... 3116 The response MAY include any fields described Section 3 that are 3117 applicable to this ongoing request, including the most recently 3118 issued access tokens, any released subject claims, and any currently 3119 active interaction modes. The response MAY contain a new "continue" 3120 response (Section 3.1) as described above. 3122 [[ See issue #98 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3123 issues/98) ]] 3125 5.5. Canceling a Grant Request 3127 If the client instance wishes to cancel an ongoing grant request, it 3128 makes an HTTP DELETE request to the continuation URI. 3130 DELETE /continue HTTP/1.1 3131 Host: server.example.com 3132 Content-type: application/json 3133 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3134 Detached-JWS: ejy0... 3136 If the request is successfully cancelled, the AS responds with an 3137 HTTP 202. The AS MUST revoke all associated access tokens, if 3138 possible. 3140 6. Token Management 3142 If an access token response includes the "manage" parameter as 3143 described in Section 3.2.1, the client instance MAY call this URL to 3144 manage the access token with any of the actions defined in the 3145 following sections. Other actions are undefined by this 3146 specification. 3148 The access token being managed acts as the access element for its own 3149 management API. The client instance MUST present proof of an 3150 appropriate key along with the access token. 3152 If the token is sender-constrained (i.e., not a bearer token), it 3153 MUST be sent with the appropriate binding for the access token 3154 (Section 7). 3156 If the token is a bearer token, the client instance MUST present 3157 proof of the same key identified in the initial request 3158 (Section 2.3.2) as described in Section 8. 3160 The AS MUST validate the proof and assure that it is associated with 3161 either the token itself or the client instance the token was issued 3162 to, as appropriate for the token's presentation type. 3164 [[ See issue #99 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3165 issues/99) ]] 3167 6.1. Rotating the Access Token 3169 The client instance makes an HTTP POST to the token management URI, 3170 sending the access token in the appropriate header and signing the 3171 request with the appropriate key. 3173 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3174 Host: server.example.com 3175 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3176 Detached-JWS: eyj0.... 3178 The AS validates that the token presented is associated with the 3179 management URL, that the AS issued the token to the given client 3180 instance, and that the presented key is appropriate to the token. 3182 If the access token has expired, the AS SHOULD honor the rotation 3183 request to the token management URL since it is likely that the 3184 client instance is attempting to refresh the expired token. To 3185 support this, the AS MAY apply different lifetimes for the use of the 3186 token in management vs. its use at an RS. An AS MUST NOT honor a 3187 rotation request for an access token that has been revoked, either by 3188 the AS or by the client instance through the token management URI 3189 (Section 6.2). 3191 If the token is validated and the key is appropriate for the request, 3192 the AS MUST invalidate the current access token associated with this 3193 URL, if possible, and return a new access token response as described 3194 in Section 3.2.1, unless the "multi_token" flag is specified in the 3195 request. The value of the access token MUST NOT be the same as the 3196 current value of the access token used to access the management API. 3197 The response MAY include an updated access token management URL as 3198 well, and if so, the client instance MUST use this new URL to manage 3199 the new access token. [[ See issue #101 (https://github.com/ietf-wg- 3200 gnap/gnap-core-protocol/issues/101) ]] 3202 [[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core- 3203 protocol/issues/102) ]] 3205 { 3206 "access_token": { 3207 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3208 "key": false, 3209 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 3210 "resources": [ 3211 { 3212 "type": "photo-api", 3213 "actions": [ 3214 "read", 3215 "write", 3216 "dolphin" 3217 ], 3218 "locations": [ 3219 "https://server.example.net/", 3220 "https://resource.local/other" 3221 ], 3222 "datatypes": [ 3223 "metadata", 3224 "images" 3225 ] 3226 }, 3227 "read", "dolphin-metadata" 3228 ] 3229 } 3230 } 3232 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3233 protocol/issues/103) ]] 3235 6.2. Revoking the Access Token 3237 If the client instance wishes to revoke the access token proactively, 3238 such as when a user indicates to the client instance that they no 3239 longer wish for it to have access or the client instance application 3240 detects that it is being uninstalled, the client instance can use the 3241 token management URI to indicate to the AS that the AS should 3242 invalidate the access token for all purposes. 3244 The client instance makes an HTTP DELETE request to the token 3245 management URI, presenting the access token and signing the request 3246 with the appropriate key. 3248 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3249 Host: server.example.com 3250 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3251 Detached-JWS: eyj0.... 3253 If the key presented is associated with the token (or the client 3254 instance, in the case of a bearer token), the AS MUST invalidate the 3255 access token, if possible, and return an HTTP 204 response code. 3257 204 No Content 3259 Though the AS MAY revoke an access token at any time for any reason, 3260 the token management function is specifically for the client 3261 instance's use. If the access token has already expired or has been 3262 revoked through other means, the AS SHOULD honor the revocation 3263 request to the token management URL as valid, since the end result is 3264 still the token not being usable. 3266 7. Using Access Tokens 3268 The method the client instance uses to send an access token to the RS 3269 depends on the value of the "key" and "proof" parameters in the 3270 access token response (Section 3.2.1). 3272 If the key value is the boolean "false", the access token is a bearer 3273 token sent using the HTTP Header method defined in [RFC6750]. 3275 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3277 The form parameter and query parameter methods of [RFC6750] MUST NOT 3278 be used. 3280 If the "key" value is the boolean "true", the access token MUST be 3281 sent to the RS using the same key and proofing mechanism that the 3282 client instance used in its initial request. 3284 If the "key" value is an object, the value of the "proof" field 3285 within the key indicates the particular proofing mechanism to use. 3286 The access token is sent using the HTTP authorization scheme "GNAP" 3287 along with a key proof as described in Section 8 for the key bound to 3288 the access token. For example, a "jwsd"-bound access token is sent 3289 as follows: 3291 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3292 Detached-JWS: eyj0.... 3294 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3295 protocol/issues/104) ]] 3297 8. Binding Keys 3299 Any keys presented by the client instance to the AS or RS MUST be 3300 validated as part of the request in which they are presented. The 3301 type of binding used is indicated by the proof parameter of the key 3302 section in the initial request Section 2.3.2. Values defined by this 3303 specification are as follows: 3305 jwsd A detached JWS signature header 3307 jws Attached JWS payload 3309 mtls Mutual TLS certificate verification 3311 dpop OAuth Demonstration of Proof-of-Possession key proof header 3313 httpsig HTTP Signing signature header 3315 oauthpop OAuth PoP key proof authentication header 3317 Additional proofing methods are defined by a registry TBD 3318 (Section 12). 3320 All key binding methods used by this specification MUST cover all 3321 relevant portions of the request, including anything that would 3322 change the nature of the request, to allow for secure validation of 3323 the request by the AS. Relevant aspects include the URI being 3324 called, the HTTP method being used, any relevant HTTP headers and 3325 values, and the HTTP message body itself. The recipient of the 3326 signed message MUST validate all components of the signed message to 3327 ensure that nothing has been tampered with or substituted in a way 3328 that would change the nature of the request. 3330 When used for delegation in GNAP, these key binding mechanisms allow 3331 the AS to ensure that the keys presented by the client instance in 3332 the initial request are in control of the party calling any follow-up 3333 or continuation requests. To facilitate this requirement, the 3334 continuation response (Section 3.1) includes an access token bound to 3335 the client instance's key (Section 2.3.2), and that key (or its most 3336 recent rotation) MUST be proved in all continuation requests 3337 Section 5. Token management requests Section 6 are similarly bound 3338 to either the access token's own key or, in the case of bearer 3339 tokens, the client instance's key. The AS MUST validate all keys 3340 presented by the client instance (Section 2.3.2) or referenced in an 3341 ongoing request for each call within that request. 3343 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 3344 protocol/issues/105) ]] 3345 When used to bind to an access token, the access token MUST be 3346 covered by the signature method. 3348 8.1. Detached JWS 3350 This method is indicated by "jwsd" in the "proof" field. A JWS 3351 [RFC7515] signature object is created as follows: 3353 The header of the JWS MUST contain the "kid" field of the key bound 3354 to this client instance for this request. The JWS header MUST 3355 contain an "alg" field appropriate for the key identified by kid and 3356 MUST NOT be "none". The "b64" field MUST be set to "false" and the 3357 "crit" field MUST contain at least "b64" as specified in [RFC7797] 3359 To protect the request, the JWS header MUST contain the following 3360 additional fields. 3362 htm (string) The HTTP Method used to make this request, as an 3363 uppercase ASCII string. 3365 htu (string) The HTTP URI used for this request, including all path 3366 and query components. 3368 ts (integer) A timestamp of the request in integer seconds 3370 at_hash (string) When to bind a request to an access token, the 3371 access token hash value. Its value is the base64url encoding of 3372 the left-most half of the hash of the octets of the ASCII 3373 representation of the "access_token" value, where the hash 3374 algorithm used is the hash algorithm used in the "alg" header 3375 parameter of the JWS's JOSE Header. For instance, if the "alg" is 3376 "RS256", hash the "access_token" value with SHA-256, then take the 3377 left-most 128 bits and base64url encode them. 3379 [[ See issue #106 (https://github.com/ietf-wg-gnap/gnap-core- 3380 protocol/issues/106) ]] 3382 The payload of the JWS object is the serialized body of the request, 3383 and the object is signed according to detached JWS [RFC7797]. 3385 The client instance presents the signature in the Detached-JWS HTTP 3386 Header field. 3388 POST /tx HTTP/1.1 3389 Host: server.example.com 3390 Content-Type: application/json 3391 Detached-JWS: eyJiNjQiOmZhbHNlLCJhbGciOiJSUzI1NiIsImtpZCI6Inh5ei0xIn0. 3392 .Y287HMtaY0EegEjoTd_04a4GC6qV48GgVbGKOhHdJnDtD0VuUlVjLfwne8AuUY3U7e8 3393 9zUWwXLnAYK_BiS84M8EsrFvmv8yDLWzqveeIpcN5_ysveQnYt9Dqi32w6IOtAywkNUD 3394 ZeJEdc3z5s9Ei8qrYFN2fxcu28YS4e8e_cHTK57003WJu-wFn2TJUmAbHuqvUsyTb-nz 3395 YOKxuCKlqQItJF7E-cwSb_xULu-3f77BEU_vGbNYo5ZBa2B7UHO-kWNMSgbW2yeNNLbL 3396 C18Kv80GF22Y7SbZt0e2TwnR2Aa2zksuUbntQ5c7a1-gxtnXzuIKa34OekrnyqE1hmVW 3397 peQ 3399 { 3400 "resources": [ 3401 "dolphin-metadata" 3402 ], 3403 "interact": { 3404 "redirect": true, 3405 "callback": { 3406 "method": "redirect", 3407 "uri": "https://client.foo", 3408 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3409 } 3410 }, 3411 "client": { 3412 "proof": "jwsd", 3413 "key": { 3414 "jwk": { 3415 "kty": "RSA", 3416 "e": "AQAB", 3417 "kid": "xyz-1", 3418 "alg": "RS256", 3419 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8 3420 xYJCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPF 3421 vpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyD 3422 SWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS 3423 63WYPHi_Ap2B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFe 3424 kpdfWdiPQddQ6Y1cK2U3obvUg7w" 3425 } 3426 } 3427 "display": { 3428 "name": "My Client Display Name", 3429 "uri": "https://example.net/client" 3430 }, 3431 } 3432 } 3433 If the request being made does not have a message body, such as an 3434 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3435 over an empty payload. 3437 When the server (AS or RS) receives the Detached-JWS header, it MUST 3438 parse its contents as a detached JWS object. The HTTP Body is used 3439 as the payload for purposes of validating the JWS, with no 3440 transformations. 3442 8.2. Attached JWS 3444 This method is indicated by "jws" in the "proof" field. A JWS 3445 [RFC7515] signature object is created as follows: 3447 The header of the JWS MUST contain the "kid" field of the key bound 3448 to this client instance for this request. The JWS header MUST 3449 contain an "alg" field appropriate for the key identified by kid and 3450 MUST NOT be "none". 3452 To protect the request, the JWS header MUST contain the following 3453 additional fields. 3455 htm (string) The HTTP Method used to make this request, as an 3456 uppercase ASCII string. 3458 htu (string) The HTTP URI used for this request, including all path 3459 and query components. 3461 ts (integer) A timestamp of the request in integer seconds 3463 at_hash (string) When to bind a request to an access token, the 3464 access token hash value. Its value is the base64url encoding of 3465 the left-most half of the hash of the octets of the ASCII 3466 representation of the "access_token" value, where the hash 3467 algorithm used is the hash algorithm used in the "alg" header 3468 parameter of the JWS's JOSE Header. For instance, if the "alg" is 3469 "RS256", hash the "access_token" value with SHA-256, then take the 3470 left-most 128 bits and base64url encode them. 3472 The payload of the JWS object is the JSON serialized body of the 3473 request, and the object is signed according to JWS and serialized 3474 into compact form [RFC7515]. 3476 The client instance presents the JWS as the body of the request along 3477 with a content type of "application/jose". The AS MUST extract the 3478 payload of the JWS and treat it as the request body for further 3479 processing. 3481 POST /tx HTTP/1.1 3482 Host: server.example.com 3483 Content-Type: application/jose 3485 eyJhbGciOiJSUzI1NiIsImtpZCI6IktBZ05wV2JSeXk5T 3486 WYycmlrbDQ5OExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLC 3487 JodG0iOiJwb3N0IiwiaHR1IjoiL3R4IiwidHMiOjE2MDM 3488 4MDA3ODN9.eyJjYXBhYmlsaXRpZXMiOltdLCJjbGllbnQ 3489 iOnsia2V5Ijp7Imp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi 3490 QVFBQiIsImtpZCI6IktBZ05wV2JSeXk5TWYycmlrbDQ5O 3491 ExUaE1ydmtiWldIVlNRT0JDNFZIVTQiLCJuIjoibGxXbU 3492 hGOFhBMktOTGRteE9QM2t4RDlPWTc2cDBTcjM3amZoejk 3493 0YTkzeG0yRk5xb1NQY1JaQVBkMGxxRFM4TjNVaWE1M2RC 3494 MjNaNTlPd1k0YnBNX1ZmOEdKdnZwdExXbnhvMVB5aG1Qc 3495 i1lY2RTQ1JRZFRjX1pjTUY0aFJWNDhxcWx2dUQwbXF0Y0 3496 RiSWtTQkR2Y2NKbVpId2ZUcERIaW5UOHR0dmNWUDhWa0F 3497 NQXE0a1ZhenhPcE1vSVJzb3lFcF9lQ2U1cFN3cUhvMGRh 3498 Q1dOS1ItRXBLbTZOaU90ZWRGNE91bXQ4TkxLVFZqZllnR 3499 khlQkRkQ2JyckVUZDR2Qk13RHRBbmpQcjNDVkN3d3gyYk 3500 FRVDZTbHhGSjNmajJoaHlJcHE3cGM4clppYjVqTnlYS3d 3501 mQnVrVFZZWm96a3NodC1Mb2h5QVNhS3BZVHA4THROWi13 3502 In0sInByb29mIjoiandzIn0sIm5hbWUiOiJNeSBGaXN0I 3503 ENsaWVudCIsInVyaSI6Imh0dHA6Ly9sb2NhbGhvc3QvY2 3504 xpZW50L2NsaWVudElEIn0sImludGVyYWN0Ijp7ImNhbGx 3505 iYWNrIjp7Im1ldGhvZCI6InJlZGlyZWN0Iiwibm9uY2Ui 3506 OiJkOTAyMTM4ODRiODQwOTIwNTM4YjVjNTEiLCJ1cmkiO 3507 iJodHRwOi8vbG9jYWxob3N0L2NsaWVudC9yZXF1ZXN0LW 3508 RvbmUifSwicmVkaXJlY3QiOnRydWV9LCJyZXNvdXJjZXM 3509 iOnsiYWN0aW9ucyI6WyJyZWFkIiwicHJpbnQiXSwibG9j 3510 YXRpb25zIjpbImh0dHA6Ly9sb2NhbGhvc3QvcGhvdG9zI 3511 l0sInR5cGUiOiJwaG90by1hcGkifSwic3ViamVjdCI6ey 3512 JzdWJfaWRzIjpbImlzcy1zdWIiLCJlbWFpbCJdfX0.LUy 3513 Z8_fERmxbYARq8kBYMwzcd8GnCAKAlo2ZSYLRRNAYWPrp 3514 2XGLJOvg97WK1idf_LB08OJmLVsCXxCvn9mgaAkYNL_Zj 3515 HcusBvY1mNo0E1sdTEr31CVKfC-6WrZCscb8YqE4Ayhh0 3516 Te8kzSng3OkLdy7xN4xeKuHzpF7yGsM52JZ0cBcTo6WrY 3517 EfGdr08AWQJ59ht72n3jTsmYNy9A6I4Wrvfgj3TNxmwYo 3518 jpBAicfjnzA1UVcNm9F_xiSz1_y2tdH7j5rVqBMQife-k 3519 9Ewk95vr3lurthenliYSNiUinVfoW1ybnaIBcTtP1_YCx 3520 g_h1y-B5uZEvYNGCuoCqa6IQ 3522 This example's JWS header decodes to: 3524 { 3525 "alg": "RS256", 3526 "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", 3527 "htm": "post", 3528 "htu": "/tx", 3529 "ts": 1603800783 3530 } 3532 And the JWS body decodes to: 3534 { 3535 "capabilities": [], 3536 "client": { 3537 "key": { 3538 "jwk": { 3539 "kty": "RSA", 3540 "e": "AQAB", 3541 "kid": "KAgNpWbRyy9Mf2rikl498LThMrvkbZWHVSQOBC4VHU4", 3542 "n": "llWmHF8XA2KNLdmxOP3kxD9OY76p0Sr37jfhz94a93xm2FNqoSPc 3543 RZAPd0lqDS8N3Uia53dB23Z59OwY4bpM_Vf8GJvvptLWnxo1PyhmPr-ecd 3544 SCRQdTc_ZcMF4hRV48qqlvuD0mqtcDbIkSBDvccJmZHwfTpDHinT8ttvcV 3545 P8VkAMAq4kVazxOpMoIRsoyEp_eCe5pSwqHo0daCWNKR-EpKm6NiOtedF4 3546 Oumt8NLKTVjfYgFHeBDdCbrrETd4vBMwDtAnjPr3CVCwwx2bAQT6SlxFJ3 3547 fj2hhyIpq7pc8rZib5jNyXKwfBukTVYZozksht-LohyASaKpYTp8LtNZ-w" 3548 }, 3549 "proof": "jws" 3550 }, 3551 "name": "My Fist Client", 3552 "uri": "http://localhost/client/clientID" 3553 }, 3554 "interact": { 3555 "callback": { 3556 "method": "redirect", 3557 "nonce": "d90213884b840920538b5c51", 3558 "uri": "http://localhost/client/request-done" 3559 }, 3560 "redirect": true 3561 }, 3562 "resources": { 3563 "actions": [ 3564 "read", 3565 "print" 3566 ], 3567 "locations": [ 3568 "http://localhost/photos" 3569 ], 3570 "type": "photo-api" 3571 }, 3572 "subject": { 3573 "sub_ids": [ 3574 "iss_sub", 3575 "email" 3576 ] 3577 } 3578 } 3579 If the request being made does not have a message body, such as an 3580 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3581 over an empty payload and passed in the "Detached-JWS" header as 3582 described in Section 8.1. 3584 [[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core- 3585 protocol/issues/109) ]] 3587 8.3. Mutual TLS 3589 This method is indicated by "mtls" in the "proof" field. The client 3590 instance presents its TLS client certificate during TLS negotiation 3591 with the server (either AS or RS). The AS or RS takes the thumbprint 3592 of the TLS client certificate presented during mutual TLS negotiation 3593 and compares that thumbprint to the thumbprint presented by the 3594 client instance application as described in [RFC8705] section 3. 3596 POST /tx HTTP/1.1 3597 Host: server.example.com 3598 Content-Type: application/json 3599 SSL_CLIENT_CERT: MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3MDUGA1UEAwwuQmVz 3600 cG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eTELMAkG 3601 A1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFgpjYUBic3BrLmlv 3602 MRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQLDANNVEkwHhcN 3603 MTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQDDAlsb2NhbGhv 3604 c3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3DQEJARYRdGxz 3605 Y2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZXJpbmcxDDAK 3606 BgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMmaXQHb 3607 s/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77OmJ4bQLokq 3608 sd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYNDOmCdHww 3609 UjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+aOJytk 3610 vj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nqsmZQc 3611 jfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8puLW 3612 aD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4DBs 3613 BgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdGxz 3614 Y2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGxz 3615 Y2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3616 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe 3617 2573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboX 3618 hufHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb 3619 907/p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3k 3620 lwLW9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh 3622 { 3623 "resources": [ 3624 "dolphin-metadata" 3625 ], 3626 "interact": { 3627 "redirect": true, 3628 "callback": { 3629 "method": "redirect", 3630 "uri": "https://client.foo", 3631 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3632 } 3633 }, 3634 "client": { 3635 "display": { 3636 "name": "My Client Display Name", 3637 "uri": "https://example.net/client" 3638 }, 3639 "key": { 3640 "proof": "mtls", 3641 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFADCBmjE3 3642 MDUGA1UEAwwuQmVzcG9rZSBFbmdpbmVlcmluZyBSb290IENlcnRpZmljYXRlIEF1d 3643 Ghvcml0eTELMAkGA1UECAwCTUExCzAJBgNVBAYTAlVTMRkwFwYJKoZIhvcNAQkBFg 3644 pjYUBic3BrLmlvMRwwGgYDVQQKDBNCZXNwb2tlIEVuZ2luZWVyaW5nMQwwCgYDVQQ 3645 LDANNVEkwHhcNMTkwNDEwMjE0MDI5WhcNMjQwNDA4MjE0MDI5WjB8MRIwEAYDVQQD 3646 DAlsb2NhbGhvc3QxCzAJBgNVBAgMAk1BMQswCQYDVQQGEwJVUzEgMB4GCSqGSIb3D 3647 QEJARYRdGxzY2xpZW50QGJzcGsuaW8xHDAaBgNVBAoME0Jlc3Bva2UgRW5naW5lZX 3648 JpbmcxDDAKBgNVBAsMA01USTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggE 3649 BAMmaXQHbs/wc1RpsQ6Orzf6rN+q2ijaZbQxD8oi+XaaN0P/gnE13JqQduvdq77Om 3650 J4bQLokqsd0BexnI07Njsl8nkDDYpe8rNve5TjyUDCfbwgS7U1CluYenXmNQbaYND 3651 OmCdHwwUjV4kKREg6DGAx22Oq7+VHPTeeFgyw4kQgWRSfDENWY3KUXJlb/vKR6lQ+ 3652 aOJytkvj8kVZQtWupPbvwoJe0na/ISNAOhL74w20DWWoDKoNltXsEtflNljVoi5nq 3653 smZQcjfjt6LO0T7O1OX3Cwu2xWx8KZ3n/2ocuRqKEJHqUGfeDtuQNt6Jz79v/OTr8 3654 puLWaD+uyk6NbtGjoQsCAwEAAaOBiTCBhjAJBgNVHRMEAjAAMAsGA1UdDwQEAwIF4 3655 DBsBgNVHREEZTBjgglsb2NhbGhvc3SCD3Rsc2NsaWVudC5sb2NhbIcEwKgBBIERdG 3656 xzY2xpZW50QGJzcGsuaW+GF2h0dHA6Ly90bHNjbGllbnQubG9jYWwvhhNzc2g6dGx 3657 zY2xpZW50LmxvY2FsMA0GCSqGSIb3DQEBCwUAA4IBAQCKKv8WlLrT4Z5NazaUrYtl 3658 TF+2v0tvZBQ7qzJQjlOqAcvxry/d2zyhiRCRS/v318YCJBEv4Iq2W3I3JMMyAYEe2 3659 573HzT7rH3xQP12yZyRQnetdiVM1Z1KaXwfrPDLs72hUeELtxIcfZ0M085jLboXhu 3660 fHI6kqm3NCyCCTihe2ck5RmCc5l2KBO/vAHF0ihhFOOOby1v6qbPHQcxAU6rEb907 3661 /p6BW/LV1NCgYB1QtFSfGxowqb9FRIMD2kvMSmO0EMxgwZ6k6spa+jk0IsI3klwLW 3662 9b+Tfn/daUbIDctxeJneq2anQyU2znBgQl6KILDSF4eaOqlBut/KNZHHazJh" 3663 } 3664 } 3666 [[ See issue #110 (https://github.com/ietf-wg-gnap/gnap-core- 3667 protocol/issues/110) ]] 3669 8.4. Demonstration of Proof-of-Possession (DPoP) 3671 This method is indicated by "dpop" in the "proof" field. The client 3672 instance creates a Demonstration of Proof-of-Possession signature 3673 header as described in [I-D.ietf-oauth-dpop] section 2. In addition 3674 to the required fields, the DPoP body MUST also contain a digest of 3675 the request body: 3677 digest (string) Digest of the request body as the value of the 3678 Digest header defined in [RFC3230]. 3680 POST /tx HTTP/1.1 3681 Host: server.example.com 3682 Content-Type: application/json 3683 DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlJTMjU2IiwiandrIjp7Imt0eSI6Il 3684 JTQSIsImUiOiJBUUFCIiwia2lkIjoieHl6LWNsaWVudCIsImFsZyI6IlJTMjU2Iiwibi 3685 I6Inp3Q1RfM2J4LWdsYmJIcmhlWXBZcFJXaVk5SS1uRWFNUnBablJySWpDczZiX2VteV 3686 RrQmtEREVqU3lzaTM4T0M3M2hqMS1XZ3hjUGRLTkdaeUlvSDNRWmVuMU1LeXloUXBMSk 3687 cxLW9MTkxxbTdwWFh0ZFl6U2RDOU8zLW9peXk4eWtPNFlVeU5aclJSZlBjaWhkUUNiT1 3688 9PQzhRdWdtZzlyZ05ET1NxcHBkYU5lYXMxb3Y5UHhZdnhxcnoxLThIYTdna0QwMFlFQ1 3689 hIYUIwNXVNYVVhZEhxLU9fV0l2WVhpY2c2STVqNlM0NFZOVTY1VkJ3dS1BbHluVHhRZE 3690 1BV1AzYll4VlZ5NnAzLTdlVEpva3ZqWVRGcWdEVkRaOGxVWGJyNXlDVG5SaG5oSmd2Zj 3691 NWakRfbWFsTmU4LXRPcUs1T1NEbEhUeTZnRDlOcWRHQ20tUG0zUSJ9fQ.eyJodHRwX21 3692 ldGhvZCI6IlBPU1QiLCJodHRwX3VyaSI6Imh0dHA6XC9cL2hvc3QuZG9ja2VyLmludGV 3693 ybmFsOjk4MzRcL2FwaVwvYXNcL3RyYW5zYWN0aW9uIiwiaWF0IjoxNTcyNjQyNjEzLCJ 3694 qdGkiOiJIam9IcmpnbTJ5QjR4N2pBNXl5RyJ9.aUhftvfw2NoW3M7durkopReTvONng1 3695 fOzbWjAlKNSLL0qIwDgfG39XUyNvwQ23OBIwe6IuvTQ2UBBPklPAfJhDTKd8KHEAfidN 3696 B-LzUOzhDetLg30yLFzIpcEBMLCjb0TEsmXadvxuNkEzFRL-Q-QCg0AXSF1h57eAqZV8 3697 SYF4CQK9OUV6fIWwxLDd3cVTx83MgyCNnvFlG_HDyim1Xx-rxV4ePd1vgDeRubFb6QWj 3698 iKEO7vj1APv32dsux67gZYiUpjm0wEZprjlG0a07R984KLeK1XPjXgViEwEdlirUmpVy 3699 T9tyEYqGrTfm5uautELgMls9sgSyE929woZ59elg 3701 { 3702 "resources": [ 3703 "dolphin-metadata" 3704 ], 3705 "interact": { 3706 "redirect": true, 3707 "callback": { 3708 "method": "redirect", 3709 "uri": "https://client.foo", 3710 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3711 } 3712 }, 3713 "client": { 3714 "display": { 3715 "name": "My Client Display Name", 3716 "uri": "https://example.net/client" 3718 }, 3719 "proof": "dpop", 3720 "key": { 3721 "jwk": { 3722 "kty": "RSA", 3723 "e": "AQAB", 3724 "kid": "xyz-1", 3725 "alg": "RS256", 3726 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xYJ 3727 CCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD-y6jnD1u9YhBOCWObNPFvpkTM 3728 8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5-ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCH 3729 e5mXT4cL0BwrZC6S-uu-LAx06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2 3730 B7_8Wbw4ttzbMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6Y 3731 1cK2U3obvUg7w" 3732 } 3733 } 3734 } 3735 } 3737 8.5. HTTP Signing 3739 This method is indicated by "httpsig" in the "proof" field. The 3740 client instance creates an HTTP Signature header as described in 3741 [I-D.ietf-httpbis-message-signatures] section 4. The client instance 3742 MUST calculate and present the Digest header as defined in [RFC3230] 3743 and include this header in the signature. 3745 POST /tx HTTP/1.1 3746 Host: server.example.com 3747 Content-Type: application/json 3748 Content-Length: 716 3749 Signature: keyId="xyz-client", algorithm="rsa-sha256", 3750 headers="(request-target) digest content-length", 3751 signature="TkehmgK7GD/z4jGkmcHS67cjVRgm3zVQNlNrrXW32Wv7d 3752 u0VNEIVI/dMhe0WlHC93NP3ms91i2WOW5r5B6qow6TNx/82/6W84p5jqF 3753 YuYfTkKYZ69GbfqXkYV9gaT++dl5kvZQjVk+KZT1dzpAzv8hdk9nO87Xi 3754 rj7qe2mdAGE1LLc3YvXwNxuCQh82sa5rXHqtNT1077fiDvSVYeced0UEm 3755 rWwErVgr7sijtbTohC4FJLuJ0nG/KJUcIG/FTchW9rd6dHoBnY43+3Dzj 3756 CIthXpdH5u4VX3TBe6GJDO6Mkzc6vB+67OWzPwhYTplUiFFV6UZCsDEeu 3757 Sa/Ue1yLEAMg=="]} 3758 Digest: SHA=oZz2O3kg5SEFAhmr0xEBbc4jEfo= 3760 { 3761 "resources": [ 3762 "dolphin-metadata" 3763 ], 3764 "interact": { 3765 "redirect": true, 3766 "callback": { 3767 "method": "push", 3768 "uri": "https://client.foo", 3769 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3770 } 3771 }, 3772 "client": { 3773 "display": { 3774 "name": "My Client Display Name", 3775 "uri": "https://example.net/client" 3776 }, 3777 "proof": "httpsig", 3778 "key": { 3779 "jwk": { 3780 "kty": "RSA", 3781 "e": "AQAB", 3782 "kid": "xyz-1", 3783 "alg": "RS256", 3784 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 3785 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 3786 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 3787 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 3788 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 3789 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 3790 Y1cK2U3obvUg7w" 3791 } 3792 } 3793 } 3794 } 3796 When used to present an access token as in Section 7, the 3797 Authorization header MUST be included in the signature. 3799 8.6. OAuth Proof of Possession (PoP) 3801 This method is indicated by "oauthpop" in the "proof" field. The 3802 client instance creates an HTTP Authorization PoP header as described 3803 in [I-D.ietf-oauth-signed-http-request] section 4, with the following 3804 additional requirements: 3806 * The "at" (access token) field MUST be omitted unless this method 3807 is being used in conjunction with an access token as in Section 7. 3808 [[ See issue #112 (https://github.com/ietf-wg-gnap/gnap-core- 3809 protocol/issues/112) ]] 3811 * The "b" (body hash) field MUST be calculated and supplied, unless 3812 there is no entity body (such as a GET, OPTIONS, or DELETE 3813 request). 3815 * All components of the URL MUST be calculated and supplied 3817 * The m (method) field MUST be supplied 3819 POST /tx HTTP/1.1 3820 Host: server.example.com 3821 Content-Type: application/json 3822 PoP: eyJhbGciOiJSUzI1NiIsImp3ayI6eyJrdHkiOiJSU0EiLCJlIjoi 3823 QVFBQiIsImtpZCI6Inh5ei1jbGllbnQiLCJhbGciOiJSUzI1NiIsIm4iO 3824 iJ6d0NUXzNieC1nbGJiSHJoZVlwWXBSV2lZOUktbkVhTVJwWm5ScklqQ3 3825 M2Yl9lbXlUa0JrRERFalN5c2kzOE9DNzNoajEtV2d4Y1BkS05HWnlJb0g 3826 zUVplbjFNS3l5aFFwTEpHMS1vTE5McW03cFhYdGRZelNkQzlPMy1vaXl5 3827 OHlrTzRZVXlOWnJSUmZQY2loZFFDYk9fT0M4UXVnbWc5cmdORE9TcXBwZ 3828 GFOZWFzMW92OVB4WXZ4cXJ6MS04SGE3Z2tEMDBZRUNYSGFCMDV1TWFVYW 3829 RIcS1PX1dJdllYaWNnNkk1ajZTNDRWTlU2NVZCd3UtQWx5blR4UWRNQVd 3830 QM2JZeFZWeTZwMy03ZVRKb2t2allURnFnRFZEWjhsVVhicjV5Q1RuUmhu 3831 aEpndmYzVmpEX21hbE5lOC10T3FLNU9TRGxIVHk2Z0Q5TnFkR0NtLVBtM 3832 1EifX0.eyJwIjoiXC9hcGlcL2FzXC90cmFuc2FjdGlvbiIsImIiOiJxa0 3833 lPYkdOeERhZVBTZnc3NnFjamtqSXNFRmxDb3g5bTU5NFM0M0RkU0xBIiw 3834 idSI6Imhvc3QuZG9ja2VyLmludGVybmFsIiwiaCI6W1siQWNjZXB0Iiwi 3835 Q29udGVudC1UeXBlIiwiQ29udGVudC1MZW5ndGgiXSwiVjQ2OUhFWGx6S 3836 k9kQTZmQU5oMmpKdFhTd3pjSGRqMUloOGk5M0h3bEVHYyJdLCJtIjoiUE 3837 9TVCIsInRzIjoxNTcyNjQyNjEwfQ.xyQ47qy8bu4fyK1T3Ru1Sway8wp6 3838 5rfAKnTQQU92AUUU07I2iKoBL2tipBcNCC5zLH5j_WUyjlN15oi_lLHym 3839 fPdzihtt8_Jibjfjib5J15UlifakjQ0rHX04tPal9PvcjwnyZHFcKn-So 3840 Y3wsARn-gGwxpzbsPhiKQP70d2eG0CYQMA6rTLslT7GgdQheelhVFW29i 3841 27NcvqtkJmiAG6Swrq4uUgCY3zRotROkJ13qo86t2DXklV-eES4-2dCxf 3842 cWFkzBAr6oC4Qp7HnY_5UT6IWkRJt3efwYprWcYouOVjtRan3kEtWkaWr 3843 G0J4bPVnTI5St9hJYvvh7FE8JirIg 3845 { 3846 "resources": [ 3847 "dolphin-metadata" 3848 ], 3849 "interact": { 3850 "redirect": true, 3851 "callback": { 3852 "method": "redirect", 3853 "uri": "https://client.foo", 3854 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3855 } 3856 }, 3857 "client": { 3858 "display": { 3859 "name": "My Client Display Name", 3860 "uri": "https://example.net/client" 3861 }, 3862 "proof": "oauthpop", 3863 "key": { 3864 "jwk": { 3865 "kty": "RSA", 3866 "e": "AQAB", 3867 "kid": "xyz-1", 3868 "alg": "RS256", 3869 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_J 3870 tffXyaSx8xYJCCNaOKNJn_Oz0YhdHbXTeWO5AoyspDWJbN5w_7bdWDxgpD- 3871 y6jnD1u9YhBOCWObNPFvpkTM8LC7SdXGRKx2k8Me2r_GssYlyRpqvpBlY5- 3872 ejCywKRBfctRcnhTTGNztbbDBUyDSWmFMVCHe5mXT4cL0BwrZC6S-uu-LAx 3873 06aKwQOPwYOGOslK8WPm1yGdkaA1uF_FpS6LS63WYPHi_Ap2B7_8Wbw4ttz 3874 bMS_doJvuDagW8A1Ip3fXFAHtRAcKw7rdI4_Xln66hJxFekpdfWdiPQddQ6 3875 Y1cK2U3obvUg7w" 3876 } 3877 } 3878 } 3879 } 3881 [[ See issue #113 (https://github.com/ietf-wg-gnap/gnap-core- 3882 protocol/issues/113) ]] 3884 9. Discovery 3886 By design, the protocol minimizes the need for any pre-flight 3887 discovery. To begin a request, the client instance only needs to 3888 know the endpoint of the AS and which keys it will use to sign the 3889 request. Everything else can be negotiated dynamically in the course 3890 of the protocol. 3892 However, the AS can have limits on its allowed functionality. If the 3893 client instance wants to optimize its calls to the AS before making a 3894 request, it MAY send an HTTP OPTIONS request to the grant request 3895 endpoint to retrieve the server's discovery information. The AS MUST 3896 respond with a JSON document containing the following information: 3898 grant_request_endpoint (string) REQUIRED. The full URL of the AS's 3899 grant request endpoint. This MUST match the URL the client 3900 instance used to make the discovery request. 3902 capabilities (array of strings) OPTIONAL. A list of the AS's 3903 capabilities. The values of this result MAY be used by the client 3904 instance in the capabilities section (Section 2.6) of the request. 3906 interaction_methods (array of strings) OPTIONAL. A list of the AS's 3907 interaction methods. The values of this list correspond to the 3908 possible fields in the interaction section (Section 2.5) of the 3909 request. 3911 key_proofs (array strings) OPTIONAL. A list of the AS's supported 3912 key proofing mechanisms. The values of this list correspond to 3913 possible values of the "proof" field of the key section 3914 (Section 2.3.2) of the request. 3916 sub_ids (array of strings) OPTIONAL. A list of the AS's supported 3917 identifiers. The values of this list correspond to possible 3918 values of the subject identifier section (Section 2.2) of the 3919 request. 3921 assertions (array of strings) OPTIONAL. A list of the AS's 3922 supported assertion formats. The values of this list correspond 3923 to possible values of the subject assertion section (Section 2.2) 3924 of the request. 3926 The information returned from this method is for optimization 3927 purposes only. The AS MAY deny any request, or any portion of a 3928 request, even if it lists a capability as supported. For example, a 3929 given client instance can be registered with the "mtls" key proofing 3930 mechanism, but the AS also returns other proofing methods, then the 3931 AS will deny a request from that client instance using a different 3932 proofing mechanism. 3934 10. Resource Servers 3936 In some deployments, a resource server will need to be able to call 3937 the AS for a number of functions. 3939 [[ See issue #114 (https://github.com/ietf-wg-gnap/gnap-core- 3940 protocol/issues/114) ]] 3942 10.1. Introspecting a Token 3944 When the RS receives an access token, it can call the introspection 3945 endpoint at the AS to get token information. [[ See issue #115 3946 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115) ]] 3948 +--------+ +------+ +------+ 3949 | Client |--(1)->| RS | | AS | 3950 |Instance| | |--(2)->| | 3951 | | | |<-(3)--| | 3952 | | | | +------+ 3953 | |<-(4)--| | 3954 +--------+ +------+ 3956 1. The client instance calls the RS with its access token. 3958 2. The RS introspects the access token value at the AS. The RS 3959 signs the request with its own key (not the client instance's key 3960 or the token's key). 3962 3. The AS validates the token value and the client instance's 3963 request and returns the introspection response for the token. 3965 4. The RS fulfills the request from the client instance. 3967 The RS signs the request with its own key and sends the access token 3968 as the body of the request. 3970 POST /introspect HTTP/1.1 3971 Host: server.example.com 3972 Content-type: application/json 3973 Detached-JWS: ejy0... 3975 { 3976 "access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3977 } 3979 The AS responds with a data structure describing the token's current 3980 state and any information the RS would need to validate the token's 3981 presentation, such as its intended proofing mechanism and key 3982 material. 3984 Content-type: application/json 3986 { 3987 "active": true, 3988 "resources": [ 3989 "dolphin-metadata", "some other thing" 3990 ], 3991 "client": { 3992 "key": { 3993 "proof": "httpsig", 3994 "jwk": { 3995 "kty": "RSA", 3996 "e": "AQAB", 3997 "kid": "xyz-1", 3998 "alg": "RS256", 3999 "n": "kOB5rR4Jv0GMeL...." 4000 } 4001 } 4002 } 4003 } 4005 10.2. Deriving a downstream token 4007 Some architectures require an RS to act as a client instance and 4008 request a derived access token for a secondary RS. This internal 4009 token is issued in the context of the incoming access token. 4011 +--------+ +-------+ +------+ +-------+ 4012 | Client |--(1)->| RS1 | | AS | | RS2 | 4013 |Instance| | |--(2)->| | | | 4014 | | | |<-(3)--| | | | 4015 | | | | +------+ | | 4016 | | | | | | 4017 | | | |-----------(4)------->| | 4018 | | | |<----------(5)--------| | 4019 | |<-(6)--| | | | 4020 +--------+ +-------+ +-------+ 4022 1. The client instance calls RS1 with an access token. 4024 2. RS1 presents that token to the AS to get a derived token for use 4025 at RS2. RS1 indicates that it has no ability to interact with 4026 the RO. RS1 signs its request with its own key, not the token's 4027 key or the client instance's key. 4029 3. The AS returns a derived token to RS1 for use at RS2. 4031 4. RS1 calls RS2 with the token from (3). 4033 5. RS2 fulfills the call from RS1. 4035 6. RS1 fulfills the call from client instance. 4037 If the RS needs to derive a token from one presented to it, it can 4038 request one from the AS by making a token request as described in 4039 Section 2 and presenting the existing access token's value in the 4040 "existing_access_token" field. 4042 The RS MUST identify itself with its own key and sign the request. 4044 [[ See issue #116 (https://github.com/ietf-wg-gnap/gnap-core- 4045 protocol/issues/116) ]] 4047 POST /tx HTTP/1.1 4048 Host: server.example.com 4049 Content-type: application/json 4050 Detached-JWS: ejy0... 4052 { 4053 "resources": [ 4054 { 4055 "actions": [ 4056 "read", 4057 "write", 4058 "dolphin" 4059 ], 4060 "locations": [ 4061 "https://server.example.net/", 4062 "https://resource.local/other" 4063 ], 4064 "datatypes": [ 4065 "metadata", 4066 "images" 4067 ] 4068 }, 4069 "dolphin-metadata" 4070 ], 4071 "client": "7C7C4AZ9KHRS6X63AJAO", 4072 "existing_access_token": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 4073 } 4075 The AS responds with a token as described in Section 3. 4077 10.3. Registering a Resource Handle 4079 If the RS needs to, it can post a set of resources as described in 4080 Section 2.1.1 to the AS's resource registration endpoint. 4082 The RS MUST identify itself with its own key and sign the request. 4084 POST /resource HTTP/1.1 4085 Host: server.example.com 4086 Content-type: application/json 4087 Detached-JWS: ejy0... 4089 { 4090 "resources": [ 4091 { 4092 "actions": [ 4093 "read", 4094 "write", 4095 "dolphin" 4096 ], 4097 "locations": [ 4098 "https://server.example.net/", 4099 "https://resource.local/other" 4100 ], 4101 "datatypes": [ 4102 "metadata", 4103 "images" 4104 ] 4105 }, 4106 "dolphin-metadata" 4107 ], 4108 "client": "7C7C4AZ9KHRS6X63AJAO" 4110 } 4112 The AS responds with a handle appropriate to represent the resources 4113 list that the RS presented. 4115 Content-type: application/json 4117 { 4118 "resource_handle": "FWWIKYBQ6U56NL1" 4119 } 4121 The RS MAY make this handle available as part of a response 4122 (Section 10.4) or as documentation to developers. 4124 [[ See issue #117 (https://github.com/ietf-wg-gnap/gnap-core- 4125 protocol/issues/117) ]] 4127 10.4. Requesting Resources With Insufficient Access 4129 If the client instance calls an RS without an access token, or with 4130 an invalid access token, the RS MAY respond to the client instance 4131 with an authentication header indicating that GNAP needs to be used 4132 to access the resource. The address of the GNAP endpoint MUST be 4133 sent in the "as_uri" parameter. The RS MAY additionally return a 4134 resource reference that the client instance MAY use in its resource 4135 request (Section 2.1). This resource reference handle SHOULD be 4136 sufficient for at least the action the client instance was attempting 4137 to take at the RS. The RS MAY use the dynamic resource handle 4138 request (Section 10.3) to register a new resource handle, or use a 4139 handle that has been pre-configured to represent what the AS is 4140 protecting. The content of this handle is opaque to the RS and the 4141 client instance. 4143 WWW-Authenticate: GNAP as_uri=http://server.example/tx,resource=FWWIKYBQ6U56NL1 4145 The client instance then makes a call to the "as_uri" as described in 4146 Section 2, with the value of "resource" as one of the members of a 4147 "resources" array Section 2.1.1. The client instance MAY request 4148 additional resources and other information, and MAY request multiple 4149 access tokens. 4151 [[ See issue #118 (https://github.com/ietf-wg-gnap/gnap-core- 4152 protocol/issues/118) ]] 4154 11. Acknowledgements 4156 The editors would like to thank the feedback of the following 4157 individuals for their reviews, implementations, and contributions: 4158 Aaron Parecki, Annabelle Backman, Dick Hardt, Dmitri Zagidulin, 4159 Dmitry Barinov, Fabien Imbault, Francis Pouatcha, George Fletcher, 4160 Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan, Justin 4161 Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat Sakimura, 4162 Takahiko Kawasaki, Takahiro Tsuchiya. 4164 The editors would also like to thank the GNAP working group design 4165 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 4166 and Justin Richer, who incorporated elements from the XAuth and XYZ 4167 proposals to create the first version of this document. 4169 In addition, the editors would like to thank Aaron Parecki and Mike 4170 Jones for insights into how to integrate identity and authentication 4171 systems into the core protocol, and Justin Richer and Dick Hardt for 4172 the use cases, diagrams, and insights provided in the XYZ and XAuth 4173 proposals that have been incorporated here. The editors would like 4174 to especially thank Mike Varley and the team at SecureKey for 4175 feedback and development of early versions of the XYZ protocol that 4176 fed into this standards work. 4178 12. IANA Considerations 4180 [[ TBD: There are a lot of items in the document that are expandable 4181 through the use of value registries. ]] 4183 13. Security Considerations 4185 [[ TBD: There are a lot of security considerations to add. ]] 4187 All requests have to be over TLS or equivalent as per [BCP195]. Many 4188 handles act as shared secrets, though they can be combined with a 4189 requirement to provide proof of a key as well. 4191 14. Privacy Considerations 4193 [[ TBD: There are a lot of privacy considerations to add. ]] 4195 Handles are passed between parties and therefore should not contain 4196 any private data. 4198 When user information is passed to the client instance, the AS needs 4199 to make sure that it has the permission to do so. 4201 15. Normative References 4203 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 4204 "Recommendations for Secure Use of Transport Layer 4205 Security (TLS) and Datagram Transport Layer Security 4206 (DTLS)", May 2015, 4207 . 4209 [I-D.ietf-httpbis-message-signatures] 4210 Backman, A., Richer, J., and M. Sporny, "Signing HTTP 4211 Messages", Work in Progress, Internet-Draft, draft-ietf- 4212 httpbis-message-signatures-01, 17 November 2020, 4213 . 4216 [I-D.ietf-oauth-dpop] 4217 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 4218 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 4219 of-Possession at the Application Layer (DPoP)", Work in 4220 Progress, Internet-Draft, draft-ietf-oauth-dpop-02, 18 4221 November 2020, . 4224 [I-D.ietf-oauth-signed-http-request] 4225 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 4226 Signing HTTP Requests for OAuth", Work in Progress, 4227 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 4228 August 2016, . 4231 [I-D.ietf-secevent-subject-identifiers] 4232 Backman, A. and M. Scurtescu, "Subject Identifiers for 4233 Security Event Tokens", Work in Progress, Internet-Draft, 4234 draft-ietf-secevent-subject-identifiers-06, 4 September 4235 2020, . 4238 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 4239 C. Mortimore, "OpenID Connect Core 1.0 incorporating 4240 errata set 1", November 2014, 4241 . 4243 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4244 Requirement Levels", BCP 14, RFC 2119, 4245 DOI 10.17487/RFC2119, March 1997, 4246 . 4248 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 4249 RFC 3230, DOI 10.17487/RFC3230, January 2002, 4250 . 4252 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 4253 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 4254 September 2009, . 4256 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 4257 RFC 6749, DOI 10.17487/RFC6749, October 2012, 4258 . 4260 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 4261 Framework: Bearer Token Usage", RFC 6750, 4262 DOI 10.17487/RFC6750, October 2012, 4263 . 4265 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4266 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4267 2015, . 4269 [RFC7797] Jones, M., "JSON Web Signature (JWS) Unencoded Payload 4270 Option", RFC 7797, DOI 10.17487/RFC7797, February 2016, 4271 . 4273 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4274 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4275 May 2017, . 4277 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4278 Interchange Format", STD 90, RFC 8259, 4279 DOI 10.17487/RFC8259, December 2017, 4280 . 4282 [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., 4283 and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, 4284 DOI 10.17487/RFC8693, January 2020, 4285 . 4287 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 4288 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 4289 and Certificate-Bound Access Tokens", RFC 8705, 4290 DOI 10.17487/RFC8705, February 2020, 4291 . 4293 Appendix A. Document History 4295 * -03 4297 - Changed "resource client" terminology to separate "client 4298 instance" and "client software". 4300 * -02 4302 - Moved all "editor's note" items to GitHub Issues. 4304 - Added JSON types to fields. 4306 - Changed "GNAP Protocol" to "GNAP". 4308 - Editorial fixes. 4310 * -01 4311 - "updated_at" subject info timestamp now in ISO 8601 string 4312 format. 4314 - Editorial fixes. 4316 - Added Aaron and Fabien as document authors. 4318 * -00 4320 - Initial working group draft. 4322 Appendix B. Component Data Models 4324 While different implementations of this protocol will have different 4325 realizations of all the components and artifacts enumerated here, the 4326 nature of the protocol implies some common structures and elements 4327 for certain components. This appendix seeks to enumerate those 4328 common elements. 4330 TBD: Client has keys, allowed requested resources, identifier(s), 4331 allowed requested subjects, allowed 4333 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 4334 client keys, policies 4336 TBD: Token has RO, user, client, resource list, RS list, 4338 Appendix C. Example Protocol Flows 4340 The protocol defined in this specification provides a number of 4341 features that can be combined to solve many different kinds of 4342 authentication scenarios. This section seeks to show examples of how 4343 the protocol would be applied for different situations. 4345 Some longer fields, particularly cryptographic information, have been 4346 truncated for display purposes in these examples. 4348 C.1. Redirect-Based User Interaction 4350 In this scenario, the user is the RO and has access to a web browser, 4351 and the client instance can take front-channel callbacks on the same 4352 device as the user. This combination is analogous to the OAuth 2 4353 Authorization Code grant type. 4355 The client instance initiates the request to the AS. Here the client 4356 instance identifies itself using its public key. 4358 POST /tx HTTP/1.1 4359 Host: server.example.com 4360 Content-type: application/json 4361 Detached-JWS: ejy0... 4363 { 4364 "resources": [ 4365 { 4366 "actions": [ 4367 "read", 4368 "write", 4369 "dolphin" 4370 ], 4371 "locations": [ 4372 "https://server.example.net/", 4373 "https://resource.local/other" 4374 ], 4375 "datatypes": [ 4376 "metadata", 4377 "images" 4378 ] 4379 } 4380 ], 4381 "client": { 4382 "key": { 4383 "proof": "jwsd", 4384 "jwk": { 4385 "kty": "RSA", 4386 "e": "AQAB", 4387 "kid": "xyz-1", 4388 "alg": "RS256", 4389 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 4390 } 4391 } 4392 }, 4393 "interact": { 4394 "redirect": true, 4395 "callback": { 4396 "method": "redirect", 4397 "uri": "https://client.example.net/return/123455", 4398 "nonce": "LKLTI25DK82FX4T4QFZC" 4399 } 4400 } 4401 } 4402 The AS processes the request and determines that the RO needs to 4403 interact. The AS returns the following response giving the client 4404 instance the information it needs to connect. The AS has also 4405 indicated to the client instance that it can use the given instance 4406 identifier to identify itself in future requests (Section 2.3.1). 4408 Content-type: application/json 4410 { 4411 "interact": { 4412 "redirect": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ", 4413 "callback": "MBDOFXG4Y5CVJCX821LH" 4414 } 4415 "continue": { 4416 "access_token": { 4417 "value": "80UPRY5NM33OMUKMKSKU", 4418 "key": true 4419 }, 4420 "uri": "https://server.example.com/continue" 4421 }, 4422 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 4423 } 4425 The client instance saves the response and redirects the user to the 4426 interaction_url by sending the following HTTP message to the user's 4427 browser. 4429 HTTP 302 Found 4430 Location: https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ 4432 The user's browser fetches the AS's interaction URL. The user logs 4433 in, is identified as the RO for the resource being requested, and 4434 approves the request. Since the AS has a callback parameter, the AS 4435 generates the interaction reference, calculates the hash, and 4436 redirects the user back to the client instance with these additional 4437 values added as query parameters. 4439 HTTP 302 Found 4440 Location: https://client.example.net/return/123455 4441 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A 4442 &interact_ref=4IFWWIKYBC2PQ6U56NL1 4443 The client instance receives this request from the user's browser. 4444 The client instance ensures that this is the same user that was sent 4445 out by validating session information and retrieves the stored 4446 pending request. The client instance uses the values in this to 4447 validate the hash parameter. The client instance then calls the 4448 continuation URL and presents the handle and interaction reference in 4449 the request body. The client instance signs the request as above. 4451 POST /continue HTTP/1.1 4452 Host: server.example.com 4453 Content-type: application/json 4454 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 4455 Detached-JWS: ejy0... 4457 { 4458 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 4459 } 4461 The AS retrieves the pending request based on the handle and issues a 4462 bearer access token and returns this to the client instance. 4464 Content-type: application/json 4466 { 4467 "access_token": { 4468 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4469 "key": false, 4470 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4471 "resources": [{ 4472 "actions": [ 4473 "read", 4474 "write", 4475 "dolphin" 4476 ], 4477 "locations": [ 4478 "https://server.example.net/", 4479 "https://resource.local/other" 4480 ], 4481 "datatypes": [ 4482 "metadata", 4483 "images" 4484 ] 4485 }] 4486 }, 4487 "continue": { 4488 "access_token": { 4489 "value": "80UPRY5NM33OMUKMKSKU", 4490 "key": true 4491 }, 4492 "uri": "https://server.example.com/continue" 4493 } 4494 } 4496 C.2. Secondary Device Interaction 4498 In this scenario, the user does not have access to a web browser on 4499 the device and must use a secondary device to interact with the AS. 4500 The client instance can display a user code or a printable QR code. 4501 The client instance is not able to accept callbacks from the AS and 4502 needs to poll for updates while waiting for the user to authorize the 4503 request. 4505 The client instance initiates the request to the AS. 4507 POST /tx HTTP/1.1 4508 Host: server.example.com 4509 Content-type: application/json 4510 Detached-JWS: ejy0... 4512 { 4513 "resources": [ 4514 "dolphin-metadata", "some other thing" 4515 ], 4516 "client": "7C7C4AZ9KHRS6X63AJAO", 4517 "interact": { 4518 "redirect": true, 4519 "user_code": true 4520 } 4521 } 4523 The AS processes this and determines that the RO needs to interact. 4524 The AS supports both redirect URIs and user codes for interaction, so 4525 it includes both. Since there is no "callback" the AS does not 4526 include a nonce, but does include a "wait" parameter on the 4527 continuation section because it expects the client instance to poll 4528 for results. 4530 Content-type: application/json 4532 { 4533 "interact": { 4534 "redirect": "https://srv.ex/MXKHQ", 4535 "user_code": { 4536 "code": "A1BC-3DFF", 4537 "url": "https://srv.ex/device" 4538 } 4539 }, 4540 "continue": { 4541 "access_token": { 4542 "value": "80UPRY5NM33OMUKMKSKU", 4543 "key": true 4544 }, 4545 "uri": "https://server.example.com/continue/VGJKPTKC50", 4546 "wait": 60 4547 } 4548 } 4550 The client instance saves the response and displays the user code 4551 visually on its screen along with the static device URL. The client 4552 instance also displays the short interaction URL as a QR code to be 4553 scanned. 4555 If the user scans the code, they are taken to the interaction 4556 endpoint and the AS looks up the current pending request based on the 4557 incoming URL. If the user instead goes to the static page and enters 4558 the code manually, the AS looks up the current pending request based 4559 on the value of the user code. In both cases, the user logs in, is 4560 identified as the RO for the resource being requested, and approves 4561 the request. Once the request has been approved, the AS displays to 4562 the user a message to return to their device. 4564 Meanwhile, the client instance periodically polls the AS every 60 4565 seconds at the continuation URL. The client instance signs the 4566 request using the same key and method that it did in the first 4567 request. 4569 POST /continue/VGJKPTKC50 HTTP/1.1 4570 Host: server.example.com 4571 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 4572 Detached-JWS: ejy0... 4574 The AS retrieves the pending request based on the handle and 4575 determines that it has not yet been authorized. The AS indicates to 4576 the client instance that no access token has yet been issued but it 4577 can continue to call after another 60 second timeout. 4579 Content-type: application/json 4581 { 4582 "continue": { 4583 "access_token": { 4584 "value": "G7YQT4KQQ5TZY9SLSS5E", 4585 "key": true 4586 }, 4587 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 4588 "wait": 60 4589 } 4590 } 4592 Note that the continuation URL and access token have been rotated 4593 since they were used by the client instance to make this call. The 4594 client instance polls the continuation URL after a 60 second timeout 4595 using this new information. 4597 POST /continue/ATWHO4Q1WV HTTP/1.1 4598 Host: server.example.com 4599 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 4600 Detached-JWS: ejy0... 4602 The AS retrieves the pending request based on the URL and access 4603 token, determines that it has been approved, and issues an access 4604 token for the client to use at the RS. 4606 Content-type: application/json 4608 { 4609 "access_token": { 4610 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4611 "key": false, 4612 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4613 "resources": [ 4614 "dolphin-metadata", "some other thing" 4615 ] 4616 } 4617 } 4619 Appendix D. No User Involvement 4621 In this scenario, the client instance is requesting access on its own 4622 behalf, with no user to interact with. 4624 The client instance creates a request to the AS, identifying itself 4625 with its public key and using MTLS to make the request. 4627 POST /tx HTTP/1.1 4628 Host: server.example.com 4629 Content-type: application/json 4631 { 4632 "resources": [ 4633 "backend service", "nightly-routine-3" 4634 ], 4635 "client": { 4636 "key": { 4637 "proof": "mtls", 4638 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 4639 } 4640 } 4641 } 4643 The AS processes this and determines that the client instance can ask 4644 for the requested resources and issues an access token. 4646 Content-type: application/json 4648 { 4649 "access_token": { 4650 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4651 "key": true, 4652 "manage": "https://server.example.com/token", 4653 "resources": [ 4654 "backend service", "nightly-routine-3" 4655 ] 4656 } 4657 } 4659 D.1. Asynchronous Authorization 4661 In this scenario, the client instance is requesting on behalf of a 4662 specific RO, but has no way to interact with the user. The AS can 4663 asynchronously reach out to the RO for approval in this scenario. 4665 The client instance starts the request at the AS by requesting a set 4666 of resources. The client instance also identifies a particular user. 4668 POST /tx HTTP/1.1 4669 Host: server.example.com 4670 Content-type: application/json 4671 Detached-JWS: ejy0... 4673 { 4674 "resources": [ 4675 { 4676 "type": "photo-api", 4677 "actions": [ 4678 "read", 4679 "write", 4680 "dolphin" 4681 ], 4682 "locations": [ 4683 "https://server.example.net/", 4684 "https://resource.local/other" 4685 ], 4686 "datatypes": [ 4687 "metadata", 4688 "images" 4689 ] 4690 }, 4691 "read", "dolphin-metadata", 4692 { 4693 "type": "financial-transaction", 4694 "actions": [ 4695 "withdraw" 4696 ], 4697 "identifier": "account-14-32-32-3", 4698 "currency": "USD" 4699 }, 4700 "some other thing" 4701 ], 4702 "client": "7C7C4AZ9KHRS6X63AJAO", 4703 "user": { 4704 "sub_ids": [ { 4705 "subject_type": "email", 4706 "email": "user@example.com" 4707 } ] 4708 } 4709 } 4711 The AS processes this and determines that the RO needs to interact. 4712 The AS determines that it can reach the identified user 4713 asynchronously and that the identified user does have the ability to 4714 approve this request. The AS indicates to the client instance that 4715 it can poll for continuation. 4717 Content-type: application/json 4719 { 4720 "continue": { 4721 "access_token": { 4722 "value": "80UPRY5NM33OMUKMKSKU", 4723 "key": true 4724 }, 4725 "uri": "https://server.example.com/continue", 4726 "wait": 60 4727 } 4728 } 4730 The AS reaches out to the RO and prompts them for consent. In this 4731 example, the AS has an application that it can push notifications in 4732 to for the specified account. 4734 Meanwhile, the client instance periodically polls the AS every 60 4735 seconds at the continuation URL. 4737 POST /continue HTTP/1.1 4738 Host: server.example.com 4739 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 4740 Detached-JWS: ejy0... 4742 The AS retrieves the pending request based on the handle and 4743 determines that it has not yet been authorized. The AS indicates to 4744 the client instance that no access token has yet been issued but it 4745 can continue to call after another 60 second timeout. 4747 Content-type: application/json 4749 { 4750 "continue": { 4751 "access_token": { 4752 "value": "BI9QNW6V9W3XFJK4R02D", 4753 "key": true 4754 }, 4755 "uri": "https://server.example.com/continue", 4756 "wait": 60 4757 } 4758 } 4760 Note that the continuation handle has been rotated since it was used 4761 by the client instance to make this call. The client instance polls 4762 the continuation URL after a 60 second timeout using the new handle. 4764 POST /continue HTTP/1.1 4765 Host: server.example.com 4766 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 4767 Detached-JWS: ejy0... 4769 The AS retrieves the pending request based on the handle and 4770 determines that it has been approved and it issues an access token. 4772 Content-type: application/json 4774 { 4775 "access_token": { 4776 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 4777 "key": false, 4778 "manage": "https://server.example.com/token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L", 4779 "resources": [ 4780 "dolphin-metadata", "some other thing" 4781 ] 4782 } 4783 } 4785 D.2. Applying OAuth 2 Scopes and Client IDs 4787 While GNAP is not designed to be directly compatible with OAuth 2 4788 [RFC6749], considerations have been made to enable the use of OAuth 2 4789 concepts and constructs more smoothly within GNAP. 4791 In this scenario, the client developer has a "client_id" and set of 4792 "scope" values from their OAuth 2 system and wants to apply them to 4793 the new protocol. Traditionally, the OAuth 2 client developer would 4794 put their "client_id" and "scope" values as parameters into a 4795 redirect request to the authorization endpoint. 4797 HTTP 302 Found 4798 Location: https://server.example.com/authorize 4799 ?client_id=7C7C4AZ9KHRS6X63AJAO 4800 &scope=read%20write%20dolphin 4801 &redirect_uri=https://client.example.net/return 4802 &response_type=code 4803 &state=123455 4805 Now the developer wants to make an analogous request to the AS using 4806 GNAP. To do so, the client instance makes an HTTP POST and places 4807 the OAuth 2 values in the appropriate places. 4809 POST /tx HTTP/1.1 4810 Host: server.example.com 4811 Content-type: application/json 4812 Detached-JWS: ejy0... 4814 { 4815 "resources": [ 4816 "read", "write", "dolphin" 4817 ], 4818 "client": "7C7C4AZ9KHRS6X63AJAO", 4819 "interact": { 4820 "redirect": true, 4821 "callback": { 4822 "method": "redirect", 4823 "uri": "https://client.example.net/return?state=123455", 4824 "nonce": "LKLTI25DK82FX4T4QFZC" 4825 } 4826 } 4827 } 4829 The client_id can be used to identify the client instance's keys that 4830 it uses for authentication, the scopes represent resources that the 4831 client instance is requesting, and the "redirect_uri" and "state" 4832 value are pre-combined into a "callback" URI that can be unique per 4833 request. The client instance additionally creates a nonce to protect 4834 the callback, separate from the state parameter that it has added to 4835 its return URL. 4837 From here, the protocol continues as above. 4839 Appendix E. JSON Structures and Polymorphism 4841 GNAP makes use of polymorphism within the JSON [RFC8259] structures 4842 used for the protocol. Each portion of this protocol is defined in 4843 terms of the JSON data type that its values can take, whether it's a 4844 string, object, array, boolean, or number. For some fields, 4845 different data types offer different descriptive capabilities and are 4846 used in different situations for the same field. Each data type 4847 provides a different syntax to express the same underlying semantic 4848 protocol element, which allows for optimization and simplification in 4849 many common cases. 4851 Even though JSON is often used to describe strongly typed structures, 4852 JSON on its own is naturally polymorphic. In JSON, the named members 4853 of an object have no type associated with them, and any data type can 4854 be used as the value for any member. In practice, each member has a 4855 semantic type that needs to make sense to the parties creating and 4856 consuming the object. Within this protocol, each object member is 4857 defined in terms of its semantic content, and this semantic content 4858 might have expressions in different concrete data types for different 4859 specific purposes. Since each object member has exactly one value in 4860 JSON, each data type for an object member field is naturally mutually 4861 exclusive with other data types within a single JSON object. 4863 For example, a resource request for a single access token is composed 4864 of an array of resource request descriptions while a request for 4865 multiple access tokens is composed of an object whose member values 4866 are all arrays. Both of these represent requests for access, but the 4867 difference in syntax allows the client instance and AS to 4868 differentiate between the two request types in the same request. 4870 Another form of polymorphism in JSON comes from the fact that the 4871 values within JSON arrays need not all be of the same JSON data type. 4872 However, within this protocol, each element within the array needs to 4873 be of the same kind of semantic element for the collection to make 4874 sense, even when the data types are different from each other. 4876 For example, each aspect of a resource request can be described using 4877 an object with multiple dimensional components, or the aspect can be 4878 requested using a string. In both cases, the resource request is 4879 being described in a way that the AS needs to interpret, but with 4880 different levels of specificity and complexity for the client 4881 instance to deal with. An API designer can provide a set of common 4882 access scopes as simple strings but still allow RC developers to 4883 specify custom access when needed for more complex APIs. 4885 Extensions to this specification can use different data types for 4886 defined fields, but each extension needs to not only declare what the 4887 data type means, but also provide justification for the data type 4888 representing the same basic kind of thing it extends. For example, 4889 an extension declaring an "array" representation for a field would 4890 need to explain how the array represents something akin to the non- 4891 array element that it is replacing. 4893 Authors' Addresses 4895 Justin Richer (editor) 4896 Bespoke Engineering 4898 Email: ietf@justin.richer.org 4899 URI: https://bspk.io/ 4901 Aaron Parecki 4902 Okta 4903 Email: aaron@parecki.com 4904 URI: https://aaronparecki.com 4906 Fabien Imbault 4907 acert.io 4909 Email: fabien.imbault@acert.io 4910 URI: https://acert.io/