idnits 2.17.00 (12 Aug 2021) /tmp/idnits24615/draft-hardt-xauth-protocol-11.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 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: * *authorization_details* - an authorization_details JSON array of objects per [RAR]. MUST be included if type is "oauth_rich". MUST not be included if type is "oauth_scope" == 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 Client 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 Client 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 Client 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 (4 July 2020) is 686 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: 1 error (**), 0 flaws (~~), 7 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 4 July 2020 5 Expires: 5 January 2021 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-11 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 to support alternative authorizations, 21 claims, interactions, and client authentication mechanisms. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 5 January 2021. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6 59 1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7 61 2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 8 63 2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 9 64 2.3. Independent RO Authorization . . . . . . . . . . . . . . 10 65 2.4. Resource Server Access . . . . . . . . . . . . . . . . . 11 66 3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 12 68 3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 12 69 3.3. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 15 70 3.4. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 16 71 3.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16 72 3.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 17 73 3.5.2. "interaction" Object . . . . . . . . . . . . . . . . 17 74 3.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 17 75 3.5.4. "authorization" Object . . . . . . . . . . . . . . . 18 76 3.5.5. "authorizations" Object . . . . . . . . . . . . . . . 18 77 3.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 18 78 3.6. Read Authorization . . . . . . . . . . . . . . . . . . . 19 79 3.7. GS Options . . . . . . . . . . . . . . . . . . . . . . . 19 80 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 20 81 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 20 82 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 21 83 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 22 84 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 23 85 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 23 86 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 23 87 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23 88 4.4.4. "authorization" Object . . . . . . . . . . . . . . . 23 89 4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 24 90 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24 91 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 24 92 4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 25 93 4.6. Response Verification . . . . . . . . . . . . . . . . . . 26 94 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 26 95 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.1.1. "redirect" verification . . . . . . . . . . . . . . . 26 98 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 27 99 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 27 100 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 28 102 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 28 103 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28 104 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32 106 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 107 13. Security Considerations . . . . . . . . . . . . . . . . . . . 32 108 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 109 14.1. Normative References . . . . . . . . . . . . . . . . . . 32 110 14.2. Informative References . . . . . . . . . . . . . . . . . 33 111 Appendix A. Document History . . . . . . . . . . . . . . . . . . 34 112 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 34 113 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 34 114 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 35 115 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 35 116 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 35 117 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 35 118 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 36 119 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 36 120 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 36 121 A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 36 122 A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 36 123 A.12. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 36 124 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 37 125 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 127 1. Introduction 129 *EDITOR NOTE* 131 _This document captures a number of concepts that may be adopted by 132 the proposed GNAP working group. Please refer to this document as:_ 134 *XAuth* 136 _The use of GNAP in this document is not intended to be a declaration 137 of it being endorsed by the proposed GNAP working group._ 139 This document describes the core Grant Negotiation and Authorization 140 Protocol (GNAP). The protocol supports the widely deployed use cases 141 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 142 an extension of OAuth 2.0, as well as other extensions. Related 143 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 144 Authentication [JOSE_Authentication] that describes the JOSE 145 mechanisms for client authentication. 147 The technology landscape has changed since OAuth 2.0 was initially 148 drafted. More interactions happen on mobile devices than PCs. 149 Modern browsers now directly support asymetric cryptographic 150 functions. Standards have emerged for signing and encrypting tokens 151 with rich payloads (JOSE) that are widely deployed. 153 GNAP simplifies the overall architectural model, takes advantage of 154 today's technology landscape, provides support for all the widely 155 deployed use cases, offers numerous extension points, and addresses 156 many of the security issues in OAuth 2.0 by passing parameters 157 securely between parties, rather than via a browser redirection. . 159 While GNAP is not backwards compatible with OAuth 2.0, it strives to 160 minimize the migration effort. 162 GNAP centers around a Grant, a representation of the collection of 163 user identity claims and/or resource authorizations the Client is 164 requesting, and the resulting identity claims and/or resource 165 authorizations granted by the Grant Server (GS). 167 User consent is often required at the GS. GNAP enables a Client and 168 GS to negotiate the interaction mode for the GS to obtain consent. 170 The suggested pronunciation of GNAP is the same as the English word 171 "nap", a silent "g" as in "gnaw". 173 _[Editor: suggestions on how to improve this are welcome!]_ 175 1.1. Parties 177 The parties and their relationships to each other: 179 +--------+ +------------+ 180 | User | | Resource | 181 | | | Owner (RO) | 182 +--------+ +------------+ 183 | \ / | 184 | \ / | 185 | \ / | 186 | \ / | 187 +--------+ +---------------+ +------------+ 188 | Client |---->| Grant | | Resource | 189 | | (1) | Server (GS) | _ _ | Server | 190 | |<----| | | (RS) | 191 | | +---------------+ | | 192 | |-------------------------->| | 193 | | (2) | | 194 | |<--------------------------| | 195 +--------+ +------------+ 197 This document specifies interactions between the Client and GS (1), 198 and the Client and RS (2). 200 * *User* - the person interacting with the Client who has delegated 201 access to identity claims about themselves to the Grant Server 202 (GS), and can authenticate at the GS. 204 * *Client* - requests a Grant from the GS to access one or more 205 Resource Servers (RSs), and/or identity claims about the User. 206 The Grant may include access tokens that the Client uses to access 207 the RS. There are two types of Clients: Registered Clients and 208 Dynamic Clients. All Clients have a private asymetric key to 209 authenticate with the Grant Server. 211 * *Registered Client* - a Client that has registered with the GS and 212 has a Client ID to identify itself, and can prove it possesses a 213 key that is linked to the Client ID. The GS may have different 214 policies for what different Registered Clients can request. A 215 Registered Client MAY be interacting with a User. 217 * *Dynamic Client* - a Client that has not been previously 218 registered with the GS, and each instance will generate it's own 219 asymetric key pair so it can prove it is the same instance of the 220 Client on subsequent requests. The GS MAY return a Dynamic Client 221 a Client Handle for the Client to identify itself in subsequent 222 requests. A single-page application with no active server 223 component is an example of a Dynamic Client. A Dynamic Client 224 MUST be interacting with a User. 226 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 227 release of identity claims about the User. The GS may require 228 explicit consent from the RO or User to provide these to the 229 Client. A GS may support Registered Clients and/or Dynamic 230 Clients. The GS is a combination of the Authorization Server (AS) 231 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 233 * *Resource Server* (RS) - has API resources that require an access 234 token from the GS. Some, or all of the resources are owned by the 235 Resource Owner. 237 * *Resource Owner* (RO) - owns resources at the RS, and has 238 delegated RS access management to the GS. The RO may be the same 239 entity as the User, or may be a different entity that the GS 240 interacts with independently. GS and RO interactions are out of 241 scope of this document. 243 1.2. Reused Terms 245 * *access token* - an access token as defined in [RFC6749] 246 Section 1.4. 248 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 249 issued by the GS, or by other issuers. 251 * *Client ID* - a GS unique identifier for a Registered Client as 252 defined in [RFC6749] Section 2.2. 254 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 256 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 258 * *authN* - short for authentication. 260 * *authZ* - short for authorization. 262 1.3. New Terms 264 * *GS URI* - the endpoint at the GS the Client calls to create a 265 Grant, and is the unique identifier for the GS. 267 * *Grant* - the user identity claims and/or RS authorizations the GS 268 has granted to the Client. The GS MAY invalidate a Grant at any 269 time. 271 * *Grant URI* - the URI that represents the Grant. The Grant URI 272 MUST start with the GS URI. 274 * *Authorization* - the access granted by the RO to the Client and 275 contains an access token. The GS may invalidate an Authorization 276 at any time. 278 * *Authorization URI* (AZ URI) - the URI that represents the 279 Authorization the Client was granted by the RO. The AZ URI MUST 280 start with the GS URI. The AZ URI is used to refresh an access 281 token. 283 * *Interaction* - how the Client directs the User to interact with 284 the GS. This document defines the interaction modes: "redirect", 285 "indirect", and "user_code" in Section 5 287 * *Client Handle* - a unique identifier at the GS for a Dynamic 288 Client for the Dynamic Client to refer to itself in subsequent 289 requests. 291 1.4. Notational Conventions 293 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 294 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 295 specification are to be interpreted as described in [RFC2119]. 297 Certain security-related terms are to be understood in the sense 298 defined in [RFC4949]. These terms include, but are not limited to, 299 "attack", "authentication", "authorization", "certificate", 300 "confidentiality", "credential", "encryption", "identity", "sign", 301 "signature", "trust", "validate", and "verify". 303 _[Editor: review terms]_ 305 Unless otherwise noted, all the protocol parameter names and values 306 are case sensitive. 308 Some protocol parameters are parts of a JSON document, and are 309 referred to in JavaScript notation. For example, foo.bar refers to 310 the "bar" boolean attribute in the "foo" object in the following 311 example JSON document: 313 { 314 "foo" : { 315 "bar": true 316 } 317 } 319 2. Sequences 321 Before any sequence, the Client needs to be manually or 322 programmatically configured for the GS. See GS Options Section 3.7 323 for details on programmatically acquiring GS metadata. 325 2.1. "redirect" Interaction 327 The Client is a web application and wants a Grant from the User: 329 +--------+ +-------+ 330 | Client | | GS | 331 | |--(1)--- Create Grant ----------->| | 332 | | | | 333 | |<--- Interaction Response ---(2)--| | +------+ 334 | | | | | User | 335 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 336 | | | |<--(4)-->| | 337 | | | | authN | | 338 | | | | | | 339 | | | |<--(5)-->| | 340 | | | | authZ | | 341 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 342 | | | | | | 343 | |--(7)--- Verify Grant ----------->| | +------+ 344 | | | | 345 | |<--------- Grant Response ---(8)--| | 346 | | | | 347 +--------+ +-------+ 349 1. *Create Grant* The Client creates a Request JSON document 350 Section 3.5 containing an interaction.redirect object and makes a 351 Create Grant request (Section 3.2) by sending the JSON with an 352 HTTP POST to the GS URI. 354 2. *Interaction Response* The GS determines that interaction with 355 the User is required and sends an Interaction Response 356 (Section 4.2) containing the Grant URI and an 357 interaction.redirect object. 359 3. *Interaction Transfer* The Client redirects the User to the 360 redirect_uri at the GS. 362 4. *User Authentication* The GS authenticates the User. 364 5. *User Authorization* If required, the GS interacts with the User 365 to determine which identity claims and/or authorizations in the 366 Grant Request are to be granted. 368 6. *Interaction Transfer* The GS redirects the User to the 369 completion_uri at the Client. 371 7. *Verify Grant* The Client makes an HTTP PATCH request to the 372 Grant URI passing the verification code (Section 3.3). 374 8. *Grant Response* The GS responds with a Grant Response 375 (Section 4.1). 377 2.2. "user_code" Interaction 379 A Client is on a device wants a Grant from the User: 381 +--------+ +-------+ 382 | Client | | GS | 383 | |--(1)--- Create Grant ----------->| | 384 | | | | 385 | |<--- Interaction Response ---(2)--| | +------+ 386 | | | | | User | 387 | |--(3)--- Read Grant ------------->| | | | 388 | | | |<--(4)-->| | 389 | | | | authN | | 390 | | | | | | 391 | | | |<--(5)---| | 392 | | | | code | | 393 | | | | | | 394 | | | |<--(6)-->| | 395 | | | | authZ | | 396 | | | | | | 397 | |<--------- Grant Response ---(7)--| | | | 398 | | | | | | 399 +--------+ | | | | 400 | | | | 401 +--------+ | | | | 402 | Client |<---- Information URI Redirect -- | - - - | --(8)---| | 403 | Server | | | | | 404 +--------+ +-------+ +------+ 406 1. *Create Grant* The Client creates a Request JSON document 407 Section 3.5 containing an interaction.user_code object and makes 408 a Create Grant request (Section 3.2) by sending the JSON with an 409 HTTP POST to the GS URI. 411 2. *Interaction Response* The GS determines that interaction with 412 the User is required and sends an Interaction Response 413 (Section 4.2) containing the Grant URI and an 414 interaction.user_code object. 416 3. *Read Grant* The Client makes an HTTP GET request to the Grant 417 URI. 419 4. *User Authentication* The User loads display_uri in their 420 browser, and the GS authenticates the User. 422 5. *User Code* The User enters the code at the GS. 424 6. *User Authorization* If required, the GS interacts with the User 425 to determine which identity claims and/or authorizations in the 426 Grant Request are to be granted. 428 7. *Grant Response* The GS responds with a Grant Response 429 (Section 4.1). 431 8. *Information URI Redirect* The GS redirects the User to the 432 information_uri provided by the Client. 434 2.3. Independent RO Authorization 436 The Client wants access to resources that require the GS to interact 437 with the RO, who is not interacting with the Client. The 438 authorization from the RO may take some time, so the GS instructs the 439 Client to wait and check back later. 441 +--------+ +-------+ 442 | Client | | GS | 443 | |--(1)--- Create Grant ----------->| | 444 | | | | 445 | |<---------- Wait Response ---(2)--| | +------+ 446 | (3) | | | | RO | 447 | Wait | | |<--(4)-->| | 448 | | | | AuthZ | | 449 | |--(5)--- Read Grant ------------->| | +------+ 450 | | | | 451 | |<--------- Grant Response --(6)---| | 452 | | | | 453 +--------+ +-------+ 455 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 456 and sends it with an HTTP POST to the GS GS URI. 458 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 459 containing the Grant URI and the "wait" attribute. 461 3. *Client Waits* The Client waits for the time specified in the 462 "wait" attribute. 464 4. *RO AuthZ* The GS interacts with the RO to determine which 465 identity claims and/or resource authorizations in the Grant 466 Request are to be granted. 468 5. *Read Grant* The Client does an HTTP GET of the Grant URI 469 (Section 3.4). 471 6. *Grant Response* The GS responds with a Grant Response 472 (Section 4.1). 474 2.4. Resource Server Access 476 The Client received an AZ URI from the GS. The Client acquires an 477 access token, calls the RS, and later the access token expires. The 478 Client then gets a fresh access token. 480 +--------+ +----------+ +-------+ 481 | Client | | Resource | | GS | 482 | |--(1)--- Access Resource --->| Server | | | 483 | |<------- Resource Response --| (RS) | | | 484 | | | | | | 485 | |--(2)--- Access Resource --->| | | | 486 | |<------- Error Response -----| | | | 487 | | | | | | 488 | | +----------+ | | 489 | | | | 490 | |--(3)--- Read AuthZ ---------------------->| | 491 | |<------- AuthZ Response -------------------| | 492 | | | | 493 +--------+ +-------+ 495 1. *Resource Request* The Client accesses the RS with the access 496 token per Section 6 and receives a response from the RS. 498 2. *Resource Request* The Client attempts to access the RS, but 499 receives an error indicating the access token needs to be 500 refreshed. 502 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.6) with an 503 HTTP GET to the AZ URI and receives an Response JSON 504 "authorization" object (Section 4.4.4) with a fresh access token. 506 3. GS APIs 508 *Client Authentication* 510 All GS APIs except for GS Options require the Client to authenticate. 511 Authentication mechanisms include: 513 * JOSE Authentication [JOSE_Authentication] 515 * [Others TBD]* 517 3.1. GS API Table 519 +==============+=============+========+=============================+ 520 | request | http method | uri | response | 521 +==============+=============+========+=============================+ 522 | GS Options | OPTIONS | GS URI | metadata | 523 +--------------+-------------+--------+-----------------------------+ 524 | Create Grant | POST | GS URI | interaction, | 525 | | | | wait, or grant | 526 +--------------+-------------+--------+-----------------------------+ 527 | Verify Grant | PATCH | Grant | grant | 528 | | | URI | | 529 +--------------+-------------+--------+-----------------------------+ 530 | Read Grant | GET | Grant | wait, or grant | 531 | | | URI | | 532 +--------------+-------------+--------+-----------------------------+ 533 | Read AuthZ | GET | AZ URI | authorization | 534 +--------------+-------------+--------+-----------------------------+ 536 Table 1 538 3.2. Create Grant 540 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 541 document to the GS URI. This is a Grant Request. 543 The JSON document MUST include the following from the Request JSON 544 Section 3.5: 546 * iat 548 * nonce 550 * uri - MUST be set to the GS URI 552 * method - MUST be "POST" 554 * client 556 and MAY include the following from Request JSON Section 3.5 558 * user 560 * interaction 561 * authorization or authorizations 563 * claims 565 The GS MUST respond with one of Grant Response Section 4.1, 566 Interaction Response Section 4.2, Wait Response Section 4.3, or one 567 of the following errors: 569 * TBD 571 from Error Responses Section 7. 573 Following is a non-normative example of a web application Client 574 requesting identity claims about the User and read access to the 575 User's contacts: 577 Example 1 579 { 580 "iat" : 15790460234, 581 "uri" : "https://as.example/endpoint", 582 "method" : "POST, 583 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 584 "client": { 585 "display": { 586 "name" : "SPA Display Name", 587 "uri" : "https://spa.example/about" 588 } 589 }, 590 "interaction": { 591 "redirect": { 592 "completion_uri" : "https://web.example/return" 593 }, 594 "global" : { 595 "ui_locals" : "de" 596 } 597 }, 598 "authorization": { 599 "type" : "oauth_scope", 600 "scope" : "read_contacts" 601 }, 602 "claims": { 603 "oidc": { 604 "id_token" : { 605 "email" : { "essential" : true }, 606 "email_verified" : { "essential" : true } 607 }, 608 "userinfo" : { 609 "name" : { "essential" : true }, 610 "picture" : null 611 } 612 } 613 } 614 } 616 Following is a non-normative example of a device Client requesting 617 access to play music using "oauth_rich": 619 Example 2 621 { 622 "iat" : 15790460234, 623 "uri" : "https://as.example/endpoint", 624 "method" : "POST, 625 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 626 "client": { 627 "id" : "di3872h34dkJW" 628 }, 629 "interaction": { 630 "indirect": { 631 "information_uri": "https://device.example/c/indirect" 632 }, 633 "user_code": { 634 "information_uri": "https://device.example/c/user_code" 635 } 636 }, 637 "authorization": { 638 "type" : "oauth_rich", 639 "scope" : "play_music", 640 "authorization_details" [ 641 { 642 "type": "customer_information", 643 "locations": [ 644 "https://example.com/customers", 645 ] 646 "actions": [ 647 "read" 648 ], 649 "datatypes": [ 650 "contacts", 651 "photos" 652 ] 653 } 654 ] 655 } 656 } 658 3.3. Verify Grant 660 The Client verifies a Grant by doing an HTTP PATCH of a JSON document 661 to the Grant URI. The Client MUST only verify a Grant once. 663 The JSON document MUST include the following from the Request JSON 664 Section 3.5: 666 * iat 667 * nonce 669 * uri - MUST be set to the Grant URI 671 * method - MUST be PATCH 673 * interaction.redirection.verification - MUST be the verification 674 code received per Section 5.1.1. 676 Following is a non-normative example: 678 { 679 "iat" : 15790460235, 680 "uri" : "https://as.example/endpoint/grant/example1", 681 "method" : "PATCH, 682 "nonce" : "9b6afd70-2036-47c9-b953-5dd1fd0c699a", 683 "interaction": { 684 "redirect": { 685 "verification" : "cb4aa22d-2fe1-4321-b87e-bbaa66fbe707" 686 } 687 } 688 } 690 The GS MUST respond with one of Grant Response Section 4.1 or one of 691 the following errors: 693 * TBD 695 3.4. Read Grant 697 The Client reads a Grant by doing an HTTP GET of the corresponding 698 Grant URI. The Client MAY read a Grant until it expires or has been 699 invalidated. 701 The GS MUST respond with one of Grant Response Section 4.1, Wait 702 Response Section 4.3, or one of the following errors: 704 * TBD 706 3.5. Request JSON 708 * *iat* - the time of the request as a NumericDate. 710 * *nonce* - a unique identifier for this request. Note the Grant 711 Response MUST contain a matching "nonce" attribute value. 713 * *uri* - the URI being invoked 714 * *method* - the HTTP method being used 716 3.5.1. "client" Object 718 The client object MUST only one of the following: 720 * *id* - the Client ID the GS has for a Registered Client. 722 * *handle* - the Client Handle the GS previously provided a Dynamic 723 Client 725 * *display* - the display object contains the following attributes: 727 - *name* - a string that represents the Dynamic Client 729 - *uri* - a URI representing the Dynamic Client 731 The GS will show the the User the display.name and display.uri values 732 when prompting for authorization. 734 _[Editor: a max length for the name and URI so a GS can reserve 735 appropriate space?]_ 737 3.5.2. "interaction" Object 739 The interaction object contains one or more interaction mode objects 740 per Section 5 representing the interactions the Client is willing to 741 provide the User. In addition to the interaction mode objects, the 742 interaction object may contain the "global" object; 744 * *global* - an optional object containing parameters that are 745 applicable for all interaction modes. Only one attribute is 746 defined in this document: 748 - *ui_locales* - End-User's preferred languages and scripts for 749 the user interface, represented as a space-separated list of 750 [RFC5646] language tag values, ordered by preference. This 751 attribute is OPTIONAL. 753 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 754 a JSON array?]_ 756 3.5.3. "user" Object 758 * *identifiers* - The identifiers MAY be used by the GS to improve 759 the User experience. This object contains one or more of the 760 following identifiers for the User: 762 - *phone_number* - contains a phone number per Section 5 of 763 [RFC3966]. 765 - *email* - contains an email address per [RFC5322]. 767 - *oidc* - is an object containing both the "iss" and "sub" 768 attributes from an OpenID Connect ID Token [OIDC] Section 2. 770 * *claims* - an optional object containing one or more assertions 771 the Client has about the User. 773 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 774 Section 2. 776 3.5.4. "authorization" Object 778 * *type* - one of the following values: "oauth_scope" or 779 "oauth_rich". Extensions MAY define additional types, and the 780 required attributes. This attribute is REQUIRED. 782 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 783 section 3.3. MUST be included if type is "oauth_scope". MAY be 784 included if type is "oauth_rich". 786 * *authorization_details* - an authorization_details JSON array of 787 objects per [RAR]. MUST be included if type is "oauth_rich". 788 MUST not be included if type is "oauth_scope" 790 _[Editor: details may change as the RAR document evolves]_ 792 3.5.5. "authorizations" Object 794 One or more key / value pairs, where each unique key is created by 795 the client, and the value is an authorization object per 796 Section 3.5.4. 798 3.5.6. "claims" Object 800 Includes one or more of the following: 802 * *oidc* - an object that contains one or both of the following 803 objects: 805 - *userinfo* - Claims that will be returned as a JSON object 807 - *id_token* - Claims that will be included in the returned ID 808 Token. If the null value, an ID Token will be returned 809 containing no additional Claims. 811 The contents of the userinfo and id_token objects are Claims as 812 defined in [OIDC] Section 5. 814 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 815 per [OIDC4IA]. 817 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 818 requested.]_[W3C_VC] 820 3.6. Read Authorization 822 The Client acquires and refreshes an Authorization by doing an HTTP 823 GET to the corresponding AZ URI. 825 The GS MUST respond with a Authorization JSON document Section 4.5, 826 or one of the following errors: 828 * TBD 830 from Error Responses Section 7. 832 3.7. GS Options 834 The Client can get the metadata for the GS by doing an HTTP OPTIONS 835 of the corresponding GS URI. This is the only API where the GS MAY 836 respond to an unauthenticated request. 838 The GS MUST respond with the the following JSON document: 840 * *uri* - the GS URI. 842 * *client_authentication* - a JSON array of the Client 843 Authentication mechanisms supported by the GS 845 * *interactions* - a JSON array of the interaction modes supported 846 by the GS. 848 * *authorization* - an object containing the authorizations the 849 Client may request from the GS, if any. 851 - Details TBD 853 * *claims* - an object containing the identity claims the Client may 854 request from the GS, if any, and what public keys the claims will 855 be signed with. 857 - Details TBD 859 * *algorithms* - a JSON array of the cryptographic algorithms 860 supported by the GS. [details TBD]* 862 * *features* - an object containing feature support 864 - *authorizations* - boolean indicating if a request for more 865 than one authorization in a request is supported. 867 or one of the following errors: 869 * TBD 871 from Error Responses Section 7. 873 4. GS Responses 875 There are three successful responses to a Grant Request: Grant 876 Response, Interaction Response, or Wait Response. 878 4.1. Grant Response 880 The Grant Response MUST include the following from the Response JSON 881 Section 4.4 883 * iat 885 * nonce 887 * uri 889 and MAY include the following from the Response JSON Section 4.4 891 * client.handle 893 * authorization or authorizations 895 * claims 897 * expires_in 899 * warnings 901 Example non-normative Grant Response JSON document for Example 1 in 902 Section 3.2: 904 { 905 "iat" : 15790460234, 906 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 907 "uri" : "https://as.example/endpoint/grant/example1", 908 "expires_in" : 300 909 "authorization": { 910 "access": { 911 "type" : "oauth_scope", 912 "scope" : "read_contacts" 913 }, 914 "expires_in" : 3600, 915 "mechanism" : "bearer", 916 "token" : "eyJJ2D6.example.access.token.mZf9p" 917 }, 918 "claims": { 919 "oidc": { 920 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 921 "userinfo" : { 922 "name" : "John Doe", 923 "picture" : "https://photos.example/p/eyJzdkiO" 924 } 925 } 926 } 927 } 929 Note in this example the access token can not be refreshed, and 930 expires in an hour. 932 Example non-normative Grant Response JSON document for Example 2 in 933 Section 3.2: 935 { 936 "iat" : 15790460234, 937 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 938 "uri" : "https://as.example/endpoint/grant/example2", 939 "authorization": { 940 "uri" : "https://as.example/endpoint/authz/example2" 941 } 942 } 944 Note in this example the GS only provided the AZ URI, and Client must 945 acquire the Authorization per Section 3.6 947 4.2. Interaction Response 949 The Interaction Response MUST include the following from the Response 950 JSON Section 4.4 951 * iat 953 * nonce 955 * uri 957 * interaction 959 and MAY include the following from the Response JSON Section 4.4 961 * user 963 * wait 965 * warnings 967 A non-normative example of an Interaction Response follows: 969 { 970 "iat" : 15790460234, 971 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 972 "uri" : "https://as.example/endpoint/grant/example4", 973 "interaction" : { 974 ""redirect" : { 975 "redirect_uri" : "https://as.example/i/example4" 976 } 977 } 978 } 980 4.3. Wait Response 982 The Wait Response MUST include the following from the Response JSON 983 Section 4.4 985 * iat 987 * nonce 989 * uri 991 * wait 993 and MAY include the following from the Response JSON Section 4.4 995 * warnings 997 A non-normative example of Wait Response follows: 999 { 1000 "iat" : 15790460234, 1001 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1002 "uri" : "https://as.example/endpoint/grant/example5", 1003 "wait" : 300 1004 } 1006 4.4. Response JSON 1008 Details of the JSON document: 1010 * *iat* - the time of the response as a NumericDate. 1012 * *nonce* - the nonce that was included in the Request JSON 1013 Section 3.5. 1015 * *uri* - the Grant URI. 1017 * *wait* - a numeric value representing the number of seconds the 1018 Client should want before making a Read Grant request to the Grant 1019 URI. 1021 * *expires_in* - a numeric value specifying how many seconds until 1022 the Grant expires. This attribute is OPTIONAL. 1024 4.4.1. "client" Object 1026 The GS may 1028 4.4.2. "interaction" Object 1030 If the GS wants the Client to start the interaction, the GS MUST 1031 return an interaction object containing one or more interaction mode 1032 responses per Section 5 to one or more of the interaction mode 1033 requests provided by the Client. 1035 4.4.3. "user" Object 1037 * *exists* - a boolean value indicating if the GS has a user with 1038 one or more of the provided identifiers in the Request 1039 user.identifiers object Section 3.5.3 1041 4.4.4. "authorization" Object 1043 The authorization object MUST contain only a "uri" attribute or the 1044 following from Authorization JSON Section 4.5: 1046 * mechanism 1047 * token 1049 The authorization object MAY contain any of the following from 1050 Authorization JSON Section 4.5: 1052 * access 1054 * expires_in 1056 * uri 1058 If there is no "uri" attribute, the access token can not be 1059 refreshed. If only the "uri" attribute is present, the Client MUST 1060 acquire the Authorization per Section 3.6 1062 4.4.5. "authorizations" Object 1064 A key / value pair for each key in the Grant Request "authorizations" 1065 object, and the value is per Section 4.4.4. 1067 4.4.6. "claims" Object 1069 The claims object is a response to the Grant Request "claims" object 1070 Section 3.5.4. 1072 * *oidc* 1074 - *id_token* - an OpenID Connect ID Token containing the Claims 1075 the User consented to be released. 1077 - *userinfo* - the Claims the User consented to be released. 1079 Claims are defined in [OIDC] Section 5. 1081 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1082 per [OIDC4IA]. 1084 * *vc* 1086 The verified claims the user consented to be released. _[Editor: 1087 details TBD]_ 1089 4.4.7. "warnings" JSON Array 1091 Includes zero or more warnings from Section 8, 1093 4.5. Authorization JSON 1095 The Authorization JSON is the contents of a Grant Response 1096 "authorization" object Section 4.4.5 or the response to a Read AuthZ 1097 request by the Client Section 3.6. 1099 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1100 See the "type" object in Section 3.5.4 for details. 1102 * *mechanism* - the RS access mechanism. This document defines the 1103 "bearer" mechanism as defined in Section 6 1105 * *token* - the access token for accessing an RS. 1107 * *expires_in* - a numeric value specifying how many seconds until 1108 the access token expires. 1110 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1112 * *access* - an object containing the access granted: 1114 - *type* - the type of claim request: "oauth_scope" or 1115 "oauth_rich". See the "type" object in Section 3.5.4 for 1116 details. This attribute is REQUIRED. 1118 - *scope* - the scopes the Client was granted authorization for. 1119 This will be all, or a subset, of what was requested. This 1120 attribute is OPTIONAL. 1122 - *authorization_details* - the authorization details granted per 1123 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1125 _[Editor: would an optional expiry for the Authorization be useful?]_ 1127 The following is a non-normative example of Authorization JSON: 1129 { 1130 "mechanism" : "bearer", 1131 "token" : "eyJJ2D6.example.access.token.mZf9p" 1132 "expires_in" : 3600, 1133 "uri" : "https://as.example/endpoint/authz/example2", 1134 "access": { 1135 "type" : "oauth_scope", 1136 "scope" : "read_calendar write_calendar" 1137 } 1138 } 1140 4.6. Response Verification 1142 On receipt of a response, the Client MUST verify the following: 1144 * TBD 1146 5. Interaction Modes 1148 This document defines three interaction modes: "redirect", 1149 "indirect", and "user_code". Extensions may define additional 1150 interaction modes. 1152 The "global" attribute is reserved in the interaction object for 1153 attributes that apply to all interaction modes. 1155 5.1. "redirect" 1157 A Redirect Interaction is characterized by the Client redirecting the 1158 User's browser to the GS, the GS interacting with the User, and then 1159 GS redirecting the User's browser back to the Client. The GS 1160 correlates the Grant Request with the unique redirect_uri, and the 1161 Client correlates the Grant Request with the unique completion_uri. 1163 *The request "interaction" object contains:* 1165 * *completion_uri* a unique URI at the Client that the GS will 1166 return the User to. The URI MUST not contain the "nonce" from the 1167 Grant Request, and MUST not be guessable. This attribute is 1168 REQUIRED. 1170 *The response "interaction" object contains:* 1172 * *redirect_uri* a unique URI at the GS that the Client will 1173 redirect the User to. The URI MUST not contain the "nonce" from 1174 the Grant Request, and MUST not be guessable. This attribute is 1175 REQUIRED. 1177 * *verification* a boolean value indicating the GS requires the 1178 Client to make a Verify Grant request.(Section 3.3) 1180 5.1.1. "redirect" verification 1182 If the GS indicates that Grant Verification is required, the GS MUST 1183 add a 'verification' query parameter with a value of a unique 1184 verification code to the completion_uri. 1186 On receiving the verification code in the redirect from the GS, the 1187 Client makes a Verify Grant request (Section 3.3) with the 1188 verification code. 1190 5.2. "indirect" 1192 An Indirect Interaction is characterized by the Client causing the 1193 User's browser to load the indirect_uri at GS, the GS interacting 1194 with the User, and then the GS MAY optionally redirect the User's 1195 Browser to a information_uri. There is no mechanism for the GS to 1196 redirect the User's browser back to the Client. 1198 Examples of how the Client may initiate the interaction are encoding 1199 the indirect_uri as a code scannable by the User's mobile device, or 1200 launching a system browser from a command line interface (CLI) 1201 application. 1203 The "indirect" mode is susceptible to session fixation attacks. See 1204 TBD in the Security Considerations for details. 1206 *The request "interaction" object contains:* 1208 * *information_uri* an OPTIONAL URI that the GS will redirect the 1209 User's browser to after GS interaction. 1211 *The response "interaction" object contains:* 1213 * *indirect_uri* the URI the Client will cause to load in the User's 1214 browser. The URI SHOULD be short enough to be easily encoded in a 1215 scannable code. The URI MUST not contain the "nonce" from the 1216 Grant Request, and MUST not be guessable. _[Editor: recommend a 1217 maximum length?]_ 1219 5.3. "user_code" 1221 An Indirect Interaction is characterized by the Client displaying a 1222 code and a URI for the User to load in a browser and then enter the 1223 code. _[Editor: recommend a minimum entropy?]_ 1225 *The request "interaction" object contains:* 1227 * *information_uri* an OPTIONAL URI that the GS will redirect the 1228 User's browser to after GS interaction. 1230 *The response "interaction" object contains:* 1232 * *code* the code the Client displays to the User to enter at the 1233 display_uri. This attribute is REQUIRED. 1235 * *display_uri* the URI the Client displays to the User to load in a 1236 browser to enter the code. 1238 6. RS Access 1240 The mechanism the Client MUST use to access an RS is in the 1241 Authorization JSON "mechanism" attribute Section 4.4.4. 1243 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1245 The "jose" and "jose+body" mechanisms are defined in 1246 [JOSE_Authentication] 1248 A non-normative "bearer" example of the HTTP request headers follows: 1250 GET /calendar HTTP/2 1251 Host: calendar.example 1252 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1254 7. Error Responses 1256 * TBD 1258 8. Warnings 1260 Warnings assist a Client in detecting non-fatal errors. 1262 * TBD 1264 9. Extensibility 1266 This standard can be extended in a number of areas: 1268 * *Client Authentication Mechanisms* 1270 - An extension could define other mechanisms for the Client to 1271 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1272 Signing. Constrained environments could use CBOR [RFC7049] 1273 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1274 [RFC8323] instead of HTTP/2. 1276 * *Grant* 1278 - An extension can define new objects in the Grant Request and 1279 Grant Response JSON that return new URIs. 1281 * *Top Level* 1282 - Top level objects SHOULD only be defined to represent 1283 functionality other the existing top level objects and 1284 attributes. 1286 * *"client" Object* 1288 - Additional information about the Client that the GS would 1289 require related to an extension. 1291 * *"user" Object* 1293 - Additional information about the User that the GS would require 1294 related to an extension. 1296 * *"authorization" Object* 1298 - Additional authorization schemas in addition to OAuth 2.0 1299 scopes and RAR. 1301 * *"claims" Object* 1303 - Additional claim schemas in addition to OpenID Connect claims 1304 and Verified Credentials. 1306 * *interaction modes* 1308 - Additional types of interactions a Client can start with the 1309 User. 1311 * *Continuous Authentication* 1313 - An extension could define a mechanism for the Client to 1314 regularly provide continuous authentication signals and receive 1315 responses. 1317 _[Editor: do we specify access token introspection in this document, 1318 or leave that to an extension?]_ 1320 10. Rational 1322 1. *Why do Clients now always use Asymetric cryptography? Why not 1323 keep the client secret?* 1325 In the past, asymetric cryptography was relatively computational 1326 expensive. Modern browsers now have asymetric cryptographic 1327 APIs available, and modern hardware has significantly reduced 1328 the computational impact. 1330 2. *Why have both Client ID and Client Handle?* 1332 While they both refer to a Client in the protocol, the Client ID 1333 refers to a pre-registered client,and the Client Handle is 1334 specific to an instance of a Dynamic Client. Using separate 1335 terms clearly differentiates which identifier is being presented 1336 to the GS. 1338 3. *Why allow Client and GS to negotiate the user interaction 1339 mode?* 1341 The Client knows what interaction modes it is capable of, and 1342 the GS knows which interaction modes it will permit for a given 1343 Grant Request. The Client can then present the intersection to 1344 the User to choose which one is preferred. For example, while a 1345 device based Client may be willing to do both "indirect" and 1346 "user_code", a GS may not enable "indirect" for concern of a 1347 session fixation attack. Additional interaction modes will 1348 likely become available which allows new modes to be negotiated 1349 between Client and GS as each adds additional interaction modes. 1351 4. *Why have both claims and authorizations?* 1353 There are use cases for each that are independent: 1354 authenticating a user and providing claims vs granting access to 1355 a resource. A request for an authorization returns an access 1356 token which may have full CRUD capabilities, while a request for 1357 a claim returns the claim about the User - with no create, 1358 update or delete capabilities. While the UserInfo endpoint in 1359 OIDC may be thought of as a resource, separating the concepts 1360 and how they are requested keeps each of them simpler in the 1361 Editor's opinion. :) 1363 5. *Why do some of the JSON objects only have one child, such as 1364 the identifiers object in the user object in the Grant Request?* 1366 It is difficult to forecast future use cases. Having more 1367 resolution may mean the difference between a simple extension, 1368 and a convoluted extension. For example, the "global" object in 1369 the "interaction" object allows new global parameters to be 1370 added without impacting new interaction modes. 1372 6. *Why is the "iss" included in the "oidc" identifier object? 1373 Would the "sub" not be enough for the GS to identify the User?* 1374 This decouples the GS from the OpenID Provider (OP). The GS 1375 identifier is the GS URI, which is the endpoint at the GS. The 1376 OP issuer identifier will likely not be the same as the GS URI. 1377 The GS may also provide claims from multiple OPs. 1379 7. *Why is there not a UserInfo endpoint as there is with OpenID 1380 Connect?* 1382 Since the Client can Read Grant at any time, it get the same 1383 functionality as the UserInfo endpoint, without the Client 1384 having to manage a separate access token and refresh token. If 1385 the Client would like additional claims, it can Update Grant, 1386 and the GS will let the Client know if an interaction is 1387 required to get any of the additional claims, which the Client 1388 can then start. 1390 _[Editor: is there some other reason to have the UserInfo 1391 endpoint?]_ 1393 8. *Why use URIs for the Grant and Authorization?* 1395 * Grant URI and AZ URI are defined to start with the GS URI, 1396 allowing the Client, and GS to determine which GS a Grant or 1397 Authorization belongs to. 1399 * URIs also enable a RESTful interface to the GS functionality. 1401 * A large scale GS can easily separate out the services that 1402 provide functionality as routing of requests can be done at 1403 the HTTP layer based on URI and HTTP method. This allows a 1404 separation of concerns, independent deployment, and 1405 resiliency. 1407 9. *Why use the OPTIONS method on the GS URI? Why not use a .well- 1408 known mechanism?* 1410 Having the GS URI endpoint respond to the metadata allows the GS 1411 to provide Client specific results using the same Client 1412 authentication used for other requests to the GS. It also 1413 reduces the risk of a mismatch between the advertised metadata, 1414 and the actual metadata. A .well-known discovery mechanism may 1415 be defined to resolve from a hostname to the GS URI. 1417 10. *Why is there a Verify Grant? The Client can protect itself 1418 from session fixation without it.* 1419 Client implementations may not always follow the best practices. 1420 The Verify Grant allows the GS to ensure there is not a session 1421 fixation as the instance of the Client making creating the Grant 1422 is the one that gets the verification code in the redirect. 1424 11. Acknowledgments 1426 This draft derives many of its concepts from Justin Richer's 1427 Transactional Authorization draft [TxAuth]. 1429 Additional thanks to Justin Richer and Annabelle Richard Backman for 1430 their strong critique of earlier drafts. 1432 12. IANA Considerations 1434 TBD 1436 13. Security Considerations 1438 TBD 1440 14. References 1442 14.1. Normative References 1444 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1445 Requirement Levels", BCP 14, RFC 2119, 1446 DOI 10.17487/RFC2119, March 1997, 1447 . 1449 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1450 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1451 . 1453 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1454 DOI 10.17487/RFC5322, October 2008, 1455 . 1457 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1458 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1459 . 1461 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1462 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1463 September 2009, . 1465 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1466 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1467 . 1469 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1470 Framework: Bearer Token Usage", RFC 6750, 1471 DOI 10.17487/RFC6750, October 2012, 1472 . 1474 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1475 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1476 . 1478 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1479 Interchange Format", STD 90, RFC 8259, 1480 DOI 10.17487/RFC8259, December 2017, 1481 . 1483 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1484 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1485 . 1487 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1488 Assurance 1.0", October 2019, . 1491 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1492 Rich Authorization Requests", January 2020, 1493 . 1495 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1496 Credentials Data Model 1.0", November 2019, 1497 . 1499 [JOSE_Authentication] 1500 Hardt, D., "JOSE Authentication", June 2020, 1501 . 1503 [GNAP_Advanced] 1504 Hardt, D., "The Grant Negotiation and Authorization 1505 Protocol - Advanced Features", June 2020, 1506 . 1508 14.2. Informative References 1510 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1511 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1512 October 2013, . 1514 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1515 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1516 . 1518 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1519 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1520 Application Protocol) over TCP, TLS, and WebSockets", 1521 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1522 . 1524 [browser_based_apps] 1525 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1526 Apps", September 2019, . 1529 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1530 identification and data capture techniques - QR Code bar 1531 code symbology specification", February 2015, 1532 . 1534 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1535 . 1538 Appendix A. Document History 1540 A.1. draft-hardt-xauth-protocol-00 1542 * Initial version 1544 A.2. draft-hardt-xauth-protocol-01 1546 * text clean up 1548 * added OIDC4IA claims 1550 * added "jws" method for accessing a resource. 1552 * renamed Initiation Request -> Grant Request 1554 * renamed Initiation Response -> Interaction Response 1556 * renamed Completion Request -> Authorization Request 1558 * renamed Completion Response -> Grant Request 1560 * renamed completion handle -> authorization handle 1561 * added Authentication Request, Authentication Response, 1562 authentication handle 1564 A.3. draft-hardt-xauth-protocol-02 1566 * major rewrite 1568 * handles are now URIs 1570 * the collection of claims and authorizations are a Grant 1572 * an Authorization is its own type 1574 * lots of sequences added 1576 A.4. draft-hardt-xauth-protocol-03 1578 * fixed RO definition 1580 * improved language in Rationals 1582 * added user code interaction method, and aligned qrcode interaction 1583 method 1585 * added information_uri for code flows 1587 A.5. draft-hardt-xauth-protocol-04 1589 * renamed interaction uris to have purpose specific names 1591 A.6. draft-hardt-xauth-protocol-05 1593 * separated claims from identifiers in request user object 1595 * simplified reciprocal grant flow 1597 * reduced interactions to redirect and indirect 1599 * simplified interaction parameters 1601 * added in language for Client to verify interaction completion 1603 * added Verify Grant API and Interaction Nonce 1605 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1606 operation. 1608 A.7. draft-hardt-xauth-protocol-06 1610 * fixup examples to match specification 1612 A.8. draft-hardt-xauth-protocol-07 1614 * refactored interaction request and response syntax, and enabled 1615 interaction mode negotiation 1617 * generation of client handle by GS for dynamic clients 1619 * renamed title to Grant Negotiation and Authorization Protocol. 1620 Preserved draft-hardt-xauth-protocol filename to ease tracking 1621 changes. 1623 * changed Authorizations to be key / value pairs (aka dictionary) 1624 instead of a JSON array 1626 A.9. draft-hardt-xauth-protocol-08 1628 * split document into three documents: core, advanced, and JOSE 1629 authentication. 1631 * grouped access granted into "access" object in Authorization JSON 1633 * added warnings object to the Grant Response JSON 1635 A.10. draft-hardt-xauth-protocol-09 1637 * added editorial note that this document should be referred to as 1638 XAuth 1640 A.11. draft-hardt-xauth-protocol-10 1642 * added example of RAR authorization request 1644 * fixed typos 1646 A.12. draft-hardt-xauth-protocol-11 1648 * renamed authorization_uri to interaction_uri to avoid confusion 1649 with AZ URI 1651 * made URI names more consistent 1653 - renamed completion_uri to information_uri 1655 - renamed redirect_uri to completion_uri 1656 - renamed interaction_uri to redirect_uri 1658 - renamed short_uri to indirect_uri 1660 * editorial fixes 1662 * renamed http verb to method 1664 * added Verify Grant and verification parameters 1666 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1668 *Changed Features* 1670 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1672 * The Client always uses a private asymetric key to authenticate to 1673 the GS. There is no client secret. i 1675 * The Client initiates the protocol by making a signed request 1676 directly to the GS instead of redirecting the User to the GS. 1678 * The Client does not pass any parameters in redirecting the User to 1679 the GS. 1681 * The refresh_token has been replaced with a AZ URI that both 1682 represents the authorization, and is the URI for obtaining a fresh 1683 access token. 1685 * The Client can request identity claims to be returned independent 1686 of the ID Token. There is no UserInfo endpoint to query claims as 1687 there is in OpenID Connect. 1689 * The GS URI is the token endpoint. 1691 *Preserved Features* 1693 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1694 2.0. 1696 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1698 * No change is required by the Client or the RS for accessing 1699 existing bearer token protected APIs. 1701 *New Features* 1702 * All Client calls to the GS are authenticated with asymetric 1703 cryptography 1705 * A Grant represents both the user identity claims and RS access 1706 granted to the Client. 1708 * Support for scannable code initiated interactions. 1710 * Highly extensible per Section 9. 1712 Author's Address 1714 Dick Hardt (editor) 1715 SignIn.Org 1716 United States 1718 Email: dick.hardt@gmail.com