idnits 2.17.00 (12 Aug 2021) /tmp/idnits32645/draft-hardt-xauth-protocol-08.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 (6 June 2020) is 714 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 6 June 2020 5 Expires: 8 December 2020 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-08 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 8 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 . . . . . . . . . . . . . . . . . . . . . . 5 59 1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6 61 2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 7 63 2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . . . . . . 14 70 3.4. Request JSON . . . . . . . . . . . . . . . . . . . . . . 14 71 3.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 14 72 3.4.2. "interaction" Object . . . . . . . . . . . . . . . . 15 73 3.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 15 74 3.4.4. "authorization" Object . . . . . . . . . . . . . . . 16 75 3.4.5. "authorizations" Object . . . . . . . . . . . . . . . 16 76 3.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 16 77 3.5. Read Authorization . . . . . . . . . . . . . . . . . . . 17 78 3.6. GS Options . . . . . . . . . . . . . . . . . . . . . . . 17 79 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 18 80 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 18 81 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 19 82 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 20 83 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 21 84 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 21 85 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 21 86 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 21 87 4.4.4. "authorization" Object . . . . . . . . . . . . . . . 21 88 4.4.5. "authorizations" Object . . . . . . . . . . . . . . . 22 89 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 22 90 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 22 91 4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 23 92 4.6. Response Verification . . . . . . . . . . . . . . . . . . 24 93 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 24 94 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 24 95 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 24 96 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 25 98 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 25 99 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 26 100 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 26 101 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 26 102 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 27 103 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 104 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 105 13. Security Considerations . . . . . . . . . . . . . . . . . . . 29 106 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 107 14.1. Normative References . . . . . . . . . . . . . . . . . . 29 108 14.2. Informative References . . . . . . . . . . . . . . . . . 31 109 Appendix A. Document History . . . . . . . . . . . . . . . . . . 31 110 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 31 111 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 31 112 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 32 113 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 32 114 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 32 115 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 32 116 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 33 117 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 33 118 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 33 119 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 33 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 34 122 1. Introduction 124 This document describes the core Grant Negotiation and Authorization 125 Protocol (GNAP). The protocol supports the widely deployed use cases 126 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 127 an extension of OAuth 2.0, as well as other extensions. Related 128 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 129 Authentication [JOSE_Authentication] that describes the JOSE 130 mechanisms for client authentication. 132 The technology landscape has changed since OAuth 2.0 was initially 133 drafted. More interactions happen on mobile devices than PCs. 134 Modern browsers now directly support asymetric cryptographic 135 functions. Standards have emerged for signing and encrypting tokens 136 with rich payloads (JOSE) that are widely deployed. 138 GNAP simplifies the overall architectural model, takes advantage of 139 today's technology landscape, provides support for all the widely 140 deployed use cases, offers numerous extension points, and addresses 141 many of the security issues in OAuth 2.0 by passing parameters 142 securely between parties, rather than via a browser redirection. . 144 While GNAP is not backwards compatible with OAuth 2.0, it strives to 145 minimize the migration effort. 147 GNAP centers around a Grant, a representation of the collection of 148 user identity claims and/or resource authorizations the Client is 149 requesting, and the resulting identity claims and/or resource 150 authorizations granted by the Grant Server (GS). 152 User consent is often required at the GS. GNAP enables a Client and 153 GS to negotiate the interaction mode for the GS to obtain consent. 155 The suggested pronunciation of GNAP is the same as the English word 156 "nap", a silent "g" as in "gnaw". 158 _[Editor: suggestions on how to improve this are welcome!]_ 160 1.1. Parties 162 The parties and their relationships to each other: 164 +--------+ +------------+ 165 | User | | Resource | 166 | | | Owner (RO) | 167 +--------+ +------------+ 168 | \ / | 169 | \ / | 170 | \ / | 171 | \ / | 172 +--------+ +---------------+ +------------+ 173 | Client |---->| Grant | | Resource | 174 | | (1) | Server (GS) | _ _ | Server | 175 | |<----| | | (RS) | 176 | | +---------------+ | | 177 | |-------------------------->| | 178 | | (2) | | 179 | |<--------------------------| | 180 +--------+ +------------+ 182 This document specifies interactions between the Client and GS (1), 183 and the Client and RS (2). 185 * *User* - the person interacting with the Client who has delegated 186 access to identity claims about themselves to the Grant Server 187 (GS), and can authenticate at the GS. 189 * *Client* - requests a Grant from the GS to access one or more 190 Resource Servers (RSs), and/or identity claims about the User. 191 The Grant may include access tokens that the Client uses to access 192 the RS. There are two types of Clients: Registered Clients and 193 Dynamic Clients. All Clients have a private asymetric key to 194 authenticate with the Grant Server. 196 * *Registered Client* - a Client that has registered with the GS and 197 has a Client ID to identify itself, and can prove it possesses a 198 key that is linked to the Client ID. The GS may have different 199 policies for what different Registered Clients can request. A 200 Registered Client MAY be interacting with a User. 202 * *Dynamic Client* - a Client that has not been previously 203 registered with the GS, and each instance will generate it's own 204 asymetric key pair so it can prove it is the same instance of the 205 Client on subsequent requests. The GS MAY return a Dynamic Client 206 a Client Handle for the Client to identify itself in subsequent 207 requests. A single-page application with no active server 208 component is an example of a Dynamic Client. A Dynamic Client 209 MUST be interacting with a User. 211 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 212 release of identity claims about the User. The GS may require 213 explicit consent from the RO or User to provide these to the 214 Client. A GS may support Registered Clients and/or Dynamic 215 Clients. The GS is a combination of the Authorization Server (AS) 216 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 218 * *Resource Server* (RS) - has API resources that require an access 219 token from the GS. Some, or all of the resources are owned by the 220 Resource Owner. 222 * *Resource Owner* (RO) - owns resources at the RS, and has 223 delegated RS access management to the GS. The RO may be the same 224 entity as the User, or may be a different entity that the GS 225 interacts with independently. GS and RO interactions are out of 226 scope of this document. 228 1.2. Reused Terms 230 * *access token* - an access token as defined in [RFC6749] 231 Section 1.4. 233 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 234 issued by the GS, or by other issuers. 236 * *Client ID* - a GS unique identifier for a Registered Client as 237 defined in [RFC6749] Section 2.2. 239 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 241 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 243 * *authN* - short for authentication. 245 * *authZ* - short for authorization. 247 1.3. New Terms 249 * *GS URI* - the endpoint at the GS the Client calls to create a 250 Grant, and is the unique identifier for the GS. 252 * *Grant* - the user identity claims and/or RS authorizations the GS 253 has granted to the Client. The GS MAY invalidate a Grant at any 254 time. 256 * *Grant URI* - the URI that represents the Grant. The Grant URI 257 MUST start with the GS URI. 259 * *Authorization* - the access granted by the RO to the Client and 260 contains an access token. The GS may invalidate an Authorization 261 at any time. 263 * *Authorization URI* (AZ URI) - the URI that represents the 264 Authorization the Client was granted by the RO. The AZ URI MUST 265 start with the GS URI. The AZ URI is used to refresh an access 266 token. 268 * *Interaction* - how the Client directs the User to interact with 269 the GS. This document defines the interaction modes: "redirect", 270 "indirect", and "user_code" in Section 5 272 * *Client Handle* - a unique identifier at the GS for a Dynamic 273 Client for the Dynamic Client to refer to itself in subsequent 274 requests. 276 1.4. Notational Conventions 278 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 279 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 280 specification are to be interpreted as described in [RFC2119]. 282 Certain security-related terms are to be understood in the sense 283 defined in [RFC4949]. These terms include, but are not limited to, 284 "attack", "authentication", "authorization", "certificate", 285 "confidentiality", "credential", "encryption", "identity", "sign", 286 "signature", "trust", "validate", and "verify". 288 _[Editor: review terms]_ 290 Unless otherwise noted, all the protocol parameter names and values 291 are case sensitive. 293 Some protocol parameters are parts of a JSON document, and are 294 referred to in JavaScript notation. For example, foo.bar refers to 295 the "bar" boolean attribute in the "foo" object in the following 296 example JSON document: 298 { 299 "foo" : { 300 "bar": true 301 } 302 } 304 2. Sequences 306 Before any sequence, the Client needs to be manually or 307 programmatically configured for the GS. See GS Options Section 3.6 308 for details on programmatically acquiring GS metadata. 310 2.1. "redirect" Interaction 312 The Client is a web application and wants a Grant from the User: 314 +--------+ +-------+ 315 | Client | | GS | 316 | |--(1)--- Create Grant ----------->| | 317 | | | | 318 | |<--- Interaction Response ---(2)--| | +------+ 319 | | | | | User | 320 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 321 | | | |<--(4)-->| | 322 | | | | authN | | 323 | | | | | | 324 | | | |<--(5)-->| | 325 | | | | authZ | | 326 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 327 | | | | | | 328 | |--(7)--- Read Grant ------------->| | +------+ 329 | | | | 330 | |<--------- Grant Response ---(8)--| | 331 | | | | 332 +--------+ +-------+ 334 1. *Create Grant* The Client creates a Request JSON document 335 Section 3.4 containing an interaction.redirect object and makes a 336 Create Grant request (Section 3.2) by sending the JSON with an 337 HTTP POST to the GS URI. 339 2. *Interaction Response* The GS determines that interaction with 340 the User is required and sends an Interaction Response 341 (Section 4.2) containing the Grant URI and an 342 interaction.redirect object. 344 3. *Interaction Transfer* The Client redirects the User to the 345 authorization_uri at the GS. 347 4. *User Authentication* The GS authenticates the User. 349 5. *User Authorization* If required, the GS interacts with the User 350 to determine which identity claims and/or authorizations in the 351 Grant Request are to be granted. 353 6. *Interaction Transfer* The GS redirects the User to the 354 redirect_uri at the Client. 356 7. *Read Grant* The Client makes an HTTP GET request to the Grant 357 URI. 359 8. *Grant Response* The GS responds with a Grant Response 360 (Section 4.1). 362 2.2. "user_code" Interaction 364 A Client is on a device wants a Grant from the User: 366 +--------+ +-------+ 367 | Client | | GS | 368 | |--(1)--- Create Grant ----------->| | 369 | | | | 370 | |<--- Interaction Response ---(2)--| | +------+ 371 | | | | | User | 372 | |--(3)--- Read Grant ------------->| | | | 373 | | | |<--(4)-->| | 374 | | | | authN | | 375 | | | | | | 376 | | | |<--(5)---| | 377 | | | | code | | 378 | | | | | | 379 | | | |<--(6)-->| | 380 | | | | authZ | | 381 | | | | | | 382 | |<--------- Grant Response ---(7)--| | | | 383 | | | | | | 384 +--------+ | | | | 385 | | | | 386 +--------+ | | | | 387 | Client |<----- Completion URI Redirect -- | - - - | --(8)---| | 388 | Server | | | | | 389 +--------+ +-------+ +------+ 391 1. *Create Grant* The Client creates a Request JSON document 392 Section 3.4 containing an interaction.user_code object and makes 393 a Create Grant request (Section 3.2) by sending the JSON with an 394 HTTP POST to the GS URI. 396 2. *Interaction Response* The GS determines that interaction with 397 the User is required and sends an Interaction Response 398 (Section 4.2) containing the Grant URI and an 399 interaction.user_code object. 401 3. *Read Grant* The Client makes an HTTP GET request to the Grant 402 URI. 404 4. *User Authentication* The User loads display_uri in their 405 browser, and the GS authenticates the User. 407 5. *User Code* The User enters the code at the GS. 409 6. *User Authorization* If required, the GS interacts with the User 410 to determine which identity claims and/or authorizations in the 411 Grant Request are to be granted. 413 7. *Grant Response* The GS responds with a Grant Response 414 (Section 4.1). 416 8. *Completion URI Redirect* The GS redirects the User to the 417 completion_uri provided by the Client. 419 2.3. Independent RO Authorization 421 The Client wants access to resources that require the GS to interact 422 with the RO, who is not interacting with the Client. The 423 authorization from the RO may take some time, so the GS instructs the 424 Client to wait and check back later. 426 +--------+ +-------+ 427 | Client | | GS | 428 | |--(1)--- Create Grant ----------->| | 429 | | | | 430 | |<---------- Wait Response ---(2)--| | +------+ 431 | (3) | | | | RO | 432 | Wait | | |<--(4)-->| | 433 | | | | AuthZ | | 434 | |--(5)--- Read Grant ------------->| | +------+ 435 | | | | 436 | |<--------- Grant Response --(6)---| | 437 | | | | 438 +--------+ +-------+ 440 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 441 and sends it with an HTTP POST to the GS GS URI. 443 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 444 containing the Grant URI and the "wait" attribute. 446 3. *Client Waits* The Client waits for the time specified in the 447 "wait" attribute. 449 4. *RO AuthZ* The GS interacts with the RO to determine which 450 identity claims and/or resource authorizations in the Grant 451 Request are to be granted. 453 5. *Read Grant* The Client does an HTTP GET of the Grant URI 454 (Section 3.3). 456 6. *Grant Response* The GS responds with a Grant Response 457 (Section 4.1). 459 2.4. Resource Server Access 461 The Client received an AZ URI from the GS. The Client acquires an 462 access token, calls the RS, and later the access token expires. The 463 Client then gets a fresh access token. 465 +--------+ +----------+ +-------+ 466 | Client | | Resource | | GS | 467 | |--(1)--- Access Resource --->| Server | | | 468 | |<------- Resource Response --| (RS) | | | 469 | | | | | | 470 | |--(2)--- Access Resource --->| | | | 471 | |<------- Error Response -----| | | | 472 | | | | | | 473 | | +----------+ | | 474 | | | | 475 | |--(3)--- Read AuthZ ---------------------->| | 476 | |<------- AuthZ Response -------------------| | 477 | | | | 478 +--------+ +-------+ 480 1. *Resource Request* The Client accesses the RS with the access 481 token per Section 6 and receives a response from the RS. 483 2. *Resource Request* The Client attempts to access the RS, but 484 receives an error indicating the access token needs to be 485 refreshed. 487 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.5) with an 488 HTTP GET to the AZ URI and receives an Response JSON 489 "authorization" object (Section 4.4.4) with a fresh access token. 491 3. GS APIs 493 *Client Authentication* 495 All GS APIs except for GS Options require the Client to authenticate. 496 Authentication mechanisms include: 498 * JOSE Authentication [JOSE_Authentication] 500 * [Others TBD]* 502 3.1. GS API Table 504 +--------------+-----------+--------+-----------------------------+ 505 | request | http verb | uri | response | 506 +==============+===========+========+=============================+ 507 | GS Options | OPTIONS | GS URI | metadata | 508 +--------------+-----------+--------+-----------------------------+ 509 | Create Grant | POST | GS URI | interaction, wait, or grant | 510 +--------------+-----------+--------+-----------------------------+ 511 | Read Grant | GET | Grant | wait, or grant | 512 | | | URI | | 513 +--------------+-----------+--------+-----------------------------+ 514 | Read AuthZ | GET | AZ URI | authorization | 515 +--------------+-----------+--------+-----------------------------+ 517 Table 1 519 3.2. Create Grant 521 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 522 document to the GS URI. This is a Greant Request. 524 The JSON document MUST include the following from the Request JSON 525 Section 3.4: 527 * iat 529 * nonce 531 * uri set to the GS URI 533 * client 535 and MAY include the following from Request JSON Section 3.4 537 * user 539 * interaction 541 * authorization or authorizations 543 * claims 545 The GS MUST respond with one of Grant Response Section 4.1, 546 Interaction Response Section 4.2, Wait Response Section 4.3, or one 547 of the following errors: 549 * TBD 550 from Error Responses Section 7. 552 Following is a non-normative example of a web application Client 553 requesting identity claims about the User and read access to the 554 User's contacts: 556 Example 1 558 { 559 "iat" : 15790460234, 560 "uri" : "https://as.example/endpoint", 561 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 562 "client": { 563 "display": { 564 "name" : "SPA Display Name", 565 "uri" : "https://spa.example/about" 566 } 567 }, 568 "interaction": { 569 "redirect": { 570 "redirect_uri" : "https://web.example/return" 571 }, 572 "global" : { 573 "ui_locals" : "de" 574 } 575 }, 576 "authorization": { 577 "type" : "oauth_scope", 578 "scope" : "read_contacts" 579 }, 580 "claims": { 581 "oidc": { 582 "id_token" : { 583 "email" : { "essential" : true }, 584 "email_verified" : { "essential" : true } 585 }, 586 "userinfo" : { 587 "name" : { "essential" : true }, 588 "picture" : null 589 } 590 } 591 } 592 } 594 Following is a non-normative example of a device Client requesting 595 access to play music: 597 Example 2 599 { 600 "iat" : 15790460234, 601 "uri" : "https://as.example/endpoint", 602 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 603 "client": { 604 "id" : "di3872h34dkJW" 605 }, 606 "interaction": { 607 "indirect": { 608 "completion_uri": "https://device.example/c/indirect" 609 }, 610 "user_code": { 611 "completion_uri": "https://device.example/c/user_code" 612 } 613 }, 614 "authorization": { 615 "type" : "oauth_scope", 616 "scope" : "play_music" 617 } 618 } 620 3.3. Read Grant 622 The Client reads a Grant by doing an HTTP GET of the corresponding 623 Grant URI. The Client MAY read a Grant until it expires or has been 624 invalidated. 626 The GS MUST respond with one of Grant Response Section 4.1, Wait 627 Response Section 4.3, or one of the following errors: 629 * TBD 631 3.4. Request JSON 633 * *iat* - the time of the request as a NumericDate. 635 * *nonce* - a unique identifier for this request. Note the Grant 636 Response MUST contain a matching "nonce" attribute value. 638 * *uri* - the GS URI 640 3.4.1. "client" Object 642 The client object MUST only one of the following: 644 * *id* - the Client ID the GS has for a Registered Client. 646 * *handle* - the Client Handle the GS previously provided a Dynamic 647 Client 649 * *display* - the display object contains the following attributes: 651 - *name* - a string that represents the Dynamic Client 653 - *uri* - a URI representing the Dynamic Client 655 The GS will show the the User the display.name and display.uri values 656 when prompting for authorization. 658 _[Editor: a max length for the name and URI so a GS can reserve 659 appropriate space?]_ 661 3.4.2. "interaction" Object 663 The interaction object contains one or more interaction mode objects 664 per Section 5 representing the interactions the Client is willing to 665 provide the User. In addition to the interaction mode objects, the 666 interaction object may contain the "global" object; 668 * *global* - an optional object containing parameters that are 669 applicable for all interaction modes. Only one attribute is 670 defined in this document: 672 - *ui_locales* - End-User's preferred languages and scripts for 673 the user interface, represented as a space-separated list of 674 [RFC5646] language tag values, ordered by preference. This 675 attribute is OPTIONAL. 677 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 678 a JSON array?]_ 680 3.4.3. "user" Object 682 * *identifiers* - The identifiers MAY be used by the GS to improve 683 the User experience. This object contains one or more of the 684 following identifiers for the User: 686 - *phone_number* - contains a phone number per Section 5 of 687 [RFC3966]. 689 - *email* - contains an email address per [RFC5322]. 691 - *oidc* - is an object containing both the "iss" and "sub" 692 attributes from an OpenID Connect ID Token [OIDC] Section 2. 694 * *claims* - an optional object containing one or more assertions 695 the Client has about the User. 697 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 698 Section 2. 700 3.4.4. "authorization" Object 702 * *type* - one of the following values: "oauth_scope" or 703 "oauth_rich". This attribute is REQUIRED. 705 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 706 section 3.3. MUST be included if type is "oauth_scope" or 707 "oauth_rich". 709 * *authorization_details* - an authorization_details object per 710 [RAR]. MUST be included if type is "oauth_rich". 712 _[Editor: details may change as the RAR document evolves]_ 714 3.4.5. "authorizations" Object 716 One or more key / value pairs, where each unique key is created by 717 the client, and the value is an authorization object per 718 Section 3.4.4. 720 3.4.6. "claims" Object 722 Includes one or more of the following: 724 * *oidc* - an object that contains one or both of the following 725 objects: 727 - *userinfo* - Claims that will be returned as a JSON object 729 - *id_token* - Claims that will be included in the returned ID 730 Token. If the null value, an ID Token will be returned 731 containing no additional Claims. 733 The contents of the userinfo and id_token objects are Claims as 734 defined in [OIDC] Section 5. 736 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 737 per [OIDC4IA]. 739 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 740 requested.]_[W3C_VC] 742 3.5. Read Authorization 744 The Client acquires and refreshes an Authorization by doing an HTTP 745 GET to the corresponding AZ URI. 747 The GS MUST respond with a Authorization JSON document Section 4.5, 748 or one of the following errors: 750 * TBD 752 from Error Responses Section 7. 754 3.6. GS Options 756 The Client can get the metadata for the GS by doing an HTTP OPTIONS 757 of the corresponding GS URI. This is the only API where the GS MAY 758 respond to an unauthenticated request. 760 The GS MUST respond with the the following JSON document: 762 * *uri* - the GS URI. 764 * *client_authentication* - a JSON array of the Client 765 Authentication mechanisms supported by the GS 767 * *interactions* - a JSON array of the interaction modes supported 768 by the GS. 770 * *authorization* - an object containing the authorizations the 771 Client may request from the GS, if any. 773 - Details TBD 775 * *claims* - an object containing the identity claims the Client may 776 request from the GS, if any, and what public keys the claims will 777 be signed with. 779 - Details TBD 781 * *algorithms* - a JSON array of the cryptographic algorithms 782 supported by the GS. [details TBD]* 784 * *features* - an object containing feature support 786 - *authorizations* - boolean indicating if a request for more 787 than one authorization in a request is supported. 789 or one of the following errors: 791 * TBD 793 from Error Responses Section 7. 795 4. GS Responses 797 There are three successful responses to a Grant Request: Grant 798 Response, Interaction Response, or Wait Response. 800 4.1. Grant Response 802 The Grant Response MUST include the following from the Response JSON 803 Section 4.4 805 * iat 807 * nonce 809 * uri 811 and MAY include the following from the Response JSON Section 4.4 813 * client.handle 815 * authorization or authorizations 817 * claims 819 * expires_in 821 * warnings 823 Example non-normative Grant Response JSON document for Example 1 in 824 Section 3.2: 826 { 827 "iat" : 15790460234, 828 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 829 "uri" : "https://as.example/endpoint/grant/example1", 830 "expires_in" : 300 831 "authorization": { 832 "type" : "oauth_scope", 833 "scope" : "read_contacts", 834 "expires_in" : 3600, 835 "mechanism" : "bearer", 836 "token" : "eyJJ2D6.example.access.token.mZf9p" 837 }, 838 "claims": { 839 "oidc": { 840 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 841 "userinfo" : { 842 "name" : "John Doe", 843 "picture" : "https://photos.example/p/eyJzdkiO" 844 } 845 } 846 } 847 } 849 Note in this example the access token can not be refreshed, and 850 expires in an hour. 852 Example non-normative Grant Response JSON document for Example 2 in 853 Section 3.2: 855 { 856 "iat" : 15790460234, 857 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 858 "uri" : "https://as.example/endpoint/grant/example2", 859 "authorization": { 860 "uri" : "https://as.example/endpoint/authz/example2" 861 } 862 } 864 Note in this example the GS only provided the AZ URI, and Client must 865 acquire the Authorization per Section 3.5 867 4.2. Interaction Response 869 The Interaction Response MUST include the following from the Response 870 JSON Section 4.4 872 * iat 873 * nonce 875 * uri 877 * interaction 879 and MAY include the following from the Response JSON Section 4.4 881 * user 883 * wait 885 * warnings 887 A non-normative example of an Interaction Response follows: 889 { 890 "iat" : 15790460234, 891 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 892 "uri" : "https://as.example/endpoint/grant/example4", 893 "interaction" : { 894 ""redirect" : { 895 "authorization_uri" : "https://as.example/i/example4" 896 } 897 }, 898 "user": { 899 "exists" : true 900 } 901 } 903 4.3. Wait Response 905 The Wait Response MUST include the following from the Response JSON 906 Section 4.4 908 * iat 910 * nonce 912 * uri 914 * wait 916 and MAY include the following from the Response JSON Section 4.4 918 * warnings 920 A non-normative example of Wait Response follows: 922 { 923 "iat" : 15790460234, 924 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 925 "uri" : "https://as.example/endpoint/grant/example5", 926 "wait" : 300 927 } 929 4.4. Response JSON 931 Details of the JSON document: 933 * *iat* - the time of the response as a NumericDate. 935 * *nonce* - the nonce that was included in the Request JSON 936 Section 3.4. 938 * *uri* - the Grant URI. 940 * *wait* - a numeric value representing the number of seconds the 941 Client should want before making a Read Grant request to the Grant 942 URI. 944 * *expires_in* - a numeric value specifying how many seconds until 945 the Grant expires. This attribute is OPTIONAL. 947 4.4.1. "client" Object 949 The GS may 951 4.4.2. "interaction" Object 953 If the GS wants the Client to start the interaction, the GS MUST 954 return an interaction object containing one or more interaction mode 955 responses per Section 5 to one or more of the interaction mode 956 requests provided by the Client. 958 4.4.3. "user" Object 960 * *exists* - a boolean value indicating if the GS has a user with 961 one or more of the provided identifiers in the Request 962 user.identifiers object Section 3.4.3 964 4.4.4. "authorization" Object 966 The authorization object MUST contain only a "uri" attribute or the 967 following from Authorization JSON Section 4.5: 969 * mechanism 970 * token 972 The authorization object MAY contain any of the following from 973 Authorization JSON Section 4.5: 975 * access 977 * expires_in 979 * uri 981 If there is no "uri" attribute, the access token can not be 982 refreshed. If only the "uri" attribute is present, the Client MUST 983 acquire the Authorization per Section 3.5 985 4.4.5. "authorizations" Object 987 A key / value pair for each key in the Grant Request "authorizations" 988 object, and the value is per Section 4.4.4. 990 4.4.6. "claims" Object 992 The claims object is a response to the Grant Request "claims" object 993 Section 3.4.4. 995 * *oidc* 997 - *id_token* - an OpenID Connect ID Token containing the Claims 998 the User consented to be released. 1000 - *userinfo* - the Claims the User consented to be released. 1002 Claims are defined in [OIDC] Section 5. 1004 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1005 per [OIDC4IA]. 1007 * *vc* 1009 The verified claims the user consented to be released. _[Editor: 1010 details TBD]_ 1012 4.4.7. "warnings" JSON Array 1014 Includes zero or more warnings from Section 8, 1016 4.5. Authorization JSON 1018 The Authorization JSON is the contents of a Grant Response 1019 "authorization" object Section 4.4.5 or the response to a Read AuthZ 1020 request by the Client Section 3.5. 1022 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1023 See the "type" object in Section 3.4.4 for details 1025 * *mechanism* - the RS access mechanism. This document defines the 1026 "bearer" mechanism as defined in Section 6 1028 * *token* - the access token for accessing an RS. 1030 * *expires_in* - a numeric value specifying how many seconds until 1031 the access token expires. 1033 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1035 * *access* - an object containing the access granted: 1037 - *type* - the type of claim request: "oauth_scope" or 1038 "oauth_rich". See the "type" object in Section 3.4.4 for 1039 details. This attribute is REQUIRED. 1041 - *scope* - the scopes the Client was granted authorization for. 1042 This will be all, or a subset, of what was requested. This 1043 attribute is OPTIONAL. 1045 - *authorization_details* - the authorization details granted per 1046 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1048 _[Editor: would an optional expiry for the Authorization be useful?]_ 1050 The following is a non-normative example of Authorization JSON: 1052 { 1053 "mechanism" : "bearer", 1054 "token" : "eyJJ2D6.example.access.token.mZf9p" 1055 "expires_in" : 3600, 1056 "uri" : "https://as.example/endpoint/authz/example2", 1057 "access": { 1058 "type" : "oauth_scope", 1059 "scope" : "read_calendar write_calendar" 1060 } 1061 } 1063 4.6. Response Verification 1065 On receipt of a response, the Client MUST verify the following: 1067 * TBD 1069 5. Interaction Modes 1071 This document defines three interaction modes: "redirect", 1072 "indirect", and "user_code". Extensions may define additional 1073 interaction modes. 1075 The "global" attribute is reserved in the interaction object for 1076 attributes that apply to all interaction modes. 1078 5.1. "redirect" 1080 A Redirect Interaction is characterized by the Client redirecting the 1081 User's browser to the GS, the GS interacting with the User, and then 1082 GS redirecting the User's browser back to the Client. The GS 1083 correlates the Grant Request with the unique authorization_uri, and 1084 the Client correlates the Grant Request with the unique redirect_uri. 1086 *The request "interaction" object contains:* 1088 * *redirect_uri* a unique URI at the Client that the GS will return 1089 the User to. The URI MUST not contain the "nonce" from the Grant 1090 Request, and MUST not be guessable. This attribute is REQUIRED. 1092 *The response "interaction" object contains:* 1094 * *authorization_uri* a unique URI at the GS that the Client will 1095 redirect the User to. The URI MUST not contain the "nonce" from 1096 the Grant Request, and MUST not be guessable. This attribute is 1097 REQUIRED. 1099 5.2. "indirect" 1101 An Indirect Interaction is characterized by the Client causing the 1102 User's browser to load the short_uri at GS, the GS interacting with 1103 the User, and then the GS MAY optionally redirect the User's Browser 1104 to a completion_uri. There is no mechanism for the GS to redirect 1105 the User's browser back to the Client. 1107 Examples of how the Client may initiate the interaction are encoding 1108 the short_uri as a code scannable by the User's mobile device, or 1109 launching a system browser from a command line interface (CLI) 1110 application. 1112 The "indirect" mode is susceptible to session fixation attacks. See 1113 TBD in the Security Considerations for details. 1115 *The request "interaction" object contains:* 1117 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1118 User's browser to after GS interaction. 1120 *The response "interaction" object contains:* 1122 * *short_uri* the URI the Client will cause to load in the User's 1123 browser. The URI SHOULD be short enough to be easily encoded in a 1124 scannable code. The URI MUST not contain the "nonce" from the 1125 Grant Request, and MUST not be guessable. _[Editor: recommend a 1126 maximum length?]_ 1128 5.3. "user_code" 1130 An Indirect Interaction is characterized by the Client displaying a 1131 code and a URI for the User to load in a browser and then enter the 1132 code. _[Editor: recommend a minimum entropy?]_ 1134 *The request "interaction" object contains:* 1136 * *completion_uri* an OPTIONAL URI that the GS will redirect the 1137 User's browser to after GS interaction. 1139 *The response "interaction" object contains:* 1141 * *code* the code the Client displays to the User to enter at the 1142 display_uri. This attribute is REQUIRED. 1144 * *display_uri* the URI the Client displays to the User to load in a 1145 browser to enter the code. 1147 6. RS Access 1149 The mechanism the Client MUST use to access an RS is in the 1150 Authorization JSON "mechanism" attribute Section 4.4.4. 1152 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1154 The "jose" and "jose+body" mechanisms are defined in 1155 [JOSE_Authentication] 1157 A non-normative "bearer" example of the HTTP request headers follows: 1159 GET /calendar HTTP/2 1160 Host: calendar.example 1161 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1163 7. Error Responses 1165 * TBD 1167 8. Warnings 1169 Warnings assist a Client in detecting non-fatal errors. 1171 * TBD 1173 9. Extensibility 1175 This standard can be extended in a number of areas: 1177 * *Client Authentication Mechanisms* 1179 - An extension could define other mechanisms for the Client to 1180 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1181 Signing. Constrained environments could use CBOR [RFC7049] 1182 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1183 [RFC8323] instead of HTTP/2. 1185 * *Grant* 1187 - An extension can define new objects in the Grant Request and 1188 Grant Response JSON that return new URIs. 1190 * *Top Level* 1192 - Top level objects SHOULD only be defined to represent 1193 functionality other the existing top level objects and 1194 attributes. 1196 * *"client" Object* 1198 - Additional information about the Client that the GS would 1199 require related to an extension. 1201 * *"user" Object* 1203 - Additional information about the User that the GS would require 1204 related to an extension. 1206 * *"authorization" Object* 1207 - Additional authorization schemas in addition to OAuth 2.0 1208 scopes and RAR. 1210 * *"claims" Object* 1212 - Additional claim schemas in addition to OpenID Connect claims 1213 and Verified Credentials. 1215 * *interaction modes* 1217 - Additional types of interactions a Client can start with the 1218 User. 1220 * *Continuous Authentication* 1222 - An extension could define a mechanism for the Client to 1223 regularly provide continuous authentication signals and receive 1224 responses. 1226 _[Editor: do we specify access token introspection in this document, 1227 or leave that to an extension?]_ 1229 10. Rational 1231 1. *Why have both Client ID and Client Handle?* 1233 While they both refer to a Client in the protocol, the Client ID 1234 refers to a pre-registered client,and the Client Handle is 1235 specific to an instance of a Dynamic Client. Using separate 1236 terms clearly differentiates which identifier is being presented 1237 to the GS. 1239 2. *Why allow Client and GS to negotiate the user interaction mode?* 1241 The Client knows what interaction modes it is capable of, and the 1242 GS knows which interaction modes it will permit for a given Grant 1243 Request. The Client can then present the intersection to the 1244 User to choose which one is preferred. For example, while a 1245 device based Client may be willing to do both "indirect" and 1246 "user_code", a GS may not enable "indirect" for concern of a 1247 session fixation attack. Additional interaction modes will 1248 likely become available which allows new modes to be negotiated 1249 between Client and GS as each adds additional interaction modes. 1251 3. *Why have both claims and authorizations?* 1252 There are use cases for each that are independent: authenticating 1253 a user and providing claims vs granting access to a resource. A 1254 request for an authorization returns an access token which may 1255 have full CRUD capabilities, while a request for a claim returns 1256 the claim about the User - with no create, update or delete 1257 capabilities. While the UserInfo endpoint in OIDC may be thought 1258 of as a resource, separating the concepts and how they are 1259 requested keeps each of them simpler in the Editor's opinion. :) 1261 4. *Why do some of the JSON objects only have one child, such as the 1262 identifiers object in the user object in the Grant Request?* 1264 It is difficult to forecast future use cases. Having more 1265 resolution may mean the difference between a simple extension, 1266 and a convoluted extension. For example, the "global" object in 1267 the "interaction" object allows new global parameters to be added 1268 without impacting new interaction modes. 1270 5. *Why is the "iss" included in the "oidc" identifier object? 1271 Would the "sub" not be enough for the GS to identify the User?* 1273 This decouples the GS from the OpenID Provider (OP). The GS 1274 identifier is the GS URI, which is the endpoint at the GS. The 1275 OP issuer identifier will likely not be the same as the GS URI. 1276 The GS may also provide claims from multiple OPs. 1278 6. *Why is there not a UserInfo endpoint as there is with OpenID 1279 Connect?* 1281 Since the Client can Read Grant at any time, it get the same 1282 functionality as the UserInfo endpoint, without the Client having 1283 to manage a separate access token and refresh token. If the 1284 Client would like additional claims, it can Update Grant, and the 1285 GS will let the Client know if an interaction is required to get 1286 any of the additional claims, which the Client can then start. 1288 _[Editor: is there some other reason to have the UserInfo 1289 endpoint?]_ 1291 7. *Why use URIs for the Grant and Authorization?* 1293 * Grant URI and AZ URI are defined to start with the GS URI, 1294 allowing the Client, and GS to determine which GS a Grant or 1295 Authorization belongs to. 1297 * URIs also enable a RESTful interface to the GS functionality. 1299 * A large scale GS can easily separate out the services that 1300 provide functionality as routing of requests can be done at 1301 the HTTP layer based on URI and HTTP verb. This allows a 1302 separation of concerns, independent deployment, and 1303 resiliency. 1305 8. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 1306 known mechanism?* 1308 Having the GS URI endpoint respond to the metadata allows the GS 1309 to provide Client specific results using the same Client 1310 authentication used for other requests to the GS. It also 1311 reduces the risk of a mismatch between the advertised metadata, 1312 and the actual metadata. A .well-known discovery mechanism may 1313 be defined to resolve from a hostname to the GS URI. 1315 11. Acknowledgments 1317 This draft derives many of its concepts from Justin Richer's 1318 Transactional Authorization draft [TxAuth]. 1320 Additional thanks to Justin Richer and Annabelle Richard Backman for 1321 their strong critique of earlier drafts. 1323 12. IANA Considerations 1325 TBD 1327 13. Security Considerations 1329 TBD 1331 14. References 1333 14.1. Normative References 1335 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1336 Requirement Levels", BCP 14, RFC 2119, 1337 DOI 10.17487/RFC2119, March 1997, 1338 . 1340 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1341 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1342 . 1344 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1345 DOI 10.17487/RFC5322, October 2008, 1346 . 1348 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1349 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1350 . 1352 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1353 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1354 September 2009, . 1356 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1357 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1358 . 1360 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1361 Framework: Bearer Token Usage", RFC 6750, 1362 DOI 10.17487/RFC6750, October 2012, 1363 . 1365 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1366 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1367 . 1369 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1370 Interchange Format", STD 90, RFC 8259, 1371 DOI 10.17487/RFC8259, December 2017, 1372 . 1374 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1375 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1376 . 1378 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1379 Assurance 1.0", October 2019, . 1382 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1383 Rich Authorization Requests", January 2020, 1384 . 1386 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1387 Credentials Data Model 1.0", November 2019, 1388 . 1390 [JOSE_Authentication] 1391 Hardt, D., "JOSE Authentication", June 2020, 1392 . 1394 [GNAP_Advanced] 1395 Hardt, D., "The Grant Negotiation and Authorization 1396 Protocol - Advanced Features", June 2020, 1397 . 1399 14.2. Informative References 1401 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1402 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1403 October 2013, . 1405 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1406 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1407 . 1409 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1410 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1411 Application Protocol) over TCP, TLS, and WebSockets", 1412 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1413 . 1415 [browser_based_apps] 1416 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1417 Apps", September 2019, . 1420 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1421 identification and data capture techniques - QR Code bar 1422 code symbology specification", February 2015, 1423 . 1425 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1426 . 1429 Appendix A. Document History 1431 A.1. draft-hardt-xauth-protocol-00 1433 * Initial version 1435 A.2. draft-hardt-xauth-protocol-01 1437 * text clean up 1439 * added OIDC4IA claims 1441 * added "jws" method for accessing a resource. 1443 * renamed Initiation Request -> Grant Request 1445 * renamed Initiation Response -> Interaction Response 1447 * renamed Completion Request -> Authorization Request 1449 * renamed Completion Response -> Grant Request 1451 * renamed completion handle -> authorization handle 1453 * added Authentication Request, Authentication Response, 1454 authentication handle 1456 A.3. draft-hardt-xauth-protocol-02 1458 * major rewrite 1460 * handles are now URIs 1462 * the collection of claims and authorizations are a Grant 1464 * an Authorization is its own type 1466 * lots of sequences added 1468 A.4. draft-hardt-xauth-protocol-03 1470 * fixed RO definition 1472 * improved language in Rationals 1474 * added user code interaction method, and aligned qrcode interaction 1475 method 1477 * added completion_uri for code flows 1479 A.5. draft-hardt-xauth-protocol-04 1481 * renamed interaction uris to have purpose specific names 1483 A.6. draft-hardt-xauth-protocol-05 1485 * separated claims from identifiers in request user object 1487 * simplified reciprocal grant flow 1489 * reduced interactions to redirect and indirect 1490 * simplified interaction parameters 1492 * added in language for Client to verify interaction completion 1494 * added Verify Grant API and Interaction Nonce 1496 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1497 operation. 1499 A.7. draft-hardt-xauth-protocol-06 1501 * fixup examples to match specification 1503 A.8. draft-hardt-xauth-protocol-07 1505 * refactored interaction request and response syntax, and enabled 1506 interaction mode negotiation 1508 * generation of client handle by GS for dynamic clients 1510 * renamed title to Grant Negotiation and Authorization Protocol. 1511 Preserved draft-hardt-xauth-protocol filename to ease tracking 1512 changes. 1514 * changed Authorizations to be key / value pairs (aka dictionary) 1515 instead of a JSON array 1517 A.9. draft-hardt-xauth-protocol-08 1519 * split document into three documents: core, advanced, and JOSE 1520 authentication. 1522 * grouped access granted into "access" object in Authorization JSON 1524 * added warnings object to the Grant Response JSON 1526 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1528 *Changed Features* 1530 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1532 * The Client always uses a private asymetric key to authenticate to 1533 the GS. There is no client secret. i 1535 * The Client initiates the protocol by making a signed request 1536 directly to the GS instead of redirecting the User to the GS. 1538 * The Client does not pass any parameters in redirecting the User to 1539 the GS. 1541 * The refresh_token has been replaced with a AZ URI that both 1542 represents the authorization, and is the URI for obtaining a fresh 1543 access token. 1545 * The Client can request identity claims to be returned independent 1546 of the ID Token. There is no UserInfo endpoint to query claims as 1547 there is in OpenID Connect. 1549 * The GS URI is the token endpoint. 1551 *Preserved Features* 1553 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1554 2.0. 1556 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1558 * No change is required by the Client or the RS for accessing 1559 existing bearer token protected APIs. 1561 *New Features* 1563 * All Client calls to the GS are authenticated with asymetric 1564 cryptography 1566 * A Grant represents both the user identity claims and RS access 1567 granted to the Client. 1569 * Support for scannable code initiated interactions. 1571 * Highly extensible per Section 9. 1573 Author's Address 1575 Dick Hardt (editor) 1576 SignIn.Org 1577 United States 1579 Email: dick.hardt@gmail.com