idnits 2.17.1 draft-hardt-xauth-protocol-10.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 37 instances of too long lines in the document, the longest one being 1 character in excess of 72. 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: * *redirect_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: * *authorization_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: * *short_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 (8 June 2020) is 1417 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) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 6 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 8 June 2020 5 Expires: 10 December 2020 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-10 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 10 December 2020. 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. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 15 70 3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16 71 3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 16 72 3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 16 73 3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 17 74 3.4.4. "authorization" Object . . . . . . . . . . . . . . . 17 75 3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 17 76 3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 17 77 3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 18 78 3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 18 79 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 19 80 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 19 81 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 21 82 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 21 83 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 22 84 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 22 85 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 22 86 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 22 87 4.4.4. "authorization" Object . . . . . . . . . . . . . . . 23 88 4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 23 89 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 23 90 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 24 91 4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 24 92 4.6. Response Verification . . . . . . . . . . . . . . . . . . 25 93 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 25 94 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 25 95 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 26 98 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 27 99 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 27 100 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 27 101 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 27 102 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 28 103 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 104 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 105 13. Security Considerations . . . . . . . . . . . . . . . . . . . 30 106 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 107 14.1. Normative References . . . . . . . . . . . . . . . . . . 30 108 14.2. Informative References . . . . . . . . . . . . . . . . . 32 109 Appendix A. Document History . . . . . . . . . . . . . . . . . . 33 110 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 33 111 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 33 112 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 33 113 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 33 114 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 34 115 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 34 116 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 34 117 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 34 118 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 34 119 A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 35 120 A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 35 121 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 35 122 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36 124 1. Introduction 126 *EDITOR NOTE* 128 _This document captures a number of concepts that may be adopted by 129 the proposed GNAP working group. Please refer to this document as:_ 131 *XAuth* 133 _The use of GNAP in this document is not intended to be a declaration 134 of it being endorsed by the proposed GNAP working group._ 136 This document describes the core Grant Negotiation and Authorization 137 Protocol (GNAP). The protocol supports the widely deployed use cases 138 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 139 an extension of OAuth 2.0, as well as other extensions. Related 140 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 141 Authentication [JOSE_Authentication] that describes the JOSE 142 mechanisms for client authentication. 144 The technology landscape has changed since OAuth 2.0 was initially 145 drafted. More interactions happen on mobile devices than PCs. 146 Modern browsers now directly support asymetric cryptographic 147 functions. Standards have emerged for signing and encrypting tokens 148 with rich payloads (JOSE) that are widely deployed. 150 GNAP simplifies the overall architectural model, takes advantage of 151 today's technology landscape, provides support for all the widely 152 deployed use cases, offers numerous extension points, and addresses 153 many of the security issues in OAuth 2.0 by passing parameters 154 securely between parties, rather than via a browser redirection. . 156 While GNAP is not backwards compatible with OAuth 2.0, it strives to 157 minimize the migration effort. 159 GNAP centers around a Grant, a representation of the collection of 160 user identity claims and/or resource authorizations the Client is 161 requesting, and the resulting identity claims and/or resource 162 authorizations granted by the Grant Server (GS). 164 User consent is often required at the GS. GNAP enables a Client and 165 GS to negotiate the interaction mode for the GS to obtain consent. 167 The suggested pronunciation of GNAP is the same as the English word 168 "nap", a silent "g" as in "gnaw". 170 _[Editor: suggestions on how to improve this are welcome!]_ 172 1.1. Parties 174 The parties and their relationships to each other: 176 +--------+ +------------+ 177 | User | | Resource | 178 | | | Owner (RO) | 179 +--------+ +------------+ 180 | \ / | 181 | \ / | 182 | \ / | 183 | \ / | 184 +--------+ +---------------+ +------------+ 185 | Client |---->| Grant | | Resource | 186 | | (1) | Server (GS) | _ _ | Server | 187 | |<----| | | (RS) | 188 | | +---------------+ | | 189 | |-------------------------->| | 190 | | (2) | | 191 | |<--------------------------| | 192 +--------+ +------------+ 194 This document specifies interactions between the Client and GS (1), 195 and the Client and RS (2). 197 * *User* - the person interacting with the Client who has delegated 198 access to identity claims about themselves to the Grant Server 199 (GS), and can authenticate at the GS. 201 * *Client* - requests a Grant from the GS to access one or more 202 Resource Servers (RSs), and/or identity claims about the User. 203 The Grant may include access tokens that the Client uses to access 204 the RS. There are two types of Clients: Registered Clients and 205 Dynamic Clients. All Clients have a private asymetric key to 206 authenticate with the Grant Server. 208 * *Registered Client* - a Client that has registered with the GS and 209 has a Client ID to identify itself, and can prove it possesses a 210 key that is linked to the Client ID. The GS may have different 211 policies for what different Registered Clients can request. A 212 Registered Client MAY be interacting with a User. 214 * *Dynamic Client* - a Client that has not been previously 215 registered with the GS, and each instance will generate it's own 216 asymetric key pair so it can prove it is the same instance of the 217 Client on subsequent requests. The GS MAY return a Dynamic Client 218 a Client Handle for the Client to identify itself in subsequent 219 requests. A single-page application with no active server 220 component is an example of a Dynamic Client. A Dynamic Client 221 MUST be interacting with a User. 223 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 224 release of identity claims about the User. The GS may require 225 explicit consent from the RO or User to provide these to the 226 Client. A GS may support Registered Clients and/or Dynamic 227 Clients. The GS is a combination of the Authorization Server (AS) 228 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 230 * *Resource Server* (RS) - has API resources that require an access 231 token from the GS. Some, or all of the resources are owned by the 232 Resource Owner. 234 * *Resource Owner* (RO) - owns resources at the RS, and has 235 delegated RS access management to the GS. The RO may be the same 236 entity as the User, or may be a different entity that the GS 237 interacts with independently. GS and RO interactions are out of 238 scope of this document. 240 1.2. Reused Terms 242 * *access token* - an access token as defined in [RFC6749] 243 Section 1.4. 245 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 246 issued by the GS, or by other issuers. 248 * *Client ID* - a GS unique identifier for a Registered Client as 249 defined in [RFC6749] Section 2.2. 251 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 253 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 255 * *authN* - short for authentication. 257 * *authZ* - short for authorization. 259 1.3. New Terms 261 * *GS URI* - the endpoint at the GS the Client calls to create a 262 Grant, and is the unique identifier for the GS. 264 * *Grant* - the user identity claims and/or RS authorizations the GS 265 has granted to the Client. The GS MAY invalidate a Grant at any 266 time. 268 * *Grant URI* - the URI that represents the Grant. The Grant URI 269 MUST start with the GS URI. 271 * *Authorization* - the access granted by the RO to the Client and 272 contains an access token. The GS may invalidate an Authorization 273 at any time. 275 * *Authorization URI* (AZ URI) - the URI that represents the 276 Authorization the Client was granted by the RO. The AZ URI MUST 277 start with the GS URI. The AZ URI is used to refresh an access 278 token. 280 * *Interaction* - how the Client directs the User to interact with 281 the GS. This document defines the interaction modes: "redirect", 282 "indirect", and "user_code" in Section 5 284 * *Client Handle* - a unique identifier at the GS for a Dynamic 285 Client for the Dynamic Client to refer to itself in subsequent 286 requests. 288 1.4. Notational Conventions 290 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 291 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 292 specification are to be interpreted as described in [RFC2119]. 294 Certain security-related terms are to be understood in the sense 295 defined in [RFC4949]. These terms include, but are not limited to, 296 "attack", "authentication", "authorization", "certificate", 297 "confidentiality", "credential", "encryption", "identity", "sign", 298 "signature", "trust", "validate", and "verify". 300 _[Editor: review terms]_ 302 Unless otherwise noted, all the protocol parameter names and values 303 are case sensitive. 305 Some protocol parameters are parts of a JSON document, and are 306 referred to in JavaScript notation. For example, foo.bar refers to 307 the "bar" boolean attribute in the "foo" object in the following 308 example JSON document: 310 { 311 "foo" : { 312 "bar": true 313 } 314 } 316 2. Sequences 318 Before any sequence, the Client needs to be manually or 319 programmatically configured for the GS. See GS Options Section 3.6 320 for details on programmatically acquiring GS metadata. 322 2.1. "redirect" Interaction 324 The Client is a web application and wants a Grant from the User: 326 +--------+ +-------+ 327 | Client | | GS | 328 | |--(1)--- Create Grant ----------->| | 329 | | | | 330 | |<--- Interaction Response ---(2)--| | +------+ 331 | | | | | User | 332 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 333 | | | |<--(4)-->| | 334 | | | | authN | | 335 | | | | | | 336 | | | |<--(5)-->| | 337 | | | | authZ | | 338 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 339 | | | | | | 340 | |--(7)--- Read Grant ------------->| | +------+ 341 | | | | 342 | |<--------- Grant Response ---(8)--| | 343 | | | | 344 +--------+ +-------+ 346 1. *Create Grant* The Client creates a Request JSON document 347 Section 3.4 containing an interaction.redirect object and makes a 348 Create Grant request (Section 3.2) by sending the JSON with an 349 HTTP POST to the GS URI. 351 2. *Interaction Response* The GS determines that interaction with 352 the User is required and sends an Interaction Response 353 (Section 4.2) containing the Grant URI and an 354 interaction.redirect object. 356 3. *Interaction Transfer* The Client redirects the User to the 357 authorization_uri at the GS. 359 4. *User Authentication* The GS authenticates the User. 361 5. *User Authorization* If required, the GS interacts with the User 362 to determine which identity claims and/or authorizations in the 363 Grant Request are to be granted. 365 6. *Interaction Transfer* The GS redirects the User to the 366 redirect_uri at the Client. 368 7. *Read Grant* The Client makes an HTTP GET request to the Grant 369 URI. 371 8. *Grant Response* The GS responds with a Grant Response 372 (Section 4.1). 374 2.2. "user_code" Interaction 376 A Client is on a device wants a Grant from the User: 378 +--------+ +-------+ 379 | Client | | GS | 380 | |--(1)--- Create Grant ----------->| | 381 | | | | 382 | |<--- Interaction Response ---(2)--| | +------+ 383 | | | | | User | 384 | |--(3)--- Read Grant ------------->| | | | 385 | | | |<--(4)-->| | 386 | | | | authN | | 387 | | | | | | 388 | | | |<--(5)---| | 389 | | | | code | | 390 | | | | | | 391 | | | |<--(6)-->| | 392 | | | | authZ | | 393 | | | | | | 394 | |<--------- Grant Response ---(7)--| | | | 395 | | | | | | 396 +--------+ | | | | 397 | | | | 398 +--------+ | | | | 399 | Client |<----- Completion URI Redirect -- | - - - | --(8)---| | 400 | Server | | | | | 401 +--------+ +-------+ +------+ 403 1. *Create Grant* The Client creates a Request JSON document 404 Section 3.4 containing an interaction.user_code object and makes 405 a Create Grant request (Section 3.2) by sending the JSON with an 406 HTTP POST to the GS URI. 408 2. *Interaction Response* The GS determines that interaction with 409 the User is required and sends an Interaction Response 410 (Section 4.2) containing the Grant URI and an 411 interaction.user_code object. 413 3. *Read Grant* The Client makes an HTTP GET request to the Grant 414 URI. 416 4. *User Authentication* The User loads display_uri in their 417 browser, and the GS authenticates the User. 419 5. *User Code* The User enters the code at the GS. 421 6. *User Authorization* If required, the GS interacts with the User 422 to determine which identity claims and/or authorizations in the 423 Grant Request are to be granted. 425 7. *Grant Response* The GS responds with a Grant Response 426 (Section 4.1). 428 8. *Completion URI Redirect* The GS redirects the User to the 429 completion_uri provided by the Client. 431 2.3. Independent RO Authorization 433 The Client wants access to resources that require the GS to interact 434 with the RO, who is not interacting with the Client. The 435 authorization from the RO may take some time, so the GS instructs the 436 Client to wait and check back later. 438 +--------+ +-------+ 439 | Client | | GS | 440 | |--(1)--- Create Grant ----------->| | 441 | | | | 442 | |<---------- Wait Response ---(2)--| | +------+ 443 | (3) | | | | RO | 444 | Wait | | |<--(4)-->| | 445 | | | | AuthZ | | 446 | |--(5)--- Read Grant ------------->| | +------+ 447 | | | | 448 | |<--------- Grant Response --(6)---| | 449 | | | | 450 +--------+ +-------+ 452 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 453 and sends it with an HTTP POST to the GS GS URI. 455 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 456 containing the Grant URI and the "wait" attribute. 458 3. *Client Waits* The Client waits for the time specified in the 459 "wait" attribute. 461 4. *RO AuthZ* The GS interacts with the RO to determine which 462 identity claims and/or resource authorizations in the Grant 463 Request are to be granted. 465 5. *Read Grant* The Client does an HTTP GET of the Grant URI 466 (Section 3.3). 468 6. *Grant Response* The GS responds with a Grant Response 469 (Section 4.1). 471 2.4. Resource Server Access 473 The Client received an AZ URI from the GS. The Client acquires an 474 access token, calls the RS, and later the access token expires. The 475 Client then gets a fresh access token. 477 +--------+ +----------+ +-------+ 478 | Client | | Resource | | GS | 479 | |--(1)--- Access Resource --->| Server | | | 480 | |<------- Resource Response --| (RS) | | | 481 | | | | | | 482 | |--(2)--- Access Resource --->| | | | 483 | |<------- Error Response -----| | | | 484 | | | | | | 485 | | +----------+ | | 486 | | | | 487 | |--(3)--- Read AuthZ ---------------------->| | 488 | |<------- AuthZ Response -------------------| | 489 | | | | 490 +--------+ +-------+ 492 1. *Resource Request* The Client accesses the RS with the access 493 token per Section 6 and receives a response from the RS. 495 2. *Resource Request* The Client attempts to access the RS, but 496 receives an error indicating the access token needs to be 497 refreshed. 499 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.5) with an 500 HTTP GET to the AZ URI and receives an Response JSON 501 "authorization" object (Section 4.4.4) with a fresh access token. 503 3. GS APIs 505 *Client Authentication* 507 All GS APIs except for GS Options require the Client to authenticate. 508 Authentication mechanisms include: 510 * JOSE Authentication [JOSE_Authentication] 512 * [Others TBD]* 514 3.1. GS API Table 516 +--------------+-----------+--------+-----------------------------+ 517 | request | http verb | uri | response | 518 +==============+===========+========+=============================+ 519 | GS Options | OPTIONS | GS URI | metadata | 520 +--------------+-----------+--------+-----------------------------+ 521 | Create Grant | POST | GS URI | interaction, wait, or grant | 522 +--------------+-----------+--------+-----------------------------+ 523 | Read Grant | GET | Grant | wait, or grant | 524 | | | URI | | 525 +--------------+-----------+--------+-----------------------------+ 526 | Read AuthZ | GET | AZ URI | authorization | 527 +--------------+-----------+--------+-----------------------------+ 529 Table 1 531 3.2. Create Grant 533 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 534 document to the GS URI. This is a Greant Request. 536 The JSON document MUST include the following from the Request JSON 537 Section 3.4: 539 * iat 541 * nonce 543 * uri set to the GS URI 545 * client 547 and MAY include the following from Request JSON Section 3.4 549 * user 551 * interaction 553 * authorization or authorizations 555 * claims 556 The GS MUST respond with one of Grant Response Section 4.1, 557 Interaction Response Section 4.2, Wait Response Section 4.3, or one 558 of the following errors: 560 * TBD 562 from Error Responses Section 7. 564 Following is a non-normative example of a web application Client 565 requesting identity claims about the User and read access to the 566 User's contacts: 568 Example 1 570 { 571 "iat" : 15790460234, 572 "uri" : "https://as.example/endpoint", 573 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 574 "client": { 575 "display": { 576 "name" : "SPA Display Name", 577 "uri" : "https://spa.example/about" 578 } 579 }, 580 "interaction": { 581 "redirect": { 582 "redirect_uri" : "https://web.example/return" 583 }, 584 "global" : { 585 "ui_locals" : "de" 586 } 587 }, 588 "authorization": { 589 "type" : "oauth_scope", 590 "scope" : "read_contacts" 591 }, 592 "claims": { 593 "oidc": { 594 "id_token" : { 595 "email" : { "essential" : true }, 596 "email_verified" : { "essential" : true } 597 }, 598 "userinfo" : { 599 "name" : { "essential" : true }, 600 "picture" : null 601 } 602 } 603 } 604 } 606 Following is a non-normative example of a device Client requesting 607 access to play music using "oauth_rich": 609 Example 2 611 { 612 "iat" : 15790460234, 613 "uri" : "https://as.example/endpoint", 614 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 615 "client": { 616 "id" : "di3872h34dkJW" 617 }, 618 "interaction": { 619 "indirect": { 620 "completion_uri": "https://device.example/c/indirect" 621 }, 622 "user_code": { 623 "completion_uri": "https://device.example/c/user_code" 624 } 625 }, 626 "authorization": { 627 "type" : "oauth_rich", 628 "scope" : "play_music", 629 "authorization_details" [ 630 { 631 "type": "customer_information", 632 "locations": [ 633 "https://example.com/customers", 634 ] 635 "actions": [ 636 "read" 637 ], 638 "datatypes": [ 639 "contacts", 640 "photos" 641 ] 642 } 643 ] 644 } 645 } 647 3.3. Read Grant 649 The Client reads a Grant by doing an HTTP GET of the corresponding 650 Grant URI. The Client MAY read a Grant until it expires or has been 651 invalidated. 653 The GS MUST respond with one of Grant Response Section 4.1, Wait 654 Response Section 4.3, or one of the following errors: 656 * TBD 658 3.4. Request JSON 660 * *iat* - the time of the request as a NumericDate. 662 * *nonce* - a unique identifier for this request. Note the Grant 663 Response MUST contain a matching "nonce" attribute value. 665 * *uri* - the GS URI 667 3.4.1. "client" Object 669 The client object MUST only one of the following: 671 * *id* - the Client ID the GS has for a Registered Client. 673 * *handle* - the Client Handle the GS previously provided a Dynamic 674 Client 676 * *display* - the display object contains the following attributes: 678 - *name* - a string that represents the Dynamic Client 680 - *uri* - a URI representing the Dynamic Client 682 The GS will show the the User the display.name and display.uri values 683 when prompting for authorization. 685 _[Editor: a max length for the name and URI so a GS can reserve 686 appropriate space?]_ 688 3.4.2. "interaction" Object 690 The interaction object contains one or more interaction mode objects 691 per Section 5 representing the interactions the Client is willing to 692 provide the User. In addition to the interaction mode objects, the 693 interaction object may contain the "global" object; 695 * *global* - an optional object containing parameters that are 696 applicable for all interaction modes. Only one attribute is 697 defined in this document: 699 - *ui_locales* - End-User's preferred languages and scripts for 700 the user interface, represented as a space-separated list of 701 [RFC5646] language tag values, ordered by preference. This 702 attribute is OPTIONAL. 704 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 705 a JSON array?]_ 707 3.4.3. "user" Object 709 * *identifiers* - The identifiers MAY be used by the GS to improve 710 the User experience. This object contains one or more of the 711 following identifiers for the User: 713 - *phone_number* - contains a phone number per Section 5 of 714 [RFC3966]. 716 - *email* - contains an email address per [RFC5322]. 718 - *oidc* - is an object containing both the "iss" and "sub" 719 attributes from an OpenID Connect ID Token [OIDC] Section 2. 721 * *claims* - an optional object containing one or more assertions 722 the Client has about the User. 724 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 725 Section 2. 727 3.4.4. "authorization" Object 729 * *type* - one of the following values: "oauth_scope" or 730 "oauth_rich". Extensions MAY define additional types, and the 731 required attributes. This attribute is REQUIRED. 733 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 734 section 3.3. MUST be included if type is "oauth_scope". MAY be 735 included if type is "oauth_rich". 737 * *authorization_details* - an authorization_details JSON array of 738 objects per [RAR]. MUST be included if type is "oauth_rich". 739 MUST not be included if type is "oauth_scope" 741 _[Editor: details may change as the RAR document evolves]_ 743 3.4.5. "authorizations" Object 745 One or more key / value pairs, where each unique key is created by 746 the client, and the value is an authorization object per 747 Section 3.4.4. 749 3.4.6. "claims" Object 751 Includes one or more of the following: 753 * *oidc* - an object that contains one or both of the following 754 objects: 756 - *userinfo* - Claims that will be returned as a JSON object 758 - *id_token* - Claims that will be included in the returned ID 759 Token. If the null value, an ID Token will be returned 760 containing no additional Claims. 762 The contents of the userinfo and id_token objects are Claims as 763 defined in [OIDC] Section 5. 765 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 766 per [OIDC4IA]. 768 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 769 requested.]_[W3C_VC] 771 3.5. Read Authorization 773 The Client acquires and refreshes an Authorization by doing an HTTP 774 GET to the corresponding AZ URI. 776 The GS MUST respond with a Authorization JSON document Section 4.5, 777 or one of the following errors: 779 * TBD 781 from Error Responses Section 7. 783 3.6. GS Options 785 The Client can get the metadata for the GS by doing an HTTP OPTIONS 786 of the corresponding GS URI. This is the only API where the GS MAY 787 respond to an unauthenticated request. 789 The GS MUST respond with the the following JSON document: 791 * *uri* - the GS URI. 793 * *client_authentication* - a JSON array of the Client 794 Authentication mechanisms supported by the GS 796 * *interactions* - a JSON array of the interaction modes supported 797 by the GS. 799 * *authorization* - an object containing the authorizations the 800 Client may request from the GS, if any. 802 - Details TBD 804 * *claims* - an object containing the identity claims the Client may 805 request from the GS, if any, and what public keys the claims will 806 be signed with. 808 - Details TBD 810 * *algorithms* - a JSON array of the cryptographic algorithms 811 supported by the GS. [details TBD]* 813 * *features* - an object containing feature support 815 - *authorizations* - boolean indicating if a request for more 816 than one authorization in a request is supported. 818 or one of the following errors: 820 * TBD 822 from Error Responses Section 7. 824 4. GS Responses 826 There are three successful responses to a Grant Request: Grant 827 Response, Interaction Response, or Wait Response. 829 4.1. Grant Response 831 The Grant Response MUST include the following from the Response JSON 832 Section 4.4 834 * iat 836 * nonce 838 * uri 840 and MAY include the following from the Response JSON Section 4.4 842 * client.handle 844 * authorization or authorizations 846 * claims 848 * expires_in 850 * warnings 851 Example non-normative Grant Response JSON document for Example 1 in 852 Section 3.2: 854 { 855 "iat" : 15790460234, 856 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 857 "uri" : "https://as.example/endpoint/grant/example1", 858 "expires_in" : 300 859 "authorization": { 860 "access": { 861 "type" : "oauth_scope", 862 "scope" : "read_contacts" 863 }, 864 "expires_in" : 3600, 865 "mechanism" : "bearer", 866 "token" : "eyJJ2D6.example.access.token.mZf9p" 867 }, 868 "claims": { 869 "oidc": { 870 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 871 "userinfo" : { 872 "name" : "John Doe", 873 "picture" : "https://photos.example/p/eyJzdkiO" 874 } 875 } 876 } 877 } 879 Note in this example the access token can not be refreshed, and 880 expires in an hour. 882 Example non-normative Grant Response JSON document for Example 2 in 883 Section 3.2: 885 { 886 "iat" : 15790460234, 887 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 888 "uri" : "https://as.example/endpoint/grant/example2", 889 "authorization": { 890 "uri" : "https://as.example/endpoint/authz/example2" 891 } 892 } 894 Note in this example the GS only provided the AZ URI, and Client must 895 acquire the Authorization per Section 3.5 897 4.2. Interaction Response 899 The Interaction Response MUST include the following from the Response 900 JSON Section 4.4 902 * iat 904 * nonce 906 * uri 908 * interaction 910 and MAY include the following from the Response JSON Section 4.4 912 * user 914 * wait 916 * warnings 918 A non-normative example of an Interaction Response follows: 920 { 921 "iat" : 15790460234, 922 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 923 "uri" : "https://as.example/endpoint/grant/example4", 924 "interaction" : { 925 ""redirect" : { 926 "authorization_uri" : "https://as.example/i/example4" 927 } 928 }, 929 "user": { 930 "exists" : true 931 } 932 } 934 4.3. Wait Response 936 The Wait Response MUST include the following from the Response JSON 937 Section 4.4 939 * iat 941 * nonce 943 * uri 944 * wait 946 and MAY include the following from the Response JSON Section 4.4 948 * warnings 950 A non-normative example of Wait Response follows: 952 { 953 "iat" : 15790460234, 954 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 955 "uri" : "https://as.example/endpoint/grant/example5", 956 "wait" : 300 957 } 959 4.4. Response JSON 961 Details of the JSON document: 963 * *iat* - the time of the response as a NumericDate. 965 * *nonce* - the nonce that was included in the Request JSON 966 Section 3.4. 968 * *uri* - the Grant URI. 970 * *wait* - a numeric value representing the number of seconds the 971 Client should want before making a Read Grant request to the Grant 972 URI. 974 * *expires_in* - a numeric value specifying how many seconds until 975 the Grant expires. This attribute is OPTIONAL. 977 4.4.1. "client" Object 979 The GS may 981 4.4.2. "interaction" Object 983 If the GS wants the Client to start the interaction, the GS MUST 984 return an interaction object containing one or more interaction mode 985 responses per Section 5 to one or more of the interaction mode 986 requests provided by the Client. 988 4.4.3. "user" Object 989 * *exists* - a boolean value indicating if the GS has a user with 990 one or more of the provided identifiers in the Request 991 user.identifiers object Section 3.4.3 993 4.4.4. "authorization" Object 995 The authorization object MUST contain only a "uri" attribute or the 996 following from Authorization JSON Section 4.5: 998 * mechanism 1000 * token 1002 The authorization object MAY contain any of the following from 1003 Authorization JSON Section 4.5: 1005 * access 1007 * expires_in 1009 * uri 1011 If there is no "uri" attribute, the access token can not be 1012 refreshed. If only the "uri" attribute is present, the Client MUST 1013 acquire the Authorization per Section 3.5 1015 4.4.5. "authorizations" Object 1017 A key / value pair for each key in the Grant Request "authorizations" 1018 object, and the value is per Section 4.4.4. 1020 4.4.6. "claims" Object 1022 The claims object is a response to the Grant Request "claims" object 1023 Section 3.4.4. 1025 * *oidc* 1027 - *id_token* - an OpenID Connect ID Token containing the Claims 1028 the User consented to be released. 1030 - *userinfo* - the Claims the User consented to be released. 1032 Claims are defined in [OIDC] Section 5. 1034 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1035 per [OIDC4IA]. 1037 * *vc* 1039 The verified claims the user consented to be released. _[Editor: 1040 details TBD]_ 1042 4.4.7. "warnings" JSON Array 1044 Includes zero or more warnings from Section 8, 1046 4.5. Authorization JSON 1048 The Authorization JSON is the contents of a Grant Response 1049 "authorization" object Section 4.4.5 or the response to a Read AuthZ 1050 request by the Client Section 3.5. 1052 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1053 See the "type" object in Section 3.4.4 for details. 1055 * *mechanism* - the RS access mechanism. This document defines the 1056 "bearer" mechanism as defined in Section 6 1058 * *token* - the access token for accessing an RS. 1060 * *expires_in* - a numeric value specifying how many seconds until 1061 the access token expires. 1063 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1065 * *access* - an object containing the access granted: 1067 - *type* - the type of claim request: "oauth_scope" or 1068 "oauth_rich". See the "type" object in Section 3.4.4 for 1069 details. This attribute is REQUIRED. 1071 - *scope* - the scopes the Client was granted authorization for. 1072 This will be all, or a subset, of what was requested. This 1073 attribute is OPTIONAL. 1075 - *authorization_details* - the authorization details granted per 1076 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1078 _[Editor: would an optional expiry for the Authorization be useful?]_ 1080 The following is a non-normative example of Authorization JSON: 1082 { 1083 "mechanism" : "bearer", 1084 "token" : "eyJJ2D6.example.access.token.mZf9p" 1085 "expires_in" : 3600, 1086 "uri" : "https://as.example/endpoint/authz/example2", 1087 "access": { 1088 "type" : "oauth_scope", 1089 "scope" : "read_calendar write_calendar" 1090 } 1091 } 1093 4.6. Response Verification 1095 On receipt of a response, the Client MUST verify the following: 1097 * TBD 1099 5. Interaction Modes 1101 This document defines three interaction modes: "redirect", 1102 "indirect", and "user_code". Extensions may define additional 1103 interaction modes. 1105 The "global" attribute is reserved in the interaction object for 1106 attributes that apply to all interaction modes. 1108 5.1. "redirect" 1110 A Redirect Interaction is characterized by the Client redirecting the 1111 User's browser to the GS, the GS interacting with the User, and then 1112 GS redirecting the User's browser back to the Client. The GS 1113 correlates the Grant Request with the unique authorization_uri, and 1114 the Client correlates the Grant Request with the unique redirect_uri. 1116 *The request "interaction" object contains:* 1118 * *redirect_uri* a unique URI at the Client that the GS will return 1119 the User to. The URI MUST not contain the "nonce" from the Grant 1120 Request, and MUST not be guessable. This attribute is REQUIRED. 1122 *The response "interaction" object contains:* 1124 * *authorization_uri* a unique URI at the GS that the Client will 1125 redirect the User to. The URI MUST not contain the "nonce" from 1126 the Grant Request, and MUST not be guessable. This attribute is 1127 REQUIRED. 1129 5.2. "indirect" 1131 An Indirect Interaction is characterized by the Client causing the 1132 User's browser to load the short_uri at GS, the GS interacting with 1133 the User, and then the GS MAY optionally redirect the User's Browser 1134 to a completion_uri. There is no mechanism for the GS to redirect 1135 the User's browser back to the Client. 1137 Examples of how the Client may initiate the interaction are encoding 1138 the short_uri as a code scannable by the User's mobile device, or 1139 launching a system browser from a command line interface (CLI) 1140 application. 1142 The "indirect" mode is susceptible to session fixation attacks. See 1143 TBD in the Security Considerations for details. 1145 *The request "interaction" object contains:* 1147 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1148 User's browser to after GS interaction. 1150 *The response "interaction" object contains:* 1152 * *short_uri* the URI the Client will cause to load in the User's 1153 browser. The URI SHOULD be short enough to be easily encoded in a 1154 scannable code. The URI MUST not contain the "nonce" from the 1155 Grant Request, and MUST not be guessable. _[Editor: recommend a 1156 maximum length?]_ 1158 5.3. "user_code" 1160 An Indirect Interaction is characterized by the Client displaying a 1161 code and a URI for the User to load in a browser and then enter the 1162 code. _[Editor: recommend a minimum entropy?]_ 1164 *The request "interaction" object contains:* 1166 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1167 User's browser to after GS interaction. 1169 *The response "interaction" object contains:* 1171 * *code* the code the Client displays to the User to enter at the 1172 display_uri. This attribute is REQUIRED. 1174 * *display_uri* the URI the Client displays to the User to load in a 1175 browser to enter the code. 1177 6. RS Access 1179 The mechanism the Client MUST use to access an RS is in the 1180 Authorization JSON "mechanism" attribute Section 4.4.4. 1182 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1184 The "jose" and "jose+body" mechanisms are defined in 1185 [JOSE_Authentication] 1187 A non-normative "bearer" example of the HTTP request headers follows: 1189 GET /calendar HTTP/2 1190 Host: calendar.example 1191 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1193 7. Error Responses 1195 * TBD 1197 8. Warnings 1199 Warnings assist a Client in detecting non-fatal errors. 1201 * TBD 1203 9. Extensibility 1205 This standard can be extended in a number of areas: 1207 * *Client Authentication Mechanisms* 1209 - An extension could define other mechanisms for the Client to 1210 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1211 Signing. Constrained environments could use CBOR [RFC7049] 1212 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1213 [RFC8323] instead of HTTP/2. 1215 * *Grant* 1217 - An extension can define new objects in the Grant Request and 1218 Grant Response JSON that return new URIs. 1220 * *Top Level* 1222 - Top level objects SHOULD only be defined to represent 1223 functionality other the existing top level objects and 1224 attributes. 1226 * *"client" Object* 1228 - Additional information about the Client that the GS would 1229 require related to an extension. 1231 * *"user" Object* 1233 - Additional information about the User that the GS would require 1234 related to an extension. 1236 * *"authorization" Object* 1238 - Additional authorization schemas in addition to OAuth 2.0 1239 scopes and RAR. 1241 * *"claims" Object* 1243 - Additional claim schemas in addition to OpenID Connect claims 1244 and Verified Credentials. 1246 * *interaction modes* 1248 - Additional types of interactions a Client can start with the 1249 User. 1251 * *Continuous Authentication* 1253 - An extension could define a mechanism for the Client to 1254 regularly provide continuous authentication signals and receive 1255 responses. 1257 _[Editor: do we specify access token introspection in this document, 1258 or leave that to an extension?]_ 1260 10. Rational 1262 1. *Why have both Client ID and Client Handle?* 1264 While they both refer to a Client in the protocol, the Client ID 1265 refers to a pre-registered client,and the Client Handle is 1266 specific to an instance of a Dynamic Client. Using separate 1267 terms clearly differentiates which identifier is being presented 1268 to the GS. 1270 2. *Why allow Client and GS to negotiate the user interaction mode?* 1271 The Client knows what interaction modes it is capable of, and the 1272 GS knows which interaction modes it will permit for a given Grant 1273 Request. The Client can then present the intersection to the 1274 User to choose which one is preferred. For example, while a 1275 device based Client may be willing to do both "indirect" and 1276 "user_code", a GS may not enable "indirect" for concern of a 1277 session fixation attack. Additional interaction modes will 1278 likely become available which allows new modes to be negotiated 1279 between Client and GS as each adds additional interaction modes. 1281 3. *Why have both claims and authorizations?* 1283 There are use cases for each that are independent: authenticating 1284 a user and providing claims vs granting access to a resource. A 1285 request for an authorization returns an access token which may 1286 have full CRUD capabilities, while a request for a claim returns 1287 the claim about the User - with no create, update or delete 1288 capabilities. While the UserInfo endpoint in OIDC may be thought 1289 of as a resource, separating the concepts and how they are 1290 requested keeps each of them simpler in the Editor's opinion. :) 1292 4. *Why do some of the JSON objects only have one child, such as the 1293 identifiers object in the user object in the Grant Request?* 1295 It is difficult to forecast future use cases. Having more 1296 resolution may mean the difference between a simple extension, 1297 and a convoluted extension. For example, the "global" object in 1298 the "interaction" object allows new global parameters to be added 1299 without impacting new interaction modes. 1301 5. *Why is the "iss" included in the "oidc" identifier object? 1302 Would the "sub" not be enough for the GS to identify the User?* 1304 This decouples the GS from the OpenID Provider (OP). The GS 1305 identifier is the GS URI, which is the endpoint at the GS. The 1306 OP issuer identifier will likely not be the same as the GS URI. 1307 The GS may also provide claims from multiple OPs. 1309 6. *Why is there not a UserInfo endpoint as there is with OpenID 1310 Connect?* 1312 Since the Client can Read Grant at any time, it get the same 1313 functionality as the UserInfo endpoint, without the Client having 1314 to manage a separate access token and refresh token. If the 1315 Client would like additional claims, it can Update Grant, and the 1316 GS will let the Client know if an interaction is required to get 1317 any of the additional claims, which the Client can then start. 1319 _[Editor: is there some other reason to have the UserInfo 1320 endpoint?]_ 1322 7. *Why use URIs for the Grant and Authorization?* 1324 * Grant URI and AZ URI are defined to start with the GS URI, 1325 allowing the Client, and GS to determine which GS a Grant or 1326 Authorization belongs to. 1328 * URIs also enable a RESTful interface to the GS functionality. 1330 * A large scale GS can easily separate out the services that 1331 provide functionality as routing of requests can be done at 1332 the HTTP layer based on URI and HTTP verb. This allows a 1333 separation of concerns, independent deployment, and 1334 resiliency. 1336 8. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 1337 known mechanism?* 1339 Having the GS URI endpoint respond to the metadata allows the GS 1340 to provide Client specific results using the same Client 1341 authentication used for other requests to the GS. It also 1342 reduces the risk of a mismatch between the advertised metadata, 1343 and the actual metadata. A .well-known discovery mechanism may 1344 be defined to resolve from a hostname to the GS URI. 1346 11. Acknowledgments 1348 This draft derives many of its concepts from Justin Richer's 1349 Transactional Authorization draft [TxAuth]. 1351 Additional thanks to Justin Richer and Annabelle Richard Backman for 1352 their strong critique of earlier drafts. 1354 12. IANA Considerations 1356 TBD 1358 13. Security Considerations 1360 TBD 1362 14. References 1364 14.1. Normative References 1366 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1367 Requirement Levels", BCP 14, RFC 2119, 1368 DOI 10.17487/RFC2119, March 1997, 1369 . 1371 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1372 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1373 . 1375 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1376 DOI 10.17487/RFC5322, October 2008, 1377 . 1379 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1380 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1381 . 1383 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1384 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1385 September 2009, . 1387 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1388 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1389 . 1391 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1392 Framework: Bearer Token Usage", RFC 6750, 1393 DOI 10.17487/RFC6750, October 2012, 1394 . 1396 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1397 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1398 . 1400 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1401 Interchange Format", STD 90, RFC 8259, 1402 DOI 10.17487/RFC8259, December 2017, 1403 . 1405 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1406 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1407 . 1409 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1410 Assurance 1.0", October 2019, . 1413 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1414 Rich Authorization Requests", January 2020, 1415 . 1417 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1418 Credentials Data Model 1.0", November 2019, 1419 . 1421 [JOSE_Authentication] 1422 Hardt, D., "JOSE Authentication", June 2020, 1423 . 1425 [GNAP_Advanced] 1426 Hardt, D., "The Grant Negotiation and Authorization 1427 Protocol - Advanced Features", June 2020, 1428 . 1430 14.2. Informative References 1432 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1433 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1434 October 2013, . 1436 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1437 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1438 . 1440 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1441 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1442 Application Protocol) over TCP, TLS, and WebSockets", 1443 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1444 . 1446 [browser_based_apps] 1447 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1448 Apps", September 2019, . 1451 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1452 identification and data capture techniques - QR Code bar 1453 code symbology specification", February 2015, 1454 . 1456 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1457 . 1460 Appendix A. Document History 1462 A.1. draft-hardt-xauth-protocol-00 1464 * Initial version 1466 A.2. draft-hardt-xauth-protocol-01 1468 * text clean up 1470 * added OIDC4IA claims 1472 * added "jws" method for accessing a resource. 1474 * renamed Initiation Request -> Grant Request 1476 * renamed Initiation Response -> Interaction Response 1478 * renamed Completion Request -> Authorization Request 1480 * renamed Completion Response -> Grant Request 1482 * renamed completion handle -> authorization handle 1484 * added Authentication Request, Authentication Response, 1485 authentication handle 1487 A.3. draft-hardt-xauth-protocol-02 1489 * major rewrite 1491 * handles are now URIs 1493 * the collection of claims and authorizations are a Grant 1495 * an Authorization is its own type 1497 * lots of sequences added 1499 A.4. draft-hardt-xauth-protocol-03 1501 * fixed RO definition 1503 * improved language in Rationals 1505 * added user code interaction method, and aligned qrcode interaction 1506 method 1508 * added completion_uri for code flows 1510 A.5. draft-hardt-xauth-protocol-04 1512 * renamed interaction uris to have purpose specific names 1514 A.6. draft-hardt-xauth-protocol-05 1516 * separated claims from identifiers in request user object 1518 * simplified reciprocal grant flow 1520 * reduced interactions to redirect and indirect 1522 * simplified interaction parameters 1524 * added in language for Client to verify interaction completion 1526 * added Verify Grant API and Interaction Nonce 1528 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1529 operation. 1531 A.7. draft-hardt-xauth-protocol-06 1533 * fixup examples to match specification 1535 A.8. draft-hardt-xauth-protocol-07 1537 * refactored interaction request and response syntax, and enabled 1538 interaction mode negotiation 1540 * generation of client handle by GS for dynamic clients 1542 * renamed title to Grant Negotiation and Authorization Protocol. 1543 Preserved draft-hardt-xauth-protocol filename to ease tracking 1544 changes. 1546 * changed Authorizations to be key / value pairs (aka dictionary) 1547 instead of a JSON array 1549 A.9. draft-hardt-xauth-protocol-08 1551 * split document into three documents: core, advanced, and JOSE 1552 authentication. 1554 * grouped access granted into "access" object in Authorization JSON 1555 * added warnings object to the Grant Response JSON 1557 A.10. draft-hardt-xauth-protocol-09 1559 * added editorial note that this document should be referred to as 1560 XAuth 1562 A.11. draft-hardt-xauth-protocol-10 1564 * added example of RAR authorization request 1566 * fixed typos 1568 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1570 *Changed Features* 1572 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1574 * The Client always uses a private asymetric key to authenticate to 1575 the GS. There is no client secret. i 1577 * The Client initiates the protocol by making a signed request 1578 directly to the GS instead of redirecting the User to the GS. 1580 * The Client does not pass any parameters in redirecting the User to 1581 the GS. 1583 * The refresh_token has been replaced with a AZ URI that both 1584 represents the authorization, and is the URI for obtaining a fresh 1585 access token. 1587 * The Client can request identity claims to be returned independent 1588 of the ID Token. There is no UserInfo endpoint to query claims as 1589 there is in OpenID Connect. 1591 * The GS URI is the token endpoint. 1593 *Preserved Features* 1595 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1596 2.0. 1598 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1600 * No change is required by the Client or the RS for accessing 1601 existing bearer token protected APIs. 1603 *New Features* 1605 * All Client calls to the GS are authenticated with asymetric 1606 cryptography 1608 * A Grant represents both the user identity claims and RS access 1609 granted to the Client. 1611 * Support for scannable code initiated interactions. 1613 * Highly extensible per Section 9. 1615 Author's Address 1617 Dick Hardt (editor) 1618 SignIn.Org 1619 United States 1621 Email: dick.hardt@gmail.com