idnits 2.17.00 (12 Aug 2021) /tmp/idnits56775/draft-ietf-gnap-core-protocol-09.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 are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 25 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 297 has weird spacing: '... Client appli...' == Line 322 has weird spacing: '...nd user natur...' == Line 384 has weird spacing: '...tribute chara...' == Line 386 has weird spacing: '...s Token a dat...' == Line 397 has weird spacing: '...ivilege right...' == (4 more instances...) -- The document date (6 March 2022) is 69 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP195' == Outdated reference: A later version (-08) exists of draft-ietf-httpbis-digest-headers-07 == Outdated reference: A later version (-12) exists of draft-ietf-oauth-rar-10 == Outdated reference: A later version (-11) exists of draft-ietf-secevent-subject-identifiers-09 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' ** Downref: Normative reference to an Informational RFC: RFC 8792 Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GNAP J. Richer, Ed. 3 Internet-Draft Bespoke Engineering 4 Intended status: Standards Track A. Parecki 5 Expires: 7 September 2022 Okta 6 F. Imbault 7 acert.io 8 6 March 2022 10 Grant Negotiation and Authorization Protocol 11 draft-ietf-gnap-core-protocol-09 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 7 September 2022. 37 Copyright Notice 39 Copyright (c) 2022 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 Revised BSD License text as 48 described in Section 4.e of the Trust Legal Provisions and are 49 provided without warranty as described in the Revised BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 54 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 1.3. Elements . . . . . . . . . . . . . . . . . . . . . . . . 9 57 1.4. Trust relationships . . . . . . . . . . . . . . . . . . . 10 58 1.5. Sequences . . . . . . . . . . . . . . . . . . . . . . . . 12 59 1.5.1. Overall Protocol Sequence . . . . . . . . . . . . . . 12 60 1.5.2. Redirect-based Interaction . . . . . . . . . . . . . 15 61 1.5.3. User-code Interaction . . . . . . . . . . . . . . . . 18 62 1.5.4. Asynchronous Authorization . . . . . . . . . . . . . 20 63 1.5.5. Software-only Authorization . . . . . . . . . . . . . 22 64 1.5.6. Refreshing an Expired Access Token . . . . . . . . . 23 65 1.5.7. Requesting User Information . . . . . . . . . . . . . 25 66 2. Requesting Access . . . . . . . . . . . . . . . . . . . . . . 26 67 2.1. Requesting Access to Resources . . . . . . . . . . . . . 28 68 2.1.1. Requesting a Single Access Token . . . . . . . . . . 28 69 2.1.2. Requesting Multiple Access Tokens . . . . . . . . . . 31 70 2.2. Requesting Subject Information . . . . . . . . . . . . . 33 71 2.3. Identifying the Client Instance . . . . . . . . . . . . . 34 72 2.3.1. Identifying the Client Instance by Reference . . . . 35 73 2.3.2. Providing Displayable Client Instance Information . . 36 74 2.3.3. Authenticating the Client Instance . . . . . . . . . 37 75 2.4. Identifying the User . . . . . . . . . . . . . . . . . . 37 76 2.4.1. Identifying the User by Reference . . . . . . . . . . 38 77 2.5. Interacting with the User . . . . . . . . . . . . . . . . 39 78 2.5.1. Start Mode Definitions . . . . . . . . . . . . . . . 40 79 2.5.2. Finish Interaction Methods . . . . . . . . . . . . . 42 80 2.5.3. Hints . . . . . . . . . . . . . . . . . . . . . . . . 45 81 2.5.4. Extending Interaction Modes . . . . . . . . . . . . . 45 82 2.6. Extending The Grant Request . . . . . . . . . . . . . . . 46 83 3. Grant Response . . . . . . . . . . . . . . . . . . . . . . . 46 84 3.1. Request Continuation . . . . . . . . . . . . . . . . . . 48 85 3.2. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 49 86 3.2.1. Single Access Token . . . . . . . . . . . . . . . . . 49 87 3.2.2. Multiple Access Tokens . . . . . . . . . . . . . . . 53 88 3.3. Interaction Modes . . . . . . . . . . . . . . . . . . . . 54 89 3.3.1. Redirection to an arbitrary URI . . . . . . . . . . . 55 90 3.3.2. Launch of an application URI . . . . . . . . . . . . 56 91 3.3.3. Display of a Short User Code . . . . . . . . . . . . 56 92 3.3.4. Display of a Short User Code and URI . . . . . . . . 57 93 3.3.5. Interaction Finish . . . . . . . . . . . . . . . . . 58 94 3.3.6. Extending Interaction Mode Responses . . . . . . . . 59 95 3.4. Returning Subject Information . . . . . . . . . . . . . . 59 96 3.5. Returning a Dynamically-bound Client Instance 97 Identifier . . . . . . . . . . . . . . . . . . . . . . . 60 98 3.6. Error Response . . . . . . . . . . . . . . . . . . . . . 61 99 3.7. Extending the Response . . . . . . . . . . . . . . . . . 62 100 4. Determining Authorization and Consent . . . . . . . . . . . . 62 101 4.1. Interaction Start Methods . . . . . . . . . . . . . . . . 65 102 4.1.1. Interaction at a Redirected URI . . . . . . . . . . . 66 103 4.1.2. Interaction at the Static User Code URI . . . . . . . 66 104 4.1.3. Interaction at a Dynamic User Code URI . . . . . . . 67 105 4.1.4. Interaction through an Application URI . . . . . . . 68 106 4.2. Post-Interaction Completion . . . . . . . . . . . . . . . 68 107 4.2.1. Completing Interaction with a Browser Redirect to the 108 Callback URI . . . . . . . . . . . . . . . . . . . . 69 109 4.2.2. Completing Interaction with a Direct HTTP Request 110 Callback . . . . . . . . . . . . . . . . . . . . . . 70 111 4.2.3. Calculating the interaction hash . . . . . . . . . . 71 112 5. Continuing a Grant Request . . . . . . . . . . . . . . . . . 72 113 5.1. Continuing After a Completed Interaction . . . . . . . . 74 114 5.2. Continuing During Pending Interaction . . . . . . . . . . 75 115 5.3. Modifying an Existing Request . . . . . . . . . . . . . . 77 116 5.4. Canceling a Grant Request . . . . . . . . . . . . . . . . 83 117 6. Token Management . . . . . . . . . . . . . . . . . . . . . . 83 118 6.1. Rotating the Access Token . . . . . . . . . . . . . . . . 83 119 6.2. Revoking the Access Token . . . . . . . . . . . . . . . . 85 120 7. Securing Requests from the Client Instance . . . . . . . . . 86 121 7.1. Key Formats . . . . . . . . . . . . . . . . . . . . . . . 87 122 7.1.1. Key References . . . . . . . . . . . . . . . . . . . 88 123 7.1.2. Key Protection . . . . . . . . . . . . . . . . . . . 88 124 7.2. Presenting Access Tokens . . . . . . . . . . . . . . . . 89 125 7.3. Proving Possession of a Key with a Request . . . . . . . 90 126 7.3.1. HTTP Message Signing . . . . . . . . . . . . . . . . 92 127 7.3.2. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 96 128 7.3.3. Detached JWS . . . . . . . . . . . . . . . . . . . . 98 129 7.3.4. Attached JWS . . . . . . . . . . . . . . . . . . . . 102 130 8. Resource Access Rights . . . . . . . . . . . . . . . . . . . 106 131 8.1. Requesting Resources By Reference . . . . . . . . . . . . 109 132 9. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 111 133 9.1. RS-first Method of AS Discovery . . . . . . . . . . . . . 113 134 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 114 135 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 115 136 12. Security Considerations . . . . . . . . . . . . . . . . . . . 115 137 12.1. TLS Protection in Transit . . . . . . . . . . . . . . . 115 138 12.2. Signing Requests from the Client Software . . . . . . . 116 139 12.3. Protection of Client Instance Key Material . . . . . . . 117 140 12.4. Protection of Authorization Server . . . . . . . . . . . 118 141 12.5. Symmetric and Asymmetric Client Instance Keys . . . . . 119 142 12.6. Generation of Access Tokens . . . . . . . . . . . . . . 120 143 12.7. Bearer Access Tokens . . . . . . . . . . . . . . . . . . 121 144 12.8. Key-Bound Access Tokens . . . . . . . . . . . . . . . . 121 145 12.9. Exposure of End-user Credentials to Client Instance . . 122 146 12.10. Mixing Up Authorization Servers . . . . . . . . . . . . 123 147 12.11. Processing of Client-Presented User Information . . . . 123 148 12.12. Client Instance Pre-registration . . . . . . . . . . . . 124 149 12.13. Client Instance Impersonation . . . . . . . . . . . . . 125 150 12.14. Interception of Information in the Browser . . . . . . . 126 151 12.15. Callback URI Manipulation . . . . . . . . . . . . . . . 127 152 12.16. Redirection Status Codes . . . . . . . . . . . . . . . . 127 153 12.17. MTLS Message Integrity . . . . . . . . . . . . . . . . . 128 154 12.18. MTLS Deployment Patterns . . . . . . . . . . . . . . . . 129 155 12.19. Interception of Responses from the AS . . . . . . . . . 130 156 12.20. Key Distribution . . . . . . . . . . . . . . . . . . . . 130 157 12.21. Interaction Finish Modes and Polling . . . . . . . . . . 130 158 12.22. Session Management for Interaction Finish Methods . . . 131 159 12.23. Storage of Information During Interaction and 160 Continuation . . . . . . . . . . . . . . . . . . . . . 133 161 12.24. Denial of Service (DoS) through Grant Continuation . . . 133 162 12.25. Exhaustion of Random Value Space . . . . . . . . . . . . 134 163 12.26. Front-channel URIs . . . . . . . . . . . . . . . . . . . 135 164 12.27. Processing Assertions . . . . . . . . . . . . . . . . . 136 165 12.28. Stolen Token Replay . . . . . . . . . . . . . . . . . . 136 166 12.29. Self-contained Stateless Access Tokens . . . . . . . . . 137 167 12.30. Network Problems and Token and Grant Management . . . . 138 168 12.31. Server-side Request Forgery (SSRF) . . . . . . . . . . . 139 169 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 140 170 13.1. Surveillance . . . . . . . . . . . . . . . . . . . . . . 140 171 13.1.1. Surveillance by the Client . . . . . . . . . . . . . 140 172 13.1.2. Surveillance by the Authorization Server . . . . . . 141 173 13.2. Stored Data . . . . . . . . . . . . . . . . . . . . . . 141 174 13.3. Intrusion . . . . . . . . . . . . . . . . . . . . . . . 142 175 13.4. Correlation . . . . . . . . . . . . . . . . . . . . . . 142 176 13.4.1. Correlation by Clients . . . . . . . . . . . . . . . 142 177 13.4.2. Correlation by Resource Servers . . . . . . . . . . 143 178 13.4.3. Correlation by Authorization Servers . . . . . . . . 143 179 13.5. Disclosure in Shared References . . . . . . . . . . . . 143 180 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 143 181 14.1. Normative References . . . . . . . . . . . . . . . . . . 144 182 14.2. Informative References . . . . . . . . . . . . . . . . . 146 183 Appendix A. Document History . . . . . . . . . . . . . . . . . . 147 184 Appendix B. Compared to OAuth 2.0 . . . . . . . . . . . . . . . 150 185 Appendix C. Component Data Models . . . . . . . . . . . . . . . 153 186 Appendix D. Example Protocol Flows . . . . . . . . . . . . . . . 153 187 D.1. Redirect-Based User Interaction . . . . . . . . . . . . . 154 188 D.2. Secondary Device Interaction . . . . . . . . . . . . . . 157 189 D.3. No User Involvement . . . . . . . . . . . . . . . . . . . 160 190 D.4. Asynchronous Authorization . . . . . . . . . . . . . . . 161 191 D.5. Applying OAuth 2.0 Scopes and Client IDs . . . . . . . . 165 192 Appendix E. JSON Structures and Polymorphism . . . . . . . . . . 166 193 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 167 195 1. Introduction 197 This protocol allows a piece of software, the client instance, to 198 request delegated authorization to resource servers and to request 199 direct information. This delegation is facilitated by an 200 authorization server usually on behalf of a resource owner. The end 201 user operating the software may interact with the authorization 202 server to authenticate, provide consent, and authorize the request. 204 The process by which the delegation happens is known as a grant, and 205 GNAP allows for the negotiation of the grant process over time by 206 multiple parties acting in distinct roles. 208 This specification focuses on the portions of the delegation process 209 facing the client instance. In particular, this specification 210 defines interoperable methods for a client instance to request, 211 negotiate, and receive access to information facilitated by the 212 authorization server. This specification also discusses discovery 213 mechanisms for the client instance to configure itself dynamically. 214 The means for an authorization server and resource server to 215 interoperate are discussed in the companion document, 216 [I-D.ietf-gnap-resource-servers]. 218 The focus of this protocol is to provide interoperability between the 219 different parties acting in each role, and is not to specify 220 implementation details of each. Where appropriate, GNAP may make 221 recommendations about internal implementation details, but these 222 recommendations are to ensure the security of the overall deployment 223 rather than to be prescriptive in the implementation. 225 This protocol solves many of the same use cases as OAuth 2.0 226 [RFC6749], OpenID Connect [OIDC], and the family of protocols that 227 have grown up around that ecosystem. However, GNAP is not an 228 extension of OAuth 2.0 and is not intended to be directly compatible 229 with OAuth 2.0. GNAP seeks to provide functionality and solve use 230 cases that OAuth 2.0 cannot easily or cleanly address. Appendix B 231 further details the protocol rationale compared to OAuth 2.0. GNAP 232 and OAuth 2.0 will likely exist in parallel for many deployments, and 233 considerations have been taken to facilitate the mapping and 234 transition from legacy systems to GNAP. Some examples of these can 235 be found in Appendix D.5. 237 1.1. Terminology 239 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 240 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 241 "OPTIONAL" in this document are to be interpreted as described in 242 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 243 capitals, as shown here. 245 This document contains non-normative examples of partial and complete 246 HTTP messages, JSON structures, URIs, query components, keys, and 247 other elements. Whenever possible, the document uses URI as a 248 generic term, since it aligns with [RFC3986] recommendations and 249 matches better with the intent that the identifier may be reachable 250 through various/generic means (compared to URLs). Some examples use 251 a single trailing backslash \ to indicate line wrapping for long 252 values, as per [RFC8792]. The \ character and leading spaces on 253 wrapped lines are not part of the value. 255 1.2. Roles 257 The parties in GNAP perform actions under different roles. Roles are 258 defined by the actions taken and the expectations leveraged on the 259 role by the overall protocol. 261 +-------------+ +------------+ 262 | | | | 263 |Authorization| | Resource | 264 | Server | | Server | 265 | |<--+ +--->| | 266 +-------------+ | | +------------+ 267 + | | 268 + | | 269 + | | 270 + | | 271 + | | 272 + +----------+ 273 + | Client | 274 + | Instance | 275 + +----------+ 276 + + 277 + + 278 + + 279 +-----------+ + +------------+ 280 | | + + + | | 281 | Resource | | End | 282 | Owner | ~ ~ ~ ~ ~ ~ | User | 283 | | | | 284 +-----------+ +------------+ 286 Legend 288 + + + indicates interaction between a human and computer 289 ----- indicates interaction between two pieces of software 290 ~ ~ ~ indicates a potential equivalence or out-of-band 291 communication between roles 293 Authorization Server (AS) server that grants delegated privileges to 294 a particular instance of client software in the form of access 295 tokens or other information (such as subject information). 297 Client application that consumes resources from one or several RSs, 298 possibly requiring access privileges from one or several ASs. The 299 client is operated by the end user or it runs autonomously on 300 behalf of a resource owner. 302 Example: a client can be a mobile application, a web application, 303 etc. 305 Note: this specification differentiates between a specific 306 instance (the client instance, identified by its unique key) and 307 the software running the instance (the client software). For some 308 kinds of client software, there could be many instances of that 309 software, each instance with a different key. 311 Resource Server (RS) server that provides operations on protected 312 resources, where operations require a valid access token issued by 313 an AS. 315 Resource Owner (RO) subject entity that may grant or deny operations 316 on resources it has authority upon. 318 Note: the act of granting or denying an operation may be manual 319 (i.e. through an interaction with a physical person) or automatic 320 (i.e. through predefined organizational rules). 322 End user natural person that operates a client instance. 324 Note: that natural person may or may not be the same entity as the 325 RO. 327 The design of GNAP does not assume any one deployment architecture, 328 but instead attempts to define roles that can be fulfilled in a 329 number of different ways for different use cases. As long as a given 330 role fulfills all of its obligations and behaviors as defined by the 331 protocol, GNAP does not make additional requirements on its structure 332 or setup. 334 Multiple roles can be fulfilled by the same party, and a given party 335 can switch roles in different instances of the protocol. For 336 example, the RO and end user in many instances are the same person, 337 where a user is authorizing the client instance to act on their own 338 behalf at the RS. In this case, one party fulfills both of the RO 339 and end-user roles, but the roles themselves are still defined 340 separately from each other to allow for other use cases where they 341 are fulfilled by different parties. 343 For another example, in some complex scenarios, an RS receiving 344 requests from one client instance can act as a client instance for a 345 downstream secondary RS in order to fulfill the original request. In 346 this case, one piece of software is both an RS and a client instance 347 from different perspectives, and it fulfills these roles separately 348 as far as the overall protocol is concerned. 350 A single role need not be deployed as a monolithic service. For 351 example, a client instance could have components that are installed 352 on the end user's device as well as a back-end system that it 353 communicates with. If both of these components participate in the 354 delegation protocol, they are both considered part of the client 355 instance. If there are several copies of the client software that 356 run separately but all share the same key material, such as a 357 deployed cluster, then this cluster is considered a single client 358 instance. 360 In these cases, the distinct components of what is considered a GNAP 361 client instance may use any number of different communication 362 mechanisms between them, all of which would be considered an 363 implementation detail of the client instances and out of scope of 364 GNAP. 366 For another example, an AS could likewise be built out of many 367 constituent components in a distributed architecture. The component 368 that the client instance calls directly could be different from the 369 component that the RO interacts with to drive consent, since API 370 calls and user interaction have different security considerations in 371 many environments. Furthermore, the AS could need to collect 372 identity claims about the RO from one system that deals with user 373 attributes while generating access tokens at another system that 374 deals with security rights. From the perspective of GNAP, all of 375 these are pieces of the AS and together fulfill the role of the AS as 376 defined by the protocol. These pieces may have their own internal 377 communications mechanisms which are considered out of scope of GNAP. 379 1.3. Elements 381 In addition to the roles above, the protocol also involves several 382 elements that are acted upon by the roles throughout the process. 384 Attribute characteristics related to a subject. 386 Access Token a data artifact representing a set of rights and/or 387 attributes. 389 Note: an access token can be first issued to an client instance 390 (requiring authorization by the RO) and subsequently rotated. 392 Grant (verb): to permit an instance of client software to receive 393 some attributes at a specific time and valid for a specific 394 duration and/or to exercise some set of delegated rights to access 395 a protected resource (noun): the act of granting. 397 Privilege right or attribute associated with a subject. 399 Note: the RO defines and maintains the rights and attributes 400 associated to the protected resource, and might temporarily 401 delegate some set of those privileges to an end user. This 402 process is refered to as privilege delegation. 404 Protected Resource protected API (Application Programming Interface) 405 served by an RS and that can be accessed by a client, if and only 406 if a valid access token is provided. 408 Note: to avoid complex sentences, the specification document may 409 simply refer to "resource" instead of "protected resource". 411 Right ability given to a subject to perform a given operation on a 412 resource under the control of an RS. 414 Subject person, organization or device. It decides whether and 415 under which conditions its attributes can be disclosed to other 416 parties. 418 Subject Information statement asserted by an AS about a subject. 420 1.4. Trust relationships 422 GNAP defines its trust objective as: "the RO trusts the AS to ensure 423 access validation and delegation of protected resources to end users, 424 through third party clients." 426 This trust objective can be decomposed into trust relationships 427 between software elements and roles, especially the pairs end user/ 428 RO, end user/client, client/AS, RS/RO, AS/RO, AS/RS. Trust of an 429 agent by its pair can exist if the pair is informed that the agent 430 has made a promise to follow the protocol in the past (e.g. pre- 431 registration, uncompromised cryptographic components) or if the pair 432 is able to infer by indirect means that the agent has made such a 433 promise (e.g. a compliant client request). Each agent defines its 434 own valuation function of promises given or received. Examples of 435 such valuations can be the benefits from interacting with other 436 agents (e.g. safety in client access, interoperability with identity 437 standards), the cost of following the protocol (including its 438 security and privacy requirements and recommendations), a ranking of 439 promise importance (e.g. a policy decision made by the AS), the 440 assessment of one's vulnerability or risk of not being able to defend 441 against threats, etc. Those valuations may depend on the context of 442 the request. For instance, the AS may decide to either take into 443 account or discard hints provided by the client, the RS may refuse 444 bearer tokens, etc. depending on the specific case in which GNAP is 445 used. Some promises can be conditional of some previous interactions 446 (e.g. repeated requests). 448 Looking back on each trust relationship: 450 * end user/RO: this relationship exists only when the end user and 451 the RO are different, in which case the end user needs some out of 452 band mechanism of getting the RO consent (see Section 4). GNAP 453 generally assumes that humans can be authenticated thanks to 454 identity protocols (for instance, through an id_token assertion in 455 Section 2.2). 457 * end user/client: the client acts as a user agent. Depending on 458 the technology used (browser, SPA, mobile application, IoT device, 459 etc.), some interactions may or may not be possible (as described 460 in Section 2.5.1). Client developers promise to implement 461 requirements and generally some recommendations or best practices, 462 so that the end users may confidently use their software. 463 However, end users might also be facing some attacker's client 464 software, without even realizing it. 466 * end user/AS: when the client supports it (see Section 3.3), the 467 end user gets to interact with front-channel URIs provided by the 468 AS. See Section 12.26 for some considerations in trusting these 469 interactions. 471 * client/AS: An honest AS may be facing an attacker's client (as 472 discussed just above), or the reverse, and GNAP aims at making 473 common attacks impractical. The core specification makes access 474 tokens opaque to the client and defines the request/response 475 scheme in detail, therefore avoiding extra trust hypotheses from 476 this critical piece of software. Yet the AS may further define 477 cryptographic attestations or optional rules to simplify the 478 access of clients it already trusts, due to past behavior or 479 organizational policies (see Section 2.3). 481 * RS/RO: the RS promises it protects its resources from unauthorized 482 access, and only accepts valid access tokens issued by a trusted 483 AS. In case tokens are key bound, proper validation is expected 484 from the RS. 486 * AS/RO: the AS is expected to follow the decisions made by the RO, 487 either through interactive consent requests, repeated interactions 488 or automated rules (as described in Section 1.5). Privacy 489 considerations aim to reduce the risk of an honest but too curious 490 AS, or the consequences of an unexpected user data exposure. 492 * AS/RS: the AS promises to issue valid access tokens to legitimate 493 client requests (i.e. after carrying out appropriate due 494 diligence, as defined in the GNAP protocol). Some optional 495 configurations are covered by [I-D.ietf-gnap-resource-servers]. 497 A global assumption made by GNAP is that authorization requests are 498 security and privacy sensitive, and appropriate measures are 499 respectively detailed in Section 12 and Section 13. 501 A formal trust model is out of scope of this specification, but might 502 be carried out thanks to [promise-theory]. 504 1.5. Sequences 506 GNAP can be used in a variety of ways to allow the core delegation 507 process to take place. Many portions of this process are 508 conditionally present depending on the context of the deployments, 509 and not every step in this overview will happen in all circumstances. 511 Note that a connection between roles in this process does not 512 necessarily indicate that a specific protocol message is sent across 513 the wire between the components fulfilling the roles in question, or 514 that a particular step is required every time. For example, for a 515 client instance interested in only getting subject information 516 directly, and not calling an RS, all steps involving the RS below do 517 not apply. 519 In some circumstances, the information needed at a given stage is 520 communicated out of band or is preconfigured between the components 521 or entities performing the roles. For example, one entity can 522 fulfill multiple roles, and so explicit communication between the 523 roles is not necessary within the protocol flow. Additionally some 524 components may not be involved in all use cases. For example, a 525 client instance could be calling the AS just to get direct user 526 information and have no need to get an access token to call an RS. 528 1.5.1. Overall Protocol Sequence 530 The following diagram provides a general overview of GNAP, including 531 many different optional phases and connections. The diagrams in the 532 following sections provide views of GNAP under more specific 533 circumstances. 535 +------------+ +------------+ 536 | End user | ~ ~ ~ ~ | Resource | 537 | | | Owner (RO) | 538 +------------+ +------------+ 539 + + 540 + + 541 (A) (B) 542 + + 543 + + 544 +--------+ + +------------+ 545 | Client | (1) + | Resource | 546 |Instance| + | Server | 547 | | +---------------+ | (RS) | 548 | |--(2)->| Authorization | | | 549 | |<-(3)--| Server | | | 550 | | | (AS) | | | 551 | |--(4)->| | | | 552 | |<-(5)--| | | | 553 | |--------------(6)------------->| | 554 | | | | (7) | | 555 | |<-------------(8)------------->| | 556 | |--(9)->| | | | 557 | |<-(10)-| | | | 558 | |--------------(11)------------>| | 559 | | | | (12) | | 560 | |-(13)->| | | | 561 | | | | | | 562 +--------+ +---------------+ +------------+ 564 Legend 565 + + + indicates a possible interaction with a human 566 ----- indicates an interaction between protocol roles 567 ~ ~ ~ indicates a potential equivalence or out-of-band 568 communication between roles 570 * (A) The end user interacts with the client instance to indicate a 571 need for resources on behalf of the RO. This could identify the 572 RS the client instance needs to call, the resources needed, or the 573 RO that is needed to approve the request. Note that the RO and 574 end user are often the same entity in practice, but GNAP makes no 575 general assumption that they are. 577 * (1) The client instance determines what access is needed and which 578 AS to approach for access. Note that for most situations, the 579 client instance is pre-configured with which AS to talk to and 580 which kinds of access it needs, but some more dynamic processes 581 are discussed in Section 9.1. 583 * (2) The client instance requests access at the AS (Section 2). 585 * (3) The AS processes the request and determines what is needed to 586 fulfill the request. (See Section 4.) The AS sends its response 587 to the client instance (Section 3). 589 * (B) If interaction is required, the AS interacts with the RO 590 (Section 4) to gather authorization. The interactive component of 591 the AS can function using a variety of possible mechanisms 592 including web page redirects, applications, challenge/response 593 protocols, or other methods. The RO approves the request for the 594 client instance being operated by the end user. Note that the RO 595 and end user are often the same entity in practice, and many of 596 GNAP's interaction methods allow the client instance to facilitate 597 the end user interacting with the AS in order to fulfill the role 598 of the RO. 600 * (4) The client instance continues the grant at the AS (Section 5). 602 * (5) If the AS determines that access can be granted, it returns a 603 response to the client instance (Section 3) including an access 604 token (Section 3.2) for calling the RS and any directly returned 605 information (Section 3.4) about the RO. 607 * (6) The client instance uses the access token (Section 7.2) to 608 call the RS. 610 * (7) The RS determines if the token is sufficient for the request 611 by examining the token. The means of the RS determining this 612 access are out of scope of this specification, but some options 613 are discussed in [I-D.ietf-gnap-resource-servers]. 615 * (8) The client instance calls the RS (Section 7.2) using the 616 access token until the RS or client instance determine that the 617 token is no longer valid. 619 * (9) When the token no longer works, the client instance fetches an 620 updated access token (Section 6.1) based on the rights granted in 621 (5). 623 * (10) The AS issues a new access token (Section 3.2) to the client 624 instance. 626 * (11) The client instance uses the new access token (Section 7.2) 627 to call the RS. 629 * (12) The RS determines if the new token is sufficient for the 630 request. The means of the RS determining this access are out of 631 scope of this specification, but some options are discussed in 632 [I-D.ietf-gnap-resource-servers]. 634 * (13) The client instance disposes of the token (Section 6.2) once 635 the client instance has completed its access of the RS and no 636 longer needs the token. 638 The following sections and Appendix D contain specific guidance on 639 how to use GNAP in different situations and deployments. For 640 example, it is possible for the client instance to never request an 641 access token and never call an RS, just as it is possible for there 642 not to be a user involved in the delegation process. 644 1.5.2. Redirect-based Interaction 646 In this example flow, the client instance is a web application that 647 wants access to resources on behalf of the current user, who acts as 648 both the end user and the resource owner (RO). Since the client 649 instance is capable of directing the user to an arbitrary URI and 650 receiving responses from the user's browser, interaction here is 651 handled through front-channel redirects using the user's browser. 652 The redirection URI used for interaction is a service hosted by the 653 AS in this example. The client instance uses a persistent session 654 with the user to ensure the same user that is starting the 655 interaction is the user that returns from the interaction. 657 +--------+ +--------+ +------+ 658 | Client | | AS | | User | 659 |Instance| | | | | 660 | |< (1) + Start Session + + + + + + + + + + + + + + + +| | 661 | | | | | | 662 | |--(2)--- Request Access --------->| | | | 663 | | | | | | 664 | |<-(3)-- Interaction Needed -------| | | | 665 | | | | | | 666 | |+ (4) + Redirect for Interaction + + + + + + + + + > | | 667 | | | | | | 668 | | | |<+ (5) +>| | 669 | | | | AuthN | | 670 | | | | | | 671 | | | |<+ (6) +>| | 672 | | | | AuthZ | | 673 | | | | | | 674 | |< (7) + Redirect for Continuation + + + + + + + + + +| | 675 | | | | +------+ 676 | |--(8)--- Continue Request ------->| | 677 | | | | 678 | |<-(9)----- Grant Access ----------| | 679 | | | | 680 | | | | +--------+ 681 | |--(10)-- Access API ---------------------------->| RS | 682 | | | | | | 683 | |<-(11)-- API Response ---------------------------| | 684 | | | | +--------+ 685 +--------+ +--------+ 687 1. The client instance establishes a verifiable session to the 688 user, in the role of the end user. 690 2. The client instance requests access to the resource (Section 2). 691 The client instance indicates that it can redirect to an 692 arbitrary URI (Section 2.5.1.1) and receive a redirect from the 693 browser (Section 2.5.2.1). The client instance stores 694 verification information for its redirect in the session created 695 in (1). 697 3. The AS determines that interaction is needed and responds 698 (Section 3) with a URI to send the user to (Section 3.3.1) and 699 information needed to verify the redirect (Section 3.3.5) in 700 (7). The AS also includes information the client instance will 701 need to continue the request (Section 3.1) in (8). The AS 702 associates this continuation information with an ongoing request 703 that will be referenced in (4), (6), and (8). 705 4. The client instance stores the verification and continuation 706 information from (3) in the session from (1). The client 707 instance then redirects the user to the URI (Section 4.1.1) 708 given by the AS in (3). The user's browser loads the 709 interaction redirect URI. The AS loads the pending request 710 based on the incoming URI generated in (3). 712 5. The user authenticates at the AS, taking on the role of the RO. 714 6. As the RO, the user authorizes the pending request from the 715 client instance. 717 7. When the AS is done interacting with the user, the AS redirects 718 the user back (Section 4.2.1) to the client instance using the 719 redirect URI provided in (2). The redirect URI is augmented 720 with an interaction reference that the AS associates with the 721 ongoing request created in (2) and referenced in (4). The 722 redirect URI is also augmented with a hash of the security 723 information provided in (2) and (3). The client instance loads 724 the verification information from (2) and (3) from the session 725 created in (1). The client instance calculates a hash 726 (Section 4.2.3) based on this information and continues only if 727 the hash validates. Note that the client instance needs to 728 ensure that the parameters for the incoming request match those 729 that it is expecting from the session created in (1). The 730 client instance also needs to be prepared for the end user never 731 being returned to the client instance and handle timeouts 732 appropriately. 734 8. The client instance loads the continuation information from (3) 735 and sends the interaction reference from (7) in a request to 736 continue the request (Section 5.1). The AS validates the 737 interaction reference ensuring that the reference is associated 738 with the request being continued. 740 9. If the request has been authorized, the AS grants access to the 741 information in the form of access tokens (Section 3.2) and 742 direct subject information (Section 3.4) to the client instance. 744 10. The client instance uses the access token (Section 7.2) to call 745 the RS. 747 11. The RS validates the access token and returns an appropriate 748 response for the API. 750 An example set of protocol messages for this method can be found in 751 Appendix D.1. 753 1.5.3. User-code Interaction 755 In this example flow, the client instance is a device that is capable 756 of presenting a short, human-readable code to the user and directing 757 the user to enter that code at a known URI. The URI the user enters 758 the code at is an interactive service hosted by the AS in this 759 example. The client instance is not capable of presenting an 760 arbitrary URI to the user, nor is it capable of accepting incoming 761 HTTP requests from the user's browser. The client instance polls the 762 AS while it is waiting for the RO to authorize the request. The 763 user's interaction is assumed to occur on a secondary device. In 764 this example it is assumed that the user is both the end user and RO, 765 though the user is not assumed to be interacting with the client 766 instance through the same web browser used for interaction at the AS. 768 +--------+ +--------+ +------+ 769 | Client | | AS | | User | 770 |Instance|--(1)--- Request Access --------->| | | | 771 | | | | | | 772 | |<-(2)-- Interaction Needed -------| | | | 773 | | | | | | 774 | |+ (3) + + Display User Code + + + + + + + + + + + + >| | 775 | | | | | | 776 | | | |<+ (4) + | | 777 | | | |Open URI | | 778 | | | | | | 779 | | | |<+ (5) +>| | 780 | | | | AuthN | | 781 | |--(9)--- Continue Request (A) --->| | | | 782 | | | |<+ (6) +>| | 783 | |<-(10)- Not Yet Granted (Wait) ---| | Code | | 784 | | | | | | 785 | | | |<+ (7) +>| | 786 | | | | AuthZ | | 787 | | | | | | 788 | | | |<+ (8) +>| | 789 | | | |Completed| | 790 | | | | | | 791 | |--(11)-- Continue Request (B) --->| | +------+ 792 | | | | 793 | |<-(12)----- Grant Access ---------| | 794 | | | | 795 | | | | +--------+ 796 | |--(13)-- Access API ---------------------------->| RS | 797 | | | | | | 798 | |<-(14)-- API Response ---------------------------| | 799 | | | | +--------+ 800 +--------+ +--------+ 801 1. The client instance requests access to the resource (Section 2). 802 The client instance indicates that it can display a user code 803 (Section 2.5.1.3). 805 2. The AS determines that interaction is needed and responds 806 (Section 3) with a user code to communicate to the user 807 (Section 3.3.3). This could optionally include a URI to direct 808 the user to, but this URI should be static and so could be 809 configured in the client instance's documentation. The AS also 810 includes information the client instance will need to continue 811 the request (Section 3.1) in (8) and (10). The AS associates 812 this continuation information with an ongoing request that will 813 be referenced in (4), (6), (8), and (10). 815 3. The client instance stores the continuation information from (2) 816 for use in (8) and (10). The client instance then communicates 817 the code to the user (Section 4.1.2) given by the AS in (2). 819 4. The users directs their browser to the user code URI. This URI 820 is stable and can be communicated via the client software's 821 documentation, the AS documentation, or the client software 822 itself. Since it is assumed that the RO will interact with the 823 AS through a secondary device, the client instance does not 824 provide a mechanism to launch the RO's browser at this URI. 826 5. The end user authenticates at the AS, taking on the role of the 827 RO. 829 6. The RO enters the code communicated in (3) to the AS. The AS 830 validates this code against a current request in process. 832 7. As the RO, the user authorizes the pending request from the 833 client instance. 835 8. When the AS is done interacting with the user, the AS indicates 836 to the RO that the request has been completed. 838 9. Meanwhile, the client instance loads the continuation 839 information stored at (3) and continues the request (Section 5). 840 The AS determines which ongoing access request is referenced 841 here and checks its state. 843 10. If the access request has not yet been authorized by the RO in 844 (6), the AS responds to the client instance to continue the 845 request (Section 3.1) at a future time through additional polled 846 continuation requests. This response can include updated 847 continuation information as well as information regarding how 848 long the client instance should wait before calling again. The 849 client instance replaces its stored continuation information 850 from the previous response (2). Note that the AS may need to 851 determine that the RO has not approved the request in a 852 sufficient amount of time and return an appropriate error to the 853 client instance. 855 11. The client instance continues to poll the AS (Section 5.2) with 856 the new continuation information in (9). 858 12. If the request has been authorized, the AS grants access to the 859 information in the form of access tokens (Section 3.2) and 860 direct subject information (Section 3.4) to the client instance. 862 13. The client instance uses the access token (Section 7.2) to call 863 the RS. 865 14. The RS validates the access token and returns an appropriate 866 response for the API. 868 An example set of protocol messages for this method can be found in 869 Appendix D.2. 871 1.5.4. Asynchronous Authorization 873 In this example flow, the end user and RO roles are fulfilled by 874 different parties, and the RO does not interact with the client 875 instance. The AS reaches out asynchronously to the RO during the 876 request process to gather the RO's authorization for the client 877 instance's request. The client instance polls the AS while it is 878 waiting for the RO to authorize the request. 880 +--------+ +--------+ +------+ 881 | Client | | AS | | RO | 882 |Instance|--(1)--- Request Access --------->| | | | 883 | | | | | | 884 | |<-(2)-- Not Yet Granted (Wait) ---| | | | 885 | | | |<+ (3) +>| | 886 | | | | AuthN | | 887 | |--(6)--- Continue Request (A) --->| | | | 888 | | | |<+ (4) +>| | 889 | |<-(7)-- Not Yet Granted (Wait) ---| | AuthZ | | 890 | | | | | | 891 | | | |<+ (5) +>| | 892 | | | |Completed| | 893 | | | | | | 894 | |--(8)--- Continue Request (B) --->| | +------+ 895 | | | | 896 | |<-(9)------ Grant Access ---------| | 897 | | | | 898 | | | | +--------+ 899 | |--(10)-- Access API ---------------------------->| RS | 900 | | | | | | 901 | |<-(11)-- API Response ---------------------------| | 902 | | | | +--------+ 903 +--------+ +--------+ 905 1. The client instance requests access to the resource (Section 2). 906 The client instance does not send any interaction modes to the 907 server, indicating that it does not expect to interact with the 908 RO. The client instance can also signal which RO it requires 909 authorization from, if known, by using the user request section 910 (Section 2.4). 912 2. The AS determines that interaction is needed, but the client 913 instance cannot interact with the RO. The AS responds 914 (Section 3) with the information the client instance will need 915 to continue the request (Section 3.1) in (6) and (8), including 916 a signal that the client instance should wait before checking 917 the status of the request again. The AS associates this 918 continuation information with an ongoing request that will be 919 referenced in (3), (4), (5), (6), and (8). 921 3. The AS determines which RO to contact based on the request in 922 (1), through a combination of the user request (Section 2.4), 923 the resources request (Section 2.1), and other policy 924 information. The AS contacts the RO and authenticates them. 926 4. The RO authorizes the pending request from the client instance. 928 5. When the AS is done interacting with the RO, the AS indicates to 929 the RO that the request has been completed. 931 6. Meanwhile, the client instance loads the continuation 932 information stored at (2) and continues the request (Section 5). 933 The AS determines which ongoing access request is referenced 934 here and checks its state. 936 7. If the access request has not yet been authorized by the RO in 937 (6), the AS responds to the client instance to continue the 938 request (Section 3.1) at a future time through additional 939 polling. This response can include refreshed credentials as 940 well as information regarding how long the client instance 941 should wait before calling again. The client instance replaces 942 its stored continuation information from the previous response 943 (2). Note that the AS may need to determine that the RO has not 944 approved the request in a sufficient amount of time and return 945 an appropriate error to the client instance. 947 8. The client instance continues to poll the AS (Section 5.2) with 948 the new continuation information from (7). 950 9. If the request has been authorized, the AS grants access to the 951 information in the form of access tokens (Section 3.2) and 952 direct subject information (Section 3.4) to the client instance. 954 10. The client instance uses the access token (Section 7.2) to call 955 the RS. 957 11. The RS validates the access token and returns an appropriate 958 response for the API. 960 An example set of protocol messages for this method can be found in 961 Appendix D.4. 963 1.5.5. Software-only Authorization 965 In this example flow, the AS policy allows the client instance to 966 make a call on its own behalf, without the need for an RO to be 967 involved at runtime to approve the decision. Since there is no 968 explicit RO, the client instance does not interact with an RO. 970 +--------+ +--------+ 971 | Client | | AS | 972 |Instance|--(1)--- Request Access --->| | 973 | | | | 974 | |<-(2)---- Grant Access -----| | 975 | | | | +--------+ 976 | |--(3)--- Access API ------------------->| RS | 977 | | | | | | 978 | |<-(4)--- API Response ------------------| | 979 | | | | +--------+ 980 +--------+ +--------+ 982 1. The client instance requests access to the resource (Section 2). 983 The client instance does not send any interaction modes to the 984 server. 986 2. The AS determines that the request has been authorized, the AS 987 grants access to the resource in the form of access tokens 988 (Section 3.2) to the client instance. Note that direct subject 989 information (Section 3.4) is not generally applicable in this use 990 case, as there is no user involved. 992 3. The client instance uses the access token (Section 7.2) to call 993 the RS. 995 4. The RS validates the access token and returns an appropriate 996 response for the API. 998 An example set of protocol messages for this method can be found in 999 Appendix D.3. 1001 1.5.6. Refreshing an Expired Access Token 1003 In this example flow, the client instance receives an access token to 1004 access a resource server through some valid GNAP process. The client 1005 instance uses that token at the RS for some time, but eventually the 1006 access token expires. The client instance then gets a new access 1007 token by rotating the expired access token at the AS using the 1008 token's management URI. 1010 +--------+ +--------+ 1011 | Client | | AS | 1012 |Instance|--(1)--- Request Access ----------------->| | 1013 | | | | 1014 | |<-(2)--- Grant Access --------------------| | 1015 | | | | 1016 | | +--------+ | | 1017 | |--(3)--- Access Resource --->| RS | | | 1018 | | | | | | 1019 | |<-(4)--- Success Response ---| | | | 1020 | | | | | | 1021 | | | | | | 1022 | | | | | | 1023 | |--(5)--- Access Resource --->| | | | 1024 | | | | | | 1025 | |<-(6)--- Error Response -----| | | | 1026 | | +--------+ | | 1027 | | | | 1028 | |--(7)--- Rotate Token ------------------->| | 1029 | | | | 1030 | |<-(8)--- Rotated Token -------------------| | 1031 | | | | 1032 +--------+ +--------+ 1034 1. The client instance requests access to the resource (Section 2). 1036 2. The AS grants access to the resource (Section 3) with an access 1037 token (Section 3.2) usable at the RS. The access token response 1038 includes a token management URI. 1040 3. The client instance uses the access token (Section 7.2) to call 1041 the RS. 1043 4. The RS validates the access token and returns an appropriate 1044 response for the API. 1046 5. Time passes and the client instance uses the access token to call 1047 the RS again. 1049 6. The RS validates the access token and determines that the access 1050 token is expired. The RS responds to the client instance with an 1051 error. 1053 7. The client instance calls the token management URI returned in 1054 (2) to rotate the access token (Section 6.1). The client 1055 instance uses the access token (Section 7.2) in this call as well 1056 as the appropriate key, see the token rotation section for 1057 details. 1059 8. The AS validates the rotation request including the signature and 1060 keys presented in (5) and returns a new access token 1061 (Section 3.2.1). The response includes a new access token and 1062 can also include updated token management information, which the 1063 client instance will store in place of the values returned in 1064 (2). 1066 1.5.7. Requesting User Information 1068 In this scenario, the client instance does not call an RS and does 1069 not request an access token. Instead, the client instance only 1070 requests and is returned direct subject information (Section 3.4). 1071 Many different interaction modes can be used in this scenario, so 1072 these are shown only in the abstract as functions of the AS here. 1074 +--------+ +--------+ +------+ 1075 | Client | | AS | | User | 1076 |Instance| | | | | 1077 | |--(1)--- Request Access --------->| | | | 1078 | | | | | | 1079 | |<-(2)-- Interaction Needed -------| | | | 1080 | | | | | | 1081 | |+ (3) + Facilitate Interaction + + + + + + + + + + > | | 1082 | | | | | | 1083 | | | |<+ (4) +>| | 1084 | | | | AuthN | | 1085 | | | | | | 1086 | | | |<+ (5) +>| | 1087 | | | | AuthZ | | 1088 | | | | | | 1089 | |< (6) + Signal Continuation + + + + + + + + + + + + +| | 1090 | | | | +------+ 1091 | |--(7)--- Continue Request ------->| | 1092 | | | | 1093 | |<-(8)----- Grant Access ----------| | 1094 | | | | 1095 +--------+ +--------+ 1097 1. The client instance requests access to subject information 1098 (Section 2). 1100 2. The AS determines that interaction is needed and responds 1101 (Section 3) with appropriate information for facilitating user 1102 interaction (Section 3.3). 1104 3. The client instance facilitates the user interacting with the AS 1105 (Section 4) as directed in (2). 1107 4. The user authenticates at the AS, taking on the role of the RO. 1109 5. As the RO, the user authorizes the pending request from the 1110 client instance. 1112 6. When the AS is done interacting with the user, the AS returns the 1113 user to the client instance and signals continuation. 1115 7. The client instance loads the continuation information from (2) 1116 and calls the AS to continue the request (Section 5). 1118 8. If the request has been authorized, the AS grants access to the 1119 requested direct subject information (Section 3.4) to the client 1120 instance. At this stage, the user is generally considered 1121 "logged in" to the client instance based on the identifiers and 1122 assertions provided by the AS. Note that the AS can restrict the 1123 subject information returned and it might not match what the 1124 client instance requested, see the section on subject information 1125 for details. 1127 2. Requesting Access 1129 To start a request, the client instance sends a JSON [RFC8259] 1130 document with an object as its root. Each member of the request 1131 object represents a different aspect of the client instance's 1132 request. Each field is described in detail in a section below. 1134 access_token (object / array of objects): Describes the rights and 1135 properties associated with the requested access token. REQUIRED 1136 if requesting an access token. See Section 2.1. 1138 subject (object): Describes the information about the RO that the 1139 client instance is requesting to be returned directly in the 1140 response from the AS. REQUIRED if requesting subject information. 1141 See Section 2.2. 1143 client (object / string): Describes the client instance that is 1144 making this request, including the key that the client instance 1145 will use to protect this request and any continuation requests at 1146 the AS and any user-facing information about the client instance 1147 used in interactions. REQUIRED. See Section 2.3. 1149 user (object / string): Identifies the end user to the AS in a 1150 manner that the AS can verify, either directly or by interacting 1151 with the end user to determine their status as the RO. OPTIONAL. 1152 See Section 2.4. 1154 interact (object): Describes the modes that the client instance 1155 supports for allowing the RO to interact with the AS and modes for 1156 the client instance to receive updates when interaction is 1157 complete. REQUIRED if interaction is supported. See Section 2.5. 1159 Additional members of this request object can be defined by 1160 extensions to this protocol as described in Section 2.6. 1162 A non-normative example of a grant request is below: 1164 { 1165 "access_token": { 1166 "access": [ 1167 { 1168 "type": "photo-api", 1169 "actions": [ 1170 "read", 1171 "write", 1172 "dolphin" 1173 ], 1174 "locations": [ 1175 "https://server.example.net/", 1176 "https://resource.local/other" 1177 ], 1178 "datatypes": [ 1179 "metadata", 1180 "images" 1181 ] 1182 }, 1183 "dolphin-metadata" 1184 ] 1185 }, 1186 "client": { 1187 "display": { 1188 "name": "My Client Display Name", 1189 "uri": "https://example.net/client" 1190 }, 1191 "key": { 1192 "proof": "httpsig", 1193 "jwk": { 1194 "kty": "RSA", 1195 "e": "AQAB", 1196 "kid": "xyz-1", 1197 "alg": "RS256", 1198 "n": "kOB5rR4Jv0GMeL...." 1199 } 1200 } 1201 }, 1202 "interact": { 1203 "start": ["redirect"], 1204 "finish": { 1205 "method": "redirect", 1206 "uri": "https://client.example.net/return/123455", 1207 "nonce": "LKLTI25DK82FX4T4QFZC" 1208 } 1209 }, 1210 "subject": { 1211 "sub_id_formats": ["iss_sub", "opaque"], 1212 "assertion_formats": ["id_token"] 1213 } 1214 } 1216 The request and response MUST be sent as a JSON object in the body of 1217 the HTTP POST request with Content-Type application/json, unless 1218 otherwise specified by the signature mechanism. 1220 The authorization server MUST include the HTTP "Cache-Control" 1221 response header field [RFC7234] with a value set to "no-store". 1223 2.1. Requesting Access to Resources 1225 If the client instance is requesting one or more access tokens for 1226 the purpose of accessing an API, the client instance MUST include an 1227 access_token field. This field MUST be an object (for a single 1228 access token (Section 2.1.1)) or an array of these objects (for 1229 multiple access tokens (Section 2.1.2)), as described in the 1230 following sections. 1232 2.1.1. Requesting a Single Access Token 1234 To request a single access token, the client instance sends an 1235 acccess_token object composed of the following fields. 1237 access (array of objects/strings): Describes the rights that the 1238 client instance is requesting for one or more access tokens to be 1239 used at RS's. REQUIRED. See Section 8. 1241 label (string): A unique name chosen by the client instance to refer 1242 to the resulting access token. The value of this field is opaque 1243 to the AS. If this field is included in the request, the AS MUST 1244 include the same label in the token response (Section 3.2). 1245 REQUIRED if used as part of a multiple access token request 1246 (Section 2.1.2), OPTIONAL otherwise. 1248 flags (array of strings): A set of flags that indicate desired 1249 attributes or behavior to be attached to the access token by the 1250 AS. OPTIONAL. 1252 The values of the flags field defined by this specification are as 1253 follows: 1255 "bearer": If this flag is included, the access token being requested 1256 is a bearer token. If this flag is omitted, the access token is 1257 bound to the key used by the client instance in this request (or 1258 that key's most recent rotation) and the access token MUST be 1259 presented using the same key and proofing method. Methods for 1260 presenting bound and bearer access tokens are described in 1261 Section 7.2. See Section 12.7 for additional considerations on 1262 the use of bearer tokens. 1264 "split": If this flag is included, the client instance is capable of 1265 receiving a different number of tokens than specified in the token 1266 request (Section 2.1), including receiving multiple access tokens 1267 (Section 3.2.2) in response to any single token request 1268 (Section 2.1.1) or a different number of access tokens than 1269 requested in a multiple access token request (Section 2.1.2). The 1270 label fields of the returned additional tokens are chosen by the 1271 AS. The client instance MUST be able to tell from the token 1272 response where and how it can use each of the access tokens. [[ 1273 See issue #37 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1274 issues/37) ]] 1276 Flag values MUST NOT be included more than once. 1278 Additional flags can be defined by extensions using a registry TBD 1279 (Section 11). 1281 In the following example, the client instance is requesting access to 1282 a complex resource described by a pair of access request object. 1284 "access_token": { 1285 "access": [ 1286 { 1287 "type": "photo-api", 1288 "actions": [ 1289 "read", 1290 "write", 1291 "delete" 1292 ], 1293 "locations": [ 1294 "https://server.example.net/", 1295 "https://resource.local/other" 1296 ], 1297 "datatypes": [ 1298 "metadata", 1299 "images" 1300 ] 1301 }, 1302 { 1303 "type": "walrus-access", 1304 "actions": [ 1305 "foo", 1306 "bar" 1307 ], 1308 "locations": [ 1309 "https://resource.other/" 1310 ], 1311 "datatypes": [ 1312 "data", 1313 "pictures", 1314 "walrus whiskers" 1315 ] 1316 } 1317 ], 1318 "label": "token1-23", 1319 "flags": [ "split" ] 1320 } 1322 If access is approved, the resulting access token is valid for the 1323 described resource and is bound to the client instance's key (or its 1324 most recent rotation). The token is labeled "token1-23" and could be 1325 split into multiple access tokens by the AS, if the AS chooses. The 1326 token response structure is described in Section 3.2.1. 1328 2.1.2. Requesting Multiple Access Tokens 1330 To request multiple access tokens to be returned in a single 1331 response, the client instance sends an array of objects as the value 1332 of the access_token parameter. Each object MUST conform to the 1333 request format for a single access token request, as specified in 1334 requesting a single access token (Section 2.1.1). Additionally, each 1335 object in the array MUST include the label field, and all values of 1336 these fields MUST be unique within the request. If the client 1337 instance does not include a label value for any entry in the array, 1338 or the values of the label field are not unique within the array, the 1339 AS MUST return an error. 1341 The following non-normative example shows a request for two separate 1342 access tokens, token1 and token2. 1344 "access_token": [ 1345 { 1346 "label": "token1", 1347 "access": [ 1348 { 1349 "type": "photo-api", 1350 "actions": [ 1351 "read", 1352 "write", 1353 "dolphin" 1354 ], 1355 "locations": [ 1356 "https://server.example.net/", 1357 "https://resource.local/other" 1358 ], 1359 "datatypes": [ 1360 "metadata", 1361 "images" 1362 ] 1363 }, 1364 "dolphin-metadata" 1365 ] 1366 }, 1367 { 1368 "label": "token2", 1369 "access": [ 1370 { 1371 "type": "walrus-access", 1372 "actions": [ 1373 "foo", 1374 "bar" 1375 ], 1376 "locations": [ 1377 "https://resource.other/" 1378 ], 1379 "datatypes": [ 1380 "data", 1381 "pictures", 1382 "walrus whiskers" 1383 ] 1384 } 1385 ], 1386 "flags": [ "bearer" ] 1387 } 1388 ] 1389 All approved access requests are returned in the multiple access 1390 token response (Section 3.2.2) structure using the values of the 1391 label fields in the request. 1393 2.2. Requesting Subject Information 1395 If the client instance is requesting information about the RO from 1396 the AS, it sends a subject field as a JSON object. This object MAY 1397 contain the following fields (or additional fields defined in a 1398 registry TBD (Section 11)). 1400 sub_id_formats (array of strings): An array of subject identifier 1401 subject formats requested for the RO, as defined by 1402 [I-D.ietf-secevent-subject-identifiers]. REQUIRED if subject 1403 identifiers are requested. 1405 assertion_formats (array of strings): An array of requested 1406 assertion formats. Possible values include id_token for an [OIDC] 1407 ID Token and saml2 for a SAML 2 assertion. Additional assertion 1408 formats are defined by a registry TBD (Section 11). REQUIRED if 1409 assertions are requested. 1411 "subject": { 1412 "sub_id_formats": [ "iss_sub", "opaque" ], 1413 "assertion_formats": [ "id_token", "saml2" ] 1414 } 1416 The AS can determine the RO's identity and permission for releasing 1417 this information through interaction with the RO (Section 4), AS 1418 policies, or assertions presented by the client instance 1419 (Section 2.4). If this is determined positively, the AS MAY return 1420 the RO's information in its response (Section 3.4) as requested. 1422 Subject identifier types requested by the client instance serve only 1423 to identify the RO in the context of the AS and can't be used as 1424 communication channels by the client instance, as discussed in 1425 Section 3.4. 1427 The AS SHOULD NOT re-use subject identifiers for multiple different 1428 ROs. 1430 The "formats" and "assertions" request fields are independent of each 1431 other, and a returned assertion MAY use a different subject 1432 identifier than other assertions and subject identifiers in the 1433 response. All subject identifiers and assertions returned MUST refer 1434 to the same person. 1436 2.3. Identifying the Client Instance 1438 When sending a non-continuation request to the AS, the client 1439 instance MUST identify itself by including the client field of the 1440 request and by signing the request as described in Section 7.3. Note 1441 that for a continuation request (Section 5), the client instance is 1442 identified by its association with the request being continued and so 1443 this field is not sent under those circumstances. 1445 When client instance information is sent by value, the client field 1446 of the request consists of a JSON object with the following fields. 1448 key (object / string): The public key of the client instance to be 1449 used in this request as described in Section 7.1 or a reference to 1450 a key as described in Section 7.1.1. REQUIRED. 1452 class_id (string): An identifier string that the AS can use to 1453 identify the client software comprising this client instance. The 1454 contents and format of this field are up to the AS. OPTIONAL. 1456 display (object): An object containing additional information that 1457 the AS MAY display to the RO during interaction, authorization, 1458 and management. OPTIONAL. 1460 "client": { 1461 "key": { 1462 "proof": "httpsig", 1463 "jwk": { 1464 "kty": "RSA", 1465 "e": "AQAB", 1466 "kid": "xyz-1", 1467 "alg": "RS256", 1468 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 1469 }, 1470 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 1471 }, 1472 "class_id": "web-server-1234", 1473 "display": { 1474 "name": "My Client Display Name", 1475 "uri": "https://example.net/client" 1476 } 1477 } 1479 Additional fields are defined in a registry TBD (Section 11). 1481 The client instance MUST prove possession of any presented key by the 1482 proof mechanism associated with the key in the request. Proof types 1483 are defined in a registry TBD (Section 11) and an initial set of 1484 methods is described in Section 7.3. 1486 If the same public key is sent by value on different access requests, 1487 the AS MUST treat these requests as coming from the same client 1488 instance for purposes of identification, authentication, and policy 1489 application. If the AS does not know the client instance's public 1490 key ahead of time, the AS MAY accept or reject the request based on 1491 AS policy, attestations within the client request, and other 1492 mechanisms. 1494 [[ See issue #44 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1495 issues/44) ]] 1497 The client instance MUST NOT send a symmetric key by value in the 1498 request, as doing so would expose the key directly instead of simply 1499 proving possession of it. See considerations on symmetric keys in 1500 Section 12.5. 1502 The client instance's key MAY be pre-registered with the AS ahead of 1503 time and associated with a set of policies and allowable actions 1504 pertaining to that client. If this pre-registration includes other 1505 fields that can occur in the client request object described in this 1506 section, such as class_id or display, the pre-registered values MUST 1507 take precedence over any values given at runtime. Additional fields 1508 sent during a request but not present in a pre-registered client 1509 instance record at the AS SHOULD NOT be added to the client's pre- 1510 registered record. See additional considerations regarding client 1511 instance impersonation in Section 12.13. 1513 A client instance that is capable of talking to multiple AS's SHOULD 1514 use a different key for each AS to prevent a class of mix-up attacks 1515 as described in Section 12.28. 1517 2.3.1. Identifying the Client Instance by Reference 1519 If the client instance has an instance identifier that the AS can use 1520 to determine appropriate key information, the client instance can 1521 send this instance identifier as a direct reference value in lieu of 1522 the client object. The instance identifier MAY be assigned to a 1523 client instance at runtime through a grant response (Section 3.5) or 1524 MAY be obtained in another fashion, such as a static registration 1525 process at the AS. 1527 "client": "client-541-ab" 1528 When the AS receives a request with an instance identifier, the AS 1529 MUST ensure that the key used to sign the request (Section 7.3) is 1530 associated with the instance identifier. 1532 If the AS does not recognize the instance identifier, the request 1533 MUST be rejected with an error. 1535 If the client instance is identified in this manner, the registered 1536 key for the client instance MAY be a symmetric key known to the AS. 1537 See considerations on symmetric keys in Section 12.5. 1539 2.3.2. Providing Displayable Client Instance Information 1541 If the client instance has additional information to display to the 1542 RO during any interactions at the AS, it MAY send that information in 1543 the "display" field. This field is a JSON object that declares 1544 information to present to the RO during any interactive sequences. 1546 name (string): Display name of the client software. RECOMMENDED. 1548 uri (string): User-facing web page of the client software. 1549 OPTIONAL. 1551 logo_uri (string) Display image to represent the client software. 1552 The logo MAY be passed by value by using a data: URI [RFC2397] 1553 referencing an image mediatype. OPTIONAL. 1555 "display": { 1556 "name": "My Client Display Name", 1557 "uri": "https://example.net/client", 1558 "logo_uri": "data:image/png;base64,Eeww...=" 1559 } 1561 Additional display fields are defined by a registry TBD (Section 11). 1563 The AS SHOULD use these values during interaction with the RO. The 1564 values are for informational purposes only and MUST NOT be taken as 1565 authentic proof of the client instance's identity or source. The AS 1566 MAY restrict display values to specific client instances, as 1567 identified by their keys in Section 2.3. See additional 1568 considerations for displayed client information in Section 12.13. 1570 2.3.3. Authenticating the Client Instance 1572 If the presented key is known to the AS and is associated with a 1573 single instance of the client software, the process of presenting a 1574 key and proving possession of that key is sufficient to authenticate 1575 the client instance to the AS. The AS MAY associate policies with 1576 the client instance identified by this key, such as limiting which 1577 resources can be requested and which interaction methods can be used. 1578 For example, only specific client instances with certain known keys 1579 might be trusted with access tokens without the AS interacting 1580 directly with the RO as in Appendix D.3. 1582 The presentation of a key allows the AS to strongly associate 1583 multiple successive requests from the same client instance with each 1584 other. This is true when the AS knows the key ahead of time and can 1585 use the key to authenticate the client instance, but also if the key 1586 is ephemeral and created just for this series of requests. As such 1587 the AS MAY allow for client instances to make requests with unknown 1588 keys. This pattern allows for ephemeral client instances, such as 1589 single-page applications, and client software with many individual 1590 long-lived instances, such as mobile applications, to generate key 1591 pairs per instance and use the keys within the protocol without 1592 having to go through a separate registration step. The AS MAY limit 1593 which capabilities are made available to client instances with 1594 unknown keys. For example, the AS could have a policy saying that 1595 only previously-registered client instances can request particular 1596 resources, or that all client instances with unknown keys have to be 1597 interactively approved by an RO. 1599 2.4. Identifying the User 1601 If the client instance knows the identity of the end user through one 1602 or more identifiers or assertions, the client instance MAY send that 1603 information to the AS in the "user" field. The client instance MAY 1604 pass this information by value or by reference. 1606 sub_ids (array of objects): An array of subject identifiers for the 1607 end user, as defined by [I-D.ietf-secevent-subject-identifiers]. 1608 OPTIONAL. 1610 assertions (array of objects) An array containing assertions as 1611 objects each containing the assertion format and the assertion 1612 value as the JSON string serialization of the assertion. 1613 OPTIONAL. 1615 "user": { 1616 "sub_ids": [ { 1617 "format": "opaque", 1618 "id": "J2G8G8O4AZ" 1619 } ], 1620 "assertions": [ { 1621 "format": "id_token", 1622 "value": "eyj..." 1623 } ] 1624 } 1626 Subject identifiers are hints to the AS in determining the RO and 1627 MUST NOT be taken as declarative statements that a particular RO is 1628 present at the client instance and acting as the end user. 1629 Assertions SHOULD be validated by the AS. [[ See issue #49 1630 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/49) ]] 1632 If the identified end user does not match the RO present at the AS 1633 during an interaction step, the AS SHOULD reject the request with an 1634 error. 1636 [[ See issue #50 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1637 issues/50) ]] 1639 If the AS trusts the client instance to present verifiable 1640 assertions, the AS MAY decide, based on its policy, to skip 1641 interaction with the RO, even if the client instance provides one or 1642 more interaction modes in its request. 1644 See Section 12.27 for considerations that the AS has to make when 1645 accepting and processing assertions from the client instance. 1647 2.4.1. Identifying the User by Reference 1649 The AS can identify the current end user to the client instance with 1650 a reference which can be used by the client instance to refer to the 1651 end user across multiple requests. If the client instance has a 1652 reference for the end user at this AS, the client instance MAY pass 1653 that reference as a string. The format of this string is opaque to 1654 the client instance. 1656 "user": "XUT2MFM1XBIKJKSDU8QM" 1658 One means of dynamically obtaining such a user reference is from the 1659 AS returning an opaque subject identifier as described in 1660 Section 3.4. Other means of configuring a client instance with a 1661 user identifier are out of scope of this specification. 1663 User reference identifiers are not intended to be human-readable user 1664 identifiers or structured assertions. For the client instance to 1665 send either of these, use the full user request object (Section 2.4) 1666 instead. 1668 If the AS does not recognize the user reference, it MUST return an 1669 error. 1671 2.5. Interacting with the User 1673 Often, the AS will require interaction with the RO (Section 4) in 1674 order to approve a requested delegation to the client instance for 1675 both access to resources and direct subject information. Many times 1676 the end user using the client instance is the same person as the RO, 1677 and the client instance can directly drive interaction with the end 1678 user by facilitating the process through means such as redirection to 1679 a URI or launching an application. Other times, the client instance 1680 can provide information to start the RO's interaction on a secondary 1681 device, or the client instance will wait for the RO to approve the 1682 request asynchronously. The client instance could also be signaled 1683 that interaction has concluded through a callback mechanism. 1685 The client instance declares the parameters for interaction methods 1686 that it can support using the interact field. 1688 The interact field is a JSON object with three keys whose values 1689 declare how the client can initiate and complete the request, as well 1690 as provide hints to the AS about user preferences such as locale. A 1691 client instance MUST NOT declare an interaction mode it does not 1692 support. The client instance MAY send multiple modes in the same 1693 request. There is no preference order specified in this request. An 1694 AS MAY respond to any, all, or none of the presented interaction 1695 modes (Section 3.3) in a request, depending on its capabilities and 1696 what is allowed to fulfill the request. 1698 start (array of strings/objects): Indicates how the client instance 1699 can start an interaction. REQUIRED. 1701 finish (object): Indicates how the client instance can receive an 1702 indication that interaction has finished at the AS. OPTIONAL. 1704 hints (object): Provides additional information to inform the 1705 interaction process at the AS. OPTIONAL. 1707 In this non-normative example, the client instance is indicating that 1708 it can redirect (Section 2.5.1.1) the end user to an arbitrary URI 1709 and can receive a redirect (Section 2.5.2.1) through a browser 1710 request. 1712 "interact": { 1713 "start": ["redirect"], 1714 "finish": { 1715 "method": "redirect", 1716 "uri": "https://client.example.net/return/123455", 1717 "nonce": "LKLTI25DK82FX4T4QFZC" 1718 } 1719 } 1721 In this non-normative example, the client instance is indicating that 1722 it can display a user code (Section 2.5.1.3) and direct the end user 1723 to an arbitrary URI (Section 2.5.1.1) on a secondary device, but it 1724 cannot accept a redirect or push callback. 1726 "interact": { 1727 "start": ["redirect", "user_code"] 1728 } 1730 If the client instance does not provide a suitable interaction 1731 mechanism, the AS cannot contact the RO asynchronously, and the AS 1732 determines that interaction is required, then the AS SHOULD return an 1733 error since the client instance will be unable to complete the 1734 request without authorization. 1736 The AS SHOULD handle any interact request as a one-time-use mechanism 1737 and SHOULD apply suitable timeouts to any interaction mechanisms 1738 provided, including user codes and redirection URIs. The client 1739 instance SHOULD apply suitable timeouts to any callback URIs. 1741 2.5.1. Start Mode Definitions 1743 This specification defines the following interaction start modes as 1744 an array of string values under the start key: 1746 "redirect": Indicates that the client instance can direct the end 1747 user to an arbitrary URI for interaction. Section 2.5.1.1 1749 "app": Indicates that the client instance can launch an application 1750 on the end user's device for interaction. Section 2.5.1.2 1752 "user_code": Indicates that the client instance can communicate a 1753 human-readable short code to the end user for use with a stable 1754 URI. Section 2.5.1.3 1756 "user_code_uri": Indicates that the client instance can communicate 1757 a human-readable short code to the end user for use with a short, 1758 dynamic URI. Section 2.5.1.4 1760 2.5.1.1. Redirect to an Arbitrary URI 1762 If the client instance is capable of directing the end user to a URI 1763 defined by the AS at runtime, the client instance indicates this by 1764 including redirect in the array under the start key. The means by 1765 which the client instance will activate this URI is out of scope of 1766 this specification, but common methods include an HTTP redirect, 1767 launching a browser on the end user's device, providing a scannable 1768 image encoding, and printing out a URI to an interactive console. 1769 While this URI is generally hosted at the AS, the client instance can 1770 make no assumptions about its contents, composition, or relationship 1771 to the AS grant URI. 1773 "interact": { 1774 "start": ["redirect"] 1775 } 1777 If this interaction mode is supported for this client instance and 1778 request, the AS returns a redirect interaction response 1779 Section 3.3.1. The client instance manages this interaction method 1780 as described in Section 4.1.1. 1782 See Section 12.26 for more considerations regarding the use of front- 1783 channel communication techniques such as this. 1785 2.5.1.2. Open an Application-specific URI 1787 If the client instance can open a URI associated with an application 1788 on the end user's device, the client instance indicates this by 1789 including app in the array under the start key. The means by which 1790 the client instance determines the application to open with this URI 1791 are out of scope of this specification. 1793 "interact": { 1794 "start": ["app"] 1795 } 1797 If this interaction mode is supported for this client instance and 1798 request, the AS returns an app interaction response with an app URI 1799 payload Section 3.3.2. The client instance manages this interaction 1800 method as described in Section 4.1.4. 1802 [[ See issue #54 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1803 issues/54) ]] 1805 2.5.1.3. Display a Short User Code 1807 If the client instance is capable of displaying or otherwise 1808 communicating a short, human-entered code to the RO, the client 1809 instance indicates this by including user_code in the array under the 1810 start key. This code is to be entered at a static URI that does not 1811 change at runtime. The client instance has no reasonable means to 1812 communicate a dynamic URI to the RO, and so this URI is usually 1813 communicated out of band to the RO through documentation or other 1814 messaging outside of GNAP. While this URI is generally hosted at the 1815 AS, the client instance can make no assumptions about its contents, 1816 composition, or relationship to the AS grant URI. 1818 "interact": { 1819 "start": ["user_code"] 1820 } 1822 If this interaction mode is supported for this client instance and 1823 request, the AS returns a user code as specified in Section 3.3.3. 1824 The client instance manages this interaction method as described in 1825 Section 4.1.2. 1827 2.5.1.4. Display a Short User Code and URI 1829 If the client instance is capable of displaying or otherwise 1830 communicating a short, human-entered code along with a short, human- 1831 entered URI to the RO, the client instance indicates this by 1832 including user_code_uri in the array under the start key. This code 1833 is to be entered at the dynamic URL given in the response. While 1834 this URL is generally hosted at the AS, the client instance can make 1835 no assumptions about its contents, composition, or relationship to 1836 the AS grant URL. 1838 "interact": { 1839 "start": ["user_code_uri"] 1840 } 1842 If this interaction mode is supported for this client instance and 1843 request, the AS returns a user code and interaction URL as specified 1844 in Section 3.3.4. The client instance manages this interaction 1845 method as described in Section 4.1.3. 1847 2.5.2. Finish Interaction Methods 1849 If the client instance is capable of receiving a message from the AS 1850 indicating that the RO has completed their interaction, the client 1851 instance indicates this by sending the following members of an object 1852 under the finish key. 1854 method (string): The callback method that the AS will use to contact 1855 the client instance. REQUIRED. 1857 uri (string): Indicates the URI that the AS will either send the RO 1858 to after interaction or send an HTTP POST request. This URI MAY 1859 be unique per request and MUST be hosted by or accessible by the 1860 client instance. This URI MUST NOT contain any fragment 1861 component. This URI MUST be protected by HTTPS, be hosted on a 1862 server local to the RO's browser ("localhost"), or use an 1863 application-specific URI scheme. If the client instance needs any 1864 state information to tie to the front channel interaction 1865 response, it MUST use a unique callback URI to link to that 1866 ongoing state. The allowable URIs and URI patterns MAY be 1867 restricted by the AS based on the client instance's presented key 1868 information. The callback URI SHOULD be presented to the RO 1869 during the interaction phase before redirect. REQUIRED for 1870 redirect and push methods. 1872 nonce (string): Unique value to be used in the calculation of the 1873 "hash" query parameter sent to the callback URI, must be 1874 sufficiently random to be unguessable by an attacker. MUST be 1875 generated by the client instance as a unique value for this 1876 request. REQUIRED. 1878 hash_method (string): The hash calculation mechanism to be used for 1879 the callback hash in Section 4.2.3. Can be one of sha3 or sha2. 1880 If absent, the default value is sha3. OPTIONAL. [[ See issue #56 1881 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/56) ]] 1883 This specification defines the following values for the method 1884 parameter, with other values defined by a registry TBD (Section 11): 1886 "redirect": Indicates that the client instance can receive a 1887 redirect from the end user's device after interaction with the RO 1888 has concluded. Section 2.5.2.1 1890 "push": Indicates that the client instance can receive an HTTP POST 1891 request from the AS after interaction with the RO has concluded. 1892 Section 2.5.2.2 1894 If this interaction mode is supported for this client instance and 1895 request, the AS returns a nonce for use in validating the callback 1896 response (Section 3.3.5). Requests to the callback URI MUST be 1897 processed as described in Section 4.2, and the AS MUST require 1898 presentation of an interaction callback reference as described in 1899 Section 5.1. 1901 [[ See issue #58 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 1902 issues/58) ]] 1904 2.5.2.1. Receive an HTTP Callback Through the Browser 1906 A finish method value of redirect indicates that the client instance 1907 will expect a request from the RO's browser using the HTTP method GET 1908 as described in Section 4.2.1. 1910 "interact": { 1911 "finish": { 1912 "method": "redirect", 1913 "uri": "https://client.example.net/return/123455", 1914 "nonce": "LKLTI25DK82FX4T4QFZC" 1915 } 1916 } 1918 Requests to the callback URI MUST be processed by the client instance 1919 as described in Section 4.2.1. 1921 Since the incoming request to the callback URI is from the RO's 1922 browser, this method is usually used when the RO and end user are the 1923 same entity. See Section 12.22 for considerations on ensuring the 1924 incoming HTTP message matches the expected context of the request. 1925 See Section 12.26 for more considerations regarding the use of front- 1926 channel communication techniques such as this. 1928 2.5.2.2. Receive an HTTP Direct Callback 1930 A finish method value of push indicates that the client instance will 1931 expect a request from the AS directly using the HTTP method POST as 1932 described in Section 4.2.2. 1934 "interact": { 1935 "finish": { 1936 "method": "push", 1937 "uri": "https://client.example.net/return/123455", 1938 "nonce": "LKLTI25DK82FX4T4QFZC" 1939 } 1940 } 1942 Requests to the callback URI MUST be processed by the client instance 1943 as described in Section 4.2.2. 1945 Since the incoming request to the callback URI is from the AS and not 1946 from the RO's browser, this request is not expected to have any 1947 shared session information from the start method. See Section 12.22 1948 and Section 12.21 for more considerations regarding the use of back- 1949 channel and polling mechanisms like this. 1951 2.5.3. Hints 1953 The hints key is an object describing one or more suggestions from 1954 the client instance that the AS can use to help drive user 1955 interaction. 1957 This specification defines the following properties under the hints 1958 key: 1960 ui_locales (array of strings): Indicates the end user's preferred 1961 locales that the AS can use during interaction, particularly 1962 before the RO has authenticated. OPTIONAL. Section 2.5.3.1 1964 The following sections detail requests for interaction hints. 1965 Additional interaction hints are defined in a registry TBD 1966 (Section 11). 1968 2.5.3.1. Indicate Desired Interaction Locales 1970 If the client instance knows the end user's locale and language 1971 preferences, the client instance can send this information to the AS 1972 using the ui_locales field with an array of locale strings as defined 1973 by [RFC5646]. 1975 "interact": { 1976 "hints": { 1977 "ui_locales": ["en-US", "fr-CA"] 1978 } 1979 } 1981 If possible, the AS SHOULD use one of the locales in the array, with 1982 preference to the first item in the array supported by the AS. If 1983 none of the given locales are supported, the AS MAY use a default 1984 locale. 1986 2.5.4. Extending Interaction Modes 1988 Additional interaction start modes, finish modes, and hints are 1989 defined in a registry TBD (Section 11). 1991 2.6. Extending The Grant Request 1993 The request object MAY be extended by registering new items in a 1994 registry TBD (Section 11). Extensions SHOULD be orthogonal to other 1995 parameters. Extensions MUST document any aspects where the extension 1996 item affects or influences the values or behavior of other request 1997 and response objects. 1999 3. Grant Response 2001 In response to a client instance's request, the AS responds with a 2002 JSON object as the HTTP entity body. Each possible field is detailed 2003 in the sections below. 2005 continue (object): Indicates that the client instance can continue 2006 the request by making one or more continuation requests. REQUIRED 2007 if continuation calls are allowed for this client instance on this 2008 grant request. See Section 3.1. 2010 access_token (object / array of objects): A single access token or 2011 set of access tokens that the client instance can use to call the 2012 RS on behalf of the RO. REQUIRED if an access token is included. 2013 See Section 3.2. 2015 interact (object): Indicates that interaction through some set of 2016 defined mechanisms needs to take place. REQUIRED if interaction 2017 is needed or allowed. See Section 3.3. 2019 subject (object): Claims about the RO as known and declared by the 2020 AS. REQUIRED if subject information is included. See 2021 Section 3.4. 2023 instance_id (string): An identifier this client instance can use to 2024 identify itself when making future requests. OPTIONAL. See 2025 Section 3.5. 2027 error (object): An error code indicating that something has gone 2028 wrong. REQUIRED for an error condition. If included, other 2029 fields MUST NOT be included. See Section 3.6. 2031 In this example, the AS is returning an interaction URI 2032 (Section 3.3.1), a callback nonce (Section 3.3.5), and a continuation 2033 response (Section 3.1). 2035 NOTE: '\' line wrapping per RFC 8792 2037 { 2038 "interact": { 2039 "redirect": "https://server.example.com/interact/4CF492ML\ 2040 VMSW9MKMXKHQ", 2041 "finish": "MBDOFXG4Y5CVJCX821LH" 2042 }, 2043 "continue": { 2044 "access_token": { 2045 "value": "80UPRY5NM33OMUKMKSKU", 2046 }, 2047 "uri": "https://server.example.com/tx" 2048 } 2049 } 2051 In this example, the AS is returning a bearer access token 2052 (Section 3.2.1) with a management URI and a subject identifier 2053 (Section 3.4) in the form of an opaque identifier. 2055 NOTE: '\' line wrapping per RFC 8792 and a [subject identifier](#response-subject) in the form of 2056 an opaque identifier. 2058 { 2059 "access_token": { 2060 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2061 "flags": ["bearer"], 2062 "manage": "https://server.example.com/token/PRY5NM33O\ 2063 M4TB8N6BW7OZB8CDFONP219RP1L", 2064 }, 2065 "subject": { 2066 "sub_ids": [ { 2067 "format": "opaque", 2068 "id": "J2G8G8O4AZ" 2069 } ] 2070 } 2071 } 2073 In this example, the AS is returning set of subject identifiers 2074 (Section 3.4), simultaneously as an opaque identifier, an email 2075 address, and a decentralized identifier URL (DID). 2077 { 2078 "subject": { 2079 "sub_ids": [ { 2080 "format": "opaque", 2081 "id": "J2G8G8O4AZ" 2082 }, { 2083 "format": "email", 2084 "email": "user@example.com" 2085 }, { 2086 "format": "did", 2087 "url": "did:example:123456" 2088 } ] 2089 } 2090 } 2092 3.1. Request Continuation 2094 If the AS determines that the request can be continued with 2095 additional requests, it responds with the continue field. This field 2096 contains a JSON object with the following properties. 2098 uri (string): The URI at which the client instance can make 2099 continuation requests. This URI MAY vary per request, or MAY be 2100 stable at the AS. The client instance MUST use this value exactly 2101 as given when making a continuation request (Section 5). 2102 REQUIRED. 2104 wait (integer): The amount of time in integer seconds the client 2105 instance MUST wait after receiving this request continuation 2106 response and calling the continuation URI. The value SHOULD NOT 2107 be less than five seconds, and omission of the value MUST NOT be 2108 interpreted as zero (i.e., no delay between requests). 2109 RECOMMENDED. 2111 access_token (object): A unique access token for continuing the 2112 request, called the "continuation access token". The value of 2113 this property MUST be in the format specified in Section 3.2.1. 2114 This access token MUST be bound to the client instance's key used 2115 in the request and MUST NOT be a bearer token. As a consequence, 2116 the flags array of this access token MUST NOT contain the string 2117 bearer and the key field MUST be omitted. The client instance 2118 MUST present the continuation access token in all requests to the 2119 continuation URI as described in Section 7.2. REQUIRED. 2121 { 2122 "continue": { 2123 "access_token": { 2124 "value": "80UPRY5NM33OMUKMKSKU" 2125 }, 2126 "uri": "https://server.example.com/continue", 2127 "wait": 60 2128 } 2129 } 2131 The client instance can use the values of this field to continue the 2132 request as described in Section 5. Note that the client instance 2133 MUST sign all continuation requests with its key as described in 2134 Section 7.3 and MUST present the access token in its continuation 2135 request. 2137 This field SHOULD be returned when interaction is expected, to allow 2138 the client instance to follow up after interaction has been 2139 concluded. 2141 3.2. Access Tokens 2143 If the AS has successfully granted one or more access tokens to the 2144 client instance, the AS responds with the access_token field. This 2145 field contains either a single access token as described in 2146 Section 3.2.1 or an array of access tokens as described in 2147 Section 3.2.2. 2149 The client instance uses any access tokens in this response to call 2150 the RS as described in Section 7.2. 2152 3.2.1. Single Access Token 2154 If the client instance has requested a single access token and the AS 2155 has granted that access token, the AS responds with the 2156 "access_token" field. The value of this field is an object with the 2157 following properties. 2159 value (string): The value of the access token as a string. The 2160 value is opaque to the client instance. The value SHOULD be 2161 limited to ASCII characters to facilitate transmission over HTTP 2162 headers within other protocols without requiring additional 2163 encoding. REQUIRED. 2165 label (string): The value of the label the client instance provided 2166 in the associated token request (Section 2.1), if present. If the 2167 token has been split by the AS, the value of the label field is 2168 chosen by the AS and the split flag is used. REQUIRED for 2169 multiple access tokens, OPTIONAL for single access token. 2171 manage (string): The management URI for this access token. If 2172 provided, the client instance MAY manage its access token as 2173 described in Section 6. This management URI is a function of the 2174 AS and is separate from the RS the client instance is requesting 2175 access to. This URI MUST NOT include the access token value and 2176 SHOULD be different for each access token issued in a request. 2177 OPTIONAL. 2179 access (array of objects/strings): A description of the rights 2180 associated with this access token, as defined in Section 8. If 2181 included, this MUST reflect the rights associated with the issued 2182 access token. These rights MAY vary from what was requested by 2183 the client instance. REQUIRED. 2185 expires_in (integer): The number of seconds in which the access will 2186 expire. The client instance MUST NOT use the access token past 2187 this time. An RS MUST NOT accept an access token past this time. 2188 Note that the access token MAY be revoked by the AS or RS at any 2189 point prior to its expiration. OPTIONAL. 2191 key (object / string): The key that the token is bound to, if 2192 different from the client instance's presented key. The key MUST 2193 be an object or string in a format described in Section 7.1. The 2194 client instance MUST be able to dereference or process the key 2195 information in order to be able to sign the request. OPTIONAL. 2197 flags (array of strings): A set of flags that represent attributes 2198 or behaviors of the access token issued by the AS. OPTIONAL. 2200 The values of the flags field defined by this specification are as 2201 follows: 2203 "bearer": This flag indicates whether the token is a bearer token, 2204 not bound to a key and proofing mechanism. If the bearer flag is 2205 present, the access token is a bearer token, and the key field in 2206 this response MUST be omitted. If the bearer flag is omitted and 2207 the key field in this response is omitted, the token is bound the 2208 key used by the client instance (Section 2.3) in its request for 2209 access. If the bearer flag is omitted, and the key field is 2210 present, the token is bound to the key and proofing mechanism 2211 indicated in the key field. See Section 12.7 for additional 2212 considerations on the use of bearer tokens. 2214 "durable": Flag indicating a hint of AS behavior on token rotation. 2215 If this flag is present, then the client instance can expect a 2216 previously-issued access token to continue to work after it has 2217 been rotated (Section 6.1) or the underlying grant request has 2218 been modified (Section 5.3), resulting in the issuance of new 2219 access tokens. If this flag is omitted, the client instance can 2220 anticipate a given access token could stop working after token 2221 rotation or grant request modification. Note that a token flagged 2222 as durable can still expire or be revoked through any normal 2223 means. 2225 "split": Flag indicating that this token was generated by issuing 2226 multiple access tokens in response to one of the client instance's 2227 token request (Section 2.1) objects. This behavior MUST NOT be 2228 used unless the client instance has specifically requested it by 2229 use of the split flag. 2231 Flag values MUST NOT be included more than once. 2233 Additional flags can be defined by extensions using a registry TBD 2234 (Section 11). 2236 The following non-normative example shows a single access token bound 2237 to the client instance's key used in the initial request, with a 2238 management URI, and that has access to three described resources (one 2239 using an object and two described by reference strings). 2241 NOTE: '\' line wrapping per RFC 8792 2243 "access_token": { 2244 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2245 "manage": "https://server.example.com/token/PRY5NM33O\ 2246 M4TB8N6BW7OZB8CDFONP219RP1L", 2247 "access": [ 2248 { 2249 "type": "photo-api", 2250 "actions": [ 2251 "read", 2252 "write", 2253 "dolphin" 2254 ], 2255 "locations": [ 2256 "https://server.example.net/", 2257 "https://resource.local/other" 2258 ], 2259 "datatypes": [ 2260 "metadata", 2261 "images" 2262 ] 2263 }, 2264 "read", "dolphin-metadata" 2265 ] 2266 } 2268 The following non-normative example shows a single bearer access 2269 token with access to two described resources. 2271 "access_token": { 2272 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2273 "flags": ["bearer"], 2274 "access": [ 2275 "finance", "medical" 2276 ] 2277 } 2279 If the client instance requested a single access token 2280 (Section 2.1.1), the AS MUST NOT respond with the multiple access 2281 token structure unless the client instance sends the split flag as 2282 described in Section 2.1.1. 2284 If the AS has split the access token response, the response MUST 2285 include the split flag. 2287 [[ See issue #69 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2288 issues/69) ]] 2290 3.2.2. Multiple Access Tokens 2292 If the client instance has requested multiple access tokens and the 2293 AS has granted at least one of them, the AS responds with the 2294 "access_token" field. The value of this field is a JSON array, the 2295 members of which are distinct access tokens as described in 2296 Section 3.2.1. Each object MUST have a unique label field, 2297 corresponding to the token labels chosen by the client instance in 2298 the multiple access token request (Section 2.1.2). 2300 In this non-normative example, two tokens are issued under the names 2301 token1 and token2, and only the first token has a management URI 2302 associated with it. 2304 NOTE: '\' line wrapping per RFC 8792 2306 "access_token": [ 2307 { 2308 "label": "token1", 2309 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 2310 "manage": "https://server.example.com/token/PRY5NM33O\ 2311 M4TB8N6BW7OZB8CDFONP219RP1L", 2312 "access": [ "finance" ] 2313 }, 2314 { 2315 "label": "token2", 2316 "value": "UFGLO2FDAFG7VGZZPJ3IZEMN21EVU71FHCARP4J1", 2317 "access": [ "medical" ] 2318 } 2319 } 2321 Each access token corresponds to one of the objects in the 2322 access_token array of the client instance's request (Section 2.1.2). 2324 The multiple access token response MUST be used when multiple access 2325 tokens are requested, even if only one access token is issued as a 2326 result of the request. The AS MAY refuse to issue one or more of the 2327 requested access tokens, for any reason. In such cases the refused 2328 token is omitted from the response and all of the other issued access 2329 tokens are included in the response the requested names appropriate 2330 names. 2332 If the client instance requested multiple access tokens 2333 (Section 2.1.2), the AS MUST NOT respond with a single access token 2334 structure, even if only a single access token is granted. In such 2335 cases, the AS responds with a multiple access token structure 2336 containing one access token. 2338 If the AS has split the access token response, the response MUST 2339 include the split flag in the flags array. 2341 "access_token": [ 2342 { 2343 "label": "split-1", 2344 "value": "8N6BW7OZB8CDFONP219-OS9M2PMHKUR64TBRP1LT0", 2345 "flags": ["split"], 2346 "manage": "https://server.example.com/token/PRY5NM33O\ 2347 M4TB8N6BW7OZB8CDFONP219RP1L", 2348 "access": [ "fruits" ] 2349 }, 2350 { 2351 "label": "split-2", 2352 "value": "FG7VGZZPJ3IZEMN21EVU71FHCAR-UFGLO2FDAP4J1", 2353 "flags": ["split"], 2354 "access": [ "vegetables" ] 2355 } 2356 } 2358 Each access token MAY be bound to different keys with different 2359 proofing mechanisms. 2361 The manage URI MUST NOT contain the access token value. 2363 3.3. Interaction Modes 2365 If the client instance has indicated a capability to interact with 2366 the RO in its request (Section 2.5), and the AS has determined that 2367 interaction is both supported and necessary, the AS responds to the 2368 client instance with any of the following values in the interact 2369 field of the response. There is no preference order for interaction 2370 modes in the response, and it is up to the client instance to 2371 determine which ones to use. All supported interaction methods are 2372 included in the same interact object. 2374 redirect (string): Redirect to an arbitrary URI. REQUIRED if the 2375 redirect interaction start mode is possible for this request. See 2376 Section 3.3.1. 2378 app (string): Launch of an application URI. REQUIRED if the app 2379 interaction start mode is possible for this request. See 2380 Section 3.3.2. 2382 user_code (object): Display a short user code. REQUIRED if the 2383 user_code interaction start mode is possible for this request. 2384 See Section 3.3.3. 2386 user_code_uri (object): Display a short user code and URL. REQUIRED 2387 if the user_code_uri interaction start mode is possible for this 2388 request. Section 3.3.4 2390 finish (string): A nonce used by the client instance to verify the 2391 callback after interaction is completed. REQUIRED if the 2392 interaction finish method requested by the client instance is 2393 possible for this request. See Section 3.3.5. 2395 Additional interaction mode responses can be defined in a registry 2396 TBD (Section 11). 2398 The AS MUST NOT respond with any interaction mode that the client 2399 instance did not indicate in its request. The AS MUST NOT respond 2400 with any interaction mode that the AS does not support. Since 2401 interaction responses include secret or unique information, the AS 2402 SHOULD respond to each interaction mode only once in an ongoing 2403 request, particularly if the client instance modifies its request 2404 (Section 5.3). 2406 3.3.1. Redirection to an arbitrary URI 2408 If the client instance indicates that it can redirect to an arbitrary 2409 URI (Section 2.5.1.1) and the AS supports this mode for the client 2410 instance's request, the AS responds with the "redirect" field, which 2411 is a string containing the URI to direct the end user to. This URI 2412 MUST be unique for the request and MUST NOT contain any security- 2413 sensitive information such as user identifiers or access tokens. 2415 "interact": { 2416 "redirect": "https://interact.example.com/4CF492MLVMSW9MKMXKHQ" 2417 } 2419 The URI returned is a function of the AS, but the URI itself MAY be 2420 completely distinct from the URI the client instance uses to request 2421 access (Section 2), allowing an AS to separate its user-interactive 2422 functionality from its back-end security functionality. If the AS 2423 does not directly host the functionality accessed through the given 2424 URI, then the means for the interaction functionality to communicate 2425 with the rest of the AS are out of scope for this specification. 2427 [[ See issue #72 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2428 issues/72) ]] 2430 The client instance sends the end user to the URI to interact with 2431 the AS. The client instance MUST NOT alter the URI in any way. The 2432 means for the client instance to send the end user to this URI is out 2433 of scope of this specification, but common methods include an HTTP 2434 redirect, launching the system browser, displaying a scannable code, 2435 or printing out the URI in an interactive console. See details of 2436 the interaction in Section 4.1.1. 2438 3.3.2. Launch of an application URI 2440 If the client instance indicates that it can launch an application 2441 URI (Section 2.5.1.2) and the AS supports this mode for the client 2442 instance's request, the AS responds with the "app" field, which is a 2443 string containing the URI for the client instance to launch. This 2444 URI MUST be unique for the request and MUST NOT contain any security- 2445 sensitive information such as user identifiers or access tokens. 2447 "interact": { 2448 "app": "https://app.example.com/launch?tx=4CF492MLV" 2449 } 2451 The means for the launched application to communicate with the AS are 2452 out of scope for this specification. 2454 The client instance launches the URI as appropriate on its platform, 2455 and the means for the client instance to launch this URI is out of 2456 scope of this specification. The client instance MUST NOT alter the 2457 URI in any way. The client instance MAY attempt to detect if an 2458 installed application will service the URI being sent before 2459 attempting to launch the application URI. See details of the 2460 interaction in Section 4.1.4. 2462 [[ See issue #71 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2463 issues/71) ]] 2465 3.3.3. Display of a Short User Code 2467 If the client instance indicates that it can display a short 2468 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2469 for the client instance's request, the AS responds with a "user_code" 2470 field. This field is an object that contains the following members. 2472 code (string): A unique short code that the user can type into a web 2473 page. This string MUST be case-insensitive, MUST consist of only 2474 easily typeable characters (such as letters or numbers). The time 2475 in which this code will be accepted SHOULD be short lived, such as 2476 several minutes. It is RECOMMENDED that this code be no more than 2477 eight characters in length. REQUIRED. 2479 "interact": { 2480 "user_code": { 2481 "code": "A1BC-3DFF", 2482 } 2483 } 2485 The client instance MUST communicate the "code" to the end user in 2486 some fashion, such as displaying it on a screen or reading it out 2487 audibly. This code is used by the interaction component of the AS as 2488 a means of identifying the pending grant request and does not 2489 function as an authentication factor for the RO. 2491 The URI that the end user is intended to enter the code into MUST be 2492 stable, since the client instance is expected to have no means of 2493 communicating a dynamic URI to the end user at runtime. 2495 As this interaction mode is designed to facilitate interaction via a 2496 secondary device, it is not expected that the client instance 2497 redirect the end user to the URL given here at runtime. If the 2498 client instance is capable of communicating an short arbitrary URI to 2499 the end user for use with the user code, the client instance can 2500 instead use the "user_code_uri" (Section 2.5.1.4) method instead. If 2501 the client instance is capable of communicating a long arbitrary URI 2502 to the end user, such as through a scannable code, the client 2503 instance can use the "redirect" (Section 2.5.1.1) mode for this 2504 purpose instead of or in addition to the user code mode. 2506 See details of the interaction in Section 4.1.2. 2508 3.3.4. Display of a Short User Code and URI 2510 If the client instance indicates that it can display a short 2511 user-typeable code (Section 2.5.1.3) and the AS supports this mode 2512 for the client instance's request, the AS responds with a 2513 "user_code_uri" object that contains the following members. 2515 code (string): A unique short code that the end user can type into a 2516 provided URI. This string MUST be case-insensitive, MUST consist 2517 of only easily typeable characters (such as letters or numbers). 2518 The time in which this code will be accepted SHOULD be short 2519 lived, such as several minutes. It is RECOMMENDED that this code 2520 be no more than eight characters in length. REQUIRED. 2522 uri (string): The interaction URI that the client instance will 2523 direct the RO to. This URI MUST be short enough to be 2524 communicated to the end user. It is RECOMMENDED that this URI be 2525 short enough for an end user to type in manually. The URI MUST 2526 NOT contain the code value. REQUIRED. 2528 "interact": { 2529 "user_code_uri": { 2530 "code": "A1BC-3DFF", 2531 "uri": "https://srv.ex/device" 2532 } 2533 } 2535 The client instance MUST communicate the "code" to the end user in 2536 some fashion, such as displaying it on a screen or reading it out 2537 audibly. This code is used by the interaction component of the AS as 2538 a means of identifying the pending grant request and does not 2539 function as an authentication factor for the RO. 2541 The client instance MUST also communicate the URI to the end user. 2542 Since it is expected that the end user will continue interaction on a 2543 secondary device, the URI needs to be short enough to allow the end 2544 user to type or copy it to a secondary device without mistakes. 2546 The URI returned is a function of the AS, but the URI itself MAY be 2547 completely distinct from the URI the client instance uses to request 2548 access (Section 2), allowing an AS to separate its user-interactive 2549 functionality from its back-end security functionality. If the AS 2550 does not directly host the functionality accessed through the given 2551 URI, then the means for the interaction functionality to communicate 2552 with the rest of the AS are out of scope for this specification. 2554 See details of the interaction in Section 4.1.2. 2556 3.3.5. Interaction Finish 2558 If the client instance indicates that it can receive a 2559 post-interaction redirect or push at a URI (Section 2.5.2) and the AS 2560 supports this mode for the client instance's request, the AS responds 2561 with a finish field containing a nonce that the client instance will 2562 use in validating the callback as defined in Section 4.2. 2564 "interact": { 2565 "finish": "MBDOFXG4Y5CVJCX821LH" 2566 } 2568 When the interaction is completed, the interaction component MUST 2569 contact the client instance using either a redirect or launch of the 2570 RO's browser or through an HTTP POST to the client instance's 2571 callback URI using the method indicated in the interaction request 2572 (Section 2.5.2) as described in Section 4.2. 2574 If the AS returns a nonce, the client instance MUST NOT continue a 2575 grant request before it receives the associated interaction reference 2576 on the callback URI. See details in Section 4.2. 2578 3.3.6. Extending Interaction Mode Responses 2580 Extensions to this specification can define new interaction mode 2581 responses in a registry TBD (Section 11). Extensions MUST document 2582 the corresponding interaction request. 2584 3.4. Returning Subject Information 2586 If information about the RO is requested and the AS grants the client 2587 instance access to that data, the AS returns the approved information 2588 in the "subject" response field. The AS MUST return the subject 2589 field only in cases where the AS is sure that the RO and the end user 2590 are the same party. This can be accomplished through some forms of 2591 interaction with the RO (Section 4). 2593 This field is an object with the following OPTIONAL properties. 2595 sub_ids (array of objects): An array of subject identifiers for the 2596 RO, as defined by [I-D.ietf-secevent-subject-identifiers]. 2597 REQUIRED if returning subject identifiers. 2599 assertions (array of objects): An array containing assertions as 2600 objects each containing the assertion format and the assertion 2601 value as the JSON string serialization of the assertion. Possible 2602 formats include id_token for an [OIDC] ID Token and saml2 for a 2603 SAML 2 assertion. Additional assertion formats are defined by a 2604 registry TBD (Section 11). REQUIRED if returning assertions. 2606 updated_at (string): Timestamp as an ISO8610 date string, indicating 2607 when the identified account was last updated. The client instance 2608 MAY use this value to determine if it needs to request updated 2609 profile information through an identity API. The definition of 2610 such an identity API is out of scope for this specification. 2611 RECOMMENDED. 2613 "subject": { 2614 "sub_ids": [ { 2615 "format": "opaque", 2616 "id": "XUT2MFM1XBIKJKSDU8QM" 2617 } ], 2618 "assertions": [ { 2619 "format": "id_token", 2620 "value": "eyj..." 2621 } ] 2622 } 2624 Subject identifiers returned by the AS SHOULD uniquely identify the 2625 RO at the AS. Some forms of subject identifier are opaque to the 2626 client instance (such as the subject of an issuer and subject pair), 2627 while others forms (such as email address and phone number) are 2628 intended to allow the client instance to correlate the identifier 2629 with other account information at the client instance. The AS MUST 2630 ensure that the returned subject identifiers only apply to the 2631 authenticated end user. The client instance MUST NOT request or use 2632 any returned subject identifiers for communication purposes (see 2633 Section 2.2). That is, a subject identifier returned in the format 2634 of an email address or a phone number only identifies the RO to the 2635 AS and does not indicate that the AS has validated that the 2636 represented email address or phone number in the identifier is 2637 suitable for communication with the current user. To get such 2638 information, the client instance MUST use an identity protocol to 2639 request and receive additional identity claims. The details of an 2640 identity protocol and associated schema are outside the scope of this 2641 specification. 2643 Extensions to this specification MAY define additional response 2644 properties in a registry TBD (Section 11). 2646 See Section 12.27 for considerations that the client instance has to 2647 make when accepting and processing assertions from the AS. 2649 3.5. Returning a Dynamically-bound Client Instance Identifier 2651 Many parts of the client instance's request can be passed as either a 2652 value or a reference. The use of a reference in place of a value 2653 allows for a client instance to optimize requests to the AS. 2655 Some references, such as for the client instance's identity 2656 (Section 2.3.1) or the requested resources (Section 8.1), can be 2657 managed statically through an admin console or developer portal 2658 provided by the AS or RS. The developer of the client software can 2659 include these values in their code for a more efficient and compact 2660 request. 2662 If desired, the AS MAY also generate and return an instance 2663 identifier dynamically to the client instance in the response to 2664 facilitate multiple interactions with the same client instance over 2665 time. The client instance SHOULD use this instance identifier in 2666 future requests in lieu of sending the associated data values in the 2667 client field. 2669 Dynamically generated client instance identifiers are string values 2670 that MUST be protected by the client instance as secrets. Instance 2671 identifier values MUST be unguessable and MUST NOT contain any 2672 information that would compromise any party if revealed. Instance 2673 identifier values are opaque to the client instance. 2675 instance_id (string): A string value used to represent the 2676 information in the client object that the client instance can use 2677 in a future request, as described in Section 2.3.1. OPTIONAL. 2679 This non-normative example shows an instance identifier along side an 2680 issued access token. 2682 { 2683 "instance_id": "7C7C4AZ9KHRS6X63AJAO", 2684 "access_token": { 2685 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0" 2686 } 2687 } 2689 [[ See issue #77 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2690 issues/77) ]] 2692 [[ See issue #78 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 2693 issues/78) ]] 2695 3.6. Error Response 2697 If the AS determines that the request cannot be issued for any 2698 reason, it responds to the client instance with an error message. 2700 error (string): A single ASCII error code from the following, with 2701 additional values available in a registry TBD (Section 11). 2702 REQUIRED. 2704 "invalid_request": The request is missing a required parameter, 2705 includes an invalid parameter value or is otherwise malformed. 2707 "invalid_client": The request was made from a client that was not 2708 recognized or allowed by the AS, or the client's signature 2709 validation failed. 2711 "user_denied": The RO denied the request. 2713 "too_fast": The client instance did not respect the timeout in 2714 the wait response. 2716 "unknown_request": The request referenced an unknown ongoing 2717 access request. 2719 "request_denied": The request was denied for an unspecified 2720 reason. 2722 error_description (string): A human-readable string description of 2723 the error intended for the developer of the client. OPTIONAL. 2725 For example, if the RO denied the request while interacting with the 2726 AS, the AS would return the following error when the client instance 2727 tries to continue the grant request: 2729 { 2730 "error": "user_denied" 2731 } 2733 3.7. Extending the Response 2735 Extensions to this specification MAY define additional fields for the 2736 grant response in a registry TBD (Section 11). 2738 4. Determining Authorization and Consent 2740 When the client instance makes its initial request (Section 2) to the 2741 AS for delegated access, it is capable of asking for several 2742 different kinds of information in response: 2744 * the access being requested in the access_token request parameter 2746 * the subject information being requested in the subject request 2747 parameter 2749 * any additional requested information defined by extensions of this 2750 protocol 2752 The AS determines what authorizations and consents are required to 2753 fulfill this requested delegation. The details of how the AS makes 2754 this determination are out of scope for this document. However, 2755 there are several common patterns defined and supported by GNAP for 2756 fulfilling these requirements, including information sent by the 2757 client instance, information gathered through the interaction 2758 process, and information supplied by external parties. An individual 2759 AS can define its own policies and processes for deciding when and 2760 how to gather the necessary authorizations and consent. 2762 The client instance can supply information directly to the AS in its 2763 request. From this information, the AS can determine if the 2764 requested delegation can be granted immediately. The client instance 2765 can send several kinds of things, including: 2767 * the identity of the client instance, known from the presented keys 2768 or associated identifiers 2770 * the identity of the end user presented in the user request 2771 parameter 2773 * any additional information presented by the client instance in the 2774 request, including any extensions 2776 The AS will verify this presented information in the context of the 2777 client instance's request and can only trust the information as much 2778 as it trusts the presentation and context of the information. If the 2779 AS determines that the information presented in the initial request 2780 is sufficient for granting the requested access, the AS MAY return 2781 the positive results immediately in its response (Section 3) with 2782 access tokens and subject information. 2784 If the AS determines that additional runtime authorization is 2785 required, the AS can either deny the request outright or use a number 2786 of means at its disposal to gather that authorization from the 2787 appropriate ROs, including for example: 2789 * starting interaction with the end user facilitated by the client 2790 software, such as a redirection or user code 2792 * challenging the client instance through a challenge-response 2793 mechanism 2795 * requesting that the client instance present specific additional 2796 information, such as a user's credential or an assertion 2798 * contacting an RO through an out-of-band mechanism, such as a push 2799 notification 2801 * contacting an auxiliary software process through an out-of-band 2802 mechanism, such as querying a digital wallet 2804 The authorization and consent gathering process in GNAP is left 2805 deliberately flexible to allow for a wide variety of different 2806 deployments, interactions, and methodologies. In this process, the 2807 AS can gather consent from the RO as necessitated by the access that 2808 has been requested. The AS can sometimes determine which RO needs to 2809 consent based on what has been requested by the client instance, such 2810 as a specific RS record, an identified user, or a request requiring 2811 specific access such as approval by an administrator. If the AS has 2812 a means of contacting the RO directly, it could do so without 2813 involving the client instance in its consent gathering process. For 2814 example, the AS could push a notification to a known RO and have the 2815 RO approve the pending request asynchronously. These interactions 2816 can be through an interface of the AS itself (such as a hosted web 2817 page), through another application (such as something installed on 2818 the RO's device), through a messaging fabric, or any other means. 2819 When interacting with an RO, the AS can do anything it needs to 2820 determine the authorization of the requested grant, including: 2822 * authenticate the RO, through a local account or some other means 2823 such as federated login 2825 * validate the RO through presentation of claims, attributes, or 2826 other information 2828 * prompt the RO for consent for the requested delegation 2830 * describe to the RO what information is being released, to whom, 2831 and for what purpose 2833 * provide warnings to the RO about potential attacks or negative 2834 effects of allowing the information 2836 * allow the RO to modify the client instance's requested access, 2837 including limiting or expanding that access 2839 * provide the RO with artifacts such as receipts to facilitate an 2840 audit trail of authorizations 2842 * allow the RO to deny the requested delegation 2844 The AS is also allowed to request authorization from more than one 2845 RO, if the AS deems fit. For example, a medical record might need to 2846 be released by both an attending nurse and a physician, or both 2847 owners of a bank account need to sign off on a transfer request. 2848 Alternatively, the AS could require N of M possible RO's to approve a 2849 given request in order. The AS could also determine that the end 2850 user is not the appropriate RO for a given request and reach out to 2851 the appropriate RO asynchronously. The details of determining which 2852 RO's are required for a given request are out of scope for this 2853 specification. 2855 The client instance can also indicate that it is capable of 2856 facilitating interaction with the end user, another party, or another 2857 piece of software through its interaction start (Section 2.5.1) 2858 request. In many cases, the end user is delegating their own access 2859 as RO to the client instance. Here, the AS needs to determine the 2860 identity of the end user and will often need to interact directly 2861 with the end user to determine their status as an RO and collect 2862 their consent. If the AS has determined that authorization is 2863 required and the AS can support one or more of the requested 2864 interaction start methods, the AS returns the associated interaction 2865 start responses (Section 3.3). The client instance SHOULD initiate 2866 one or more of these interaction methods (Section 4.1) in order to 2867 facilitate the granting of the request. If more than one interaction 2868 start method is available, the means by which the client chooses 2869 which methods to follow is out of scope of this specification. The 2870 client instance MUST use each interaction method once at most. 2872 After starting interaction, the client instance can then make a 2873 continuation request (Section 5) either in response to a signal 2874 indicating the finish of the interaction (Section 4.2), through 2875 polling, or through some other method defined by an extension of this 2876 specification. 2878 If the AS and client instance have not reached a state where the 2879 delegation can be granted, the AS and client instance can repeat the 2880 interaction process as long as the AS supplies the client instance 2881 with continuation information (Section 3.1) to facilitate the ongoing 2882 requests. 2884 4.1. Interaction Start Methods 2886 To initiate an interaction start method indicated by the interaction 2887 start responses (Section 3.3) from the AS, the client instance 2888 follows the steps defined by that interaction method. The actions of 2889 the client instance required for the interaction start modes defined 2890 in this specification are described in the following sections. 2892 4.1.1. Interaction at a Redirected URI 2894 When the end user is directed to an arbitrary URI through the 2895 "redirect" (Section 3.3.1) mode, the client instance facilitates 2896 opening the URI through the end user's web browser. The client 2897 instance could launch the URI through the system browser, provide a 2898 clickable link, redirect the user through HTTP response codes, or 2899 display the URI in a form the end user can use to launch such as a 2900 multidimensional barcode. With this method, it is common (though not 2901 required) for the RO to be the same party as the end user, since the 2902 client instance has to communicate the redirection URI to the end 2903 user. 2905 In many cases, the URI indicates a web page hosted at the AS, 2906 allowing the AS to authenticate the end user as the RO and 2907 interactively provide consent. The URI value is used to identify the 2908 grant request being authorized. If the URI cannot be associated with 2909 a currently active request, the AS MUST display an error to the RO 2910 and MUST NOT attempt to redirect the RO back to any client instance 2911 even if a redirect finish method is supplied (Section 2.5.2.1). If 2912 the URI is not hosted by the AS directly, the means of communication 2913 between the AS and this URI are out of scope for this specification. 2915 The client instance MUST NOT modify the URI when launching it, in 2916 particular the client instance MUST NOT add any parameters to the 2917 URI. The URI MUST be reachable from the end user's browser, though 2918 the URI MAY be opened on a separate device from the client instance 2919 itself. The URI MUST be accessible from an HTTP GET request and MUST 2920 be protected by HTTPS or equivalent means. 2922 4.1.2. Interaction at the Static User Code URI 2924 When the end user is directed to enter a short code through the 2925 "user_code" (Section 3.3.3) mode, the client instance communicates 2926 the user code to the end user and directs the end user to enter that 2927 code at an associated URI. This mode is used when the client 2928 instance is not able to communicate or facilitate launching an 2929 arbitrary URI. The associated URI could be statically configured 2930 with the client instance or in the client software's documentation. 2931 As a consequence, these URIs SHOULD be short. The user code URI MUST 2932 be reachable from the end user's browser, though the URI is usually 2933 be opened on a separate device from the client instance itself. 2934 Since it is designed to be typed in, the URI SHOULD be accessible 2935 from an HTTP GET request and MUST be protected by HTTPS or equivalent 2936 means. 2938 In many cases, the URI indicates a web page hosted at the AS, 2939 allowing the AS to authenticate the end user as the RO and 2940 interactively provide consent. The value of the user code is used to 2941 identify the grant request being authorized. If the user code cannot 2942 be associated with a currently active request, the AS MUST display an 2943 error to the RO and MUST NOT attempt to redirect the RO back to any 2944 client instance even if a redirect finish method is supplied 2945 (Section 2.5.2.1). If the interaction component at the user code URI 2946 is not hosted by the AS directly, the means of communication between 2947 the AS and this URI, including communication of the user code itself, 2948 are out of scope for this specification. 2950 When the RO enters this code at the user code URI, the AS MUST 2951 uniquely identify the pending request that the code was associated 2952 with. If the AS does not recognize the entered code, the interaction 2953 component MUST display an error to the user. If the AS detects too 2954 many unrecognized code enter attempts, the interaction component 2955 SHOULD display an error to the user and MAY take additional actions 2956 such as slowing down the input interactions. The user should be 2957 warned as such an error state is approached, if possible. 2959 4.1.3. Interaction at a Dynamic User Code URI 2961 When the end user is directed to enter a short code through the 2962 "user_code_uri" (Section 3.3.4) mode, the client instance 2963 communicates the user code and associated URI to the end user and 2964 directs the end user to enter that code at the URI. This mode is 2965 used when the client instance is not able to facilitate launching an 2966 arbitrary URI but can communicate arbitrary values like URIs. As a 2967 consequence, these URIs SHOULD be short. The client instance MUST 2968 NOT modify the URI when communicating it to the end user; in 2969 particular the client instance MUST NOT add any parameters to the 2970 URI. The user code URI MUST be reachable from the end user's 2971 browser, though the URI is usually be opened on a separate device 2972 from the client instance itself. Since it is designed to be typed 2973 in, the URI SHOULD be accessible from an HTTP GET request and MUST be 2974 protected by HTTPS or equivalent means. 2976 In many cases, the URI indicates a web page hosted at the AS, 2977 allowing the AS to authenticate the end user as the RO and 2978 interactively provide consent. The value of the user code is used to 2979 identify the grant request being authorized. If the user code cannot 2980 be associated with a currently active request, the AS MUST display an 2981 error to the RO and MUST NOT attempt to redirect the RO back to any 2982 client instance even if a redirect finish method is supplied 2983 (Section 2.5.2.1). If the interaction component at the user code URI 2984 is not hosted by the AS directly, the means of communication between 2985 the AS and this URI, including communication of the user code itself, 2986 are out of scope for this specification. 2988 When the RO enters this code at the given URI, the AS MUST uniquely 2989 identify the pending request that the code was associated with. If 2990 the AS does not recognize the entered code, the interaction component 2991 MUST display an error to the user. If the AS detects too many 2992 unrecognized code enter attempts, the interaction component SHOULD 2993 display an error to the user and MAY take additional actions such as 2994 slowing down the input interactions. The user should be warned as 2995 such an error state is approached, if possible. 2997 4.1.4. Interaction through an Application URI 2999 When the client instance is directed to launch an application through 3000 the "app" (Section 3.3.2) mode, the client launches the URI as 3001 appropriate to the system, such as through a deep link or custom URI 3002 scheme registered to a mobile application. The means by which the AS 3003 and the launched application communicate with each other and perform 3004 any of the required actions are out of scope for this specification. 3006 4.2. Post-Interaction Completion 3008 If an interaction "finish" (Section 3.3.5) method is associated with 3009 the current request, the AS MUST follow the appropriate method at 3010 upon completion of interaction in order to signal the client instance 3011 to continue, except for some limited error cases discussed below. If 3012 a finish method is not available, the AS SHOULD instruct the RO to 3013 return to the client instance upon completion. 3015 The AS MUST create an interaction reference and associate that 3016 reference with the current interaction and the underlying pending 3017 request. This interaction reference value MUST be sufficiently 3018 random so as not to be guessable by an attacker. The interaction 3019 reference MUST be one-time-use to prevent interception and replay 3020 attacks. 3022 The AS MUST calculate a hash value based on the client instance and 3023 AS nonces and the interaction reference, as described in 3024 Section 4.2.3. The client instance will use this value to validate 3025 the "finish" call. 3027 The AS MUST send the hash and interaction reference based on the 3028 interaction finish mode as described in the following sections. 3030 Note that the "finish" method still occurs in many error cases, such 3031 as when the RO has denied access. This pattern allows the client 3032 instance to potentially recover from the error state by modifying its 3033 request or providing additional information directly to the AS in a 3034 continuation request. The AS MUST NOT follow the "finish" method in 3035 the following circumstances: 3037 * The AS has determined that any URIs involved with the finish 3038 method are dangerous or blocked. 3040 * The AS cannot determine which ongoing grant request is being 3041 referenced. 3043 * The ongoing grant request has been cancelled or otherwise blocked. 3045 4.2.1. Completing Interaction with a Browser Redirect to the Callback 3046 URI 3048 When using the redirect interaction finish method (Section 3.3.5), 3049 the AS signals to the client instance that interaction is complete 3050 and the request can be continued by directing the RO (in their 3051 browser) back to the client instance's redirect URI sent in the 3052 callback request (Section 2.5.2.1). 3054 The AS secures this redirect by adding the hash and interaction 3055 reference as query parameters to the client instance's redirect URI. 3057 hash: The interaction hash value as described in Section 4.2.3. 3058 REQUIRED. 3060 interact_ref: The interaction reference generated for this 3061 interaction. REQUIRED. 3063 The means of directing the RO to this URI are outside the scope of 3064 this specification, but common options include redirecting the RO 3065 from a web page and launching the system browser with the target URI. 3066 See Section 12.16 for considerations on which HTTP status code to use 3067 when redirecting a request that potentially contains credentials. 3069 NOTE: '\' line wrapping per RFC 8792 3071 https://client.example.net/return/123455\ 3072 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 3073 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 3074 &interact_ref=4IFWWIKYBC2PQ6U56NL1 3076 When receiving the request, the client instance MUST parse the query 3077 parameters to calculate and validate the hash value as described in 3078 Section 4.2.3. If the hash validates, the client instance sends a 3079 continuation request to the AS as described in Section 5.1 using the 3080 interaction reference value received here. 3082 4.2.2. Completing Interaction with a Direct HTTP Request Callback 3084 When using the push interaction finish method (Section 3.3.5), the AS 3085 signals to the client instance that interaction is complete and the 3086 request can be continued by sending an HTTP POST request to the 3087 client instance's callback URI sent in the callback request 3088 (Section 2.5.2.2). 3090 The entity message body is a JSON object consisting of the following 3091 two fields: 3093 hash (string): The interaction hash value as described in 3094 Section 4.2.3. REQUIRED. 3096 interact_ref (string) The interaction reference generated for this 3097 interaction. REQUIRED. 3099 NOTE: '\' line wrapping per RFC 8792 3101 POST /push/554321 HTTP/1.1 3102 Host: client.example.net 3103 Content-Type: application/json 3105 { 3106 "hash": "p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R\ 3107 2HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A", 3108 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3109 } 3111 When processing such a call, the AS MUST protect itself against SSRF 3112 attacks as discussed in Section 12.31. 3114 When receiving the request, the client instance MUST parse the JSON 3115 object and validate the hash value as described in Section 4.2.3. If 3116 the hash validates, the client instance sends a continuation request 3117 to the AS as described in Section 5.1 using the interaction reference 3118 value received here. 3120 4.2.3. Calculating the interaction hash 3122 The "hash" parameter in the request to the client instance's callback 3123 URI ties the front channel response to an ongoing request by using 3124 values known only to the parties involved. This security mechanism 3125 allows the client instance to protect itself against several kinds of 3126 session fixation and injection attacks. The AS MUST always provide 3127 this hash, and the client instance MUST validate the hash when 3128 received. 3130 To calculate the "hash" value, the party doing the calculation 3131 creates a hash string by concatenating the following values in the 3132 following order using a single newline (\n) character to separate 3133 them: 3135 * the "nonce" value sent by the client instance in the interaction 3136 "finish" section of the initial request (Section 2.5.2) 3138 * the AS's nonce value from the interaction finish response 3139 (Section 3.3.5) 3141 * the "interact_ref" returned from the AS as part of the interaction 3142 finish method (Section 4.2) 3144 * the grant endpoint URI the client instance used to make its 3145 initial request (Section 2) 3147 There is no padding or whitespace before or after any of the lines, 3148 and no trailing newline character. 3150 VJLO6A4CAYLBXHTR0KRO 3151 MBDOFXG4Y5CVJCX821LH 3152 4IFWWIKYBC2PQ6U56NL1 3153 https://server.example.com/tx 3155 The party then hashes this string with the appropriate algorithm 3156 based on the "hash_method" parameter under the "finish" key. If the 3157 "hash_method" value is not present in the client instance's request, 3158 the algorithm defaults to "sha3". 3160 [[ See issue #56 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3161 issues/56) ]] 3163 4.2.3.1. SHA3-512 3165 The "sha3" hash method consists of hashing the input string with the 3166 512-bit SHA3 algorithm. The byte array is then encoded using URL 3167 Safe Base64 with no padding [RFC4648]. The resulting string is the 3168 hash value. 3170 NOTE: '\' line wrapping per RFC 8792 3172 p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2HZT8BOWYHcLmObM\ 3173 7XHPAdJzTZMtKBsaraJ64A 3175 4.2.3.2. SHA2-512 3177 The "sha2" hash method consists of hashing the input string with the 3178 512-bit SHA2 algorithm. The byte array is then encoded using URL 3179 Safe Base64 with no padding [RFC4648]. The resulting string is the 3180 hash value. 3182 NOTE: '\' line wrapping per RFC 8792 3184 62SbcD3Xs7L40rjgALA-ymQujoh2LB2hPJyX9vlcr1H6ecChZ8BNKkG_HrOKP_Bp\ 3185 j84rh4mC9aE9x7HPBFcIHw 3187 5. Continuing a Grant Request 3189 While it is possible for the AS to return a grant response 3190 (Section 3) with all the client instance's requested information 3191 (including access tokens (Section 3.2) and direct user information 3192 (Section 3.4)), it's more common that the AS and the client instance 3193 will need to communicate several times over the lifetime of an access 3194 grant. This is often part of facilitating interaction (Section 4), 3195 but it could also be used to allow the AS and client instance to 3196 continue negotiating the parameters of the original grant request 3197 (Section 2). 3199 To enable this ongoing negotiation, the AS provides a continuation 3200 API to the client software. The AS returns a continue field in the 3201 response (Section 3.1) that contains information the client instance 3202 needs to access this API, including a URI to access as well as a 3203 continuation access token to use during the requests. 3205 The continuation access token is initially bound to the same key and 3206 method the client instance used to make the initial request. As a 3207 consequence, when the client instance makes any calls to the 3208 continuation URI, the client instance MUST present the continuation 3209 access token as described in Section 7.2 and present proof of the 3210 client instance's key (or its most recent rotation) by signing the 3211 request as described in Section 7.3. The AS MUST validate all keys 3212 presented by the client instance or referenced in an ongoing request 3213 for each call within that request. 3215 Access tokens other than the continuation access tokens MUST NOT be 3216 usable for continuation requests. 3218 [[ See issue #85 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3219 issues/85) ]] 3221 For example, here the client instance makes a POST request to a 3222 unique URI and signs the request with HTTP Message Signatures: 3224 POST /continue/KSKUOMUKM HTTP/1.1 3225 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3226 Host: server.example.com 3227 Signature-Input: sig1=... 3228 Signature: sig1=... 3230 The AS MUST be able to tell from the client instance's request which 3231 specific ongoing request is being accessed, using a combination of 3232 the continuation URI, the provided continuation access token, and the 3233 client instance identified by the key signature. If the AS cannot 3234 determine a single active grant request to map the continuation 3235 request to, the AS MUST return an error. 3237 The ability to continue an already-started request allows the client 3238 instance to perform several important functions, including presenting 3239 additional information from interaction, modifying the initial 3240 request, and getting the current state of the request. 3242 All requests to the continuation API are protected by this bound 3243 continuation access token. For example, here the client instance 3244 makes a POST request to a stable continuation endpoint URI with the 3245 interaction reference (Section 5.1), includes the access token, and 3246 signs with HTTP Message Signatures: 3248 POST /continue HTTP/1.1 3249 Host: server.example.com 3250 Content-Type: application/json 3251 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3252 Signature-Input: sig1=... 3253 Signature: sig1=... 3254 Content-Digest: sha-256=... 3256 { 3257 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3258 } 3259 If a wait parameter was included in the continuation response 3260 (Section 3.1), the client instance MUST NOT call the continuation URI 3261 prior to waiting the number of seconds indicated. If no wait period 3262 is indicated, the client instance MUST NOT poll immediately and 3263 SHOULD wait at least 5 seconds. If the client instance does not 3264 respect the given wait period, the AS MUST return the error too_fast 3265 defined in Section 3.6. 3267 The response from the AS is a JSON object and MAY contain any of the 3268 fields described in Section 3, as described in more detail in the 3269 sections below. 3271 If the AS determines that the client instance can make a further 3272 continuation request, the AS MUST include a new "continue" response 3273 (Section 3.1). The new continue response MUST include a continuation 3274 access token as well, and this token SHOULD be a new access token, 3275 invalidating the previous access token. If the AS does not return a 3276 new continue response, the client instance MUST NOT make an 3277 additional continuation request. If a client instance does so, the 3278 AS MUST return an error. [[ See issue #87 (https://github.com/ietf- 3279 wg-gnap/gnap-core-protocol/issues/87) ]] 3281 For continuation functions that require the client instance to send a 3282 message body, the body MUST be a JSON object. 3284 5.1. Continuing After a Completed Interaction 3286 When the AS responds to the client instance's finish method as in 3287 Section 4.2.1, this response includes an interaction reference. The 3288 client instance MUST include that value as the field interact_ref in 3289 a POST request to the continuation URI. 3291 POST /continue HTTP/1.1 3292 Host: server.example.com 3293 Content-Type: application/json 3294 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3295 Signature-Input: sig1=... 3296 Signature: sig1=... 3297 Content-Digest: sha-256=... 3299 { 3300 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 3301 } 3303 Since the interaction reference is a one-time-use value as described 3304 in Section 4.2.1, if the client instance needs to make additional 3305 continuation calls after this request, the client instance MUST NOT 3306 include the interaction reference. If the AS detects a client 3307 instance submitting the same interaction reference multiple times, 3308 the AS MUST return an error and SHOULD invalidate the ongoing 3309 request. 3311 The grant response (Section 3) MAY contain any newly-created access 3312 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3313 The response MAY contain a new "continue" response (Section 3.1) as 3314 described above. The response SHOULD NOT contain any interaction 3315 responses (Section 3.3). [[ See issue #89 (https://github.com/ietf- 3316 wg-gnap/gnap-core-protocol/issues/89) ]] 3318 For example, if the request is successful in causing the AS to issue 3319 access tokens and release opaque subject claims, the response could 3320 look like this: 3322 NOTE: '\' line wrapping per RFC 8792 3324 { 3325 "access_token": { 3326 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3327 "manage": "https://server.example.com/token/PRY5NM33O\ 3328 M4TB8N6BW7OZB8CDFONP219RP1L", 3329 }, 3330 "subject": { 3331 "sub_ids": [ { 3332 "format": "opaque", 3333 "id": "J2G8G8O4AZ" 3334 } ] 3335 } 3336 } 3338 With this example, the client instance can not make an additional 3339 continuation request because a continue field is not included. 3341 [[ See issue #88 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3342 issues/88) ]] 3344 5.2. Continuing During Pending Interaction 3346 When the client instance does not include a finish parameter, the 3347 client instance will often need to poll the AS until the RO has 3348 authorized the request. To do so, the client instance makes a POST 3349 request to the continuation URI as in Section 5.1, but does not 3350 include a message body. 3352 POST /continue HTTP/1.1 3353 Host: server.example.com 3354 Content-Type: application/json 3355 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3356 Signature-Input: sig1=... 3357 Signature: sig1=... 3359 The grant response (Section 3) MAY contain any newly-created access 3360 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3361 The response MAY contain a new "continue" response (Section 3.1) as 3362 described above. If a continue field is included, it SHOULD include 3363 a wait field to facilitate a reasonable polling rate by the client 3364 instance. The response SHOULD NOT contain interaction responses 3365 (Section 3.3). 3367 For example, if the request has not yet been authorized by the RO, 3368 the AS could respond by telling the client instance to make another 3369 continuation request in the future. In this example, a new, unique 3370 access token has been issued for the call, which the client instance 3371 will use in its next continuation request. 3373 { 3374 "continue": { 3375 "access_token": { 3376 "value": "33OMUKMKSKU80UPRY5NM" 3377 }, 3378 "uri": "https://server.example.com/continue", 3379 "wait": 30 3380 } 3381 } 3383 [[ See issue #90 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3384 issues/90) ]] 3386 [[ See issue #91 (https://github.com/ietf-wg-gnap/gnap-core-protocol/ 3387 issues/91) ]] 3389 If the request is successful in causing the AS to issue access tokens 3390 and release subject claims, the response could look like this 3391 example: 3393 NOTE: '\' line wrapping per RFC 8792 3395 { 3396 "access_token": { 3397 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 3398 "manage": "https://server.example.com/token/PRY5NM33O\ 3399 M4TB8N6BW7OZB8CDFONP219RP1L", 3400 }, 3401 "subject": { 3402 "sub_ids": [ { 3403 "format": "opaque", 3404 "id": "J2G8G8O4AZ" 3405 } ] 3406 } 3407 } 3409 See Section 12.21 for considerations on polling for continuation 3410 without an interaction finish method. 3412 5.3. Modifying an Existing Request 3414 The client instance might need to modify an ongoing request, whether 3415 or not tokens have already been issued or claims have already been 3416 released. In such cases, the client instance makes an HTTP PATCH 3417 request to the continuation URI and includes any fields it needs to 3418 modify. Fields that aren't included in the request are considered 3419 unchanged from the original request. 3421 The client instance MAY include the access_token and subject fields 3422 as described in Section 2.1 and Section 2.2. Inclusion of these 3423 fields override any values in the initial request, which MAY trigger 3424 additional requirements and policies by the AS. For example, if the 3425 client instance is asking for more access, the AS could require 3426 additional interaction with the RO to gather additional consent. If 3427 the client instance is asking for more limited access, the AS could 3428 determine that sufficient authorization has been granted to the 3429 client instance and return the more limited access rights 3430 immediately. [[ See issue #92 (https://github.com/ietf-wg-gnap/gnap- 3431 core-protocol/issues/92) ]] 3433 The client instance MAY include the interact field as described in 3434 Section 2.5. Inclusion of this field indicates that the client 3435 instance is capable of driving interaction with the RO, and this 3436 field replaces any values from a previous request. The AS MAY 3437 respond to any of the interaction responses as described in 3438 Section 3.3, just like it would to a new request. 3440 The client instance MAY include the user field as described in 3441 Section 2.4 to present new assertions or information about the end 3442 user. [[ See issue #93 (https://github.com/ietf-wg-gnap/gnap-core- 3443 protocol/issues/93) ]] 3445 The client instance MUST NOT include the client section of the 3446 request. [[ See issue #94 (https://github.com/ietf-wg-gnap/gnap-core- 3447 protocol/issues/94) ]] 3449 The client instance MAY include post-interaction responses such as 3450 described in Section 5.1. [[ See issue #95 (https://github.com/ietf- 3451 wg-gnap/gnap-core-protocol/issues/95) ]] 3453 Modification requests MUST NOT alter previously-issued access tokens. 3454 Instead, any access tokens issued from a continuation are considered 3455 new, separate access tokens. The AS MAY revoke existing access 3456 tokens after a modification has occurred. [[ See issue #96 3457 (https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/96) ]] 3459 If the modified request can be granted immediately by the AS, the 3460 grant response (Section 3) MAY contain any newly-created access 3461 tokens (Section 3.2) or newly-released subject claims (Section 3.4). 3462 The response MAY contain a new "continue" response (Section 3.1) as 3463 described above. If interaction can occur, the response SHOULD 3464 contain interaction responses (Section 3.3) as well. 3466 For example, a client instance initially requests a set of resources 3467 using references: 3469 POST /tx HTTP/1.1 3470 Host: server.example.com 3471 Content-Type: application/json 3472 Signature-Input: sig1=... 3473 Signature: sig1=... 3474 Content-Digest: sha-256=... 3476 { 3477 "access_token": { 3478 "access": [ 3479 "read", "write" 3480 ] 3481 }, 3482 "interact": { 3483 "start": ["redirect"], 3484 "finish": { 3485 "method": "redirect", 3486 "uri": "https://client.example.net/return/123455", 3487 "nonce": "LKLTI25DK82FX4T4QFZC" 3488 } 3489 }, 3490 "client": "987YHGRT56789IOLK" 3491 } 3493 Access is granted by the RO, and a token is issued by the AS. In its 3494 final response, the AS includes a continue field, which includes a 3495 separate access token for accessing the continuation API: 3497 { 3498 "continue": { 3499 "access_token": { 3500 "value": "80UPRY5NM33OMUKMKSKU" 3501 }, 3502 "uri": "https://server.example.com/continue", 3503 "wait": 30 3504 }, 3505 "access_token": { 3506 "value": "RP1LT0-OS9M2P_R64TB", 3507 "access": [ 3508 "read", "write" 3509 ] 3510 } 3511 } 3512 This continue field allows the client instance to make an eventual 3513 continuation call. In the future, the client instance realizes that 3514 it no longer needs "write" access and therefore modifies its ongoing 3515 request, here asking for just "read" access instead of both "read" 3516 and "write" as before. 3518 PATCH /continue HTTP/1.1 3519 Host: server.example.com 3520 Content-Type: application/json 3521 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3522 Signature-Input: sig1=... 3523 Signature: sig1=... 3524 Content-Digest: sha-256=... 3526 { 3527 "access_token": { 3528 "access": [ 3529 "read" 3530 ] 3531 } 3532 ... 3533 } 3535 The AS replaces the previous access from the first request, allowing 3536 the AS to determine if any previously-granted consent already 3537 applies. In this case, the AS would likely determine that reducing 3538 the breadth of the requested access means that new access tokens can 3539 be issued to the client instance. The AS would likely revoke 3540 previously-issued access tokens that had the greater access rights 3541 associated with them, unless they had been issued with the durable 3542 flag. 3544 { 3545 "continue": { 3546 "access_token": { 3547 "value": "M33OMUK80UPRY5NMKSKU" 3548 }, 3549 "uri": "https://server.example.com/continue", 3550 "wait": 30 3551 }, 3552 "access_token": { 3553 "value": "0EVKC7-2ZKwZM_6N760", 3554 "access": [ 3555 "read" 3556 ] 3557 } 3558 } 3559 For another example, the client instance initially requests read-only 3560 access but later needs to step up its access. The initial request 3561 could look like this example. 3563 POST /tx HTTP/1.1 3564 Host: server.example.com 3565 Content-Type: application/json 3566 Signature-Input: sig1=... 3567 Signature: sig1=... 3568 Content-Digest: sha-256=... 3570 { 3571 "access_token": { 3572 "access": [ 3573 "read" 3574 ] 3575 }, 3576 "interact": { 3577 "start": ["redirect"], 3578 "finish": { 3579 "method": "redirect", 3580 "uri": "https://client.example.net/return/123455", 3581 "nonce": "LKLTI25DK82FX4T4QFZC" 3582 } 3583 }, 3584 "client": "987YHGRT56789IOLK" 3585 } 3587 Access is granted by the RO, and a token is issued by the AS. In its 3588 final response, the AS includes a continue field: 3590 { 3591 "continue": { 3592 "access_token": { 3593 "value": "80UPRY5NM33OMUKMKSKU" 3594 }, 3595 "uri": "https://server.example.com/continue", 3596 "wait": 30 3597 }, 3598 "access_token": { 3599 "value": "RP1LT0-OS9M2P_R64TB", 3600 "access": [ 3601 "read" 3602 ] 3603 } 3604 } 3605 This allows the client instance to make an eventual continuation 3606 call. The client instance later realizes that it now needs "write" 3607 access in addition to the "read" access. Since this is an expansion 3608 of what it asked for previously, the client instance also includes a 3609 new interaction section in case the AS needs to interact with the RO 3610 again to gather additional authorization. Note that the client 3611 instance's nonce and callback are different from the initial request. 3612 Since the original callback was already used in the initial exchange, 3613 and the callback is intended for one-time-use, a new one needs to be 3614 included in order to use the callback again. 3616 PATCH /continue HTTP/1.1 3617 Host: server.example.com 3618 Content-Type: application/json 3619 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3620 Signature-Input: sig1=... 3621 Signature: sig1=... 3622 Content-Digest: sha-256=... 3624 { 3625 "access_token": { 3626 "access": [ 3627 "read", "write" 3628 ] 3629 }, 3630 "interact": { 3631 "start": ["redirect"], 3632 "finish": { 3633 "method": "redirect", 3634 "uri": "https://client.example.net/return/654321", 3635 "nonce": "K82FX4T4LKLTI25DQFZC" 3636 } 3637 } 3638 } 3640 From here, the AS can determine that the client instance is asking 3641 for more than it was previously granted, but since the client 3642 instance has also provided a mechanism to interact with the RO, the 3643 AS can use that to gather the additional consent. The protocol 3644 continues as it would with a new request. Since the old access 3645 tokens are good for a subset of the rights requested here, the AS 3646 might decide to not revoke them. However, any access tokens granted 3647 after this update process are new access tokens and do not modify the 3648 rights of existing access tokens. 3650 5.4. Canceling a Grant Request 3652 If the client instance wishes to cancel an ongoing grant request, it 3653 makes an HTTP DELETE request to the continuation URI. 3655 DELETE /continue HTTP/1.1 3656 Host: server.example.com 3657 Content-Type: application/json 3658 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3659 Signature-Input: sig1=... 3660 Signature: sig1=... 3662 If the request is successfully cancelled, the AS responds with an 3663 HTTP 202. The AS SHOULD revoke all associated access tokens. 3665 6. Token Management 3667 If an access token response includes the manage parameter as 3668 described in Section 3.2.1, the client instance MAY call this URI to 3669 manage the access token with any of the actions defined in the 3670 following sections: rotate and revoke. Other actions are undefined 3671 by this specification. 3673 The access token being managed acts as the access element for its own 3674 management API. The client instance MUST present proof of an 3675 appropriate key along with the access token. 3677 If the token is sender-constrained (i.e., not a bearer token), it 3678 MUST be sent with the appropriate binding for the access token 3679 (Section 7.2). 3681 If the token is a bearer token, the client instance MUST present 3682 proof of the same key identified in the initial request (Section 2.3) 3683 as described in Section 7.3. 3685 The AS MUST validate the proof and assure that it is associated with 3686 either the token itself or the client instance the token was issued 3687 to, as appropriate for the token's presentation type. 3689 6.1. Rotating the Access Token 3691 If the client instance has an access token and that access token 3692 expires, the client instance might want to rotate the access token. 3693 Rotating an access token consists of issuing a new access token in 3694 place of an existing access token, with the same rights and 3695 properties as the original token, apart from an updated expiration 3696 time. 3698 To rotate an access token, the client instance makes an HTTP POST to 3699 the token management URI, sending the access token in the appropriate 3700 header and signing the request with the appropriate key. 3702 POST /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3703 Host: server.example.com 3704 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3705 Signature-Input: sig1=... 3706 Signature: sig1=... 3707 Content-Digest: sha-256=... 3709 The AS validates that the token presented is associated with the 3710 management URI, that the AS issued the token to the given client 3711 instance, and that the presented key is appropriate to the token. 3713 Note that in many cases, the access token will have expired for 3714 regular use. To facilitate token rotation, the AS SHOULD honor the 3715 rotation request of the expired access token since it is likely that 3716 the client instance is attempting to refresh the expired token. To 3717 support this, the AS MAY allow a longer lifetime for token management 3718 compared to its use at an RS. An AS MUST NOT honor a rotation 3719 request for an access token that has been revoked or otherwise 3720 disabled. 3722 If the token is validated and the key is appropriate for the request, 3723 the AS MUST invalidate the current access token associated with this 3724 URI, if possible. Note that stateless access tokens can make 3725 proactive revocation difficult within a system, see Section 12.29. 3727 The AS responds with an HTTP 200 with a JSON body consisting of the 3728 rotated access token in the access_token field described in 3729 Section 3.2.1. The value of the access token MUST NOT be the same as 3730 the current value of the access token used to access the management 3731 API. The response MUST include an access token management URI, and 3732 the value of this URI MAY be different from the URI used by the 3733 client instance to make the rotation call. The client instance MUST 3734 use this new URI to manage the rotated access token. 3736 The access rights in the access array for the rotated access token 3737 MUST be included in the response and MUST be the same as the token 3738 before rotation. If the client instance requires different access 3739 rights, the client instance can request a new access token by 3740 creating a new request (Section 2) or by updating an existing grant 3741 request (Section 5.3). 3743 NOTE: '\' line wrapping per RFC 8792 3745 { 3746 "access_token": { 3747 "value": "FP6A8H6HY37MH13CK76LBZ6Y1UADG6VEUPEER5H2", 3748 "manage": "https://server.example.com/token/PRY5NM33O\ 3749 M4TB8N6BW7OZB8CDFONP219RP1L", 3750 "expires_in": 3600, 3751 "access": [ 3752 { 3753 "type": "photo-api", 3754 "actions": [ 3755 "read", 3756 "write", 3757 "dolphin" 3758 ], 3759 "locations": [ 3760 "https://server.example.net/", 3761 "https://resource.local/other" 3762 ], 3763 "datatypes": [ 3764 "metadata", 3765 "images" 3766 ] 3767 }, 3768 "read", "dolphin-metadata" 3769 ] 3770 } 3771 } 3773 [[ See issue #103 (https://github.com/ietf-wg-gnap/gnap-core- 3774 protocol/issues/103) ]] 3776 6.2. Revoking the Access Token 3778 If the client instance wishes to revoke the access token proactively, 3779 such as when a user indicates to the client instance that they no 3780 longer wish for it to have access or the client instance application 3781 detects that it is being uninstalled, the client instance can use the 3782 token management URI to indicate to the AS that the AS should 3783 invalidate the access token for all purposes. 3785 The client instance makes an HTTP DELETE request to the token 3786 management URI, presenting the access token and signing the request 3787 with the appropriate key. 3789 DELETE /token/PRY5NM33OM4TB8N6BW7OZB8CDFONP219RP1L HTTP/1.1 3790 Host: server.example.com 3791 Authorization: GNAP OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3792 Signature-Input: sig1=... 3793 Signature: sig1=... 3795 If the key presented is associated with the token (or the client 3796 instance, in the case of a bearer token), the AS MUST invalidate the 3797 access token, if possible, and return an HTTP 204 response code. 3799 204 No Content 3801 Though the AS MAY revoke an access token at any time for any reason, 3802 the token management function is specifically for the client 3803 instance's use. If the access token has already expired or has been 3804 revoked through other means, the AS SHOULD honor the revocation 3805 request to the token management URI as valid, since the end result is 3806 still the token not being usable. 3808 7. Securing Requests from the Client Instance 3810 In GNAP, the client instance secures its requests to the AS and RS by 3811 presenting an access token, presenting proof of a key that it 3812 possesses (aka, a "key proof"), or both an access token and key proof 3813 together. 3815 * When an access token is used with a key proof, this is a bound 3816 token request. This type of request is used for calls to the RS 3817 as well as the AS during negotiation. 3819 * When a key proof is used with no access token, this is a non- 3820 authorized signed request. This type of request is used for calls 3821 to the AS to initiate a negotiation. 3823 * When an access token is used with no key proof, this is a bearer 3824 token request. This type of request is used only for calls to the 3825 RS, and only with access tokens that are not bound to any key as 3826 described in Section 3.2.1. 3828 * When neither an access token nor key proof are used, this is an 3829 unsecured request. This type of request is used optionally for 3830 calls to the RS as part of an RS-first discovery process as 3831 described in Section 9.1. 3833 7.1. Key Formats 3835 Several different places in GNAP require the presentation of key 3836 material by value. Proof of this key material MUST be bound to a 3837 request, the nature of which varies with the location in the protocol 3838 the key is used. For a key used as part of a client instance's 3839 initial request in Section 2.3, the key value is the client 3840 instance's public key, and proof of that key MUST be presented in 3841 that request. For a key used as part of an access token response in 3842 Section 3.2.1, the proof of that key MUST be used when presenting the 3843 access token. 3845 A key presented by value MUST be a public key in at least one 3846 supported format. If a key is sent in multiple formats, all the key 3847 format values MUST be equivalent. Note that while most formats 3848 present the full value of the public key, some formats present a 3849 value cryptographically derived from the public key. 3851 proof (string): The form of proof that the client instance will use 3852 when presenting the key. The valid values of this field and the 3853 processing requirements for each are detailed in Section 7.3. 3854 REQUIRED. 3856 jwk (object): The public key and its properties represented as a 3857 JSON Web Key [RFC7517]. A JWK MUST contain the alg (Algorithm) 3858 and kid (Key ID) parameters. The alg parameter MUST NOT be 3859 "none". The x5c (X.509 Certificate Chain) parameter MAY be used 3860 to provide the X.509 representation of the provided public key. 3861 OPTIONAL. 3863 cert (string): PEM serialized value of the certificate used to sign 3864 the request, with optional internal whitespace per [RFC7468]. The 3865 PEM header and footer are optionally removed. OPTIONAL. 3867 cert#S256 (string): The certificate thumbprint calculated as per 3868 OAuth-MTLS [RFC8705] in base64 URL encoding. Note that this 3869 format does not include the full public key. OPTIONAL. 3871 Additional key formats are defined in a registry TBD (Section 11). 3873 This non-normative example shows a single key presented in multiple 3874 formats. This example key is intended to be used with the HTTP 3875 Message Signatures ({{httpsig-binding}}) proofing mechanism, as 3876 indicated by the httpsig value of the proof field. 3878 "key": { 3879 "proof": "httpsig", 3880 "jwk": { 3881 "kty": "RSA", 3882 "e": "AQAB", 3883 "kid": "xyz-1", 3884 "alg": "RS256", 3885 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8xY..." 3886 }, 3887 "cert": "MIIEHDCCAwSgAwIBAgIBATANBgkqhkiG9w0BAQsFA..." 3888 } 3890 7.1.1. Key References 3892 Keys in GNAP can also be passed by reference such that the party 3893 receiving the reference will be able to determine the appropriate 3894 keying material for use in that part of the protocol. 3896 "key": "S-P4XJQ_RYJCRTSU1.63N3E" 3898 Keys referenced in this manner MAY be shared symmetric keys. The key 3899 reference MUST NOT contain any unencrypted private or shared 3900 symmetric key information. 3902 Keys referenced in this manner MUST be bound to a single proofing 3903 mechanism. 3905 The means of dereferencing this value are out of scope for this 3906 specification. Commonly, key references are created by the AS and 3907 are not necessarily needed to be dereferencable by the client. These 3908 types of key references are an internal reference to the AS, such as 3909 an identifier of a record in a database. In other applications, it 3910 can be useful to use key references that are resolvable by both 3911 clients and ASs, which could be accomplished by e.g. a client 3912 publishing a public key at a URI. For interoperability, this method 3913 could later be described as an extension. 3915 7.1.2. Key Protection 3917 The security of GNAP relies on the cryptographic security of the keys 3918 themselves. When symmetric keys are used in GNAP, a key management 3919 system or secure key derivation mechanism MUST be used to supply the 3920 keys. Symmetric keys MUST NOT be a human memorable password or a 3921 value derived from one. Symmetric keys MUST NOT be passed by value 3922 from the client instance to the AS. 3924 7.2. Presenting Access Tokens 3926 The method the client instance uses to send an access token depends 3927 on whether the token is bound to a key, and if so which proofing 3928 method is associated with the key. This information is conveyed by 3929 the key parameter and the bearer flag in the single (Section 3.2.1) 3930 and multiple access tokens (Section 3.2.2) responses. 3932 If the flags field does not contain the bearer flag and the key is 3933 absent, the access token MUST be sent using the same key and proofing 3934 mechanism that the client instance used in its initial request (or 3935 its most recent rotation). 3937 If the flags field does not contain the bearer flag and the key value 3938 is an object as described in Section 7.1, the access token MUST be 3939 sent using the key and proofing mechanism defined by the value of the 3940 proof field within the key object. 3942 The access token MUST be sent using the HTTP "Authorization" request 3943 header field and the "GNAP" authorization scheme along with a key 3944 proof as described in Section 7.3 for the key bound to the access 3945 token. For example, an "httpsig"-bound access token is sent as 3946 follows: 3948 NOTE: '\' line wrapping per RFC 8792 3950 GET /stuff HTTP/1.1 3951 Host: resource.example.com 3952 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 3953 Signature-Input: sig1=("@method" "@target-uri" "authorization")\ 3954 ;created=1618884473;keyid="gnap-rsa" 3955 Signature: sig1=:ThgXGQjGiJYQW8JYxcNypXk7wQWG8KZ6AtyKOrqNOkgoa8iWgm\ 3956 feHLkRmT6BUj83DkLX84TQehhK3D5Lcgllhghuu2Pr3JmYVY7FFYwYAcfoISzVPKp\ 3957 YyDbh/g34qOpFvlCYDgG94ZX16LAKlqYXWn5vYgealgm54zzCCnvyaLKViGVWz6PM\ 3958 7rOIZqMQPOu6JceqdsiVn8xj2qTS9CWEmuJABtTnRoXNGVg8tUEQp7qt3F7tCI/AM\ 3959 vHW4FAYrQbE47qQsjh4zPiES1EM+lHdA9fCE0OEsfabxB7Gr9GvkMyiApWTf/Zs45\ 3960 IoJhr1OVtOCGVhEmoiNFreBTm7cTyTgg==: 3962 If the flags field contains the bearer flag, the access token is a 3963 bearer token that MUST be sent using the Authorization Request Header 3964 Field method defined in [RFC6750]. 3966 Authorization: Bearer OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0 3968 The Form-Encoded Body Parameter and URI Query Parameter methods of 3969 [RFC6750] MUST NOT be used. 3971 [[ See issue #104 (https://github.com/ietf-wg-gnap/gnap-core- 3972 protocol/issues/104) ]] 3974 The client software MUST reject as an error a situation where the 3975 flags field contains the bearer flag and the key field is present 3976 with any value. 3978 7.3. Proving Possession of a Key with a Request 3980 Any keys presented by the client instance to the AS or RS MUST be 3981 validated as part of the request in which they are presented. The 3982 type of binding used is indicated by the proof parameter of the key 3983 object in Section 7.1. Values defined by this specification are as 3984 follows: 3986 "httpsig": HTTP Signing signature headers. See Section 7.3.1. 3988 "mtls": Mutual TLS certificate verification. See Section 7.3.2. 3990 "jwsd": A detached JWS signature header. See Section 7.3.3. 3992 "jws": Attached JWS payload. See Section 7.3.4. 3994 Additional proofing methods are defined by a registry TBD 3995 (Section 11). 3997 All key binding methods used by this specification MUST cover all 3998 relevant portions of the request, including anything that would 3999 change the nature of the request, to allow for secure validation of 4000 the request. Relevant aspects include the URI being called, the HTTP 4001 method being used, any relevant HTTP headers and values, and the HTTP 4002 message body itself. The verifier of the signed message MUST 4003 validate all components of the signed message to ensure that nothing 4004 has been tampered with or substituted in a way that would change the 4005 nature of the request. Key binding method definitions SHOULD 4006 enumerate how these requirements are fulfilled. 4008 When a key proofing mechanism is bound to an access token, the key 4009 being presented MUST be the key associated with the access token and 4010 the access token MUST be covered by the signature method of the 4011 proofing mechanism. 4013 The key binding methods in this section MAY be used by other 4014 components making calls as part of GNAP, such as the extensions 4015 allowing the RS to make calls to the AS defined in 4016 [I-D.ietf-gnap-resource-servers]. To facilitate this extended use, 4017 the sections below are defined in generic terms of the "signer" and 4018 "verifier" of the HTTP message. In the core functions of GNAP, the 4019 "signer" is the client instance and the "verifier" is the AS or RS, 4020 as appropriate. 4022 When used for delegation in GNAP, these key binding mechanisms allow 4023 the AS to ensure that the keys presented by the client instance in 4024 the initial request are in control of the party calling any follow-up 4025 or continuation requests. To facilitate this requirement, the 4026 continuation response (Section 3.1) includes an access token bound to 4027 the client instance's key (Section 2.3), and that key (or its most 4028 recent rotation) MUST be proved in all continuation requests 4029 Section 5. Token management requests Section 6 are similarly bound 4030 to either the access token's own key or, in the case of bearer 4031 tokens, the client instance's key. 4033 [[ See issue #105 (https://github.com/ietf-wg-gnap/gnap-core- 4034 protocol/issues/105) ]] 4036 In the following sections, unless otherwise noted, the RS256 JOSE 4037 Signature Algorithm is applied using the following RSA key (presented 4038 here in JWK format): 4040 NOTE: '\' line wrapping per RFC 8792 4042 { 4043 "kid": "gnap-rsa", 4044 "p": "xS4-YbQ0SgrsmcA7xDzZKuVNxJe3pCYwdAe6efSy4hdDgF9-vhC5gjaRk\ 4045 i1wWuERSMW4Tv44l5HNrL-Bbj_nCJxr_HAOaesDiPn2PnywwEfg3Nv95Nn-\ 4046 eilhqXRaW-tJKEMjDHu_fmJBeemHNZI412gBnXdGzDVo22dvYoxd6GM", 4047 "kty": "RSA", 4048 "q": "rVdcT_uy-CD0GKVLGpEGRR7k4JO6Tktc8MEHkC6NIFXihk_6vAIOCzCD6\ 4049 LMovMinOYttpRndKoGTNdJfWlDFDScAs8C5n2y1STCQPRximBY-bw39-aZq\ 4050 JXMxOLyPjzuVgiTOCBIvLD6-8-mvFjXZk_eefD0at6mQ5qV3U1jZt88", 4051 "d": "FHlhdTF0ozTliDxMBffT6aJVKZKmbbFJOVNten9c3lXKB3ux3NAb_D2dB\ 4052 7inp9EV23oWrDspFtvCvD9dZrXgRKMHofkEpo_SSvBZfgtH-OTkbY_TqtPF\ 4053 FLPKAw0JX5cFPnn4Q2xE4n-dQ7tpRCKl59vZLHBrHShr90zqzFp0AKXU5fj\ 4054 b1gC9LPwsFA2Fd7KXmI1drQQEVq9R-o18Pnn4BGQNQNjO_VkcJTiBmEIVT_\ 4055 KJRPdpVJAmbgnYWafL_hAfeb_dK8p85yurEVF8nCK5oO3EPrqB7IL4UqaEn\ 4056 5Sl3u0j8x5or-xrrAoNz-gdOv7ONfZY6NFoa-3f8q9wBAHUuQ", 4057 "e": "AQAB", 4058 "qi": "ogpNEkDKg22Rj9cDV_-PJBZaXMk66Fp557RT1tafIuqJRHEufSOYnsto\ 4059 bWPJ0gHxv1gVJw3gm-zYvV-wTMNgr2wVsBSezSJjPSjxWZtmT2z68W1DuvK\ 4060 kZy15vz7Jd85hmDlriGcXNCoFEUsGLWkpHH9RwPIzguUHWmTt8y0oXyI", 4061 "dp": "dvCKGI2G7RLh3WyjoJ_Dr6hZ3LhXweB3YcY3qdD9BnxZ71mrLiMQg4c_\ 4062 EBnwqCETN_5sStn2cRc2JXnvLP3G8t7IFKHTT_i_TSTacJ7uT04MSa053Y3\ 4063 RfwbvLjRNPR0UKAE3ZxROUoIaVNuU_6-QMf8-2ilUv2GIOrCN87gP_Vk", 4064 "alg": "RS256", 4065 "dq": "iMZmELaKgT9_W_MRT-UfDWtTLeFjIGRW8aFeVmZk9R7Pnyt8rNzyN-IQ\ 4066 M40ql8u8J6vc2GmQGfokLlPQ6XLSCY68_xkTXrhoU1f-eDntkhP7L6XawSK\ 4067 Onv5F2H7wyBQ75HUmHTg8AK2B_vRlMyFKjXbVlzKf4kvqChSGEz4IjQ", 4068 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAt\ 4069 YKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZGYX\ 4070 jHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZx\ 4071 e0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0\ 4072 bunS0K3bA_3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kO\ 4073 zywzwPTuq-cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4074 } 4076 7.3.1. HTTP Message Signing 4078 This method is indicated by httpsig in the proof field. The signer 4079 creates an HTTP Message Signature as described in 4080 [I-D.ietf-httpbis-message-signatures]. 4082 The covered components of the signature MUST include the following: 4084 "@method": The method used in the HTTP request. 4086 "@target-uri": The full request URI of the HTTP request. 4088 When the message contains a request body, the covered components MUST 4089 also include the following: 4091 "content-digest": The Content-Digest header as defined in 4092 [I-D.ietf-httpbis-digest-headers]. When the request message has a 4093 body, the signer MUST calculate this header value and the verifier 4094 MUST validate this field value. Use of content-encoding agnostic 4095 digest methods (such as sha-256) is RECOMMENDED. 4097 When the request is bound to an access token, the covered components 4098 MUST also include the following: 4100 "authorization": The Authorization header used to present the access 4101 token as discussed in Section 7.2. 4103 Other message components MAY also be included. 4105 If the signer's key presented is a JWK, the keyid parameter of the 4106 signature MUST be set to the kid value of the JWK, the signing 4107 algorithm used MUST be the JWS algorithm denoted by the key's alg 4108 field, and the explicit alg signature parameter MUST NOT be included. 4110 In this example, the message body is the following JSON object: 4112 NOTE: '\' line wrapping per RFC 8792 4114 { 4115 "access_token": { 4116 "access": [ 4117 "dolphin-metadata" 4118 ] 4119 }, 4120 "interact": { 4121 "start": ["redirect"], 4122 "finish": { 4123 "method": "redirect", 4124 "uri": "https://client.foo/callback", 4125 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4126 } 4127 }, 4128 "client": { 4129 "key": { 4130 "proof": "httpsig", 4131 "jwk": { 4132 "kid": "gnap-rsa", 4133 "kty": "RSA", 4134 "e": "AQAB", 4135 "alg": "PS512", 4136 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4137 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4138 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4139 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4140 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4141 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4142 } 4143 } 4144 "display": { 4145 "name": "My Client Display Name", 4146 "uri": "https://client.foo/" 4147 }, 4148 } 4149 } 4151 This body is hashed for the Content-Digest header using sha-256 into 4152 the following encoded value: 4154 sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=: 4156 The HTTP message signature input string is calculated to be the 4157 following: 4159 NOTE: '\' line wrapping per RFC 8792 4161 "@method": POST 4162 "@target-uri": https://server.example.com/gnap 4163 "content-digest": \ 4164 sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAGg=: 4165 "content-length": 988 4166 "content-type": application/json 4167 "@signature-params": ("@method" "@target-uri" "content-digest" \ 4168 "content-length" "content-type");created=1618884473;keyid="gnap-rsa" 4170 This leads to the following full HTTP message request: 4172 NOTE: '\' line wrapping per RFC 8792 4174 POST /gnap HTTP/1.1 4175 Host: server.example.com 4176 Content-Type: application/json 4177 Content-Length: 988 4178 Content-Digest: sha-256=:q2XBmzRDCREcS2nWo/6LYwYyjrlN1bRfv+HKLbeGAG\ 4179 g=: 4180 Signature-Input: sig1=("@method" "@target-uri" "content-digest" \ 4181 "content-length" "content-type");created=1618884473;keyid="gnap-rsa" 4182 Signature: sig1=:EWJgAONk3D6542Scj8g51rYeMHw96cH2XiCMxcyL511wyemGcw\ 4183 5PosYVO3eK+v+h1H+LiO4BjapL5ffZV+SgU8Q2v+qEDA4FrP0+/ni9W+lazjIrzNs\ 4184 FAojwTlngMkAjZyDC/5+qUYB0KeEb4gnAhmuikv28DF30MT28yxCjeui2NGyzpPxB\ 4185 cWk1K2Cxb6hS1WXUSZufFN9jOzrTg2c8/jcKkROKbLZLshF/oCuxAAgDabTqJy+qk\ 4186 kz/Z/U5hI181qlTzNIYijnAvXzezlsLPZcMpJ1Au9APyBYAtDipAzyD6+IZl3rhzP\ 4187 2leuCMCOvDxg9qA83LVtsqfjNJO+dEHA==: 4189 { 4190 "access_token": { 4191 "access": [ 4192 "dolphin-metadata" 4193 ] 4194 }, 4195 "interact": { 4196 "start": ["redirect"], 4197 "finish": { 4198 "method": "redirect", 4199 "uri": "https://client.foo/callback", 4200 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4201 } 4202 }, 4203 "client": { 4204 "key": { 4205 "proof": "httpsig", 4206 "jwk": { 4207 "kid": "gnap-rsa", 4208 "kty": "RSA", 4209 "e": "AQAB", 4210 "alg": "PS512", 4211 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4212 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4213 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4214 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4215 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4216 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4217 } 4218 } 4219 "display": { 4220 "name": "My Client Display Name", 4221 "uri": "https://client.foo/" 4222 }, 4223 } 4224 } 4226 If the HTTP Message includes a message body, the verifier MUST 4227 calculate and verify the value of the Digest or Content-Digest 4228 header. The verifier MUST ensure that the signature covers all 4229 required message components. The verifier MUST validate the 4230 signature against the expected key of the signer. 4232 7.3.2. Mutual TLS 4234 This method is indicated by mtls in the proof field. The signer 4235 presents its TLS client certificate during TLS negotiation with the 4236 verifier. 4238 In this example, the certificate is communicated to the application 4239 through the Client-Cert header from a TLS reverse proxy, leading to 4240 the following full HTTP request message: 4242 POST /gnap HTTP/1.1 4243 Host: server.example.com 4244 Content-Type: application/jose 4245 Content-Length: 1567 4246 Client-Cert: \ 4247 :MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMDYxNDAyBgNVBAMM\ 4248 K05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV6QzY2bVEwHhcN\ 4249 MjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQDDCtOSVlNeUJq\ 4250 c0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBIjANBgkqhkiG\ 4251 9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT0VWtQBsmBB\ 4252 kI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8I\ 4253 kZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn11V2vxE4\ 4254 1hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo+\ 4255 uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKXfGhi3k\ 4256 OzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0GCSqG\ 4257 SIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/XsWfCE\ 4258 wHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5NH9\ 4259 W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeCgu\ 4260 NMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHlU\ 4261 fn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4262 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx: 4264 { 4265 "access_token": { 4266 "access": [ 4267 "dolphin-metadata" 4268 ] 4269 }, 4270 "interact": { 4271 "start": ["redirect"], 4272 "finish": { 4273 "method": "redirect", 4274 "uri": "https://client.foo/callback", 4275 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4276 } 4277 }, 4278 "client": { 4279 "key": { 4280 "proof": "mtls", 4281 "cert": "MIIC6jCCAdKgAwIBAgIGAXjw74xPMA0GCSqGSIb3DQEBCwUAMD\ 4282 YxNDAyBgNVBAMMK05JWU15QmpzRGp5QkM5UDUzN0Q2SVR6a3BEOE50UmppOXlhcEV\ 4283 6QzY2bVEwHhcNMjEwNDIwMjAxODU0WhcNMjIwMjE0MjAxODU0WjA2MTQwMgYDVQQD\ 4284 DCtOSVlNeUJqc0RqeUJDOVA1MzdENklUemtwRDhOdFJqaTl5YXBFekM2Nm1RMIIBI\ 4285 jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhYOJ+XOKISdMMShn/G4W9m20mT\ 4286 0VWtQBsmBBkI2cmRt4Ai8BfYdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8\ 4287 KowlyVy8IkZ8NMwSrcUIBZGYXjHpwjzvfGvXH/5KJlnR3/uRUp4Z4Ujk2bCaKegDn\ 4288 11V2vxE41hqaPUnhRZxe0jRETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDad\ 4289 z8BkPo+uv4BC0bunS0K3bA/3UgVp7zBlQFoFnLTO2uWp/muLEWGl67gBq9MO3brKX\ 4290 fGhi3kOzywzwPTuq+cVQDyEN7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQIDAQABMA0\ 4291 GCSqGSIb3DQEBCwUAA4IBAQBnYFK0eYHy+hVf2D58usj39lhL5znb/q9G35GBd/Xs\ 4292 WfCEwHuLOSZSUmG71bZtrOcx0ptle9bp2kKl4HlSTTfbtpuG5onSa3swRNhtKtUy5\ 4293 NH9W/FLViKWfoPS3kwoEpC1XqKY6l7evoTCtS+kTQRSrCe4vbNprCAZRxz6z1nEeC\ 4294 guNMk38yTRvx8ihZpVOuU+Ih+dOtVe/ex5IAPYxlQsvtfhsUZqc7IyCcy72WHnRHl\ 4295 Ufn3pJm0S5270+Yls3Iv6h3oBAP19i906UjiUTNH3g0xMW+V4uLxgyckt4wD4Mlyv\ 4296 jnaQ7Z3sR6EsXMocAbXHIAJhwKdtU/fLgdwL5vtx" 4297 } 4298 "display": { 4299 "name": "My Client Display Name", 4300 "uri": "https://client.foo/" 4301 }, 4303 }, 4304 "subject": { 4305 "formats": ["iss_sub", "opaque"] 4306 } 4307 } 4309 The verifier compares the TLS client certificate presented during 4310 mutual TLS negotiation to the expected key of the signer. Since the 4311 TLS connection covers the entire message, there are no additional 4312 requirements to check. 4314 Note that in many instances, the verifier will not do a full 4315 certificate chain validation of the presented TLS client certificate, 4316 as the means of trust for this certificate could be in something 4317 other than a PKI system, such as a static registration or trust-on- 4318 first-use. See Section 12.17 and Section 12.18 for some additional 4319 considerations for this key proofing method. 4321 7.3.3. Detached JWS 4323 This method is indicated by jwsd in the proof field. A JWS [RFC7515] 4324 object is created as follows: 4326 To protect the request, the JOSE header of the signature contains the 4327 following claims: 4329 kid (string): The key identifier. REQUIRED if the key is presented 4330 in JWK format, this MUST be the value of the kid field of the key. 4332 alg (string): The algorithm used to sign the request. MUST be 4333 appropriate to the key presented. If the key is presented as a 4334 JWK, this MUST be equal to the alg parameter of the key. MUST NOT 4335 be none. REQUIRED. 4337 typ (string): The type header, value "gnap-binding+jwsd". REQUIRED. 4339 htm (string): The HTTP Method used to make this request, as a case- 4340 sensitive ASCII string. Note that most public HTTP methods are in 4341 uppercase ASCII by convention. REQUIRED. 4343 uri (string): The HTTP URI used for this request, including all path 4344 and query components and no fragment component. REQUIRED. 4346 created (integer): A timestamp of when the signature was created, in 4347 integer seconds since UNIX Epoch. REQUIRED. 4349 When the request is bound to an access token, the JOSE header MUST 4350 also include the following: 4352 ath (string): The hash of the access token. The value MUST be the 4353 result of Base64url encoding (with no padding) the SHA-256 digest 4354 of the ASCII encoding of the associated access token's value. 4355 REQUIRED. 4357 If the HTTP request has a message body, such as an HTTP POST or PUT 4358 method, the payload of the JWS object is the Base64url encoding 4359 (without padding) of the SHA256 digest of the bytes of the body. If 4360 the request being made does not have a message body, such as an HTTP 4361 GET, OPTIONS, or DELETE method, the JWS signature is calculated over 4362 an empty payload. 4364 The signer presents the signed object in compact form [RFC7515] in 4365 the Detached-JWS HTTP Header field. 4367 In this example, the JOSE Header contains the following parameters: 4369 { 4370 "alg": "RS256", 4371 "kid": "gnap-rsa", 4372 "uri": "https://server.example.com/gnap", 4373 "htm": "POST", 4374 "typ": "gnap-binding+jwsd", 4375 "created": 1618884475 4376 } 4378 The request body is the following JSON object: 4380 NOTE: '\' line wrapping per RFC 8792 4382 { 4383 "access_token": { 4384 "access": [ 4385 "dolphin-metadata" 4386 ] 4387 }, 4388 "interact": { 4389 "start": ["redirect"], 4390 "finish": { 4391 "method": "redirect", 4392 "uri": "https://client.foo/callback", 4393 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4394 } 4395 }, 4396 "client": { 4397 "key": { 4398 "proof": "jwsd", 4399 "jwk": { 4400 "kid": "gnap-rsa", 4401 "kty": "RSA", 4402 "e": "AQAB", 4403 "alg": "RS256", 4404 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4405 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4406 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4407 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4408 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4409 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4410 } 4411 } 4412 "display": { 4413 "name": "My Client Display Name", 4414 "uri": "https://client.foo/" 4415 }, 4416 } 4417 } 4419 This is hashed to the following Base64 encoded value: 4421 PGiVuOZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc 4423 This leads to the following full HTTP request message: 4425 NOTE: '\' line wrapping per RFC 8792 4427 POST /gnap HTTP/1.1 4428 Host: server.example.com 4429 Content-Type: application/json 4430 Content-Length: 983 4431 Detached-JWS: eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0b\ 4432 SI6IlBPU1QiLCJraWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3\ 4433 NkIiwidXJpIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.PGiVuO\ 4434 ZUcN1tRtUS6tx2b4cBgw9mPgXG3IPB3wY7ctc.fUq-SV-A1iFN2MwCRW_yolVtT2_\ 4435 TZA2h5YeXUoi5F2Q2iToC0Tc4drYFOSHIX68knd68RUA7yHqCVP-ZQEd6aL32H69e\ 4436 9zuMiw6O_s4TBKB3vDOvwrhYtDH6fX2hP70cQoO-47OwbqP-ifkrvI3hVgMX9TfjV\ 4437 eKNwnhoNnw3vbu7SNKeqJEbbwZfpESaGepS52xNBlDNMYBQQXxM9OqKJaXffzLFEl\ 4438 -Xe0UnfolVtBraz3aPrPy1C6a4uT7wLda3PaTOVtgysxzii3oJWpuz0WP5kRujzDF\ 4439 wX_EOzW0jsjCSkL-PXaKSpZgEjNjKDMg9irSxUISt1C1T6q3SzRgfuQ 4441 { 4442 "access_token": { 4443 "access": [ 4444 "dolphin-metadata" 4445 ] 4446 }, 4447 "interact": { 4448 "start": ["redirect"], 4449 "finish": { 4450 "method": "redirect", 4451 "uri": "https://client.foo/callback", 4452 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4453 } 4454 }, 4455 "client": { 4456 "key": { 4457 "proof": "jwsd", 4458 "jwk": { 4459 "kid": "gnap-rsa", 4460 "kty": "RSA", 4461 "e": "AQAB", 4462 "alg": "RS256", 4463 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4464 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4465 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4466 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4467 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4468 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4469 } 4470 } 4471 "display": { 4472 "name": "My Client Display Name", 4473 "uri": "https://client.foo/" 4474 }, 4475 } 4476 } 4478 When the verifier receives the Detached-JWS header, it MUST parse and 4479 validate the JWS object. The signature MUST be validated against the 4480 expected key of the signer. All required fields MUST be present and 4481 their values MUST be valid. If the HTTP message request contains a 4482 body, the verifier MUST calculate the hash of body just as the signer 4483 does, with no normalization or transformation of the request. 4485 7.3.4. Attached JWS 4487 This method is indicated by jws in the proof field. A JWS [RFC7515] 4488 object is created as follows: 4490 To protect the request, the JWS header contains the following claims. 4492 kid (string): The key identifier. REQUIRED if the key is presented 4493 in JWK format, this MUST be the value of the kid field of the key. 4495 alg (string): The algorithm used to sign the request. MUST be 4496 appropriate to the key presented. If the key is presented as a 4497 JWK, this MUST be equal to the alg parameter of the key. MUST NOT 4498 be none. REQUIRED. 4500 typ (string): The type header, value "gnap-binding+jwsd". REQUIRED. 4502 htm (string): The HTTP Method used to make this request, as a case- 4503 sensitive ASCII string. (Note that most public HTTP methods are 4504 in uppercase.) REQUIRED. 4506 uri (string): The HTTP URI used for this request, including all path 4507 and query components and no fragment component. REQUIRED. 4509 created (integer): A timestamp of when the signature was created, in 4510 integer seconds since UNIX Epoch. REQUIRED. 4512 When the request is bound to an access token, the JOSE header MUST 4513 also include the following: 4515 ath (string): The hash of the access token. The value MUST be the 4516 result of Base64url encoding (with no padding) the SHA-256 digest 4517 of the ASCII encoding of the associated access token's value. 4518 REQUIRED. 4520 If the HTTP request has a message body, such as an HTTP POST or PUT 4521 method, the payload of the JWS object is the JSON serialized body of 4522 the request, and the object is signed according to JWS and serialized 4523 into compact form [RFC7515]. The signer presents the JWS as the body 4524 of the request along with a content type of application/jose. The 4525 verifier MUST extract the payload of the JWS and treat it as the 4526 request body for further processing. 4528 If the request being made does not have a message body, such as an 4529 HTTP GET, OPTIONS, or DELETE method, the JWS signature is calculated 4530 over an empty payload and passed in the Detached-JWS header as 4531 described in Section 7.3.3. 4533 In this example, the JOSE header contains the following parameters: 4535 { 4536 "alg": "RS256", 4537 "kid": "gnap-rsa", 4538 "uri": "https://server.example.com/gnap", 4539 "htm": "POST", 4540 "typ": "gnap-binding+jwsd", 4541 "created": 1618884475 4542 } 4544 The request body, used as the JWS Payload, is the following JSON 4545 object: 4547 NOTE: '\' line wrapping per RFC 8792 4549 { 4550 "access_token": { 4551 "access": [ 4552 "dolphin-metadata" 4553 ] 4554 }, 4555 "interact": { 4556 "start": ["redirect"], 4557 "finish": { 4558 "method": "redirect", 4559 "uri": "https://client.foo/callback", 4560 "nonce": "VJLO6A4CAYLBXHTR0KRO" 4561 } 4562 }, 4563 "client": { 4564 "key": { 4565 "proof": "jws", 4566 "jwk": { 4567 "kid": "gnap-rsa", 4568 "kty": "RSA", 4569 "e": "AQAB", 4570 "alg": "RS256", 4571 "n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\ 4572 YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\ 4573 YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\ 4574 ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\ 4575 3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\ 4576 N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ" 4577 } 4578 } 4579 "display": { 4580 "name": "My Client Display Name", 4581 "uri": "https://client.foo/" 4582 }, 4583 }, 4584 "subject": { 4585 "formats": ["iss_sub", "opaque"] 4586 } 4587 } 4589 This leads to the following full HTTP request message: 4591 NOTE: '\' line wrapping per RFC 8792 4593 POST /gnap HTTP/1.1 4594 Host: server.example.com 4595 Content-Type: application/jose 4596 Content-Length: 1047 4598 eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\ 4599 raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\ 4600 R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\ 4601 ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\ 4602 0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\ 4603 Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\ 4604 CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\ 4605 cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\ 4606 KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\ 4607 ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\ 4608 ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\ 4609 Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\ 4610 gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\ 4611 5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\ 4612 nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\ 4613 akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\ 4614 xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\ 4615 BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\ 4616 XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\ 4617 YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\ 4618 gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\ 4619 FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\ 4620 AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\ 4621 c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\ 4622 vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\ 4623 u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\ 4624 LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\ 4625 PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\ 4626 8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ 4628 When the verifier receives an attached JWS request, it MUST parse and 4629 validate the JWS object. The signature MUST be validated against the 4630 expected key of the signer. All required fields MUST be present and 4631 their values MUST be valid. If the HTTP message request contains a 4632 body, the verifier MUST decode the payload of the JWS object and 4633 treat this as the HTTP message body. 4635 8. Resource Access Rights 4637 GNAP provides a rich structure for describing the protected resources 4638 hosted by RSs and accessed by client software. This structure is 4639 used when the client instance requests an access token (Section 2.1) 4640 and when an access token is returned (Section 3.2). 4642 The root of this structure is a JSON array. The elements of the JSON 4643 array represent rights of access that are associated with the the 4644 access token. The resulting access is the union of all elements 4645 within the array. 4647 The access associated with the access token is described using 4648 objects that each contain multiple dimensions of access. Each object 4649 contains a REQUIRED type property that determines the type of API 4650 that the token is used for. 4652 type (string): The type of resource request as a string. This field 4653 MAY define which other fields are allowed in the request object. 4654 REQUIRED. 4656 The value of the type field is under the control of the AS. This 4657 field MUST be compared using an exact byte match of the string value 4658 against known types by the AS. The AS MUST ensure that there is no 4659 collision between different authorization data types that it 4660 supports. The AS MUST NOT do any collation or normalization of data 4661 types during comparison. It is RECOMMENDED that designers of 4662 general-purpose APIs use a URI for this field to avoid collisions 4663 between multiple API types protected by a single AS. 4665 While it is expected that many APIs will have their own properties, a 4666 set of common properties are defined here. Specific API 4667 implementations SHOULD NOT re-use these fields with different 4668 semantics or syntax. The available values for these properties are 4669 determined by the API being protected at the RS. All values are 4670 OPTIONAL at the discretion of the API definition. 4672 actions (array of strings): The types of actions the client instance 4673 will take at the RS as an array of strings. For example, a client 4674 instance asking for a combination of "read" and "write" access. 4676 locations (array of strings): The location of the RS as an array of 4677 strings. These strings are typically URIs identifying the 4678 location of the RS. 4680 datatypes (array of strings): The kinds of data available to the 4681 client instance at the RS's API as an array of strings. For 4682 example, a client instance asking for access to raw "image" data 4683 and "metadata" at a photograph API. 4685 identifier (string): A string identifier indicating a specific 4686 resource at the RS. For example, a patient identifier for a 4687 medical API or a bank account number for a financial API. 4689 privileges (array of strings): The types or levels of privilege 4690 being requested at the resource. For example, a client instance 4691 asking for administrative level access, or access when the 4692 resource owner is no longer online. 4694 The following non-normative example is describing three kinds of 4695 access (read, write, delete) to each of two different locations and 4696 two different data types (metadata, images) for a single access token 4697 using the fictitious photo-api type definition. 4699 "access": [ 4700 { 4701 "type": "photo-api", 4702 "actions": [ 4703 "read", 4704 "write", 4705 "delete" 4706 ], 4707 "locations": [ 4708 "https://server.example.net/", 4709 "https://resource.local/other" 4710 ], 4711 "datatypes": [ 4712 "metadata", 4713 "images" 4714 ] 4715 } 4716 ] 4718 The access requested for a given object when using these fields is 4719 the cross-product of all fields of the object. That is to say, the 4720 object represents a request for all actions listed to be used at all 4721 locations listed for all possible datatypes listed within the object. 4722 Assuming the request above was granted, the client instance could 4723 assume that it would be able to do a read action against the images 4724 on the first server as well as a delete action on the metadata of the 4725 second server, or any other combination of these fields, using the 4726 same access token. 4728 To request a different combination of access, such as requesting one 4729 of the possible actions against one of the possible locations and a 4730 different choice of possible actions against a different one of the 4731 possible locations, the client instance can include multiple separate 4732 objects in the resources array. The following non-normative example 4733 uses the same fictitious photo-api type definition to request a 4734 single access token with more specifically targeted access rights by 4735 using two discrete objects within the request. 4737 "access": [ 4738 { 4739 "type": "photo-api", 4740 "actions": [ 4741 "read" 4742 ], 4743 "locations": [ 4744 "https://server.example.net/" 4745 ], 4746 "datatypes": [ 4747 "images" 4748 ] 4749 }, 4750 { 4751 "type": "photo-api", 4752 "actions": [ 4753 "write", 4754 "delete" 4755 ], 4756 "locations": [ 4757 "https://resource.local/other" 4758 ], 4759 "datatypes": [ 4760 "metadata" 4761 ] 4762 } 4763 ] 4765 The access requested here is for read access to images on one server 4766 while simultaneously requesting write and delete access for metadata 4767 on a different server, but importantly without requesting write or 4768 delete access to images on the first server. 4770 It is anticipated that API designers will use a combination of common 4771 fields defined in this specification as well as fields specific to 4772 the API itself. The following non-normative example shows the use of 4773 both common and API-specific fields as part of two different 4774 fictitious API type values. The first access request includes the 4775 actions, locations, and datatypes fields specified here as well as 4776 the API-specific geolocation field. The second access request 4777 includes the actions and identifier fields specified here as well as 4778 the API-specific currency field. 4780 "access": [ 4781 { 4782 "type": "photo-api", 4783 "actions": [ 4784 "read", 4785 "write" 4786 ], 4787 "locations": [ 4788 "https://server.example.net/", 4789 "https://resource.local/other" 4790 ], 4791 "datatypes": [ 4792 "metadata", 4793 "images" 4794 ], 4795 "geolocation": [ 4796 { lat: -32.364, lng: 153.207 }, 4797 { lat: -35.364, lng: 158.207 } 4798 ] 4799 }, 4800 { 4801 "type": "financial-transaction", 4802 "actions": [ 4803 "withdraw" 4804 ], 4805 "identifier": "account-14-32-32-3", 4806 "currency": "USD" 4807 } 4808 ] 4810 If this request is approved, the resulting access token 4811 (Section 3.2.1)'s access rights will be the union of the requested 4812 types of access for each of the two APIs, just as above. 4814 8.1. Requesting Resources By Reference 4816 Instead of sending an object describing the requested resource 4817 (Section 8), access rights MAY be communicated as a string known to 4818 the AS or RS representing the access being requested. Each string 4819 SHOULD correspond to a specific expanded object representation at the 4820 AS. 4822 "access": [ 4823 "read", "dolphin-metadata", "some other thing" 4824 ] 4826 This value is opaque to the client instance and MAY be any valid JSON 4827 string, and therefore could include spaces, unicode characters, and 4828 properly escaped string sequences. However, in some situations the 4829 value is intended to be seen and understood by the client software's 4830 developer. In such cases, the API designer choosing any such human- 4831 readable strings SHOULD take steps to ensure the string values are 4832 not easily confused by a developer, such as by limiting the strings 4833 to easily disambiguated characters. 4835 This functionality is similar in practice to OAuth 2.0's scope 4836 parameter [RFC6749], where a single string represents the set of 4837 access rights requested by the client instance. As such, the 4838 reference string could contain any valid OAuth 2.0 scope value as in 4839 Appendix D.5. Note that the reference string here is not bound to 4840 the same character restrictions as in OAuth 2.0's scope definition. 4842 A single access array MAY include both object-type and string-type 4843 resource items. In this non-normative example, the client instance 4844 is requesting access to a photo-api and financial-transaction API 4845 type as well as the reference values of read, dolphin-metadata, and 4846 some other thing. 4848 "access": [ 4849 { 4850 "type": "photo-api", 4851 "actions": [ 4852 "read", 4853 "write", 4854 "delete" 4855 ], 4856 "locations": [ 4857 "https://server.example.net/", 4858 "https://resource.local/other" 4859 ], 4860 "datatypes": [ 4861 "metadata", 4862 "images" 4863 ] 4864 }, 4865 "read", 4866 "dolphin-metadata", 4867 { 4868 "type": "financial-transaction", 4869 "actions": [ 4870 "withdraw" 4871 ], 4872 "identifier": "account-14-32-32-3", 4873 "currency": "USD" 4874 }, 4875 "some other thing" 4876 ] 4878 The requested access is the union of all elements of the array, 4879 including both objects and reference strings. 4881 9. Discovery 4883 By design, the protocol minimizes the need for any pre-flight 4884 discovery. To begin a request, the client instance only needs to 4885 know the endpoint of the AS and which keys it will use to sign the 4886 request. Everything else can be negotiated dynamically in the course 4887 of the protocol. 4889 However, the AS can have limits on its allowed functionality. If the 4890 client instance wants to optimize its calls to the AS before making a 4891 request, it MAY send an HTTP OPTIONS request to the grant request 4892 endpoint to retrieve the server's discovery information. The AS MUST 4893 respond with a JSON document with Content-Type application/json 4894 containing a single object with the following information: 4896 grant_request_endpoint (string): The location of the AS's grant 4897 request endpoint. The location MUST be a URL [RFC3986] with a 4898 scheme component that MUST be https, a host component, and 4899 optionally, port, path and query components and no fragment 4900 components. This URL MUST match the URL the client instance used 4901 to make the discovery request. REQUIRED. 4903 interaction_start_modes_supported (array of strings): A list of the 4904 AS's interaction start methods. The values of this list 4905 correspond to the possible values for the interaction start 4906 section (Section 2.5.1) of the request. OPTIONAL. 4908 interaction_finish_methods_supported (array of strings): A list of 4909 the AS's interaction finish methods. The values of this list 4910 correspond to the possible values for the method element of the 4911 interaction finish section (Section 2.5.2) of the request. 4912 OPTIONAL. 4914 key_proofs_supported (array of strings): A list of the AS's 4915 supported key proofing mechanisms. The values of this list 4916 correspond to possible values of the proof field of the key 4917 section (Section 7.1) of the request. OPTIONAL. 4919 sub_id_formats_supported (array of strings): A list of the AS's 4920 supported subject identifier formats. The values of this list 4921 correspond to possible values of the subject identifier section 4922 (Section 2.2) of the request. OPTIONAL. 4924 assertion_formats_supported (array of strings): A list of the AS's 4925 supported assertion formats. The values of this list correspond 4926 to possible values of the subject assertion section (Section 2.2) 4927 of the request. OPTIONAL. 4929 The information returned from this method is for optimization 4930 purposes only. The AS MAY deny any request, or any portion of a 4931 request, even if it lists a capability as supported. For example, a 4932 given client instance can be registered with the mtls key proofing 4933 mechanism, but the AS also returns other proofing methods from the 4934 discovery document, then the AS will still deny a request from that 4935 client instance using a different proofing mechanism. 4937 9.1. RS-first Method of AS Discovery 4939 If the client instance calls an RS without an access token, or with 4940 an invalid access token, the RS MAY respond to the client instance 4941 with an authentication header indicating that GNAP needs to be used 4942 to access the resource. The address of the GNAP endpoint MUST be 4943 sent in the "as_uri" parameter. The RS MAY additionally return a 4944 resource reference that the client instance MAY use in its access 4945 token request. This resource reference MUST be sufficient for at 4946 least the action the client instance was attempting to take at the RS 4947 and MAY be more powerful. The means for the RS to determine the 4948 resource reference are out of scope of this specification, but some 4949 dynamic methods are discussed in [I-D.ietf-gnap-resource-servers]. 4950 The content of the resource reference is opaque to the client 4951 instance. 4953 NOTE: '\' line wrapping per RFC 8792 4955 WWW-Authenticate: \ 4956 GNAP as_uri=https://server.example/tx,access=FWWIKYBQ6U56NL1 4958 The client instance then makes a request to the "as_uri" as described 4959 in Section 2, with the value of "access" as one of the members of the 4960 access array in the access_token portion of the request. The client 4961 instance MAY request additional resources and other information. The 4962 client instance MAY request multiple access tokens. 4964 In this non-normative example, the client instance is requesting a 4965 single access token using the resource reference FWWIKYBQ6U56NL1 4966 received from the RS in addition to the dolphin-metadata resource 4967 reference that the client instance has been configured with out of 4968 band. 4970 POST /tx HTTP/1.1 4971 Host: server.example.com 4972 Content-Type: application/json 4973 Signature-Input: sig1=... 4974 Signature: sig1=... 4975 Content-Digest: sha-256=... 4977 { 4978 "access_token": { 4979 "access": [ 4980 "FWWIKYBQ6U56NL1", 4981 "dolphin-metadata" 4982 ] 4983 }, 4984 "client": "KHRS6X63AJ7C7C4AZ9AO" 4985 } 4987 If issued, the resulting access token would contain sufficient access 4988 to be used at both referenced resources. 4990 10. Acknowledgements 4992 The editors would like to thank the feedback of the following 4993 individuals for their reviews, implementations, and contributions: 4994 Åke Axeland, Aaron Parecki, Adam Omar Oueidat, Andrii Deinega, 4995 Annabelle Backman, Dick Hardt, Dmitri Zagidulin, Dmitry Barinov, 4996 Fabien Imbault, Florian Helmschmidt, Francis Pouatcha, George 4997 Fletcher, Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan, 4998 Justin Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat 4999 Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya. 5001 The editors would also like to thank the GNAP working group design 5002 team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, 5003 and Justin Richer, who incorporated elements from the XAuth and XYZ 5004 proposals to create the first version of this document. 5006 In addition, the editors would like to thank Aaron Parecki and Mike 5007 Jones for insights into how to integrate identity and authentication 5008 systems into the core protocol, and Justin Richer and Dick Hardt for 5009 the use cases, diagrams, and insights provided in the XYZ and XAuth 5010 proposals that have been incorporated here. The editors would like 5011 to especially thank Mike Varley and the team at SecureKey for 5012 feedback and development of early versions of the XYZ protocol that 5013 fed into this standards work. 5015 11. IANA Considerations 5017 [[ TBD: There are a lot of items in the document that are expandable 5018 through the use of value registries. ]] 5020 12. Security Considerations 5022 12.1. TLS Protection in Transit 5024 All requests in GNAP have to be made over TLS or equivalent as 5025 outlined in [BCP195] to protect the contents of the request and 5026 response from manipulation and interception by an attacker. This 5027 includes all requests from a client instance to the AS, all requests 5028 from the client instance to an RS, any requests back to a client 5029 instance such as the push-based interaction finish method, and any 5030 back-end communications such as from an RS to an AS as described in 5031 [I-D.ietf-gnap-resource-servers]. Additionally, all requests between 5032 a browser and other components, such as during redirect-based 5033 interaction, need to be made over TLS or use equivalent protection. 5035 Even though requests from the client instance to the AS are signed, 5036 the signature method alone does not protect the request from 5037 interception by an attacker. TLS protects the response as well as 5038 the request, preventing an attacker from intercepting requested 5039 information as it is returned. This is particularly important in the 5040 core protocol for security artifacts such as nonces and for personal 5041 information such as subject information. 5043 The use of key-bound access tokens does not negate the requirement 5044 for protecting calls to the RS with TLS. While the keys and 5045 signatures associated a bound access token will prevent an attacker 5046 from using a stolen token, without TLS an attacker would be able to 5047 watch the data being sent to the RS and returned from the RS during 5048 legitimate use of the client instance under attack. Additionally, 5049 without TLS an attacker would be able to profile the calls made 5050 between the client instance and RS, possibly gaining information 5051 about the functioning of the API between the client software and RS 5052 software that would be otherwise unknown to the attacker. 5054 TLS or equivalent protection also needs to be used between the 5055 browser and any other components. This applies during initial 5056 redirects to an AS's components during interaction, during any 5057 interaction with the resource owner, and during any redirect back to 5058 the client instance. Without TLS protection on these portions of the 5059 process, an attacker could wait for a valid request to start and then 5060 take over the resource owner's interaction session. 5062 12.2. Signing Requests from the Client Software 5064 Even though all requests in GNAP need to be transmitted over TLS or 5065 its equivalent, the use of TLS alone is not sufficient to protect all 5066 parts of a multi-party and multi-stage protocol like GNAP, and TLS is 5067 not targeted at tying multiple requests to each other over time. To 5068 account for this, GNAP makes use of message-level protection and key 5069 presentation mechanisms that strongly associate a request with a key 5070 held by the client instance (see Section 7). 5072 During the initial request from a client instance to the AS, the 5073 client instance has to identify and prove possession of a 5074 cryptographic key. If the key is known to the AS, such as if it is 5075 previously registered or dereferenceable to a trusted source, the AS 5076 can associate a set of policies to the client instance identified by 5077 the key. Without the requirement that the client instance prove that 5078 it holds that key, the AS could not trust that the connection came 5079 from any particular client and could not apply any associated 5080 policies. 5082 Even more importantly, the client instance proving possession of a 5083 key on the first request allows the AS to associate future requests 5084 with each other. The access token used for grant continuation is 5085 bound to the same key and proofing mechanism used by the client 5086 instance in its initial request, which means that the client instance 5087 needs to prove possession of that same key in future requests 5088 allowing the AS to be sure that the same client instance is executing 5089 the follow-ups for a given ongoing grant request. Therefore, the AS 5090 has to ensure that all subsequent requests for a grant are associated 5091 with the same key that started the grant, or the most recent rotation 5092 of that key. This need holds true even if the initial key is 5093 previously unknown to the AS, such as would be the case when a client 5094 instance creates an ephemeral key for its request. Without this 5095 ongoing association, an attacker would be able to impersonate a 5096 client instance in the midst of a grant request, potentially stealing 5097 access tokens and subject information with impunity. 5099 Additionally, all access tokens in GNAP default to be associated with 5100 the key that was presented during the grant request that created the 5101 access token. This association allows an RS to know that the 5102 presenter of the access token is the same party that the token was 5103 issued to, as identified by their keys. While non-bound bearer 5104 tokens are an option in GNAP, these types of tokens have their own 5105 tradeoffs discussed elsewhere in this section. 5107 TLS functions at the socket layer, ensuring that only the parties on 5108 either end of that socket connection can read the information passed 5109 along that connection. Each time a new socket connection is made, 5110 such as for a new HTTP request, a new trust is re-established that is 5111 unrelated to previous connections. As such, it is not possible with 5112 TLS alone to know that the same party is making a set of calls, and 5113 therefore TLS alone cannot provide the continuity of security needed 5114 for GNAP. However, mutual TLS (MTLS) does provide such security 5115 characteristics through the use of the TLS client certificate, and 5116 thus MTLS is acceptable as a key-presentation mechanism when applied 5117 as described in Section 7.3.2. 5119 12.3. Protection of Client Instance Key Material 5121 Client instances are identified by their unique keys, and anyone with 5122 access to a client instance's key material will be able to 5123 impersonate that client instance to all parties. This is true for 5124 both calls to the AS as well as calls to an RS using a key-bound 5125 access token. 5127 Different types of client software have different methods available 5128 for creating, managing, and registering keys. GNAP explicitly allows 5129 for ephemeral clients, such as SPAs, and single-user clients, such as 5130 mobile applications, to create and present their own keys during the 5131 initial grant request. The client software can securely generate a 5132 keypair on-device and present the public key, along with proof of 5133 holding that public key, to the AS as part of the initial request. 5134 To facilitate trust in these ephemeral keys, GNAP further allows for 5135 an extensible set of client information to be passed with the 5136 request. This information can include device posture and third-party 5137 attestations of the client software's provenance and authenticity, 5138 depending on the needs and capabilities of the client software and 5139 its deployment. 5141 From GNAP's perspective, each distinct key is a different client 5142 instance. However, multiple client instances can be grouped together 5143 by an AS policy and treated similarly to each other. For instance, 5144 if an AS knows of several different keys for different servers within 5145 a cluster, the AS can decide that authorization of one of these 5146 servers applies to all other servers within the cluster. An AS that 5147 chooses to do this needs to be careful with how it groups different 5148 client keys together in its policy, since the breach of one instance 5149 would have direct effects on the others in the cluster. 5151 Additionally, if an end user controls multiple instances of a single 5152 type of client software, such as having an application installed on 5153 multiple devices, each of these instances is expected to have a 5154 separate key and be issued separate access tokens. However, if the 5155 AS is able to group these separate instances together as described 5156 above, it can streamline the authorization process for new instances 5157 of the same client software. For example, if two client instances 5158 can present proof of a valid installation of a piece of client 5159 software, the AS would be able to associate the approval of the first 5160 instance of this software to all related instances. The AS could 5161 then choose to bypass an explicit prompt of the resource owner for 5162 approval during authorization, since such approval has already been 5163 given. An AS doing such a process would need to take assurance 5164 measures that the different instances are in fact correlated and 5165 authentic, as well as ensuring the expected resource owner is in 5166 control of the client instance. 5168 Finally, if multiple instances of client software each have the same 5169 key, then from GNAP's perspective, these are functionally the same 5170 client instance as GNAP has no reasonable way to differentiate 5171 between them. This situation could happen if multiple instances 5172 within a cluster can securely share secret information among 5173 themselves. Even though there are multiple copies of the software, 5174 the shared key makes these copies all present as a single instance. 5175 It is considered bad practice to share keys between copies of 5176 software unless they are very tightly integrated with each other and 5177 can be closely managed. It is particularly bad practice to allow an 5178 end user to copy keys between client instances and to willingly use 5179 the same key in multiple instances. 5181 12.4. Protection of Authorization Server 5183 The AS performs critical functions in GNAP, including authenticating 5184 client software, managing interactions with end users to gather 5185 consent and provide notice, and issuing access tokens for client 5186 instances to present to resource servers. As such, protecting the AS 5187 is central to any GNAP deployment. 5189 If an attacker is able to gain control over an AS, they would be able 5190 to create fraudulent tokens and manipulate registration information 5191 to allow for malicious clients. These tokens and clients would be 5192 trusted by other components in the ecosystem under the protection of 5193 the AS. 5195 If the AS is using signed access tokens, an attacker in control of 5196 the AS's signing keys would be able to manufacture fraudulent tokens 5197 for use at RS's under the protection of the AS. 5199 If an attacker is able to impersonate an AS, they would be able to 5200 trick legitimate client instances into making signed requests for 5201 information which could potentially be proxied to a real AS. To 5202 combat this, all communications to the AS need to be made over TLS or 5203 its equivalent, and the software making the connection has to 5204 validate the certificate chain of the host it is connecting to. 5206 Consequently, protecting, monitoring, and auditing the AS is 5207 paramount to preserving the security of a GNAP-protected ecosystem. 5209 12.5. Symmetric and Asymmetric Client Instance Keys 5211 The cryptographic methods used by GNAP for key-proofing can support 5212 both asymmetric and symmetric cryptography, and can be extended to 5213 use a wide variety of mechanisms. While symmetric cryptographic 5214 systems have some benefits in speed and simplicity, they have a 5215 distinct drawback that both parties need access to the same key in 5216 order to do both signing and verification of the message. This means 5217 that when the client instance calls the AS to request a token, the AS 5218 needs to know the exact value of the client instance's key (or be 5219 able to derive it) in order to validate the key proof signature. 5220 With asymmetric keys, the client needs only to send its public key to 5221 the AS to allow for verification that the client holds the associated 5222 private key, regardless of whether that key was pre-registered or not 5223 with the AS. 5225 When used to bind to an access token, a key value must be known by 5226 the RS in order to validate the proof signature on the request. 5227 Common methods for communicating these proofing keys include putting 5228 information in a structured access token and allowing the RS to look 5229 up the associated key material against the value of the access token. 5230 With symmetric cryptography, both of these methods would expose the 5231 signing key to the RS, and in the case of an structured access token, 5232 potentially to any party that can see the access token itself unless 5233 the token's payload has been encrypted. Any of these parties would 5234 then be able to make calls using the access token by creating a valid 5235 signature. With asymmetric cryptography, the RS only needs to know 5236 the public key associated with the token in order to validate, and 5237 therefore cannot create any new calls. 5239 Symmetric keys also have the expected advantage of providing better 5240 protection against quantum threats in the future. Also, these types 5241 of keys (and their secure derivations) are widely supported among 5242 many cloud-based key management systems. 5244 While both signing approaches are allowed, GNAP treats these two 5245 classes of keys somewhat differently. Only the public portion of 5246 asymmetric keys are allowed to be sent by value in requests to the AS 5247 when establishing a connection. Since sending a symmetric key (or 5248 the private portion of an asymmetric key) would expose the signing 5249 material to any parties on the request path, including any attackers, 5250 sending these kinds of keys is prohibited. Symmetric keys can still 5251 be used by client instances, but only a reference to the key and not 5252 its value can be sent. This allows the AS to use pre-registered 5253 symmetric keys as well as key derivation schemes to take advantage of 5254 symmetric cryptography but without requiring key distribution at 5255 runtime, which would expose the keys in transit. 5257 Both the AS and client software can use systems such as hardware 5258 security modules to strengthen their key security storage and 5259 generation for both asymmetric and symmetric keys (see also 5260 Section 7.1.2). 5262 12.6. Generation of Access Tokens 5264 The content of access tokens need to be such that only the generating 5265 AS would be able to create them, and the contents cannot be 5266 manipulated by an attacker to gain different or additional access 5267 rights. 5269 One method for accomplishing this is to use a cryptographically 5270 random value for the access token, generated by the AS using a secure 5271 randomization function with sufficiently high entropy. The odds of 5272 an attacker guessing the output of the randomization function to 5273 collide with a valid access token are exceedingly small, and even 5274 then the attacker would not have any control over what the access 5275 token would represent since that information would be held close by 5276 the AS. 5278 Another method for accomplishing this is to use a structured token 5279 that is cryptographically signed. In this case, the payload of the 5280 access token declares to the RS what the token is good for, but the 5281 signature applied by the AS during token generation covers this 5282 payload. Only the AS can create such a signature and therefore only 5283 the AS can create such a signed token. The odds of an attacker being 5284 able to guess a signature value with a useful payload are exceedingly 5285 small. This technique only works if all targeted RS's check the 5286 signature of the access token. Any RS that does not validate the 5287 signature of all presented tokens would be susceptible to injection 5288 of a modified or falsified token. Furthermore, an AS has to 5289 carefully protect the keys used to sign access tokens, since anyone 5290 with access to these signing keys would be able to create seemingly- 5291 valid access tokens using them. 5293 12.7. Bearer Access Tokens 5295 Bearer access tokens can be used by any party that has access to the 5296 token itself, without any additional information. As a natural 5297 consequence, any RS that a bearer token is presented to has the 5298 technical capability of presenting that bearer token to another RS, 5299 as long as the token is valid. It also means that any party that is 5300 able capture of the token value in storage or in transit is able to 5301 use the access token. While bearer tokens are inherently simpler, 5302 this simplicity has been misapplied and abused in making needlessly 5303 insecure systems. 5305 In GNAP, key-bound access tokens are the default due to their higher 5306 security properties. While bearer tokens can be used in GNAP, their 5307 use should be limited to cases where the simplicity benefits outweigh 5308 the significant security downsides. 5310 12.8. Key-Bound Access Tokens 5312 Key-bound access tokens, as the name suggests, are bound to a 5313 specific key and must be presented along with proof of that key 5314 during use. The key itself is not presented at the same time as the 5315 token, so even if a token value is captured, it cannot be used to 5316 make a new request. This is particularly true for an RS, which will 5317 see the token value but will not see the keys used to make the 5318 request. 5320 Key-bound access tokens provide this additional layer of protection 5321 only when the RS checks the signature of the message presented with 5322 the token. Acceptance of an invalid presentation signature, or 5323 failure to check the signature entirely, would allow an attacker to 5324 make calls with a captured access token without having access to the 5325 related signing key material. 5327 In addition to validating the signature of the presentation message 5328 itself, the RS also needs to ensure that the signing key used is 5329 appropriate for the presented token. If an RS does not ensure that 5330 the right keys were used to sign a message with a specific token, an 5331 attacker would be able to capture an access token and sign the 5332 request with their own keys, thereby negating the benefits of using 5333 key-bound access tokens. 5335 The RS also needs to ensure that sufficient portions of the message 5336 are covered by the signature. Any items outside the signature could 5337 still affect the API's processing decisions, but these items would 5338 not be strongly bound to the token presentation. As such, an 5339 attacker could capture a valid request, then manipulate portions of 5340 the request outside of the signature envelope in order to cause 5341 unwanted actions at the protected API. 5343 Some key-bound tokens are susceptible to replay attacks, depending on 5344 the details of the signing method used. If a signature method covers 5345 only portions of a given request, that same signature proof can be 5346 used by an attacker to make a similar call, potentially even varying 5347 elements that are outside of the protection of the signature. Key 5348 proofing mechanisms used with access tokens therefore need to use 5349 replay protection mechanisms covered under the signature such as a 5350 per-message nonce, a reasonably short time validity window, or other 5351 uniqueness constraints. The details of using these will vary 5352 depending on the key proofing mechanism in use, but for example, HTTP 5353 Message Signatures has both a created and nonce signature parameter 5354 as well as the ability to cover significant portions of the HTTP 5355 message. 5357 12.9. Exposure of End-user Credentials to Client Instance 5359 As a delegation protocol, one of the main goals of GNAP is to prevent 5360 the client software from being exposed to any credentials or 5361 information about the end user or resource owner as a requirement of 5362 the delegation process. By using the variety of interaction 5363 mechanisms, the resource owner can interact with the AS without ever 5364 authenticating to the client software, and without the client 5365 software having to impersonate the resource owner through replay of 5366 their credentials. 5368 Consequently, no interaction methods defined in the GNAP core require 5369 the end user to enter their credentials, but it is technologically 5370 possible for an extension to be defined to carry such values. Such 5371 an extension would be dangerous as it would allow rogue client 5372 software to directly collect, store, and replay the end user's 5373 credentials outside of any legitimate use within a GNAP request. 5375 The concerns of such an extension could be mitigated through use of a 5376 challenge and response unlocked by the end user's credentials. For 5377 example, the AS presents a challenge as part of an interaction start 5378 method, and the client instance signs that challenge using a key 5379 derived from a password presented by the end user. It would be 5380 possible for the client software to collect this password in a secure 5381 software enclave without exposing the password to the rest of the 5382 client software or putting it across the wire to the AS. The AS can 5383 validate this challenge response against a known password for the 5384 identified end user. While an approach such as this does not remove 5385 all of the concerns surrounding such a password-based scheme, it is 5386 at least possible to implement in a more secure fashion than simply 5387 collecting and replaying the password. Even so, such schemes should 5388 only ever be used by trusted clients due to the ease of abusing them. 5390 12.10. Mixing Up Authorization Servers 5392 If a client instance is able to work with multiple AS's 5393 simultaneously, it is more possible for an attacker to add a 5394 compromised AS to the client instance's configuration and cause the 5395 client software to start a request at the compromised AS. This AS 5396 could then proxy the client's request to a valid AS in order to 5397 attempt to get the resource owner to approve access for the 5398 legitimate client instance. 5400 A client instance needs to always be aware of which AS it is talking 5401 to throughout a grant process, and ensure that any callback for one 5402 AS does not get conflated with the callback to different AS. The 5403 interaction finish hash calculate allows a client instance to protect 5404 against this kind of substitution, but only if the client instance 5405 validates the hash. If the client instance does not use an 5406 interaction finish method or does not check the interaction finish 5407 hash value, the compromised AS can be granted a valid access token on 5408 behalf of the resource owner. See [AXELAND2021] for details of one 5409 such attack, which has been since addressed in this document by 5410 including the grant endpoint in the interaction hash calculation. 5411 The client instance still needs to validate the hash for the attack 5412 to be prevented. 5414 12.11. Processing of Client-Presented User Information 5416 GNAP allows the client instance to present assertions and identifiers 5417 of the current user to the AS as part of the initial request. This 5418 information should only ever be taken by the AS as a hint, since the 5419 AS has no way to tell if the represented person is present at the 5420 client software, without using an interaction mechanism. This 5421 information does not guarantee the given user is there, but it does 5422 constitute a statement by the client software that the AS can take 5423 into account. 5425 For example, if a specific user is claimed to be present prior to 5426 interaction, but a different user is shown to be present during 5427 interaction, the AS can either determine this to be an error or 5428 signal to the client instance through returned subject information 5429 that the current user has changed from what the client instance 5430 thought. This user information can also be used by the AS to 5431 streamline the interaction process when the user is present. For 5432 example, instead of having the user type in their account identifier 5433 during interaction at a redirected URI, the AS can immediately 5434 challenge the user for their account credentials. Alternatively, if 5435 an existing session is detected, the AS can determine that it matches 5436 the identifier provided by the client and subsequently skip an 5437 explicit authentication event by the resource owner. 5439 In cases where the AS trusts the client software more completely, due 5440 to policy or by previous approval of a given client instance, the AS 5441 can take this user information as a statement that the user is 5442 present and could issue access tokens and release subject information 5443 without interaction. The AS should only take such action in very 5444 limited circumstances, as a client instance could assert whatever it 5445 likes for the user's identifiers in its request. 5447 When a client instance presents an assertion to the AS, the AS needs 5448 to evaluate that assertion. Since the AS is unlikely to be the 5449 intended audience of an assertion held by the client software, the AS 5450 will need to evaluate the assertion in a different context. Even in 5451 this case, the AS can still evaluate that the assertion was generated 5452 by a trusted party, was appropriately signed, and is within any time 5453 validity windows stated by the assertion. If the client instance's 5454 audience identifier is known to the AS and can be associated with the 5455 client instance's presented key, the AS can also evaluate that the 5456 appropriate client instance is presenting the claimed assertion. All 5457 of this will prevent an attacker from presenting a manufactured 5458 assertion, or one captured from an untrusted system. However, 5459 without validating the audience of the assertion, a captured 5460 assertion could be presented by the client instance to impersonate a 5461 given end user. In such cases, the assertion offers little more 5462 protection than a simple identifier would. 5464 A special case exists where the AS is the generator of the assertion 5465 being presented by the client instance. In these cases, the AS can 5466 validate that it did issue the assertion and it is associated with 5467 the client instance presenting the assertion. 5469 12.12. Client Instance Pre-registration 5471 Each client instance is identified by its own unique key, and for 5472 some kinds of client software such as a web server or backend system, 5473 this identification can be facilitated by registering a single key 5474 for a piece of client software ahead of time. This registration can 5475 be associated with a set of display attributes to be used during the 5476 authorization process, identifying the client software to the user. 5477 In these cases, it can be assumed that only one instance of client 5478 software will exist, likely to serve many different users. 5480 A client's registration record needs to include its identifying key. 5481 Furthermore, it is the case that any clients using symmetric 5482 cryptography for key proofing mechanisms need to have their keys pre- 5483 registered. The registration should also include any information 5484 that would aid in the authorization process, such as a display name 5485 and logo. The registration record can also limit a given client to 5486 ask for certain kinds of information and access, or be limited to 5487 specific interaction mechanisms at runtime. 5489 It also is sensible to pre-register client instances when the 5490 software is acting autonomously, without the need for a runtime 5491 approval by a resource owner or any interaction with an end user. In 5492 these cases, an AS needs to rest on the trust decisions that have 5493 been determined prior to runtime in determining what rights and 5494 tokens to grant to a given client instance. 5496 However, it does not make sense to pre-register many types of 5497 clients. Single-page applications (SPAs) and mobile/desktop 5498 applications in particular present problems with pre-registration. 5499 For SPAs, the instances are ephemeral in nature and long-term 5500 registration of a single instance leads to significant storage and 5501 management overhead at the AS. For mobile applications, each 5502 installation of the client software is a separate instance, and 5503 sharing a key among all instances would be detrimental to security as 5504 the compromise of any single installation would compromise all copies 5505 for all users. 5507 An AS can treat these classes of client software differently from 5508 each other, perhaps by allowing access to certain high-value APIs 5509 only to pre-registered known clients, or by requiring an active end 5510 user delegation of authority to any client software not pre- 5511 registered. 5513 An AS can also provide warnings and caveats to resource owners during 5514 the authorization process, allowing the user to make an informed 5515 decision regarding the software they are authorizing. For example, 5516 if the AS has done vetting of the client software and this specific 5517 instance, it can present a different authorization screen compared to 5518 a client instance that is presenting all of its information at 5519 runtime. 5521 12.13. Client Instance Impersonation 5523 If client instances are allowed to set their own user-facing display 5524 information, such as a display name and website URL, a malicious 5525 client instance could impersonate legitimate client software for the 5526 purposes of tricking users into authorizing the malicious client. 5528 Requiring clients to pre-register does not fully mitigate this 5529 problem since many pre-registration systems have self-service portals 5530 for management of client registration, allowing authenticated 5531 developers to enter self-asserted information into the management 5532 portal. 5534 An AS can mitigate this by actively filtering all self-asserted 5535 values presented by client software, both dynamically as part of GNAP 5536 and through a registration portal, to limit the kinds of 5537 impersonation that would be done. 5539 An AS can also warn the resource owner about the provenance of the 5540 information it is displaying, allowing the resource owner to make a 5541 more informed delegation decision. For example, an AS can visually 5542 differentiate between a client instance that can be traced back to a 5543 specific developer's registration and an instance that has self- 5544 asserted its own key and display information. 5546 12.14. Interception of Information in the Browser 5548 Most information passed through the web-browser is susceptible to 5549 interception and possible manipulation by elements within the browser 5550 such as scripts loaded within pages. Information in the URI is 5551 exposed through browser and server logs, and can also leak to other 5552 parties through HTTP Referer headers. 5554 GNAP's design limits the information passed directly through the 5555 browser, allowing for opaque URIs in most circumstances. For the 5556 redirect-based interaction finish mechanism, named query parameters 5557 are used to carry unguessable opaque values. For these, GNAP 5558 requires creation and validation of a cryptographic hash to protect 5559 the query parameters added to the URI and associate them with an 5560 ongoing grant process. The client instance has to properly validate 5561 this hash to prevent an attacker from injecting an interaction 5562 reference intended for a different AS or client instance. 5564 Several interaction start mechanisms use URIs created by the AS and 5565 passed to the client instance. While these URIs are opaque to the 5566 client instance, it's possible for the AS to include parameters, 5567 paths, and other pieces of information that could leak security data 5568 or be manipulated by a party in the middle of the transaction. 5570 12.15. Callback URI Manipulation 5572 The callback URI used in interaction finish mechanisms is defined by 5573 the client instance. This URI is opaque to the AS, but can contain 5574 information relevant to the client instance's operations. In 5575 particular, the client instance can include state information to 5576 allow the callback request to be associated with an ongoing grant 5577 request. 5579 Since this URI is exposed to the end user's browser, it is 5580 susceptible to both logging and manipulation in transit before the 5581 request is made to the client software. As such, a client instance 5582 should never put security-critical or private information into the 5583 callback URI in a cleartext form. For example, if the client 5584 software includes a post-redirect target URI in its callback URI to 5585 the AS, this target URI could be manipulated by an attacker, creating 5586 an open redirector at the client. Instead, a client instance can use 5587 an unguessable identifier into the URI that can then be used by the 5588 client software to look up the details of the pending request. Since 5589 this approach requires some form of statefulness by the client 5590 software during the redirection process, clients that are not capable 5591 of holding state through a redirect should not use redirect-based 5592 interaction mechanisms. 5594 12.16. Redirection Status Codes 5596 As already described in [I-D.ietf-oauth-security-topics], a server 5597 should never use the HTTP 307 status code to redirect a request that 5598 potentially contains user credentials. If an HTTP redirect is used 5599 for such a request, the HTTP status code 303 "See Other" should be 5600 used instead. 5602 The status code 307, as defined in the HTTP standard [RFC7231], 5603 requires the user agent to preserve the method and body of a request, 5604 thus submitting the body of the POST request to the redirect target. 5605 In the HTTP standard [RFC7231], only the status code 303 5606 unambiguously enforces rewriting the HTTP POST request to an HTTP GET 5607 request, which eliminates the POST body from the redirected request. 5608 For all other status codes, including status code 302, user agents 5609 are allowed not to rewrite a POST request into a GET request and thus 5610 to resubmit the body. 5612 The use of status code 307 results in a vulnerability when using the 5613 redirect interaction finish method (Section 3.3.5). With this 5614 method, the AS potentially prompts the RO to enter their credentials 5615 in a form that is then submitted back to the AS (using an HTTP POST 5616 request). The AS checks the credentials and, if successful, may 5617 directly redirect the RO to the client instance's redirect URI. Due 5618 to the use of status code 307, the RO's user agent now transmits the 5619 RO's credentials to the client instance. A malicious client instance 5620 can then use the obtained credentials to impersonate the RO at the 5621 AS. 5623 Redirection away from the initial URI in an interaction session could 5624 also leak information found in that initial URI through the HTTP 5625 Referer header field, which would be sent by the user agent to the 5626 redirect target. To avoid such leakage, a server can first redirect 5627 to an internal interstitial page without any identifying or sensitive 5628 information on the URI before processing the request. When the user 5629 agent is ultimately redirected from this page, no part of the 5630 original interaction URI will be found in the Referrer header. 5632 12.17. MTLS Message Integrity 5634 The MTLS key proofing mechanism (Section 7.3.2) provides a means for 5635 a client instance to present a key using a certificate at the TLS 5636 layer. Since TLS protects the entire HTTP message in transit, 5637 verification of the TLS client certificate presented with the message 5638 provides a sufficient binding between the two. However, since TLS is 5639 functioning at a separate layer from HTTP, there is no direct 5640 connection between the TLS key presentation and the message itself, 5641 other than the fact that the message was presented over the TLS 5642 channel. That is to say, any HTTP message can be presented over the 5643 TLS channel in question with the same level of trust. The verifier 5644 is responsible for ensuring the key in the TLS client certificate is 5645 the one expected for a particular request. For example, if the 5646 request is a grant request (Section 2), the AS needs to compare the 5647 TLS client certificate presented at the TLS layer to the key 5648 identified in the request body itself (either by value or through a 5649 referenced identifier). 5651 Furthermore, the prevalence of the TLS-terminating reverse proxy 5652 (TTRP) pattern in deployments adds a wrinkle to the situation. In 5653 this common pattern, the TTRP validates the TLS connection and then 5654 forwards the HTTP message contents onward to an internal system for 5655 processing. The system processing the HTTP message no longer has 5656 access to the original TLS connection's information and context. To 5657 compensate for this, the TTRP could inject the TLS client certificate 5658 into the forwarded request as a header parameter using 5659 [I-D.ietf-httpbis-client-cert-field], giving the downstream system 5660 access to the certificate information. The TTRP has to be trusted to 5661 provide accurate certificate information, and the connection between 5662 the TTRP and the downstream system also has to be protected. The 5663 TTRP could provide some additional assurance, for example, by adding 5664 its own signature to the Client-Cert header field using 5665 [I-D.ietf-httpbis-message-signatures]. This signature would be 5666 effectively ignored by GNAP but understood by the downstream service 5667 as part of its deployment. 5669 Additional considerations for different types of deployment patterns 5670 and key distribution mechanisms for MTLS are found in Section 12.18. 5672 12.18. MTLS Deployment Patterns 5674 GNAP does not specify how a client instance's keys could be made 5675 known to the AS ahead of time. Public Key Infrastructure (PKI) can 5676 be used to manage the keys used by client instances when calling the 5677 AS, allowing the AS to trust a root key from a trusted authority. 5678 This method is particularly relevant to the MTLS key proofing method, 5679 where the client instance presents its certificate to the AS as part 5680 of the TLS connection. An AS using PKI to validate the MTLS 5681 connection would need to ensure that the presented certificate was 5682 issued by a trusted certificate authority before allowing the 5683 connection to continue. PKI-based certificates would allow a key to 5684 be revoked and rotated through management at the certificate 5685 authority without requiring additional registration or management at 5686 the AS. PKI has historically been difficult to deploy, especially at 5687 scale, but it remains an appropriate solution for systems where the 5688 required overhead is not an impediment. 5690 MTLS in GNAP need not use a PKI backing, as self-signed certificates 5691 and certificates from untrusted authorities can still be presented as 5692 part of a TLS connection. In this case, the verifier would validate 5693 the connection but accept whatever certificate was presented by the 5694 client software. This specific certificate would then be bound to 5695 all future connections from that client software by being bound to 5696 the resulting access tokens. See Section 12.17 for more 5697 considerations on MTLS as a key proofing mechanism. 5699 12.19. Interception of Responses from the AS 5701 Responses from the AS contain information vital to both the security 5702 and privacy operations of GNAP. This information includes nonces 5703 used in cryptographic calculations, subject identifiers, assertions, 5704 public keys, and information about what client software is requesting 5705 and was granted. 5707 In addition, if bearer tokens are used or keys are issued alongside a 5708 bound access token, the response from the AS contains all information 5709 necessary for use of the contained access token. Any party that is 5710 capable of viewing such a response, such as an intermediary proxy, 5711 would be able to exfiltrate and use this token. If the access token 5712 is instead bound to the client instance's presented key, 5713 intermediaries no longer have sufficient information to use the 5714 token. They can still, however, gain information about the end user 5715 as well as the actions of the client software. 5717 12.20. Key Distribution 5719 The keys for client instances could be distributed as part of the 5720 deployment process of instances of the client software. For example, 5721 an application installation framework could generate a keypair for 5722 each copy of client software, then both install it into the client 5723 software upon installation and registering that instance with the AS. 5725 Additionally, it's possible for the AS to generate keys to be used 5726 with access tokens that are separate from the keys used by the client 5727 instance to request tokens. In this method, the AS would generate 5728 the asymmetric keypair or symmetric key and return the entire key, 5729 including all private signing information, to the client instance 5730 alongside the access token itself. This approach would make 5731 interception of the return from the token endpoint equivalent to that 5732 of a bearer token, since all information required to use the access 5733 token would be present in the request. 5735 12.21. Interaction Finish Modes and Polling 5737 During the interaction process, the client instance usually hands 5738 control of the user experience over to another component, beit the 5739 system browser, another application, or some action the resource 5740 owner is instructed to take on another device. By using an 5741 interaction finish method, the client instance can be securely 5742 notified by the AS when the interaction is completed and the next 5743 phase of the protocol should occur. This process includes 5744 information that the client instance can use to validate the finish 5745 call from the AS and prevent some injection, session hijacking, and 5746 phishing attacks. 5748 Some types of client deployment are unable to receive an interaction 5749 finish message. Without an interaction finish method to notify it, 5750 the client instance will need to poll the grant continuation API 5751 while waiting for the resource owner to approve or deny the request. 5752 An attacker could take advantage of this situation by capturing the 5753 interaction start parameters and phishing a legitimate user into 5754 authorizing the attacker's waiting client instance, which would in 5755 turn have no way of associating the completed interaction with the 5756 start of the request. 5758 However, it is important to note that this pattern is practically 5759 indistinguishable from some legitimate use cases. For example, a 5760 smart device emits a code for the resource owner to enter on a 5761 separate device. The smart device has to poll because the expected 5762 behavior is that the interaction will take place on the separate 5763 device, without a way to return information to the original device's 5764 context. 5766 As such, developers need to weigh the risks of forgoing an 5767 interaction finish method against the deployment capabilities of the 5768 client software and its environment. Due to the increased security, 5769 an interaction finish method should be employed whenever possible. 5771 12.22. Session Management for Interaction Finish Methods 5773 When using an interaction finish method such as redirect or push, the 5774 client instance receives an unsolicited HTTP request from an unknown 5775 party. The client instance needs to be able to successfully 5776 associate this incoming request with a specific pending grant request 5777 being managed by the client instance. If the client instance is not 5778 careful and precise about this, an attacker could associate their own 5779 session at the client instance with a stolen interaction response. 5780 The means of preventing this varies by the type of client software 5781 and interaction methods in use. Some common patterns are enumerated 5782 here. 5784 If the end user interacts with the client instance through a web 5785 browser and the redirect interaction finish method is used, the 5786 client instance can ensure that the incoming HTTP request from the 5787 finish method is presented in the same browser session that the grant 5788 request was started in. This technique is particularly useful when 5789 the redirect interaction start mode is used as well, since in many 5790 cases the end user will follow the redirection with the same browser 5791 that they are using to interact with the client instance. The client 5792 instance can then store the relevant pending grant information in the 5793 session, either in the browser storage directly (such as with a 5794 single-page application) or in an associated session store on a back- 5795 end server. In both cases, when the incoming request reaches the 5796 client instance, the session information can be used to ensure that 5797 the same party that started the request is present as the request 5798 finishes. 5800 Ensuring that the same party that started a request is present when 5801 that request finishes can prevent phishing attacks, where an attacker 5802 starts a request at an honest client instance and tricks an honest RO 5803 into authorizing it. For example, if an honest end user (that also 5804 acts as the RO) wants to start a request through a client instance 5805 controlled by the attacker, the attacker can start a request at an 5806 honest client instance and then redirect the honest end user to the 5807 interaction URI from the attackers session with the honest client 5808 instance. If the honest end user then fails to realize that it is 5809 not authorizing the attacker-controlled client instance (with which 5810 it started its request) but the honest client instance when 5811 interacting with the AS, the attacker's session with the honest 5812 client instance would be authorized. This would give the attacker 5813 access to the honest end user's resources that the honest client 5814 instance is authorized to access. However, if after the interaction 5815 the AS redirects the honest end user back to the client instance 5816 whose grant request the end user just authorized, the honest end user 5817 is redirected to the honest client instance. The honest client 5818 instance can then detect that it is not the party that started the 5819 request that is present, since the request at the honest client 5820 instance was started by the attacker, which can prevent the attack. 5821 This is related to Section 12.13, because again the attack can be 5822 prevented by the AS informing the user as much as possible about the 5823 client instance that is to be authorized. 5825 If the end user does not interact with the client instance through a 5826 web browser or the interaction start method does not use the same 5827 browser or device that the end user is interacting through (such as 5828 the launch of a second device through a scannable code or 5829 presentation of a user code) the client instance will not be able to 5830 strongly associate an incoming HTTP request with an established 5831 session with the end user. This is also true when the push 5832 interaction finish method is used, since the HTTP request comes 5833 directly from the interaction component of the AS. In these 5834 circumstances, the client instance can at least ensure that the 5835 incoming HTTP request can be uniquely associated with an ongoing 5836 grant request by making the interaction finish callback URI unique 5837 for the grant when making the interaction request (Section 2.5.2). 5838 Mobile applications and other client instances that generally serve 5839 only a single end user at a time can use this unique incoming URL to 5840 differentiate between a legitimate incoming request and an attacker's 5841 stolen request. 5843 If the client instance does not have the ability to use an 5844 interaction finish method, it can use polling to continue the 5845 request. The tradeoffs of this approach are discussed in 5846 Section 12.21, and if possible, an explicit interaction finish method 5847 should be used instead. 5849 12.23. Storage of Information During Interaction and Continuation 5851 When starting an interactive grant request, a client application has 5852 a number of protocol elements that it needs to manage, including 5853 nonces, references, keys, access tokens, and other elements. During 5854 the interaction process, the client instance usually hands control of 5855 the user experience over to another component, beit the system 5856 browser, another application, or some action the resource owner is 5857 instructed to take on another device. In order for the client 5858 instance to make its continuation call, it will need to recall all of 5859 these protocol elements. Usually this means the client instance will 5860 need to store these protocol elements in some retrievable fashion. 5862 If the security protocol elements are stored on the end user's 5863 device, such as in browser storage or in local application data 5864 stores, capture and exfiltration of this information could allow an 5865 attacker to continue a pending transaction instead of the client 5866 instance. Client software can make use of secure storage mechanisms, 5867 including hardware-based key and data storage, to prevent such 5868 exfiltration. 5870 Note that in GNAP, the client instance has to choose its interaction 5871 finish URI prior to making the first call to the AS. As such, the 5872 interaction finish URI will often have a unique identifier for the 5873 ongoing request, allowing the client instance to access the correct 5874 portion of its storage. Since this URI is passed to other parties 5875 and often used through a browser, this URI should not contain any 5876 security-sensitive information that would be valuable to an attacker, 5877 such as any token identifier, nonce, or user information. Instead, a 5878 cryptographically random value is suggested. 5880 12.24. Denial of Service (DoS) through Grant Continuation 5882 When a client instance starts off an interactive process, it will 5883 eventually need to continue the grant request in a subsequent message 5884 to the AS. It's possible for a naive client implementation to 5885 continuously send continuation requests to the AS while waiting for 5886 approval, especially if no interaction finish method is used. Such 5887 constant requests could overwhelm the AS's ability to respond to both 5888 these and other requests. 5890 To mitigate this for well-behaved client software, the continuation 5891 response contains a wait parameter that is intended to tell the 5892 client instance how long it should wait until making its next 5893 request. This value can be used to back off client software that is 5894 checking too quickly by returning increasing wait times for a single 5895 client instance. 5897 If client software ignores the wait value and makes its continuation 5898 calls too quickly, or if the client software assumes the absence of 5899 the wait values means it should poll immediately, the AS can choose 5900 to return errors to the offending client instance, including possibly 5901 canceling the ongoing grant request. With well-meaning client 5902 software these errors can indicate a need to change the client 5903 software's programmed behavior. 5905 12.25. Exhaustion of Random Value Space 5907 Several parts of the GNAP process make use of unguessable randomized 5908 values, such as nonces, tokens, and randomized URIs. Since these 5909 values are intended to be unique, a sufficiently powerful attacker 5910 could make a large number of requests to trigger generation of 5911 randomized values in an attempt to exhaust the random number 5912 generation space. While this attack is particularly applicable to 5913 the AS, client software could likewise be targeted by an attacker 5914 triggering new grant requests against an AS. 5916 To mitigate this, software can ensure that its random values are 5917 chosen from a significantly large pool that exhaustion of that pool 5918 is prohibitive for an attacker. Additionally, the random values can 5919 be time-boxed in such a way as their validity windows are reasonably 5920 short. Since many of the random values used within GNAP are used 5921 within limited portions of the protocol, it is reasonable for a 5922 particular random value to be valid for only a small amount of time. 5923 For example, the nonces used for interaction finish hash calculation 5924 need only to be valid while the client instance is waiting for the 5925 finish callback and can be functionally expired when the interaction 5926 has completed. Similarly, artifacts like access tokens and the 5927 interaction reference can be limited to have lifetimes tied to their 5928 functional utility. Finally, each different category of artifact 5929 (nonce, token, reference, identifier, etc.) can be generated from a 5930 separate random pool of values instead of a single global value 5931 space. 5933 12.26. Front-channel URIs 5935 Some interaction methods in GNAP make use of URIs accessed through 5936 the end user's browser, known collectively as front-channel 5937 communication. These URIs are most notably present in the redirect 5938 interaction start method and the redirect interaction finish mode. 5939 Since these URIs are intended to be given to the end user, the end 5940 user and their browser will be subjected to anything hosted at that 5941 URI including viruses, malware, and phishing scams. This kind of 5942 risk is inherent to all redirection-based protocols, including GNAP 5943 when used in this way. 5945 When talking to a new or unknown AS, a client instance might want to 5946 check the URI from the interaction start against a blocklist and warn 5947 the end user before redirecting them. Many client instances will 5948 provide an interstitial message prior to redirection in order to 5949 prepare the user for control of the user experience being handed to 5950 the domain of the AS, and such a method could be used to warn the 5951 user of potential threats. For instance, a rogue AS impersonating a 5952 well-known service provider. Client software can also prevent this 5953 by managing an allowlist of known and trusted AS's. 5955 Alternatively, an attacker could start a GNAP request with a known 5956 and trusted AS but include their own attack site URI as the callback 5957 for the redirect finish method. The attacker would then send the 5958 interaction start URI to the victim and get them to click on it. 5959 Since the URI is at the known AS, the victim is inclined to do so. 5960 The victim will then be prompted to approve the attacker's 5961 application, and in most circumstances the victim will then be 5962 redirected to the attacker's site whether or not the user approved 5963 the request. The AS could mitigate this partially by using a 5964 blocklist and allowlist of interaction finish URIs during the client 5965 instance's initial request, but this approach can be especially 5966 difficult if the URI has any dynamic portion chosen by the client 5967 software. The AS can couple these checks with policies associated 5968 with the client instance that has been authenticated in the request. 5969 If the AS has any doubt about the interaction finish URI, the AS can 5970 provide an interstitial warning to the end user before processing the 5971 redirect. 5973 Ultimately, all protocols that use redirect-based communication 5974 through the user's browser are susceptible to having an attacker try 5975 to co-opt one or more of those URIs in order to harm the user. It is 5976 the responsibility of the AS and the client software to provide 5977 appropriate warnings, education, and mitigation to protect end users. 5979 12.27. Processing Assertions 5981 Identity assertions can be used in GNAP to convey subject 5982 information, both from the AS to the client instance in a response 5983 (Section 3.4) and from the client instance to the AS in a request 5984 (Section 2.2). In both of these circumstances, when an assertion is 5985 passed in GNAP, the receiver of the assertion needs to parse and 5986 process the assertion. As assertions are complex artifacts with 5987 their own syntax and security, special care needs to be taken to 5988 prevent the assertion values from being used as an attack vector. 5990 All assertion processing needs to account for the security aspects of 5991 the assertion format in use. In particular, the processor needs to 5992 parse the assertion from a JSON string object, and apply the 5993 appropriate cryptographic processes to ensure the integrity of the 5994 assertion. 5996 For example, when SAML 2 assertions are used, the receiver hast to 5997 parse an XML document. There are many well-known security 5998 vulnerabilities in XML parsers, and the XML standard itself can be 5999 attacked through the use of processing instructions and entity 6000 expansions to cause problems with the processor. Therefore, any 6001 system capable of processing SAML 2 assertions also needs to have a 6002 secure and correct XML parser. In addition to this, the SAML 2 6003 specification uses XML Signatures, which have their own 6004 implementation problems that need to be accounted for. Similar 6005 requirements exist for OpenID Connect's ID token, which is based on 6006 the JSON Web Token (JWT) format and the related JSON Object Signing 6007 And Encryption (JOSE) cryptography suite. 6009 12.28. Stolen Token Replay 6011 If a client instance can request tokens at multiple AS's, and the 6012 client instance uses the same keys to make its requests across those 6013 different AS's, then it is possible for an attacker to replay a 6014 stolen token issued by an honest AS from a compromised AS, thereby 6015 binding the stolen token to the client instance's key in a different 6016 context. The attacker can manipulate the client instance into using 6017 the stolen token at an RS, particularly at an RS that is expecting a 6018 token from the honest AS. Since the honest AS issued the token and 6019 the client instance presents the token with its expected bound key, 6020 the attack succeeds. 6022 This attack has several preconditions. In this attack, the attacker 6023 does not need access to the client instance's key and cannot use the 6024 stolen token directly at the RS, but the attacker is able to get the 6025 access token value in some fashion. The client instance also needs 6026 to be configured to talk to multiple AS's, including the attacker's 6027 controlled AS. Finally, the client instance needs to be able to be 6028 manipulated by the attacker to call the RS while using a token issued 6029 from the stolen AS. The RS does not need to be compromised or made 6030 to trust the attacker's AS. 6032 To protect against this attack, the client instance can use a 6033 different key for each AS that it talks to. Since the replayed token 6034 will be bound to the key used at the honest AS, the uncompromised RS 6035 will reject the call since the client instance will be using the key 6036 used at the attacker's AS instead with the same token. When the MTLS 6037 key proofing method is used, a client instance can use self-signed 6038 certificates to use a different key for each AS that it talks to, as 6039 discussed in Section 12.18. 6041 Additionally, the client instance can keep a strong association 6042 between the RS and a specific AS that it trusts to issue tokens for 6043 that RS. This strong binding also helps against some forms of AS 6044 mix-up attacks (Section 12.10). Managing this binding is outside the 6045 scope of GNAP core, but it can be managed either as a configuration 6046 element for the client instance or dynamically through discovering 6047 the AS from the RS (Section 9.1). 6049 The details of this attack are available in [HELMSCHMIDT2022] with 6050 additional discussion and considerations. 6052 12.29. Self-contained Stateless Access Tokens 6054 The contents and format of the access token are at the discretion of 6055 the AS, and are opaque to the client instance within GNAP. As 6056 discussed in the companion document, 6057 [I-D.ietf-gnap-resource-servers], the AS and RS can make use of 6058 stateless access tokens with an internal structure and format. These 6059 access tokens allow an RS to validate the token without having to 6060 make any external calls at runtime, allowing for benefits in some 6061 deployments, the discussion of which are outside the scope of this 6062 specification. 6064 However, the use of such self-contained access tokens has an effect 6065 on the ability of the AS to provide certain functionality defined 6066 within this specification. Specifically, since the access token is 6067 self-contained, it is difficult or impossible for an AS to signal to 6068 all RS's within an ecosystem when a specific access token has been 6069 revoked. Therefore, an AS in such an ecosystem should probably not 6070 offer token revocation functionality to client instances, since the 6071 client instance's calls to such an endpoint is effectively 6072 meaningless. However, a client instance calling the token revocation 6073 function will also throw out its copy of the token, so such a placebo 6074 endpoint might not be completely meaningless. Token rotation 6075 similarly difficult because the AS has to revoke the old access token 6076 after a rotation call has been made. If the access tokens are 6077 completely self-contained and non-revocable, this means that there 6078 will be a period of time during which both the old and new access 6079 tokens are valid and usable, which is an increased security risk for 6080 the environment. 6082 These problems can be mitigated by keeping the validity time windows 6083 of self-contained access tokens reasonably short, limiting the time 6084 after a revocation event that a revoked token could be used. 6085 Additionally, the AS could proactively signal to RS's under its 6086 control identifiers for revoked tokens that have yet to expire. This 6087 type of information push would be expected to be relatively small and 6088 infrequent, and its implementation is outside the scope of this 6089 specification. 6091 12.30. Network Problems and Token and Grant Management 6093 If a client instance makes a call to rotate an access token but the 6094 network connection is dropped before the client instance receives the 6095 response with the new access token, the system as a whole can end up 6096 in an inconsistent state, where the AS has already rotated the old 6097 access token and invalidated it, but the client instance only has 6098 access to the invalidated access token and not the newly rotated 6099 token value. If the client instance retries the rotation request, it 6100 would fail because the client is no longer presenting a valid and 6101 current access token. A similar situation can occur during grant 6102 continuation, where the same client instance calls to continue or 6103 update a grant request without successfully receiving the results of 6104 the update. 6106 To combat this, both grant Management (Section 5) and token 6107 management (Section 6) are designed to be idempotent, where 6108 subsequent calls to the same function with the same credentials are 6109 meant to produce the same results. For example, multiple calls to 6110 rotate the same access token need to result in the same rotated token 6111 value. 6113 In practice, an AS can hold on to an old token value for such limited 6114 purposes. For example, to support rotating access tokens over 6115 unreliable networks, the AS receives the initial request to rotate an 6116 access token and creates a new token value and returns it. The AS 6117 also marks the old token value as having been used to create the 6118 newly-rotated token value. If the AS sees the old token value within 6119 a small enough time window, such as a few seconds since the first 6120 rotation attempt, the AS can return the same rotated access token. 6121 Furthermore, once the system has seen the newly-rotated token in use, 6122 the original token can be discarded because the client instance has 6123 proved that it did receive the token. The result of this is a system 6124 that is eventually self-consistent without placing an undue 6125 complexity burden on the client instance. 6127 12.31. Server-side Request Forgery (SSRF) 6129 There are several places within GNAP where a URI can be given to a 6130 party causing it to fetch that URI during normal operation of the 6131 protocol. If an attacker is able to control the value of one of 6132 these URIs within the protocol, the attacker could cause the target 6133 system to execute a request on a URI that is within reach of the 6134 target system but normally unavailable to the attacker. For example, 6135 an attacker sending a URL of http://localhost/admin to cause the 6136 server to access an internal function on itself, or 6137 https://192.168.0.14/ to call a service behind a firewall. Even if 6138 the attacker does not gain access to the results of the call, the 6139 side effects of such requests coming from a trusted host can be 6140 problematic to the security and sanctity of such otherwise unexposed 6141 endpoints. 6143 In GNAP, the most vulnerable place in the core protocol is the 6144 push-based post-interaction finish method (Section 4.2.2), as the 6145 client instance is less trusted than the AS and can use this method 6146 to make the AS call an arbitrary URI. While it is not required by 6147 the protocol, the AS can fetch other client-instance provided URIs 6148 such as the logo image or home page, for verification or privacy- 6149 preserving purposes before displaying them to the resource owner as 6150 part of a consent screen. Furthermore, extensions to GNAP that allow 6151 or require URI fetch could also be similarly susceptible, such as a 6152 system for having the AS fetch a client instance's keys from a 6153 presented URI instead of the client instance presenting the key by 6154 value. Such extensions are outside the scope of this specification, 6155 but any system deploying such an extension would need to be aware of 6156 this issue. 6158 To help mitigate this problem, similar approaches to protecting 6159 parties against malicious redirects (Section 12.26) can be used. For 6160 example, all URIs that can result in a direct request being made by a 6161 party in the protocol can be filtered through an allowlist or 6162 blocklist. For example, an AS that supports the push based 6163 interaction finish can compare the callback URI in the interaction 6164 request to a known URI for a pre-registered client instance, or it 6165 can ensure that the URI is not on a blocklist of sensitive URLs such 6166 as internal network addresses. However, note that because these 6167 types of calls happen outside of the view of human interaction, it is 6168 not usually feasible to provide notification and warning to someone 6169 before the request needs to be executed, as is the case with 6170 redirection URLs. As such, SSRF is somewhat more difficult to manage 6171 at runtime, and systems should generally refuse to fetch a URI if 6172 unsure. 6174 13. Privacy Considerations 6176 The privacy considerations in this section are modeled after the list 6177 of privacy threats in [RFC6973], "Privacy Considerations for Internet 6178 Protocols", and either explain how these threats are mitigated or 6179 advise how the threats relate to GNAP. 6181 13.1. Surveillance 6183 Surveillance is the observation or monitoring of an individual's 6184 communications or activities. Surveillance can be conducted by 6185 observers or eavesdroppers at any point along the communications 6186 path. 6188 GNAP assumes the TLS protection used throughout the spec is intact. 6189 Without the protection of TLS, there are many points throughout the 6190 use of GNAP that would lead to possible surveillance. 6192 13.1.1. Surveillance by the Client 6194 The purpose of GNAP is to authorize clients to be able to access 6195 information on behalf of a user. So while it is expected that the 6196 client may be aware of the user's identity as well as data being 6197 fetched for that user, in some cases the extent of the client may be 6198 beyond what the user is aware of. For example, a client may be 6199 implemented as multiple distinct pieces of software, such as a 6200 logging service or a mobile app that reports usage data to an 6201 external backend service. 6203 13.1.2. Surveillance by the Authorization Server 6205 The role of the authorization server is to manage the authorization 6206 of client instances to protect access to the user's data. In this 6207 role, the authorization server is by definition aware of each 6208 authorization of a client instance by a user. When the authorization 6209 server shares user information with the client instance, it needs to 6210 make sure that it has the permission from that user to do so. 6212 Additionally, as part of the authorization grant process, the 6213 authorization server may be aware of which resource servers the 6214 client intends to use an access token at. However, it is possible to 6215 design a system using GNAP in which this knowledge is not made 6216 available to the authorization server, such as by avoiding the use of 6217 the locations object in the authorization request. 6219 If the authorization server's implementation of access tokens is such 6220 that it requires a resource server call back to the authorization 6221 server to validate them, then the authorization server will be aware 6222 of which resource servers are actively in use and by which users and 6223 which clients. To avoid this possibility, the authorization server 6224 would need to structure access tokens in such a way that they can be 6225 validated by the resource server without notifying the authorization 6226 server that the token is being validated. 6228 13.2. Stored Data 6230 Several parties in the GNAP process are expected to persist data at 6231 least temporarily, if not semi-permanently, for the normal 6232 functioning of the system. If compromised, this could lead to 6233 exposure of sensitive information. This section documents the 6234 potentially sensitive information each party in GNAP is expected to 6235 store for normal operation. Naturally it is possible that any party 6236 is storing information for longer than technically necessary of the 6237 protocol mechanics (such as audit logs, etc). 6239 The authorization server is expected to store subject identifiers for 6240 users indefinitely, in order to be able to include them in the 6241 responses to clients. The authorization server is also expected to 6242 store client key identifiers associated with display information 6243 about the client such as its name and logo. 6245 The client is expected to store its client instance key indefinitely, 6246 in order to authenticate to the authorization server for the normal 6247 functioning of the GNAP flows. Additionally, the client will be 6248 temporarily storing artifacts issued by the authorization server 6249 during a flow, and these artifacts SHOULD be discarded by the client 6250 when the transaction is complete. 6252 The resource server is not required to store any state for its normal 6253 operation. Depending on the implementation of access tokens, the 6254 resource server may need to cache public keys from the authorization 6255 server in order to validate access tokens. 6257 13.3. Intrusion 6259 Intrusion refers to the ability of various parties to send 6260 unsolicited messages or cause denial of service for unrelated 6261 parties. 6263 If the resource owner is different from the end user, there is an 6264 opportunity for the end user to cause unsolicited messages to be sent 6265 to the resource owner if the system prompts the resource owner for 6266 consent when an end user attempts to access their data. 6268 The format and contents of subject identifiers are intentionally not 6269 defined by GNAP. If the authorization server uses values for subject 6270 identifiers that are also identifiers for communication channels, 6271 (e.g. an email address or phone number), this opens up the 6272 possibility for a client to learn this information when it was not 6273 otherwise authorized to access this kind of data about the user. 6275 13.4. Correlation 6277 The threat of correlation is the combination of various pieces of 6278 information related to an individual in a way that defies their 6279 expectations of what others know about them. 6281 13.4.1. Correlation by Clients 6283 The biggest risk of correlation in GNAP is when an authorization 6284 server returns stable consistent user identifiers to multiple 6285 different applications. In this case, applications created by 6286 different parties would be able to correlate these user identifiers 6287 out of band in order to know which users they have in common. 6289 The most common example of this in practice is tracking for 6290 advertising purposes, such that client A shares their list of user 6291 IDs with an ad platform that is then able to retarget ads to 6292 applications created by other parties. In contrast, a positive 6293 example of correlation is a corporate acquisition where two 6294 previously unrelated clients now do need to be able to identify the 6295 same user between the two clients. 6297 13.4.2. Correlation by Resource Servers 6299 Unrelated resource servers also have an opportunity to correlate 6300 users if the authorization server includes stable user identifiers in 6301 access tokens or in access token introspection responses. 6303 In some cases a resource server may not actually need to be able to 6304 identify users, (such as a resource server providing access to a 6305 company cafeteria menu which only needs to validate whether the user 6306 is a current employee), so authorization servers should be thoughtful 6307 of when user identifiers are actually necessary to communicate to 6308 resource servers for the functioning of the system. 6310 However, note that the lack of inclusion of a user identifier in an 6311 access token may be a risk if there is a concern that two users may 6312 voluntarily share access tokens between them in order to access 6313 protected resources. For example, if a website wants to limit access 6314 to only people over 18, and such does not need to know any user 6315 identifiers, an access token may be issued by an AS contains only the 6316 claim "over 18". If the user is aware that this access token doesn't 6317 reference them individually, they may be willing to share the access 6318 token with a user who is under 18 in order to let them get access to 6319 the website. (Note that the binding of an access token to a non- 6320 extractable client instance key also prevents the access token from 6321 being voluntarily shared.) 6323 13.4.3. Correlation by Authorization Servers 6325 Clients are expected to be identified by their client instance key. 6326 If a particular client instance key is used at more than one 6327 authorization server, this could open up the possibility for multiple 6328 unrelated authorization servers to correlate client instances. This 6329 is especially a problem in the common case where a client instance is 6330 used by a single individual, as it would allow the authorization 6331 servers to correlate that individual between them. If this is a 6332 concern of a client, the client should use distinct keys with each 6333 authorization server. 6335 13.5. Disclosure in Shared References 6337 Throughout many parts of GNAP, the parties pass shared references 6338 between each other, sometimes in place of the values themselves. For 6339 example the interact_ref value used throughout the flow. These 6340 references are intended to be random strings and should not contain 6341 any private or sensitive data that would potentially leak information 6342 between parties. 6344 14. References 6345 14.1. Normative References 6347 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 6348 "Recommendations for Secure Use of Transport Layer 6349 Security (TLS) and Datagram Transport Layer Security 6350 (DTLS)", May 2015, 6351 . 6353 [I-D.ietf-gnap-resource-servers] 6354 Richer, J., Parecki, A., and F. Imbault, "Grant 6355 Negotiation and Authorization Protocol Resource Server 6356 Connections", Work in Progress, Internet-Draft, draft- 6357 ietf-gnap-resource-servers-01, 12 July 2021, 6358 . 6361 [I-D.ietf-httpbis-digest-headers] 6362 Polli, R. and L. Pardue, "Digest Fields", Work in 6363 Progress, Internet-Draft, draft-ietf-httpbis-digest- 6364 headers-07, 16 November 2021, 6365 . 6368 [I-D.ietf-httpbis-message-signatures] 6369 Backman, A., Richer, J., and M. Sporny, "HTTP Message 6370 Signatures", Work in Progress, Internet-Draft, draft-ietf- 6371 httpbis-message-signatures-09, 6 March 2022, 6372 . 6375 [I-D.ietf-oauth-rar] 6376 Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 6377 Rich Authorization Requests", Work in Progress, Internet- 6378 Draft, draft-ietf-oauth-rar-10, 26 January 2022, 6379 . 6382 [I-D.ietf-secevent-subject-identifiers] 6383 Backman, A. and M. Scurtescu, "Subject Identifiers for 6384 Security Event Tokens", Work in Progress, Internet-Draft, 6385 draft-ietf-secevent-subject-identifiers-09, 25 February 6386 2022, . 6389 [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 6390 C. Mortimore, "OpenID Connect Core 1.0 incorporating 6391 errata set 1", November 2014, 6392 . 6394 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 6395 Requirement Levels", BCP 14, RFC 2119, 6396 DOI 10.17487/RFC2119, March 1997, 6397 . 6399 [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, 6400 DOI 10.17487/RFC2397, August 1998, 6401 . 6403 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 6404 Resource Identifier (URI): Generic Syntax", STD 66, 6405 RFC 3986, DOI 10.17487/RFC3986, January 2005, 6406 . 6408 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 6409 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 6410 . 6412 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 6413 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 6414 September 2009, . 6416 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 6417 RFC 6749, DOI 10.17487/RFC6749, October 2012, 6418 . 6420 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 6421 Framework: Bearer Token Usage", RFC 6750, 6422 DOI 10.17487/RFC6750, October 2012, 6423 . 6425 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 6426 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 6427 DOI 10.17487/RFC7231, June 2014, 6428 . 6430 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 6431 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 6432 RFC 7234, DOI 10.17487/RFC7234, June 2014, 6433 . 6435 [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX, 6436 PKCS, and CMS Structures", RFC 7468, DOI 10.17487/RFC7468, 6437 April 2015, . 6439 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 6440 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 6441 2015, . 6443 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 6444 DOI 10.17487/RFC7517, May 2015, 6445 . 6447 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 6448 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 6449 May 2017, . 6451 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 6452 Interchange Format", STD 90, RFC 8259, 6453 DOI 10.17487/RFC8259, December 2017, 6454 . 6456 [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. 6457 Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 6458 and Certificate-Bound Access Tokens", RFC 8705, 6459 DOI 10.17487/RFC8705, February 2020, 6460 . 6462 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 6463 "Handling Long Lines in Content of Internet-Drafts and 6464 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 6465 . 6467 14.2. Informative References 6469 [AXELAND2021] 6470 Axeland, Å. and O. Oueidat, "Security Analysis of Attack 6471 Surfaces on the Grant Negotiation and Authorization 6472 Protocol", 2021, 6473 . 6475 [HELMSCHMIDT2022] 6476 Helmschmidt, F., "tbd", 2022, . 6478 [I-D.ietf-httpbis-client-cert-field] 6479 Campbell, B. and M. Bishop, "Client-Cert HTTP Header 6480 Field", Work in Progress, Internet-Draft, draft-ietf- 6481 httpbis-client-cert-field-01, 25 January 2022, 6482 . 6485 [I-D.ietf-oauth-security-topics] 6486 Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, 6487 "OAuth 2.0 Security Best Current Practice", Work in 6488 Progress, Internet-Draft, draft-ietf-oauth-security- 6489 topics-19, 16 December 2021, 6490 . 6493 [promise-theory] 6494 Burgess, M. and J. Bergstra, "Promise theory", January 6495 2014, . 6497 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 6498 Morris, J., Hansen, M., and R. Smith, "Privacy 6499 Considerations for Internet Protocols", RFC 6973, 6500 DOI 10.17487/RFC6973, July 2013, 6501 . 6503 Appendix A. Document History 6505 * -09 6507 - Added security considerations on redirection status codes. 6509 - Added security considerations on cuckoo token attack. 6511 - Made token management URL required on token rotation. 6513 - Added considerations on token rotation and self-contained 6514 tokens. 6516 - Added security considerations for SSRF. 6518 - Moved normative requirements about end user presence to 6519 security considerations. 6521 - Clarified default wait times for continuation requests 6522 (including polling). 6524 - Clarified URI vs. URL. 6526 - Added "user_code_uri" mode, removed "uri" from "user_code" 6527 mode. 6529 - Consistently formatted all parameter lists. 6531 - Updated examples for HTTP Signatures. 6533 * -08 6535 - Update definition for "Client" to account for the case of no 6536 end user. 6538 - Change definition for "Subject". 6540 - Expanded security and privacy considerations for more 6541 situations. 6543 - Added cross-links from security and privacy considerations. 6545 - Editorial updates. 6547 * -07 6549 - Replace user handle by opaque identifier 6551 - Added trust relationships 6553 - Added privacy considerations section 6555 - Added security considerations. 6557 * -06 6559 - Removed "capabilities" and "existing_grant" protocol fields. 6561 - Removed separate "instance_id" field. 6563 - Split "interaction_methods_supported" into 6564 "interaction_start_modes_supported" and 6565 "interaction_finish_methods_supported". 6567 - Added AS endpoint to hash calculation to fix mix-up attack. 6569 - Added "privileges" field to resource access request object. 6571 - Moved client-facing RS response back from GNAP-RS document. 6573 - Removed oauthpop key binding. 6575 - Removed dpop key binding. 6577 - Added example DID identifier. 6579 - Changed token response booleans to flag structure to match 6580 request. 6582 - Updated signature examples to use HTTP Message Signatures. 6584 * -05 6586 - Changed "interaction_methods" to 6587 "interaction_methods_supported". 6589 - Changed "key_proofs" to "key_proofs_supported". 6591 - Changed "assertions" to "assertions_supported". 6593 - Updated discovery and field names for subject formats. 6595 - Add an appendix to provide protocol rationale, compared to 6596 OAuth2. 6598 - Updated subject information definition. 6600 - Refactored the RS-centric components into a new document. 6602 - Updated cryptographic proof of possession methods to match 6603 current reference syntax. 6605 - Updated proofing language to use "signer" and "verifier" 6606 generically. 6608 - Updated cryptographic proof of possession examples. 6610 - Editorial cleanup and fixes. 6612 - Diagram cleanup and fixes. 6614 * -04 6616 - Updated terminology. 6618 - Refactored key presentation and binding. 6620 - Refactored "interact" request to group start and end modes. 6622 - Changed access token request and response syntax. 6624 - Changed DPoP digest field to 'htd' to match proposed FAPI 6625 profile. 6627 - Include the access token hash in the DPoP message. 6629 - Removed closed issue links. 6631 - Removed function to read state of grant request by client. 6633 - Closed issues related to reading and updating access tokens. 6635 * -03 6637 - Changed "resource client" terminology to separate "client 6638 instance" and "client software". 6640 - Removed OpenID Connect "claims" parameter. 6642 - Dropped "short URI" redirect. 6644 - Access token is mandatory for continuation. 6646 - Removed closed issue links. 6648 - Editorial fixes. 6650 * -02 6652 - Moved all "editor's note" items to GitHub Issues. 6654 - Added JSON types to fields. 6656 - Changed "GNAP Protocol" to "GNAP". 6658 - Editorial fixes. 6660 * -01 6662 - "updated_at" subject info timestamp now in ISO 8601 string 6663 format. 6665 - Editorial fixes. 6667 - Added Aaron and Fabien as document authors. 6669 * -00 6671 - Initial working group draft. 6673 Appendix B. Compared to OAuth 2.0 6675 GNAP's protocol design differs from OAuth 2.0's in several 6676 fundamental ways: 6678 1. *Consent and authorization flexibility:* 6679 OAuth 2.0 generally assumes the user has access to the a web 6680 browser. The type of interaction available is fixed by the grant 6681 type, and the most common interactive grant types start in the 6682 browser. OAuth 2.0 assumes that the user using the client 6683 software is the same user that will interact with the AS to 6684 approve access. 6686 GNAP allows various patterns to manage authorizations and 6687 consents required to fulfill this requested delegation, including 6688 information sent by the client instance, information supplied by 6689 external parties, and information gathered through the 6690 interaction process. GNAP allows a client instance to list 6691 different ways that it can start and finish an interaction, and 6692 these can be mixed together as needed for different use cases. 6693 GNAP interactions can use a browser, but don't have to. Methods 6694 can use inter-application messaging protocols, out-of-band data 6695 transfer, or anything else. GNAP allows extensions to define new 6696 ways to start and finish an interaction, as new methods and 6697 platforms are expected to become available over time. GNAP is 6698 designed to allow the end user and the resource owner to be two 6699 different people, but still works in the optimized case of them 6700 being the same party. 6702 2. *Intent registration and inline negotiation:* 6704 OAuth 2.0 uses different "grant types" that start at different 6705 endpoints for different purposes. Many of these require 6706 discovery of several interrelated parameters. 6708 GNAP requests all start with the same type of request to the same 6709 endpoint at the AS. Next steps are negotiated between the client 6710 instance and AS based on software capabilities, policies 6711 surrounding requested access, and the overall context of the 6712 ongoing request. GNAP defines a continuation API that allows the 6713 client instance and AS to request and send additional information 6714 from each other over multiple steps. This continuation API uses 6715 the same access token protection that other GNAP-protected APIs 6716 use. GNAP allows discovery to optimize the requests but it isn't 6717 required thanks to the negotiation capabilities. 6719 3. *Client instances:* 6720 OAuth 2.0 requires all clients to be registered at the AS and to 6721 use a client_id known to the AS as part of the protocol. This 6722 client_id is generally assumed to be assigned by a trusted 6723 authority during a registration process, and OAuth places a lot 6724 of trust on the client_id as a result. Dynamic registration 6725 allows different classes of clients to get a client_id at 6726 runtime, even if they only ever use it for one request. 6728 GNAP allows the client instance to present an unknown key to the 6729 AS and use that key to protect the ongoing request. GNAP's 6730 client instance identifier mechanism allows for pre-registered 6731 clients and dynamically registered clients to exist as an 6732 optimized case without requiring the identifier as part of the 6733 protocol at all times. 6735 4. *Expanded delegation:* 6737 OAuth 2.0 defines the "scope" parameter for controlling access to 6738 APIs. This parameter has been coopted to mean a number of 6739 different things in different protocols, including flags for 6740 turning special behavior on and off, including the return of data 6741 apart from the access token. The "resource" parameter and RAR 6742 extensions (as defined in [I-D.ietf-oauth-rar]) expand on the 6743 "scope" concept in similar but different ways. 6745 GNAP defines a rich structure for requesting access, with string 6746 references as an optimization. GNAP defines methods for 6747 requesting directly-returned user information, separate from API 6748 access. This information includes identifiers for the current 6749 user and structured assertions. The core GNAP protocol makes no 6750 assumptions or demands on the format or contents of the access 6751 token, but the RS extension allows a negotiation of token formats 6752 between the AS and RS. 6754 5. *Cryptography-based security:* 6756 OAuth 2.0 uses shared bearer secrets, including the client_secret 6757 and access token, and advanced authentication and sender 6758 constraint have been built on after the fact in inconsistent 6759 ways. 6761 In GNAP, all communication between the client instance and AS is 6762 bound to a key held by the client instance. GNAP uses the same 6763 cryptographic mechanisms for both authenticating the client (to 6764 the AS) and binding the access token (to the RS and the AS). 6765 GNAP allows extensions to define new cryptographic protection 6766 mechanisms, as new methods are expected to become available over 6767 time. GNAP does not have a notion of "public clients" because 6768 key information can always be sent and used dynamically. 6770 6. *Privacy and usable security:* 6772 OAuth 2.0's deployment model assumes a strong binding between the 6773 AS and the RS. 6775 GNAP is designed to be interoperable with decentralized identity 6776 standards and to provide a human-centric authorization layer. In 6777 addition to the core protocol, GNAP supports various patterns of 6778 communication between RSs and ASs through extensions. GNAP tries 6779 to limit the odds of a consolidation to just a handful of super- 6780 popular AS services. 6782 Appendix C. Component Data Models 6784 While different implementations of this protocol will have different 6785 realizations of all the components and artifacts enumerated here, the 6786 nature of the protocol implies some common structures and elements 6787 for certain components. This appendix seeks to enumerate those 6788 common elements. 6790 TBD: Client has keys, allowed requested resources, identifier(s), 6791 allowed requested subjects, allowed 6793 TBD: AS has "grant endpoint", interaction endpoints, store of trusted 6794 client keys, policies 6796 TBD: Token has RO, user, client, resource list, RS list, 6798 Appendix D. Example Protocol Flows 6800 The protocol defined in this specification provides a number of 6801 features that can be combined to solve many different kinds of 6802 authentication scenarios. This section seeks to show examples of how 6803 the protocol would be applied for different situations. 6805 Some longer fields, particularly cryptographic information, have been 6806 truncated for display purposes in these examples. 6808 D.1. Redirect-Based User Interaction 6810 In this scenario, the user is the RO and has access to a web browser, 6811 and the client instance can take front-channel callbacks on the same 6812 device as the user. This combination is analogous to the OAuth 2.0 6813 Authorization Code grant type. 6815 The client instance initiates the request to the AS. Here the client 6816 instance identifies itself using its public key. 6818 POST /tx HTTP/1.1 6819 Host: server.example.com 6820 Content-Type: application/json 6821 Signature-Input: sig1=... 6822 Signature: sig1=... 6823 Content-Digest: sha-256=... 6825 { 6826 "access_token": { 6827 "access": [ 6828 { 6829 "actions": [ 6830 "read", 6831 "write", 6832 "dolphin" 6833 ], 6834 "locations": [ 6835 "https://server.example.net/", 6836 "https://resource.local/other" 6837 ], 6838 "datatypes": [ 6839 "metadata", 6840 "images" 6841 ] 6842 } 6843 ], 6844 }, 6845 "client": { 6846 "key": { 6847 "proof": "httpsig", 6848 "jwk": { 6849 "kty": "RSA", 6850 "e": "AQAB", 6851 "kid": "xyz-1", 6852 "alg": "RS256", 6853 "n": "kOB5rR4Jv0GMeLaY6_It_r3ORwdf8ci_JtffXyaSx8..." 6854 } 6855 } 6857 }, 6858 "interact": { 6859 "start": ["redirect"], 6860 "finish": { 6861 "method": "redirect", 6862 "uri": "https://client.example.net/return/123455", 6863 "nonce": "LKLTI25DK82FX4T4QFZC" 6864 } 6865 } 6866 } 6868 The AS processes the request and determines that the RO needs to 6869 interact. The AS returns the following response giving the client 6870 instance the information it needs to connect. The AS has also 6871 indicated to the client instance that it can use the given instance 6872 identifier to identify itself in future requests (Section 2.3.1). 6874 HTTP/1.1 200 OK 6875 Content-Type: application/json 6876 Cache-Control: no-store 6878 { 6879 "interact": { 6880 "redirect": 6881 "https://server.example.com/interact/4CF492MLVMSW9MKM", 6882 "finish": "MBDOFXG4Y5CVJCX821LH" 6883 } 6884 "continue": { 6885 "access_token": { 6886 "value": "80UPRY5NM33OMUKMKSKU" 6887 }, 6888 "uri": "https://server.example.com/continue" 6889 }, 6890 "instance_id": "7C7C4AZ9KHRS6X63AJAO" 6891 } 6893 The client instance saves the response and redirects the user to the 6894 interaction_url by sending the following HTTP message to the user's 6895 browser. 6897 HTTP 302 Found 6898 Location: https://server.example.com/interact/4CF492MLVMSW9MKM 6899 The user's browser fetches the AS's interaction URI. The user logs 6900 in, is identified as the RO for the resource being requested, and 6901 approves the request. Since the AS has a callback parameter, the AS 6902 generates the interaction reference, calculates the hash, and 6903 redirects the user back to the client instance with these additional 6904 values added as query parameters. 6906 NOTE: '\' line wrapping per RFC 8792 6908 HTTP 302 Found 6909 Location: https://client.example.net/return/123455\ 6910 ?hash=p28jsq0Y2KK3WS__a42tavNC64ldGTBroywsWxT4md_jZQ1R2\ 6911 HZT8BOWYHcLmObM7XHPAdJzTZMtKBsaraJ64A\ 6912 &interact_ref=4IFWWIKYBC2PQ6U56NL1 6914 The client instance receives this request from the user's browser. 6915 The client instance ensures that this is the same user that was sent 6916 out by validating session information and retrieves the stored 6917 pending request. The client instance uses the values in this to 6918 validate the hash parameter. The client instance then calls the 6919 continuation URI and presents the handle and interaction reference in 6920 the request body. The client instance signs the request as above. 6922 POST /continue HTTP/1.1 6923 Host: server.example.com 6924 Content-Type: application/json 6925 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 6926 Signature-Input: sig1=... 6927 Signature: sig1=... 6928 Content-Digest: sha-256=... 6930 { 6931 "interact_ref": "4IFWWIKYBC2PQ6U56NL1" 6932 } 6934 The AS retrieves the pending request based on the handle and issues 6935 an access token and returns this to the client instance. 6937 NOTE: '\' line wrapping per RFC 8792 6939 HTTP/1.1 200 OK 6940 Content-Type: application/json 6941 Cache-Control: no-store 6943 { 6944 "access_token": { 6945 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 6946 "manage": "https://server.example.com/token/PRY5NM33O\ 6947 M4TB8N6BW7OZB8CDFONP219RP1L", 6948 "access": [{ 6949 "actions": [ 6950 "read", 6951 "write", 6952 "dolphin" 6953 ], 6954 "locations": [ 6955 "https://server.example.net/", 6956 "https://resource.local/other" 6957 ], 6958 "datatypes": [ 6959 "metadata", 6960 "images" 6961 ] 6962 }] 6963 }, 6964 "continue": { 6965 "access_token": { 6966 "value": "80UPRY5NM33OMUKMKSKU" 6967 }, 6968 "uri": "https://server.example.com/continue" 6969 } 6970 } 6972 D.2. Secondary Device Interaction 6974 In this scenario, the user does not have access to a web browser on 6975 the device and must use a secondary device to interact with the AS. 6976 The client instance can display a user code or a printable QR code. 6977 The client instance is not able to accept callbacks from the AS and 6978 needs to poll for updates while waiting for the user to authorize the 6979 request. 6981 The client instance initiates the request to the AS. 6983 POST /tx HTTP/1.1 6984 Host: server.example.com 6985 Content-Type: application/json 6986 Signature-Input: sig1=... 6987 Signature: sig1=... 6988 Content-Digest: sha-256=... 6990 { 6991 "access_token": { 6992 "access": [ 6993 "dolphin-metadata", "some other thing" 6994 ], 6995 }, 6996 "client": "7C7C4AZ9KHRS6X63AJAO", 6997 "interact": { 6998 "start": ["redirect", "user_code"] 6999 } 7000 } 7002 The AS processes this and determines that the RO needs to interact. 7003 The AS supports both redirect URIs and user codes for interaction, so 7004 it includes both. Since there is no interaction finish mode, the AS 7005 does not include a nonce, but does include a "wait" parameter on the 7006 continuation section because it expects the client instance to poll 7007 for results. 7009 HTTP/1.1 200 OK 7010 Content-Type: application/json 7011 Cache-Control: no-store 7013 { 7014 "interact": { 7015 "redirect": "https://srv.ex/MXKHQ", 7016 "user_code": { 7017 "code": "A1BC-3DFF" 7018 } 7019 }, 7020 "continue": { 7021 "access_token": { 7022 "value": "80UPRY5NM33OMUKMKSKU" 7023 }, 7024 "uri": "https://server.example.com/continue/VGJKPTKC50", 7025 "wait": 60 7026 } 7027 } 7028 The client instance saves the response and displays the user code 7029 visually on its screen along with the static device URI. The client 7030 instance also displays the short interaction URI as a QR code to be 7031 scanned. 7033 If the user scans the code, they are taken to the interaction 7034 endpoint and the AS looks up the current pending request based on the 7035 incoming URI. If the user instead goes to the static page and enters 7036 the code manually, the AS looks up the current pending request based 7037 on the value of the user code. In both cases, the user logs in, is 7038 identified as the RO for the resource being requested, and approves 7039 the request. Once the request has been approved, the AS displays to 7040 the user a message to return to their device. 7042 Meanwhile, the client instance periodically polls the AS every 60 7043 seconds at the continuation URI. The client instance signs the 7044 request using the same key and method that it did in the first 7045 request. 7047 POST /continue/VGJKPTKC50 HTTP/1.1 7048 Host: server.example.com 7049 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 7050 Signature-Input: sig1=... 7051 Signature: sig1=... 7052 Content-Digest: sha-256=... 7054 The AS retrieves the pending request based on the handle and 7055 determines that it has not yet been authorized. The AS indicates to 7056 the client instance that no access token has yet been issued but it 7057 can continue to call after another 60 second timeout. 7059 HTTP/1.1 200 OK 7060 Content-Type: application/json 7061 Cache-Control: no-store 7063 { 7064 "continue": { 7065 "access_token": { 7066 "value": "G7YQT4KQQ5TZY9SLSS5E" 7067 }, 7068 "uri": "https://server.example.com/continue/ATWHO4Q1WV", 7069 "wait": 60 7070 } 7071 } 7072 Note that the continuation URI and access token have been rotated 7073 since they were used by the client instance to make this call. The 7074 client instance polls the continuation URI after a 60 second timeout 7075 using this new information. 7077 POST /continue/ATWHO4Q1WV HTTP/1.1 7078 Host: server.example.com 7079 Authorization: GNAP G7YQT4KQQ5TZY9SLSS5E 7080 Signature-Input: sig1=... 7081 Signature: sig1=... 7082 Content-Digest: sha-256=... 7084 The AS retrieves the pending request based on the URI and access 7085 token, determines that it has been approved, and issues an access 7086 token for the client to use at the RS. 7088 NOTE: '\' line wrapping per RFC 8792 7090 HTTP/1.1 200 OK 7091 Content-Type: application/json 7092 Cache-Control: no-store 7094 { 7095 "access_token": { 7096 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 7097 "manage": "https://server.example.com/token/PRY5NM33O\ 7098 M4TB8N6BW7OZB8CDFONP219RP1L", 7099 "access": [ 7100 "dolphin-metadata", "some other thing" 7101 ] 7102 } 7103 } 7105 D.3. No User Involvement 7107 In this scenario, the client instance is requesting access on its own 7108 behalf, with no user to interact with. 7110 The client instance creates a request to the AS, identifying itself 7111 with its public key and using MTLS to make the request. 7113 POST /tx HTTP/1.1 7114 Host: server.example.com 7115 Content-Type: application/json 7117 { 7118 "access_token": { 7119 "access": [ 7120 "backend service", "nightly-routine-3" 7121 ], 7122 }, 7123 "client": { 7124 "key": { 7125 "proof": "mtls", 7126 "cert#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 7127 } 7128 } 7129 } 7131 The AS processes this and determines that the client instance can ask 7132 for the requested resources and issues an access token. 7134 HTTP/1.1 200 OK 7135 Content-Type: application/json 7136 Cache-Control: no-store 7138 { 7139 "access_token": { 7140 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 7141 "manage": "https://server.example.com/token", 7142 "access": [ 7143 "backend service", "nightly-routine-3" 7144 ] 7145 } 7146 } 7148 D.4. Asynchronous Authorization 7150 In this scenario, the client instance is requesting on behalf of a 7151 specific RO, but has no way to interact with the user. The AS can 7152 asynchronously reach out to the RO for approval in this scenario. 7154 The client instance starts the request at the AS by requesting a set 7155 of resources. The client instance also identifies a particular user. 7157 POST /tx HTTP/1.1 7158 Host: server.example.com 7159 Content-Type: application/json 7160 Signature-Input: sig1=... 7161 Signature: sig1=... 7162 Content-Digest: sha-256=... 7164 { 7165 "access_token": { 7166 "access": [ 7167 { 7168 "type": "photo-api", 7169 "actions": [ 7170 "read", 7171 "write", 7172 "dolphin" 7173 ], 7174 "locations": [ 7175 "https://server.example.net/", 7176 "https://resource.local/other" 7177 ], 7178 "datatypes": [ 7179 "metadata", 7180 "images" 7181 ] 7182 }, 7183 "read", "dolphin-metadata", 7184 { 7185 "type": "financial-transaction", 7186 "actions": [ 7187 "withdraw" 7188 ], 7189 "identifier": "account-14-32-32-3", 7190 "currency": "USD" 7191 }, 7192 "some other thing" 7193 ], 7194 }, 7195 "client": "7C7C4AZ9KHRS6X63AJAO", 7196 "user": { 7197 "sub_ids": [ { 7198 "format": "opaque", 7199 "id": "J2G8G8O4AZ" 7200 } ] 7201 } 7202 } 7203 The AS processes this and determines that the RO needs to interact. 7204 The AS determines that it can reach the identified user 7205 asynchronously and that the identified user does have the ability to 7206 approve this request. The AS indicates to the client instance that 7207 it can poll for continuation. 7209 HTTP/1.1 200 OK 7210 Content-Type: application/json 7211 Cache-Control: no-store 7213 { 7214 "continue": { 7215 "access_token": { 7216 "value": "80UPRY5NM33OMUKMKSKU" 7217 }, 7218 "uri": "https://server.example.com/continue", 7219 "wait": 60 7220 } 7221 } 7223 The AS reaches out to the RO and prompts them for consent. In this 7224 example, the AS has an application that it can push notifications in 7225 to for the specified account. 7227 Meanwhile, the client instance periodically polls the AS every 60 7228 seconds at the continuation URI. 7230 POST /continue HTTP/1.1 7231 Host: server.example.com 7232 Authorization: GNAP 80UPRY5NM33OMUKMKSKU 7233 Signature-Input: sig1=... 7234 Signature: sig1=... 7236 The AS retrieves the pending request based on the handle and 7237 determines that it has not yet been authorized. The AS indicates to 7238 the client instance that no access token has yet been issued but it 7239 can continue to call after another 60 second timeout. 7241 HTTP/1.1 200 OK 7242 Content-Type: application/json 7243 Cache-Control: no-store 7245 { 7246 "continue": { 7247 "access_token": { 7248 "value": "BI9QNW6V9W3XFJK4R02D" 7249 }, 7250 "uri": "https://server.example.com/continue", 7251 "wait": 60 7252 } 7253 } 7255 Note that the continuation handle has been rotated since it was used 7256 by the client instance to make this call. The client instance polls 7257 the continuation URI after a 60 second timeout using the new handle. 7259 POST /continue HTTP/1.1 7260 Host: server.example.com 7261 Authorization: GNAP BI9QNW6V9W3XFJK4R02D 7262 Signature-Input: sig1=... 7263 Signature: sig1=... 7265 The AS retrieves the pending request based on the handle and 7266 determines that it has been approved and it issues an access token. 7268 NOTE: '\' line wrapping per RFC 8792 7270 HTTP/1.1 200 OK 7271 Content-Type: application/json 7272 Cache-Control: no-store 7274 { 7275 "access_token": { 7276 "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0", 7277 "manage": "https://server.example.com/token/PRY5NM33O\ 7278 M4TB8N6BW7OZB8CDFONP219RP1L", 7279 "access": [ 7280 "dolphin-metadata", "some other thing" 7281 ] 7282 } 7283 } 7285 D.5. Applying OAuth 2.0 Scopes and Client IDs 7287 While GNAP is not designed to be directly compatible with OAuth 2.0 7288 [RFC6749], considerations have been made to enable the use of OAuth 7289 2.0 concepts and constructs more smoothly within GNAP. 7291 In this scenario, the client developer has a client_id and set of 7292 scope values from their OAuth 2.0 system and wants to apply them to 7293 the new protocol. Traditionally, the OAuth 2.0 client developer 7294 would put their client_id and scope values as parameters into a 7295 redirect request to the authorization endpoint. 7297 NOTE: '\' line wrapping per RFC 8792 7299 HTTP 302 Found 7300 Location: https://server.example.com/authorize\ 7301 ?client_id=7C7C4AZ9KHRS6X63AJAO\ 7302 &scope=read%20write%20dolphin\ 7303 &redirect_uri=https://client.example.net/return\ 7304 &response_type=code\ 7305 &state=123455 7307 Now the developer wants to make an analogous request to the AS using 7308 GNAP. To do so, the client instance makes an HTTP POST and places 7309 the OAuth 2.0 values in the appropriate places. 7311 POST /tx HTTP/1.1 7312 Host: server.example.com 7313 Content-Type: application/json 7314 Signature-Input: sig1=... 7315 Signature: sig1=... 7316 Content-Digest: sha-256=... 7318 { 7319 "access_token": { 7320 "access": [ 7321 "read", "write", "dolphin" 7322 ], 7323 "flags": [ "bearer" ] 7324 }, 7325 "client": "7C7C4AZ9KHRS6X63AJAO", 7326 "interact": { 7327 "start": ["redirect"], 7328 "finish": { 7329 "method": "redirect", 7330 "uri": "https://client.example.net/return?state=123455", 7331 "nonce": "LKLTI25DK82FX4T4QFZC" 7332 } 7333 } 7334 } 7336 The client_id can be used to identify the client instance's keys that 7337 it uses for authentication, the scopes represent resources that the 7338 client instance is requesting, and the redirect_uri and state value 7339 are pre-combined into a finish URI that can be unique per request. 7340 The client instance additionally creates a nonce to protect the 7341 callback, separate from the state parameter that it has added to its 7342 return URI. 7344 From here, the protocol continues as above. 7346 Appendix E. JSON Structures and Polymorphism 7348 GNAP makes use of polymorphism within the JSON [RFC8259] structures 7349 used for the protocol. Each portion of this protocol is defined in 7350 terms of the JSON data type that its values can take, whether it's a 7351 string, object, array, boolean, or number. For some fields, 7352 different data types offer different descriptive capabilities and are 7353 used in different situations for the same field. Each data type 7354 provides a different syntax to express the same underlying semantic 7355 protocol element, which allows for optimization and simplification in 7356 many common cases. 7358 Even though JSON is often used to describe strongly typed structures, 7359 JSON on its own is naturally polymorphic. In JSON, the named members 7360 of an object have no type associated with them, and any data type can 7361 be used as the value for any member. In practice, each member has a 7362 semantic type that needs to make sense to the parties creating and 7363 consuming the object. Within this protocol, each object member is 7364 defined in terms of its semantic content, and this semantic content 7365 might have expressions in different concrete data types for different 7366 specific purposes. Since each object member has exactly one value in 7367 JSON, each data type for an object member field is naturally mutually 7368 exclusive with other data types within a single JSON object. 7370 For example, a resource request for a single access token is composed 7371 of an array of resource request descriptions while a request for 7372 multiple access tokens is composed of an object whose member values 7373 are all arrays. Both of these represent requests for access, but the 7374 difference in syntax allows the client instance and AS to 7375 differentiate between the two request types in the same request. 7377 Another form of polymorphism in JSON comes from the fact that the 7378 values within JSON arrays need not all be of the same JSON data type. 7379 However, within this protocol, each element within the array needs to 7380 be of the same kind of semantic element for the collection to make 7381 sense, even when the data types are different from each other. 7383 For example, each aspect of a resource request can be described using 7384 an object with multiple dimensional components, or the aspect can be 7385 requested using a string. In both cases, the resource request is 7386 being described in a way that the AS needs to interpret, but with 7387 different levels of specificity and complexity for the client 7388 instance to deal with. An API designer can provide a set of common 7389 access scopes as simple strings but still allow client software 7390 developers to specify custom access when needed for more complex 7391 APIs. 7393 Extensions to this specification can use different data types for 7394 defined fields, but each extension needs to not only declare what the 7395 data type means, but also provide justification for the data type 7396 representing the same basic kind of thing it extends. For example, 7397 an extension declaring an "array" representation for a field would 7398 need to explain how the array represents something akin to the non- 7399 array element that it is replacing. 7401 Authors' Addresses 7403 Justin Richer (editor) 7404 Bespoke Engineering 7405 Email: ietf@justin.richer.org 7406 URI: https://bspk.io/ 7408 Aaron Parecki 7409 Okta 7410 Email: aaron@parecki.com 7411 URI: https://aaronparecki.com 7413 Fabien Imbault 7414 acert.io 7415 Email: fabien.imbault@acert.io 7416 URI: https://acert.io/