idnits 2.17.1 draft-ietf-gnap-core-protocol-08.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. 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 284 has weird spacing: '... Client appli...' == Line 309 has weird spacing: '...nd-user natur...' == Line 371 has weird spacing: '...tribute chara...' == Line 373 has weird spacing: '...s Token a dat...' == Line 384 has weird spacing: '...ivilege right...' == (4 more instances...) -- The document date (25 October 2021) is 885 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC3230' is defined on line 5917, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-05) exists of draft-ietf-gnap-resource-servers-01 == Outdated reference: A later version (-13) exists of draft-ietf-httpbis-digest-headers-06 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-06 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-08 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Downref: Normative reference to an Informational RFC: RFC 8792 == Outdated reference: A later version (-06) exists of draft-ietf-httpbis-client-cert-field-00 Summary: 3 errors (**), 0 flaws (~~), 15 warnings (==), 3 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: 28 April 2022 Okta 6 F. Imbault 7 acert.io 8 25 October 2021 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-08 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 28 April 2022. 37 Copyright Notice 39 Copyright (c) 2021 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 44 license-info) in effect on the date of publication of this document. 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. Code Components 47 extracted from this document must include Simplified BSD License text 48 as described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 9 57 1.4. Trust relationships . . . . . . . . . . . . . . . . . . . 10 58 1.5. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 12 59 1.5.1. Redirect-based Interaction . . . . . . . . . . . . . 15 60 1.5.2. User-code Interaction . . . . . . . . . . . . . . . . 18 61 1.5.3. Asynchronous Authorization . . . . . . . . . . . . . 20 62 1.5.4. Software-only Authorization . . . . . . . . . . . . . 22 63 1.5.5. Refreshing an Expired Access Token . . . . . . . . . 23 64 1.5.6. Requesting User Information . . . . . . . . . . . . . 25 65 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 26 66 2.1. Requesting Access to Resources . . . . . . . . . . . . . 28 67 2.1.1. Requesting a Single Access Token . . . . . . . . . . 28 68 2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 31 69 2.2. Requesting Subject Information . . . . . . . . . . . . . 33 70 2.3. Identifying the Client Instance . . . . . . . . . . . . . 34 71 2.3.1. Identifying the Client Instance by Reference . . . . 35 72 2.3.2. Providing Displayable Client Instance Information . . 36 73 2.3.3. Authenticating the Client Instance . . . . . . . . . 36 74 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 37 75 2.4.1. Identifying the User by Reference . . . . . . . . . . 38 76 2.5. Interacting with the User . . . . . . . . . . . . . . . . 39 77 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 40 78 2.5.2. Finish Interaction Modes . . . . . . . . . . . . . . 42 79 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 44 80 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 45 81 2.6. Extending The Grant Request . . . . . . . . . . . . . . . 45 82 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 45 83 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 47 84 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 48 85 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 48 86 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 52 87 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 53 88 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 54 89 3.3.2. Launch of an application URL . . . . . . . . . . . . 55 90 3.3.3. Display of a Short User Code . . . . . . . . . . . . 55 91 3.3.4. Interaction Finish . . . . . . . . . . . . . . . . . 56 92 3.3.5. Extending Interaction Mode Responses . . . . . . . . 57 93 3.4. Returning Subject Information . . . . . . . . . . . . . . 57 94 3.5. Returning a Dynamically-bound Client Instance 95 Identifier . . . . . . . . . . . . . . . . . . . . . . . 58 96 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 59 97 3.7. Extending the Response . . . . . . . . . . . . . . . . . 60 98 4. Determining Authorization and Consent . . . . . . . . . . . . 60 99 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 63 100 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 63 101 4.1.2. Interaction at the User Code URI . . . . . . . . . . 64 102 4.1.3. Interaction through an Application URI . . . . . . . 65 103 4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 65 104 4.2.1. Completing Interaction with a Browser Redirect to the 105 Callback URI . . . . . . . . . . . . . . . . . . . . 66 106 4.2.2. Completing Interaction with a Direct HTTP Request 107 Callback . . . . . . . . . . . . . . . . . . . . . . 67 108 4.2.3. Calculating the interaction hash . . . . . . . . . . 68 109 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 69 110 5.1. Continuing After a Completed Interaction . . . . . . . . 71 111 5.2. Continuing During Pending Interaction . . . . . . . . . . 72 112 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 74 113 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 80 114 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 80 115 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 80 116 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 82 117 7. Securing Requests from the Client Instance . . . . . . . . . 83 118 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 84 119 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 85 120 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 85 121 7.3. Proving Possession of a Key with a Request . . . . . . . 86 122 7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 88 123 7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 92 124 7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 94 125 7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 98 126 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 102 127 8.1. Requesting Resources By Reference . . . . . . . . . . . . 105 128 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 107 129 9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 108 130 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 110 131 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 110 132 12. Security Considerations . . . . . . . . . . . . . . . . . . . 110 133 12.1. TLS Protection in Transit . . . . . . . . . . . . . . . 110 134 12.2. Signing Requests from the Client Software . . . . . . . 111 135 12.3. Protection of Client Instance Key Material . . . . . . . 112 136 12.4. Protection of Authorization Server . . . . . . . . . . . 114 137 12.5. Symmetric and Asymmetric Client Instance Keys . . . . . 114 138 12.6. Generation of Access Tokens . . . . . . . . . . . . . . 115 139 12.7. Bearer Access Tokens . . . . . . . . . . . . . . . . . . 116 140 12.8. Key-Bound Token Access Tokens . . . . . . . . . . . . . 116 141 12.9. Exposure of End-user Credentials to Client Instance . . 117 142 12.10. Mixing Up Authorization Servers . . . . . . . . . . . . 118 143 12.11. Processing of Client-Presented User Information . . . . 119 144 12.12. Client Instance Pre-registration . . . . . . . . . . . . 120 145 12.13. Client Instance Impersonation . . . . . . . . . . . . . 121 146 12.14. Interception of Information in the Browser . . . . . . . 122 147 12.15. Callback URL Manipulation . . . . . . . . . . . . . . . 122 148 12.16. MTLS Message Integrity . . . . . . . . . . . . . . . . . 123 149 12.17. MTLS Deployment Patterns . . . . . . . . . . . . . . . . 124 150 12.18. Interception of Responses from the AS . . . . . . . . . 124 151 12.19. Key Distribution . . . . . . . . . . . . . . . . . . . . 125 152 12.20. Interaction Finish Modes and Polling . . . . . . . . . . 125 153 12.21. Storage of Information During Interaction and 154 Continuation . . . . . . . . . . . . . . . . . . . . . 126 155 12.22. Denial of Service (DoS) through Grant Continuation . . . 126 156 12.23. Exhaustion of Random Value Space . . . . . . . . . . . . 127 157 12.24. Front-channel URLs . . . . . . . . . . . . . . . . . . . 128 158 12.25. Processing Assertions . . . . . . . . . . . . . . . . . 129 159 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 129 160 13.1. Surveillance . . . . . . . . . . . . . . . . . . . . . . 129 161 13.1.1. Surveillance by the Client . . . . . . . . . . . . . 130 162 13.1.2. Surveillance by the Authorization Server . . . . . . 130 163 13.2. Stored Data . . . . . . . . . . . . . . . . . . . . . . 130 164 13.3. Intrusion . . . . . . . . . . . . . . . . . . . . . . . 131 165 13.4. Correlation . . . . . . . . . . . . . . . . . . . . . . 131 166 13.4.1. Correlation by Clients . . . . . . . . . . . . . . . 132 167 13.4.2. Correlation by Resource Servers . . . . . . . . . . 132 168 13.4.3. Correlation by Authorization Servers . . . . . . . . 133 169 13.5. Disclosure in Shared References . . . . . . . . . . . . 133 170 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 133 171 14.1. Normative References . . . . . . . . . . . . . . . . . . 133 172 14.2. Informative References . . . . . . . . . . . . . . . . . 135 173 Appendix A. Document History . . . . . . . . . . . . . . . . . . 136 174 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 139 175 Appendix C. Component Data Models . . . . . . . . . . . . . . . 141 176 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 142 177 D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 142 178 D.2. Secondary Device Interaction . . . . . . . . . . . . . . 146 179 D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 149 180 D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 150 181 D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 154 182 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 155 183 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 156 185 1. Introduction 187 This protocol allows a piece of software, the client instance, to 188 request delegated authorization to resource servers and to request 189 direct information. This delegation is facilitated by an 190 authorization server usually on behalf of a resource owner. The end- 191 user operating the software may interact with the authorization 192 server to authenticate, provide consent, and authorize the request. 194 The process by which the delegation happens is known as a grant, and 195 GNAP allows for the negotiation of the grant process over time by 196 multiple parties acting in distinct roles. 198 This specification focuses on the portions of the delegation process 199 facing the client instance. In particular, this specification 200 defines interoperable methods for a client instance to request, 201 negotiate, and receive access to information facilitated by the 202 authorization server. This specification also discusses discovery 203 mechanisms for the client instance to configure itself dynamically. 204 The means for an authorization server and resource server to 205 interoperate are discussed in the companion document, 206 [I-D.ietf-gnap-resource-servers]. 208 The focus of this protocol is to provide interoperability between the 209 different parties acting in each role, and is not to specify 210 implementation details of each. Where appropriate, GNAP may make 211 recommendations about internal implementation details, but these 212 recommendations are to ensure the security of the overall deployment 213 rather than to be prescriptive in the implementation. 215 This protocol solves many of the same use cases as OAuth 2.0 216 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 217 have grown up around that ecosystem. However, GNAP is not an 218 extension of OAuth 2.0 and is not intended to be directly compatible 219 with OAuth 2.0. GNAP seeks to provide functionality and solve use 220 cases that OAuth 2.0 cannot easily or cleanly address. Appendix B 221 further details the protocol rationale compared to OAuth 2.0. GNAP 222 and OAuth 2.0 will likely exist in parallel for many deployments, and 223 considerations have been taken to facilitate the mapping and 224 transition from legacy systems to GNAP. Some examples of these can 225 be found in Appendix D.5. 227 1.1. Terminology 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in 232 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 233 capitals, as shown here. 235 This document contains non-normative examples of partial and complete 236 HTTP messages, JSON structures, URLs, query components, keys, and 237 other elements. Some examples use a single trailing backslash \ to 238 indicate line wrapping for long values, as per [RFC8792]. The \ 239 character and leading spaces on wrapped lines are not part of the 240 value. 242 1.2. Roles 244 The parties in GNAP perform actions under different roles. Roles are 245 defined by the actions taken and the expectations leveraged on the 246 role by the overall protocol. 248 +-------------+ +------------+ 249 | | | | 250 |Authorization| | Resource | 251 | Server | | Server | 252 | |<-+ +---->| | 253 +-------------+ | | +------------+ 254 + | | 255 + | | 256 + | | 257 + | | 258 + | | 259 + +----------+ 260 + | Client | 261 + | Instance | 262 + +----------+ 263 + + 264 + + 265 + + 266 +-----------+ + +------------+ 267 | | + + + +| | 268 | Resource | | End | 269 | Owner | ~ ~ ~ ~ ~ ~ | User | 270 | | | | 271 +-----------+ +------------+ 273 Legend 275 + + + indicates interaction between a human and computer 276 ----- indicates interaction between two pieces of software 277 ~ ~ ~ indicates a potential equivalence or out-of-band 278 communication between roles 280 Authorization Server (AS) server that grants delegated privileges to 281 a particular instance of client software in the form of access 282 tokens or other information (such as subject information). 284 Client application that consumes resources from one or several RSs, 285 possibly requiring access privileges from one or several ASs. The 286 client is operated by the end-user or it runs autonomously on 287 behalf of a resource owner. 289 Example: a client can be a mobile application, a web application, 290 etc. 292 Note: this specification differentiates between a specific 293 instance (the client instance, identified by its unique key) and 294 the software running the instance (the client software). For some 295 kinds of client software, there could be many instances of that 296 software, each instance with a different key. 298 Resource Server (RS) server that provides operations on protected 299 resources, where operations require a valid access token issued by 300 an AS. 302 Resource Owner (RO) subject entity that may grant or deny operations 303 on resources it has authority upon. 305 Note: the act of granting or denying an operation may be manual 306 (i.e. through an interaction with a physical person) or automatic 307 (i.e. through predefined organizational rules). 309 End-user natural person that operates a client instance. 311 Note: that natural person may or may not be the same entity as the 312 RO. 314 The design of GNAP does not assume any one deployment architecture, 315 but instead attempts to define roles that can be fulfilled in a 316 number of different ways for different use cases. As long as a given 317 role fulfills all of its obligations and behaviors as defined by the 318 protocol, GNAP does not make additional requirements on its structure 319 or setup. 321 Multiple roles can be fulfilled by the same party, and a given party 322 can switch roles in different instances of the protocol. For 323 example, the RO and end-user in many instances are the same person, 324 where a user is authorizing the client instance to act on their own 325 behalf at the RS. In this case, one party fulfills both of the RO 326 and end-user roles, but the roles themselves are still defined 327 separately from each other to allow for other use cases where they 328 are fulfilled by different parties. 330 For another example, in some complex scenarios, an RS receiving 331 requests from one client instance can act as a client instance for a 332 downstream secondary RS in order to fulfill the original request. In 333 this case, one piece of software is both an RS and a client instance 334 from different perspectives, and it fulfills these roles separately 335 as far as the overall protocol is concerned. 337 A single role need not be deployed as a monolithic service. For 338 example, A client instance could have components that are installed 339 on the end-user's device as well as a back-end system that it 340 communicates with. If both of these components participate in the 341 delegation protocol, they are both considered part of the client 342 instance. If there are several copies of the client software that 343 run separately but all share the same key material, such as a 344 deployed cluster, then this cluster is considered a single client 345 instance. 347 In these cases, the distinct components of what is considered a GNAP 348 client instance may use any number of different communication 349 mechanisms between them, all of which would be considered an 350 implementation detail of the client instances and out of scope of 351 GNAP. 353 For another example, an AS could likewise be built out of many 354 constituent components in a distributed architecture. The component 355 that the client instance calls directly could be different from the 356 component that the RO interacts with to drive consent, since API 357 calls and user interaction have different security considerations in 358 many environments. Furthermore, the AS could need to collect 359 identity claims about the RO from one system that deals with user 360 attributes while generating access tokens at another system that 361 deals with security rights. From the perspective of GNAP, all of 362 these are pieces of the AS and together fulfill the role of the AS as 363 defined by the protocol. These pieces may have their own internal 364 communications mechanisms which are considered out of scope of GNAP. 366 1.3. Elements 368 In addition to the roles above, the protocol also involves several 369 elements that are acted upon by the roles throughout the process. 371 Attribute characteristics related to a subject. 373 Access Token a data artifact representing a set of rights and/or 374 attributes. 376 Note: an access token can be first issued to an client instance 377 (requiring authorization by the RO) and subsequently rotated. 379 Grant (verb): to permit an instance of client software to receive 380 some attributes at a specific time and valid for a specific 381 duration and/or to exercise some set of delegated rights to access 382 a protected resource (noun): the act of granting. 384 Privilege right or attribute associated with a subject. 386 Note: the RO defines and maintains the rights and attributes 387 associated to the protected resource, and might temporarily 388 delegate some set of those privileges to an end-user. This 389 process is refered to as privilege delegation. 391 Protected Resource protected API (Application Programming Interface) 392 served by an RS and that can be accessed by a client, if and only 393 if a valid access token is provided. 395 Note: to avoid complex sentences, the specification document may 396 simply refer to resource instead of protected resource. 398 Right ability given to a subject to perform a given operation on a 399 resource under the control of an RS. 401 Subject person, organization or device. It decides whether and 402 under which conditions its attributes can be disclosed to other 403 parties. 405 Subject Information statement asserted by an AS about a subject. 407 1.4. Trust relationships 409 GNAP defines its trust objective as: "the RO trusts the AS to ensure 410 access validation and delegation of protected resources to end-users, 411 through third party clients." 413 This trust objective can be decomposed into trust relationships 414 between software elements and roles, especially the pairs end-user/ 415 RO, end-user/client, client/AS, RS/RO, AS/RO, AS/RS. Trust of an 416 agent by its pair can exist if the pair is informed that the agent 417 has made a promise to follow the protocol in the past (e.g. pre- 418 registration, uncompromised cryptographic components) or if the pair 419 is able to infer by indirect means that the agent has made such a 420 promise (e.g. a compliant client request). Each agent defines its 421 own valuation function of promises given or received. Examples of 422 such valuations can be the benefits from interacting with other 423 agents (e.g. safety in client access, interoperability with identity 424 standards), the cost of following the protocol (including its 425 security and privacy requirements and recommendations), a ranking of 426 promise importance (e.g. a policy decision made by the AS), the 427 assessment of one's vulnerability or risk of not being able to defend 428 against threats, etc. Those valuations may depend on the context of 429 the request. For instance, the AS may decide to either take into 430 account or discard hints provided by the client, the RS may refuse 431 bearer tokens, etc. depending on the specific case in which GNAP is 432 used. Some promises can be conditional of some previous interactions 433 (e.g. repeated requests). 435 Looking back on each trust relationship: 437 * end-user/RO: this relationship exists only when the end-user and 438 the RO are different, in which case the end-user needs some out of 439 band mechanism of getting the RO consent (see Section 4). GNAP 440 generally assumes that humans can be authenticated thanks to 441 identity protocols (for instance, through an id_token assertion in 442 Section 2.2). 444 * end-user/client: the client acts as a user agent. Depending on 445 the technology used (browser, SPA, mobile application, IoT device, 446 etc.), some interactions may or may not be possible (as described 447 in Section 2.5.1). Client developers promise to implement 448 requirements and generally some recommendations or best practices, 449 so that the end-users may confidently use their software. 450 However, end-users might also be facing some attacker's client 451 software, without even realizing it. 453 * end-user / AS: when the client supports it (see Section 3.3), the 454 end-user gets to interact with front-channel URLs provided by the 455 AS. See Section 12.24 for some considerations in trusting these 456 interactions. 458 * client/AS: An honest AS may be facing an attacker's client (as 459 discussed just above), or the reverse, and GNAP aims at making 460 common attacks impractical. The core specification makes access 461 tokens opaque to the client and defines the request/response 462 scheme in detail, therefore avoiding extra trust hypotheses from 463 this critical piece of software. Yet the AS may further define 464 cryptographic attestations or optional rules to simplify the 465 access of clients it already trusts, due to past behavior or 466 organizational policies (see Section 2.3). 468 * RS/RO: the RS promises it protects its resources from unauthorized 469 access, and only accepts valid access tokens issued by a trusted 470 AS. In case tokens are key bound, proper validation is expected 471 from the RS. 473 * AS/RO: the AS is expected to follow the decisions made by the RO, 474 either through interactive consent requests, repeated interactions 475 or automated rules (as described in Section 1.5). Privacy 476 considerations aim to reduce the risk of an honest but too curious 477 AS, or the consequences of an unexpected user data exposure. 479 * AS/RS: the AS promises to issue valid access tokens to legitimate 480 client requests (i.e. after carrying out appropriate due 481 diligence, as defined in the GNAP protocol). Some optional 482 configurations are covered by [I-D.ietf-gnap-resource-servers]. 484 A global assumption made by GNAP is that authorization requests are 485 security and privacy sensitive, and appropriate measures are 486 respectively detailed in Section 12 and Section 13. 488 A formal trust model is out of scope of this specification, but might 489 be carried out thanks to [promise-theory]. 491 1.5. Sequences 493 GNAP can be used in a variety of ways to allow the core delegation 494 process to take place. Many portions of this process are 495 conditionally present depending on the context of the deployments, 496 and not every step in this overview will happen in all circumstances. 498 Note that a connection between roles in this process does not 499 necessarily indicate that a specific protocol message is sent across 500 the wire between the components fulfilling the roles in question, or 501 that a particular step is required every time. For example, for a 502 client instance interested in only getting subject information 503 directly, and not calling an RS, all steps involving the RS below do 504 not apply. 506 In some circumstances, the information needed at a given stage is 507 communicated out of band or is preconfigured between the components 508 or entities performing the roles. For example, one entity can fulfil 509 multiple roles, and so explicit communication between the roles is 510 not necessary within the protocol flow. Additionally some components 511 may not be involved in all use cases. For example, a client instance 512 could be calling the AS just to get direct user information and have 513 no need to get an access token to call an RS. 515 +------------+ +------------+ 516 | End-user | ~ ~ ~ ~ | Resource | 517 | | | Owner (RO) | 518 +------------+ +------------+ 519 + + 520 + + 521 (A) (B) 522 + + 523 + + 524 +--------+ + +------------+ 525 | Client | (1) + | Resource | 526 |Instance| + | Server | 527 | | +---------------+ | (RS) | 528 | |--(2)->| Authorization | | | 529 | |<-(3)--| Server | | | 530 | | | (AS) | | | 531 | |--(4)->| | | | 532 | |<-(5)--| | | | 533 | |--------------(6)------------->| | 534 | | | | (7) | | 535 | |<-------------(8)------------->| | 536 | |--(9)->| | | | 537 | |<-(10)-| | | | 538 | |--------------(11)------------>| | 539 | | | | (12) | | 540 | |-(13)->| | | | 541 | | | | | | 542 +--------+ +---------------+ +------------+ 544 Legend 545 + + + indicates a possible interaction with a human 546 ----- indicates an interaction between protocol roles 547 ~ ~ ~ indicates a potential equivalence or out-of-band 548 communication between roles 550 * (A) The end-user interacts with the client instance to indicate a 551 need for resources on behalf of the RO. This could identify the 552 RS the client instance needs to call, the resources needed, or the 553 RO that is needed to approve the request. Note that the RO and 554 end-user are often the same entity in practice, but GNAP makes no 555 general assumption that they are. 557 * (1) The client instance determines what access is needed and which 558 AS to approach for access. Note that for most situations, the 559 client instance is pre-configured with which AS to talk to and 560 which kinds of access it needs, but some more dynamic processes 561 are discussed in Section 9.1. 563 * (2) The client instance requests access at the AS (Section 2). 565 * (3) The AS processes the request and determines what is needed to 566 fulfill the request. (See Section 4.) The AS sends its response 567 to the client instance (Section 3). 569 * (B) If interaction is required, the AS interacts with the RO 570 (Section 4) to gather authorization. The interactive component of 571 the AS can function using a variety of possible mechanisms 572 including web page redirects, applications, challenge/response 573 protocols, or other methods. The RO approves the request for the 574 client instance being operated by the end-user. Note that the RO 575 and end-user are often the same entity in practice, and many of 576 GNAP's interaction methods allow the client instance to facilitate 577 the end user interacting with the AS in order to fulfill the role 578 of the RO. 580 * (4) The client instance continues the grant at the AS (Section 5). 582 * (5) If the AS determines that access can be granted, it returns a 583 response to the client instance (Section 3) including an access 584 token (Section 3.2) for calling the RS and any directly returned 585 information (Section 3.4) about the RO. 587 * (6) The client instance uses the access token (Section 7.2) to 588 call the RS. 590 * (7) The RS determines if the token is sufficient for the request 591 by examining the token. The means of the RS determining this 592 access are out of scope of this specification, but some options 593 are discussed in [I-D.ietf-gnap-resource-servers]. 595 * (8) The client instance calls the RS (Section 7.2) using the 596 access token until the RS or client instance determine that the 597 token is no longer valid. 599 * (9) When the token no longer works, the client instance fetches an 600 updated access token (Section 6.1) based on the rights granted in 601 (5). 603 * (10) The AS issues a new access token (Section 3.2) to the client 604 instance. 606 * (11) The client instance uses the new access token (Section 7.2) 607 to call the RS. 609 * (12) The RS determines if the new token is sufficient for the 610 request. The means of the RS determining this access are out of 611 scope of this specification, but some options are discussed in 612 [I-D.ietf-gnap-resource-servers]. 614 * (13) The client instance disposes of the token (Section 6.2) once 615 the client instance has completed its access of the RS and no 616 longer needs the token. 618 The following sections and Appendix D contain specific guidance on 619 how to use GNAP in different situations and deployments. For 620 example, it is possible for the client instance to never request an 621 access token and never call an RS, just as it is possible for there 622 not to be a user involved in the delegation process. 624 1.5.1. Redirect-based Interaction 626 In this example flow, the client instance is a web application that 627 wants access to resources on behalf of the current user, who acts as 628 both the end-user and the resource owner (RO). Since the client 629 instance is capable of directing the user to an arbitrary URL and 630 receiving responses from the user's browser, interaction here is 631 handled through front-channel redirects using the user's browser. 632 The redirection URL used for interaction is a service hosted by the 633 AS in this example. The client instance uses a persistent session 634 with the user to ensure the same user that is starting the 635 interaction is the user that returns from the interaction. 637 +--------+ +--------+ +------+ 638 | Client | | AS | | User | 639 |Instance| | | | | 640 | |< (1) + Start Session + + + + + + + + + + + + + + + +| | 641 | | | | | | 642 | |--(2)--- Request Access --------->| | | | 643 | | | | | | 644 | |<-(3)-- Interaction Needed -------| | | | 645 | | | | | | 646 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 647 | | | | | | 648 | | | |<+ (5) +>| | 649 | | | | AuthN | | 650 | | | | | | 651 | | | |<+ (6) +>| | 652 | | | | AuthZ | | 653 | | | | | | 654 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 655 | | | | +------+ 656 | |--(8)--- Continue Request ------->| | 657 | | | | 658 | |<-(9)----- Grant Access ----------| | 659 | | | | 660 | | | | +--------+ 661 | |--(10)-- Access API ---------------------------->| RS | 662 | | | | | | 663 | |<-(11)-- API Response ---------------------------| | 664 | | | | +--------+ 665 +--------+ +--------+ 667 1. The client instance establishes a verifiable session to the 668 user, in the role of the end-user. 670 2. The client instance requests access to the resource (Section 2). 671 The client instance indicates that it can redirect to an 672 arbitrary URL (Section 2.5.1.1) and receive a redirect from the 673 browser (Section 2.5.2.1). The client instance stores 674 verification information for its redirect in the session created 675 in (1). 677 3. The AS determines that interaction is needed and responds 678 (Section 3) with a URL to send the user to (Section 3.3.1) and 679 information needed to verify the redirect (Section 3.3.4) in 680 (7). The AS also includes information the client instance will 681 need to continue the request (Section 3.1) in (8). The AS 682 associates this continuation information with an ongoing request 683 that will be referenced in (4), (6), and (8). 685 4. The client instance stores the verification and continuation 686 information from (3) in the session from (1). The client 687 instance then redirects the user to the URL (Section 4.1.1) 688 given by the AS in (3). The user's browser loads the 689 interaction redirect URL. The AS loads the pending request 690 based on the incoming URL generated in (3). 692 5. The user authenticates at the AS, taking on the role of the RO. 694 6. As the RO, the user authorizes the pending request from the 695 client instance. 697 7. When the AS is done interacting with the user, the AS redirects 698 the user back (Section 4.2.1) to the client instance using the 699 redirect URL provided in (2). The redirect URL is augmented 700 with an interaction reference that the AS associates with the 701 ongoing request created in (2) and referenced in (4). The 702 redirect URL is also augmented with a hash of the security 703 information provided in (2) and (3). The client instance loads 704 the verification information from (2) and (3) from the session 705 created in (1). The client instance calculates a hash 706 (Section 4.2.3) based on this information and continues only if 707 the hash validates. Note that the client instance needs to 708 ensure that the parameters for the incoming request match those 709 that it is expecting from the session created in (1). The 710 client instance also needs to be prepared for the end-user never 711 being returned to the client instance and handle timeouts 712 appropriately. 714 8. The client instance loads the continuation information from (3) 715 and sends the interaction reference from (7) in a request to 716 continue the request (Section 5.1). The AS validates the 717 interaction reference ensuring that the reference is associated 718 with the request being continued. 720 9. If the request has been authorized, the AS grants access to the 721 information in the form of access tokens (Section 3.2) and 722 direct subject information (Section 3.4) to the client instance. 724 10. The client instance uses the access token (Section 7.2) to call 725 the RS. 727 11. The RS validates the access token and returns an appropriate 728 response for the API. 730 An example set of protocol messages for this method can be found in 731 Appendix D.1. 733 1.5.2. User-code Interaction 735 In this example flow, the client instance is a device that is capable 736 of presenting a short, human-readable code to the user and directing 737 the user to enter that code at a known URL. The URL the user enters 738 the code at is an interactive service hosted by the AS in this 739 example. The client instance is not capable of presenting an 740 arbitrary URL to the user, nor is it capable of accepting incoming 741 HTTP requests from the user's browser. The client instance polls the 742 AS while it is waiting for the RO to authorize the request. The 743 user's interaction is assumed to occur on a secondary device. In 744 this example it is assumed that the user is both the end-user and RO, 745 though the user is not assumed to be interacting with the client 746 instance through the same web browser used for interaction at the AS. 748 +--------+ +--------+ +------+ 749 | Client | | AS | | User | 750 |Instance|--(1)--- Request Access --------->| | | | 751 | | | | | | 752 | |<-(2)-- Interaction Needed -------| | | | 753 | | | | | | 754 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 755 | | | | | | 756 | | | |<+ (4) + | | 757 | | | |Open URI | | 758 | | | | | | 759 | | | |<+ (5) +>| | 760 | | | | AuthN | | 761 | |--(9)--- Continue Request (A) --->| | | | 762 | | | |<+ (6) +>| | 763 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 764 | | | | | | 765 | | | |<+ (7) +>| | 766 | | | | AuthZ | | 767 | | | | | | 768 | | | |<+ (8) +>| | 769 | | | |Completed| | 770 | | | | | | 771 | |--(11)-- Continue Request (B) --->| | +------+ 772 | | | | 773 | |<-(12)----- Grant Access ---------| | 774 | | | | 775 | | | | +--------+ 776 | |--(13)-- Access API ---------------------------->| RS | 777 | | | | | | 778 | |<-(14)-- API Response ---------------------------| | 779 | | | | +--------+ 780 +--------+ +--------+ 781 1. The client instance requests access to the resource (Section 2). 782 The client instance indicates that it can display a user code 783 (Section 2.5.1.3). 785 2. The AS determines that interaction is needed and responds 786 (Section 3) with a user code to communicate to the user 787 (Section 3.3.3). This could optionally include a URL to direct 788 the user to, but this URL should be static and so could be 789 configured in the client instance's documentation. The AS also 790 includes information the client instance will need to continue 791 the request (Section 3.1) in (8) and (10). The AS associates 792 this continuation information with an ongoing request that will 793 be referenced in (4), (6), (8), and (10). 795 3. The client instance stores the continuation information from (2) 796 for use in (8) and (10). The client instance then communicates 797 the code to the user (Section 4.1.1) given by the AS in (2). 799 4. The user's directs their browser to the user code URL. This URL 800 is stable and can be communicated via the client software's 801 documentation, the AS documentation, or the client software 802 itself. Since it is assumed that the RO will interact with the 803 AS through a secondary device, the client instance does not 804 provide a mechanism to launch the RO's browser at this URL. 806 5. The end-user authenticates at the AS, taking on the role of the 807 RO. 809 6. The RO enters the code communicated in (3) to the AS. The AS 810 validates this code against a current request in process. 812 7. As the RO, the user authorizes the pending request from the 813 client instance. 815 8. When the AS is done interacting with the user, the AS indicates 816 to the RO that the request has been completed. 818 9. Meanwhile, the client instance loads the continuation 819 information stored at (3) and continues the request (Section 5). 820 The AS determines which ongoing access request is referenced 821 here and checks its state. 823 10. If the access request has not yet been authorized by the RO in 824 (6), the AS responds to the client instance to continue the 825 request (Section 3.1) at a future time through additional polled 826 continuation requests. This response can include updated 827 continuation information as well as information regarding how 828 long the client instance should wait before calling again. The 829 client instance replaces its stored continuation information 830 from the previous response (2). Note that the AS may need to 831 determine that the RO has not approved the request in a 832 sufficient amount of time and return an appropriate error to the 833 client instance. 835 11. The client instance continues to poll the AS (Section 5.2) with 836 the new continuation information in (9). 838 12. If the request has been authorized, the AS grants access to the 839 information in the form of access tokens (Section 3.2) and 840 direct subject information (Section 3.4) to the client instance. 842 13. The client instance uses the access token (Section 7.2) to call 843 the RS. 845 14. The RS validates the access token and returns an appropriate 846 response for the API. 848 An example set of protocol messages for this method can be found in 849 Appendix D.2. 851 1.5.3. Asynchronous Authorization 853 In this example flow, the end-user and RO roles are fulfilled by 854 different parties, and the RO does not interact with the client 855 instance. The AS reaches out asynchronously to the RO during the 856 request process to gather the RO's authorization for the client 857 instance's request. The client instance polls the AS while it is 858 waiting for the RO to authorize the request. 860 +--------+ +--------+ +------+ 861 | Client | | AS | | RO | 862 |Instance|--(1)--- Request Access --------->| | | | 863 | | | | | | 864 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 865 | | | |<+ (3) +>| | 866 | | | | AuthN | | 867 | |--(6)--- Continue Request (A) --->| | | | 868 | | | |<+ (4) +>| | 869 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 870 | | | | | | 871 | | | |<+ (5) +>| | 872 | | | |Completed| | 873 | | | | | | 874 | |--(8)--- Continue Request (B) --->| | +------+ 875 | | | | 876 | |<-(9)------ Grant Access ---------| | 877 | | | | 878 | | | | +--------+ 879 | |--(10)-- Access API ---------------------------->| RS | 880 | | | | | | 881 | |<-(11)-- API Response ---------------------------| | 882 | | | | +--------+ 883 +--------+ +--------+ 885 1. The client instance requests access to the resource (Section 2). 886 The client instance does not send any interactions modes to the 887 server, indicating that it does not expect to interact with the 888 RO. The client instance can also signal which RO it requires 889 authorization from, if known, by using the user request section 890 (Section 2.4). 892 2. The AS determines that interaction is needed, but the client 893 instance cannot interact with the RO. The AS responds 894 (Section 3) with the information the client instance will need 895 to continue the request (Section 3.1) in (6) and (8), including 896 a signal that the client instance should wait before checking 897 the status of the request again. The AS associates this 898 continuation information with an ongoing request that will be 899 referenced in (3), (4), (5), (6), and (8). 901 3. The AS determines which RO to contact based on the request in 902 (1), through a combination of the user request (Section 2.4), 903 the resources request (Section 2.1), and other policy 904 information. The AS contacts the RO and authenticates them. 906 4. The RO authorizes the pending request from the client instance. 908 5. When the AS is done interacting with the RO, the AS indicates to 909 the RO that the request has been completed. 911 6. Meanwhile, the client instance loads the continuation 912 information stored at (2) and continues the request (Section 5). 913 The AS determines which ongoing access request is referenced 914 here and checks its state. 916 7. If the access request has not yet been authorized by the RO in 917 (6), the AS responds to the client instance to continue the 918 request (Section 3.1) at a future time through additional 919 polling. This response can include refreshed credentials as 920 well as information regarding how long the client instance 921 should wait before calling again. The client instance replaces 922 its stored continuation information from the previous response 923 (2). Note that the AS may need to determine that the RO has not 924 approved the request in a sufficient amount of time and return 925 an appropriate error to the client instance. 927 8. The client instance continues to poll the AS (Section 5.2) with 928 the new continuation information from (7). 930 9. If the request has been authorized, the AS grants access to the 931 information in the form of access tokens (Section 3.2) and 932 direct subject information (Section 3.4) to the client instance. 934 10. The client instance uses the access token (Section 7.2) to call 935 the RS. 937 11. The RS validates the access token and returns an appropriate 938 response for the API. 940 An example set of protocol messages for this method can be found in 941 Appendix D.4. 943 1.5.4. Software-only Authorization 945 In this example flow, the AS policy allows the client instance to 946 make a call on its own behalf, without the need for a RO to be 947 involved at runtime to approve the decision. Since there is no 948 explicit RO, the client instance does not interact with an RO. 950 +--------+ +--------+ 951 | Client | | AS | 952 |Instance|--(1)--- Request Access --->| | 953 | | | | 954 | |<-(2)---- Grant Access -----| | 955 | | | | +--------+ 956 | |--(3)--- Access API ------------------->| RS | 957 | | | | | | 958 | |<-(4)--- API Response ------------------| | 959 | | | | +--------+ 960 +--------+ +--------+ 962 1. The client instance requests access to the resource (Section 2). 963 The client instance does not send any interactions modes to the 964 server. 966 2. The AS determines that the request is been authorized, the AS 967 grants access to the information in the form of access tokens 968 (Section 3.2) to the client instance. Note that direct subject 969 information (Section 3.4) is not generally applicable in this use 970 case, as there is no user involved. 972 3. The client instance uses the access token (Section 7.2) to call 973 the RS. 975 4. The RS validates the access token and returns an appropriate 976 response for the API. 978 An example set of protocol messages for this method can be found in 979 Appendix D.3. 981 1.5.5. Refreshing an Expired Access Token 983 In this example flow, the client instance receives an access token to 984 access a resource server through some valid GNAP process. The client 985 instance uses that token at the RS for some time, but eventually the 986 access token expires. The client instance then gets a new access 987 token by rotating the expired access token at the AS using the 988 token's management URL. 990 +--------+ +--------+ 991 | Client | | AS | 992 |Instance|--(1)--- Request Access ----------------->| | 993 | | | | 994 | |<-(2)--- Grant Access --------------------| | 995 | | | | 996 | | +--------+ | | 997 | |--(3)--- Access Resource --->| RS | | | 998 | | | | | | 999 | |<-(4)--- Success Response ---| | | | 1000 | | | | | | 1001 | | | | | | 1002 | | | | | | 1003 | |--(5)--- Access Resource --->| | | | 1004 | | | | | | 1005 | |<-(6)--- Error Response -----| | | | 1006 | | +--------+ | | 1007 | | | | 1008 | |--(7)--- Rotate Token ------------------->| | 1009 | | | | 1010 | |<-(8)--- Rotated Token -------------------| | 1011 | | | | 1012 +--------+ +--------+ 1014 1. The client instance requests access to the resource (Section 2). 1016 2. The AS grants access to the resource (Section 3) with an access 1017 token (Section 3.2) usable at the RS. The access token response 1018 includes a token management URI. 1020 3. The client instance uses the access token (Section 7.2) to call 1021 the RS. 1023 4. The RS validates the access token and returns an appropriate 1024 response for the API. 1026 5. Time passes and the client instance uses the access token to call 1027 the RS again. 1029 6. The RS validates the access token and determines that the access 1030 token is expired The RS responds to the client instance with an 1031 error. 1033 7. The client instance calls the token management URI returned in 1034 (2) to rotate the access token (Section 6.1). The client 1035 instance uses the access token (Section 7.2) in this call as well 1036 as the appropriate key, see the token rotation section for 1037 details. 1039 8. The AS validates the rotation request including the signature and 1040 keys presented in (5) and returns a new access token 1041 (Section 3.2.1). The response includes a new access token and 1042 can also include updated token management information, which the 1043 client instance will store in place of the values returned in 1044 (2). 1046 1.5.6. Requesting User Information 1048 In this scenario, the client instance does not call an RS and does 1049 not request an access token. Instead, the client instance only 1050 requests and is returned direct subject information (Section 3.4). 1051 Many different interaction modes can be used in this scenario, so 1052 these are shown only in the abstract as functions of the AS here. 1054 +--------+ +--------+ +------+ 1055 | Client | | AS | | User | 1056 |Instance| | | | | 1057 | |--(1)--- Request Access --------->| | | | 1058 | | | | | | 1059 | |<-(2)-- Interaction Needed -------| | | | 1060 | | | | | | 1061 | |+ (3) + Facilitate Interaction + + + + + + + + + + > | | 1062 | | | | | | 1063 | | | |<+ (4) +>| | 1064 | | | | AuthN | | 1065 | | | | | | 1066 | | | |<+ (5) +>| | 1067 | | | | AuthZ | | 1068 | | | | | | 1069 | |< (6) + Signal Continuation + + + + + + + + + + + + +| | 1070 | | | | +------+ 1071 | |--(7)--- Continue Request ------->| | 1072 | | | | 1073 | |<-(8)----- Grant Access ----------| | 1074 | | | | 1075 +--------+ +--------+ 1077 1. The client instance requests access to subject information 1078 (Section 2). 1080 2. The AS determines that interaction is needed and responds 1081 (Section 3) with appropriate information for facilitating user 1082 interaction (Section 3.3). 1084 3. The client instance facilitates the user interacting with the AS 1085 (Section 4) as directed in (2). 1087 4. The user authenticates at the AS, taking on the role of the RO. 1089 5. As the RO, the user authorizes the pending request from the 1090 client instance. 1092 6. When the AS is done interacting with the user, the AS returns the 1093 user to the client instance and signals continuation. 1095 7. The client instance loads the continuation information from (2) 1096 and calls the AS to continue the request (Section 5). 1098 8. If the request has been authorized, the AS grants access to the 1099 requested direct subject information (Section 3.4) to the client 1100 instance. At this stage, the user is generally considered 1101 "logged in" to the client instance based on the identifiers and 1102 assertions provided by the AS. Note that the AS can restrict the 1103 subject information returned and it might not match what the 1104 client instance requested, see the section on subject information 1105 for details. 1107 2. Requesting Access 1109 To start a request, the client instance sends JSON [RFC8259] document 1110 with an object as its root. Each member of the request object 1111 represents a different aspect of the client instance's request. Each 1112 field is described in detail in a section below. 1114 access_token (object / array of objects) Describes the rights and 1115 properties associated with the requested access token. 1116 Section 2.1 1118 subject (object) Describes the information about the RO that the 1119 client instance is requesting to be returned directly in the 1120 response from the AS. Section 2.2 1122 client (object / string) Describes the client instance that is 1123 making this request, including the key that the client instance 1124 will use to protect this request and any continuation requests at 1125 the AS and any user-facing information about the client instance 1126 used in interactions. Section 2.3 1128 user (object / string) Identifies the end-user to the AS in a manner 1129 that the AS can verify, either directly or by interacting with the 1130 end-user to determine their status as the RO. Section 2.4 1132 interact (object) Describes the modes that the client instance has 1133 for allowing the RO to interact with the AS and modes for the 1134 client instance to receive updates when interaction is complete. 1135 Section 2.5 1137 Additional members of this request object can be defined by 1138 extensions to this protocol as described in Section 2.6 1140 A non-normative example of a grant request is below: 1142 { 1143 "access_token": { 1144 "access": [ 1145 { 1146 "type": "photo-api", 1147 "actions": [ 1148 "read", 1149 "write", 1150 "dolphin" 1151 ], 1152 "locations": [ 1153 "https://server.example.net/", 1154 "https://resource.local/other" 1155 ], 1156 "datatypes": [ 1157 "metadata", 1158 "images" 1159 ] 1160 }, 1161 "dolphin-metadata" 1162 ] 1163 }, 1164 "client": { 1165 "display": { 1166 "name": "My Client Display Name", 1167 "uri": "https://example.net/client" 1168 }, 1169 "key": { 1170 "proof": "httpsig", 1171 "jwk": { 1172 "kty": "RSA", 1173 "e": "AQAB", 1174 "kid": "xyz-1", 1175 "alg": "RS256", 1176 "n": "kOB5rR4Jv0GMeL...." 1177 } 1178 } 1179 }, 1180 "interact": { 1181 "start": ["redirect"], 1182 "finish": { 1183 "method": "redirect", 1184 "uri": "https://client.example.net/return/123455", 1185 "nonce": "LKLTI25DK82FX4T4QFZC" 1186 } 1187 }, 1188 "subject": { 1189 "formats": ["iss_sub", "opaque"], 1190 "assertions": ["id_token"] 1191 } 1192 } 1194 The request and response MUST be sent as a JSON object in the body of 1195 the HTTP POST request with Content-Type application/json, unless 1196 otherwise specified by the signature mechanism. 1198 The authorization server MUST include the HTTP "Cache-Control" 1199 response header field [RFC7234] with a value set to "no-store". 1201 2.1. Requesting Access to Resources 1203 If the client instance is requesting one or more access tokens for 1204 the purpose of accessing an API, the client instance MUST include an 1205 access_token field. This field MUST be an object (for a single 1206 access token (Section 2.1.1)) or an array of these objects (for 1207 multiple access tokens (Section 2.1.2)), as described in the 1208 following sections. 1210 2.1.1. Requesting a Single Access Token 1212 To request a single access token, the client instance sends an 1213 acccess_token object composed of the following fields. 1215 access (array of objects/strings) Describes the rights that the 1216 client instance is requesting for one or more access tokens to be 1217 used at RS's. This field is REQUIRED. Section 8 1219 label (string) A unique name chosen by the client instance to refer 1220 to the resulting access token. The value of this field is opaque 1221 to the AS. If this field is included in the request, the AS MUST 1222 include the same label in the token response (Section 3.2). This 1223 field is REQUIRED if used as part of a multiple access token 1224 request (Section 2.1.2), and is OPTIONAL otherwise. 1226 flags (array of strings) A set of flags that indicate desired 1227 attributes or behavior to be attached to the access token by the 1228 AS. This field is OPTIONAL. 1230 The values of the flags field defined by this specification are as 1231 follows: 1233 "bearer" If this flag is included, the access token being requested 1234 is a bearer token. If this flag is omitted, the access token is 1235 bound to the key used by the client instance in this request (or 1236 that key's most recent rotation) and the access token MUST be 1237 presented using the same key and proofing method. Methods for 1238 presenting bound and bearer access tokens are described in 1239 Section 7.2. See Section 12.7 for additional considerations on 1240 the use of bearer tokens. 1242 "split" If this flag is included, the client instance is capable of 1243 receiving a different number of tokens than specified in the token 1244 request (Section 2.1), including receiving multiple access tokens 1245 (Section 3.2.2) in response to any single token request 1246 (Section 2.1.1) or a different number of access tokens than 1247 requested in a multiple access token request (Section 2.1.2). The 1248 label fields of the returned additional tokens are chosen by the 1249 AS. The client instance MUST be able to tell from the token 1250 response where and how it can use each of the access tokens. [[ 1251 See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1252 issues/37) ]] 1254 Flag values MUST NOT be included more than once. 1256 Additional flags can be defined by extensions using a registry TBD 1257 (Section 11). 1259 In the following example, the client instance is requesting access to 1260 a complex resource described by a pair of access request object. 1262 "access_token": { 1263 "access": [ 1264 { 1265 "type": "photo-api", 1266 "actions": [ 1267 "read", 1268 "write", 1269 "delete" 1270 ], 1271 "locations": [ 1272 "https://server.example.net/", 1273 "https://resource.local/other" 1274 ], 1275 "datatypes": [ 1276 "metadata", 1277 "images" 1278 ] 1279 }, 1280 { 1281 "type": "walrus-access", 1282 "actions": [ 1283 "foo", 1284 "bar" 1285 ], 1286 "locations": [ 1287 "https://resource.other/" 1288 ], 1289 "datatypes": [ 1290 "data", 1291 "pictures", 1292 "walrus whiskers" 1293 ] 1294 } 1295 ], 1296 "label": "token1-23", 1297 "flags": [ "split" ] 1298 } 1300 If access is approved, the resulting access token is valid for the 1301 described resource and is bound to the client instance's key (or its 1302 most recent rotation). The token is labeled "token1-23" and could be 1303 split into multiple access tokens by the AS, if the AS chooses. The 1304 token response structure is described in Section 3.2.1. 1306 2.1.2. Requesting Multiple Access Tokens 1308 To request multiple access tokens to be returned in a single 1309 response, the client instance sends an array of objects as the value 1310 of the access_token parameter. Each object MUST conform to the 1311 request format for a single access token request, as specified in 1312 requesting a single access token (Section 2.1.1). Additionally, each 1313 object in the array MUST include the label field, and all values of 1314 these fields MUST be unique within the request. If the client 1315 instance does not include a label value for any entry in the array, 1316 or the values of the label field are not unique within the array, the 1317 AS MUST return an error. 1319 The following non-normative example shows a request for two separate 1320 access tokens, token1 and token2. 1322 "access_token": [ 1323 { 1324 "label": "token1", 1325 "access": [ 1326 { 1327 "type": "photo-api", 1328 "actions": [ 1329 "read", 1330 "write", 1331 "dolphin" 1332 ], 1333 "locations": [ 1334 "https://server.example.net/", 1335 "https://resource.local/other" 1336 ], 1337 "datatypes": [ 1338 "metadata", 1339 "images" 1340 ] 1341 }, 1342 "dolphin-metadata" 1343 ] 1344 }, 1345 { 1346 "label": "token2", 1347 "access": [ 1348 { 1349 "type": "walrus-access", 1350 "actions": [ 1351 "foo", 1352 "bar" 1353 ], 1354 "locations": [ 1355 "https://resource.other/" 1356 ], 1357 "datatypes": [ 1358 "data", 1359 "pictures", 1360 "walrus whiskers" 1361 ] 1362 } 1363 ], 1364 "flags": [ "bearer" ] 1365 } 1366 ] 1367 All approved access requests are returned in the multiple access 1368 token response (Section 3.2.2) structure using the values of the 1369 label fields in the request. 1371 2.2. Requesting Subject Information 1373 If the client instance is requesting information about the RO from 1374 the AS, it sends a subject field as a JSON object. This object MAY 1375 contain the following fields (or additional fields defined in a 1376 registry TBD (Section 11)). 1378 formats (array of strings) An array of subject identifier subject 1379 types requested for the RO, as defined by 1380 [I-D.ietf-secevent-subject-identifiers]. 1382 assertions (array of strings) An array of requested assertion 1383 formats. Possible values include id_token for an [OIDC] ID Token 1384 and saml2 for a SAML 2 assertion. Additional assertion values are 1385 defined by a registry TBD (Section 11). [[ See issue #41 1386 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] 1388 "subject": { 1389 "formats": [ "iss_sub", "opaque" ], 1390 "assertions": [ "id_token", "saml2" ] 1391 } 1393 The AS can determine the RO's identity and permission for releasing 1394 this information through interaction with the RO (Section 4), AS 1395 policies, or assertions presented by the client instance 1396 (Section 2.4). If this is determined positively, the AS MAY return 1397 the RO's information in its response (Section 3.4) as requested. 1399 Subject identifier types requested by the client instance serve only 1400 to identify the RO in the context of the AS and can't be used as 1401 communication channels by the client instance, as discussed in 1402 Section 3.4. 1404 The AS SHOULD NOT re-use subject identifiers for multiple different 1405 ROs. 1407 Note: the "formats" and "assertions" request fields are independent 1408 of each other, and a returned assertion MAY use a different subject 1409 identifier. 1411 [[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1412 issues/43) ]] 1414 2.3. Identifying the Client Instance 1416 When sending a non-continuation request to the AS, the client 1417 instance MUST identify itself by including the client field of the 1418 request and by signing the request as described in Section 7.3. Note 1419 that for a continuation request (Section 5), the client instance is 1420 identified by its association with the request being continued and so 1421 this field is not sent under those circumstances. 1423 When client instance information is sent by value, the client field 1424 of the request consists of a JSON object with the following fields. 1426 key (object / string) The public key of the client instance to be 1427 used in this request as described in Section 7.1 or a reference to 1428 a key as described in Section 7.1.1. This field is REQUIRED. 1430 class_id (string) An identifier string that the AS can use to 1431 identify the client software comprising this client instance. The 1432 contents and format of this field are up to the AS. This field is 1433 OPTIONAL. 1435 display (object) An object containing additional information that 1436 the AS MAY display to the RO during interaction, authorization, 1437 and management. This field is OPTIONAL. 1439 "client": { 1440 "key": { 1441 "proof": "httpsig", 1442 "jwk": { 1443 "kty": "RSA", 1444 "e": "AQAB", 1445 "kid": "xyz-1", 1446 "alg": "RS256", 1447 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 1448 }, 1449 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1450 }, 1451 "class_id": "web-server-1234", 1452 "display": { 1453 "name": "My Client Display Name", 1454 "uri": "https://example.net/client" 1455 } 1456 } 1458 Additional fields are defined in a registry TBD (Section 11). 1460 The client instance MUST prove possession of any presented key by the 1461 proof mechanism associated with the key in the request. Proof types 1462 are defined in a registry TBD (Section 11) and an initial set of 1463 methods is described in Section 7.3. 1465 If the same public key is sent by value on different access requests, 1466 the AS MUST treat these requests as coming from the same client 1467 instance for purposes of identification, authentication, and policy 1468 application. If the AS does not know the client instance's public 1469 key ahead of time, the AS MAY accept or reject the request based on 1470 AS policy, attestations within the client request, and other 1471 mechanisms. 1473 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1474 issues/44) ]] 1476 The client instance MUST NOT send a symmetric key by value in the 1477 request, as doing so would expose the key directly instead of simply 1478 proving possession of it. See considerations on symmetric keys in 1479 Section 12.5. 1481 The client instance's key MAY be pre-registered with the AS ahead of 1482 time and associated with a set of policies and allowable actions 1483 pertaining to that client. If this pre-registration includes other 1484 fields that can occur in the client request object described in this 1485 section, such as class_id or display, the pre-registered values MUST 1486 take precedence over any values given at runtime. Additional fields 1487 sent during a request but not present in a pre-registered client 1488 instance record at the AS SHOULD NOT be added to the client's pre- 1489 registered record. See additional considerations regarding client 1490 instance impersonation in Section 12.13. 1492 2.3.1. Identifying the Client Instance by Reference 1494 If the client instance has an instance identifier that the AS can use 1495 to determine appropriate key information, the client instance can 1496 send this instance identifier as a direct reference value in lieu of 1497 the client object. The instance identifier MAY be assigned to a 1498 client instance at runtime through the Section 3.5 or MAY be obtained 1499 in another fashion, such as a static registration process at the AS. 1501 "client": "client-541-ab" 1503 When the AS receives a request with an instance identifier, the AS 1504 MUST ensure that the key used to sign the request (Section 7.3) is 1505 associated with the instance identifier. 1507 If the AS does not recognize the instance identifier, the request 1508 MUST be rejected with an error. 1510 If the client instance is identified in this manner, the registered 1511 key for the client instance MAY be a symmetric key known to the AS. 1512 See considerations on symmetric keys in Section 12.5. 1514 2.3.2. Providing Displayable Client Instance Information 1516 If the client instance has additional information to display to the 1517 RO during any interactions at the AS, it MAY send that information in 1518 the "display" field. This field is a JSON object that declares 1519 information to present to the RO during any interactive sequences. 1521 name (string) Display name of the client software 1523 uri (string) User-facing web page of the client software 1525 logo_uri (string) Display image to represent the client software 1527 "display": { 1528 "name": "My Client Display Name", 1529 "uri": "https://example.net/client" 1530 } 1532 [[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1533 issues/48) ]] 1535 Additional display fields are defined by a registry TBD (Section 11). 1537 The AS SHOULD use these values during interaction with the RO. The 1538 values are for informational purposes only and MUST NOT be taken as 1539 authentic proof of the client instance's identity or source. The AS 1540 MAY restrict display values to specific client instances, as 1541 identified by their keys in Section 2.3. See additional 1542 considerations for displayed client information in Section 12.13. 1544 2.3.3. Authenticating the Client Instance 1546 If the presented key is known to the AS and is associated with a 1547 single instance of the client software, the process of presenting a 1548 key and proving possession of that key is sufficient to authenticate 1549 the client instance to the AS. The AS MAY associate policies with 1550 the client instance identified by this key, such as limiting which 1551 resources can be requested and which interaction methods can be used. 1552 For example, only specific client instances with certain known keys 1553 might be trusted with access tokens without the AS interacting 1554 directly with the RO as in Appendix D.3. 1556 The presentation of a key allows the AS to strongly associate 1557 multiple successive requests from the same client instance with each 1558 other. This is true when the AS knows the key ahead of time and can 1559 use the key to authenticate the client instance, but also if the key 1560 is ephemeral and created just for this series of requests. As such 1561 the AS MAY allow for client instances to make requests with unknown 1562 keys. This pattern allows for ephemeral client instances, such as 1563 single-page applications, and client software with many individual 1564 long-lived instances, such as mobile applications, to generate key 1565 pairs per instance and use the keys within the protocol without 1566 having to go through a separate registration step. The AS MAY limit 1567 which capabilities are made available to client instances with 1568 unknown keys. For example, the AS could have a policy saying that 1569 only previously-registered client instances can request particular 1570 resources, or that all client instances with unknown keys have to be 1571 interactively approved by an RO. 1573 2.4. Identifying the User 1575 If the client instance knows the identity of the end-user through one 1576 or more identifiers or assertions, the client instance MAY send that 1577 information to the AS in the "user" field. The client instance MAY 1578 pass this information by value or by reference. 1580 sub_ids (array of objects) An array of subject identifiers for the 1581 end-user, as defined by [I-D.ietf-secevent-subject-identifiers]. 1583 assertions (object) An object containing assertions as values keyed 1584 on the assertion type defined by a registry TBD (Section 11). 1585 Possible keys include id_token for an [OIDC] ID Token and saml2 1586 for a SAML 2 assertion. The assertion values are the string 1587 serialization of the assertion format, encoded as a plain JSON 1588 string. Additional assertion types are defined by a registry TBD 1589 (Section 11). [[ See issue #41 (https://github.com/ietf-wg-gnap/ 1590 gnap-core-protocol/issues/41) ]] 1592 "user": { 1593 "sub_ids": [ { 1594 "format": "opaque", 1595 "id": "J2G8G8O4AZ" 1596 } ], 1597 "assertions": { 1598 "id_token": "eyj..." 1599 } 1600 } 1601 Subject identifiers are hints to the AS in determining the RO and 1602 MUST NOT be taken as declarative statements that a particular RO is 1603 present at the client instance and acting as the end-user. 1604 Assertions SHOULD be validated by the AS. [[ See issue #49 1605 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1607 If the identified end-user does not match the RO present at the AS 1608 during an interaction step, the AS SHOULD reject the request with an 1609 error. 1611 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1612 issues/50) ]] 1614 If the AS trusts the client instance to present verifiable 1615 assertions, the AS MAY decide, based on its policy, to skip 1616 interaction with the RO, even if the client instance provides one or 1617 more interaction modes in its request. 1619 See Section 12.25 for considerations that the AS has to make when 1620 accepting and processing assertions from the client instance. 1622 2.4.1. Identifying the User by Reference 1624 The AS can identify the current end-user to the client instance with 1625 a reference which can be used by the client instance to refer to the 1626 end-user across multiple requests. If the client instance has a 1627 reference for the end-user at this AS, the client instance MAY pass 1628 that reference as a string. The format of this string is opaque to 1629 the client instance. 1631 "user": "XUT2MFM1XBIKJKSDU8QM" 1633 One means of dynamically obtaining such a user reference is from the 1634 AS returning an opaque subject identifier as described in 1635 Section 3.4. Other means of configuring a client instance with a 1636 user identifier are out of scope of this specification. 1638 User reference identifiers are not intended to be human-readable user 1639 identifiers or structured assertions. For the client instance to 1640 send either of these, use the full user request object (Section 2.4) 1641 instead. 1643 If the AS does not recognize the user reference, it MUST return an 1644 error. 1646 2.5. Interacting with the User 1648 Often, the AS will require interaction with the RO (Section 4) in 1649 order to approve a requested delegation to the client instance for 1650 both access to resources and direct subject information. Many times 1651 the end-user using the client instance is the same person as the RO, 1652 and the client instance can directly drive interaction with the end 1653 user by facilitating the process through means such as redirection to 1654 a URL or launching an application. Other times, the client instance 1655 can provide information to start the RO's interaction on a secondary 1656 device, or the client instance will wait for the RO to approve the 1657 request asynchronously. The client instance could also be signaled 1658 that interaction has concluded through a callback mechanism. 1660 The client instance declares the parameters for interaction methods 1661 that it can support using the interact field. 1663 The interact field is a JSON object with three keys whose values 1664 declare how the client can initiate and complete the request, as well 1665 as provide hints to the AS about user preferences such as locale. A 1666 client instance MUST NOT declare an interaction mode it does not 1667 support. The client instance MAY send multiple modes in the same 1668 request. There is no preference order specified in this request. An 1669 AS MAY respond to any, all, or none of the presented interaction 1670 modes (Section 3.3) in a request, depending on its capabilities and 1671 what is allowed to fulfill the request. 1673 start (list of strings/objects) Indicates how the client instance 1674 can start an interaction. 1676 finish (object) Indicates how the client instance can receive an 1677 indication that interaction has finished at the AS. 1679 hints (object) Provides additional information to inform the 1680 interaction process at the AS. 1682 The interact field MUST contain the start key, and MAY contain the 1683 finish and hints keys. The value of each key is an array which 1684 contains strings or JSON objects as defined below. 1686 In this non-normative example, the client instance is indicating that 1687 it can redirect (Section 2.5.1.1) the end-user to an arbitrary URL 1688 and can receive a redirect (Section 2.5.2.1) through a browser 1689 request. 1691 "interact": { 1692 "start": ["redirect"], 1693 "finish": { 1694 "method": "redirect", 1695 "uri": "https://client.example.net/return/123455", 1696 "nonce": "LKLTI25DK82FX4T4QFZC" 1697 } 1698 } 1700 In this non-normative example, the client instance is indicating that 1701 it can display a user code (Section 2.5.1.3) and direct the end-user 1702 to an arbitrary URL (Section 2.5.1.1) on a secondary device, but it 1703 cannot accept a redirect or push callback. 1705 "interact": { 1706 "start": ["redirect", "user_code"] 1707 } 1709 If the client instance does not provide a suitable interaction 1710 mechanism, the AS cannot contact the RO asynchronously, and the AS 1711 determines that interaction is required, then the AS SHOULD return an 1712 error since the client instance will be unable to complete the 1713 request without authorization. 1715 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1716 provided, including user codes and redirection URLs. The client 1717 instance SHOULD apply suitable timeouts to any callback URLs. 1719 2.5.1. Start Mode Definitions 1721 This specification defines the following interaction start modes as 1722 an array of string values under the start key: 1724 "redirect" Indicates that the client instance can direct the end- 1725 user to an arbitrary URL for interaction. Section 2.5.1.1 1727 "app" Indicates that the client instance can launch an application 1728 on the end-user's device for interaction. Section 2.5.1.2 1730 "user_code" Indicates that the client instance can communicate a 1731 human-readable short code to the end-user for use with a stable 1732 URL. Section 2.5.1.3 1734 2.5.1.1. Redirect to an Arbitrary URL 1736 If the client instance is capable of directing the end-user to a URL 1737 defined by the AS at runtime, the client instance indicates this by 1738 including redirect in the array under the start key. The means by 1739 which the client instance will activate this URL is out of scope of 1740 this specification, but common methods include an HTTP redirect, 1741 launching a browser on the end-user's device, providing a scannable 1742 image encoding, and printing out a URL to an interactive console. 1743 While this URL is generally hosted at the AS, the client instance can 1744 make no assumptions about its contents, composition, or relationship 1745 to the AS grant URL. 1747 "interact": { 1748 "start": ["redirect"] 1749 } 1751 If this interaction mode is supported for this client instance and 1752 request, the AS returns a redirect interaction response 1753 Section 3.3.1. The client instance manages this interaction method 1754 as described in Section 4.1.1. 1756 See Section 12.24 for more considerations regarding the use of front- 1757 channel communication techniques such as this. 1759 2.5.1.2. Open an Application-specific URL 1761 If the client instance can open a URL associated with an application 1762 on the end-user's device, the client instance indicates this by 1763 including app in the array under the start key. The means by which 1764 the client instance determines the application to open with this URL 1765 are out of scope of this specification. 1767 "interact": { 1768 "start": ["app"] 1769 } 1771 If this interaction mode is supported for this client instance and 1772 request, the AS returns an app interaction response with an app URL 1773 payload Section 3.3.2. The client instance manages this interaction 1774 method as described in Section 4.1.3. 1776 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1777 issues/54) ]] 1779 2.5.1.3. Display a Short User Code 1781 If the client instance is capable of displaying or otherwise 1782 communicating a short, human-entered code to the RO, the client 1783 instance indicates this by including user_code in the array under the 1784 start key. This code is to be entered at a static URL that does not 1785 change at runtime. While this URL is generally hosted at the AS, the 1786 client instance can make no assumptions about its contents, 1787 composition, or relationship to the AS grant URL. 1789 "interact": { 1790 "start": ["user_code"] 1791 } 1793 If this interaction mode is supported for this client instance and 1794 request, the AS returns a user code and interaction URL as specified 1795 in Section 3.3.3. The client instances manages this interaction 1796 method as described in Section 4.1.2 1798 2.5.2. Finish Interaction Modes 1800 If the client instance is capable of receiving a message from the AS 1801 indicating that the RO has completed their interaction, the client 1802 instance indicates this by sending the following members of an object 1803 under the finish key. 1805 method (string) REQUIRED. The callback method that the AS will use 1806 to contact the client instance. This specification defines the 1807 following interaction completion methods, with other values 1808 defined by a registry TBD (Section 11): 1810 "redirect" Indicates that the client instance can receive a 1811 redirect from the end-user's device after interaction with the 1812 RO has concluded. Section 2.5.2.1 1814 "push" Indicates that the client instance can receive an HTTP 1815 POST request from the AS after interaction with the RO has 1816 concluded. Section 2.5.2.2 1818 uri (string) REQUIRED. Indicates the URI that the AS will either 1819 send the RO to after interaction or send an HTTP POST request. 1820 This URI MAY be unique per request and MUST be hosted by or 1821 accessible by the client instance. This URI MUST NOT contain any 1822 fragment component. This URI MUST be protected by HTTPS, be 1823 hosted on a server local to the RO's browser ("localhost"), or use 1824 an application-specific URI scheme. If the client instance needs 1825 any state information to tie to the front channel interaction 1826 response, it MUST use a unique callback URI to link to that 1827 ongoing state. The allowable URIs and URI patterns MAY be 1828 restricted by the AS based on the client instance's presented key 1829 information. The callback URI SHOULD be presented to the RO 1830 during the interaction phase before redirect. 1832 nonce (string) REQUIRED. Unique value to be used in the calculation 1833 of the "hash" query parameter sent to the callback URL, must be 1834 sufficiently random to be unguessable by an attacker. MUST be 1835 generated by the client instance as a unique value for this 1836 request. 1838 hash_method (string) OPTIONAL. The hash calculation mechanism to be 1839 used for the callback hash in Section 4.2.3. Can be one of sha3 1840 or sha2. If absent, the default value is sha3. [[ See issue #56 1841 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) ]] 1843 If this interaction mode is supported for this client instance and 1844 request, the AS returns a nonce for use in validating the callback 1845 response (Section 3.3.4). Requests to the callback URI MUST be 1846 processed as described in Section 4.2, and the AS MUST require 1847 presentation of an interaction callback reference as described in 1848 Section 5.1. 1850 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1851 issues/58) ]] 1853 2.5.2.1. Receive an HTTP Callback Through the Browser 1855 A finish method value of redirect indicates that the client instance 1856 will expect a request from the RO's browser using the HTTP method GET 1857 as described in Section 4.2.1. 1859 "interact": { 1860 "finish": { 1861 "method": "redirect", 1862 "uri": "https://client.example.net/return/123455", 1863 "nonce": "LKLTI25DK82FX4T4QFZC" 1864 } 1865 } 1867 Requests to the callback URI MUST be processed by the client instance 1868 as described in Section 4.2.1. 1870 Since the incoming request to the callback URL is from the RO's 1871 browser, this method is usually used when the RO and end-user are the 1872 same entity. As such, the client instance MUST ensure the end-user 1873 is present on the request to prevent substitution attacks. 1875 See Section 12.24 for more considerations regarding the use of front- 1876 channel communication techniques such as this. 1878 2.5.2.2. Receive an HTTP Direct Callback 1880 A finish method value of push indicates that the client instance will 1881 expect a request from the AS directly using the HTTP method POST as 1882 described in Section 4.2.2. 1884 "interact": { 1885 "finish": { 1886 "method": "push", 1887 "uri": "https://client.example.net/return/123455", 1888 "nonce": "LKLTI25DK82FX4T4QFZC" 1889 } 1890 } 1892 Requests to the callback URI MUST be processed by the client instance 1893 as described in Section 4.2.2. 1895 Since the incoming request to the callback URL is from the AS and not 1896 from the RO's browser, the client instance MUST NOT require the end- 1897 user to be present on the incoming HTTP request. 1899 2.5.3. Hints 1901 The hints key is an object describing one or more suggestions from 1902 the client instance that the AS can use to help drive user 1903 interaction. 1905 This specification defines the following properties under the hints 1906 key: 1908 ui_locales (array of strings) Indicates the end-user's preferred 1909 locales that the AS can use during interaction, particularly 1910 before the RO has authenticated. Section 2.5.3.1 1912 The following sections detail requests for interaction modes. 1913 Additional interaction modes are defined in a registry TBD 1914 (Section 11). 1916 2.5.3.1. Indicate Desired Interaction Locales 1918 If the client instance knows the end-user's locale and language 1919 preferences, the client instance can send this information to the AS 1920 using the ui_locales field with an array of locale strings as defined 1921 by [RFC5646]. 1923 "interact": { 1924 "hints": { 1925 "ui_locales": ["en-US", "fr-CA"] 1926 } 1927 } 1929 If possible, the AS SHOULD use one of the locales in the array, with 1930 preference to the first item in the array supported by the AS. If 1931 none of the given locales are supported, the AS MAY use a default 1932 locale. 1934 2.5.4. Extending Interaction Modes 1936 Additional interaction start modes, finish modes, and hints are 1937 defined in a registry TBD (Section 11). 1939 2.6. Extending The Grant Request 1941 The request object MAY be extended by registering new items in a 1942 registry TBD (Section 11). Extensions SHOULD be orthogonal to other 1943 parameters. Extensions MUST document any aspects where the extension 1944 item affects or influences the values or behavior of other request 1945 and response objects. 1947 3. Grant Response 1949 In response to a client instance's request, the AS responds with a 1950 JSON object as the HTTP entity body. Each possible field is detailed 1951 in the sections below 1953 continue (object) Indicates that the client instance can continue 1954 the request by making one or more continuation requests. 1955 Section 3.1 1957 access_token (object / array of objects) A single access token or 1958 set of access tokens that the client instance can use to call the 1959 RS on behalf of the RO. Section 3.2.1 1961 interact (object) Indicates that interaction through some set of 1962 defined mechanisms needs to take place. Section 3.3 1964 subject (object) Claims about the RO as known and declared by the 1965 AS, as described in Section 3.4. 1967 instance_id (string) An identifier this client instance can use to 1968 identify itself when making future requests. Section 3.5 1970 error (object) An error code indicating that something has gone 1971 wrong. Section 3.6 1973 In this example, the AS is returning an interaction URL 1974 (Section 3.3.1), a callback nonce (Section 3.3.4), and a continuation 1975 response (Section 3.1). 1977 NOTE: '\' line wrapping per RFC 8792 1979 { 1980 "interact": { 1981 "redirect": "https://server.example.com/interact/4CF492ML\ 1982 VMSW9MKMXKHQ", 1983 "finish": "MBDOFXG4Y5CVJCX821LH" 1984 }, 1985 "continue": { 1986 "access_token": { 1987 "value": "80UPRY5NM33OMUKMKSKU", 1988 }, 1989 "uri": "https://server.example.com/tx" 1990 } 1991 } 1993 In this example, the AS is returning a bearer access token 1994 (Section 3.2.1) with a management URL and a subject identifier 1995 (Section 3.4) in the form of an opaque identifier. 1997 NOTE: '\' line wrapping per RFC 8792 1999 { 2000 "access_token": { 2001 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2002 "flags": ["bearer"], 2003 "manage": "https://server.example.com/token/PRY5NM33O\ 2004 M4TB8N6BW7OZB8CDFONP219RP1L", 2005 }, 2006 "subject": { 2007 "sub_ids": [ { 2008 "format": "opaque", 2009 "id": "J2G8G8O4AZ" 2010 } ] 2011 } 2012 } 2014 In this example, the AS is returning set of subject identifiers 2015 (Section 3.4), simultaneously as an opaque identifier, an email 2016 address, and a decentralized identifier (DID). 2018 { 2019 "subject": { 2020 "sub_ids": [ { 2021 "format": "opaque", 2022 "id": "J2G8G8O4AZ" 2023 }, { 2024 "format": "email", 2025 "email": "user@example.com" 2026 }, { 2027 "format": "did", 2028 "url": "did:example:123456" 2029 } ] 2030 } 2031 } 2033 3.1. Request Continuation 2035 If the AS determines that the request can be continued with 2036 additional requests, it responds with the continue field. This field 2037 contains a JSON object with the following properties. 2039 uri (string) REQUIRED. The URI at which the client instance can 2040 make continuation requests. This URI MAY vary per request, or MAY 2041 be stable at the AS. The client instance MUST use this value 2042 exactly as given when making a continuation request (Section 5). 2044 wait (integer) RECOMMENDED. The amount of time in integer seconds 2045 the client instance SHOULD wait after receiving this continuation 2046 handle and calling the URI. 2048 access_token (object) REQUIRED. A unique access token for 2049 continuing the request, called the "continuation access token". 2050 The value of this property MUST be in the format specified in 2051 Section 3.2.1. This access token MUST be bound to the client 2052 instance's key used in the request and MUST NOT be a bearer token. 2053 As a consequence, the flags array of this access token MUST NOT 2054 contain the string bearer and the key field MUST be omitted. The 2055 client instance MUST present the continuation access token in all 2056 requests to the continuation URI as described in Section 7.2. 2058 { 2059 "continue": { 2060 "access_token": { 2061 "value": "80UPRY5NM33OMUKMKSKU" 2062 }, 2063 "uri": "https://server.example.com/continue", 2064 "wait": 60 2065 } 2066 } 2068 The client instance can use the values of this field to continue the 2069 request as described in Section 5. Note that the client instance 2070 MUST sign all continuation requests with its key as described in 2071 Section 7.3 and MUST present the access token in its continuation 2072 request. 2074 This field SHOULD be returned when interaction is expected, to allow 2075 the client instance to follow up after interaction has been 2076 concluded. 2078 3.2. Access Tokens 2080 If the AS has successfully granted one or more access tokens to the 2081 client instance, the AS responds with the access_token field. This 2082 field contains either a single access token as described in 2083 Section 3.2.1 or an array of access tokens as described in 2084 Section 3.2.2. 2086 The client instance uses any access tokens in this response to call 2087 the RS as described in Section 7.2. 2089 3.2.1. Single Access Token 2091 If the client instance has requested a single access token and the AS 2092 has granted that access token, the AS responds with the 2093 "access_token" field. The value of this field is an object with the 2094 following properties. 2096 value (string) REQUIRED. The value of the access token as a string. 2097 The value is opaque to the client instance. The value SHOULD be 2098 limited to ASCII characters to facilitate transmission over HTTP 2099 headers within other protocols without requiring additional 2100 encoding. 2102 label (string) REQUIRED for multiple access tokens, OPTIONAL for 2103 single access token. The value of the label the client instance 2104 provided in the associated token request (Section 2.1), if 2105 present. If the token has been split by the AS, the value of the 2106 label field is chosen by the AS and the split flag is used. 2108 manage (string) OPTIONAL. The management URI for this access token. 2109 If provided, the client instance MAY manage its access token as 2110 described in Section 6. This management URI is a function of the 2111 AS and is separate from the RS the client instance is requesting 2112 access to. This URI MUST NOT include the access token value and 2113 SHOULD be different for each access token issued in a request. 2115 access (array of objects/strings) RECOMMENDED. A description of the 2116 rights associated with this access token, as defined in Section 8. 2117 If included, this MUST reflect the rights associated with the 2118 issued access token. These rights MAY vary from what was 2119 requested by the client instance. 2121 expires_in (integer) OPTIONAL. The number of seconds in which the 2122 access will expire. The client instance MUST NOT use the access 2123 token past this time. An RS MUST NOT accept an access token past 2124 this time. Note that the access token MAY be revoked by the AS or 2125 RS at any point prior to its expiration. 2127 key (object / string) OPTIONAL. The key that the token is bound to, 2128 if different from the client instance's presented key. The key 2129 MUST be an object or string in a format described in Section 7.1. 2130 The client instance MUST be able to dereference or process the key 2131 information in order to be able to sign the request. 2133 flags (array of strings) OPTIONAL. A set of flags that represent 2134 attributes or behaviors of the access token issued by the AS. 2136 The values of the flags field defined by this specification are as 2137 follows: 2139 "bearer" This flag indicates whether the token is a bearer token, 2140 not bound to a key and proofing mechanism. If the bearer flag is 2141 present, the access token is a bearer token, and the key field in 2142 this response MUST be omitted. If the bearer flag is omitted and 2143 the key field in this response is omitted, the token is bound the 2144 key used by the client instance (Section 2.3) in its request for 2145 access. If the bearer flag is omitted, and the key field is 2146 present, the token is bound to the key and proofing mechanism 2147 indicated in the key field. See Section 12.7 for additional 2148 considerations on the use of bearer tokens. 2150 "durable" OPTIONAL. Flag indicating a hint of AS behavior on token 2151 rotation. If this flag is present, then the client instance can 2152 expect a previously-issued access token to continue to work after 2153 it has been rotated (Section 6.1) or the underlying grant request 2154 has been modified (Section 5.3), resulting in the issuance of new 2155 access tokens. If this flag is omitted, the client instance can 2156 anticipate a given access token will stop working after token 2157 rotation or grant request modification. Note that a token flagged 2158 as durable can still expire or be revoked through any normal 2159 means. 2161 "split" OPTIONAL. Flag indicating that this token was generated by 2162 issuing multiple access tokens in response to one of the client 2163 instance's token request (Section 2.1) objects. This behavior 2164 MUST NOT be used unless the client instance has specifically 2165 requested it by use of the split flag. 2167 Flag values MUST NOT be included more than once. 2169 Additional flags can be defined by extensions using a registry TBD 2170 (Section 11). 2172 The following non-normative example shows a single access token bound 2173 to the client instance's key used in the initial request, with a 2174 management URL, and that has access to three described resources (one 2175 using an object and two described by reference strings). 2177 NOTE: '\' line wrapping per RFC 8792 2179 "access_token": { 2180 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2181 "manage": "https://server.example.com/token/PRY5NM33O\ 2182 M4TB8N6BW7OZB8CDFONP219RP1L", 2183 "access": [ 2184 { 2185 "type": "photo-api", 2186 "actions": [ 2187 "read", 2188 "write", 2189 "dolphin" 2190 ], 2191 "locations": [ 2192 "https://server.example.net/", 2193 "https://resource.local/other" 2194 ], 2195 "datatypes": [ 2196 "metadata", 2197 "images" 2198 ] 2199 }, 2200 "read", "dolphin-metadata" 2201 ] 2202 } 2204 The following non-normative example shows a single bearer access 2205 token with access to two described resources. 2207 "access_token": { 2208 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2209 "flags": ["bearer"], 2210 "access": [ 2211 "finance", "medical" 2212 ] 2213 } 2215 If the client instance requested a single access token 2216 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2217 token structure unless the client instance sends the split flag as 2218 described in Section 2.1.1. 2220 If the AS has split the access token response, the response MUST 2221 include the split flag. 2223 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2224 issues/69) ]] 2226 3.2.2. Multiple Access Tokens 2228 If the client instance has requested multiple access tokens and the 2229 AS has granted at least one of them, the AS responds with the 2230 "access_token" field. The value of this field is a JSON array, the 2231 members of which are distinct access tokens as described in 2232 Section 3.2.1. Each object MUST have a unique label field, 2233 corresponding to the token labels chosen by the client instance in 2234 the multiple access token request (Section 2.1.2). 2236 In this non-normative example, two tokens are issued under the names 2237 token1 and token2, and only the first token has a management URL 2238 associated with it. 2240 NOTE: '\' line wrapping per RFC 8792 2242 "access_token": [ 2243 { 2244 "label": "token1", 2245 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2246 "manage": "https://server.example.com/token/PRY5NM33O\ 2247 M4TB8N6BW7OZB8CDFONP219RP1L", 2248 "access": [ "finance" ] 2249 }, 2250 { 2251 "label": "token2", 2252 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2253 "access": [ "medical" ] 2254 } 2255 } 2257 Each access token corresponds to one of the objects in the 2258 access_token array of the client instance's request (Section 2.1.2). 2260 The multiple access token response MUST be used when multiple access 2261 tokens are requested, even if only one access token is issued as a 2262 result of the request. The AS MAY refuse to issue one or more of the 2263 requested access tokens, for any reason. In such cases the refused 2264 token is omitted from the response and all of the other issued access 2265 tokens are included in the response the requested names appropriate 2266 names. 2268 If the client instance requested multiple access tokens 2269 (Section 2.1.2), the AS MUST NOT respond with a single access token 2270 structure, even if only a single access token is granted. In such 2271 cases, the AS responds with a multiple access token structure 2272 containing one access token. 2274 If the AS has split the access token response, the response MUST 2275 include the split flag in the flags array. 2277 "access_token": [ 2278 { 2279 "label": "split-1", 2280 "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", 2281 "flags": ["split"], 2282 "manage": "https://server.example.com/token/PRY5NM33O\ 2283 M4TB8N6BW7OZB8CDFONP219RP1L", 2284 "access": [ "fruits" ] 2285 }, 2286 { 2287 "label": "split-2", 2288 "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", 2289 "flags": ["split"], 2290 "access": [ "vegetables" ] 2291 } 2292 } 2294 Each access token MAY be bound to different keys with different 2295 proofing mechanisms. 2297 If token management (Section 6) is allowed, each access token SHOULD 2298 have different manage URIs. 2300 [[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2301 issues/70) ]] 2303 3.3. Interaction Modes 2305 If the client instance has indicated a capability to interact with 2306 the RO in its request (Section 2.5), and the AS has determined that 2307 interaction is both supported and necessary, the AS responds to the 2308 client instance with any of the following values in the interact 2309 field of the response. There is no preference order for interaction 2310 modes in the response, and it is up to the client instance to 2311 determine which ones to use. All supported interaction methods are 2312 included in the same interact object. 2314 redirect (string) Redirect to an arbitrary URL. Section 3.3.1 2316 app (string) Launch of an application URL. Section 3.3.2 2318 finish (string) A nonce used by the client instance to verify the 2319 callback after interaction is completed. Section 3.3.4 2321 user_code (object) Display a short user code. Section 3.3.3 2322 Additional interaction mode responses can be defined in a registry 2323 TBD (Section 11). 2325 The AS MUST NOT respond with any interaction mode that the client 2326 instance did not indicate in its request. The AS MUST NOT respond 2327 with any interaction mode that the AS does not support. Since 2328 interaction responses include secret or unique information, the AS 2329 SHOULD respond to each interaction mode only once in an ongoing 2330 request, particularly if the client instance modifies its request 2331 (Section 5.3). 2333 3.3.1. Redirection to an arbitrary URL 2335 If the client instance indicates that it can redirect to an arbitrary 2336 URL (Section 2.5.1.1) and the AS supports this mode for the client 2337 instance's request, the AS responds with the "redirect" field, which 2338 is a string containing the URL to direct the end-user to. This URL 2339 MUST be unique for the request and MUST NOT contain any security- 2340 sensitive information such as user identifiers or access tokens. 2342 "interact": { 2343 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2344 } 2346 The URL returned is a function of the AS, but the URL itself MAY be 2347 completely distinct from the URL the client instance uses to request 2348 access (Section 2), allowing an AS to separate its user-interactive 2349 functionality from its back-end security functionality. If the AS 2350 does not directly host the functionality accessed through the given 2351 URL, then the means for the interaction functionality to communicate 2352 with the rest of the AS are out of scope for this specification. 2354 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2355 issues/72) ]] 2357 The client instance sends the end-user to the URL to interact with 2358 the AS. The client instance MUST NOT alter the URL in any way. The 2359 means for the client instance to send the end-user to this URL is out 2360 of scope of this specification, but common methods include an HTTP 2361 redirect, launching the system browser, displaying a scannable code, 2362 or printing out the URL in an interactive console. See details of 2363 the interaction in Section 4.1.1. 2365 3.3.2. Launch of an application URL 2367 If the client instance indicates that it can launch an application 2368 URL (Section 2.5.1.2) and the AS supports this mode for the client 2369 instance's request, the AS responds with the "app" field, which is a 2370 string containing the URL for the client instance to launch. This 2371 URL MUST be unique for the request and MUST NOT contain any security- 2372 sensitive information such as user identifiers or access tokens. 2374 "interact": { 2375 "app": "https://app.example.com/launch?tx=4CF492MLV" 2376 } 2378 The means for the launched application to communicate with the AS are 2379 out of scope for this specification. 2381 The client instance launches the URL as appropriate on its platform, 2382 and the means for the client instance to launch this URL is out of 2383 scope of this specification. The client instance MUST NOT alter the 2384 URL in any way. The client instance MAY attempt to detect if an 2385 installed application will service the URL being sent before 2386 attempting to launch the application URL. See details of the 2387 interaction in Section 4.1.3. 2389 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2390 issues/71) ]] 2392 3.3.3. Display of a Short User Code 2394 If the client instance indicates that it can display a short 2395 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2396 for the client instance's request, the AS responds with a "user_code" 2397 field. This field is an object that contains the following members. 2399 code (string) REQUIRED. A unique short code that the user can type 2400 into an authorization server. This string MUST be case- 2401 insensitive, MUST consist of only easily typeable characters (such 2402 as letters or numbers). The time in which this code will be 2403 accepted SHOULD be short lived, such as several minutes. It is 2404 RECOMMENDED that this code be no more than eight characters in 2405 length. 2407 url (string) RECOMMENDED. The interaction URL that the client 2408 instance will direct the RO to. This URL MUST be stable such that 2409 client instances can be statically configured with it. 2411 "interact": { 2412 "user_code": { 2413 "code": "A1BC-3DFF", 2414 "url": "https://srv.ex/device" 2415 } 2416 } 2418 The client instance MUST communicate the "code" to the end-user in 2419 some fashion, such as displaying it on a screen or reading it out 2420 audibly. 2422 The client instance SHOULD also communicate the URL if possible to 2423 facilitate user interaction, but since the URL should be stable, the 2424 client instance should be able to safely decide to not display this 2425 value. As this interaction mode is designed to facilitate 2426 interaction via a secondary device, it is not expected that the 2427 client instance redirect the end-user to the URL given here at 2428 runtime. Consequently, the URL needs to be stable enough that a 2429 client instance could be statically configured with it, perhaps 2430 referring the end-user to the URL via documentation instead of 2431 through an interactive means. If the client instance is capable of 2432 communicating an arbitrary URL to the end-user, such as through a 2433 scannable code, the client instance can use the "redirect" 2434 (Section 2.5.1.1) mode for this purpose instead of or in addition to 2435 the user code mode. 2437 The URL returned is a function of the AS, but the URL itself MAY be 2438 completely distinct from the URL the client instance uses to request 2439 access (Section 2), allowing an AS to separate its user-interactive 2440 functionality from its back-end security functionality. If the AS 2441 does not directly host the functionality accessed through the given 2442 URL, then the means for the interaction functionality to communicate 2443 with the rest of the AS are out of scope for this specification. 2445 See details of the interaction in Section 4.1.2. 2447 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2448 issues/72) ]] 2450 3.3.4. Interaction Finish 2452 If the client instance indicates that it can receive a 2453 post-interaction redirect or push at a URL (Section 2.5.2) and the AS 2454 supports this mode for the client instance's request, the AS responds 2455 with a finish field containing a nonce that the client instance will 2456 use in validating the callback as defined in Section 4.2. 2458 "interact": { 2459 "finish": "MBDOFXG4Y5CVJCX821LH" 2460 } 2462 When the interaction is completed, the interaction component MUST 2463 contact the client instance using either a redirect or launch of the 2464 RO's browser or through an HTTP POST to the client instance's 2465 callback URL using the method indicated in the interaction request 2466 (Section 2.5.2) as described in Section 4.2. 2468 If the AS returns a nonce, the client instance MUST NOT continue a 2469 grant request before it receives the associated interaction reference 2470 on the callback URI. See details in Section 4.2. 2472 3.3.5. Extending Interaction Mode Responses 2474 Extensions to this specification can define new interaction mode 2475 responses in a registry TBD (Section 11). Extensions MUST document 2476 the corresponding interaction request. 2478 3.4. Returning Subject Information 2480 If information about the RO is requested and the AS grants the client 2481 instance access to that data, the AS returns the approved information 2482 in the "subject" response field. The AS MUST return the subject 2483 field only in cases where the AS is sure that the RO and the end-user 2484 are the same party. This can be accomplished through some forms of 2485 interaction with the RO (Section 4). 2487 This field is an object with the following OPTIONAL properties. 2489 sub_ids (array of objects) An array of subject identifiers for the 2490 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2492 An object containing assertions as values keyed on the assertion 2493 type defined by a registry TBD (Section 11). Possible keys 2494 include id_token for an [OIDC] ID Token and saml2 for a SAML 2 2495 assertion. The assertion values are the string serialization of 2496 the assertion format, encoded as a plain JSON string. Additional 2497 assertion types are defined by a registry TBD (Section 11). [[ 2498 See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2499 issues/41) ]] 2501 updated_at (string) Timestamp as an ISO8610 date string, indicating 2502 when the identified account was last updated. The client instance 2503 MAY use this value to determine if it needs to request updated 2504 profile information through an identity API. The definition of 2505 such an identity API is out of scope for this specification. 2507 "subject": { 2508 "sub_ids": [ { 2509 "format": "opaque", 2510 "id": "XUT2MFM1XBIKJKSDU8QM" 2511 } ], 2512 "assertions": { 2513 "id_token": "eyj..." 2514 } 2515 } 2517 Subject identifiers returned by the AS SHOULD uniquely identify the 2518 RO at the AS. Some forms of subject identifier are opaque to the 2519 client instance (such as the subject of an issuer and subject pair), 2520 while others forms (such as email address and phone number) are 2521 intended to allow the client instance to correlate the identifier 2522 with other account information at the client instance. The AS MUST 2523 ensure that the returned subject identifiers only apply to the 2524 authenticated end user. The client instance MUST NOT request or use 2525 any returned subject identifiers for communication purposes (see 2526 Section 2.2). That is, a subject identifier returned in the format 2527 of an email address or a phone number only identifies the RO to the 2528 AS and does not indicate that the AS has validated that the 2529 represented email address or phone number in the identifier is 2530 suitable for communication with the current user. To get such 2531 information, the client instance MUST use an identity protocol to 2532 request and receive additional identity claims. The details of an 2533 identity protocol and associated schema are outside the scope of this 2534 specification. 2536 Extensions to this specification MAY define additional response 2537 properties in a registry TBD (Section 11). 2539 See Section 12.25 for considerations that the client instance has to 2540 make when accepting and processing assertions from the AS. 2542 3.5. Returning a Dynamically-bound Client Instance Identifier 2544 Many parts of the client instance's request can be passed as either a 2545 value or a reference. The use of a reference in place of a value 2546 allows for a client instance to optimize requests to the AS. 2548 Some references, such as for the client instance's identity 2549 (Section 2.3.1) or the requested resources (Section 8.1), can be 2550 managed statically through an admin console or developer portal 2551 provided by the AS or RS. The developer of the client software can 2552 include these values in their code for a more efficient and compact 2553 request. 2555 If desired, the AS MAY also generate and return an instance 2556 identifier dynamically to the client instance in the response to 2557 facilitate multiple interactions with the same client instance over 2558 time. The client instance SHOULD use this instance identifier in 2559 future requests in lieu of sending the associated data values in the 2560 client field. 2562 Dynamically generated client instance identifiers are string values 2563 that MUST be protected by the client instance as secrets. Instance 2564 identifier values MUST be unguessable and MUST NOT contain any 2565 sensitive information. Instance identifier values are opaque to the 2566 client instance. 2568 instance_id (string) A string value used to represent the 2569 information in the client object that the client instance can use 2570 in a future request, as described in Section 2.3.1. 2572 This non-normative example shows an instance identifier along side an 2573 issued access token. 2575 { 2576 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2577 "access_token": { 2578 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 2579 } 2580 } 2582 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2583 issues/77) ]] 2585 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2586 issues/78) ]] 2588 3.6. Error Response 2590 If the AS determines that the request cannot be issued for any 2591 reason, it responds to the client instance with an error message. 2593 error (string) The error code. 2595 { 2597 "error": "user_denied" 2599 } 2601 The error code is one of the following, with additional values 2602 available in a registry TBD (Section 11): 2604 user_denied The RO denied the request. 2606 too_fast The client instance did not respect the timeout in the wait 2607 response. 2609 unknown_request The request referenced an unknown ongoing access 2610 request. 2612 [[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2613 issues/79) ]] 2615 3.7. Extending the Response 2617 Extensions to this specification MAY define additional fields for the 2618 grant response in a registry TBD (Section 11). 2620 4. Determining Authorization and Consent 2622 When the client instance makes its initial request (Section 2) to the 2623 AS for delegated access, it is capable of asking for several 2624 different kinds of information in response: 2626 * the access being requested in the access_token request parameter 2628 * the subject information being requested in the subject request 2629 parameter 2631 * any additional requested information defined by extensions of this 2632 protocol 2634 The AS determines what authorizations and consents are required to 2635 fulfill this requested delegation. The details of how the AS makes 2636 this determination are out of scope for this document. However, 2637 there are several common patterns defined and supported by GNAP for 2638 fulfilling these requirements, including information sent by the 2639 client instance, information gathered through the interaction 2640 process, and information supplied by external parties. An individual 2641 AS can define its own policies and processes for deciding when and 2642 how to gather the necessary authorizations and consent. 2644 The client instance can supply information directly to the AS in its 2645 request. From this information, the AS can determine if the 2646 requested delegation can be granted immediately. The client instance 2647 can send several kinds of things, including: 2649 * the identity of the client instance, known from the presented keys 2650 or associated identifiers 2652 * the identity of the end user presented in the user request 2653 parameter 2655 * any additional information presented by the client instance in the 2656 request, including any extensions 2658 The AS will verify this presented information in the context of the 2659 client instance's request and can only trust the information as much 2660 as it trusts the presentation and context of the information. If the 2661 AS determines that the information presented in the initial request 2662 is sufficient for granting the requested access, the AS MAY return 2663 the positive results immediately in its response (Section 3) with 2664 access tokens and subject information. 2666 If the AS determines that additional runtime authorization is 2667 required, the AS can either deny the request outright or use a number 2668 of means at its disposal to gather that authorization from the 2669 appropriate ROs, including for example: 2671 * starting interaction with the end user facilitated by the client 2672 software, such as a redirection or user code 2674 * challenging the client instance through a challenge-response 2675 mechanism 2677 * requesting that the client instance present specific additional 2678 information, such as a user's credential or an assertion 2680 * contacting a RO through an out-of-band mechanism, such as a push 2681 notification 2683 * contacting an auxiliary software process through an out-of-band 2684 mechanism, such as querying a digital wallet 2686 The authorization and consent gathering process in GNAP is left 2687 deliberately flexible to allow for a wide variety of different 2688 deployments, interactions, and methodologies. In this process, the 2689 AS can gather consent from the RO as necessitated by the access that 2690 has been requested. The AS can sometimes determine which RO needs to 2691 consent based on what has been requested by the client instance, such 2692 as a specific RS record, an identified user, or a request requiring 2693 specific access such as approval by an administrator. If the AS has 2694 a means of contacting the RO directly, it could do so without 2695 involving the client instance in its consent gathering process. For 2696 example, the AS could push a notification to a known RO and have the 2697 RO approve the pending request asynchronously. These interactions 2698 can be through an interface of the AS itself (such as a hosted web 2699 page), through another application (such as something installed on 2700 the RO's device), through a messaging fabric, or any other means. 2701 When interacting with an RO, the AS can do anything it needs to 2702 determine the authorization of the requested grant, including: 2704 * authenticate the RO, through a local account or some other means 2705 such as federated login 2707 * validate the RO through presentation of claims, attributes, or 2708 other information 2710 * prompt the RO for consent for the requested delegation 2712 * describe to the RO what information is being released, to whom, 2713 and for what purpose 2715 * provide warnings to the RO about potential attacks or negative 2716 effects of allowing the information 2718 * allow the RO to modify the client instance's requested access, 2719 including limiting or expanding that access 2721 * provide the RO with artifacts such as receipts to facilitate an 2722 audit trail of authorizations 2724 * allow the RO to deny the requested delegation 2726 The AS is also allowed to request authorization from more than one 2727 RO, if the AS deems fit. For example, a medical record might need to 2728 be released by both an attending nurse and a physician, or both 2729 owners of a bank account need to sign off on a transfer request. 2730 Alternatively, the AS could require N of M possible RO's to approve a 2731 given request in order. The AS could also determine that the end 2732 user is not the appropriate RO for a given request and reach out to 2733 the appropriate RO asynchronously. The details of determining which 2734 RO's are required for a given request are out of scope for this 2735 specification. 2737 The client instance can also indicate that it is capable of 2738 facilitating interaction with the end user, another party, or another 2739 piece of software through its interaction start (Section 2.5.1) 2740 request. In many cases, the end user is delegating their own access 2741 as RO to the client instance. Here, the AS needs to determine the 2742 identity of the end user and will often need to interact directly 2743 with the end user to determine their status as an RO and collect 2744 their consent. If the AS has determined that authorization is 2745 required and the AS can support one or more of the requested 2746 interaction start methods, the AS returns the associated interaction 2747 start responses (Section 3.3). The client instance SHOULD initiate 2748 one or more of these interaction methods (Section 4.1) in order to 2749 facilitate the granting of the request. If more than one interaction 2750 start method is available, the means by which the client chooses 2751 which methods to follow is out of scope of this specification. The 2752 client instance MUST use each interaction method once at most. 2754 After starting interaction, the client instance can then make a 2755 continuation request (Section 5) either in response to a signal 2756 indicating the finish of the interaction (Section 4.2), through 2757 polling, or through some other method defined by an extension of this 2758 specification. 2760 If the AS and client instance have not reached a state where the 2761 delegation can be granted, the AS and client instance can repeat the 2762 interaction process as long as the AS supplies the client instance 2763 with continuation information (Section 3.1) to facilitate the ongoing 2764 requests. 2766 4.1. Interaction Start Methods 2768 To initiate an interaction start method indicated by the interaction 2769 start responses (Section 3.3) from the AS, the client instance 2770 follows the steps defined by that interaction method. The actions of 2771 the client instance required for the interaction start modes defined 2772 in this specification are described in the following sections. 2774 4.1.1. Interaction at a Redirected URI 2776 When the end user is directed to an arbitrary URI through the 2777 "redirect" (Section 3.3.1) mode, the client instance facilitates 2778 opening the URI through the end user's web browser. The client 2779 instance could launch the URI through the system browser, provide a 2780 clickable link, redirect the user through HTTP response codes, or 2781 display the URI in a form the end user can use to launch such as a 2782 multidimensional barcode. With this method, it is common (though not 2783 required) for the RO to be the same party as the end-user, since the 2784 client instance has to communicate the redirection URI to the end- 2785 user. 2787 In many cases, the URI indicates a web page hosted at the AS, 2788 allowing the AS to authenticate the end user as the RO and 2789 interactively provide consent. If the URI is hosted by the AS, the 2790 AS MUST determine the grant request being referenced from the URL 2791 value itself. If the URL cannot be associated with a currently 2792 active request, the AS MUST display an error to the RO and MUST NOT 2793 attempt to redirect the RO back to any client instance even if a 2794 redirect finish method is supplied (Section 2.5.2.1). If the URI is 2795 not hosted by the AS directly, the means of communication between the 2796 AS and this URI are out of scope for this specification. 2798 The client instance MUST NOT modify the URI when launching it, in 2799 particular the client instance MUST NOT add any parameters to the 2800 URI. The URI MUST be reachable from the end user's browser, though 2801 the URI MAY be opened on a separate device from the client instance 2802 itself. The URI MUST be accessible from an HTTP GET request and MUST 2803 be protected by HTTPS or equivalent means. 2805 4.1.2. Interaction at the User Code URI 2807 When the end user is directed to enter a short code through the 2808 "user_code" (Section 3.3.3) mode, the client instance communicates 2809 the user code to the end-user and directs the end user to enter that 2810 code at an associated URI. This mode is used when the client 2811 instance is not able to facilitate launching an arbitrary URI. The 2812 associated URI could be statically configured with the client 2813 instance or communicated in the response from the AS, but the client 2814 instance communicates that URL to the end user. As a consequence, 2815 these URIs SHOULD be short. 2817 In many cases, the URI indicates a web page hosted at the AS, 2818 allowing the AS to authenticate the end user as the RO and 2819 interactively provide consent. If the URI is hosted by the AS, the 2820 AS MUST determine the grant request being referenced from the user 2821 code. If the user code cannot be associated with a currently active 2822 request, the AS MUST display an error to the RO and MUST NOT attempt 2823 to redirect the RO back to any client instance even if a redirect 2824 finish method is supplied (Section 2.5.2.1). If the interaction 2825 component at the user code URI is not hosted by the AS directly, the 2826 means of communication between the AS and this URI, including 2827 communication of the user code itself, are out of scope for this 2828 specification. 2830 When the RO enters this code at the user code URI, the AS MUST 2831 uniquely identify the pending request that the code was associated 2832 with. If the AS does not recognize the entered code, the interaction 2833 component MUST display an error to the user. If the AS detects too 2834 many unrecognized code enter attempts, the interaction component 2835 SHOULD display an error to the user and MAY take additional actions 2836 such as slowing down the input interactions. The user should be 2837 warned as such an error state is approached, if possible. 2839 The client instance MUST NOT modify the URI when launching it, in 2840 particular the client instance MUST NOT add any parameters to the 2841 URI. The user code URI MUST be reachable from the end user's 2842 browser, though the URI is usually be opened on a separate device 2843 from the client instance itself. The URI MUST be accessible from an 2844 HTTP GET request and MUST be protected by HTTPS or equivalent means. 2846 4.1.3. Interaction through an Application URI 2848 When the client instance is directed to launch an application through 2849 the "app" (Section 3.3.2) mode, the client launches the URL as 2850 appropriate to the system, such as through a deep link or custom URI 2851 scheme registered to a mobile application. The means by which the AS 2852 and the launched application communicate with each other and perform 2853 any of the required actions are out of scope for this specification. 2855 4.2. Post-Interaction Completion 2857 If an interaction "finish" (Section 3.3.4) method is associated with 2858 the current request, the AS MUST follow the appropriate method at 2859 upon completion of interaction in order to signal the client instance 2860 to continue, except for some limited error cases discussed below. If 2861 a finish method is not available, the AS SHOULD instruct the RO to 2862 return to the client instance upon completion. 2864 The AS MUST create an interaction reference and associate that 2865 reference with the current interaction and the underlying pending 2866 request. This interaction reference value MUST be sufficiently 2867 random so as not to be guessable by an attacker. The interaction 2868 reference MUST be one-time-use to prevent interception and replay 2869 attacks. 2871 The AS MUST calculate a hash value based on the client instance and 2872 AS nonces and the interaction reference, as described in 2873 Section 4.2.3. The client instance will use this value to validate 2874 the "finish" call. 2876 The AS MUST send the hash and interaction reference based on the 2877 interaction finish mode as described in the following sections. 2879 Note that the "finish" method still occurs in many error cases, such 2880 as when the RO has denied access. This pattern allows the client 2881 instance to potentially recover from the error state by modifying its 2882 request or providing additional information directly to the AS in a 2883 continuation request. The AS MUST NOT follow the "finish" method in 2884 the following circumstances: 2886 * The AS has determined that any URIs involved with the finish 2887 method are dangerous or blocked. 2889 * The AS cannot determine which ongoing grant request is being 2890 referenced. 2892 * The ongoing grant request has been cancelled or otherwise blocked. 2894 4.2.1. Completing Interaction with a Browser Redirect to the Callback 2895 URI 2897 When using the redirect interaction finish method (Section 3.3.4), 2898 the AS signals to the client instance that interaction is complete 2899 and the request can be continued by directing the RO (in their 2900 browser) back to the client instance's redirect URL sent in the 2901 callback request (Section 2.5.2.1). 2903 The AS secures this redirect by adding the hash and interaction 2904 reference as query parameters to the client instance's redirect URL. 2906 hash REQUIRED. The interaction hash value as described in 2907 Section 4.2.3. 2909 interact_ref REQUIRED. The interaction reference generated for this 2910 interaction. 2912 The means of directing the RO to this URL are outside the scope of 2913 this specification, but common options include redirecting the RO 2914 from a web page and launching the system browser with the target URL. 2916 NOTE: '\' line wrapping per RFC 8792 2918 https://client.example.net/return/123455\ 2919 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 2920 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 2921 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2923 When receiving the request, the client instance MUST parse the query 2924 parameters to calculate and validate the hash value as described in 2925 Section 4.2.3. If the hash validates, the client instance sends a 2926 continuation request to the AS as described in Section 5.1 using the 2927 interaction reference value received here. 2929 4.2.2. Completing Interaction with a Direct HTTP Request Callback 2931 When using the push interaction finish method (Section 3.3.4), the AS 2932 signals to the client instance that interaction is complete and the 2933 request can be continued by sending an HTTP POST request to the 2934 client instance's callback URL sent in the callback request 2935 (Section 2.5.2.2). 2937 The entity message body is a JSON object consisting of the following 2938 two fields: 2940 hash (string) REQUIRED. The interaction hash value as described in 2941 Section 4.2.3. 2943 interact_ref (string) REQUIRED. The interaction reference generated 2944 for this interaction. 2946 NOTE: '\' line wrapping per RFC 8792 2948 POST /push/554321 HTTP/1.1 2949 Host: client.example.net 2950 Content-Type: application/json 2952 { 2953 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ 2954 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2955 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2956 } 2958 When receiving the request, the client instance MUST parse the JSON 2959 object and validate the hash value as described in Section 4.2.3. If 2960 the hash validates, the client instance sends a continuation request 2961 to the AS as described in Section 5.1 using the interaction reference 2962 value received here. 2964 4.2.3. Calculating the interaction hash 2966 The "hash" parameter in the request to the client instance's callback 2967 URL ties the front channel response to an ongoing request by using 2968 values known only to the parties involved. This security mechanism 2969 allows the client instance to protect itself against several kinds of 2970 session fixation and injection attacks. The AS MUST always provide 2971 this hash, and the client instance MUST validate the hash when 2972 received. 2974 To calculate the "hash" value, the party doing the calculation 2975 creates a hash string by concatenating the following values in the 2976 following order using a single newline (\n) character to separate 2977 them: 2979 * the "nonce" value sent by the client instance in the interaction 2980 "finish" section of the initial request (Section 2.5.2) 2982 * the AS's nonce value from the interaction finish response 2983 (Section 3.3.4) 2985 * the "interact_ref" returned from the AS as part of the interaction 2986 finish method (Section 4.2) 2988 * the grant endpoint URL the client instance used to make its 2989 initial request (Section 2) 2991 There is no padding or whitespace before or after any of the lines, 2992 and no trailing newline character. 2994 VJLO6A4CAYLBXHTR0KRO 2995 MBDOFXG4Y5CVJCX821LH 2996 4IFWWIKYBC2PQ6U56NL1 2997 https://server.example.com/tx 2999 The party then hashes this string with the appropriate algorithm 3000 based on the "hash_method" parameter under the "finish" key. If the 3001 "hash_method" value is not present in the client instance's request, 3002 the algorithm defaults to "sha3". 3004 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3005 issues/56) ]] 3007 4.2.3.1. SHA3-512 3009 The "sha3" hash method consists of hashing the input string with the 3010 512-bit SHA3 algorithm. The byte array is then encoded using URL 3011 Safe Base64 with no padding. The resulting string is the hash value. 3013 NOTE: '\' line wrapping per RFC 8792 3015 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ 3016 7XHPAdJzTZMtKBsaraJ64A 3018 4.2.3.2. SHA2-512 3020 The "sha2" hash method consists of hashing the input string with the 3021 512-bit SHA2 algorithm. The byte array is then encoded using URL 3022 Safe Base64 with no padding. The resulting string is the hash value. 3024 NOTE: '\' line wrapping per RFC 8792 3026 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 3027 j84rh4mC9aE9x7HPBFcIHw 3029 5. Continuing a Grant Request 3031 While it is possible for the AS to return a grant response 3032 (Section 3) with all the client instance's requested information 3033 (including access tokens (Section 3.2) and direct user information 3034 (Section 3.4)), it's more common that the AS and the client instance 3035 will need to communicate several times over the lifetime of an access 3036 grant. This is often part of facilitating interaction (Section 4), 3037 but it could also be used to allow the AS and client instance to 3038 continue negotiating the parameters of the original grant request 3039 (Section 2). 3041 To enable this ongoing negotiation, the AS provides a continuation 3042 API to the client software. The AS returns a continue field in the 3043 response (Section 3.1) that contains information the client instance 3044 needs to access this API, including a URI to access as well as a 3045 continuation access token to use during the requests. 3047 The continuation access token is initially bound to the same key and 3048 method the client instance used to make the initial request. As a 3049 consequence, when the client instance makes any calls to the 3050 continuation URL, the client instance MUST present the continuation 3051 access token as described in Section 7.2 and present proof of the 3052 client instance's key (or its most recent rotation) by signing the 3053 request as described in Section 7.3. The AS MUST validate all keys 3054 presented by the client instance or referenced in an ongoing request 3055 for each call within that request. 3057 Access tokens other than the continuation access tokens MUST NOT be 3058 usable for continuation requests. 3060 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3061 issues/85) ]] 3063 For example, here the client instance makes a POST request to a 3064 unique URI and signs the request with HTTP Message Signatures: 3066 POST /continue/KSKUOMUKM HTTP/1.1 3067 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3068 Host: server.example.com 3069 Signature-Input: sig1=... 3070 Signature: sig1=... 3072 The AS MUST be able to tell from the client instance's request which 3073 specific ongoing request is being accessed, using a combination of 3074 the continuation URL, the provided continuation access token, and the 3075 client instance identified by the key signature. If the AS cannot 3076 determine a single active grant request to map the continuation 3077 request to, the AS MUST return an error. 3079 The ability to continue an already-started request allows the client 3080 instance to perform several important functions, including presenting 3081 additional information from interaction, modifying the initial 3082 request, and getting the current state of the request. 3084 All requests to the continuation API are protected by this bound 3085 continuation access token. For example, here the client instance 3086 makes a POST request to a stable continuation endpoint URL with the 3087 interaction reference (Section 5.1), includes the access token, and 3088 signs with HTTP Message Signatures: 3090 POST /continue HTTP/1.1 3091 Host: server.example.com 3092 Content-Type: application/json 3093 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3094 Signature-Input: sig1=... 3095 Signature: sig1=... 3096 Digest: sha256=... 3098 { 3099 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3100 } 3102 If a wait parameter was included in the continuation response 3103 (Section 3.1), the client instance MUST NOT call the continuation URI 3104 prior to waiting the number of seconds indicated. If no wait period 3105 is indicated, the client instance SHOULD wait at least 5 seconds. If 3106 the client instance does not respect the given wait period, the AS 3107 MUST return an error. 3109 The response from the AS is a JSON object and MAY contain any of the 3110 fields described in Section 3, as described in more detail in the 3111 sections below. 3113 If the AS determines that the client instance can make a further 3114 continuation request, the AS MUST include a new "continue" response 3115 (Section 3.1). The new continue response MUST include a continuation 3116 access token as well, and this token SHOULD be a new access token, 3117 invalidating the previous access token. If the AS does not return a 3118 new continue response, the client instance MUST NOT make an 3119 additional continuation request. If a client instance does so, the 3120 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 3121 wg-gnap/gnap-core-protocol/issues/87) ]] 3123 For continuation functions that require the client instance to send a 3124 message body, the body MUST be a JSON object. 3126 5.1. Continuing After a Completed Interaction 3128 When the AS responds to the client instance's finish method as in 3129 Section 4.2.1, this response includes an interaction reference. The 3130 client instance MUST include that value as the field interact_ref in 3131 a POST request to the continuation URI. 3133 POST /continue HTTP/1.1 3134 Host: server.example.com 3135 Content-Type: application/json 3136 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3137 Signature-Input: sig1=... 3138 Signature: sig1=... 3139 Digest: sha256=... 3141 { 3142 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3143 } 3145 Since the interaction reference is a one-time-use value as described 3146 in Section 4.2.1, if the client instance needs to make additional 3147 continuation calls after this request, the client instance MUST NOT 3148 include the interaction reference. If the AS detects a client 3149 instance submitting the same interaction reference multiple times, 3150 the AS MUST return an error and SHOULD invalidate the ongoing 3151 request. 3153 The grant response (Section 3) MAY contain any newly-created access 3154 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3155 The response MAY contain a new "continue" response (Section 3.1) as 3156 described above. The response SHOULD NOT contain any interaction 3157 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 3158 wg-gnap/gnap-core-protocol/issues/89) ]] 3160 For example, if the request is successful in causing the AS to issue 3161 access tokens and release opaque subject claims, the response could 3162 look like this: 3164 NOTE: '\' line wrapping per RFC 8792 3166 { 3167 "access_token": { 3168 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3169 "manage": "https://server.example.com/token/PRY5NM33O\ 3170 M4TB8N6BW7OZB8CDFONP219RP1L", 3171 }, 3172 "subject": { 3173 "sub_ids": [ { 3174 "format": "opaque", 3175 "id": "J2G8G8O4AZ" 3176 } ] 3177 } 3178 } 3180 With this example, the client instance can not make an additional 3181 continuation request because a continue field is not included. 3183 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3184 issues/88) ]] 3186 5.2. Continuing During Pending Interaction 3188 When the client instance does not include a finish parameter, the 3189 client instance will often need to poll the AS until the RO has 3190 authorized the request. To do so, the client instance makes a POST 3191 request to the continuation URI as in Section 5.1, but does not 3192 include a message body. 3194 POST /continue HTTP/1.1 3195 Host: server.example.com 3196 Content-Type: application/json 3197 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3198 Signature-Input: sig1=... 3199 Signature: sig1=... 3201 The grant response (Section 3) MAY contain any newly-created access 3202 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3203 The response MAY contain a new "continue" response (Section 3.1) as 3204 described above. If a continue field is included, it SHOULD include 3205 a wait field to facilitate a reasonable polling rate by the client 3206 instance. The response SHOULD NOT contain interaction responses 3207 (Section 3.3). 3209 For example, if the request has not yet been authorized by the RO, 3210 the AS could respond by telling the client instance to make another 3211 continuation request in the future. In this example, a new, unique 3212 access token has been issued for the call, which the client instance 3213 will use in its next continuation request. 3215 { 3216 "continue": { 3217 "access_token": { 3218 "value": "33OMUKMKSKU80UPRY5NM" 3219 }, 3220 "uri": "https://server.example.com/continue", 3221 "wait": 30 3222 } 3223 } 3225 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3226 issues/90) ]] 3228 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3229 issues/91) ]] 3231 If the request is successful in causing the AS to issue access tokens 3232 and release subject claims, the response could look like this 3233 example: 3235 NOTE: '\' line wrapping per RFC 8792 3237 { 3238 "access_token": { 3239 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3240 "manage": "https://server.example.com/token/PRY5NM33O\ 3241 M4TB8N6BW7OZB8CDFONP219RP1L", 3242 }, 3243 "subject": { 3244 "sub_ids": [ { 3245 "format": "opaque", 3246 "id": "J2G8G8O4AZ" 3247 } ] 3248 } 3249 } 3251 See Section 12.20 for considerations on polling for continuation 3252 without an interaction finish method. 3254 5.3. Modifying an Existing Request 3256 The client instance might need to modify an ongoing request, whether 3257 or not tokens have already been issued or claims have already been 3258 released. In such cases, the client instance makes an HTTP PATCH 3259 request to the continuation URI and includes any fields it needs to 3260 modify. Fields that aren't included in the request are considered 3261 unchanged from the original request. 3263 The client instance MAY include the access_token and subject fields 3264 as described in Section 2.1 and Section 2.2. Inclusion of these 3265 fields override any values in the initial request, which MAY trigger 3266 additional requirements and policies by the AS. For example, if the 3267 client instance is asking for more access, the AS could require 3268 additional interaction with the RO to gather additional consent. If 3269 the client instance is asking for more limited access, the AS could 3270 determine that sufficient authorization has been granted to the 3271 client instance and return the more limited access rights 3272 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 3273 core-protocol/issues/92) ]] 3275 The client instance MAY include the interact field as described in 3276 Section 2.5. Inclusion of this field indicates that the client 3277 instance is capable of driving interaction with the RO, and this 3278 field replaces any values from a previous request. The AS MAY 3279 respond to any of the interaction responses as described in 3280 Section 3.3, just like it would to a new request. 3282 The client instance MAY include the user field as described in 3283 Section 2.4 to present new assertions or information about the end- 3284 user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- 3285 protocol/issues/93) ]] 3287 The client instance MUST NOT include the client section of the 3288 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 3289 protocol/issues/94) ]] 3291 The client instance MAY include post-interaction responses such as 3292 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 3293 wg-gnap/gnap-core-protocol/issues/95) ]] 3295 Modification requests MUST NOT alter previously-issued access tokens. 3296 Instead, any access tokens issued from a continuation are considered 3297 new, separate access tokens. The AS MAY revoke existing access 3298 tokens after a modification has occurred. [[ See issue #96 3299 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 3301 If the modified request can be granted immediately by the AS, the 3302 grant response (Section 3) MAY contain any newly-created access 3303 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3304 The response MAY contain a new "continue" response (Section 3.1) as 3305 described above. If interaction can occur, the response SHOULD 3306 contain interaction responses (Section 3.3) as well. 3308 For example, a client instance initially requests a set of resources 3309 using references: 3311 POST /tx HTTP/1.1 3312 Host: server.example.com 3313 Content-Type: application/json 3314 Signature-Input: sig1=... 3315 Signature: sig1=... 3316 Digest: sha256=... 3318 { 3319 "access_token": { 3320 "access": [ 3321 "read", "write" 3322 ] 3323 }, 3324 "interact": { 3325 "start": ["redirect"], 3326 "finish": { 3327 "method": "redirect", 3328 "uri": "https://client.example.net/return/123455", 3329 "nonce": "LKLTI25DK82FX4T4QFZC" 3330 } 3331 }, 3332 "client": "987YHGRT56789IOLK" 3333 } 3335 Access is granted by the RO, and a token is issued by the AS. In its 3336 final response, the AS includes a continue field, which includes a 3337 separate access token for accessing the continuation API: 3339 { 3340 "continue": { 3341 "access_token": { 3342 "value": "80UPRY5NM33OMUKMKSKU" 3343 }, 3344 "uri": "https://server.example.com/continue", 3345 "wait": 30 3346 }, 3347 "access_token": { 3348 "value": "RP1LT0-OS9M2P_R64TB", 3349 "access": [ 3350 "read", "write" 3351 ] 3352 } 3353 } 3354 This continue field allows the client instance to make an eventual 3355 continuation call. In the future, the client instance realizes that 3356 it no longer needs "write" access and therefore modifies its ongoing 3357 request, here asking for just "read" access instead of both "read" 3358 and "write" as before. 3360 PATCH /continue HTTP/1.1 3361 Host: server.example.com 3362 Content-Type: application/json 3363 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3364 Signature-Input: sig1=... 3365 Signature: sig1=... 3366 Digest: sha256=... 3368 { 3369 "access_token": { 3370 "access": [ 3371 "read" 3372 ] 3373 } 3374 ... 3375 } 3377 The AS replaces the previous access from the first request, allowing 3378 the AS to determine if any previously-granted consent already 3379 applies. In this case, the AS would likely determine that reducing 3380 the breadth of the requested access means that new access tokens can 3381 be issued to the client instance. The AS would likely revoke 3382 previously-issued access tokens that had the greater access rights 3383 associated with them, unless they had been issued with the durable 3384 flag. 3386 { 3387 "continue": { 3388 "access_token": { 3389 "value": "M33OMUK80UPRY5NMKSKU" 3390 }, 3391 "uri": "https://server.example.com/continue", 3392 "wait": 30 3393 }, 3394 "access_token": { 3395 "value": "0EVKC7-2ZKwZM_6N760", 3396 "access": [ 3397 "read" 3398 ] 3399 } 3400 } 3401 For another example, the client instance initially requests read-only 3402 access but later needs to step up its access. The initial request 3403 could look like this example. 3405 POST /tx HTTP/1.1 3406 Host: server.example.com 3407 Content-Type: application/json 3408 Signature-Input: sig1=... 3409 Signature: sig1=... 3410 Digest: sha256=... 3412 { 3413 "access_token": { 3414 "access": [ 3415 "read" 3416 ] 3417 }, 3418 "interact": { 3419 "start": ["redirect"], 3420 "finish": { 3421 "method": "redirect", 3422 "uri": "https://client.example.net/return/123455", 3423 "nonce": "LKLTI25DK82FX4T4QFZC" 3424 } 3425 }, 3426 "client": "987YHGRT56789IOLK" 3427 } 3429 Access is granted by the RO, and a token is issued by the AS. In its 3430 final response, the AS includes a continue field: 3432 { 3433 "continue": { 3434 "access_token": { 3435 "value": "80UPRY5NM33OMUKMKSKU" 3436 }, 3437 "uri": "https://server.example.com/continue", 3438 "wait": 30 3439 }, 3440 "access_token": { 3441 "value": "RP1LT0-OS9M2P_R64TB", 3442 "access": [ 3443 "read" 3444 ] 3445 } 3446 } 3447 This allows the client instance to make an eventual continuation 3448 call. The client instance later realizes that it now needs "write" 3449 access in addition to the "read" access. Since this is an expansion 3450 of what it asked for previously, the client instance also includes a 3451 new interaction section in case the AS needs to interact with the RO 3452 again to gather additional authorization. Note that the client 3453 instance's nonce and callback are different from the initial request. 3454 Since the original callback was already used in the initial exchange, 3455 and the callback is intended for one-time-use, a new one needs to be 3456 included in order to use the callback again. 3458 [[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3459 issues/97) ]] 3461 PATCH /continue HTTP/1.1 3462 Host: server.example.com 3463 Content-Type: application/json 3464 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3465 Signature-Input: sig1=... 3466 Signature: sig1=... 3467 Digest: sha256=... 3469 { 3470 "access_token": { 3471 "access": [ 3472 "read", "write" 3473 ] 3474 }, 3475 "interact": { 3476 "start": ["redirect"], 3477 "finish": { 3478 "method": "redirect", 3479 "uri": "https://client.example.net/return/654321", 3480 "nonce": "K82FX4T4LKLTI25DQFZC" 3481 } 3482 } 3483 } 3485 From here, the AS can determine that the client instance is asking 3486 for more than it was previously granted, but since the client 3487 instance has also provided a mechanism to interact with the RO, the 3488 AS can use that to gather the additional consent. The protocol 3489 continues as it would with a new request. Since the old access 3490 tokens are good for a subset of the rights requested here, the AS 3491 might decide to not revoke them. However, any access tokens granted 3492 after this update process are new access tokens and do not modify the 3493 rights of existing access tokens. 3495 5.4. Canceling a Grant Request 3497 If the client instance wishes to cancel an ongoing grant request, it 3498 makes an HTTP DELETE request to the continuation URI. 3500 DELETE /continue HTTP/1.1 3501 Host: server.example.com 3502 Content-Type: application/json 3503 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3504 Signature-Input: sig1=... 3505 Signature: sig1=... 3507 If the request is successfully cancelled, the AS responds with an 3508 HTTP 202. The AS SHOULD revoke all associated access tokens. 3510 6. Token Management 3512 If an access token response includes the "manage" parameter as 3513 described in Section 3.2.1, the client instance MAY call this URL to 3514 manage the access token with any of the actions defined in the 3515 following sections. Other actions are undefined by this 3516 specification. 3518 The access token being managed acts as the access element for its own 3519 management API. The client instance MUST present proof of an 3520 appropriate key along with the access token. 3522 If the token is sender-constrained (i.e., not a bearer token), it 3523 MUST be sent with the appropriate binding for the access token 3524 (Section 7.2). 3526 If the token is a bearer token, the client instance MUST present 3527 proof of the same key identified in the initial request (Section 2.3) 3528 as described in Section 7.3. 3530 The AS MUST validate the proof and assure that it is associated with 3531 either the token itself or the client instance the token was issued 3532 to, as appropriate for the token's presentation type. 3534 6.1. Rotating the Access Token 3536 The client instance makes an HTTP POST to the token management URI, 3537 sending the access token in the appropriate header and signing the 3538 request with the appropriate key. 3540 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3541 Host: server.example.com 3542 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3543 Signature-Input: sig1=... 3544 Signature: sig1=... 3545 Digest: sha256=... 3547 The AS validates that the token presented is associated with the 3548 management URL, that the AS issued the token to the given client 3549 instance, and that the presented key is appropriate to the token. 3551 If the access token has expired, the AS SHOULD honor the rotation 3552 request to the token management URL since it is likely that the 3553 client instance is attempting to refresh the expired token. To 3554 support this, the AS MAY apply different lifetimes for the use of the 3555 token in management vs. its use at an RS. An AS MUST NOT honor a 3556 rotation request for an access token that has been revoked, either by 3557 the AS or by the client instance through the token management URI 3558 (Section 6.2). 3560 If the token is validated and the key is appropriate for the request, 3561 the AS MUST invalidate the current access token associated with this 3562 URL, if possible, and return a new access token response as described 3563 in Section 3.2.1, unless the multi_token flag is specified in the 3564 request. The value of the access token MUST NOT be the same as the 3565 current value of the access token used to access the management API. 3566 The response MAY include an updated access token management URL as 3567 well, and if so, the client instance MUST use this new URL to manage 3568 the new access token. [[ See issue #101 (https://github.com/ietf-wg- 3569 gnap/gnap-core-protocol/issues/101) ]] 3571 [[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core- 3572 protocol/issues/102) ]] 3573 NOTE: '\' line wrapping per RFC 8792 3575 { 3576 "access_token": { 3577 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3578 "manage": "https://server.example.com/token/PRY5NM33O\ 3579 M4TB8N6BW7OZB8CDFONP219RP1L", 3580 "access": [ 3581 { 3582 "type": "photo-api", 3583 "actions": [ 3584 "read", 3585 "write", 3586 "dolphin" 3587 ], 3588 "locations": [ 3589 "https://server.example.net/", 3590 "https://resource.local/other" 3591 ], 3592 "datatypes": [ 3593 "metadata", 3594 "images" 3595 ] 3596 }, 3597 "read", "dolphin-metadata" 3598 ] 3599 } 3600 } 3602 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3603 protocol/issues/103) ]] 3605 6.2. Revoking the Access Token 3607 If the client instance wishes to revoke the access token proactively, 3608 such as when a user indicates to the client instance that they no 3609 longer wish for it to have access or the client instance application 3610 detects that it is being uninstalled, the client instance can use the 3611 token management URI to indicate to the AS that the AS should 3612 invalidate the access token for all purposes. 3614 The client instance makes an HTTP DELETE request to the token 3615 management URI, presenting the access token and signing the request 3616 with the appropriate key. 3618 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3619 Host: server.example.com 3620 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3621 Signature-Input: sig1=... 3622 Signature: sig1=... 3624 If the key presented is associated with the token (or the client 3625 instance, in the case of a bearer token), the AS MUST invalidate the 3626 access token, if possible, and return an HTTP 204 response code. 3628 204 No Content 3630 Though the AS MAY revoke an access token at any time for any reason, 3631 the token management function is specifically for the client 3632 instance's use. If the access token has already expired or has been 3633 revoked through other means, the AS SHOULD honor the revocation 3634 request to the token management URL as valid, since the end result is 3635 still the token not being usable. 3637 7. Securing Requests from the Client Instance 3639 In GNAP, the client instance secures its requests to the AS and RS by 3640 presenting an access token, presenting proof of a key that it 3641 possesses (aka, a "key proof"), or both an access token and key proof 3642 together. 3644 * When an access token is used with a key proof, this is a bound 3645 token request. This type of request is used for calls to the RS 3646 as well as the AS during negotiation. 3648 * When a key proof is used with no access token, this is a non- 3649 authorized signed request. This type of request is used for calls 3650 to the AS to initiate a negotiation. 3652 * When an access token is used with no key proof, this is a bearer 3653 token request. This type of request is used only for calls to the 3654 RS, and only with access tokens that are not bound to any key as 3655 described in Section 3.2.1. 3657 * When neither an access token nor key proof are used, this is an 3658 unsecured request. This type of request is used optionally for 3659 calls to the RS as part of an RS-first discovery process as 3660 described in Section 9.1. 3662 7.1. Key Formats 3664 Several different places in GNAP require the presentation of key 3665 material by value. Proof of this key material MUST be bound to a 3666 request, the nature of which varies with the location in the protocol 3667 the key is used. For a key used as part of a client instance's 3668 initial request in Section 2.3, the key value is the client 3669 instance's public key, and proof of that key MUST be presented in 3670 that request. For a key used as part of an access token response in 3671 Section 3.2.1, the proof of that key MUST be used when presenting the 3672 access token. 3674 A key presented by value MUST be a public key in at least one 3675 supported format. If a key is sent in multiple formats, all the key 3676 format values MUST be equivalent. Note that while most formats 3677 present the full value of the public key, some formats present a 3678 value cryptographically derived from the public key. 3680 proof (string) The form of proof that the client instance will use 3681 when presenting the key. The valid values of this field and the 3682 processing requirements for each are detailed in Section 7.3. The 3683 proof field is REQUIRED. 3685 jwk (object) The public key and its properties represented as a JSON 3686 Web Key [RFC7517]. A JWK MUST contain the alg (Algorithm) and kid 3687 (Key ID) parameters. The alg parameter MUST NOT be "none". The 3688 x5c (X.509 Certificate Chain) parameter MAY be used to provide the 3689 X.509 representation of the provided public key. 3691 cert (string) PEM serialized value of the certificate used to sign 3692 the request, with optional internal whitespace per [RFC7468]. The 3693 PEM header and footer are optionally removed. 3695 cert#S256 (string) The certificate thumbprint calculated as per 3696 OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this 3697 format does not include the full public key. 3699 Additional key formats are defined in a registry TBD (Section 11). 3701 This non-normative example shows a single key presented in multiple 3702 formats. This example key is intended to be used with the HTTP 3703 Message Signatures ({{httpsig-binding}}) proofing mechanism, as 3704 indicated by the httpsig value of the proof field. 3706 "key": { 3707 "proof": "httpsig", 3708 "jwk": { 3709 "kty": "RSA", 3710 "e": "AQAB", 3711 "kid": "xyz-1", 3712 "alg": "RS256", 3713 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 3714 }, 3715 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 3716 } 3718 7.1.1. Key References 3720 Keys in GNAP can also be passed by reference such that the party 3721 receiving the reference will be able to determine the appropriate 3722 keying material for use in that part of the protocol. 3724 "key": "S-P4XJQ_RYJCRTSU1.63N3E" 3726 Keys referenced in this manner MAY be shared symmetric keys. The key 3727 reference MUST NOT contain any unencrypted private or shared 3728 symmetric key information. 3730 Keys referenced in this manner MUST be bound to a single proofing 3731 mechanism. 3733 The means of dereferencing this value are out of scope for this 3734 specification. 3736 7.2. Presenting Access Tokens 3738 The method the client instance uses to send an access token depends 3739 on whether the token is bound to a key, and if so which proofing 3740 method is associated with the key. This information is conveyed by 3741 the key parameter and the bearer flag in the single (Section 3.2.1) 3742 and multiple access tokens (Section 3.2.2) responses. 3744 If the flags field does not contain the bearer flag and the key is 3745 absent, the access token MUST be sent using the same key and proofing 3746 mechanism that the client instance used in its initial request (or 3747 its most recent rotation). 3749 If the flags field does not contain the bearer flag and the key value 3750 is an object as described in Section 7.1, the access token MUST be 3751 sent using the key and proofing mechanism defined by the value of the 3752 proof field within the key object. 3754 The access token MUST be sent using the HTTP "Authorization" request 3755 header field and the "GNAP" authorization scheme along with a key 3756 proof as described in Section 7.3 for the key bound to the access 3757 token. For example, an "httpsig"-bound access token is sent as 3758 follows: 3760 NOTE: '\' line wrapping per RFC 8792 3762 GET /stuff HTTP/1.1 3763 Host: resource.example.com 3764 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3765 Signature-Input: sig1=("@method" "@target-uri" "authorization")\ 3766 ;created=1618884475;keyid="gnap-rsa" 3767 Signature: sig1=:KymTn1/++nwWsNHdc48sguMjnVSnvqQNrijQT0/kXDfljaIgHl\ 3768 o12NkEt4e5qZeCFutzRxWpHKtjVEDldIUSsktxj4Li7PgUNJtIkJkdA1EoebGz1X/\ 3769 AD3coqYpoaFsOcPyfXjYHYWFd8HxLOUz3imA8xbxS+J9GZAjyDjTfG6yfsMsfd10f\ 3770 nrDRJqalPNDEgOOwwyEtjht4MnzpV1Wf43YWwgEJOC2rvxPIeuNxWbUc5v/o3s3Zr\ 3771 ywo2sunUcwXwlmbgyiGY0vgGFWjdHfgKvjda7eNLTr7r3jPgo/GlOB3jyadD4xcKs\ 3772 S/idS3RGk1+e9jbGHK5cRTp0ZzF94kWw==: 3774 If the flags field contains the bearer flag, the access token is a 3775 bearer token that MUST be sent using the Authorization Request Header 3776 Field method defined in [RFC6750]. 3778 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3780 The Form-Encoded Body Parameter and URI Query Parameter methods of 3781 [RFC6750] MUST NOT be used. 3783 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3784 protocol/issues/104) ]] 3786 The client software MUST reject as an error a situation where the 3787 flags field contains the bearer flag and the key field is present 3788 with any value. 3790 7.3. Proving Possession of a Key with a Request 3792 Any keys presented by the client instance to the AS or RS MUST be 3793 validated as part of the request in which they are presented. The 3794 type of binding used is indicated by the proof parameter of the key 3795 object in Section 7.1. Values defined by this specification are as 3796 follows: 3798 httpsig HTTP Signing signature header 3800 mtls Mutual TLS certificate verification 3801 jwsd A detached JWS signature header 3803 jws Attached JWS payload 3805 Additional proofing methods are defined by a registry TBD 3806 (Section 11). 3808 All key binding methods used by this specification MUST cover all 3809 relevant portions of the request, including anything that would 3810 change the nature of the request, to allow for secure validation of 3811 the request. Relevant aspects include the URI being called, the HTTP 3812 method being used, any relevant HTTP headers and values, and the HTTP 3813 message body itself. The verifier of the signed message MUST 3814 validate all components of the signed message to ensure that nothing 3815 has been tampered with or substituted in a way that would change the 3816 nature of the request. Key binding method definitions SHOULD 3817 enumerate how these requirements are fulfilled. 3819 When a key proofing mechanism is bound to an access token, the key 3820 being presented MUST be the key associated with the access token and 3821 the access token MUST be covered by the signature method of the 3822 proofing mechanism. 3824 The key binding methods in this section MAY be used by other 3825 components making calls as part of GNAP, such as the extensions 3826 allowing the RS to make calls to the AS defined in 3827 [I-D.ietf-gnap-resource-servers]. To facilitate this extended use, 3828 the sections below are defined in generic terms of the "signer" and 3829 "verifier" of the HTTP message. In the core functions of GNAP, the 3830 "signer" is the client instance and the "verifier" is the AS or RS, 3831 as appropriate. 3833 When used for delegation in GNAP, these key binding mechanisms allow 3834 the AS to ensure that the keys presented by the client instance in 3835 the initial request are in control of the party calling any follow-up 3836 or continuation requests. To facilitate this requirement, the 3837 continuation response (Section 3.1) includes an access token bound to 3838 the client instance's key (Section 2.3), and that key (or its most 3839 recent rotation) MUST be proved in all continuation requests 3840 Section 5. Token management requests Section 6 are similarly bound 3841 to either the access token's own key or, in the case of bearer 3842 tokens, the client instance's key. 3844 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 3845 protocol/issues/105) ]] 3846 In the following sections, unless otherwise noted, the RS256 JOSE 3847 Signature Algorithm is applied using the following RSA key (presented 3848 here in JWK format): 3850 NOTE: '\' line wrapping per RFC 8792 3852 { 3853 "kid": "gnap-rsa", 3854 "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ 3855 i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ 3856 eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", 3857 "kty": "RSA", 3858 "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ 3859 LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ 3860 JXMxOLyPjzuVgiTOCBIvLD6-8-mvFjXZk_eefD0at6mQ5qV3U1jZt88", 3861 "d": "FHlhdTF0ozTliDxMBffT6aJVKZKmbbFJOVNten9c3lXKB3ux3NAb_D2dB\ 3862 7inp9EV23oWrDspFtvCvD9dZrXgRKMHofkEpo_SSvBZfgtH-OTkbY_TqtPF\ 3863 FLPKAw0JX5cFPnn4Q2xE4n-dQ7tpRCKl59vZLHBrHShr90zqzFp0AKXU5fj\ 3864 b1gC9LPwsFA2Fd7KXmI1drQQEVq9R-o18Pnn4BGQNQNjO_VkcJTiBmEIVT_\ 3865 KJRPdpVJAmbgnYWafL_hAfeb_dK8p85yurEVF8nCK5oO3EPrqB7IL4UqaEn\ 3866 5Sl3u0j8x5or-xrrAoNz-gdOv7ONfZY6NFoa-3f8q9wBAHUuQ", 3867 "e": "AQAB", 3868 "qi": "ogpNEkDKg22Rj9cDV_-PJBZaXMk66Fp557RT1tafIuqJRHEufSOYnsto\ 3869 bWPJ0gHxv1gVJw3gm-zYvV-wTMNgr2wVsBSezSJjPSjxWZtmT2z68W1DuvK\ 3870 kZy15vz7Jd85hmDlriGcXNCoFEUsGLWkpHH9RwPIzguUHWmTt8y0oXyI", 3871 "dp": "dvCKGI2G7RLh3WyjoJ_Dr6hZ3LhXweB3YcY3qdD9BnxZ71mrLiMQg4c_\ 3872 EBnwqCETN_5sStn2cRc2JXnvLP3G8t7IFKHTT_i_TSTacJ7uT04MSa053Y3\ 3873 RfwbvLjRNPR0UKAE3ZxROUoIaVNuU_6-QMf8-2ilUv2GIOrCN87gP_Vk", 3874 "alg": "RS256", 3875 "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ 3876 M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ 3877 Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", 3878 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ 3879 YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ 3880 jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ 3881 e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ 3882 bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ 3883 zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3884 } 3886 7.3.1. HTTP Message Signing 3888 This method is indicated by httpsig in the proof field. The signer 3889 creates an HTTP Message Signature as described in 3890 [I-D.ietf-httpbis-message-signatures]. 3892 The message components of the signature MUST include the following: 3894 @method: the method used in the HTTP request 3896 @target-uri: the full request URL of the HTTP request 3898 content-digest or digest: The Content-Digest or Digest header as 3899 defined in [I-D.ietf-httpbis-digest-headers]. When the request 3900 message has a body, the signer MUST calculate this header value 3901 and the verifier MUST validate this field value. Use of Content- 3902 Digest is RECOMMENDED. Use of content-encoding agnostic digest 3903 methods (such as id-sha-256) is RECOMMENDED. 3905 When the request is bound to an access token, the covered content 3906 MUST also include: 3908 authorization: The Authorization header used to present the access 3909 token as discussed in Section 7.2. 3911 Other message components MAY also be included. 3913 If the signer's key presented is a JWK, the keyid parameter of the 3914 signature MUST be set to the kid value of the JWK, the signing 3915 algorithm used MUST be the JWS algorithm denoted by the key's alg 3916 field, and the explicit alg signature parameter MUST NOT be included. 3918 In this example, the message body is the following JSON object: 3920 NOTE: '\' line wrapping per RFC 8792 3922 { 3923 "access_token": { 3924 "access": [ 3925 "dolphin-metadata" 3926 ] 3927 }, 3928 "interact": { 3929 "start": ["redirect"], 3930 "finish": { 3931 "method": "redirect", 3932 "uri": "https://client.foo/callback", 3933 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3934 } 3935 }, 3936 "client": { 3937 "proof": "httpsig", 3938 "key": { 3939 "jwk": { 3940 "kid": "gnap-rsa", 3941 "kty": "RSA", 3942 "e": "AQAB", 3943 "alg": "RS256", 3944 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3945 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3946 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3947 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3948 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3949 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3950 } 3951 } 3952 "display": { 3953 "name": "My Client Display Name", 3954 "uri": "https://client.foo/" 3955 }, 3956 } 3957 } 3959 This body is hashed for the Content-Digest header using id-sha-256 3960 into the following encoded value: 3962 id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3964 The HTTP message signature input string is calculated to be the 3965 following: 3967 NOTE: '\' line wrapping per RFC 8792 3969 "@method": POST 3970 "@target-uri": https://server.example.com/gnap 3971 "content-type": application/json 3972 "content-digest": id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+Crwwv\ 3973 UoiaDCSjKxw= 3974 "content-length": 986 3975 "@signature-params": ("@method" "@target-uri" "content-type" \ 3976 "content-digest" "content-length");created=1618884475\ 3977 ;keyid="gnap-rsa" 3979 This leads to the following full HTTP message request: 3981 NOTE: '\' line wrapping per RFC 8792 3983 POST /gnap HTTP/1.1 3984 Host: server.example.com 3985 Content-Type: application/json 3986 Content-Length: 986 3987 Content-Digest: id-sha-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSj\ 3988 Kxw= 3989 Signature-Input: sig1=("@method" "@target-uri" "content-type" \ 3990 "content-digest" "content-length");created=1618884475\ 3991 ;keyid="gnap-rsa" 3992 Signature: sig1=:SatKrAh2qNxbDBY6H3XUtpWn07aSrukpi3202L4DIPLLGgKdSu\ 3993 XyObjdCK/agmEx36xyn40iiCAqYskXugpNARianBiWKOkcWHhSs31FSTSoJ8vvGpJ\ 3994 4GxemDPvI6BXmLZtJvYBehoXtfcRFKGLzYOtbbtefzw2vP+k19W4PrhNmxFEUCepT\ 3995 KRk0sBoz4zIYK6FqEAHir0oRjwdCcXHFqI9U6+/DgpuxjFFX+OSZehmN6Q1quJgu0\ 3996 FITmsC9OANs5hwIAkXGJNdv3FuxAZAVrSnUScuGutSJXAn1daXToewVgBA+IrQ86m\ 3997 lsXtWgvmTTXENUvOELV6qTV2nenwr/UQ==: 3999 { 4000 "access_token": { 4001 "access": [ 4002 "dolphin-metadata" 4003 ] 4004 }, 4005 "interact": { 4006 "start": ["redirect"], 4007 "finish": { 4008 "method": "redirect", 4009 "uri": "https://client.foo/callback", 4010 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4011 } 4012 }, 4013 "client": { 4014 "proof": "httpsig", 4015 "key": { 4016 "jwk": { 4017 "kid": "gnap-rsa", 4018 "kty": "RSA", 4019 "e": "AQAB", 4020 "alg": "RS256", 4021 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4022 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4023 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4024 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4025 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4026 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4027 } 4028 } 4029 "display": { 4030 "name": "My Client Display Name", 4031 "uri": "https://client.foo/" 4032 }, 4033 } 4034 } 4036 If the HTTP Message includes a message body, the verifier MUST 4037 calculate and verify the value of the Digest or Content-Digest 4038 header. The verifier MUST ensure that the signature covers all 4039 required message components. The verifier MUST validate the 4040 signature against the expected key of the signer. 4042 7.3.2. Mutual TLS 4044 This method is indicated by mtls in the proof field. The signer 4045 presents its TLS client certificate during TLS negotiation with the 4046 verifier. 4048 In this example, the certificate is communicated to the application 4049 through the Client-Cert header from a TLS reverse proxy, leading to 4050 the following full HTTP request message: 4052 POST /gnap HTTP/1.1 4053 Host: server.example.com 4054 Content-Type: application/jose 4055 Content-Length: 1567 4056 Client-Cert: \ 4057 :MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM\ 4058 K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN\ 4059 MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq\ 4060 c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG\ 4061 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB\ 4062 kI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8I\ 4063 kZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn11V2vxE4\ 4064 1hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo+\ 4065 uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKXfGhi3k\ 4066 OzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0GCSqG\ 4067 SIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/XsWfCE\ 4068 wHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5NH9\ 4069 W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeCgu\ 4070 NMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHlU\ 4071 fn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4072 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx: 4074 { 4075 "access_token": { 4076 "access": [ 4077 "dolphin-metadata" 4078 ] 4079 }, 4080 "interact": { 4081 "start": ["redirect"], 4082 "finish": { 4083 "method": "redirect", 4084 "uri": "https://client.foo/callback", 4085 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4086 } 4087 }, 4088 "client": { 4089 "proof": "jws", 4090 "key": { 4091 "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ 4092 YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ 4093 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 4094 DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ 4095 jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ 4096 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 4097 KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ 4098 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 4099 z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ 4100 fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ 4101 GCSqGSIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/Xs\ 4102 WfCEwHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5\ 4103 NH9W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeC\ 4104 guNMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHl\ 4105 Ufn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4106 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx" 4107 } 4108 "display": { 4109 "name": "My Client Display Name", 4110 "uri": "https://client.foo/" 4111 }, 4112 }, 4113 "subject": { 4114 "formats": ["iss_sub", "opaque"] 4115 } 4116 } 4118 The verifier compares the TLS client certificate presented during 4119 mutual TLS negotiation to the expected key of the signer. Since the 4120 TLS connection covers the entire message, there are no additional 4121 requirements to check. 4123 Note that in many instances, the verifier will not do a full 4124 certificate chain validation of the presented TLS client certificate, 4125 as the means of trust for this certificate could be in something 4126 other than a PKI system, such as a static registration or trust-on- 4127 first-use. See Section 12.16 and Section 12.17 for some additional 4128 considerations for this key proofing method. 4130 7.3.3. Detached JWS 4132 This method is indicated by jwsd in the proof field. A JWS [RFC7515] 4133 object is created as follows: 4135 To protect the request, the JOSE header of the signature contains the 4136 following parameters: 4138 kid (string) The key identifier. RECOMMENDED. If the key is 4139 presented in JWK format, this MUST be the value of the kid field 4140 of the key. 4142 alg (string) The algorithm used to sign the request. REQUIRED. 4143 MUST be appropriate to the key presented. If the key is presented 4144 as a JWK, this MUST be equal to the alg parameter of the key. 4145 MUST NOT be none. 4147 typ (string) The type header, value "gnap-binding+jwsd". REQUIRED 4149 htm (string) The HTTP Method used to make this request, as an 4150 uppercase ASCII string. REQUIRED 4152 uri (string) The HTTP URI used for this request, including all path 4153 and query components and no fragment component. REQUIRED 4155 created (integer) A timestamp of when the signature was created, in 4156 integer seconds since UNIX Epoch 4158 ath (string) When a request is bound to an access token, the access 4159 token hash value. The value MUST be the result of Base64url 4160 encoding (with no padding) the SHA-256 digest of the ASCII 4161 encoding of the associated access token's value. REQUIRED if the 4162 request protects an access token. 4164 If the HTTP request has a message body, such as an HTTP POST or PUT 4165 method, the payload of the JWS object is the Base64url encoding 4166 (without padding) of the SHA256 digest of the bytes of the body. If 4167 the request being made does not have a message body, such as an HTTP 4168 GET, OPTIONS, or DELETE method, the JWS signature is calculated over 4169 an empty payload. 4171 The signer presents the signed object in compact form [RFC7515] in 4172 the Detached-JWS HTTP Header field. 4174 In this example, the JOSE Header contains the following parameters: 4176 { 4177 "alg": "RS256", 4178 "kid": "gnap-rsa", 4179 "uri": "https://server.example.com/gnap", 4180 "htm": "POST", 4181 "typ": "gnap-binding+jwsd", 4182 "created": 1618884475 4183 } 4185 The request body is the following JSON object: 4187 NOTE: '\' line wrapping per RFC 8792 4189 { 4190 "access_token": { 4191 "access": [ 4192 "dolphin-metadata" 4193 ] 4194 }, 4195 "interact": { 4196 "start": ["redirect"], 4197 "finish": { 4198 "method": "redirect", 4199 "uri": "https://client.foo/callback", 4200 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4201 } 4202 }, 4203 "client": { 4204 "proof": "jwsd", 4205 "key": { 4206 "jwk": { 4207 "kid": "gnap-rsa", 4208 "kty": "RSA", 4209 "e": "AQAB", 4210 "alg": "RS256", 4211 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4212 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4213 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4214 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4215 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4216 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4217 } 4218 } 4219 "display": { 4220 "name": "My Client Display Name", 4221 "uri": "https://client.foo/" 4222 }, 4223 } 4224 } 4226 This is hashed to the following Base64 encoded value: 4228 PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc 4230 This leads to the following full HTTP request message: 4232 NOTE: '\' line wrapping per RFC 8792 4234 POST /gnap HTTP/1.1 4235 Host: server.example.com 4236 Content-Type: application/json 4237 Content-Length: 983 4238 Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ 4239 SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ 4240 NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ 4241 ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ 4242 TZA2h5YeXUoi5F2Q2iToC0Tc4drYFOSHIX68knd68RUA7yHqCVP-ZQEd6aL32H69e\ 4243 9zuMiw6O_s4TBKB3vDOvwrhYtDH6fX2hP70cQoO-47OwbqP-ifkrvI3hVgMX9TfjV\ 4244 eKNwnhoNnw3vbu7SNKeqJEbbwZfpESaGepS52xNBlDNMYBQQXxM9OqKJaXffzLFEl\ 4245 -Xe0UnfolVtBraz3aPrPy1C6a4uT7wLda3PaTOVtgysxzii3oJWpuz0WP5kRujzDF\ 4246 wX_EOzW0jsjCSkL-PXaKSpZgEjNjKDMg9irSxUISt1C1T6q3SzRgfuQ 4248 { 4249 "access_token": { 4250 "access": [ 4251 "dolphin-metadata" 4252 ] 4253 }, 4254 "interact": { 4255 "start": ["redirect"], 4256 "finish": { 4257 "method": "redirect", 4258 "uri": "https://client.foo/callback", 4259 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4260 } 4261 }, 4262 "client": { 4263 "proof": "jwsd", 4264 "key": { 4265 "jwk": { 4266 "kid": "gnap-rsa", 4267 "kty": "RSA", 4268 "e": "AQAB", 4269 "alg": "RS256", 4270 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4271 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4272 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4273 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4274 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4275 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4276 } 4277 } 4278 "display": { 4279 "name": "My Client Display Name", 4280 "uri": "https://client.foo/" 4281 }, 4282 } 4283 } 4285 When the verifier receives the Detached-JWS header, it MUST parse and 4286 validate the JWS object. The signature MUST be validated against the 4287 expected key of the signer. All required fields MUST be present and 4288 their values MUST be valid. If the HTTP message request contains a 4289 body, the verifier MUST calculate the hash of body just as the signer 4290 does, with no normalization or transformation of the request. 4292 7.3.4. Attached JWS 4294 This method is indicated by jws in the proof field. A JWS [RFC7515] 4295 object is created as follows: 4297 The JOSE header MUST contain the kid parameter of the key bound to 4298 this signer for this request. The alg parameter MUST be set to a 4299 value appropriate for the key identified by kid and MUST NOT be none. 4301 To protect the request, the JWS header MUST contain the following 4302 additional parameters. 4304 typ (string) The type header, value "gnap-binding+jws". 4306 htm (string) The HTTP Method used to make this request, as an 4307 uppercase ASCII string. 4309 uri (string) The HTTP URI used for this request, including all path 4310 and query components and no fragment component. 4312 created (integer) A timestamp of when the signature was created, in 4313 integer seconds since UNIX Epoch 4315 ath (string) When a request is bound to an access token, the access 4316 token hash value. The value MUST be the result of Base64url 4317 encoding (with no padding) the SHA-256 digest of the ASCII 4318 encoding of the associated access token's value. 4320 If the HTTP request has a message body, such as an HTTP POST or PUT 4321 method, the payload of the JWS object is the JSON serialized body of 4322 the request, and the object is signed according to JWS and serialized 4323 into compact form [RFC7515]. The signer presents the JWS as the body 4324 of the request along with a content type of application/jose. The 4325 verifier MUST extract the payload of the JWS and treat it as the 4326 request body for further processing. 4328 If the request being made does not have a message body, such as an 4329 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 4330 over an empty payload and passed in the Detached-JWS header as 4331 described in Section 7.3.3. 4333 In this example, the JOSE header contains the following parameters: 4335 { 4336 "alg": "RS256", 4337 "kid": "gnap-rsa", 4338 "uri": "https://server.example.com/gnap", 4339 "htm": "POST", 4340 "typ": "gnap-binding+jwsd", 4341 "created": 1618884475 4342 } 4344 The request body, used as the JWS Payload, is the following JSON 4345 object: 4347 NOTE: '\' line wrapping per RFC 8792 4349 { 4350 "access_token": { 4351 "access": [ 4352 "dolphin-metadata" 4353 ] 4354 }, 4355 "interact": { 4356 "start": ["redirect"], 4357 "finish": { 4358 "method": "redirect", 4359 "uri": "https://client.foo/callback", 4360 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4361 } 4362 }, 4363 "client": { 4364 "proof": "jws", 4365 "key": { 4366 "jwk": { 4367 "kid": "gnap-rsa", 4368 "kty": "RSA", 4369 "e": "AQAB", 4370 "alg": "RS256", 4371 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4372 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4373 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4374 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4375 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4376 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4377 } 4378 } 4379 "display": { 4380 "name": "My Client Display Name", 4381 "uri": "https://client.foo/" 4382 }, 4383 }, 4384 "subject": { 4385 "formats": ["iss_sub", "opaque"] 4386 } 4387 } 4389 This leads to the following full HTTP request message: 4391 NOTE: '\' line wrapping per RFC 8792 4393 POST /gnap HTTP/1.1 4394 Host: server.example.com 4395 Content-Type: application/jose 4396 Content-Length: 1047 4398 eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ 4399 raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ 4400 R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ 4401 ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\ 4402 0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\ 4403 Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\ 4404 CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\ 4405 cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\ 4406 KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\ 4407 ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\ 4408 ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\ 4409 Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\ 4410 gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\ 4411 5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\ 4412 nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\ 4413 akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\ 4414 xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\ 4415 BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\ 4416 XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\ 4417 YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ 4418 gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ 4419 FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ 4420 AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ 4421 c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ 4422 vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ 4423 u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ 4424 LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ 4425 PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ 4426 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 4428 [[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core- 4429 protocol/issues/109) ]] 4431 When the verifier receives an attached JWS request, it MUST parse and 4432 validate the JWS object. The signature MUST be validated against the 4433 expected key of the signer. All required fields MUST be present and 4434 their values MUST be valid. If the HTTP message request contains a 4435 body, the verifier MUST decode the payload of the JWS object and 4436 treat this as the HTTP message body. 4438 8. Resource Access Rights 4440 GNAP provides a rich structure for describing the protected resources 4441 hosted by RSs and accessed by client software. This structure is 4442 used when the client instance requests an access token (Section 2.1) 4443 and when an access token is returned (Section 3.2). 4445 The root of this structure is a JSON array. The elements of the JSON 4446 array represent rights of access that are associated with the the 4447 access token. The resulting access is the union of all elements 4448 within the array. 4450 The access associated with the access token is described using 4451 objects that each contain multiple dimensions of access. Each object 4452 contains a REQUIRED type property that determines the type of API 4453 that the token is used for. 4455 type (string) The type of resource request as a string. This field 4456 MAY define which other fields are allowed in the request object. 4457 This field is REQUIRED. 4459 The value of the type field is under the control of the AS. This 4460 field MUST be compared using an exact byte match of the string value 4461 against known types by the AS. The AS MUST ensure that there is no 4462 collision between different authorization data types that it 4463 supports. The AS MUST NOT do any collation or normalization of data 4464 types during comparison. It is RECOMMENDED that designers of 4465 general-purpose APIs use a URI for this field to avoid collisions 4466 between multiple API types protected by a single AS. 4468 While it is expected that many APIs will have their own properties, a 4469 set of common properties are defined here. Specific API 4470 implementations SHOULD NOT re-use these fields with different 4471 semantics or syntax. The available values for these properties are 4472 determined by the API being protected at the RS. 4474 actions (array of strings) The types of actions the client instance 4475 will take at the RS as an array of strings. For example, a client 4476 instance asking for a combination of "read" and "write" access. 4478 locations (array of strings) The location of the RS as an array of 4479 strings. These strings are typically URIs identifying the 4480 location of the RS. 4482 datatypes (array of strings) The kinds of data available to the 4483 client instance at the RS's API as an array of strings. For 4484 example, a client instance asking for access to raw "image" data 4485 and "metadata" at a photograph API. 4487 identifier (string) A string identifier indicating a specific 4488 resource at the RS. For example, a patient identifier for a 4489 medical API or a bank account number for a financial API. 4491 privileges (array of strings) The types or levels of privilege being 4492 requested at the resource. For example, a client instance asking 4493 for administrative level access, or access when the resource owner 4494 is no longer online. 4496 The following non-normative example is describing three kinds of 4497 access (read, write, delete) to each of two different locations and 4498 two different data types (metadata, images) for a single access token 4499 using the fictitious photo-api type definition. 4501 "access": [ 4502 { 4503 "type": "photo-api", 4504 "actions": [ 4505 "read", 4506 "write", 4507 "delete" 4508 ], 4509 "locations": [ 4510 "https://server.example.net/", 4511 "https://resource.local/other" 4512 ], 4513 "datatypes": [ 4514 "metadata", 4515 "images" 4516 ] 4517 } 4518 ] 4520 The access requested for a given object when using these fields is 4521 the cross-product of all fields of the object. That is to say, the 4522 object represents a request for all actions listed to be used at all 4523 locations listed for all possible datatypes listed within the object. 4524 Assuming the request above was granted, the client instance could 4525 assume that it would be able to do a read action against the images 4526 on the first server as well as a delete action on the metadata of the 4527 second server, or any other combination of these fields, using the 4528 same access token. 4530 To request a different combination of access, such as requesting one 4531 of the possible actions against one of the possible locations and a 4532 different choice of possible actions against a different one of the 4533 possible locations, the client instance can include multiple separate 4534 objects in the resources array. The following non-normative example 4535 uses the same fictitious photo-api type definition to request a 4536 single access token with more specifically targeted access rights by 4537 using two discrete objects within the request. 4539 "access": [ 4540 { 4541 "type": "photo-api", 4542 "actions": [ 4543 "read" 4544 ], 4545 "locations": [ 4546 "https://server.example.net/" 4547 ], 4548 "datatypes": [ 4549 "images" 4550 ] 4551 }, 4552 { 4553 "type": "photo-api", 4554 "actions": [ 4555 "write", 4556 "delete" 4557 ], 4558 "locations": [ 4559 "https://resource.local/other" 4560 ], 4561 "datatypes": [ 4562 "metadata" 4563 ] 4564 } 4565 ] 4567 The access requested here is for read access to images on one server 4568 while simultaneously requesting write and delete access for metadata 4569 on a different server, but importantly without requesting write or 4570 delete access to images on the first server. 4572 It is anticipated that API designers will use a combination of common 4573 fields defined in this specification as well as fields specific to 4574 the API itself. The following non-normative example shows the use of 4575 both common and API-specific fields as part of two different 4576 fictitious API type values. The first access request includes the 4577 actions, locations, and datatypes fields specified here as well as 4578 the API-specific geolocation field. The second access request 4579 includes the actions and identifier fields specified here as well as 4580 the API-specific currency field. 4582 "access": [ 4583 { 4584 "type": "photo-api", 4585 "actions": [ 4586 "read", 4587 "write" 4588 ], 4589 "locations": [ 4590 "https://server.example.net/", 4591 "https://resource.local/other" 4592 ], 4593 "datatypes": [ 4594 "metadata", 4595 "images" 4596 ], 4597 "geolocation": [ 4598 { lat: -32.364, lng: 153.207 }, 4599 { lat: -35.364, lng: 158.207 } 4600 ] 4601 }, 4602 { 4603 "type": "financial-transaction", 4604 "actions": [ 4605 "withdraw" 4606 ], 4607 "identifier": "account-14-32-32-3", 4608 "currency": "USD" 4609 } 4610 ] 4612 If this request is approved, the resulting access token 4613 (Section 3.2.1)'s access rights will be the union of the requested 4614 types of access for each of the two APIs, just as above. 4616 8.1. Requesting Resources By Reference 4618 Instead of sending an object describing the requested resource 4619 (Section 8), access rights MAY be communicated as a string known to 4620 the AS or RS representing the access being requested. Each string 4621 SHOULD correspond to a specific expanded object representation at the 4622 AS. 4624 "access": [ 4625 "read", "dolphin-metadata", "some other thing" 4626 ] 4627 This value is opaque to the client instance and MAY be any valid JSON 4628 string, and therefore could include spaces, unicode characters, and 4629 properly escaped string sequences. However, in some situations the 4630 value is intended to be seen and understood by the client software's 4631 developer. In such cases, the API designer choosing any such human- 4632 readable strings SHOULD take steps to ensure the string values are 4633 not easily confused by a developer, such as by limiting the strings 4634 to easily disambiguated characters. 4636 This functionality is similar in practice to OAuth 2.0's scope 4637 parameter [RFC6749], where a single string represents the set of 4638 access rights requested by the client instance. As such, the 4639 reference string could contain any valid OAuth 2.0 scope value as in 4640 Appendix D.5. Note that the reference string here is not bound to 4641 the same character restrictions as in OAuth 2.0's scope definition. 4643 A single access array MAY include both object-type and string-type 4644 resource items. In this non-normative example, the client instance 4645 is requesting access to a photo-api and financial-transaction API 4646 type as well as the reference values of read, dolphin-metadata, and 4647 some other thing. 4649 "access": [ 4650 { 4651 "type": "photo-api", 4652 "actions": [ 4653 "read", 4654 "write", 4655 "delete" 4656 ], 4657 "locations": [ 4658 "https://server.example.net/", 4659 "https://resource.local/other" 4660 ], 4661 "datatypes": [ 4662 "metadata", 4663 "images" 4664 ] 4665 }, 4666 "read", 4667 "dolphin-metadata", 4668 { 4669 "type": "financial-transaction", 4670 "actions": [ 4671 "withdraw" 4672 ], 4673 "identifier": "account-14-32-32-3", 4674 "currency": "USD" 4675 }, 4676 "some other thing" 4677 ] 4679 The requested access is the union of all elements of the array, 4680 including both objects and reference strings. 4682 9. Discovery 4684 By design, the protocol minimizes the need for any pre-flight 4685 discovery. To begin a request, the client instance only needs to 4686 know the endpoint of the AS and which keys it will use to sign the 4687 request. Everything else can be negotiated dynamically in the course 4688 of the protocol. 4690 However, the AS can have limits on its allowed functionality. If the 4691 client instance wants to optimize its calls to the AS before making a 4692 request, it MAY send an HTTP OPTIONS request to the grant request 4693 endpoint to retrieve the server's discovery information. The AS MUST 4694 respond with a JSON document containing the following information: 4696 grant_request_endpoint (string) REQUIRED. The location of the AS's 4697 grant request endpoint. The location MUST be a URL [RFC3986] with 4698 a scheme component that MUST be https, a host component, and 4699 optionally, port, path and query components and no fragment 4700 components. This URL MUST match the URL the client instance used 4701 to make the discovery request. 4703 interaction_start_modes_supported (array of strings) OPTIONAL. A 4704 list of the AS's interaction start methods. The values of this 4705 list correspond to the possible values for the interaction start 4706 section (Section 2.5.1) of the request. 4708 interaction_finish_methods_supported (array of strings) OPTIONAL. A 4709 list of the AS's interaction finish methods. The values of this 4710 list correspond to the possible values for the method element of 4711 the interaction finish section (Section 2.5.2) of the request. 4713 key_proofs_supported (array of strings) OPTIONAL. A list of the 4714 AS's supported key proofing mechanisms. The values of this list 4715 correspond to possible values of the proof field of the key 4716 section (Section 7.1) of the request. 4718 subject_formats_supported (array of strings) OPTIONAL. A list of 4719 the AS's supported subject identifier types. The values of this 4720 list correspond to possible values of the subject identifier 4721 section (Section 2.2) of the request. 4723 assertions_supported (array of strings) OPTIONAL. A list of the 4724 AS's supported assertion formats. The values of this list 4725 correspond to possible values of the subject assertion section 4726 (Section 2.2) of the request. 4728 The information returned from this method is for optimization 4729 purposes only. The AS MAY deny any request, or any portion of a 4730 request, even if it lists a capability as supported. For example, a 4731 given client instance can be registered with the mtls key proofing 4732 mechanism, but the AS also returns other proofing methods, then the 4733 AS will deny a request from that client instance using a different 4734 proofing mechanism. 4736 9.1. RS-first Method of AS Discovery 4738 If the client instance calls an RS without an access token, or with 4739 an invalid access token, the RS MAY respond to the client instance 4740 with an authentication header indicating that GNAP needs to be used 4741 to access the resource. The address of the GNAP endpoint MUST be 4742 sent in the "as_uri" parameter. The RS MAY additionally return a 4743 resource reference that the client instance MAY use in its access 4744 token request. This resource reference MUST be sufficient for at 4745 least the action the client instance was attempting to take at the RS 4746 and MAY be more powerful. The means for the RS to determine the 4747 resource reference are out of scope of this specification, but some 4748 dynamic methods are discussed in [I-D.ietf-gnap-resource-servers]. 4749 The content of the resource reference is opaque to the client 4750 instance. 4752 NOTE: '\' line wrapping per RFC 8792 4754 WWW-Authenticate: \ 4755 GNAP as_uri=https://server.example/tx,access=FWWIKYBQ6U56NL1 4757 The client instance then makes a request to the "as_uri" as described 4758 in Section 2, with the value of "access" as one of the members of the 4759 access array in the access_token portion of the request. The client 4760 instance MAY request additional resources and other information. The 4761 client instance MAY request multiple access tokens. 4763 In this non-normative example, the client instance is requesting a 4764 single access token using the resource reference FWWIKYBQ6U56NL1 4765 received from the RS in addition to the dolphin-metadata resource 4766 reference that the client instance has been configured with out of 4767 band. 4769 POST /tx HTTP/1.1 4770 Host: server.example.com 4771 Content-Type: application/json 4772 Signature-Input: sig1=... 4773 Signature: sig1=... 4774 Digest: sha256=... 4776 { 4777 "access_token": { 4778 "access": [ 4779 "FWWIKYBQ6U56NL1", 4780 "dolphin-metadata" 4781 ] 4782 }, 4783 "client": "KHRS6X63AJ7C7C4AZ9AO" 4784 } 4786 If issued, the resulting access token would contain sufficient access 4787 to be used at both referenced resources. 4789 10. Acknowledgements 4791 The editors would like to thank the feedback of the following 4792 individuals for their reviews, implementations, and contributions: 4793 Aeke Axeland, Aaron Parecki, Adam Omar Oueidat, Andrii Deinega, 4794 Annabelle Backman, Dick Hardt, Dmitri Zagidulin, Dmitry Barinov, 4795 Fabien Imbault, Francis Pouatcha, George Fletcher, Haardik Haardik, 4796 Florian Helmschmidt, Hamid Massaoud, Jacky Yuan, Joseph Heenan, 4797 Justin Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat 4798 Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya. 4800 The editors would also like to thank the GNAP working group design 4801 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 4802 and Justin Richer, who incorporated elements from the XAuth and XYZ 4803 proposals to create the first version of this document. 4805 In addition, the editors would like to thank Aaron Parecki and Mike 4806 Jones for insights into how to integrate identity and authentication 4807 systems into the core protocol, and Justin Richer and Dick Hardt for 4808 the use cases, diagrams, and insights provided in the XYZ and XAuth 4809 proposals that have been incorporated here. The editors would like 4810 to especially thank Mike Varley and the team at SecureKey for 4811 feedback and development of early versions of the XYZ protocol that 4812 fed into this standards work. 4814 11. IANA Considerations 4816 [[ TBD: There are a lot of items in the document that are expandable 4817 through the use of value registries. ]] 4819 12. Security Considerations 4821 12.1. TLS Protection in Transit 4823 All requests in GNAP have to be made over TLS or equivalent as 4824 outlined in [BCP195] to protect the contents of the request and 4825 response from manipulation and interception by an attacker. This 4826 includes all requests from a client instance to the AS, all requests 4827 from the client instance to an RS, any requests back to a client 4828 instance such as the push-based interaction finish method, and any 4829 back-end communications such as from an RS to an AS as described in 4830 [I-D.ietf-gnap-resource-servers]. Additionally, all requests between 4831 a browser and other components, such as during redirect-based 4832 interaction, need to be made over TLS or use equivalent protection. 4834 Even though requests from the client instance to the AS are signed, 4835 the signature method alone does not protect the request from 4836 interception by an attacker. TLS protects the response as well as 4837 the request, preventing an attacker from intercepting requested 4838 information as it is returned. This is particularly important in the 4839 core protocol for security artifacts such as nonces and for personal 4840 information such as subject information. 4842 The use of key-bound access tokens does not negate the requirement 4843 for protecting calls to the RS with TLS. While the keys and 4844 signatures associated a bound access token will prevent an attacker 4845 from using a stolen token, without TLS an attacker would be able to 4846 watch the data being sent to the RS and returned from the RS during 4847 legitimate use of the client instance under attack. Additionally, 4848 without TLS an attacker would be able to profile the calls made 4849 between the client instance and RS, possibly gaining information 4850 about the functioning of the API between the client software and RS 4851 software that would be otherwise unknown to the attacker. 4853 TLS or equivalent protection also needs to be used between the 4854 browser and any other components. This applies during initial 4855 redirects to an AS's components during interaction, during any 4856 interaction with the resource owner, and during any redirect back to 4857 the client instance. Without TLS protection on these portions of the 4858 process, an attacker could wait for a valid request to start and then 4859 take over the resource owner's interaction session. 4861 12.2. Signing Requests from the Client Software 4863 Even though all requests in GNAP need to be transmitted over TLS or 4864 its equivalent, the use of TLS alone is not sufficient to protect all 4865 parts of a multi-party and multi-stage protocol like GNAP, and TLS is 4866 not targeted at tying multiple requests to each other over time. To 4867 account for this, GNAP makes use of message-level protection and key 4868 presentation mechanisms that strongly associate a request with a key 4869 held by the client instance (see Section 7). 4871 During the initial request from a client instance to the AS, the 4872 client instance has to identify and prove possession of a 4873 cryptographic key. If the key is known to the AS, such as if it is 4874 previously registered or dereferenceable to a trusted source, the AS 4875 can associate a set of policies to the client instance identified by 4876 the key. Without the requirement that the client instance prove that 4877 it holds that key, the AS could not trust that the connection came 4878 from any particular client and could not apply any associated 4879 policies. 4881 Even more importantly, the client instance proving possession of a 4882 key on the first request allows the AS to associate future requests 4883 with each other. The access token used for grant continuation is 4884 bound to the same key and proofing mechanism used by the client 4885 instance in its initial request, which means that the client instance 4886 needs to prove possession of that same key in future requests 4887 allowing the AS to be sure that the same client instance is executing 4888 the follow-ups for a given ongoing grant request. Therefore, the AS 4889 has to ensure that all subsequent requests for a grant are associated 4890 with the same key that started the grant, or the most recent rotation 4891 of that key. This need holds true even if the initial key is 4892 previously unknown to the AS, such as would be the case when a client 4893 instance creates an ephemeral key for its request. Without this 4894 ongoing association, an attacker would be able to impersonate a 4895 client instance in the midst of a grant request, potentially stealing 4896 access tokens and subject information with impunity. 4898 Additionally, all access tokens in GNAP default to be associated with 4899 the key that was presented during the grant request that created the 4900 access token. This association allows an RS to know that the 4901 presenter of the access token is the same party that the token was 4902 issued to, as identified by their keys. While non-bound bearer 4903 tokens are an option in GNAP, these types of tokens have their own 4904 tradeoffs discussed elsewhere in this section. 4906 TLS functions at the socket layer, ensuring that only the parties on 4907 either end of that socket connection can read the information passed 4908 along that connection. Each time a new socket connection is made, 4909 such as for a new HTTP request, a new trust is re-established that is 4910 unrelated to previous connections. As such, it is not possible with 4911 TLS alone to know that the same party is making a set of calls, and 4912 therefore TLS alone cannot provide the continuity of security needed 4913 for GNAP. However, mutual TLS (MTLS) does provide such security 4914 characteristics through the use of the TLS client certificate, and 4915 thus MTLS is acceptable as a key-presentation mechanism when applied 4916 as described in Section 7.3.2. 4918 12.3. Protection of Client Instance Key Material 4920 Client instances are identified by their unique keys, and anyone with 4921 access to a client instance's key material will be able to 4922 impersonate that client instance to all parties. This is true for 4923 both calls to the AS as well as calls to an RS using a key-bound 4924 access token. 4926 Different types of client software have different methods available 4927 for creating, managing, and registering keys. GNAP explicitly allows 4928 for ephemeral clients, such as SPAs, and single-user clients, such as 4929 mobile applications, to create and present their own keys during the 4930 initial grant request. The client software can securely generate a 4931 keypair on-device and present the public key, along with proof of 4932 holding that public key, to the AS as part of the initial request. 4934 To facilitate trust in these ephemeral keys, GNAP further allows for 4935 an extensible set of client information to be passed with the 4936 request. This information can include device posture and third-party 4937 attestations of the client software's provenance and authenticity, 4938 depending on the needs and capabilities of the client software and 4939 its deployment. 4941 From GNAP's perspective, each distinct key is a different client 4942 instance. However, multiple client instances can be grouped together 4943 by an AS policy and treated similarly to each other. For instance, 4944 if an AS knows of several different keys for different servers within 4945 a cluster, the AS can decide that authorization of one of these 4946 servers applies to all other servers within the cluster. An AS that 4947 chooses to do this needs to be careful with how it groups different 4948 client keys together in its policy, since the breach of one instance 4949 would have direct effects on the others in the cluster. 4951 Additionally, if an end user controls multiple instances of a single 4952 type of client software, such as having an application installed on 4953 multiple devices, each of these instances is expected to have a 4954 separate key and be issued separate access tokens. However, if the 4955 AS is able to group these separate instances together as described 4956 above, it can streamline the authorization process for new instances 4957 of the same client software. For example, if two client instances 4958 can present proof of a valid installation of a piece of client 4959 software, the AS would be able to associate the approval of the first 4960 instance of this software to all related instances. The AS could 4961 then choose to bypass an explicit prompt of the resource owner for 4962 approval during authorization, since such approval has already been 4963 given. An AS doing such a process would need to take assurance 4964 measures that the different instances are in fact correlated and 4965 authentic, as well as ensuring the expected resource owner is in 4966 control of the client instance. 4968 Finally, if multiple instances of client software each have the same 4969 key, then from GNAP's perspective, these are functionally the same 4970 client instance as GNAP has no reasonable way to differentiate 4971 between them. This situation could happen if multiple instances 4972 within a cluster can securely share secret information among 4973 themselves. Even though there are multiple copies of the software, 4974 the shared key makes these copies all present as a single instance. 4975 It is considered bad practice to share keys between copies of 4976 software unless they are very tightly integrated with each other and 4977 can be closely managed. It is particularly bad practice to allow an 4978 end-user to copy keys between client instances and to willingly use 4979 the same key in multiple instances. 4981 12.4. Protection of Authorization Server 4983 The AS performs critical functions in GNAP, including authenticating 4984 client software, managing interactions with end-users to gather 4985 consent and provide notice, and issuing access tokens for client 4986 instances to present to resource servers. As such, protecting the AS 4987 is central to any GNAP deployment. 4989 If an attacker is able to gain control over an AS, they would be able 4990 to create fraudulent tokens and manipulate registration information 4991 to allow for malicious clients. These tokens and clients would be 4992 trusted by other components in the ecosystem under the protection of 4993 the AS. 4995 If the AS is using signed access tokens, an attacker in control of 4996 the AS's signing keys would be able to manufacture fraudulent tokens 4997 for use at RS's under the protection of the AS. 4999 If an attacker is able to impersonate an AS, they would be able to 5000 trick legitimate client instances into making signed requests for 5001 information which could potentially be proxied to a real AS. To 5002 combat this, all communications to the AS need to be made over TLS or 5003 its equivalent, and the software making the connection has to 5004 validate the certificate chain of the host it is connecting to. 5006 Consequently, protecting, monitoring, and auditing the AS is 5007 paramount to preserving the security of a GNAP-protected ecosystem. 5009 12.5. Symmetric and Asymmetric Client Instance Keys 5011 The cryptographic methods used by GNAP for key-proofing can support 5012 both asymmetric and symmetric cryptography, and can be extended to 5013 use a wide variety of mechanisms. While symmetric cryptographic 5014 systems have some benefits in speed and simplicity, they have a 5015 distinct drawback that both parties need access to the same key in 5016 order to do both signing and verification of the message. This means 5017 that when the client instance calls the AS to request a token, the AS 5018 needs to know the exact value of the client instance's key (or be 5019 able to derive it) in order to validate the key proof signature. 5020 With asymmetric keys, the client needs only to send its public key to 5021 the AS to allow for verification that the client holds the associated 5022 private key, regardless of whether that key was pre-registered or not 5023 with the AS. 5025 When used to bind to an access token, a key value must be known by 5026 the RS in order to validate the proof signature on the request. 5027 Common methods for communicating these proofing keys include putting 5028 information in a structured access token and allowing the RS to look 5029 up the associated key material against the value of the access token. 5030 With symmetric cryptography, both of these methods would expose the 5031 signing key to the RS, and in the case of an structured access token, 5032 potentially to any party that can see the access token itself unless 5033 the token's payload has been encrypted. Any of these parties would 5034 then be able to make calls using the access token by creating a valid 5035 signature. With asymmetric cryptography, the RS only needs to know 5036 the public key associated with the token in order to validate, and 5037 therefore cannot create any new calls. 5039 Symmetric keys also have the expected advantage of providing better 5040 protection against quantum threats in the future. Also, these types 5041 of keys (and their secure derivations) are widely supported among 5042 many cloud-based key management systems. 5044 While both signing approaches are allowed, GNAP treats these two 5045 classes of keys somewhat differently. Only the public portion of 5046 asymmetric keys are allowed to be sent by value in requests to the AS 5047 when establishing a connection. Since sending a symmetric key (or 5048 the private portion of an asymmetric key) would expose the signing 5049 material to any parties on the request path, including any attackers, 5050 sending these kinds of keys is prohibited. Symmetric keys can still 5051 be used by client instances, but only a reference to the key and not 5052 its value can be sent. This allows the AS to use pre-registered 5053 symmetric keys as well as key derivation schemes to take advantage of 5054 symmetric cryptography but without requiring key distribution at 5055 runtime, which would expose the keys in transit. 5057 Both the AS and client software can use systems such as hardware 5058 security modules to strengthen their key security storage and 5059 generation for both asymmetric and symmetric keys. 5061 12.6. Generation of Access Tokens 5063 The content of access tokens need to be such that only the generating 5064 AS would be able to create them, and the contents cannot be 5065 manipulated by an attacker to gain different or additional access 5066 rights. 5068 One method for accomplishing this is to use a cryptographically 5069 random value for the access token, generated by the AS using a secure 5070 randomization function with sufficiently high entropy. The odds of 5071 an attacker guessing the output of the randomization function to 5072 collide with a valid access token are exceedingly small, and even 5073 then the attacker would not have any control over what the access 5074 token would represent since that information would be held close by 5075 the AS. 5077 Another method for accomplishing this is to use a structured token 5078 that is cryptographically signed. In this case, the payload of the 5079 access token declares to the RS what the token is good for, but the 5080 signature applied by the AS during token generation covers this 5081 payload. Only the AS can create such a signature and therefore only 5082 the AS can create such a signed token. The odds of an attacker being 5083 able to guess a signature value with a useful payload are exceedingly 5084 small. This technique only works if all targeted RS's check the 5085 signature of the access token. Any RS that does not validate the 5086 signature of all presented tokens would be susceptible to injection 5087 of a modified or falsified token. Furthermore, an AS has to 5088 carefully protect the keys used to sign access tokens, since anyone 5089 with access to these signing keys would be able to create seemingly- 5090 valid access tokens using them. 5092 12.7. Bearer Access Tokens 5094 Bearer access tokens can be used by any party that has access to the 5095 token itself, without any additional information. As a natural 5096 consequence, any RS that a bearer token is presented to has the 5097 technical capability of presenting that bearer token to another RS, 5098 as long as the token is valid. It also means that any party that is 5099 able capture of the token value in storage or in transit is able to 5100 use the access token. While bearer tokens are inherently simpler, 5101 this simplicity has been misapplied and abused in making needlessly 5102 insecure systems. 5104 In GNAP, key-bound access tokens are the default due to their higher 5105 security properties. While bearer tokens can be used in GNAP, their 5106 use should be limited onto to cases where the simplicity benefits 5107 outweigh the significant security downsides. 5109 12.8. Key-Bound Token Access Tokens 5111 Key-bound access tokens, as the name suggests, are bound to a 5112 specific key and must be presented along with proof of that key 5113 during use. The key itself is not presented at the same time as the 5114 token, so even if a token value is captured, it cannot be used to 5115 make a new request. This is particularly true for an RS, which will 5116 see the token value but will not see the keys used to make the 5117 request. 5119 Key-bound access tokens provide this additional layer of protection 5120 only when the RS checks the signature of the message presented with 5121 the token. Acceptance of an invalid presentation signature, or 5122 failure to check the signature entirely, would allow an attacker to 5123 make calls with a captured access token without having access to the 5124 related signing key material. 5126 In addition to validating the signature of the presentation message 5127 itself, the RS also needs to ensure that the signing key used is 5128 appropriate for the presented token. If an RS does not ensure that 5129 the right keys were used to sign a message with a specific token, an 5130 attacker would be able to capture an access token and sign the 5131 request with their own keys, thereby negating the benefits of using 5132 key-bound access tokens. 5134 The RS also needs to ensure that a sufficient portions of the message 5135 are covered by the signature. Any items outside the signature could 5136 still affect the API's processing decisions, but these items would 5137 not be strongly bound to the token presentation. As such, an 5138 attacker could capture a valid request, then manipulate portions of 5139 the request outside of the signature envelope in order to cause 5140 unwanted actions at the protected API. 5142 Some key-bound tokens are susceptible to replay attacks, depending on 5143 the details of the signing method used. If a signature method covers 5144 only portions of a given request, that same signature proof can be 5145 used by an attacker to make a similar call, potentially even varying 5146 elements that are outside of the protection of the signature. Key 5147 proofing mechanisms used with access tokens therefore need to use 5148 replay protection mechanisms covered under the signature such as a 5149 per-message nonce, a reasonably short time validity window, or other 5150 uniqueness constraints. The details of using these will vary 5151 depending on the key proofing mechanism in use, but for example, HTTP 5152 Message Signatures has both a created and nonce signature parameter 5153 as well as the ability to cover significant portions of the HTTP 5154 message. 5156 12.9. Exposure of End-user Credentials to Client Instance 5158 As a delegation protocol, one of the main goals of GNAP is to prevent 5159 the client software from being exposed to any credentials or 5160 information about the end-user or resource owner as a requirement of 5161 the delegation process. By using the variety of interaction 5162 mechanisms, the resource owner can interact with the AS without ever 5163 authenticating to the client software, and without the client 5164 software having to impersonate the resource owner through replay of 5165 their credentials. 5167 Consequently, no interaction methods defined in the GNAP core require 5168 the end-user to enter their credentials, but it is technologically 5169 possible for an extension to be defined to carry such values. Such 5170 an extension would be dangerous as it would allow rogue client 5171 software to directly collect, store, and replay the end-user's 5172 credentials outside of any legitimate use within a GNAP request. 5174 The concerns of such an extension could be mitigated through use of a 5175 challenge and response unlocked by the end user's credentials. For 5176 example, the AS presents a challenge as part of an interaction start 5177 method, and the client instance signs that challenge using a key 5178 derived from a password presented by the end user. It would be 5179 possible for the client software to collect this password in a secure 5180 software enclave without exposing the password to the rest of the 5181 client software or putting it across the wire to the AS. The AS can 5182 validate this challenge response against a known password for the 5183 identified end user. While an approach such as this does not remove 5184 all of the concerns surrounding such a password-based scheme, it is 5185 at least possible to implement in a more secure fashion than simply 5186 collecting and replaying the password. Even so, such schemes should 5187 only ever be used by trusted clients due to the ease of abusing them. 5189 12.10. Mixing Up Authorization Servers 5191 If a client instance is able to work with multiple AS's 5192 simultaneously, it is more possible for an attacker to add a 5193 compromised AS to the client instance's configuration and cause the 5194 client software to start a request at the compromised AS. This AS 5195 could then proxy the client's request to a valid AS in order to 5196 attempt to get the resource owner to approve access for the 5197 legitimate client instance. 5199 A client instance needs to always be aware of which AS it is talking 5200 to throughout a grant process, and ensure that any callback for one 5201 AS does not get conflated with the callback to different AS. The 5202 interaction finish hash calculate allows a client instance to protect 5203 against this kind of substitution, but only if the client instance 5204 validates the hash. If the client instance does not use an 5205 interaction finish method or does not check the interaction finish 5206 hash value, the compromised AS can be granted a valid access token on 5207 behalf of the resource owner. See [attack-surfaces] for details of 5208 one such attack, which has been since addressed in this document by 5209 including the grant endpoint in the interaction hash calculation. 5210 The client instance still needs to validate the hash for the attack 5211 to be prevented. 5213 12.11. Processing of Client-Presented User Information 5215 GNAP allows the client instance to present assertions and identifiers 5216 of the current user to the AS as part of the initial request. This 5217 information should only ever be taken by the AS as a hint, since the 5218 AS has no way to tell if the represented person is present at the 5219 client software, without using an interaction mechanism. This 5220 information does not guarantee the given user is there, but it does 5221 constitute a statement by the client software that the AS can take 5222 into account. 5224 For example, if a specific user is claimed to be present prior to 5225 interaction, but a different user is shown to be present during 5226 interaction, the AS can either determine this to be an error or 5227 signal to the client instance through returned subject information 5228 that the current user has changed from what the client instance 5229 thought. This user information can also be used by the AS to 5230 streamline the interaction process when the user is present. For 5231 example, instead of having the user type in their account identifier 5232 during interaction at a redirected URL, the AS can immediately 5233 challenge the user for their account credentials. Alternatively, if 5234 an existing session is detected, the AS can determine that it matches 5235 the identifier provided by the client and subsequently skip an 5236 explicit authentication event by the resource owner. 5238 In cases where the AS trusts the client software more completely, due 5239 to policy or by previous approval of a given client instance, the AS 5240 can take this user information as a statement that the user is 5241 present and could issue access tokens and release subject information 5242 without interaction. The AS should only take such action in very 5243 limited circumstances, as a client instance could assert whatever it 5244 likes for the user's identifiers in its request. 5246 When a client instance presents an assertion to the AS, the AS needs 5247 to evaluate that assertion. Since the AS is unlikely to be the 5248 intended audience of an assertion held by the client software, the AS 5249 will need to evaluate the assertion in a different context. Even in 5250 this case, the AS can still evaluate that the assertion was generated 5251 by a trusted party, was appropriately signed, and is within any time 5252 validity windows stated by the assertion. If the client instance's 5253 audience identifier is known to the AS and can be associated with the 5254 client instance's presented key, the AS can also evaluate that the 5255 appropriate client instance is presenting the claimed assertion. All 5256 of this will prevent an attacker from presenting a manufactured 5257 assertion, or one captured from an untrusted system. However, 5258 without validating the audience of the assertion, a captured 5259 assertion could be presented by the client instance to impersonate a 5260 given end user. In such cases, the assertion offers little more 5261 protection than a simple identifier would. 5263 A special case exists where the AS is the generator of the assertion 5264 being presented by the client instance. In these cases, the AS can 5265 validate that it did issue the assertion and it is associated with 5266 the client instance presenting the assertion. 5268 12.12. Client Instance Pre-registration 5270 Each client instance is identified by its own unique key, and for 5271 some kinds of client software such as a web server or backend system, 5272 this identification can be facilitated by registering a single key 5273 for a piece of client software ahead of time. This registration can 5274 be associated with a set of display attributes to be used during the 5275 authorization process, identifying the client software to the user. 5276 In these cases, it can be assumed that only one instance of client 5277 software will exist, likely to serve many different users. 5279 A client's registration record needs to include its identifying key. 5280 Furthermore, it is the case that any clients using symmetric 5281 cryptography for key proofing mechanisms need to have their keys pre- 5282 registered. The registration should also include any information 5283 that would aid in the authorization process, such as a display name 5284 and logo. The registration record can also limit a given client to 5285 ask for certain kinds of information and access, or be limited to 5286 specific interaction mechanisms at runtime. 5288 It also is sensible to pre-register client instances when the 5289 software is acting autonomously, without the need for a runtime 5290 approval by a resource owner or any interaction with an end-user. In 5291 these cases, an AS needs to rest on the trust decisions that have 5292 been determined prior to runtime in determining what rights and 5293 tokens to grant to a given client instance. 5295 However, it does not make sense to pre-register many types of 5296 clients. Single-page applications (SPAs) and mobile/desktop 5297 applications in particular present problems with pre-registration. 5298 For SPAs, the instances are ephemeral in nature and long-term 5299 registration of a single instance leads to significant storage and 5300 management overhead at the AS. For mobile applications, each 5301 installation of the client software is a separate instance, and 5302 sharing a key among all instances would be detrimental to security as 5303 the compromise of any single installation would compromise all copies 5304 for all users. 5306 An AS can treat these classes of client software differently from 5307 each other, perhaps by allowing access to certain high-value APIs 5308 only to pre-registered known clients, or by requiring an active end- 5309 user delegation of authority to any client software not pre- 5310 registered. 5312 An AS can also provide warnings and caveats to resource owners during 5313 the authorization process, allowing the user to make an informed 5314 decision regarding the software they are authorizing. For example, 5315 if the AS has done vetting of the client software and this specific 5316 instance, it can present a different authorization screen compared to 5317 a client instance that is presenting all of its information at 5318 runtime. 5320 12.13. Client Instance Impersonation 5322 If client instances are allowed to set their own user-facing display 5323 information, such as a display name and website URL, a malicious 5324 client instance could impersonate legitimate client software for the 5325 purposes of tricking users into authorizing the malicious client. 5327 Requiring clients to pre-register does not fully mitigate this 5328 problem since many pre-registration systems have self-service portals 5329 for management of client registration, allowing authenticated 5330 developers to enter self-asserted information into the management 5331 portal. 5333 An AS can mitigate this by actively filtering all self-asserted 5334 values presented by client software, both dynamically as part of GNAP 5335 and through a registration portal, to limit the kinds of 5336 impersonation that would be done. 5338 An AS can also warn the resource owner about the provenance of the 5339 information it is displaying, allowing the resource owner to make a 5340 more informed delegation decision. For example, an AS can visually 5341 differentiate between a client instance that can be traced back to a 5342 specific developer's registration and an instance that has self- 5343 asserted its own key and display information. 5345 12.14. Interception of Information in the Browser 5347 Most information passed through the web-browser is susceptible to 5348 interception and possible manipulation by elements within the browser 5349 such as scripts loaded within pages. Information in the URL is 5350 exposed through browser and server logs, and can also leak to other 5351 parties through HTTP Referrer headers. 5353 GNAP's design limits the information passed directly through the 5354 browser, allowing for opaque URLs in most circumstances. For the 5355 redirect-based interaction finish mechanism, named query parameters 5356 are used to carry unguessable opaque values. For these, GNAP 5357 requires creation and validation of a cryptographic hash to protect 5358 the query parameters added to the URL and associate them with an 5359 ongoing grant process. The client instance has to properly validate 5360 this hash to prevent an attacker from injecting an interaction 5361 reference intended for a different AS or client instance. 5363 Several interaction start mechanisms use URLs created by the AS and 5364 passed to the client instance. While these URLs are opaque to the 5365 client instance, it's possible for the AS to include parameters, 5366 paths, and other pieces of information that could leak security data 5367 or be manipulated by a party in the middle of the transaction. 5369 12.15. Callback URL Manipulation 5371 The callback URL used in interaction finish mechanisms is defined by 5372 the client instance. This URL is opaque to the AS, but can contain 5373 information relevant to the client instance's operations. In 5374 particular, the client instance can include state information to 5375 allow the callback request to be associated with an ongoing grant 5376 request. 5378 Since this URL is exposed to the end-user's browser, it is 5379 susceptible to both logging and manipulation in transit before the 5380 request is made to the client software. As such, a client instance 5381 should never put security-critical or private information into the 5382 callback URL in a cleartext form. For example, if the client 5383 software includes a post-redirect target URL in its callback URL to 5384 the AS, this target URL could be manipulated by an attacker, creating 5385 an open redirector at the client. Instead, a client instance can use 5386 an unguessable identifier into the URL that can then be used by the 5387 client software to look up the details of the pending request. Since 5388 this approach requires some form of statefulness by the client 5389 software during the redirection process, clients that are not capable 5390 of holding state through a redirect should not use redirect-based 5391 interaction mechanisms. 5393 12.16. MTLS Message Integrity 5395 The MTLS key proofing mechanism (Section 7.3.2) provides a means for 5396 a client instance to present a key using a certificate the TLS layer. 5397 Since TLS protects the entire HTTP message in transit, verification 5398 of the TLS client certificate presented with the message provides a 5399 sufficient binding between the two. However, since TLS is 5400 functioning at a separate layer from HTTP, there is no direct 5401 connection between the TLS key presentation and the message itself, 5402 other than the fact that the message was presented over the TLS 5403 channel. That is to say, any HTTP message can be presented over the 5404 TLS channel in question with the same level of trust. The verifier 5405 is responsible for ensuring the key in the TLS client certificate is 5406 the one expected for a particular request. For example, if the 5407 request is a grant request (request), the AS needs to compare the TLS 5408 client certificate presented at the TLS layer to the key identified 5409 in the request body itself (either by value or through a referenced 5410 identifier). 5412 Furthermore, the prevalence of the TLS-terminating reverse proxy 5413 (TTRP) pattern in deployments adds a wrinkle to the situation. In 5414 this common pattern, the TTRP validates the TLS connection and then 5415 forwards the HTTP message contents onward to an internal system for 5416 processing. The system processing the HTTP message no longer has 5417 access to the original TLS connection's information and context. To 5418 compensate for this, the TTRP could inject the TLS client certificate 5419 into the forwarded request as a header parameter using 5420 [I-D.ietf-httpbis-client-cert-field], giving the downstream system 5421 access to the certificate information. The TTRP has to be trusted to 5422 provide accurate certificate information, and the connection between 5423 the TTRP and the downstream system also has to be protected. The 5424 TTRP could provide some additional assurance, for example, by adding 5425 its own signature to the Client-Cert header field using 5426 [I-D.ietf-httpbis-message-signatures]. This signature would be 5427 effectively ignored by GNAP but understood by the downstream service 5428 as part of its deployment. 5430 Additional considerations for different types of deployment patterns 5431 and key distribution mechanisms for MTLS are found in Section 12.17. 5433 12.17. MTLS Deployment Patterns 5435 GNAP does not specify how a client instance's keys could be made 5436 known to the AS ahead of time. Public Key Infrastructure (PKI) can 5437 be used to manage the keys used by client instances when calling the 5438 AS, allowing the AS to trust a root key from a trusted authority. 5439 This method is particularly relevant to the MTLS key proofing method, 5440 where the client instance presents its certificate to the AS as part 5441 of the TLS connection. An AS using PKI to validate the MTLS 5442 connection would need to ensure that the presented certificate was 5443 issued by a trusted certificate authority before allowing the 5444 connection to continue. PKI-based certificates would allow a key to 5445 be revoked and rotated through management at the certificate 5446 authority without requiring additional registration or management at 5447 the AS. PKI has historically been difficult to deploy, especially at 5448 scale, but it remains an appropriate solution for systems where the 5449 required overhead is not an impediment. 5451 MTLS in GNAP need not use a PKI backing, as self-signed certificates 5452 and certificates from untrusted authorities can still be presented as 5453 part of a TLS connection. In this case, the verifier would validate 5454 the connection but accept whatever certificate was presented by the 5455 client software. This specific certificate would then be bound to 5456 all future connections from that client software by being bound to 5457 the resulting access tokens. See Section 12.16 for more 5458 considerations on MTLS as a key proofing mechanism. 5460 12.18. Interception of Responses from the AS 5462 Responses from the AS contain information vital to both the security 5463 and privacy operations of GNAP. This information includes nonces 5464 used in cryptographic calculations, subject identifiers, assertions, 5465 public keys, and information about what client software is requesting 5466 and was granted. 5468 In addition, if bearer tokens are used or keys are issued alongside a 5469 bound access token, the response from the AS contains all information 5470 necessary for use of the contained access token. Any party that is 5471 capable of viewing such a response, such as an intermediary proxy, 5472 would be able to exfiltrate and use this token. If the access token 5473 is instead bound to the client instance's presented key, 5474 intermediaries no longer have sufficient information to use the 5475 token. They can still, however, gain information about the end user 5476 as well as the actions of the client software. 5478 12.19. Key Distribution 5480 The keys for client instances could be distributed as part of the 5481 deployment process of instances of the client software. For example, 5482 an application installation framework could generate a keypair for 5483 each copy of client software, then both install it into the client 5484 software upon installation and registering that instance with the AS. 5486 Additionally, it's possible for the AS to generate keys to be used 5487 with access tokens that are separate from the keys used by the client 5488 instance to request tokens. In this method, the AS would generate 5489 the asymmetric keypair or symmetric key and return the entire key, 5490 including all private signing information, to the client instance 5491 alongside the access token itself. This approach would make 5492 interception of the return from the token endpoint equivalent to that 5493 of a bearer token, since all information required to use the access 5494 token would be present in the request. 5496 12.20. Interaction Finish Modes and Polling 5498 During the interaction process, the client instance usually hands 5499 control of the user experience over to another component, beit the 5500 system browser, another application, or some action the resource 5501 owner is instructed to take on another device. By using an 5502 interaction finish method, the client instance can be securely 5503 notified by the AS when the interaction is completed and the next 5504 phase of the protocol should occur. This process includes 5505 information that the client instance can use to validate the finish 5506 call from the AS and prevent some injection, session hijacking, and 5507 phishing attacks. 5509 Some types of client deployment are unable to receive an interaction 5510 finish message. Without an interaction finish method to notify it, 5511 the client instance will need to poll the grant continuation API 5512 while waiting for the resource owner to approve or deny the request. 5513 An attacker could take advantage of this situation by capturing the 5514 interaction start parameters and phishing a legitimate user into 5515 authorizing the attacker's waiting client instance, which would in 5516 turn have no way of associating the completed interaction with the 5517 start of the request. 5519 However, it is important to note that this pattern is practically 5520 indistinguishable from some legitimate use cases. For example, a 5521 smart device emits a code for the resource owner to enter on a 5522 separate device. The smart device has to poll because the expected 5523 behavior is that the interaction will take place on the separate 5524 device, without a way to return information to the original device's 5525 context. 5527 As such, developers need to weigh the risks of forgoing an 5528 interaction finish method against the deployment capabilities of the 5529 client software and its environment. Due to the increased security, 5530 an interaction finish method should be employed whenever possible. 5532 12.21. Storage of Information During Interaction and Continuation 5534 When starting an interactive grant request, a client application has 5535 a number of protocol elements that it needs to manage, including 5536 nonces, references, keys, access tokens, and other elements. During 5537 the interaction process, the client instance usually hands control of 5538 the user experience over to another component, beit the system 5539 browser, another application, or some action the resource owner is 5540 instructed to take on another device. In order for the client 5541 instance to make its continuation call, it will need to recall all of 5542 these protocol elements. Usually this means the client instance will 5543 need to store these protocol elements in some retrievable fashion. 5545 If the security protocol elements are stored on the end-user's 5546 device, such as in browser storage or in local application data 5547 stores, capture and exfiltration of this information could allow an 5548 attacker to continue a pending transaction instead of the client 5549 instance. Client software can make use of secure storage mechanisms, 5550 including hardware-based key and data storage, to prevent such 5551 exfiltration. 5553 Note that in GNAP, the client instance has to choose its interaction 5554 finish URL prior to making the first call to the AS. As such, the 5555 interaction finish URL will often have a unique identifier for the 5556 ongoing request, allowing the client instance to access the correct 5557 portion of its storage. Since this URL is passed to other parties 5558 and often used through a browser, this URL should not contain any 5559 security-sensitive information that would be valuable to an attacker, 5560 such as any token identifier, nonce, or user information. Instead, a 5561 cryptographically random value is suggested. 5563 12.22. Denial of Service (DoS) through Grant Continuation 5565 When a client instance starts off an interactive process, it will 5566 eventually need to continue the grant request in a subsequent message 5567 to the AS. It's possible for a naive client implementation to 5568 continuously send continuation requests to the AS while waiting for 5569 approval, especially if no interaction finish method is used. Such 5570 constant requests could overwhelm the AS's ability to respond to both 5571 these and other requests. 5573 To mitigate this for well-behaved client software, the continuation 5574 response contains a wait parameter that is intended to tell the 5575 client instance how long it should wait until making its next 5576 request. This value can be used to back off client software that is 5577 checking too quickly by returning increasing wait times for a single 5578 client instance. 5580 If client software ignores the wait value and makes its continuation 5581 calls too quickly, or if the client software assumes the absence of 5582 the wait values means it should poll immediately, the AS can choose 5583 to return errors to the offending client instance, including possibly 5584 canceling the ongoing grant request. With well-meaning client 5585 software these errors can indicate a need to change the client 5586 software's programmed behavior. 5588 12.23. Exhaustion of Random Value Space 5590 Several parts of the GNAP process make use of unguessable randomized 5591 values, such as nonces, tokens, and randomized URLs. Since these 5592 values are intended to be unique, a sufficiently powerful attacker 5593 could make a large number of requests to trigger generation of 5594 randomized values in an attempt to exhaust the random number 5595 generation space. While this attack is particularly applicable to 5596 the AS, client software could likewise be targeted by an attacker 5597 triggering new grant requests against an AS. 5599 To mitigate this, software can ensure that its random values are 5600 chosen from a significantly large pool that exhaustion of that pool 5601 is prohibitive for an attacker. Additionally, the random values can 5602 be time-boxed in such a way as their validity windows are reasonably 5603 short. Since many of the random values used within GNAP are used 5604 within limited portions of the protocol, it is reasonable for a 5605 particular random value to be valid for only a small amount of time. 5606 For example, the nonces used for interaction finish hash calculation 5607 need only to be valid while the client instance is waiting for the 5608 finish callback and can be functionally expired when the interaction 5609 has completed. Similarly, artifacts like access tokens and the 5610 interaction reference can be limited to have lifetimes tied to their 5611 functional utility. Finally, each different category of artifact 5612 (nonce, token, reference, identifier, etc.) can be generated from a 5613 separate random pool of values instead of a single global value 5614 space. 5616 12.24. Front-channel URLs 5618 Some interaction methods in GNAP make use of URLs accessed through 5619 the end-user's browser, known collectively as front-channel 5620 communication. These URLs are most notably present in the redirect 5621 interaction start method and the redirect interaction finish mode. 5622 Since these URLs are intended to be given to the end-user, the end 5623 user and their browser will be subjected to anything hosted at that 5624 URL including viruses, malware, and phishing scams. This kind of 5625 risk is inherent to all redirection-based protocols, including GNAP 5626 when used in this way. 5628 When talking to a new or unknown AS, a client instance might want to 5629 check the URL from the interaction start against a blocklist and warn 5630 the end-user before redirecting them. Many client instances will 5631 provide an interstitial message prior to redirection in order to 5632 prepare the user for control of the user experience being handed to 5633 the domain of the AS, and such a method could be used to warn the 5634 user of potential threats. For instance, a rogue AS impersonating a 5635 well-known service provider. Client software can also prevent this 5636 by managing an allowlist of known and trusted AS's. 5638 Alternatively, an attacker could start a GNAP request with a known 5639 and trusted AS but include their own attack site URL as the callback 5640 for the finish method. The attacker would then send the interaction 5641 start URL to the victim and get them to click on it. Since the URL 5642 is at the known AS, the victim is inclined to do so. The victim will 5643 then be prompted to approve the attacker's application, and in most 5644 circumstances the victim will then be redirected to the attacker's 5645 site whether or not the user approved the request. The AS could 5646 mitigate this partially by using a blocklist and allowlist of 5647 interaction finish URLs during the client instance's initial request, 5648 but this approach can be especially difficult if the URL has any 5649 dynamic portion chosen by the client software. The AS can couple 5650 these checks with policies associated with the client instance that 5651 has been authenticated in the request. If the AS has any doubt about 5652 the interaction finish URL, the AS can provide an interstitial 5653 warning to the end-user before processing the redirect. 5655 Ultimately, all protocols that use redirect-based communication 5656 through the user's browser are susceptible to having an attacker try 5657 to co-opt one or more of those URLs in order to harm the user. It is 5658 the responsibility of the AS and the client software to provide 5659 appropriate warnings, education, and mitigation to protect end users. 5661 12.25. Processing Assertions 5663 Identity assertions can be used in GNAP to convey subject 5664 information, both from the AS to the client instance in a response 5665 (Section 3.4) and from the client instance to the AS in a request 5666 (Section 2.2). In both of these circumstances, when an assertion is 5667 passed in GNAP, the receiver of the assertion needs to parse and 5668 process the assertion. As assertions are complex artifacts with 5669 their own syntax and security, special care needs to be taken to 5670 prevent the assertion values from being used as an attack vector. 5672 All assertion processing needs to account for the security aspects of 5673 the assertion format in use. In particular, the processor needs to 5674 parse the assertion from a JSON string object, and apply the 5675 appropriate cryptographic processes to ensure the integrity of the 5676 assertion. 5678 For example, when SAML 2 assertions are used, the receiver hast to 5679 parse an XML document. There are many well-known security 5680 vulnerabilities in XML parsers, and the XML standard itself can be 5681 attacked through the use of processing instructions and entity 5682 expansions to cause problems with the processor. Therefore, any 5683 system capable of processing SAML 2 assertions also needs to have a 5684 secure and correct XML parser. In addition to this, the SAML 2 5685 specification uses XML Signatures, which have their own 5686 implementation problems that need to be accounted for. Similar 5687 requirements exist for OpenID Connect's ID token, which is based on 5688 the JSON Web Token (JWT) format and the related JSON Object Signing 5689 And Encryption (JOSE) cryptography suite. 5691 13. Privacy Considerations 5693 The privacy considerations in this section are modeled after the list 5694 of privacy threats in [RFC6973], "Privacy Considerations for Internet 5695 Protocols", and either explain how these threats are mitigated or 5696 advise how the threats relate to GNAP. 5698 13.1. Surveillance 5700 Surveillance is the observation or monitoring of an individual's 5701 communications or activities. Surveillance can be conducted by 5702 observers or eavesdroppers at any point along the communications 5703 path. 5705 GNAP assumes the TLS protection used throughout the spec is intact. 5706 Without the protection of TLS, there are many points throughout the 5707 use of GNAP that would lead to possible surveillance. 5709 13.1.1. Surveillance by the Client 5711 The purpose of GNAP is to authorize clients to be able to access 5712 information on behalf of a user. So while it is expected that the 5713 client may be aware of the user's identity as well as data being 5714 fetched for that user, in some cases the extent of the client may be 5715 beyond what the user is aware of. For example, a client may be 5716 implemented as multiple distinct pieces of software, such as a 5717 logging service or a mobile app that reports usage data to an 5718 external backend service. 5720 13.1.2. Surveillance by the Authorization Server 5722 The role of the authorization server is to manage the authorization 5723 of client instances to protect access to the user's data. In this 5724 role, the authorization server is by definition aware of each 5725 authorization of a client instance by a user. When the authorization 5726 server shares user information with the client instance, it needs to 5727 make sure that it has the permission from that user to do so. 5729 Additionally, as part of the authorization grant process, the 5730 authorization server may be aware of which resource servers the 5731 client intends to use an access token at. However, it is possible to 5732 design a system using GNAP in which this knowledge is not made 5733 available to the authorization server, such as by avoiding the use of 5734 the locations object in the authorization request. 5736 If the authorization server's implementation of access tokens is such 5737 that it requires a resource server call back to the authorization 5738 server to validate them, then the authorization server will be aware 5739 of which resource servers are actively in use and by which users and 5740 which clients. To avoid this possibility, the authorization server 5741 would need to structure access tokens in such a way that they can be 5742 validated by the resource server without notifying the authorization 5743 server that the token is being validated. 5745 13.2. Stored Data 5747 Several parties in the GNAP process are expected to persist data at 5748 least temporarily, if not semi-permanently, for the normal 5749 functioning of the system. If compromised, this could lead to 5750 exposure of sensitive information. This section documents the 5751 potentially sensitive information each party in GNAP is expected to 5752 store for normal operation. Naturally it is possible that any party 5753 is storing information for longer than technically necessary of the 5754 protocol mechanics (such as audit logs, etc). 5756 The authorization server is expected to store subject identifiers for 5757 user indefinitely, in order to be able to include them in the 5758 responses to clients. The authorization server is also expected to 5759 store client key identifiers associated with display information 5760 about the client such as its name and logo. 5762 The client is expected to store its client instance key indefinitely, 5763 in order to authenticate to the authorization server for the normal 5764 functioning of the GNAP flows. Additionally, the client will be 5765 temporarily storing artifacts issued by the authorization server 5766 during a flow, and these artifacts SHOULD be discarded by the client 5767 when the transaction is complete. 5769 The resource server is not required to store any state for its normal 5770 operation. Depending on the implementation of access tokens, the 5771 resource server may need to cache public keys from the authorization 5772 server in order to validate access tokens. 5774 13.3. Intrusion 5776 Intrusion refers to the ability of various parties to send 5777 unsolicited messages or cause denial of service for unrelated 5778 parties. 5780 If the resource owner is different from the end user, there is an 5781 opportunity for the end user to cause unsolicited messages to be sent 5782 to the resource owner if the system prompts the resource owner for 5783 consent when an end user attempts to access their data. 5785 The format and contents of subject identifiers are intentionally not 5786 defined by GNAP. If the authorization server uses values for subject 5787 identifiers that are also identifiers for communication channels, 5788 (e.g. an email address or phone number), this opens up the 5789 possibility for a client to learn this information when it was not 5790 otherwise authorized to access this kind of data about the user. 5792 13.4. Correlation 5794 The threat of correlation is the combination of various pieces of 5795 information related to an individual in a way that defies their 5796 expectations of what others know about them. 5798 13.4.1. Correlation by Clients 5800 The biggest risk of correlation in GNAP is when an authorization 5801 server returns stable consistent user identifiers to multiple 5802 different applications. In this case, applications created by 5803 different parties would be able to correlate these user identifiers 5804 out of band in order to know which users they have in common. 5806 The most common example of this in practice is tracking for 5807 advertising purposes, such that client A shares their list of user 5808 IDs with an ad platform that is then able to retarget ads to 5809 applications created by other parties. In contrast, a positive 5810 example of correlation is a corporate acquisition where two 5811 previously unrelated clients now do need to be able to identify the 5812 same user between the two clients. 5814 13.4.2. Correlation by Resource Servers 5816 Unrelated resource servers also have an opportunity to correlate 5817 users if the authorization server includes stable user identifiers in 5818 access tokens or in access token introspection responses. 5820 In some cases a resource server may not actually need to be able to 5821 identify users, (such as a resource server providing access to a 5822 company cafeteria menu which only needs to validate whether the user 5823 is a current employee), so authorization servers should be thoughtful 5824 of when user identifiers are actually necessary to communicate to 5825 resource servers for the functioning of the system. 5827 However, note that the lack of inclusion of a user identifier in an 5828 access token may be a risk if there is a concern that two users may 5829 voluntarily share access tokens between them in order to access 5830 protected resources. For example, if a website wants to limit access 5831 to only people over 18, and such does not need to know any user 5832 identifiers, an access token may be issued by an AS contains only the 5833 claim "over 18". If the user is aware that this access token doesn't 5834 reference them individually, they may be willing to share the access 5835 token with a user who is under 18 in order to let them get access to 5836 the website. (Note that the binding of an access token to a non- 5837 extractable client instance key also prevents the access token from 5838 being voluntarily shared.) 5840 13.4.3. Correlation by Authorization Servers 5842 Clients are expected to be identified by their client instance key. 5843 If a particular client instance key is used at more than one 5844 authorization server, this could open up the possibility for multiple 5845 unrelated authorization servers to correlate client instances. This 5846 is especially a problem in the common case where a client instance is 5847 used by a single individual, as it would allow the authorization 5848 servers to correlate that individual between them. If this is a 5849 concern of a client, the client should use distinct keys with each 5850 authorization server. 5852 13.5. Disclosure in Shared References 5854 Throughout many parts of GNAP, the parties pass shared references 5855 between each other, sometimes in place of the values themselves. For 5856 example the interact_ref value used throughout the flow. These 5857 references are intended to be random strings and should not contain 5858 any private or sensitive data that would potentially leak information 5859 between parties. 5861 14. References 5863 14.1. Normative References 5865 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 5866 "Recommendations for Secure Use of Transport Layer 5867 Security (TLS) and Datagram Transport Layer Security 5868 (DTLS)", May 2015, 5869 . 5871 [I-D.ietf-gnap-resource-servers] 5872 Richer, J., Parecki, A., and F. Imbault, "Grant 5873 Negotiation and Authorization Protocol Resource Server 5874 Connections", Work in Progress, Internet-Draft, draft- 5875 ietf-gnap-resource-servers-01, 12 July 2021, 5876 . 5879 [I-D.ietf-httpbis-digest-headers] 5880 Polli, R. and L. Pardue, "Digest Fields", Work in 5881 Progress, Internet-Draft, draft-ietf-httpbis-digest- 5882 headers-06, 27 September 2021, 5883 . 5886 [I-D.ietf-httpbis-message-signatures] 5887 Backman, A., Richer, J., and M. Sporny, "HTTP Message 5888 Signatures", Work in Progress, Internet-Draft, draft-ietf- 5889 httpbis-message-signatures-06, 13 August 2021, 5890 . 5893 [I-D.ietf-oauth-rar] 5894 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 5895 Rich Authorization Requests", Work in Progress, Internet- 5896 Draft, draft-ietf-oauth-rar-08, 18 October 2021, 5897 . 5900 [I-D.ietf-secevent-subject-identifiers] 5901 Backman, A. and M. Scurtescu, "Subject Identifiers for 5902 Security Event Tokens", Work in Progress, Internet-Draft, 5903 draft-ietf-secevent-subject-identifiers-08, 24 May 2021, 5904 . 5907 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 5908 C. Mortimore, "OpenID Connect Core 1.0 incorporating 5909 errata set 1", November 2014, 5910 . 5912 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5913 Requirement Levels", BCP 14, RFC 2119, 5914 DOI 10.17487/RFC2119, March 1997, 5915 . 5917 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 5918 RFC 3230, DOI 10.17487/RFC3230, January 2002, 5919 . 5921 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 5922 Resource Identifier (URI): Generic Syntax", STD 66, 5923 RFC 3986, DOI 10.17487/RFC3986, January 2005, 5924 . 5926 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 5927 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 5928 September 2009, . 5930 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 5931 RFC 6749, DOI 10.17487/RFC6749, October 2012, 5932 . 5934 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 5935 Framework: Bearer Token Usage", RFC 6750, 5936 DOI 10.17487/RFC6750, October 2012, 5937 . 5939 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 5940 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 5941 RFC 7234, DOI 10.17487/RFC7234, June 2014, 5942 . 5944 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 5945 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 5946 April 2015, . 5948 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 5949 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 5950 2015, . 5952 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 5953 DOI 10.17487/RFC7517, May 2015, 5954 . 5956 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5957 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5958 May 2017, . 5960 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 5961 Interchange Format", STD 90, RFC 8259, 5962 DOI 10.17487/RFC8259, December 2017, 5963 . 5965 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 5966 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 5967 and Certificate-Bound Access Tokens", RFC 8705, 5968 DOI 10.17487/RFC8705, February 2020, 5969 . 5971 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 5972 "Handling Long Lines in Content of Internet-Drafts and 5973 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 5974 . 5976 14.2. Informative References 5978 [attack-surfaces] 5979 Axeland, Å. and O. Oueidat, "Security Analysis of Attack 5980 Surfaces on the Grant Negotiation and Authorization 5981 Protocol", 2021, 5982 . 5984 [I-D.ietf-httpbis-client-cert-field] 5985 Campbell, B. and M. Bishop, "Client-Cert HTTP Header 5986 Field: Conveying Client Certificate Information from TLS 5987 Terminating Reverse Proxies to Origin Server 5988 Applications", Work in Progress, Internet-Draft, draft- 5989 ietf-httpbis-client-cert-field-00, 8 June 2021, 5990 . 5993 [promise-theory] 5994 Burgess, M. and J. Bergstra, "Promise theory", January 5995 2014, . 5997 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 5998 Morris, J., Hansen, M., and R. Smith, "Privacy 5999 Considerations for Internet Protocols", RFC 6973, 6000 DOI 10.17487/RFC6973, July 2013, 6001 . 6003 Appendix A. Document History 6005 * -08 6007 - Update definition for "Client" to account for the case of no 6008 end-user. 6010 - Change definition for "Subject". 6012 - Expanded security and privacy considerations for more 6013 situations. 6015 - Added cross-links from security and privacy considerations. 6017 - Editorial updates. 6019 * -07 6021 - Replace user handle by opaque identifier 6023 - Added trust relationships 6025 - Added privacy considerations section 6026 - Added security considerations. 6028 * -06 6030 - Removed "capabilities" and "existing_grant" protocol fields. 6032 - Removed separate "instance_id" field. 6034 - Split "interaction_methods_supported" into 6035 "interaction_start_modes_supported" and 6036 "interaction_finish_methods_supported". 6038 - Added AS endpoint to hash calculation to fix mix-up attack. 6040 - Added "privileges" field to resource access request object. 6042 - Moved client-facing RS response back from GNAP-RS document. 6044 - Removed oauthpop key binding. 6046 - Removed dpop key binding. 6048 - Added example DID identifier. 6050 - Changed token response booleans to flag structure to match 6051 request. 6053 - Updated signature examples to use HTTP Message Signatures. 6055 * -05 6057 - Changed "interaction_methods" to 6058 "interaction_methods_supported". 6060 - Changed "key_proofs" to "key_proofs_supported". 6062 - Changed "assertions" to "assertions_supported". 6064 - Updated discovery and field names for subject formats. 6066 - Add an appendix to provide protocol rationale, compared to 6067 OAuth2. 6069 - Updated subject information definition. 6071 - Refactored the RS-centric components into a new document. 6073 - Updated cryptographic proof of possession methods to match 6074 current reference syntax. 6076 - Updated proofing language to use "signer" and "verifier" 6077 generically. 6079 - Updated cryptographic proof of possession examples. 6081 - Editorial cleanup and fixes. 6083 - Diagram cleanup and fixes. 6085 * -04 6087 - Updated terminology. 6089 - Refactored key presentation and binding. 6091 - Refactored "interact" request to group start and end modes. 6093 - Changed access token request and response syntax. 6095 - Changed DPoP digest field to 'htd' to match proposed FAPI 6096 profile. 6098 - Include the access token hash in the DPoP message. 6100 - Removed closed issue links. 6102 - Removed function to read state of grant request by client. 6104 - Closed issues related to reading and updating access tokens. 6106 * -03 6108 - Changed "resource client" terminology to separate "client 6109 instance" and "client software". 6111 - Removed OpenID Connect "claims" parameter. 6113 - Dropped "short URI" redirect. 6115 - Access token is mandatory for continuation. 6117 - Removed closed issue links. 6119 - Editorial fixes. 6121 * -02 6123 - Moved all "editor's note" items to GitHub Issues. 6125 - Added JSON types to fields. 6127 - Changed "GNAP Protocol" to "GNAP". 6129 - Editorial fixes. 6131 * -01 6133 - "updated_at" subject info timestamp now in ISO 8601 string 6134 format. 6136 - Editorial fixes. 6138 - Added Aaron and Fabien as document authors. 6140 * -00 6142 - Initial working group draft. 6144 Appendix B. Compared to OAuth 2.0 6146 GNAP's protocol design differs from OAuth 2.0's in several 6147 fundamental ways: 6149 1. *Consent and authorization flexibility:* 6151 OAuth 2.0 generally assumes the user has access to the a web 6152 browser. The type of interaction available is fixed by the grant 6153 type, and the most common interactive grant types start in the 6154 browser. OAuth 2.0 assumes that the user using the client 6155 software is the same user that will interact with the AS to 6156 approve access. 6158 GNAP allows various patterns to manage authorizations and 6159 consents required to fulfill this requested delegation, including 6160 information sent by the client instance, information supplied by 6161 external parties, and information gathered through the 6162 interaction process. GNAP allows a client instance to list 6163 different ways that it can start and finish an interaction, and 6164 these can be mixed together as needed for different use cases. 6165 GNAP interactions can use a browser, but don't have to. Methods 6166 can use inter-application messaging protocols, out-of-band data 6167 transfer, or anything else. GNAP allows extensions to define new 6168 ways to start and finish an interaction, as new methods and 6169 platforms are expected to become available over time. GNAP is 6170 designed to allow the end-user and the resource owner to be two 6171 different people, but still works in the optimized case of them 6172 being the same party. 6174 2. *Intent registration and inline negotiation:* 6176 OAuth 2.0 uses different "grant types" that start at different 6177 endpoints for different purposes. Many of these require 6178 discovery of several interrelated parameters. 6180 GNAP requests all start with the same type of request to the same 6181 endpoint at the AS. Next steps are negotiated between the client 6182 instance and AS based on software capabilities, policies 6183 surrounding requested access, and the overall context of the 6184 ongoing request. GNAP defines a continuation API that allows the 6185 client instance and AS to request and send additional information 6186 from each other over multiple steps. This continuation API uses 6187 the same access token protection that other GNAP-protected APIs 6188 use. GNAP allows discovery to optimize the requests but it isn't 6189 required thanks to the negotiation capabilities. 6191 3. *Client instances:* 6193 OAuth 2.0 requires all clients to be registered at the AS and to 6194 use a client_id known to the AS as part of the protocol. This 6195 client_id is generally assumed to be assigned by a trusted 6196 authority during a registration process, and OAuth places a lot 6197 of trust on the client_id as a result. Dynamic registration 6198 allows different classes of clients to get a client_id at 6199 runtime, even if they only ever use it for one request. 6201 GNAP allows the client instance to present an unknown key to the 6202 AS and use that key to protect the ongoing request. GNAP's 6203 client instance identifier mechanism allows for pre-registered 6204 clients and dynamically registered clients to exist as an 6205 optimized case without requiring the identifier as part of the 6206 protocol at all times. 6208 4. *Expanded delegation:* 6210 OAuth 2.0 defines the "scope" parameter for controlling access to 6211 APIs. This parameter has been coopted to mean a number of 6212 different things in different protocols, including flags for 6213 turning special behavior on and off, including the return of data 6214 apart from the access token. The "resource" parameter and RAR 6215 extensions (as defined in [I-D.ietf-oauth-rar]) expand on the 6216 "scope" concept in similar but different ways. 6218 GNAP defines a rich structure for requesting access, with string 6219 references as an optimization. GNAP defines methods for 6220 requesting directly-returned user information, separate from API 6221 access. This information includes identifiers for the current 6222 user and structured assertions. The core GNAP protocol makes no 6223 assumptions or demands on the format or contents of the access 6224 token, but the RS extension allows a negotiation of token formats 6225 between the AS and RS. 6227 5. *Cryptography-based security:* 6229 OAuth 2.0 uses shared bearer secrets, including the client_secret 6230 and access token, and advanced authentication and sender 6231 constraint have been built on after the fact in inconsistent 6232 ways. 6234 In GNAP, all communication between the client instance and AS is 6235 bound to a key held by the client instance. GNAP uses the same 6236 cryptographic mechanisms for both authenticating the client (to 6237 the AS) and binding the access token (to the RS and the AS). 6238 GNAP allows extensions to define new cryptographic protection 6239 mechanisms, as new methods are expected to become available over 6240 time. GNAP does not have a notion of "public clients" because 6241 key information can always be sent and used dynamically. 6243 6. *Privacy and usable security:* 6245 OAuth 2.0's deployment model assumes a strong binding between the 6246 AS and the RS. 6248 GNAP is designed to be interoperable with decentralized identity 6249 standards and to provide a human-centric authorization layer. In 6250 addition to the core protocol, GNAP that supports various 6251 patterns of communication between RSs and ASs through extensions. 6252 GNAP tries to limit the odds of a consolidation to just a handful 6253 of super-popular AS services. 6255 Appendix C. Component Data Models 6257 While different implementations of this protocol will have different 6258 realizations of all the components and artifacts enumerated here, the 6259 nature of the protocol implies some common structures and elements 6260 for certain components. This appendix seeks to enumerate those 6261 common elements. 6263 TBD: Client has keys, allowed requested resources, identifier(s), 6264 allowed requested subjects, allowed 6265 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 6266 client keys, policies 6268 TBD: Token has RO, user, client, resource list, RS list, 6270 Appendix D. Example Protocol Flows 6272 The protocol defined in this specification provides a number of 6273 features that can be combined to solve many different kinds of 6274 authentication scenarios. This section seeks to show examples of how 6275 the protocol would be applied for different situations. 6277 Some longer fields, particularly cryptographic information, have been 6278 truncated for display purposes in these examples. 6280 D.1. Redirect-Based User Interaction 6282 In this scenario, the user is the RO and has access to a web browser, 6283 and the client instance can take front-channel callbacks on the same 6284 device as the user. This combination is analogous to the OAuth 2.0 6285 Authorization Code grant type. 6287 The client instance initiates the request to the AS. Here the client 6288 instance identifies itself using its public key. 6290 POST /tx HTTP/1.1 6291 Host: server.example.com 6292 Content-Type: application/json 6293 Signature-Input: sig1=... 6294 Signature: sig1=... 6295 Digest: sha256=... 6297 { 6298 "access_token": { 6299 "access": [ 6300 { 6301 "actions": [ 6302 "read", 6303 "write", 6304 "dolphin" 6305 ], 6306 "locations": [ 6307 "https://server.example.net/", 6308 "https://resource.local/other" 6309 ], 6310 "datatypes": [ 6311 "metadata", 6312 "images" 6314 ] 6315 } 6316 ], 6317 }, 6318 "client": { 6319 "key": { 6320 "proof": "httpsig", 6321 "jwk": { 6322 "kty": "RSA", 6323 "e": "AQAB", 6324 "kid": "xyz-1", 6325 "alg": "RS256", 6326 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 6327 } 6328 } 6329 }, 6330 "interact": { 6331 "start": ["redirect"], 6332 "finish": { 6333 "method": "redirect", 6334 "uri": "https://client.example.net/return/123455", 6335 "nonce": "LKLTI25DK82FX4T4QFZC" 6336 } 6337 } 6338 } 6340 The AS processes the request and determines that the RO needs to 6341 interact. The AS returns the following response giving the client 6342 instance the information it needs to connect. The AS has also 6343 indicated to the client instance that it can use the given instance 6344 identifier to identify itself in future requests (Section 2.3.1). 6346 HTTP/1.1 200 OK 6347 Content-Type: application/json 6348 Cache-Control: no-store 6350 { 6351 "interact": { 6352 "redirect": 6353 "https://server.example.com/interact/4CF492MLVMSW9MKM", 6354 "finish": "MBDOFXG4Y5CVJCX821LH" 6355 } 6356 "continue": { 6357 "access_token": { 6358 "value": "80UPRY5NM33OMUKMKSKU" 6359 }, 6360 "uri": "https://server.example.com/continue" 6361 }, 6362 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 6363 } 6365 The client instance saves the response and redirects the user to the 6366 interaction_url by sending the following HTTP message to the user's 6367 browser. 6369 HTTP 302 Found 6370 Location: https://server.example.com/interact/4CF492MLVMSW9MKM 6372 The user's browser fetches the AS's interaction URL. The user logs 6373 in, is identified as the RO for the resource being requested, and 6374 approves the request. Since the AS has a callback parameter, the AS 6375 generates the interaction reference, calculates the hash, and 6376 redirects the user back to the client instance with these additional 6377 values added as query parameters. 6379 NOTE: '\' line wrapping per RFC 8792 6381 HTTP 302 Found 6382 Location: https://client.example.net/return/123455\ 6383 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 6384 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 6385 &interact_ref=4IFWWIKYBC2PQ6U56NL1 6387 The client instance receives this request from the user's browser. 6388 The client instance ensures that this is the same user that was sent 6389 out by validating session information and retrieves the stored 6390 pending request. The client instance uses the values in this to 6391 validate the hash parameter. The client instance then calls the 6392 continuation URL and presents the handle and interaction reference in 6393 the request body. The client instance signs the request as above. 6395 POST /continue HTTP/1.1 6396 Host: server.example.com 6397 Content-Type: application/json 6398 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6399 Signature-Input: sig1=... 6400 Signature: sig1=... 6401 Digest: sha256=... 6403 { 6404 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 6405 } 6407 The AS retrieves the pending request based on the handle and issues 6408 an access token and returns this to the client instance. 6410 NOTE: '\' line wrapping per RFC 8792 6412 HTTP/1.1 200 OK 6413 Content-Type: application/json 6414 Cache-Control: no-store 6416 { 6417 "access_token": { 6418 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6419 "manage": "https://server.example.com/token/PRY5NM33O\ 6420 M4TB8N6BW7OZB8CDFONP219RP1L", 6421 "access": [{ 6422 "actions": [ 6423 "read", 6424 "write", 6425 "dolphin" 6426 ], 6427 "locations": [ 6428 "https://server.example.net/", 6429 "https://resource.local/other" 6430 ], 6431 "datatypes": [ 6432 "metadata", 6433 "images" 6434 ] 6435 }] 6436 }, 6437 "continue": { 6438 "access_token": { 6439 "value": "80UPRY5NM33OMUKMKSKU" 6440 }, 6441 "uri": "https://server.example.com/continue" 6442 } 6443 } 6445 D.2. Secondary Device Interaction 6447 In this scenario, the user does not have access to a web browser on 6448 the device and must use a secondary device to interact with the AS. 6449 The client instance can display a user code or a printable QR code. 6450 The client instance is not able to accept callbacks from the AS and 6451 needs to poll for updates while waiting for the user to authorize the 6452 request. 6454 The client instance initiates the request to the AS. 6456 POST /tx HTTP/1.1 6457 Host: server.example.com 6458 Content-Type: application/json 6459 Signature-Input: sig1=... 6460 Signature: sig1=... 6461 Digest: sha256=... 6463 { 6464 "access_token": { 6465 "access": [ 6466 "dolphin-metadata", "some other thing" 6467 ], 6468 }, 6469 "client": "7C7C4AZ9KHRS6X63AJAO", 6470 "interact": { 6471 "start": ["redirect", "user_code"] 6472 } 6473 } 6475 The AS processes this and determines that the RO needs to interact. 6476 The AS supports both redirect URIs and user codes for interaction, so 6477 it includes both. Since there is no interaction finish mode, the AS 6478 does not include a nonce, but does include a "wait" parameter on the 6479 continuation section because it expects the client instance to poll 6480 for results. 6482 HTTP/1.1 200 OK 6483 Content-Type: application/json 6484 Cache-Control: no-store 6486 { 6487 "interact": { 6488 "redirect": "https://srv.ex/MXKHQ", 6489 "user_code": { 6490 "code": "A1BC-3DFF", 6491 "url": "https://srv.ex/device" 6492 } 6493 }, 6494 "continue": { 6495 "access_token": { 6496 "value": "80UPRY5NM33OMUKMKSKU" 6497 }, 6498 "uri": "https://server.example.com/continue/VGJKPTKC50", 6499 "wait": 60 6500 } 6501 } 6502 The client instance saves the response and displays the user code 6503 visually on its screen along with the static device URL. The client 6504 instance also displays the short interaction URL as a QR code to be 6505 scanned. 6507 If the user scans the code, they are taken to the interaction 6508 endpoint and the AS looks up the current pending request based on the 6509 incoming URL. If the user instead goes to the static page and enters 6510 the code manually, the AS looks up the current pending request based 6511 on the value of the user code. In both cases, the user logs in, is 6512 identified as the RO for the resource being requested, and approves 6513 the request. Once the request has been approved, the AS displays to 6514 the user a message to return to their device. 6516 Meanwhile, the client instance periodically polls the AS every 60 6517 seconds at the continuation URL. The client instance signs the 6518 request using the same key and method that it did in the first 6519 request. 6521 POST /continue/VGJKPTKC50 HTTP/1.1 6522 Host: server.example.com 6523 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6524 Signature-Input: sig1=... 6525 Signature: sig1=... 6526 Digest: sha256=... 6528 The AS retrieves the pending request based on the handle and 6529 determines that it has not yet been authorized. The AS indicates to 6530 the client instance that no access token has yet been issued but it 6531 can continue to call after another 60 second timeout. 6533 HTTP/1.1 200 OK 6534 Content-Type: application/json 6535 Cache-Control: no-store 6537 { 6538 "continue": { 6539 "access_token": { 6540 "value": "G7YQT4KQQ5TZY9SLSS5E" 6541 }, 6542 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 6543 "wait": 60 6544 } 6545 } 6546 Note that the continuation URL and access token have been rotated 6547 since they were used by the client instance to make this call. The 6548 client instance polls the continuation URL after a 60 second timeout 6549 using this new information. 6551 POST /continue/ATWHO4Q1WV HTTP/1.1 6552 Host: server.example.com 6553 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 6554 Signature-Input: sig1=... 6555 Signature: sig1=... 6556 Digest: sha256=... 6558 The AS retrieves the pending request based on the URL and access 6559 token, determines that it has been approved, and issues an access 6560 token for the client to use at the RS. 6562 NOTE: '\' line wrapping per RFC 8792 6564 HTTP/1.1 200 OK 6565 Content-Type: application/json 6566 Cache-Control: no-store 6568 { 6569 "access_token": { 6570 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6571 "manage": "https://server.example.com/token/PRY5NM33O\ 6572 M4TB8N6BW7OZB8CDFONP219RP1L", 6573 "access": [ 6574 "dolphin-metadata", "some other thing" 6575 ] 6576 } 6577 } 6579 D.3. No User Involvement 6581 In this scenario, the client instance is requesting access on its own 6582 behalf, with no user to interact with. 6584 The client instance creates a request to the AS, identifying itself 6585 with its public key and using MTLS to make the request. 6587 POST /tx HTTP/1.1 6588 Host: server.example.com 6589 Content-Type: application/json 6591 { 6592 "access_token": { 6593 "access": [ 6594 "backend service", "nightly-routine-3" 6595 ], 6596 }, 6597 "client": { 6598 "key": { 6599 "proof": "mtls", 6600 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 6601 } 6602 } 6603 } 6605 The AS processes this and determines that the client instance can ask 6606 for the requested resources and issues an access token. 6608 HTTP/1.1 200 OK 6609 Content-Type: application/json 6610 Cache-Control: no-store 6612 { 6613 "access_token": { 6614 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6615 "manage": "https://server.example.com/token", 6616 "access": [ 6617 "backend service", "nightly-routine-3" 6618 ] 6619 } 6620 } 6622 D.4. Asynchronous Authorization 6624 In this scenario, the client instance is requesting on behalf of a 6625 specific RO, but has no way to interact with the user. The AS can 6626 asynchronously reach out to the RO for approval in this scenario. 6628 The client instance starts the request at the AS by requesting a set 6629 of resources. The client instance also identifies a particular user. 6631 POST /tx HTTP/1.1 6632 Host: server.example.com 6633 Content-Type: application/json 6634 Signature-Input: sig1=... 6635 Signature: sig1=... 6636 Digest: sha256=... 6638 { 6639 "access_token": { 6640 "access": [ 6641 { 6642 "type": "photo-api", 6643 "actions": [ 6644 "read", 6645 "write", 6646 "dolphin" 6647 ], 6648 "locations": [ 6649 "https://server.example.net/", 6650 "https://resource.local/other" 6651 ], 6652 "datatypes": [ 6653 "metadata", 6654 "images" 6655 ] 6656 }, 6657 "read", "dolphin-metadata", 6658 { 6659 "type": "financial-transaction", 6660 "actions": [ 6661 "withdraw" 6662 ], 6663 "identifier": "account-14-32-32-3", 6664 "currency": "USD" 6665 }, 6666 "some other thing" 6667 ], 6668 }, 6669 "client": "7C7C4AZ9KHRS6X63AJAO", 6670 "user": { 6671 "sub_ids": [ { 6672 "format": "opaque", 6673 "id": "J2G8G8O4AZ" 6674 } ] 6675 } 6676 } 6677 The AS processes this and determines that the RO needs to interact. 6678 The AS determines that it can reach the identified user 6679 asynchronously and that the identified user does have the ability to 6680 approve this request. The AS indicates to the client instance that 6681 it can poll for continuation. 6683 HTTP/1.1 200 OK 6684 Content-Type: application/json 6685 Cache-Control: no-store 6687 { 6688 "continue": { 6689 "access_token": { 6690 "value": "80UPRY5NM33OMUKMKSKU" 6691 }, 6692 "uri": "https://server.example.com/continue", 6693 "wait": 60 6694 } 6695 } 6697 The AS reaches out to the RO and prompts them for consent. In this 6698 example, the AS has an application that it can push notifications in 6699 to for the specified account. 6701 Meanwhile, the client instance periodically polls the AS every 60 6702 seconds at the continuation URL. 6704 POST /continue HTTP/1.1 6705 Host: server.example.com 6706 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6707 Signature-Input: sig1=... 6708 Signature: sig1=... 6710 The AS retrieves the pending request based on the handle and 6711 determines that it has not yet been authorized. The AS indicates to 6712 the client instance that no access token has yet been issued but it 6713 can continue to call after another 60 second timeout. 6715 HTTP/1.1 200 OK 6716 Content-Type: application/json 6717 Cache-Control: no-store 6719 { 6720 "continue": { 6721 "access_token": { 6722 "value": "BI9QNW6V9W3XFJK4R02D" 6723 }, 6724 "uri": "https://server.example.com/continue", 6725 "wait": 60 6726 } 6727 } 6729 Note that the continuation handle has been rotated since it was used 6730 by the client instance to make this call. The client instance polls 6731 the continuation URL after a 60 second timeout using the new handle. 6733 POST /continue HTTP/1.1 6734 Host: server.example.com 6735 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 6736 Signature-Input: sig1=... 6737 Signature: sig1=... 6739 The AS retrieves the pending request based on the handle and 6740 determines that it has been approved and it issues an access token. 6742 NOTE: '\' line wrapping per RFC 8792 6744 HTTP/1.1 200 OK 6745 Content-Type: application/json 6746 Cache-Control: no-store 6748 { 6749 "access_token": { 6750 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6751 "manage": "https://server.example.com/token/PRY5NM33O\ 6752 M4TB8N6BW7OZB8CDFONP219RP1L", 6753 "access": [ 6754 "dolphin-metadata", "some other thing" 6755 ] 6756 } 6757 } 6759 D.5. Applying OAuth 2.0 Scopes and Client IDs 6761 While GNAP is not designed to be directly compatible with OAuth 2.0 6762 [RFC6749], considerations have been made to enable the use of OAuth 6763 2.0 concepts and constructs more smoothly within GNAP. 6765 In this scenario, the client developer has a client_id and set of 6766 scope values from their OAuth 2.0 system and wants to apply them to 6767 the new protocol. Traditionally, the OAuth 2.0 client developer 6768 would put their client_id and scope values as parameters into a 6769 redirect request to the authorization endpoint. 6771 NOTE: '\' line wrapping per RFC 8792 6773 HTTP 302 Found 6774 Location: https://server.example.com/authorize\ 6775 ?client_id=7C7C4AZ9KHRS6X63AJAO\ 6776 &scope=read%20write%20dolphin\ 6777 &redirect_uri=https://client.example.net/return\ 6778 &response_type=code\ 6779 &state=123455 6781 Now the developer wants to make an analogous request to the AS using 6782 GNAP. To do so, the client instance makes an HTTP POST and places 6783 the OAuth 2.0 values in the appropriate places. 6785 POST /tx HTTP/1.1 6786 Host: server.example.com 6787 Content-Type: application/json 6788 Signature-Input: sig1=... 6789 Signature: sig1=... 6790 Digest: sha256=... 6792 { 6793 "access_token": { 6794 "access": [ 6795 "read", "write", "dolphin" 6796 ], 6797 "flags": [ "bearer" ] 6798 }, 6799 "client": "7C7C4AZ9KHRS6X63AJAO", 6800 "interact": { 6801 "start": ["redirect"], 6802 "finish": { 6803 "method": "redirect", 6804 "uri": "https://client.example.net/return?state=123455", 6805 "nonce": "LKLTI25DK82FX4T4QFZC" 6806 } 6807 } 6808 } 6810 The client_id can be used to identify the client instance's keys that 6811 it uses for authentication, the scopes represent resources that the 6812 client instance is requesting, and the redirect_uri and state value 6813 are pre-combined into a finish URI that can be unique per request. 6814 The client instance additionally creates a nonce to protect the 6815 callback, separate from the state parameter that it has added to its 6816 return URL. 6818 From here, the protocol continues as above. 6820 Appendix E. JSON Structures and Polymorphism 6822 GNAP makes use of polymorphism within the JSON [RFC8259] structures 6823 used for the protocol. Each portion of this protocol is defined in 6824 terms of the JSON data type that its values can take, whether it's a 6825 string, object, array, boolean, or number. For some fields, 6826 different data types offer different descriptive capabilities and are 6827 used in different situations for the same field. Each data type 6828 provides a different syntax to express the same underlying semantic 6829 protocol element, which allows for optimization and simplification in 6830 many common cases. 6832 Even though JSON is often used to describe strongly typed structures, 6833 JSON on its own is naturally polymorphic. In JSON, the named members 6834 of an object have no type associated with them, and any data type can 6835 be used as the value for any member. In practice, each member has a 6836 semantic type that needs to make sense to the parties creating and 6837 consuming the object. Within this protocol, each object member is 6838 defined in terms of its semantic content, and this semantic content 6839 might have expressions in different concrete data types for different 6840 specific purposes. Since each object member has exactly one value in 6841 JSON, each data type for an object member field is naturally mutually 6842 exclusive with other data types within a single JSON object. 6844 For example, a resource request for a single access token is composed 6845 of an array of resource request descriptions while a request for 6846 multiple access tokens is composed of an object whose member values 6847 are all arrays. Both of these represent requests for access, but the 6848 difference in syntax allows the client instance and AS to 6849 differentiate between the two request types in the same request. 6851 Another form of polymorphism in JSON comes from the fact that the 6852 values within JSON arrays need not all be of the same JSON data type. 6853 However, within this protocol, each element within the array needs to 6854 be of the same kind of semantic element for the collection to make 6855 sense, even when the data types are different from each other. 6857 For example, each aspect of a resource request can be described using 6858 an object with multiple dimensional components, or the aspect can be 6859 requested using a string. In both cases, the resource request is 6860 being described in a way that the AS needs to interpret, but with 6861 different levels of specificity and complexity for the client 6862 instance to deal with. An API designer can provide a set of common 6863 access scopes as simple strings but still allow client software 6864 developers to specify custom access when needed for more complex 6865 APIs. 6867 Extensions to this specification can use different data types for 6868 defined fields, but each extension needs to not only declare what the 6869 data type means, but also provide justification for the data type 6870 representing the same basic kind of thing it extends. For example, 6871 an extension declaring an "array" representation for a field would 6872 need to explain how the array represents something akin to the non- 6873 array element that it is replacing. 6875 Authors' Addresses 6877 Justin Richer (editor) 6878 Bespoke Engineering 6879 Email: ietf@justin.richer.org 6880 URI: https://bspk.io/ 6882 Aaron Parecki 6883 Okta 6885 Email: aaron@parecki.com 6886 URI: https://aaronparecki.com 6888 Fabien Imbault 6889 acert.io 6891 Email: fabien.imbault@acert.io 6892 URI: https://acert.io/