idnits 2.17.00 (12 Aug 2021) /tmp/idnits32644/draft-hardt-xauth-protocol-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- 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: * *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 (7 June 2020) is 713 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' -- Possible downref: Non-RFC (?) normative reference: ref. 'RAR' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 2 errors (**), 0 flaws (~~), 5 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 7 June 2020 5 Expires: 9 December 2020 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-09 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 9 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 . . . . . . . . . . . . . . . . . . . . . . 15 71 3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 15 72 3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 16 73 3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . 20 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 . . . . . . . . . . . . . . . 22 88 4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 23 89 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 23 90 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 23 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" . . . . . . . . . . . . . . . . . . . . . . . 25 96 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 26 98 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . . 32 110 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 32 111 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 32 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 . . . . . . . . . . . . . . 33 115 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 33 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 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 34 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 35 122 1. Introduction 124 *EDITOR NOTE* 126 _This document captures a number of concepts that may be adopted by 127 the proposed GNAP working group. Please refer to this document as:_ 129 *XAuth* 131 _The use of GNAP in this document is not intended to be a declaration 132 of it being endorsed by the proposed GNAP working group._ 134 This document describes the core Grant Negotiation and Authorization 135 Protocol (GNAP). The protocol supports the widely deployed use cases 136 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 137 an extension of OAuth 2.0, as well as other extensions. Related 138 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 139 Authentication [JOSE_Authentication] that describes the JOSE 140 mechanisms for client authentication. 142 The technology landscape has changed since OAuth 2.0 was initially 143 drafted. More interactions happen on mobile devices than PCs. 144 Modern browsers now directly support asymetric cryptographic 145 functions. Standards have emerged for signing and encrypting tokens 146 with rich payloads (JOSE) that are widely deployed. 148 GNAP simplifies the overall architectural model, takes advantage of 149 today's technology landscape, provides support for all the widely 150 deployed use cases, offers numerous extension points, and addresses 151 many of the security issues in OAuth 2.0 by passing parameters 152 securely between parties, rather than via a browser redirection. . 154 While GNAP is not backwards compatible with OAuth 2.0, it strives to 155 minimize the migration effort. 157 GNAP centers around a Grant, a representation of the collection of 158 user identity claims and/or resource authorizations the Client is 159 requesting, and the resulting identity claims and/or resource 160 authorizations granted by the Grant Server (GS). 162 User consent is often required at the GS. GNAP enables a Client and 163 GS to negotiate the interaction mode for the GS to obtain consent. 165 The suggested pronunciation of GNAP is the same as the English word 166 "nap", a silent "g" as in "gnaw". 168 _[Editor: suggestions on how to improve this are welcome!]_ 170 1.1. Parties 172 The parties and their relationships to each other: 174 +--------+ +------------+ 175 | User | | Resource | 176 | | | Owner (RO) | 177 +--------+ +------------+ 178 | \ / | 179 | \ / | 180 | \ / | 181 | \ / | 182 +--------+ +---------------+ +------------+ 183 | Client |---->| Grant | | Resource | 184 | | (1) | Server (GS) | _ _ | Server | 185 | |<----| | | (RS) | 186 | | +---------------+ | | 187 | |-------------------------->| | 188 | | (2) | | 189 | |<--------------------------| | 190 +--------+ +------------+ 192 This document specifies interactions between the Client and GS (1), 193 and the Client and RS (2). 195 * *User* - the person interacting with the Client who has delegated 196 access to identity claims about themselves to the Grant Server 197 (GS), and can authenticate at the GS. 199 * *Client* - requests a Grant from the GS to access one or more 200 Resource Servers (RSs), and/or identity claims about the User. 201 The Grant may include access tokens that the Client uses to access 202 the RS. There are two types of Clients: Registered Clients and 203 Dynamic Clients. All Clients have a private asymetric key to 204 authenticate with the Grant Server. 206 * *Registered Client* - a Client that has registered with the GS and 207 has a Client ID to identify itself, and can prove it possesses a 208 key that is linked to the Client ID. The GS may have different 209 policies for what different Registered Clients can request. A 210 Registered Client MAY be interacting with a User. 212 * *Dynamic Client* - a Client that has not been previously 213 registered with the GS, and each instance will generate it's own 214 asymetric key pair so it can prove it is the same instance of the 215 Client on subsequent requests. The GS MAY return a Dynamic Client 216 a Client Handle for the Client to identify itself in subsequent 217 requests. A single-page application with no active server 218 component is an example of a Dynamic Client. A Dynamic Client 219 MUST be interacting with a User. 221 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 222 release of identity claims about the User. The GS may require 223 explicit consent from the RO or User to provide these to the 224 Client. A GS may support Registered Clients and/or Dynamic 225 Clients. The GS is a combination of the Authorization Server (AS) 226 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 228 * *Resource Server* (RS) - has API resources that require an access 229 token from the GS. Some, or all of the resources are owned by the 230 Resource Owner. 232 * *Resource Owner* (RO) - owns resources at the RS, and has 233 delegated RS access management to the GS. The RO may be the same 234 entity as the User, or may be a different entity that the GS 235 interacts with independently. GS and RO interactions are out of 236 scope of this document. 238 1.2. Reused Terms 240 * *access token* - an access token as defined in [RFC6749] 241 Section 1.4. 243 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 244 issued by the GS, or by other issuers. 246 * *Client ID* - a GS unique identifier for a Registered Client as 247 defined in [RFC6749] Section 2.2. 249 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 251 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 253 * *authN* - short for authentication. 255 * *authZ* - short for authorization. 257 1.3. New Terms 259 * *GS URI* - the endpoint at the GS the Client calls to create a 260 Grant, and is the unique identifier for the GS. 262 * *Grant* - the user identity claims and/or RS authorizations the GS 263 has granted to the Client. The GS MAY invalidate a Grant at any 264 time. 266 * *Grant URI* - the URI that represents the Grant. The Grant URI 267 MUST start with the GS URI. 269 * *Authorization* - the access granted by the RO to the Client and 270 contains an access token. The GS may invalidate an Authorization 271 at any time. 273 * *Authorization URI* (AZ URI) - the URI that represents the 274 Authorization the Client was granted by the RO. The AZ URI MUST 275 start with the GS URI. The AZ URI is used to refresh an access 276 token. 278 * *Interaction* - how the Client directs the User to interact with 279 the GS. This document defines the interaction modes: "redirect", 280 "indirect", and "user_code" in Section 5 282 * *Client Handle* - a unique identifier at the GS for a Dynamic 283 Client for the Dynamic Client to refer to itself in subsequent 284 requests. 286 1.4. Notational Conventions 288 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 289 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 290 specification are to be interpreted as described in [RFC2119]. 292 Certain security-related terms are to be understood in the sense 293 defined in [RFC4949]. These terms include, but are not limited to, 294 "attack", "authentication", "authorization", "certificate", 295 "confidentiality", "credential", "encryption", "identity", "sign", 296 "signature", "trust", "validate", and "verify". 298 _[Editor: review terms]_ 300 Unless otherwise noted, all the protocol parameter names and values 301 are case sensitive. 303 Some protocol parameters are parts of a JSON document, and are 304 referred to in JavaScript notation. For example, foo.bar refers to 305 the "bar" boolean attribute in the "foo" object in the following 306 example JSON document: 308 { 309 "foo" : { 310 "bar": true 311 } 312 } 314 2. Sequences 316 Before any sequence, the Client needs to be manually or 317 programmatically configured for the GS. See GS Options Section 3.6 318 for details on programmatically acquiring GS metadata. 320 2.1. "redirect" Interaction 322 The Client is a web application and wants a Grant from the User: 324 +--------+ +-------+ 325 | Client | | GS | 326 | |--(1)--- Create Grant ----------->| | 327 | | | | 328 | |<--- Interaction Response ---(2)--| | +------+ 329 | | | | | User | 330 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 331 | | | |<--(4)-->| | 332 | | | | authN | | 333 | | | | | | 334 | | | |<--(5)-->| | 335 | | | | authZ | | 336 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 337 | | | | | | 338 | |--(7)--- Read Grant ------------->| | +------+ 339 | | | | 340 | |<--------- Grant Response ---(8)--| | 341 | | | | 342 +--------+ +-------+ 344 1. *Create Grant* The Client creates a Request JSON document 345 Section 3.4 containing an interaction.redirect object and makes a 346 Create Grant request (Section 3.2) by sending the JSON with an 347 HTTP POST to the GS URI. 349 2. *Interaction Response* The GS determines that interaction with 350 the User is required and sends an Interaction Response 351 (Section 4.2) containing the Grant URI and an 352 interaction.redirect object. 354 3. *Interaction Transfer* The Client redirects the User to the 355 authorization_uri at the GS. 357 4. *User Authentication* The GS authenticates the User. 359 5. *User Authorization* If required, the GS interacts with the User 360 to determine which identity claims and/or authorizations in the 361 Grant Request are to be granted. 363 6. *Interaction Transfer* The GS redirects the User to the 364 redirect_uri at the Client. 366 7. *Read Grant* The Client makes an HTTP GET request to the Grant 367 URI. 369 8. *Grant Response* The GS responds with a Grant Response 370 (Section 4.1). 372 2.2. "user_code" Interaction 374 A Client is on a device wants a Grant from the User: 376 +--------+ +-------+ 377 | Client | | GS | 378 | |--(1)--- Create Grant ----------->| | 379 | | | | 380 | |<--- Interaction Response ---(2)--| | +------+ 381 | | | | | User | 382 | |--(3)--- Read Grant ------------->| | | | 383 | | | |<--(4)-->| | 384 | | | | authN | | 385 | | | | | | 386 | | | |<--(5)---| | 387 | | | | code | | 388 | | | | | | 389 | | | |<--(6)-->| | 390 | | | | authZ | | 391 | | | | | | 392 | |<--------- Grant Response ---(7)--| | | | 393 | | | | | | 394 +--------+ | | | | 395 | | | | 396 +--------+ | | | | 397 | Client |<----- Completion URI Redirect -- | - - - | --(8)---| | 398 | Server | | | | | 399 +--------+ +-------+ +------+ 401 1. *Create Grant* The Client creates a Request JSON document 402 Section 3.4 containing an interaction.user_code object and makes 403 a Create Grant request (Section 3.2) by sending the JSON with an 404 HTTP POST to the GS URI. 406 2. *Interaction Response* The GS determines that interaction with 407 the User is required and sends an Interaction Response 408 (Section 4.2) containing the Grant URI and an 409 interaction.user_code object. 411 3. *Read Grant* The Client makes an HTTP GET request to the Grant 412 URI. 414 4. *User Authentication* The User loads display_uri in their 415 browser, and the GS authenticates the User. 417 5. *User Code* The User enters the code at the GS. 419 6. *User Authorization* If required, the GS interacts with the User 420 to determine which identity claims and/or authorizations in the 421 Grant Request are to be granted. 423 7. *Grant Response* The GS responds with a Grant Response 424 (Section 4.1). 426 8. *Completion URI Redirect* The GS redirects the User to the 427 completion_uri provided by the Client. 429 2.3. Independent RO Authorization 431 The Client wants access to resources that require the GS to interact 432 with the RO, who is not interacting with the Client. The 433 authorization from the RO may take some time, so the GS instructs the 434 Client to wait and check back later. 436 +--------+ +-------+ 437 | Client | | GS | 438 | |--(1)--- Create Grant ----------->| | 439 | | | | 440 | |<---------- Wait Response ---(2)--| | +------+ 441 | (3) | | | | RO | 442 | Wait | | |<--(4)-->| | 443 | | | | AuthZ | | 444 | |--(5)--- Read Grant ------------->| | +------+ 445 | | | | 446 | |<--------- Grant Response --(6)---| | 447 | | | | 448 +--------+ +-------+ 450 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 451 and sends it with an HTTP POST to the GS GS URI. 453 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 454 containing the Grant URI and the "wait" attribute. 456 3. *Client Waits* The Client waits for the time specified in the 457 "wait" attribute. 459 4. *RO AuthZ* The GS interacts with the RO to determine which 460 identity claims and/or resource authorizations in the Grant 461 Request are to be granted. 463 5. *Read Grant* The Client does an HTTP GET of the Grant URI 464 (Section 3.3). 466 6. *Grant Response* The GS responds with a Grant Response 467 (Section 4.1). 469 2.4. Resource Server Access 471 The Client received an AZ URI from the GS. The Client acquires an 472 access token, calls the RS, and later the access token expires. The 473 Client then gets a fresh access token. 475 +--------+ +----------+ +-------+ 476 | Client | | Resource | | GS | 477 | |--(1)--- Access Resource --->| Server | | | 478 | |<------- Resource Response --| (RS) | | | 479 | | | | | | 480 | |--(2)--- Access Resource --->| | | | 481 | |<------- Error Response -----| | | | 482 | | | | | | 483 | | +----------+ | | 484 | | | | 485 | |--(3)--- Read AuthZ ---------------------->| | 486 | |<------- AuthZ Response -------------------| | 487 | | | | 488 +--------+ +-------+ 490 1. *Resource Request* The Client accesses the RS with the access 491 token per Section 6 and receives a response from the RS. 493 2. *Resource Request* The Client attempts to access the RS, but 494 receives an error indicating the access token needs to be 495 refreshed. 497 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.5) with an 498 HTTP GET to the AZ URI and receives an Response JSON 499 "authorization" object (Section 4.4.4) with a fresh access token. 501 3. GS APIs 503 *Client Authentication* 505 All GS APIs except for GS Options require the Client to authenticate. 506 Authentication mechanisms include: 508 * JOSE Authentication [JOSE_Authentication] 510 * [Others TBD]* 512 3.1. GS API Table 514 +--------------+-----------+--------+-----------------------------+ 515 | request | http verb | uri | response | 516 +==============+===========+========+=============================+ 517 | GS Options | OPTIONS | GS URI | metadata | 518 +--------------+-----------+--------+-----------------------------+ 519 | Create Grant | POST | GS URI | interaction, wait, or grant | 520 +--------------+-----------+--------+-----------------------------+ 521 | Read Grant | GET | Grant | wait, or grant | 522 | | | URI | | 523 +--------------+-----------+--------+-----------------------------+ 524 | Read AuthZ | GET | AZ URI | authorization | 525 +--------------+-----------+--------+-----------------------------+ 527 Table 1 529 3.2. Create Grant 531 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 532 document to the GS URI. This is a Greant Request. 534 The JSON document MUST include the following from the Request JSON 535 Section 3.4: 537 * iat 539 * nonce 541 * uri set to the GS URI 543 * client 545 and MAY include the following from Request JSON Section 3.4 547 * user 549 * interaction 551 * authorization or authorizations 553 * claims 554 The GS MUST respond with one of Grant Response Section 4.1, 555 Interaction Response Section 4.2, Wait Response Section 4.3, or one 556 of the following errors: 558 * TBD 560 from Error Responses Section 7. 562 Following is a non-normative example of a web application Client 563 requesting identity claims about the User and read access to the 564 User's contacts: 566 Example 1 568 { 569 "iat" : 15790460234, 570 "uri" : "https://as.example/endpoint", 571 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 572 "client": { 573 "display": { 574 "name" : "SPA Display Name", 575 "uri" : "https://spa.example/about" 576 } 577 }, 578 "interaction": { 579 "redirect": { 580 "redirect_uri" : "https://web.example/return" 581 }, 582 "global" : { 583 "ui_locals" : "de" 584 } 585 }, 586 "authorization": { 587 "type" : "oauth_scope", 588 "scope" : "read_contacts" 589 }, 590 "claims": { 591 "oidc": { 592 "id_token" : { 593 "email" : { "essential" : true }, 594 "email_verified" : { "essential" : true } 595 }, 596 "userinfo" : { 597 "name" : { "essential" : true }, 598 "picture" : null 599 } 600 } 601 } 602 } 604 Following is a non-normative example of a device Client requesting 605 access to play music: 607 Example 2 609 { 610 "iat" : 15790460234, 611 "uri" : "https://as.example/endpoint", 612 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 613 "client": { 614 "id" : "di3872h34dkJW" 615 }, 616 "interaction": { 617 "indirect": { 618 "completion_uri": "https://device.example/c/indirect" 619 }, 620 "user_code": { 621 "completion_uri": "https://device.example/c/user_code" 622 } 623 }, 624 "authorization": { 625 "type" : "oauth_scope", 626 "scope" : "play_music" 627 } 628 } 630 3.3. Read Grant 632 The Client reads a Grant by doing an HTTP GET of the corresponding 633 Grant URI. The Client MAY read a Grant until it expires or has been 634 invalidated. 636 The GS MUST respond with one of Grant Response Section 4.1, Wait 637 Response Section 4.3, or one of the following errors: 639 * TBD 641 3.4. Request JSON 643 * *iat* - the time of the request as a NumericDate. 645 * *nonce* - a unique identifier for this request. Note the Grant 646 Response MUST contain a matching "nonce" attribute value. 648 * *uri* - the GS URI 650 3.4.1. "client" Object 652 The client object MUST only one of the following: 654 * *id* - the Client ID the GS has for a Registered Client. 656 * *handle* - the Client Handle the GS previously provided a Dynamic 657 Client 659 * *display* - the display object contains the following attributes: 661 - *name* - a string that represents the Dynamic Client 663 - *uri* - a URI representing the Dynamic Client 665 The GS will show the the User the display.name and display.uri values 666 when prompting for authorization. 668 _[Editor: a max length for the name and URI so a GS can reserve 669 appropriate space?]_ 671 3.4.2. "interaction" Object 673 The interaction object contains one or more interaction mode objects 674 per Section 5 representing the interactions the Client is willing to 675 provide the User. In addition to the interaction mode objects, the 676 interaction object may contain the "global" object; 678 * *global* - an optional object containing parameters that are 679 applicable for all interaction modes. Only one attribute is 680 defined in this document: 682 - *ui_locales* - End-User's preferred languages and scripts for 683 the user interface, represented as a space-separated list of 684 [RFC5646] language tag values, ordered by preference. This 685 attribute is OPTIONAL. 687 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 688 a JSON array?]_ 690 3.4.3. "user" Object 692 * *identifiers* - The identifiers MAY be used by the GS to improve 693 the User experience. This object contains one or more of the 694 following identifiers for the User: 696 - *phone_number* - contains a phone number per Section 5 of 697 [RFC3966]. 699 - *email* - contains an email address per [RFC5322]. 701 - *oidc* - is an object containing both the "iss" and "sub" 702 attributes from an OpenID Connect ID Token [OIDC] Section 2. 704 * *claims* - an optional object containing one or more assertions 705 the Client has about the User. 707 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 708 Section 2. 710 3.4.4. "authorization" Object 712 * *type* - one of the following values: "oauth_scope" or 713 "oauth_rich". This attribute is REQUIRED. 715 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 716 section 3.3. MUST be included if type is "oauth_scope" or 717 "oauth_rich". 719 * *authorization_details* - an authorization_details object per 720 [RAR]. MUST be included if type is "oauth_rich". 722 _[Editor: details may change as the RAR document evolves]_ 724 3.4.5. "authorizations" Object 726 One or more key / value pairs, where each unique key is created by 727 the client, and the value is an authorization object per 728 Section 3.4.4. 730 3.4.6. "claims" Object 732 Includes one or more of the following: 734 * *oidc* - an object that contains one or both of the following 735 objects: 737 - *userinfo* - Claims that will be returned as a JSON object 739 - *id_token* - Claims that will be included in the returned ID 740 Token. If the null value, an ID Token will be returned 741 containing no additional Claims. 743 The contents of the userinfo and id_token objects are Claims as 744 defined in [OIDC] Section 5. 746 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 747 per [OIDC4IA]. 749 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 750 requested.]_[W3C_VC] 752 3.5. Read Authorization 754 The Client acquires and refreshes an Authorization by doing an HTTP 755 GET to the corresponding AZ URI. 757 The GS MUST respond with a Authorization JSON document Section 4.5, 758 or one of the following errors: 760 * TBD 762 from Error Responses Section 7. 764 3.6. GS Options 766 The Client can get the metadata for the GS by doing an HTTP OPTIONS 767 of the corresponding GS URI. This is the only API where the GS MAY 768 respond to an unauthenticated request. 770 The GS MUST respond with the the following JSON document: 772 * *uri* - the GS URI. 774 * *client_authentication* - a JSON array of the Client 775 Authentication mechanisms supported by the GS 777 * *interactions* - a JSON array of the interaction modes supported 778 by the GS. 780 * *authorization* - an object containing the authorizations the 781 Client may request from the GS, if any. 783 - Details TBD 785 * *claims* - an object containing the identity claims the Client may 786 request from the GS, if any, and what public keys the claims will 787 be signed with. 789 - Details TBD 791 * *algorithms* - a JSON array of the cryptographic algorithms 792 supported by the GS. [details TBD]* 794 * *features* - an object containing feature support 796 - *authorizations* - boolean indicating if a request for more 797 than one authorization in a request is supported. 799 or one of the following errors: 801 * TBD 803 from Error Responses Section 7. 805 4. GS Responses 807 There are three successful responses to a Grant Request: Grant 808 Response, Interaction Response, or Wait Response. 810 4.1. Grant Response 812 The Grant Response MUST include the following from the Response JSON 813 Section 4.4 815 * iat 817 * nonce 819 * uri 821 and MAY include the following from the Response JSON Section 4.4 823 * client.handle 825 * authorization or authorizations 827 * claims 829 * expires_in 831 * warnings 833 Example non-normative Grant Response JSON document for Example 1 in 834 Section 3.2: 836 { 837 "iat" : 15790460234, 838 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 839 "uri" : "https://as.example/endpoint/grant/example1", 840 "expires_in" : 300 841 "authorization": { 842 "type" : "oauth_scope", 843 "scope" : "read_contacts", 844 "expires_in" : 3600, 845 "mechanism" : "bearer", 846 "token" : "eyJJ2D6.example.access.token.mZf9p" 847 }, 848 "claims": { 849 "oidc": { 850 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 851 "userinfo" : { 852 "name" : "John Doe", 853 "picture" : "https://photos.example/p/eyJzdkiO" 854 } 855 } 856 } 857 } 859 Note in this example the access token can not be refreshed, and 860 expires in an hour. 862 Example non-normative Grant Response JSON document for Example 2 in 863 Section 3.2: 865 { 866 "iat" : 15790460234, 867 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 868 "uri" : "https://as.example/endpoint/grant/example2", 869 "authorization": { 870 "uri" : "https://as.example/endpoint/authz/example2" 871 } 872 } 874 Note in this example the GS only provided the AZ URI, and Client must 875 acquire the Authorization per Section 3.5 877 4.2. Interaction Response 879 The Interaction Response MUST include the following from the Response 880 JSON Section 4.4 882 * iat 883 * nonce 885 * uri 887 * interaction 889 and MAY include the following from the Response JSON Section 4.4 891 * user 893 * wait 895 * warnings 897 A non-normative example of an Interaction Response follows: 899 { 900 "iat" : 15790460234, 901 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 902 "uri" : "https://as.example/endpoint/grant/example4", 903 "interaction" : { 904 ""redirect" : { 905 "authorization_uri" : "https://as.example/i/example4" 906 } 907 }, 908 "user": { 909 "exists" : true 910 } 911 } 913 4.3. Wait Response 915 The Wait Response MUST include the following from the Response JSON 916 Section 4.4 918 * iat 920 * nonce 922 * uri 924 * wait 926 and MAY include the following from the Response JSON Section 4.4 928 * warnings 930 A non-normative example of Wait Response follows: 932 { 933 "iat" : 15790460234, 934 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 935 "uri" : "https://as.example/endpoint/grant/example5", 936 "wait" : 300 937 } 939 4.4. Response JSON 941 Details of the JSON document: 943 * *iat* - the time of the response as a NumericDate. 945 * *nonce* - the nonce that was included in the Request JSON 946 Section 3.4. 948 * *uri* - the Grant URI. 950 * *wait* - a numeric value representing the number of seconds the 951 Client should want before making a Read Grant request to the Grant 952 URI. 954 * *expires_in* - a numeric value specifying how many seconds until 955 the Grant expires. This attribute is OPTIONAL. 957 4.4.1. "client" Object 959 The GS may 961 4.4.2. "interaction" Object 963 If the GS wants the Client to start the interaction, the GS MUST 964 return an interaction object containing one or more interaction mode 965 responses per Section 5 to one or more of the interaction mode 966 requests provided by the Client. 968 4.4.3. "user" Object 970 * *exists* - a boolean value indicating if the GS has a user with 971 one or more of the provided identifiers in the Request 972 user.identifiers object Section 3.4.3 974 4.4.4. "authorization" Object 976 The authorization object MUST contain only a "uri" attribute or the 977 following from Authorization JSON Section 4.5: 979 * mechanism 980 * token 982 The authorization object MAY contain any of the following from 983 Authorization JSON Section 4.5: 985 * access 987 * expires_in 989 * uri 991 If there is no "uri" attribute, the access token can not be 992 refreshed. If only the "uri" attribute is present, the Client MUST 993 acquire the Authorization per Section 3.5 995 4.4.5. "authorizations" Object 997 A key / value pair for each key in the Grant Request "authorizations" 998 object, and the value is per Section 4.4.4. 1000 4.4.6. "claims" Object 1002 The claims object is a response to the Grant Request "claims" object 1003 Section 3.4.4. 1005 * *oidc* 1007 - *id_token* - an OpenID Connect ID Token containing the Claims 1008 the User consented to be released. 1010 - *userinfo* - the Claims the User consented to be released. 1012 Claims are defined in [OIDC] Section 5. 1014 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1015 per [OIDC4IA]. 1017 * *vc* 1019 The verified claims the user consented to be released. _[Editor: 1020 details TBD]_ 1022 4.4.7. "warnings" JSON Array 1024 Includes zero or more warnings from Section 8, 1026 4.5. Authorization JSON 1028 The Authorization JSON is the contents of a Grant Response 1029 "authorization" object Section 4.4.5 or the response to a Read AuthZ 1030 request by the Client Section 3.5. 1032 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1033 See the "type" object in Section 3.4.4 for details 1035 * *mechanism* - the RS access mechanism. This document defines the 1036 "bearer" mechanism as defined in Section 6 1038 * *token* - the access token for accessing an RS. 1040 * *expires_in* - a numeric value specifying how many seconds until 1041 the access token expires. 1043 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1045 * *access* - an object containing the access granted: 1047 - *type* - the type of claim request: "oauth_scope" or 1048 "oauth_rich". See the "type" object in Section 3.4.4 for 1049 details. This attribute is REQUIRED. 1051 - *scope* - the scopes the Client was granted authorization for. 1052 This will be all, or a subset, of what was requested. This 1053 attribute is OPTIONAL. 1055 - *authorization_details* - the authorization details granted per 1056 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1058 _[Editor: would an optional expiry for the Authorization be useful?]_ 1060 The following is a non-normative example of Authorization JSON: 1062 { 1063 "mechanism" : "bearer", 1064 "token" : "eyJJ2D6.example.access.token.mZf9p" 1065 "expires_in" : 3600, 1066 "uri" : "https://as.example/endpoint/authz/example2", 1067 "access": { 1068 "type" : "oauth_scope", 1069 "scope" : "read_calendar write_calendar" 1070 } 1071 } 1073 4.6. Response Verification 1075 On receipt of a response, the Client MUST verify the following: 1077 * TBD 1079 5. Interaction Modes 1081 This document defines three interaction modes: "redirect", 1082 "indirect", and "user_code". Extensions may define additional 1083 interaction modes. 1085 The "global" attribute is reserved in the interaction object for 1086 attributes that apply to all interaction modes. 1088 5.1. "redirect" 1090 A Redirect Interaction is characterized by the Client redirecting the 1091 User's browser to the GS, the GS interacting with the User, and then 1092 GS redirecting the User's browser back to the Client. The GS 1093 correlates the Grant Request with the unique authorization_uri, and 1094 the Client correlates the Grant Request with the unique redirect_uri. 1096 *The request "interaction" object contains:* 1098 * *redirect_uri* a unique URI at the Client that the GS will return 1099 the User to. The URI MUST not contain the "nonce" from the Grant 1100 Request, and MUST not be guessable. This attribute is REQUIRED. 1102 *The response "interaction" object contains:* 1104 * *authorization_uri* a unique URI at the GS that the Client will 1105 redirect the User to. The URI MUST not contain the "nonce" from 1106 the Grant Request, and MUST not be guessable. This attribute is 1107 REQUIRED. 1109 5.2. "indirect" 1111 An Indirect Interaction is characterized by the Client causing the 1112 User's browser to load the short_uri at GS, the GS interacting with 1113 the User, and then the GS MAY optionally redirect the User's Browser 1114 to a completion_uri. There is no mechanism for the GS to redirect 1115 the User's browser back to the Client. 1117 Examples of how the Client may initiate the interaction are encoding 1118 the short_uri as a code scannable by the User's mobile device, or 1119 launching a system browser from a command line interface (CLI) 1120 application. 1122 The "indirect" mode is susceptible to session fixation attacks. See 1123 TBD in the Security Considerations for details. 1125 *The request "interaction" object contains:* 1127 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1128 User's browser to after GS interaction. 1130 *The response "interaction" object contains:* 1132 * *short_uri* the URI the Client will cause to load in the User's 1133 browser. The URI SHOULD be short enough to be easily encoded in a 1134 scannable code. The URI MUST not contain the "nonce" from the 1135 Grant Request, and MUST not be guessable. _[Editor: recommend a 1136 maximum length?]_ 1138 5.3. "user_code" 1140 An Indirect Interaction is characterized by the Client displaying a 1141 code and a URI for the User to load in a browser and then enter the 1142 code. _[Editor: recommend a minimum entropy?]_ 1144 *The request "interaction" object contains:* 1146 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1147 User's browser to after GS interaction. 1149 *The response "interaction" object contains:* 1151 * *code* the code the Client displays to the User to enter at the 1152 display_uri. This attribute is REQUIRED. 1154 * *display_uri* the URI the Client displays to the User to load in a 1155 browser to enter the code. 1157 6. RS Access 1159 The mechanism the Client MUST use to access an RS is in the 1160 Authorization JSON "mechanism" attribute Section 4.4.4. 1162 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1164 The "jose" and "jose+body" mechanisms are defined in 1165 [JOSE_Authentication] 1167 A non-normative "bearer" example of the HTTP request headers follows: 1169 GET /calendar HTTP/2 1170 Host: calendar.example 1171 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1173 7. Error Responses 1175 * TBD 1177 8. Warnings 1179 Warnings assist a Client in detecting non-fatal errors. 1181 * TBD 1183 9. Extensibility 1185 This standard can be extended in a number of areas: 1187 * *Client Authentication Mechanisms* 1189 - An extension could define other mechanisms for the Client to 1190 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1191 Signing. Constrained environments could use CBOR [RFC7049] 1192 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1193 [RFC8323] instead of HTTP/2. 1195 * *Grant* 1197 - An extension can define new objects in the Grant Request and 1198 Grant Response JSON that return new URIs. 1200 * *Top Level* 1202 - Top level objects SHOULD only be defined to represent 1203 functionality other the existing top level objects and 1204 attributes. 1206 * *"client" Object* 1208 - Additional information about the Client that the GS would 1209 require related to an extension. 1211 * *"user" Object* 1213 - Additional information about the User that the GS would require 1214 related to an extension. 1216 * *"authorization" Object* 1217 - Additional authorization schemas in addition to OAuth 2.0 1218 scopes and RAR. 1220 * *"claims" Object* 1222 - Additional claim schemas in addition to OpenID Connect claims 1223 and Verified Credentials. 1225 * *interaction modes* 1227 - Additional types of interactions a Client can start with the 1228 User. 1230 * *Continuous Authentication* 1232 - An extension could define a mechanism for the Client to 1233 regularly provide continuous authentication signals and receive 1234 responses. 1236 _[Editor: do we specify access token introspection in this document, 1237 or leave that to an extension?]_ 1239 10. Rational 1241 1. *Why have both Client ID and Client Handle?* 1243 While they both refer to a Client in the protocol, the Client ID 1244 refers to a pre-registered client,and the Client Handle is 1245 specific to an instance of a Dynamic Client. Using separate 1246 terms clearly differentiates which identifier is being presented 1247 to the GS. 1249 2. *Why allow Client and GS to negotiate the user interaction mode?* 1251 The Client knows what interaction modes it is capable of, and the 1252 GS knows which interaction modes it will permit for a given Grant 1253 Request. The Client can then present the intersection to the 1254 User to choose which one is preferred. For example, while a 1255 device based Client may be willing to do both "indirect" and 1256 "user_code", a GS may not enable "indirect" for concern of a 1257 session fixation attack. Additional interaction modes will 1258 likely become available which allows new modes to be negotiated 1259 between Client and GS as each adds additional interaction modes. 1261 3. *Why have both claims and authorizations?* 1262 There are use cases for each that are independent: authenticating 1263 a user and providing claims vs granting access to a resource. A 1264 request for an authorization returns an access token which may 1265 have full CRUD capabilities, while a request for a claim returns 1266 the claim about the User - with no create, update or delete 1267 capabilities. While the UserInfo endpoint in OIDC may be thought 1268 of as a resource, separating the concepts and how they are 1269 requested keeps each of them simpler in the Editor's opinion. :) 1271 4. *Why do some of the JSON objects only have one child, such as the 1272 identifiers object in the user object in the Grant Request?* 1274 It is difficult to forecast future use cases. Having more 1275 resolution may mean the difference between a simple extension, 1276 and a convoluted extension. For example, the "global" object in 1277 the "interaction" object allows new global parameters to be added 1278 without impacting new interaction modes. 1280 5. *Why is the "iss" included in the "oidc" identifier object? 1281 Would the "sub" not be enough for the GS to identify the User?* 1283 This decouples the GS from the OpenID Provider (OP). The GS 1284 identifier is the GS URI, which is the endpoint at the GS. The 1285 OP issuer identifier will likely not be the same as the GS URI. 1286 The GS may also provide claims from multiple OPs. 1288 6. *Why is there not a UserInfo endpoint as there is with OpenID 1289 Connect?* 1291 Since the Client can Read Grant at any time, it get the same 1292 functionality as the UserInfo endpoint, without the Client having 1293 to manage a separate access token and refresh token. If the 1294 Client would like additional claims, it can Update Grant, and the 1295 GS will let the Client know if an interaction is required to get 1296 any of the additional claims, which the Client can then start. 1298 _[Editor: is there some other reason to have the UserInfo 1299 endpoint?]_ 1301 7. *Why use URIs for the Grant and Authorization?* 1303 * Grant URI and AZ URI are defined to start with the GS URI, 1304 allowing the Client, and GS to determine which GS a Grant or 1305 Authorization belongs to. 1307 * URIs also enable a RESTful interface to the GS functionality. 1309 * A large scale GS can easily separate out the services that 1310 provide functionality as routing of requests can be done at 1311 the HTTP layer based on URI and HTTP verb. This allows a 1312 separation of concerns, independent deployment, and 1313 resiliency. 1315 8. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 1316 known mechanism?* 1318 Having the GS URI endpoint respond to the metadata allows the GS 1319 to provide Client specific results using the same Client 1320 authentication used for other requests to the GS. It also 1321 reduces the risk of a mismatch between the advertised metadata, 1322 and the actual metadata. A .well-known discovery mechanism may 1323 be defined to resolve from a hostname to the GS URI. 1325 11. Acknowledgments 1327 This draft derives many of its concepts from Justin Richer's 1328 Transactional Authorization draft [TxAuth]. 1330 Additional thanks to Justin Richer and Annabelle Richard Backman for 1331 their strong critique of earlier drafts. 1333 12. IANA Considerations 1335 TBD 1337 13. Security Considerations 1339 TBD 1341 14. References 1343 14.1. Normative References 1345 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1346 Requirement Levels", BCP 14, RFC 2119, 1347 DOI 10.17487/RFC2119, March 1997, 1348 . 1350 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1351 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1352 . 1354 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1355 DOI 10.17487/RFC5322, October 2008, 1356 . 1358 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1359 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1360 . 1362 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1363 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1364 September 2009, . 1366 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1367 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1368 . 1370 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1371 Framework: Bearer Token Usage", RFC 6750, 1372 DOI 10.17487/RFC6750, October 2012, 1373 . 1375 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1376 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1377 . 1379 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1380 Interchange Format", STD 90, RFC 8259, 1381 DOI 10.17487/RFC8259, December 2017, 1382 . 1384 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1385 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1386 . 1388 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1389 Assurance 1.0", October 2019, . 1392 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1393 Rich Authorization Requests", January 2020, 1394 . 1396 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1397 Credentials Data Model 1.0", November 2019, 1398 . 1400 [JOSE_Authentication] 1401 Hardt, D., "JOSE Authentication", June 2020, 1402 . 1404 [GNAP_Advanced] 1405 Hardt, D., "The Grant Negotiation and Authorization 1406 Protocol - Advanced Features", June 2020, 1407 . 1409 14.2. Informative References 1411 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1412 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1413 October 2013, . 1415 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1416 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1417 . 1419 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1420 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1421 Application Protocol) over TCP, TLS, and WebSockets", 1422 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1423 . 1425 [browser_based_apps] 1426 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1427 Apps", September 2019, . 1430 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1431 identification and data capture techniques - QR Code bar 1432 code symbology specification", February 2015, 1433 . 1435 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1436 . 1439 Appendix A. Document History 1441 A.1. draft-hardt-xauth-protocol-00 1443 * Initial version 1445 A.2. draft-hardt-xauth-protocol-01 1447 * text clean up 1449 * added OIDC4IA claims 1451 * added "jws" method for accessing a resource. 1453 * renamed Initiation Request -> Grant Request 1455 * renamed Initiation Response -> Interaction Response 1457 * renamed Completion Request -> Authorization Request 1459 * renamed Completion Response -> Grant Request 1461 * renamed completion handle -> authorization handle 1463 * added Authentication Request, Authentication Response, 1464 authentication handle 1466 A.3. draft-hardt-xauth-protocol-02 1468 * major rewrite 1470 * handles are now URIs 1472 * the collection of claims and authorizations are a Grant 1474 * an Authorization is its own type 1476 * lots of sequences added 1478 A.4. draft-hardt-xauth-protocol-03 1480 * fixed RO definition 1482 * improved language in Rationals 1484 * added user code interaction method, and aligned qrcode interaction 1485 method 1487 * added completion_uri for code flows 1489 A.5. draft-hardt-xauth-protocol-04 1491 * renamed interaction uris to have purpose specific names 1493 A.6. draft-hardt-xauth-protocol-05 1495 * separated claims from identifiers in request user object 1497 * simplified reciprocal grant flow 1499 * reduced interactions to redirect and indirect 1500 * simplified interaction parameters 1502 * added in language for Client to verify interaction completion 1504 * added Verify Grant API and Interaction Nonce 1506 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1507 operation. 1509 A.7. draft-hardt-xauth-protocol-06 1511 * fixup examples to match specification 1513 A.8. draft-hardt-xauth-protocol-07 1515 * refactored interaction request and response syntax, and enabled 1516 interaction mode negotiation 1518 * generation of client handle by GS for dynamic clients 1520 * renamed title to Grant Negotiation and Authorization Protocol. 1521 Preserved draft-hardt-xauth-protocol filename to ease tracking 1522 changes. 1524 * changed Authorizations to be key / value pairs (aka dictionary) 1525 instead of a JSON array 1527 A.9. draft-hardt-xauth-protocol-08 1529 * split document into three documents: core, advanced, and JOSE 1530 authentication. 1532 * grouped access granted into "access" object in Authorization JSON 1534 * added warnings object to the Grant Response JSON 1536 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1538 *Changed Features* 1540 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1542 * The Client always uses a private asymetric key to authenticate to 1543 the GS. There is no client secret. i 1545 * The Client initiates the protocol by making a signed request 1546 directly to the GS instead of redirecting the User to the GS. 1548 * The Client does not pass any parameters in redirecting the User to 1549 the GS. 1551 * The refresh_token has been replaced with a AZ URI that both 1552 represents the authorization, and is the URI for obtaining a fresh 1553 access token. 1555 * The Client can request identity claims to be returned independent 1556 of the ID Token. There is no UserInfo endpoint to query claims as 1557 there is in OpenID Connect. 1559 * The GS URI is the token endpoint. 1561 *Preserved Features* 1563 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1564 2.0. 1566 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1568 * No change is required by the Client or the RS for accessing 1569 existing bearer token protected APIs. 1571 *New Features* 1573 * All Client calls to the GS are authenticated with asymetric 1574 cryptography 1576 * A Grant represents both the user identity claims and RS access 1577 granted to the Client. 1579 * Support for scannable code initiated interactions. 1581 * Highly extensible per Section 9. 1583 Author's Address 1585 Dick Hardt (editor) 1586 SignIn.Org 1587 United States 1589 Email: dick.hardt@gmail.com