idnits 2.17.00 (12 Aug 2021) /tmp/idnits29721/draft-hardt-xauth-protocol-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 13 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Contains either an authorization request object, or key / value pairs, where each unique key is created by the client, and the value is an authorization request object Section 3.5.5. The key value of "type" is reserved and MUST not be used by the client. The GS detects the authorizations object contains an authorization request object by the presence of the "type" property. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *completion_uri* a unique URI at the Client that the GS will return the User to. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. This attribute is REQUIRED. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *redirect_uri* a unique URI at the GS that the Client will redirect the User to. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. This attribute is REQUIRED. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *indirect_uri* the URI the Client will cause to load in the User's browser. The URI SHOULD be short enough to be easily encoded in a scannable code. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. _[Editor: recommend a maximum length?]_ -- The document date (13 July 2020) is 677 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 (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 13 July 2020 5 Expires: 14 January 2021 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-13 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 14 January 2021. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6 59 1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 60 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7 61 2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 2.1. "redirect" Interaction . . . . . . . . . . . . . . . . . 8 63 2.2. "user_code" Interaction . . . . . . . . . . . . . . . . . 9 64 2.3. Independent RO Authorization . . . . . . . . . . . . . . 10 65 2.4. Resource Server Access . . . . . . . . . . . . . . . . . 11 66 3. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 3.1. GS API Table . . . . . . . . . . . . . . . . . . . . . . 12 68 3.2. Create Grant . . . . . . . . . . . . . . . . . . . . . . 12 69 3.3. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 15 70 3.4. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 16 71 3.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 16 72 3.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 17 73 3.5.2. "interaction" Object . . . . . . . . . . . . . . . . 17 74 3.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 18 75 3.5.4. "authorizations" Object . . . . . . . . . . . . . . . 18 76 3.5.5. Authorization Request Object . . . . . . . . . . . . 18 77 3.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 18 78 3.6. Read Authorization . . . . . . . . . . . . . . . . . . . 19 79 3.7. GS Options . . . . . . . . . . . . . . . . . . . . . . . 19 80 4. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 20 81 4.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 20 82 4.2. Interaction Response . . . . . . . . . . . . . . . . . . 22 83 4.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 22 84 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 23 85 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 23 86 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 23 87 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23 88 4.4.4. "authorizations" Object . . . . . . . . . . . . . . . 24 89 4.4.5. Authorization response Object . . . . . . . . . . . . 24 90 4.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24 91 4.4.7. "warnings" JSON Array . . . . . . . . . . . . . . . . 25 92 4.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 25 93 4.6. Response Verification . . . . . . . . . . . . . . . . . . 26 94 5. Interaction Modes . . . . . . . . . . . . . . . . . . . . . . 26 95 5.1. "redirect" . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.1.1. "redirect" verification . . . . . . . . . . . . . . . 27 98 5.2. "indirect" . . . . . . . . . . . . . . . . . . . . . . . 27 99 5.3. "user_code" . . . . . . . . . . . . . . . . . . . . . . . 27 100 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 28 102 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 28 103 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 28 104 10. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 30 105 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32 106 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 107 13. Security Considerations . . . . . . . . . . . . . . . . . . . 32 108 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 109 14.1. Normative References . . . . . . . . . . . . . . . . . . 32 110 14.2. Informative References . . . . . . . . . . . . . . . . . 34 111 Appendix A. Document History . . . . . . . . . . . . . . . . . . 34 112 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 34 113 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 35 114 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 35 115 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 35 116 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 35 117 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 36 118 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 36 119 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 36 120 A.9. draft-hardt-xauth-protocol-08 . . . . . . . . . . . . . . 36 121 A.10. draft-hardt-xauth-protocol-09 . . . . . . . . . . . . . . 36 122 A.11. draft-hardt-xauth-protocol-10 . . . . . . . . . . . . . . 37 123 A.12. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 37 124 A.13. draft-hardt-xauth-protocol-11 . . . . . . . . . . . . . . 37 125 A.14. draft-hardt-xauth-protocol-12 . . . . . . . . . . . . . . 37 126 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 37 127 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 129 1. Introduction 131 *EDITOR NOTE* 133 _This document captures a number of concepts that may be adopted by 134 the proposed GNAP working group. Please refer to this document as:_ 136 *XAuth* 138 _The use of GNAP in this document is not intended to be a declaration 139 of it being endorsed by the proposed GNAP working group._ 140 This document describes the core Grant Negotiation and Authorization 141 Protocol (GNAP). The protocol supports the widely deployed use cases 142 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 143 an extension of OAuth 2.0, as well as other extensions. Related 144 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 145 Authentication [JOSE_Authentication] that describes the JOSE 146 mechanisms for client authentication. 148 The technology landscape has changed since OAuth 2.0 was initially 149 drafted. More interactions happen on mobile devices than PCs. 150 Modern browsers now directly support asymetric cryptographic 151 functions. Standards have emerged for signing and encrypting tokens 152 with rich payloads (JOSE) that are widely deployed. 154 GNAP simplifies the overall architectural model, takes advantage of 155 today's technology landscape, provides support for all the widely 156 deployed use cases, offers numerous extension points, and addresses 157 many of the security issues in OAuth 2.0 by passing parameters 158 securely between parties, rather than via a browser redirection. . 160 While GNAP is not backwards compatible with OAuth 2.0, it strives to 161 minimize the migration effort. 163 GNAP centers around a Grant, a representation of the collection of 164 user identity claims and/or resource authorizations the Client is 165 requesting, and the resulting identity claims and/or resource 166 authorizations granted by the Grant Server (GS). 168 User consent is often required at the GS. GNAP enables a Client and 169 GS to negotiate the interaction mode for the GS to obtain consent. 171 The suggested pronunciation of GNAP is the same as the English word 172 "nap", a silent "g" as in "gnaw". 174 _[Editor: suggestions on how to improve this are welcome!]_ 176 1.1. Parties 178 The parties and their relationships to each other: 180 +--------+ +------------+ 181 | User | | Resource | 182 | | | Owner (RO) | 183 +--------+ +------------+ 184 | \ / | 185 | \ / | 186 | \ / | 187 | \ / | 188 +--------+ +---------------+ +------------+ 189 | Client |---->| Grant | | Resource | 190 | | (1) | Server (GS) | _ _ | Server | 191 | |<----| | | (RS) | 192 | | +---------------+ | | 193 | |-------------------------->| | 194 | | (2) | | 195 | |<--------------------------| | 196 +--------+ +------------+ 198 This document specifies interactions between the Client and GS (1), 199 and the Client and RS (2). 201 * *User* - the person interacting with the Client who has delegated 202 access to identity claims about themselves to the Grant Server 203 (GS), and can authenticate at the GS. 205 * *Client* - requests a Grant from the GS to access one or more 206 Resource Servers (RSs), and/or identity claims about the User. 207 The Grant may include access tokens that the Client uses to access 208 the RS. There are two types of Clients: Registered Clients and 209 Dynamic Clients. All Clients have a private asymetric key to 210 authenticate with the Grant Server. 212 * *Registered Client* - a Client that has registered with the GS and 213 has a Client ID to identify itself, and can prove it possesses a 214 key that is linked to the Client ID. The GS may have different 215 policies for what different Registered Clients can request. A 216 Registered Client MAY be interacting with a User. 218 * *Dynamic Client* - a Client that has not been previously 219 registered with the GS, and each instance will generate it's own 220 asymetric key pair so it can prove it is the same instance of the 221 Client on subsequent requests. The GS MAY return a Dynamic Client 222 a Client Handle for the Client to identify itself in subsequent 223 requests. A single-page application with no active server 224 component is an example of a Dynamic Client. A Dynamic Client 225 MUST be interacting with a User. 227 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 228 release of identity claims about the User. The GS may require 229 explicit consent from the RO or User to provide these to the 230 Client. A GS may support Registered Clients and/or Dynamic 231 Clients. The GS is a combination of the Authorization Server (AS) 232 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 234 * *Resource Server* (RS) - has API resources that require an access 235 token from the GS. Some, or all of the resources are owned by the 236 Resource Owner. 238 * *Resource Owner* (RO) - owns resources at the RS, and has 239 delegated RS access management to the GS. The RO may be the same 240 entity as the User, or may be a different entity that the GS 241 interacts with independently. GS and RO interactions are out of 242 scope of this document. 244 1.2. Reused Terms 246 * *access token* - an access token as defined in [RFC6749] 247 Section 1.4. 249 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 250 issued by the GS, or by other issuers. 252 * *Client ID* - a GS unique identifier for a Registered Client as 253 defined in [RFC6749] Section 2.2. 255 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 257 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 259 * *authN* - short for authentication. 261 * *authZ* - short for authorization. 263 1.3. New Terms 265 * *GS URI* - the endpoint at the GS the Client calls to create a 266 Grant, and is the unique identifier for the GS. 268 * *Grant* - the user identity claims and/or RS authorizations the GS 269 has granted to the Client. The GS MAY invalidate a Grant at any 270 time. 272 * *Grant URI* - the URI that represents the Grant. The Grant URI 273 MUST start with the GS URI. 275 * *Authorization* - the access granted by the RO to the Client and 276 contains an access token. The GS may invalidate an Authorization 277 at any time. 279 * *Authorization URI* (AZ URI) - the URI that represents the 280 Authorization the Client was granted by the RO. The AZ URI MUST 281 start with the GS URI. The AZ URI is used to refresh an access 282 token. 284 * *Interaction* - how the Client directs the User to interact with 285 the GS. This document defines the interaction modes: "redirect", 286 "indirect", and "user_code" in Section 5 288 * *Client Handle* - a unique identifier at the GS for a Dynamic 289 Client for the Dynamic Client to refer to itself in subsequent 290 requests. 292 1.4. Notational Conventions 294 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 295 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 296 specification are to be interpreted as described in [RFC2119]. 298 Certain security-related terms are to be understood in the sense 299 defined in [RFC4949]. These terms include, but are not limited to, 300 "attack", "authentication", "authorization", "certificate", 301 "confidentiality", "credential", "encryption", "identity", "sign", 302 "signature", "trust", "validate", and "verify". 304 _[Editor: review terms]_ 306 Unless otherwise noted, all the protocol parameter names and values 307 are case sensitive. 309 Some protocol parameters are parts of a JSON document, and are 310 referred to in JavaScript notation. For example, foo.bar refers to 311 the "bar" boolean attribute in the "foo" object in the following 312 example JSON document: 314 { 315 "foo" : { 316 "bar": true 317 } 318 } 320 2. Sequences 322 Before any sequence, the Client needs to be manually or 323 programmatically configured for the GS. See GS Options Section 3.7 324 for details on programmatically acquiring GS metadata. 326 2.1. "redirect" Interaction 328 The Client is a web application and wants a Grant from the User: 330 +--------+ +-------+ 331 | Client | | GS | 332 | |--(1)--- Create Grant ----------->| | 333 | | | | 334 | |<--- Interaction Response ---(2)--| | +------+ 335 | | | | | User | 336 | |--(3)--- Interaction Transfer --- | - - - | ------->| (RO) | 337 | | | |<--(4)-->| | 338 | | | | authN | | 339 | | | | | | 340 | | | |<--(5)-->| | 341 | | | | authZ | | 342 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 343 | | | | | | 344 | |--(7)--- Verify Grant ----------->| | +------+ 345 | | | | 346 | |<--------- Grant Response ---(8)--| | 347 | | | | 348 +--------+ +-------+ 350 1. *Create Grant* The Client creates a Request JSON document 351 Section 3.5 containing an interaction.redirect object and makes a 352 Create Grant request (Section 3.2) by sending the JSON with an 353 HTTP POST to the GS URI. 355 2. *Interaction Response* The GS determines that interaction with 356 the User is required and sends an Interaction Response 357 (Section 4.2) containing the Grant URI and an 358 interaction.redirect object. 360 3. *Interaction Transfer* The Client redirects the User to the 361 redirect_uri at the GS. 363 4. *User Authentication* The GS authenticates the User. 365 5. *User Authorization* If required, the GS interacts with the User 366 (who is also the RO) to determine which identity claims and/or 367 authorizations in the Grant Request are to be granted. 369 6. *Interaction Transfer* The GS redirects the User to the 370 completion_uri at the Client. 372 7. *Verify Grant* The Client makes an HTTP PATCH request to the 373 Grant URI passing the verification code (Section 3.3). 375 8. *Grant Response* The GS responds with a Grant Response 376 (Section 4.1). 378 2.2. "user_code" Interaction 380 A Client is on a device wants a Grant from the User: 382 +--------+ +-------+ 383 | Client | | GS | 384 | |--(1)--- Create Grant ----------->| | 385 | | | | 386 | |<--- Interaction Response ---(2)--| | +------+ 387 | | | | | User | 388 | |--(3)--- Read Grant ------------->| | | (RO) | 389 | | | |<--(4)-->| | 390 | | | | authN | | 391 | | | | | | 392 | | | |<--(5)---| | 393 | | | | code | | 394 | | | | | | 395 | | | |<--(6)-->| | 396 | | | | authZ | | 397 | | | | | | 398 | |<--------- Grant Response ---(7)--| | | | 399 | | | | | | 400 +--------+ | | | | 401 | | | | 402 +--------+ | | | | 403 | Client |<---- Information URI Redirect -- | - - - | --(8)---| | 404 | Server | | | | | 405 +--------+ +-------+ +------+ 407 1. *Create Grant* The Client creates a Request JSON document 408 Section 3.5 containing an interaction.user_code object and makes 409 a Create Grant request (Section 3.2) by sending the JSON with an 410 HTTP POST to the GS URI. 412 2. *Interaction Response* The GS determines that interaction with 413 the User is required and sends an Interaction Response 414 (Section 4.2) containing the Grant URI and an 415 interaction.user_code object. 417 3. *Read Grant* The Client makes an HTTP GET request to the Grant 418 URI. 420 4. *User Authentication* The User loads display_uri in their 421 browser, and the GS authenticates the User. 423 5. *User Code* The User enters the code at the GS. 425 6. *User Authorization* If required, the GS interacts with the User 426 (who is also the RO) to determine which identity claims and/or 427 authorizations in the Grant Request are to be granted. 429 7. *Grant Response* The GS responds with a Grant Response 430 (Section 4.1). 432 8. *Information URI Redirect* The GS redirects the User to the 433 information_uri provided by the Client. 435 2.3. Independent RO Authorization 437 The Client wants access to resources that require the GS to interact 438 with the RO, who is not interacting with the Client. The 439 authorization from the RO may take some time, so the GS instructs the 440 Client to wait and check back later. 442 +--------+ +-------+ 443 | Client | | GS | 444 | |--(1)--- Create Grant ----------->| | 445 | | | | 446 | |<---------- Wait Response ---(2)--| | +------+ 447 | (3) | | | | RO | 448 | Wait | | |<--(4)-->| | 449 | | | | AuthZ | | 450 | |--(5)--- Read Grant ------------->| | +------+ 451 | | | | 452 | |<--------- Grant Response --(6)---| | 453 | | | | 454 +--------+ +-------+ 456 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 457 and sends it with an HTTP POST to the GS GS URI. 459 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 460 containing the Grant URI and the "wait" attribute. 462 3. *Client Waits* The Client waits for the time specified in the 463 "wait" attribute. 465 4. *RO AuthZ* The GS interacts with the RO to determine which 466 identity claims and/or resource authorizations in the Grant 467 Request are to be granted. 469 5. *Read Grant* The Client does an HTTP GET of the Grant URI 470 (Section 3.4). 472 6. *Grant Response* The GS responds with a Grant Response 473 (Section 4.1). 475 2.4. Resource Server Access 477 The Client received an AZ URI from the GS. The Client acquires an 478 access token, calls the RS, and later the access token expires. The 479 Client then gets a fresh access token. 481 +--------+ +----------+ +-------+ 482 | Client | | Resource | | GS | 483 | |--(1)--- Access Resource --->| Server | | | 484 | |<------- Resource Response --| (RS) | | | 485 | | | | | | 486 | |--(2)--- Access Resource --->| | | | 487 | |<------- Error Response -----| | | | 488 | | | | | | 489 | | +----------+ | | 490 | | | | 491 | |--(3)--- Read AuthZ ---------------------->| | 492 | |<------- AuthZ Response -------------------| | 493 | | | | 494 +--------+ +-------+ 496 1. *Resource Request* The Client accesses the RS with the access 497 token per Section 6 and receives a response from the RS. 499 2. *Resource Request* The Client attempts to access the RS, but 500 receives an error indicating the access token needs to be 501 refreshed. 503 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.6) with an 504 HTTP GET to the AZ URI and receives as Response JSON 505 "authorization" object (Section 4.4.5) with a fresh access token. 507 3. GS APIs 509 *Client Authentication* 511 All GS APIs except for GS Options require the Client to authenticate. 512 Authentication mechanisms include: 514 * JOSE Authentication [JOSE_Authentication] 516 * [Others TBD]* 518 3.1. GS API Table 520 +==============+=============+========+=============================+ 521 | request | http method | uri | response | 522 +==============+=============+========+=============================+ 523 | GS Options | OPTIONS | GS URI | metadata | 524 +--------------+-------------+--------+-----------------------------+ 525 | Create Grant | POST | GS URI | interaction, | 526 | | | | wait, or grant | 527 +--------------+-------------+--------+-----------------------------+ 528 | Verify Grant | PATCH | Grant | grant | 529 | | | URI | | 530 +--------------+-------------+--------+-----------------------------+ 531 | Read Grant | GET | Grant | wait, or grant | 532 | | | URI | | 533 +--------------+-------------+--------+-----------------------------+ 534 | Read AuthZ | GET | AZ URI | authorization | 535 +--------------+-------------+--------+-----------------------------+ 537 Table 1 539 3.2. Create Grant 541 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 542 document to the GS URI. This is a Grant Request. 544 The JSON document MUST include the following from the Request JSON 545 Section 3.5: 547 * iat 549 * nonce 551 * uri - MUST be set to the GS URI 553 * method - MUST be "POST" 555 * client 557 and MAY include the following from Request JSON Section 3.5 559 * user 561 * interaction 562 * authorizations 564 * claims 566 The GS MUST respond with one of Grant Response Section 4.1, 567 Interaction Response Section 4.2, Wait Response Section 4.3, or one 568 of the following errors: 570 * TBD 572 from Error Responses Section 7. 574 Following is a non-normative example of a web application Client 575 requesting identity claims about the User and read access to the 576 User's contacts: 578 Example 1 580 { 581 "iat" : 15790460234, 582 "uri" : "https://as.example/endpoint", 583 "method" : "POST, 584 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 585 "client": { 586 "display": { 587 "name" : "SPA Display Name", 588 "uri" : "https://spa.example/about" 589 } 590 }, 591 "interaction": { 592 "redirect": { 593 "completion_uri" : "https://web.example/return" 594 }, 595 "global" : { 596 "ui_locals" : "de" 597 } 598 }, 599 "authorizations": { 600 "type" : "oauth_scope", 601 "scope" : "read_contacts" 602 }, 603 "claims": { 604 "oidc": { 605 "id_token" : { 606 "email" : { "essential" : true }, 607 "email_verified" : { "essential" : true } 608 }, 609 "userinfo" : { 610 "name" : { "essential" : true }, 611 "picture" : null 612 } 613 } 614 } 615 } 617 Following is a non-normative example of a device Client requesting 618 two different access tokens, one request with "oauth_scope", the 619 other with "oauth_rich": 621 Example 2 623 { 624 "iat" : 15790460234, 625 "uri" : "https://as.example/endpoint", 626 "method" : "POST, 627 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 628 "client": { 629 "id" : "di3872h34dkJW" 630 }, 631 "interaction": { 632 "indirect": { 633 "information_uri": "https://device.example/c/indirect" 634 }, 635 "user_code": { 636 "information_uri": "https://device.example/c/user_code" 637 } 638 }, 639 "authorizations": { 640 "play_music": { 641 "type" : "oauth_scope", 642 "scope" : "play_music", 643 }, 644 "read_user_info: { 645 "type" : "customer_information", 646 "locations": [ 647 "https://example.com/customers", 648 ] 649 "actions": [ 650 "read" 651 ], 652 "datatypes": [ 653 "contacts", 654 "photos" 655 ] 656 } 657 } 658 } 660 [Editor: the "oauth_scope" and "customer_information" types are not 661 normative, but generally representative of what may be defined in 662 [RAR]. 664 3.3. Verify Grant 666 The Client verifies a Grant by doing an HTTP PATCH of a JSON document 667 to the Grant URI. The Client MUST only verify a Grant once. 669 The JSON document MUST include the following from the Request JSON 670 Section 3.5: 672 * iat 674 * nonce 676 * uri - MUST be set to the Grant URI 678 * method - MUST be PATCH 680 * interaction.redirection.verification - MUST be the verification 681 code received per Section 5.1.1. 683 Following is a non-normative example: 685 { 686 "iat" : 15790460235, 687 "uri" : "https://as.example/endpoint/grant/example1", 688 "method" : "PATCH, 689 "nonce" : "9b6afd70-2036-47c9-b953-5dd1fd0c699a", 690 "interaction": { 691 "redirect": { 692 "verification" : "cb4aa22d-2fe1-4321-b87e-bbaa66fbe707" 693 } 694 } 695 } 697 The GS MUST respond with one of Grant Response Section 4.1 or one of 698 the following errors: 700 * TBD 702 3.4. Read Grant 704 The Client reads a Grant by doing an HTTP GET of the corresponding 705 Grant URI. The Client MAY read a Grant until it expires or has been 706 invalidated. 708 The GS MUST respond with one of Grant Response Section 4.1, Wait 709 Response Section 4.3, or one of the following errors: 711 * TBD 713 3.5. Request JSON 715 * *iat* - the time of the request as a NumericDate. 717 * *nonce* - a unique identifier for this request. Note the Grant 718 Response MUST contain a matching "nonce" attribute value. 720 * *uri* - the URI being invoked 722 * *method* - the HTTP method being used 724 3.5.1. "client" Object 726 The client object MUST only one of the following: 728 * *id* - the Client ID the GS has for a Registered Client. 730 * *handle* - the Client Handle the GS previously provided a Dynamic 731 Client 733 * *display* - the display object contains the following attributes: 735 - *name* - a string that represents the Dynamic Client 737 - *uri* - a URI representing the Dynamic Client 739 The GS will show the the User the display.name and display.uri values 740 when prompting for authorization. 742 _[Editor: a max length for the name and URI so a GS can reserve 743 appropriate space?]_ 745 3.5.2. "interaction" Object 747 The interaction object contains one or more interaction mode objects 748 per Section 5 representing the interactions the Client is willing to 749 provide the User. In addition to the interaction mode objects, the 750 interaction object may contain the "global" object; 752 * *global* - an optional object containing parameters that are 753 applicable for all interaction modes. Only one attribute is 754 defined in this document: 756 - *ui_locales* - End-User's preferred languages and scripts for 757 the user interface, represented as a space-separated list of 758 [RFC5646] language tag values, ordered by preference. This 759 attribute is OPTIONAL. 761 _[Editor: ui_locales is taken from OIDC. Why space-separated and not 762 a JSON array?]_ 764 3.5.3. "user" Object 766 * *identifiers* - The identifiers MAY be used by the GS to improve 767 the User experience. This object contains one or more of the 768 following identifiers for the User: 770 - *phone_number* - contains a phone number per Section 5 of 771 [RFC3966]. 773 - *email* - contains an email address per [RFC5322]. 775 - *oidc* - is an object containing both the "iss" and "sub" 776 attributes from an OpenID Connect ID Token [OIDC] Section 2. 778 * *claims* - an optional object containing one or more assertions 779 the Client has about the User. 781 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 782 Section 2. 784 3.5.4. "authorizations" Object 786 Contains either an authorization request object, or key / value 787 pairs, where each unique key is created by the client, and the value 788 is an authorization request object Section 3.5.5. The key value of 789 "type" is reserved and MUST not be used by the client. The GS 790 detects the authorizations object contains an authorization request 791 object by the presence of the "type" property. 793 3.5.5. Authorization Request Object 795 * *type* - any of the types per [RAR]. The remaining properties are 796 dependent on the type. 798 [Editor: in the example we made up the "oauth_scope" type as a way of 799 using existing OAuth scopes.] 801 [Editor: rather then using the "type" property to differentiate 802 between singular and plural authorization requests, the authorization 803 could be an array, which would allow multiple types to be included in 804 a single authorization, per the latest {{RAR} document}, and 805 detection is if authorizations contains an array(singular), or 806 object(plural)] 808 3.5.6. "claims" Object 810 Includes one or more of the following: 812 * *oidc* - an object that contains one or both of the following 813 objects: 815 - *userinfo* - Claims that will be returned as a JSON object 817 - *id_token* - Claims that will be included in the returned ID 818 Token. If the null value, an ID Token will be returned 819 containing no additional Claims. 821 The contents of the userinfo and id_token objects are Claims as 822 defined in [OIDC] Section 5. 824 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 825 per [OIDC4IA]. 827 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 828 requested.]_[W3C_VC] 830 3.6. Read Authorization 832 The Client acquires and refreshes an Authorization by doing an HTTP 833 GET to the corresponding AZ URI. 835 The GS MUST respond with a Authorization JSON document Section 4.5, 836 or one of the following errors: 838 * TBD 840 from Error Responses Section 7. 842 3.7. GS Options 844 The Client can get the metadata for the GS by doing an HTTP OPTIONS 845 of the corresponding GS URI. This is the only API where the GS MAY 846 respond to an unauthenticated request. 848 The GS MUST respond with the the following JSON document: 850 * *uri* - the GS URI. 852 * *client_authentication* - a JSON array of the Client 853 Authentication mechanisms supported by the GS 855 * *interactions* - a JSON array of the interaction modes supported 856 by the GS. 858 * *authorization* - an object containing the authorizations the 859 Client may request from the GS, if any. 861 - Details TBD 863 * *claims* - an object containing the identity claims the Client may 864 request from the GS, if any, and what public keys the claims will 865 be signed with. 867 - Details TBD 869 * *algorithms* - a JSON array of the cryptographic algorithms 870 supported by the GS. [details TBD]* 872 * *features* - an object containing feature or extension support 874 or one of the following errors: 876 * TBD 878 from Error Responses Section 7. 880 4. GS Responses 882 There are three successful responses to a Grant Request: Grant 883 Response, Interaction Response, or Wait Response. 885 4.1. Grant Response 887 The Grant Response MUST include the following from the Response JSON 888 Section 4.4 890 * iat 892 * nonce 894 * uri 896 and MAY include the following from the Response JSON Section 4.4 898 * client.handle 900 * authorizations 902 * claims 904 * expires_in 906 * warnings 907 Example non-normative Grant Response JSON document for Example 1 in 908 Section 3.2: 910 { 911 "iat" : 15790460234, 912 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 913 "uri" : "https://as.example/endpoint/grant/example1", 914 "expires_in" : 300 915 "authorizations": { 916 "access": { 917 "type" : "oauth_scope", 918 "scope" : "read_contacts" 919 }, 920 "expires_in" : 3600, 921 "mechanism" : "bearer", 922 "token" : "eyJJ2D6.example.access.token.mZf9p" 923 }, 924 "claims": { 925 "oidc": { 926 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 927 "userinfo" : { 928 "name" : "John Doe", 929 "picture" : "https://photos.example/p/eyJzdkiO" 930 } 931 } 932 } 933 } 935 Note in this example the access token can not be refreshed, and 936 expires in an hour. 938 Example non-normative Grant Response JSON document for Example 2 in 939 Section 3.2: 941 { 942 "iat" : 15790460234, 943 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 944 "uri" : "https://as.example/endpoint/grant/example2", 945 "authorizations": { 946 "play_music": { "uri" : "https://as.example/endpoint/authz/example2" }, 947 "read_user_info: { "uri" " "https://as.example/endpoint/authz/"} 948 } 949 } 951 Note in this example the GS only provided the AZ URIs, and Client 952 must acquire the Authorizations per Section 3.6 954 [Editor: the Client needs to remember if it asked for a single, or 955 multiple authorizations, as there is no crisp algorithm for 956 differentiating between the responses] 958 4.2. Interaction Response 960 The Interaction Response MUST include the following from the Response 961 JSON Section 4.4 963 * iat 965 * nonce 967 * uri 969 * interaction 971 and MAY include the following from the Response JSON Section 4.4 973 * user 975 * wait 977 * warnings 979 A non-normative example of an Interaction Response follows: 981 { 982 "iat" : 15790460234, 983 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 984 "uri" : "https://as.example/endpoint/grant/example4", 985 "interaction" : { 986 "redirect" : { 987 "redirect_uri" : "https://as.example/i/example4" 988 } 989 } 990 } 992 4.3. Wait Response 994 The Wait Response MUST include the following from the Response JSON 995 Section 4.4 997 * iat 999 * nonce 1001 * uri 1002 * wait 1004 and MAY include the following from the Response JSON Section 4.4 1006 * warnings 1008 A non-normative example of Wait Response follows: 1010 { 1011 "iat" : 15790460234, 1012 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1013 "uri" : "https://as.example/endpoint/grant/example5", 1014 "wait" : 300 1015 } 1017 4.4. Response JSON 1019 Details of the JSON document: 1021 * *iat* - the time of the response as a NumericDate. 1023 * *nonce* - the nonce that was included in the Request JSON 1024 Section 3.5. 1026 * *uri* - the Grant URI. 1028 * *wait* - a numeric value representing the number of seconds the 1029 Client should want before making a Read Grant request to the Grant 1030 URI. 1032 * *expires_in* - a numeric value specifying how many seconds until 1033 the Grant expires. This attribute is OPTIONAL. 1035 4.4.1. "client" Object 1037 The GS may 1039 4.4.2. "interaction" Object 1041 If the GS wants the Client to start the interaction, the GS MUST 1042 return an interaction object containing one or more interaction mode 1043 responses per Section 5 to one or more of the interaction mode 1044 requests provided by the Client. 1046 4.4.3. "user" Object 1047 * *exists* - a boolean value indicating if the GS has a user with 1048 one or more of the provided identifiers in the Request 1049 user.identifiers object Section 3.5.3 1051 4.4.4. "authorizations" Object 1053 The authorizations object MUST contain either an authorization 1054 response object Section 4.4.5, or a key / value pair for each key in 1055 the Grant Request "authorizations" objectSection 3.5.4, and the value 1056 is an authorization response object Section 4.4.5. 1058 4.4.5. Authorization response Object 1060 The authorization response object MUST contain only a "uri" attribute 1061 or the following from Authorization JSON Section 4.5: 1063 * mechanism 1065 * token 1067 The authorization object MAY contain any of the following from 1068 Authorization JSON Section 4.5: 1070 * access 1072 * expires_in 1074 * uri 1076 If there is no "uri" attribute, the access token can not be 1077 refreshed. If only the "uri" attribute is present, the Client MUST 1078 acquire the Authorization per Section 3.6 1080 4.4.6. "claims" Object 1082 The claims object is a response to the Grant Request "claims" object 1083 Section 3.5.6. 1085 * *oidc* 1087 - *id_token* - an OpenID Connect ID Token containing the Claims 1088 the User consented to be released. 1090 - *userinfo* - the Claims the User consented to be released. 1092 Claims are defined in [OIDC] Section 5. 1094 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1095 per [OIDC4IA]. 1097 * *vc* 1099 The verified claims the user consented to be released. _[Editor: 1100 details TBD]_ 1102 4.4.7. "warnings" JSON Array 1104 Includes zero or more warnings from Section 8, 1106 4.5. Authorization JSON 1108 The Authorization JSON is a Grant Response Authorization Object 1109 Section 4.4.5 or the response to a Read AuthZ request by the Client 1110 Section 3.6. 1112 * *mechanism* - the RS access mechanism. This document defines the 1113 "bearer" mechanism as defined in Section 6 1115 * *token* - the access token for accessing an RS. 1117 * *expires_in* - a numeric value specifying how many seconds until 1118 the access token expires. 1120 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1122 * *access* - an object containing the access granted: 1124 - *type* - the type of claim request: "oauth_scope" or 1125 "oauth_rich". See the "type" object in Section 3.5.4 for 1126 details. This attribute is REQUIRED. 1128 - *scope* - the scopes the Client was granted authorization for. 1129 This will be all, or a subset, of what was requested. This 1130 attribute is OPTIONAL. 1132 - *authorization_details* - the authorization details granted per 1133 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1135 _[Editor: would an optional expiry for the Authorization be useful?]_ 1137 The following is a non-normative example of Authorization JSON: 1139 { 1140 "mechanism" : "bearer", 1141 "token" : "eyJJ2D6.example.access.token.mZf9p" 1142 "expires_in" : 3600, 1143 "uri" : "https://as.example/endpoint/authz/example2", 1144 "access": { 1145 "type" : "oauth_scope", 1146 "scope" : "read_calendar write_calendar" 1147 } 1148 } 1150 4.6. Response Verification 1152 On receipt of a response, the Client MUST verify the following: 1154 * TBD 1156 5. Interaction Modes 1158 This document defines three interaction modes: "redirect", 1159 "indirect", and "user_code". Extensions may define additional 1160 interaction modes. 1162 The "global" attribute is reserved in the interaction object for 1163 attributes that apply to all interaction modes. 1165 5.1. "redirect" 1167 A Redirect Interaction is characterized by the Client redirecting the 1168 User's browser to the GS, the GS interacting with the User, and then 1169 GS redirecting the User's browser back to the Client. The GS 1170 correlates the Grant Request with the unique redirect_uri, and the 1171 Client correlates the Grant Request with the unique completion_uri. 1173 *The request "interaction" object contains:* 1175 * *completion_uri* a unique URI at the Client that the GS will 1176 return the User to. The URI MUST not contain the "nonce" from the 1177 Grant Request, and MUST not be guessable. This attribute is 1178 REQUIRED. 1180 *The response "interaction" object contains:* 1182 * *redirect_uri* a unique URI at the GS that the Client will 1183 redirect the User to. The URI MUST not contain the "nonce" from 1184 the Grant Request, and MUST not be guessable. This attribute is 1185 REQUIRED. 1187 * *verification* a boolean value indicating the GS requires the 1188 Client to make a Verify Grant request.(Section 3.3) 1190 5.1.1. "redirect" verification 1192 If the GS indicates that Grant Verification is required, the GS MUST 1193 add a 'verification' query parameter with a value of a unique 1194 verification code to the completion_uri. 1196 On receiving the verification code in the redirect from the GS, the 1197 Client makes a Verify Grant request (Section 3.3) with the 1198 verification code. 1200 5.2. "indirect" 1202 An Indirect Interaction is characterized by the Client causing the 1203 User's browser to load the indirect_uri at GS, the GS interacting 1204 with the User, and then the GS MAY optionally redirect the User's 1205 Browser to a information_uri. There is no mechanism for the GS to 1206 redirect the User's browser back to the Client. 1208 Examples of how the Client may initiate the interaction are encoding 1209 the indirect_uri as a code scannable by the User's mobile device, or 1210 launching a system browser from a command line interface (CLI) 1211 application. 1213 The "indirect" mode is susceptible to session fixation attacks. See 1214 TBD in the Security Considerations for details. 1216 *The request "interaction" object contains:* 1218 * *information_uri* an OPTIONAL URI that the GS will redirect the 1219 User's browser to after GS interaction. 1221 *The response "interaction" object contains:* 1223 * *indirect_uri* the URI the Client will cause to load in the User's 1224 browser. The URI SHOULD be short enough to be easily encoded in a 1225 scannable code. The URI MUST not contain the "nonce" from the 1226 Grant Request, and MUST not be guessable. _[Editor: recommend a 1227 maximum length?]_ 1229 5.3. "user_code" 1231 An Indirect Interaction is characterized by the Client displaying a 1232 code and a URI for the User to load in a browser and then enter the 1233 code. _[Editor: recommend a minimum entropy?]_ 1234 *The request "interaction" object contains:* 1236 * *information_uri* an OPTIONAL URI that the GS will redirect the 1237 User's browser to after GS interaction. 1239 *The response "interaction" object contains:* 1241 * *code* the code the Client displays to the User to enter at the 1242 display_uri. This attribute is REQUIRED. 1244 * *display_uri* the URI the Client displays to the User to load in a 1245 browser to enter the code. 1247 6. RS Access 1249 The mechanism the Client MUST use to access an RS is in the 1250 Authorization JSON "mechanism" attribute Section 4.4.5. 1252 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1254 The "jose" and "jose+body" mechanisms are defined in 1255 [JOSE_Authentication] 1257 A non-normative "bearer" example of the HTTP request headers follows: 1259 GET /calendar HTTP/2 1260 Host: calendar.example 1261 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1263 7. Error Responses 1265 * TBD 1267 8. Warnings 1269 Warnings assist a Client in detecting non-fatal errors. 1271 * TBD 1273 9. Extensibility 1275 This standard can be extended in a number of areas: 1277 * *Client Authentication Mechanisms* 1278 - An extension could define other mechanisms for the Client to 1279 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1280 Signing. Constrained environments could use CBOR [RFC7049] 1281 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1282 [RFC8323] instead of HTTP/2. 1284 * *Grant* 1286 - An extension can define new objects in the Grant Request and 1287 Grant Response JSON that return new URIs. 1289 * *Top Level* 1291 - Top level objects SHOULD only be defined to represent 1292 functionality other the existing top level objects and 1293 attributes. 1295 * *"client" Object* 1297 - Additional information about the Client that the GS would 1298 require related to an extension. 1300 * *"user" Object* 1302 - Additional information about the User that the GS would require 1303 related to an extension. 1305 * *"authorization" Object* 1307 - Additional authorization schemas in addition to OAuth 2.0 1308 scopes and RAR. 1310 * *"claims" Object* 1312 - Additional claim schemas in addition to OpenID Connect claims 1313 and Verified Credentials. 1315 * *interaction modes* 1317 - Additional types of interactions a Client can start with the 1318 User. 1320 * *Continuous Authentication* 1322 - An extension could define a mechanism for the Client to 1323 regularly provide continuous authentication signals and receive 1324 responses. 1326 _[Editor: do we specify access token introspection in this document, 1327 or leave that to an extension?]_ 1329 10. Rational 1331 1. *Why do Clients now always use Asymetric cryptography? Why not 1332 keep the client secret?* 1334 In the past, asymetric cryptography was relatively computational 1335 expensive. Modern browsers now have asymetric cryptographic 1336 APIs available, and modern hardware has significantly reduced 1337 the computational impact. 1339 2. *Why have both Client ID and Client Handle?* 1341 While they both refer to a Client in the protocol, the Client ID 1342 refers to a pre-registered client,and the Client Handle is 1343 specific to an instance of a Dynamic Client. Using separate 1344 terms clearly differentiates which identifier is being presented 1345 to the GS. 1347 3. *Why allow Client and GS to negotiate the user interaction 1348 mode?* 1350 The Client knows what interaction modes it is capable of, and 1351 the GS knows which interaction modes it will permit for a given 1352 Grant Request. The Client can then present the intersection to 1353 the User to choose which one is preferred. For example, while a 1354 device based Client may be willing to do both "indirect" and 1355 "user_code", a GS may not enable "indirect" for concern of a 1356 session fixation attack. Additional interaction modes will 1357 likely become available which allows new modes to be negotiated 1358 between Client and GS as each adds additional interaction modes. 1360 4. *Why have both claims and authorizations?* 1362 There are use cases for each that are independent: 1363 authenticating a user and providing claims vs granting access to 1364 a resource. A request for an authorization returns an access 1365 token which may have full CRUD capabilities, while a request for 1366 a claim returns the claim about the User - with no create, 1367 update or delete capabilities. While the UserInfo endpoint in 1368 OIDC may be thought of as a resource, separating the concepts 1369 and how they are requested keeps each of them simpler in the 1370 Editor's opinion. :) 1372 5. *Why do some of the JSON objects only have one child, such as 1373 the identifiers object in the user object in the Grant Request?* 1374 It is difficult to forecast future use cases. Having more 1375 resolution may mean the difference between a simple extension, 1376 and a convoluted extension. For example, the "global" object in 1377 the "interaction" object allows new global parameters to be 1378 added without impacting new interaction modes. 1380 6. *Why is the "iss" included in the "oidc" identifier object? 1381 Would the "sub" not be enough for the GS to identify the User?* 1383 This decouples the GS from the OpenID Provider (OP). The GS 1384 identifier is the GS URI, which is the endpoint at the GS. The 1385 OP issuer identifier will likely not be the same as the GS URI. 1386 The GS may also provide claims from multiple OPs. 1388 7. *Why is there not a UserInfo endpoint as there is with OpenID 1389 Connect?* 1391 Since the Client can Read Grant at any time, it get the same 1392 functionality as the UserInfo endpoint, without the Client 1393 having to manage a separate access token and refresh token. If 1394 the Client would like additional claims, it can Update Grant, 1395 and the GS will let the Client know if an interaction is 1396 required to get any of the additional claims, which the Client 1397 can then start. 1399 _[Editor: is there some other reason to have the UserInfo 1400 endpoint?]_ 1402 8. *Why use URIs for the Grant and Authorization?* 1404 * Grant URI and AZ URI are defined to start with the GS URI, 1405 allowing the Client, and GS to determine which GS a Grant or 1406 Authorization belongs to. 1408 * URIs also enable a RESTful interface to the GS functionality. 1410 * A large scale GS can easily separate out the services that 1411 provide functionality as routing of requests can be done at 1412 the HTTP layer based on URI and HTTP method. This allows a 1413 separation of concerns, independent deployment, and 1414 resiliency. 1416 9. *Why use the OPTIONS method on the GS URI? Why not use a .well- 1417 known mechanism?* 1419 Having the GS URI endpoint respond to the metadata allows the GS 1420 to provide Client specific results using the same Client 1421 authentication used for other requests to the GS. It also 1422 reduces the risk of a mismatch between the advertised metadata, 1423 and the actual metadata. A .well-known discovery mechanism may 1424 be defined to resolve from a hostname to the GS URI. 1426 10. *Why is there a Verify Grant? The Client can protect itself 1427 from session fixation without it.* 1429 Client implementations may not always follow the best practices. 1430 The Verify Grant allows the GS to ensure there is not a session 1431 fixation as the instance of the Client making creating the Grant 1432 is the one that gets the verification code in the redirect. 1434 11. **Why use the [OIDC] claims rather than the [IANA_JWT] list of 1435 claims? 1437 The [IANA_JWT] claims include claims that are not identity 1438 claims, and [IANA_JWT] references the [OIDC] claims, and [OIDC] 1439 5.1 are only identity claims. 1441 11. Acknowledgments 1443 This draft derives many of its concepts from Justin Richer's 1444 Transactional Authorization draft [TxAuth]. 1446 Additional thanks to Justin Richer and Annabelle Richard Backman for 1447 their strong critique of earlier drafts. 1449 12. IANA Considerations 1451 TBD 1453 13. Security Considerations 1455 TBD 1457 14. References 1459 14.1. Normative References 1461 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1462 Requirement Levels", BCP 14, RFC 2119, 1463 DOI 10.17487/RFC2119, March 1997, 1464 . 1466 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1467 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1468 . 1470 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1471 DOI 10.17487/RFC5322, October 2008, 1472 . 1474 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1475 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1476 . 1478 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1479 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1480 September 2009, . 1482 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1483 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1484 . 1486 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1487 Framework: Bearer Token Usage", RFC 6750, 1488 DOI 10.17487/RFC6750, October 2012, 1489 . 1491 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1492 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1493 . 1495 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1496 Interchange Format", STD 90, RFC 8259, 1497 DOI 10.17487/RFC8259, December 2017, 1498 . 1500 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1501 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1502 . 1504 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1505 Assurance 1.0", October 2019, . 1508 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1509 Rich Authorization Requests", January 2020, 1510 . 1512 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1513 Credentials Data Model 1.0", November 2019, 1514 . 1516 [JOSE_Authentication] 1517 Hardt, D., "JOSE Authentication", June 2020, 1518 . 1520 [GNAP_Advanced] 1521 Hardt, D., "The Grant Negotiation and Authorization 1522 Protocol - Advanced Features", June 2020, 1523 . 1525 14.2. Informative References 1527 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1528 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1529 October 2013, . 1531 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1532 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1533 . 1535 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1536 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1537 Application Protocol) over TCP, TLS, and WebSockets", 1538 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1539 . 1541 [browser_based_apps] 1542 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1543 Apps", September 2019, . 1546 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1547 identification and data capture techniques - QR Code bar 1548 code symbology specification", February 2015, 1549 . 1551 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1552 . 1555 [IANA_JWT] "JSON Web Token Claims", January 2015, 1556 . 1558 Appendix A. Document History 1560 A.1. draft-hardt-xauth-protocol-00 1562 * Initial version 1564 A.2. draft-hardt-xauth-protocol-01 1566 * text clean up 1568 * added OIDC4IA claims 1570 * added "jws" method for accessing a resource. 1572 * renamed Initiation Request -> Grant Request 1574 * renamed Initiation Response -> Interaction Response 1576 * renamed Completion Request -> Authorization Request 1578 * renamed Completion Response -> Grant Request 1580 * renamed completion handle -> authorization handle 1582 * added Authentication Request, Authentication Response, 1583 authentication handle 1585 A.3. draft-hardt-xauth-protocol-02 1587 * major rewrite 1589 * handles are now URIs 1591 * the collection of claims and authorizations are a Grant 1593 * an Authorization is its own type 1595 * lots of sequences added 1597 A.4. draft-hardt-xauth-protocol-03 1599 * fixed RO definition 1601 * improved language in Rationals 1603 * added user code interaction method, and aligned qrcode interaction 1604 method 1606 * added information_uri for code flows 1608 A.5. draft-hardt-xauth-protocol-04 1610 * renamed interaction uris to have purpose specific names 1612 A.6. draft-hardt-xauth-protocol-05 1614 * separated claims from identifiers in request user object 1616 * simplified reciprocal grant flow 1618 * reduced interactions to redirect and indirect 1620 * simplified interaction parameters 1622 * added in language for Client to verify interaction completion 1624 * added Verify Grant API and Interaction Nonce 1626 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1627 operation. 1629 A.7. draft-hardt-xauth-protocol-06 1631 * fixup examples to match specification 1633 A.8. draft-hardt-xauth-protocol-07 1635 * refactored interaction request and response syntax, and enabled 1636 interaction mode negotiation 1638 * generation of client handle by GS for dynamic clients 1640 * renamed title to Grant Negotiation and Authorization Protocol. 1641 Preserved draft-hardt-xauth-protocol filename to ease tracking 1642 changes. 1644 * changed Authorizations to be key / value pairs (aka dictionary) 1645 instead of a JSON array 1647 A.9. draft-hardt-xauth-protocol-08 1649 * split document into three documents: core, advanced, and JOSE 1650 authentication. 1652 * grouped access granted into "access" object in Authorization JSON 1654 * added warnings object to the Grant Response JSON 1656 A.10. draft-hardt-xauth-protocol-09 1658 * added editorial note that this document should be referred to as 1659 XAuth 1661 A.11. draft-hardt-xauth-protocol-10 1663 * added example of RAR authorization request 1665 * fixed typos 1667 A.12. draft-hardt-xauth-protocol-11 1669 * renamed authorization_uri to interaction_uri to avoid confusion 1670 with AZ URI 1672 * made URI names more consistent 1674 - renamed completion_uri to information_uri 1676 - renamed redirect_uri to completion_uri 1678 - renamed interaction_uri to redirect_uri 1680 - renamed short_uri to indirect_uri 1682 * editorial fixes 1684 * renamed http verb to method 1686 * added Verify Grant and verification parameters 1688 A.13. draft-hardt-xauth-protocol-11 1690 * removed authorization object, and made authorizations object 1691 polymorphic 1693 A.14. draft-hardt-xauth-protocol-12 1695 * added Q about referencing OIDC claims vs IANA JWT 1697 * made all authorizations be a RAR type as it provides the required 1698 flexibility, removed "oauth_rar" type 1700 * added RO to places where the RO and User are the same 1702 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1704 *Changed Features* 1706 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1708 * The Client always uses a private asymetric key to authenticate to 1709 the GS. There is no client secret. i 1711 * The Client initiates the protocol by making a signed request 1712 directly to the GS instead of redirecting the User to the GS. 1714 * The Client does not pass any parameters in redirecting the User to 1715 the GS. 1717 * The refresh_token has been replaced with an AZ URI that both 1718 represents the authorization, and is the URI for obtaining a fresh 1719 access token. 1721 * The Client can request identity claims to be returned independent 1722 of the ID Token. 1724 * The GS URI is the only static endpoint. All other URIs are 1725 dynamically generated. The Client does not need to register it's 1726 redirect URIs. 1728 *Preserved Features* 1730 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1731 2.0. 1733 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1735 * No change is required by the Client or the RS for accessing 1736 existing bearer token protected APIs. 1738 *New Features* 1740 * All Client calls to the GS are authenticated with asymetric 1741 cryptography 1743 * A Grant represents both the user identity claims and RS access 1744 granted to the Client. 1746 * Support for scannable code initiated interactions. 1748 * Highly extensible per Section 9. 1750 Author's Address 1752 Dick Hardt (editor) 1753 SignIn.Org 1754 United States 1755 Email: dick.hardt@gmail.com