idnits 2.17.1 draft-ietf-gnap-core-protocol-07.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 279 has weird spacing: '... Client appli...' == Line 299 has weird spacing: '...nd-user natur...' == Line 359 has weird spacing: '...tribute chara...' == Line 361 has weird spacing: '...s Token a dat...' == Line 371 has weird spacing: '...ivilege right...' == (4 more instances...) -- The document date (24 September 2021) is 944 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-oauth-signed-http-request' is defined on line 5647, but no explicit reference was found in the text == Unused Reference: 'RFC6973' is defined on line 5742, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-05) exists of draft-ietf-gnap-resource-servers-00 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-06 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-rar-07 == Outdated reference: A later version (-18) exists of draft-ietf-secevent-subject-identifiers-08 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Downref: Normative reference to an Informational RFC: RFC 8792 Summary: 3 errors (**), 0 flaws (~~), 14 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GNAP J. Richer, Ed. 3 Internet-Draft Bespoke Engineering 4 Intended status: Standards Track A. Parecki 5 Expires: 28 March 2022 Okta 6 F. Imbault 7 acert.io 8 24 September 2021 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-07 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 March 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 . . . . . . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . 38 77 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 40 78 2.5.2. Finish Interaction Modes . . . . . . . . . . . . . . 41 79 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 44 80 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 44 81 2.6. Extending The Grant Request . . . . . . . . . . . . . . . 44 82 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 45 83 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 46 84 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 85 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 48 86 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 51 87 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 52 88 3.3.1. Redirection to an arbitrary URL . . . . . . . . . . . 53 89 3.3.2. Launch of an application URL . . . . . . . . . . . . 54 90 3.3.3. Display of a Short User Code . . . . . . . . . . . . 54 91 3.3.4. Interaction Finish . . . . . . . . . . . . . . . . . 55 92 3.3.5. Extending Interaction Mode Responses . . . . . . . . 56 93 3.4. Returning Subject Information . . . . . . . . . . . . . . 56 94 3.5. Returning Dynamically-bound Reference Handles . . . . . . 57 95 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 58 96 3.7. Extending the Response . . . . . . . . . . . . . . . . . 59 97 4. Determining Authorization and Consent . . . . . . . . . . . . 59 98 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 62 99 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 62 100 4.1.2. Interaction at the User Code URI . . . . . . . . . . 63 101 4.1.3. Interaction through an Application URI . . . . . . . 64 102 4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 64 103 4.2.1. Completing Interaction with a Browser Redirect to the 104 Callback URI . . . . . . . . . . . . . . . . . . . . 65 105 4.2.2. Completing Interaction with a Direct HTTP Request 106 Callback . . . . . . . . . . . . . . . . . . . . . . 66 107 4.2.3. Calculating the interaction hash . . . . . . . . . . 66 108 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 68 109 5.1. Continuing After a Completed Interaction . . . . . . . . 70 110 5.2. Continuing During Pending Interaction . . . . . . . . . . 71 111 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 73 112 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 78 113 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 79 114 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 79 115 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 81 116 7. Securing Requests from the Client Instance . . . . . . . . . 82 117 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 83 118 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 84 119 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 84 120 7.3. Proving Possession of a Key with a Request . . . . . . . 85 121 7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 87 122 7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 91 123 7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 93 124 7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 97 125 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 101 126 8.1. Requesting Resources By Reference . . . . . . . . . . . . 104 127 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 106 128 9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 107 129 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 109 130 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 109 131 12. Security Considerations . . . . . . . . . . . . . . . . . . . 109 132 12.1. TLS Protection in Transit . . . . . . . . . . . . . . . 109 133 12.2. Protection of Client Instance Key Material . . . . . . . 110 134 12.3. Protection of Authorization Server . . . . . . . . . . . 111 135 12.4. Symmetric and Asymmetric Client Instance Keys . . . . . 112 136 12.5. Generation of Access Tokens . . . . . . . . . . . . . . 113 137 12.6. Bearer Access Tokens . . . . . . . . . . . . . . . . . . 114 138 12.7. Key-Bound Token Access Tokens . . . . . . . . . . . . . 114 139 12.8. Exposure of End-user Credentials to Client Instance . . 115 140 12.9. Mixing Up Authorization Servers . . . . . . . . . . . . 116 141 12.10. Processing of Client-Presented User Information . . . . 117 142 12.11. Client Instance Pre-registration . . . . . . . . . . . . 118 143 12.12. Client Instance Impersonation . . . . . . . . . . . . . 119 144 12.13. Interception of Information in the Browser . . . . . . . 120 145 12.14. Callback URL Manipulation . . . . . . . . . . . . . . . 120 146 12.15. MTLS Deployment Patterns . . . . . . . . . . . . . . . . 121 147 12.16. Interception of Responses from the AS . . . . . . . . . 121 148 12.17. Key Distribution . . . . . . . . . . . . . . . . . . . . 122 149 12.18. Interaction Finish Modes and Polling . . . . . . . . . . 122 150 12.19. Storage of Information During Interaction and 151 Continuation . . . . . . . . . . . . . . . . . . . . . 123 152 12.20. Denial of Service (DoS) through Grant Continuation . . . 124 153 12.21. Exhaustion of Random Value Space . . . . . . . . . . . . 124 154 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 125 155 13.1. Surveillance . . . . . . . . . . . . . . . . . . . . . . 125 156 13.1.1. Surveillance by the Client . . . . . . . . . . . . . 125 157 13.1.2. Surveillance by the Authorization Server . . . . . . 125 158 13.2. Stored Data . . . . . . . . . . . . . . . . . . . . . . 126 159 13.3. Intrusion . . . . . . . . . . . . . . . . . . . . . . . 127 160 13.4. Correlation . . . . . . . . . . . . . . . . . . . . . . 127 161 13.4.1. Correlation by Clients . . . . . . . . . . . . . . . 127 162 13.4.2. Correlation by Resource Servers . . . . . . . . . . 127 163 13.4.3. Correlation by Authorization Servers . . . . . . . . 128 164 13.5. Disclosure in Shared References . . . . . . . . . . . . 128 165 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 128 166 14.1. Normative References . . . . . . . . . . . . . . . . . . 128 167 14.2. Informative References . . . . . . . . . . . . . . . . . 131 168 Appendix A. Document History . . . . . . . . . . . . . . . . . . 131 169 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 134 170 Appendix C. Component Data Models . . . . . . . . . . . . . . . 136 171 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 136 172 D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 137 173 D.2. Secondary Device Interaction . . . . . . . . . . . . . . 140 174 D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 143 175 D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 144 176 D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 148 177 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 149 178 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 150 180 1. Introduction 182 This protocol allows a piece of software, the client instance, to 183 request delegated authorization to resource servers and to request 184 direct information. This delegation is facilitated by an 185 authorization server usually on behalf of a resource owner. The end- 186 user operating the software may interact with the authorization 187 server to authenticate, provide consent, and authorize the request. 189 The process by which the delegation happens is known as a grant, and 190 GNAP allows for the negotiation of the grant process over time by 191 multiple parties acting in distinct roles. 193 This specification focuses on the portions of the delegation process 194 facing the client instance. In particular, this specification 195 defines interoperable methods for a client instance to request, 196 negotiate, and receive access to information facilitated by the 197 authorization server. This specification also discusses discovery 198 mechanisms for the client instance to configure itself dynamically. 199 The means for an authorization server and resource server to 200 interoperate are discussed in the companion document, 201 [I-D.draft-ietf-gnap-resource-servers]. 203 The focus of this protocol is to provide interoperability between the 204 different parties acting in each role, and is not to specify 205 implementation details of each. Where appropriate, GNAP may make 206 recommendations about internal implementation details, but these 207 recommendations are to ensure the security of the overall deployment 208 rather than to be prescriptive in the implementation. 210 This protocol solves many of the same use cases as OAuth 2.0 211 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 212 have grown up around that ecosystem. However, GNAP is not an 213 extension of OAuth 2.0 and is not intended to be directly compatible 214 with OAuth 2.0. GNAP seeks to provide functionality and solve use 215 cases that OAuth 2.0 cannot easily or cleanly address. Appendix B 216 further details the protocol rationale compared to OAuth 2.0. GNAP 217 and OAuth 2.0 will likely exist in parallel for many deployments, and 218 considerations have been taken to facilitate the mapping and 219 transition from legacy systems to GNAP. Some examples of these can 220 be found in Appendix D.5. 222 1.1. Terminology 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 226 "OPTIONAL" in this document are to be interpreted as described in 227 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 228 capitals, as shown here. 230 This document contains non-normative examples of partial and complete 231 HTTP messages, JSON structures, URLs, query components, keys, and 232 other elements. Some examples use a single trailing backslash '' to 233 indicate line wrapping for long values, as per [RFC8792]. The "\" 234 character and leading spaces on wrapped lines are not part of the 235 value. 237 1.2. Roles 239 The parties in GNAP perform actions under different roles. Roles are 240 defined by the actions taken and the expectations leveraged on the 241 role by the overall protocol. 243 +-------------+ +------------+ 244 | | | | 245 |Authorization| | Resource | 246 | Server | | Server | 247 | |<-+ +---->| | 248 +-------------+ | | +------------+ 249 + | | 250 + | | 251 + | | 252 + | | 253 + | | 254 + +----------+ 255 + | Client | 256 + | Instance | 257 + +----------+ 258 + + 259 + + 260 + + 261 +-----------+ + +------------+ 262 | | + + + +| | 263 | Resource | | End | 264 | Owner | ~ ~ ~ ~ ~ ~ | User | 265 | | | | 266 +-----------+ +------------+ 268 Legend 270 + + + indicates interaction between a human and computer 271 ----- indicates interaction between two pieces of software 272 ~ ~ ~ indicates a potential equivalence or out-of-band 273 communication between roles 275 Authorization Server (AS) server that grants delegated privileges to 276 a particular instance of client software in the form of access 277 tokens or other information (such as subject information). 279 Client application operated by an end-user that consumes resources 280 from one or several RSs, possibly requiring access privileges from 281 one or several ASs. Example: a client can be a mobile 282 application, a web application, etc. Note: this specification 283 differentiates between a specific instance (the client instance, 284 identified by its unique key) and the software running the 285 instance (the client software). For some kinds of client 286 software, there could be many instances of that software, each 287 instance with a different key. 289 Resource Server (RS) server that provides operations on protected 290 resources, where operations require a valid access token issued by 291 an AS. 293 Resource Owner (RO) subject entity that may grant or deny operations 294 on resources it has authority upon. Note: the act of granting or 295 denying an operation may be manual (i.e. through an interaction 296 with a physical person) or automatic (i.e. through predefined 297 organizational rules). 299 End-user natural person that operates a client instance. Note: that 300 natural person may or may not be the same entity as the RO. 302 The design of GNAP does not assume any one deployment architecture, 303 but instead attempts to define roles that can be fulfilled in a 304 number of different ways for different use cases. As long as a given 305 role fulfills all of its obligations and behaviors as defined by the 306 protocol, GNAP does not make additional requirements on its structure 307 or setup. 309 Multiple roles can be fulfilled by the same party, and a given party 310 can switch roles in different instances of the protocol. For 311 example, the RO and end-user in many instances are the same person, 312 where a user is authorizing the client instance to act on their own 313 behalf at the RS. In this case, one party fulfills both of the RO 314 and end-user roles, but the roles themselves are still defined 315 separately from each other to allow for other use cases where they 316 are fulfilled by different parties. 318 For another example, in some complex scenarios, an RS receiving 319 requests from one client instance can act as a client instance for a 320 downstream secondary RS in order to fulfill the original request. In 321 this case, one piece of software is both an RS and a client instance 322 from different perspectives, and it fulfills these roles separately 323 as far as the overall protocol is concerned. 325 A single role need not be deployed as a monolithic service. For 326 example, A client instance could have components that are installed 327 on the end-user's device as well as a back-end system that it 328 communicates with. If both of these components participate in the 329 delegation protocol, they are both considered part of the client 330 instance. If there are several copies of the client software that 331 run separately but all share the same key material, such as a 332 deployed cluster, then this cluster is considered a single client 333 instance. 335 In these cases, the distinct components of what is considered a GNAP 336 client instance may use any number of different communication 337 mechanisms between them, all of which would be considered an 338 implementation detail of the client instances and out of scope of 339 GNAP. 341 For another example, an AS could likewise be built out of many 342 constituent components in a distributed architecture. The component 343 that the client instance calls directly could be different from the 344 component that the RO interacts with to drive consent, since API 345 calls and user interaction have different security considerations in 346 many environments. Furthermore, the AS could need to collect 347 identity claims about the RO from one system that deals with user 348 attributes while generating access tokens at another system that 349 deals with security rights. From the perspective of GNAP, all of 350 these are pieces of the AS and together fulfill the role of the AS as 351 defined by the protocol. These pieces may have their own internal 352 communications mechanisms which are considered out of scope of GNAP. 354 1.3. Elements 356 In addition to the roles above, the protocol also involves several 357 elements that are acted upon by the roles throughout the process. 359 Attribute characteristics related to a subject. 361 Access Token a data artifact representing a set of rights and/or 362 attributes. Note: an access token can be first issued to an 363 client instance (requiring authorization by the RO) and 364 subsequently rotated. 366 Grant (verb): to permit an instance of client software to receive 367 some attributes at a specific time and valid for a specific 368 duration and/or to exercise some set of delegated rights to access 369 a protected resource (noun): the act of granting. 371 Privilege right or attribute associated with a subject. Note: the 372 RO defines and maintains the rights and attributes associated to 373 the protected resource, and might temporarily delegate some set of 374 those privileges to an end-user. This process is refered to as 375 privilege delegation. 377 Protected Resource protected API (Application Programming Interface) 378 served by an RS and that can be accessed by a client, if and only 379 if a valid access token is provided. Note: to avoid complex 380 sentences, the specification document may simply refer to resource 381 instead of protected resource. 383 Right ability given to a subject to perform a given operation on a 384 resource under the control of an RS. 386 Subject person, organization or device. 388 Subject Information statement asserted by an AS about a subject. 390 1.4. Trust relationships 392 GNAP defines its trust objective as: "the RO trusts the AS to ensure 393 access validation and delegation of protected resources to end-users, 394 through third party clients." 396 This trust objective can be decomposed into trust relationships 397 between software elements and roles, especially the pairs end-user/ 398 RO, end-user/client, client/AS, RS/RO, AS/RO, AS/RS. Trust of an 399 agent by its pair can exist if the pair is informed that the agent 400 has made a promise to follow the protocol in the past (e.g. pre- 401 registration, uncompromised cryptographic components) or if the pair 402 is able to infer by indirect means that the agent has made such a 403 promise (e.g. a compliant client request). Each agent defines its 404 own valuation function of promises given or received. Examples of 405 such valuations can be the benefits from interacting with other 406 agents (e.g. safety in client access, interoperability with identity 407 standards), the cost of following the protocol (including its 408 security and privacy requirements and recommendations), a ranking of 409 promise importance (e.g. a policy decision made by the AS), the 410 assessment of one's vulnerability or risk of not being able to defend 411 against threats, etc. Those valuations may depend on the context of 412 the request. For instance, the AS may decide to either take into 413 account or discard hints provided by the client, the RS may refuse 414 bearer tokens, etc. depending on the specific case in which GNAP is 415 used. Some promises can be conditional of some previous interactions 416 (e.g. repeated requests). 418 Looking back on each trust relationship: 420 * end-user/RO: this relationship exists only when the end-user and 421 the RO are different, in which case the end-user needs some out of 422 band mechanism of getting the RO consent (see Section 4). GNAP 423 generally assumes that humans can be authenticated thanks to 424 identity protocols (for instance, through an id_token assertion in 425 Section 2.2). 427 * end-user/client: the client acts as a user agent. Depending on 428 the technology used (browser, SPA, mobile application, IoT device, 429 etc.), some interactions may or may not be possible (as described 430 in Section 2.5.1). Client developers promise to implement 431 requirements and generally some recommendations or best practices, 432 so that the end-users may confidently use their software. 433 However, end-users might also be facing some attacker's client 434 software, without even realizing it. 436 * client/AS: An honest AS may be facing an attacker's client (as 437 discussed just above), or the reverse, and GNAP aims at making 438 common attacks impractical. The core specification makes access 439 tokens opaque to the client and defines the request/response 440 scheme in detail, therefore avoiding extra trust hypotheses from 441 this critical piece of software. Yet the AS may further define 442 cryptographic attestations or optional rules to simplify the 443 access of clients it already trusts, due to past behavior or 444 organizational policies (see Section 2.3). 446 * RS/RO: the RS promises it protects its resources from unauthorized 447 access, and only accepts valid access tokens issued by a trusted 448 AS. In case tokens are key bound, proper validation is expected 449 from the RS. 451 * AS/RO: the AS is expected to follow the decisions made by the RO, 452 either through interactive consent requests, repeated interactions 453 or automated rules (as described in Section 1.5). Privacy 454 considerations aim to reduce the risk of an honest but too curious 455 AS, or the consequences of an unexpected user data exposure. 457 * AS/RS: the AS promises to issue valid access tokens to legitimate 458 client requests (i.e. after carrying out appropriate due 459 diligence, as defined in the GNAP protocol). Some optional 460 configurations are covered by 461 [I-D.draft-ietf-gnap-resource-servers]. 463 A global assumption made by GNAP is that authorization requests are 464 security and privacy sensitive, and appropriate measures are 465 respectively detailed in Section 12 and Section 13. 467 A formal trust model is out of scope of this specification, but might 468 be carried out thanks to [promise-theory]. 470 1.5. Sequences 472 GNAP can be used in a variety of ways to allow the core delegation 473 process to take place. Many portions of this process are 474 conditionally present depending on the context of the deployments, 475 and not every step in this overview will happen in all circumstances. 477 Note that a connection between roles in this process does not 478 necessarily indicate that a specific protocol message is sent across 479 the wire between the components fulfilling the roles in question, or 480 that a particular step is required every time. For example, for a 481 client instance interested in only getting subject information 482 directly, and not calling an RS, all steps involving the RS below do 483 not apply. 485 In some circumstances, the information needed at a given stage is 486 communicated out of band or is preconfigured between the components 487 or entities performing the roles. For example, one entity can fulfil 488 multiple roles, and so explicit communication between the roles is 489 not necessary within the protocol flow. Additionally some components 490 may not be involved in all use cases. For example, a client instance 491 could be calling the AS just to get direct user information and have 492 no need to get an access token to call an RS. 494 +------------+ +------------+ 495 | End-user | ~ ~ ~ ~ | Resource | 496 | | | Owner (RO) | 497 +------------+ +------------+ 498 + + 499 + + 500 (A) (B) 501 + + 502 + + 503 +--------+ + +------------+ 504 | Client | (1) + | Resource | 505 |Instance| + | Server | 506 | | +---------------+ | (RS) | 507 | |--(2)->| Authorization | | | 508 | |<-(3)--| Server | | | 509 | | | (AS) | | | 510 | |--(4)->| | | | 511 | |<-(5)--| | | | 512 | |--------------(6)------------->| | 513 | | | | (7) | | 514 | |<-------------(8)------------->| | 515 | |--(9)->| | | | 516 | |<-(10)-| | | | 517 | |--------------(11)------------>| | 518 | | | | (12) | | 519 | |-(13)->| | | | 520 | | | | | | 521 +--------+ +---------------+ +------------+ 523 Legend 524 + + + indicates a possible interaction with a human 525 ----- indicates an interaction between protocol roles 526 ~ ~ ~ indicates a potential equivalence or out-of-band 527 communication between roles 529 * (A) The end-user interacts with the client instance to indicate a 530 need for resources on behalf of the RO. This could identify the 531 RS the client instance needs to call, the resources needed, or the 532 RO that is needed to approve the request. Note that the RO and 533 end-user are often the same entity in practice, but some more 534 dynamic processes are discussed in 535 [I-D.draft-ietf-gnap-resource-servers]. 537 * (1) The client instance determines what access is needed and which 538 AS to approach for access. Note that for most situations, the 539 client instance is pre-configured with which AS to talk to and 540 which kinds of access it needs. 542 * (2) The client instance requests access at the AS (Section 2). 544 * (3) The AS processes the request and determines what is needed to 545 fulfill the request. The AS sends its response to the client 546 instance (Section 3). 548 * (B) If interaction is required, the AS interacts with the RO 549 (Section 4) to gather authorization. The interactive component of 550 the AS can function using a variety of possible mechanisms 551 including web page redirects, applications, challenge/response 552 protocols, or other methods. The RO approves the request for the 553 client instance being operated by the end-user. Note that the RO 554 and end-user are often the same entity in practice. 556 * (4) The client instance continues the grant at the AS (Section 5). 558 * (5) If the AS determines that access can be granted, it returns a 559 response to the client instance (Section 3) including an access 560 token (Section 3.2) for calling the RS and any directly returned 561 information (Section 3.4) about the RO. 563 * (6) The client instance uses the access token (Section 7.2) to 564 call the RS. 566 * (7) The RS determines if the token is sufficient for the request 567 by examining the token. The means of the RS determining this 568 access are out of scope of this specification, but some options 569 are discussed in [I-D.draft-ietf-gnap-resource-servers]. 571 * (8) The client instance calls the RS (Section 7.2) using the 572 access token until the RS or client instance determine that the 573 token is no longer valid. 575 * (9) When the token no longer works, the client instance fetches an 576 updated access token (Section 6.1) based on the rights granted in 577 (5). 579 * (10) The AS issues a new access token (Section 3.2) to the client 580 instance. 582 * (11) The client instance uses the new access token (Section 7.2) 583 to call the RS. 585 * (12) The RS determines if the new token is sufficient for the 586 request. The means of the RS determining this access are out of 587 scope of this specification, but some options are discussed in 588 [I-D.draft-ietf-gnap-resource-servers]. 590 * (13) The client instance disposes of the token (Section 6.2) once 591 the client instance has completed its access of the RS and no 592 longer needs the token. 594 The following sections and Appendix D contain specific guidance on 595 how to use GNAP in different situations and deployments. For 596 example, it is possible for the client instance to never request an 597 access token and never call an RS, just as it is possible for there 598 not to be a user involved in the delegation process. 600 1.5.1. Redirect-based Interaction 602 In this example flow, the client instance is a web application that 603 wants access to resources on behalf of the current user, who acts as 604 both the end-user and the resource owner (RO). Since the client 605 instance is capable of directing the user to an arbitrary URL and 606 receiving responses from the user's browser, interaction here is 607 handled through front-channel redirects using the user's browser. 608 The redirection URL used for interaction is a service hosted by the 609 AS in this example. The client instance uses a persistent session 610 with the user to ensure the same user that is starting the 611 interaction is the user that returns from the interaction. 613 +--------+ +--------+ +------+ 614 | Client | | AS | | User | 615 |Instance| | | | | 616 | |< (1) + Start Session + + + + + + + + + + + + + + + +| | 617 | | | | | | 618 | |--(2)--- Request Access --------->| | | | 619 | | | | | | 620 | |<-(3)-- Interaction Needed -------| | | | 621 | | | | | | 622 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 623 | | | | | | 624 | | | |<+ (5) +>| | 625 | | | | AuthN | | 626 | | | | | | 627 | | | |<+ (6) +>| | 628 | | | | AuthZ | | 629 | | | | | | 630 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 631 | | | | +------+ 632 | |--(8)--- Continue Request ------->| | 633 | | | | 634 | |<-(9)----- Grant Access ----------| | 635 | | | | 636 | | | | +--------+ 637 | |--(10)-- Access API ---------------------------->| RS | 638 | | | | | | 639 | |<-(11)-- API Response ---------------------------| | 640 | | | | +--------+ 641 +--------+ +--------+ 643 1. The client instance establishes a verifiable session to the 644 user, in the role of the end-user. 646 2. The client instance requests access to the resource (Section 2). 647 The client instance indicates that it can redirect to an 648 arbitrary URL (Section 2.5.1.1) and receive a redirect from the 649 browser (Section 2.5.2.1). The client instance stores 650 verification information for its redirect in the session created 651 in (1). 653 3. The AS determines that interaction is needed and responds 654 (Section 3) with a URL to send the user to (Section 3.3.1) and 655 information needed to verify the redirect (Section 3.3.4) in 656 (7). The AS also includes information the client instance will 657 need to continue the request (Section 3.1) in (8). The AS 658 associates this continuation information with an ongoing request 659 that will be referenced in (4), (6), and (8). 661 4. The client instance stores the verification and continuation 662 information from (3) in the session from (1). The client 663 instance then redirects the user to the URL (Section 4.1.1) 664 given by the AS in (3). The user's browser loads the 665 interaction redirect URL. The AS loads the pending request 666 based on the incoming URL generated in (3). 668 5. The user authenticates at the AS, taking on the role of the RO. 670 6. As the RO, the user authorizes the pending request from the 671 client instance. 673 7. When the AS is done interacting with the user, the AS redirects 674 the user back (Section 4.2.1) to the client instance using the 675 redirect URL provided in (2). The redirect URL is augmented 676 with an interaction reference that the AS associates with the 677 ongoing request created in (2) and referenced in (4). The 678 redirect URL is also augmented with a hash of the security 679 information provided in (2) and (3). The client instance loads 680 the verification information from (2) and (3) from the session 681 created in (1). The client instance calculates a hash 682 (Section 4.2.3) based on this information and continues only if 683 the hash validates. Note that the client instance needs to 684 ensure that the parameters for the incoming request match those 685 that it is expecting from the session created in (1). The 686 client instance also needs to be prepared for the end-user never 687 being returned to the client instance and handle timeouts 688 appropriately. 690 8. The client instance loads the continuation information from (3) 691 and sends the interaction reference from (7) in a request to 692 continue the request (Section 5.1). The AS validates the 693 interaction reference ensuring that the reference is associated 694 with the request being continued. 696 9. If the request has been authorized, the AS grants access to the 697 information in the form of access tokens (Section 3.2) and 698 direct subject information (Section 3.4) to the client instance. 700 10. The client instance uses the access token (Section 7.2) to call 701 the RS. 703 11. The RS validates the access token and returns an appropriate 704 response for the API. 706 An example set of protocol messages for this method can be found in 707 Appendix D.1. 709 1.5.2. User-code Interaction 711 In this example flow, the client instance is a device that is capable 712 of presenting a short, human-readable code to the user and directing 713 the user to enter that code at a known URL. The URL the user enters 714 the code at is an interactive service hosted by the AS in this 715 example. The client instance is not capable of presenting an 716 arbitrary URL to the user, nor is it capable of accepting incoming 717 HTTP requests from the user's browser. The client instance polls the 718 AS while it is waiting for the RO to authorize the request. The 719 user's interaction is assumed to occur on a secondary device. In 720 this example it is assumed that the user is both the end-user and RO, 721 though the user is not assumed to be interacting with the client 722 instance through the same web browser used for interaction at the AS. 724 +--------+ +--------+ +------+ 725 | Client | | AS | | User | 726 |Instance|--(1)--- Request Access --------->| | | | 727 | | | | | | 728 | |<-(2)-- Interaction Needed -------| | | | 729 | | | | | | 730 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 731 | | | | | | 732 | | | |<+ (4) + | | 733 | | | |Open URI | | 734 | | | | | | 735 | | | |<+ (5) +>| | 736 | | | | AuthN | | 737 | |--(9)--- Continue Request (A) --->| | | | 738 | | | |<+ (6) +>| | 739 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 740 | | | | | | 741 | | | |<+ (7) +>| | 742 | | | | AuthZ | | 743 | | | | | | 744 | | | |<+ (8) +>| | 745 | | | |Completed| | 746 | | | | | | 747 | |--(11)-- Continue Request (B) --->| | +------+ 748 | | | | 749 | |<-(12)----- Grant Access ---------| | 750 | | | | 751 | | | | +--------+ 752 | |--(13)-- Access API ---------------------------->| RS | 753 | | | | | | 754 | |<-(14)-- API Response ---------------------------| | 755 | | | | +--------+ 756 +--------+ +--------+ 757 1. The client instance requests access to the resource (Section 2). 758 The client instance indicates that it can display a user code 759 (Section 2.5.1.3). 761 2. The AS determines that interaction is needed and responds 762 (Section 3) with a user code to communicate to the user 763 (Section 3.3.3). This could optionally include a URL to direct 764 the user to, but this URL should be static and so could be 765 configured in the client instance's documentation. The AS also 766 includes information the client instance will need to continue 767 the request (Section 3.1) in (8) and (10). The AS associates 768 this continuation information with an ongoing request that will 769 be referenced in (4), (6), (8), and (10). 771 3. The client instance stores the continuation information from (2) 772 for use in (8) and (10). The client instance then communicates 773 the code to the user (Section 4.1.1) given by the AS in (2). 775 4. The user's directs their browser to the user code URL. This URL 776 is stable and can be communicated via the client software's 777 documentation, the AS documentation, or the client software 778 itself. Since it is assumed that the RO will interact with the 779 AS through a secondary device, the client instance does not 780 provide a mechanism to launch the RO's browser at this URL. 782 5. The end-user authenticates at the AS, taking on the role of the 783 RO. 785 6. The RO enters the code communicated in (3) to the AS. The AS 786 validates this code against a current request in process. 788 7. As the RO, the user authorizes the pending request from the 789 client instance. 791 8. When the AS is done interacting with the user, the AS indicates 792 to the RO that the request has been completed. 794 9. Meanwhile, the client instance loads the continuation 795 information stored at (3) and continues the request (Section 5). 796 The AS determines which ongoing access request is referenced 797 here and checks its state. 799 10. If the access request has not yet been authorized by the RO in 800 (6), the AS responds to the client instance to continue the 801 request (Section 3.1) at a future time through additional polled 802 continuation requests. This response can include updated 803 continuation information as well as information regarding how 804 long the client instance should wait before calling again. The 805 client instance replaces its stored continuation information 806 from the previous response (2). Note that the AS may need to 807 determine that the RO has not approved the request in a 808 sufficient amount of time and return an appropriate error to the 809 client instance. 811 11. The client instance continues to poll the AS (Section 5.2) with 812 the new continuation information in (9). 814 12. If the request has been authorized, the AS grants access to the 815 information in the form of access tokens (Section 3.2) and 816 direct subject information (Section 3.4) to the client instance. 818 13. The client instance uses the access token (Section 7.2) to call 819 the RS. 821 14. The RS validates the access token and returns an appropriate 822 response for the API. 824 An example set of protocol messages for this method can be found in 825 Appendix D.2. 827 1.5.3. Asynchronous Authorization 829 In this example flow, the end-user and RO roles are fulfilled by 830 different parties, and the RO does not interact with the client 831 instance. The AS reaches out asynchronously to the RO during the 832 request process to gather the RO's authorization for the client 833 instance's request. The client instance polls the AS while it is 834 waiting for the RO to authorize the request. 836 +--------+ +--------+ +------+ 837 | Client | | AS | | RO | 838 |Instance|--(1)--- Request Access --------->| | | | 839 | | | | | | 840 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 841 | | | |<+ (3) +>| | 842 | | | | AuthN | | 843 | |--(6)--- Continue Request (A) --->| | | | 844 | | | |<+ (4) +>| | 845 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 846 | | | | | | 847 | | | |<+ (5) +>| | 848 | | | |Completed| | 849 | | | | | | 850 | |--(8)--- Continue Request (B) --->| | +------+ 851 | | | | 852 | |<-(9)------ Grant Access ---------| | 853 | | | | 854 | | | | +--------+ 855 | |--(10)-- Access API ---------------------------->| RS | 856 | | | | | | 857 | |<-(11)-- API Response ---------------------------| | 858 | | | | +--------+ 859 +--------+ +--------+ 861 1. The client instance requests access to the resource (Section 2). 862 The client instance does not send any interactions modes to the 863 server, indicating that it does not expect to interact with the 864 RO. The client instance can also signal which RO it requires 865 authorization from, if known, by using the user request section 866 (Section 2.4). 868 2. The AS determines that interaction is needed, but the client 869 instance cannot interact with the RO. The AS responds 870 (Section 3) with the information the client instance will need 871 to continue the request (Section 3.1) in (6) and (8), including 872 a signal that the client instance should wait before checking 873 the status of the request again. The AS associates this 874 continuation information with an ongoing request that will be 875 referenced in (3), (4), (5), (6), and (8). 877 3. The AS determines which RO to contact based on the request in 878 (1), through a combination of the user request (Section 2.4), 879 the resources request (Section 2.1), and other policy 880 information. The AS contacts the RO and authenticates them. 882 4. The RO authorizes the pending request from the client instance. 884 5. When the AS is done interacting with the RO, the AS indicates to 885 the RO that the request has been completed. 887 6. Meanwhile, the client instance loads the continuation 888 information stored at (2) and continues the request (Section 5). 889 The AS determines which ongoing access request is referenced 890 here and checks its state. 892 7. If the access request has not yet been authorized by the RO in 893 (6), the AS responds to the client instance to continue the 894 request (Section 3.1) at a future time through additional 895 polling. This response can include refreshed credentials as 896 well as information regarding how long the client instance 897 should wait before calling again. The client instance replaces 898 its stored continuation information from the previous response 899 (2). Note that the AS may need to determine that the RO has not 900 approved the request in a sufficient amount of time and return 901 an appropriate error to the client instance. 903 8. The client instance continues to poll the AS (Section 5.2) with 904 the new continuation information from (7). 906 9. If the request has been authorized, the AS grants access to the 907 information in the form of access tokens (Section 3.2) and 908 direct subject information (Section 3.4) to the client instance. 910 10. The client instance uses the access token (Section 7.2) to call 911 the RS. 913 11. The RS validates the access token and returns an appropriate 914 response for the API. 916 An example set of protocol messages for this method can be found in 917 Appendix D.4. 919 1.5.4. Software-only Authorization 921 In this example flow, the AS policy allows the client instance to 922 make a call on its own behalf, without the need for a RO to be 923 involved at runtime to approve the decision. Since there is no 924 explicit RO, the client instance does not interact with an RO. 926 +--------+ +--------+ 927 | Client | | AS | 928 |Instance|--(1)--- Request Access --->| | 929 | | | | 930 | |<-(2)---- Grant Access -----| | 931 | | | | +--------+ 932 | |--(3)--- Access API ------------------->| RS | 933 | | | | | | 934 | |<-(4)--- API Response ------------------| | 935 | | | | +--------+ 936 +--------+ +--------+ 938 1. The client instance requests access to the resource (Section 2). 939 The client instance does not send any interactions modes to the 940 server. 942 2. The AS determines that the request is been authorized, the AS 943 grants access to the information in the form of access tokens 944 (Section 3.2) to the client instance. Note that direct subject 945 information (Section 3.4) is not generally applicable in this use 946 case, as there is no user involved. 948 3. The client instance uses the access token (Section 7.2) to call 949 the RS. 951 4. The RS validates the access token and returns an appropriate 952 response for the API. 954 An example set of protocol messages for this method can be found in 955 Appendix D.3. 957 1.5.5. Refreshing an Expired Access Token 959 In this example flow, the client instance receives an access token to 960 access a resource server through some valid GNAP process. The client 961 instance uses that token at the RS for some time, but eventually the 962 access token expires. The client instance then gets a new access 963 token by rotating the expired access token at the AS using the 964 token's management URL. 966 +--------+ +--------+ 967 | Client | | AS | 968 |Instance|--(1)--- Request Access ----------------->| | 969 | | | | 970 | |<-(2)--- Grant Access --------------------| | 971 | | | | 972 | | +--------+ | | 973 | |--(3)--- Access Resource --->| RS | | | 974 | | | | | | 975 | |<-(4)--- Success Response ---| | | | 976 | | | | | | 977 | | | | | | 978 | | | | | | 979 | |--(5)--- Access Resource --->| | | | 980 | | | | | | 981 | |<-(6)--- Error Response -----| | | | 982 | | +--------+ | | 983 | | | | 984 | |--(7)--- Rotate Token ------------------->| | 985 | | | | 986 | |<-(8)--- Rotated Token -------------------| | 987 | | | | 988 +--------+ +--------+ 990 1. The client instance requests access to the resource (Section 2). 992 2. The AS grants access to the resource (Section 3) with an access 993 token (Section 3.2) usable at the RS. The access token response 994 includes a token management URI. 996 3. The client instance uses the access token (Section 7.2) to call 997 the RS. 999 4. The RS validates the access token and returns an appropriate 1000 response for the API. 1002 5. Time passes and the client instance uses the access token to call 1003 the RS again. 1005 6. The RS validates the access token and determines that the access 1006 token is expired The RS responds to the client instance with an 1007 error. 1009 7. The client instance calls the token management URI returned in 1010 (2) to rotate the access token (Section 6.1). The client 1011 instance uses the access token (Section 7.2) in this call as well 1012 as the appropriate key, see the token rotation section for 1013 details. 1015 8. The AS validates the rotation request including the signature and 1016 keys presented in (5) and returns a new access token 1017 (Section 3.2.1). The response includes a new access token and 1018 can also include updated token management information, which the 1019 client instance will store in place of the values returned in 1020 (2). 1022 1.5.6. Requesting User Information 1024 In this scenario, the client instance does not call an RS and does 1025 not request an access token. Instead, the client instance only 1026 requests and is returned direct subject information (Section 3.4). 1027 Many different interaction modes can be used in this scenario, so 1028 these are shown only in the abstract as functions of the AS here. 1030 +--------+ +--------+ +------+ 1031 | Client | | AS | | User | 1032 |Instance| | | | | 1033 | |--(1)--- Request Access --------->| | | | 1034 | | | | | | 1035 | |<-(2)--- Request Access ----------| | | | 1036 | | | | | | 1037 | |+ (3) + Facilitate Interaction + + + + + + + + + + > | | 1038 | | | | | | 1039 | | | |<+ (4) +>| | 1040 | | | | AuthN | | 1041 | | | | | | 1042 | | | |<+ (5) +>| | 1043 | | | | AuthZ | | 1044 | | | | | | 1045 | |< (6) + Signal Continuation + + + + + + + + + + + + +| | 1046 | | | | +------+ 1047 | |--(7)--- Continue Request ------->| | 1048 | | | | 1049 | |<-(8)----- Grant Access ----------| | 1050 | | | | 1051 +--------+ +--------+ 1053 1. The client instance requests access to subject information 1054 (Section 2). 1056 2. The AS determines that interaction is needed and responds 1057 (Section 3) with appropriate information for facilitating user 1058 interaction (Section 3.3). 1060 3. The client instance facilitates the user interacting with the AS 1061 (Section 4) as directed in (2). 1063 4. The user authenticates at the AS, taking on the role of the RO. 1065 5. As the RO, the user authorizes the pending request from the 1066 client instance. 1068 6. When the AS is done interacting with the user, the AS returns the 1069 user to the client instance and signals continuation. 1071 7. The client instance loads the continuation information from (2) 1072 and calls the AS to continue the request (Section 5). 1074 8. If the request has been authorized, the AS grants access to the 1075 requested direct subject information (Section 3.4) to the client 1076 instance. At this stage, the user is generally considered 1077 "logged in" to the client instance based on the identifiers and 1078 assertions provided by the AS. Note that the AS can restrict the 1079 subject information returned and it might not match what the 1080 client instance requested, see the section on subject information 1081 for details. 1083 2. Requesting Access 1085 To start a request, the client instance sends JSON [RFC8259] document 1086 with an object as its root. Each member of the request object 1087 represents a different aspect of the client instance's request. Each 1088 field is described in detail in a section below. 1090 access_token (object / array of objects) Describes the rights and 1091 properties associated with the requested access token. 1092 Section 2.1 1094 subject (object) Describes the information about the RO that the 1095 client instance is requesting to be returned directly in the 1096 response from the AS. Section 2.2 1098 client (object / string) Describes the client instance that is 1099 making this request, including the key that the client instance 1100 will use to protect this request and any continuation requests at 1101 the AS and any user-facing information about the client instance 1102 used in interactions. Section 2.3 1104 user (object / string) Identifies the end-user to the AS in a manner 1105 that the AS can verify, either directly or by interacting with the 1106 end-user to determine their status as the RO. Section 2.4 1108 interact (object) Describes the modes that the client instance has 1109 for allowing the RO to interact with the AS and modes for the 1110 client instance to receive updates when interaction is complete. 1111 Section 2.5 1113 Additional members of this request object can be defined by 1114 extensions to this protocol as described in Section 2.6 1116 A non-normative example of a grant request is below: 1118 { 1119 "access_token": { 1120 "access": [ 1121 { 1122 "type": "photo-api", 1123 "actions": [ 1124 "read", 1125 "write", 1126 "dolphin" 1127 ], 1128 "locations": [ 1129 "https://server.example.net/", 1130 "https://resource.local/other" 1131 ], 1132 "datatypes": [ 1133 "metadata", 1134 "images" 1135 ] 1136 }, 1137 "dolphin-metadata" 1138 ] 1139 }, 1140 "client": { 1141 "display": { 1142 "name": "My Client Display Name", 1143 "uri": "https://example.net/client" 1144 }, 1145 "key": { 1146 "proof": "httpsig", 1147 "jwk": { 1148 "kty": "RSA", 1149 "e": "AQAB", 1150 "kid": "xyz-1", 1151 "alg": "RS256", 1152 "n": "kOB5rR4Jv0GMeL...." 1153 } 1154 } 1155 }, 1156 "interact": { 1157 "start": ["redirect"], 1158 "finish": { 1159 "method": "redirect", 1160 "uri": "https://client.example.net/return/123455", 1161 "nonce": "LKLTI25DK82FX4T4QFZC" 1162 } 1163 }, 1164 "subject": { 1165 "formats": ["iss_sub", "opaque"], 1166 "assertions": ["id_token"] 1167 } 1168 } 1170 The request and response MUST be sent as a JSON object in the body of 1171 the HTTP POST request with Content-Type "application/json", unless 1172 otherwise specified by the signature mechanism. 1174 The authorization server MUST include the HTTP "Cache-Control" 1175 response header field [RFC7234] with a value set to "no-store". 1177 2.1. Requesting Access to Resources 1179 If the client instance is requesting one or more access tokens for 1180 the purpose of accessing an API, the client instance MUST include an 1181 "access_token" field. This field MUST be an object (for a single 1182 access token (Section 2.1.1)) or an array of these objects (for 1183 multiple access tokens (Section 2.1.2)), as described in the 1184 following sections. 1186 2.1.1. Requesting a Single Access Token 1188 To request a single access token, the client instance sends an 1189 "acccess_token" object composed of the following fields. 1191 access (array of objects/strings) Describes the rights that the 1192 client instance is requesting for one or more access tokens to be 1193 used at RS's. This field is REQUIRED. Section 8 1195 label (string) A unique name chosen by the client instance to refer 1196 to the resulting access token. The value of this field is opaque 1197 to the AS. If this field is included in the request, the AS MUST 1198 include the same label in the token response (Section 3.2). This 1199 field is REQUIRED if used as part of a multiple access token 1200 request (Section 2.1.2), and is OPTIONAL otherwise. 1202 flags (array of strings) A set of flags that indicate desired 1203 attributes or behavior to be attached to the access token by the 1204 AS. This field is OPTIONAL. 1206 The values of the "flags" field defined by this specification are as 1207 follows: 1209 "bearer" If this flag is included, the access token being requested 1210 is a bearer token. If this flag is omitted, the access token is 1211 bound to the key used by the client instance in this request, or 1212 the key's most recent rotation. Methods for presenting bound and 1213 bearer access tokens are described in Section 7.2. [[ See issue 1214 #38 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/38) 1215 ]] 1217 "split" If this flag is included, the client instance is capable of 1218 receiving a different number of tokens than specified in the token 1219 request (Section 2.1), including receiving multiple access tokens 1220 (Section 3.2.2) in response to any single token request 1221 (Section 2.1.1) or a different number of access tokens than 1222 requested in a multiple access token request (Section 2.1.2). The 1223 "label" fields of the returned additional tokens are chosen by the 1224 AS. The client instance MUST be able to tell from the token 1225 response where and how it can use each of the access tokens. [[ 1226 See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1227 issues/37) ]] 1229 Flag values MUST NOT be included more than once. 1231 Additional flags can be defined by extensions using a registry TBD 1232 (Section 11). 1234 In the following example, the client instance is requesting access to 1235 a complex resource described by a pair of access request object. 1237 "access_token": { 1238 "access": [ 1239 { 1240 "type": "photo-api", 1241 "actions": [ 1242 "read", 1243 "write", 1244 "delete" 1245 ], 1246 "locations": [ 1247 "https://server.example.net/", 1248 "https://resource.local/other" 1249 ], 1250 "datatypes": [ 1251 "metadata", 1252 "images" 1253 ] 1254 }, 1255 { 1256 "type": "walrus-access", 1257 "actions": [ 1258 "foo", 1259 "bar" 1260 ], 1261 "locations": [ 1262 "https://resource.other/" 1263 ], 1264 "datatypes": [ 1265 "data", 1266 "pictures", 1267 "walrus whiskers" 1268 ] 1269 } 1270 ], 1271 "label": "token1-23", 1272 "flags": [ "split" ] 1273 } 1275 If access is approved, the resulting access token is valid for the 1276 described resource and is bound to the client instance's key (or its 1277 most recent rotation). The token is labeled "token1-23" and could be 1278 split into multiple access tokens by the AS, if the AS chooses. The 1279 token response structure is described in Section 3.2.1. 1281 2.1.2. Requesting Multiple Access Tokens 1283 To request multiple access tokens to be returned in a single 1284 response, the client instance sends an array of objects as the value 1285 of the "access_token" parameter. Each object MUST conform to the 1286 request format for a single access token request, as specified in 1287 requesting a single access token (Section 2.1.1). Additionally, each 1288 object in the array MUST include the "label" field, and all values of 1289 these fields MUST be unique within the request. If the client 1290 instance does not include a "label" value for any entry in the array, 1291 or the values of the "label" field are not unique within the array, 1292 the AS MUST return an error. 1294 The following non-normative example shows a request for two separate 1295 access tokens, "token1" and "token2". 1297 "access_token": [ 1298 { 1299 "label": "token1", 1300 "access": [ 1301 { 1302 "type": "photo-api", 1303 "actions": [ 1304 "read", 1305 "write", 1306 "dolphin" 1307 ], 1308 "locations": [ 1309 "https://server.example.net/", 1310 "https://resource.local/other" 1311 ], 1312 "datatypes": [ 1313 "metadata", 1314 "images" 1315 ] 1316 }, 1317 "dolphin-metadata" 1318 ] 1319 }, 1320 { 1321 "label": "token2", 1322 "access": [ 1323 { 1324 "type": "walrus-access", 1325 "actions": [ 1326 "foo", 1327 "bar" 1328 ], 1329 "locations": [ 1330 "https://resource.other/" 1331 ], 1332 "datatypes": [ 1333 "data", 1334 "pictures", 1335 "walrus whiskers" 1336 ] 1337 } 1338 ], 1339 "flags": [ "bearer" ] 1340 } 1341 ] 1342 All approved access requests are returned in the multiple access 1343 token response (Section 3.2.2) structure using the values of the 1344 "label" fields in the request. 1346 2.2. Requesting Subject Information 1348 If the client instance is requesting information about the RO from 1349 the AS, it sends a "subject" field as a JSON object. This object MAY 1350 contain the following fields (or additional fields defined in a 1351 registry TBD (Section 11)). 1353 formats (array of strings) An array of subject identifier subject 1354 types requested for the RO, as defined by 1355 [I-D.ietf-secevent-subject-identifiers]. 1357 assertions (array of strings) An array of requested assertion 1358 formats. Possible values include "id_token" for an [OIDC] ID 1359 Token and "saml2" for a SAML 2 assertion. Additional assertion 1360 values are defined by a registry TBD (Section 11). [[ See issue 1361 #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) 1362 ]] 1364 "subject": { 1365 "formats": [ "iss_sub", "opaque" ], 1366 "assertions": [ "id_token", "saml2" ] 1367 } 1369 The AS can determine the RO's identity and permission for releasing 1370 this information through interaction with the RO (Section 4), AS 1371 policies, or assertions presented by the client instance 1372 (Section 2.4). If this is determined positively, the AS MAY return 1373 the RO's information in its response (Section 3.4) as requested. 1375 Subject identifier types requested by the client instance serve only 1376 to identify the RO in the context of the AS and can't be used as 1377 communication channels by the client instance, as discussed in 1378 Section 3.4. 1380 The AS SHOULD NOT re-use subject identifiers for multiple different 1381 ROs. 1383 Note: the "formats" and "assertions" request fields are independent 1384 of each other, and a returned assertion MAY omit a requested subject 1385 identifier. 1387 [[ See issue #43 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1388 issues/43) ]] 1390 2.3. Identifying the Client Instance 1392 When sending a non-continuation request to the AS, the client 1393 instance MUST identify itself by including the "client" field of the 1394 request and by signing the request as described in Section 7.3. Note 1395 that for a continuation request (Section 5), the client instance is 1396 identified by its association with the request being continued and so 1397 this field is not sent under those circumstances. 1399 When client instance information is sent by value, the "client" field 1400 of the request consists of a JSON object with the following fields. 1402 key (object / string) The public key of the client instance to be 1403 used in this request as described in Section 7.1 or a reference to 1404 a key as described in Section 7.1.1. This field is REQUIRED. 1406 class_id (string) An identifier string that the AS can use to 1407 identify the client software comprising this client instance. The 1408 contents and format of this field are up to the AS. This field is 1409 OPTIONAL. 1411 display (object) An object containing additional information that 1412 the AS MAY display to the RO during interaction, authorization, 1413 and management. This field is OPTIONAL. 1415 "client": { 1416 "key": { 1417 "proof": "httpsig", 1418 "jwk": { 1419 "kty": "RSA", 1420 "e": "AQAB", 1421 "kid": "xyz-1", 1422 "alg": "RS256", 1423 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 1424 }, 1425 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1426 }, 1427 "class_id": "web-server-1234", 1428 "display": { 1429 "name": "My Client Display Name", 1430 "uri": "https://example.net/client" 1431 } 1432 } 1434 Additional fields are defined in a registry TBD (Section 11). 1436 The client instance MUST prove possession of any presented key by the 1437 "proof" mechanism associated with the key in the request. Proof 1438 types are defined in a registry TBD (Section 11) and an initial set 1439 of methods is described in Section 7.3. 1441 Note that the AS MAY know the client instance's public key ahead of 1442 time, and the AS MAY apply different policies to the request 1443 depending on what has been registered against that key. If the same 1444 public key is sent by value on subsequent access requests, the AS 1445 SHOULD treat these requests as coming from the same client instance 1446 for purposes of identification, authentication, and policy 1447 application. If the AS does not know the client instance's public 1448 key ahead of time, the AS MAY accept or reject the request based on 1449 AS policy, attestations within the "client" request, and other 1450 mechanisms. 1452 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1453 issues/44) ]] 1455 2.3.1. Identifying the Client Instance by Reference 1457 If the client instance has an instance identifier that the AS can use 1458 to determine appropriate key information, the client instance can 1459 send this instance identifier as a direct reference value in lieu of 1460 the "client" object. The instance identifier MAY be assigned to a 1461 client instance at runtime through the Section 3.5 or MAY be obtained 1462 in another fashion, such as a static registration process at the AS. 1464 "client": "client-541-ab" 1466 When the AS receives a request with an instance identifier, the AS 1467 MUST ensure that the key used to sign the request (Section 7.3) is 1468 associated with the instance identifier. 1470 If the AS does not recognize the instance identifier, the request 1471 MUST be rejected with an error. 1473 If the client instance is identified in this manner, the registered 1474 key for the client instance MAY be a symmetric key known to the AS. 1475 The client instance MUST NOT send a symmetric key by value in the 1476 request, as doing so would expose the key directly instead of proving 1477 possession of it. 1479 2.3.2. Providing Displayable Client Instance Information 1481 If the client instance has additional information to display to the 1482 RO during any interactions at the AS, it MAY send that information in 1483 the "display" field. This field is a JSON object that declares 1484 information to present to the RO during any interactive sequences. 1486 name (string) Display name of the client software 1488 uri (string) User-facing web page of the client software 1490 logo_uri (string) Display image to represent the client software 1492 "display": { 1493 "name": "My Client Display Name", 1494 "uri": "https://example.net/client" 1495 } 1497 [[ See issue #48 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1498 issues/48) ]] 1500 Additional display fields are defined by a registry TBD (Section 11). 1502 The AS SHOULD use these values during interaction with the RO. The 1503 values are for informational purposes only and MUST NOT be taken as 1504 authentic proof of the client instance's identity or source. The AS 1505 MAY restrict display values to specific client instances, as 1506 identified by their keys in Section 2.3. 1508 2.3.3. Authenticating the Client Instance 1510 If the presented key is known to the AS and is associated with a 1511 single instance of the client software, the process of presenting a 1512 key and proving possession of that key is sufficient to authenticate 1513 the client instance to the AS. The AS MAY associate policies with 1514 the client instance identified by this key, such as limiting which 1515 resources can be requested and which interaction methods can be used. 1516 For example, only specific client instances with certain known keys 1517 might be trusted with access tokens without the AS interacting 1518 directly with the RO as in Appendix D.3. 1520 The presentation of a key allows the AS to strongly associate 1521 multiple successive requests from the same client instance with each 1522 other. This is true when the AS knows the key ahead of time and can 1523 use the key to authenticate the client instance, but also if the key 1524 is ephemeral and created just for this series of requests. As such 1525 the AS MAY allow for client instances to make requests with unknown 1526 keys. This pattern allows for ephemeral client instances, such as 1527 single-page applications, and client software with many individual 1528 long-lived instances, such as mobile applications, to generate key 1529 pairs per instance and use the keys within the protocol without 1530 having to go through a separate registration step. The AS MAY limit 1531 which capabilities are made available to client instances with 1532 unknown keys. For example, the AS could have a policy saying that 1533 only previously-registered client instances can request particular 1534 resources, or that all client instances with unknown keys have to be 1535 interactively approved by an RO. 1537 2.4. Identifying the User 1539 If the client instance knows the identity of the end-user through one 1540 or more identifiers or assertions, the client instance MAY send that 1541 information to the AS in the "user" field. The client instance MAY 1542 pass this information by value or by reference. 1544 sub_ids (array of objects) An array of subject identifiers for the 1545 end-user, as defined by [I-D.ietf-secevent-subject-identifiers]. 1547 assertions (object) An object containing assertions as values keyed 1548 on the assertion type defined by a registry TBD (Section 11). 1549 Possible keys include "id_token" for an [OIDC] ID Token and 1550 "saml2" for a SAML 2 assertion. Additional assertion values are 1551 defined by a registry TBD (Section 11). [[ See issue #41 1552 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/41) ]] 1554 "user": { 1555 "sub_ids": [ { 1556 "format": "opaque", 1557 "id": "J2G8G8O4AZ" 1558 } ], 1559 "assertions": { 1560 "id_token": "eyj..." 1561 } 1562 } 1564 Subject identifiers are hints to the AS in determining the RO and 1565 MUST NOT be taken as declarative statements that a particular RO is 1566 present at the client instance and acting as the end-user. 1567 Assertions SHOULD be validated by the AS. [[ See issue #49 1568 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1570 If the identified end-user does not match the RO present at the AS 1571 during an interaction step, the AS SHOULD reject the request with an 1572 error. 1574 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1575 issues/50) ]] 1577 If the AS trusts the client instance to present verifiable 1578 assertions, the AS MAY decide, based on its policy, to skip 1579 interaction with the RO, even if the client instance provides one or 1580 more interaction modes in its request. 1582 2.4.1. Identifying the User by Reference 1584 The AS can identify the current end-user to the client instance with 1585 a reference which can be used by the client instance to refer to the 1586 end-user across multiple requests. If the client instance has a 1587 reference for the end-user at this AS, the client instance MAY pass 1588 that reference as a string. The format of this string is opaque to 1589 the client instance. 1591 "user": "XUT2MFM1XBIKJKSDU8QM" 1593 One means of dynamically obtaining such a user reference is from the 1594 AS returning an "opaque" subject identifier as described in 1595 Section 3.4. Other means of configuring a client instance with a 1596 user identifier are out of scope of this specification. 1598 User reference identifiers are not intended to be human-readable user 1599 identifiers or structured assertions. For the client instance to 1600 send either of these, use the full user request object (Section 2.4) 1601 instead. 1603 If the AS does not recognize the user reference, it MUST return an 1604 error. 1606 2.5. Interacting with the User 1608 Often, the AS will require interaction with the RO (Section 4) in 1609 order to approve a requested delegation to the client instance for 1610 both access to resources and direct subject information. Many times 1611 the end-user using the client instance is the same person as the RO, 1612 and the client instance can directly drive interaction with the end 1613 user by facilitating the process through means such as redirection to 1614 a URL or launching an application. Other times, the client instance 1615 can provide information to start the RO's interaction on a secondary 1616 device, or the client instance will wait for the RO to approve the 1617 request asynchronously. The client instance could also be signaled 1618 that interaction has concluded through a callback mechanism. 1620 The client instance declares the parameters for interaction methods 1621 that it can support using the "interact" field. 1623 The "interact" field is a JSON object with three keys whose values 1624 declare how the client can initiate and complete the request, as well 1625 as provide hints to the AS about user preferences such as locale. A 1626 client instance MUST NOT declare an interaction mode it does not 1627 support. The client instance MAY send multiple modes in the same 1628 request. There is no preference order specified in this request. An 1629 AS MAY respond to any, all, or none of the presented interaction 1630 modes (Section 3.3) in a request, depending on its capabilities and 1631 what is allowed to fulfill the request. 1633 start (list of strings/objects) Indicates how the client instance 1634 can start an interaction. 1636 finish (object) Indicates how the client instance can receive an 1637 indication that interaction has finished at the AS. 1639 hints (object) Provides additional information to inform the 1640 interaction process at the AS. 1642 The "interact" field MUST contain the "start" key, and MAY contain 1643 the "finish" and "hints" keys. The value of each key is an array 1644 which contains strings or JSON objects as defined below. 1646 In this non-normative example, the client instance is indicating that 1647 it can redirect (Section 2.5.1.1) the end-user to an arbitrary URL 1648 and can receive a redirect (Section 2.5.2.1) through a browser 1649 request. 1651 "interact": { 1652 "start": ["redirect"], 1653 "finish": { 1654 "method": "redirect", 1655 "uri": "https://client.example.net/return/123455", 1656 "nonce": "LKLTI25DK82FX4T4QFZC" 1657 } 1658 } 1660 In this non-normative example, the client instance is indicating that 1661 it can display a user code (Section 2.5.1.3) and direct the end-user 1662 to an arbitrary URL (Section 2.5.1.1) on a secondary device, but it 1663 cannot accept a redirect or push callback. 1665 "interact": { 1666 "start": ["redirect", "user_code"] 1667 } 1668 If the client instance does not provide a suitable interaction 1669 mechanism, the AS cannot contact the RO asynchronously, and the AS 1670 determines that interaction is required, then the AS SHOULD return an 1671 error since the client instance will be unable to complete the 1672 request without authorization. 1674 The AS SHOULD apply suitable timeouts to any interaction mechanisms 1675 provided, including user codes and redirection URLs. The client 1676 instance SHOULD apply suitable timeouts to any callback URLs. 1678 2.5.1. Start Mode Definitions 1680 This specification defines the following interaction start modes as 1681 an array of string values under the "start" key: 1683 "redirect" Indicates that the client instance can direct the end- 1684 user to an arbitrary URL for interaction. Section 2.5.1.1 1686 "app" Indicates that the client instance can launch an application 1687 on the end-user's device for interaction. Section 2.5.1.2 1689 "user_code" Indicates that the client instance can communicate a 1690 human-readable short code to the end-user for use with a stable 1691 URL. Section 2.5.1.3 1693 2.5.1.1. Redirect to an Arbitrary URL 1695 If the client instance is capable of directing the end-user to a URL 1696 defined by the AS at runtime, the client instance indicates this by 1697 sending the "redirect" field with the boolean value "true". The 1698 means by which the client instance will activate this URL is out of 1699 scope of this specification, but common methods include an HTTP 1700 redirect, launching a browser on the end-user's device, providing a 1701 scannable image encoding, and printing out a URL to an interactive 1702 console. While this URL is generally hosted at the AS, the client 1703 instance can make no assumptions about its contents, composition, or 1704 relationship to the AS grant URL. 1706 "interact": { 1707 "start": ["redirect"] 1708 } 1710 If this interaction mode is supported for this client instance and 1711 request, the AS returns a redirect interaction response 1712 Section 3.3.1. The client instance manages this interaction method 1713 as described in Section 4.1.1. 1715 2.5.1.2. Open an Application-specific URL 1717 If the client instance can open a URL associated with an application 1718 on the end-user's device, the client instance indicates this by 1719 sending the "app" field with boolean value "true". The means by 1720 which the client instance determines the application to open with 1721 this URL are out of scope of this specification. 1723 "interact": { 1724 "start": ["app"] 1725 } 1727 If this interaction mode is supported for this client instance and 1728 request, the AS returns an app interaction response with an app URL 1729 payload Section 3.3.2. The client instance manages this interaction 1730 method as described in Section 4.1.3. 1732 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1733 issues/54) ]] 1735 2.5.1.3. Display a Short User Code 1737 If the client instance is capable of displaying or otherwise 1738 communicating a short, human-entered code to the RO, the client 1739 instance indicates this by sending the "user_code" field with the 1740 boolean value "true". This code is to be entered at a static URL 1741 that does not change at runtime. While this URL is generally hosted 1742 at the AS, the client instance can make no assumptions about its 1743 contents, composition, or relationship to the AS grant URL. 1745 "interact": { 1746 "start": ["user_code"] 1747 } 1749 If this interaction mode is supported for this client instance and 1750 request, the AS returns a user code and interaction URL as specified 1751 in Section 3.3.3. The client instances manages this interaction 1752 method as described in Section 4.1.2 1754 2.5.2. Finish Interaction Modes 1756 If the client instance is capable of receiving a message from the AS 1757 indicating that the RO has completed their interaction, the client 1758 instance indicates this by sending the following members of an object 1759 under the "finish" key. 1761 method (string) REQUIRED. The callback method that the AS will use 1762 to contact the client instance. This specification defines the 1763 following interaction completion methods, with other values 1764 defined by a registry TBD (Section 11): 1766 "redirect" Indicates that the client instance can receive a 1767 redirect from the end-user's device after interaction with the 1768 RO has concluded. Section 2.5.2.1 1770 "push" Indicates that the client instance can receive an HTTP 1771 POST request from the AS after interaction with the RO has 1772 concluded. Section 2.5.2.2 1774 uri (string) REQUIRED. Indicates the URI that the AS will either 1775 send the RO to after interaction or send an HTTP POST request. 1776 This URI MAY be unique per request and MUST be hosted by or 1777 accessible by the client instance. This URI MUST NOT contain any 1778 fragment component. This URI MUST be protected by HTTPS, be 1779 hosted on a server local to the RO's browser ("localhost"), or use 1780 an application-specific URI scheme. If the client instance needs 1781 any state information to tie to the front channel interaction 1782 response, it MUST use a unique callback URI to link to that 1783 ongoing state. The allowable URIs and URI patterns MAY be 1784 restricted by the AS based on the client instance's presented key 1785 information. The callback URI SHOULD be presented to the RO 1786 during the interaction phase before redirect. 1788 nonce (string) REQUIRED. Unique value to be used in the calculation 1789 of the "hash" query parameter sent to the callback URL, must be 1790 sufficiently random to be unguessable by an attacker. MUST be 1791 generated by the client instance as a unique value for this 1792 request. 1794 hash_method (string) OPTIONAL. The hash calculation mechanism to be 1795 used for the callback hash in Section 4.2.3. Can be one of "sha3" 1796 or "sha2". If absent, the default value is "sha3". [[ See issue 1797 #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) 1798 ]] 1800 If this interaction mode is supported for this client instance and 1801 request, the AS returns a nonce for use in validating the callback 1802 response (Section 3.3.4). Requests to the callback URI MUST be 1803 processed as described in Section 4.2, and the AS MUST require 1804 presentation of an interaction callback reference as described in 1805 Section 5.1. 1807 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1808 issues/58) ]] 1810 [[ See issue #59 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1811 issues/59) ]] 1813 2.5.2.1. Receive an HTTP Callback Through the Browser 1815 A finish "method" value of "redirect" indicates that the client 1816 instance will expect a request from the RO's browser using the HTTP 1817 method GET as described in Section 4.2.1. 1819 "interact": { 1820 "finish": { 1821 "method": "redirect", 1822 "uri": "https://client.example.net/return/123455", 1823 "nonce": "LKLTI25DK82FX4T4QFZC" 1824 } 1825 } 1827 Requests to the callback URI MUST be processed by the client instance 1828 as described in Section 4.2.1. 1830 Since the incoming request to the callback URL is from the RO's 1831 browser, this method is usually used when the RO and end-user are the 1832 same entity. As such, the client instance MUST ensure the end-user 1833 is present on the request to prevent substitution attacks. 1835 2.5.2.2. Receive an HTTP Direct Callback 1837 A finish "method" value of "push" indicates that the client instance 1838 will expect a request from the AS directly using the HTTP method POST 1839 as described in Section 4.2.2. 1841 "interact": { 1842 "finish": { 1843 "method": "push", 1844 "uri": "https://client.example.net/return/123455", 1845 "nonce": "LKLTI25DK82FX4T4QFZC" 1846 } 1847 } 1849 Requests to the callback URI MUST be processed by the client instance 1850 as described in Section 4.2.2. 1852 Since the incoming request to the callback URL is from the AS and not 1853 from the RO's browser, the client instance MUST NOT require the end- 1854 user to be present on the incoming HTTP request. 1856 [[ See issue #60 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1857 issues/60) ]] 1859 2.5.3. Hints 1861 The "hints" key is an object describing one or more suggestions from 1862 the client instance that the AS can use to help drive user 1863 interaction. 1865 This specification defines the following properties under the "hints" 1866 key: 1868 ui_locales (array of strings) Indicates the end-user's preferred 1869 locales that the AS can use during interaction, particularly 1870 before the RO has authenticated. Section 2.5.3.1 1872 The following sections detail requests for interaction modes. 1873 Additional interaction modes are defined in a registry TBD 1874 (Section 11). 1876 2.5.3.1. Indicate Desired Interaction Locales 1878 If the client instance knows the end-user's locale and language 1879 preferences, the client instance can send this information to the AS 1880 using the "ui_locales" field with an array of locale strings as 1881 defined by [RFC5646]. 1883 "interact": { 1884 "hints": { 1885 "ui_locales": ["en-US", "fr-CA"] 1886 } 1887 } 1889 If possible, the AS SHOULD use one of the locales in the array, with 1890 preference to the first item in the array supported by the AS. If 1891 none of the given locales are supported, the AS MAY use a default 1892 locale. 1894 2.5.4. Extending Interaction Modes 1896 Additional interaction start modes, finish modes, and hints are 1897 defined in a registry TBD (Section 11). 1899 2.6. Extending The Grant Request 1901 The request object MAY be extended by registering new items in a 1902 registry TBD (Section 11). Extensions SHOULD be orthogonal to other 1903 parameters. Extensions MUST document any aspects where the extension 1904 item affects or influences the values or behavior of other request 1905 and response objects. 1907 3. Grant Response 1909 In response to a client instance's request, the AS responds with a 1910 JSON object as the HTTP entity body. Each possible field is detailed 1911 in the sections below 1913 continue (object) Indicates that the client instance can continue 1914 the request by making one or more continuation requests. 1915 Section 3.1 1917 access_token (object / array of objects) A single access token or 1918 set of access tokens that the client instance can use to call the 1919 RS on behalf of the RO. Section 3.2.1 1921 interact (object) Indicates that interaction through some set of 1922 defined mechanisms needs to take place. Section 3.3 1924 subject (object) Claims about the RO as known and declared by the 1925 AS, as described in Section 3.4. 1927 instance_id (string) An identifier this client instance can use to 1928 identify itself when making future requests. Section 3.5 1930 error (object) An error code indicating that something has gone 1931 wrong. Section 3.6 1933 In this example, the AS is returning an interaction URL 1934 (Section 3.3.1), a callback nonce (Section 3.3.4), and a continuation 1935 response (Section 3.1). 1937 NOTE: '\' line wrapping per RFC 8792 1939 { 1940 "interact": { 1941 "redirect": "https://server.example.com/interact/4CF492ML\ 1942 VMSW9MKMXKHQ", 1943 "finish": "MBDOFXG4Y5CVJCX821LH" 1944 }, 1945 "continue": { 1946 "access_token": { 1947 "value": "80UPRY5NM33OMUKMKSKU", 1948 }, 1949 "uri": "https://server.example.com/tx" 1950 } 1951 } 1952 In this example, the AS is returning a bearer access token 1953 (Section 3.2.1) with a management URL and a subject identifier 1954 (Section 3.4) in the form of an opaque identifier. 1956 NOTE: '\' line wrapping per RFC 8792 1958 { 1959 "access_token": { 1960 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 1961 "flags": ["bearer"], 1962 "manage": "https://server.example.com/token/PRY5NM33O\ 1963 M4TB8N6BW7OZB8CDFONP219RP1L", 1964 }, 1965 "subject": { 1966 "sub_ids": [ { 1967 "format": "opaque", 1968 "id": "J2G8G8O4AZ" 1969 } ] 1970 } 1971 } 1973 In this example, the AS is returning set of subject identifiers 1974 (Section 3.4), simultaneously as an opaque identifier, an email 1975 address, and a decentralized identifier (DID). 1977 { 1978 "subject": { 1979 "sub_ids": [ { 1980 "subject_type": "opaque", 1981 "id": "J2G8G8O4AZ" 1982 }, { 1983 "format": "email", 1984 "email": "user@example.com" 1985 }, { 1986 "format": "did", 1987 "url": "did:example:123456" 1988 } ] 1989 } 1990 } 1992 3.1. Request Continuation 1994 If the AS determines that the request can be continued with 1995 additional requests, it responds with the "continue" field. This 1996 field contains a JSON object with the following properties. 1998 uri (string) REQUIRED. The URI at which the client instance can 1999 make continuation requests. This URI MAY vary per request, or MAY 2000 be stable at the AS if the AS includes an access token. The 2001 client instance MUST use this value exactly as given when making a 2002 continuation request (Section 5). 2004 wait (integer) RECOMMENDED. The amount of time in integer seconds 2005 the client instance SHOULD wait after receiving this continuation 2006 handle and calling the URI. 2008 access_token (object) REQUIRED. A unique access token for 2009 continuing the request, in the format specified in Section 3.2.1. 2010 This access token MUST be bound to the client instance's key used 2011 in the request and MUST NOT be a "bearer" token. As a 2012 consequence, the "flags" array of this access token MUST NOT 2013 contain the string "bearer" and the "key" field MUST be omitted. 2014 This access token MUST NOT be usable at resources outside of the 2015 AS. The client instance MUST present the access token in all 2016 requests to the continuation URI as described in Section 7.2. [[ 2017 See issue #66 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2018 issues/66) ]] 2020 { 2021 "continue": { 2022 "access_token": { 2023 "value": "80UPRY5NM33OMUKMKSKU" 2024 }, 2025 "uri": "https://server.example.com/continue", 2026 "wait": 60 2027 } 2028 } 2030 The client instance can use the values of this field to continue the 2031 request as described in Section 5. Note that the client instance 2032 MUST sign all continuation requests with its key as described in 2033 Section 7.3 and MUST present the access token in its continuation 2034 request. 2036 This field SHOULD be returned when interaction is expected, to allow 2037 the client instance to follow up after interaction has been 2038 concluded. 2040 3.2. Access Tokens 2042 If the AS has successfully granted one or more access tokens to the 2043 client instance, the AS responds with the "access_token" field. This 2044 field contains either a single access token as described in 2045 Section 3.2.1 or an array of access tokens as described in 2046 Section 3.2.2. 2048 The client instance uses any access tokens in this response to call 2049 the RS as described in Section 7.2. 2051 3.2.1. Single Access Token 2053 If the client instance has requested a single access token and the AS 2054 has granted that access token, the AS responds with the 2055 "access_token" field. The value of this field is an object with the 2056 following properties. 2058 value (string) REQUIRED. The value of the access token as a string. 2059 The value is opaque to the client instance. The value SHOULD be 2060 limited to ASCII characters to facilitate transmission over HTTP 2061 headers within other protocols without requiring additional 2062 encoding. 2064 label (string) REQUIRED for multiple access tokens, OPTIONAL for 2065 single access token. The value of the "label" the client instance 2066 provided in the associated token request (Section 2.1), if 2067 present. If the token has been split by the AS, the value of the 2068 "label" field is chosen by the AS and the "split" field is 2069 included and set to "true". 2071 manage (string) OPTIONAL. The management URI for this access token. 2072 If provided, the client instance MAY manage its access token as 2073 described in Section 6. This management URI is a function of the 2074 AS and is separate from the RS the client instance is requesting 2075 access to. This URI MUST NOT include the access token value and 2076 SHOULD be different for each access token issued in a request. 2078 access (array of objects/strings) RECOMMENDED. A description of the 2079 rights associated with this access token, as defined in Section 8. 2080 If included, this MUST reflect the rights associated with the 2081 issued access token. These rights MAY vary from what was 2082 requested by the client instance. 2084 expires_in (integer) OPTIONAL. The number of seconds in which the 2085 access will expire. The client instance MUST NOT use the access 2086 token past this time. An RS MUST NOT accept an access token past 2087 this time. Note that the access token MAY be revoked by the AS or 2088 RS at any point prior to its expiration. 2090 key (object / string) OPTIONAL. The key that the token is bound to, 2091 if different from the client instance's presented key. The key 2092 MUST be an object or string in a format described in Section 7.1. 2093 The client instance MUST be able to dereference or process the key 2094 information in order to be able to sign the request. 2096 flags (array of strings) OPTIONAL. A set of flags that represent 2097 attributes or behaviors of the access token issued by the AS. 2099 The values of the "flags" field defined by this specification are as 2100 follows: 2102 "bearer" This flag indicates whether the token is bound to the 2103 client instance's key. If the "bearer" flag is present, the 2104 access token is a bearer token, and the "key" field in this 2105 response MUST be omitted. If the "bearer" flag is omitted and the 2106 "key" field in this response is omitted, the token is bound the 2107 key used by the client instance (Section 2.3) in its request for 2108 access. If the "bearer" flag is omitted, and the "key" field is 2109 present, the token is bound to the key and proofing mechanism 2110 indicated in the "key" field. 2112 "durable" OPTIONAL. Flag indicating a hint of AS behavior on token 2113 rotation. If this flag is present, then the client instance can 2114 expect a previously-issued access token to continue to work after 2115 it has been rotated (Section 6.1) or the underlying grant request 2116 has been modified (Section 5.3), resulting in the issuance of new 2117 access tokens. If this flag is omitted, the client instance can 2118 anticipate a given access token will stop working after token 2119 rotation or grant request modification. Note that a token flagged 2120 as "durable" can still expire or be revoked through any normal 2121 means. 2123 "split" OPTIONAL. Flag indicating that this token was generated by 2124 issuing multiple access tokens in response to one of the client 2125 instance's token request (Section 2.1) objects. This behavior 2126 MUST NOT be used unless the client instance has specifically 2127 requested it by use of the "split" flag. 2129 Flag values MUST NOT be included more than once. 2131 Additional flags can be defined by extensions using a registry TBD 2132 (Section 11). 2134 The following non-normative example shows a single access token bound 2135 to the client instance's key used in the initial request, with a 2136 management URL, and that has access to three described resources (one 2137 using an object and two described by reference strings). 2139 NOTE: '\' line wrapping per RFC 8792 2141 "access_token": { 2142 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2143 "manage": "https://server.example.com/token/PRY5NM33O\ 2144 M4TB8N6BW7OZB8CDFONP219RP1L", 2145 "access": [ 2146 { 2147 "type": "photo-api", 2148 "actions": [ 2149 "read", 2150 "write", 2151 "dolphin" 2152 ], 2153 "locations": [ 2154 "https://server.example.net/", 2155 "https://resource.local/other" 2156 ], 2157 "datatypes": [ 2158 "metadata", 2159 "images" 2160 ] 2161 }, 2162 "read", "dolphin-metadata" 2163 ] 2164 } 2166 The following non-normative example shows a single bearer access 2167 token with access to two described resources. 2169 "access_token": { 2170 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2171 "flags": ["bearer"], 2172 "access": [ 2173 "finance", "medical" 2174 ] 2175 } 2177 If the client instance requested a single access token 2178 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2179 token structure unless the client instance sends the "split" flag as 2180 described in Section 2.1.1. 2182 If the AS has split the access token response, the response MUST 2183 include the "split" flag. 2185 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2186 issues/69) ]] 2188 3.2.2. Multiple Access Tokens 2190 If the client instance has requested multiple access tokens and the 2191 AS has granted at least one of them, the AS responds with the 2192 "access_token" field. The value of this field is a JSON array, the 2193 members of which are distinct access tokens as described in 2194 Section 3.2.1. Each object MUST have a unique "label" field, 2195 corresponding to the token labels chosen by the client instance in 2196 the multiple access token request (Section 2.1.2). 2198 In this non-normative example, two tokens are issued under the names 2199 "token1" and "token2", and only the first token has a management URL 2200 associated with it. 2202 NOTE: '\' line wrapping per RFC 8792 2204 "access_token": [ 2205 { 2206 "label": "token1", 2207 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2208 "manage": "https://server.example.com/token/PRY5NM33O\ 2209 M4TB8N6BW7OZB8CDFONP219RP1L", 2210 "access": [ "finance" ] 2211 }, 2212 { 2213 "label": "token2", 2214 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2215 "access": [ "medical" ] 2216 } 2217 } 2219 Each access token corresponds to one of the objects in the 2220 "access_token" array of the client instance's request 2221 (Section 2.1.2). 2223 The multiple access token response MUST be used when multiple access 2224 tokens are requested, even if only one access token is issued as a 2225 result of the request. The AS MAY refuse to issue one or more of the 2226 requested access tokens, for any reason. In such cases the refused 2227 token is omitted from the response and all of the other issued access 2228 tokens are included in the response the requested names appropriate 2229 names. 2231 If the client instance requested multiple access tokens 2232 (Section 2.1.2), the AS MUST NOT respond with a single access token 2233 structure, even if only a single access token is granted. In such 2234 cases, the AS responds with a multiple access token structure 2235 containing one access token. 2237 If the AS has split the access token response, the response MUST 2238 include the "split" flag in the "flags" array. 2240 "access_token": [ 2241 { 2242 "label": "split-1", 2243 "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", 2244 "flags": ["split"], 2245 "manage": "https://server.example.com/token/PRY5NM33O\ 2246 M4TB8N6BW7OZB8CDFONP219RP1L", 2247 "access": [ "fruits" ] 2248 }, 2249 { 2250 "label": "split-2", 2251 "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", 2252 "flags": ["split"], 2253 "access": [ "vegetables" ] 2254 } 2255 } 2257 Each access token MAY be bound to different keys with different 2258 proofing mechanisms. 2260 If token management (Section 6) is allowed, each access token SHOULD 2261 have different "manage" URIs. 2263 [[ See issue #70 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2264 issues/70) ]] 2266 3.3. Interaction Modes 2268 If the client instance has indicated a capability to interact with 2269 the RO in its request (Section 2.5), and the AS has determined that 2270 interaction is both supported and necessary, the AS responds to the 2271 client instance with any of the following values in the "interact" 2272 field of the response. There is no preference order for interaction 2273 modes in the response, and it is up to the client instance to 2274 determine which ones to use. All supported interaction methods are 2275 included in the same "interact" object. 2277 redirect (string) Redirect to an arbitrary URL. Section 3.3.1 2279 app (string) Launch of an application URL. Section 3.3.2 2281 finish (string) A nonce used by the client instance to verify the 2282 callback after interaction is completed. Section 3.3.4 2284 user_code (object) Display a short user code. Section 3.3.3 2285 Additional interaction mode responses can be defined in a registry 2286 TBD (Section 11). 2288 The AS MUST NOT respond with any interaction mode that the client 2289 instance did not indicate in its request. The AS MUST NOT respond 2290 with any interaction mode that the AS does not support. Since 2291 interaction responses include secret or unique information, the AS 2292 SHOULD respond to each interaction mode only once in an ongoing 2293 request, particularly if the client instance modifies its request 2294 (Section 5.3). 2296 3.3.1. Redirection to an arbitrary URL 2298 If the client instance indicates that it can redirect to an arbitrary 2299 URL (Section 2.5.1.1) and the AS supports this mode for the client 2300 instance's request, the AS responds with the "redirect" field, which 2301 is a string containing the URL to direct the end-user to. This URL 2302 MUST be unique for the request and MUST NOT contain any security- 2303 sensitive information such as user identifiers or access tokens. 2305 "interact": { 2306 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2307 } 2309 The URL returned is a function of the AS, but the URL itself MAY be 2310 completely distinct from the URL the client instance uses to request 2311 access (Section 2), allowing an AS to separate its user-interactive 2312 functionality from its back-end security functionality. If the AS 2313 does not directly host the functionality accessed through the given 2314 URL, then the means for the interaction functionality to communicate 2315 with the rest of the AS are out of scope for this specification. 2317 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2318 issues/72) ]] 2320 The client instance sends the end-user to the URL to interact with 2321 the AS. The client instance MUST NOT alter the URL in any way. The 2322 means for the client instance to send the end-user to this URL is out 2323 of scope of this specification, but common methods include an HTTP 2324 redirect, launching the system browser, displaying a scannable code, 2325 or printing out the URL in an interactive console. See details of 2326 the interaction in Section 4.1.1. 2328 3.3.2. Launch of an application URL 2330 If the client instance indicates that it can launch an application 2331 URL (Section 2.5.1.2) and the AS supports this mode for the client 2332 instance's request, the AS responds with the "app" field, which is a 2333 string containing the URL for the client instance to launch. This 2334 URL MUST be unique for the request and MUST NOT contain any security- 2335 sensitive information such as user identifiers or access tokens. 2337 "interact": { 2338 "app": "https://app.example.com/launch?tx=4CF492MLV" 2339 } 2341 The means for the launched application to communicate with the AS are 2342 out of scope for this specification. 2344 The client instance launches the URL as appropriate on its platform, 2345 and the means for the client instance to launch this URL is out of 2346 scope of this specification. The client instance MUST NOT alter the 2347 URL in any way. The client instance MAY attempt to detect if an 2348 installed application will service the URL being sent before 2349 attempting to launch the application URL. See details of the 2350 interaction in Section 4.1.3. 2352 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2353 issues/71) ]] 2355 3.3.3. Display of a Short User Code 2357 If the client instance indicates that it can display a short 2358 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2359 for the client instance's request, the AS responds with a "user_code" 2360 field. This field is an object that contains the following members. 2362 code (string) REQUIRED. A unique short code that the user can type 2363 into an authorization server. This string MUST be case- 2364 insensitive, MUST consist of only easily typeable characters (such 2365 as letters or numbers). The time in which this code will be 2366 accepted SHOULD be short lived, such as several minutes. It is 2367 RECOMMENDED that this code be no more than eight characters in 2368 length. 2370 url (string) RECOMMENDED. The interaction URL that the client 2371 instance will direct the RO to. This URL MUST be stable such that 2372 client instances can be statically configured with it. 2374 "interact": { 2375 "user_code": { 2376 "code": "A1BC-3DFF", 2377 "url": "https://srv.ex/device" 2378 } 2379 } 2381 The client instance MUST communicate the "code" to the end-user in 2382 some fashion, such as displaying it on a screen or reading it out 2383 audibly. 2385 The client instance SHOULD also communicate the URL if possible to 2386 facilitate user interaction, but since the URL should be stable, the 2387 client instance should be able to safely decide to not display this 2388 value. As this interaction mode is designed to facilitate 2389 interaction via a secondary device, it is not expected that the 2390 client instance redirect the end-user to the URL given here at 2391 runtime. Consequently, the URL needs to be stable enough that a 2392 client instance could be statically configured with it, perhaps 2393 referring the end-user to the URL via documentation instead of 2394 through an interactive means. If the client instance is capable of 2395 communicating an arbitrary URL to the end-user, such as through a 2396 scannable code, the client instance can use the "redirect" 2397 (Section 2.5.1.1) mode for this purpose instead of or in addition to 2398 the user code mode. 2400 The URL returned is a function of the AS, but the URL itself MAY be 2401 completely distinct from the URL the client instance uses to request 2402 access (Section 2), allowing an AS to separate its user-interactive 2403 functionality from its back-end security functionality. If the AS 2404 does not directly host the functionality accessed through the given 2405 URL, then the means for the interaction functionality to communicate 2406 with the rest of the AS are out of scope for this specification. 2408 See details of the interaction in Section 4.1.2. 2410 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2411 issues/72) ]] 2413 3.3.4. Interaction Finish 2415 If the client instance indicates that it can receive a 2416 post-interaction redirect or push at a URL (Section 2.5.2) and the AS 2417 supports this mode for the client instance's request, the AS responds 2418 with a "finish" field containing a nonce that the client instance 2419 will use in validating the callback as defined in Section 4.2. 2421 "interact": { 2422 "finish": "MBDOFXG4Y5CVJCX821LH" 2423 } 2425 When the interaction is completed, the interaction component MUST 2426 contact the client instance using either a redirect or launch of the 2427 RO's browser or through an HTTP POST to the client instance's 2428 callback URL using the method indicated in the interaction request 2429 (Section 2.5.2) as described in Section 4.2. 2431 If the AS returns a nonce, the client instance MUST NOT continue a 2432 grant request before it receives the associated interaction reference 2433 on the callback URI. See details in Section 4.2. 2435 3.3.5. Extending Interaction Mode Responses 2437 Extensions to this specification can define new interaction mode 2438 responses in a registry TBD (Section 11). Extensions MUST document 2439 the corresponding interaction request. 2441 3.4. Returning Subject Information 2443 If information about the RO is requested and the AS grants the client 2444 instance access to that data, the AS returns the approved information 2445 in the "subject" response field. The AS MUST return the "subject" 2446 field only in cases where the AS is sure that the RO and the end-user 2447 are the same party. This can be accomplished through some forms of 2448 interaction with the RO (Section 4). 2450 This field is an object with the following OPTIONAL properties. 2452 sub_ids (array of objects) An array of subject identifiers for the 2453 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2455 assertions (object) An object containing assertions as values keyed 2456 on the assertion type defined by a registry TBD (Section 11). [[ 2457 See issue #41 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2458 issues/41) ]] 2460 updated_at (string) Timestamp as an ISO8610 date string, indicating 2461 when the identified account was last updated. The client instance 2462 MAY use this value to determine if it needs to request updated 2463 profile information through an identity API. The definition of 2464 such an identity API is out of scope for this specification. 2466 "subject": { 2467 "sub_ids": [ { 2468 "format": "opaque", 2469 "id": "XUT2MFM1XBIKJKSDU8QM" 2470 } ], 2471 "assertions": { 2472 "id_token": "eyj..." 2473 } 2474 } 2476 Subject identifiers returned by the AS SHOULD uniquely identify the 2477 RO at the AS. Some forms of subject identifier are opaque to the 2478 client instance (such as the subject of an issuer and subject pair), 2479 while others forms (such as email address and phone number) are 2480 intended to allow the client instance to correlate the identifier 2481 with other account information at the client instance. The AS MUST 2482 ensure that the returned subject identifiers only apply to the 2483 authenticated end user. The client instance MUST NOT request or use 2484 any returned subject identifiers for communication purposes (see 2485 Section 2.2). That is, a subject identifier returned in the format 2486 of an email address or a phone number only identifies the RO to the 2487 AS and does not indicate that the AS has validated that the 2488 represented email address or phone number in the identifier is 2489 suitable for communication with the current user. To get such 2490 information, the client instance MUST use an identity protocol to 2491 request and receive additional identity claims. The details of an 2492 identity protocol and associated schema are outside the scope of this 2493 specification. 2495 Extensions to this specification MAY define additional response 2496 properties in a registry TBD (Section 11). 2498 3.5. Returning Dynamically-bound Reference Handles 2500 Many parts of the client instance's request can be passed as either a 2501 value or a reference. The use of a reference in place of a value 2502 allows for a client instance to optimize requests to the AS. 2504 Some references, such as for the client instance's identity 2505 (Section 2.3.1) or the requested resources (Section 8.1), can be 2506 managed statically through an admin console or developer portal 2507 provided by the AS or RS. The developer of the client software can 2508 include these values in their code for a more efficient and compact 2509 request. 2511 If desired, the AS MAY also generate and return some of these 2512 references dynamically to the client instance in its response to 2513 facilitate multiple interactions with the same software. The client 2514 instance SHOULD use these references in future requests in lieu of 2515 sending the associated data value. These handles are intended to be 2516 used on future requests. 2518 Dynamically generated handles are string values that MUST be 2519 protected by the client instance as secrets. Handle values MUST be 2520 unguessable and MUST NOT contain any sensitive information. Handle 2521 values are opaque to the client instance. 2523 All dynamically generated handles are returned as fields in the root 2524 JSON object of the response. This specification defines the 2525 following dynamic handle return, additional handles can be defined in 2526 a registry TBD (Section 11). 2528 instance_id (string) A string value used to represent the 2529 information in the "client" object that the client instance can 2530 use in a future request, as described in Section 2.3.1. 2532 This non-normative example shows one handle along side an issued 2533 access token. 2535 { 2536 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2537 "access_token": { 2538 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 2539 } 2540 } 2542 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2543 issues/77) ]] 2545 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2546 issues/78) ]] 2548 3.6. Error Response 2550 If the AS determines that the request cannot be issued for any 2551 reason, it responds to the client instance with an error message. 2553 error (string) The error code. 2555 { 2557 "error": "user_denied" 2559 } 2560 The error code is one of the following, with additional values 2561 available in a registry TBD (Section 11): 2563 user_denied The RO denied the request. 2565 too_fast The client instance did not respect the timeout in the wait 2566 response. 2568 unknown_request The request referenced an unknown ongoing access 2569 request. 2571 [[ See issue #79 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2572 issues/79) ]] 2574 3.7. Extending the Response 2576 Extensions to this specification MAY define additional fields for the 2577 grant response in a registry TBD (Section 11). 2579 4. Determining Authorization and Consent 2581 When the client instance makes its Section 2 to the AS for delegated 2582 access, it is capable of asking for several different kinds of 2583 information in response: 2585 * the access being requested in the "access_token" request parameter 2587 * the subject information being requested in the "subject" request 2588 parameter 2590 * any additional requested information defined by extensions of this 2591 protocol 2593 The AS determines what authorizations and consents are required to 2594 fulfill this requested delegation. The details of how the AS makes 2595 this determination are out of scope for this document. However, 2596 there are several common patterns defined and supported by GNAP for 2597 fulfilling these requirements, including information sent by the 2598 client instance, information gathered through the interaction 2599 process, and information supplied by external parties. An individual 2600 AS can define its own policies and processes for deciding when and 2601 how to gather the necessary authorizations and consent. 2603 The client instance can supply information directly to the AS in its 2604 request. From this information, the AS can determine if the 2605 requested delegation can be granted immediately. The client instance 2606 can send several kinds of things, including: 2608 * the identity of the client instance, known from the presented keys 2609 or associated identifiers 2611 * the identity of the end user presented in the "user" request 2612 parameter 2614 * any additional information presented by the client instance in the 2615 request, including any extensions 2617 The AS will verify this presented information in the context of the 2618 client instance's request and can only trust the information as much 2619 as it trusts the presentation and context of the information. If the 2620 AS determines that the information presented in the initial request 2621 is sufficient for granting the requested access, the AS MAY return 2622 the positive results immediately in its Section 3 with access tokens 2623 and subject information. 2625 If the AS determines that additional runtime authorization is 2626 required, the AS can either deny the request outright or use a number 2627 of means at its disposal to gather that authorization from the 2628 appropriate ROs, including for example: 2630 * starting interaction with the end user facilitated by the client 2631 software, such as a redirection or user code 2633 * challenging the client instance through a challenge-response 2634 mechanism 2636 * requesting that the client instance present specific additional 2637 information, such as a user's credential or an assertion 2639 * contacting a RO through an out-of-band mechanism, such as a push 2640 notification 2642 * contacting an auxiliary software process through an out-of-band 2643 mechanism, such as querying a digital wallet 2645 The authorization and consent gathering process in GNAP is left 2646 deliberately flexible to allow for a wide variety of different 2647 deployments, interactions, and methodologies. In this process, the 2648 AS can gather consent from the RO as necessitated by the access that 2649 has been requested. The AS can sometimes determine which RO needs to 2650 consent based on what has been requested by the client instance, such 2651 as a specific RS record, an identified user, or a request requiring 2652 specific access such as approval by an administrator. If the AS has 2653 a means of contacting the RO directly, it could do so without 2654 involving the client instance in its consent gathering process. For 2655 example, the AS could push a notification to a known RO and have the 2656 RO approve the pending request asynchronously. These interactions 2657 can be through an interface of the AS itself (such as a hosted web 2658 page), through another application (such as something installed on 2659 the RO's device), through a messaging fabric, or any other means. 2660 When interacting with an RO, the AS can do anything it needs to 2661 determine the authorization of the requested grant, including: 2663 * authenticate the RO, through a local account or some other means 2664 such as federated login 2666 * validate the RO through presentation of claims, attributes, or 2667 other information 2669 * prompt the RO for consent for the requested delegation 2671 * describe to the RO what information is being released, to whom, 2672 and for what purpose 2674 * provide warnings to the RO about potential attacks or negative 2675 effects of allowing the information 2677 * allow the RO to modify the client instance's requested access, 2678 including limiting or expanding that access 2680 * provide the RO with artifacts such as receipts to facilitate an 2681 audit trail of authorizations 2683 * allow the RO to deny the requested delegation 2685 The AS is also allowed to request authorization from more than one 2686 RO, if the AS deems fit. For example, a medical record might need to 2687 be released by both an attending nurse and a physician, or both 2688 owners of a bank account need to sign off on a transfer request. 2689 Alternatively, the AS could require N of M possible RO's to approve a 2690 given request in order. The AS could also determine that the end 2691 user is not the appropriate RO for a given request and reach out to 2692 the appropriate RO asynchronously. The details of determining which 2693 RO's are required for a given request are out of scope for this 2694 specification. 2696 The client instance can also indicate that it is capable of 2697 facilitating interaction with the end user, another party, or another 2698 piece of software through its interaction start (Section 2.5.1) 2699 request. In many cases, the end user is delegating their own access 2700 as RO to the client instance. Here, the AS needs to determine the 2701 identity of the end user and will often need to interact directly 2702 with the end user to determine their status as an RO and collect 2703 their consent. If the AS has determined that authorization is 2704 required and the AS can support one or more of the requested 2705 interaction start methods, the AS returns the associated interaction 2706 start responses (Section 3.3). The client instance SHOULD initiate 2707 one or more of these interaction methods (Section 4.1) in order to 2708 facilitate the granting of the request. If more than one interaction 2709 start method is available, the means by which the client chooses 2710 which methods to follow is out of scope of this specification. The 2711 client instance MUST use each interaction method once at most. 2713 After starting interaction, the client instance can then make a 2714 continuation request (Section 5) either in response to a signal 2715 indicating the finish of the interaction (Section 4.2), through 2716 polling, or through some other method defined by an extension of this 2717 specification. 2719 If the AS and client instance have not reached a state where the 2720 delegation can be granted, the AS and client instance can repeat the 2721 interaction process as long as the AS supplies the client instance 2722 with continuation information (Section 3.1) to facilitate the ongoing 2723 requests. 2725 4.1. Interaction Start Methods 2727 To initiate an interaction start method indicated by the interaction 2728 start responses (Section 3.3) from the AS, the client instance 2729 follows the steps defined by that interaction method. The actions of 2730 the client instance required for the interaction start modes defined 2731 in this specification are described in the following sections. 2733 4.1.1. Interaction at a Redirected URI 2735 When the end user is directed to an arbitrary URI through the 2736 "redirect" (Section 3.3.1) mode, the client instance facilitates 2737 opening the URI through the end user's web browser. The client 2738 instance could launch the URI through the system browser, provide a 2739 clickable link, redirect the user through HTTP response codes, or 2740 display the URI in a form the end user can use to launch such as a 2741 multidimensional barcode. With this method, it is common (though not 2742 required) for the RO to be the same party as the end-user, since the 2743 client instance has to communicate the redirection URI to the end- 2744 user. 2746 In many cases, the URI indicates a web page hosted at the AS, 2747 allowing the AS to authenticate the end user as the RO and 2748 interactively provide consent. If the URI is hosted by the AS, the 2749 AS MUST determine the grant request being referenced from the URL 2750 value itself. If the URL cannot be associated with a currently 2751 active request, the AS MUST display an error to the RO and MUST NOT 2752 attempt to redirect the RO back to any client instance even if a 2753 redirect finish method is supplied (Section 2.5.2.1). If the URI is 2754 not hosted by the AS directly, the means of communication between the 2755 AS and this URI are out of scope for this specification. 2757 The client instance MUST NOT modify the URI when launching it, in 2758 particular the client instance MUST NOT add any parameters to the 2759 URI. The URI MUST be reachable from the end user's browser, though 2760 the URI MAY be opened on a separate device from the client instance 2761 itself. The URI MUST be accessible from an HTTP GET request and MUST 2762 be protected by HTTPS or equivalent means. 2764 4.1.2. Interaction at the User Code URI 2766 When the end user is directed to enter a short code through the 2767 "user_code" (Section 3.3.3) mode, the client instance communicates 2768 the user code to the end-user and directs the end user to enter that 2769 code at an associated URI. This mode is used when the client 2770 instance is not able to facilitate launching an arbitrary URI. The 2771 associated URI could be statically configured with the client 2772 instance or communicated in the response from the AS, but the client 2773 instance communicates that URL to the end user. As a consequence, 2774 these URIs SHOULD be short. 2776 In many cases, the URI indicates a web page hosted at the AS, 2777 allowing the AS to authenticate the end user as the RO and 2778 interactively provide consent. If the URI is hosted by the AS, the 2779 AS MUST determine the grant request being referenced from the user 2780 code. If the user code cannot be associated with a currently active 2781 request, the AS MUST display an error to the RO and MUST NOT attempt 2782 to redirect the RO back to any client instance even if a redirect 2783 finish method is supplied (Section 2.5.2.1). If the interaction 2784 component at the user code URI is not hosted by the AS directly, the 2785 means of communication between the AS and this URI, including 2786 communication of the user code itself, are out of scope for this 2787 specification. 2789 When the RO enters this code at the user code URI, the AS MUST 2790 uniquely identify the pending request that the code was associated 2791 with. If the AS does not recognize the entered code, the interaction 2792 component MUST display an error to the user. If the AS detects too 2793 many unrecognized code enter attempts, the interaction component 2794 SHOULD display an error to the user and MAY take additional actions 2795 such as slowing down the input interactions. The user should be 2796 warned as such an error state is approached, if possible. 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 user code URI MUST be reachable from the end user's 2801 browser, though the URI is usually be opened on a separate device 2802 from the client instance itself. The URI MUST be accessible from an 2803 HTTP GET request and MUST be protected by HTTPS or equivalent means. 2805 4.1.3. Interaction through an Application URI 2807 When the client instance is directed to launch an application through 2808 the "app" (Section 3.3.2) mode, the client launches the URL as 2809 appropriate to the system, such as through a deep link or custom URI 2810 scheme registered to a mobile application. The means by which the AS 2811 and the launched application communicate with each other and perform 2812 any of the required actions are out of scope for this specification. 2814 4.2. Post-Interaction Completion 2816 If an interaction "finish" (Section 3.3.4) method is associated with 2817 the current request, the AS MUST follow the appropriate method at 2818 upon completion of interaction in order to signal the client instance 2819 to continue, except for some limited error cases discussed below. If 2820 a finish method is not available, the AS SHOULD instruct the RO to 2821 return to the client instance upon completion. 2823 The AS MUST create an interaction reference and associate that 2824 reference with the current interaction and the underlying pending 2825 request. This interaction reference value MUST be sufficiently 2826 random so as not to be guessable by an attacker. The interaction 2827 reference MUST be one-time-use to prevent interception and replay 2828 attacks. 2830 The AS MUST calculate a hash value based on the client instance and 2831 AS nonces and the interaction reference, as described in 2832 Section 4.2.3. The client instance will use this value to validate 2833 the "finish" call. 2835 The AS MUST send the hash and interaction reference based on the 2836 interaction finish mode as described in the following sections. 2838 Note that the "finish" method still occurs in many error cases, such 2839 as when the RO has denied access. This pattern allows the client 2840 instance to potentially recover from the error state by modifying its 2841 request or providing additional information directly to the AS in a 2842 continuation request. The AS MUST NOT follow the "finish" method in 2843 the following circumstances: 2845 * The AS has determined that any URIs involved with the finish 2846 method are dangerous or blocked. 2848 * The AS cannot determine which ongoing grant request is being 2849 referenced. 2851 * The ongoing grant request has been cancelled or otherwise blocked. 2853 4.2.1. Completing Interaction with a Browser Redirect to the Callback 2854 URI 2856 When using the "redirect" interaction finish method (Section 3.3.4), 2857 the AS signals to the client instance that interaction is complete 2858 and the request can be continued by directing the RO (in their 2859 browser) back to the client instance's redirect URL sent in the 2860 callback request (Section 2.5.2.1). 2862 The AS secures this redirect by adding the hash and interaction 2863 reference as query parameters to the client instance's redirect URL. 2865 hash REQUIRED. The interaction hash value as described in 2866 Section 4.2.3. 2868 interact_ref REQUIRED. The interaction reference generated for this 2869 interaction. 2871 The means of directing the RO to this URL are outside the scope of 2872 this specification, but common options include redirecting the RO 2873 from a web page and launching the system browser with the target URL. 2875 NOTE: '\' line wrapping per RFC 8792 2877 https://client.example.net/return/123455\ 2878 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 2879 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 2880 &interact_ref=4IFWWIKYBC2PQ6U56NL1 2882 When receiving the request, the client instance MUST parse the query 2883 parameters to calculate and validate the hash value as described in 2884 Section 4.2.3. If the hash validates, the client instance sends a 2885 continuation request to the AS as described in Section 5.1 using the 2886 interaction reference value received here. 2888 4.2.2. Completing Interaction with a Direct HTTP Request Callback 2890 When using the "callback" interaction mode (Section 3.3.4) with the 2891 "push" method, the AS signals to the client instance that interaction 2892 is complete and the request can be continued by sending an HTTP POST 2893 request to the client instance's callback URL sent in the callback 2894 request (Section 2.5.2.2). 2896 The entity message body is a JSON object consisting of the following 2897 two fields: 2899 hash (string) REQUIRED. The interaction hash value as described in 2900 Section 4.2.3. 2902 interact_ref (string) REQUIRED. The interaction reference generated 2903 for this interaction. 2905 NOTE: '\' line wrapping per RFC 8792 2907 POST /push/554321 HTTP/1.1 2908 Host: client.example.net 2909 Content-Type: application/json 2911 { 2912 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ 2913 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 2914 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 2915 } 2917 When receiving the request, the client instance MUST parse the JSON 2918 object and validate the hash value as described in Section 4.2.3. If 2919 the hash validates, the client instance sends a continuation request 2920 to the AS as described in Section 5.1 using the interaction reference 2921 value received here. 2923 4.2.3. Calculating the interaction hash 2925 The "hash" parameter in the request to the client instance's callback 2926 URL ties the front channel response to an ongoing request by using 2927 values known only to the parties involved. This security mechanism 2928 allows the client instance to protect itself against several kinds of 2929 session fixation and injection attacks. The AS MUST always provide 2930 this hash, and the client instance MUST validate the hash when 2931 received. 2933 To calculate the "hash" value, the party doing the calculation 2934 creates a hash string by concatenating the following values in the 2935 following order using a single newline ("\\n") character to separate 2936 them: 2938 * the "nonce" value sent by the client instance in the interaction 2939 "finish" section of the initial request (Section 2.5.2) 2941 * the AS's nonce value from the interaction finish response 2942 (Section 3.3.4) 2944 * the "interact_ref" returned from the AS as part of the interaction 2945 finish method (Section 4.2) 2947 * the grant endpoint URL the client instance used to make its 2948 initial request (Section 2) 2950 There is no padding or whitespace before or after any of the lines, 2951 and no trailing newline character. 2953 VJLO6A4CAYLBXHTR0KRO 2954 MBDOFXG4Y5CVJCX821LH 2955 4IFWWIKYBC2PQ6U56NL1 2956 https://server.example.com/tx 2958 The party then hashes this string with the appropriate algorithm 2959 based on the "hash_method" parameter of the "callback". If the 2960 "hash_method" value is not present in the client instance's request, 2961 the algorithm defaults to "sha3". 2963 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2964 issues/56) ]] 2966 4.2.3.1. SHA3-512 2968 The "sha3" hash method consists of hashing the input string with the 2969 512-bit SHA3 algorithm. The byte array is then encoded using URL 2970 Safe Base64 with no padding. The resulting string is the hash value. 2972 NOTE: '\' line wrapping per RFC 8792 2974 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ 2975 7XHPAdJzTZMtKBsaraJ64A 2977 4.2.3.2. SHA2-512 2979 The "sha2" hash method consists of hashing the input string with the 2980 512-bit SHA2 algorithm. The byte array is then encoded using URL 2981 Safe Base64 with no padding. The resulting string is the hash value. 2983 NOTE: '\' line wrapping per RFC 8792 2985 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 2986 j84rh4mC9aE9x7HPBFcIHw 2988 5. Continuing a Grant Request 2990 While it is possible for the AS to return a Section 3 with all the 2991 client instance's requested information (including access tokens 2992 (Section 3.2) and direct user information (Section 3.4)), it's more 2993 common that the AS and the client instance will need to communicate 2994 several times over the lifetime of an access grant. This is often 2995 part of facilitating interaction (Section 4), but it could also be 2996 used to allow the AS and client instance to continue negotiating the 2997 parameters of the original grant request (Section 2). 2999 To enable this ongoing negotiation, the AS provides a continuation 3000 API to the client software. The AS returns a "continue" field in the 3001 response (Section 3.1) that contains information the client instance 3002 needs to access this API, including a URI to access as well as an 3003 access token to use during the continued requests. 3005 The access token is initially bound to the same key and method the 3006 client instance used to make the initial request. As a consequence, 3007 when the client instance makes any calls to the continuation URL, the 3008 client instance MUST present the access token as described in 3009 Section 7.2 and present proof of the client instance's key (or its 3010 most recent rotation) by signing the request as described in 3011 Section 7.3. The AS MUST validate all keys presented by the client 3012 instance or referenced in an ongoing request for each call within 3013 that request. 3015 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3016 issues/85) ]] 3018 For example, here the client instance makes a POST request to a 3019 unique URI and signs the request with HTTP Message Signatures: 3021 POST /continue/KSKUOMUKM HTTP/1.1 3022 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3023 Host: server.example.com 3024 Signature-Input: sig1=... 3025 Signature: sig1=... 3027 The AS MUST be able to tell from the client instance's request which 3028 specific ongoing request is being accessed, using a combination of 3029 the continuation URL, the provided access token, and the client 3030 instance identified by the key signature. If the AS cannot determine 3031 a single active grant request to map the continuation request to, the 3032 AS MUST return an error. 3034 The ability to continue an already-started request allows the client 3035 instance to perform several important functions, including presenting 3036 additional information from interaction, modifying the initial 3037 request, and getting the current state of the request. 3039 All requests to the continuation API are protected by this bound 3040 access token. For example, here the client instance makes a POST 3041 request to a stable continuation endpoint URL with the interaction 3042 reference (Section 5.1), includes the access token, and signs with 3043 HTTP Message Signatures: 3045 POST /continue HTTP/1.1 3046 Host: server.example.com 3047 Content-Type: application/json 3048 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3049 Signature-Input: sig1=... 3050 Signature: sig1=... 3051 Digest: sha256=... 3053 { 3054 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3055 } 3057 If a "wait" parameter was included in the continuation response 3058 (Section 3.1), the client instance MUST NOT call the continuation URI 3059 prior to waiting the number of seconds indicated. If no "wait" 3060 period is indicated, the client instance SHOULD wait at least 5 3061 seconds. If the client instance does not respect the given wait 3062 period, the AS MUST return an error. [[ See issue #86 3063 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/86) ]] 3065 The response from the AS is a JSON object and MAY contain any of the 3066 fields described in Section 3, as described in more detail in the 3067 sections below. 3069 If the AS determines that the client instance can make a further 3070 continuation request, the AS MUST include a new "continue" response 3071 (Section 3.1). The new "continue" response MUST include a bound 3072 access token as well, and this token SHOULD be a new access token, 3073 invalidating the previous access token. If the AS does not return a 3074 new "continue" response, the client instance MUST NOT make an 3075 additional continuation request. If a client instance does so, the 3076 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 3077 wg-gnap/gnap-core-protocol/issues/87) ]] 3079 For continuation functions that require the client instance to send a 3080 message body, the body MUST be a JSON object. 3082 5.1. Continuing After a Completed Interaction 3084 When the AS responds to the client instance's "finish" method as in 3085 Section 4.2.1, this response includes an interaction reference. The 3086 client instance MUST include that value as the field "interact_ref" 3087 in a POST request to the continuation URI. 3089 POST /continue HTTP/1.1 3090 Host: server.example.com 3091 Content-Type: application/json 3092 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3093 Signature-Input: sig1=... 3094 Signature: sig1=... 3095 Digest: sha256=... 3097 { 3098 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3099 } 3101 Since the interaction reference is a one-time-use value as described 3102 in Section 4.2.1, if the client instance needs to make additional 3103 continuation calls after this request, the client instance MUST NOT 3104 include the interaction reference. If the AS detects a client 3105 instance submitting the same interaction reference multiple times, 3106 the AS MUST return an error and SHOULD invalidate the ongoing 3107 request. 3109 The Section 3 MAY contain any newly-created access tokens 3110 (Section 3.2) or newly-released subject claims (Section 3.4). The 3111 response MAY contain a new "continue" response (Section 3.1) as 3112 described above. The response SHOULD NOT contain any interaction 3113 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 3114 wg-gnap/gnap-core-protocol/issues/89) ]] 3115 For example, if the request is successful in causing the AS to issue 3116 access tokens and release opaque subject claims, the response could 3117 look like this: 3119 NOTE: '\' line wrapping per RFC 8792 3121 { 3122 "access_token": { 3123 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3124 "manage": "https://server.example.com/token/PRY5NM33O\ 3125 M4TB8N6BW7OZB8CDFONP219RP1L", 3126 }, 3127 "subject": { 3128 "sub_ids": [ { 3129 "format": "opaque", 3130 "id": "J2G8G8O4AZ" 3131 } ] 3132 } 3133 } 3135 With this example, the client instance can not make an additional 3136 continuation request because a "continue" field is not included. 3138 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3139 issues/88) ]] 3141 5.2. Continuing During Pending Interaction 3143 When the client instance does not include a "finish" parameter, the 3144 client instance will often need to poll the AS until the RO has 3145 authorized the request. To do so, the client instance makes a POST 3146 request to the continuation URI as in Section 5.1, but does not 3147 include a message body. 3149 POST /continue HTTP/1.1 3150 Host: server.example.com 3151 Content-Type: application/json 3152 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3153 Signature-Input: sig1=... 3154 Signature: sig1=... 3156 The Section 3 MAY contain any newly-created access tokens 3157 (Section 3.2) or newly-released subject claims (Section 3.4). The 3158 response MAY contain a new "continue" response (Section 3.1) as 3159 described above. If a "continue" field is included, it SHOULD 3160 include a "wait" field to facilitate a reasonable polling rate by the 3161 client instance. The response SHOULD NOT contain interaction 3162 responses (Section 3.3). 3164 For example, if the request has not yet been authorized by the RO, 3165 the AS could respond by telling the client instance to make another 3166 continuation request in the future. In this example, a new, unique 3167 access token has been issued for the call, which the client instance 3168 will use in its next continuation request. 3170 { 3171 "continue": { 3172 "access_token": { 3173 "value": "33OMUKMKSKU80UPRY5NM" 3174 }, 3175 "uri": "https://server.example.com/continue", 3176 "wait": 30 3177 } 3178 } 3180 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3181 issues/90) ]] 3183 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3184 issues/91) ]] 3186 If the request is successful in causing the AS to issue access tokens 3187 and release subject claims, the response could look like this 3188 example: 3190 NOTE: '\' line wrapping per RFC 8792 3192 { 3193 "access_token": { 3194 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3195 "manage": "https://server.example.com/token/PRY5NM33O\ 3196 M4TB8N6BW7OZB8CDFONP219RP1L", 3197 }, 3198 "subject": { 3199 "sub_ids": [ { 3200 "format": "opaque", 3201 "id": "J2G8G8O4AZ" 3202 } ] 3203 } 3204 } 3206 5.3. Modifying an Existing Request 3208 The client instance might need to modify an ongoing request, whether 3209 or not tokens have already been issued or claims have already been 3210 released. In such cases, the client instance makes an HTTP PATCH 3211 request to the continuation URI and includes any fields it needs to 3212 modify. Fields that aren't included in the request are considered 3213 unchanged from the original request. 3215 The client instance MAY include the "access_token" and "subject" 3216 fields as described in Section 2.1 and Section 2.2. Inclusion of 3217 these fields override any values in the initial request, which MAY 3218 trigger additional requirements and policies by the AS. For example, 3219 if the client instance is asking for more access, the AS could 3220 require additional interaction with the RO to gather additional 3221 consent. If the client instance is asking for more limited access, 3222 the AS could determine that sufficient authorization has been granted 3223 to the client instance and return the more limited access rights 3224 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 3225 core-protocol/issues/92) ]] 3227 The client instance MAY include the "interact" field as described in 3228 Section 2.5. Inclusion of this field indicates that the client 3229 instance is capable of driving interaction with the RO, and this 3230 field replaces any values from a previous request. The AS MAY 3231 respond to any of the interaction responses as described in 3232 Section 3.3, just like it would to a new request. 3234 The client instance MAY include the "user" field as described in 3235 Section 2.4 to present new assertions or information about the end- 3236 user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- 3237 protocol/issues/93) ]] 3239 The client instance MUST NOT include the "client" section of the 3240 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 3241 protocol/issues/94) ]] 3243 The client instance MAY include post-interaction responses such as 3244 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 3245 wg-gnap/gnap-core-protocol/issues/95) ]] 3247 Modification requests MUST NOT alter previously-issued access tokens. 3248 Instead, any access tokens issued from a continuation are considered 3249 new, separate access tokens. The AS MAY revoke existing access 3250 tokens after a modification has occurred. [[ See issue #96 3251 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 3252 If the modified request can be granted immediately by the AS, the 3253 Section 3 MAY contain any newly-created access tokens (Section 3.2) 3254 or newly-released subject claims (Section 3.4). The response MAY 3255 contain a new "continue" response (Section 3.1) as described above. 3256 If interaction can occur, the response SHOULD contain interaction 3257 responses (Section 3.3) as well. 3259 For example, a client instance initially requests a set of resources 3260 using references: 3262 POST /tx HTTP/1.1 3263 Host: server.example.com 3264 Content-Type: application/json 3265 Signature-Input: sig1=... 3266 Signature: sig1=... 3267 Digest: sha256=... 3269 { 3270 "access_token": { 3271 "access": [ 3272 "read", "write" 3273 ] 3274 }, 3275 "interact": { 3276 "start": ["redirect"], 3277 "finish": { 3278 "method": "redirect", 3279 "uri": "https://client.example.net/return/123455", 3280 "nonce": "LKLTI25DK82FX4T4QFZC" 3281 } 3282 }, 3283 "client": "987YHGRT56789IOLK" 3284 } 3286 Access is granted by the RO, and a token is issued by the AS. In its 3287 final response, the AS includes a "continue" field, which includes a 3288 separate access token for accessing the continuation API: 3290 { 3291 "continue": { 3292 "access_token": { 3293 "value": "80UPRY5NM33OMUKMKSKU" 3294 }, 3295 "uri": "https://server.example.com/continue", 3296 "wait": 30 3297 }, 3298 "access_token": { 3299 "value": "RP1LT0-OS9M2P_R64TB", 3300 "access": [ 3301 "read", "write" 3302 ] 3303 } 3304 } 3306 This "continue" field allows the client instance to make an eventual 3307 continuation call. In the future, the client instance realizes that 3308 it no longer needs "write" access and therefore modifies its ongoing 3309 request, here asking for just "read" access instead of both "read" 3310 and "write" as before. 3312 PATCH /continue HTTP/1.1 3313 Host: server.example.com 3314 Content-Type: application/json 3315 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3316 Signature-Input: sig1=... 3317 Signature: sig1=... 3318 Digest: sha256=... 3320 { 3321 "access_token": { 3322 "access": [ 3323 "read" 3324 ] 3325 } 3326 ... 3327 } 3329 The AS replaces the previous "access" from the first request, 3330 allowing the AS to determine if any previously-granted consent 3331 already applies. In this case, the AS would likely determine that 3332 reducing the breadth of the requested access means that new access 3333 tokens can be issued to the client instance. The AS would likely 3334 revoke previously-issued access tokens that had the greater access 3335 rights associated with them, unless they had been issued with the 3336 "durable" flag. 3338 { 3339 "continue": { 3340 "access_token": { 3341 "value": "M33OMUK80UPRY5NMKSKU" 3342 }, 3343 "uri": "https://server.example.com/continue", 3344 "wait": 30 3345 }, 3346 "access_token": { 3347 "value": "0EVKC7-2ZKwZM_6N760", 3348 "access": [ 3349 "read" 3350 ] 3351 } 3352 } 3354 For another example, the client instance initially requests read-only 3355 access but later needs to step up its access. The initial request 3356 could look like this example. 3358 POST /tx HTTP/1.1 3359 Host: server.example.com 3360 Content-Type: application/json 3361 Signature-Input: sig1=... 3362 Signature: sig1=... 3363 Digest: sha256=... 3365 { 3366 "access_token": { 3367 "access": [ 3368 "read" 3369 ] 3370 }, 3371 "interact": { 3372 "start": ["redirect"], 3373 "finish": { 3374 "method": "redirect", 3375 "uri": "https://client.example.net/return/123455", 3376 "nonce": "LKLTI25DK82FX4T4QFZC" 3377 } 3378 }, 3379 "client": "987YHGRT56789IOLK" 3380 } 3382 Access is granted by the RO, and a token is issued by the AS. In its 3383 final response, the AS includes a "continue" field: 3385 { 3386 "continue": { 3387 "access_token": { 3388 "value": "80UPRY5NM33OMUKMKSKU" 3389 }, 3390 "uri": "https://server.example.com/continue", 3391 "wait": 30 3392 }, 3393 "access_token": { 3394 "value": "RP1LT0-OS9M2P_R64TB", 3395 "access": [ 3396 "read" 3397 ] 3398 } 3399 } 3401 This allows the client instance to make an eventual continuation 3402 call. The client instance later realizes that it now needs "write" 3403 access in addition to the "read" access. Since this is an expansion 3404 of what it asked for previously, the client instance also includes a 3405 new interaction section in case the AS needs to interact with the RO 3406 again to gather additional authorization. Note that the client 3407 instance's nonce and callback are different from the initial request. 3408 Since the original callback was already used in the initial exchange, 3409 and the callback is intended for one-time-use, a new one needs to be 3410 included in order to use the callback again. 3412 [[ See issue #97 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3413 issues/97) ]] 3414 PATCH /continue HTTP/1.1 3415 Host: server.example.com 3416 Content-Type: application/json 3417 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3418 Signature-Input: sig1=... 3419 Signature: sig1=... 3420 Digest: sha256=... 3422 { 3423 "access_token": { 3424 "access": [ 3425 "read", "write" 3426 ] 3427 }, 3428 "interact": { 3429 "start": ["redirect"], 3430 "finish": { 3431 "method": "redirect", 3432 "uri": "https://client.example.net/return/654321", 3433 "nonce": "K82FX4T4LKLTI25DQFZC" 3434 } 3435 } 3436 } 3438 From here, the AS can determine that the client instance is asking 3439 for more than it was previously granted, but since the client 3440 instance has also provided a mechanism to interact with the RO, the 3441 AS can use that to gather the additional consent. The protocol 3442 continues as it would with a new request. Since the old access 3443 tokens are good for a subset of the rights requested here, the AS 3444 might decide to not revoke them. However, any access tokens granted 3445 after this update process are new access tokens and do not modify the 3446 rights of existing access tokens. 3448 5.4. Canceling a Grant Request 3450 If the client instance wishes to cancel an ongoing grant request, it 3451 makes an HTTP DELETE request to the continuation URI. 3453 DELETE /continue HTTP/1.1 3454 Host: server.example.com 3455 Content-Type: application/json 3456 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3457 Signature-Input: sig1=... 3458 Signature: sig1=... 3460 If the request is successfully cancelled, the AS responds with an 3461 HTTP 202. The AS SHOULD revoke all associated access tokens. 3463 6. Token Management 3465 If an access token response includes the "manage" parameter as 3466 described in Section 3.2.1, the client instance MAY call this URL to 3467 manage the access token with any of the actions defined in the 3468 following sections. Other actions are undefined by this 3469 specification. 3471 The access token being managed acts as the access element for its own 3472 management API. The client instance MUST present proof of an 3473 appropriate key along with the access token. 3475 If the token is sender-constrained (i.e., not a bearer token), it 3476 MUST be sent with the appropriate binding for the access token 3477 (Section 7.2). 3479 If the token is a bearer token, the client instance MUST present 3480 proof of the same key identified in the initial request (Section 2.3) 3481 as described in Section 7.3. 3483 The AS MUST validate the proof and assure that it is associated with 3484 either the token itself or the client instance the token was issued 3485 to, as appropriate for the token's presentation type. 3487 6.1. Rotating the Access Token 3489 The client instance makes an HTTP POST to the token management URI, 3490 sending the access token in the appropriate header and signing the 3491 request with the appropriate key. 3493 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3494 Host: server.example.com 3495 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3496 Signature-Input: sig1=... 3497 Signature: sig1=... 3498 Digest: sha256=... 3500 The AS validates that the token presented is associated with the 3501 management URL, that the AS issued the token to the given client 3502 instance, and that the presented key is appropriate to the token. 3504 If the access token has expired, the AS SHOULD honor the rotation 3505 request to the token management URL since it is likely that the 3506 client instance is attempting to refresh the expired token. To 3507 support this, the AS MAY apply different lifetimes for the use of the 3508 token in management vs. its use at an RS. An AS MUST NOT honor a 3509 rotation request for an access token that has been revoked, either by 3510 the AS or by the client instance through the token management URI 3511 (Section 6.2). 3513 If the token is validated and the key is appropriate for the request, 3514 the AS MUST invalidate the current access token associated with this 3515 URL, if possible, and return a new access token response as described 3516 in Section 3.2.1, unless the "multi_token" flag is specified in the 3517 request. The value of the access token MUST NOT be the same as the 3518 current value of the access token used to access the management API. 3519 The response MAY include an updated access token management URL as 3520 well, and if so, the client instance MUST use this new URL to manage 3521 the new access token. [[ See issue #101 (https://github.com/ietf-wg- 3522 gnap/gnap-core-protocol/issues/101) ]] 3524 [[ See issue #102 (https://github.com/ietf-wg-gnap/gnap-core- 3525 protocol/issues/102) ]] 3526 NOTE: '\' line wrapping per RFC 8792 3528 { 3529 "access_token": { 3530 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3531 "manage": "https://server.example.com/token/PRY5NM33O\ 3532 M4TB8N6BW7OZB8CDFONP219RP1L", 3533 "access": [ 3534 { 3535 "type": "photo-api", 3536 "actions": [ 3537 "read", 3538 "write", 3539 "dolphin" 3540 ], 3541 "locations": [ 3542 "https://server.example.net/", 3543 "https://resource.local/other" 3544 ], 3545 "datatypes": [ 3546 "metadata", 3547 "images" 3548 ] 3549 }, 3550 "read", "dolphin-metadata" 3551 ] 3552 } 3553 } 3555 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3556 protocol/issues/103) ]] 3558 6.2. Revoking the Access Token 3560 If the client instance wishes to revoke the access token proactively, 3561 such as when a user indicates to the client instance that they no 3562 longer wish for it to have access or the client instance application 3563 detects that it is being uninstalled, the client instance can use the 3564 token management URI to indicate to the AS that the AS should 3565 invalidate the access token for all purposes. 3567 The client instance makes an HTTP DELETE request to the token 3568 management URI, presenting the access token and signing the request 3569 with the appropriate key. 3571 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3572 Host: server.example.com 3573 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3574 Signature-Input: sig1=... 3575 Signature: sig1=... 3577 If the key presented is associated with the token (or the client 3578 instance, in the case of a bearer token), the AS MUST invalidate the 3579 access token, if possible, and return an HTTP 204 response code. 3581 204 No Content 3583 Though the AS MAY revoke an access token at any time for any reason, 3584 the token management function is specifically for the client 3585 instance's use. If the access token has already expired or has been 3586 revoked through other means, the AS SHOULD honor the revocation 3587 request to the token management URL as valid, since the end result is 3588 still the token not being usable. 3590 7. Securing Requests from the Client Instance 3592 In GNAP, the client instance secures its requests to the AS and RS by 3593 presenting an access token, presenting proof of a key that it 3594 possesses, or both an access token and key proof together. 3596 * When an access token is used with a key proof, this is a bound 3597 token request. This type of request is used for calls to the RS 3598 as well as the AS during negotiation. 3600 * When a key proof is used with no access token, this is a non- 3601 authorized signed request. This type of request is used for calls 3602 to the AS to initiate a negotiation. 3604 * When an access token is used with no key proof, this is a bearer 3605 token request. This type of request is used only for calls to the 3606 RS, and only with access tokens that are not bound to any key as 3607 described in Section 3.2.1. 3609 * When neither an access token nor key proof are used, this is an 3610 unsecured request. This type of request is used optionally for 3611 calls to the RS as part of an RS-first discovery process as 3612 described in Section 9.1. 3614 7.1. Key Formats 3616 Several different places in GNAP require the presentation of key 3617 material by value. Proof of this key material MUST be bound to a 3618 request, the nature of which varies with the location in the protocol 3619 the key is used. For a key used as part of a client instance's 3620 initial request in Section 2.3, the key value is the client 3621 instance's public key, and proof of that key MUST be presented in 3622 that request. For a key used as part of an access token response in 3623 Section 3.2.1, the proof of that key MUST be used when presenting the 3624 access token. 3626 A key presented by value MUST be a public key in at least one 3627 supported format. If a key is sent in multiple formats, all the key 3628 format values MUST be equivalent. Note that while most formats 3629 present the full value of the public key, some formats present a 3630 value cryptographically derived from the public key. 3632 proof (string) The form of proof that the client instance will use 3633 when presenting the key. The valid values of this field and the 3634 processing requirements for each are detailed in Section 7.3. The 3635 "proof" field is REQUIRED. 3637 jwk (object) The public key and its properties represented as a JSON 3638 Web Key [RFC7517]. A JWK MUST contain the "alg" (Algorithm) and 3639 "kid" (Key ID) parameters. The "alg" parameter MUST NOT be 3640 "none". The "x5c" (X.509 Certificate Chain) parameter MAY be used 3641 to provide the X.509 representation of the provided public key. 3643 cert (string) PEM serialized value of the certificate used to sign 3644 the request, with optional internal whitespace per [RFC7468]. The 3645 PEM header and footer are optionally removed. 3647 cert#S256 (string) The certificate thumbprint calculated as per 3648 OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this 3649 format does not include the full public key. 3651 Additional key formats are defined in a registry TBD (Section 11). 3653 This non-normative example shows a single key presented in multiple 3654 formats. This example key is intended to be used with the HTTP 3655 Message Signatures ({{httpsig-binding}}) proofing mechanism, as 3656 indicated by the "httpsig" value of the "proof" field. 3658 "key": { 3659 "proof": "httpsig", 3660 "jwk": { 3661 "kty": "RSA", 3662 "e": "AQAB", 3663 "kid": "xyz-1", 3664 "alg": "RS256", 3665 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 3666 }, 3667 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 3668 } 3670 7.1.1. Key References 3672 Keys in GNAP can also be passed by reference such that the party 3673 receiving the reference will be able to determine the appropriate 3674 keying material for use in that part of the protocol. 3676 "key": "S-P4XJQ_RYJCRTSU1.63N3E" 3678 Keys referenced in this manner MAY be shared symmetric keys. The key 3679 reference MUST NOT contain any unencrypted private or shared 3680 symmetric key information. 3682 Keys referenced in this manner MUST be bound to a single proofing 3683 mechanism. 3685 The means of dereferencing this value are out of scope for this 3686 specification. 3688 7.2. Presenting Access Tokens 3690 The method the client instance uses to send an access token depends 3691 on whether the token is bound to a key, and if so which proofing 3692 method is associated with the key. This information is conveyed in 3693 the "bound" and "key" parameters in the single (Section 3.2.1) and 3694 multiple access tokens (Section 3.2.2) responses. 3696 If the "flags" field does not contain the "bearer" flag and the "key" 3697 is absent, the access token MUST be sent using the same key and 3698 proofing mechanism that the client instance used in its initial 3699 request (or its most recent rotation). 3701 If the "flags" field does not contain the "bearer" flag and the "key" 3702 value is an object as described in Section 7.1, the access token MUST 3703 be sent using the key and proofing mechanism defined by the value of 3704 the "proof" field within the key object. 3706 The access token MUST be sent using the HTTP "Authorization" request 3707 header field and the "GNAP" authorization scheme along with a key 3708 proof as described in Section 7.3 for the key bound to the access 3709 token. For example, an "httpsig"-bound access token is sent as 3710 follows: 3712 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3713 Signature-Input: sig1=(authorization);... 3714 Signature: sig1=... 3716 If the "flags" field contains the "bearer" flag, the access token is 3717 a bearer token that MUST be sent using the "Authorization Request 3718 Header Field" method defined in [RFC6750]. 3720 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3722 The "Form-Encoded Body Parameter" and "URI Query Parameter" methods 3723 of [RFC6750] MUST NOT be used. 3725 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3726 protocol/issues/104) ]] 3728 The client software MUST reject as an error a situation where the 3729 "flags" field contains the "bearer" flag and the "key" field is 3730 present with any value. 3732 7.3. Proving Possession of a Key with a Request 3734 Any keys presented by the client instance to the AS or RS MUST be 3735 validated as part of the request in which they are presented. The 3736 type of binding used is indicated by the proof parameter of the key 3737 object in Section 7.1. Values defined by this specification are as 3738 follows: 3740 httpsig HTTP Signing signature header 3742 mtls Mutual TLS certificate verification 3744 jwsd A detached JWS signature header 3746 jws Attached JWS payload 3748 Additional proofing methods are defined by a registry TBD 3749 (Section 11). 3751 All key binding methods used by this specification MUST cover all 3752 relevant portions of the request, including anything that would 3753 change the nature of the request, to allow for secure validation of 3754 the request. Relevant aspects include the URI being called, the HTTP 3755 method being used, any relevant HTTP headers and values, and the HTTP 3756 message body itself. The verifier of the signed message MUST 3757 validate all components of the signed message to ensure that nothing 3758 has been tampered with or substituted in a way that would change the 3759 nature of the request. Key binding method definitions SHOULD 3760 enumerate how these requirements are fulfilled. 3762 When a key proofing mechanism is bound to an access token, the key 3763 being presented MUST be the key associated with the access token and 3764 the access token MUST be covered by the signature method of the 3765 proofing mechanism. 3767 The key binding methods in this section MAY be used by other 3768 components making calls as part of GNAP, such as the extensions 3769 allowing the RS to make calls to the AS defined in {{I-D.ietf-gnap- 3770 resource-servers}}. To facilitate this extended use, the sections 3771 below are defined in generic terms of the "sender" and "verifier" of 3772 the HTTP message. In the core functions of GNAP, the "sender" is the 3773 client instance and the "verifier" is the AS or RS, as appropriate. 3775 When used for delegation in GNAP, these key binding mechanisms allow 3776 the AS to ensure that the keys presented by the client instance in 3777 the initial request are in control of the party calling any follow-up 3778 or continuation requests. To facilitate this requirement, the 3779 continuation response (Section 3.1) includes an access token bound to 3780 the client instance's key (Section 2.3), and that key (or its most 3781 recent rotation) MUST be proved in all continuation requests 3782 Section 5. Token management requests Section 6 are similarly bound 3783 to either the access token's own key or, in the case of bearer 3784 tokens, the client instance's key. 3786 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 3787 protocol/issues/105) ]] 3789 In the following sections, unless otherwise noted, the "RS256" JOSE 3790 Signature Algorithm is applied using the following RSA key (presented 3791 here in JWK format): 3793 NOTE: '\' line wrapping per RFC 8792 3795 { 3796 "kid": "gnap-rsa", 3797 "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ 3798 i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ 3799 eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", 3800 "kty": "RSA", 3801 "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ 3802 LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ 3803 JXMxOLyPjzuVgiTOCBIvLD6-8-mvFjXZk_eefD0at6mQ5qV3U1jZt88", 3804 "d": "FHlhdTF0ozTliDxMBffT6aJVKZKmbbFJOVNten9c3lXKB3ux3NAb_D2dB\ 3805 7inp9EV23oWrDspFtvCvD9dZrXgRKMHofkEpo_SSvBZfgtH-OTkbY_TqtPF\ 3806 FLPKAw0JX5cFPnn4Q2xE4n-dQ7tpRCKl59vZLHBrHShr90zqzFp0AKXU5fj\ 3807 b1gC9LPwsFA2Fd7KXmI1drQQEVq9R-o18Pnn4BGQNQNjO_VkcJTiBmEIVT_\ 3808 KJRPdpVJAmbgnYWafL_hAfeb_dK8p85yurEVF8nCK5oO3EPrqB7IL4UqaEn\ 3809 5Sl3u0j8x5or-xrrAoNz-gdOv7ONfZY6NFoa-3f8q9wBAHUuQ", 3810 "e": "AQAB", 3811 "qi": "ogpNEkDKg22Rj9cDV_-PJBZaXMk66Fp557RT1tafIuqJRHEufSOYnsto\ 3812 bWPJ0gHxv1gVJw3gm-zYvV-wTMNgr2wVsBSezSJjPSjxWZtmT2z68W1DuvK\ 3813 kZy15vz7Jd85hmDlriGcXNCoFEUsGLWkpHH9RwPIzguUHWmTt8y0oXyI", 3814 "dp": "dvCKGI2G7RLh3WyjoJ_Dr6hZ3LhXweB3YcY3qdD9BnxZ71mrLiMQg4c_\ 3815 EBnwqCETN_5sStn2cRc2JXnvLP3G8t7IFKHTT_i_TSTacJ7uT04MSa053Y3\ 3816 RfwbvLjRNPR0UKAE3ZxROUoIaVNuU_6-QMf8-2ilUv2GIOrCN87gP_Vk", 3817 "alg": "RS256", 3818 "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ 3819 M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ 3820 Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", 3821 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ 3822 YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ 3823 jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ 3824 e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ 3825 bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ 3826 zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3827 } 3829 7.3.1. HTTP Message Signing 3831 This method is indicated by "httpsig" in the "proof" field. The 3832 sender creates an HTTP Message Signature as described in 3833 [I-D.ietf-httpbis-message-signatures]. 3835 The covered content of the signature MUST include the following: 3837 @request-target: the target of the HTTP request 3839 digest: The Digest header as defined in [RFC3230]. When the request 3840 message has a body, the signer MUST calculate this header value 3841 and the verifier MUST validate this header. 3843 When the request is bound to an access token, the covered content 3844 MUST also include: 3846 authorization: The Authorization header used to present the access 3847 token as discussed in Section 7.2. 3849 Other covered content MAY also be included. 3851 If the signer's key presented is a JWK, the "keyid" parameter of the 3852 signature MUST be set to the "kid" value of the JWK, the signing 3853 algorithm used MUST be the JWS algorithm denoted by the key's "alg" 3854 field, and the explicit "alg" signature parameter MUST NOT be 3855 included. 3857 In this example, the message body is the following JSON object: 3859 NOTE: '\' line wrapping per RFC 8792 3861 { 3862 "access_token": { 3863 "access": [ 3864 "dolphin-metadata" 3865 ] 3866 }, 3867 "interact": { 3868 "start": ["redirect"], 3869 "finish": { 3870 "method": "redirect", 3871 "uri": "https://client.foo/callback", 3872 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3873 } 3874 }, 3875 "client": { 3876 "proof": "httpsig", 3877 "key": { 3878 "jwk": { 3879 "kid": "gnap-rsa", 3880 "kty": "RSA", 3881 "e": "AQAB", 3882 "alg": "RS256", 3883 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3884 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3885 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3886 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3887 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3888 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3889 } 3890 } 3891 "display": { 3892 "name": "My Client Display Name", 3893 "uri": "https://client.foo/" 3894 }, 3895 } 3896 } 3898 This body is hashed for the Digest header using SHA-256 into the 3899 following encoded value: 3901 SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3903 The HTTP message signature input string is calculated to be the 3904 following: 3906 NOTE: '\' line wrapping per RFC 8792 3908 "@request-target": post /gnap 3909 "host": server.example.com 3910 "content-type": application/json 3911 "digest": SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3912 "content-length": 986 3913 "@signature-params": ("@request-target" "host" "content-type" \ 3914 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 3916 This leads to the following full HTTP message request: 3918 NOTE: '\' line wrapping per RFC 8792 3920 POST /gnap HTTP/1.1 3921 Host: server.example.com 3922 Content-Type: application/json 3923 Content-Length: 986 3924 Digest: SHA-256=98QzyNVYpdgTrWBKpC4qFSCmmR+CrwwvUoiaDCSjKxw= 3925 Signature-Input: sig1=("@request-target" "host" "content-type" \ 3926 "digest" "content-length");created=1618884475;keyid="gnap-rsa" 3927 Signature: \ 3928 sig1=:axj8FLOvEWBcwh+Xk6VTTKXxqo4XNygleTDJ8h3ZJfi1sSmWrRtyo9RG/dc\ 3929 miZmdszRjWbg+/ixVZpA4BL3AOwEOxxtmHAXNB8uJ0I3tfbs6Suyk4sEo8zPr+MJq\ 3930 MjxdJEUgAQAy2AH+wg5a7CKq4IdLTulFK9njUIeG7MygHumeiumM3DbDQAHgF46dV\ 3931 q5UC6KJnqhGM1rFC128jd2D0sgWKCUgKGCHtfR159zfKWcEO9krsLoOnCdTzm1UyD\ 3932 DMjkIjqeN/1j8PdMJaRAwV4On079O0DVu6bl1jVtkzo/e/ZmwPr/X436V4xiw/hZt\ 3933 w4sfNsSbmsT0+UAQ20X/xaw==: 3935 { 3936 "access_token": { 3937 "access": [ 3938 "dolphin-metadata" 3939 ] 3940 }, 3941 "interact": { 3942 "start": ["redirect"], 3943 "finish": { 3944 "method": "redirect", 3945 "uri": "https://client.foo/callback", 3946 "nonce": "VJLO6A4CAYLBXHTR0KRO" 3947 } 3948 }, 3949 "client": { 3950 "proof": "httpsig", 3951 "key": { 3952 "jwk": { 3953 "kid": "gnap-rsa", 3954 "kty": "RSA", 3955 "e": "AQAB", 3956 "alg": "RS256", 3957 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 3958 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 3959 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 3960 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 3961 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 3962 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 3963 } 3964 } 3965 "display": { 3966 "name": "My Client Display Name", 3967 "uri": "https://client.foo/" 3968 }, 3969 } 3970 } 3972 If the HTTP Message includes a message body, the verifier MUST 3973 calculate and verify the value of the "Digest" header. The verifier 3974 MUST ensure that the signature includes all required covered content. 3975 The verifier MUST validate the signature against the expected key of 3976 the signer. 3978 7.3.2. Mutual TLS 3980 This method is indicated by "mtls" in the "proof" field. The signer 3981 presents its TLS client certificate during TLS negotiation with the 3982 verifier. 3984 In this example, the certificate is communicated to the application 3985 through the "Client-Cert" header from a TLS reverse proxy, leading to 3986 the following full HTTP request message: 3988 POST /gnap HTTP/1.1 3989 Host: server.example.com 3990 Content-Type: application/jose 3991 Content-Length: 1567 3992 Client-Cert: \ 3993 :MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM\ 3994 K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN\ 3995 MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq\ 3996 c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG\ 3997 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB\ 3998 kI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8I\ 3999 kZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn11V2vxE4\ 4000 1hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo+\ 4001 uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKXfGhi3k\ 4002 OzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0GCSqG\ 4003 SIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/XsWfCE\ 4004 wHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5NH9\ 4005 W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeCgu\ 4006 NMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHlU\ 4007 fn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4008 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx: 4010 { 4011 "access_token": { 4012 "access": [ 4013 "dolphin-metadata" 4014 ] 4015 }, 4016 "interact": { 4017 "start": ["redirect"], 4018 "finish": { 4019 "method": "redirect", 4020 "uri": "https://client.foo/callback", 4021 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4022 } 4023 }, 4024 "client": { 4025 "proof": "jws", 4026 "key": { 4027 "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ 4028 YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ 4029 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 4030 DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ 4031 jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ 4032 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 4033 KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ 4034 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 4035 z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ 4036 fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ 4037 GCSqGSIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/Xs\ 4038 WfCEwHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5\ 4039 NH9W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeC\ 4040 guNMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHl\ 4041 Ufn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4042 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx" 4043 } 4044 "display": { 4045 "name": "My Client Display Name", 4046 "uri": "https://client.foo/" 4047 }, 4049 }, 4050 "subject": { 4051 "formats": ["iss_sub", "opaque"] 4052 } 4053 } 4055 The verifier compares the TLS client certificate presented during 4056 mutual TLS negotiation to the expected key of the signer. Since the 4057 TLS connection covers the entire message, there are no additional 4058 requirements to check. 4060 Note that in many instances, the verifier will not do a full 4061 certificate chain validation of the presented TLS client certificate, 4062 as the means of trust for this certificate could be in something 4063 other than a PKI system, such as a static registration or trust-on- 4064 first-use. 4066 [[ See issue #110 (https://github.com/ietf-wg-gnap/gnap-core- 4067 protocol/issues/110) ]] 4069 7.3.3. Detached JWS 4071 This method is indicated by "jwsd" in the "proof" field. A JWS 4072 [RFC7515] object is created as follows: 4074 To protect the request, the JOSE header of the signature contains the 4075 following parameters: 4077 kid (string) The key identifier. RECOMMENDED. If the key is 4078 presented in JWK format, this MUST be the value of the "kid" field 4079 of the key. 4081 alg (string) The algorithm used to sign the request. REQUIRED. 4082 MUST be appropriate to the key presented. If the key is presented 4083 as a JWK, this MUST be equal to the "alg" parameter of the key. 4084 MUST NOT be "none". 4086 typ (string) The type header, value "gnap-binding+jwsd". REQUIRED 4088 htm (string) The HTTP Method used to make this request, as an 4089 uppercase ASCII string. REQUIRED 4091 uri (string) The HTTP URI used for this request, including all path 4092 and query components and no fragment component. REQUIRED 4094 created (integer) A timestamp of when the signature was created, in 4095 integer seconds since UNIX Epoch 4097 ath (string) When a request is bound to an access token, the access 4098 token hash value. The value MUST be the result of Base64url 4099 encoding (with no padding) the SHA-256 digest of the ASCII 4100 encoding of the associated access token's value. REQUIRED if the 4101 request protects an access token. 4103 If the HTTP request has a message body, such as an HTTP POST or PUT 4104 method, the payload of the JWS object is the Base64url encoding 4105 (without padding) of the SHA256 digest of the bytes of the body. If 4106 the request being made does not have a message body, such as an HTTP 4107 GET, OPTIONS, or DELETE method, the JWS signature is calculated over 4108 an empty payload. 4110 The client instance presents the signed object in compact form 4111 [RFC7515] in the Detached-JWS HTTP Header field. 4113 In this example, the JOSE Header contains the following parameters: 4115 { 4116 "alg": "RS256", 4117 "kid": "gnap-rsa", 4118 "uri": "https://server.example.com/gnap", 4119 "htm": "POST", 4120 "typ": "gnap-binding+jwsd", 4121 "created": 1618884475 4122 } 4124 The request body is the following JSON object: 4126 NOTE: '\' line wrapping per RFC 8792 4128 { 4129 "access_token": { 4130 "access": [ 4131 "dolphin-metadata" 4132 ] 4133 }, 4134 "interact": { 4135 "start": ["redirect"], 4136 "finish": { 4137 "method": "redirect", 4138 "uri": "https://client.foo/callback", 4139 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4140 } 4141 }, 4142 "client": { 4143 "proof": "jwsd", 4144 "key": { 4145 "jwk": { 4146 "kid": "gnap-rsa", 4147 "kty": "RSA", 4148 "e": "AQAB", 4149 "alg": "RS256", 4150 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4151 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4152 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4153 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4154 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4155 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4156 } 4157 } 4158 "display": { 4159 "name": "My Client Display Name", 4160 "uri": "https://client.foo/" 4161 }, 4162 } 4163 } 4165 This is hashed to the following Base64 encoded value: 4167 PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc 4169 This leads to the following full HTTP request message: 4171 NOTE: '\' line wrapping per RFC 8792 4173 POST /gnap HTTP/1.1 4174 Host: server.example.com 4175 Content-Type: application/json 4176 Content-Length: 983 4177 Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ 4178 SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ 4179 NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ 4180 ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ 4181 TZA2h5YeXUoi5F2Q2iToC0Tc4drYFOSHIX68knd68RUA7yHqCVP-ZQEd6aL32H69e\ 4182 9zuMiw6O_s4TBKB3vDOvwrhYtDH6fX2hP70cQoO-47OwbqP-ifkrvI3hVgMX9TfjV\ 4183 eKNwnhoNnw3vbu7SNKeqJEbbwZfpESaGepS52xNBlDNMYBQQXxM9OqKJaXffzLFEl\ 4184 -Xe0UnfolVtBraz3aPrPy1C6a4uT7wLda3PaTOVtgysxzii3oJWpuz0WP5kRujzDF\ 4185 wX_EOzW0jsjCSkL-PXaKSpZgEjNjKDMg9irSxUISt1C1T6q3SzRgfuQ 4187 { 4188 "access_token": { 4189 "access": [ 4190 "dolphin-metadata" 4191 ] 4192 }, 4193 "interact": { 4194 "start": ["redirect"], 4195 "finish": { 4196 "method": "redirect", 4197 "uri": "https://client.foo/callback", 4198 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4199 } 4200 }, 4201 "client": { 4202 "proof": "jwsd", 4203 "key": { 4204 "jwk": { 4205 "kid": "gnap-rsa", 4206 "kty": "RSA", 4207 "e": "AQAB", 4208 "alg": "RS256", 4209 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4210 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4211 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4212 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4213 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4214 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4215 } 4216 } 4217 "display": { 4218 "name": "My Client Display Name", 4219 "uri": "https://client.foo/" 4220 }, 4221 } 4222 } 4224 When the verifier receives the Detached-JWS header, it MUST parse and 4225 validate the JWS object. The signature MUST be validated against the 4226 expected key of the signer. All required fields MUST be present and 4227 their values MUST be valid. If the HTTP message request contains a 4228 body, the verifier MUST calculate the hash of body just as the signer 4229 does, with no normalization or transformation of the request. 4231 7.3.4. Attached JWS 4233 This method is indicated by "jws" in the "proof" field. A JWS 4234 [RFC7515] object is created as follows: 4236 The JOSE header MUST contain the "kid" parameter of the key bound to 4237 this client instance for this request. The "alg" parameter MUST be 4238 set to a value appropriate for the key identified by kid and MUST NOT 4239 be "none". 4241 To protect the request, the JWS header MUST contain the following 4242 additional parameters. 4244 typ (string) The type header, value "gnap-binding+jws". 4246 htm (string) The HTTP Method used to make this request, as an 4247 uppercase ASCII string. 4249 uri (string) The HTTP URI used for this request, including all path 4250 and query components and no fragment component. 4252 created (integer) A timestamp of when the signature was created, in 4253 integer seconds since UNIX Epoch 4255 ath (string) When a request is bound to an access token, the access 4256 token hash value. The value MUST be the result of Base64url 4257 encoding (with no padding) the SHA-256 digest of the ASCII 4258 encoding of the associated access token's value. 4260 If the HTTP request has a message body, such as an HTTP POST or PUT 4261 method, the payload of the JWS object is the JSON serialized body of 4262 the request, and the object is signed according to JWS and serialized 4263 into compact form [RFC7515]. The client instance presents the JWS as 4264 the body of the request along with a content type of "application/ 4265 jose". The AS MUST extract the payload of the JWS and treat it as 4266 the request body for further processing. 4268 If the request being made does not have a message body, such as an 4269 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 4270 over an empty payload and passed in the "Detached-JWS" header as 4271 described in Section 7.3.3. 4273 In this example, the JOSE header contains the following parameters: 4275 { 4276 "alg": "RS256", 4277 "kid": "gnap-rsa", 4278 "uri": "https://server.example.com/gnap", 4279 "htm": "POST", 4280 "typ": "gnap-binding+jwsd", 4281 "created": 1618884475 4282 } 4284 The request body, used as the JWS Payload, is the following JSON 4285 object: 4287 NOTE: '\' line wrapping per RFC 8792 4289 { 4290 "access_token": { 4291 "access": [ 4292 "dolphin-metadata" 4293 ] 4294 }, 4295 "interact": { 4296 "start": ["redirect"], 4297 "finish": { 4298 "method": "redirect", 4299 "uri": "https://client.foo/callback", 4300 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4301 } 4302 }, 4303 "client": { 4304 "proof": "jws", 4305 "key": { 4306 "jwk": { 4307 "kid": "gnap-rsa", 4308 "kty": "RSA", 4309 "e": "AQAB", 4310 "alg": "RS256", 4311 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4312 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4313 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4314 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4315 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4316 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4317 } 4318 } 4319 "display": { 4320 "name": "My Client Display Name", 4321 "uri": "https://client.foo/" 4322 }, 4323 }, 4324 "subject": { 4325 "formats": ["iss_sub", "opaque"] 4326 } 4327 } 4329 This leads to the following full HTTP request message: 4331 NOTE: '\' line wrapping per RFC 8792 4333 POST /gnap HTTP/1.1 4334 Host: server.example.com 4335 Content-Type: application/jose 4336 Content-Length: 1047 4338 eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ 4339 raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ 4340 R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ 4341 ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\ 4342 0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\ 4343 Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\ 4344 CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\ 4345 cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\ 4346 KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\ 4347 ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\ 4348 ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\ 4349 Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\ 4350 gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\ 4351 5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\ 4352 nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\ 4353 akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\ 4354 xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\ 4355 BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\ 4356 XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\ 4357 YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ 4358 gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ 4359 FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ 4360 AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ 4361 c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ 4362 vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ 4363 u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ 4364 LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ 4365 PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ 4366 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 4368 [[ See issue #109 (https://github.com/ietf-wg-gnap/gnap-core- 4369 protocol/issues/109) ]] 4371 When the verifier receives an attached JWS request, it MUST parse and 4372 validate the JWS object. The signature MUST be validated against the 4373 expected key of the signer. All required fields MUST be present and 4374 their values MUST be valid. If the HTTP message request contains a 4375 body, the verifier MUST decode the payload of the JWS object and 4376 treat this as the HTTP message body. 4378 8. Resource Access Rights 4380 GNAP provides a rich structure for describing the protected resources 4381 hosted by RSs and accessed by client software. This structure is 4382 used when the client instance requests an access token (Section 2.1) 4383 and when an access token is returned (Section 3.2). 4385 The root of this structure is a JSON array. The elements of the JSON 4386 array represent rights of access that are associated with the the 4387 access token. The resulting access is the union of all elements 4388 within the array. 4390 The access associated with the access token is described using 4391 objects that each contain multiple dimensions of access. Each object 4392 contains a REQUIRED "type" property that determines the type of API 4393 that the token is used for. 4395 type (string) The type of resource request as a string. This field 4396 MAY define which other fields are allowed in the request object. 4397 This field is REQUIRED. 4399 The value of the "type" field is under the control of the AS. This 4400 field MUST be compared using an exact byte match of the string value 4401 against known types by the AS. The AS MUST ensure that there is no 4402 collision between different authorization data types that it 4403 supports. The AS MUST NOT do any collation or normalization of data 4404 types during comparison. It is RECOMMENDED that designers of 4405 general-purpose APIs use a URI for this field to avoid collisions 4406 between multiple API types protected by a single AS. 4408 While it is expected that many APIs will have their own properties, a 4409 set of common properties are defined here. Specific API 4410 implementations SHOULD NOT re-use these fields with different 4411 semantics or syntax. The available values for these properties are 4412 determined by the API being protected at the RS. 4414 actions (array of strings) The types of actions the client instance 4415 will take at the RS as an array of strings. For example, a client 4416 instance asking for a combination of "read" and "write" access. 4418 locations (array of strings) The location of the RS as an array of 4419 strings. These strings are typically URIs identifying the 4420 location of the RS. 4422 datatypes (array of strings) The kinds of data available to the 4423 client instance at the RS's API as an array of strings. For 4424 example, a client instance asking for access to raw "image" data 4425 and "metadata" at a photograph API. 4427 identifier (string) A string identifier indicating a specific 4428 resource at the RS. For example, a patient identifier for a 4429 medical API or a bank account number for a financial API. 4431 privileges (array of strings) The types or levels of privilege being 4432 requested at the resource. For example, a client instance asking 4433 for administrative level access, or access when the resource owner 4434 is no longer online. 4436 The following non-normative example is describing three kinds of 4437 access (read, write, delete) to each of two different locations and 4438 two different data types (metadata, images) for a single access token 4439 using the fictitious "photo-api" type definition. 4441 "access": [ 4442 { 4443 "type": "photo-api", 4444 "actions": [ 4445 "read", 4446 "write", 4447 "delete" 4448 ], 4449 "locations": [ 4450 "https://server.example.net/", 4451 "https://resource.local/other" 4452 ], 4453 "datatypes": [ 4454 "metadata", 4455 "images" 4456 ] 4457 } 4458 ] 4460 The access requested for a given object when using these fields is 4461 the cross-product of all fields of the object. That is to say, the 4462 object represents a request for all "actions" listed to be used at 4463 all "locations" listed for all possible "datatypes" listed within the 4464 object. Assuming the request above was granted, the client instance 4465 could assume that it would be able to do a "read" action against the 4466 "images" on the first server as well as a "delete" action on the 4467 "metadata" of the second server, or any other combination of these 4468 fields, using the same access token. 4470 To request a different combination of access, such as requesting one 4471 of the possible "actions" against one of the possible "locations" and 4472 a different choice of possible "actions" against a different one of 4473 the possible "locations", the client instance can include multiple 4474 separate objects in the "resources" array. The following non- 4475 normative example uses the same fictitious "photo-api" type 4476 definition to request a single access token with more specifically 4477 targeted access rights by using two discrete objects within the 4478 request. 4480 "access": [ 4481 { 4482 "type": "photo-api", 4483 "actions": [ 4484 "read" 4485 ], 4486 "locations": [ 4487 "https://server.example.net/" 4488 ], 4489 "datatypes": [ 4490 "images" 4491 ] 4492 }, 4493 { 4494 "type": "photo-api", 4495 "actions": [ 4496 "write", 4497 "delete" 4498 ], 4499 "locations": [ 4500 "https://resource.local/other" 4501 ], 4502 "datatypes": [ 4503 "metadata" 4504 ] 4505 } 4506 ] 4508 The access requested here is for "read" access to "images" on one 4509 server while simultaneously requesting "write" and "delete" access 4510 for "metadata" on a different server, but importantly without 4511 requesting "write" or "delete" access to "images" on the first 4512 server. 4514 It is anticipated that API designers will use a combination of common 4515 fields defined in this specification as well as fields specific to 4516 the API itself. The following non-normative example shows the use of 4517 both common and API-specific fields as part of two different 4518 fictitious API "type" values. The first access request includes the 4519 "actions", "locations", and "datatypes" fields specified here as well 4520 as the API-specific "geolocation" field. The second access request 4521 includes the "actions" and "identifier" fields specified here as well 4522 as the API-specific "currency" field. 4524 "access": [ 4525 { 4526 "type": "photo-api", 4527 "actions": [ 4528 "read", 4529 "write" 4530 ], 4531 "locations": [ 4532 "https://server.example.net/", 4533 "https://resource.local/other" 4534 ], 4535 "datatypes": [ 4536 "metadata", 4537 "images" 4538 ], 4539 "geolocation": [ 4540 { lat: -32.364, lng: 153.207 }, 4541 { lat: -35.364, lng: 158.207 } 4542 ] 4543 }, 4544 { 4545 "type": "financial-transaction", 4546 "actions": [ 4547 "withdraw" 4548 ], 4549 "identifier": "account-14-32-32-3", 4550 "currency": "USD" 4551 } 4552 ] 4554 If this request is approved, the resulting access token 4555 (Section 3.2.1)'s access rights will be the union of the requested 4556 types of access for each of the two APIs, just as above. 4558 8.1. Requesting Resources By Reference 4560 Instead of sending an object describing the requested resource 4561 (Section 8), access rights MAY be communicated as a string known to 4562 the AS or RS representing the access being requested. Each string 4563 SHOULD correspond to a specific expanded object representation at the 4564 AS. 4566 "access": [ 4567 "read", "dolphin-metadata", "some other thing" 4568 ] 4569 This value is opaque to the client instance and MAY be any valid JSON 4570 string, and therefore could include spaces, unicode characters, and 4571 properly escaped string sequences. However, in some situations the 4572 value is intended to be seen and understood by the client software's 4573 developer. In such cases, the API designer choosing any such human- 4574 readable strings SHOULD take steps to ensure the string values are 4575 not easily confused by a developer, such as by limiting the strings 4576 to easily disambiguated characters. 4578 This functionality is similar in practice to OAuth 2.0's "scope" 4579 parameter [RFC6749], where a single string represents the set of 4580 access rights requested by the client instance. As such, the 4581 reference string could contain any valid OAuth 2.0 scope value as in 4582 Appendix D.5. Note that the reference string here is not bound to 4583 the same character restrictions as in OAuth 2.0's "scope" definition. 4585 A single "access" array MAY include both object-type and string-type 4586 resource items. In this non-normative example, the client instance 4587 is requesting access to a "photo-api" and "financial-transaction" API 4588 type as well as the reference values of "read", "dolphin-metadata", 4589 and "some other thing". 4591 "access": [ 4592 { 4593 "type": "photo-api", 4594 "actions": [ 4595 "read", 4596 "write", 4597 "delete" 4598 ], 4599 "locations": [ 4600 "https://server.example.net/", 4601 "https://resource.local/other" 4602 ], 4603 "datatypes": [ 4604 "metadata", 4605 "images" 4606 ] 4607 }, 4608 "read", 4609 "dolphin-metadata", 4610 { 4611 "type": "financial-transaction", 4612 "actions": [ 4613 "withdraw" 4614 ], 4615 "identifier": "account-14-32-32-3", 4616 "currency": "USD" 4617 }, 4618 "some other thing" 4619 ] 4621 The requested access is the union of all elements of the array, 4622 including both objects and reference strings. 4624 9. Discovery 4626 By design, the protocol minimizes the need for any pre-flight 4627 discovery. To begin a request, the client instance only needs to 4628 know the endpoint of the AS and which keys it will use to sign the 4629 request. Everything else can be negotiated dynamically in the course 4630 of the protocol. 4632 However, the AS can have limits on its allowed functionality. If the 4633 client instance wants to optimize its calls to the AS before making a 4634 request, it MAY send an HTTP OPTIONS request to the grant request 4635 endpoint to retrieve the server's discovery information. The AS MUST 4636 respond with a JSON document containing the following information: 4638 grant_request_endpoint (string) REQUIRED. The location of the AS's 4639 grant request endpoint. The location MUST be a URL [RFC3986] with 4640 a scheme component that MUST be https, a host component, and 4641 optionally, port, path and query components and no fragment 4642 components. This URL MUST match the URL the client instance used 4643 to make the discovery request. 4645 interaction_start_modes_supported (array of strings) OPTIONAL. A 4646 list of the AS's interaction start methods. The values of this 4647 list correspond to the possible values for the interaction start 4648 section (Section 2.5.1) of the request. 4650 interaction_finish_methods_supported (array of strings) OPTIONAL. A 4651 list of the AS's interaction finish methods. The values of this 4652 list correspond to the possible values for the method element of 4653 the interaction finish section (Section 2.5.2) of the request. 4655 key_proofs_supported (array of strings) OPTIONAL. A list of the 4656 AS's supported key proofing mechanisms. The values of this list 4657 correspond to possible values of the "proof" field of the key 4658 section (Section 7.1) of the request. 4660 subject_formats_supported (array of strings) OPTIONAL. A list of 4661 the AS's supported subject identifier types. The values of this 4662 list correspond to possible values of the subject identifier 4663 section (Section 2.2) of the request. 4665 assertions_supported (array of strings) OPTIONAL. A list of the 4666 AS's supported assertion formats. The values of this list 4667 correspond to possible values of the subject assertion section 4668 (Section 2.2) of the request. 4670 The information returned from this method is for optimization 4671 purposes only. The AS MAY deny any request, or any portion of a 4672 request, even if it lists a capability as supported. For example, a 4673 given client instance can be registered with the "mtls" key proofing 4674 mechanism, but the AS also returns other proofing methods, then the 4675 AS will deny a request from that client instance using a different 4676 proofing mechanism. 4678 9.1. RS-first Method of AS Discovery 4680 If the client instance calls an RS without an access token, or with 4681 an invalid access token, the RS MAY respond to the client instance 4682 with an authentication header indicating that GNAP needs to be used 4683 to access the resource. The address of the GNAP endpoint MUST be 4684 sent in the "as_uri" parameter. The RS MAY additionally return a 4685 resource reference that the client instance MAY use in its access 4686 token request. This resource reference MUST be sufficient for at 4687 least the action the client instance was attempting to take at the RS 4688 and MAY be more powerful. The means for the RS to determine the 4689 resource reference are out of scope of this specification, but some 4690 dynamic methods are discussed in 4691 [I-D.draft-ietf-gnap-resource-servers]. The content of the resource 4692 reference is opaque to the client instance. 4694 NOTE: '\' line wrapping per RFC 8792 4696 WWW-Authenticate: \ 4697 GNAP as_uri=https://server.example/tx,access=FWWIKYBQ6U56NL1 4699 The client instance then makes a request to the "as_uri" as described 4700 in Section 2, with the value of "access" as one of the members of the 4701 "access" array in the "access_token" portion of the request. The 4702 client instance MAY request additional resources and other 4703 information. The client instance MAY request multiple access tokens. 4705 In this non-normative example, the client instance is requesting a 4706 single access token using the resource reference "FWWIKYBQ6U56NL1" 4707 received from the RS in addition to the "dolphin-metadata" resource 4708 reference that the client instance has been configured with out of 4709 band. 4711 POST /tx HTTP/1.1 4712 Host: server.example.com 4713 Content-Type: application/json 4714 Signature-Input: sig1=... 4715 Signature: sig1=... 4716 Digest: sha256=... 4718 { 4719 "access_token": { 4720 "access": [ 4721 "FWWIKYBQ6U56NL1", 4722 "dolphin-metadata" 4723 ] 4724 }, 4725 "client": "KHRS6X63AJ7C7C4AZ9AO" 4726 } 4728 If issued, the resulting access token would contain sufficient access 4729 to be used at both referenced resources. 4731 10. Acknowledgements 4733 The editors would like to thank the feedback of the following 4734 individuals for their reviews, implementations, and contributions: 4735 Aeke Axeland, Aaron Parecki, Adam Omar Oueidat, Annabelle Backman, 4736 Dick Hardt, Dmitri Zagidulin, Dmitry Barinov, Fabien Imbault, Francis 4737 Pouatcha, George Fletcher, Haardik Haardik, Hamid Massaoud, Jacky 4738 Yuan, Joseph Heenan, Justin Richer, Kathleen Moriarty, Mike Jones, 4739 Mike Varley, Nat Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya. 4741 The editors would also like to thank the GNAP working group design 4742 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 4743 and Justin Richer, who incorporated elements from the XAuth and XYZ 4744 proposals to create the first version of this document. 4746 In addition, the editors would like to thank Aaron Parecki and Mike 4747 Jones for insights into how to integrate identity and authentication 4748 systems into the core protocol, and Justin Richer and Dick Hardt for 4749 the use cases, diagrams, and insights provided in the XYZ and XAuth 4750 proposals that have been incorporated here. The editors would like 4751 to especially thank Mike Varley and the team at SecureKey for 4752 feedback and development of early versions of the XYZ protocol that 4753 fed into this standards work. 4755 11. IANA Considerations 4757 [[ TBD: There are a lot of items in the document that are expandable 4758 through the use of value registries. ]] 4760 12. Security Considerations 4762 12.1. TLS Protection in Transit 4764 All requests in GNAP have to be made over TLS or equivalent as 4765 outlined in [BCP195] to protect the contents of the request and 4766 response from manipulation and interception by an attacker. This 4767 includes all requests from a client instance to the AS, all requests 4768 from the client instance to an RS, any requests back to a client 4769 instance such as the push-based interaction finish method, and any 4770 back-end communications such as from an RS to an AS as described in 4771 [I-D.draft-ietf-gnap-resource-servers]. Additionally, all requests 4772 between a browser and other components, such as during redirect-based 4773 interaction, need to be made over TLS or use equivalent protection. 4775 Even though requests from the client instance to the AS are signed, 4776 the signature method alone does not protect the request from 4777 interception by an attacker. TLS protects the response as well as 4778 the request, preventing an attacker from intercepting requested 4779 information as it is returned. This is particularly important in the 4780 core protocol for security artifacts such as nonces and for personal 4781 information such as subject information. 4783 The use of key-bound access tokens does not negate the requirement 4784 for protecting calls to the RS with TLS. While the keys and 4785 signatures associated a bound access token will prevent an attacker 4786 from using a stolen token, without TLS an attacker would be able to 4787 watch the data being sent to the RS and returned from the RS during 4788 legitimate use of the client instance under attack. Additionally, 4789 without TLS an attacker would be able to profile the calls made 4790 between the client instance and RS, possibly gaining information 4791 about the functioning of the API between the client software and RS 4792 software that would be otherwise unknown to the attacker. 4794 TLS or equivalent protection also needs to be used between the 4795 browser and any other components. This applies during initial 4796 redirects to an AS's components during interaction, during any 4797 interaction with the resource owner, and during any redirect back to 4798 the client instance. Without TLS protection on these portions of the 4799 process, an attacker could wait for a valid request to start and then 4800 take over the resource owner's interaction session. 4802 12.2. Protection of Client Instance Key Material 4804 Client instances are identified by their unique keys, and anyone with 4805 access to a client instance's key material will be able to 4806 impersonate that client instance to all parties. This is true for 4807 both calls to the AS as well as calls to an RS using a key-bound 4808 access token. 4810 Different types of client software have different methods available 4811 for creating, managing, and registering keys. GNAP explicitly allows 4812 for ephemeral clients, such as SPAs, and single-user clients, such as 4813 mobile applications, to create and present their own keys during the 4814 initial grant request. The client software can securely generate a 4815 keypair on-device and present the public key, along with proof of 4816 holding that public key, to the AS as part of the initial request. 4817 To facilitate trust in these ephemeral keys, GNAP further allows for 4818 an extensible set of client information to be passed with the 4819 request. This information can include device posture and third-party 4820 attestations of the client software's provenance and authenticity, 4821 depending on the needs and capabilities of the client software and 4822 its deployment. 4824 From GNAP's perspective, each distinct key is a different client 4825 instance. However, multiple client instances can be grouped together 4826 by an AS policy and treated similarly to each other. For instance, 4827 if an AS knows of several different keys for different servers within 4828 a cluster, the AS can decide that authorization of one of these 4829 servers applies to all other servers within the cluster. An AS that 4830 chooses to do this needs to be careful with how it groups different 4831 client keys together in its policy, since the breach of one instance 4832 would have direct effects on the others in the cluster. 4834 Additionally, if an end user controls multiple instances of a single 4835 type of client software, such as having an application installed on 4836 multiple devices, each of these instances is expected to have a 4837 separate key and be issued separate access tokens. However, if the 4838 AS is able to group these separate instances together as described 4839 above, it can streamline the authorization process for new instances 4840 of the same client software. For example, if two client instances 4841 can present proof of a valid installation of a piece of client 4842 software, the AS would be able to associate the approval of the first 4843 instance of this software to all related instances. The AS could 4844 then choose to bypass an explicit prompt of the resource owner for 4845 approval during authorization, since such approval has already been 4846 given. An AS doing such a process would need to take assurance 4847 measures that the different instances are in fact correlated and 4848 authentic, as well as ensuring the expected resource owner is in 4849 control of the client instance. 4851 Finally, if multiple instances of client software each have the same 4852 key, then from GNAP's perspective, these are functionally the same 4853 client instance as GNAP has no reasonable way to differentiate 4854 between them. This situation could happen if multiple instances 4855 within a cluster can securely share secret information among 4856 themselves. Even though there are multiple copies of the software, 4857 the shared key makes these copies all present as a single instance. 4858 It is considered bad practice to share keys between copies of 4859 software unless they are very tightly integrated with each other and 4860 can be closely managed. It is particularly bad practice to allow an 4861 end-user to copy keys between client instances and to willingly use 4862 the same key in multiple instances. 4864 12.3. Protection of Authorization Server 4866 The AS performs critical functions in GNAP, including authenticating 4867 client software, managing interactions with end-users to gather 4868 consent and provide notice, and issuing access tokens for client 4869 instances to present to resource servers. As such, protecting the AS 4870 is central to any GNAP deployment. 4872 If an attacker is able to gain control over an AS, they would be able 4873 to create fraudulent tokens and manipulate registration information 4874 to allow for malicious clients. These tokens and clients would be 4875 trusted by other components in the ecosystem under the protection of 4876 the AS. 4878 If the AS is using signed access tokens, an attacker in control of 4879 the AS's signing keys would be able to manufacture fraudulent tokens 4880 for use at RS's under the protection of the AS. 4882 If an attacker is able to impersonate an AS, they would be able to 4883 trick legitimate client instances into making signed requests for 4884 information which could potentially be proxied to a real AS. To 4885 combat this, all communications to the AS need to be made over TLS or 4886 its equivalent, and the software making the connection has to 4887 validate the certificate chain of the host it is connecting to. 4889 Consequently, protecting, monitoring, and auditing the AS is 4890 paramount to preserving the security of a GNAP-protected ecosystem. 4892 12.4. Symmetric and Asymmetric Client Instance Keys 4894 The cryptographic methods used by GNAP for key-proofing can support 4895 both asymmetric and symmetric cryptography, and can be extended to 4896 use a wide variety of mechanisms. While symmetric cryptographic 4897 systems have some benefits in speed and simplicity, they have a 4898 distinct drawback that both parties need access to the same key in 4899 order to do both signing and verification of the message. This means 4900 that when the client instance calls the AS to request a token, the AS 4901 needs to know the exact value of the client instance's key (or be 4902 able to derive it) in order to validate the key proof signature. 4903 With asymmetric keys, the client needs only to send its public key to 4904 the AS to allow for verification that the client holds the associated 4905 private key, regardless of whether that key was pre-registered or not 4906 with the AS. 4908 When used to bind to an access token, a key value must be known by 4909 the RS in order to validate the proof signature on the request. 4910 Common methods for communicating these proofing keys include putting 4911 information in a structured access token and allowing the RS to look 4912 up the associated key material against the value of the access token. 4913 With symmetric cryptography, both of these methods would expose the 4914 signing key to the RS, and in the case of an structured access token, 4915 potentially to any party that can see the access token itself unless 4916 the token's payload has been encrypted. Any of these parties would 4917 then be able to make calls using the access token by creating a valid 4918 signature. With asymmetric cryptography, the RS only needs to know 4919 the public key associated with the token in order to validate, and 4920 therefore cannot create any new calls. 4922 Symmetric keys also have the expected advantage of providing better 4923 protection against quantum threats in the future. Also, these types 4924 of keys (and their secure derivations) are widely supported among 4925 many cloud-based key management systems. 4927 While both signing approaches are allowed, GNAP treats these two 4928 classes of keys somewhat differently. Only the public portion of 4929 asymmetric keys are allowed to be sent by value in requests to the AS 4930 when establishing a connection. Since sending a symmetric key (or 4931 the private portion of an asymmetric key) would expose the signing 4932 material to any parties on the request path, including any attackers, 4933 sending these kinds of keys is prohibited. Symmetric keys can still 4934 be used by client instances, but only a reference to the key and not 4935 its value can be sent. This allows the AS to use pre-registered 4936 symmetric keys as well as key derivation schemes to take advantage of 4937 symmetric cryptography but without requiring key distribution at 4938 runtime, which would expose the keys in transit. 4940 Both the AS and client software can use systems such as hardware 4941 security modules to strengthen their key security storage and 4942 generation for both asymmetric and symmetric keys. 4944 12.5. Generation of Access Tokens 4946 The content of access tokens need to be such that only the generating 4947 AS would be able to create them, and the contents cannot be 4948 manipulated by an attacker to gain different or additional access 4949 rights. 4951 One method for accomplishing this is to use a cryptographically 4952 random value for the access token, generated by the AS using a secure 4953 randomization function with sufficiently high entropy. The odds of 4954 an attacker guessing the output of the randomization function to 4955 collide with a valid access token are exceedingly small, and even 4956 then the attacker would not have any control over what the access 4957 token would represent since that information would be held close by 4958 the AS. 4960 Another method for accomplishing this is to use a structured token 4961 that is cryptographically signed. In this case, the payload of the 4962 access token declares to the RS what the token is good for, but the 4963 signature applied by the AS during token generation covers this 4964 payload. Only the AS can create such a signature and therefore only 4965 the AS can create such a signed token. The odds of an attacker being 4966 able to guess a signature value with a useful payload are exceedingly 4967 small. This technique only works if all targeted RS's check the 4968 signature of the access token. Any RS that does not validate the 4969 signature of all presented tokens would be susceptible to injection 4970 of a modified or falsified token. Furthermore, an AS has to 4971 carefully protect the keys used to sign access tokens, since anyone 4972 with access to these signing keys would be able to create seemingly- 4973 valid access tokens using them. 4975 12.6. Bearer Access Tokens 4977 Bearer access tokens can be used by any party that has access to the 4978 token itself, without any additional information. As a natural 4979 consequence, any RS that a bearer token is presented to has the 4980 technical capability of presenting that bearer token to another RS, 4981 as long as the token is valid. It also means that any party that is 4982 able capture of the token value in storage or in transit is able to 4983 use the access token. While bearer tokens are inherently simpler, 4984 this simplicity has been misapplied and abused in making needlessly 4985 insecure systems. 4987 In GNAP, key-bound access tokens are the default due to their higher 4988 security properties. While bearer tokens can be used in GNAP, their 4989 use should be limited onto to cases where the simplicity benefits 4990 outweigh the significant security downsides. 4992 12.7. Key-Bound Token Access Tokens 4994 Key-bound access tokens, as the name suggests, are bound to a 4995 specific key and must be presented along with proof of that key 4996 during use. The key itself is not presented at the same time as the 4997 token, so even if a token value is captured, it cannot be used to 4998 make a new request. This is particularly true for an RS, which will 4999 see the token value but will not see the keys used to make the 5000 request. 5002 Key-bound access tokens provide this additional layer of protection 5003 only when the RS checks the signature of the message presented with 5004 the token. Acceptance of an invalid presentation signature, or 5005 failure to check the signature entirely, would allow an attacker to 5006 make calls with a captured access token without having access to the 5007 related signing key material. 5009 In addition to validating the signature of the presentation message 5010 itself, the RS also needs to ensure that the signing key used is 5011 appropriate for the presented token. If an RS does not ensure that 5012 the right keys were used to sign a message with a specific token, an 5013 attacker would be able to capture an access token and sign the 5014 request with their own keys, thereby negating the benefits of using 5015 key-bound access tokens. 5017 The RS also needs to ensure that a sufficient portions of the message 5018 are covered by the signature. Any items outside the signature could 5019 still affect the API's processing decisions, but these items would 5020 not be strongly bound to the token presentation. As such, an 5021 attacker could capture a valid request, then manipulate portions of 5022 the request outside of the signature envelope in order to cause 5023 unwanted actions at the protected API. 5025 Some key-bound tokens are susceptible to replay attacks, depending on 5026 the details of the signing method used. If a signature method covers 5027 only portions of a given request, that same signature proof can be 5028 used by an attacker to make a similar call, potentially even varying 5029 elements that are outside of the protection of the signature. Key 5030 proofing mechanisms used with access tokens therefore need to use 5031 replay protection mechanisms covered under the signature such as a 5032 per-message nonce, a reasonably short time validity window, or other 5033 uniqueness constraints. The details of using these will vary 5034 depending on the key proofing mechanism in use, but for example, HTTP 5035 Message Signatures has both a "created" and "nonce" signature 5036 parameter as well as the ability to cover significant portions of the 5037 HTTP message. 5039 12.8. Exposure of End-user Credentials to Client Instance 5041 As a delegation protocol, one of the main goals of GNAP is to prevent 5042 the client software from being exposed to any credentials or 5043 information about the end-user or resource owner as a requirement of 5044 the delegation process. By using the variety of interaction 5045 mechanisms, the resource owner can interact with the AS without ever 5046 authenticating to the client software, and without the client 5047 software having to impersonate the resource owner through replay of 5048 their credentials. 5050 Consequently, no interaction methods defined in the GNAP core require 5051 the end-user to enter their credentials, but it is technologically 5052 possible for an extension to be defined to carry such values. Such 5053 an extension would be dangerous as it would allow rogue client 5054 software to directly collect, store, and replay the end-user's 5055 credentials outside of any legitimate use within a GNAP request. 5057 The concerns of such an extension could be mitigated through use of a 5058 challenge and response unlocked by the end user's credentials. For 5059 example, the AS presents a challenge as part of an interaction start 5060 method, and the client instance signs that challenge using a key 5061 derived from a password presented by the end user. It would be 5062 possible for the client software to collect this password in a secure 5063 software enclave without exposing the password to the rest of the 5064 client software or putting it across the wire to the AS. The AS can 5065 validate this challenge response against a known password for the 5066 identified end user. While an approach such as this does not remove 5067 all of the concerns surrounding such a password-based scheme, it is 5068 at least possible to implement in a more secure fashion than simply 5069 collecting and replaying the password. Even so, such schemes should 5070 only ever be used by trusted clients due to the ease of abusing them. 5072 12.9. Mixing Up Authorization Servers 5074 If a client instance is able to work with multiple AS's 5075 simultaneously, it is more possible for an attacker to add a 5076 compromised AS to the client instance's configuration and cause the 5077 client software to start a request at the compromised AS. This AS 5078 could then proxy the client's request to a valid AS in order to 5079 attempt to get the resource owner to approve access for the 5080 legitimate client instance. 5082 A client instance needs to always be aware of which AS it is talking 5083 to throughout a grant process, and ensure that any callback for one 5084 AS does not get conflated with the callback to different AS. The 5085 interaction finish hash calculate allows a client instance to protect 5086 against this kind of substitution, but only if the client instance 5087 validates the hash. If the client instance does not use an 5088 interaction finish method or does not check the interaction finish 5089 hash value, the compromised AS can be granted a valid access token on 5090 behalf of the resource owner. See [attack-surfaces] for details of 5091 one such attack, which has been since addressed in this document by 5092 including the grant endpoint in the interaction hash calculation. 5093 The client instance still needs to validate the hash for the attack 5094 to be prevented. 5096 12.10. Processing of Client-Presented User Information 5098 GNAP allows the client instance to present assertions and identifiers 5099 of the current user to the AS as part of the initial request. This 5100 information should only ever be taken by the AS as a hint, since the 5101 AS has no way to tell if the represented person is present at the 5102 client software, without using an interaction mechanism. This 5103 information does not guarantee the given user is there, but it does 5104 constitute a statement by the client software that the AS can take 5105 into account. 5107 For example, if a specific user is claimed to be present prior to 5108 interaction, but a different user is shown to be present during 5109 interaction, the AS can either determine this to be an error or 5110 signal to the client instance through returned subject information 5111 that the current user has changed from what the client instance 5112 thought. This user information can also be used by the AS to 5113 streamline the interaction process when the user is present. For 5114 example, instead of having the user type in their account identifier 5115 during interaction at a redirected URL, the AS can immediately 5116 challenge the user for their account credentials. Alternatively, if 5117 an existing session is detected, the AS can determine that it matches 5118 the identifier provided by the client and subsequently skip an 5119 explicit authentication event by the resource owner. 5121 In cases where the AS trusts the client software more completely, due 5122 to policy or by previous approval of a given client instance, the AS 5123 can take this user information as a statement that the user is 5124 present and could issue access tokens and release subject information 5125 without interaction. The AS should only take such action in very 5126 limited circumstances, as a client instance could assert whatever it 5127 likes for the user's identifiers in its request. 5129 When a client instance presents an assertion to the AS, the AS needs 5130 to evaluate that assertion. Since the AS is unlikely to be the 5131 intended audience of an assertion held by the client software, the AS 5132 will need to evaluate the assertion in a different context. Even in 5133 this case, the AS can still evaluate that the assertion was generated 5134 by a trusted party, was appropriately signed, and is within any time 5135 validity windows stated by the assertion. If the client instance's 5136 audience identifier is known to the AS and can be associated with the 5137 client instance's presented key, the AS can also evaluate that the 5138 appropriate client instance is presenting the claimed assertion. All 5139 of this will prevent an attacker from presenting a manufactured 5140 assertion, or one captured from an untrusted system. However, 5141 without validating the audience of the assertion, a captured 5142 assertion could be presented by the client instance to impersonate a 5143 given end user. In such cases, the assertion offers little more 5144 protection than a simple identifier would. 5146 A special case exists where the AS is the generator of the assertion 5147 being presented by the client instance. In these cases, the AS can 5148 validate that it did issue the assertion and it is associated with 5149 the client instance presenting the assertion. 5151 12.11. Client Instance Pre-registration 5153 Each client instance is identified by its own unique key, and for 5154 some kinds of client software such as a web server or backend system, 5155 this identification can be facilitated by registering a single key 5156 for a piece of client software ahead of time. This registration can 5157 be associated with a set of display attributes to be used during the 5158 authorization process, identifying the client software to the user. 5159 In these cases, it can be assumed that only one instance of client 5160 software will exist, likely to serve many different users. 5162 A client's registration record needs to include its identifying key. 5163 Furthermore, it is the case that any clients using symmetric 5164 cryptography for key proofing mechanisms need to have their keys pre- 5165 registered. The registration should also include any information 5166 that would aid in the authorization process, such as a display name 5167 and logo. The registration record can also limit a given client to 5168 ask for certain kinds of information and access, or be limited to 5169 specific interaction mechanisms at runtime. 5171 It also is sensible to pre-register client instances when the 5172 software is acting on its own behalf, without the need for a runtime 5173 approval by a resource owner or any interaction with an end-user. In 5174 these cases, an AS needs to rest on the trust decisions that have 5175 been determined prior to runtime in determining what rights and 5176 tokens to grant to a given client instance. 5178 However, it does not make sense to pre-register many types of 5179 clients. Single-page applications (SPAs) and mobile/desktop 5180 applications in particular present problems with pre-registration. 5181 For SPAs, the instances are ephemeral in nature and long-term 5182 registration of a single instance leads to significant storage and 5183 management overhead at the AS. For mobile applications, each 5184 installation of the client software is a separate instance, and 5185 sharing a key among all instances would be detrimental to security as 5186 the compromise of any single installation would compromise all copies 5187 for all users. 5189 An AS can treat these classes of client software differently from 5190 each other, perhaps by allowing access to certain high-value APIs 5191 only to pre-registered known clients, or by requiring an active end- 5192 user delegation of authority to any client software not pre- 5193 registered. 5195 An AS can also provide warnings and caveats to resource owners during 5196 the authorization process, allowing the user to make an informed 5197 decision regarding the software they are authorizing. For example, 5198 if the AS has done vetting of the client software and this specific 5199 instance, it can present a different authorization screen compared to 5200 a client instance that is presenting all of its information at 5201 runtime. 5203 12.12. Client Instance Impersonation 5205 If client instances are allowed to set their own user-facing display 5206 information, such as a display name and website URL, a malicious 5207 client instance could impersonate legitimate client software for the 5208 purposes of tricking users into authorizing the malicious client. 5210 Requiring clients to pre-register does not fully mitigate this 5211 problem since many pre-registration systems have self-service portals 5212 for management of client registration, allowing authenticated 5213 developers to enter self-asserted information into the management 5214 portal. 5216 An AS can mitigate this by actively filtering all self-asserted 5217 values presented by client software, both dynamically as part of GNAP 5218 and through a registration portal, to limit the kinds of 5219 impersonation that would be done. 5221 An AS can also warn the resource owner about the provenance of the 5222 information it is displaying, allowing the resource owner to make a 5223 more informed delegation decision. For example, an AS can visually 5224 differentiate between a client instance that can be traced back to a 5225 specific developer's registration and an instance that has self- 5226 asserted its own key and display information. 5228 12.13. Interception of Information in the Browser 5230 Most information passed through the web-browser is susceptible to 5231 interception and possible manipulation by elements within the browser 5232 such as scripts loaded within pages. Information in the URL is 5233 exposed through browser and server logs, and can also leak to other 5234 parties through HTTP "Referrer" headers. 5236 GNAP's design limits the information passed directly through the 5237 browser, allowing for opaque URLs in most circumstances. For the 5238 redirect-based interaction finish mechanism, named query parameters 5239 are used to carry unguessable opaque values. For these, GNAP 5240 requires creation and validation of a cryptographic hash to protect 5241 the query parameters added to the URL and associate them with an 5242 ongoing grant process. The client instance has to properly validate 5243 this hash to prevent an attacker from injecting an interaction 5244 reference intended for a different AS or client instance. 5246 Several interaction start mechanisms use URLs created by the AS and 5247 passed to the client instance. While these URLs are opaque to the 5248 client instance, it's possible for the AS to include parameters, 5249 paths, and other pieces of information that could leak security data 5250 or be manipulated by a party in the middle of the transaction. 5252 12.14. Callback URL Manipulation 5254 The callback URL used in interaction finish mechanisms is defined by 5255 the client instance. This URL is opaque to the AS, but can contain 5256 information relevant to the client instance's operations. In 5257 particular, the client instance can include state information to 5258 allow the callback request to be associated with an ongoing grant 5259 request. 5261 Since this URL is exposed to the end-user's browser, it is 5262 susceptible to both logging and manipulation in transit before the 5263 request is made to the client software. As such, a client instance 5264 should never put security-critical or private information into the 5265 callback URL in a cleartext form. For example, if the client 5266 software includes a post-redirect target URL in its callback URL to 5267 the AS, this target URL could be manipulated by an attacker, creating 5268 an open redirector at the client. Instead, a client instance can use 5269 an unguessable identifier into the URL that can then be used by the 5270 client software to look up the details of the pending request. Since 5271 this approach requires some form of statefulness by the client 5272 software during the redirection process, clients that are not capable 5273 of holding state through a redirect should not use redirect-based 5274 interaction mechanisms. 5276 12.15. MTLS Deployment Patterns 5278 GNAP does not specify how a client instance's keys could be made 5279 known to the AS ahead of time. Public Key Infrastructure (PKI) can 5280 be used to manage the keys used by client instances when calling the 5281 AS, allowing the AS to trust a root key from a trusted authority. 5282 This method is particularly relevant to the MTLS signature method, 5283 where the client instance presents its certificate to the AS as part 5284 of the TLS connection. An AS using PKI to validate the MTLS 5285 connection would need to ensure that the presented certificate was 5286 issued by a trusted certificate authority before allowing the 5287 connection to continue. PKI-based certificates would allow a key to 5288 be revoked and rotated through management at the certificate 5289 authority without requiring additional registration or management at 5290 the AS. PKI has historically been difficult to deploy, especially at 5291 scale, but it remains an appropriate solution for systems where the 5292 required overhead is not an impediment. 5294 MTLS need not use a PKI backing, as self-signed certificates and 5295 certificates from untrusted authorities can still be presented as 5296 part of a TLS connection. In this case, the AS or RS would validate 5297 the connection but accept whatever certificate was presented by the 5298 client software. This specific certificate would then be bound to 5299 all future connections from that client software by being bound to 5300 the resulting access tokens. 5302 12.16. Interception of Responses from the AS 5304 Responses from the AS contain information vital to both the security 5305 and privacy operations of GNAP. This information includes nonces 5306 used in cryptographic calculations, subject identifiers, assertions, 5307 public keys, and information about what client software is requesting 5308 and was granted. 5310 In addition, if bearer tokens are used or keys are issued alongside a 5311 bound access token, the response from the AS contains all information 5312 necessary for use of the contained access token. Any party that is 5313 capable of viewing such a response, such as an intermediary proxy, 5314 would be able to exfiltrate and use this token. If the access token 5315 is instead bound to the client instance's presented key, 5316 intermediaries no longer have sufficient information to use the 5317 token. They can still, however, gain information about the end user 5318 as well as the actions of the client software. 5320 12.17. Key Distribution 5322 The keys for client instances could be distributed as part of the 5323 deployment process of instances of the client software. For example, 5324 an application installation framework could generate a keypair for 5325 each copy of client software, then both install it into the client 5326 software upon installation and registering that instance with the AS. 5328 Additionally, it's possible for the AS to generate keys to be used 5329 with access tokens that are separate from the keys used by the client 5330 instance to request tokens. In this method, the AS would generate 5331 the asymmetric keypair or symmetric key and return the entire key, 5332 including all private signing information, to the client instance 5333 alongside the access token itself. This approach would make 5334 interception of the return from the token endpoint equivalent to that 5335 of a bearer token, since all information required to use the access 5336 token would be present in the request. 5338 12.18. Interaction Finish Modes and Polling 5340 During the interaction process, the client instance usually hands 5341 control of the user experience over to another component, beit the 5342 system browser, another application, or some action the resource 5343 owner is instructed to take on another device. By using an 5344 interaction finish method, the client instance can be securely 5345 notified by the AS when the interaction is completed and the next 5346 phase of the protocol should occur. This process includes 5347 information that the client instance can use to validate the finish 5348 call from the AS and prevent some injection, session hijacking, and 5349 phishing attacks. 5351 Some types of client deployment are unable to receive an interaction 5352 finish message. Without an interaction finish method to notify it, 5353 the client instance will need to poll the grant continuation API 5354 while waiting for the resource owner to approve or deny the request. 5355 An attacker could take advantage of this situation by capturing the 5356 interaction start parameters and phishing a legitimate user into 5357 authorizing the attacker's waiting client instance, which would in 5358 turn have no way of associating the completed interaction with the 5359 start of the request. 5361 However, it is important to note that this pattern is practically 5362 indistinguishable from some legitimate use cases. For example, a 5363 smart device emits a code for the resource owner to enter on a 5364 separate device. The smart device has to poll because the expected 5365 behavior is that the interaction will take place on the separate 5366 device, without a way to return information to the original device's 5367 context. 5369 As such, developers need to weigh the risks of forgoing an 5370 interaction finish method against the deployment capabilities of the 5371 client software and its environment. Due to the increased security, 5372 an interaction finish method should be employed whenever possible. 5374 12.19. Storage of Information During Interaction and Continuation 5376 When starting an interactive grant request, a client application has 5377 a number of protocol elements that it needs to manage, including 5378 nonces, references, keys, access tokens, and other elements. During 5379 the interaction process, the client instance usually hands control of 5380 the user experience over to another component, beit the system 5381 browser, another application, or some action the resource owner is 5382 instructed to take on another device. In order for the client 5383 instance to make its continuation call, it will need to recall all of 5384 these protocol elements. Usually this means the client instance will 5385 need to store these protocol elements in some retrievable fashion. 5387 If the security protocol elements are stored on the end-user's 5388 device, such as in browser storage or in local application data 5389 stores, capture and exfiltration of this information could allow an 5390 attacker to continue a pending transaction instead of the client 5391 instance. Client software can make use of secure storage mechanisms, 5392 including hardware-based key and data storage, to prevent such 5393 exfiltration. 5395 Note that in GNAP, the client instance has to choose its interaction 5396 finish URL prior to making the first call to the AS. As such, the 5397 interaction finish URL will often have a unique identifier for the 5398 ongoing request, allowing the client instance to access the correct 5399 portion of its storage. Since this URL is passed to other parties 5400 and often used through a browser, this URL should not contain any 5401 security-sensitive information that would be valuable to an attacker, 5402 such as any token identifier, nonce, or user information. Instead, a 5403 cryptographically random value is suggested. 5405 12.20. Denial of Service (DoS) through Grant Continuation 5407 When a client instance starts off an interactive process, it will 5408 eventually need to continue the grant request in a subsequent message 5409 to the AS. It's possible for a naive client implementation to 5410 continuously send continuation requests to the AS while waiting for 5411 approval, especially if no interaction finish method is used. Such 5412 constant requests could overwhelm the AS's ability to respond to both 5413 these and other requests. 5415 To mitigate this for well-behaved client software, the continuation 5416 response contains a "wait" parameter that is intended to tell the 5417 client instance how long it should wait until making its next 5418 request. This value can be used to back off client software that is 5419 checking too quickly by returning increasing wait times for a single 5420 client instance. 5422 If client software ignores the "wait" value and makes its 5423 continuation calls too quickly, or if the client software assumes the 5424 absence of the "wait" values means it should poll immediately, the AS 5425 can choose to return errors to the offending client instance, 5426 including possibly canceling the ongoing grant request. With well- 5427 meaning client software these errors can indicate a need to change 5428 the client software's programmed behavior. 5430 12.21. Exhaustion of Random Value Space 5432 Several parts of the GNAP process make use of unguessable randomized 5433 values, such as nonces, tokens, and randomized URLs. Since these 5434 values are intended to be unique, a sufficiently powerful attacker 5435 could make a large number of requests to trigger generation of 5436 randomized values in an attempt to exhaust the random number 5437 generation space. While this attack is particularly applicable to 5438 the AS, client software could likewise be targeted by an attacker 5439 triggering new grant requests against an AS. 5441 To mitigate this, software can ensure that its random values are 5442 chosen from a significantly large pool that exhaustion of that pool 5443 is prohibitive for an attacker. Additionally, the random values can 5444 be time-boxed in such a way as their validity windows are reasonably 5445 short. Since many of the random values used within GNAP are used 5446 within limited portions of the protocol, it is reasonable for a 5447 particular random value to be valid for only a small amount of time. 5448 For example, the nonces used for interaction finish hash calculation 5449 need only to be valid while the client instance is waiting for the 5450 finish callback and can be functionally expired when the interaction 5451 has completed. Similarly, artifacts like access tokens and the 5452 interaction reference can be limited to have lifetimes tied to their 5453 functional utility. Finally, each different category of artifact 5454 (nonce, token, reference, identifier, etc.) can be generated from a 5455 separate random pool of values instead of a single global value 5456 space. 5458 13. Privacy Considerations 5460 The privacy considerations in this section are modeled after the list 5461 of privacy threats in [[RFC6973]], "Privacy Considerations for 5462 Internet Protocols", and either explain how these threats are 5463 mitigated or advise how the threats relate to GNAP. 5465 13.1. Surveillance 5467 Surveillance is the observation or monitoring of an individual's 5468 communications or activities. Surveillance can be conducted by 5469 observers or eavesdroppers at any point along the communications 5470 path. 5472 GNAP assumes the TLS protection used throughout the spec is intact. 5473 Without the protection of TLS, there are many points throughout the 5474 use of GNAP that would lead to possible surveillance. 5476 13.1.1. Surveillance by the Client 5478 The purpose of GNAP is to authorize clients to be able to access 5479 information on behalf of a user. So while it is expected that the 5480 client may be aware of the user's identity as well as data being 5481 fetched for that user, in some cases the extent of the client may be 5482 beyond what the user is aware of. For example, a client may be 5483 implemented as multiple distinct pieces of software, such as a 5484 logging service or a mobile app that reports usage data to an 5485 external backend service. 5487 13.1.2. Surveillance by the Authorization Server 5489 The role of the authorization server is to manage the authorization 5490 of client instances to protect access to the user's data. In this 5491 role, the authorization server is by definition aware of each 5492 authorization of a client instance by a user. When the authorization 5493 server shares user information with the client instance, it needs to 5494 make sure that it has the permission from that user to do so. 5496 Additionally, as part of the authorization grant process, the 5497 authorization server may be aware of which resource servers the 5498 client intends to use an access token at. However, it is possible to 5499 design a system using GNAP in which this knowledge is not made 5500 available to the authorization server, such as by avoiding the use of 5501 the "locations" object in the authorization request. 5503 If the authorization server's implementation of access tokens is such 5504 that it requires a resource server call back to the authorization 5505 server to validate them, then the authorization server will be aware 5506 of which resource servers are actively in use and by which users and 5507 which clients. To avoid this possibility, the authorization server 5508 would need to structure access tokens in such a way that they can be 5509 validated by the resource server without notifying the authorization 5510 server that the token is being validated. 5512 13.2. Stored Data 5514 Several parties in the GNAP process are expected to persist data at 5515 least temporarily, if not semi-permanently, for the normal 5516 functioning of the system. If compromised, this could lead to 5517 exposure of sensitive information. This section documents the 5518 potentially sensitive information each party in GNAP is expected to 5519 store for normal operation. Naturally it is possible that any party 5520 is storing information for longer than technically necessary of the 5521 protocol mechanics (such as audit logs, etc). 5523 The authorization server is expected to store subject identifiers for 5524 user indefinitely, in order to be able to include them in the 5525 responses to clients. The authorization server is also expected to 5526 store client key identifiers associated with display information 5527 about the client such as its name and logo. 5529 The client is expected to store its client instance key indefinitely, 5530 in order to authenticate to the authorization server for the normal 5531 functioning of the GNAP flows. Additionally, the client will be 5532 temporarily storing artifacts issued by the authorization server 5533 during a flow, and these artifacts SHOULD be discarded by the client 5534 when the transaction is complete. 5536 The resource server is not required to store any state for its normal 5537 operation. Depending on the implementation of access tokens, the 5538 resource server may need to cache public keys from the authorization 5539 server in order to validate access tokens. 5541 13.3. Intrusion 5543 Intrusion refers to the ability of various parties to send 5544 unsolicited messages or cause denial of service for unrelated 5545 parties. 5547 If the resource owner is different from the end user, there is an 5548 opportunity for the end user to cause unsolicited messages to be sent 5549 to the resource owner if the system prompts the resource owner for 5550 consent when an end user attempts to access their data. 5552 The format and contents of subject identifiers are intentionally not 5553 defined by GNAP. If the authorization server uses values for subject 5554 identifiers that are also identifiers for communication channels, 5555 (e.g. an email address or phone number), this opens up the 5556 possibility for a client to learn this information when it was not 5557 otherwise authorized to access this kind of data about the user. 5559 13.4. Correlation 5561 The threat of correlation is the combination of various pieces of 5562 information related to an individual in a way that defies their 5563 expectations of what others know about them. 5565 13.4.1. Correlation by Clients 5567 The biggest risk of correlation in GNAP is when an authorization 5568 server returns stable consistent user identifiers to multiple 5569 different applications. In this case, applications created by 5570 different parties would be able to correlate these user identifiers 5571 out of band in order to know which users they have in common. 5573 The most common example of this in practice is tracking for 5574 advertising purposes, such that client A shares their list of user 5575 IDs with an ad platform that is then able to retarget ads to 5576 applications created by other parties. In contrast, a positive 5577 example of correlation is a corporate acquisition where two 5578 previously unrelated clients now do need to be able to identify the 5579 same user between the two clients. 5581 13.4.2. Correlation by Resource Servers 5583 Unrelated resource servers also have an opportunity to correlate 5584 users if the authorization server includes stable user identifiers in 5585 access tokens or in access token introspection responses. 5587 In some cases a resource server may not actually need to be able to 5588 identify users, (such as a resource server providing access to a 5589 company cafeteria menu which only needs to validate whether the user 5590 is a current employee), so authorization servers should be thoughtful 5591 of when user identifiers are actually necessary to communicate to 5592 resource servers for the functionining of the system. 5594 13.4.3. Correlation by Authorization Servers 5596 Clients are expected to be identified by their client instance key. 5597 If a particular client instance key is used at more than one 5598 authorization server, this could open up the possibility for multiple 5599 unrelated authorization servers to correlate client instances. This 5600 is especially a problem in the common case where a client instance is 5601 used by a single individual, as it would allow the authorization 5602 servers to correlate that individual between them. If this is a 5603 concern of a client, the client should use distinct keys with each 5604 authorization server. 5606 13.5. Disclosure in Shared References 5608 Throughout many parts of GNAP, the parties pass shared references 5609 between each other, sometimes in place of the values themselves. For 5610 example the "interact_ref" value used throughout the flow. These 5611 references are intended to be random strings and should not contain 5612 any private or sensitive data that would potentially leak information 5613 between parties. 5615 14. References 5617 14.1. Normative References 5619 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 5620 "Recommendations for Secure Use of Transport Layer 5621 Security (TLS) and Datagram Transport Layer Security 5622 (DTLS)", May 2015, 5623 . 5625 [I-D.draft-ietf-gnap-resource-servers] 5626 Richer, J., Parecki, A., and F. Imbault, "Grant 5627 Negotiation and Authorization Protocol Resource Server 5628 Connections", Work in Progress, Internet-Draft, draft- 5629 ietf-gnap-resource-servers-00, 28 April 2021, 5630 . 5633 [I-D.ietf-httpbis-message-signatures] 5634 Backman, A., Richer, J., and M. Sporny, "HTTP Message 5635 Signatures", Work in Progress, Internet-Draft, draft-ietf- 5636 httpbis-message-signatures-06, 13 August 2021, 5637 . 5640 [I-D.ietf-oauth-rar] 5641 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 5642 Rich Authorization Requests", Work in Progress, Internet- 5643 Draft, draft-ietf-oauth-rar-07, 12 September 2021, 5644 . 5647 [I-D.ietf-oauth-signed-http-request] 5648 Richer, J., Bradley, J., and H. Tschofenig, "A Method for 5649 Signing HTTP Requests for OAuth", Work in Progress, 5650 Internet-Draft, draft-ietf-oauth-signed-http-request-03, 8 5651 August 2016, . 5654 [I-D.ietf-secevent-subject-identifiers] 5655 Backman, A. and M. Scurtescu, "Subject Identifiers for 5656 Security Event Tokens", Work in Progress, Internet-Draft, 5657 draft-ietf-secevent-subject-identifiers-08, 24 May 2021, 5658 . 5661 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 5662 C. Mortimore, "OpenID Connect Core 1.0 incorporating 5663 errata set 1", November 2014, 5664 . 5666 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5667 Requirement Levels", BCP 14, RFC 2119, 5668 DOI 10.17487/RFC2119, March 1997, 5669 . 5671 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 5672 RFC 3230, DOI 10.17487/RFC3230, January 2002, 5673 . 5675 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 5676 Resource Identifier (URI): Generic Syntax", STD 66, 5677 RFC 3986, DOI 10.17487/RFC3986, January 2005, 5678 . 5680 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 5681 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 5682 September 2009, . 5684 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 5685 RFC 6749, DOI 10.17487/RFC6749, October 2012, 5686 . 5688 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 5689 Framework: Bearer Token Usage", RFC 6750, 5690 DOI 10.17487/RFC6750, October 2012, 5691 . 5693 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 5694 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 5695 RFC 7234, DOI 10.17487/RFC7234, June 2014, 5696 . 5698 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 5699 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 5700 April 2015, . 5702 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 5703 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 5704 2015, . 5706 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 5707 DOI 10.17487/RFC7517, May 2015, 5708 . 5710 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5711 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5712 May 2017, . 5714 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 5715 Interchange Format", STD 90, RFC 8259, 5716 DOI 10.17487/RFC8259, December 2017, 5717 . 5719 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 5720 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 5721 and Certificate-Bound Access Tokens", RFC 8705, 5722 DOI 10.17487/RFC8705, February 2020, 5723 . 5725 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 5726 "Handling Long Lines in Content of Internet-Drafts and 5727 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 5728 . 5730 14.2. Informative References 5732 [attack-surfaces] 5733 Axeland, Å. and O. Oueidat, "Security Analysis of Attack 5734 Surfaces on the Grant Negotiation and Authorization 5735 Protocol", 2021, 5736 . 5738 [promise-theory] 5739 Burgess, M. and J. Bergstra, "Promise theory", January 5740 2014, . 5742 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 5743 Morris, J., Hansen, M., and R. Smith, "Privacy 5744 Considerations for Internet Protocols", RFC 6973, 5745 DOI 10.17487/RFC6973, July 2013, 5746 . 5748 Appendix A. Document History 5750 * -07 5752 - Replace user handle by opaque identifier 5754 - Added trust relationships 5756 - Added privacy considerations section 5758 - Added security considerations. 5760 * -06 5762 - Removed "capabilities" and "existing_grant" protocol fields. 5764 - Removed separate "instance_id" field. 5766 - Split "interaction_methods_supported" into 5767 "interaction_start_modes_supported" and 5768 "interaction_finish_methods_supported". 5770 - Added AS endpoint to hash calculation to fix mix-up attack. 5772 - Added "privileges" field to resource access request object. 5774 - Moved client-facing RS response back from GNAP-RS document. 5776 - Removed oauthpop key binding. 5778 - Removed dpop key binding. 5780 - Added example DID identifier. 5782 - Changed token response booleans to flag structure to match 5783 request. 5785 - Updated signature examples to use HTTP Message Signatures. 5787 * -05 5789 - Changed "interaction_methods" to 5790 "interaction_methods_supported". 5792 - Changed "key_proofs" to "key_proofs_supported". 5794 - Changed "assertions" to "assertions_supported". 5796 - Updated discovery and field names for subject formats. 5798 - Add an appendix to provide protocol rationale, compared to 5799 OAuth2. 5801 - Updated subject information definition. 5803 - Refactored the RS-centric components into a new document. 5805 - Updated cryptographic proof of possession methods to match 5806 current reference syntax. 5808 - Updated proofing language to use "signer" and "verifier" 5809 generically. 5811 - Updated cryptographic proof of possession examples. 5813 - Editorial cleanup and fixes. 5815 - Diagram cleanup and fixes. 5817 * -04 5819 - Updated terminology. 5821 - Refactored key presentation and binding. 5823 - Refactored "interact" request to group start and end modes. 5825 - Changed access token request and response syntax. 5827 - Changed DPoP digest field to 'htd' to match proposed FAPI 5828 profile. 5830 - Include the access token hash in the DPoP message. 5832 - Removed closed issue links. 5834 - Removed function to read state of grant request by client. 5836 - Closed issues related to reading and updating access tokens. 5838 * -03 5840 - Changed "resource client" terminology to separate "client 5841 instance" and "client software". 5843 - Removed OpenID Connect "claims" parameter. 5845 - Dropped "short URI" redirect. 5847 - Access token is mandatory for continuation. 5849 - Removed closed issue links. 5851 - Editorial fixes. 5853 * -02 5855 - Moved all "editor's note" items to GitHub Issues. 5857 - Added JSON types to fields. 5859 - Changed "GNAP Protocol" to "GNAP". 5861 - Editorial fixes. 5863 * -01 5865 - "updated_at" subject info timestamp now in ISO 8601 string 5866 format. 5868 - Editorial fixes. 5870 - Added Aaron and Fabien as document authors. 5872 * -00 5874 - Initial working group draft. 5876 Appendix B. Compared to OAuth 2.0 5878 GNAP's protocol design differs from OAuth 2.0's in several 5879 fundamental ways: 5881 1. *Consent and authorization flexibility:* 5883 OAuth 2.0 generally assumes the user has access to the a web 5884 browser. The type of interaction available is fixed by the grant 5885 type, and the most common interactive grant types start in the 5886 browser. OAuth 2.0 assumes that the user using the client 5887 software is the same user that will interact with the AS to 5888 approve access. 5890 GNAP allows various patterns to manage authorizations and 5891 consents required to fulfill this requested delegation, including 5892 information sent by the client instance, information supplied by 5893 external parties, and information gathered through the 5894 interaction process. GNAP allows a client instance to list 5895 different ways that it can start and finish an interaction, and 5896 these can be mixed together as needed for different use cases. 5897 GNAP interactions can use a browser, but don't have to. Methods 5898 can use inter-application messaging protocols, out-of-band data 5899 transfer, or anything else. GNAP allows extensions to define new 5900 ways to start and finish an interaction, as new methods and 5901 platforms are expected to become available over time. GNAP is 5902 designed to allow the end-user and the resource owner to be two 5903 different people, but still works in the optimized case of them 5904 being the same party. 5906 2. *Intent registration and inline negotiation:* 5908 OAuth 2.0 uses different "grant types" that start at different 5909 endpoints for different purposes. Many of these require 5910 discovery of several interrelated parameters. 5912 GNAP requests all start with the same type of request to the same 5913 endpoint at the AS. Next steps are negotiated between the client 5914 instance and AS based on software capabilities, policies 5915 surrounding requested access, and the overall context of the 5916 ongoing request. GNAP defines a continuation API that allows the 5917 client instance and AS to request and send additional information 5918 from each other over multiple steps. This continuation API uses 5919 the same access token protection that other GNAP-protected APIs 5920 use. GNAP allows discovery to optimize the requests but it isn't 5921 required thanks to the negotiation capabilities. 5923 3. *Client instances:* 5925 OAuth 2.0 requires all clients to be registered at the AS and to 5926 use a client_id known to the AS as part of the protocol. This 5927 client_id is generally assumed to be assigned by a trusted 5928 authority during a registration process, and OAuth places a lot 5929 of trust on the client_id as a result. Dynamic registration 5930 allows different classes of clients to get a client_id at 5931 runtime, even if they only ever use it for one request. 5933 GNAP allows the client instance to present an unknown key to the 5934 AS and use that key to protect the ongoing request. GNAP's 5935 client instance identifier mechanism allows for pre-registered 5936 clients and dynamically registered clients to exist as an 5937 optimized case without requiring the identifier as part of the 5938 protocol at all times. 5940 4. *Expanded delegation:* 5942 OAuth 2.0 defines the "scope" parameter for controlling access to 5943 APIs. This parameter has been coopted to mean a number of 5944 different things in different protocols, including flags for 5945 turning special behavior on and off, including the return of data 5946 apart from the access token. The "resource" parameter and RAR 5947 extensions (as defined in [I-D.ietf-oauth-rar]) expand on the 5948 "scope" concept in similar but different ways. 5950 GNAP defines a rich structure for requesting access, with string 5951 references as an optimization. GNAP defines methods for 5952 requesting directly-returned user information, separate from API 5953 access. This information includes identifiers for the current 5954 user and structured assertions. The core GNAP protocol makes no 5955 assumptions or demands on the format or contents of the access 5956 token, but the RS extension allows a negotiation of token formats 5957 between the AS and RS. 5959 5. *Cryptography-based security:* 5960 OAuth 2.0 uses shared bearer secrets, including the client_secret 5961 and access token, and advanced authentication and sender 5962 constraint have been built on after the fact in inconsistent 5963 ways. 5965 In GNAP, all communication between the client instance and AS is 5966 bound to a key held by the client instance. GNAP uses the same 5967 cryptographic mechanisms for both authenticating the client (to 5968 the AS) and binding the access token (to the RS and the AS). 5969 GNAP allows extensions to define new cryptographic protection 5970 mechanisms, as new methods are expected to become available over 5971 time. GNAP does not have a notion of "public clients" because 5972 key information can always be sent and used dynamically. 5974 6. *Privacy and usable security:* 5976 OAuth 2.0's deployment model assumes a strong binding between the 5977 AS and the RS. 5979 GNAP is designed to be interoperable with decentralized identity 5980 standards and to provide a human-centric authorization layer. In 5981 addition to the core protocol, GNAP that supports various 5982 patterns of communication between RSs and ASs through extensions. 5983 GNAP tries to limit the odds of a consolidation to just a handful 5984 of super-popular AS services. 5986 Appendix C. Component Data Models 5988 While different implementations of this protocol will have different 5989 realizations of all the components and artifacts enumerated here, the 5990 nature of the protocol implies some common structures and elements 5991 for certain components. This appendix seeks to enumerate those 5992 common elements. 5994 TBD: Client has keys, allowed requested resources, identifier(s), 5995 allowed requested subjects, allowed 5997 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 5998 client keys, policies 6000 TBD: Token has RO, user, client, resource list, RS list, 6002 Appendix D. Example Protocol Flows 6004 The protocol defined in this specification provides a number of 6005 features that can be combined to solve many different kinds of 6006 authentication scenarios. This section seeks to show examples of how 6007 the protocol would be applied for different situations. 6009 Some longer fields, particularly cryptographic information, have been 6010 truncated for display purposes in these examples. 6012 D.1. Redirect-Based User Interaction 6014 In this scenario, the user is the RO and has access to a web browser, 6015 and the client instance can take front-channel callbacks on the same 6016 device as the user. This combination is analogous to the OAuth 2.0 6017 Authorization Code grant type. 6019 The client instance initiates the request to the AS. Here the client 6020 instance identifies itself using its public key. 6022 POST /tx HTTP/1.1 6023 Host: server.example.com 6024 Content-Type: application/json 6025 Signature-Input: sig1=... 6026 Signature: sig1=... 6027 Digest: sha256=... 6029 { 6030 "access_token": { 6031 "access": [ 6032 { 6033 "actions": [ 6034 "read", 6035 "write", 6036 "dolphin" 6037 ], 6038 "locations": [ 6039 "https://server.example.net/", 6040 "https://resource.local/other" 6041 ], 6042 "datatypes": [ 6043 "metadata", 6044 "images" 6045 ] 6046 } 6047 ], 6048 }, 6049 "client": { 6050 "key": { 6051 "proof": "httpsig", 6052 "jwk": { 6053 "kty": "RSA", 6054 "e": "AQAB", 6055 "kid": "xyz-1", 6056 "alg": "RS256", 6057 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 6058 } 6059 } 6060 }, 6061 "interact": { 6062 "start": ["redirect"], 6063 "finish": { 6064 "method": "redirect", 6065 "uri": "https://client.example.net/return/123455", 6066 "nonce": "LKLTI25DK82FX4T4QFZC" 6067 } 6068 } 6069 } 6071 The AS processes the request and determines that the RO needs to 6072 interact. The AS returns the following response giving the client 6073 instance the information it needs to connect. The AS has also 6074 indicated to the client instance that it can use the given instance 6075 identifier to identify itself in future requests (Section 2.3.1). 6077 HTTP/1.1 200 OK 6078 Content-Type: application/json 6079 Cache-Control: no-store 6081 { 6082 "interact": { 6083 "redirect": 6084 "https://server.example.com/interact/4CF492MLVMSW9MKM", 6085 "push": "MBDOFXG4Y5CVJCX821LH" 6086 } 6087 "continue": { 6088 "access_token": { 6089 "value": "80UPRY5NM33OMUKMKSKU" 6090 }, 6091 "uri": "https://server.example.com/continue" 6092 }, 6093 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 6094 } 6096 The client instance saves the response and redirects the user to the 6097 interaction_url by sending the following HTTP message to the user's 6098 browser. 6100 HTTP 302 Found 6101 Location: https://server.example.com/interact/4CF492MLVMSW9MKM 6102 The user's browser fetches the AS's interaction URL. The user logs 6103 in, is identified as the RO for the resource being requested, and 6104 approves the request. Since the AS has a callback parameter, the AS 6105 generates the interaction reference, calculates the hash, and 6106 redirects the user back to the client instance with these additional 6107 values added as query parameters. 6109 NOTE: '\' line wrapping per RFC 8792 6111 HTTP 302 Found 6112 Location: https://client.example.net/return/123455\ 6113 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 6114 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 6115 &interact_ref=4IFWWIKYBC2PQ6U56NL1 6117 The client instance receives this request from the user's browser. 6118 The client instance ensures that this is the same user that was sent 6119 out by validating session information and retrieves the stored 6120 pending request. The client instance uses the values in this to 6121 validate the hash parameter. The client instance then calls the 6122 continuation URL and presents the handle and interaction reference in 6123 the request body. The client instance signs the request as above. 6125 POST /continue HTTP/1.1 6126 Host: server.example.com 6127 Content-Type: application/json 6128 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6129 Signature-Input: sig1=... 6130 Signature: sig1=... 6131 Digest: sha256=... 6133 { 6134 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 6135 } 6137 The AS retrieves the pending request based on the handle and issues a 6138 bearer access token and returns this to the client instance. 6140 NOTE: '\' line wrapping per RFC 8792 6142 HTTP/1.1 200 OK 6143 Content-Type: application/json 6144 Cache-Control: no-store 6146 { 6147 "access_token": { 6148 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6149 "manage": "https://server.example.com/token/PRY5NM33O\ 6150 M4TB8N6BW7OZB8CDFONP219RP1L", 6151 "access": [{ 6152 "actions": [ 6153 "read", 6154 "write", 6155 "dolphin" 6156 ], 6157 "locations": [ 6158 "https://server.example.net/", 6159 "https://resource.local/other" 6160 ], 6161 "datatypes": [ 6162 "metadata", 6163 "images" 6164 ] 6165 }] 6166 }, 6167 "continue": { 6168 "access_token": { 6169 "value": "80UPRY5NM33OMUKMKSKU" 6170 }, 6171 "uri": "https://server.example.com/continue" 6172 } 6173 } 6175 D.2. Secondary Device Interaction 6177 In this scenario, the user does not have access to a web browser on 6178 the device and must use a secondary device to interact with the AS. 6179 The client instance can display a user code or a printable QR code. 6180 The client instance is not able to accept callbacks from the AS and 6181 needs to poll for updates while waiting for the user to authorize the 6182 request. 6184 The client instance initiates the request to the AS. 6186 POST /tx HTTP/1.1 6187 Host: server.example.com 6188 Content-Type: application/json 6189 Signature-Input: sig1=... 6190 Signature: sig1=... 6191 Digest: sha256=... 6193 { 6194 "access_token": { 6195 "access": [ 6196 "dolphin-metadata", "some other thing" 6197 ], 6198 }, 6199 "client": "7C7C4AZ9KHRS6X63AJAO", 6200 "interact": { 6201 "start": ["redirect", "user_code"] 6202 } 6203 } 6205 The AS processes this and determines that the RO needs to interact. 6206 The AS supports both redirect URIs and user codes for interaction, so 6207 it includes both. Since there is no "callback" the AS does not 6208 include a nonce, but does include a "wait" parameter on the 6209 continuation section because it expects the client instance to poll 6210 for results. 6212 HTTP/1.1 200 OK 6213 Content-Type: application/json 6214 Cache-Control: no-store 6216 { 6217 "interact": { 6218 "redirect": "https://srv.ex/MXKHQ", 6219 "user_code": { 6220 "code": "A1BC-3DFF", 6221 "url": "https://srv.ex/device" 6222 } 6223 }, 6224 "continue": { 6225 "access_token": { 6226 "value": "80UPRY5NM33OMUKMKSKU" 6227 }, 6228 "uri": "https://server.example.com/continue/VGJKPTKC50", 6229 "wait": 60 6230 } 6231 } 6232 The client instance saves the response and displays the user code 6233 visually on its screen along with the static device URL. The client 6234 instance also displays the short interaction URL as a QR code to be 6235 scanned. 6237 If the user scans the code, they are taken to the interaction 6238 endpoint and the AS looks up the current pending request based on the 6239 incoming URL. If the user instead goes to the static page and enters 6240 the code manually, the AS looks up the current pending request based 6241 on the value of the user code. In both cases, the user logs in, is 6242 identified as the RO for the resource being requested, and approves 6243 the request. Once the request has been approved, the AS displays to 6244 the user a message to return to their device. 6246 Meanwhile, the client instance periodically polls the AS every 60 6247 seconds at the continuation URL. The client instance signs the 6248 request using the same key and method that it did in the first 6249 request. 6251 POST /continue/VGJKPTKC50 HTTP/1.1 6252 Host: server.example.com 6253 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6254 Signature-Input: sig1=... 6255 Signature: sig1=... 6256 Digest: sha256=... 6258 The AS retrieves the pending request based on the handle and 6259 determines that it has not yet been authorized. The AS indicates to 6260 the client instance that no access token has yet been issued but it 6261 can continue to call after another 60 second timeout. 6263 HTTP/1.1 200 OK 6264 Content-Type: application/json 6265 Cache-Control: no-store 6267 { 6268 "continue": { 6269 "access_token": { 6270 "value": "G7YQT4KQQ5TZY9SLSS5E" 6271 }, 6272 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 6273 "wait": 60 6274 } 6275 } 6276 Note that the continuation URL and access token have been rotated 6277 since they were used by the client instance to make this call. The 6278 client instance polls the continuation URL after a 60 second timeout 6279 using this new information. 6281 POST /continue/ATWHO4Q1WV HTTP/1.1 6282 Host: server.example.com 6283 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 6284 Signature-Input: sig1=... 6285 Signature: sig1=... 6286 Digest: sha256=... 6288 The AS retrieves the pending request based on the URL and access 6289 token, determines that it has been approved, and issues an access 6290 token for the client to use at the RS. 6292 NOTE: '\' line wrapping per RFC 8792 6294 HTTP/1.1 200 OK 6295 Content-Type: application/json 6296 Cache-Control: no-store 6298 { 6299 "access_token": { 6300 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6301 "manage": "https://server.example.com/token/PRY5NM33O\ 6302 M4TB8N6BW7OZB8CDFONP219RP1L", 6303 "access": [ 6304 "dolphin-metadata", "some other thing" 6305 ] 6306 } 6307 } 6309 D.3. No User Involvement 6311 In this scenario, the client instance is requesting access on its own 6312 behalf, with no user to interact with. 6314 The client instance creates a request to the AS, identifying itself 6315 with its public key and using MTLS to make the request. 6317 POST /tx HTTP/1.1 6318 Host: server.example.com 6319 Content-Type: application/json 6321 { 6322 "access_token": { 6323 "access": [ 6324 "backend service", "nightly-routine-3" 6325 ], 6326 }, 6327 "client": { 6328 "key": { 6329 "proof": "mtls", 6330 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 6331 } 6332 } 6333 } 6335 The AS processes this and determines that the client instance can ask 6336 for the requested resources and issues an access token. 6338 HTTP/1.1 200 OK 6339 Content-Type: application/json 6340 Cache-Control: no-store 6342 { 6343 "access_token": { 6344 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6345 "manage": "https://server.example.com/token", 6346 "access": [ 6347 "backend service", "nightly-routine-3" 6348 ] 6349 } 6350 } 6352 D.4. Asynchronous Authorization 6354 In this scenario, the client instance is requesting on behalf of a 6355 specific RO, but has no way to interact with the user. The AS can 6356 asynchronously reach out to the RO for approval in this scenario. 6358 The client instance starts the request at the AS by requesting a set 6359 of resources. The client instance also identifies a particular user. 6361 POST /tx HTTP/1.1 6362 Host: server.example.com 6363 Content-Type: application/json 6364 Signature-Input: sig1=... 6365 Signature: sig1=... 6366 Digest: sha256=... 6368 { 6369 "access_token": { 6370 "access": [ 6371 { 6372 "type": "photo-api", 6373 "actions": [ 6374 "read", 6375 "write", 6376 "dolphin" 6377 ], 6378 "locations": [ 6379 "https://server.example.net/", 6380 "https://resource.local/other" 6381 ], 6382 "datatypes": [ 6383 "metadata", 6384 "images" 6385 ] 6386 }, 6387 "read", "dolphin-metadata", 6388 { 6389 "type": "financial-transaction", 6390 "actions": [ 6391 "withdraw" 6392 ], 6393 "identifier": "account-14-32-32-3", 6394 "currency": "USD" 6395 }, 6396 "some other thing" 6397 ], 6398 }, 6399 "client": "7C7C4AZ9KHRS6X63AJAO", 6400 "user": { 6401 "sub_ids": [ { 6402 "format": "opaque", 6403 "id": "J2G8G8O4AZ" 6404 } ] 6405 } 6406 } 6407 The AS processes this and determines that the RO needs to interact. 6408 The AS determines that it can reach the identified user 6409 asynchronously and that the identified user does have the ability to 6410 approve this request. The AS indicates to the client instance that 6411 it can poll for continuation. 6413 HTTP/1.1 200 OK 6414 Content-Type: application/json 6415 Cache-Control: no-store 6417 { 6418 "continue": { 6419 "access_token": { 6420 "value": "80UPRY5NM33OMUKMKSKU" 6421 }, 6422 "uri": "https://server.example.com/continue", 6423 "wait": 60 6424 } 6425 } 6427 The AS reaches out to the RO and prompts them for consent. In this 6428 example, the AS has an application that it can push notifications in 6429 to for the specified account. 6431 Meanwhile, the client instance periodically polls the AS every 60 6432 seconds at the continuation URL. 6434 POST /continue HTTP/1.1 6435 Host: server.example.com 6436 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6437 Signature-Input: sig1=... 6438 Signature: sig1=... 6440 The AS retrieves the pending request based on the handle and 6441 determines that it has not yet been authorized. The AS indicates to 6442 the client instance that no access token has yet been issued but it 6443 can continue to call after another 60 second timeout. 6445 HTTP/1.1 200 OK 6446 Content-Type: application/json 6447 Cache-Control: no-store 6449 { 6450 "continue": { 6451 "access_token": { 6452 "value": "BI9QNW6V9W3XFJK4R02D" 6453 }, 6454 "uri": "https://server.example.com/continue", 6455 "wait": 60 6456 } 6457 } 6459 Note that the continuation handle has been rotated since it was used 6460 by the client instance to make this call. The client instance polls 6461 the continuation URL after a 60 second timeout using the new handle. 6463 POST /continue HTTP/1.1 6464 Host: server.example.com 6465 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 6466 Signature-Input: sig1=... 6467 Signature: sig1=... 6469 The AS retrieves the pending request based on the handle and 6470 determines that it has been approved and it issues an access token. 6472 NOTE: '\' line wrapping per RFC 8792 6474 HTTP/1.1 200 OK 6475 Content-Type: application/json 6476 Cache-Control: no-store 6478 { 6479 "access_token": { 6480 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6481 "manage": "https://server.example.com/token/PRY5NM33O\ 6482 M4TB8N6BW7OZB8CDFONP219RP1L", 6483 "access": [ 6484 "dolphin-metadata", "some other thing" 6485 ] 6486 } 6487 } 6489 D.5. Applying OAuth 2.0 Scopes and Client IDs 6491 While GNAP is not designed to be directly compatible with OAuth 2.0 6492 [RFC6749], considerations have been made to enable the use of OAuth 6493 2.0 concepts and constructs more smoothly within GNAP. 6495 In this scenario, the client developer has a "client_id" and set of 6496 "scope" values from their OAuth 2.0 system and wants to apply them to 6497 the new protocol. Traditionally, the OAuth 2.0 client developer 6498 would put their "client_id" and "scope" values as parameters into a 6499 redirect request to the authorization endpoint. 6501 NOTE: '\' line wrapping per RFC 8792 6503 HTTP 302 Found 6504 Location: https://server.example.com/authorize\ 6505 ?client_id=7C7C4AZ9KHRS6X63AJAO\ 6506 &scope=read%20write%20dolphin\ 6507 &redirect_uri=https://client.example.net/return\ 6508 &response_type=code\ 6509 &state=123455 6511 Now the developer wants to make an analogous request to the AS using 6512 GNAP. To do so, the client instance makes an HTTP POST and places 6513 the OAuth 2.0 values in the appropriate places. 6515 POST /tx HTTP/1.1 6516 Host: server.example.com 6517 Content-Type: application/json 6518 Signature-Input: sig1=... 6519 Signature: sig1=... 6520 Digest: sha256=... 6522 { 6523 "access_token": { 6524 "access": [ 6525 "read", "write", "dolphin" 6526 ], 6527 "flags": [ "bearer" ] 6528 }, 6529 "client": "7C7C4AZ9KHRS6X63AJAO", 6530 "interact": { 6531 "start": ["redirect"], 6532 "finish": { 6533 "method": "redirect", 6534 "uri": "https://client.example.net/return?state=123455", 6535 "nonce": "LKLTI25DK82FX4T4QFZC" 6536 } 6537 } 6538 } 6540 The "client_id" can be used to identify the client instance's keys 6541 that it uses for authentication, the scopes represent resources that 6542 the client instance is requesting, and the "redirect_uri" and "state" 6543 value are pre-combined into a "finish" URI that can be unique per 6544 request. The client instance additionally creates a nonce to protect 6545 the callback, separate from the state parameter that it has added to 6546 its return URL. 6548 From here, the protocol continues as above. 6550 Appendix E. JSON Structures and Polymorphism 6552 GNAP makes use of polymorphism within the JSON [RFC8259] structures 6553 used for the protocol. Each portion of this protocol is defined in 6554 terms of the JSON data type that its values can take, whether it's a 6555 string, object, array, boolean, or number. For some fields, 6556 different data types offer different descriptive capabilities and are 6557 used in different situations for the same field. Each data type 6558 provides a different syntax to express the same underlying semantic 6559 protocol element, which allows for optimization and simplification in 6560 many common cases. 6562 Even though JSON is often used to describe strongly typed structures, 6563 JSON on its own is naturally polymorphic. In JSON, the named members 6564 of an object have no type associated with them, and any data type can 6565 be used as the value for any member. In practice, each member has a 6566 semantic type that needs to make sense to the parties creating and 6567 consuming the object. Within this protocol, each object member is 6568 defined in terms of its semantic content, and this semantic content 6569 might have expressions in different concrete data types for different 6570 specific purposes. Since each object member has exactly one value in 6571 JSON, each data type for an object member field is naturally mutually 6572 exclusive with other data types within a single JSON object. 6574 For example, a resource request for a single access token is composed 6575 of an array of resource request descriptions while a request for 6576 multiple access tokens is composed of an object whose member values 6577 are all arrays. Both of these represent requests for access, but the 6578 difference in syntax allows the client instance and AS to 6579 differentiate between the two request types in the same request. 6581 Another form of polymorphism in JSON comes from the fact that the 6582 values within JSON arrays need not all be of the same JSON data type. 6583 However, within this protocol, each element within the array needs to 6584 be of the same kind of semantic element for the collection to make 6585 sense, even when the data types are different from each other. 6587 For example, each aspect of a resource request can be described using 6588 an object with multiple dimensional components, or the aspect can be 6589 requested using a string. In both cases, the resource request is 6590 being described in a way that the AS needs to interpret, but with 6591 different levels of specificity and complexity for the client 6592 instance to deal with. An API designer can provide a set of common 6593 access scopes as simple strings but still allow client software 6594 developers to specify custom access when needed for more complex 6595 APIs. 6597 Extensions to this specification can use different data types for 6598 defined fields, but each extension needs to not only declare what the 6599 data type means, but also provide justification for the data type 6600 representing the same basic kind of thing it extends. For example, 6601 an extension declaring an "array" representation for a field would 6602 need to explain how the array represents something akin to the non- 6603 array element that it is replacing. 6605 Authors' Addresses 6607 Justin Richer (editor) 6608 Bespoke Engineering 6609 Email: ietf@justin.richer.org 6610 URI: https://bspk.io/ 6612 Aaron Parecki 6613 Okta 6615 Email: aaron@parecki.com 6616 URI: https://aaronparecki.com 6618 Fabien Imbault 6619 acert.io 6621 Email: fabien.imbault@acert.io 6622 URI: https://acert.io/