idnits 2.17.00 (12 Aug 2021) /tmp/idnits22022/draft-hardt-xauth-protocol-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 14 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *completion_uri* a unique URI at the GC that the GS will return the User to. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. This attribute is REQUIRED. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *redirect_uri* a unique URI at the GS that the GC will redirect the User to. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. This attribute is REQUIRED. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *indirect_uri* the URI the GC will cause to load in the User's browser. The URI SHOULD be short enough to be easily encoded in a scannable code. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. _[Editor: recommend a maximum length?]_ -- The document date (15 August 2020) is 637 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) ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' -- Possible downref: Non-RFC (?) normative reference: ref. 'RAR' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 15 August 2020 5 Expires: 16 February 2021 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-14 10 Abstract 12 Client software often desires resources or identity claims that are 13 independent of the client. This protocol allows a user and/or 14 resource owner to delegate resource authorization and/or release of 15 identity claims to a server. Client software can then request access 16 to resources and/or identity claims by calling the server. The 17 server acquires consent and authorization from the user and/or 18 resource owner if required, and then returns to the client software 19 the authorization and identity claims that were approved. This 20 protocol may be extended on many dimensions. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 16 February 2021. 39 Copyright Notice 41 Copyright (c) 2020 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 50 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 52 extracted from this document must include Simplified BSD License text 53 as described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. The Grant . . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.2. Protocol Roles . . . . . . . . . . . . . . . . . . . . . 4 61 1.3. Human Interactions . . . . . . . . . . . . . . . . . . . 5 62 1.4. Trust Model . . . . . . . . . . . . . . . . . . . . . . . 7 63 1.5. Terminology . . . . . . . . . . . . . . . . . . . . . . . 8 64 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 10 65 2. Exemplar Sequences . . . . . . . . . . . . . . . . . . . . . 11 66 2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 11 67 2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 13 68 2.3. Independent RO Authorization . . . . . . . . . . . . . . 14 69 2.4. Resource Server Access . . . . . . . . . . . . . . . . . 15 70 3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 71 3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 16 72 3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 16 73 3.3. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 19 74 3.4. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 20 75 3.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 20 76 3.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 20 77 3.5.2. "interaction" Object . . . . . . . . . . . . . . . . 21 78 3.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 21 79 3.5.4. "access" Object . . . . . . . . . . . . . . . . . . . 22 80 3.5.5. "claims" Object . . . . . . . . . . . . . . . . . . . 22 81 3.6. Read Access . . . . . . . . . . . . . . . . . . . . . . . 22 82 3.7. GS Options . . . . . . . . . . . . . . . . . . . . . . . 23 83 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 23 84 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 23 85 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 25 86 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 26 87 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 26 88 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 27 89 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 27 90 4.4.3. "access" Object . . . . . . . . . . . . . . . . . . . 27 91 4.4.4. Access Response Object . . . . . . . . . . . . . . . 27 92 4.4.5. "claims" Object . . . . . . . . . . . . . . . . . . . 28 93 4.4.6. "warnings" JSON Array . . . . . . . . . . . . . . . . 28 94 4.5. Access JSON . . . . . . . . . . . . . . . . . . . . . . . 28 95 4.6. Response Verification . . . . . . . . . . . . . . . . . . 29 96 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 29 97 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 29 98 5.1.1. "redirect" verification . . . . . . . . . . . . . . . 30 99 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 30 101 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 103 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 30 104 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 31 105 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 31 106 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 31 107 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 31 108 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 33 109 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 35 110 12. Security Considerations . . . . . . . . . . . . . . . . . . . 35 111 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 35 112 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 113 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 114 15.1. Normative References . . . . . . . . . . . . . . . . . . 35 115 15.2. Informative References . . . . . . . . . . . . . . . . . 37 116 Appendix A. Document History . . . . . . . . . . . . . . . . . . 38 117 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 38 118 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 38 119 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 38 120 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 38 121 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 39 122 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 39 123 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 39 124 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 39 125 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 39 126 A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 40 127 A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 40 128 A.12. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 40 129 A.13. draft-hardt-xauth-protocol-12 . . . . . . . . . . . . . . 40 130 A.14. draft-hardt-xauth-protocol-13 . . . . . . . . . . . . . . 40 131 A.15. draft-hardt-xauth-protocol-14 . . . . . . . . . . . . . . 41 132 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 41 133 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42 135 1. Introduction 137 *EDITOR NOTE* 139 _This document captures a number of concepts that may be adopted by 140 the proposed GNAP working group. Please refer to this document as:_ 142 *XAuth* 144 _The use of GNAP in this document is not intended to be a declaration 145 of it being endorsed by the GNAP working group._ 147 This document describes the core Grant Negotiation and Authorization 148 Protocol (GNAP). The protocol supports the widely deployed use cases 149 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 150 an extension of OAuth 2.0, as well as other extensions. Related 152 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 154 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 155 Authentication [JOSE_Authentication] that describes the JOSE 156 mechanisms for client authentication. 158 The technology landscape has changed since OAuth 2.0 was initially 159 drafted. More interactions happen on mobile devices than PCs. 160 Modern browsers now directly support asymetric cryptographic 161 functions. Standards have emerged for signing and encrypting tokens 162 with rich payloads (JOSE) that are widely deployed. 164 GNAP simplifies the overall architectural model, takes advantage of 165 today's technology landscape, provides support for all the widely 166 deployed use cases, offers numerous extension points, and addresses 167 many of the security issues in OAuth 2.0 by passing parameters 168 securely between parties rather than via a browser redirection. 170 While GNAP is not backwards compatible with OAuth 2.0, it strives to 171 minimize the migration effort. 173 The suggested pronunciation of GNAP is "guh-nap". 175 1.1. The Grant 177 The Grant is at the center of the protocol between a client and a 178 server. A Grant Client requests a Grant from a Grant Server. The 179 Grant Client and Grant Server negotiate the Grant. The Grant Server 180 acquires authorization to grant the Grant to the Grant Client. The 181 Grant Server then returns the Grant to the Grant Client. 183 The Grant Request may contain information about the User, the Grant 184 Client, the interaction modes supported by the Grant Client, the 185 requested identity claims, and the requested resource access. 186 Extensions may define additional information to be included in the 187 Grant Request. 189 1.2. Protocol Roles 191 There are three roles in GNAP: the Grant Client (GC), the Grant 192 Server (GS), and the Resource Server (RS). Below is how the roles 193 interact: 195 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 197 +--------+ +------------+ 198 | Grant | - - - - - - -(1)- - - - - - ->| Resource | 199 | Client | | Server | 200 | (GC) | +---------------+ | (RS) | 201 | |--(2)->| Grant | | | 202 | |<-(3)->| Server |- (6) -| | 203 | |<-(4)--| (GS) | | | 204 | | +---------------+ | | 205 | | | | 206 | |--------------(5)------------->| | 207 +--------+ +------------+ 209 (1) The GC may query the RS to determine what the RS requires from a 210 GS for resource access. This step is not in scope for this document. 212 (2) The GC makes a Grant request to the GS (Create Grant 213 Section 3.2). How the GC authenticates to the GS is not in scope for 214 this document. One mechanism is [JOSE_Authentication]. 216 (3) The GC and GS may negotiate the Grant. 218 (4) The GS returns a Grant to the GC (Grant Response Section 4.1). 220 (5) The GC accesses resources at the RS (RS Access Section 6). 222 (6) The RS evaluates access granted by the GS to determine access 223 granted to the GC. This step is not in scope for this document. 225 1.3. Human Interactions 227 The Grant Client may be interacting with a human end-user (User), and 228 the Grant Client may need to get authorization to release the Grant 229 from the User, or from the owner of the resources at the Resource 230 Server, the Resource Owner (RO) 232 Below is when the human interactions may occur in the protocol: 234 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 236 +--------+ +------------+ 237 | User | | Resource | 238 | | | Owner (RO) | 239 +--------+ +------------+ 240 + + + 241 + + + 242 (A) (B) (C) 243 + + + 244 + + + 245 +--------+ + + +------------+ 246 | Grant | - - -+- - - -(1)- - - -+- - ->| Resource | 247 | Client | + + | Server | 248 | (GC) | +---------------+ | (RS) | 249 | |--(2)->| Grant | | | 250 | |<-(3)->| Server |- (6) -| | 251 | |<-(4)--| (GS) | | | 252 | | +---------------+ | | 253 | | | | 254 | |--------------(5)------------->| | 255 +--------+ +------------+ 257 Legend 258 + + + indicates an interaction with a human 259 ----- indicates an interaction between protocol roles 261 Steps (1) - (6) are the same as Section 1.2. The addition of the 262 human interactions (A) - (C) are *bolded* below. 264 *(A) The User is interacting with a GC, and the GC needs resource 265 access and/or identity claims (a Grant)* 267 (1) The GC may query the RS to determine what the RS requires from a 268 GS for resource access 270 (2) The GC makes a Grant request to the GS 272 (3) The GC and GS may negotiate the Grant 274 *(B) The GS may interact with the User for grant authorization* 276 *(C) The GS may interact with the RO for grant authorization* 278 (4) The GS returns a Grant to the GC 280 (5) The GC accesses resources at the RS 282 (6) The RS evaluates access granted by the GS to determine access 283 granted to the GC 285 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 287 Alternatively, the Resource Owner could be a legal entity that has a 288 software component that the Grant Server interacts with for Grant 289 authorization. This interaction is not in scope of this document. 291 1.4. Trust Model 293 In addition to the User and the Resource Owner, there are three other 294 entities that are part of the trust model: 296 * *Client Owner* (CO) - the legal entity that owns the Grant Client. 298 * *Grant Server Owner* (GSO) - the legal entity that owns the Grant 299 Server. 301 * *Claims Issuer* (Issuer) - a legal entity that issues identity 302 claims about the User. The Grant Server Owner may be an Issuer, 303 and the Resource Owner may be an Issuer. 305 These three entities do not interact in the protocol, but are trusted 306 by the User and the Resource Owner: 308 +------------+ +--------------+----------+ 309 | User | >> (A) >> | Grant Server | | 310 | | | Owner (GSO) | | 311 +------------+ > +--------------+ | 312 V / ^ | Claims | 313 (B) (C) (E) | Issuer | 314 V / ^ | (Issuer) | 315 +------------+ > +--------------+ | 316 | Client | | Resource | | 317 | Owner (CO) | >> (D) >> | Owner (RO) | | 318 +------------+ +--------------+----------+ 320 (A) User trusts the GSO to acquire authorization before making a 321 grant to the CO 323 (B) User trusts the CO to act in the User's best interest with the 324 Grant the GSO grants to the CO 326 (C) CO trusts claims issued by the GSO 328 (D) CO trusts claims issued by the RO 330 (E) RO trusts the GSO to manage access to the RO resources 332 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 334 1.5. Terminology 336 *Roles* 338 * *Grant Client* (GC) 340 - may want access to resources at a Resource Server 342 - may be interacting with a User and want identity claims about 343 the User 345 - requests the Grant Service to grant resource access and 346 identity claims 348 * *Grant Server* (GS) 350 - accepts Grant requests from the GC for resource access and 351 identity claims 353 - negotiates the interaction mode with the GC if interaction is 354 required with the User 356 - acquires authorization from the User before granting identity 357 claims to the GC 359 - acquires authorization from the RO before granting resource 360 access to the GC 362 - grants resource access and identity claims to the GC 364 * *Resource Server* (RS) 366 - has resources that the GC may want to access 368 - expresses what the GC must obtain from the GS for access 369 through documentation or an API. This is not in scope for this 370 document 372 - verifies the GS granted access to the GC, when the GS makes 373 resource access requests 375 *Humans* 377 * *User* 379 - the person interacting with the Grant Client. 381 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 383 - has delegated access to identity claims about themselves to the 384 Grant Server. 386 - may authenticate at the GS. 388 * *Resource Owner* (RO) 390 - the legal entity that owns resources at the Resource Server 391 (RS). 393 - has delegated resource access management to the GS. 395 - may be the User, or may be a different entity that the GS 396 interacts with independently. 398 *Reused Terms* 400 * *access token* - an access token as defined in [RFC6749] 401 Section 1.4. An GC uses an access token for resource access at a 402 RS. 404 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims are 405 issued by a Claims Issuer. 407 * *Client ID* - a GS unique identifier for a Registered Client as 408 defined in [RFC6749] Section 2.2. 410 * *ID Token* - an ID Token as defined in [OIDC] Section 2. ID 411 Tokens are issued by the GS. The GC uses an ID Token to 412 authenticate the User. 414 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 416 * *authN* - short for authentication. 418 * *authZ* - short for authorization. 420 *New Terms* 422 * *GS URI* - the endpoint at the GS the GC calls to create a Grant, 423 and is the unique identifier for the GS. 425 * *Registered Client* - a GC that has registered with the GS and has 426 a Client ID to identify itself, and can prove it possesses a key 427 that is linked to the Client ID. The GS may have different 428 policies for what different Registered Clients can request. A 429 Registered Client MAY be interacting with a User. 431 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 433 * *Dynamic Client* - a GC that has not been previously registered 434 with the GS, and each instance will generate it's own asymetric 435 key pair so it can prove it is the same instance of the GC on 436 subsequent requests. The GS MAY return a Dynamic Client a Client 437 Handle for the Dynamic Client to identify itself in subsequent 438 requests. A single-page application with no active server 439 component is an example of a Dynamic Client. 441 * *Client Handle* - a unique identifier at the GS for a Dynamic 442 Client for the Dynamic Client to refer to itself in subsequent 443 requests. 445 * *Interaction* - how the GC directs the User to interact with the 446 GS. This document defines the interaction modes: "redirect", 447 "indirect", and "user_code" in Section 5. 449 * *Grant* - the user identity claims and/or resource access the GS 450 has granted to the Client. The GS MAY invalidate a Grant at any 451 time. 453 * *Grant URI* - the URI that represents the Grant. The Grant URI 454 MUST start with the GS URI. 456 * *Access* - the access granted by the RO to the GC and contains an 457 access token. The GS may invalidate an Access at any time. 459 * *Access URI* - the URI that represents the Access the GC was 460 granted by the RO. The Access URI MUST start with the GS URI. 461 The Access URI is used to refresh an access token. 463 1.6. Notational Conventions 465 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 466 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 467 specification are to be interpreted as described in [RFC2119]. 469 Certain security-related terms are to be understood in the sense 470 defined in [RFC4949]. These terms include, but are not limited to, 471 "attack", "authentication", "authorization", "certificate", 472 "confidentiality", "credential", "encryption", "identity", "sign", 473 "signature", "trust", "validate", and "verify". 475 _[Editor: review that the terms listed and used are the same]_ 477 Unless otherwise noted, all the protocol parameter names and values 478 are case sensitive. 480 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 482 Some protocol parameters are parts of a JSON document, and are 483 referred to in JavaScript notation. For example, "foo.bar" refers to 484 the "bar" boolean attribute in the "foo" object in the following 485 example JSON document: 487 { 488 "foo" : { 489 "bar": true 490 } 491 } 493 2. Exemplar Sequences 495 The following sequences are demonstrative of how GNAP can be used, 496 but are just a few of the possible sequences possible with GNAP. 498 Before any sequence, the GC needs to be manually or programmatically 499 configured for the GS. See GS Options Section 3.7 for details on 500 programmatically acquiring GS metadata. 502 In the sequence diagrams: 504 + + + indicates an interaction with a person 505 ----- indicates an interaction between protocol roles 507 2.1. "redirect" Interaction 509 The GC is a web application and wants a Grant from the User 510 containing resource access and identity claims. The User is the RO 511 for the resource: 513 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 515 +--------+ +--------+ 516 | Grant | | Grant | 517 | Client |--(1)--- Create Grant ----------->| Server | 518 | (GC) | | (GS) | 519 | |<--- Interaction Response ---(2)--| | +------+ 520 | | | | | User | 521 | |+ +(3)+ + Interaction Transfer + +| + + + +|+ + + + >| | 522 | | | | | | 523 | | | |<+ (4) +>| | 524 | | | | authN | | 525 | | | | | | 526 | | | |<+ (5) +>| | 527 | | | | authZ | | 528 | |<+ + Interaction Transfer + +(6)+ | + + + +|+ + + + +| | 529 | | | | | | 530 | |--(7)--- Verify Grant ----------->| | +------+ 531 | | | | 532 | |<--------- Grant Response ---(8)--| | 533 | | | | 534 +--------+ +--------+ 536 1. *Create Grant* The GC creates a Request JSON document Section 3.5 537 containing an interaction.redirect object, and the requested 538 identity claims and resource access. The GC then makes a Create 539 Grant request (Section 3.2) by sending the JSON with an HTTP POST 540 to the GS URI. 542 2. *Interaction Response* The GS determines that interaction with 543 the User is required and sends an Interaction Response 544 (Section 4.2) containing the Grant URI and an 545 interaction.redirect object containing the redirect_uri. 547 3. *Interaction Transfer* The GC redirects the User to the 548 redirect_uri at the GS. 550 4. *User Authentication* The GS authenticates the User. 552 5. *User Authorization* If required, the GS interacts with the User 553 (who may also be the RO) to determine the identity claims and 554 resource access in the Grant Request are to be granted. 556 6. *Interaction Transfer* The GS redirects the User to the 557 completion_uri at the GC. 559 7. *Verify Grant* The GC makes an HTTP PATCH request to the Grant 560 URI passing the verification code (Section 3.3). 562 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 564 8. *Grant Response* The GS responds with a Grant Response 565 (Section 4.1). 567 The GC can now access the resources at the RS per Section 2.4. 569 2.2. "user_code" Interaction 571 A GC is on a device that wants a Grant from the User. The User will 572 interact with the GS using a separate device: 574 +--------+ +--------+ 575 | Grant | | Grant | 576 | Client |--(1)--- Create Grant ----------->| Server | 577 | (GC) | | (GS) | 578 | |<--- Interaction Response ---(2)--| | +------+ 579 | | | | | User | 580 | |--(3)--- Read Grant ------------->| | | | 581 | | | |<+ (4) +>| | 582 | | | | authN | | 583 | | | | | | 584 | | | |<+ (5) +>| | 585 | | | | code | | 586 | | | | | | 587 | | | |<+ (6) +>| | 588 | | | | authZ | | 589 | | | | | | 590 | |<--------- Grant Response ---(7)--| | | | 591 | | | | | | 592 +--------+ | | | | 593 | | | | 594 +--------+ | | | | 595 | Client |< + + Information URI Redirect + +| + + + +|+ (8) + +| | 596 | Server | | | | | 597 +--------+ +--------+ +------+ 599 1. *Create Grant* The GC creates a Request JSON document Section 3.5 600 containing an interaction.user_code object and makes a Create 601 Grant request (Section 3.2) by sending the JSON with an HTTP POST 602 to the GS URI. 604 2. *Interaction Response* The GS determines that interaction with 605 the User is required and sends an Interaction Response 606 (Section 4.2) containing the Grant URI and an 607 interaction.user_code object. 609 3. *Read Grant* The GC makes an HTTP GET request to the Grant URI. 611 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 613 4. *User Authentication* The User loads display_uri in their 614 browser, and the GS authenticates the User. 616 5. *User Code* The User enters the code at the GS. 618 6. *User Authorization* If required, the GS interacts with the User 619 (who may also be the RO) to determine the identity claims and 620 resource access in the Grant Request are to be granted. 622 7. *Grant Response* The GS responds with a Grant Response 623 (Section 4.1). 625 8. *Information URI Redirect* The GS redirects the User to the 626 information_uri provided by the GC. 628 The GC can now access the resources at the RS per Section 2.4. 630 2.3. Independent RO Authorization 632 The GC wants access to resources that require the GS to interact with 633 the RO, who is not interacting with the GC. The authorization from 634 the RO may take some time, so the GS instructs the GC to wait and 635 check back later. 637 +--------+ +--------+ 638 | Grant | | Grant | 639 | Client |--(1)--- Create Grant ----------->| Server | 640 | (GC) | | (GS) | 641 | |<---------- Wait Response ---(2)--| | +------+ 642 | (3) | | | | RO | 643 | Wait | | |<+ (4) +>| | 644 | | | | authZ | | 645 | |--(5)--- Read Grant ------------->| | +------+ 646 | | | | 647 | |<--------- Grant Response --(6)---| | 648 | | | | 649 +--------+ +--------+ 651 1. *Create Grant* The GC creates a Grant Request (Section 3.2) and 652 sends it with an HTTP POST to the GS GS URI. 654 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 655 containing the Grant URI and the "wait" attribute. 657 3. *GC Waits* The GC waits for the time specified in the "wait" 658 attribute. 660 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 662 4. *RO AuthZ* The GS interacts with the RO to determine which 663 identity claims and/or resource access in the Grant Request are 664 to be granted. 666 5. *Read Grant* The GC does an HTTP GET of the Grant URI 667 (Section 3.4). 669 6. *Grant Response* The GS responds with a Grant Response 670 (Section 4.1). 672 The GC can now access the resources at the RS per Section 2.4. 674 2.4. Resource Server Access 676 The GC received an Access URI from the GS. The GC acquires an access 677 token, calls the RS, and later the access token expires. The GC then 678 gets a fresh access token. 680 +--------+ +----------+ +--------+ 681 | Grant | | Resource | | Grant | 682 | Client |--(1)--- Access Resource --->| Server | | Server | 683 | (GC) |<------- Resource Response --| (RS) | | (GS) | 684 | | | | | | 685 | |--(2)--- Access Resource --->| | | | 686 | |<------- Error Response -----| | | | 687 | | | | | | 688 | | +----------+ | | 689 | | | | 690 | |--(3)--- Read Access --------------------->| | 691 | |<------- Access Response ------------------| | 692 | | | | 693 +--------+ +--------+ 695 1. *Resource Request* The GC accesses the RS with the access token 696 per Section 6 and receives a response from the RS. 698 2. *Resource Request* The GC attempts to access the RS, but receives 699 an error indicating the access token needs to be refreshed. 701 3. *Read Access* The GC makes a Read Access (Section 3.6) with an 702 HTTP GET to the Access URI and receives as Response JSON "access" 703 object (Section 4.4.4) with a fresh access token. 705 3. GS APIs 707 *GC Authentication* 709 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 711 All GS APIs except for GS Options require the GC to authenticate. 712 Authentication mechanisms include: 714 * JOSE Authentication [JOSE_Authentication] 716 * [Others TBD]* 718 3.1. GS API Table 720 +==============+=============+========+=============================+ 721 | request | http method | uri | response | 722 +==============+=============+========+=============================+ 723 | Create Grant | POST | GS URI | Interaction, | 724 | | | | wait, or Grant | 725 +--------------+-------------+--------+-----------------------------+ 726 | Verify Grant | PATCH | Grant | Grant | 727 | | | URI | | 728 +--------------+-------------+--------+-----------------------------+ 729 | Read Grant | GET | Grant | wait, or Grant | 730 | | | URI | | 731 +--------------+-------------+--------+-----------------------------+ 732 | Read Access | GET | Access | Access | 733 | | | URI | | 734 +--------------+-------------+--------+-----------------------------+ 735 | GS Options | OPTIONS | GS URI | metadata | 736 +--------------+-------------+--------+-----------------------------+ 738 Table 1 740 3.2. Create Grant 742 The GC creates a Grant by doing an HTTP POST of a JSON [RFC8259] 743 document to the GS URI. This is a Grant Request. 745 The JSON document MUST include the following from the Request JSON 746 Section 3.5: 748 * iat 750 * nonce 752 * uri - MUST be set to the GS URI 754 * method - MUST be "POST" 756 * client 758 and MAY include the following from Request JSON Section 3.5 760 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 762 * user 764 * interaction 766 * access 768 * claims 770 The GS MUST respond with one of Grant Response Section 4.1, 771 Interaction Response Section 4.2, Wait Response Section 4.3, or one 772 of the following errors: 774 * TBD 776 from Error Responses Section 7. 778 Following is a non-normative example of a web application GC 779 requesting identity claims about the User and read access to the 780 User's contacts: 782 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 784 Example 1 786 { 787 "iat" : 15790460234, 788 "uri" : "https://as.example/endpoint", 789 "method" : "POST, 790 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 791 "client": { 792 "display": { 793 "name" : "SPA Display Name", 794 "uri" : "https://spa.example/about" 795 } 796 }, 797 "interaction": { 798 "redirect": { 799 "completion_uri" : "https://web.example/return" 800 }, 801 "global" : { 802 "ui_locals" : "de" 803 } 804 }, 805 "access": [ "read_contacts" ], 806 "claims": { 807 "oidc": { 808 "id_token" : { 809 "email" : { "essential" : true }, 810 "email_verified" : { "essential" : true } 811 }, 812 "userinfo" : { 813 "name" : { "essential" : true }, 814 "picture" : null 815 } 816 } 817 } 818 } 820 Following is a non-normative example of a device GC requesting two 821 different access tokens, one request with "oauth_scope", the other 822 with "oauth_rich": 824 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 826 Example 2 828 { 829 "iat" : 15790460234, 830 "uri" : "https://as.example/endpoint", 831 "method" : "POST, 832 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 833 "client": { 834 "id" : "di3872h34dkJW" 835 }, 836 "interaction": { 837 "indirect": { 838 "information_uri": "https://device.example/c/indirect" 839 }, 840 "user_code": { 841 "information_uri": "https://device.example/c/user_code" 842 } 843 }, 844 "access": { 845 "play_music": [ "play_music" ], 846 "read_user_info: [ { 847 "type" : "customer_information", 848 "locations" : [ "https://example.com/customers" ], 849 "actions" : [ "read" ], 850 "datatypes" : [ "contacts", "photos" ] 851 } ] 852 } 853 } 855 3.3. Verify Grant 857 The GC verifies a Grant by doing an HTTP PATCH of a JSON document to 858 the Grant URI. The GC MUST only verify a Grant once. 860 The JSON document MUST include the following from the Request JSON 861 Section 3.5: 863 * iat 865 * nonce 867 * uri - MUST be set to the Grant URI 869 * method - MUST be PATCH 871 * interaction.redirection.verification - MUST be the verification 872 code received per Section 5.1.1. 874 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 876 Following is a non-normative example: 878 { 879 "iat" : 15790460235, 880 "uri" : "https://as.example/endpoint/grant/example1", 881 "method" : "PATCH, 882 "nonce" : "9b6afd70-2036-47c9-b953-5dd1fd0c699a", 883 "interaction": { 884 "redirect": { 885 "verification" : "cb4aa22d-2fe1-4321-b87e-bbaa66fbe707" 886 } 887 } 888 } 890 The GS MUST respond with one of Grant Response Section 4.1 or one of 891 the following errors: 893 * TBD 895 3.4. Read Grant 897 The GC reads a Grant by doing an HTTP GET of the corresponding Grant 898 URI. The GC MAY read a Grant until it expires or has been 899 invalidated. 901 The GS MUST respond with one of Grant Response Section 4.1, Wait 902 Response Section 4.3, or one of the following errors: 904 * TBD 906 3.5. Request JSON 908 * *iat* - the time of the request as a NumericDate. 910 * *nonce* - a unique identifier for this request. Note the Grant 911 Response MUST contain a matching "nonce" attribute value. 913 * *uri* - the URI being invoked 915 * *method* - the HTTP method being used 917 3.5.1. "client" Object 919 The client object MUST only one of the following: 921 * *id* - the Client ID the GS has for a Registered Client. 923 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 925 * *handle* - the Client Handle the GS previously provided a Dynamic 926 Client 928 * *display* - the display object contains the following attributes: 930 - *name* - a string that represents the Dynamic Client 932 - *uri* - a URI representing the Dynamic Client 934 The GS will show the the User the display.name and display.uri values 935 when prompting for authorization. 937 _[Editor: a max length for the name and URI so a GS can reserve 938 appropriate space?]_ 940 3.5.2. "interaction" Object 942 The interaction object contains one or more interaction mode objects 943 per Section 5 representing the interactions the GC is willing to 944 provide the User. In addition to the interaction mode objects, the 945 interaction object may contain the "global" object; 947 * *global* - an optional object containing parameters that are 948 applicable for all interaction modes. Only one attribute is 949 defined in this document: 951 - *ui_locales* - End-User's preferred languages and scripts for 952 the user interface, represented as a space-separated list of 953 [RFC5646] language tag values, ordered by preference. This 954 attribute is OPTIONAL. 956 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 957 a JSON array?]_ 959 3.5.3. "user" Object 961 * *identifiers* - The identifiers MAY be used by the GS to improve 962 the User experience. This object contains one or more of the 963 following identifiers for the User: 965 - *phone_number* - contains a phone number per Section 5 of 966 [RFC3966]. 968 - *email* - contains an email address per [RFC5322]. 970 - *oidc* - is an object containing both the "iss" and "sub" 971 attributes from an OpenID Connect ID Token [OIDC] Section 2. 973 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 975 * *claims* - an optional object containing one or more assertions 976 the GC has about the User. 978 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 979 Section 2. 981 3.5.4. "access" Object 983 The GC may request a single Access, or multiple. If a single Access, 984 the "access" object contains an array of [RAR] objects. If multiple, 985 the "access" object contains an object where each property name is a 986 unique string created by the GC, and the property value is an array 987 of [RAR] objects. 989 3.5.5. "claims" Object 991 Includes one or more of the following: 993 * *oidc* - an object that contains one or both of the following 994 objects: 996 - *userinfo* - Claims that will be returned as a JSON object 998 - *id_token* - Claims that will be included in the returned ID 999 Token. If the null value, an ID Token will be returned 1000 containing no additional Claims. 1002 The contents of the userinfo and id_token objects are Claims as 1003 defined in [OIDC] Section 5. 1005 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1006 per [OIDC4IA]. 1008 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 1009 requested.]_[W3C_VC] 1011 3.6. Read Access 1013 The GC acquires and refreshes an Access by doing an HTTP GET to the 1014 corresponding Access URI. 1016 The GS MUST respond with a Access JSON document Section 4.5, or one 1017 of the following errors: 1019 * TBD 1021 from Error Responses Section 7. 1023 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1025 3.7. GS Options 1027 The GC can get the metadata for the GS by doing an HTTP OPTIONS of 1028 the corresponding GS URI. This is the only API where the GS MAY 1029 respond to an unauthenticated request. 1031 The GS MUST respond with the the following JSON document: 1033 * *uri* - the GS URI. 1035 * *client_authentication* - a JSON array of the GC Authentication 1036 mechanisms supported by the GS 1038 * *interactions* - a JSON array of the interaction modes supported 1039 by the GS. 1041 * *access* - an object containing the access the GC may request from 1042 the GS, if any. 1044 - Details TBD 1046 * *claims* - an object containing the identity claims the GC may 1047 request from the GS, if any, and what public keys the claims will 1048 be signed with. 1050 - Details TBD 1052 * *algorithms* - a JSON array of the cryptographic algorithms 1053 supported by the GS. [details TBD]* 1055 * *features* - an object containing feature or extension support 1057 or one of the following errors: 1059 * TBD 1061 from Error Responses Section 7. 1063 4. GS Responses 1065 There are three successful responses to a Grant Request: Grant 1066 Response, Interaction Response, or Wait Response. 1068 4.1. Grant Response 1070 The Grant Response MUST include the following from the Response JSON 1071 Section 4.4 1073 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1075 * iat 1077 * nonce 1079 * uri 1081 and MAY include the following from the Response JSON Section 4.4 1083 * client.handle 1085 * access 1087 * claims 1089 * expires_in 1091 * warnings 1093 Example non-normative Grant Response JSON document for Example 1 in 1094 Section 3.2: 1096 { 1097 "iat" : 15790460234, 1098 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1099 "uri" : "https://as.example/endpoint/grant/example1", 1100 "expires_in" : 300 1101 "access": { 1102 "mechanism" : "bearer", 1103 "token" : "eyJJ2D6.example.access.token.mZf9p" 1104 "expires_in" : 3600, 1105 "granted" : [ "read_contacts" ], 1106 }, 1107 "claims": { 1108 "oidc": { 1109 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1110 "userinfo" : { 1111 "name" : "John Doe", 1112 "picture" : "https://photos.example/p/eyJzdkiO" 1113 } 1114 } 1115 } 1116 } 1118 Note in this example since no Access URI was returned in the access 1119 object, the access token can not be refreshed, and expires in an 1120 hour. 1122 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1124 Example non-normative Grant Response JSON document for Example 2 in 1125 Section 3.2: 1127 { 1128 "iat" : 15790460234, 1129 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1130 "uri" : "https://as.example/endpoint/grant/example2", 1131 "access": { 1132 "play_music": { "uri" : "https://as.example/endpoint/access/example2" }, 1133 "read_user_info: { "uri" " "https://as.example/endpoint/access/"} 1134 } 1135 } 1137 Note in this example the GS only provided the Access URIs. The GC 1138 must acquire the Access per Section 3.6 1140 [Editor: the GC needs to remember if it asked for a single access, or 1141 multiple, as there is no crisp algorithm for differentiating between 1142 the responses] 1144 4.2. Interaction Response 1146 The Interaction Response MUST include the following from the Response 1147 JSON Section 4.4 1149 * iat 1151 * nonce 1153 * uri 1155 * interaction 1157 and MAY include the following from the Response JSON Section 4.4 1159 * user 1161 * wait 1163 * warnings 1165 A non-normative example of an Interaction Response follows: 1167 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1169 { 1170 "iat" : 15790460234, 1171 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1172 "uri" : "https://as.example/endpoint/grant/example4", 1173 "interaction" : { 1174 "redirect" : { 1175 "redirect_uri" : "https://as.example/i/example4" 1176 } 1177 } 1178 } 1180 4.3. Wait Response 1182 The Wait Response MUST include the following from the Response JSON 1183 Section 4.4 1185 * iat 1187 * nonce 1189 * uri 1191 * wait 1193 and MAY include the following from the Response JSON Section 4.4 1195 * warnings 1197 A non-normative example of Wait Response follows: 1199 { 1200 "iat" : 15790460234, 1201 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1202 "uri" : "https://as.example/endpoint/grant/example5", 1203 "wait" : 300 1204 } 1206 4.4. Response JSON 1208 Details of the JSON document: 1210 * *iat* - the time of the response as a NumericDate. 1212 * *nonce* - the nonce that was included in the Request JSON 1213 Section 3.5. 1215 * *uri* - the Grant URI. 1217 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1219 * *wait* - a numeric value representing the number of seconds the GC 1220 should want before making a Read Grant request to the Grant URI. 1222 * *expires_in* - a numeric value specifying how many seconds until 1223 the Grant expires. This attribute is OPTIONAL. 1225 4.4.1. "client" Object 1227 If the GC is a Dynamic Client, the GS may return 1229 * *handle* the Client Handle 1231 4.4.2. "interaction" Object 1233 If the GS wants the GC to start the interaction, the GS MUST return 1234 an interaction object containing one or more interaction mode 1235 responses per Section 5 to one or more of the interaction mode 1236 requests provided by the GC. 1238 4.4.3. "access" Object 1240 If the GC requested a single Access, the "access" object is an access 1241 response object Section 4.4.4. If the GC requested multiple, the 1242 access object contains a property of the same name for each Access 1243 requested by the GC, and each property is an access response object 1244 Section 4.4.4. 1246 4.4.4. Access Response Object 1248 The access response object contains properties from the Access JSON 1249 Section 4.5. The access response object MUST contain either the 1250 "uri" property from, or MUST contain: 1252 * mechanism 1254 * token 1256 and MAY contain: 1258 * access 1260 * expires_in 1262 * uri 1264 If there is no "uri" property, the access token can not be refreshed. 1265 If only the "uri" property is present, the GC MUST acquire the Access 1266 per Section 3.6 1268 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1270 4.4.5. "claims" Object 1272 The claims object is a response to the Grant Request "claims" object 1273 Section 3.5.5. 1275 * *oidc* 1277 - *id_token* - an OpenID Connect ID Token containing the Claims 1278 the User consented to be released. 1280 - *userinfo* - the Claims the User consented to be released. 1282 Claims are defined in [OIDC] Section 5. 1284 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1285 per [OIDC4IA]. 1287 * *vc* 1289 The verified claims the user consented to be released. _[Editor: 1290 details TBD]_ 1292 4.4.6. "warnings" JSON Array 1294 Includes zero or more warnings from Section 8, 1296 4.5. Access JSON 1298 The Access JSON is a Grant Response Access Object Section 4.4.4 or 1299 the response to a Read Access request by the GC Section 3.6. 1301 * *mechanism* - the RS access mechanism. This document defines the 1302 "bearer" mechanism as defined in Section 6. Required. 1304 * *token* - the access token for accessing an RS. Required. 1306 * *expires_in* - an optional numeric value specifying how many 1307 seconds until the access token expires. 1309 * *uri* - the Access URI. Used to acquire or refresh Access. 1310 Required. 1312 * *granted* - an optional array of [RAR] objects containing the 1313 resource access granted 1315 _[Editor: would an optional expiry for the Access be useful?]_ 1317 The following is a non-normative example of Access JSON: 1319 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1321 { 1322 "mechanism" : "bearer", 1323 "token" : "eyJJ2D6.example.access.token.mZf9p" 1324 "expires_in" : 3600, 1325 "uri" : "https://as.example/endpoint/access/example2", 1326 "granted" : [ "read_calendar write_calendar" ] 1327 } 1329 4.6. Response Verification 1331 On receipt of a response, the GC MUST verify the following: 1333 * TBD 1335 5. Interaction Modes 1337 This document defines three interaction modes: "redirect", 1338 "indirect", and "user_code". Extensions may define additional 1339 interaction modes. 1341 The "global" attribute is reserved in the interaction object for 1342 attributes that apply to all interaction modes. 1344 5.1. "redirect" 1346 A Redirect Interaction is characterized by the GC redirecting the 1347 User's browser to the GS, the GS interacting with the User, and then 1348 GS redirecting the User's browser back to the GC. The GS correlates 1349 the Grant Request with the unique redirect_uri, and the GC correlates 1350 the Grant Request with the unique completion_uri. 1352 *The request "interaction" object contains:* 1354 * *completion_uri* a unique URI at the GC that the GS will return 1355 the User to. The URI MUST not contain the "nonce" from the Grant 1356 Request, and MUST not be guessable. This attribute is REQUIRED. 1358 *The response "interaction" object contains:* 1360 * *redirect_uri* a unique URI at the GS that the GC will redirect 1361 the User to. The URI MUST not contain the "nonce" from the Grant 1362 Request, and MUST not be guessable. This attribute is REQUIRED. 1364 * *verification* a boolean value indicating the GS requires the GC 1365 to make a Verify Grant request.(Section 3.3) 1367 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1369 5.1.1. "redirect" verification 1371 If the GS indicates that Grant Verification is required, the GS MUST 1372 add a 'verification' query parameter with a value of a unique 1373 verification code to the completion_uri. 1375 On receiving the verification code in the redirect from the GS, the 1376 GC makes a Verify Grant request (Section 3.3) with the verification 1377 code. 1379 5.2. "indirect" 1381 An Indirect Interaction is characterized by the GC causing the User's 1382 browser to load the indirect_uri at GS, the GS interacting with the 1383 User, and then the GS MAY optionally redirect the User's Browser to a 1384 information_uri. There is no mechanism for the GS to redirect the 1385 User's browser back to the GC. 1387 Examples of how the GC may initiate the interaction are encoding the 1388 indirect_uri as a code scannable by the User's mobile device, or 1389 launching a system browser from a command line interface (CLI) 1390 application. 1392 The "indirect" mode is susceptible to session fixation attacks. See 1393 TBD in the Security Considerations for details. 1395 *The request "interaction" object contains:* 1397 * *information_uri* an OPTIONAL URI that the GS will redirect the 1398 User's browser to after GS interaction. 1400 *The response "interaction" object contains:* 1402 * *indirect_uri* the URI the GC will cause to load in the User's 1403 browser. The URI SHOULD be short enough to be easily encoded in a 1404 scannable code. The URI MUST not contain the "nonce" from the 1405 Grant Request, and MUST not be guessable. _[Editor: recommend a 1406 maximum length?]_ 1408 5.3. "user_code" 1410 An Indirect Interaction is characterized by the GC displaying a code 1411 and a URI for the User to load in a browser and then enter the code. 1412 _[Editor: recommend a minimum entropy?]_ 1414 *The request "interaction" object contains:* 1416 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1418 * *information_uri* an OPTIONAL URI that the GS will redirect the 1419 User's browser to after GS interaction. 1421 *The response "interaction" object contains:* 1423 * *code* the code the GC displays to the User to enter at the 1424 display_uri. This attribute is REQUIRED. 1426 * *display_uri* the URI the GC displays to the User to load in a 1427 browser to enter the code. 1429 6. RS Access 1431 The mechanism the GC MUST use to access an RS is in the Access JSON 1432 "mechanism" attribute Section 4.4.4. 1434 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1436 The "jose" and "jose+body" mechanisms are defined in 1437 [JOSE_Authentication] 1439 A non-normative "bearer" example of the HTTP request headers follows: 1441 GET /calendar HTTP/2 1442 Host: calendar.example 1443 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1445 7. Error Responses 1447 * TBD 1449 8. Warnings 1451 [Editor: Warnings are an optional response that can assist a GC in 1452 detecting non-fatal errors, such as ignored objects and properties.] 1454 * TBD 1456 9. Extensibility 1458 This standard can be extended in a number of areas: 1460 * *GC Authentication Mechanisms* 1462 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1464 - An extension could define other mechanisms for the GC to 1465 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1466 Signing. Constrained environments could use CBOR [RFC7049] 1467 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1468 [RFC8323] instead of HTTP/2. 1470 * *Grant* 1472 - An extension can define new objects in the Grant Request and 1473 Grant Response JSON that return new URIs. 1475 * *Top Level* 1477 - Top level objects SHOULD only be defined to represent 1478 functionality other the existing top level objects and 1479 attributes. 1481 * *"client" Object* 1483 - Additional information about the GC that the GS would require 1484 related to an extension. 1486 * *"user" Object* 1488 - Additional information about the User that the GS would require 1489 related to an extension. 1491 * *"access" Object* 1493 - RAR is inherently extensible. 1495 * *"claims" Object* 1497 - Additional claim schemas in addition to OpenID Connect claims 1498 and Verified Credentials. 1500 * *interaction modes* 1502 - Additional types of interactions a GC can start with the User. 1504 * *Continuous Authentication* 1506 - An extension could define a mechanism for the GC to regularly 1507 provide continuous authentication signals and receive 1508 responses. 1510 _[Editor: do we specify access token introspection in this document, 1511 or leave that to an extension?]_ 1513 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1515 10. Rational 1517 1. *Why do GCs now always use Asymetric cryptography? Why not keep 1518 the client secret?* 1520 In the past, asymetric cryptography was relatively computational 1521 expensive. Modern browsers now have asymetric cryptographic 1522 APIs available, and modern hardware has significantly reduced 1523 the computational impact. 1525 2. *Why have both Client ID and Client Handle?* 1527 While they both refer to a Grant Client in the protocol, the 1528 Client ID refers to a pre-registered client,and the Client 1529 Handle is specific to an instance of a Dynamic Client. Using 1530 separate terms clearly differentiates which identifier is being 1531 presented to the GS. 1533 3. *Why allow GC and GS to negotiate the user interaction mode?* 1535 The GC knows what interaction modes it is capable of, and the GS 1536 knows which interaction modes it will permit for a given Grant 1537 Request. The GC can then present the intersection to the User 1538 to choose which one is preferred. For example, while a device 1539 based GC may be willing to do both "indirect" and "user_code", a 1540 GS may not enable "indirect" for concern of a session fixation 1541 attack. Additional interaction modes will likely become 1542 available which allows new modes to be negotiated between GC and 1543 GS as each adds additional interaction modes. 1545 4. *Why have both identity claims and resource access?* 1547 There are use cases for each that are independent: 1548 authenticating a user and providing claims vs granting access to 1549 a resource. A request for an authorization returns an access 1550 token which may have full CRUD capabilities, while a request for 1551 a claim returns the claim about the User - with no create, 1552 update or delete capabilities. While the UserInfo endpoint in 1553 OIDC may be thought of as a resource, separating the concepts 1554 and how they are requested keeps each of them simpler in the 1555 Editor's opinion. :) 1557 5. *Why do some of the JSON objects only have one child, such as 1558 the identifiers object in the user object in the Grant Request?* 1560 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1562 It is difficult to forecast future use cases. Having more 1563 resolution may mean the difference between a simple extension, 1564 and a convoluted extension. For example, the "global" object in 1565 the "interaction" object allows new global parameters to be 1566 added without impacting new interaction modes. 1568 6. *Why is the "iss" included in the "oidc" identifier object? 1569 Would the "sub" not be enough for the GS to identify the User?* 1571 This decouples the GS from the OpenID Provider (OP). The GS 1572 identifier is the GS URI, which is the endpoint at the GS. The 1573 OP issuer identifier will likely not be the same as the GS URI. 1574 The GS may also provide claims from multiple OPs. 1576 7. *Why is there not a UserInfo endpoint as there is with OpenID 1577 Connect?* 1579 Since the GC can Read Grant at any time, it get the same 1580 functionality as the UserInfo endpoint, without the GC having to 1581 manage a separate access token and refresh token. If the GC 1582 would like additional claims, it can Update Grant, and the GS 1583 will let the GC know if an interaction is required to get any of 1584 the additional claims, which the GC can then start. 1586 _[Editor: is there some other reason to have the UserInfo 1587 endpoint?]_ 1589 8. *Why use URIs for the Grant and Access?* 1591 * Grant URI and Access URI are defined to start with the GS 1592 URI, allowing the GC, and GS to determine which GS a Grant or 1593 Access belongs to. 1595 * URIs also enable a RESTful interface to the GS functionality. 1597 * A large scale GS can easily separate out the services that 1598 provide functionality as routing of requests can be done at 1599 the HTTP layer based on URI and HTTP method. This allows a 1600 separation of concerns, independent deployment, and 1601 resiliency. 1603 9. *Why use the OPTIONS method on the GS URI? Why not use a .well- 1604 known mechanism?* 1606 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1608 Having the GS URI endpoint respond to the metadata allows the GS 1609 to provide GC specific results using the same GC authentication 1610 used for other requests to the GS. It also reduces the risk of 1611 a mismatch between the advertised metadata, and the actual 1612 metadata. A .well-known discovery mechanism may be defined to 1613 resolve from a hostname to the GS URI. 1615 10. *Why is there a Verify Grant? The GC can protect itself from 1616 session fixation without it.* 1618 GC implementations may not always follow the best practices. 1619 The Verify Grant allows the GS to ensure there is not a session 1620 fixation as the instance of the GC making creating the Grant is 1621 the one that gets the verification code in the redirect. 1623 11. **Why use the [OIDC] claims rather than the [IANA_JWT] list of 1624 claims? 1626 The [IANA_JWT] claims include claims that are not identity 1627 claims, and [IANA_JWT] references the [OIDC] claims, and [OIDC] 1628 5.1 are only identity claims. 1630 11. Privacy Considerations 1632 TBD 1634 12. Security Considerations 1636 TBD 1638 13. Acknowledgments 1640 This draft derives many of its concepts from Justin Richer's 1641 Transactional Authorization draft [TxAuth]. 1643 Additional thanks to Justin Richer and Annabelle Richard Backman for 1644 their strong critique of earlier drafts. [Editor: add in the other 1645 contributors from mail list] 1647 14. IANA Considerations 1649 TBD 1651 15. References 1653 15.1. Normative References 1654 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1656 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1657 Requirement Levels", BCP 14, RFC 2119, 1658 DOI 10.17487/RFC2119, March 1997, 1659 . 1661 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1662 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1663 . 1665 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1666 DOI 10.17487/RFC5322, October 2008, 1667 . 1669 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1670 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1671 . 1673 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1674 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1675 September 2009, . 1677 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1678 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1679 . 1681 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1682 Framework: Bearer Token Usage", RFC 6750, 1683 DOI 10.17487/RFC6750, October 2012, 1684 . 1686 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1687 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1688 . 1690 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1691 Interchange Format", STD 90, RFC 8259, 1692 DOI 10.17487/RFC8259, December 2017, 1693 . 1695 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1696 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1697 . 1699 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1700 Assurance 1.0", October 2019, . 1703 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1705 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1706 Rich Authorization Requests", January 2020, 1707 . 1709 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1710 Credentials Data Model 1.0", November 2019, 1711 . 1713 [JOSE_Authentication] 1714 Hardt, D., "JOSE Authentication", June 2020, 1715 . 1717 [GNAP_Advanced] 1718 Hardt, D., "The Grant Negotiation and Authorization 1719 Protocol - Advanced Features", June 2020, 1720 . 1722 15.2. Informative References 1724 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1725 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1726 October 2013, . 1728 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1729 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1730 . 1732 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1733 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1734 Application Protocol) over TCP, TLS, and WebSockets", 1735 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1736 . 1738 [browser_based_apps] 1739 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1740 Apps", September 2019, . 1743 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1744 identification and data capture techniques - QR Code bar 1745 code symbology specification", February 2015, 1746 . 1748 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1749 . 1752 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1754 [IANA_JWT] "JSON Web Token Claims", January 2015, 1755 . 1757 Appendix A. Document History 1759 A.1. draft-hardt-xauth-protocol-00 1761 * Initial version 1763 A.2. draft-hardt-xauth-protocol-01 1765 * text clean up 1767 * added OIDC4IA claims 1769 * added "jws" method for accessing a resource. 1771 * renamed Initiation Request -> Grant Request 1773 * renamed Initiation Response -> Interaction Response 1775 * renamed Completion Request -> Authorization Request 1777 * renamed Completion Response -> Grant Request 1779 * renamed completion handle -> authorization handle 1781 * added Authentication Request, Authentication Response, 1782 authentication handle 1784 A.3. draft-hardt-xauth-protocol-02 1786 * major rewrite 1788 * handles are now URIs 1790 * the collection of claims and authorizations are a Grant 1792 * an Authorization is its own type 1794 * lots of sequences added 1796 A.4. draft-hardt-xauth-protocol-03 1798 * fixed RO definition 1800 * improved language in Rationals 1802 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1804 * added user code interaction method, and aligned qrcode interaction 1805 method 1807 * added information_uri for code flows 1809 A.5. draft-hardt-xauth-protocol-04 1811 * renamed interaction uris to have purpose specific names 1813 A.6. draft-hardt-xauth-protocol-05 1815 * separated claims from identifiers in request user object 1817 * simplified reciprocal grant flow 1819 * reduced interactions to redirect and indirect 1821 * simplified interaction parameters 1823 * added in language for Client to verify interaction completion 1825 * added Verify Grant API and Interaction Nonce 1827 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1828 operation. 1830 A.7. draft-hardt-xauth-protocol-06 1832 * fixup examples to match specification 1834 A.8. draft-hardt-xauth-protocol-07 1836 * refactored interaction request and response syntax, and enabled 1837 interaction mode negotiation 1839 * generation of client handle by GS for dynamic clients 1841 * renamed title to Grant Negotiation and Authorization Protocol. 1842 Preserved draft-hardt-xauth-protocol filename to ease tracking 1843 changes. 1845 * changed Authorizations to be key / value pairs (aka dictionary) 1846 instead of a JSON array 1848 A.9. draft-hardt-xauth-protocol-08 1850 * split document into three documents: core, advanced, and JOSE 1851 authentication. 1853 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1855 * grouped access granted into "access" object in Authorization JSON 1857 * added warnings object to the Grant Response JSON 1859 A.10. draft-hardt-xauth-protocol-09 1861 * added editorial note that this document should be referred to as 1862 XAuth 1864 A.11. draft-hardt-xauth-protocol-10 1866 * added example of RAR authorization request 1868 * fixed typos 1870 A.12. draft-hardt-xauth-protocol-11 1872 * renamed authorization_uri to interaction_uri to avoid confusion 1873 with AZ URI 1875 * made URI names more consistent 1877 - renamed completion_uri to information_uri 1879 - renamed redirect_uri to completion_uri 1881 - renamed interaction_uri to redirect_uri 1883 - renamed short_uri to indirect_uri 1885 * editorial fixes 1887 * renamed http verb to method 1889 * added Verify Grant and verification parameters 1891 A.13. draft-hardt-xauth-protocol-12 1893 * removed authorization object, and made authorizations object 1894 polymorphic 1896 A.14. draft-hardt-xauth-protocol-13 1898 * added Q about referencing OIDC claims vs IANA JWT 1900 * made all authorizations be a RAR type as it provides the required 1901 flexibility, removed "oauth_rar" type 1903 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1905 * added RO to places where the RO and User are the same 1907 A.15. draft-hardt-xauth-protocol-14 1909 * rewrote introduction 1911 * add in claims issuer and grant server owner 1913 * abstract protocol 1915 * add clarification on different parties 1917 * renamed Client to Grant Client 1919 * added entity relationship diagram 1921 * updated diagrams 1923 * added placeholder for Privacy Considerations 1925 * renamed Authorization to Access 1927 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1929 *Changed Features* 1931 The major changes between GNAP and OAuth 2.X and OpenID Connect are: 1933 * The OAuth 2.X client and the OpenID Connect replying party are the 1934 Grant Client in GNAP. 1936 * The GNAP Grant Server is a superset of the OAuth 2.X authorization 1937 server, and the OpenID Connect OP (OpenID Provider). 1939 * The GC always uses a private asymetric key to authenticate to the 1940 GS. There is no client secret. 1942 * The GC initiates the protocol by making a signed request directly 1943 to the GS instead of redirecting the User to the GS. 1945 * The GC does not pass any parameters in redirecting the User to the 1946 GS. 1948 * The refresh_token has been replaced with an AZ URI that both 1949 represents the authorization, and is the URI for obtaining a fresh 1950 access token. 1952 Internet-DrafThe Grant Negotiation and Authorization Protoco August 2020 1954 * The GC can request identity claims to be returned independent of 1955 the ID Token. 1957 * The GS URI is the only static endpoint. All other URIs are 1958 dynamically generated. The GC does not need to register it's 1959 redirect URIs. 1961 TBD - negotiation 1963 *Preserved Features* 1965 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1966 2.0. 1968 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1970 * No change is required by the GC or the RS for accessing existing 1971 bearer token protected APIs. 1973 *New Features* 1975 * All GC calls to the GS are authenticated with asymetric 1976 cryptography 1978 * A Grant represents both the user identity claims and RS access 1979 granted to the GC. 1981 * Support for scannable code initiated interactions. 1983 * Highly extensible per Section 9. 1985 Author's Address 1987 Dick Hardt (editor) 1988 SignIn.Org 1989 United States 1991 Email: dick.hardt@gmail.com