idnits 2.17.1 draft-ietf-gnap-core-protocol-05.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 205 has weird spacing: '... Client appli...' == Line 229 has weird spacing: '...nd-user natur...' == Line 291 has weird spacing: '...tribute chara...' == Line 293 has weird spacing: '...s Token a dat...' == Line 304 has weird spacing: '...ivilege right...' == (4 more instances...) -- The document date (28 April 2021) is 1093 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-04 == Outdated reference: A later version (-16) exists of draft-ietf-oauth-dpop-03 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-04 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-07 -- 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: 3 errors (**), 0 flaws (~~), 11 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: 30 October 2021 Okta 6 F. Imbault 7 acert.io 8 28 April 2021 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-05 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 30 October 2021. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 7 57 1.4. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 8 58 1.4.1. Redirect-based Interaction . . . . . . . . . . . . . 11 59 1.4.2. User-code Interaction . . . . . . . . . . . . . . . . 14 60 1.4.3. Asynchronous Authorization . . . . . . . . . . . . . 16 61 1.4.4. Software-only Authorization . . . . . . . . . . . . . 18 62 1.4.5. Refreshing an Expired Access Token . . . . . . . . . 19 63 1.4.6. Requesting User Information . . . . . . . . . . . . . 21 64 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 22 65 2.1. Requesting Access to Resources . . . . . . . . . . . . . 24 66 2.1.1. Requesting a Single Access Token . . . . . . . . . . 24 67 2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 27 68 2.2. Requesting Subject Information . . . . . . . . . . . . . 29 69 2.3. Identifying the Client Instance . . . . . . . . . . . . . 30 70 2.3.1. Identifying the Client Instance by Reference . . . . 31 71 2.3.2. Providing Displayable Client Instance Information . . 32 72 2.3.3. Authenticating the Client Instance . . . . . . . . . 33 73 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 33 74 2.4.1. Identifying the User by Reference . . . . . . . . . . 34 75 2.5. Interacting with the User . . . . . . . . . . . . . . . . 35 76 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 36 77 2.5.2. Finish Interaction Modes . . . . . . . . . . . . . . 38 78 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 40 79 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 41 80 2.6. Declaring Client Capabilities . . . . . . . . . . . . . . 41 81 2.7. Referencing an Existing Grant Request . . . . . . . . . . 41 82 2.8. Extending The Grant Request . . . . . . . . . . . . . . . 42 83 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 42 84 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 44 85 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 45 86 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 45 87 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 48 88 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 50 89 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 51 90 3.3.2. Launch of an application URL . . . . . . . . . . . . 51 91 3.3.3. Display of a Short User Code . . . . . . . . . . . . 52 92 3.3.4. Interaction Finish . . . . . . . . . . . . . . . . . 53 93 3.3.5. Extending Interaction Mode Responses . . . . . . . . 54 94 3.4. Returning User Information . . . . . . . . . . . . . . . 54 95 3.5. Returning Dynamically-bound Reference Handles . . . . . . 55 96 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 56 97 3.7. Extending the Response . . . . . . . . . . . . . . . . . 57 98 4. Determining Authorization and Consent . . . . . . . . . . . . 57 99 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 60 100 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 61 101 4.1.2. Interaction at the User Code URI . . . . . . . . . . 61 102 4.1.3. Interaction through an Application URI . . . . . . . 62 103 4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 62 104 4.2.1. Completing Interaction with a Browser Redirect to the 105 Callback URI . . . . . . . . . . . . . . . . . . . . 63 106 4.2.2. Completing Interaction with a Direct HTTP Request 107 Callback . . . . . . . . . . . . . . . . . . . . . . 64 108 4.2.3. Calculating the interaction hash . . . . . . . . . . 65 109 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 66 110 5.1. Continuing After a Completed Interaction . . . . . . . . 68 111 5.2. Continuing During Pending Interaction . . . . . . . . . . 69 112 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 70 113 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 75 114 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 76 115 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 76 116 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 78 117 7. Securing Requests from the Client Instance . . . . . . . . . 79 118 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 79 119 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 81 120 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 81 121 7.3. Proving Possession of a Key with a Request . . . . . . . 82 122 7.3.1. Detached JWS . . . . . . . . . . . . . . . . . . . . 84 123 7.3.2. Attached JWS . . . . . . . . . . . . . . . . . . . . 88 124 7.3.3. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 92 125 7.3.4. Demonstration of Proof-of-Possession (DPoP) . . . . . 94 126 7.3.5. HTTP Message Signing . . . . . . . . . . . . . . . . 96 127 7.3.6. OAuth Proof of Possession (PoP) . . . . . . . . . . . 99 128 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 102 129 8.1. Requesting Resources By Reference . . . . . . . . . . . . 106 130 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 108 131 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 109 132 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 110 133 12. Security Considerations . . . . . . . . . . . . . . . . . . . 110 134 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 110 135 14. Normative References . . . . . . . . . . . . . . . . . . . . 110 136 Appendix A. Document History . . . . . . . . . . . . . . . . . . 113 137 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 115 138 Appendix C. Component Data Models . . . . . . . . . . . . . . . 117 139 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 117 140 D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 118 141 D.2. Secondary Device Interaction . . . . . . . . . . . . . . 122 142 D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 125 143 D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 126 144 D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 129 145 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 131 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 132 148 1. Introduction 150 This protocol allows a piece of software, the client instance, to 151 request delegated authorization to resource servers and to request 152 direct information. This delegation is facilitated by an 153 authorization server usually on behalf of a resource owner. The end- 154 user operating the software may interact with the authorization 155 server to authenticate, provide consent, and authorize the request. 157 The process by which the delegation happens is known as a grant, and 158 GNAP allows for the negotiation of the grant process over time by 159 multiple parties acting in distinct roles. 161 The focus of this protocol is to provide interoperability between the 162 different parties acting in each role, and is not to specify 163 implementation details of each. Where appropriate, GNAP may make 164 recommendations about internal implementation details, but these 165 recommendations are to ensure the security of the overall deployment 166 rather than to be prescriptive in the implementation. 168 This protocol solves many of the same use cases as OAuth 2.0 169 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 170 have grown up around that ecosystem. However, GNAP is not an 171 extension of OAuth 2.0 and is not intended to be directly compatible 172 with OAuth 2.0. GNAP seeks to provide functionality and solve use 173 cases that OAuth 2.0 cannot easily or cleanly address. Appendix B 174 further details the protocol rationale compared to OAuth 2.0. GNAP 175 and OAuth 2.0 will likely exist in parallel for many deployments, and 176 considerations have been taken to facilitate the mapping and 177 transition from legacy systems to GNAP. Some examples of these can 178 be found in Appendix D.5. 180 1.1. Terminology 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 184 "OPTIONAL" in this document are to be interpreted as described in 185 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 186 capitals, as shown here. 188 This document contains non-normative examples of partial and complete 189 HTTP messages, JSON structures, URLs, query components, keys, and 190 other elements. Some examples use a single trailing backslash '' to 191 indicate line wrapping for long values, as per [RFC8792]. The "\" 192 character and leading spaces on wrapped lines are not part of the 193 value. 195 1.2. Roles 197 The parties in GNAP perform actions under different roles. Roles are 198 defined by the actions taken and the expectations leveraged on the 199 role by the overall protocol. 201 Authorization Server (AS) server that grants delegated privileges to 202 a particular instance of client software in the form of access 203 tokens or other information (such as subject information). 205 Client application operated by an end-user that consumes resources 206 from one or several RSs, possibly requiring access privileges from 207 one or several ASs. 209 Example: a client can be a mobile application, a web application, 210 etc. 212 Note: this specification differentiates between a specific 213 instance (the client instance, identified by its unique key) and 214 the software running the instance (the client software). For some 215 kinds of client software, there could be many instances of that 216 software, each instance with a different key. 218 Resource Server (RS) server that provides operations on protected 219 resources, where operations require a valid access token issued by 220 an AS. 222 Resource Owner (RO) subject entity that may grant or deny operations 223 on resources it has authority upon. 225 Note: the act of granting or denying an operation may be manual 226 (i.e. through an interaction with a physical person) or automatic 227 (i.e. through predefined organizational rules). 229 End-user natural person that operates a client instance. 231 Note: that natural person may or may not be the same entity as the 232 RO. 234 The design of GNAP does not assume any one deployment architecture, 235 but instead attempts to define roles that can be fulfilled in a 236 number of different ways for different use cases. As long as a given 237 role fulfills all of its obligations and behaviors as defined by the 238 protocol, GNAP does not make additional requirements on its structure 239 or setup. 241 Multiple roles can be fulfilled by the same party, and a given party 242 can switch roles in different instances of the protocol. For 243 example, the RO and end-user in many instances are the same person, 244 where a user is authorizing the client instance to act on their own 245 behalf at the RS. In this case, one party fulfills both of the RO 246 and end-user roles, but the roles themselves are still defined 247 separately from each other to allow for other use cases where they 248 are fulfilled by different parties. 250 For another example, in some complex scenarios, an RS receiving 251 requests from one client instance can act as a client instance for a 252 downstream secondary RS in order to fulfill the original request. In 253 this case, one piece of software is both an RS and a client instance 254 from different perspectives, and it fulfills these roles separately 255 as far as the overall protocol is concerned. 257 A single role need not be deployed as a monolithic service. For 258 example, A client instance could have components that are installed 259 on the end-user's device as well as a back-end system that it 260 communicates with. If both of these components participate in the 261 delegation protocol, they are both considered part of the client 262 instance. If there are several copies of the client software that 263 run separately but all share the same key material, such as a 264 deployed cluster, then this cluster is considered a single client 265 instance. 267 In these cases, the distinct components of what is considered a GNAP 268 client instance may use any number of different communication 269 mechanisms between them, all of which would be considered an 270 implementation detail of the client instances and out of scope of 271 GNAP. 273 For another example, an AS could likewise be built out of many 274 constituent components in a distributed architecture. The component 275 that the client instance calls directly could be different from the 276 component that the RO interacts with to drive consent, since API 277 calls and user interaction have different security considerations in 278 many environments. Furthermore, the AS could need to collect 279 identity claims about the RO from one system that deals with user 280 attributes while generating access tokens at another system that 281 deals with security rights. From the perspective of GNAP, all of 282 these are pieces of the AS and together fulfill the role of the AS as 283 defined by the protocol. These pieces may have their own internal 284 communications mechanisms which are considered out of scope of GNAP. 286 1.3. Elements 288 In addition to the roles above, the protocol also involves several 289 elements that are acted upon by the roles throughout the process. 291 Attribute characteristics related to a subject. 293 Access Token a data artifact representing a set of rights and/or 294 attributes. 296 Note: an access token can be first issued to an client instance 297 (requiring authorization by the RO) and subsequently rotated. 299 Grant (verb): to permit an instance of client software to receive 300 some attributes at a specific time and valid for a specific 301 duration and/or to exercise some set of delegated rights to access 302 a protected resource (noun): the act of granting. 304 Privilege right or attribute associated with a subject. 306 Note: the RO defines and maintains the rights and attributes 307 associated to the protected resource, and might temporarily 308 delegate some set of those privileges to an end-user. This 309 process is refered to as privilege delegation. 311 Protected Resource protected API (Application Programming Interface) 312 served by an RS and that can be accessed by a client, if and only 313 if a valid access token is provided. 315 Note: to avoid complex sentences, the specification document may 316 simply refer to resource instead of protected resource. 318 Right ability given to a subject to perform a given operation on a 319 resource under the control of an RS. 321 Subject person, organization or device. 323 Subject Information statement asserted by an AS about a subject. 325 1.4. Sequences 327 GNAP can be used in a variety of ways to allow the core delegation 328 process to take place. Many portions of this process are 329 conditionally present depending on the context of the deployments, 330 and not every step in this overview will happen in all circumstances. 332 Note that a connection between roles in this process does not 333 necessarily indicate that a specific protocol message is sent across 334 the wire between the components fulfilling the roles in question, or 335 that a particular step is required every time. For example, for a 336 client instance interested in only getting subject information 337 directly, and not calling an RS, all steps involving the RS below do 338 not apply. 340 In some circumstances, the information needed at a given stage is 341 communicated out of band or is preconfigured between the components 342 or entities performing the roles. For example, one entity can fulfil 343 multiple roles, and so explicit communication between the roles is 344 not necessary within the protocol flow. Additionally some components 345 may not be involved in all use cases. For example, a client instance 346 could be calling the AS just to get direct user information and have 347 no need to get an access token to call an RS. 349 +------------+ +------------+ 350 | End-user | ~ ~ ~ ~ | Resource | 351 | | | Owner (RO) | 352 +------------+ +------------+ 353 + + 354 + + 355 (A) (B) 356 + + 357 + + 358 +--------+ + +------------+ 359 | Client | (1) + | Resource | 360 |Instance| + | Server | 361 | | +---------------+ | (RS) | 362 | |--(2)->| Authorization | | | 363 | |<-(3)--| Server | | | 364 | | | (AS) | | | 365 | |--(4)->| | | | 366 | |<-(5)--| | | | 367 | |--------------(6)------------->| | 368 | | | | (7) | | 369 | |<-------------(8)------------->| | 370 | |--(9)->| | | | 371 | |<-(10)-| | | | 372 | |--------------(11)------------>| | 373 | | | | (12) | | 374 | |-(13)->| | | | 375 | | | | | | 376 +--------+ +---------------+ +------------+ 378 Legend 379 + + + indicates a possible interaction with a human 380 ----- indicates an interaction between protocol roles 381 ~ ~ ~ indicates a potential equivalence or out-of-band 382 communication between roles 384 * (A) The end-user interacts with the client instance to indicate a 385 need for resources on behalf of the RO. This could identify the 386 RS the client instance needs to call, the resources needed, or the 387 RO that is needed to approve the request. Note that the RO and 388 end-user are often the same entity in practice, but some more 389 dynamic processes are discussed in 390 [I-D.draft-ietf-gnap-resource-servers]. 392 * (1) The client instance determines what access is needed and which 393 AS to approach for access. Note that for most situations, the 394 client instance is pre-configured with which AS to talk to and 395 which kinds of access it needs. 397 * (2) The client instance requests access at the AS (Section 2). 399 * (3) The AS processes the request and determines what is needed to 400 fulfill the request. The AS sends its response to the client 401 instance (Section 3). 403 * (B) If interaction is required, the AS interacts with the RO 404 (Section 4) to gather authorization. The interactive component of 405 the AS can function using a variety of possible mechanisms 406 including web page redirects, applications, challenge/response 407 protocols, or other methods. The RO approves the request for the 408 client instance being operated by the end-user. Note that the RO 409 and end-user are often the same entity in practice. 411 * (4) The client instance continues the grant at the AS (Section 5). 413 * (5) If the AS determines that access can be granted, it returns a 414 response to the client instance (Section 3) including an access 415 token (Section 3.2) for calling the RS and any directly returned 416 information (Section 3.4) about the RO. 418 * (6) The client instance uses the access token (Section 7.2) to 419 call the RS. 421 * (7) The RS determines if the token is sufficient for the request 422 by examining the token. The means of the RS determining this 423 access are out of scope of this specification, but some options 424 are discussed in [I-D.draft-ietf-gnap-resource-servers]. 426 * (8) The client instance calls the RS (Section 7.2) using the 427 access token until the RS or client instance determine that the 428 token is no longer valid. 430 * (9) When the token no longer works, the client instance fetches an 431 updated access token (Section 6.1) based on the rights granted in 432 (5). 434 * (10) The AS issues a new access token (Section 3.2) to the client 435 instance. 437 * (11) The client instance uses the new access token (Section 7.2) 438 to call the RS. 440 * (12) The RS determines if the new token is sufficient for the 441 request. The means of the RS determining this access are out of 442 scope of this specification, but some options are discussed in 443 [I-D.draft-ietf-gnap-resource-servers]. 445 * (13) The client instance disposes of the token (Section 6.2) once 446 the client instance has completed its access of the RS and no 447 longer needs the token. 449 The following sections and Appendix D contain specific guidance on 450 how to use GNAP in different situations and deployments. For 451 example, it is possible for the client instance to never request an 452 access token and never call an RS, just as it is possible for there 453 not to be a user involved in the delegation process. 455 1.4.1. Redirect-based Interaction 457 In this example flow, the client instance is a web application that 458 wants access to resources on behalf of the current user, who acts as 459 both the end-user and the resource owner (RO). Since the client 460 instance is capable of directing the user to an arbitrary URL and 461 receiving responses from the user's browser, interaction here is 462 handled through front-channel redirects using the user's browser. 463 The redirection URL used for interaction is a service hosted by the 464 AS in this example. The client instance uses a persistent session 465 with the user to ensure the same user that is starting the 466 interaction is the user that returns from the interaction. 468 +--------+ +--------+ +------+ 469 | Client | | AS | | User | 470 |Instance| | | | | 471 | |< (1) + Start Session + + + + + + + + + + + + + + + +| | 472 | | | | | | 473 | |--(2)--- Request Access --------->| | | | 474 | | | | | | 475 | |<-(3)-- Interaction Needed -------| | | | 476 | | | | | | 477 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 478 | | | | | | 479 | | | |<+ (5) +>| | 480 | | | | AuthN | | 481 | | | | | | 482 | | | |<+ (6) +>| | 483 | | | | AuthZ | | 484 | | | | | | 485 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 486 | | | | +------+ 487 | |--(8)--- Continue Request ------->| | 488 | | | | 489 | |<-(9)----- Grant Access ----------| | 490 | | | | 491 | | | | +--------+ 492 | |--(10)-- Access API ---------------------------->| RS | 493 | | | | | | 494 | |<-(11)-- API Response ---------------------------| | 495 | | | | +--------+ 496 +--------+ +--------+ 498 1. The client instance establishes a verifiable session to the 499 user, in the role of the end-user. 501 2. The client instance requests access to the resource (Section 2). 502 The client instance indicates that it can redirect to an 503 arbitrary URL (Section 2.5.1.1) and receive a redirect from the 504 browser (Section 2.5.2.1). The client instance stores 505 verification information for its redirect in the session created 506 in (1). 508 3. The AS determines that interaction is needed and responds 509 (Section 3) with a URL to send the user to (Section 3.3.1) and 510 information needed to verify the redirect (Section 3.3.4) in 511 (7). The AS also includes information the client instance will 512 need to continue the request (Section 3.1) in (8). The AS 513 associates this continuation information with an ongoing request 514 that will be referenced in (4), (6), and (8). 516 4. The client instance stores the verification and continuation 517 information from (3) in the session from (1). The client 518 instance then redirects the user to the URL (Section 4.1.1) 519 given by the AS in (3). The user's browser loads the 520 interaction redirect URL. The AS loads the pending request 521 based on the incoming URL generated in (3). 523 5. The user authenticates at the AS, taking on the role of the RO. 525 6. As the RO, the user authorizes the pending request from the 526 client instance. 528 7. When the AS is done interacting with the user, the AS redirects 529 the user back (Section 4.2.1) to the client instance using the 530 redirect URL provided in (2). The redirect URL is augmented 531 with an interaction reference that the AS associates with the 532 ongoing request created in (2) and referenced in (4). The 533 redirect URL is also augmented with a hash of the security 534 information provided in (2) and (3). The client instance loads 535 the verification information from (2) and (3) from the session 536 created in (1). The client instance calculates a hash 537 (Section 4.2.3) based on this information and continues only if 538 the hash validates. Note that the client instance needs to 539 ensure that the parameters for the incoming request match those 540 that it is expecting from the session created in (1). The 541 client instance also needs to be prepared for the end-user never 542 being returned to the client instance and handle timeouts 543 appropriately. 545 8. The client instance loads the continuation information from (3) 546 and sends the interaction reference from (7) in a request to 547 continue the request (Section 5.1). The AS validates the 548 interaction reference ensuring that the reference is associated 549 with the request being continued. 551 9. If the request has been authorized, the AS grants access to the 552 information in the form of access tokens (Section 3.2) and 553 direct subject information (Section 3.4) to the client instance. 555 10. The client instance uses the access token (Section 7.2) to call 556 the RS. 558 11. The RS validates the access token and returns an appropriate 559 response for the API. 561 An example set of protocol messages for this method can be found in 562 Appendix D.1. 564 1.4.2. User-code Interaction 566 In this example flow, the client instance is a device that is capable 567 of presenting a short, human-readable code to the user and directing 568 the user to enter that code at a known URL. The URL the user enters 569 the code at is an interactive service hosted by the AS in this 570 example. The client instance is not capable of presenting an 571 arbitrary URL to the user, nor is it capable of accepting incoming 572 HTTP requests from the user's browser. The client instance polls the 573 AS while it is waiting for the RO to authorize the request. The 574 user's interaction is assumed to occur on a secondary device. In 575 this example it is assumed that the user is both the end-user and RO, 576 though the user is not assumed to be interacting with the client 577 instance through the same web browser used for interaction at the AS. 579 +--------+ +--------+ +------+ 580 | Client | | AS | | User | 581 |Instance|--(1)--- Request Access --------->| | | | 582 | | | | | | 583 | |<-(2)-- Interaction Needed -------| | | | 584 | | | | | | 585 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 586 | | | | | | 587 | | | |<+ (4) + | | 588 | | | |Open URI | | 589 | | | | | | 590 | | | |<+ (5) +>| | 591 | | | | AuthN | | 592 | |--(9)--- Continue Request (A) --->| | | | 593 | | | |<+ (6) +>| | 594 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 595 | | | | | | 596 | | | |<+ (7) +>| | 597 | | | | AuthZ | | 598 | | | | | | 599 | | | |<+ (8) +>| | 600 | | | |Completed| | 601 | | | | | | 602 | |--(11)-- Continue Request (B) --->| | +------+ 603 | | | | 604 | |<-(12)----- Grant Access ---------| | 605 | | | | 606 | | | | +--------+ 607 | |--(13)-- Access API ---------------------------->| RS | 608 | | | | | | 609 | |<-(14)-- API Response ---------------------------| | 610 | | | | +--------+ 611 +--------+ +--------+ 612 1. The client instance requests access to the resource (Section 2). 613 The client instance indicates that it can display a user code 614 (Section 2.5.1.3). 616 2. The AS determines that interaction is needed and responds 617 (Section 3) with a user code to communicate to the user 618 (Section 3.3.3). This could optionally include a URL to direct 619 the user to, but this URL should be static and so could be 620 configured in the client instance's documentation. The AS also 621 includes information the client instance will need to continue 622 the request (Section 3.1) in (8) and (10). The AS associates 623 this continuation information with an ongoing request that will 624 be referenced in (4), (6), (8), and (10). 626 3. The client instance stores the continuation information from (2) 627 for use in (8) and (10). The client instance then communicates 628 the code to the user (Section 4.1.1) given by the AS in (2). 630 4. The user's directs their browser to the user code URL. This URL 631 is stable and can be communicated via the client software's 632 documentation, the AS documentation, or the client software 633 itself. Since it is assumed that the RO will interact with the 634 AS through a secondary device, the client instance does not 635 provide a mechanism to launch the RO's browser at this URL. 637 5. The end-user authenticates at the AS, taking on the role of the 638 RO. 640 6. The RO enters the code communicated in (3) to the AS. The AS 641 validates this code against a current request in process. 643 7. As the RO, the user authorizes the pending request from the 644 client instance. 646 8. When the AS is done interacting with the user, the AS indicates 647 to the RO that the request has been completed. 649 9. Meanwhile, the client instance loads the continuation 650 information stored at (3) and continues the request (Section 5). 651 The AS determines which ongoing access request is referenced 652 here and checks its state. 654 10. If the access request has not yet been authorized by the RO in 655 (6), the AS responds to the client instance to continue the 656 request (Section 3.1) at a future time through additional polled 657 continuation requests. This response can include updated 658 continuation information as well as information regarding how 659 long the client instance should wait before calling again. The 660 client instance replaces its stored continuation information 661 from the previous response (2). Note that the AS may need to 662 determine that the RO has not approved the request in a 663 sufficient amount of time and return an appropriate error to the 664 client instance. 666 11. The client instance continues to poll the AS (Section 5.2) with 667 the new continuation information in (9). 669 12. If the request has been authorized, the AS grants access to the 670 information in the form of access tokens (Section 3.2) and 671 direct subject information (Section 3.4) to the client instance. 673 13. The client instance uses the access token (Section 7.2) to call 674 the RS. 676 14. The RS validates the access token and returns an appropriate 677 response for the API. 679 An example set of protocol messages for this method can be found in 680 Appendix D.2. 682 1.4.3. Asynchronous Authorization 684 In this example flow, the end-user and RO roles are fulfilled by 685 different parties, and the RO does not interact with the client 686 instance. The AS reaches out asynchronously to the RO during the 687 request process to gather the RO's authorization for the client 688 instance's request. The client instance polls the AS while it is 689 waiting for the RO to authorize the request. 691 +--------+ +--------+ +------+ 692 | Client | | AS | | RO | 693 |Instance|--(1)--- Request Access --------->| | | | 694 | | | | | | 695 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 696 | | | |<+ (3) +>| | 697 | | | | AuthN | | 698 | |--(6)--- Continue Request (A) --->| | | | 699 | | | |<+ (4) +>| | 700 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 701 | | | | | | 702 | | | |<+ (5) +>| | 703 | | | |Completed| | 704 | | | | | | 705 | |--(8)--- Continue Request (B) --->| | +------+ 706 | | | | 707 | |<-(9)------ Grant Access ---------| | 708 | | | | 709 | | | | +--------+ 710 | |--(10)-- Access API ---------------------------->| RS | 711 | | | | | | 712 | |<-(11)-- API Response ---------------------------| | 713 | | | | +--------+ 714 +--------+ +--------+ 716 1. The client instance requests access to the resource (Section 2). 717 The client instance does not send any interactions modes to the 718 server, indicating that it does not expect to interact with the 719 RO. The client instance can also signal which RO it requires 720 authorization from, if known, by using the user request section 721 (Section 2.4). 723 2. The AS determines that interaction is needed, but the client 724 instance cannot interact with the RO. The AS responds 725 (Section 3) with the information the client instance will need 726 to continue the request (Section 3.1) in (6) and (8), including 727 a signal that the client instance should wait before checking 728 the status of the request again. The AS associates this 729 continuation information with an ongoing request that will be 730 referenced in (3), (4), (5), (6), and (8). 732 3. The AS determines which RO to contact based on the request in 733 (1), through a combination of the user request (Section 2.4), 734 the resources request (Section 2.1), and other policy 735 information. The AS contacts the RO and authenticates them. 737 4. The RO authorizes the pending request from the client instance. 739 5. When the AS is done interacting with the RO, the AS indicates to 740 the RO that the request has been completed. 742 6. Meanwhile, the client instance loads the continuation 743 information stored at (2) and continues the request (Section 5). 744 The AS determines which ongoing access request is referenced 745 here and checks its state. 747 7. If the access request has not yet been authorized by the RO in 748 (6), the AS responds to the client instance to continue the 749 request (Section 3.1) at a future time through additional 750 polling. This response can include refreshed credentials as 751 well as information regarding how long the client instance 752 should wait before calling again. The client instance replaces 753 its stored continuation information from the previous response 754 (2). Note that the AS may need to determine that the RO has not 755 approved the request in a sufficient amount of time and return 756 an appropriate error to the client instance. 758 8. The client instance continues to poll the AS (Section 5.2) with 759 the new continuation information from (7). 761 9. If the request has been authorized, the AS grants access to the 762 information in the form of access tokens (Section 3.2) and 763 direct subject information (Section 3.4) to the client instance. 765 10. The client instance uses the access token (Section 7.2) to call 766 the RS. 768 11. The RS validates the access token and returns an appropriate 769 response for the API. 771 An example set of protocol messages for this method can be found in 772 Appendix D.4. 774 1.4.4. Software-only Authorization 776 In this example flow, the AS policy allows the client instance to 777 make a call on its own behalf, without the need for a RO to be 778 involved at runtime to approve the decision. Since there is no 779 explicit RO, the client instance does not interact with an RO. 781 +--------+ +--------+ 782 | Client | | AS | 783 |Instance|--(1)--- Request Access --->| | 784 | | | | 785 | |<-(2)---- Grant Access -----| | 786 | | | | +--------+ 787 | |--(3)--- Access API ------------------->| RS | 788 | | | | | | 789 | |<-(4)--- API Response ------------------| | 790 | | | | +--------+ 791 +--------+ +--------+ 793 1. The client instance requests access to the resource (Section 2). 794 The client instance does not send any interactions modes to the 795 server. 797 2. The AS determines that the request is been authorized, the AS 798 grants access to the information in the form of access tokens 799 (Section 3.2) to the client instance. Note that direct subject 800 information (Section 3.4) is not generally applicable in this use 801 case, as there is no user involved. 803 3. The client instance uses the access token (Section 7.2) to call 804 the RS. 806 4. 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.3. 812 1.4.5. Refreshing an Expired Access Token 814 In this example flow, the client instance receives an access token to 815 access a resource server through some valid GNAP process. The client 816 instance uses that token at the RS for some time, but eventually the 817 access token expires. The client instance then gets a new access 818 token by rotating the expired access token at the AS using the 819 token's management URL. 821 +--------+ +--------+ 822 | Client | | AS | 823 |Instance|--(1)--- Request Access ----------------->| | 824 | | | | 825 | |<-(2)--- Grant Access --------------------| | 826 | | | | 827 | | +--------+ | | 828 | |--(3)--- Access Resource --->| RS | | | 829 | | | | | | 830 | |<-(4)--- Success Response ---| | | | 831 | | | | | | 832 | | | | | | 833 | | | | | | 834 | |--(5)--- Access Resource --->| | | | 835 | | | | | | 836 | |<-(6)--- Error Response -----| | | | 837 | | +--------+ | | 838 | | | | 839 | |--(7)--- Rotate Token ------------------->| | 840 | | | | 841 | |<-(8)--- Rotated Token -------------------| | 842 | | | | 843 +--------+ +--------+ 845 1. The client instance requests access to the resource (Section 2). 847 2. The AS grants access to the resource (Section 3) with an access 848 token (Section 3.2) usable at the RS. The access token response 849 includes a token management URI. 851 3. The client instance uses the access token (Section 7.2) to call 852 the RS. 854 4. The RS validates the access token and returns an appropriate 855 response for the API. 857 5. Time passes and the client instance uses the access token to call 858 the RS again. 860 6. The RS validates the access token and determines that the access 861 token is expired The RS responds to the client instance with an 862 error. 864 7. The client instance calls the token management URI returned in 865 (2) to rotate the access token (Section 6.1). The client 866 instance uses the access token (Section 7.2) in this call as well 867 as the appropriate key, see the token rotation section for 868 details. 870 8. The AS validates the rotation request including the signature and 871 keys presented in (5) and returns a new access token 872 (Section 3.2.1). The response includes a new access token and 873 can also include updated token management information, which the 874 client instance will store in place of the values returned in 875 (2). 877 1.4.6. Requesting User Information 879 In this scenario, the client instance does not call an RS and does 880 not request an access token. Instead, the client instance only 881 requests and is returned direct subject information (Section 3.4). 882 Many different interaction modes can be used in this scenario, so 883 these are shown only in the abstract as functions of the AS here. 885 +--------+ +--------+ +------+ 886 | Client | | AS | | User | 887 |Instance| | | | | 888 | |--(1)--- Request Access --------->| | | | 889 | | | | | | 890 | |<-(2)--- Request Access ----------| | | | 891 | | | | | | 892 | |+ (3) + Facilitate Interaction + + + + + + + + + + > | | 893 | | | | | | 894 | | | |<+ (4) +>| | 895 | | | | AuthN | | 896 | | | | | | 897 | | | |<+ (5) +>| | 898 | | | | AuthZ | | 899 | | | | | | 900 | |< (6) + Signal Continuation + + + + + + + + + + + + +| | 901 | | | | +------+ 902 | |--(7)--- Continue Request ------->| | 903 | | | | 904 | |<-(8)----- Grant Access ----------| | 905 | | | | 906 +--------+ +--------+ 908 1. The client instance requests access to subject information 909 (Section 2). 911 2. The AS determines that interaction is needed and responds 912 (Section 3) with appropriate information for facilitating user 913 interaction (Section 3.3). 915 3. The client instance facilitates the user interacting with the AS 916 (Section 4) as directed in (2). 918 4. The user authenticates at the AS, taking on the role of the RO. 920 5. As the RO, the user authorizes the pending request from the 921 client instance. 923 6. When the AS is done interacting with the user, the AS returns the 924 user to the client instance and signals continuation. 926 7. The client instance loads the continuation information from (2) 927 and calls the AS to continue the request (Section 5). 929 8. If the request has been authorized, the AS grants access to the 930 requested direct subject information (Section 3.4) to the client 931 instance. At this stage, the user is generally considered 932 "logged in" to the client instance based on the identifiers and 933 assertions provided by the AS. Note that the AS can restrict the 934 subject information returned and it might not match what the 935 client instance requested, see the section on subject information 936 for details. 938 2. Requesting Access 940 To start a request, the client instance sends JSON [RFC8259] document 941 with an object as its root. Each member of the request object 942 represents a different aspect of the client instance's request. Each 943 field is described in detail in a section below. 945 access_token (object / array of objects) Describes the rights and 946 properties associated with the requested access token. 947 Section 2.1 949 subject (object) Describes the information about the RO that the 950 client instance is requesting to be returned directly in the 951 response from the AS. Section 2.2 953 client (object / string) Describes the client instance that is 954 making this request, including the key that the client instance 955 will use to protect this request and any continuation requests at 956 the AS and any user-facing information about the client instance 957 used in interactions. Section 2.3 959 user (object / string) Identifies the end-user to the AS in a manner 960 that the AS can verify, either directly or by interacting with the 961 end-user to determine their status as the RO. Section 2.4 963 interact (object) Describes the modes that the client instance has 964 for allowing the RO to interact with the AS and modes for the 965 client instance to receive updates when interaction is complete. 966 Section 2.5 968 capabilities (array of strings) Identifies named extension 969 capabilities that the client instance can use, signaling to the AS 970 which extensions it can use. Section 2.6 972 existing_grant (string) Identifies a previously-existing grant that 973 the client instance is extending with this request. Section 2.7 975 Additional members of this request object can be defined by 976 extensions to this protocol as described in Section 2.8 978 A non-normative example of a grant request is below: 980 { 981 "access_token": { 982 "access": [ 983 { 984 "type": "photo-api", 985 "actions": [ 986 "read", 987 "write", 988 "dolphin" 989 ], 990 "locations": [ 991 "https://server.example.net/", 992 "https://resource.local/other" 993 ], 994 "datatypes": [ 995 "metadata", 996 "images" 997 ] 998 }, 999 "dolphin-metadata" 1000 ] 1001 }, 1002 "client": { 1003 "display": { 1004 "name": "My Client Display Name", 1005 "uri": "https://example.net/client" 1006 }, 1007 "key": { 1008 "proof": "jwsd", 1009 "jwk": { 1010 "kty": "RSA", 1011 "e": "AQAB", 1012 "kid": "xyz-1", 1013 "alg": "RS256", 1014 "n": "kOB5rR4Jv0GMeL...." 1015 } 1016 } 1017 }, 1018 "interact": { 1019 "start": ["redirect"], 1020 "finish": { 1021 "method": "redirect", 1022 "uri": "https://client.example.net/return/123455", 1023 "nonce": "LKLTI25DK82FX4T4QFZC" 1024 } 1025 }, 1026 "capabilities": ["ext1", "ext2"], 1027 "subject": { 1028 "formats": ["iss_sub", "opaque"], 1029 "assertions": ["id_token"] 1030 } 1031 } 1033 The request and response MUST be sent as a JSON object in the body of 1034 the HTTP POST request with Content-Type "application/json", unless 1035 otherwise specified by the signature mechanism. 1037 The authorization server MUST include the HTTP "Cache-Control" 1038 response header field [RFC7234] with a value set to "no-store". 1040 2.1. Requesting Access to Resources 1042 If the client instance is requesting one or more access tokens for 1043 the purpose of accessing an API, the client instance MUST include an 1044 "access_token" field. This field MUST be an object (for a single 1045 access token (Section 2.1.1)) or an array of these objects (for 1046 multiple access tokens (Section 2.1.2)), as described in the 1047 following sections. 1049 2.1.1. Requesting a Single Access Token 1051 To request a single access token, the client instance sends an 1052 "acccess_token" object composed of the following fields. 1054 access (array of objects/strings) Describes the rights that the 1055 client instance is requesting for one or more access tokens to be 1056 used at RS's. This field is REQUIRED. Section 8 1058 label (string) A unique name chosen by the client instance to refer 1059 to the resulting access token. The value of this field is opaque 1060 to the AS. If this field is included in the request, the AS MUST 1061 include the same label in the token response (Section 3.2). This 1062 field is REQUIRED if used as part of a multiple access token 1063 request (Section 2.1.2), and is OPTIONAL otherwise. 1065 flags (array of strings) A set of flags that indicate desired 1066 attributes or behavior to be attached to the access token by the 1067 AS. This field is OPTIONAL. 1069 The values of the "flags" field defined by this specification are as 1070 follows: 1072 bearer If this flag is included, the access token being requested is 1073 a bearer token. If this flag is omitted, the access token is 1074 bound to the key used by the client instance in this request, or 1075 the key's most recent rotation. Methods for presenting bound and 1076 bearer access tokens are described in Section 7.2. [[ See issue 1077 #38 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/38) 1078 ]] 1080 split If this flag is included, the client instance is capable of 1081 receiving a different number of tokens than specified in the token 1082 request (Section 2.1), including receiving multiple access tokens 1083 (Section 3.2.2) in response to any single token request 1084 (Section 2.1.1) or a different number of access tokens than 1085 requested in a multiple access token request (Section 2.1.2). The 1086 "label" fields of the returned additional tokens are chosen by the 1087 AS. The client instance MUST be able to tell from the token 1088 response where and how it can use each of the access tokens. [[ 1089 See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1090 issues/37) ]] 1092 Flag values MUST NOT be included more than once. 1094 Additional flags can be defined by extensions using a registry TBD 1095 (Section 11). 1097 In the following example, the client instance is requesting access to 1098 a complex resource described by a pair of access request object. 1100 "access_token": { 1101 "access": [ 1102 { 1103 "type": "photo-api", 1104 "actions": [ 1105 "read", 1106 "write", 1107 "delete" 1108 ], 1109 "locations": [ 1110 "https://server.example.net/", 1111 "https://resource.local/other" 1112 ], 1113 "datatypes": [ 1114 "metadata", 1115 "images" 1116 ] 1117 }, 1118 { 1119 "type": "walrus-access", 1120 "actions": [ 1121 "foo", 1122 "bar" 1123 ], 1124 "locations": [ 1125 "https://resource.other/" 1126 ], 1127 "datatypes": [ 1128 "data", 1129 "pictures", 1130 "walrus whiskers" 1131 ] 1132 } 1133 ], 1134 "label": "token1-23", 1135 "flags": [ "split" ] 1136 } 1138 If access is approved, the resulting access token is valid for the 1139 described resource and is bound to the client instance's key (or its 1140 most recent rotation). The token is labeled "token1-23" and could be 1141 split into multiple access tokens by the AS, if the AS chooses. The 1142 token response structure is described in Section 3.2.1. 1144 2.1.2. Requesting Multiple Access Tokens 1146 To request multiple access tokens to be returned in a single 1147 response, the client instance sends an array of objects as the value 1148 of the "access_token" parameter. Each object MUST conform to the 1149 request format for a single access token request, as specified in 1150 requesting a single access token (Section 2.1.1). Additionally, each 1151 object in the array MUST include the "label" field, and all values of 1152 these fields MUST be unique within the request. If the client 1153 instance does not include a "label" value for any entry in the array, 1154 or the values of the "label" field are not unique within the array, 1155 the AS MUST return an error. 1157 The following non-normative example shows a request for two separate 1158 access tokens, "token1" and "token2". 1160 "access_token": [ 1161 { 1162 "label": "token1", 1163 "access": [ 1164 { 1165 "type": "photo-api", 1166 "actions": [ 1167 "read", 1168 "write", 1169 "dolphin" 1170 ], 1171 "locations": [ 1172 "https://server.example.net/", 1173 "https://resource.local/other" 1174 ], 1175 "datatypes": [ 1176 "metadata", 1177 "images" 1178 ] 1179 }, 1180 "dolphin-metadata" 1181 ] 1182 }, 1183 { 1184 "label": "token2", 1185 "access": [ 1186 { 1187 "type": "walrus-access", 1188 "actions": [ 1189 "foo", 1190 "bar" 1191 ], 1192 "locations": [ 1193 "https://resource.other/" 1194 ], 1195 "datatypes": [ 1196 "data", 1197 "pictures", 1198 "walrus whiskers" 1199 ] 1200 } 1201 ], 1202 "flags": [ "bearer" ] 1203 } 1204 ] 1205 All approved access requests are returned in the multiple access 1206 token response (Section 3.2.2) structure using the values of the 1207 "label" fields in the request. 1209 2.2. Requesting Subject Information 1211 If the client instance is requesting information about the RO from 1212 the AS, it sends a "subject" field as a JSON object. This object MAY 1213 contain the following fields (or additional fields defined in a 1214 registry TBD (Section 11)). 1216 formats (array of strings) An array of subject identifier subject 1217 types requested for the RO, as defined by 1218 [I-D.ietf-secevent-subject-identifiers]. 1220 assertions (array of strings) An array of requested assertion 1221 formats. Possible values include "id_token" for an [OIDC] ID 1222 Token and "saml2" for a SAML 2 assertion. Additional assertion 1223 values are defined by a registry TBD (Section 11). [[ See issue 1224 #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) 1225 ]] 1227 "subject": { 1228 "formats": [ "iss_sub", "opaque" ], 1229 "assertions": [ "id_token", "saml2" ] 1230 } 1232 The AS can determine the RO's identity and permission for releasing 1233 this information through interaction with the RO (Section 4), AS 1234 policies, or assertions presented by the client instance 1235 (Section 2.4). If this is determined positively, the AS MAY return 1236 the RO's information in its response (Section 3.4) as requested. 1238 Subject identifier types requested by the client instance serve only 1239 to identify the RO in the context of the AS and can't be used as 1240 communication channels by the client instance, as discussed in 1241 Section 3.4. 1243 The AS SHOULD NOT re-use subject identifiers for multiple different 1244 ROs. 1246 Note: the "formats" and "assertions" request fields are independent 1247 of each other, and a returned assertion MAY omit a requested subject 1248 identifier. 1250 [[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1251 issues/43) ]] 1253 2.3. Identifying the Client Instance 1255 When sending a non-continuation request to the AS, the client 1256 instance MUST identify itself by including the "client" field of the 1257 request and by signing the request as described in Section 7.3. Note 1258 that for a continuation request (Section 5), the client instance is 1259 identified by its association with the request being continued and so 1260 this field is not sent under those circumstances. 1262 When client instance information is sent by value, the "client" field 1263 of the request consists of a JSON object with the following fields. 1265 key (object / string) The public key of the client instance to be 1266 used in this request as described in Section 7.1 or a reference to 1267 a key as described in Section 7.1.1. This field is REQUIRED. 1269 class_id (string) An identifier string that the AS can use to 1270 identify the client software comprising this client instance. The 1271 contents and format of this field are up to the AS. This field is 1272 OPTIONAL. 1274 display (object) An object containing additional information that 1275 the AS MAY display to the RO during interaction, authorization, 1276 and management. This field is OPTIONAL. 1278 "client": { 1279 "key": { 1280 "proof": "httpsig", 1281 "jwk": { 1282 "kty": "RSA", 1283 "e": "AQAB", 1284 "kid": "xyz-1", 1285 "alg": "RS256", 1286 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 1287 }, 1288 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1289 }, 1290 "class_id": "web-server-1234", 1291 "display": { 1292 "name": "My Client Display Name", 1293 "uri": "https://example.net/client" 1294 } 1295 } 1297 Additional fields are defined in a registry TBD (Section 11). 1299 The client instance MUST prove possession of any presented key by the 1300 "proof" mechanism associated with the key in the request. Proof 1301 types are defined in a registry TBD (Section 11) and an initial set 1302 of methods is described in Section 7.3. 1304 Note that the AS MAY know the client instance's public key ahead of 1305 time, and the AS MAY apply different policies to the request 1306 depending on what has been registered against that key. If the same 1307 public key is sent by value on subsequent access requests, the AS 1308 SHOULD treat these requests as coming from the same client instance 1309 for purposes of identification, authentication, and policy 1310 application. If the AS does not know the client instance's public 1311 key ahead of time, the AS MAY accept or reject the request based on 1312 AS policy, attestations within the "client" request, and other 1313 mechanisms. 1315 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1316 issues/44) ]] 1318 2.3.1. Identifying the Client Instance by Reference 1320 If the client instance has an instance identifier that the AS can use 1321 to determine appropriate key information, the client instance can 1322 send this value in the "instance_id" field. The instance identifier 1323 MAY be assigned to a client instance at runtime through the 1324 Section 3.5 or MAY be obtained in another fashion, such as a static 1325 registration process at the AS. 1327 instance_id (string) An identifier string that the AS can use to 1328 identify the particular instance of this client software. The 1329 content and structure of this identifier is opaque to the client 1330 instance. 1332 "client": { 1333 "instance_id": "client-541-ab" 1334 } 1336 If there are no additional fields to send, the client instance MAY 1337 send the instance identifier as a direct reference value in lieu of 1338 the object. 1340 "client": "client-541-ab" 1342 When the AS receives a request with an instance identifier, the AS 1343 MUST ensure that the key used to sign the request (Section 7.3) is 1344 associated with the instance identifier. 1346 If the "instance_id" field is sent, it MUST NOT be accompanied by 1347 other fields unless such fields are explicitly marked safe for 1348 inclusion alongside the instance identifier. 1350 [[ See issue #45 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1351 issues/45) ]] 1353 If the AS does not recognize the instance identifier, the request 1354 MUST be rejected with an error. 1356 If the client instance is identified in this manner, the registered 1357 key for the client instance MAY be a symmetric key known to the AS. 1358 The client instance MUST NOT send a symmetric key by value in the 1359 request, as doing so would expose the key directly instead of proving 1360 possession of it. 1362 2.3.2. Providing Displayable Client Instance Information 1364 If the client instance has additional information to display to the 1365 RO during any interactions at the AS, it MAY send that information in 1366 the "display" field. This field is a JSON object that declares 1367 information to present to the RO during any interactive sequences. 1369 name (string) Display name of the client software 1371 uri (string) User-facing web page of the client software 1373 logo_uri (string) Display image to represent the client software 1375 "display": { 1376 "name": "My Client Display Name", 1377 "uri": "https://example.net/client" 1378 } 1380 [[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1381 issues/48) ]] 1383 Additional display fields are defined by a registry TBD (Section 11). 1385 The AS SHOULD use these values during interaction with the RO. The 1386 values are for informational purposes only and MUST NOT be taken as 1387 authentic proof of the client instance's identity or source. The AS 1388 MAY restrict display values to specific client instances, as 1389 identified by their keys in Section 2.3. 1391 2.3.3. Authenticating the Client Instance 1393 If the presented key is known to the AS and is associated with a 1394 single instance of the client software, the process of presenting a 1395 key and proving possession of that key is sufficient to authenticate 1396 the client instance to the AS. The AS MAY associate policies with 1397 the client instance identified by this key, such as limiting which 1398 resources can be requested and which interaction methods can be used. 1399 For example, only specific client instances with certain known keys 1400 might be trusted with access tokens without the AS interacting 1401 directly with the RO as in Appendix D.3. 1403 The presentation of a key allows the AS to strongly associate 1404 multiple successive requests from the same client instance with each 1405 other. This is true when the AS knows the key ahead of time and can 1406 use the key to authenticate the client instance, but also if the key 1407 is ephemeral and created just for this series of requests. As such 1408 the AS MAY allow for client instances to make requests with unknown 1409 keys. This pattern allows for ephemeral client instances, such as 1410 single-page applications, and client software with many individual 1411 long-lived instances, such as mobile applications, to generate key 1412 pairs per instance and use the keys within the protocol without 1413 having to go through a separate registration step. The AS MAY limit 1414 which capabilities are made available to client instances with 1415 unknown keys. For example, the AS could have a policy saying that 1416 only previously-registered client instances can request particular 1417 resources, or that all client instances with unknown keys have to be 1418 interactively approved by an RO. 1420 2.4. Identifying the User 1422 If the client instance knows the identity of the end-user through one 1423 or more identifiers or assertions, the client instance MAY send that 1424 information to the AS in the "user" field. The client instance MAY 1425 pass this information by value or by reference. 1427 sub_ids (array of objects) An array of subject identifiers for the 1428 end-user, as defined by [I-D.ietf-secevent-subject-identifiers]. 1430 assertions (object) An object containing assertions as values keyed 1431 on the assertion type defined by a registry TBD (Section 11). 1432 Possible keys include "id_token" for an [OIDC] ID Token and 1433 "saml2" for a SAML 2 assertion. Additional assertion values are 1434 defined by a registry TBD (Section 11). [[ See issue #41 1435 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] 1437 "user": { 1438 "sub_ids": [ { 1439 "format": "opaque", 1440 "id": "J2G8G8O4AZ" 1441 } ], 1442 "assertions": { 1443 "id_token": "eyj..." 1444 } 1445 } 1447 Subject identifiers are hints to the AS in determining the RO and 1448 MUST NOT be taken as declarative statements that a particular RO is 1449 present at the client instance and acting as the end-user. 1450 Assertions SHOULD be validated by the AS. [[ See issue #49 1451 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1453 If the identified end-user does not match the RO present at the AS 1454 during an interaction step, the AS SHOULD reject the request with an 1455 error. 1457 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1458 issues/50) ]] 1460 If the AS trusts the client instance to present verifiable 1461 assertions, the AS MAY decide, based on its policy, to skip 1462 interaction with the RO, even if the client instance provides one or 1463 more interaction modes in its request. 1465 2.4.1. Identifying the User by Reference 1467 User reference identifiers can be dynamically issued by the AS 1468 (Section 3.5) to allow the client instance to represent the same end- 1469 user to the AS over subsequent requests. 1471 If the client instance has a reference for the end-user at this AS, 1472 the client instance MAY pass that reference as a string. The format 1473 of this string is opaque to the client instance. 1475 "user": "XUT2MFM1XBIKJKSDU8QM" 1477 User reference identifiers are not intended to be human-readable user 1478 identifiers or structured assertions. For the client instance to 1479 send either of these, use the full user request object (Section 2.4) 1480 instead. 1482 [[ See issue #51 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1483 issues/51) ]] 1484 If the AS does not recognize the user reference, it MUST return an 1485 error. 1487 2.5. Interacting with the User 1489 Often, the AS will require interaction with the RO (Section 4) in 1490 order to approve a requested delegation to the client instance for 1491 both access to resources and direct subject information. Many times 1492 the end-user using the client instance is the same person as the RO, 1493 and the client instance can directly drive interaction with the end 1494 user by facilitating the process through means such as redirection to 1495 a URL or launching an application. Other times, the client instance 1496 can provide information to start the RO's interaction on a secondary 1497 device, or the client instance will wait for the RO to approve the 1498 request asynchronously. The client instance could also be signaled 1499 that interaction has concluded through a callback mechanism. 1501 The client instance declares the parameters for interaction methods 1502 that it can support using the "interact" field. 1504 The "interact" field is a JSON object with three keys whose values 1505 declare how the client can initiate and complete the request, as well 1506 as provide hints to the AS about user preferences such as locale. A 1507 client instance MUST NOT declare an interaction mode it does not 1508 support. The client instance MAY send multiple modes in the same 1509 request. There is no preference order specified in this request. An 1510 AS MAY respond to any, all, or none of the presented interaction 1511 modes (Section 3.3) in a request, depending on its capabilities and 1512 what is allowed to fulfill the request. 1514 start (list of strings/objects) Indicates how the client instance 1515 can start an interaction. 1517 finish (object) Indicates how the client instance can receive an 1518 indication that interaction has finished at the AS. 1520 hints (object) Provides additional information to inform the 1521 interaction process at the AS. 1523 The "interact" field MUST contain the "start" key, and MAY contain 1524 the "finish" and "hints" keys. The value of each key is an array 1525 which contains strings or JSON objects as defined below. 1527 In this non-normative example, the client instance is indicating that 1528 it can redirect (Section 2.5.1.1) the end-user to an arbitrary URL 1529 and can receive a redirect (Section 2.5.2.1) through a browser 1530 request. 1532 "interact": { 1533 "start": ["redirect"], 1534 "finish": { 1535 "method": "redirect", 1536 "uri": "https://client.example.net/return/123455", 1537 "nonce": "LKLTI25DK82FX4T4QFZC" 1538 } 1539 } 1541 In this non-normative example, the client instance is indicating that 1542 it can display a user code (Section 2.5.1.3) and direct the end-user 1543 to an arbitrary URL (Section 2.5.1.1) on a secondary device, but it 1544 cannot accept a redirect or push callback. 1546 "interact": { 1547 "start": ["redirect", "user_code"] 1548 } 1550 If the client instance does not provide a suitable interaction 1551 mechanism, the AS cannot contact the RO asynchronously, and the AS 1552 determines that interaction is required, then the AS SHOULD return an 1553 error since the client instance will be unable to complete the 1554 request without authorization. 1556 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1557 provided, including user codes and redirection URLs. The client 1558 instance SHOULD apply suitable timeouts to any callback URLs. 1560 2.5.1. Start Mode Definitions 1562 This specification defines the following interaction start modes as 1563 an array of string values under the "start" key: 1565 "redirect" Indicates that the client instance can direct the end- 1566 user to an arbitrary URL for interaction. Section 2.5.1.1 1568 "app" Indicates that the client instance can launch an application 1569 on the end-user's device for interaction. Section 2.5.1.2 1571 "user_code" Indicates that the client instance can communicate a 1572 human-readable short code to the end-user for use with a stable 1573 URL. Section 2.5.1.3 1575 2.5.1.1. Redirect to an Arbitrary URL 1577 If the client instance is capable of directing the end-user to a URL 1578 defined by the AS at runtime, the client instance indicates this by 1579 sending the "redirect" field with the boolean value "true". The 1580 means by which the client instance will activate this URL is out of 1581 scope of this specification, but common methods include an HTTP 1582 redirect, launching a browser on the end-user's device, providing a 1583 scannable image encoding, and printing out a URL to an interactive 1584 console. While this URL is generally hosted at the AS, the client 1585 instance can make no assumptions about its contents, composition, or 1586 relationship to the AS grant URL. 1588 "interact": { 1589 "start": ["redirect"] 1590 } 1592 If this interaction mode is supported for this client instance and 1593 request, the AS returns a redirect interaction response 1594 Section 3.3.1. The client instance manages this interaction method 1595 as described in Section 4.1.1. 1597 2.5.1.2. Open an Application-specific URL 1599 If the client instance can open a URL associated with an application 1600 on the end-user's device, the client instance indicates this by 1601 sending the "app" field with boolean value "true". The means by 1602 which the client instance determines the application to open with 1603 this URL are out of scope of this specification. 1605 "interact": { 1606 "start": ["app"] 1607 } 1609 If this interaction mode is supported for this client instance and 1610 request, the AS returns an app interaction response with an app URL 1611 payload Section 3.3.2. The client instance manages this interaction 1612 method as described in Section 4.1.3. 1614 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1615 issues/54) ]] 1617 2.5.1.3. Display a Short User Code 1619 If the client instance is capable of displaying or otherwise 1620 communicating a short, human-entered code to the RO, the client 1621 instance indicates this by sending the "user_code" field with the 1622 boolean value "true". This code is to be entered at a static URL 1623 that does not change at runtime. While this URL is generally hosted 1624 at the AS, the client instance can make no assumptions about its 1625 contents, composition, or relationship to the AS grant URL. 1627 "interact": { 1628 "start": ["user_code"] 1629 } 1631 If this interaction mode is supported for this client instance and 1632 request, the AS returns a user code and interaction URL as specified 1633 in Section 3.3.3. The client instances manages this interaction 1634 method as described in Section 4.1.2 1636 2.5.2. Finish Interaction Modes 1638 If the client instance is capable of receiving a message from the AS 1639 indicating that the RO has completed their interaction, the client 1640 instance indicates this by sending the following members of an object 1641 under the "finish" key. 1643 method (string) REQUIRED. The callback method that the AS will use 1644 to contact the client instance. This specification defines the 1645 following interaction completion methods, with other values 1646 defined by a registry TBD (Section 11): 1648 "redirect" Indicates that the client instance can receive a 1649 redirect from the end-user's device after interaction with the 1650 RO has concluded. Section 2.5.2.1 1652 "push" Indicates that the client instance can receive an HTTP 1653 POST request from the AS after interaction with the RO has 1654 concluded. Section 2.5.2.2 1656 uri (string) REQUIRED. Indicates the URI that the AS will either 1657 send the RO to after interaction or send an HTTP POST request. 1658 This URI MAY be unique per request and MUST be hosted by or 1659 accessible by the client instance. This URI MUST NOT contain any 1660 fragment component. This URI MUST be protected by HTTPS, be 1661 hosted on a server local to the RO's browser ("localhost"), or use 1662 an application-specific URI scheme. If the client instance needs 1663 any state information to tie to the front channel interaction 1664 response, it MUST use a unique callback URI to link to that 1665 ongoing state. The allowable URIs and URI patterns MAY be 1666 restricted by the AS based on the client instance's presented key 1667 information. The callback URI SHOULD be presented to the RO 1668 during the interaction phase before redirect. 1670 nonce (string) REQUIRED. Unique value to be used in the calculation 1671 of the "hash" query parameter sent to the callback URL, must be 1672 sufficiently random to be unguessable by an attacker. MUST be 1673 generated by the client instance as a unique value for this 1674 request. 1676 hash_method (string) OPTIONAL. The hash calculation mechanism to be 1677 used for the callback hash in Section 4.2.3. Can be one of "sha3" 1678 or "sha2". If absent, the default value is "sha3". [[ See issue 1679 #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) 1680 ]] 1682 If this interaction mode is supported for this client instance and 1683 request, the AS returns a nonce for use in validating the callback 1684 response (Section 3.3.4). Requests to the callback URI MUST be 1685 processed as described in Section 4.2, and the AS MUST require 1686 presentation of an interaction callback reference as described in 1687 Section 5.1. 1689 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1690 issues/58) ]] 1692 [[ See issue #59 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1693 issues/59) ]] 1695 2.5.2.1. Receive an HTTP Callback Through the Browser 1697 A finish "method" value of "redirect" indicates that the client 1698 instance will expect a request from the RO's browser using the HTTP 1699 method GET as described in Section 4.2.1. 1701 "interact": { 1702 "finish": { 1703 "method": "redirect", 1704 "uri": "https://client.example.net/return/123455", 1705 "nonce": "LKLTI25DK82FX4T4QFZC" 1706 } 1707 } 1709 Requests to the callback URI MUST be processed by the client instance 1710 as described in Section 4.2.1. 1712 Since the incoming request to the callback URL is from the RO's 1713 browser, this method is usually used when the RO and end-user are the 1714 same entity. As such, the client instance MUST ensure the end-user 1715 is present on the request to prevent substitution attacks. 1717 2.5.2.2. Receive an HTTP Direct Callback 1719 A finish "method" value of "push" indicates that the client instance 1720 will expect a request from the AS directly using the HTTP method POST 1721 as described in Section 4.2.2. 1723 "interact": { 1724 "finish": { 1725 "method": "push", 1726 "uri": "https://client.example.net/return/123455", 1727 "nonce": "LKLTI25DK82FX4T4QFZC" 1728 } 1729 } 1731 Requests to the callback URI MUST be processed by the client instance 1732 as described in Section 4.2.2. 1734 Since the incoming request to the callback URL is from the AS and not 1735 from the RO's browser, the client instance MUST NOT require the end- 1736 user to be present on the incoming HTTP request. 1738 [[ See issue #60 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1739 issues/60) ]] 1741 2.5.3. Hints 1743 The "hints" key is an object describing one or more suggestions from 1744 the client instance that the AS can use to help drive user 1745 interaction. 1747 This specification defines the following properties under the "hints" 1748 key: 1750 ui_locales (array of strings) Indicates the end-user's preferred 1751 locales that the AS can use during interaction, particularly 1752 before the RO has authenticated. Section 2.5.3.1 1754 The following sections detail requests for interaction modes. 1755 Additional interaction modes are defined in a registry TBD 1756 (Section 11). 1758 2.5.3.1. Indicate Desired Interaction Locales 1760 If the client instance knows the end-user's locale and language 1761 preferences, the client instance can send this information to the AS 1762 using the "ui_locales" field with an array of locale strings as 1763 defined by [RFC5646]. 1765 "interact": { 1766 "hints": { 1767 "ui_locales": ["en-US", "fr-CA"] 1768 } 1769 } 1771 If possible, the AS SHOULD use one of the locales in the array, with 1772 preference to the first item in the array supported by the AS. If 1773 none of the given locales are supported, the AS MAY use a default 1774 locale. 1776 2.5.4. Extending Interaction Modes 1778 Additional interaction start modes, finish modes, and hints are 1779 defined in a registry TBD (Section 11). 1781 2.6. Declaring Client Capabilities 1783 If the client software supports extension capabilities, the client 1784 instance MAY present them to the AS in the "capabilities" field. 1785 This field is an array of strings representing specific extensions 1786 and capabilities, as defined by a registry TBD (Section 11). 1788 "capabilities": ["ext1", "ext2"] 1790 2.7. Referencing an Existing Grant Request 1792 If the client instance has a reference handle from a previously 1793 granted request, it MAY send that reference in the "existing_grant" 1794 field. This field is a single string consisting of the "value" of 1795 the "access_token" returned in a previous request's continuation 1796 response (Section 3.1). 1798 "existing_grant": "80UPRY5NM33OMUKMKSKU" 1800 The AS MUST dereference the grant associated with the reference and 1801 process this request in the context of the referenced one. The AS 1802 MUST NOT alter the existing grant associated with the reference. 1804 [[ See issue #62 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1805 issues/62) ]] 1807 2.8. Extending The Grant Request 1809 The request object MAY be extended by registering new items in a 1810 registry TBD (Section 11). Extensions SHOULD be orthogonal to other 1811 parameters. Extensions MUST document any aspects where the extension 1812 item affects or influences the values or behavior of other request 1813 and response objects. 1815 3. Grant Response 1817 In response to a client instance's request, the AS responds with a 1818 JSON object as the HTTP entity body. Each possible field is detailed 1819 in the sections below 1821 continue (object) Indicates that the client instance can continue 1822 the request by making one or more continuation requests. 1823 Section 3.1 1825 access_token (object / array of objects) A single access token or 1826 set of access tokens that the client instance can use to call the 1827 RS on behalf of the RO. Section 3.2.1 1829 interact (object) Indicates that interaction through some set of 1830 defined mechanisms needs to take place. Section 3.3 1832 subject (object) Claims about the RO as known and declared by the 1833 AS. Section 3.4 1835 instance_id (string) An identifier this client instance can use to 1836 identify itself when making future requests. Section 3.5 1838 user_handle (string) An identifier this client instance can use to 1839 identify its current end-user when making future requests. 1840 Section 3.5 1842 error (object) An error code indicating that something has gone 1843 wrong. Section 3.6 1845 In this example, the AS is returning an interaction URL 1846 (Section 3.3.1), a callback nonce (Section 3.3.4), and a continuation 1847 response (Section 3.1). 1849 { 1850 "interact": { 1851 "redirect": "https://server.example.com/interact/4CF492ML\ 1852 VMSW9MKMXKHQ", 1853 "finish": "MBDOFXG4Y5CVJCX821LH" 1854 }, 1855 "continue": { 1856 "access_token": { 1857 "value": "80UPRY5NM33OMUKMKSKU", 1858 "bound": true 1859 }, 1860 "uri": "https://server.example.com/tx" 1861 } 1862 } 1864 In this example, the AS is returning a bearer access token 1865 (Section 3.2.1) with a management URL and a subject identifier 1866 (Section 3.4) in the form of an opaque identifier. 1868 { 1869 "access_token": { 1870 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 1871 "bound": false, 1872 "manage": "https://server.example.com/token/PRY5NM33O\ 1873 M4TB8N6BW7OZB8CDFONP219RP1L", 1874 }, 1875 "subject": { 1876 "sub_ids": [ { 1877 "format": "opaque", 1878 "id": "J2G8G8O4AZ" 1879 } ] 1880 } 1881 } 1883 In this example, the AS is returning only a pair of subject 1884 identifiers (Section 3.4) as both an email address and an opaque 1885 identifier. 1887 { 1888 "subject": { 1889 "sub_ids": [ { 1890 "subject_type": "opaque", 1891 "id": "J2G8G8O4AZ" 1892 }, { 1893 "format": "email", 1894 "email": "user@example.com" 1895 } ] 1896 } 1897 } 1899 3.1. Request Continuation 1901 If the AS determines that the request can be continued with 1902 additional requests, it responds with the "continue" field. This 1903 field contains a JSON object with the following properties. 1905 uri (string) REQUIRED. The URI at which the client instance can 1906 make continuation requests. This URI MAY vary per request, or MAY 1907 be stable at the AS if the AS includes an access token. The 1908 client instance MUST use this value exactly as given when making a 1909 continuation request (Section 5). 1911 wait (integer) RECOMMENDED. The amount of time in integer seconds 1912 the client instance SHOULD wait after receiving this continuation 1913 handle and calling the URI. 1915 access_token (object) REQUIRED. A unique access token for 1916 continuing the request, in the format specified in Section 3.2.1. 1917 This access token MUST be bound to the client instance's key used 1918 in the request and MUST NOT be a "bearer" token. As a 1919 consequence, the "bound" field of this access token is always the 1920 boolean value "true" and the "key" field MUST be omitted. This 1921 access token MUST NOT be usable at resources outside of the AS. 1922 The client instance MUST present the access token in all requests 1923 to the continuation URI as described in Section 7.2. [[ See issue 1924 #66 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/66) 1925 ]] 1927 { 1928 "continue": { 1929 "access_token": { 1930 "value": "80UPRY5NM33OMUKMKSKU" 1931 }, 1932 "uri": "https://server.example.com/continue", 1933 "wait": 60 1934 } 1935 } 1937 The client instance can use the values of this field to continue the 1938 request as described in Section 5. Note that the client instance 1939 MUST sign all continuation requests with its key as described in 1940 Section 7.3 and MUST present the access token in its continuation 1941 request. 1943 This field SHOULD be returned when interaction is expected, to allow 1944 the client instance to follow up after interaction has been 1945 concluded. 1947 3.2. Access Tokens 1949 If the AS has successfully granted one or more access tokens to the 1950 client instance, the AS responds with the "access_token" field. This 1951 field contains either a single access token as described in 1952 Section 3.2.1 or an array of access tokens as described in 1953 Section 3.2.2. 1955 The client instance uses any access tokens in this response to call 1956 the RS as described in Section 7.2. 1958 3.2.1. Single Access Token 1960 If the client instance has requested a single access token and the AS 1961 has granted that access token, the AS responds with the 1962 "access_token" field. The value of this field is an object with the 1963 following properties. 1965 value (string) REQUIRED. The value of the access token as a string. 1966 The value is opaque to the client instance. The value SHOULD be 1967 limited to ASCII characters to facilitate transmission over HTTP 1968 headers within other protocols without requiring additional 1969 encoding. 1971 bound (boolean) RECOMMENDED. Flag indicating if the token is bound 1972 to the client instance's key. If the boolean value is "true" or 1973 the field is omitted, and the "key" field is omitted, the token is 1974 bound to the key used by the client instance (Section 2.3) in its 1975 request for access. If the boolean value is "true" or the field 1976 is omitted, and the "key" field is present, the token is bound to 1977 the key and proofing mechanism indicated in the "key" field. If 1978 the boolean value is "false", the token is a bearer token with no 1979 key bound to it and the "key" field MUST be omitted. 1981 label (string) REQUIRED for multiple access tokens, OPTIONAL for 1982 single access token. The value of the "label" the client instance 1983 provided in the associated token request (Section 2.1), if 1984 present. If the token has been split by the AS, the value of the 1985 "label" field is chosen by the AS and the "split" field is 1986 included and set to "true". 1988 manage (string) OPTIONAL. The management URI for this access token. 1989 If provided, the client instance MAY manage its access token as 1990 described in Section 6. This management URI is a function of the 1991 AS and is separate from the RS the client instance is requesting 1992 access to. This URI MUST NOT include the access token value and 1993 SHOULD be different for each access token issued in a request. 1995 access (array of objects/strings) RECOMMENDED. A description of the 1996 rights associated with this access token, as defined in Section 8. 1997 If included, this MUST reflect the rights associated with the 1998 issued access token. These rights MAY vary from what was 1999 requested by the client instance. 2001 expires_in (integer) OPTIONAL. The number of seconds in which the 2002 access will expire. The client instance MUST NOT use the access 2003 token past this time. An RS MUST NOT accept an access token past 2004 this time. Note that the access token MAY be revoked by the AS or 2005 RS at any point prior to its expiration. 2007 key (object / string) OPTIONAL. The key that the token is bound to, 2008 if different from the client instance's presented key. The key 2009 MUST be an object or string in a format described in Section 7.1. 2010 The client instance MUST be able to dereference or process the key 2011 information in order to be able to sign the request. 2013 durable (boolean) OPTIONAL. Flag indicating a hint of AS behavior 2014 on token rotation. If this flag is set to the value "true", then 2015 the client instance can expect a previously-issued access token to 2016 continue to work after it has been rotated (Section 6.1) or the 2017 underlying grant request has been modified (Section 5.3), 2018 resulting in the issuance of new access tokens. If this flag is 2019 set to the boolean value "false" or is omitted, the client 2020 instance can anticipate a given access token will stop working 2021 after token rotation or grant request modification. Note that a 2022 token flagged as "durable" can still expire or be revoked through 2023 any normal means. 2025 split (boolean) OPTIONAL. Flag indicating that this token was 2026 generated by issuing multiple access tokens in response to one of 2027 the client instance's token request (Section 2.1) objects. This 2028 behavior MUST NOT be used unless the client instance has 2029 specifically requested it by use of the "split" flag. 2031 The following non-normative example shows a single access token bound 2032 to the client instance's key used in the initial request, with a 2033 management URL, and that has access to three described resources (one 2034 using an object and two described by reference strings). 2036 "access_token": { 2037 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2038 "manage": "https://server.example.com/token/PRY5NM33O\ 2039 M4TB8N6BW7OZB8CDFONP219RP1L", 2040 "access": [ 2041 { 2042 "type": "photo-api", 2043 "actions": [ 2044 "read", 2045 "write", 2046 "dolphin" 2047 ], 2048 "locations": [ 2049 "https://server.example.net/", 2050 "https://resource.local/other" 2051 ], 2052 "datatypes": [ 2053 "metadata", 2054 "images" 2055 ] 2056 }, 2057 "read", "dolphin-metadata" 2058 ] 2059 } 2060 The following non-normative example shows a single bearer access 2061 token with access to two described resources. 2063 "access_token": { 2064 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2065 "bound": false, 2066 "access": [ 2067 "finance", "medical" 2068 ] 2069 } 2071 If the client instance requested a single access token 2072 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2073 token structure unless the client instance sends the "split" flag as 2074 described in Section 2.1.1. 2076 If the AS has split the access token response, the response MUST 2077 include the "split" flag set to "true". 2079 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2080 issues/69) ]] 2082 3.2.2. Multiple Access Tokens 2084 If the client instance has requested multiple access tokens and the 2085 AS has granted at least one of them, the AS responds with the 2086 "access_token" field. The value of this field is a JSON array, the 2087 members of which are distinct access tokens as described in 2088 Section 3.2.1. Each object MUST have a unique "label" field, 2089 corresponding to the token labels chosen by the client instance in 2090 the multiple access token request (Section 2.1.2). 2092 In this non-normative example, two tokens are issued under the names 2093 "token1" and "token2", and only the first token has a management URL 2094 associated with it. 2096 "access_token": [ 2097 { 2098 "label": "token1", 2099 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2100 "manage": "https://server.example.com/token/PRY5NM33O\ 2101 M4TB8N6BW7OZB8CDFONP219RP1L", 2102 "access": [ "finance" ] 2103 }, 2104 { 2105 "label": "token2", 2106 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2107 "access": [ "medical" ] 2108 } 2109 } 2111 Each access token corresponds to one of the objects in the 2112 "access_token" array of the client instance's request 2113 (Section 2.1.2). 2115 The multiple access token response MUST be used when multiple access 2116 tokens are requested, even if only one access token is issued as a 2117 result of the request. The AS MAY refuse to issue one or more of the 2118 requested access tokens, for any reason. In such cases the refused 2119 token is omitted from the response and all of the other issued access 2120 tokens are included in the response the requested names appropriate 2121 names. 2123 If the client instance requested multiple access tokens 2124 (Section 2.1.2), the AS MUST NOT respond with a single access token 2125 structure, even if only a single access token is granted. In such 2126 cases, the AS responds with a multiple access token structure 2127 containing one access token. 2129 If the AS has split the access token response, the response MUST 2130 include the "split" flag set to "true". 2132 "access_token": [ 2133 { 2134 "label": "split-1", 2135 "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", 2136 "split": true, 2137 "manage": "https://server.example.com/token/PRY5NM33O\ 2138 M4TB8N6BW7OZB8CDFONP219RP1L", 2139 "access": [ "fruits" ] 2140 }, 2141 { 2142 "label": "split-2", 2143 "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", 2144 "split": true, 2145 "access": [ "vegetables" ] 2146 } 2147 } 2149 Each access token MAY be bound to different keys with different 2150 proofing mechanisms. 2152 If token management (Section 6) is allowed, each access token SHOULD 2153 have different "manage" URIs. 2155 [[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2156 issues/70) ]] 2158 3.3. Interaction Modes 2160 If the client instance has indicated a capability to interact with 2161 the RO in its request (Section 2.5), and the AS has determined that 2162 interaction is both supported and necessary, the AS responds to the 2163 client instance with any of the following values in the "interact" 2164 field of the response. There is no preference order for interaction 2165 modes in the response, and it is up to the client instance to 2166 determine which ones to use. All supported interaction methods are 2167 included in the same "interact" object. 2169 redirect (string) Redirect to an arbitrary URL. Section 3.3.1 2171 app (string) Launch of an application URL. Section 3.3.2 2173 finish (string) A nonce used by the client instance to verify the 2174 callback after interaction is completed. Section 3.3.4 2176 user_code (object) Display a short user code. Section 3.3.3 2178 Additional interaction mode responses can be defined in a registry 2179 TBD (Section 11). 2181 The AS MUST NOT respond with any interaction mode that the client 2182 instance did not indicate in its request. The AS MUST NOT respond 2183 with any interaction mode that the AS does not support. Since 2184 interaction responses include secret or unique information, the AS 2185 SHOULD respond to each interaction mode only once in an ongoing 2186 request, particularly if the client instance modifies its request 2187 (Section 5.3). 2189 3.3.1. Redirection to an arbitrary URL 2191 If the client instance indicates that it can redirect to an arbitrary 2192 URL (Section 2.5.1.1) and the AS supports this mode for the client 2193 instance's request, the AS responds with the "redirect" field, which 2194 is a string containing the URL to direct the end-user to. This URL 2195 MUST be unique for the request and MUST NOT contain any security- 2196 sensitive information such as user identifiers or access tokens. 2198 "interact": { 2199 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2200 } 2202 The URL returned is a function of the AS, but the URL itself MAY be 2203 completely distinct from the URL the client instance uses to request 2204 access (Section 2), allowing an AS to separate its user-interactive 2205 functionality from its back-end security functionality. If the AS 2206 does not directly host the functionality accessed through the given 2207 URL, then the means for the interaction functionality to communicate 2208 with the rest of the AS are out of scope for this specification. 2210 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2211 issues/72) ]] 2213 The client instance sends the end-user to the URL to interact with 2214 the AS. The client instance MUST NOT alter the URL in any way. The 2215 means for the client instance to send the end-user to this URL is out 2216 of scope of this specification, but common methods include an HTTP 2217 redirect, launching the system browser, displaying a scannable code, 2218 or printing out the URL in an interactive console. See details of 2219 the interaction in Section 4.1.1. 2221 3.3.2. Launch of an application URL 2223 If the client instance indicates that it can launch an application 2224 URL (Section 2.5.1.2) and the AS supports this mode for the client 2225 instance's request, the AS responds with the "app" field, which is a 2226 string containing the URL for the client instance to launch. This 2227 URL MUST be unique for the request and MUST NOT contain any security- 2228 sensitive information such as user identifiers or access tokens. 2230 "interact": { 2231 "app": "https://app.example.com/launch?tx=4CF492MLV" 2232 } 2234 The means for the launched application to communicate with the AS are 2235 out of scope for this specification. 2237 The client instance launches the URL as appropriate on its platform, 2238 and the means for the client instance to launch this URL is out of 2239 scope of this specification. The client instance MUST NOT alter the 2240 URL in any way. The client instance MAY attempt to detect if an 2241 installed application will service the URL being sent before 2242 attempting to launch the application URL. See details of the 2243 interaction in Section 4.1.3. 2245 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2246 issues/71) ]] 2248 3.3.3. Display of a Short User Code 2250 If the client instance indicates that it can display a short 2251 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2252 for the client instance's request, the AS responds with a "user_code" 2253 field. This field is an object that contains the following members. 2255 code (string) REQUIRED. A unique short code that the user can type 2256 into an authorization server. This string MUST be case- 2257 insensitive, MUST consist of only easily typeable characters (such 2258 as letters or numbers). The time in which this code will be 2259 accepted SHOULD be short lived, such as several minutes. It is 2260 RECOMMENDED that this code be no more than eight characters in 2261 length. 2263 url (string) RECOMMENDED. The interaction URL that the client 2264 instance will direct the RO to. This URL MUST be stable such that 2265 client instances can be statically configured with it. 2267 "interact": { 2268 "user_code": { 2269 "code": "A1BC-3DFF", 2270 "url": "https://srv.ex/device" 2271 } 2272 } 2274 The client instance MUST communicate the "code" to the end-user in 2275 some fashion, such as displaying it on a screen or reading it out 2276 audibly. 2278 The client instance SHOULD also communicate the URL if possible to 2279 facilitate user interaction, but since the URL should be stable, the 2280 client instance should be able to safely decide to not display this 2281 value. As this interaction mode is designed to facilitate 2282 interaction via a secondary device, it is not expected that the 2283 client instance redirect the end-user to the URL given here at 2284 runtime. Consequently, the URL needs to be stable enough that a 2285 client instance could be statically configured with it, perhaps 2286 referring the end-user to the URL via documentation instead of 2287 through an interactive means. If the client instance is capable of 2288 communicating an arbitrary URL to the end-user, such as through a 2289 scannable code, the client instance can use the "redirect" 2290 (Section 2.5.1.1) mode for this purpose instead of or in addition to 2291 the user code mode. 2293 The URL returned is a function of the AS, but the URL itself MAY be 2294 completely distinct from the URL the client instance uses to request 2295 access (Section 2), allowing an AS to separate its user-interactive 2296 functionality from its back-end security functionality. If the AS 2297 does not directly host the functionality accessed through the given 2298 URL, then the means for the interaction functionality to communicate 2299 with the rest of the AS are out of scope for this specification. 2301 See details of the interaction in Section 4.1.2. 2303 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2304 issues/72) ]] 2306 3.3.4. Interaction Finish 2308 If the client instance indicates that it can receive a 2309 post-interaction redirect or push at a URL (Section 2.5.2) and the AS 2310 supports this mode for the client instance's request, the AS responds 2311 with a "finish" field containing a nonce that the client instance 2312 will use in validating the callback as defined in Section 4.2. 2314 "interact": { 2315 "finish": "MBDOFXG4Y5CVJCX821LH" 2316 } 2318 When the interaction is completed, the interaction component MUST 2319 contact the client instance using either a redirect or launch of the 2320 RO's browser or through an HTTP POST to the client instance's 2321 callback URL using the method indicated in the interaction request 2322 (Section 2.5.2) as described in Section 4.2. 2324 If the AS returns a nonce, the client instance MUST NOT continue a 2325 grant request before it receives the associated interaction reference 2326 on the callback URI. See details in Section 4.2. 2328 3.3.5. Extending Interaction Mode Responses 2330 Extensions to this specification can define new interaction mode 2331 responses in a registry TBD (Section 11). Extensions MUST document 2332 the corresponding interaction request. 2334 3.4. Returning User Information 2336 If information about the RO is requested and the AS grants the client 2337 instance access to that data, the AS returns the approved information 2338 in the "subject" response field. This field is an object with the 2339 following OPTIONAL properties. 2341 sub_ids (array of objects) An array of subject identifiers for the 2342 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2344 assertions (object) An object containing assertions as values keyed 2345 on the assertion type defined by a registry TBD (Section 11). [[ 2346 See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2347 issues/41) ]] 2349 updated_at (string) Timestamp as an ISO8610 date string, indicating 2350 when the identified account was last updated. The client instance 2351 MAY use this value to determine if it needs to request updated 2352 profile information through an identity API. The definition of 2353 such an identity API is out of scope for this specification. 2355 "subject": { 2356 "sub_ids": [ { 2357 "format": "opaque", 2358 "id": "J2G8G8O4AZ" 2359 } ], 2360 "assertions": { 2361 "id_token": "eyj..." 2362 } 2363 } 2365 The AS MUST return the "subject" field only in cases where the AS is 2366 sure that the RO and the end-user are the same party. This can be 2367 accomplished through some forms of interaction with the RO 2368 (Section 4). 2370 Subject identifiers returned by the AS SHOULD uniquely identify the 2371 RO at the AS. Some forms of subject identifier are opaque to the 2372 client instance (such as the subject of an issuer and subject pair), 2373 while others forms (such as email address and phone number) are 2374 intended to allow the client instance to correlate the identifier 2375 with other account information at the client instance. The AS MUST 2376 ensure that the returned subject identifiers only apply to the 2377 authenticated end user. The client instance MUST NOT request or use 2378 any returned subject identifiers for communication purposes (see 2379 Section 2.2). That is, a subject identifier returned in the format 2380 of an email address or a phone number only identifies the RO to the 2381 AS and does not indicate that the AS has validated that the 2382 represented email address or phone number in the identifier is 2383 suitable for communication with the current user. To get such 2384 information, the client instance MUST use an identity protocol to 2385 request and receive additional identity claims. The details of an 2386 identity protocol and associated schema are outside the scope of this 2387 specification. 2389 Extensions to this specification MAY define additional response 2390 properties in a registry TBD (Section 11). 2392 3.5. Returning Dynamically-bound Reference Handles 2394 Many parts of the client instance's request can be passed as either a 2395 value or a reference. The use of a reference in place of a value 2396 allows for a client instance to optimize requests to the AS. 2398 Some references, such as for the client instance's identity 2399 (Section 2.3.1) or the requested resources (Section 8.1), can be 2400 managed statically through an admin console or developer portal 2401 provided by the AS or RS. The developer of the client software can 2402 include these values in their code for a more efficient and compact 2403 request. 2405 If desired, the AS MAY also generate and return some of these 2406 references dynamically to the client instance in its response to 2407 facilitate multiple interactions with the same software. The client 2408 instance SHOULD use these references in future requests in lieu of 2409 sending the associated data value. These handles are intended to be 2410 used on future requests. 2412 Dynamically generated handles are string values that MUST be 2413 protected by the client instance as secrets. Handle values MUST be 2414 unguessable and MUST NOT contain any sensitive information. Handle 2415 values are opaque to the client instance. 2417 All dynamically generated handles are returned as fields in the root 2418 JSON object of the response. This specification defines the 2419 following dynamic handle returns, additional handles can be defined 2420 in a registry TBD (Section 11). 2422 instance_id (string) A string value used to represent the 2423 information in the "client" object that the client instance can 2424 use in a future request, as described in Section 2.3.1. 2426 user_handle (string) A string value used to represent the current 2427 user. The client instance can use in a future request, as 2428 described in Section 2.4.1. 2430 This non-normative example shows two handles along side an issued 2431 access token. 2433 { 2434 "user_handle": "XUT2MFM1XBIKJKSDU8QM", 2435 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2436 "access_token": { 2437 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 2438 } 2439 } 2441 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2442 issues/77) ]] 2444 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2445 issues/78) ]] 2447 3.6. Error Response 2449 If the AS determines that the request cannot be issued for any 2450 reason, it responds to the client instance with an error message. 2452 error (string) The error code. 2454 { 2456 "error": "user_denied" 2458 } 2460 The error code is one of the following, with additional values 2461 available in a registry TBD (Section 11): 2463 user_denied The RO denied the request. 2465 too_fast The client instance did not respect the timeout in the wait 2466 response. 2468 unknown_request The request referenced an unknown ongoing access 2469 request. 2471 [[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2472 issues/79) ]] 2474 3.7. Extending the Response 2476 Extensions to this specification MAY define additional fields for the 2477 grant response in a registry TBD (Section 11). 2479 4. Determining Authorization and Consent 2481 When the client instance makes its Section 2 to the AS for delegated 2482 access, it is capable of asking for several different kinds of 2483 information in response: 2485 * the access being requested in the "access_token" request parameter 2487 * the subject information being requested in the "subject" request 2488 parameter 2490 * any additional requested information defined by extensions of this 2491 protocol 2493 The AS determines what authorizations and consents are required to 2494 fulfill this requested delegation. The details of how the AS makes 2495 this determination are out of scope for this document. However, 2496 there are several common patterns defined and supported by GNAP for 2497 fulfilling these requirements, including information sent by the 2498 client instance, information gathered through the interaction 2499 process, and information supplied by external parties. An individual 2500 AS can define its own policies and processes for deciding when and 2501 how to gather the necessary authorizations and consent. 2503 The client instance can supply information directly to the AS in its 2504 request. From this information, the AS can determine if the 2505 requested delegation can be granted immediately. The client instance 2506 can send several kinds of things, including: 2508 * the identity of the client instance, known from the presented keys 2509 or associated identifiers 2511 * the identity of the end user presented in the "user" request 2512 parameter 2514 * any additional information presented by the client instance in the 2515 request, including any extensions 2517 The AS will verify this presented information in the context of the 2518 client instance's request and can only trust the information as much 2519 as it trusts the presentation and context of the information. If the 2520 AS determines that the information presented in the initial request 2521 is sufficient for granting the requested access, the AS MAY return 2522 the positive results immediately in its Section 3 with access tokens 2523 and subject information. 2525 If the AS determines that additional runtime authorization is 2526 required, the AS can either deny the request outright or use a number 2527 of means at its disposal to gather that authorization from the 2528 appropriate ROs, including for example: 2530 * starting interaction with the end user facilitated by the client 2531 software, such as a redirection or user code 2533 * challenging the client instance through a challenge-response 2534 mechanism 2536 * requesting that the client instance present specific additional 2537 information, such as a user's credential or an assertion 2539 * contacting a RO through an out-of-band mechanism, such as a push 2540 notification 2542 * contacting an auxiliary software process through an out-of-band 2543 mechanism, such as querying a digital wallet 2545 The authorization and consent gathering process in GNAP is left 2546 deliberately flexible to allow for a wide variety of different 2547 deployments, interactions, and methodologies. In this process, the 2548 AS can gather consent from the RO as necessitated by the access that 2549 has been requested. The AS can sometimes determine which RO needs to 2550 consent based on what has been requested by the client instance, such 2551 as a specific RS record, an identified user, or a request requiring 2552 specific access such as approval by an administrator. If the AS has 2553 a means of contacting the RO directly, it could do so without 2554 involving the client instance in its consent gathering process. For 2555 example, the AS could push a notification to a known RO and have the 2556 RO approve the pending request asynchronously. These interactions 2557 can be through an interface of the AS itself (such as a hosted web 2558 page), through another application (such as something installed on 2559 the RO's device), through a messaging fabric, or any other means. 2560 When interacting with an RO, the AS can do anything it needs to 2561 determine the authorization of the requested grant, including: 2563 * authenticate the RO, through a local account or some other means 2564 such as federated login 2566 * validate the RO through presentation of claims, attributes, or 2567 other information 2569 * prompt the RO for consent for the requested delegation 2571 * describe to the RO what information is being released, to whom, 2572 and for what purpose 2574 * provide warnings to the RO about potential attacks or negative 2575 effects of allowing the information 2577 * allow the RO to modify the client instance's requested access, 2578 including limiting or expanding that access 2580 * provide the RO with artifacts such as receipts to facilitate an 2581 audit trail of authorizations 2583 * allow the RO to deny the requested delegation 2585 The AS is also allowed to request authorization from more than one 2586 RO, if the AS deems fit. For example, a medical record might need to 2587 be released by both an attending nurse and a physician, or both 2588 owners of a bank account need to sign off on a transfer request. 2589 Alternatively, the AS could require N of M possible RO's to approve a 2590 given request in order. The AS could also determine that the end 2591 user is not the appropriate RO for a given request and reach out to 2592 the appropriate RO asynchronously. The details of determining which 2593 RO's are required for a given request are out of scope for this 2594 specification. 2596 The client instance can also indicate that it is capable of 2597 facilitating interaction with the end user, another party, or another 2598 piece of software through its interaction start (Section 2.5.1) 2599 request. In many cases, the end user is delegating their own access 2600 as RO to the client instance. Here, the AS needs to determine the 2601 identity of the end user and will often need to interact directly 2602 with the end user to determine their status as an RO and collect 2603 their consent. If the AS has determined that authorization is 2604 required and the AS can support one or more of the requested 2605 interaction start methods, the AS returns the associated interaction 2606 start responses (Section 3.3). The client instance SHOULD initiate 2607 one or more of these interaction methods (Section 4.1) in order to 2608 facilitate the granting of the request. If more than one interaction 2609 start method is available, the means by which the client chooses 2610 which methods to follow is out of scope of this specification. The 2611 client instance MUST use each interaction method once at most. 2613 After starting interaction, the client instance can then make a 2614 continuation request (Section 5) either in response to a signal 2615 indicating the finish of the interaction (Section 4.2), through 2616 polling, or through some other method defined by an extension of this 2617 specification. 2619 If the AS and client instance have not reached a state where the 2620 delegation can be granted, the AS and client instance can repeat the 2621 interaction process as long as the AS supplies the client instance 2622 with continuation information (Section 3.1) to facilitate the ongoing 2623 requests. 2625 4.1. Interaction Start Methods 2627 To initiate an interaction start method indicated by the interaction 2628 start responses (Section 3.3) from the AS, the client instance 2629 follows the steps defined by that interaction method. The actions of 2630 the client instance required for the interaction start modes defined 2631 in this specification are described in the following sections. 2633 4.1.1. Interaction at a Redirected URI 2635 When the end user is directed to an arbitrary URI through the 2636 "redirect" (Section 3.3.1) mode, the client instance facilitates 2637 opening the URI through the end user's web browser. The client 2638 instance could launch the URI through the system browser, provide a 2639 clickable link, redirect the user through HTTP response codes, or 2640 display the URI in a form the end user can use to launch such as a 2641 multidimensional barcode. With this method, it is common (though not 2642 required) for the RO to be the same party as the end-user, since the 2643 client instance has to communicate the redirection URI to the end- 2644 user. 2646 In many cases, the URI indicates a web page hosted at the AS, 2647 allowing the AS to authenticate the end user as the RO and 2648 interactively provide consent. If the URI is hosted by the AS, the 2649 AS MUST determine the grant request being referenced from the URL 2650 value itself. If the URL cannot be associated with a currently 2651 active request, the AS MUST display an error to the RO and MUST NOT 2652 attempt to redirect the RO back to any client instance even if a 2653 redirect finish method is supplied (Section 2.5.2.1). If the URI is 2654 not hosted by the AS directly, the means of communication between the 2655 AS and this URI are out of scope for this specification. 2657 The client instance MUST NOT modify the URI when launching it, in 2658 particular the client instance MUST NOT add any parameters to the 2659 URI. The URI MUST be reachable from the end user's browser, though 2660 the URI MAY be opened on a separate device from the client instance 2661 itself. The URI MUST be accessible from an HTTP GET request and MUST 2662 be protected by HTTPS or equivalent means. 2664 4.1.2. Interaction at the User Code URI 2666 When the end user is directed to enter a short code through the 2667 "user_code" (Section 3.3.3) mode, the client instance communicates 2668 the user code to the end-user and directs the end user to enter that 2669 code at an associated URI. This mode is used when the client 2670 instance is not able to facilitate launching an arbitrary URI. The 2671 associated URI could be statically configured with the client 2672 instance or communicated in the response from the AS, but the client 2673 instance communicates that URL to the end user. As a consequence, 2674 these URIs SHOULD be short. 2676 In many cases, the URI indicates a web page hosted at the AS, 2677 allowing the AS to authenticate the end user as the RO and 2678 interactively provide consent. If the URI is hosted by the AS, the 2679 AS MUST determine the grant request being referenced from the user 2680 code. If the user code cannot be associated with a currently active 2681 request, the AS MUST display an error to the RO and MUST NOT attempt 2682 to redirect the RO back to any client instance even if a redirect 2683 finish method is supplied (Section 2.5.2.1). If the interaction 2684 component at the user code URI is not hosted by the AS directly, the 2685 means of communication between the AS and this URI, including 2686 communication of the user code itself, are out of scope for this 2687 specification. 2689 When the RO enters this code at the user code URI, the AS MUST 2690 uniquely identify the pending request that the code was associated 2691 with. If the AS does not recognize the entered code, the interaction 2692 component MUST display an error to the user. If the AS detects too 2693 many unrecognized code enter attempts, the interaction component 2694 SHOULD display an error to the user and MAY take additional actions 2695 such as slowing down the input interactions. The user should be 2696 warned as such an error state is approached, if possible. 2698 The client instance MUST NOT modify the URI when launching it, in 2699 particular the client instance MUST NOT add any parameters to the 2700 URI. The user code URI MUST be reachable from the end user's 2701 browser, though the URI is usually be opened on a separate device 2702 from the client instance itself. The URI MUST be accessible from an 2703 HTTP GET request and MUST be protected by HTTPS or equivalent means. 2705 4.1.3. Interaction through an Application URI 2707 When the client instance is directed to launch an application through 2708 the "app" (Section 3.3.2) mode, the client launches the URL as 2709 appropriate to the system, such as through a deep link or custom URI 2710 scheme registered to a mobile application. The means by which the AS 2711 and the launched application communicate with each other and perform 2712 any of the required actions are out of scope for this specification. 2714 4.2. Post-Interaction Completion 2716 If an interaction "finish" (Section 3.3.4) method is associated with 2717 the current request, the AS MUST follow the appropriate method at 2718 upon completion of interaction in order to signal the client instance 2719 to continue, except for some limited error cases discussed below. If 2720 a finish method is not available, the AS SHOULD instruct the RO to 2721 return to the client instance upon completion. 2723 The AS MUST create an interaction reference and associate that 2724 reference with the current interaction and the underlying pending 2725 request. This interaction reference value MUST be sufficiently 2726 random so as not to be guessable by an attacker. The interaction 2727 reference MUST be one-time-use to prevent interception and replay 2728 attacks. 2730 The AS MUST calculate a hash value based on the client instance and 2731 AS nonces and the interaction reference, as described in 2732 Section 4.2.3. The client instance will use this value to validate 2733 the "finish" call. 2735 The AS MUST send the hash and interaction reference based on the 2736 interaction finish mode as described in the following sections. 2738 Note that the "finish" method still occurs in many error cases, such 2739 as when the RO has denied access. This pattern allows the client 2740 instance to potentially recover from the error state by modifying its 2741 request or providing additional information directly to the AS in a 2742 continuation request. The AS MUST NOT follow the "finish" method in 2743 the following circumstances: 2745 * The AS has determined that any URIs involved with the finish 2746 method are dangerous or blocked. 2748 * The AS cannot determine which ongoing grant request is being 2749 referenced. 2751 * The ongoing grant request has been cancelled or otherwise blocked. 2753 4.2.1. Completing Interaction with a Browser Redirect to the Callback 2754 URI 2756 When using the "redirect" interaction finish method (Section 3.3.4), 2757 the AS signals to the client instance that interaction is complete 2758 and the request can be continued by directing the RO (in their 2759 browser) back to the client instance's redirect URL sent in the 2760 callback request (Section 2.5.2.1). 2762 The AS secures this redirect by adding the hash and interaction 2763 reference as query parameters to the client instance's redirect URL. 2765 hash REQUIRED. The interaction hash value as described in 2766 Section 4.2.3. 2768 interact_ref REQUIRED. The interaction reference generated for this 2769 interaction. 2771 The means of directing the RO to this URL are outside the scope of 2772 this specification, but common options include redirecting the RO 2773 from a web page and launching the system browser with the target URL. 2775 https://client.example.net/return/123455\ 2776 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 2777 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 2778 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2780 When receiving the request, the client instance MUST parse the query 2781 parameters to calculate and validate the hash value as described in 2782 Section 4.2.3. If the hash validates, the client instance sends a 2783 continuation request to the AS as described in Section 5.1 using the 2784 interaction reference value received here. 2786 4.2.2. Completing Interaction with a Direct HTTP Request Callback 2788 When using the "callback" interaction mode (Section 3.3.4) with the 2789 "push" method, the AS signals to the client instance that interaction 2790 is complete and the request can be continued by sending an HTTP POST 2791 request to the client instance's callback URL sent in the callback 2792 request (Section 2.5.2.2). 2794 The entity message body is a JSON object consisting of the following 2795 two fields: 2797 hash (string) REQUIRED. The interaction hash value as described in 2798 Section 4.2.3. 2800 interact_ref (string) REQUIRED. The interaction reference generated 2801 for this interaction. 2803 POST /push/554321 HTTP/1.1 2804 Host: client.example.net 2805 Content-Type: application/json 2807 { 2808 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ 2809 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2810 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2811 } 2813 When receiving the request, the client instance MUST parse the JSON 2814 object and validate the hash value as described in Section 4.2.3. If 2815 the hash validates, the client instance sends a continuation request 2816 to the AS as described in Section 5.1 using the interaction reference 2817 value received here. 2819 4.2.3. Calculating the interaction hash 2821 The "hash" parameter in the request to the client instance's callback 2822 URL ties the front channel response to an ongoing request by using 2823 values known only to the parties involved. This security mechanism 2824 allows the client instance to protect itself against several kinds of 2825 session fixation and injection attacks. The AS MUST always provide 2826 this hash, and the client instance MUST validate the hash when 2827 received. 2829 To calculate the "hash" value, the party doing the calculation first 2830 takes the "nonce" value sent by the client instance in the 2831 interaction section of the initial request (Section 2.5.2), the AS's 2832 nonce value from the interaction finish response (Section 3.3.4), and 2833 the "interact_ref" sent to the client instance's callback URL. These 2834 three values are concatenated to each other in this order using a 2835 single newline character as a separator between the fields. There is 2836 no padding or whitespace before or after any of the lines, and no 2837 trailing newline character. 2839 VJLO6A4CAYLBXHTR0KRO 2840 MBDOFXG4Y5CVJCX821LH 2841 4IFWWIKYBC2PQ6U56NL1 2843 The party then hashes this string with the appropriate algorithm 2844 based on the "hash_method" parameter of the "callback". If the 2845 "hash_method" value is not present in the client instance's request, 2846 the algorithm defaults to "sha3". 2848 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2849 issues/56) ]] 2851 4.2.3.1. SHA3-512 2853 The "sha3" hash method consists of hashing the input string with the 2854 512-bit SHA3 algorithm. The byte array is then encoded using URL 2855 Safe Base64 with no padding. The resulting string is the hash value. 2857 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ 2858 7XHPAdJzTZMtKBsaraJ64A 2860 4.2.3.2. SHA2-512 2862 The "sha2" hash method consists of hashing the input string with the 2863 512-bit SHA2 algorithm. The byte array is then encoded using URL 2864 Safe Base64 with no padding. The resulting string is the hash value. 2866 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 2867 j84rh4mC9aE9x7HPBFcIHw 2869 5. Continuing a Grant Request 2871 While it is possible for the AS to return a Section 3 with all the 2872 client instance's requested information (including access tokens 2873 (Section 3.2) and direct user information (Section 3.4)), it's more 2874 common that the AS and the client instance will need to communicate 2875 several times over the lifetime of an access grant. This is often 2876 part of facilitating interaction (Section 4), but it could also be 2877 used to allow the AS and client instance to continue negotiating the 2878 parameters of the original grant request (Section 2). 2880 To enable this ongoing negotiation, the AS provides a continuation 2881 API to the client software. The AS returns a "continue" field in the 2882 response (Section 3.1) that contains information the client instance 2883 needs to access this API, including a URI to access as well as an 2884 access token to use during the continued requests. 2886 The access token is initially bound to the same key and method the 2887 client instance used to make the initial request. As a consequence, 2888 when the client instance makes any calls to the continuation URL, the 2889 client instance MUST present the access token as described in 2890 Section 7.2 and present proof of the client instance's key (or its 2891 most recent rotation) by signing the request as described in 2892 Section 7.3. The AS MUST validate all keys presented by the client 2893 instance or referenced in an ongoing request for each call within 2894 that request. 2896 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2897 issues/85) ]] 2899 For example, here the client instance makes a POST request to a 2900 unique URI and signs the request with detached JWS: 2902 POST /continue/KSKUOMUKM HTTP/1.1 2903 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2904 Host: server.example.com 2905 Detached-JWS: ejy0... 2907 The AS MUST be able to tell from the client instance's request which 2908 specific ongoing request is being accessed, using a combination of 2909 the continuation URL, the provided access token, and the client 2910 instance identified by the key signature. If the AS cannot determine 2911 a single active grant request to map the continuation request to, the 2912 AS MUST return an error. 2914 The ability to continue an already-started request allows the client 2915 instance to perform several important functions, including presenting 2916 additional information from interaction, modifying the initial 2917 request, and getting the current state of the request. 2919 All requests to the continuation API are protected by this bound 2920 access token. For example, here the client instance makes a POST 2921 request to a stable continuation endpoint URL with the interaction 2922 reference (Section 5.1), includes the access token, and signs with 2923 detached JWS: 2925 POST /continue HTTP/1.1 2926 Host: server.example.com 2927 Content-Type: application/json 2928 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2929 Detached-JWS: ejy0... 2931 { 2932 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2933 } 2935 If a "wait" parameter was included in the continuation response 2936 (Section 3.1), the client instance MUST NOT call the continuation URI 2937 prior to waiting the number of seconds indicated. If no "wait" 2938 period is indicated, the client instance SHOULD wait at least 5 2939 seconds. If the client instance does not respect the given wait 2940 period, the AS MUST return an error. [[ See issue #86 2941 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/86) ]] 2943 The response from the AS is a JSON object and MAY contain any of the 2944 fields described in Section 3, as described in more detail in the 2945 sections below. 2947 If the AS determines that the client instance can make a further 2948 continuation request, the AS MUST include a new "continue" response 2949 (Section 3.1). The new "continue" response MUST include a bound 2950 access token as well, and this token SHOULD be a new access token, 2951 invalidating the previous access token. If the AS does not return a 2952 new "continue" response, the client instance MUST NOT make an 2953 additional continuation request. If a client instance does so, the 2954 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 2955 wg-gnap/gnap-core-protocol/issues/87) ]] 2957 For continuation functions that require the client instance to send a 2958 message body, the body MUST be a JSON object. 2960 5.1. Continuing After a Completed Interaction 2962 When the AS responds to the client instance's "finish" method as in 2963 Section 4.2.1, this response includes an interaction reference. The 2964 client instance MUST include that value as the field "interact_ref" 2965 in a POST request to the continuation URI. 2967 POST /continue HTTP/1.1 2968 Host: server.example.com 2969 Content-Type: application/json 2970 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 2971 Detached-JWS: ejy0... 2973 { 2974 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2975 } 2977 Since the interaction reference is a one-time-use value as described 2978 in Section 4.2.1, if the client instance needs to make additional 2979 continuation calls after this request, the client instance MUST NOT 2980 include the interaction reference. If the AS detects a client 2981 instance submitting the same interaction reference multiple times, 2982 the AS MUST return an error and SHOULD invalidate the ongoing 2983 request. 2985 The Section 3 MAY contain any newly-created access tokens 2986 (Section 3.2) or newly-released subject claims (Section 3.4). The 2987 response MAY contain a new "continue" response (Section 3.1) as 2988 described above. The response SHOULD NOT contain any interaction 2989 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 2990 wg-gnap/gnap-core-protocol/issues/89) ]] 2992 For example, if the request is successful in causing the AS to issue 2993 access tokens and release opaque subject claims, the response could 2994 look like this: 2996 { 2997 "access_token": { 2998 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2999 "manage": "https://server.example.com/token/PRY5NM33O\ 3000 M4TB8N6BW7OZB8CDFONP219RP1L", 3001 }, 3002 "subject": { 3003 "sub_ids": [ { 3004 "format": "opaque", 3005 "id": "J2G8G8O4AZ" 3006 } ] 3007 } 3008 } 3010 With this example, the client instance can not make an additional 3011 continuation request because a "continue" field is not included. 3013 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3014 issues/88) ]] 3016 5.2. Continuing During Pending Interaction 3018 When the client instance does not include a "finish" parameter, the 3019 client instance will often need to poll the AS until the RO has 3020 authorized the request. To do so, the client instance makes a POST 3021 request to the continuation URI as in Section 5.1, but does not 3022 include a message body. 3024 POST /continue HTTP/1.1 3025 Host: server.example.com 3026 Content-Type: application/json 3027 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3028 Detached-JWS: ejy0... 3030 The Section 3 MAY contain any newly-created access tokens 3031 (Section 3.2) or newly-released subject claims (Section 3.4). The 3032 response MAY contain a new "continue" response (Section 3.1) as 3033 described above. If a "continue" field is included, it SHOULD 3034 include a "wait" field to facilitate a reasonable polling rate by the 3035 client instance. The response SHOULD NOT contain interaction 3036 responses (Section 3.3). 3038 For example, if the request has not yet been authorized by the RO, 3039 the AS could respond by telling the client instance to make another 3040 continuation request in the future. In this example, a new, unique 3041 access token has been issued for the call, which the client instance 3042 will use in its next continuation request. 3044 { 3045 "continue": { 3046 "access_token": { 3047 "value": "33OMUKMKSKU80UPRY5NM" 3048 }, 3049 "uri": "https://server.example.com/continue", 3050 "wait": 30 3051 } 3052 } 3054 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3055 issues/90) ]] 3057 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3058 issues/91) ]] 3060 If the request is successful in causing the AS to issue access tokens 3061 and release subject claims, the response could look like this 3062 example: 3064 { 3065 "access_token": { 3066 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3067 "manage": "https://server.example.com/token/PRY5NM33O\ 3068 M4TB8N6BW7OZB8CDFONP219RP1L", 3069 }, 3070 "subject": { 3071 "sub_ids": [ { 3072 "format": "opaque", 3073 "id": "J2G8G8O4AZ" 3074 } ] 3075 } 3076 } 3078 5.3. Modifying an Existing Request 3080 The client instance might need to modify an ongoing request, whether 3081 or not tokens have already been issued or claims have already been 3082 released. In such cases, the client instance makes an HTTP PATCH 3083 request to the continuation URI and includes any fields it needs to 3084 modify. Fields that aren't included in the request are considered 3085 unchanged from the original request. 3087 The client instance MAY include the "access_token" and "subject" 3088 fields as described in Section 2.1 and Section 2.2. Inclusion of 3089 these fields override any values in the initial request, which MAY 3090 trigger additional requirements and policies by the AS. For example, 3091 if the client instance is asking for more access, the AS could 3092 require additional interaction with the RO to gather additional 3093 consent. If the client instance is asking for more limited access, 3094 the AS could determine that sufficient authorization has been granted 3095 to the client instance and return the more limited access rights 3096 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 3097 core-protocol/issues/92) ]] 3099 The client instance MAY include the "interact" field as described in 3100 Section 2.5. Inclusion of this field indicates that the client 3101 instance is capable of driving interaction with the RO, and this 3102 field replaces any values from a previous request. The AS MAY 3103 respond to any of the interaction responses as described in 3104 Section 3.3, just like it would to a new request. 3106 The client instance MAY include the "user" field as described in 3107 Section 2.4 to present new assertions or information about the end- 3108 user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- 3109 protocol/issues/93) ]] 3111 The client instance MUST NOT include the "client" section of the 3112 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 3113 protocol/issues/94) ]] 3115 The client instance MAY include post-interaction responses such as 3116 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 3117 wg-gnap/gnap-core-protocol/issues/95) ]] 3119 Modification requests MUST NOT alter previously-issued access tokens. 3120 Instead, any access tokens issued from a continuation are considered 3121 new, separate access tokens. The AS MAY revoke existing access 3122 tokens after a modification has occurred. [[ See issue #96 3123 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 3125 If the modified request can be granted immediately by the AS, the 3126 Section 3 MAY contain any newly-created access tokens (Section 3.2) 3127 or newly-released subject claims (Section 3.4). The response MAY 3128 contain a new "continue" response (Section 3.1) as described above. 3129 If interaction can occur, the response SHOULD contain interaction 3130 responses (Section 3.3) as well. 3132 For example, a client instance initially requests a set of resources 3133 using references: 3135 POST /tx HTTP/1.1 3136 Host: server.example.com 3137 Content-Type: application/json 3138 Detached-JWS: ejy0... 3140 { 3141 "access_token": { 3142 "access": [ 3143 "read", "write" 3144 ] 3145 }, 3146 "interact": { 3147 "start": ["redirect"], 3148 "finish": { 3149 "method": "redirect", 3150 "uri": "https://client.example.net/return/123455", 3151 "nonce": "LKLTI25DK82FX4T4QFZC" 3152 } 3153 }, 3154 "client": "987YHGRT56789IOLK" 3155 } 3157 Access is granted by the RO, and a token is issued by the AS. In its 3158 final response, the AS includes a "continue" field, which includes a 3159 separate access token for accessing the continuation API: 3161 { 3162 "continue": { 3163 "access_token": { 3164 "value": "80UPRY5NM33OMUKMKSKU" 3165 }, 3166 "uri": "https://server.example.com/continue", 3167 "wait": 30 3168 }, 3169 "access_token": { 3170 "value": "RP1LT0-OS9M2P_R64TB", 3171 "access": [ 3172 "read", "write" 3173 ] 3174 } 3175 } 3177 This "continue" field allows the client instance to make an eventual 3178 continuation call. In the future, the client instance realizes that 3179 it no longer needs "write" access and therefore modifies its ongoing 3180 request, here asking for just "read" access instead of both "read" 3181 and "write" as before. 3183 PATCH /continue HTTP/1.1 3184 Host: server.example.com 3185 Content-Type: application/json 3186 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3187 Detached-JWS: ejy0... 3189 { 3190 "access_token": { 3191 "access": [ 3192 "read" 3193 ] 3194 } 3195 ... 3196 } 3198 The AS replaces the previous "access" from the first request, 3199 allowing the AS to determine if any previously-granted consent 3200 already applies. In this case, the AS would likely determine that 3201 reducing the breadth of the requested access means that new access 3202 tokens can be issued to the client instance. The AS would likely 3203 revoke previously-issued access tokens that had the greater access 3204 rights associated with them, unless they had been issued with the 3205 "durable" flag. 3207 { 3208 "continue": { 3209 "access_token": { 3210 "value": "M33OMUK80UPRY5NMKSKU" 3211 }, 3212 "uri": "https://server.example.com/continue", 3213 "wait": 30 3214 }, 3215 "access_token": { 3216 "value": "0EVKC7-2ZKwZM_6N760", 3217 "access": [ 3218 "read" 3219 ] 3220 } 3221 } 3223 For another example, the client instance initially requests read-only 3224 access but later needs to step up its access. The initial request 3225 could look like this example. 3227 POST /tx HTTP/1.1 3228 Host: server.example.com 3229 Content-Type: application/json 3230 Detached-JWS: ejy0... 3232 { 3233 "access_token": { 3234 "access": [ 3235 "read" 3236 ] 3237 }, 3238 "interact": { 3239 "start": ["redirect"], 3240 "finish": { 3241 "method": "redirect", 3242 "uri": "https://client.example.net/return/123455", 3243 "nonce": "LKLTI25DK82FX4T4QFZC" 3244 } 3245 }, 3246 "client": "987YHGRT56789IOLK" 3247 } 3249 Access is granted by the RO, and a token is issued by the AS. In its 3250 final response, the AS includes a "continue" field: 3252 { 3253 "continue": { 3254 "access_token": { 3255 "value": "80UPRY5NM33OMUKMKSKU" 3256 }, 3257 "uri": "https://server.example.com/continue", 3258 "wait": 30 3259 }, 3260 "access_token": { 3261 "value": "RP1LT0-OS9M2P_R64TB", 3262 "access": [ 3263 "read" 3264 ] 3265 } 3266 } 3268 This allows the client instance to make an eventual continuation 3269 call. The client instance later realizes that it now needs "write" 3270 access in addition to the "read" access. Since this is an expansion 3271 of what it asked for previously, the client instance also includes a 3272 new interaction section in case the AS needs to interact with the RO 3273 again to gather additional authorization. Note that the client 3274 instance's nonce and callback are different from the initial request. 3276 Since the original callback was already used in the initial exchange, 3277 and the callback is intended for one-time-use, a new one needs to be 3278 included in order to use the callback again. 3280 [[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3281 issues/97) ]] 3283 PATCH /continue HTTP/1.1 3284 Host: server.example.com 3285 Content-Type: application/json 3286 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3287 Detached-JWS: ejy0... 3289 { 3290 "access_token": { 3291 "access": [ 3292 "read", "write" 3293 ] 3294 }, 3295 "interact": { 3296 "start": ["redirect"], 3297 "finish": { 3298 "method": "redirect", 3299 "uri": "https://client.example.net/return/654321", 3300 "nonce": "K82FX4T4LKLTI25DQFZC" 3301 } 3302 } 3303 } 3305 From here, the AS can determine that the client instance is asking 3306 for more than it was previously granted, but since the client 3307 instance has also provided a mechanism to interact with the RO, the 3308 AS can use that to gather the additional consent. The protocol 3309 continues as it would with a new request. Since the old access 3310 tokens are good for a subset of the rights requested here, the AS 3311 might decide to not revoke them. However, any access tokens granted 3312 after this update process are new access tokens and do not modify the 3313 rights of existing access tokens. 3315 5.4. Canceling a Grant Request 3317 If the client instance wishes to cancel an ongoing grant request, it 3318 makes an HTTP DELETE request to the continuation URI. 3320 DELETE /continue HTTP/1.1 3321 Host: server.example.com 3322 Content-Type: application/json 3323 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3324 Detached-JWS: ejy0... 3326 If the request is successfully cancelled, the AS responds with an 3327 HTTP 202. The AS SHOULD revoke all associated access tokens. 3329 6. Token Management 3331 If an access token response includes the "manage" parameter as 3332 described in Section 3.2.1, the client instance MAY call this URL to 3333 manage the access token with any of the actions defined in the 3334 following sections. Other actions are undefined by this 3335 specification. 3337 The access token being managed acts as the access element for its own 3338 management API. The client instance MUST present proof of an 3339 appropriate key along with the access token. 3341 If the token is sender-constrained (i.e., not a bearer token), it 3342 MUST be sent with the appropriate binding for the access token 3343 (Section 7.2). 3345 If the token is a bearer token, the client instance MUST present 3346 proof of the same key identified in the initial request (Section 2.3) 3347 as described in Section 7.3. 3349 The AS MUST validate the proof and assure that it is associated with 3350 either the token itself or the client instance the token was issued 3351 to, as appropriate for the token's presentation type. 3353 6.1. Rotating the Access Token 3355 The client instance makes an HTTP POST to the token management URI, 3356 sending the access token in the appropriate header and signing the 3357 request with the appropriate key. 3359 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3360 Host: server.example.com 3361 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3362 Detached-JWS: eyj0.... 3364 The AS validates that the token presented is associated with the 3365 management URL, that the AS issued the token to the given client 3366 instance, and that the presented key is appropriate to the token. 3368 If the access token has expired, the AS SHOULD honor the rotation 3369 request to the token management URL since it is likely that the 3370 client instance is attempting to refresh the expired token. To 3371 support this, the AS MAY apply different lifetimes for the use of the 3372 token in management vs. its use at an RS. An AS MUST NOT honor a 3373 rotation request for an access token that has been revoked, either by 3374 the AS or by the client instance through the token management URI 3375 (Section 6.2). 3377 If the token is validated and the key is appropriate for the request, 3378 the AS MUST invalidate the current access token associated with this 3379 URL, if possible, and return a new access token response as described 3380 in Section 3.2.1, unless the "multi_token" flag is specified in the 3381 request. The value of the access token MUST NOT be the same as the 3382 current value of the access token used to access the management API. 3383 The response MAY include an updated access token management URL as 3384 well, and if so, the client instance MUST use this new URL to manage 3385 the new access token. [[ See issue #101 (https://github.com/ietf-wg- 3386 gnap/gnap-core-protocol/issues/101) ]] 3388 [[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core- 3389 protocol/issues/102) ]] 3390 { 3391 "access_token": { 3392 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3393 "manage": "https://server.example.com/token/PRY5NM33O\ 3394 M4TB8N6BW7OZB8CDFONP219RP1L", 3395 "access": [ 3396 { 3397 "type": "photo-api", 3398 "actions": [ 3399 "read", 3400 "write", 3401 "dolphin" 3402 ], 3403 "locations": [ 3404 "https://server.example.net/", 3405 "https://resource.local/other" 3406 ], 3407 "datatypes": [ 3408 "metadata", 3409 "images" 3410 ] 3411 }, 3412 "read", "dolphin-metadata" 3413 ] 3414 } 3415 } 3417 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3418 protocol/issues/103) ]] 3420 6.2. Revoking the Access Token 3422 If the client instance wishes to revoke the access token proactively, 3423 such as when a user indicates to the client instance that they no 3424 longer wish for it to have access or the client instance application 3425 detects that it is being uninstalled, the client instance can use the 3426 token management URI to indicate to the AS that the AS should 3427 invalidate the access token for all purposes. 3429 The client instance makes an HTTP DELETE request to the token 3430 management URI, presenting the access token and signing the request 3431 with the appropriate key. 3433 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3434 Host: server.example.com 3435 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3436 Detached-JWS: eyj0.... 3438 If the key presented is associated with the token (or the client 3439 instance, in the case of a bearer token), the AS MUST invalidate the 3440 access token, if possible, and return an HTTP 204 response code. 3442 204 No Content 3444 Though the AS MAY revoke an access token at any time for any reason, 3445 the token management function is specifically for the client 3446 instance's use. If the access token has already expired or has been 3447 revoked through other means, the AS SHOULD honor the revocation 3448 request to the token management URL as valid, since the end result is 3449 still the token not being usable. 3451 7. Securing Requests from the Client Instance 3453 In GNAP, the client instance secures its requests to the AS and RS by 3454 presenting an access token, presenting proof of a key that it 3455 possesses, or both an access token and key proof together. 3457 * When an access token is used with a key proof, this is a bound 3458 token request. This type of request is used for calls to the RS 3459 as well as the AS during negotiation. 3461 * When a key proof is used with no access token, this is a non- 3462 authorized signed request. This type of request is used for calls 3463 to the AS to initiate a negotiation. 3465 * When an access token is used with no key proof, this is a bearer 3466 token request. This type of request is used only for calls to the 3467 RS, and only with access tokens that are not bound to any key as 3468 described in Section 3.2.1. 3470 * When neither an access token nor key proof are used, this is an 3471 unsecured request. This type of request is not used in the core 3472 protocol of GNAP. 3474 7.1. Key Formats 3476 Several different places in GNAP require the presentation of key 3477 material by value. Proof of this key material MUST be bound to a 3478 request, the nature of which varies with the location in the protocol 3479 the key is used. For a key used as part of a client instance's 3480 initial request in Section 2.3, the key value is the client 3481 instance's public key, and proof of that key MUST be presented in 3482 that request. For a key used as part of an access token response in 3483 Section 3.2.1, the proof of that key MUST be used when presenting the 3484 access token. 3486 A key presented by value MUST be a public key in at least one 3487 supported format. If a key is sent in multiple formats, all the key 3488 format values MUST be equivalent. Note that while most formats 3489 present the full value of the public key, some formats present a 3490 value cryptographically derived from the public key. 3492 proof (string) The form of proof that the client instance will use 3493 when presenting the key. The valid values of this field and the 3494 processing requirements for each are detailed in Section 7.3. The 3495 "proof" field is REQUIRED. 3497 jwk (object) The public key and its properties represented as a JSON 3498 Web Key [RFC7517]. A JWK MUST contain the "alg" (Algorithm) and 3499 "kid" (Key ID) parameters. The "alg" parameter MUST NOT be 3500 "none". The "x5c" (X.509 Certificate Chain) parameter MAY be used 3501 to provide the X.509 representation of the provided public key. 3503 cert (string) PEM serialized value of the certificate used to sign 3504 the request, with optional internal whitespace per [RFC7468]. The 3505 PEM header and footer are optionally removed. 3507 cert#S256 (string) The certificate thumbprint calculated as per 3508 OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this 3509 format does not include the full public key. 3511 Additional key formats are defined in a registry TBD (Section 11). 3513 This non-normative example shows a single key presented in multiple 3514 formats. This key is intended to be used with the detached JWS 3515 (Section 7.3.1) proofing mechanism, as indicated by the "proof" 3516 field. 3518 "key": { 3519 "proof": "jwsd", 3520 "jwk": { 3521 "kty": "RSA", 3522 "e": "AQAB", 3523 "kid": "xyz-1", 3524 "alg": "RS256", 3525 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 3526 }, 3527 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 3528 } 3530 7.1.1. Key References 3532 Keys in GNAP can also be passed by reference such that the party 3533 receiving the reference will be able to determine the appropriate 3534 keying material for use in that part of the protocol. 3536 "key": "S-P4XJQ_RYJCRTSU1.63N3E" 3538 Keys referenced in this manner MAY be shared symmetric keys. The key 3539 reference MUST NOT contain any unencrypted private or shared 3540 symmetric key information. 3542 Keys referenced in this manner MUST be bound to a single proofing 3543 mechanism. 3545 The means of dereferencing this value are out of scope for this 3546 specification. 3548 7.2. Presenting Access Tokens 3550 The method the client instance uses to send an access token depends 3551 on whether the token is bound to a key, and if so which proofing 3552 method is associated with the key. This information is conveyed in 3553 the "bound" and "key" parameters in the single (Section 3.2.1) and 3554 multiple access tokens (Section 3.2.2) responses. 3556 If the "bound" value is the boolean "true" and the "key" is absent, 3557 the access token MUST be sent using the same key and proofing 3558 mechanism that the client instance used in its initial request (or 3559 its most recent rotation). 3561 If the "bound" value is the boolean "true" and the "key" value is an 3562 object as described in Section 7.1, the access token MUST be sent 3563 using the key and proofing mechanism defined by the value of the 3564 "proof" field within the key object. 3566 The access token MUST be sent using the HTTP "Authorization" request 3567 header field and the "GNAP" authorization scheme along with a key 3568 proof as described in Section 7.3 for the key bound to the access 3569 token. For example, a "jwsd"-bound access token is sent as follows: 3571 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3572 Detached-JWS: eyj0.... 3574 If the "bound" value is the boolean "false", the access token is a 3575 bearer token that MUST be sent using the "Authorization Request 3576 Header Field" method defined in [RFC6750]. 3578 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3580 The "Form-Encoded Body Parameter" and "URI Query Parameter" methods 3581 of [RFC6750] MUST NOT be used. 3583 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3584 protocol/issues/104) ]] 3586 The client software MUST reject as an error a situation where the 3587 "bound" value is the boolean "false" and the "key" is present. 3589 7.3. Proving Possession of a Key with a Request 3591 Any keys presented by the client instance to the AS or RS MUST be 3592 validated as part of the request in which they are presented. The 3593 type of binding used is indicated by the proof parameter of the key 3594 object in Section 7.1. Values defined by this specification are as 3595 follows: 3597 jwsd A detached JWS signature header 3599 jws Attached JWS payload 3601 mtls Mutual TLS certificate verification 3603 dpop OAuth Demonstration of Proof-of-Possession key proof header 3605 httpsig HTTP Signing signature header 3607 oauthpop OAuth PoP key proof authentication header 3609 Additional proofing methods are defined by a registry TBD 3610 (Section 11). 3612 All key binding methods used by this specification MUST cover all 3613 relevant portions of the request, including anything that would 3614 change the nature of the request, to allow for secure validation of 3615 the request. Relevant aspects include the URI being called, the HTTP 3616 method being used, any relevant HTTP headers and values, and the HTTP 3617 message body itself. The verifier of the signed message MUST 3618 validate all components of the signed message to ensure that nothing 3619 has been tampered with or substituted in a way that would change the 3620 nature of the request. Key binding method definitions SHOULD 3621 enumerate how these requirements are fulfilled. 3623 When a key proofing mechanism is bound to an access token, the key 3624 being presented MUST be the key associated with the access token and 3625 the access token MUST be covered by the signature method of the 3626 proofing mechanism. 3628 The key binding methods in this section MAY be used by other 3629 components making calls as part of GNAP, such as the extensions 3630 allowing the RS to make calls to the AS defined in {{I-D.ietf-gnap- 3631 resource-servers}}. To facilitate this extended use, the sections 3632 below are defined in generic terms of the "sender" and "verifier" of 3633 the HTTP message. In the core functions of GNAP, the "sender" is the 3634 client instance and the "verifier" is the AS or RS, as appropriate. 3636 When used for delegation in GNAP, these key binding mechanisms allow 3637 the AS to ensure that the keys presented by the client instance in 3638 the initial request are in control of the party calling any follow-up 3639 or continuation requests. To facilitate this requirement, the 3640 continuation response (Section 3.1) includes an access token bound to 3641 the client instance's key (Section 2.3), and that key (or its most 3642 recent rotation) MUST be proved in all continuation requests 3643 Section 5. Token management requests Section 6 are similarly bound 3644 to either the access token's own key or, in the case of bearer 3645 tokens, the client instance's key. 3647 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 3648 protocol/issues/105) ]] 3650 In the following sections, unless otherwise noted, the "RS256" JOSE 3651 Signature Algorithm is applied using the following RSA key (presented 3652 here in JWK format): 3654 { 3655 "kid": "gnap-rsa", 3656 "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ 3657 i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ 3658 eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", 3659 "kty": "RSA", 3660 "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ 3661 LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ 3662 JXMxOLyPjzuVgiTOCBIvLD6-8-mvFjXZk_eefD0at6mQ5qV3U1jZt88", 3663 "d": "FHlhdTF0ozTliDxMBffT6aJVKZKmbbFJOVNten9c3lXKB3ux3NAb_D2dB\ 3664 7inp9EV23oWrDspFtvCvD9dZrXgRKMHofkEpo_SSvBZfgtH-OTkbY_TqtPF\ 3665 FLPKAw0JX5cFPnn4Q2xE4n-dQ7tpRCKl59vZLHBrHShr90zqzFp0AKXU5fj\ 3666 b1gC9LPwsFA2Fd7KXmI1drQQEVq9R-o18Pnn4BGQNQNjO_VkcJTiBmEIVT_\ 3667 KJRPdpVJAmbgnYWafL_hAfeb_dK8p85yurEVF8nCK5oO3EPrqB7IL4UqaEn\ 3668 5Sl3u0j8x5or-xrrAoNz-gdOv7ONfZY6NFoa-3f8q9wBAHUuQ", 3669 "e": "AQAB", 3670 "qi": "ogpNEkDKg22Rj9cDV_-PJBZaXMk66Fp557RT1tafIuqJRHEufSOYnsto\ 3671 bWPJ0gHxv1gVJw3gm-zYvV-wTMNgr2wVsBSezSJjPSjxWZtmT2z68W1DuvK\ 3672 kZy15vz7Jd85hmDlriGcXNCoFEUsGLWkpHH9RwPIzguUHWmTt8y0oXyI", 3673 "dp": "dvCKGI2G7RLh3WyjoJ_Dr6hZ3LhXweB3YcY3qdD9BnxZ71mrLiMQg4c_\ 3674 EBnwqCETN_5sStn2cRc2JXnvLP3G8t7IFKHTT_i_TSTacJ7uT04MSa053Y3\ 3675 RfwbvLjRNPR0UKAE3ZxROUoIaVNuU_6-QMf8-2ilUv2GIOrCN87gP_Vk", 3676 "alg": "RS256", 3677 "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ 3678 M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ 3679 Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", 3680 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ 3681 YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ 3682 jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ 3683 e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ 3684 bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ 3685 zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3686 } 3688 7.3.1. Detached JWS 3690 This method is indicated by "jwsd" in the "proof" field. A JWS 3691 [RFC7515] object is created as follows: 3693 To protect the request, the JOSE header of the signature contains the 3694 following parameters: 3696 kid (string) The key identifier. RECOMMENDED. If the key is 3697 presented in JWK format, this MUST be the value of the "kid" field 3698 of the key. 3700 alg (string) The algorithm used to sign the request. REQUIRED. 3702 MUST be appropriate to the key presented. If the key is presented 3703 as a JWK, this MUST be equal to the "alg" parameter of the key. 3704 MUST NOT be "none". 3706 typ (string) The type header, value "gnap-binding+jwsd". REQUIRED 3708 htm (string) The HTTP Method used to make this request, as an 3709 uppercase ASCII string. REQUIRED 3711 uri (string) The HTTP URI used for this request, including all path 3712 and query components and no fragment component. REQUIRED 3714 created (integer) A timestamp of when the signature was created, in 3715 integer seconds since UNIX Epoch 3717 ath (string) When a request is bound to an access token, the access 3718 token hash value. The value MUST be the result of Base64url 3719 encoding (with no padding) the SHA-256 digest of the ASCII 3720 encoding of the associated access token's value. REQUIRED if the 3721 request protects an access token. 3723 If the HTTP request has a message body, such as an HTTP POST or PUT 3724 method, the payload of the JWS object is the Base64url encoding 3725 (without padding) of the SHA256 digest of the bytes of the body. If 3726 the request being made does not have a message body, such as an HTTP 3727 GET, OPTIONS, or DELETE method, the JWS signature is calculated over 3728 an empty payload. 3730 The client instance presents the signed object in compact form 3731 [RFC7515] in the Detached-JWS HTTP Header field. 3733 In this example, the JOSE Header contains the following parameters: 3735 { 3736 "alg": "RS256", 3737 "kid": "gnap-rsa", 3738 "uri": "https://server.example.com/gnap", 3739 "htm": "POST", 3740 "typ": "gnap-binding+jwsd", 3741 "created": 1618884475 3742 } 3744 The request body is the following JSON object: 3746 { 3747 "access_token": { 3748 "access": [ 3749 "dolphin-metadata" 3750 ] 3751 }, 3752 "interact": { 3753 "start": ["redirect"], 3754 "finish": { 3755 "method": "redirect", 3756 "uri": "https://client.foo/callback", 3757 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3758 } 3759 }, 3760 "client": { 3761 "proof": "jwsd", 3762 "key": { 3763 "jwk": { 3764 "kid": "gnap-rsa", 3765 "kty": "RSA", 3766 "e": "AQAB", 3767 "alg": "RS256", 3768 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3769 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3770 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3771 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3772 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3773 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3774 } 3775 } 3776 "display": { 3777 "name": "My Client Display Name", 3778 "uri": "https://client.foo/" 3779 }, 3780 } 3781 } 3783 This is hashed to the following Base64 encoded value: 3785 PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc 3787 This leads to the following full HTTP request message: 3789 POST /gnap HTTP/1.1 3790 Host: server.example.com 3791 Content-Type: application/json 3792 Content-Length: 983 3793 Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ 3794 SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ 3795 NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ 3796 ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ 3797 TZA2h5YeXUoi5F2Q2iToC0Tc4drYFOSHIX68knd68RUA7yHqCVP-ZQEd6aL32H69e\ 3798 9zuMiw6O_s4TBKB3vDOvwrhYtDH6fX2hP70cQoO-47OwbqP-ifkrvI3hVgMX9TfjV\ 3799 eKNwnhoNnw3vbu7SNKeqJEbbwZfpESaGepS52xNBlDNMYBQQXxM9OqKJaXffzLFEl\ 3800 -Xe0UnfolVtBraz3aPrPy1C6a4uT7wLda3PaTOVtgysxzii3oJWpuz0WP5kRujzDF\ 3801 wX_EOzW0jsjCSkL-PXaKSpZgEjNjKDMg9irSxUISt1C1T6q3SzRgfuQ 3803 { 3804 "access_token": { 3805 "access": [ 3806 "dolphin-metadata" 3807 ] 3808 }, 3809 "interact": { 3810 "start": ["redirect"], 3811 "finish": { 3812 "method": "redirect", 3813 "uri": "https://client.foo/callback", 3814 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3815 } 3816 }, 3817 "client": { 3818 "proof": "jwsd", 3819 "key": { 3820 "jwk": { 3821 "kid": "gnap-rsa", 3822 "kty": "RSA", 3823 "e": "AQAB", 3824 "alg": "RS256", 3825 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3826 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3827 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3828 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3829 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3830 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3831 } 3832 } 3833 "display": { 3834 "name": "My Client Display Name", 3835 "uri": "https://client.foo/" 3837 }, 3838 } 3839 } 3841 When the verifier receives the Detached-JWS header, it MUST parse and 3842 validate the JWS object. The signature MUST be validated against the 3843 expected key of the signer. All required fields MUST be present and 3844 their values MUST be valid. If the HTTP message request contains a 3845 body, the verifier MUST calculate the hash of body just as the signer 3846 does, with no normalization or transformation of the request. 3848 7.3.2. Attached JWS 3850 This method is indicated by "jws" in the "proof" field. A JWS 3851 [RFC7515] object is created as follows: 3853 The JOSE header MUST contain the "kid" parameter of the key bound to 3854 this client instance for this request. The "alg" parameter MUST be 3855 set to a value appropriate for the key identified by kid and MUST NOT 3856 be "none". 3858 To protect the request, the JWS header MUST contain the following 3859 additional parameters. 3861 typ (string) The type header, value "gnap-binding+jws". 3863 htm (string) The HTTP Method used to make this request, as an 3864 uppercase ASCII string. 3866 uri (string) The HTTP URI used for this request, including all path 3867 and query components and no fragment component. 3869 created (integer) A timestamp of when the signature was created, in 3870 integer seconds since UNIX Epoch 3872 ath (string) When a request is bound to an access token, the access 3873 token hash value. The value MUST be the result of Base64url 3874 encoding (with no padding) the SHA-256 digest of the ASCII 3875 encoding of the associated access token's value. 3877 If the HTTP request has a message body, such as an HTTP POST or PUT 3878 method, the payload of the JWS object is the JSON serialized body of 3879 the request, and the object is signed according to JWS and serialized 3880 into compact form [RFC7515]. The client instance presents the JWS as 3881 the body of the request along with a content type of "application/ 3882 jose". The AS MUST extract the payload of the JWS and treat it as 3883 the request body for further processing. 3885 If the request being made does not have a message body, such as an 3886 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 3887 over an empty payload and passed in the "Detached-JWS" header as 3888 described in Section 7.3.1. 3890 In this example, the JOSE header contains the following parameters: 3892 { 3893 "alg": "RS256", 3894 "kid": "gnap-rsa", 3895 "uri": "https://server.example.com/gnap", 3896 "htm": "POST", 3897 "typ": "gnap-binding+jwsd", 3898 "created": 1618884475 3899 } 3901 The request body, used as the JWS Payload, is the following JSON 3902 object: 3904 { 3905 "access_token": { 3906 "access": [ 3907 "dolphin-metadata" 3908 ] 3909 }, 3910 "interact": { 3911 "start": ["redirect"], 3912 "finish": { 3913 "method": "redirect", 3914 "uri": "https://client.foo/callback", 3915 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3916 } 3917 }, 3918 "client": { 3919 "proof": "jws", 3920 "key": { 3921 "jwk": { 3922 "kid": "gnap-rsa", 3923 "kty": "RSA", 3924 "e": "AQAB", 3925 "alg": "RS256", 3926 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3927 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3928 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3929 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3930 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3931 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3932 } 3933 } 3934 "display": { 3935 "name": "My Client Display Name", 3936 "uri": "https://client.foo/" 3937 }, 3938 }, 3939 "subject": { 3940 "formats": ["iss_sub", "opaque"] 3941 } 3942 } 3944 This leads to the following full HTTP request message: 3946 POST /gnap HTTP/1.1 3947 Host: server.example.com 3948 Content-Type: application/jose 3949 Content-Length: 1047 3951 eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ 3952 raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ 3953 R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ 3954 ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\ 3955 0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\ 3956 Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\ 3957 CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\ 3958 cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\ 3959 KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\ 3960 ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\ 3961 ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\ 3962 Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\ 3963 gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\ 3964 5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\ 3965 nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\ 3966 akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\ 3967 xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\ 3968 BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\ 3969 XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\ 3970 YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ 3971 gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ 3972 FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ 3973 AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ 3974 c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ 3975 vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ 3976 u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ 3977 LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ 3978 PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ 3979 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 3981 [[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core- 3982 protocol/issues/109) ]] 3984 When the verifier receives an attached JWS request, it MUST parse and 3985 validate the JWS object. The signature MUST be validated against the 3986 expected key of the signer. All required fields MUST be present and 3987 their values MUST be valid. If the HTTP message request contains a 3988 body, the verifier MUST decode the payload of the JWS object and 3989 treat this as the HTTP message body. 3991 7.3.3. Mutual TLS 3993 This method is indicated by "mtls" in the "proof" field. The signer 3994 presents its TLS client certificate during TLS negotiation with the 3995 verifier. 3997 In this example, the certificate is communicated to the application 3998 through the "Client-Cert" header from a TLS reverse proxy, leading to 3999 the following full HTTP request message: 4001 POST /gnap HTTP/1.1 4002 Host: server.example.com 4003 Content-Type: application/jose 4004 Content-Length: 1567 4005 Client-Cert: \ 4006 MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM \ 4007 K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN \ 4008 MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq \ 4009 c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG \ 4010 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB \ 4011 kI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8I \ 4012 kZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn11V2vxE4 \ 4013 1hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo+ \ 4014 uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKXfGhi3k \ 4015 OzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0GCSqG \ 4016 SIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/XsWfCE \ 4017 wHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5NH9 \ 4018 W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeCgu \ 4019 NMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHlU \ 4020 fn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv \ 4021 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx 4023 { 4024 "access_token": { 4025 "access": [ 4026 "dolphin-metadata" 4027 ] 4028 }, 4029 "interact": { 4030 "start": ["redirect"], 4031 "finish": { 4032 "method": "redirect", 4033 "uri": "https://client.foo/callback", 4034 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4035 } 4036 }, 4037 "client": { 4038 "proof": "jws", 4039 "key": { 4040 "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ 4041 YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ 4042 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 4043 DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ 4044 jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ 4045 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 4046 KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ 4047 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 4048 z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ 4049 fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ 4050 GCSqGSIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/Xs\ 4051 WfCEwHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5\ 4052 NH9W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeC\ 4053 guNMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHl\ 4054 Ufn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4055 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx" 4056 } 4057 "display": { 4058 "name": "My Client Display Name", 4059 "uri": "https://client.foo/" 4060 }, 4061 }, 4062 "subject": { 4063 "formats": ["iss_sub", "opaque"] 4064 } 4065 } 4067 The verifier compares the TLS client certificate presented during 4068 mutual TLS negotiation to the expected key of the signer. Since the 4069 TLS connection covers the entire message, there are no additional 4070 requirements to check. 4072 Note that in many instances, the verifier will not do a full 4073 certificate chain validation of the presented TLS client certificate, 4074 as the means of trust for this certificate could be in something 4075 other than a PKI system, such as a static registration or trust-on- 4076 first-use. 4078 [[ See issue #110 (https://github.com/ietf-wg-gnap/gnap-core- 4079 protocol/issues/110) ]] 4081 7.3.4. Demonstration of Proof-of-Possession (DPoP) 4083 This method is indicated by "dpop" in the "proof" field. The signer 4084 creates a Demonstration of Proof-of-Possession signature header as 4085 described in [I-D.ietf-oauth-dpop] section 2. In addition, this 4086 specification defines the following fields to be added to the DPoP 4087 payload: 4089 htd (string) Digest of the request body as the value of the Digest 4090 header defined in [RFC3230]. When a request contains a message 4091 body, such as a POST or PUT request, this field is REQUIRED. 4093 In this example, the request body is the following JSON object: ~~~ { 4094 "access_token": { "access": [ "dolphin-metadata" ] }, "interact": { 4095 "start": ["redirect"], "finish": { "method": "redirect", "uri": 4096 "https://client.foo/callback", "nonce": "VJLO6A4CAYLBXHTR0KRO" } }, 4097 "client": { "proof": "dpop", "key": { "jwk": { "kid": "gnap-rsa", 4098 "kty": "RSA", "e": "AQAB", "alg": "RS256", "n": "hYOJ- 4099 XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4100 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4101 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4102 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4103 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4104 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" } } "display": { "name": "My 4105 Client Display Name", "uri": "https://client.foo/" }, } } ~~~ 4107 The JOSE header contains the following parameters, including the 4108 public key: 4110 { 4111 "alg": "RS256", 4112 "typ": "dpop+jwt", 4113 "jwk": { 4114 "kid": "gnap-rsa", 4115 "kty": "RSA", 4116 "e": "AQAB", 4117 "alg": "RS256", 4118 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHs\ 4119 FzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYXjH\ 4120 pwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jRETdd\ 4121 zsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_3UgV\ 4122 p7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyEN7aL\ 4123 0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4124 } 4125 } 4127 The JWS Payload contains the following JWT claims, including a hash 4128 of the body: 4130 { 4131 "htu": "https://server.example.com/gnap", 4132 "htm": "POST", 4133 "iat": 1618884475, 4134 "jti": "HjoHrjgm2yB4x7jA5yyG", 4135 "htd": "SHA-256=tnPQ2GXm8r/rTTKdbQ8pc7EjiFFPy1ExSX6OZVG3JVI=" 4136 } 4138 This results in the following full HTTP message request: 4140 POST /gnap HTTP/1.1 4141 Host: server.example.com 4142 Content-Type: application/json 4143 Content-Length: 983 4144 DPoP: eyJhbGciOiJSUzI1NiIsImp3ayI6eyJhbGciOiJSUzI1NiIsImUiOiJBUUFCI\ 4145 iwia2lkIjoiZ25hcC1yc2EiLCJrdHkiOiJSU0EiLCJuIjoiaFlPSi1YT0tJU2RNTV\ 4146 Nobl9HNFc5bTIwbVQwVld0UUJzbUJCa0kyY21SdDRBaThCZllkSHNGekF0WUtPanB\ 4147 CUjFScEtwSm1WS3hJR055MGc2WjNhZDJYWXNoOEtvd2x5Vnk4SWtaOE5Nd1NyY1VJ\ 4148 QlpHWVhqSHB3anp2Zkd2WEhfNUtKbG5SM191UlVwNFo0VWprMmJDYUtlZ0RuMTFWM\ 4149 nZ4RTQxaHFhUFVuaFJaeGUwalJFVGRkenNFM211MVNLOGRUQ1JPandVbDE0bVVObz\ 4150 hpVHJUbTRuMHFEYWR6OEJrUG8tdXY0QkMwYnVuUzBLM2JBXzNVZ1ZwN3pCbFFGb0Z\ 4151 uTFRPMnVXcF9tdUxFV0dsNjdnQnE5TU8zYnJLWGZHaGkza096eXd6d1BUdXEtY1ZR\ 4152 RHlFTjdhTDBTeENiM0hjNElkcURhTWc4cUhVeU9icFBpdERRIn0sInR5cCI6ImRwb\ 4153 3Arand0In0.eyJodHUiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbS9nbmFwIi\ 4154 wiaHRtIjoiUE9TVCIsImlhdCI6MTYxODg4NDQ3NSwianRpIjoiSGpvSHJqZ20yeUI\ 4155 0eDdqQTV5eUciLCJodGQiOiJTSEEtMjU2PXRuUFEyR1htOHIvclRUS2RiUThwYzdF\ 4156 amlGRlB5MUV4U1g2T1pWRzNKVkk9In0.HLRh7n-3uwnSGCBGbSFitNCxgmJnpp6hs\ 4157 sF8o_u2Xbuzu3pyR4v8SJVP17tjqxuySf91lmC1gjJeK4pXvWOtfeWGuDjD7nr6aw\ 4158 pBOtiQXeBtoqiiK2ByBZO-mhccJeNkTkRfxGDtU0iJo6iarWjRgQOsPbt69FIwTP4\ 4159 Abovwv7yBCthQs3TMsBtb8-l4Lu30wNLwXEWcB-o8nFNpT4zgV9ETGoCOcBFwBjjt\ 4160 0khsCarleTBsOZ2zUuFwZMWi_bQYfd-M0pahWYro9Mdy3Fts-aUqZjS2LwHHNWvjw\ 4161 rTzz6icCHwnr9dm1Ls6orbM7xMzvHAOA5TZW39yFg_Xr5PNYg 4163 { 4164 "access_token": { 4165 "access": [ 4166 "dolphin-metadata" 4167 ] 4168 }, 4169 "interact": { 4170 "start": ["redirect"], 4171 "finish": { 4172 "method": "redirect", 4173 "uri": "https://client.foo/callback", 4174 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4175 } 4176 }, 4177 "client": { 4178 "proof": "dpop", 4179 "key": { 4180 "jwk": { 4181 "kid": "gnap-rsa", 4182 "kty": "RSA", 4183 "e": "AQAB", 4184 "alg": "RS256", 4185 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4186 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4187 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4188 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4189 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4190 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4191 } 4192 } 4193 "display": { 4194 "name": "My Client Display Name", 4195 "uri": "https://client.foo/" 4196 }, 4197 } 4198 } 4200 The verifier MUST parse and validate the DPoP proof header as defined 4201 in [I-D.ietf-oauth-dpop]. If the HTTP message request includes a 4202 message body, the verifier MUST calculate the digest of the body and 4203 compare it to the "htd" value. The verifier MUST ensure the key 4204 presented in the DPoP proof header is the same as the expected key of 4205 the signer. 4207 7.3.5. HTTP Message Signing 4209 This method is indicated by "httpsig" in the "proof" field. The 4210 sender creates an HTTP Message Signature as described in 4211 [I-D.ietf-httpbis-message-signatures]. 4213 The covered content of the signature MUST include the following: 4215 @request-target: the target of the HTTP request 4217 digest: The Digest header as defined in [RFC3230]. When the request 4218 message has a body, the signer MUST calculate this header value 4219 and the verifier MUST validate this header. 4221 When the request is bound to an access token, the covered content 4222 MUST also include: 4224 authorization: The Authorization header used to present the access 4225 token as discussed in Section 7.2. 4227 Other covered content MAY also be included. 4229 If the signer's key presented is a JWK, the "keyid" parameter of the 4230 signature MUST be set to the "kid" value of the JWK, the signing 4231 algorithm used MUST be the JWS algorithm denoted by the key's "alg" 4232 field, and the explicit "alg" signature parameter MUST NOT be 4233 included. 4235 In this example, the message body is the following JSON object: 4237 { 4238 "access_token": { 4239 "access": [ 4240 "dolphin-metadata" 4241 ] 4242 }, 4243 "interact": { 4244 "start": ["redirect"], 4245 "finish": { 4246 "method": "redirect", 4247 "uri": "https://client.foo/callback", 4248 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4249 } 4250 }, 4251 "client": { 4252 "proof": "httpsig", 4253 "key": { 4254 "jwk": { 4255 "kid": "gnap-rsa", 4256 "kty": "RSA", 4257 "e": "AQAB", 4258 "alg": "RS256", 4259 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4260 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4261 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4262 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4263 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4264 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4265 } 4266 } 4267 "display": { 4268 "name": "My Client Display Name", 4269 "uri": "https://client.foo/" 4270 }, 4271 } 4272 } 4273 This body is hashed for the Digest header using SHA-256 into the 4274 following encoded value: 4276 SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 4278 The HTTP message signature input string is calculated to be the 4279 following: 4281 "@request-target": post /gnap 4282 "host": server.example.com 4283 "content-type": application/json 4284 "digest": SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 4285 "content-length": 986 4286 "@signature-params": ("@request-target" "host" "content-type" \ 4287 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 4289 This leads to the following full HTTP message request: 4291 POST /gnap HTTP/1.1 4292 Host: server.example.com 4293 Content-Type: application/json 4294 Content-Length: 986 4295 Digest: SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 4296 Signature-Input: sig1=("@request-target" "host" "content-type" \ 4297 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 4298 Signature: \ 4299 sig1=:axj8FLOvEWBcwh+Xk6VTTKXxqo4XNygleTDJ8h3ZJfi1sSmWrRtyo9RG/dc\ 4300 miZmdszRjWbg+/ixVZpA4BL3AOwEOxxtmHAXNB8uJ0I3tfbs6Suyk4sEo8zPr+MJq\ 4301 MjxdJEUgAQAy2AH+wg5a7CKq4IdLTulFK9njUIeG7MygHumeiumM3DbDQAHgF46dV\ 4302 q5UC6KJnqhGM1rFC128jd2D0sgWKCUgKGCHtfR159zfKWcEO9krsLoOnCdTzm1UyD\ 4303 DMjkIjqeN/1j8PdMJaRAwV4On079O0DVu6bl1jVtkzo/e/ZmwPr/X436V4xiw/hZt\ 4304 w4sfNsSbmsT0+UAQ20X/xaw==: 4306 { 4307 "access_token": { 4308 "access": [ 4309 "dolphin-metadata" 4310 ] 4311 }, 4312 "interact": { 4313 "start": ["redirect"], 4314 "finish": { 4315 "method": "redirect", 4316 "uri": "https://client.foo/callback", 4317 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4318 } 4319 }, 4320 "client": { 4321 "proof": "httpsig", 4322 "key": { 4323 "jwk": { 4324 "kid": "gnap-rsa", 4325 "kty": "RSA", 4326 "e": "AQAB", 4327 "alg": "RS256", 4328 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4329 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4330 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4331 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4332 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4333 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4334 } 4335 } 4336 "display": { 4337 "name": "My Client Display Name", 4338 "uri": "https://client.foo/" 4339 }, 4340 } 4341 } 4343 If the HTTP Message includes a message body, the verifier MUST 4344 calculate and verify the value of the "Digest" header. The verifier 4345 MUST ensure that the signature includes all required covered content. 4346 The verifier MUST validate the signature against the expected key of 4347 the signer. 4349 7.3.6. OAuth Proof of Possession (PoP) 4351 This method is indicated by "oauthpop" in the "proof" field. The 4352 signer creates an HTTP Authorization PoP header as described in 4353 [I-D.ietf-oauth-signed-http-request] section 4, with the following 4354 additional requirements: 4356 * The "at" (access token) field MUST be omitted unless this method 4357 is being used in conjunction with an access token as in 4358 Section 7.2. [[ See issue #112 (https://github.com/ietf-wg-gnap/ 4359 gnap-core-protocol/issues/112) ]] 4361 * The "b" (body hash) field MUST be calculated and included, if the 4362 message includes an entity body (such as a PUT or PATCH request). 4364 * All components of the URL MUST be calculated and included, 4365 including query parameters "q", path "p", and host "u". 4367 * The "m" (method) field MUST be included 4368 In this example, the request message body is the following JSON 4369 object 4371 { 4372 "access_token": { 4373 "access": [ 4374 "dolphin-metadata" 4375 ] 4376 }, 4377 "interact": { 4378 "start": ["redirect"], 4379 "finish": { 4380 "method": "redirect", 4381 "uri": "https://client.foo/callback", 4382 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4383 } 4384 }, 4385 "client": { 4386 "proof": "oauthpop", 4387 "key": { 4388 "jwk": { 4389 "kid": "gnap-rsa", 4390 "kty": "RSA", 4391 "e": "AQAB", 4392 "alg": "RS256", 4393 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4394 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4395 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4396 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4397 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4398 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4399 } 4400 } 4401 "display": { 4402 "name": "My Client Display Name", 4403 "uri": "https://client.foo/" 4404 }, 4405 } 4406 } 4408 The JOSE header for the PoP token is the following: 4410 { 4411 "alg": "RS256", 4412 "kid": "gnap-rsa" 4413 } 4414 After calculating the hashes for the body, headers, and URL 4415 components, the JWS Payload is the following: 4417 { 4418 "u": "server.example.com", 4419 "p": "/gnap", 4420 "m": "POST", 4421 "ts": 1618884475, 4422 "b": "sCvbP9VqOcq4LHkVDcayon2MoT4xPGc49TEnqsr6WYE", 4423 "h": [ 4424 [ 4425 "content-type", 4426 "content-length" 4427 ], 4428 "EJit2-669uk8JUzLJbidMFRkATuZOimvCOieXPjtEmU" 4429 ] 4430 } 4432 This leads to the following HTTP message request: 4434 POST /gnap HTTP/1.1 4435 Host: server.example.com 4436 Content-Type: application/json 4437 Content-Length: 987 4438 PoP: eyJhbGciOiJSUzI1NiIsImtpZCI6ImduYXAtcnNhIn0.eyJ1Ijoic2VydmVyLm\ 4439 V4YW1wbGUuY29tIiwicCI6Ii9nbmFwIiwibSI6IlBPU1QiLCJ0cyI6MTYxODg4NDQ\ 4440 3NSwiYiI6InNDdmJQOVZxT2NxNExIa1ZEY2F5b24yTW9UNHhQR2M0OVRFbnFzcjZX\ 4441 WUUiLCJoIjpbWyJjb250ZW50LXR5cGUiLCJjb250ZW50LWxlbmd0aCJdLCJFSml0M\ 4442 i02Njl1azhKVXpMSmJpZE1GUmtBVHVaT2ltdkNPaWVYUGp0RW1VIl19.doLbW-VA7\ 4443 HnyeyEbl4qmcPUkiQrXIG53oSZLGrUHhs7CL9X9kd_-1j8lxyT7tWJLtjoIgDtVVn\ 4444 PN69xP-Vs9-Cx5uV4VfLKRO7O9GmdGUOXx9eP53Q4hf8UPMrfbyAEeluznajC21o9\ 4445 AriBDMyjmV4A4JkZn3A7v72zE0z1CQfqUsdfomeB_SmFlMhcsO8KsT1vG6iOmuE0x\ 4446 3rGjJvyohNUQvkzWvaP37nLTZol8VFWinlXGv-4cOx3YWgZUn_RNk7cH6ALHlzgnl\ 4447 8t1YhA14AFdVmCGaeJMDKmb5Jt7g0UnOp1BYR9j1DeUP64RQU6lH_8A1MMIc5iBwD\ 4448 yx433wxQ 4450 { 4451 "access_token": { 4452 "access": [ 4453 "dolphin-metadata" 4454 ] 4455 }, 4456 "interact": { 4457 "start": ["redirect"], 4458 "finish": { 4459 "method": "redirect", 4460 "uri": "https://client.foo/callback", 4461 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4462 } 4463 }, 4464 "client": { 4465 "proof": "oauthpop", 4466 "key": { 4467 "jwk": { 4468 "kid": "gnap-rsa", 4469 "kty": "RSA", 4470 "e": "AQAB", 4471 "alg": "RS256", 4472 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4473 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4474 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4475 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4476 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4477 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4478 } 4479 } 4480 "display": { 4481 "name": "My Client Display Name", 4482 "uri": "https://client.foo/" 4483 }, 4484 } 4485 } 4487 [[ See issue #113 (https://github.com/ietf-wg-gnap/gnap-core- 4488 protocol/issues/113) ]] 4490 The verifier MUST parse the JWS object of the PoP header. The 4491 verifier MUST validate the signature of the header against the 4492 expected key of the signer. The verifier MUST ensure that all 4493 required parts of the message are covered by the signature. The 4494 verifier MUST ensure that all components of the signature contain 4495 correct values. 4497 8. Resource Access Rights 4499 GNAP provides a rich structure for describing the protected resources 4500 hosted by RSs and accessed by client software. This structure is 4501 used when the client instance requests an access token (Section 2.1) 4502 and when an access token is returned (Section 3.2). 4504 The root of this structure is a JSON array. The elements of the JSON 4505 array represent rights of access that are associated with the the 4506 access token. The resulting access is the union of all elements 4507 within the array. 4509 The access associated with the access token is described using 4510 objects that each contain multiple dimensions of access. Each object 4511 contains a REQUIRED "type" property that determines the type of API 4512 that the token is used for. 4514 type (string) The type of resource request as a string. This field 4515 MAY define which other fields are allowed in the request object. 4516 This field is REQUIRED. 4518 The value of the "type" field is under the control of the AS. This 4519 field MUST be compared using an exact byte match of the string value 4520 against known types by the AS. The AS MUST ensure that there is no 4521 collision between different authorization data types that it 4522 supports. The AS MUST NOT do any collation or normalization of data 4523 types during comparison. It is RECOMMENDED that designers of 4524 general-purpose APIs use a URI for this field to avoid collisions 4525 between multiple API types protected by a single AS. 4527 While it is expected that many APIs will have their own properties, a 4528 set of common properties are defined here. Specific API 4529 implementations SHOULD NOT re-use these fields with different 4530 semantics or syntax. The available values for these properties are 4531 determined by the API being protected at the RS. 4533 actions (array of strings) The types of actions the client instance 4534 will take at the RS as an array of strings. For example, a client 4535 instance asking for a combination of "read" and "write" access. 4537 locations (array of strings) The location of the RS as an array of 4538 strings. These strings are typically URIs identifying the 4539 location of the RS. 4541 datatypes (array of strings) The kinds of data available to the 4542 client instance at the RS's API as an array of strings. For 4543 example, a client instance asking for access to raw "image" data 4544 and "metadata" at a photograph API. 4546 identifier (string) A string identifier indicating a specific 4547 resource at the RS. For example, a patient identifier for a 4548 medical API or a bank account number for a financial API. 4550 The following non-normative example is describing three kinds of 4551 access (read, write, delete) to each of two different locations and 4552 two different data types (metadata, images) for a single access token 4553 using the fictitious "photo-api" type definition. 4555 "access": [ 4556 { 4557 "type": "photo-api", 4558 "actions": [ 4559 "read", 4560 "write", 4561 "delete" 4562 ], 4563 "locations": [ 4564 "https://server.example.net/", 4565 "https://resource.local/other" 4566 ], 4567 "datatypes": [ 4568 "metadata", 4569 "images" 4570 ] 4571 } 4572 ] 4574 The access requested for a given object when using these fields is 4575 the cross-product of all fields of the object. That is to say, the 4576 object represents a request for all "actions" listed to be used at 4577 all "locations" listed for all possible "datatypes" listed within the 4578 object. Assuming the request above was granted, the client instance 4579 could assume that it would be able to do a "read" action against the 4580 "images" on the first server as well as a "delete" action on the 4581 "metadata" of the second server, or any other combination of these 4582 fields, using the same access token. 4584 To request a different combination of access, such as requesting one 4585 of the possible "actions" against one of the possible "locations" and 4586 a different choice of possible "actions" against a different one of 4587 the possible "locations", the client instance can include multiple 4588 separate objects in the "resources" array. The following non- 4589 normative example uses the same fictitious "photo-api" type 4590 definition to request a single access token with more specifically 4591 targeted access rights by using two discrete objects within the 4592 request. 4594 "access": [ 4595 { 4596 "type": "photo-api", 4597 "actions": [ 4598 "read" 4599 ], 4600 "locations": [ 4601 "https://server.example.net/" 4602 ], 4603 "datatypes": [ 4604 "images" 4605 ] 4606 }, 4607 { 4608 "type": "photo-api", 4609 "actions": [ 4610 "write", 4611 "delete" 4612 ], 4613 "locations": [ 4614 "https://resource.local/other" 4615 ], 4616 "datatypes": [ 4617 "metadata" 4618 ] 4619 } 4620 ] 4622 The access requested here is for "read" access to "images" on one 4623 server while simultaneously requesting "write" and "delete" access 4624 for "metadata" on a different server, but importantly without 4625 requesting "write" or "delete" access to "images" on the first 4626 server. 4628 It is anticipated that API designers will use a combination of common 4629 fields defined in this specification as well as fields specific to 4630 the API itself. The following non-normative example shows the use of 4631 both common and API-specific fields as part of two different 4632 fictitious API "type" values. The first access request includes the 4633 "actions", "locations", and "datatypes" fields specified here as well 4634 as the API-specific "geolocation" field. The second access request 4635 includes the "actions" and "identifier" fields specified here as well 4636 as the API-specific "currency" field. 4638 "access": [ 4639 { 4640 "type": "photo-api", 4641 "actions": [ 4642 "read", 4643 "write" 4644 ], 4645 "locations": [ 4646 "https://server.example.net/", 4647 "https://resource.local/other" 4648 ], 4649 "datatypes": [ 4650 "metadata", 4651 "images" 4652 ], 4653 "geolocation": [ 4654 { lat: -32.364, lng: 153.207 }, 4655 { lat: -35.364, lng: 158.207 } 4656 ] 4657 }, 4658 { 4659 "type": "financial-transaction", 4660 "actions": [ 4661 "withdraw" 4662 ], 4663 "identifier": "account-14-32-32-3", 4664 "currency": "USD" 4665 } 4666 ] 4668 If this request is approved, the resulting access token 4669 (Section 3.2.1)'s access rights will be the union of the requested 4670 types of access for each of the two APIs, just as above. 4672 8.1. Requesting Resources By Reference 4674 Instead of sending an object describing the requested resource 4675 (Section 8), access rights MAY be communicated as a string known to 4676 the AS or RS representing the access being requested. Each string 4677 SHOULD correspond to a specific expanded object representation at the 4678 AS. 4680 "access": [ 4681 "read", "dolphin-metadata", "some other thing" 4682 ] 4683 This value is opaque to the client instance and MAY be any valid JSON 4684 string, and therefore could include spaces, unicode characters, and 4685 properly escaped string sequences. However, in some situations the 4686 value is intended to be seen and understood by the client software's 4687 developer. In such cases, the API designer choosing any such human- 4688 readable strings SHOULD take steps to ensure the string values are 4689 not easily confused by a developer, such as by limiting the strings 4690 to easily disambiguated characters. 4692 This functionality is similar in practice to OAuth 2.0's "scope" 4693 parameter [RFC6749], where a single string represents the set of 4694 access rights requested by the client instance. As such, the 4695 reference string could contain any valid OAuth 2.0 scope value as in 4696 Appendix D.5. Note that the reference string here is not bound to 4697 the same character restrictions as in OAuth 2.0's "scope" definition. 4699 A single "access" array MAY include both object-type and string-type 4700 resource items. In this non-normative example, the client instance 4701 is requesting access to a "photo-api" and "financial-transaction" API 4702 type as well as the reference values of "read", "dolphin-metadata", 4703 and "some other thing". 4705 "access": [ 4706 { 4707 "type": "photo-api", 4708 "actions": [ 4709 "read", 4710 "write", 4711 "delete" 4712 ], 4713 "locations": [ 4714 "https://server.example.net/", 4715 "https://resource.local/other" 4716 ], 4717 "datatypes": [ 4718 "metadata", 4719 "images" 4720 ] 4721 }, 4722 "read", 4723 "dolphin-metadata", 4724 { 4725 "type": "financial-transaction", 4726 "actions": [ 4727 "withdraw" 4728 ], 4729 "identifier": "account-14-32-32-3", 4730 "currency": "USD" 4731 }, 4732 "some other thing" 4733 ] 4735 The requested access is the union of all elements of the array, 4736 including both objects and reference strings. 4738 9. Discovery 4740 By design, the protocol minimizes the need for any pre-flight 4741 discovery. To begin a request, the client instance only needs to 4742 know the endpoint of the AS and which keys it will use to sign the 4743 request. Everything else can be negotiated dynamically in the course 4744 of the protocol. 4746 However, the AS can have limits on its allowed functionality. If the 4747 client instance wants to optimize its calls to the AS before making a 4748 request, it MAY send an HTTP OPTIONS request to the grant request 4749 endpoint to retrieve the server's discovery information. The AS MUST 4750 respond with a JSON document containing the following information: 4752 grant_request_endpoint (string) REQUIRED. The location of the AS's 4753 grant request endpoint. The location MUST be a URL [RFC3986] with 4754 a scheme component that MUST be https, a host component, and 4755 optionally, port, path and query components and no fragment 4756 components. This URL MUST match the URL the client instance used 4757 to make the discovery request. 4759 capabilities (array of strings) OPTIONAL. A list of the AS's 4760 capabilities. The values of this result MAY be used by the client 4761 instance in the capabilities section (Section 2.6) of the request. 4763 interaction_methods_supported (array of strings) OPTIONAL. A list 4764 of the AS's interaction methods. The values of this list 4765 correspond to the possible fields in the interaction section 4766 (Section 2.5) of the request. 4768 key_proofs_supported (array of strings) OPTIONAL. A list of the 4769 AS's supported key proofing mechanisms. The values of this list 4770 correspond to possible values of the "proof" field of the key 4771 section (Section 7.1) of the request. 4773 subject_formats_supported (array of strings) OPTIONAL. A list of 4774 the AS's supported subject identifier types. The values of this 4775 list correspond to possible values of the subject identifier 4776 section (Section 2.2) of the request. 4778 assertions_supported (array of strings) OPTIONAL. A list of the 4779 AS's supported assertion formats. The values of this list 4780 correspond to possible values of the subject assertion section 4781 (Section 2.2) of the request. 4783 The information returned from this method is for optimization 4784 purposes only. The AS MAY deny any request, or any portion of a 4785 request, even if it lists a capability as supported. For example, a 4786 given client instance can be registered with the "mtls" key proofing 4787 mechanism, but the AS also returns other proofing methods, then the 4788 AS will deny a request from that client instance using a different 4789 proofing mechanism. 4791 10. Acknowledgements 4793 The editors would like to thank the feedback of the following 4794 individuals for their reviews, implementations, and contributions: 4795 Aaron Parecki, Annabelle Backman, Dick Hardt, Dmitri Zagidulin, 4796 Dmitry Barinov, Fabien Imbault, Francis Pouatcha, George Fletcher, 4797 Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan, Justin 4798 Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat Sakimura, 4799 Takahiko Kawasaki, Takahiro Tsuchiya. 4801 The editors would also like to thank the GNAP working group design 4802 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 4803 and Justin Richer, who incorporated elements from the XAuth and XYZ 4804 proposals to create the first version of this document. 4806 In addition, the editors would like to thank Aaron Parecki and Mike 4807 Jones for insights into how to integrate identity and authentication 4808 systems into the core protocol, and Justin Richer and Dick Hardt for 4809 the use cases, diagrams, and insights provided in the XYZ and XAuth 4810 proposals that have been incorporated here. The editors would like 4811 to especially thank Mike Varley and the team at SecureKey for 4812 feedback and development of early versions of the XYZ protocol that 4813 fed into this standards work. 4815 11. IANA Considerations 4817 [[ TBD: There are a lot of items in the document that are expandable 4818 through the use of value registries. ]] 4820 12. Security Considerations 4822 [[ TBD: There are a lot of security considerations to add. ]] 4824 All requests have to be over TLS or equivalent as per [BCP195]. Many 4825 handles act as shared secrets, though they can be combined with a 4826 requirement to provide proof of a key as well. 4828 13. Privacy Considerations 4830 [[ TBD: There are a lot of privacy considerations to add. ]] 4832 Handles are passed between parties and therefore should not contain 4833 any private data. 4835 When user information is passed to the client instance, the AS needs 4836 to make sure that it has the permission to do so. 4838 14. Normative References 4840 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 4841 "Recommendations for Secure Use of Transport Layer 4842 Security (TLS) and Datagram Transport Layer Security 4843 (DTLS)", May 2015, 4844 . 4846 [I-D.draft-ietf-gnap-resource-servers] 4847 "*** BROKEN REFERENCE ***". 4849 [I-D.ietf-httpbis-message-signatures] 4850 Backman, A., Richer, J., and M. Sporny, "Signing HTTP 4851 Messages", Work in Progress, Internet-Draft, draft-ietf- 4852 httpbis-message-signatures-04, 21 April 2021, 4853 . 4856 [I-D.ietf-oauth-dpop] 4857 Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., 4858 Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof- 4859 of-Possession at the Application Layer (DPoP)", Work in 4860 Progress, Internet-Draft, draft-ietf-oauth-dpop-03, 7 4861 April 2021, . 4864 [I-D.ietf-oauth-rar] 4865 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 4866 Rich Authorization Requests", Work in Progress, Internet- 4867 Draft, draft-ietf-oauth-rar-04, 7 February 2021, 4868 . 4871 [I-D.ietf-oauth-signed-http-request] 4872 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 4873 Signing HTTP Requests for OAuth", Work in Progress, 4874 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 4875 August 2016, . 4878 [I-D.ietf-secevent-subject-identifiers] 4879 Backman, A. and M. Scurtescu, "Subject Identifiers for 4880 Security Event Tokens", Work in Progress, Internet-Draft, 4881 draft-ietf-secevent-subject-identifiers-07, 8 March 2021, 4882 . 4885 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 4886 C. Mortimore, "OpenID Connect Core 1.0 incorporating 4887 errata set 1", November 2014, 4888 . 4890 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4891 Requirement Levels", BCP 14, RFC 2119, 4892 DOI 10.17487/RFC2119, March 1997, 4893 . 4895 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 4896 RFC 3230, DOI 10.17487/RFC3230, January 2002, 4897 . 4899 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4900 Resource Identifier (URI): Generic Syntax", STD 66, 4901 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4902 . 4904 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 4905 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 4906 September 2009, . 4908 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 4909 RFC 6749, DOI 10.17487/RFC6749, October 2012, 4910 . 4912 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 4913 Framework: Bearer Token Usage", RFC 6750, 4914 DOI 10.17487/RFC6750, October 2012, 4915 . 4917 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 4918 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 4919 RFC 7234, DOI 10.17487/RFC7234, June 2014, 4920 . 4922 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 4923 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 4924 April 2015, . 4926 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4927 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4928 2015, . 4930 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4931 DOI 10.17487/RFC7517, May 2015, 4932 . 4934 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4935 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4936 May 2017, . 4938 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4939 Interchange Format", STD 90, RFC 8259, 4940 DOI 10.17487/RFC8259, December 2017, 4941 . 4943 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 4944 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 4945 and Certificate-Bound Access Tokens", RFC 8705, 4946 DOI 10.17487/RFC8705, February 2020, 4947 . 4949 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 4950 "Handling Long Lines in Content of Internet-Drafts and 4951 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 4952 . 4954 Appendix A. Document History 4956 * -05 4958 - Changed "interaction_methods" to 4959 "interaction_methods_supported". 4961 - Changed "key_proofs" to "key_proofs_supported". 4963 - Changed "assertions" to "assertions_supported". 4965 - Updated discovery and field names for subject formats. 4967 - Add an appendix to provide protocol rationale, compared to 4968 OAuth2. 4970 - Updated subject information definition. 4972 - Refactored the RS-centric components into a new document. 4974 - Updated cryptographic proof of possession methods to match 4975 current reference syntax. 4977 - Updated proofing language to use "signer" and "verifier" 4978 generically. 4980 - Updated cryptographic proof of possession examples. 4982 - Editorial cleanup and fixes. 4984 - Diagram cleanup and fixes. 4986 * -04 4988 - Updated terminology. 4990 - Refactored key presentation and binding. 4992 - Refactored "interact" request to group start and end modes. 4994 - Changed access token request and response syntax. 4996 - Changed DPoP digest field to 'htd' to match proposed FAPI 4997 profile. 4999 - Include the access token hash in the DPoP message. 5001 - Removed closed issue links. 5003 - Removed function to read state of grant request by client. 5005 - Closed issues related to reading and updating access tokens. 5007 * -03 5009 - Changed "resource client" terminology to separate "client 5010 instance" and "client software". 5012 - Removed OpenID Connect "claims" parameter. 5014 - Dropped "short URI" redirect. 5016 - Access token is mandatory for continuation. 5018 - Removed closed issue links. 5020 - Editorial fixes. 5022 * -02 5024 - Moved all "editor's note" items to GitHub Issues. 5026 - Added JSON types to fields. 5028 - Changed "GNAP Protocol" to "GNAP". 5030 - Editorial fixes. 5032 * -01 5034 - "updated_at" subject info timestamp now in ISO 8601 string 5035 format. 5037 - Editorial fixes. 5039 - Added Aaron and Fabien as document authors. 5041 * -00 5043 - Initial working group draft. 5045 Appendix B. Compared to OAuth 2.0 5047 GNAP's protocol design differs from OAuth 2.0's in several 5048 fundamental ways: 5050 1. *Consent and authorization flexibility:* 5052 OAuth 2.0 generally assumes the user has access to the a web 5053 browser. The type of interaction available is fixed by the grant 5054 type, and the most common interactive grant types start in the 5055 browser. OAuth 2.0 assumes that the user using the client 5056 software is the same user that will interact with the AS to 5057 approve access. 5059 GNAP allows various patterns to manage authorizations and 5060 consents required to fulfill this requested delegation, including 5061 information sent by the client instance, information supplied by 5062 external parties, and information gathered through the 5063 interaction process. GNAP allows a client instance to list 5064 different ways that it can start and finish an interaction, and 5065 these can be mixed together as needed for different use cases. 5066 GNAP interactions can use a browser, but don't have to. Methods 5067 can use inter-application messaging protocols, out-of-band data 5068 transfer, or anything else. GNAP allows extensions to define new 5069 ways to start and finish an interaction, as new methods and 5070 platforms are expected to become available over time. GNAP is 5071 designed to allow the end-user and the resource owner to be two 5072 different people, but still works in the optimized case of them 5073 being the same party. 5075 2. *Intent registration and inline negotiation:* 5077 OAuth 2.0 uses different "grant types" that start at different 5078 endpoints for different purposes. Many of these require 5079 discovery of several interrelated parameters. 5081 GNAP requests all start with the same type of request to the same 5082 endpoint at the AS. Next steps are negotiated between the client 5083 instance and AS based on software capabilities, policies 5084 surrounding requested access, and the overall context of the 5085 ongoing request. GNAP defines a continuation API that allows the 5086 client instance and AS to request and send additional information 5087 from each other over multiple steps. This continuation API uses 5088 the same access token protection that other GNAP-protected APIs 5089 use. GNAP allows discovery to optimize the requests but it isn't 5090 required thanks to the negotiation capabilities. 5092 3. *Client instances:* 5094 OAuth 2.0 requires all clients to be registered at the AS and to 5095 use a client_id known to the AS as part of the protocol. This 5096 client_id is generally assumed to be assigned by a trusted 5097 authority during a registration process, and OAuth places a lot 5098 of trust on the client_id as a result. Dynamic registration 5099 allows different classes of clients to get a client_id at 5100 runtime, even if they only ever use it for one request. 5102 GNAP allows the client instance to present an unknown key to the 5103 AS and use that key to protect the ongoing request. GNAP's 5104 client instance identifier mechanism allows for pre-registered 5105 clients and dynamically registered clients to exist as an 5106 optimized case without requiring the identifier as part of the 5107 protocol at all times. 5109 4. *Expanded delegation:* 5111 OAuth 2.0 defines the "scope" parameter for controlling access to 5112 APIs. This parameter has been coopted to mean a number of 5113 different things in different protocols, including flags for 5114 turning special behavior on and off, including the return of data 5115 apart from the access token. The "resource" parameter and RAR 5116 extensions (as defined in [I-D.ietf-oauth-rar]) expand on the 5117 "scope" concept in similar but different ways. 5119 GNAP defines a rich structure for requesting access, with string 5120 references as an optimization. GNAP defines methods for 5121 requesting directly-returned user information, separate from API 5122 access. This information includes identifiers for the current 5123 user and structured assertions. The core GNAP protocol makes no 5124 assumptions or demands on the format or contents of the access 5125 token, but the RS extension allows a negotiation of token formats 5126 between the AS and RS. 5128 5. *Cryptography-based security:* 5129 OAuth 2.0 uses shared bearer secrets, including the client_secret 5130 and access token, and advanced authentication and sender 5131 constraint have been built on after the fact in inconsistent 5132 ways. 5134 In GNAP, all communication between the client instance and AS is 5135 bound to a key held by the client instance. GNAP uses the same 5136 cryptographic mechanisms for both authenticating the client (to 5137 the AS) and binding the access token (to the RS and the AS). 5138 GNAP allows extensions to define new cryptographic protection 5139 mechanisms, as new methods are expected to become available over 5140 time. GNAP does not have a notion of "public clients" because 5141 key information can always be sent and used dynamically. 5143 6. *Privacy and usable security:* 5145 OAuth 2.0's deployment model assumes a strong binding between the 5146 AS and the RS. 5148 GNAP is designed to be interoperable with decentralized identity 5149 standards and to provide a human-centric authorization layer. In 5150 addition to the core protocol, GNAP that supports various 5151 patterns of communication between RSs and ASs through extensions. 5152 GNAP tries to limit the odds of a consolidation to just a handful 5153 of super-popular AS services. 5155 Appendix C. Component Data Models 5157 While different implementations of this protocol will have different 5158 realizations of all the components and artifacts enumerated here, the 5159 nature of the protocol implies some common structures and elements 5160 for certain components. This appendix seeks to enumerate those 5161 common elements. 5163 TBD: Client has keys, allowed requested resources, identifier(s), 5164 allowed requested subjects, allowed 5166 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 5167 client keys, policies 5169 TBD: Token has RO, user, client, resource list, RS list, 5171 Appendix D. Example Protocol Flows 5173 The protocol defined in this specification provides a number of 5174 features that can be combined to solve many different kinds of 5175 authentication scenarios. This section seeks to show examples of how 5176 the protocol would be applied for different situations. 5178 Some longer fields, particularly cryptographic information, have been 5179 truncated for display purposes in these examples. 5181 D.1. Redirect-Based User Interaction 5183 In this scenario, the user is the RO and has access to a web browser, 5184 and the client instance can take front-channel callbacks on the same 5185 device as the user. This combination is analogous to the OAuth 2.0 5186 Authorization Code grant type. 5188 The client instance initiates the request to the AS. Here the client 5189 instance identifies itself using its public key. 5191 POST /tx HTTP/1.1 5192 Host: server.example.com 5193 Content-Type: application/json 5194 Detached-JWS: ejy0... 5196 { 5197 "access_token": { 5198 "access": [ 5199 { 5200 "actions": [ 5201 "read", 5202 "write", 5203 "dolphin" 5204 ], 5205 "locations": [ 5206 "https://server.example.net/", 5207 "https://resource.local/other" 5208 ], 5209 "datatypes": [ 5210 "metadata", 5211 "images" 5212 ] 5213 } 5214 ], 5215 }, 5216 "client": { 5217 "key": { 5218 "proof": "jwsd", 5219 "jwk": { 5220 "kty": "RSA", 5221 "e": "AQAB", 5222 "kid": "xyz-1", 5223 "alg": "RS256", 5224 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 5225 } 5226 } 5227 }, 5228 "interact": { 5229 "start": ["redirect"], 5230 "finish": { 5231 "method": "redirect", 5232 "uri": "https://client.example.net/return/123455", 5233 "nonce": "LKLTI25DK82FX4T4QFZC" 5234 } 5235 } 5236 } 5237 The AS processes the request and determines that the RO needs to 5238 interact. The AS returns the following response giving the client 5239 instance the information it needs to connect. The AS has also 5240 indicated to the client instance that it can use the given instance 5241 identifier to identify itself in future requests (Section 2.3.1). 5243 HTTP/1.1 200 OK 5244 Content-Type: application/json 5245 Cache-Control: no-store 5247 { 5248 "interact": { 5249 "redirect": 5250 "https://server.example.com/interact/4CF492MLVMSW9MKM", 5251 "push": "MBDOFXG4Y5CVJCX821LH" 5252 } 5253 "continue": { 5254 "access_token": { 5255 "value": "80UPRY5NM33OMUKMKSKU" 5256 }, 5257 "uri": "https://server.example.com/continue" 5258 }, 5259 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 5260 } 5262 The client instance saves the response and redirects the user to the 5263 interaction_url by sending the following HTTP message to the user's 5264 browser. 5266 HTTP 302 Found 5267 Location: https://server.example.com/interact/4CF492MLVMSW9MKM 5269 The user's browser fetches the AS's interaction URL. The user logs 5270 in, is identified as the RO for the resource being requested, and 5271 approves the request. Since the AS has a callback parameter, the AS 5272 generates the interaction reference, calculates the hash, and 5273 redirects the user back to the client instance with these additional 5274 values added as query parameters. 5276 HTTP 302 Found 5277 Location: https://client.example.net/return/123455\ 5278 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 5279 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 5280 &interact_ref=4IFWWIKYBC2PQ6U56NL1 5282 The client instance receives this request from the user's browser. 5283 The client instance ensures that this is the same user that was sent 5284 out by validating session information and retrieves the stored 5285 pending request. The client instance uses the values in this to 5286 validate the hash parameter. The client instance then calls the 5287 continuation URL and presents the handle and interaction reference in 5288 the request body. The client instance signs the request as above. 5290 POST /continue HTTP/1.1 5291 Host: server.example.com 5292 Content-Type: application/json 5293 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5294 Detached-JWS: ejy0... 5296 { 5297 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 5298 } 5300 The AS retrieves the pending request based on the handle and issues a 5301 bearer access token and returns this to the client instance. 5303 HTTP/1.1 200 OK 5304 Content-Type: application/json 5305 Cache-Control: no-store 5307 { 5308 "access_token": { 5309 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5310 "manage": "https://server.example.com/token/PRY5NM33O\ 5311 M4TB8N6BW7OZB8CDFONP219RP1L", 5312 "access": [{ 5313 "actions": [ 5314 "read", 5315 "write", 5316 "dolphin" 5317 ], 5318 "locations": [ 5319 "https://server.example.net/", 5320 "https://resource.local/other" 5321 ], 5322 "datatypes": [ 5323 "metadata", 5324 "images" 5325 ] 5326 }] 5327 }, 5328 "continue": { 5329 "access_token": { 5330 "value": "80UPRY5NM33OMUKMKSKU" 5331 }, 5332 "uri": "https://server.example.com/continue" 5333 } 5334 } 5336 D.2. Secondary Device Interaction 5338 In this scenario, the user does not have access to a web browser on 5339 the device and must use a secondary device to interact with the AS. 5340 The client instance can display a user code or a printable QR code. 5341 The client instance is not able to accept callbacks from the AS and 5342 needs to poll for updates while waiting for the user to authorize the 5343 request. 5345 The client instance initiates the request to the AS. 5347 POST /tx HTTP/1.1 5348 Host: server.example.com 5349 Content-Type: application/json 5350 Detached-JWS: ejy0... 5352 { 5353 "access_token": { 5354 "access": [ 5355 "dolphin-metadata", "some other thing" 5356 ], 5357 }, 5358 "client": "7C7C4AZ9KHRS6X63AJAO", 5359 "interact": { 5360 "start": ["redirect", "user_code"] 5361 } 5362 } 5364 The AS processes this and determines that the RO needs to interact. 5365 The AS supports both redirect URIs and user codes for interaction, so 5366 it includes both. Since there is no "callback" the AS does not 5367 include a nonce, but does include a "wait" parameter on the 5368 continuation section because it expects the client instance to poll 5369 for results. 5371 HTTP/1.1 200 OK 5372 Content-Type: application/json 5373 Cache-Control: no-store 5375 { 5376 "interact": { 5377 "redirect": "https://srv.ex/MXKHQ", 5378 "user_code": { 5379 "code": "A1BC-3DFF", 5380 "url": "https://srv.ex/device" 5381 } 5382 }, 5383 "continue": { 5384 "access_token": { 5385 "value": "80UPRY5NM33OMUKMKSKU" 5386 }, 5387 "uri": "https://server.example.com/continue/VGJKPTKC50", 5388 "wait": 60 5389 } 5390 } 5391 The client instance saves the response and displays the user code 5392 visually on its screen along with the static device URL. The client 5393 instance also displays the short interaction URL as a QR code to be 5394 scanned. 5396 If the user scans the code, they are taken to the interaction 5397 endpoint and the AS looks up the current pending request based on the 5398 incoming URL. If the user instead goes to the static page and enters 5399 the code manually, the AS looks up the current pending request based 5400 on the value of the user code. In both cases, the user logs in, is 5401 identified as the RO for the resource being requested, and approves 5402 the request. Once the request has been approved, the AS displays to 5403 the user a message to return to their device. 5405 Meanwhile, the client instance periodically polls the AS every 60 5406 seconds at the continuation URL. The client instance signs the 5407 request using the same key and method that it did in the first 5408 request. 5410 POST /continue/VGJKPTKC50 HTTP/1.1 5411 Host: server.example.com 5412 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5413 Detached-JWS: ejy0... 5415 The AS retrieves the pending request based on the handle and 5416 determines that it has not yet been authorized. The AS indicates to 5417 the client instance that no access token has yet been issued but it 5418 can continue to call after another 60 second timeout. 5420 HTTP/1.1 200 OK 5421 Content-Type: application/json 5422 Cache-Control: no-store 5424 { 5425 "continue": { 5426 "access_token": { 5427 "value": "G7YQT4KQQ5TZY9SLSS5E" 5428 }, 5429 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 5430 "wait": 60 5431 } 5432 } 5434 Note that the continuation URL and access token have been rotated 5435 since they were used by the client instance to make this call. The 5436 client instance polls the continuation URL after a 60 second timeout 5437 using this new information. 5439 POST /continue/ATWHO4Q1WV HTTP/1.1 5440 Host: server.example.com 5441 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 5442 Detached-JWS: ejy0... 5444 The AS retrieves the pending request based on the URL and access 5445 token, determines that it has been approved, and issues an access 5446 token for the client to use at the RS. 5448 HTTP/1.1 200 OK 5449 Content-Type: application/json 5450 Cache-Control: no-store 5452 { 5453 "access_token": { 5454 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5455 "manage": "https://server.example.com/token/PRY5NM33O\ 5456 M4TB8N6BW7OZB8CDFONP219RP1L", 5457 "access": [ 5458 "dolphin-metadata", "some other thing" 5459 ] 5460 } 5461 } 5463 D.3. No User Involvement 5465 In this scenario, the client instance is requesting access on its own 5466 behalf, with no user to interact with. 5468 The client instance creates a request to the AS, identifying itself 5469 with its public key and using MTLS to make the request. 5471 POST /tx HTTP/1.1 5472 Host: server.example.com 5473 Content-Type: application/json 5475 { 5476 "access_token": { 5477 "access": [ 5478 "backend service", "nightly-routine-3" 5479 ], 5480 }, 5481 "client": { 5482 "key": { 5483 "proof": "mtls", 5484 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 5485 } 5486 } 5487 } 5489 The AS processes this and determines that the client instance can ask 5490 for the requested resources and issues an access token. 5492 HTTP/1.1 200 OK 5493 Content-Type: application/json 5494 Cache-Control: no-store 5496 { 5497 "access_token": { 5498 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5499 "manage": "https://server.example.com/token", 5500 "access": [ 5501 "backend service", "nightly-routine-3" 5502 ] 5503 } 5504 } 5506 D.4. Asynchronous Authorization 5508 In this scenario, the client instance is requesting on behalf of a 5509 specific RO, but has no way to interact with the user. The AS can 5510 asynchronously reach out to the RO for approval in this scenario. 5512 The client instance starts the request at the AS by requesting a set 5513 of resources. The client instance also identifies a particular user. 5515 POST /tx HTTP/1.1 5516 Host: server.example.com 5517 Content-Type: application/json 5518 Detached-JWS: ejy0... 5520 { 5521 "access_token": { 5522 "access": [ 5523 { 5524 "type": "photo-api", 5525 "actions": [ 5526 "read", 5527 "write", 5528 "dolphin" 5529 ], 5530 "locations": [ 5531 "https://server.example.net/", 5532 "https://resource.local/other" 5533 ], 5534 "datatypes": [ 5535 "metadata", 5536 "images" 5537 ] 5538 }, 5539 "read", "dolphin-metadata", 5540 { 5541 "type": "financial-transaction", 5542 "actions": [ 5543 "withdraw" 5544 ], 5545 "identifier": "account-14-32-32-3", 5546 "currency": "USD" 5547 }, 5548 "some other thing" 5549 ], 5550 }, 5551 "client": "7C7C4AZ9KHRS6X63AJAO", 5552 "user": { 5553 "sub_ids": [ { 5554 "format": "opaque", 5555 "id": "J2G8G8O4AZ" 5556 } ] 5557 } 5558 } 5559 The AS processes this and determines that the RO needs to interact. 5560 The AS determines that it can reach the identified user 5561 asynchronously and that the identified user does have the ability to 5562 approve this request. The AS indicates to the client instance that 5563 it can poll for continuation. 5565 HTTP/1.1 200 OK 5566 Content-Type: application/json 5567 Cache-Control: no-store 5569 { 5570 "continue": { 5571 "access_token": { 5572 "value": "80UPRY5NM33OMUKMKSKU" 5573 }, 5574 "uri": "https://server.example.com/continue", 5575 "wait": 60 5576 } 5577 } 5579 The AS reaches out to the RO and prompts them for consent. In this 5580 example, the AS has an application that it can push notifications in 5581 to for the specified account. 5583 Meanwhile, the client instance periodically polls the AS every 60 5584 seconds at the continuation URL. 5586 POST /continue HTTP/1.1 5587 Host: server.example.com 5588 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 5589 Detached-JWS: ejy0... 5591 The AS retrieves the pending request based on the handle and 5592 determines that it has not yet been authorized. The AS indicates to 5593 the client instance that no access token has yet been issued but it 5594 can continue to call after another 60 second timeout. 5596 HTTP/1.1 200 OK 5597 Content-Type: application/json 5598 Cache-Control: no-store 5600 { 5601 "continue": { 5602 "access_token": { 5603 "value": "BI9QNW6V9W3XFJK4R02D" 5604 }, 5605 "uri": "https://server.example.com/continue", 5606 "wait": 60 5607 } 5608 } 5610 Note that the continuation handle has been rotated since it was used 5611 by the client instance to make this call. The client instance polls 5612 the continuation URL after a 60 second timeout using the new handle. 5614 POST /continue HTTP/1.1 5615 Host: server.example.com 5616 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 5617 Detached-JWS: ejy0... 5619 The AS retrieves the pending request based on the handle and 5620 determines that it has been approved and it issues an access token. 5622 HTTP/1.1 200 OK 5623 Content-Type: application/json 5624 Cache-Control: no-store 5626 { 5627 "access_token": { 5628 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 5629 "manage": "https://server.example.com/token/PRY5NM33O\ 5630 M4TB8N6BW7OZB8CDFONP219RP1L", 5631 "access": [ 5632 "dolphin-metadata", "some other thing" 5633 ] 5634 } 5635 } 5637 D.5. Applying OAuth 2.0 Scopes and Client IDs 5639 While GNAP is not designed to be directly compatible with OAuth 2.0 5640 [RFC6749], considerations have been made to enable the use of OAuth 5641 2.0 concepts and constructs more smoothly within GNAP. 5643 In this scenario, the client developer has a "client_id" and set of 5644 "scope" values from their OAuth 2.0 system and wants to apply them to 5645 the new protocol. Traditionally, the OAuth 2.0 client developer 5646 would put their "client_id" and "scope" values as parameters into a 5647 redirect request to the authorization endpoint. 5649 HTTP 302 Found 5650 Location: https://server.example.com/authorize 5651 ?client_id=7C7C4AZ9KHRS6X63AJAO 5652 &scope=read%20write%20dolphin 5653 &redirect_uri=https://client.example.net/return 5654 &response_type=code 5655 &state=123455 5657 Now the developer wants to make an analogous request to the AS using 5658 GNAP. To do so, the client instance makes an HTTP POST and places 5659 the OAuth 2.0 values in the appropriate places. 5661 POST /tx HTTP/1.1 5662 Host: server.example.com 5663 Content-Type: application/json 5664 Detached-JWS: ejy0... 5666 { 5667 "access_token": { 5668 "access": [ 5669 "read", "write", "dolphin" 5670 ], 5671 "flags": [ "bearer" ] 5672 }, 5673 "client": "7C7C4AZ9KHRS6X63AJAO", 5674 "interact": { 5675 "start": ["redirect"], 5676 "finish": { 5677 "method": "redirect", 5678 "uri": "https://client.example.net/return?state=123455", 5679 "nonce": "LKLTI25DK82FX4T4QFZC" 5680 } 5681 } 5682 } 5684 The "client_id" can be used to identify the client instance's keys 5685 that it uses for authentication, the scopes represent resources that 5686 the client instance is requesting, and the "redirect_uri" and "state" 5687 value are pre-combined into a "finish" URI that can be unique per 5688 request. The client instance additionally creates a nonce to protect 5689 the callback, separate from the state parameter that it has added to 5690 its return URL. 5692 From here, the protocol continues as above. 5694 Appendix E. JSON Structures and Polymorphism 5696 GNAP makes use of polymorphism within the JSON [RFC8259] structures 5697 used for the protocol. Each portion of this protocol is defined in 5698 terms of the JSON data type that its values can take, whether it's a 5699 string, object, array, boolean, or number. For some fields, 5700 different data types offer different descriptive capabilities and are 5701 used in different situations for the same field. Each data type 5702 provides a different syntax to express the same underlying semantic 5703 protocol element, which allows for optimization and simplification in 5704 many common cases. 5706 Even though JSON is often used to describe strongly typed structures, 5707 JSON on its own is naturally polymorphic. In JSON, the named members 5708 of an object have no type associated with them, and any data type can 5709 be used as the value for any member. In practice, each member has a 5710 semantic type that needs to make sense to the parties creating and 5711 consuming the object. Within this protocol, each object member is 5712 defined in terms of its semantic content, and this semantic content 5713 might have expressions in different concrete data types for different 5714 specific purposes. Since each object member has exactly one value in 5715 JSON, each data type for an object member field is naturally mutually 5716 exclusive with other data types within a single JSON object. 5718 For example, a resource request for a single access token is composed 5719 of an array of resource request descriptions while a request for 5720 multiple access tokens is composed of an object whose member values 5721 are all arrays. Both of these represent requests for access, but the 5722 difference in syntax allows the client instance and AS to 5723 differentiate between the two request types in the same request. 5725 Another form of polymorphism in JSON comes from the fact that the 5726 values within JSON arrays need not all be of the same JSON data type. 5727 However, within this protocol, each element within the array needs to 5728 be of the same kind of semantic element for the collection to make 5729 sense, even when the data types are different from each other. 5731 For example, each aspect of a resource request can be described using 5732 an object with multiple dimensional components, or the aspect can be 5733 requested using a string. In both cases, the resource request is 5734 being described in a way that the AS needs to interpret, but with 5735 different levels of specificity and complexity for the client 5736 instance to deal with. An API designer can provide a set of common 5737 access scopes as simple strings but still allow client software 5738 developers to specify custom access when needed for more complex 5739 APIs. 5741 Extensions to this specification can use different data types for 5742 defined fields, but each extension needs to not only declare what the 5743 data type means, but also provide justification for the data type 5744 representing the same basic kind of thing it extends. For example, 5745 an extension declaring an "array" representation for a field would 5746 need to explain how the array represents something akin to the non- 5747 array element that it is replacing. 5749 Authors' Addresses 5751 Justin Richer (editor) 5752 Bespoke Engineering 5754 Email: ietf@justin.richer.org 5755 URI: https://bspk.io/ 5757 Aaron Parecki 5758 Okta 5760 Email: aaron@parecki.com 5761 URI: https://aaronparecki.com 5763 Fabien Imbault 5764 acert.io 5766 Email: fabien.imbault@acert.io 5767 URI: https://acert.io/