idnits 2.17.1 draft-ietf-gnap-core-protocol-06.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 is 1 instance of too long lines in the document, the longest one being 10 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 243 has weird spacing: '... Client appli...' == Line 267 has weird spacing: '...nd-user natur...' == Line 329 has weird spacing: '...tribute chara...' == Line 331 has weird spacing: '...s Token a dat...' == Line 342 has weird spacing: '...ivilege right...' == (4 more instances...) -- The document date (12 July 2021) is 1018 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: 'I-D.ietf-oauth-signed-http-request' is defined on line 4671, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-05) exists of draft-ietf-gnap-resource-servers-00 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-05 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-05 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Downref: Normative reference to an Informational RFC: RFC 8792 Summary: 4 errors (**), 0 flaws (~~), 12 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: 13 January 2022 Okta 6 F. Imbault 7 acert.io 8 12 July 2021 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-06 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 13 January 2022. 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 . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 8 57 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 9 58 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 12 59 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 15 60 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 17 61 1.4.4. Software-only Authorization . . . . . . . . . . . . . 19 62 1.4.5. Refreshing an Expired Access Token . . . . . . . . . 20 63 1.4.6. Requesting User Information . . . . . . . . . . . . . 22 64 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 23 65 2.1. Requesting Access to Resources . . . . . . . . . . . . . 25 66 2.1.1. Requesting a Single Access Token . . . . . . . . . . 25 67 2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 28 68 2.2. Requesting Subject Information . . . . . . . . . . . . . 30 69 2.3. Identifying the Client Instance . . . . . . . . . . . . . 31 70 2.3.1. Identifying the Client Instance by Reference . . . . 32 71 2.3.2. Providing Displayable Client Instance Information . . 33 72 2.3.3. Authenticating the Client Instance . . . . . . . . . 33 73 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 34 74 2.4.1. Identifying the User by Reference . . . . . . . . . . 35 75 2.5. Interacting with the User . . . . . . . . . . . . . . . . 35 76 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 37 77 2.5.2. Finish Interaction Modes . . . . . . . . . . . . . . 38 78 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 41 79 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 41 80 2.6. Extending The Grant Request . . . . . . . . . . . . . . . 41 81 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 42 82 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 43 83 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 44 84 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 45 85 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 48 86 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 49 87 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 50 88 3.3.2. Launch of an application URL . . . . . . . . . . . . 51 89 3.3.3. Display of a Short User Code . . . . . . . . . . . . 51 90 3.3.4. Interaction Finish . . . . . . . . . . . . . . . . . 52 91 3.3.5. Extending Interaction Mode Responses . . . . . . . . 53 92 3.4. Returning User Information . . . . . . . . . . . . . . . 53 93 3.5. Returning Dynamically-bound Reference Handles . . . . . . 54 94 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 56 95 3.7. Extending the Response . . . . . . . . . . . . . . . . . 56 96 4. Determining Authorization and Consent . . . . . . . . . . . . 56 97 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 59 98 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 60 99 4.1.2. Interaction at the User Code URI . . . . . . . . . . 60 100 4.1.3. Interaction through an Application URI . . . . . . . 61 101 4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 61 102 4.2.1. Completing Interaction with a Browser Redirect to the 103 Callback URI . . . . . . . . . . . . . . . . . . . . 62 104 4.2.2. Completing Interaction with a Direct HTTP Request 105 Callback . . . . . . . . . . . . . . . . . . . . . . 63 106 4.2.3. Calculating the interaction hash . . . . . . . . . . 64 107 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 65 108 5.1. Continuing After a Completed Interaction . . . . . . . . 67 109 5.2. Continuing During Pending Interaction . . . . . . . . . . 68 110 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 69 111 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 112 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 75 113 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 75 114 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 77 115 7. Securing Requests from the Client Instance . . . . . . . . . 78 116 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 78 117 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 80 118 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 80 119 7.3. Proving Possession of a Key with a Request . . . . . . . 81 120 7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 83 121 7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 87 122 7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 89 123 7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 93 124 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 97 125 8.1. Requesting Resources By Reference . . . . . . . . . . . . 100 126 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 102 127 9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 103 128 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 105 129 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 105 130 12. Security Considerations . . . . . . . . . . . . . . . . . . . 105 131 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 105 132 14. Normative References . . . . . . . . . . . . . . . . . . . . 105 133 Appendix A. Document History . . . . . . . . . . . . . . . . . . 108 134 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 110 135 Appendix C. Component Data Models . . . . . . . . . . . . . . . 113 136 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 113 137 D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 113 138 D.2. Secondary Device Interaction . . . . . . . . . . . . . . 117 139 D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 120 140 D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 121 141 D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 124 142 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 126 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 127 145 1. Introduction 147 This protocol allows a piece of software, the client instance, to 148 request delegated authorization to resource servers and to request 149 direct information. This delegation is facilitated by an 150 authorization server usually on behalf of a resource owner. The end- 151 user operating the software may interact with the authorization 152 server to authenticate, provide consent, and authorize the request. 154 The process by which the delegation happens is known as a grant, and 155 GNAP allows for the negotiation of the grant process over time by 156 multiple parties acting in distinct roles. 158 This specification focuses on the portions of the delegation process 159 facing the client instance. In particular, this specification 160 defines interoperable methods for a client instance to request, 161 negotiate, and receive access to information facilitated by the 162 authorization server. This specification also discusses discovery 163 mechanisms for the client instance to configure itself dynamically. 164 The means for an authorization server and resource server to 165 interoperate are discussed in the companion document, 166 [I-D.draft-ietf-gnap-resource-servers]. 168 The focus of this protocol is to provide interoperability between the 169 different parties acting in each role, and is not to specify 170 implementation details of each. Where appropriate, GNAP may make 171 recommendations about internal implementation details, but these 172 recommendations are to ensure the security of the overall deployment 173 rather than to be prescriptive in the implementation. 175 This protocol solves many of the same use cases as OAuth 2.0 176 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 177 have grown up around that ecosystem. However, GNAP is not an 178 extension of OAuth 2.0 and is not intended to be directly compatible 179 with OAuth 2.0. GNAP seeks to provide functionality and solve use 180 cases that OAuth 2.0 cannot easily or cleanly address. Appendix B 181 further details the protocol rationale compared to OAuth 2.0. GNAP 182 and OAuth 2.0 will likely exist in parallel for many deployments, and 183 considerations have been taken to facilitate the mapping and 184 transition from legacy systems to GNAP. Some examples of these can 185 be found in Appendix D.5. 187 1.1. Terminology 189 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 190 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 191 "OPTIONAL" in this document are to be interpreted as described in 192 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 193 capitals, as shown here. 195 This document contains non-normative examples of partial and complete 196 HTTP messages, JSON structures, URLs, query components, keys, and 197 other elements. Some examples use a single trailing backslash '' to 198 indicate line wrapping for long values, as per [RFC8792]. The "\" 199 character and leading spaces on wrapped lines are not part of the 200 value. 202 1.2. Roles 204 The parties in GNAP perform actions under different roles. Roles are 205 defined by the actions taken and the expectations leveraged on the 206 role by the overall protocol. 208 +-------------+ +------------+ 209 | | | | 210 |Authorization| | Resource | 211 | Server | | Server | 212 | |<-+ +---->| | 213 +-------------+ | | +------------+ 214 + | | 215 + | | 216 + | | 217 + | | 218 + | | 219 + +----------+ 220 + | Client | 221 + | Instance | 222 + +----------+ 223 + + 224 + + 225 + + 226 +-----------+ + +------------+ 227 | | + + + +| | 228 | Resource | | End | 229 | Owner | ~ ~ ~ ~ ~ ~ | User | 230 | | | | 231 +-----------+ +------------+ 233 Legend 235 + + + indicates interaction between a human and computer 236 ----- indicates interaction between two pieces of software 237 ~ ~ ~ indicates a potential equivalence or out-of-band communication between roles 239 Authorization Server (AS) server that grants delegated privileges to 240 a particular instance of client software in the form of access 241 tokens or other information (such as subject information). 243 Client application operated by an end-user that consumes resources 244 from one or several RSs, possibly requiring access privileges from 245 one or several ASs. 247 Example: a client can be a mobile application, a web application, 248 etc. 250 Note: this specification differentiates between a specific 251 instance (the client instance, identified by its unique key) and 252 the software running the instance (the client software). For some 253 kinds of client software, there could be many instances of that 254 software, each instance with a different key. 256 Resource Server (RS) server that provides operations on protected 257 resources, where operations require a valid access token issued by 258 an AS. 260 Resource Owner (RO) subject entity that may grant or deny operations 261 on resources it has authority upon. 263 Note: the act of granting or denying an operation may be manual 264 (i.e. through an interaction with a physical person) or automatic 265 (i.e. through predefined organizational rules). 267 End-user natural person that operates a client instance. 269 Note: that natural person may or may not be the same entity as the 270 RO. 272 The design of GNAP does not assume any one deployment architecture, 273 but instead attempts to define roles that can be fulfilled in a 274 number of different ways for different use cases. As long as a given 275 role fulfills all of its obligations and behaviors as defined by the 276 protocol, GNAP does not make additional requirements on its structure 277 or setup. 279 Multiple roles can be fulfilled by the same party, and a given party 280 can switch roles in different instances of the protocol. For 281 example, the RO and end-user in many instances are the same person, 282 where a user is authorizing the client instance to act on their own 283 behalf at the RS. In this case, one party fulfills both of the RO 284 and end-user roles, but the roles themselves are still defined 285 separately from each other to allow for other use cases where they 286 are fulfilled by different parties. 288 For another example, in some complex scenarios, an RS receiving 289 requests from one client instance can act as a client instance for a 290 downstream secondary RS in order to fulfill the original request. In 291 this case, one piece of software is both an RS and a client instance 292 from different perspectives, and it fulfills these roles separately 293 as far as the overall protocol is concerned. 295 A single role need not be deployed as a monolithic service. For 296 example, A client instance could have components that are installed 297 on the end-user's device as well as a back-end system that it 298 communicates with. If both of these components participate in the 299 delegation protocol, they are both considered part of the client 300 instance. If there are several copies of the client software that 301 run separately but all share the same key material, such as a 302 deployed cluster, then this cluster is considered a single client 303 instance. 305 In these cases, the distinct components of what is considered a GNAP 306 client instance may use any number of different communication 307 mechanisms between them, all of which would be considered an 308 implementation detail of the client instances and out of scope of 309 GNAP. 311 For another example, an AS could likewise be built out of many 312 constituent components in a distributed architecture. The component 313 that the client instance calls directly could be different from the 314 component that the RO interacts with to drive consent, since API 315 calls and user interaction have different security considerations in 316 many environments. Furthermore, the AS could need to collect 317 identity claims about the RO from one system that deals with user 318 attributes while generating access tokens at another system that 319 deals with security rights. From the perspective of GNAP, all of 320 these are pieces of the AS and together fulfill the role of the AS as 321 defined by the protocol. These pieces may have their own internal 322 communications mechanisms which are considered out of scope of GNAP. 324 1.3. Elements 326 In addition to the roles above, the protocol also involves several 327 elements that are acted upon by the roles throughout the process. 329 Attribute characteristics related to a subject. 331 Access Token a data artifact representing a set of rights and/or 332 attributes. 334 Note: an access token can be first issued to an client instance 335 (requiring authorization by the RO) and subsequently rotated. 337 Grant (verb): to permit an instance of client software to receive 338 some attributes at a specific time and valid for a specific 339 duration and/or to exercise some set of delegated rights to access 340 a protected resource (noun): the act of granting. 342 Privilege right or attribute associated with a subject. 344 Note: the RO defines and maintains the rights and attributes 345 associated to the protected resource, and might temporarily 346 delegate some set of those privileges to an end-user. This 347 process is refered to as privilege delegation. 349 Protected Resource protected API (Application Programming Interface) 350 served by an RS and that can be accessed by a client, if and only 351 if a valid access token is provided. 353 Note: to avoid complex sentences, the specification document may 354 simply refer to resource instead of protected resource. 356 Right ability given to a subject to perform a given operation on a 357 resource under the control of an RS. 359 Subject person, organization or device. 361 Subject Information statement asserted by an AS about a subject. 363 1.4. Sequences 365 GNAP can be used in a variety of ways to allow the core delegation 366 process to take place. Many portions of this process are 367 conditionally present depending on the context of the deployments, 368 and not every step in this overview will happen in all circumstances. 370 Note that a connection between roles in this process does not 371 necessarily indicate that a specific protocol message is sent across 372 the wire between the components fulfilling the roles in question, or 373 that a particular step is required every time. For example, for a 374 client instance interested in only getting subject information 375 directly, and not calling an RS, all steps involving the RS below do 376 not apply. 378 In some circumstances, the information needed at a given stage is 379 communicated out of band or is preconfigured between the components 380 or entities performing the roles. For example, one entity can fulfil 381 multiple roles, and so explicit communication between the roles is 382 not necessary within the protocol flow. Additionally some components 383 may not be involved in all use cases. For example, a client instance 384 could be calling the AS just to get direct user information and have 385 no need to get an access token to call an RS. 387 +------------+ +------------+ 388 | End-user | ~ ~ ~ ~ | Resource | 389 | | | Owner (RO) | 390 +------------+ +------------+ 391 + + 392 + + 393 (A) (B) 394 + + 395 + + 396 +--------+ + +------------+ 397 | Client | (1) + | Resource | 398 |Instance| + | Server | 399 | | +---------------+ | (RS) | 400 | |--(2)->| Authorization | | | 401 | |<-(3)--| Server | | | 402 | | | (AS) | | | 403 | |--(4)->| | | | 404 | |<-(5)--| | | | 405 | |--------------(6)------------->| | 406 | | | | (7) | | 407 | |<-------------(8)------------->| | 408 | |--(9)->| | | | 409 | |<-(10)-| | | | 410 | |--------------(11)------------>| | 411 | | | | (12) | | 412 | |-(13)->| | | | 413 | | | | | | 414 +--------+ +---------------+ +------------+ 416 Legend 417 + + + indicates a possible interaction with a human 418 ----- indicates an interaction between protocol roles 419 ~ ~ ~ indicates a potential equivalence or out-of-band 420 communication between roles 422 * (A) The end-user interacts with the client instance to indicate a 423 need for resources on behalf of the RO. This could identify the 424 RS the client instance needs to call, the resources needed, or the 425 RO that is needed to approve the request. Note that the RO and 426 end-user are often the same entity in practice, but some more 427 dynamic processes are discussed in 428 [I-D.draft-ietf-gnap-resource-servers]. 430 * (1) The client instance determines what access is needed and which 431 AS to approach for access. Note that for most situations, the 432 client instance is pre-configured with which AS to talk to and 433 which kinds of access it needs. 435 * (2) The client instance requests access at the AS (Section 2). 437 * (3) The AS processes the request and determines what is needed to 438 fulfill the request. The AS sends its response to the client 439 instance (Section 3). 441 * (B) If interaction is required, the AS interacts with the RO 442 (Section 4) to gather authorization. The interactive component of 443 the AS can function using a variety of possible mechanisms 444 including web page redirects, applications, challenge/response 445 protocols, or other methods. The RO approves the request for the 446 client instance being operated by the end-user. Note that the RO 447 and end-user are often the same entity in practice. 449 * (4) The client instance continues the grant at the AS (Section 5). 451 * (5) If the AS determines that access can be granted, it returns a 452 response to the client instance (Section 3) including an access 453 token (Section 3.2) for calling the RS and any directly returned 454 information (Section 3.4) about the RO. 456 * (6) The client instance uses the access token (Section 7.2) to 457 call the RS. 459 * (7) The RS determines if the token is sufficient for the request 460 by examining the token. The means of the RS determining this 461 access are out of scope of this specification, but some options 462 are discussed in [I-D.draft-ietf-gnap-resource-servers]. 464 * (8) The client instance calls the RS (Section 7.2) using the 465 access token until the RS or client instance determine that the 466 token is no longer valid. 468 * (9) When the token no longer works, the client instance fetches an 469 updated access token (Section 6.1) based on the rights granted in 470 (5). 472 * (10) The AS issues a new access token (Section 3.2) to the client 473 instance. 475 * (11) The client instance uses the new access token (Section 7.2) 476 to call the RS. 478 * (12) The RS determines if the new token is sufficient for the 479 request. The means of the RS determining this access are out of 480 scope of this specification, but some options are discussed in 481 [I-D.draft-ietf-gnap-resource-servers]. 483 * (13) The client instance disposes of the token (Section 6.2) once 484 the client instance has completed its access of the RS and no 485 longer needs the token. 487 The following sections and Appendix D contain specific guidance on 488 how to use GNAP in different situations and deployments. For 489 example, it is possible for the client instance to never request an 490 access token and never call an RS, just as it is possible for there 491 not to be a user involved in the delegation process. 493 1.4.1. Redirect-based Interaction 495 In this example flow, the client instance is a web application that 496 wants access to resources on behalf of the current user, who acts as 497 both the end-user and the resource owner (RO). Since the client 498 instance is capable of directing the user to an arbitrary URL and 499 receiving responses from the user's browser, interaction here is 500 handled through front-channel redirects using the user's browser. 501 The redirection URL used for interaction is a service hosted by the 502 AS in this example. The client instance uses a persistent session 503 with the user to ensure the same user that is starting the 504 interaction is the user that returns from the interaction. 506 +--------+ +--------+ +------+ 507 | Client | | AS | | User | 508 |Instance| | | | | 509 | |< (1) + Start Session + + + + + + + + + + + + + + + +| | 510 | | | | | | 511 | |--(2)--- Request Access --------->| | | | 512 | | | | | | 513 | |<-(3)-- Interaction Needed -------| | | | 514 | | | | | | 515 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 516 | | | | | | 517 | | | |<+ (5) +>| | 518 | | | | AuthN | | 519 | | | | | | 520 | | | |<+ (6) +>| | 521 | | | | AuthZ | | 522 | | | | | | 523 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 524 | | | | +------+ 525 | |--(8)--- Continue Request ------->| | 526 | | | | 527 | |<-(9)----- Grant Access ----------| | 528 | | | | 529 | | | | +--------+ 530 | |--(10)-- Access API ---------------------------->| RS | 531 | | | | | | 532 | |<-(11)-- API Response ---------------------------| | 533 | | | | +--------+ 534 +--------+ +--------+ 536 1. The client instance establishes a verifiable session to the 537 user, in the role of the end-user. 539 2. The client instance requests access to the resource (Section 2). 540 The client instance indicates that it can redirect to an 541 arbitrary URL (Section 2.5.1.1) and receive a redirect from the 542 browser (Section 2.5.2.1). The client instance stores 543 verification information for its redirect in the session created 544 in (1). 546 3. The AS determines that interaction is needed and responds 547 (Section 3) with a URL to send the user to (Section 3.3.1) and 548 information needed to verify the redirect (Section 3.3.4) in 549 (7). The AS also includes information the client instance will 550 need to continue the request (Section 3.1) in (8). The AS 551 associates this continuation information with an ongoing request 552 that will be referenced in (4), (6), and (8). 554 4. The client instance stores the verification and continuation 555 information from (3) in the session from (1). The client 556 instance then redirects the user to the URL (Section 4.1.1) 557 given by the AS in (3). The user's browser loads the 558 interaction redirect URL. The AS loads the pending request 559 based on the incoming URL generated in (3). 561 5. The user authenticates at the AS, taking on the role of the RO. 563 6. As the RO, the user authorizes the pending request from the 564 client instance. 566 7. When the AS is done interacting with the user, the AS redirects 567 the user back (Section 4.2.1) to the client instance using the 568 redirect URL provided in (2). The redirect URL is augmented 569 with an interaction reference that the AS associates with the 570 ongoing request created in (2) and referenced in (4). The 571 redirect URL is also augmented with a hash of the security 572 information provided in (2) and (3). The client instance loads 573 the verification information from (2) and (3) from the session 574 created in (1). The client instance calculates a hash 575 (Section 4.2.3) based on this information and continues only if 576 the hash validates. Note that the client instance needs to 577 ensure that the parameters for the incoming request match those 578 that it is expecting from the session created in (1). The 579 client instance also needs to be prepared for the end-user never 580 being returned to the client instance and handle timeouts 581 appropriately. 583 8. The client instance loads the continuation information from (3) 584 and sends the interaction reference from (7) in a request to 585 continue the request (Section 5.1). The AS validates the 586 interaction reference ensuring that the reference is associated 587 with the request being continued. 589 9. If the request has been authorized, the AS grants access to the 590 information in the form of access tokens (Section 3.2) and 591 direct subject information (Section 3.4) to the client instance. 593 10. The client instance uses the access token (Section 7.2) to call 594 the RS. 596 11. The RS validates the access token and returns an appropriate 597 response for the API. 599 An example set of protocol messages for this method can be found in 600 Appendix D.1. 602 1.4.2. User-code Interaction 604 In this example flow, the client instance is a device that is capable 605 of presenting a short, human-readable code to the user and directing 606 the user to enter that code at a known URL. The URL the user enters 607 the code at is an interactive service hosted by the AS in this 608 example. The client instance is not capable of presenting an 609 arbitrary URL to the user, nor is it capable of accepting incoming 610 HTTP requests from the user's browser. The client instance polls the 611 AS while it is waiting for the RO to authorize the request. The 612 user's interaction is assumed to occur on a secondary device. In 613 this example it is assumed that the user is both the end-user and RO, 614 though the user is not assumed to be interacting with the client 615 instance through the same web browser used for interaction at the AS. 617 +--------+ +--------+ +------+ 618 | Client | | AS | | User | 619 |Instance|--(1)--- Request Access --------->| | | | 620 | | | | | | 621 | |<-(2)-- Interaction Needed -------| | | | 622 | | | | | | 623 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 624 | | | | | | 625 | | | |<+ (4) + | | 626 | | | |Open URI | | 627 | | | | | | 628 | | | |<+ (5) +>| | 629 | | | | AuthN | | 630 | |--(9)--- Continue Request (A) --->| | | | 631 | | | |<+ (6) +>| | 632 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 633 | | | | | | 634 | | | |<+ (7) +>| | 635 | | | | AuthZ | | 636 | | | | | | 637 | | | |<+ (8) +>| | 638 | | | |Completed| | 639 | | | | | | 640 | |--(11)-- Continue Request (B) --->| | +------+ 641 | | | | 642 | |<-(12)----- Grant Access ---------| | 643 | | | | 644 | | | | +--------+ 645 | |--(13)-- Access API ---------------------------->| RS | 646 | | | | | | 647 | |<-(14)-- API Response ---------------------------| | 648 | | | | +--------+ 649 +--------+ +--------+ 650 1. The client instance requests access to the resource (Section 2). 651 The client instance indicates that it can display a user code 652 (Section 2.5.1.3). 654 2. The AS determines that interaction is needed and responds 655 (Section 3) with a user code to communicate to the user 656 (Section 3.3.3). This could optionally include a URL to direct 657 the user to, but this URL should be static and so could be 658 configured in the client instance's documentation. The AS also 659 includes information the client instance will need to continue 660 the request (Section 3.1) in (8) and (10). The AS associates 661 this continuation information with an ongoing request that will 662 be referenced in (4), (6), (8), and (10). 664 3. The client instance stores the continuation information from (2) 665 for use in (8) and (10). The client instance then communicates 666 the code to the user (Section 4.1.1) given by the AS in (2). 668 4. The user's directs their browser to the user code URL. This URL 669 is stable and can be communicated via the client software's 670 documentation, the AS documentation, or the client software 671 itself. Since it is assumed that the RO will interact with the 672 AS through a secondary device, the client instance does not 673 provide a mechanism to launch the RO's browser at this URL. 675 5. The end-user authenticates at the AS, taking on the role of the 676 RO. 678 6. The RO enters the code communicated in (3) to the AS. The AS 679 validates this code against a current request in process. 681 7. As the RO, the user authorizes the pending request from the 682 client instance. 684 8. When the AS is done interacting with the user, the AS indicates 685 to the RO that the request has been completed. 687 9. Meanwhile, the client instance loads the continuation 688 information stored at (3) and continues the request (Section 5). 689 The AS determines which ongoing access request is referenced 690 here and checks its state. 692 10. If the access request has not yet been authorized by the RO in 693 (6), the AS responds to the client instance to continue the 694 request (Section 3.1) at a future time through additional polled 695 continuation requests. This response can include updated 696 continuation information as well as information regarding how 697 long the client instance should wait before calling again. The 698 client instance replaces its stored continuation information 699 from the previous response (2). Note that the AS may need to 700 determine that the RO has not approved the request in a 701 sufficient amount of time and return an appropriate error to the 702 client instance. 704 11. The client instance continues to poll the AS (Section 5.2) with 705 the new continuation information in (9). 707 12. If the request has been authorized, the AS grants access to the 708 information in the form of access tokens (Section 3.2) and 709 direct subject information (Section 3.4) to the client instance. 711 13. The client instance uses the access token (Section 7.2) to call 712 the RS. 714 14. The RS validates the access token and returns an appropriate 715 response for the API. 717 An example set of protocol messages for this method can be found in 718 Appendix D.2. 720 1.4.3. Asynchronous Authorization 722 In this example flow, the end-user and RO roles are fulfilled by 723 different parties, and the RO does not interact with the client 724 instance. The AS reaches out asynchronously to the RO during the 725 request process to gather the RO's authorization for the client 726 instance's request. The client instance polls the AS while it is 727 waiting for the RO to authorize the request. 729 +--------+ +--------+ +------+ 730 | Client | | AS | | RO | 731 |Instance|--(1)--- Request Access --------->| | | | 732 | | | | | | 733 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 734 | | | |<+ (3) +>| | 735 | | | | AuthN | | 736 | |--(6)--- Continue Request (A) --->| | | | 737 | | | |<+ (4) +>| | 738 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 739 | | | | | | 740 | | | |<+ (5) +>| | 741 | | | |Completed| | 742 | | | | | | 743 | |--(8)--- Continue Request (B) --->| | +------+ 744 | | | | 745 | |<-(9)------ Grant Access ---------| | 746 | | | | 747 | | | | +--------+ 748 | |--(10)-- Access API ---------------------------->| RS | 749 | | | | | | 750 | |<-(11)-- API Response ---------------------------| | 751 | | | | +--------+ 752 +--------+ +--------+ 754 1. The client instance requests access to the resource (Section 2). 755 The client instance does not send any interactions modes to the 756 server, indicating that it does not expect to interact with the 757 RO. The client instance can also signal which RO it requires 758 authorization from, if known, by using the user request section 759 (Section 2.4). 761 2. The AS determines that interaction is needed, but the client 762 instance cannot interact with the RO. The AS responds 763 (Section 3) with the information the client instance will need 764 to continue the request (Section 3.1) in (6) and (8), including 765 a signal that the client instance should wait before checking 766 the status of the request again. The AS associates this 767 continuation information with an ongoing request that will be 768 referenced in (3), (4), (5), (6), and (8). 770 3. The AS determines which RO to contact based on the request in 771 (1), through a combination of the user request (Section 2.4), 772 the resources request (Section 2.1), and other policy 773 information. The AS contacts the RO and authenticates them. 775 4. The RO authorizes the pending request from the client instance. 777 5. When the AS is done interacting with the RO, the AS indicates to 778 the RO that the request has been completed. 780 6. Meanwhile, the client instance loads the continuation 781 information stored at (2) and continues the request (Section 5). 782 The AS determines which ongoing access request is referenced 783 here and checks its state. 785 7. If the access request has not yet been authorized by the RO in 786 (6), the AS responds to the client instance to continue the 787 request (Section 3.1) at a future time through additional 788 polling. This response can include refreshed credentials as 789 well as information regarding how long the client instance 790 should wait before calling again. The client instance replaces 791 its stored continuation information from the previous response 792 (2). Note that the AS may need to determine that the RO has not 793 approved the request in a sufficient amount of time and return 794 an appropriate error to the client instance. 796 8. The client instance continues to poll the AS (Section 5.2) with 797 the new continuation information from (7). 799 9. If the request has been authorized, the AS grants access to the 800 information in the form of access tokens (Section 3.2) and 801 direct subject information (Section 3.4) to the client instance. 803 10. The client instance uses the access token (Section 7.2) to call 804 the RS. 806 11. The RS validates the access token and returns an appropriate 807 response for the API. 809 An example set of protocol messages for this method can be found in 810 Appendix D.4. 812 1.4.4. Software-only Authorization 814 In this example flow, the AS policy allows the client instance to 815 make a call on its own behalf, without the need for a RO to be 816 involved at runtime to approve the decision. Since there is no 817 explicit RO, the client instance does not interact with an RO. 819 +--------+ +--------+ 820 | Client | | AS | 821 |Instance|--(1)--- Request Access --->| | 822 | | | | 823 | |<-(2)---- Grant Access -----| | 824 | | | | +--------+ 825 | |--(3)--- Access API ------------------->| RS | 826 | | | | | | 827 | |<-(4)--- API Response ------------------| | 828 | | | | +--------+ 829 +--------+ +--------+ 831 1. The client instance requests access to the resource (Section 2). 832 The client instance does not send any interactions modes to the 833 server. 835 2. The AS determines that the request is been authorized, the AS 836 grants access to the information in the form of access tokens 837 (Section 3.2) to the client instance. Note that direct subject 838 information (Section 3.4) is not generally applicable in this use 839 case, as there is no user involved. 841 3. The client instance uses the access token (Section 7.2) to call 842 the RS. 844 4. The RS validates the access token and returns an appropriate 845 response for the API. 847 An example set of protocol messages for this method can be found in 848 Appendix D.3. 850 1.4.5. Refreshing an Expired Access Token 852 In this example flow, the client instance receives an access token to 853 access a resource server through some valid GNAP process. The client 854 instance uses that token at the RS for some time, but eventually the 855 access token expires. The client instance then gets a new access 856 token by rotating the expired access token at the AS using the 857 token's management URL. 859 +--------+ +--------+ 860 | Client | | AS | 861 |Instance|--(1)--- Request Access ----------------->| | 862 | | | | 863 | |<-(2)--- Grant Access --------------------| | 864 | | | | 865 | | +--------+ | | 866 | |--(3)--- Access Resource --->| RS | | | 867 | | | | | | 868 | |<-(4)--- Success Response ---| | | | 869 | | | | | | 870 | | | | | | 871 | | | | | | 872 | |--(5)--- Access Resource --->| | | | 873 | | | | | | 874 | |<-(6)--- Error Response -----| | | | 875 | | +--------+ | | 876 | | | | 877 | |--(7)--- Rotate Token ------------------->| | 878 | | | | 879 | |<-(8)--- Rotated Token -------------------| | 880 | | | | 881 +--------+ +--------+ 883 1. The client instance requests access to the resource (Section 2). 885 2. The AS grants access to the resource (Section 3) with an access 886 token (Section 3.2) usable at the RS. The access token response 887 includes a token management URI. 889 3. The client instance uses the access token (Section 7.2) to call 890 the RS. 892 4. The RS validates the access token and returns an appropriate 893 response for the API. 895 5. Time passes and the client instance uses the access token to call 896 the RS again. 898 6. The RS validates the access token and determines that the access 899 token is expired The RS responds to the client instance with an 900 error. 902 7. The client instance calls the token management URI returned in 903 (2) to rotate the access token (Section 6.1). The client 904 instance uses the access token (Section 7.2) in this call as well 905 as the appropriate key, see the token rotation section for 906 details. 908 8. The AS validates the rotation request including the signature and 909 keys presented in (5) and returns a new access token 910 (Section 3.2.1). The response includes a new access token and 911 can also include updated token management information, which the 912 client instance will store in place of the values returned in 913 (2). 915 1.4.6. Requesting User Information 917 In this scenario, the client instance does not call an RS and does 918 not request an access token. Instead, the client instance only 919 requests and is returned direct subject information (Section 3.4). 920 Many different interaction modes can be used in this scenario, so 921 these are shown only in the abstract as functions of the AS here. 923 +--------+ +--------+ +------+ 924 | Client | | AS | | User | 925 |Instance| | | | | 926 | |--(1)--- Request Access --------->| | | | 927 | | | | | | 928 | |<-(2)--- Request Access ----------| | | | 929 | | | | | | 930 | |+ (3) + Facilitate Interaction + + + + + + + + + + > | | 931 | | | | | | 932 | | | |<+ (4) +>| | 933 | | | | AuthN | | 934 | | | | | | 935 | | | |<+ (5) +>| | 936 | | | | AuthZ | | 937 | | | | | | 938 | |< (6) + Signal Continuation + + + + + + + + + + + + +| | 939 | | | | +------+ 940 | |--(7)--- Continue Request ------->| | 941 | | | | 942 | |<-(8)----- Grant Access ----------| | 943 | | | | 944 +--------+ +--------+ 946 1. The client instance requests access to subject information 947 (Section 2). 949 2. The AS determines that interaction is needed and responds 950 (Section 3) with appropriate information for facilitating user 951 interaction (Section 3.3). 953 3. The client instance facilitates the user interacting with the AS 954 (Section 4) as directed in (2). 956 4. The user authenticates at the AS, taking on the role of the RO. 958 5. As the RO, the user authorizes the pending request from the 959 client instance. 961 6. When the AS is done interacting with the user, the AS returns the 962 user to the client instance and signals continuation. 964 7. The client instance loads the continuation information from (2) 965 and calls the AS to continue the request (Section 5). 967 8. If the request has been authorized, the AS grants access to the 968 requested direct subject information (Section 3.4) to the client 969 instance. At this stage, the user is generally considered 970 "logged in" to the client instance based on the identifiers and 971 assertions provided by the AS. Note that the AS can restrict the 972 subject information returned and it might not match what the 973 client instance requested, see the section on subject information 974 for details. 976 2. Requesting Access 978 To start a request, the client instance sends JSON [RFC8259] document 979 with an object as its root. Each member of the request object 980 represents a different aspect of the client instance's request. Each 981 field is described in detail in a section below. 983 access_token (object / array of objects) Describes the rights and 984 properties associated with the requested access token. 985 Section 2.1 987 subject (object) Describes the information about the RO that the 988 client instance is requesting to be returned directly in the 989 response from the AS. Section 2.2 991 client (object / string) Describes the client instance that is 992 making this request, including the key that the client instance 993 will use to protect this request and any continuation requests at 994 the AS and any user-facing information about the client instance 995 used in interactions. Section 2.3 997 user (object / string) Identifies the end-user to the AS in a manner 998 that the AS can verify, either directly or by interacting with the 999 end-user to determine their status as the RO. Section 2.4 1001 interact (object) Describes the modes that the client instance has 1002 for allowing the RO to interact with the AS and modes for the 1003 client instance to receive updates when interaction is complete. 1004 Section 2.5 1006 Additional members of this request object can be defined by 1007 extensions to this protocol as described in Section 2.6 1009 A non-normative example of a grant request is below: 1011 { 1012 "access_token": { 1013 "access": [ 1014 { 1015 "type": "photo-api", 1016 "actions": [ 1017 "read", 1018 "write", 1019 "dolphin" 1020 ], 1021 "locations": [ 1022 "https://server.example.net/", 1023 "https://resource.local/other" 1024 ], 1025 "datatypes": [ 1026 "metadata", 1027 "images" 1028 ] 1029 }, 1030 "dolphin-metadata" 1031 ] 1032 }, 1033 "client": { 1034 "display": { 1035 "name": "My Client Display Name", 1036 "uri": "https://example.net/client" 1037 }, 1038 "key": { 1039 "proof": "httpsig", 1040 "jwk": { 1041 "kty": "RSA", 1042 "e": "AQAB", 1043 "kid": "xyz-1", 1044 "alg": "RS256", 1045 "n": "kOB5rR4Jv0GMeL...." 1046 } 1047 } 1048 }, 1049 "interact": { 1050 "start": ["redirect"], 1051 "finish": { 1052 "method": "redirect", 1053 "uri": "https://client.example.net/return/123455", 1054 "nonce": "LKLTI25DK82FX4T4QFZC" 1055 } 1056 }, 1057 "subject": { 1058 "formats": ["iss_sub", "opaque"], 1059 "assertions": ["id_token"] 1060 } 1061 } 1063 The request and response MUST be sent as a JSON object in the body of 1064 the HTTP POST request with Content-Type "application/json", unless 1065 otherwise specified by the signature mechanism. 1067 The authorization server MUST include the HTTP "Cache-Control" 1068 response header field [RFC7234] with a value set to "no-store". 1070 2.1. Requesting Access to Resources 1072 If the client instance is requesting one or more access tokens for 1073 the purpose of accessing an API, the client instance MUST include an 1074 "access_token" field. This field MUST be an object (for a single 1075 access token (Section 2.1.1)) or an array of these objects (for 1076 multiple access tokens (Section 2.1.2)), as described in the 1077 following sections. 1079 2.1.1. Requesting a Single Access Token 1081 To request a single access token, the client instance sends an 1082 "acccess_token" object composed of the following fields. 1084 access (array of objects/strings) Describes the rights that the 1085 client instance is requesting for one or more access tokens to be 1086 used at RS's. This field is REQUIRED. Section 8 1088 label (string) A unique name chosen by the client instance to refer 1089 to the resulting access token. The value of this field is opaque 1090 to the AS. If this field is included in the request, the AS MUST 1091 include the same label in the token response (Section 3.2). This 1092 field is REQUIRED if used as part of a multiple access token 1093 request (Section 2.1.2), and is OPTIONAL otherwise. 1095 flags (array of strings) A set of flags that indicate desired 1096 attributes or behavior to be attached to the access token by the 1097 AS. This field is OPTIONAL. 1099 The values of the "flags" field defined by this specification are as 1100 follows: 1102 "bearer" If this flag is included, the access token being requested 1103 is a bearer token. If this flag is omitted, the access token is 1104 bound to the key used by the client instance in this request, or 1105 the key's most recent rotation. Methods for presenting bound and 1106 bearer access tokens are described in Section 7.2. [[ See issue 1107 #38 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/38) 1108 ]] 1110 "split" If this flag is included, the client instance is capable of 1111 receiving a different number of tokens than specified in the token 1112 request (Section 2.1), including receiving multiple access tokens 1113 (Section 3.2.2) in response to any single token request 1114 (Section 2.1.1) or a different number of access tokens than 1115 requested in a multiple access token request (Section 2.1.2). The 1116 "label" fields of the returned additional tokens are chosen by the 1117 AS. The client instance MUST be able to tell from the token 1118 response where and how it can use each of the access tokens. [[ 1119 See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1120 issues/37) ]] 1122 Flag values MUST NOT be included more than once. 1124 Additional flags can be defined by extensions using a registry TBD 1125 (Section 11). 1127 In the following example, the client instance is requesting access to 1128 a complex resource described by a pair of access request object. 1130 "access_token": { 1131 "access": [ 1132 { 1133 "type": "photo-api", 1134 "actions": [ 1135 "read", 1136 "write", 1137 "delete" 1138 ], 1139 "locations": [ 1140 "https://server.example.net/", 1141 "https://resource.local/other" 1142 ], 1143 "datatypes": [ 1144 "metadata", 1145 "images" 1146 ] 1147 }, 1148 { 1149 "type": "walrus-access", 1150 "actions": [ 1151 "foo", 1152 "bar" 1153 ], 1154 "locations": [ 1155 "https://resource.other/" 1156 ], 1157 "datatypes": [ 1158 "data", 1159 "pictures", 1160 "walrus whiskers" 1161 ] 1162 } 1163 ], 1164 "label": "token1-23", 1165 "flags": [ "split" ] 1166 } 1168 If access is approved, the resulting access token is valid for the 1169 described resource and is bound to the client instance's key (or its 1170 most recent rotation). The token is labeled "token1-23" and could be 1171 split into multiple access tokens by the AS, if the AS chooses. The 1172 token response structure is described in Section 3.2.1. 1174 2.1.2. Requesting Multiple Access Tokens 1176 To request multiple access tokens to be returned in a single 1177 response, the client instance sends an array of objects as the value 1178 of the "access_token" parameter. Each object MUST conform to the 1179 request format for a single access token request, as specified in 1180 requesting a single access token (Section 2.1.1). Additionally, each 1181 object in the array MUST include the "label" field, and all values of 1182 these fields MUST be unique within the request. If the client 1183 instance does not include a "label" value for any entry in the array, 1184 or the values of the "label" field are not unique within the array, 1185 the AS MUST return an error. 1187 The following non-normative example shows a request for two separate 1188 access tokens, "token1" and "token2". 1190 "access_token": [ 1191 { 1192 "label": "token1", 1193 "access": [ 1194 { 1195 "type": "photo-api", 1196 "actions": [ 1197 "read", 1198 "write", 1199 "dolphin" 1200 ], 1201 "locations": [ 1202 "https://server.example.net/", 1203 "https://resource.local/other" 1204 ], 1205 "datatypes": [ 1206 "metadata", 1207 "images" 1208 ] 1209 }, 1210 "dolphin-metadata" 1211 ] 1212 }, 1213 { 1214 "label": "token2", 1215 "access": [ 1216 { 1217 "type": "walrus-access", 1218 "actions": [ 1219 "foo", 1220 "bar" 1221 ], 1222 "locations": [ 1223 "https://resource.other/" 1224 ], 1225 "datatypes": [ 1226 "data", 1227 "pictures", 1228 "walrus whiskers" 1229 ] 1230 } 1231 ], 1232 "flags": [ "bearer" ] 1233 } 1234 ] 1235 All approved access requests are returned in the multiple access 1236 token response (Section 3.2.2) structure using the values of the 1237 "label" fields in the request. 1239 2.2. Requesting Subject Information 1241 If the client instance is requesting information about the RO from 1242 the AS, it sends a "subject" field as a JSON object. This object MAY 1243 contain the following fields (or additional fields defined in a 1244 registry TBD (Section 11)). 1246 formats (array of strings) An array of subject identifier subject 1247 types requested for the RO, as defined by 1248 [I-D.ietf-secevent-subject-identifiers]. 1250 assertions (array of strings) An array of requested assertion 1251 formats. Possible values include "id_token" for an [OIDC] ID 1252 Token and "saml2" for a SAML 2 assertion. Additional assertion 1253 values are defined by a registry TBD (Section 11). [[ See issue 1254 #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) 1255 ]] 1257 "subject": { 1258 "formats": [ "iss_sub", "opaque" ], 1259 "assertions": [ "id_token", "saml2" ] 1260 } 1262 The AS can determine the RO's identity and permission for releasing 1263 this information through interaction with the RO (Section 4), AS 1264 policies, or assertions presented by the client instance 1265 (Section 2.4). If this is determined positively, the AS MAY return 1266 the RO's information in its response (Section 3.4) as requested. 1268 Subject identifier types requested by the client instance serve only 1269 to identify the RO in the context of the AS and can't be used as 1270 communication channels by the client instance, as discussed in 1271 Section 3.4. 1273 The AS SHOULD NOT re-use subject identifiers for multiple different 1274 ROs. 1276 Note: the "formats" and "assertions" request fields are independent 1277 of each other, and a returned assertion MAY omit a requested subject 1278 identifier. 1280 [[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1281 issues/43) ]] 1283 2.3. Identifying the Client Instance 1285 When sending a non-continuation request to the AS, the client 1286 instance MUST identify itself by including the "client" field of the 1287 request and by signing the request as described in Section 7.3. Note 1288 that for a continuation request (Section 5), the client instance is 1289 identified by its association with the request being continued and so 1290 this field is not sent under those circumstances. 1292 When client instance information is sent by value, the "client" field 1293 of the request consists of a JSON object with the following fields. 1295 key (object / string) The public key of the client instance to be 1296 used in this request as described in Section 7.1 or a reference to 1297 a key as described in Section 7.1.1. This field is REQUIRED. 1299 class_id (string) An identifier string that the AS can use to 1300 identify the client software comprising this client instance. The 1301 contents and format of this field are up to the AS. This field is 1302 OPTIONAL. 1304 display (object) An object containing additional information that 1305 the AS MAY display to the RO during interaction, authorization, 1306 and management. This field is OPTIONAL. 1308 "client": { 1309 "key": { 1310 "proof": "httpsig", 1311 "jwk": { 1312 "kty": "RSA", 1313 "e": "AQAB", 1314 "kid": "xyz-1", 1315 "alg": "RS256", 1316 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 1317 }, 1318 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1319 }, 1320 "class_id": "web-server-1234", 1321 "display": { 1322 "name": "My Client Display Name", 1323 "uri": "https://example.net/client" 1324 } 1325 } 1327 Additional fields are defined in a registry TBD (Section 11). 1329 The client instance MUST prove possession of any presented key by the 1330 "proof" mechanism associated with the key in the request. Proof 1331 types are defined in a registry TBD (Section 11) and an initial set 1332 of methods is described in Section 7.3. 1334 Note that the AS MAY know the client instance's public key ahead of 1335 time, and the AS MAY apply different policies to the request 1336 depending on what has been registered against that key. If the same 1337 public key is sent by value on subsequent access requests, the AS 1338 SHOULD treat these requests as coming from the same client instance 1339 for purposes of identification, authentication, and policy 1340 application. If the AS does not know the client instance's public 1341 key ahead of time, the AS MAY accept or reject the request based on 1342 AS policy, attestations within the "client" request, and other 1343 mechanisms. 1345 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1346 issues/44) ]] 1348 2.3.1. Identifying the Client Instance by Reference 1350 If the client instance has an instance identifier that the AS can use 1351 to determine appropriate key information, the client instance can 1352 send this instance identifier as a direct reference value in lieu of 1353 the "client" object. The instance identifier MAY be assigned to a 1354 client instance at runtime through the Section 3.5 or MAY be obtained 1355 in another fashion, such as a static registration process at the AS. 1357 "client": "client-541-ab" 1359 When the AS receives a request with an instance identifier, the AS 1360 MUST ensure that the key used to sign the request (Section 7.3) is 1361 associated with the instance identifier. 1363 If the AS does not recognize the instance identifier, the request 1364 MUST be rejected with an error. 1366 If the client instance is identified in this manner, the registered 1367 key for the client instance MAY be a symmetric key known to the AS. 1368 The client instance MUST NOT send a symmetric key by value in the 1369 request, as doing so would expose the key directly instead of proving 1370 possession of it. 1372 2.3.2. Providing Displayable Client Instance Information 1374 If the client instance has additional information to display to the 1375 RO during any interactions at the AS, it MAY send that information in 1376 the "display" field. This field is a JSON object that declares 1377 information to present to the RO during any interactive sequences. 1379 name (string) Display name of the client software 1381 uri (string) User-facing web page of the client software 1383 logo_uri (string) Display image to represent the client software 1385 "display": { 1386 "name": "My Client Display Name", 1387 "uri": "https://example.net/client" 1388 } 1390 [[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1391 issues/48) ]] 1393 Additional display fields are defined by a registry TBD (Section 11). 1395 The AS SHOULD use these values during interaction with the RO. The 1396 values are for informational purposes only and MUST NOT be taken as 1397 authentic proof of the client instance's identity or source. The AS 1398 MAY restrict display values to specific client instances, as 1399 identified by their keys in Section 2.3. 1401 2.3.3. Authenticating the Client Instance 1403 If the presented key is known to the AS and is associated with a 1404 single instance of the client software, the process of presenting a 1405 key and proving possession of that key is sufficient to authenticate 1406 the client instance to the AS. The AS MAY associate policies with 1407 the client instance identified by this key, such as limiting which 1408 resources can be requested and which interaction methods can be used. 1409 For example, only specific client instances with certain known keys 1410 might be trusted with access tokens without the AS interacting 1411 directly with the RO as in Appendix D.3. 1413 The presentation of a key allows the AS to strongly associate 1414 multiple successive requests from the same client instance with each 1415 other. This is true when the AS knows the key ahead of time and can 1416 use the key to authenticate the client instance, but also if the key 1417 is ephemeral and created just for this series of requests. As such 1418 the AS MAY allow for client instances to make requests with unknown 1419 keys. This pattern allows for ephemeral client instances, such as 1420 single-page applications, and client software with many individual 1421 long-lived instances, such as mobile applications, to generate key 1422 pairs per instance and use the keys within the protocol without 1423 having to go through a separate registration step. The AS MAY limit 1424 which capabilities are made available to client instances with 1425 unknown keys. For example, the AS could have a policy saying that 1426 only previously-registered client instances can request particular 1427 resources, or that all client instances with unknown keys have to be 1428 interactively approved by an RO. 1430 2.4. Identifying the User 1432 If the client instance knows the identity of the end-user through one 1433 or more identifiers or assertions, the client instance MAY send that 1434 information to the AS in the "user" field. The client instance MAY 1435 pass this information by value or by reference. 1437 sub_ids (array of objects) An array of subject identifiers for the 1438 end-user, as defined by [I-D.ietf-secevent-subject-identifiers]. 1440 assertions (object) An object containing assertions as values keyed 1441 on the assertion type defined by a registry TBD (Section 11). 1442 Possible keys include "id_token" for an [OIDC] ID Token and 1443 "saml2" for a SAML 2 assertion. Additional assertion values are 1444 defined by a registry TBD (Section 11). [[ See issue #41 1445 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] 1447 "user": { 1448 "sub_ids": [ { 1449 "format": "opaque", 1450 "id": "J2G8G8O4AZ" 1451 } ], 1452 "assertions": { 1453 "id_token": "eyj..." 1454 } 1455 } 1457 Subject identifiers are hints to the AS in determining the RO and 1458 MUST NOT be taken as declarative statements that a particular RO is 1459 present at the client instance and acting as the end-user. 1460 Assertions SHOULD be validated by the AS. [[ See issue #49 1461 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1463 If the identified end-user does not match the RO present at the AS 1464 during an interaction step, the AS SHOULD reject the request with an 1465 error. 1467 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1468 issues/50) ]] 1470 If the AS trusts the client instance to present verifiable 1471 assertions, the AS MAY decide, based on its policy, to skip 1472 interaction with the RO, even if the client instance provides one or 1473 more interaction modes in its request. 1475 2.4.1. Identifying the User by Reference 1477 User reference identifiers can be dynamically issued by the AS 1478 (Section 3.5) to allow the client instance to represent the same end- 1479 user to the AS over subsequent requests. 1481 If the client instance has a reference for the end-user at this AS, 1482 the client instance MAY pass that reference as a string. The format 1483 of this string is opaque to the client instance. 1485 "user": "XUT2MFM1XBIKJKSDU8QM" 1487 User reference identifiers are not intended to be human-readable user 1488 identifiers or structured assertions. For the client instance to 1489 send either of these, use the full user request object (Section 2.4) 1490 instead. 1492 [[ See issue #51 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1493 issues/51) ]] 1495 If the AS does not recognize the user reference, it MUST return an 1496 error. 1498 2.5. Interacting with the User 1500 Often, the AS will require interaction with the RO (Section 4) in 1501 order to approve a requested delegation to the client instance for 1502 both access to resources and direct subject information. Many times 1503 the end-user using the client instance is the same person as the RO, 1504 and the client instance can directly drive interaction with the end 1505 user by facilitating the process through means such as redirection to 1506 a URL or launching an application. Other times, the client instance 1507 can provide information to start the RO's interaction on a secondary 1508 device, or the client instance will wait for the RO to approve the 1509 request asynchronously. The client instance could also be signaled 1510 that interaction has concluded through a callback mechanism. 1512 The client instance declares the parameters for interaction methods 1513 that it can support using the "interact" field. 1515 The "interact" field is a JSON object with three keys whose values 1516 declare how the client can initiate and complete the request, as well 1517 as provide hints to the AS about user preferences such as locale. A 1518 client instance MUST NOT declare an interaction mode it does not 1519 support. The client instance MAY send multiple modes in the same 1520 request. There is no preference order specified in this request. An 1521 AS MAY respond to any, all, or none of the presented interaction 1522 modes (Section 3.3) in a request, depending on its capabilities and 1523 what is allowed to fulfill the request. 1525 start (list of strings/objects) Indicates how the client instance 1526 can start an interaction. 1528 finish (object) Indicates how the client instance can receive an 1529 indication that interaction has finished at the AS. 1531 hints (object) Provides additional information to inform the 1532 interaction process at the AS. 1534 The "interact" field MUST contain the "start" key, and MAY contain 1535 the "finish" and "hints" keys. The value of each key is an array 1536 which contains strings or JSON objects as defined below. 1538 In this non-normative example, the client instance is indicating that 1539 it can redirect (Section 2.5.1.1) the end-user to an arbitrary URL 1540 and can receive a redirect (Section 2.5.2.1) through a browser 1541 request. 1543 "interact": { 1544 "start": ["redirect"], 1545 "finish": { 1546 "method": "redirect", 1547 "uri": "https://client.example.net/return/123455", 1548 "nonce": "LKLTI25DK82FX4T4QFZC" 1549 } 1550 } 1552 In this non-normative example, the client instance is indicating that 1553 it can display a user code (Section 2.5.1.3) and direct the end-user 1554 to an arbitrary URL (Section 2.5.1.1) on a secondary device, but it 1555 cannot accept a redirect or push callback. 1557 "interact": { 1558 "start": ["redirect", "user_code"] 1559 } 1560 If the client instance does not provide a suitable interaction 1561 mechanism, the AS cannot contact the RO asynchronously, and the AS 1562 determines that interaction is required, then the AS SHOULD return an 1563 error since the client instance will be unable to complete the 1564 request without authorization. 1566 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1567 provided, including user codes and redirection URLs. The client 1568 instance SHOULD apply suitable timeouts to any callback URLs. 1570 2.5.1. Start Mode Definitions 1572 This specification defines the following interaction start modes as 1573 an array of string values under the "start" key: 1575 "redirect" Indicates that the client instance can direct the end- 1576 user to an arbitrary URL for interaction. Section 2.5.1.1 1578 "app" Indicates that the client instance can launch an application 1579 on the end-user's device for interaction. Section 2.5.1.2 1581 "user_code" Indicates that the client instance can communicate a 1582 human-readable short code to the end-user for use with a stable 1583 URL. Section 2.5.1.3 1585 2.5.1.1. Redirect to an Arbitrary URL 1587 If the client instance is capable of directing the end-user to a URL 1588 defined by the AS at runtime, the client instance indicates this by 1589 sending the "redirect" field with the boolean value "true". The 1590 means by which the client instance will activate this URL is out of 1591 scope of this specification, but common methods include an HTTP 1592 redirect, launching a browser on the end-user's device, providing a 1593 scannable image encoding, and printing out a URL to an interactive 1594 console. While this URL is generally hosted at the AS, the client 1595 instance can make no assumptions about its contents, composition, or 1596 relationship to the AS grant URL. 1598 "interact": { 1599 "start": ["redirect"] 1600 } 1602 If this interaction mode is supported for this client instance and 1603 request, the AS returns a redirect interaction response 1604 Section 3.3.1. The client instance manages this interaction method 1605 as described in Section 4.1.1. 1607 2.5.1.2. Open an Application-specific URL 1609 If the client instance can open a URL associated with an application 1610 on the end-user's device, the client instance indicates this by 1611 sending the "app" field with boolean value "true". The means by 1612 which the client instance determines the application to open with 1613 this URL are out of scope of this specification. 1615 "interact": { 1616 "start": ["app"] 1617 } 1619 If this interaction mode is supported for this client instance and 1620 request, the AS returns an app interaction response with an app URL 1621 payload Section 3.3.2. The client instance manages this interaction 1622 method as described in Section 4.1.3. 1624 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1625 issues/54) ]] 1627 2.5.1.3. Display a Short User Code 1629 If the client instance is capable of displaying or otherwise 1630 communicating a short, human-entered code to the RO, the client 1631 instance indicates this by sending the "user_code" field with the 1632 boolean value "true". This code is to be entered at a static URL 1633 that does not change at runtime. While this URL is generally hosted 1634 at the AS, the client instance can make no assumptions about its 1635 contents, composition, or relationship to the AS grant URL. 1637 "interact": { 1638 "start": ["user_code"] 1639 } 1641 If this interaction mode is supported for this client instance and 1642 request, the AS returns a user code and interaction URL as specified 1643 in Section 3.3.3. The client instances manages this interaction 1644 method as described in Section 4.1.2 1646 2.5.2. Finish Interaction Modes 1648 If the client instance is capable of receiving a message from the AS 1649 indicating that the RO has completed their interaction, the client 1650 instance indicates this by sending the following members of an object 1651 under the "finish" key. 1653 method (string) REQUIRED. The callback method that the AS will use 1654 to contact the client instance. This specification defines the 1655 following interaction completion methods, with other values 1656 defined by a registry TBD (Section 11): 1658 "redirect" Indicates that the client instance can receive a 1659 redirect from the end-user's device after interaction with the 1660 RO has concluded. Section 2.5.2.1 1662 "push" Indicates that the client instance can receive an HTTP 1663 POST request from the AS after interaction with the RO has 1664 concluded. Section 2.5.2.2 1666 uri (string) REQUIRED. Indicates the URI that the AS will either 1667 send the RO to after interaction or send an HTTP POST request. 1668 This URI MAY be unique per request and MUST be hosted by or 1669 accessible by the client instance. This URI MUST NOT contain any 1670 fragment component. This URI MUST be protected by HTTPS, be 1671 hosted on a server local to the RO's browser ("localhost"), or use 1672 an application-specific URI scheme. If the client instance needs 1673 any state information to tie to the front channel interaction 1674 response, it MUST use a unique callback URI to link to that 1675 ongoing state. The allowable URIs and URI patterns MAY be 1676 restricted by the AS based on the client instance's presented key 1677 information. The callback URI SHOULD be presented to the RO 1678 during the interaction phase before redirect. 1680 nonce (string) REQUIRED. Unique value to be used in the calculation 1681 of the "hash" query parameter sent to the callback URL, must be 1682 sufficiently random to be unguessable by an attacker. MUST be 1683 generated by the client instance as a unique value for this 1684 request. 1686 hash_method (string) OPTIONAL. The hash calculation mechanism to be 1687 used for the callback hash in Section 4.2.3. Can be one of "sha3" 1688 or "sha2". If absent, the default value is "sha3". [[ See issue 1689 #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) 1690 ]] 1692 If this interaction mode is supported for this client instance and 1693 request, the AS returns a nonce for use in validating the callback 1694 response (Section 3.3.4). Requests to the callback URI MUST be 1695 processed as described in Section 4.2, and the AS MUST require 1696 presentation of an interaction callback reference as described in 1697 Section 5.1. 1699 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1700 issues/58) ]] 1702 [[ See issue #59 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1703 issues/59) ]] 1705 2.5.2.1. Receive an HTTP Callback Through the Browser 1707 A finish "method" value of "redirect" indicates that the client 1708 instance will expect a request from the RO's browser using the HTTP 1709 method GET as described in Section 4.2.1. 1711 "interact": { 1712 "finish": { 1713 "method": "redirect", 1714 "uri": "https://client.example.net/return/123455", 1715 "nonce": "LKLTI25DK82FX4T4QFZC" 1716 } 1717 } 1719 Requests to the callback URI MUST be processed by the client instance 1720 as described in Section 4.2.1. 1722 Since the incoming request to the callback URL is from the RO's 1723 browser, this method is usually used when the RO and end-user are the 1724 same entity. As such, the client instance MUST ensure the end-user 1725 is present on the request to prevent substitution attacks. 1727 2.5.2.2. Receive an HTTP Direct Callback 1729 A finish "method" value of "push" indicates that the client instance 1730 will expect a request from the AS directly using the HTTP method POST 1731 as described in Section 4.2.2. 1733 "interact": { 1734 "finish": { 1735 "method": "push", 1736 "uri": "https://client.example.net/return/123455", 1737 "nonce": "LKLTI25DK82FX4T4QFZC" 1738 } 1739 } 1741 Requests to the callback URI MUST be processed by the client instance 1742 as described in Section 4.2.2. 1744 Since the incoming request to the callback URL is from the AS and not 1745 from the RO's browser, the client instance MUST NOT require the end- 1746 user to be present on the incoming HTTP request. 1748 [[ See issue #60 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1749 issues/60) ]] 1751 2.5.3. Hints 1753 The "hints" key is an object describing one or more suggestions from 1754 the client instance that the AS can use to help drive user 1755 interaction. 1757 This specification defines the following properties under the "hints" 1758 key: 1760 ui_locales (array of strings) Indicates the end-user's preferred 1761 locales that the AS can use during interaction, particularly 1762 before the RO has authenticated. Section 2.5.3.1 1764 The following sections detail requests for interaction modes. 1765 Additional interaction modes are defined in a registry TBD 1766 (Section 11). 1768 2.5.3.1. Indicate Desired Interaction Locales 1770 If the client instance knows the end-user's locale and language 1771 preferences, the client instance can send this information to the AS 1772 using the "ui_locales" field with an array of locale strings as 1773 defined by [RFC5646]. 1775 "interact": { 1776 "hints": { 1777 "ui_locales": ["en-US", "fr-CA"] 1778 } 1779 } 1781 If possible, the AS SHOULD use one of the locales in the array, with 1782 preference to the first item in the array supported by the AS. If 1783 none of the given locales are supported, the AS MAY use a default 1784 locale. 1786 2.5.4. Extending Interaction Modes 1788 Additional interaction start modes, finish modes, and hints are 1789 defined in a registry TBD (Section 11). 1791 2.6. Extending The Grant Request 1793 The request object MAY be extended by registering new items in a 1794 registry TBD (Section 11). Extensions SHOULD be orthogonal to other 1795 parameters. Extensions MUST document any aspects where the extension 1796 item affects or influences the values or behavior of other request 1797 and response objects. 1799 3. Grant Response 1801 In response to a client instance's request, the AS responds with a 1802 JSON object as the HTTP entity body. Each possible field is detailed 1803 in the sections below 1805 continue (object) Indicates that the client instance can continue 1806 the request by making one or more continuation requests. 1807 Section 3.1 1809 access_token (object / array of objects) A single access token or 1810 set of access tokens that the client instance can use to call the 1811 RS on behalf of the RO. Section 3.2.1 1813 interact (object) Indicates that interaction through some set of 1814 defined mechanisms needs to take place. Section 3.3 1816 subject (object) Claims about the RO as known and declared by the 1817 AS. Section 3.4 1819 instance_id (string) An identifier this client instance can use to 1820 identify itself when making future requests. Section 3.5 1822 user_handle (string) An identifier this client instance can use to 1823 identify its current end-user when making future requests. 1824 Section 3.5 1826 error (object) An error code indicating that something has gone 1827 wrong. Section 3.6 1829 In this example, the AS is returning an interaction URL 1830 (Section 3.3.1), a callback nonce (Section 3.3.4), and a continuation 1831 response (Section 3.1). 1833 { 1834 "interact": { 1835 "redirect": "https://server.example.com/interact/4CF492ML\ 1836 VMSW9MKMXKHQ", 1837 "finish": "MBDOFXG4Y5CVJCX821LH" 1838 }, 1839 "continue": { 1840 "access_token": { 1841 "value": "80UPRY5NM33OMUKMKSKU", 1842 }, 1843 "uri": "https://server.example.com/tx" 1844 } 1845 } 1846 In this example, the AS is returning a bearer access token 1847 (Section 3.2.1) with a management URL and a subject identifier 1848 (Section 3.4) in the form of an opaque identifier. 1850 { 1851 "access_token": { 1852 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 1853 "flags": ["bearer"], 1854 "manage": "https://server.example.com/token/PRY5NM33O\ 1855 M4TB8N6BW7OZB8CDFONP219RP1L", 1856 }, 1857 "subject": { 1858 "sub_ids": [ { 1859 "format": "opaque", 1860 "id": "J2G8G8O4AZ" 1861 } ] 1862 } 1863 } 1865 In this example, the AS is returning set of subject identifiers 1866 (Section 3.4), simultaneously as an opaque identifier, an email 1867 address, and a decentralized identifier (DID). 1869 { 1870 "subject": { 1871 "sub_ids": [ { 1872 "subject_type": "opaque", 1873 "id": "J2G8G8O4AZ" 1874 }, { 1875 "format": "email", 1876 "email": "user@example.com" 1877 }, { 1878 "format": "did", 1879 "url": "did:example:123456" 1880 } ] 1881 } 1882 } 1884 3.1. Request Continuation 1886 If the AS determines that the request can be continued with 1887 additional requests, it responds with the "continue" field. This 1888 field contains a JSON object with the following properties. 1890 uri (string) REQUIRED. The URI at which the client instance can 1891 make continuation requests. This URI MAY vary per request, or MAY 1892 be stable at the AS if the AS includes an access token. The 1893 client instance MUST use this value exactly as given when making a 1894 continuation request (Section 5). 1896 wait (integer) RECOMMENDED. The amount of time in integer seconds 1897 the client instance SHOULD wait after receiving this continuation 1898 handle and calling the URI. 1900 access_token (object) REQUIRED. A unique access token for 1901 continuing the request, in the format specified in Section 3.2.1. 1902 This access token MUST be bound to the client instance's key used 1903 in the request and MUST NOT be a "bearer" token. As a 1904 consequence, the "flags" array of this access token MUST NOT 1905 contain the string "bearer" and the "key" field MUST be omitted. 1906 This access token MUST NOT be usable at resources outside of the 1907 AS. The client instance MUST present the access token in all 1908 requests to the continuation URI as described in Section 7.2. [[ 1909 See issue #66 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1910 issues/66) ]] 1912 { 1913 "continue": { 1914 "access_token": { 1915 "value": "80UPRY5NM33OMUKMKSKU" 1916 }, 1917 "uri": "https://server.example.com/continue", 1918 "wait": 60 1919 } 1920 } 1922 The client instance can use the values of this field to continue the 1923 request as described in Section 5. Note that the client instance 1924 MUST sign all continuation requests with its key as described in 1925 Section 7.3 and MUST present the access token in its continuation 1926 request. 1928 This field SHOULD be returned when interaction is expected, to allow 1929 the client instance to follow up after interaction has been 1930 concluded. 1932 3.2. Access Tokens 1934 If the AS has successfully granted one or more access tokens to the 1935 client instance, the AS responds with the "access_token" field. This 1936 field contains either a single access token as described in 1937 Section 3.2.1 or an array of access tokens as described in 1938 Section 3.2.2. 1940 The client instance uses any access tokens in this response to call 1941 the RS as described in Section 7.2. 1943 3.2.1. Single Access Token 1945 If the client instance has requested a single access token and the AS 1946 has granted that access token, the AS responds with the 1947 "access_token" field. The value of this field is an object with the 1948 following properties. 1950 value (string) REQUIRED. The value of the access token as a string. 1951 The value is opaque to the client instance. The value SHOULD be 1952 limited to ASCII characters to facilitate transmission over HTTP 1953 headers within other protocols without requiring additional 1954 encoding. 1956 label (string) REQUIRED for multiple access tokens, OPTIONAL for 1957 single access token. The value of the "label" the client instance 1958 provided in the associated token request (Section 2.1), if 1959 present. If the token has been split by the AS, the value of the 1960 "label" field is chosen by the AS and the "split" field is 1961 included and set to "true". 1963 manage (string) OPTIONAL. The management URI for this access token. 1964 If provided, the client instance MAY manage its access token as 1965 described in Section 6. This management URI is a function of the 1966 AS and is separate from the RS the client instance is requesting 1967 access to. This URI MUST NOT include the access token value and 1968 SHOULD be different for each access token issued in a request. 1970 access (array of objects/strings) RECOMMENDED. A description of the 1971 rights associated with this access token, as defined in Section 8. 1972 If included, this MUST reflect the rights associated with the 1973 issued access token. These rights MAY vary from what was 1974 requested by the client instance. 1976 expires_in (integer) OPTIONAL. The number of seconds in which the 1977 access will expire. The client instance MUST NOT use the access 1978 token past this time. An RS MUST NOT accept an access token past 1979 this time. Note that the access token MAY be revoked by the AS or 1980 RS at any point prior to its expiration. 1982 key (object / string) OPTIONAL. The key that the token is bound to, 1983 if different from the client instance's presented key. The key 1984 MUST be an object or string in a format described in Section 7.1. 1985 The client instance MUST be able to dereference or process the key 1986 information in order to be able to sign the request. 1988 flags (array of strings) OPTIONAL. A set of flags that represent 1989 attributes or behaviors of the access token issued by the AS. 1991 The values of the "flags" field defined by this specification are as 1992 follows: 1994 "bearer" This flag indicates whether the token is bound to the 1995 client instance's key. If the "bearer" flag is present, the 1996 access token is a bearer token, and the "key" field in this 1997 response MUST be omitted. If the "bearer" flag is omitted and the 1998 "key" field in this response is omitted, the token is bound the 1999 key used by the client instance (Section 2.3) in its request for 2000 access. If the "bearer" flag is omitted, and the "key" field is 2001 present, the token is bound to the key and proofing mechanism 2002 indicated in the "key" field. 2004 "durable" OPTIONAL. Flag indicating a hint of AS behavior on token 2005 rotation. If this flag is present, then the client instance can 2006 expect a previously-issued access token to continue to work after 2007 it has been rotated (Section 6.1) or the underlying grant request 2008 has been modified (Section 5.3), resulting in the issuance of new 2009 access tokens. If this flag is omitted, the client instance can 2010 anticipate a given access token will stop working after token 2011 rotation or grant request modification. Note that a token flagged 2012 as "durable" can still expire or be revoked through any normal 2013 means. 2015 "split" OPTIONAL. Flag indicating that this token was generated by 2016 issuing multiple access tokens in response to one of the client 2017 instance's token request (Section 2.1) objects. This behavior 2018 MUST NOT be used unless the client instance has specifically 2019 requested it by use of the "split" flag. 2021 Flag values MUST NOT be included more than once. 2023 Additional flags can be defined by extensions using a registry TBD 2024 (Section 11). 2026 The following non-normative example shows a single access token bound 2027 to the client instance's key used in the initial request, with a 2028 management URL, and that has access to three described resources (one 2029 using an object and two described by reference strings). 2031 "access_token": { 2032 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2033 "manage": "https://server.example.com/token/PRY5NM33O\ 2034 M4TB8N6BW7OZB8CDFONP219RP1L", 2035 "access": [ 2036 { 2037 "type": "photo-api", 2038 "actions": [ 2039 "read", 2040 "write", 2041 "dolphin" 2042 ], 2043 "locations": [ 2044 "https://server.example.net/", 2045 "https://resource.local/other" 2046 ], 2047 "datatypes": [ 2048 "metadata", 2049 "images" 2050 ] 2051 }, 2052 "read", "dolphin-metadata" 2053 ] 2054 } 2056 The following non-normative example shows a single bearer access 2057 token with access to two described resources. 2059 "access_token": { 2060 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2061 "flags": ["bearer"], 2062 "access": [ 2063 "finance", "medical" 2064 ] 2065 } 2067 If the client instance requested a single access token 2068 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2069 token structure unless the client instance sends the "split" flag as 2070 described in Section 2.1.1. 2072 If the AS has split the access token response, the response MUST 2073 include the "split" flag. 2075 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2076 issues/69) ]] 2078 3.2.2. Multiple Access Tokens 2080 If the client instance has requested multiple access tokens and the 2081 AS has granted at least one of them, the AS responds with the 2082 "access_token" field. The value of this field is a JSON array, the 2083 members of which are distinct access tokens as described in 2084 Section 3.2.1. Each object MUST have a unique "label" field, 2085 corresponding to the token labels chosen by the client instance in 2086 the multiple access token request (Section 2.1.2). 2088 In this non-normative example, two tokens are issued under the names 2089 "token1" and "token2", and only the first token has a management URL 2090 associated with it. 2092 "access_token": [ 2093 { 2094 "label": "token1", 2095 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2096 "manage": "https://server.example.com/token/PRY5NM33O\ 2097 M4TB8N6BW7OZB8CDFONP219RP1L", 2098 "access": [ "finance" ] 2099 }, 2100 { 2101 "label": "token2", 2102 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2103 "access": [ "medical" ] 2104 } 2105 } 2107 Each access token corresponds to one of the objects in the 2108 "access_token" array of the client instance's request 2109 (Section 2.1.2). 2111 The multiple access token response MUST be used when multiple access 2112 tokens are requested, even if only one access token is issued as a 2113 result of the request. The AS MAY refuse to issue one or more of the 2114 requested access tokens, for any reason. In such cases the refused 2115 token is omitted from the response and all of the other issued access 2116 tokens are included in the response the requested names appropriate 2117 names. 2119 If the client instance requested multiple access tokens 2120 (Section 2.1.2), the AS MUST NOT respond with a single access token 2121 structure, even if only a single access token is granted. In such 2122 cases, the AS responds with a multiple access token structure 2123 containing one access token. 2125 If the AS has split the access token response, the response MUST 2126 include the "split" flag in the "flags" array. 2128 "access_token": [ 2129 { 2130 "label": "split-1", 2131 "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", 2132 "flags": ["split"], 2133 "manage": "https://server.example.com/token/PRY5NM33O\ 2134 M4TB8N6BW7OZB8CDFONP219RP1L", 2135 "access": [ "fruits" ] 2136 }, 2137 { 2138 "label": "split-2", 2139 "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", 2140 "flags": ["split"], 2141 "access": [ "vegetables" ] 2142 } 2143 } 2145 Each access token MAY be bound to different keys with different 2146 proofing mechanisms. 2148 If token management (Section 6) is allowed, each access token SHOULD 2149 have different "manage" URIs. 2151 [[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2152 issues/70) ]] 2154 3.3. Interaction Modes 2156 If the client instance has indicated a capability to interact with 2157 the RO in its request (Section 2.5), and the AS has determined that 2158 interaction is both supported and necessary, the AS responds to the 2159 client instance with any of the following values in the "interact" 2160 field of the response. There is no preference order for interaction 2161 modes in the response, and it is up to the client instance to 2162 determine which ones to use. All supported interaction methods are 2163 included in the same "interact" object. 2165 redirect (string) Redirect to an arbitrary URL. Section 3.3.1 2167 app (string) Launch of an application URL. Section 3.3.2 2169 finish (string) A nonce used by the client instance to verify the 2170 callback after interaction is completed. Section 3.3.4 2172 user_code (object) Display a short user code. Section 3.3.3 2173 Additional interaction mode responses can be defined in a registry 2174 TBD (Section 11). 2176 The AS MUST NOT respond with any interaction mode that the client 2177 instance did not indicate in its request. The AS MUST NOT respond 2178 with any interaction mode that the AS does not support. Since 2179 interaction responses include secret or unique information, the AS 2180 SHOULD respond to each interaction mode only once in an ongoing 2181 request, particularly if the client instance modifies its request 2182 (Section 5.3). 2184 3.3.1. Redirection to an arbitrary URL 2186 If the client instance indicates that it can redirect to an arbitrary 2187 URL (Section 2.5.1.1) and the AS supports this mode for the client 2188 instance's request, the AS responds with the "redirect" field, which 2189 is a string containing the URL to direct the end-user to. This URL 2190 MUST be unique for the request and MUST NOT contain any security- 2191 sensitive information such as user identifiers or access tokens. 2193 "interact": { 2194 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2195 } 2197 The URL returned is a function of the AS, but the URL itself MAY be 2198 completely distinct from the URL the client instance uses to request 2199 access (Section 2), allowing an AS to separate its user-interactive 2200 functionality from its back-end security functionality. If the AS 2201 does not directly host the functionality accessed through the given 2202 URL, then the means for the interaction functionality to communicate 2203 with the rest of the AS are out of scope for this specification. 2205 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2206 issues/72) ]] 2208 The client instance sends the end-user to the URL to interact with 2209 the AS. The client instance MUST NOT alter the URL in any way. The 2210 means for the client instance to send the end-user to this URL is out 2211 of scope of this specification, but common methods include an HTTP 2212 redirect, launching the system browser, displaying a scannable code, 2213 or printing out the URL in an interactive console. See details of 2214 the interaction in Section 4.1.1. 2216 3.3.2. Launch of an application URL 2218 If the client instance indicates that it can launch an application 2219 URL (Section 2.5.1.2) and the AS supports this mode for the client 2220 instance's request, the AS responds with the "app" field, which is a 2221 string containing the URL for the client instance to launch. This 2222 URL MUST be unique for the request and MUST NOT contain any security- 2223 sensitive information such as user identifiers or access tokens. 2225 "interact": { 2226 "app": "https://app.example.com/launch?tx=4CF492MLV" 2227 } 2229 The means for the launched application to communicate with the AS are 2230 out of scope for this specification. 2232 The client instance launches the URL as appropriate on its platform, 2233 and the means for the client instance to launch this URL is out of 2234 scope of this specification. The client instance MUST NOT alter the 2235 URL in any way. The client instance MAY attempt to detect if an 2236 installed application will service the URL being sent before 2237 attempting to launch the application URL. See details of the 2238 interaction in Section 4.1.3. 2240 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2241 issues/71) ]] 2243 3.3.3. Display of a Short User Code 2245 If the client instance indicates that it can display a short 2246 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2247 for the client instance's request, the AS responds with a "user_code" 2248 field. This field is an object that contains the following members. 2250 code (string) REQUIRED. A unique short code that the user can type 2251 into an authorization server. This string MUST be case- 2252 insensitive, MUST consist of only easily typeable characters (such 2253 as letters or numbers). The time in which this code will be 2254 accepted SHOULD be short lived, such as several minutes. It is 2255 RECOMMENDED that this code be no more than eight characters in 2256 length. 2258 url (string) RECOMMENDED. The interaction URL that the client 2259 instance will direct the RO to. This URL MUST be stable such that 2260 client instances can be statically configured with it. 2262 "interact": { 2263 "user_code": { 2264 "code": "A1BC-3DFF", 2265 "url": "https://srv.ex/device" 2266 } 2267 } 2269 The client instance MUST communicate the "code" to the end-user in 2270 some fashion, such as displaying it on a screen or reading it out 2271 audibly. 2273 The client instance SHOULD also communicate the URL if possible to 2274 facilitate user interaction, but since the URL should be stable, the 2275 client instance should be able to safely decide to not display this 2276 value. As this interaction mode is designed to facilitate 2277 interaction via a secondary device, it is not expected that the 2278 client instance redirect the end-user to the URL given here at 2279 runtime. Consequently, the URL needs to be stable enough that a 2280 client instance could be statically configured with it, perhaps 2281 referring the end-user to the URL via documentation instead of 2282 through an interactive means. If the client instance is capable of 2283 communicating an arbitrary URL to the end-user, such as through a 2284 scannable code, the client instance can use the "redirect" 2285 (Section 2.5.1.1) mode for this purpose instead of or in addition to 2286 the user code mode. 2288 The URL returned is a function of the AS, but the URL itself MAY be 2289 completely distinct from the URL the client instance uses to request 2290 access (Section 2), allowing an AS to separate its user-interactive 2291 functionality from its back-end security functionality. If the AS 2292 does not directly host the functionality accessed through the given 2293 URL, then the means for the interaction functionality to communicate 2294 with the rest of the AS are out of scope for this specification. 2296 See details of the interaction in Section 4.1.2. 2298 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2299 issues/72) ]] 2301 3.3.4. Interaction Finish 2303 If the client instance indicates that it can receive a 2304 post-interaction redirect or push at a URL (Section 2.5.2) and the AS 2305 supports this mode for the client instance's request, the AS responds 2306 with a "finish" field containing a nonce that the client instance 2307 will use in validating the callback as defined in Section 4.2. 2309 "interact": { 2310 "finish": "MBDOFXG4Y5CVJCX821LH" 2311 } 2313 When the interaction is completed, the interaction component MUST 2314 contact the client instance using either a redirect or launch of the 2315 RO's browser or through an HTTP POST to the client instance's 2316 callback URL using the method indicated in the interaction request 2317 (Section 2.5.2) as described in Section 4.2. 2319 If the AS returns a nonce, the client instance MUST NOT continue a 2320 grant request before it receives the associated interaction reference 2321 on the callback URI. See details in Section 4.2. 2323 3.3.5. Extending Interaction Mode Responses 2325 Extensions to this specification can define new interaction mode 2326 responses in a registry TBD (Section 11). Extensions MUST document 2327 the corresponding interaction request. 2329 3.4. Returning User Information 2331 If information about the RO is requested and the AS grants the client 2332 instance access to that data, the AS returns the approved information 2333 in the "subject" response field. This field is an object with the 2334 following OPTIONAL properties. 2336 sub_ids (array of objects) An array of subject identifiers for the 2337 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2339 assertions (object) An object containing assertions as values keyed 2340 on the assertion type defined by a registry TBD (Section 11). [[ 2341 See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2342 issues/41) ]] 2344 updated_at (string) Timestamp as an ISO8610 date string, indicating 2345 when the identified account was last updated. The client instance 2346 MAY use this value to determine if it needs to request updated 2347 profile information through an identity API. The definition of 2348 such an identity API is out of scope for this specification. 2350 "subject": { 2351 "sub_ids": [ { 2352 "format": "opaque", 2353 "id": "J2G8G8O4AZ" 2354 } ], 2355 "assertions": { 2356 "id_token": "eyj..." 2357 } 2358 } 2360 The AS MUST return the "subject" field only in cases where the AS is 2361 sure that the RO and the end-user are the same party. This can be 2362 accomplished through some forms of interaction with the RO 2363 (Section 4). 2365 Subject identifiers returned by the AS SHOULD uniquely identify the 2366 RO at the AS. Some forms of subject identifier are opaque to the 2367 client instance (such as the subject of an issuer and subject pair), 2368 while others forms (such as email address and phone number) are 2369 intended to allow the client instance to correlate the identifier 2370 with other account information at the client instance. The AS MUST 2371 ensure that the returned subject identifiers only apply to the 2372 authenticated end user. The client instance MUST NOT request or use 2373 any returned subject identifiers for communication purposes (see 2374 Section 2.2). That is, a subject identifier returned in the format 2375 of an email address or a phone number only identifies the RO to the 2376 AS and does not indicate that the AS has validated that the 2377 represented email address or phone number in the identifier is 2378 suitable for communication with the current user. To get such 2379 information, the client instance MUST use an identity protocol to 2380 request and receive additional identity claims. The details of an 2381 identity protocol and associated schema are outside the scope of this 2382 specification. 2384 Extensions to this specification MAY define additional response 2385 properties in a registry TBD (Section 11). 2387 3.5. Returning Dynamically-bound Reference Handles 2389 Many parts of the client instance's request can be passed as either a 2390 value or a reference. The use of a reference in place of a value 2391 allows for a client instance to optimize requests to the AS. 2393 Some references, such as for the client instance's identity 2394 (Section 2.3.1) or the requested resources (Section 8.1), can be 2395 managed statically through an admin console or developer portal 2396 provided by the AS or RS. The developer of the client software can 2397 include these values in their code for a more efficient and compact 2398 request. 2400 If desired, the AS MAY also generate and return some of these 2401 references dynamically to the client instance in its response to 2402 facilitate multiple interactions with the same software. The client 2403 instance SHOULD use these references in future requests in lieu of 2404 sending the associated data value. These handles are intended to be 2405 used on future requests. 2407 Dynamically generated handles are string values that MUST be 2408 protected by the client instance as secrets. Handle values MUST be 2409 unguessable and MUST NOT contain any sensitive information. Handle 2410 values are opaque to the client instance. 2412 All dynamically generated handles are returned as fields in the root 2413 JSON object of the response. This specification defines the 2414 following dynamic handle returns, additional handles can be defined 2415 in a registry TBD (Section 11). 2417 instance_id (string) A string value used to represent the 2418 information in the "client" object that the client instance can 2419 use in a future request, as described in Section 2.3.1. 2421 user_handle (string) A string value used to represent the current 2422 user. The client instance can use in a future request, as 2423 described in Section 2.4.1. 2425 This non-normative example shows two handles along side an issued 2426 access token. 2428 { 2429 "user_handle": "XUT2MFM1XBIKJKSDU8QM", 2430 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2431 "access_token": { 2432 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 2433 } 2434 } 2436 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2437 issues/77) ]] 2439 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2440 issues/78) ]] 2442 3.6. Error Response 2444 If the AS determines that the request cannot be issued for any 2445 reason, it responds to the client instance with an error message. 2447 error (string) The error code. 2449 { 2451 "error": "user_denied" 2453 } 2455 The error code is one of the following, with additional values 2456 available in a registry TBD (Section 11): 2458 user_denied The RO denied the request. 2460 too_fast The client instance did not respect the timeout in the wait 2461 response. 2463 unknown_request The request referenced an unknown ongoing access 2464 request. 2466 [[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2467 issues/79) ]] 2469 3.7. Extending the Response 2471 Extensions to this specification MAY define additional fields for the 2472 grant response in a registry TBD (Section 11). 2474 4. Determining Authorization and Consent 2476 When the client instance makes its Section 2 to the AS for delegated 2477 access, it is capable of asking for several different kinds of 2478 information in response: 2480 * the access being requested in the "access_token" request parameter 2482 * the subject information being requested in the "subject" request 2483 parameter 2485 * any additional requested information defined by extensions of this 2486 protocol 2488 The AS determines what authorizations and consents are required to 2489 fulfill this requested delegation. The details of how the AS makes 2490 this determination are out of scope for this document. However, 2491 there are several common patterns defined and supported by GNAP for 2492 fulfilling these requirements, including information sent by the 2493 client instance, information gathered through the interaction 2494 process, and information supplied by external parties. An individual 2495 AS can define its own policies and processes for deciding when and 2496 how to gather the necessary authorizations and consent. 2498 The client instance can supply information directly to the AS in its 2499 request. From this information, the AS can determine if the 2500 requested delegation can be granted immediately. The client instance 2501 can send several kinds of things, including: 2503 * the identity of the client instance, known from the presented keys 2504 or associated identifiers 2506 * the identity of the end user presented in the "user" request 2507 parameter 2509 * any additional information presented by the client instance in the 2510 request, including any extensions 2512 The AS will verify this presented information in the context of the 2513 client instance's request and can only trust the information as much 2514 as it trusts the presentation and context of the information. If the 2515 AS determines that the information presented in the initial request 2516 is sufficient for granting the requested access, the AS MAY return 2517 the positive results immediately in its Section 3 with access tokens 2518 and subject information. 2520 If the AS determines that additional runtime authorization is 2521 required, the AS can either deny the request outright or use a number 2522 of means at its disposal to gather that authorization from the 2523 appropriate ROs, including for example: 2525 * starting interaction with the end user facilitated by the client 2526 software, such as a redirection or user code 2528 * challenging the client instance through a challenge-response 2529 mechanism 2531 * requesting that the client instance present specific additional 2532 information, such as a user's credential or an assertion 2534 * contacting a RO through an out-of-band mechanism, such as a push 2535 notification 2537 * contacting an auxiliary software process through an out-of-band 2538 mechanism, such as querying a digital wallet 2540 The authorization and consent gathering process in GNAP is left 2541 deliberately flexible to allow for a wide variety of different 2542 deployments, interactions, and methodologies. In this process, the 2543 AS can gather consent from the RO as necessitated by the access that 2544 has been requested. The AS can sometimes determine which RO needs to 2545 consent based on what has been requested by the client instance, such 2546 as a specific RS record, an identified user, or a request requiring 2547 specific access such as approval by an administrator. If the AS has 2548 a means of contacting the RO directly, it could do so without 2549 involving the client instance in its consent gathering process. For 2550 example, the AS could push a notification to a known RO and have the 2551 RO approve the pending request asynchronously. These interactions 2552 can be through an interface of the AS itself (such as a hosted web 2553 page), through another application (such as something installed on 2554 the RO's device), through a messaging fabric, or any other means. 2555 When interacting with an RO, the AS can do anything it needs to 2556 determine the authorization of the requested grant, including: 2558 * authenticate the RO, through a local account or some other means 2559 such as federated login 2561 * validate the RO through presentation of claims, attributes, or 2562 other information 2564 * prompt the RO for consent for the requested delegation 2566 * describe to the RO what information is being released, to whom, 2567 and for what purpose 2569 * provide warnings to the RO about potential attacks or negative 2570 effects of allowing the information 2572 * allow the RO to modify the client instance's requested access, 2573 including limiting or expanding that access 2575 * provide the RO with artifacts such as receipts to facilitate an 2576 audit trail of authorizations 2578 * allow the RO to deny the requested delegation 2580 The AS is also allowed to request authorization from more than one 2581 RO, if the AS deems fit. For example, a medical record might need to 2582 be released by both an attending nurse and a physician, or both 2583 owners of a bank account need to sign off on a transfer request. 2584 Alternatively, the AS could require N of M possible RO's to approve a 2585 given request in order. The AS could also determine that the end 2586 user is not the appropriate RO for a given request and reach out to 2587 the appropriate RO asynchronously. The details of determining which 2588 RO's are required for a given request are out of scope for this 2589 specification. 2591 The client instance can also indicate that it is capable of 2592 facilitating interaction with the end user, another party, or another 2593 piece of software through its interaction start (Section 2.5.1) 2594 request. In many cases, the end user is delegating their own access 2595 as RO to the client instance. Here, the AS needs to determine the 2596 identity of the end user and will often need to interact directly 2597 with the end user to determine their status as an RO and collect 2598 their consent. If the AS has determined that authorization is 2599 required and the AS can support one or more of the requested 2600 interaction start methods, the AS returns the associated interaction 2601 start responses (Section 3.3). The client instance SHOULD initiate 2602 one or more of these interaction methods (Section 4.1) in order to 2603 facilitate the granting of the request. If more than one interaction 2604 start method is available, the means by which the client chooses 2605 which methods to follow is out of scope of this specification. The 2606 client instance MUST use each interaction method once at most. 2608 After starting interaction, the client instance can then make a 2609 continuation request (Section 5) either in response to a signal 2610 indicating the finish of the interaction (Section 4.2), through 2611 polling, or through some other method defined by an extension of this 2612 specification. 2614 If the AS and client instance have not reached a state where the 2615 delegation can be granted, the AS and client instance can repeat the 2616 interaction process as long as the AS supplies the client instance 2617 with continuation information (Section 3.1) to facilitate the ongoing 2618 requests. 2620 4.1. Interaction Start Methods 2622 To initiate an interaction start method indicated by the interaction 2623 start responses (Section 3.3) from the AS, the client instance 2624 follows the steps defined by that interaction method. The actions of 2625 the client instance required for the interaction start modes defined 2626 in this specification are described in the following sections. 2628 4.1.1. Interaction at a Redirected URI 2630 When the end user is directed to an arbitrary URI through the 2631 "redirect" (Section 3.3.1) mode, the client instance facilitates 2632 opening the URI through the end user's web browser. The client 2633 instance could launch the URI through the system browser, provide a 2634 clickable link, redirect the user through HTTP response codes, or 2635 display the URI in a form the end user can use to launch such as a 2636 multidimensional barcode. With this method, it is common (though not 2637 required) for the RO to be the same party as the end-user, since the 2638 client instance has to communicate the redirection URI to the end- 2639 user. 2641 In many cases, the URI indicates a web page hosted at the AS, 2642 allowing the AS to authenticate the end user as the RO and 2643 interactively provide consent. If the URI is hosted by the AS, the 2644 AS MUST determine the grant request being referenced from the URL 2645 value itself. If the URL cannot be associated with a currently 2646 active request, the AS MUST display an error to the RO and MUST NOT 2647 attempt to redirect the RO back to any client instance even if a 2648 redirect finish method is supplied (Section 2.5.2.1). If the URI is 2649 not hosted by the AS directly, the means of communication between the 2650 AS and this URI are out of scope for this specification. 2652 The client instance MUST NOT modify the URI when launching it, in 2653 particular the client instance MUST NOT add any parameters to the 2654 URI. The URI MUST be reachable from the end user's browser, though 2655 the URI MAY be opened on a separate device from the client instance 2656 itself. The URI MUST be accessible from an HTTP GET request and MUST 2657 be protected by HTTPS or equivalent means. 2659 4.1.2. Interaction at the User Code URI 2661 When the end user is directed to enter a short code through the 2662 "user_code" (Section 3.3.3) mode, the client instance communicates 2663 the user code to the end-user and directs the end user to enter that 2664 code at an associated URI. This mode is used when the client 2665 instance is not able to facilitate launching an arbitrary URI. The 2666 associated URI could be statically configured with the client 2667 instance or communicated in the response from the AS, but the client 2668 instance communicates that URL to the end user. As a consequence, 2669 these URIs SHOULD be short. 2671 In many cases, the URI indicates a web page hosted at the AS, 2672 allowing the AS to authenticate the end user as the RO and 2673 interactively provide consent. If the URI is hosted by the AS, the 2674 AS MUST determine the grant request being referenced from the user 2675 code. If the user code cannot be associated with a currently active 2676 request, the AS MUST display an error to the RO and MUST NOT attempt 2677 to redirect the RO back to any client instance even if a redirect 2678 finish method is supplied (Section 2.5.2.1). If the interaction 2679 component at the user code URI is not hosted by the AS directly, the 2680 means of communication between the AS and this URI, including 2681 communication of the user code itself, are out of scope for this 2682 specification. 2684 When the RO enters this code at the user code URI, the AS MUST 2685 uniquely identify the pending request that the code was associated 2686 with. If the AS does not recognize the entered code, the interaction 2687 component MUST display an error to the user. If the AS detects too 2688 many unrecognized code enter attempts, the interaction component 2689 SHOULD display an error to the user and MAY take additional actions 2690 such as slowing down the input interactions. The user should be 2691 warned as such an error state is approached, if possible. 2693 The client instance MUST NOT modify the URI when launching it, in 2694 particular the client instance MUST NOT add any parameters to the 2695 URI. The user code URI MUST be reachable from the end user's 2696 browser, though the URI is usually be opened on a separate device 2697 from the client instance itself. The URI MUST be accessible from an 2698 HTTP GET request and MUST be protected by HTTPS or equivalent means. 2700 4.1.3. Interaction through an Application URI 2702 When the client instance is directed to launch an application through 2703 the "app" (Section 3.3.2) mode, the client launches the URL as 2704 appropriate to the system, such as through a deep link or custom URI 2705 scheme registered to a mobile application. The means by which the AS 2706 and the launched application communicate with each other and perform 2707 any of the required actions are out of scope for this specification. 2709 4.2. Post-Interaction Completion 2711 If an interaction "finish" (Section 3.3.4) method is associated with 2712 the current request, the AS MUST follow the appropriate method at 2713 upon completion of interaction in order to signal the client instance 2714 to continue, except for some limited error cases discussed below. If 2715 a finish method is not available, the AS SHOULD instruct the RO to 2716 return to the client instance upon completion. 2718 The AS MUST create an interaction reference and associate that 2719 reference with the current interaction and the underlying pending 2720 request. This interaction reference value MUST be sufficiently 2721 random so as not to be guessable by an attacker. The interaction 2722 reference MUST be one-time-use to prevent interception and replay 2723 attacks. 2725 The AS MUST calculate a hash value based on the client instance and 2726 AS nonces and the interaction reference, as described in 2727 Section 4.2.3. The client instance will use this value to validate 2728 the "finish" call. 2730 The AS MUST send the hash and interaction reference based on the 2731 interaction finish mode as described in the following sections. 2733 Note that the "finish" method still occurs in many error cases, such 2734 as when the RO has denied access. This pattern allows the client 2735 instance to potentially recover from the error state by modifying its 2736 request or providing additional information directly to the AS in a 2737 continuation request. The AS MUST NOT follow the "finish" method in 2738 the following circumstances: 2740 * The AS has determined that any URIs involved with the finish 2741 method are dangerous or blocked. 2743 * The AS cannot determine which ongoing grant request is being 2744 referenced. 2746 * The ongoing grant request has been cancelled or otherwise blocked. 2748 4.2.1. Completing Interaction with a Browser Redirect to the Callback 2749 URI 2751 When using the "redirect" interaction finish method (Section 3.3.4), 2752 the AS signals to the client instance that interaction is complete 2753 and the request can be continued by directing the RO (in their 2754 browser) back to the client instance's redirect URL sent in the 2755 callback request (Section 2.5.2.1). 2757 The AS secures this redirect by adding the hash and interaction 2758 reference as query parameters to the client instance's redirect URL. 2760 hash REQUIRED. The interaction hash value as described in 2761 Section 4.2.3. 2763 interact_ref REQUIRED. The interaction reference generated for this 2764 interaction. 2766 The means of directing the RO to this URL are outside the scope of 2767 this specification, but common options include redirecting the RO 2768 from a web page and launching the system browser with the target URL. 2770 https://client.example.net/return/123455\ 2771 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 2772 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 2773 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2775 When receiving the request, the client instance MUST parse the query 2776 parameters to calculate and validate the hash value as described in 2777 Section 4.2.3. If the hash validates, the client instance sends a 2778 continuation request to the AS as described in Section 5.1 using the 2779 interaction reference value received here. 2781 4.2.2. Completing Interaction with a Direct HTTP Request Callback 2783 When using the "callback" interaction mode (Section 3.3.4) with the 2784 "push" method, the AS signals to the client instance that interaction 2785 is complete and the request can be continued by sending an HTTP POST 2786 request to the client instance's callback URL sent in the callback 2787 request (Section 2.5.2.2). 2789 The entity message body is a JSON object consisting of the following 2790 two fields: 2792 hash (string) REQUIRED. The interaction hash value as described in 2793 Section 4.2.3. 2795 interact_ref (string) REQUIRED. The interaction reference generated 2796 for this interaction. 2798 POST /push/554321 HTTP/1.1 2799 Host: client.example.net 2800 Content-Type: application/json 2802 { 2803 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ 2804 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2805 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2806 } 2808 When receiving the request, the client instance MUST parse the JSON 2809 object and validate the hash value as described in Section 4.2.3. If 2810 the hash validates, the client instance sends a continuation request 2811 to the AS as described in Section 5.1 using the interaction reference 2812 value received here. 2814 4.2.3. Calculating the interaction hash 2816 The "hash" parameter in the request to the client instance's callback 2817 URL ties the front channel response to an ongoing request by using 2818 values known only to the parties involved. This security mechanism 2819 allows the client instance to protect itself against several kinds of 2820 session fixation and injection attacks. The AS MUST always provide 2821 this hash, and the client instance MUST validate the hash when 2822 received. 2824 To calculate the "hash" value, the party doing the calculation 2825 creates a hash string by concatenating the following values in the 2826 following order using a single newline ("\\n") character to separate 2827 them: 2829 * the "nonce" value sent by the client instance in the interaction 2830 "finish" section of the initial request (Section 2.5.2) 2832 * the AS's nonce value from the interaction finish response 2833 (Section 3.3.4) 2835 * the "interact_ref" returned from the AS as part of the interaction 2836 finish method (Section 4.2) 2838 * the grant endpoint URL the client instance used to make its 2839 initial request (Section 2) 2841 There is no padding or whitespace before or after any of the lines, 2842 and no trailing newline character. 2844 VJLO6A4CAYLBXHTR0KRO 2845 MBDOFXG4Y5CVJCX821LH 2846 4IFWWIKYBC2PQ6U56NL1 2847 https://server.example.com/tx 2849 The party then hashes this string with the appropriate algorithm 2850 based on the "hash_method" parameter of the "callback". If the 2851 "hash_method" value is not present in the client instance's request, 2852 the algorithm defaults to "sha3". 2854 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2855 issues/56) ]] 2857 4.2.3.1. SHA3-512 2859 The "sha3" hash method consists of hashing the input string with the 2860 512-bit SHA3 algorithm. The byte array is then encoded using URL 2861 Safe Base64 with no padding. The resulting string is the hash value. 2863 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ 2864 7XHPAdJzTZMtKBsaraJ64A 2866 4.2.3.2. SHA2-512 2868 The "sha2" hash method consists of hashing the input string with the 2869 512-bit SHA2 algorithm. The byte array is then encoded using URL 2870 Safe Base64 with no padding. The resulting string is the hash value. 2872 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 2873 j84rh4mC9aE9x7HPBFcIHw 2875 5. Continuing a Grant Request 2877 While it is possible for the AS to return a Section 3 with all the 2878 client instance's requested information (including access tokens 2879 (Section 3.2) and direct user information (Section 3.4)), it's more 2880 common that the AS and the client instance will need to communicate 2881 several times over the lifetime of an access grant. This is often 2882 part of facilitating interaction (Section 4), but it could also be 2883 used to allow the AS and client instance to continue negotiating the 2884 parameters of the original grant request (Section 2). 2886 To enable this ongoing negotiation, the AS provides a continuation 2887 API to the client software. The AS returns a "continue" field in the 2888 response (Section 3.1) that contains information the client instance 2889 needs to access this API, including a URI to access as well as an 2890 access token to use during the continued requests. 2892 The access token is initially bound to the same key and method the 2893 client instance used to make the initial request. As a consequence, 2894 when the client instance makes any calls to the continuation URL, the 2895 client instance MUST present the access token as described in 2896 Section 7.2 and present proof of the client instance's key (or its 2897 most recent rotation) by signing the request as described in 2898 Section 7.3. The AS MUST validate all keys presented by the client 2899 instance or referenced in an ongoing request for each call within 2900 that request. 2902 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2903 issues/85) ]] 2905 For example, here the client instance makes a POST request to a 2906 unique URI and signs the request with HTTP Message Signatures: 2908 POST /continue/KSKUOMUKM HTTP/1.1 2909 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2910 Host: server.example.com 2911 Signature-Input: sig1=... 2912 Signature: sig1=... 2914 The AS MUST be able to tell from the client instance's request which 2915 specific ongoing request is being accessed, using a combination of 2916 the continuation URL, the provided access token, and the client 2917 instance identified by the key signature. If the AS cannot determine 2918 a single active grant request to map the continuation request to, the 2919 AS MUST return an error. 2921 The ability to continue an already-started request allows the client 2922 instance to perform several important functions, including presenting 2923 additional information from interaction, modifying the initial 2924 request, and getting the current state of the request. 2926 All requests to the continuation API are protected by this bound 2927 access token. For example, here the client instance makes a POST 2928 request to a stable continuation endpoint URL with the interaction 2929 reference (Section 5.1), includes the access token, and signs with 2930 HTTP Message Signatures: 2932 POST /continue HTTP/1.1 2933 Host: server.example.com 2934 Content-Type: application/json 2935 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2936 Signature-Input: sig1=... 2937 Signature: sig1=... 2938 Digest: sha256=... 2940 { 2941 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2942 } 2944 If a "wait" parameter was included in the continuation response 2945 (Section 3.1), the client instance MUST NOT call the continuation URI 2946 prior to waiting the number of seconds indicated. If no "wait" 2947 period is indicated, the client instance SHOULD wait at least 5 2948 seconds. If the client instance does not respect the given wait 2949 period, the AS MUST return an error. [[ See issue #86 2950 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/86) ]] 2952 The response from the AS is a JSON object and MAY contain any of the 2953 fields described in Section 3, as described in more detail in the 2954 sections below. 2956 If the AS determines that the client instance can make a further 2957 continuation request, the AS MUST include a new "continue" response 2958 (Section 3.1). The new "continue" response MUST include a bound 2959 access token as well, and this token SHOULD be a new access token, 2960 invalidating the previous access token. If the AS does not return a 2961 new "continue" response, the client instance MUST NOT make an 2962 additional continuation request. If a client instance does so, the 2963 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 2964 wg-gnap/gnap-core-protocol/issues/87) ]] 2966 For continuation functions that require the client instance to send a 2967 message body, the body MUST be a JSON object. 2969 5.1. Continuing After a Completed Interaction 2971 When the AS responds to the client instance's "finish" method as in 2972 Section 4.2.1, this response includes an interaction reference. The 2973 client instance MUST include that value as the field "interact_ref" 2974 in a POST request to the continuation URI. 2976 POST /continue HTTP/1.1 2977 Host: server.example.com 2978 Content-Type: application/json 2979 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2980 Signature-Input: sig1=... 2981 Signature: sig1=... 2982 Digest: sha256=... 2984 { 2985 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2986 } 2988 Since the interaction reference is a one-time-use value as described 2989 in Section 4.2.1, if the client instance needs to make additional 2990 continuation calls after this request, the client instance MUST NOT 2991 include the interaction reference. If the AS detects a client 2992 instance submitting the same interaction reference multiple times, 2993 the AS MUST return an error and SHOULD invalidate the ongoing 2994 request. 2996 The Section 3 MAY contain any newly-created access tokens 2997 (Section 3.2) or newly-released subject claims (Section 3.4). The 2998 response MAY contain a new "continue" response (Section 3.1) as 2999 described above. The response SHOULD NOT contain any interaction 3000 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 3001 wg-gnap/gnap-core-protocol/issues/89) ]] 3002 For example, if the request is successful in causing the AS to issue 3003 access tokens and release opaque subject claims, the response could 3004 look like this: 3006 { 3007 "access_token": { 3008 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3009 "manage": "https://server.example.com/token/PRY5NM33O\ 3010 M4TB8N6BW7OZB8CDFONP219RP1L", 3011 }, 3012 "subject": { 3013 "sub_ids": [ { 3014 "format": "opaque", 3015 "id": "J2G8G8O4AZ" 3016 } ] 3017 } 3018 } 3020 With this example, the client instance can not make an additional 3021 continuation request because a "continue" field is not included. 3023 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3024 issues/88) ]] 3026 5.2. Continuing During Pending Interaction 3028 When the client instance does not include a "finish" parameter, the 3029 client instance will often need to poll the AS until the RO has 3030 authorized the request. To do so, the client instance makes a POST 3031 request to the continuation URI as in Section 5.1, but does not 3032 include a message body. 3034 POST /continue HTTP/1.1 3035 Host: server.example.com 3036 Content-Type: application/json 3037 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3038 Signature-Input: sig1=... 3039 Signature: sig1=... 3041 The Section 3 MAY contain any newly-created access tokens 3042 (Section 3.2) or newly-released subject claims (Section 3.4). The 3043 response MAY contain a new "continue" response (Section 3.1) as 3044 described above. If a "continue" field is included, it SHOULD 3045 include a "wait" field to facilitate a reasonable polling rate by the 3046 client instance. The response SHOULD NOT contain interaction 3047 responses (Section 3.3). 3049 For example, if the request has not yet been authorized by the RO, 3050 the AS could respond by telling the client instance to make another 3051 continuation request in the future. In this example, a new, unique 3052 access token has been issued for the call, which the client instance 3053 will use in its next continuation request. 3055 { 3056 "continue": { 3057 "access_token": { 3058 "value": "33OMUKMKSKU80UPRY5NM" 3059 }, 3060 "uri": "https://server.example.com/continue", 3061 "wait": 30 3062 } 3063 } 3065 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3066 issues/90) ]] 3068 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3069 issues/91) ]] 3071 If the request is successful in causing the AS to issue access tokens 3072 and release subject claims, the response could look like this 3073 example: 3075 { 3076 "access_token": { 3077 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3078 "manage": "https://server.example.com/token/PRY5NM33O\ 3079 M4TB8N6BW7OZB8CDFONP219RP1L", 3080 }, 3081 "subject": { 3082 "sub_ids": [ { 3083 "format": "opaque", 3084 "id": "J2G8G8O4AZ" 3085 } ] 3086 } 3087 } 3089 5.3. Modifying an Existing Request 3091 The client instance might need to modify an ongoing request, whether 3092 or not tokens have already been issued or claims have already been 3093 released. In such cases, the client instance makes an HTTP PATCH 3094 request to the continuation URI and includes any fields it needs to 3095 modify. Fields that aren't included in the request are considered 3096 unchanged from the original request. 3098 The client instance MAY include the "access_token" and "subject" 3099 fields as described in Section 2.1 and Section 2.2. Inclusion of 3100 these fields override any values in the initial request, which MAY 3101 trigger additional requirements and policies by the AS. For example, 3102 if the client instance is asking for more access, the AS could 3103 require additional interaction with the RO to gather additional 3104 consent. If the client instance is asking for more limited access, 3105 the AS could determine that sufficient authorization has been granted 3106 to the client instance and return the more limited access rights 3107 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 3108 core-protocol/issues/92) ]] 3110 The client instance MAY include the "interact" field as described in 3111 Section 2.5. Inclusion of this field indicates that the client 3112 instance is capable of driving interaction with the RO, and this 3113 field replaces any values from a previous request. The AS MAY 3114 respond to any of the interaction responses as described in 3115 Section 3.3, just like it would to a new request. 3117 The client instance MAY include the "user" field as described in 3118 Section 2.4 to present new assertions or information about the end- 3119 user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- 3120 protocol/issues/93) ]] 3122 The client instance MUST NOT include the "client" section of the 3123 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 3124 protocol/issues/94) ]] 3126 The client instance MAY include post-interaction responses such as 3127 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 3128 wg-gnap/gnap-core-protocol/issues/95) ]] 3130 Modification requests MUST NOT alter previously-issued access tokens. 3131 Instead, any access tokens issued from a continuation are considered 3132 new, separate access tokens. The AS MAY revoke existing access 3133 tokens after a modification has occurred. [[ See issue #96 3134 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 3136 If the modified request can be granted immediately by the AS, the 3137 Section 3 MAY contain any newly-created access tokens (Section 3.2) 3138 or newly-released subject claims (Section 3.4). The response MAY 3139 contain a new "continue" response (Section 3.1) as described above. 3140 If interaction can occur, the response SHOULD contain interaction 3141 responses (Section 3.3) as well. 3143 For example, a client instance initially requests a set of resources 3144 using references: 3146 POST /tx HTTP/1.1 3147 Host: server.example.com 3148 Content-Type: application/json 3149 Signature-Input: sig1=... 3150 Signature: sig1=... 3151 Digest: sha256=... 3153 { 3154 "access_token": { 3155 "access": [ 3156 "read", "write" 3157 ] 3158 }, 3159 "interact": { 3160 "start": ["redirect"], 3161 "finish": { 3162 "method": "redirect", 3163 "uri": "https://client.example.net/return/123455", 3164 "nonce": "LKLTI25DK82FX4T4QFZC" 3165 } 3166 }, 3167 "client": "987YHGRT56789IOLK" 3168 } 3170 Access is granted by the RO, and a token is issued by the AS. In its 3171 final response, the AS includes a "continue" field, which includes a 3172 separate access token for accessing the continuation API: 3174 { 3175 "continue": { 3176 "access_token": { 3177 "value": "80UPRY5NM33OMUKMKSKU" 3178 }, 3179 "uri": "https://server.example.com/continue", 3180 "wait": 30 3181 }, 3182 "access_token": { 3183 "value": "RP1LT0-OS9M2P_R64TB", 3184 "access": [ 3185 "read", "write" 3186 ] 3187 } 3188 } 3189 This "continue" field allows the client instance to make an eventual 3190 continuation call. In the future, the client instance realizes that 3191 it no longer needs "write" access and therefore modifies its ongoing 3192 request, here asking for just "read" access instead of both "read" 3193 and "write" as before. 3195 PATCH /continue HTTP/1.1 3196 Host: server.example.com 3197 Content-Type: application/json 3198 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3199 Signature-Input: sig1=... 3200 Signature: sig1=... 3201 Digest: sha256=... 3203 { 3204 "access_token": { 3205 "access": [ 3206 "read" 3207 ] 3208 } 3209 ... 3210 } 3212 The AS replaces the previous "access" from the first request, 3213 allowing the AS to determine if any previously-granted consent 3214 already applies. In this case, the AS would likely determine that 3215 reducing the breadth of the requested access means that new access 3216 tokens can be issued to the client instance. The AS would likely 3217 revoke previously-issued access tokens that had the greater access 3218 rights associated with them, unless they had been issued with the 3219 "durable" flag. 3221 { 3222 "continue": { 3223 "access_token": { 3224 "value": "M33OMUK80UPRY5NMKSKU" 3225 }, 3226 "uri": "https://server.example.com/continue", 3227 "wait": 30 3228 }, 3229 "access_token": { 3230 "value": "0EVKC7-2ZKwZM_6N760", 3231 "access": [ 3232 "read" 3233 ] 3234 } 3235 } 3236 For another example, the client instance initially requests read-only 3237 access but later needs to step up its access. The initial request 3238 could look like this example. 3240 POST /tx HTTP/1.1 3241 Host: server.example.com 3242 Content-Type: application/json 3243 Signature-Input: sig1=... 3244 Signature: sig1=... 3245 Digest: sha256=... 3247 { 3248 "access_token": { 3249 "access": [ 3250 "read" 3251 ] 3252 }, 3253 "interact": { 3254 "start": ["redirect"], 3255 "finish": { 3256 "method": "redirect", 3257 "uri": "https://client.example.net/return/123455", 3258 "nonce": "LKLTI25DK82FX4T4QFZC" 3259 } 3260 }, 3261 "client": "987YHGRT56789IOLK" 3262 } 3264 Access is granted by the RO, and a token is issued by the AS. In its 3265 final response, the AS includes a "continue" field: 3267 { 3268 "continue": { 3269 "access_token": { 3270 "value": "80UPRY5NM33OMUKMKSKU" 3271 }, 3272 "uri": "https://server.example.com/continue", 3273 "wait": 30 3274 }, 3275 "access_token": { 3276 "value": "RP1LT0-OS9M2P_R64TB", 3277 "access": [ 3278 "read" 3279 ] 3280 } 3281 } 3282 This allows the client instance to make an eventual continuation 3283 call. The client instance later realizes that it now needs "write" 3284 access in addition to the "read" access. Since this is an expansion 3285 of what it asked for previously, the client instance also includes a 3286 new interaction section in case the AS needs to interact with the RO 3287 again to gather additional authorization. Note that the client 3288 instance's nonce and callback are different from the initial request. 3289 Since the original callback was already used in the initial exchange, 3290 and the callback is intended for one-time-use, a new one needs to be 3291 included in order to use the callback again. 3293 [[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3294 issues/97) ]] 3296 PATCH /continue HTTP/1.1 3297 Host: server.example.com 3298 Content-Type: application/json 3299 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3300 Signature-Input: sig1=... 3301 Signature: sig1=... 3302 Digest: sha256=... 3304 { 3305 "access_token": { 3306 "access": [ 3307 "read", "write" 3308 ] 3309 }, 3310 "interact": { 3311 "start": ["redirect"], 3312 "finish": { 3313 "method": "redirect", 3314 "uri": "https://client.example.net/return/654321", 3315 "nonce": "K82FX4T4LKLTI25DQFZC" 3316 } 3317 } 3318 } 3320 From here, the AS can determine that the client instance is asking 3321 for more than it was previously granted, but since the client 3322 instance has also provided a mechanism to interact with the RO, the 3323 AS can use that to gather the additional consent. The protocol 3324 continues as it would with a new request. Since the old access 3325 tokens are good for a subset of the rights requested here, the AS 3326 might decide to not revoke them. However, any access tokens granted 3327 after this update process are new access tokens and do not modify the 3328 rights of existing access tokens. 3330 5.4. Canceling a Grant Request 3332 If the client instance wishes to cancel an ongoing grant request, it 3333 makes an HTTP DELETE request to the continuation URI. 3335 DELETE /continue HTTP/1.1 3336 Host: server.example.com 3337 Content-Type: application/json 3338 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3339 Signature-Input: sig1=... 3340 Signature: sig1=... 3342 If the request is successfully cancelled, the AS responds with an 3343 HTTP 202. The AS SHOULD revoke all associated access tokens. 3345 6. Token Management 3347 If an access token response includes the "manage" parameter as 3348 described in Section 3.2.1, the client instance MAY call this URL to 3349 manage the access token with any of the actions defined in the 3350 following sections. Other actions are undefined by this 3351 specification. 3353 The access token being managed acts as the access element for its own 3354 management API. The client instance MUST present proof of an 3355 appropriate key along with the access token. 3357 If the token is sender-constrained (i.e., not a bearer token), it 3358 MUST be sent with the appropriate binding for the access token 3359 (Section 7.2). 3361 If the token is a bearer token, the client instance MUST present 3362 proof of the same key identified in the initial request (Section 2.3) 3363 as described in Section 7.3. 3365 The AS MUST validate the proof and assure that it is associated with 3366 either the token itself or the client instance the token was issued 3367 to, as appropriate for the token's presentation type. 3369 6.1. Rotating the Access Token 3371 The client instance makes an HTTP POST to the token management URI, 3372 sending the access token in the appropriate header and signing the 3373 request with the appropriate key. 3375 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3376 Host: server.example.com 3377 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3378 Signature-Input: sig1=... 3379 Signature: sig1=... 3380 Digest: sha256=... 3382 The AS validates that the token presented is associated with the 3383 management URL, that the AS issued the token to the given client 3384 instance, and that the presented key is appropriate to the token. 3386 If the access token has expired, the AS SHOULD honor the rotation 3387 request to the token management URL since it is likely that the 3388 client instance is attempting to refresh the expired token. To 3389 support this, the AS MAY apply different lifetimes for the use of the 3390 token in management vs. its use at an RS. An AS MUST NOT honor a 3391 rotation request for an access token that has been revoked, either by 3392 the AS or by the client instance through the token management URI 3393 (Section 6.2). 3395 If the token is validated and the key is appropriate for the request, 3396 the AS MUST invalidate the current access token associated with this 3397 URL, if possible, and return a new access token response as described 3398 in Section 3.2.1, unless the "multi_token" flag is specified in the 3399 request. The value of the access token MUST NOT be the same as the 3400 current value of the access token used to access the management API. 3401 The response MAY include an updated access token management URL as 3402 well, and if so, the client instance MUST use this new URL to manage 3403 the new access token. [[ See issue #101 (https://github.com/ietf-wg- 3404 gnap/gnap-core-protocol/issues/101) ]] 3406 [[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core- 3407 protocol/issues/102) ]] 3408 { 3409 "access_token": { 3410 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3411 "manage": "https://server.example.com/token/PRY5NM33O\ 3412 M4TB8N6BW7OZB8CDFONP219RP1L", 3413 "access": [ 3414 { 3415 "type": "photo-api", 3416 "actions": [ 3417 "read", 3418 "write", 3419 "dolphin" 3420 ], 3421 "locations": [ 3422 "https://server.example.net/", 3423 "https://resource.local/other" 3424 ], 3425 "datatypes": [ 3426 "metadata", 3427 "images" 3428 ] 3429 }, 3430 "read", "dolphin-metadata" 3431 ] 3432 } 3433 } 3435 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3436 protocol/issues/103) ]] 3438 6.2. Revoking the Access Token 3440 If the client instance wishes to revoke the access token proactively, 3441 such as when a user indicates to the client instance that they no 3442 longer wish for it to have access or the client instance application 3443 detects that it is being uninstalled, the client instance can use the 3444 token management URI to indicate to the AS that the AS should 3445 invalidate the access token for all purposes. 3447 The client instance makes an HTTP DELETE request to the token 3448 management URI, presenting the access token and signing the request 3449 with the appropriate key. 3451 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3452 Host: server.example.com 3453 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3454 Signature-Input: sig1=... 3455 Signature: sig1=... 3457 If the key presented is associated with the token (or the client 3458 instance, in the case of a bearer token), the AS MUST invalidate the 3459 access token, if possible, and return an HTTP 204 response code. 3461 204 No Content 3463 Though the AS MAY revoke an access token at any time for any reason, 3464 the token management function is specifically for the client 3465 instance's use. If the access token has already expired or has been 3466 revoked through other means, the AS SHOULD honor the revocation 3467 request to the token management URL as valid, since the end result is 3468 still the token not being usable. 3470 7. Securing Requests from the Client Instance 3472 In GNAP, the client instance secures its requests to the AS and RS by 3473 presenting an access token, presenting proof of a key that it 3474 possesses, or both an access token and key proof together. 3476 * When an access token is used with a key proof, this is a bound 3477 token request. This type of request is used for calls to the RS 3478 as well as the AS during negotiation. 3480 * When a key proof is used with no access token, this is a non- 3481 authorized signed request. This type of request is used for calls 3482 to the AS to initiate a negotiation. 3484 * When an access token is used with no key proof, this is a bearer 3485 token request. This type of request is used only for calls to the 3486 RS, and only with access tokens that are not bound to any key as 3487 described in Section 3.2.1. 3489 * When neither an access token nor key proof are used, this is an 3490 unsecured request. This type of request is used optionally for 3491 calls to the RS as part of an RS-first discovery process as 3492 described in Section 9.1. 3494 7.1. Key Formats 3496 Several different places in GNAP require the presentation of key 3497 material by value. Proof of this key material MUST be bound to a 3498 request, the nature of which varies with the location in the protocol 3499 the key is used. For a key used as part of a client instance's 3500 initial request in Section 2.3, the key value is the client 3501 instance's public key, and proof of that key MUST be presented in 3502 that request. For a key used as part of an access token response in 3503 Section 3.2.1, the proof of that key MUST be used when presenting the 3504 access token. 3506 A key presented by value MUST be a public key in at least one 3507 supported format. If a key is sent in multiple formats, all the key 3508 format values MUST be equivalent. Note that while most formats 3509 present the full value of the public key, some formats present a 3510 value cryptographically derived from the public key. 3512 proof (string) The form of proof that the client instance will use 3513 when presenting the key. The valid values of this field and the 3514 processing requirements for each are detailed in Section 7.3. The 3515 "proof" field is REQUIRED. 3517 jwk (object) The public key and its properties represented as a JSON 3518 Web Key [RFC7517]. A JWK MUST contain the "alg" (Algorithm) and 3519 "kid" (Key ID) parameters. The "alg" parameter MUST NOT be 3520 "none". The "x5c" (X.509 Certificate Chain) parameter MAY be used 3521 to provide the X.509 representation of the provided public key. 3523 cert (string) PEM serialized value of the certificate used to sign 3524 the request, with optional internal whitespace per [RFC7468]. The 3525 PEM header and footer are optionally removed. 3527 cert#S256 (string) The certificate thumbprint calculated as per 3528 OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this 3529 format does not include the full public key. 3531 Additional key formats are defined in a registry TBD (Section 11). 3533 This non-normative example shows a single key presented in multiple 3534 formats. This example key is intended to be used with the HTTP 3535 Message Signatures ({{httpsig-binding}}) proofing mechanism, as 3536 indicated by the "httpsig" value of the "proof" field. 3538 "key": { 3539 "proof": "httpsig", 3540 "jwk": { 3541 "kty": "RSA", 3542 "e": "AQAB", 3543 "kid": "xyz-1", 3544 "alg": "RS256", 3545 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 3546 }, 3547 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 3548 } 3550 7.1.1. Key References 3552 Keys in GNAP can also be passed by reference such that the party 3553 receiving the reference will be able to determine the appropriate 3554 keying material for use in that part of the protocol. 3556 "key": "S-P4XJQ_RYJCRTSU1.63N3E" 3558 Keys referenced in this manner MAY be shared symmetric keys. The key 3559 reference MUST NOT contain any unencrypted private or shared 3560 symmetric key information. 3562 Keys referenced in this manner MUST be bound to a single proofing 3563 mechanism. 3565 The means of dereferencing this value are out of scope for this 3566 specification. 3568 7.2. Presenting Access Tokens 3570 The method the client instance uses to send an access token depends 3571 on whether the token is bound to a key, and if so which proofing 3572 method is associated with the key. This information is conveyed in 3573 the "bound" and "key" parameters in the single (Section 3.2.1) and 3574 multiple access tokens (Section 3.2.2) responses. 3576 If the "flags" field does not contain the "bearer" flag and the "key" 3577 is absent, the access token MUST be sent using the same key and 3578 proofing mechanism that the client instance used in its initial 3579 request (or its most recent rotation). 3581 If the "flags" field does not contain the "bearer" flag and the "key" 3582 value is an object as described in Section 7.1, the access token MUST 3583 be sent using the key and proofing mechanism defined by the value of 3584 the "proof" field within the key object. 3586 The access token MUST be sent using the HTTP "Authorization" request 3587 header field and the "GNAP" authorization scheme along with a key 3588 proof as described in Section 7.3 for the key bound to the access 3589 token. For example, an "httpsig"-bound access token is sent as 3590 follows: 3592 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3593 Signature-Input: sig1=(authorization);... 3594 Signature: sig1=... 3596 If the "flags" field contains the "bearer" flag, the access token is 3597 a bearer token that MUST be sent using the "Authorization Request 3598 Header Field" method defined in [RFC6750]. 3600 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3602 The "Form-Encoded Body Parameter" and "URI Query Parameter" methods 3603 of [RFC6750] MUST NOT be used. 3605 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3606 protocol/issues/104) ]] 3608 The client software MUST reject as an error a situation where the 3609 "flags" field contains the "bearer" flag and the "key" field is 3610 present with any value. 3612 7.3. Proving Possession of a Key with a Request 3614 Any keys presented by the client instance to the AS or RS MUST be 3615 validated as part of the request in which they are presented. The 3616 type of binding used is indicated by the proof parameter of the key 3617 object in Section 7.1. Values defined by this specification are as 3618 follows: 3620 httpsig HTTP Signing signature header 3622 mtls Mutual TLS certificate verification 3624 jwsd A detached JWS signature header 3626 jws Attached JWS payload 3628 Additional proofing methods are defined by a registry TBD 3629 (Section 11). 3631 All key binding methods used by this specification MUST cover all 3632 relevant portions of the request, including anything that would 3633 change the nature of the request, to allow for secure validation of 3634 the request. Relevant aspects include the URI being called, the HTTP 3635 method being used, any relevant HTTP headers and values, and the HTTP 3636 message body itself. The verifier of the signed message MUST 3637 validate all components of the signed message to ensure that nothing 3638 has been tampered with or substituted in a way that would change the 3639 nature of the request. Key binding method definitions SHOULD 3640 enumerate how these requirements are fulfilled. 3642 When a key proofing mechanism is bound to an access token, the key 3643 being presented MUST be the key associated with the access token and 3644 the access token MUST be covered by the signature method of the 3645 proofing mechanism. 3647 The key binding methods in this section MAY be used by other 3648 components making calls as part of GNAP, such as the extensions 3649 allowing the RS to make calls to the AS defined in {{I-D.ietf-gnap- 3650 resource-servers}}. To facilitate this extended use, the sections 3651 below are defined in generic terms of the "sender" and "verifier" of 3652 the HTTP message. In the core functions of GNAP, the "sender" is the 3653 client instance and the "verifier" is the AS or RS, as appropriate. 3655 When used for delegation in GNAP, these key binding mechanisms allow 3656 the AS to ensure that the keys presented by the client instance in 3657 the initial request are in control of the party calling any follow-up 3658 or continuation requests. To facilitate this requirement, the 3659 continuation response (Section 3.1) includes an access token bound to 3660 the client instance's key (Section 2.3), and that key (or its most 3661 recent rotation) MUST be proved in all continuation requests 3662 Section 5. Token management requests Section 6 are similarly bound 3663 to either the access token's own key or, in the case of bearer 3664 tokens, the client instance's key. 3666 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 3667 protocol/issues/105) ]] 3669 In the following sections, unless otherwise noted, the "RS256" JOSE 3670 Signature Algorithm is applied using the following RSA key (presented 3671 here in JWK format): 3673 { 3674 "kid": "gnap-rsa", 3675 "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ 3676 i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ 3677 eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", 3678 "kty": "RSA", 3679 "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ 3680 LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ 3681 JXMxOLyPjzuVgiTOCBIvLD6-8-mvFjXZk_eefD0at6mQ5qV3U1jZt88", 3682 "d": "FHlhdTF0ozTliDxMBffT6aJVKZKmbbFJOVNten9c3lXKB3ux3NAb_D2dB\ 3683 7inp9EV23oWrDspFtvCvD9dZrXgRKMHofkEpo_SSvBZfgtH-OTkbY_TqtPF\ 3684 FLPKAw0JX5cFPnn4Q2xE4n-dQ7tpRCKl59vZLHBrHShr90zqzFp0AKXU5fj\ 3685 b1gC9LPwsFA2Fd7KXmI1drQQEVq9R-o18Pnn4BGQNQNjO_VkcJTiBmEIVT_\ 3686 KJRPdpVJAmbgnYWafL_hAfeb_dK8p85yurEVF8nCK5oO3EPrqB7IL4UqaEn\ 3687 5Sl3u0j8x5or-xrrAoNz-gdOv7ONfZY6NFoa-3f8q9wBAHUuQ", 3688 "e": "AQAB", 3689 "qi": "ogpNEkDKg22Rj9cDV_-PJBZaXMk66Fp557RT1tafIuqJRHEufSOYnsto\ 3690 bWPJ0gHxv1gVJw3gm-zYvV-wTMNgr2wVsBSezSJjPSjxWZtmT2z68W1DuvK\ 3691 kZy15vz7Jd85hmDlriGcXNCoFEUsGLWkpHH9RwPIzguUHWmTt8y0oXyI", 3692 "dp": "dvCKGI2G7RLh3WyjoJ_Dr6hZ3LhXweB3YcY3qdD9BnxZ71mrLiMQg4c_\ 3693 EBnwqCETN_5sStn2cRc2JXnvLP3G8t7IFKHTT_i_TSTacJ7uT04MSa053Y3\ 3694 RfwbvLjRNPR0UKAE3ZxROUoIaVNuU_6-QMf8-2ilUv2GIOrCN87gP_Vk", 3695 "alg": "RS256", 3696 "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ 3697 M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ 3698 Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", 3699 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ 3700 YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ 3701 jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ 3702 e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ 3703 bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ 3704 zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3705 } 3707 7.3.1. HTTP Message Signing 3709 This method is indicated by "httpsig" in the "proof" field. The 3710 sender creates an HTTP Message Signature as described in 3711 [I-D.ietf-httpbis-message-signatures]. 3713 The covered content of the signature MUST include the following: 3715 @request-target: the target of the HTTP request 3717 digest: The Digest header as defined in [RFC3230]. When the request 3718 message has a body, the signer MUST calculate this header value 3719 and the verifier MUST validate this header. 3721 When the request is bound to an access token, the covered content 3722 MUST also include: 3724 authorization: The Authorization header used to present the access 3725 token as discussed in Section 7.2. 3727 Other covered content MAY also be included. 3729 If the signer's key presented is a JWK, the "keyid" parameter of the 3730 signature MUST be set to the "kid" value of the JWK, the signing 3731 algorithm used MUST be the JWS algorithm denoted by the key's "alg" 3732 field, and the explicit "alg" signature parameter MUST NOT be 3733 included. 3735 In this example, the message body is the following JSON object: 3737 { 3738 "access_token": { 3739 "access": [ 3740 "dolphin-metadata" 3741 ] 3742 }, 3743 "interact": { 3744 "start": ["redirect"], 3745 "finish": { 3746 "method": "redirect", 3747 "uri": "https://client.foo/callback", 3748 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3749 } 3750 }, 3751 "client": { 3752 "proof": "httpsig", 3753 "key": { 3754 "jwk": { 3755 "kid": "gnap-rsa", 3756 "kty": "RSA", 3757 "e": "AQAB", 3758 "alg": "RS256", 3759 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3760 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3761 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3762 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3763 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3764 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3765 } 3766 } 3767 "display": { 3768 "name": "My Client Display Name", 3769 "uri": "https://client.foo/" 3770 }, 3771 } 3772 } 3774 This body is hashed for the Digest header using SHA-256 into the 3775 following encoded value: 3777 SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3779 The HTTP message signature input string is calculated to be the 3780 following: 3782 "@request-target": post /gnap 3783 "host": server.example.com 3784 "content-type": application/json 3785 "digest": SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3786 "content-length": 986 3787 "@signature-params": ("@request-target" "host" "content-type" \ 3788 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 3790 This leads to the following full HTTP message request: 3792 POST /gnap HTTP/1.1 3793 Host: server.example.com 3794 Content-Type: application/json 3795 Content-Length: 986 3796 Digest: SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3797 Signature-Input: sig1=("@request-target" "host" "content-type" \ 3798 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 3799 Signature: \ 3800 sig1=:axj8FLOvEWBcwh+Xk6VTTKXxqo4XNygleTDJ8h3ZJfi1sSmWrRtyo9RG/dc\ 3801 miZmdszRjWbg+/ixVZpA4BL3AOwEOxxtmHAXNB8uJ0I3tfbs6Suyk4sEo8zPr+MJq\ 3802 MjxdJEUgAQAy2AH+wg5a7CKq4IdLTulFK9njUIeG7MygHumeiumM3DbDQAHgF46dV\ 3803 q5UC6KJnqhGM1rFC128jd2D0sgWKCUgKGCHtfR159zfKWcEO9krsLoOnCdTzm1UyD\ 3804 DMjkIjqeN/1j8PdMJaRAwV4On079O0DVu6bl1jVtkzo/e/ZmwPr/X436V4xiw/hZt\ 3805 w4sfNsSbmsT0+UAQ20X/xaw==: 3807 { 3808 "access_token": { 3809 "access": [ 3810 "dolphin-metadata" 3811 ] 3812 }, 3813 "interact": { 3814 "start": ["redirect"], 3815 "finish": { 3816 "method": "redirect", 3817 "uri": "https://client.foo/callback", 3818 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3819 } 3820 }, 3821 "client": { 3822 "proof": "httpsig", 3823 "key": { 3824 "jwk": { 3825 "kid": "gnap-rsa", 3826 "kty": "RSA", 3827 "e": "AQAB", 3828 "alg": "RS256", 3829 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3830 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3831 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3832 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3833 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3834 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3835 } 3836 } 3837 "display": { 3838 "name": "My Client Display Name", 3839 "uri": "https://client.foo/" 3840 }, 3841 } 3842 } 3844 If the HTTP Message includes a message body, the verifier MUST 3845 calculate and verify the value of the "Digest" header. The verifier 3846 MUST ensure that the signature includes all required covered content. 3847 The verifier MUST validate the signature against the expected key of 3848 the signer. 3850 7.3.2. Mutual TLS 3852 This method is indicated by "mtls" in the "proof" field. The signer 3853 presents its TLS client certificate during TLS negotiation with the 3854 verifier. 3856 In this example, the certificate is communicated to the application 3857 through the "Client-Cert" header from a TLS reverse proxy, leading to 3858 the following full HTTP request message: 3860 POST /gnap HTTP/1.1 3861 Host: server.example.com 3862 Content-Type: application/jose 3863 Content-Length: 1567 3864 Client-Cert: \ 3865 MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM \ 3866 K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN \ 3867 MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq \ 3868 c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG \ 3869 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB \ 3870 kI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8I \ 3871 kZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn11V2vxE4 \ 3872 1hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo+ \ 3873 uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKXfGhi3k \ 3874 OzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0GCSqG \ 3875 SIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/XsWfCE \ 3876 wHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5NH9 \ 3877 W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeCgu \ 3878 NMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHlU \ 3879 fn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv \ 3880 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx 3882 { 3883 "access_token": { 3884 "access": [ 3885 "dolphin-metadata" 3886 ] 3887 }, 3888 "interact": { 3889 "start": ["redirect"], 3890 "finish": { 3891 "method": "redirect", 3892 "uri": "https://client.foo/callback", 3893 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3894 } 3895 }, 3896 "client": { 3897 "proof": "jws", 3898 "key": { 3899 "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ 3900 YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ 3901 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 3902 DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ 3903 jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ 3904 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 3905 KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ 3906 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 3907 z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ 3908 fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ 3909 GCSqGSIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/Xs\ 3910 WfCEwHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5\ 3911 NH9W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeC\ 3912 guNMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHl\ 3913 Ufn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 3914 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx" 3915 } 3916 "display": { 3917 "name": "My Client Display Name", 3918 "uri": "https://client.foo/" 3919 }, 3920 }, 3921 "subject": { 3922 "formats": ["iss_sub", "opaque"] 3923 } 3925 } 3927 The verifier compares the TLS client certificate presented during 3928 mutual TLS negotiation to the expected key of the signer. Since the 3929 TLS connection covers the entire message, there are no additional 3930 requirements to check. 3932 Note that in many instances, the verifier will not do a full 3933 certificate chain validation of the presented TLS client certificate, 3934 as the means of trust for this certificate could be in something 3935 other than a PKI system, such as a static registration or trust-on- 3936 first-use. 3938 [[ See issue #110 (https://github.com/ietf-wg-gnap/gnap-core- 3939 protocol/issues/110) ]] 3941 7.3.3. Detached JWS 3943 This method is indicated by "jwsd" in the "proof" field. A JWS 3944 [RFC7515] object is created as follows: 3946 To protect the request, the JOSE header of the signature contains the 3947 following parameters: 3949 kid (string) The key identifier. RECOMMENDED. If the key is 3950 presented in JWK format, this MUST be the value of the "kid" field 3951 of the key. 3953 alg (string) The algorithm used to sign the request. REQUIRED. 3954 MUST be appropriate to the key presented. If the key is presented 3955 as a JWK, this MUST be equal to the "alg" parameter of the key. 3956 MUST NOT be "none". 3958 typ (string) The type header, value "gnap-binding+jwsd". REQUIRED 3960 htm (string) The HTTP Method used to make this request, as an 3961 uppercase ASCII string. REQUIRED 3963 uri (string) The HTTP URI used for this request, including all path 3964 and query components and no fragment component. REQUIRED 3966 created (integer) A timestamp of when the signature was created, in 3967 integer seconds since UNIX Epoch 3969 ath (string) When a request is bound to an access token, the access 3970 token hash value. The value MUST be the result of Base64url 3971 encoding (with no padding) the SHA-256 digest of the ASCII 3972 encoding of the associated access token's value. REQUIRED if the 3973 request protects an access token. 3975 If the HTTP request has a message body, such as an HTTP POST or PUT 3976 method, the payload of the JWS object is the Base64url encoding 3977 (without padding) of the SHA256 digest of the bytes of the body. If 3978 the request being made does not have a message body, such as an HTTP 3979 GET, OPTIONS, or DELETE method, the JWS signature is calculated over 3980 an empty payload. 3982 The client instance presents the signed object in compact form 3983 [RFC7515] in the Detached-JWS HTTP Header field. 3985 In this example, the JOSE Header contains the following parameters: 3987 { 3988 "alg": "RS256", 3989 "kid": "gnap-rsa", 3990 "uri": "https://server.example.com/gnap", 3991 "htm": "POST", 3992 "typ": "gnap-binding+jwsd", 3993 "created": 1618884475 3994 } 3996 The request body is the following JSON object: 3998 { 3999 "access_token": { 4000 "access": [ 4001 "dolphin-metadata" 4002 ] 4003 }, 4004 "interact": { 4005 "start": ["redirect"], 4006 "finish": { 4007 "method": "redirect", 4008 "uri": "https://client.foo/callback", 4009 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4010 } 4011 }, 4012 "client": { 4013 "proof": "jwsd", 4014 "key": { 4015 "jwk": { 4016 "kid": "gnap-rsa", 4017 "kty": "RSA", 4018 "e": "AQAB", 4019 "alg": "RS256", 4020 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4021 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4022 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4023 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4024 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4025 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4026 } 4027 } 4028 "display": { 4029 "name": "My Client Display Name", 4030 "uri": "https://client.foo/" 4031 }, 4032 } 4033 } 4035 This is hashed to the following Base64 encoded value: 4037 PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc 4039 This leads to the following full HTTP request message: 4041 POST /gnap HTTP/1.1 4042 Host: server.example.com 4043 Content-Type: application/json 4044 Content-Length: 983 4045 Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ 4046 SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ 4047 NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ 4048 ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ 4049 TZA2h5YeXUoi5F2Q2iToC0Tc4drYFOSHIX68knd68RUA7yHqCVP-ZQEd6aL32H69e\ 4050 9zuMiw6O_s4TBKB3vDOvwrhYtDH6fX2hP70cQoO-47OwbqP-ifkrvI3hVgMX9TfjV\ 4051 eKNwnhoNnw3vbu7SNKeqJEbbwZfpESaGepS52xNBlDNMYBQQXxM9OqKJaXffzLFEl\ 4052 -Xe0UnfolVtBraz3aPrPy1C6a4uT7wLda3PaTOVtgysxzii3oJWpuz0WP5kRujzDF\ 4053 wX_EOzW0jsjCSkL-PXaKSpZgEjNjKDMg9irSxUISt1C1T6q3SzRgfuQ 4055 { 4056 "access_token": { 4057 "access": [ 4058 "dolphin-metadata" 4059 ] 4060 }, 4061 "interact": { 4062 "start": ["redirect"], 4063 "finish": { 4064 "method": "redirect", 4065 "uri": "https://client.foo/callback", 4066 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4067 } 4068 }, 4069 "client": { 4070 "proof": "jwsd", 4071 "key": { 4072 "jwk": { 4073 "kid": "gnap-rsa", 4074 "kty": "RSA", 4075 "e": "AQAB", 4076 "alg": "RS256", 4077 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4078 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4079 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4080 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4081 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4082 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4083 } 4084 } 4085 "display": { 4086 "name": "My Client Display Name", 4087 "uri": "https://client.foo/" 4089 }, 4090 } 4091 } 4093 When the verifier receives the Detached-JWS header, it MUST parse and 4094 validate the JWS object. The signature MUST be validated against the 4095 expected key of the signer. All required fields MUST be present and 4096 their values MUST be valid. If the HTTP message request contains a 4097 body, the verifier MUST calculate the hash of body just as the signer 4098 does, with no normalization or transformation of the request. 4100 7.3.4. Attached JWS 4102 This method is indicated by "jws" in the "proof" field. A JWS 4103 [RFC7515] object is created as follows: 4105 The JOSE header MUST contain the "kid" parameter of the key bound to 4106 this client instance for this request. The "alg" parameter MUST be 4107 set to a value appropriate for the key identified by kid and MUST NOT 4108 be "none". 4110 To protect the request, the JWS header MUST contain the following 4111 additional parameters. 4113 typ (string) The type header, value "gnap-binding+jws". 4115 htm (string) The HTTP Method used to make this request, as an 4116 uppercase ASCII string. 4118 uri (string) The HTTP URI used for this request, including all path 4119 and query components and no fragment component. 4121 created (integer) A timestamp of when the signature was created, in 4122 integer seconds since UNIX Epoch 4124 ath (string) When a request is bound to an access token, the access 4125 token hash value. The value MUST be the result of Base64url 4126 encoding (with no padding) the SHA-256 digest of the ASCII 4127 encoding of the associated access token's value. 4129 If the HTTP request has a message body, such as an HTTP POST or PUT 4130 method, the payload of the JWS object is the JSON serialized body of 4131 the request, and the object is signed according to JWS and serialized 4132 into compact form [RFC7515]. The client instance presents the JWS as 4133 the body of the request along with a content type of "application/ 4134 jose". The AS MUST extract the payload of the JWS and treat it as 4135 the request body for further processing. 4137 If the request being made does not have a message body, such as an 4138 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 4139 over an empty payload and passed in the "Detached-JWS" header as 4140 described in Section 7.3.3. 4142 In this example, the JOSE header contains the following parameters: 4144 { 4145 "alg": "RS256", 4146 "kid": "gnap-rsa", 4147 "uri": "https://server.example.com/gnap", 4148 "htm": "POST", 4149 "typ": "gnap-binding+jwsd", 4150 "created": 1618884475 4151 } 4153 The request body, used as the JWS Payload, is the following JSON 4154 object: 4156 { 4157 "access_token": { 4158 "access": [ 4159 "dolphin-metadata" 4160 ] 4161 }, 4162 "interact": { 4163 "start": ["redirect"], 4164 "finish": { 4165 "method": "redirect", 4166 "uri": "https://client.foo/callback", 4167 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4168 } 4169 }, 4170 "client": { 4171 "proof": "jws", 4172 "key": { 4173 "jwk": { 4174 "kid": "gnap-rsa", 4175 "kty": "RSA", 4176 "e": "AQAB", 4177 "alg": "RS256", 4178 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4179 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4180 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4181 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4182 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4183 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4184 } 4185 } 4186 "display": { 4187 "name": "My Client Display Name", 4188 "uri": "https://client.foo/" 4189 }, 4190 }, 4191 "subject": { 4192 "formats": ["iss_sub", "opaque"] 4193 } 4194 } 4196 This leads to the following full HTTP request message: 4198 POST /gnap HTTP/1.1 4199 Host: server.example.com 4200 Content-Type: application/jose 4201 Content-Length: 1047 4203 eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ 4204 raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ 4205 R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ 4206 ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\ 4207 0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\ 4208 Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\ 4209 CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\ 4210 cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\ 4211 KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\ 4212 ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\ 4213 ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\ 4214 Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\ 4215 gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\ 4216 5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\ 4217 nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\ 4218 akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\ 4219 xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\ 4220 BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\ 4221 XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\ 4222 YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ 4223 gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ 4224 FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ 4225 AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ 4226 c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ 4227 vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ 4228 u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ 4229 LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ 4230 PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ 4231 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 4233 [[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core- 4234 protocol/issues/109) ]] 4236 When the verifier receives an attached JWS request, it MUST parse and 4237 validate the JWS object. The signature MUST be validated against the 4238 expected key of the signer. All required fields MUST be present and 4239 their values MUST be valid. If the HTTP message request contains a 4240 body, the verifier MUST decode the payload of the JWS object and 4241 treat this as the HTTP message body. 4243 8. Resource Access Rights 4245 GNAP provides a rich structure for describing the protected resources 4246 hosted by RSs and accessed by client software. This structure is 4247 used when the client instance requests an access token (Section 2.1) 4248 and when an access token is returned (Section 3.2). 4250 The root of this structure is a JSON array. The elements of the JSON 4251 array represent rights of access that are associated with the the 4252 access token. The resulting access is the union of all elements 4253 within the array. 4255 The access associated with the access token is described using 4256 objects that each contain multiple dimensions of access. Each object 4257 contains a REQUIRED "type" property that determines the type of API 4258 that the token is used for. 4260 type (string) The type of resource request as a string. This field 4261 MAY define which other fields are allowed in the request object. 4262 This field is REQUIRED. 4264 The value of the "type" field is under the control of the AS. This 4265 field MUST be compared using an exact byte match of the string value 4266 against known types by the AS. The AS MUST ensure that there is no 4267 collision between different authorization data types that it 4268 supports. The AS MUST NOT do any collation or normalization of data 4269 types during comparison. It is RECOMMENDED that designers of 4270 general-purpose APIs use a URI for this field to avoid collisions 4271 between multiple API types protected by a single AS. 4273 While it is expected that many APIs will have their own properties, a 4274 set of common properties are defined here. Specific API 4275 implementations SHOULD NOT re-use these fields with different 4276 semantics or syntax. The available values for these properties are 4277 determined by the API being protected at the RS. 4279 actions (array of strings) The types of actions the client instance 4280 will take at the RS as an array of strings. For example, a client 4281 instance asking for a combination of "read" and "write" access. 4283 locations (array of strings) The location of the RS as an array of 4284 strings. These strings are typically URIs identifying the 4285 location of the RS. 4287 datatypes (array of strings) The kinds of data available to the 4288 client instance at the RS's API as an array of strings. For 4289 example, a client instance asking for access to raw "image" data 4290 and "metadata" at a photograph API. 4292 identifier (string) A string identifier indicating a specific 4293 resource at the RS. For example, a patient identifier for a 4294 medical API or a bank account number for a financial API. 4296 privileges (array of strings) The types or levels of privilege being 4297 requested at the resource. For example, a client instance asking 4298 for administrative level access, or access when the resource owner 4299 is no longer online. 4301 The following non-normative example is describing three kinds of 4302 access (read, write, delete) to each of two different locations and 4303 two different data types (metadata, images) for a single access token 4304 using the fictitious "photo-api" type definition. 4306 "access": [ 4307 { 4308 "type": "photo-api", 4309 "actions": [ 4310 "read", 4311 "write", 4312 "delete" 4313 ], 4314 "locations": [ 4315 "https://server.example.net/", 4316 "https://resource.local/other" 4317 ], 4318 "datatypes": [ 4319 "metadata", 4320 "images" 4321 ] 4322 } 4323 ] 4325 The access requested for a given object when using these fields is 4326 the cross-product of all fields of the object. That is to say, the 4327 object represents a request for all "actions" listed to be used at 4328 all "locations" listed for all possible "datatypes" listed within the 4329 object. Assuming the request above was granted, the client instance 4330 could assume that it would be able to do a "read" action against the 4331 "images" on the first server as well as a "delete" action on the 4332 "metadata" of the second server, or any other combination of these 4333 fields, using the same access token. 4335 To request a different combination of access, such as requesting one 4336 of the possible "actions" against one of the possible "locations" and 4337 a different choice of possible "actions" against a different one of 4338 the possible "locations", the client instance can include multiple 4339 separate objects in the "resources" array. The following non- 4340 normative example uses the same fictitious "photo-api" type 4341 definition to request a single access token with more specifically 4342 targeted access rights by using two discrete objects within the 4343 request. 4345 "access": [ 4346 { 4347 "type": "photo-api", 4348 "actions": [ 4349 "read" 4350 ], 4351 "locations": [ 4352 "https://server.example.net/" 4353 ], 4354 "datatypes": [ 4355 "images" 4356 ] 4357 }, 4358 { 4359 "type": "photo-api", 4360 "actions": [ 4361 "write", 4362 "delete" 4363 ], 4364 "locations": [ 4365 "https://resource.local/other" 4366 ], 4367 "datatypes": [ 4368 "metadata" 4369 ] 4370 } 4371 ] 4373 The access requested here is for "read" access to "images" on one 4374 server while simultaneously requesting "write" and "delete" access 4375 for "metadata" on a different server, but importantly without 4376 requesting "write" or "delete" access to "images" on the first 4377 server. 4379 It is anticipated that API designers will use a combination of common 4380 fields defined in this specification as well as fields specific to 4381 the API itself. The following non-normative example shows the use of 4382 both common and API-specific fields as part of two different 4383 fictitious API "type" values. The first access request includes the 4384 "actions", "locations", and "datatypes" fields specified here as well 4385 as the API-specific "geolocation" field. The second access request 4386 includes the "actions" and "identifier" fields specified here as well 4387 as the API-specific "currency" field. 4389 "access": [ 4390 { 4391 "type": "photo-api", 4392 "actions": [ 4393 "read", 4394 "write" 4395 ], 4396 "locations": [ 4397 "https://server.example.net/", 4398 "https://resource.local/other" 4399 ], 4400 "datatypes": [ 4401 "metadata", 4402 "images" 4403 ], 4404 "geolocation": [ 4405 { lat: -32.364, lng: 153.207 }, 4406 { lat: -35.364, lng: 158.207 } 4407 ] 4408 }, 4409 { 4410 "type": "financial-transaction", 4411 "actions": [ 4412 "withdraw" 4413 ], 4414 "identifier": "account-14-32-32-3", 4415 "currency": "USD" 4416 } 4417 ] 4419 If this request is approved, the resulting access token 4420 (Section 3.2.1)'s access rights will be the union of the requested 4421 types of access for each of the two APIs, just as above. 4423 8.1. Requesting Resources By Reference 4425 Instead of sending an object describing the requested resource 4426 (Section 8), access rights MAY be communicated as a string known to 4427 the AS or RS representing the access being requested. Each string 4428 SHOULD correspond to a specific expanded object representation at the 4429 AS. 4431 "access": [ 4432 "read", "dolphin-metadata", "some other thing" 4433 ] 4434 This value is opaque to the client instance and MAY be any valid JSON 4435 string, and therefore could include spaces, unicode characters, and 4436 properly escaped string sequences. However, in some situations the 4437 value is intended to be seen and understood by the client software's 4438 developer. In such cases, the API designer choosing any such human- 4439 readable strings SHOULD take steps to ensure the string values are 4440 not easily confused by a developer, such as by limiting the strings 4441 to easily disambiguated characters. 4443 This functionality is similar in practice to OAuth 2.0's "scope" 4444 parameter [RFC6749], where a single string represents the set of 4445 access rights requested by the client instance. As such, the 4446 reference string could contain any valid OAuth 2.0 scope value as in 4447 Appendix D.5. Note that the reference string here is not bound to 4448 the same character restrictions as in OAuth 2.0's "scope" definition. 4450 A single "access" array MAY include both object-type and string-type 4451 resource items. In this non-normative example, the client instance 4452 is requesting access to a "photo-api" and "financial-transaction" API 4453 type as well as the reference values of "read", "dolphin-metadata", 4454 and "some other thing". 4456 "access": [ 4457 { 4458 "type": "photo-api", 4459 "actions": [ 4460 "read", 4461 "write", 4462 "delete" 4463 ], 4464 "locations": [ 4465 "https://server.example.net/", 4466 "https://resource.local/other" 4467 ], 4468 "datatypes": [ 4469 "metadata", 4470 "images" 4471 ] 4472 }, 4473 "read", 4474 "dolphin-metadata", 4475 { 4476 "type": "financial-transaction", 4477 "actions": [ 4478 "withdraw" 4479 ], 4480 "identifier": "account-14-32-32-3", 4481 "currency": "USD" 4482 }, 4483 "some other thing" 4484 ] 4486 The requested access is the union of all elements of the array, 4487 including both objects and reference strings. 4489 9. Discovery 4491 By design, the protocol minimizes the need for any pre-flight 4492 discovery. To begin a request, the client instance only needs to 4493 know the endpoint of the AS and which keys it will use to sign the 4494 request. Everything else can be negotiated dynamically in the course 4495 of the protocol. 4497 However, the AS can have limits on its allowed functionality. If the 4498 client instance wants to optimize its calls to the AS before making a 4499 request, it MAY send an HTTP OPTIONS request to the grant request 4500 endpoint to retrieve the server's discovery information. The AS MUST 4501 respond with a JSON document containing the following information: 4503 grant_request_endpoint (string) REQUIRED. The location of the AS's 4504 grant request endpoint. The location MUST be a URL [RFC3986] with 4505 a scheme component that MUST be https, a host component, and 4506 optionally, port, path and query components and no fragment 4507 components. This URL MUST match the URL the client instance used 4508 to make the discovery request. 4510 interaction_start_modes_supported (array of strings) OPTIONAL. A 4511 list of the AS's interaction start methods. The values of this 4512 list correspond to the possible values for the interaction start 4513 section (Section 2.5.1) of the request. 4515 interaction_finish_methods_supported (array of strings) OPTIONAL. A 4516 list of the AS's interaction finish methods. The values of this 4517 list correspond to the possible values for the method element of 4518 the interaction finish section (Section 2.5.2) of the request. 4520 key_proofs_supported (array of strings) OPTIONAL. A list of the 4521 AS's supported key proofing mechanisms. The values of this list 4522 correspond to possible values of the "proof" field of the key 4523 section (Section 7.1) of the request. 4525 subject_formats_supported (array of strings) OPTIONAL. A list of 4526 the AS's supported subject identifier types. The values of this 4527 list correspond to possible values of the subject identifier 4528 section (Section 2.2) of the request. 4530 assertions_supported (array of strings) OPTIONAL. A list of the 4531 AS's supported assertion formats. The values of this list 4532 correspond to possible values of the subject assertion section 4533 (Section 2.2) of the request. 4535 The information returned from this method is for optimization 4536 purposes only. The AS MAY deny any request, or any portion of a 4537 request, even if it lists a capability as supported. For example, a 4538 given client instance can be registered with the "mtls" key proofing 4539 mechanism, but the AS also returns other proofing methods, then the 4540 AS will deny a request from that client instance using a different 4541 proofing mechanism. 4543 9.1. RS-first Method of AS Discovery 4545 If the client instance calls an RS without an access token, or with 4546 an invalid access token, the RS MAY respond to the client instance 4547 with an authentication header indicating that GNAP needs to be used 4548 to access the resource. The address of the GNAP endpoint MUST be 4549 sent in the "as_uri" parameter. The RS MAY additionally return a 4550 resource reference that the client instance MAY use in its access 4551 token request. This resource reference MUST be sufficient for at 4552 least the action the client instance was attempting to take at the RS 4553 and MAY be more powerful. The means for the RS to determine the 4554 resource reference are out of scope of this specification, but some 4555 dynamic methods are discussed in 4556 [I-D.draft-ietf-gnap-resource-servers]. The content of the resource 4557 handle is opaque to the client instance. 4559 WWW-Authenticate: \ 4560 GNAP as_uri=https://server.example/tx,access=FWWIKYBQ6U56NL1 4562 The client instance then makes a request to the "as_uri" as described 4563 in Section 2, with the value of "access" as one of the members of the 4564 "access" array in the "access_token" portion of the request. The 4565 client instance MAY request additional resources and other 4566 information. The client instance MAY request multiple access tokens. 4568 In this non-normative example, the client instance is requesting a 4569 single access token using the resource reference "FWWIKYBQ6U56NL1" 4570 received from the RS in addition to the "dolphin-metadata" resource 4571 reference that the client instance has been configured with out of 4572 band. 4574 POST /tx HTTP/1.1 4575 Host: server.example.com 4576 Content-Type: application/json 4577 Signature-Input: sig1=... 4578 Signature: sig1=... 4579 Digest: sha256=... 4581 { 4582 "access_token": { 4583 "access": [ 4584 "FWWIKYBQ6U56NL1", 4585 "dolphin-metadata" 4586 ] 4587 }, 4588 "client": "KHRS6X63AJ7C7C4AZ9AO" 4589 } 4591 If issued, the resulting access token would contain sufficient access 4592 to be used at both referenced resources. 4594 10. Acknowledgements 4596 The editors would like to thank the feedback of the following 4597 individuals for their reviews, implementations, and contributions: 4598 Aeke Axeland, Aaron Parecki, Adam Omar Oueidat, Annabelle Backman, 4599 Dick Hardt, Dmitri Zagidulin, Dmitry Barinov, Fabien Imbault, Francis 4600 Pouatcha, George Fletcher, Haardik Haardik, Hamid Massaoud, Jacky 4601 Yuan, Joseph Heenan, Justin Richer, Kathleen Moriarty, Mike Jones, 4602 Mike Varley, Nat Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya. 4604 The editors would also like to thank the GNAP working group design 4605 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 4606 and Justin Richer, who incorporated elements from the XAuth and XYZ 4607 proposals to create the first version of this document. 4609 In addition, the editors would like to thank Aaron Parecki and Mike 4610 Jones for insights into how to integrate identity and authentication 4611 systems into the core protocol, and Justin Richer and Dick Hardt for 4612 the use cases, diagrams, and insights provided in the XYZ and XAuth 4613 proposals that have been incorporated here. The editors would like 4614 to especially thank Mike Varley and the team at SecureKey for 4615 feedback and development of early versions of the XYZ protocol that 4616 fed into this standards work. 4618 11. IANA Considerations 4620 [[ TBD: There are a lot of items in the document that are expandable 4621 through the use of value registries. ]] 4623 12. Security Considerations 4625 [[ TBD: There are a lot of security considerations to add. ]] 4627 All requests have to be over TLS or equivalent as per [BCP195]. Many 4628 handles act as shared secrets, though they can be combined with a 4629 requirement to provide proof of a key as well. 4631 13. Privacy Considerations 4633 [[ TBD: There are a lot of privacy considerations to add. ]] 4635 Handles are passed between parties and therefore should not contain 4636 any private data. 4638 When user information is passed to the client instance, the AS needs 4639 to make sure that it has the permission to do so. 4641 14. Normative References 4643 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 4644 "Recommendations for Secure Use of Transport Layer 4645 Security (TLS) and Datagram Transport Layer Security 4646 (DTLS)", May 2015, 4647 . 4649 [I-D.draft-ietf-gnap-resource-servers] 4650 Richer, J., Parecki, A., and F. Imbault, "Grant 4651 Negotiation and Authorization Protocol Resource Server 4652 Connections", Work in Progress, Internet-Draft, draft- 4653 ietf-gnap-resource-servers-00, 28 April 2021, 4654 . 4657 [I-D.ietf-httpbis-message-signatures] 4658 Backman, A., Richer, J., and M. Sporny, "Signing HTTP 4659 Messages", Work in Progress, Internet-Draft, draft-ietf- 4660 httpbis-message-signatures-05, 8 June 2021, 4661 . 4664 [I-D.ietf-oauth-rar] 4665 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 4666 Rich Authorization Requests", Work in Progress, Internet- 4667 Draft, draft-ietf-oauth-rar-05, 15 May 2021, 4668 . 4671 [I-D.ietf-oauth-signed-http-request] 4672 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 4673 Signing HTTP Requests for OAuth", Work in Progress, 4674 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 4675 August 2016, . 4678 [I-D.ietf-secevent-subject-identifiers] 4679 Backman, A. and M. Scurtescu, "Subject Identifiers for 4680 Security Event Tokens", Work in Progress, Internet-Draft, 4681 draft-ietf-secevent-subject-identifiers-08, 24 May 2021, 4682 . 4685 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 4686 C. Mortimore, "OpenID Connect Core 1.0 incorporating 4687 errata set 1", November 2014, 4688 . 4690 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4691 Requirement Levels", BCP 14, RFC 2119, 4692 DOI 10.17487/RFC2119, March 1997, 4693 . 4695 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 4696 RFC 3230, DOI 10.17487/RFC3230, January 2002, 4697 . 4699 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4700 Resource Identifier (URI): Generic Syntax", STD 66, 4701 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4702 . 4704 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 4705 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 4706 September 2009, . 4708 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 4709 RFC 6749, DOI 10.17487/RFC6749, October 2012, 4710 . 4712 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 4713 Framework: Bearer Token Usage", RFC 6750, 4714 DOI 10.17487/RFC6750, October 2012, 4715 . 4717 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 4718 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 4719 RFC 7234, DOI 10.17487/RFC7234, June 2014, 4720 . 4722 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 4723 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 4724 April 2015, . 4726 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4727 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4728 2015, . 4730 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4731 DOI 10.17487/RFC7517, May 2015, 4732 . 4734 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4735 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4736 May 2017, . 4738 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4739 Interchange Format", STD 90, RFC 8259, 4740 DOI 10.17487/RFC8259, December 2017, 4741 . 4743 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 4744 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 4745 and Certificate-Bound Access Tokens", RFC 8705, 4746 DOI 10.17487/RFC8705, February 2020, 4747 . 4749 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 4750 "Handling Long Lines in Content of Internet-Drafts and 4751 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 4752 . 4754 Appendix A. Document History 4756 * -06 4758 - Removed "capabilities" and "existing_grant" protocol fields. 4760 - Removed separate "instance_id" field. 4762 - Split "interaction_methods_supported" into 4763 "interaction_start_modes_supported" and 4764 "interaction_finish_methods_supported". 4766 - Added AS endpoint to hash calculation to fix mix-up attack. 4768 - Added "privileges" field to resource access request object. 4770 - Moved client-facing RS response back from GNAP-RS document. 4772 - Removed oauthpop key binding. 4774 - Removed dpop key binding. 4776 - Added example DID identifier. 4778 - Changed token response booleans to flag structure to match 4779 request. 4781 - Updated signature examples to use HTTP Message Signatures. 4783 * -05 4784 - Changed "interaction_methods" to 4785 "interaction_methods_supported". 4787 - Changed "key_proofs" to "key_proofs_supported". 4789 - Changed "assertions" to "assertions_supported". 4791 - Updated discovery and field names for subject formats. 4793 - Add an appendix to provide protocol rationale, compared to 4794 OAuth2. 4796 - Updated subject information definition. 4798 - Refactored the RS-centric components into a new document. 4800 - Updated cryptographic proof of possession methods to match 4801 current reference syntax. 4803 - Updated proofing language to use "signer" and "verifier" 4804 generically. 4806 - Updated cryptographic proof of possession examples. 4808 - Editorial cleanup and fixes. 4810 - Diagram cleanup and fixes. 4812 * -04 4814 - Updated terminology. 4816 - Refactored key presentation and binding. 4818 - Refactored "interact" request to group start and end modes. 4820 - Changed access token request and response syntax. 4822 - Changed DPoP digest field to 'htd' to match proposed FAPI 4823 profile. 4825 - Include the access token hash in the DPoP message. 4827 - Removed closed issue links. 4829 - Removed function to read state of grant request by client. 4831 - Closed issues related to reading and updating access tokens. 4833 * -03 4835 - Changed "resource client" terminology to separate "client 4836 instance" and "client software". 4838 - Removed OpenID Connect "claims" parameter. 4840 - Dropped "short URI" redirect. 4842 - Access token is mandatory for continuation. 4844 - Removed closed issue links. 4846 - Editorial fixes. 4848 * -02 4850 - Moved all "editor's note" items to GitHub Issues. 4852 - Added JSON types to fields. 4854 - Changed "GNAP Protocol" to "GNAP". 4856 - Editorial fixes. 4858 * -01 4860 - "updated_at" subject info timestamp now in ISO 8601 string 4861 format. 4863 - Editorial fixes. 4865 - Added Aaron and Fabien as document authors. 4867 * -00 4869 - Initial working group draft. 4871 Appendix B. Compared to OAuth 2.0 4873 GNAP's protocol design differs from OAuth 2.0's in several 4874 fundamental ways: 4876 1. *Consent and authorization flexibility:* 4878 OAuth 2.0 generally assumes the user has access to the a web 4879 browser. The type of interaction available is fixed by the grant 4880 type, and the most common interactive grant types start in the 4881 browser. OAuth 2.0 assumes that the user using the client 4882 software is the same user that will interact with the AS to 4883 approve access. 4885 GNAP allows various patterns to manage authorizations and 4886 consents required to fulfill this requested delegation, including 4887 information sent by the client instance, information supplied by 4888 external parties, and information gathered through the 4889 interaction process. GNAP allows a client instance to list 4890 different ways that it can start and finish an interaction, and 4891 these can be mixed together as needed for different use cases. 4892 GNAP interactions can use a browser, but don't have to. Methods 4893 can use inter-application messaging protocols, out-of-band data 4894 transfer, or anything else. GNAP allows extensions to define new 4895 ways to start and finish an interaction, as new methods and 4896 platforms are expected to become available over time. GNAP is 4897 designed to allow the end-user and the resource owner to be two 4898 different people, but still works in the optimized case of them 4899 being the same party. 4901 2. *Intent registration and inline negotiation:* 4903 OAuth 2.0 uses different "grant types" that start at different 4904 endpoints for different purposes. Many of these require 4905 discovery of several interrelated parameters. 4907 GNAP requests all start with the same type of request to the same 4908 endpoint at the AS. Next steps are negotiated between the client 4909 instance and AS based on software capabilities, policies 4910 surrounding requested access, and the overall context of the 4911 ongoing request. GNAP defines a continuation API that allows the 4912 client instance and AS to request and send additional information 4913 from each other over multiple steps. This continuation API uses 4914 the same access token protection that other GNAP-protected APIs 4915 use. GNAP allows discovery to optimize the requests but it isn't 4916 required thanks to the negotiation capabilities. 4918 3. *Client instances:* 4920 OAuth 2.0 requires all clients to be registered at the AS and to 4921 use a client_id known to the AS as part of the protocol. This 4922 client_id is generally assumed to be assigned by a trusted 4923 authority during a registration process, and OAuth places a lot 4924 of trust on the client_id as a result. Dynamic registration 4925 allows different classes of clients to get a client_id at 4926 runtime, even if they only ever use it for one request. 4928 GNAP allows the client instance to present an unknown key to the 4929 AS and use that key to protect the ongoing request. GNAP's 4930 client instance identifier mechanism allows for pre-registered 4931 clients and dynamically registered clients to exist as an 4932 optimized case without requiring the identifier as part of the 4933 protocol at all times. 4935 4. *Expanded delegation:* 4937 OAuth 2.0 defines the "scope" parameter for controlling access to 4938 APIs. This parameter has been coopted to mean a number of 4939 different things in different protocols, including flags for 4940 turning special behavior on and off, including the return of data 4941 apart from the access token. The "resource" parameter and RAR 4942 extensions (as defined in [I-D.ietf-oauth-rar]) expand on the 4943 "scope" concept in similar but different ways. 4945 GNAP defines a rich structure for requesting access, with string 4946 references as an optimization. GNAP defines methods for 4947 requesting directly-returned user information, separate from API 4948 access. This information includes identifiers for the current 4949 user and structured assertions. The core GNAP protocol makes no 4950 assumptions or demands on the format or contents of the access 4951 token, but the RS extension allows a negotiation of token formats 4952 between the AS and RS. 4954 5. *Cryptography-based security:* 4956 OAuth 2.0 uses shared bearer secrets, including the client_secret 4957 and access token, and advanced authentication and sender 4958 constraint have been built on after the fact in inconsistent 4959 ways. 4961 In GNAP, all communication between the client instance and AS is 4962 bound to a key held by the client instance. GNAP uses the same 4963 cryptographic mechanisms for both authenticating the client (to 4964 the AS) and binding the access token (to the RS and the AS). 4965 GNAP allows extensions to define new cryptographic protection 4966 mechanisms, as new methods are expected to become available over 4967 time. GNAP does not have a notion of "public clients" because 4968 key information can always be sent and used dynamically. 4970 6. *Privacy and usable security:* 4972 OAuth 2.0's deployment model assumes a strong binding between the 4973 AS and the RS. 4975 GNAP is designed to be interoperable with decentralized identity 4976 standards and to provide a human-centric authorization layer. In 4977 addition to the core protocol, GNAP that supports various 4978 patterns of communication between RSs and ASs through extensions. 4979 GNAP tries to limit the odds of a consolidation to just a handful 4980 of super-popular AS services. 4982 Appendix C. Component Data Models 4984 While different implementations of this protocol will have different 4985 realizations of all the components and artifacts enumerated here, the 4986 nature of the protocol implies some common structures and elements 4987 for certain components. This appendix seeks to enumerate those 4988 common elements. 4990 TBD: Client has keys, allowed requested resources, identifier(s), 4991 allowed requested subjects, allowed 4993 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 4994 client keys, policies 4996 TBD: Token has RO, user, client, resource list, RS list, 4998 Appendix D. Example Protocol Flows 5000 The protocol defined in this specification provides a number of 5001 features that can be combined to solve many different kinds of 5002 authentication scenarios. This section seeks to show examples of how 5003 the protocol would be applied for different situations. 5005 Some longer fields, particularly cryptographic information, have been 5006 truncated for display purposes in these examples. 5008 D.1. Redirect-Based User Interaction 5010 In this scenario, the user is the RO and has access to a web browser, 5011 and the client instance can take front-channel callbacks on the same 5012 device as the user. This combination is analogous to the OAuth 2.0 5013 Authorization Code grant type. 5015 The client instance initiates the request to the AS. Here the client 5016 instance identifies itself using its public key. 5018 POST /tx HTTP/1.1 5019 Host: server.example.com 5020 Content-Type: application/json 5021 Signature-Input: sig1=... 5022 Signature: sig1=... 5023 Digest: sha256=... 5025 { 5026 "access_token": { 5027 "access": [ 5028 { 5029 "actions": [ 5030 "read", 5031 "write", 5032 "dolphin" 5033 ], 5034 "locations": [ 5035 "https://server.example.net/", 5036 "https://resource.local/other" 5037 ], 5038 "datatypes": [ 5039 "metadata", 5040 "images" 5041 ] 5042 } 5043 ], 5044 }, 5045 "client": { 5046 "key": { 5047 "proof": "httpsig", 5048 "jwk": { 5049 "kty": "RSA", 5050 "e": "AQAB", 5051 "kid": "xyz-1", 5052 "alg": "RS256", 5053 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 5054 } 5055 } 5056 }, 5057 "interact": { 5058 "start": ["redirect"], 5059 "finish": { 5060 "method": "redirect", 5061 "uri": "https://client.example.net/return/123455", 5062 "nonce": "LKLTI25DK82FX4T4QFZC" 5063 } 5064 } 5065 } 5066 The AS processes the request and determines that the RO needs to 5067 interact. The AS returns the following response giving the client 5068 instance the information it needs to connect. The AS has also 5069 indicated to the client instance that it can use the given instance 5070 identifier to identify itself in future requests (Section 2.3.1). 5072 HTTP/1.1 200 OK 5073 Content-Type: application/json 5074 Cache-Control: no-store 5076 { 5077 "interact": { 5078 "redirect": 5079 "https://server.example.com/interact/4CF492MLVMSW9MKM", 5080 "push": "MBDOFXG4Y5CVJCX821LH" 5081 } 5082 "continue": { 5083 "access_token": { 5084 "value": "80UPRY5NM33OMUKMKSKU" 5085 }, 5086 "uri": "https://server.example.com/continue" 5087 }, 5088 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 5089 } 5091 The client instance saves the response and redirects the user to the 5092 interaction_url by sending the following HTTP message to the user's 5093 browser. 5095 HTTP 302 Found 5096 Location: https://server.example.com/interact/4CF492MLVMSW9MKM 5098 The user's browser fetches the AS's interaction URL. The user logs 5099 in, is identified as the RO for the resource being requested, and 5100 approves the request. Since the AS has a callback parameter, the AS 5101 generates the interaction reference, calculates the hash, and 5102 redirects the user back to the client instance with these additional 5103 values added as query parameters. 5105 HTTP 302 Found 5106 Location: https://client.example.net/return/123455\ 5107 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 5108 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 5109 &interact_ref=4IFWWIKYBC2PQ6U56NL1 5111 The client instance receives this request from the user's browser. 5112 The client instance ensures that this is the same user that was sent 5113 out by validating session information and retrieves the stored 5114 pending request. The client instance uses the values in this to 5115 validate the hash parameter. The client instance then calls the 5116 continuation URL and presents the handle and interaction reference in 5117 the request body. The client instance signs the request as above. 5119 POST /continue HTTP/1.1 5120 Host: server.example.com 5121 Content-Type: application/json 5122 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5123 Signature-Input: sig1=... 5124 Signature: sig1=... 5125 Digest: sha256=... 5127 { 5128 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 5129 } 5131 The AS retrieves the pending request based on the handle and issues a 5132 bearer access token and returns this to the client instance. 5134 HTTP/1.1 200 OK 5135 Content-Type: application/json 5136 Cache-Control: no-store 5138 { 5139 "access_token": { 5140 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5141 "manage": "https://server.example.com/token/PRY5NM33O\ 5142 M4TB8N6BW7OZB8CDFONP219RP1L", 5143 "access": [{ 5144 "actions": [ 5145 "read", 5146 "write", 5147 "dolphin" 5148 ], 5149 "locations": [ 5150 "https://server.example.net/", 5151 "https://resource.local/other" 5152 ], 5153 "datatypes": [ 5154 "metadata", 5155 "images" 5156 ] 5157 }] 5158 }, 5159 "continue": { 5160 "access_token": { 5161 "value": "80UPRY5NM33OMUKMKSKU" 5162 }, 5163 "uri": "https://server.example.com/continue" 5164 } 5165 } 5167 D.2. Secondary Device Interaction 5169 In this scenario, the user does not have access to a web browser on 5170 the device and must use a secondary device to interact with the AS. 5171 The client instance can display a user code or a printable QR code. 5172 The client instance is not able to accept callbacks from the AS and 5173 needs to poll for updates while waiting for the user to authorize the 5174 request. 5176 The client instance initiates the request to the AS. 5178 POST /tx HTTP/1.1 5179 Host: server.example.com 5180 Content-Type: application/json 5181 Signature-Input: sig1=... 5182 Signature: sig1=... 5183 Digest: sha256=... 5185 { 5186 "access_token": { 5187 "access": [ 5188 "dolphin-metadata", "some other thing" 5189 ], 5190 }, 5191 "client": "7C7C4AZ9KHRS6X63AJAO", 5192 "interact": { 5193 "start": ["redirect", "user_code"] 5194 } 5195 } 5197 The AS processes this and determines that the RO needs to interact. 5198 The AS supports both redirect URIs and user codes for interaction, so 5199 it includes both. Since there is no "callback" the AS does not 5200 include a nonce, but does include a "wait" parameter on the 5201 continuation section because it expects the client instance to poll 5202 for results. 5204 HTTP/1.1 200 OK 5205 Content-Type: application/json 5206 Cache-Control: no-store 5208 { 5209 "interact": { 5210 "redirect": "https://srv.ex/MXKHQ", 5211 "user_code": { 5212 "code": "A1BC-3DFF", 5213 "url": "https://srv.ex/device" 5214 } 5215 }, 5216 "continue": { 5217 "access_token": { 5218 "value": "80UPRY5NM33OMUKMKSKU" 5219 }, 5220 "uri": "https://server.example.com/continue/VGJKPTKC50", 5221 "wait": 60 5222 } 5223 } 5224 The client instance saves the response and displays the user code 5225 visually on its screen along with the static device URL. The client 5226 instance also displays the short interaction URL as a QR code to be 5227 scanned. 5229 If the user scans the code, they are taken to the interaction 5230 endpoint and the AS looks up the current pending request based on the 5231 incoming URL. If the user instead goes to the static page and enters 5232 the code manually, the AS looks up the current pending request based 5233 on the value of the user code. In both cases, the user logs in, is 5234 identified as the RO for the resource being requested, and approves 5235 the request. Once the request has been approved, the AS displays to 5236 the user a message to return to their device. 5238 Meanwhile, the client instance periodically polls the AS every 60 5239 seconds at the continuation URL. The client instance signs the 5240 request using the same key and method that it did in the first 5241 request. 5243 POST /continue/VGJKPTKC50 HTTP/1.1 5244 Host: server.example.com 5245 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5246 Signature-Input: sig1=... 5247 Signature: sig1=... 5248 Digest: sha256=... 5250 The AS retrieves the pending request based on the handle and 5251 determines that it has not yet been authorized. The AS indicates to 5252 the client instance that no access token has yet been issued but it 5253 can continue to call after another 60 second timeout. 5255 HTTP/1.1 200 OK 5256 Content-Type: application/json 5257 Cache-Control: no-store 5259 { 5260 "continue": { 5261 "access_token": { 5262 "value": "G7YQT4KQQ5TZY9SLSS5E" 5263 }, 5264 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 5265 "wait": 60 5266 } 5267 } 5268 Note that the continuation URL and access token have been rotated 5269 since they were used by the client instance to make this call. The 5270 client instance polls the continuation URL after a 60 second timeout 5271 using this new information. 5273 POST /continue/ATWHO4Q1WV HTTP/1.1 5274 Host: server.example.com 5275 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 5276 Signature-Input: sig1=... 5277 Signature: sig1=... 5278 Digest: sha256=... 5280 The AS retrieves the pending request based on the URL and access 5281 token, determines that it has been approved, and issues an access 5282 token for the client to use at the RS. 5284 HTTP/1.1 200 OK 5285 Content-Type: application/json 5286 Cache-Control: no-store 5288 { 5289 "access_token": { 5290 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5291 "manage": "https://server.example.com/token/PRY5NM33O\ 5292 M4TB8N6BW7OZB8CDFONP219RP1L", 5293 "access": [ 5294 "dolphin-metadata", "some other thing" 5295 ] 5296 } 5297 } 5299 D.3. No User Involvement 5301 In this scenario, the client instance is requesting access on its own 5302 behalf, with no user to interact with. 5304 The client instance creates a request to the AS, identifying itself 5305 with its public key and using MTLS to make the request. 5307 POST /tx HTTP/1.1 5308 Host: server.example.com 5309 Content-Type: application/json 5311 { 5312 "access_token": { 5313 "access": [ 5314 "backend service", "nightly-routine-3" 5315 ], 5316 }, 5317 "client": { 5318 "key": { 5319 "proof": "mtls", 5320 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 5321 } 5322 } 5323 } 5325 The AS processes this and determines that the client instance can ask 5326 for the requested resources and issues an access token. 5328 HTTP/1.1 200 OK 5329 Content-Type: application/json 5330 Cache-Control: no-store 5332 { 5333 "access_token": { 5334 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5335 "manage": "https://server.example.com/token", 5336 "access": [ 5337 "backend service", "nightly-routine-3" 5338 ] 5339 } 5340 } 5342 D.4. Asynchronous Authorization 5344 In this scenario, the client instance is requesting on behalf of a 5345 specific RO, but has no way to interact with the user. The AS can 5346 asynchronously reach out to the RO for approval in this scenario. 5348 The client instance starts the request at the AS by requesting a set 5349 of resources. The client instance also identifies a particular user. 5351 POST /tx HTTP/1.1 5352 Host: server.example.com 5353 Content-Type: application/json 5354 Signature-Input: sig1=... 5355 Signature: sig1=... 5356 Digest: sha256=... 5358 { 5359 "access_token": { 5360 "access": [ 5361 { 5362 "type": "photo-api", 5363 "actions": [ 5364 "read", 5365 "write", 5366 "dolphin" 5367 ], 5368 "locations": [ 5369 "https://server.example.net/", 5370 "https://resource.local/other" 5371 ], 5372 "datatypes": [ 5373 "metadata", 5374 "images" 5375 ] 5376 }, 5377 "read", "dolphin-metadata", 5378 { 5379 "type": "financial-transaction", 5380 "actions": [ 5381 "withdraw" 5382 ], 5383 "identifier": "account-14-32-32-3", 5384 "currency": "USD" 5385 }, 5386 "some other thing" 5387 ], 5388 }, 5389 "client": "7C7C4AZ9KHRS6X63AJAO", 5390 "user": { 5391 "sub_ids": [ { 5392 "format": "opaque", 5393 "id": "J2G8G8O4AZ" 5394 } ] 5395 } 5396 } 5397 The AS processes this and determines that the RO needs to interact. 5398 The AS determines that it can reach the identified user 5399 asynchronously and that the identified user does have the ability to 5400 approve this request. The AS indicates to the client instance that 5401 it can poll for continuation. 5403 HTTP/1.1 200 OK 5404 Content-Type: application/json 5405 Cache-Control: no-store 5407 { 5408 "continue": { 5409 "access_token": { 5410 "value": "80UPRY5NM33OMUKMKSKU" 5411 }, 5412 "uri": "https://server.example.com/continue", 5413 "wait": 60 5414 } 5415 } 5417 The AS reaches out to the RO and prompts them for consent. In this 5418 example, the AS has an application that it can push notifications in 5419 to for the specified account. 5421 Meanwhile, the client instance periodically polls the AS every 60 5422 seconds at the continuation URL. 5424 POST /continue HTTP/1.1 5425 Host: server.example.com 5426 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5427 Signature-Input: sig1=... 5428 Signature: sig1=... 5430 The AS retrieves the pending request based on the handle and 5431 determines that it has not yet been authorized. The AS indicates to 5432 the client instance that no access token has yet been issued but it 5433 can continue to call after another 60 second timeout. 5435 HTTP/1.1 200 OK 5436 Content-Type: application/json 5437 Cache-Control: no-store 5439 { 5440 "continue": { 5441 "access_token": { 5442 "value": "BI9QNW6V9W3XFJK4R02D" 5443 }, 5444 "uri": "https://server.example.com/continue", 5445 "wait": 60 5446 } 5447 } 5449 Note that the continuation handle has been rotated since it was used 5450 by the client instance to make this call. The client instance polls 5451 the continuation URL after a 60 second timeout using the new handle. 5453 POST /continue HTTP/1.1 5454 Host: server.example.com 5455 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 5456 Signature-Input: sig1=... 5457 Signature: sig1=... 5459 The AS retrieves the pending request based on the handle and 5460 determines that it has been approved and it issues an access token. 5462 HTTP/1.1 200 OK 5463 Content-Type: application/json 5464 Cache-Control: no-store 5466 { 5467 "access_token": { 5468 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5469 "manage": "https://server.example.com/token/PRY5NM33O\ 5470 M4TB8N6BW7OZB8CDFONP219RP1L", 5471 "access": [ 5472 "dolphin-metadata", "some other thing" 5473 ] 5474 } 5475 } 5477 D.5. Applying OAuth 2.0 Scopes and Client IDs 5479 While GNAP is not designed to be directly compatible with OAuth 2.0 5480 [RFC6749], considerations have been made to enable the use of OAuth 5481 2.0 concepts and constructs more smoothly within GNAP. 5483 In this scenario, the client developer has a "client_id" and set of 5484 "scope" values from their OAuth 2.0 system and wants to apply them to 5485 the new protocol. Traditionally, the OAuth 2.0 client developer 5486 would put their "client_id" and "scope" values as parameters into a 5487 redirect request to the authorization endpoint. 5489 HTTP 302 Found 5490 Location: https://server.example.com/authorize 5491 ?client_id=7C7C4AZ9KHRS6X63AJAO 5492 &scope=read%20write%20dolphin 5493 &redirect_uri=https://client.example.net/return 5494 &response_type=code 5495 &state=123455 5497 Now the developer wants to make an analogous request to the AS using 5498 GNAP. To do so, the client instance makes an HTTP POST and places 5499 the OAuth 2.0 values in the appropriate places. 5501 POST /tx HTTP/1.1 5502 Host: server.example.com 5503 Content-Type: application/json 5504 Signature-Input: sig1=... 5505 Signature: sig1=... 5506 Digest: sha256=... 5508 { 5509 "access_token": { 5510 "access": [ 5511 "read", "write", "dolphin" 5512 ], 5513 "flags": [ "bearer" ] 5514 }, 5515 "client": "7C7C4AZ9KHRS6X63AJAO", 5516 "interact": { 5517 "start": ["redirect"], 5518 "finish": { 5519 "method": "redirect", 5520 "uri": "https://client.example.net/return?state=123455", 5521 "nonce": "LKLTI25DK82FX4T4QFZC" 5522 } 5523 } 5524 } 5525 The "client_id" can be used to identify the client instance's keys 5526 that it uses for authentication, the scopes represent resources that 5527 the client instance is requesting, and the "redirect_uri" and "state" 5528 value are pre-combined into a "finish" URI that can be unique per 5529 request. The client instance additionally creates a nonce to protect 5530 the callback, separate from the state parameter that it has added to 5531 its return URL. 5533 From here, the protocol continues as above. 5535 Appendix E. JSON Structures and Polymorphism 5537 GNAP makes use of polymorphism within the JSON [RFC8259] structures 5538 used for the protocol. Each portion of this protocol is defined in 5539 terms of the JSON data type that its values can take, whether it's a 5540 string, object, array, boolean, or number. For some fields, 5541 different data types offer different descriptive capabilities and are 5542 used in different situations for the same field. Each data type 5543 provides a different syntax to express the same underlying semantic 5544 protocol element, which allows for optimization and simplification in 5545 many common cases. 5547 Even though JSON is often used to describe strongly typed structures, 5548 JSON on its own is naturally polymorphic. In JSON, the named members 5549 of an object have no type associated with them, and any data type can 5550 be used as the value for any member. In practice, each member has a 5551 semantic type that needs to make sense to the parties creating and 5552 consuming the object. Within this protocol, each object member is 5553 defined in terms of its semantic content, and this semantic content 5554 might have expressions in different concrete data types for different 5555 specific purposes. Since each object member has exactly one value in 5556 JSON, each data type for an object member field is naturally mutually 5557 exclusive with other data types within a single JSON object. 5559 For example, a resource request for a single access token is composed 5560 of an array of resource request descriptions while a request for 5561 multiple access tokens is composed of an object whose member values 5562 are all arrays. Both of these represent requests for access, but the 5563 difference in syntax allows the client instance and AS to 5564 differentiate between the two request types in the same request. 5566 Another form of polymorphism in JSON comes from the fact that the 5567 values within JSON arrays need not all be of the same JSON data type. 5568 However, within this protocol, each element within the array needs to 5569 be of the same kind of semantic element for the collection to make 5570 sense, even when the data types are different from each other. 5572 For example, each aspect of a resource request can be described using 5573 an object with multiple dimensional components, or the aspect can be 5574 requested using a string. In both cases, the resource request is 5575 being described in a way that the AS needs to interpret, but with 5576 different levels of specificity and complexity for the client 5577 instance to deal with. An API designer can provide a set of common 5578 access scopes as simple strings but still allow client software 5579 developers to specify custom access when needed for more complex 5580 APIs. 5582 Extensions to this specification can use different data types for 5583 defined fields, but each extension needs to not only declare what the 5584 data type means, but also provide justification for the data type 5585 representing the same basic kind of thing it extends. For example, 5586 an extension declaring an "array" representation for a field would 5587 need to explain how the array represents something akin to the non- 5588 array element that it is replacing. 5590 Authors' Addresses 5592 Justin Richer (editor) 5593 Bespoke Engineering 5595 Email: ietf@justin.richer.org 5596 URI: https://bspk.io/ 5598 Aaron Parecki 5599 Okta 5601 Email: aaron@parecki.com 5602 URI: https://aaronparecki.com 5604 Fabien Imbault 5605 acert.io 5607 Email: fabien.imbault@acert.io 5608 URI: https://acert.io/