idnits 2.17.1 draft-hardt-xauth-protocol-12.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: * *authorization_details* - an authorization_details JSON array of objects per [RAR]. MUST be included if type is "oauth_rich". MUST not be included if type is "oauth_scope" == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * *completion_uri* a unique URI at the Client that the GS will return the User to. The URI MUST not contain the "nonce" from the Grant Request, and MUST not be guessable. This attribute is REQUIRED. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: *The response "interaction" object contains:* * *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 (8 July 2020) is 1381 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 4949 -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' -- Possible downref: Non-RFC (?) normative reference: ref. 'RAR' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 8 July 2020 5 Expires: 9 January 2021 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-12 10 Abstract 12 Client software often desires resources or identity claims that are 13 independent of the client. This protocol allows a user and/or 14 resource owner to delegate resource authorization and/or release of 15 identity claims to a server. Client software can then request access 16 to resources and/or identity claims by calling the server. The 17 server acquires consent and authorization from the user and/or 18 resource owner if required, and then returns to the client software 19 the authorization and identity claims that were approved. This 20 protocol may be extended to support alternative authorizations, 21 claims, interactions, and client authentication mechanisms. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 9 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 . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . . . . . . . . . 23 84 4.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 23 85 4.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 23 86 4.4.2. "interaction" Object . . . . . . . . . . . . . . . . 24 87 4.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 24 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" . . . . . . . . . . . . . . . . . . . . . . . 28 100 6. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 7. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 28 102 8. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . 28 103 9. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 29 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 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 37 126 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 128 1. Introduction 130 *EDITOR NOTE* 132 _This document captures a number of concepts that may be adopted by 133 the proposed GNAP working group. Please refer to this document as:_ 135 *XAuth* 137 _The use of GNAP in this document is not intended to be a declaration 138 of it being endorsed by the proposed GNAP working group._ 139 This document describes the core Grant Negotiation and Authorization 140 Protocol (GNAP). The protocol supports the widely deployed use cases 141 supported by OAuth 2.0 [RFC6749] & [RFC6750], OpenID Connect [OIDC] - 142 an extension of OAuth 2.0, as well as other extensions. Related 143 documents include: GNAP - Advanced Features [GNAP_Advanced] and JOSE 144 Authentication [JOSE_Authentication] that describes the JOSE 145 mechanisms for client authentication. 147 The technology landscape has changed since OAuth 2.0 was initially 148 drafted. More interactions happen on mobile devices than PCs. 149 Modern browsers now directly support asymetric cryptographic 150 functions. Standards have emerged for signing and encrypting tokens 151 with rich payloads (JOSE) that are widely deployed. 153 GNAP simplifies the overall architectural model, takes advantage of 154 today's technology landscape, provides support for all the widely 155 deployed use cases, offers numerous extension points, and addresses 156 many of the security issues in OAuth 2.0 by passing parameters 157 securely between parties, rather than via a browser redirection. . 159 While GNAP is not backwards compatible with OAuth 2.0, it strives to 160 minimize the migration effort. 162 GNAP centers around a Grant, a representation of the collection of 163 user identity claims and/or resource authorizations the Client is 164 requesting, and the resulting identity claims and/or resource 165 authorizations granted by the Grant Server (GS). 167 User consent is often required at the GS. GNAP enables a Client and 168 GS to negotiate the interaction mode for the GS to obtain consent. 170 The suggested pronunciation of GNAP is the same as the English word 171 "nap", a silent "g" as in "gnaw". 173 _[Editor: suggestions on how to improve this are welcome!]_ 175 1.1. Parties 177 The parties and their relationships to each other: 179 +--------+ +------------+ 180 | User | | Resource | 181 | | | Owner (RO) | 182 +--------+ +------------+ 183 | \ / | 184 | \ / | 185 | \ / | 186 | \ / | 187 +--------+ +---------------+ +------------+ 188 | Client |---->| Grant | | Resource | 189 | | (1) | Server (GS) | _ _ | Server | 190 | |<----| | | (RS) | 191 | | +---------------+ | | 192 | |-------------------------->| | 193 | | (2) | | 194 | |<--------------------------| | 195 +--------+ +------------+ 197 This document specifies interactions between the Client and GS (1), 198 and the Client and RS (2). 200 * *User* - the person interacting with the Client who has delegated 201 access to identity claims about themselves to the Grant Server 202 (GS), and can authenticate at the GS. 204 * *Client* - requests a Grant from the GS to access one or more 205 Resource Servers (RSs), and/or identity claims about the User. 206 The Grant may include access tokens that the Client uses to access 207 the RS. There are two types of Clients: Registered Clients and 208 Dynamic Clients. All Clients have a private asymetric key to 209 authenticate with the Grant Server. 211 * *Registered Client* - a Client that has registered with the GS and 212 has a Client ID to identify itself, and can prove it possesses a 213 key that is linked to the Client ID. The GS may have different 214 policies for what different Registered Clients can request. A 215 Registered Client MAY be interacting with a User. 217 * *Dynamic Client* - a Client that has not been previously 218 registered with the GS, and each instance will generate it's own 219 asymetric key pair so it can prove it is the same instance of the 220 Client on subsequent requests. The GS MAY return a Dynamic Client 221 a Client Handle for the Client to identify itself in subsequent 222 requests. A single-page application with no active server 223 component is an example of a Dynamic Client. A Dynamic Client 224 MUST be interacting with a User. 226 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 227 release of identity claims about the User. The GS may require 228 explicit consent from the RO or User to provide these to the 229 Client. A GS may support Registered Clients and/or Dynamic 230 Clients. The GS is a combination of the Authorization Server (AS) 231 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 233 * *Resource Server* (RS) - has API resources that require an access 234 token from the GS. Some, or all of the resources are owned by the 235 Resource Owner. 237 * *Resource Owner* (RO) - owns resources at the RS, and has 238 delegated RS access management to the GS. The RO may be the same 239 entity as the User, or may be a different entity that the GS 240 interacts with independently. GS and RO interactions are out of 241 scope of this document. 243 1.2. Reused Terms 245 * *access token* - an access token as defined in [RFC6749] 246 Section 1.4. 248 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 249 issued by the GS, or by other issuers. 251 * *Client ID* - a GS unique identifier for a Registered Client as 252 defined in [RFC6749] Section 2.2. 254 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 256 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 258 * *authN* - short for authentication. 260 * *authZ* - short for authorization. 262 1.3. New Terms 264 * *GS URI* - the endpoint at the GS the Client calls to create a 265 Grant, and is the unique identifier for the GS. 267 * *Grant* - the user identity claims and/or RS authorizations the GS 268 has granted to the Client. The GS MAY invalidate a Grant at any 269 time. 271 * *Grant URI* - the URI that represents the Grant. The Grant URI 272 MUST start with the GS URI. 274 * *Authorization* - the access granted by the RO to the Client and 275 contains an access token. The GS may invalidate an Authorization 276 at any time. 278 * *Authorization URI* (AZ URI) - the URI that represents the 279 Authorization the Client was granted by the RO. The AZ URI MUST 280 start with the GS URI. The AZ URI is used to refresh an access 281 token. 283 * *Interaction* - how the Client directs the User to interact with 284 the GS. This document defines the interaction modes: "redirect", 285 "indirect", and "user_code" in Section 5 287 * *Client Handle* - a unique identifier at the GS for a Dynamic 288 Client for the Dynamic Client to refer to itself in subsequent 289 requests. 291 1.4. Notational Conventions 293 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 294 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 295 specification are to be interpreted as described in [RFC2119]. 297 Certain security-related terms are to be understood in the sense 298 defined in [RFC4949]. These terms include, but are not limited to, 299 "attack", "authentication", "authorization", "certificate", 300 "confidentiality", "credential", "encryption", "identity", "sign", 301 "signature", "trust", "validate", and "verify". 303 _[Editor: review terms]_ 305 Unless otherwise noted, all the protocol parameter names and values 306 are case sensitive. 308 Some protocol parameters are parts of a JSON document, and are 309 referred to in JavaScript notation. For example, foo.bar refers to 310 the "bar" boolean attribute in the "foo" object in the following 311 example JSON document: 313 { 314 "foo" : { 315 "bar": true 316 } 317 } 319 2. Sequences 321 Before any sequence, the Client needs to be manually or 322 programmatically configured for the GS. See GS Options Section 3.7 323 for details on programmatically acquiring GS metadata. 325 2.1. "redirect" Interaction 327 The Client is a web application and wants a Grant from the User: 329 +--------+ +-------+ 330 | Client | | GS | 331 | |--(1)--- Create Grant ----------->| | 332 | | | | 333 | |<--- Interaction Response ---(2)--| | +------+ 334 | | | | | User | 335 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 336 | | | |<--(4)-->| | 337 | | | | authN | | 338 | | | | | | 339 | | | |<--(5)-->| | 340 | | | | authZ | | 341 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 342 | | | | | | 343 | |--(7)--- Verify Grant ----------->| | +------+ 344 | | | | 345 | |<--------- Grant Response ---(8)--| | 346 | | | | 347 +--------+ +-------+ 349 1. *Create Grant* The Client creates a Request JSON document 350 Section 3.5 containing an interaction.redirect object and makes a 351 Create Grant request (Section 3.2) by sending the JSON with an 352 HTTP POST to the GS URI. 354 2. *Interaction Response* The GS determines that interaction with 355 the User is required and sends an Interaction Response 356 (Section 4.2) containing the Grant URI and an 357 interaction.redirect object. 359 3. *Interaction Transfer* The Client redirects the User to the 360 redirect_uri at the GS. 362 4. *User Authentication* The GS authenticates the User. 364 5. *User Authorization* If required, the GS interacts with the User 365 to determine which identity claims and/or authorizations in the 366 Grant Request are to be granted. 368 6. *Interaction Transfer* The GS redirects the User to the 369 completion_uri at the Client. 371 7. *Verify Grant* The Client makes an HTTP PATCH request to the 372 Grant URI passing the verification code (Section 3.3). 374 8. *Grant Response* The GS responds with a Grant Response 375 (Section 4.1). 377 2.2. "user_code" Interaction 379 A Client is on a device wants a Grant from the User: 381 +--------+ +-------+ 382 | Client | | GS | 383 | |--(1)--- Create Grant ----------->| | 384 | | | | 385 | |<--- Interaction Response ---(2)--| | +------+ 386 | | | | | User | 387 | |--(3)--- Read Grant ------------->| | | | 388 | | | |<--(4)-->| | 389 | | | | authN | | 390 | | | | | | 391 | | | |<--(5)---| | 392 | | | | code | | 393 | | | | | | 394 | | | |<--(6)-->| | 395 | | | | authZ | | 396 | | | | | | 397 | |<--------- Grant Response ---(7)--| | | | 398 | | | | | | 399 +--------+ | | | | 400 | | | | 401 +--------+ | | | | 402 | Client |<---- Information URI Redirect -- | - - - | --(8)---| | 403 | Server | | | | | 404 +--------+ +-------+ +------+ 406 1. *Create Grant* The Client creates a Request JSON document 407 Section 3.5 containing an interaction.user_code object and makes 408 a Create Grant request (Section 3.2) by sending the JSON with an 409 HTTP POST to the GS URI. 411 2. *Interaction Response* The GS determines that interaction with 412 the User is required and sends an Interaction Response 413 (Section 4.2) containing the Grant URI and an 414 interaction.user_code object. 416 3. *Read Grant* The Client makes an HTTP GET request to the Grant 417 URI. 419 4. *User Authentication* The User loads display_uri in their 420 browser, and the GS authenticates the User. 422 5. *User Code* The User enters the code at the GS. 424 6. *User Authorization* If required, the GS interacts with the User 425 to determine which identity claims and/or authorizations in the 426 Grant Request are to be granted. 428 7. *Grant Response* The GS responds with a Grant Response 429 (Section 4.1). 431 8. *Information URI Redirect* The GS redirects the User to the 432 information_uri provided by the Client. 434 2.3. Independent RO Authorization 436 The Client wants access to resources that require the GS to interact 437 with the RO, who is not interacting with the Client. The 438 authorization from the RO may take some time, so the GS instructs the 439 Client to wait and check back later. 441 +--------+ +-------+ 442 | Client | | GS | 443 | |--(1)--- Create Grant ----------->| | 444 | | | | 445 | |<---------- Wait Response ---(2)--| | +------+ 446 | (3) | | | | RO | 447 | Wait | | |<--(4)-->| | 448 | | | | AuthZ | | 449 | |--(5)--- Read Grant ------------->| | +------+ 450 | | | | 451 | |<--------- Grant Response --(6)---| | 452 | | | | 453 +--------+ +-------+ 455 1. *Create Grant* The Client creates a Grant Request (Section 3.2) 456 and sends it with an HTTP POST to the GS GS URI. 458 2. *Wait Response* The GS sends an Wait Response (Section 4.3) 459 containing the Grant URI and the "wait" attribute. 461 3. *Client Waits* The Client waits for the time specified in the 462 "wait" attribute. 464 4. *RO AuthZ* The GS interacts with the RO to determine which 465 identity claims and/or resource authorizations in the Grant 466 Request are to be granted. 468 5. *Read Grant* The Client does an HTTP GET of the Grant URI 469 (Section 3.4). 471 6. *Grant Response* The GS responds with a Grant Response 472 (Section 4.1). 474 2.4. Resource Server Access 476 The Client received an AZ URI from the GS. The Client acquires an 477 access token, calls the RS, and later the access token expires. The 478 Client then gets a fresh access token. 480 +--------+ +----------+ +-------+ 481 | Client | | Resource | | GS | 482 | |--(1)--- Access Resource --->| Server | | | 483 | |<------- Resource Response --| (RS) | | | 484 | | | | | | 485 | |--(2)--- Access Resource --->| | | | 486 | |<------- Error Response -----| | | | 487 | | | | | | 488 | | +----------+ | | 489 | | | | 490 | |--(3)--- Read AuthZ ---------------------->| | 491 | |<------- AuthZ Response -------------------| | 492 | | | | 493 +--------+ +-------+ 495 1. *Resource Request* The Client accesses the RS with the access 496 token per Section 6 and receives a response from the RS. 498 2. *Resource Request* The Client attempts to access the RS, but 499 receives an error indicating the access token needs to be 500 refreshed. 502 3. *Read AuthZ* The Client makes a Read AuthZ (Section 3.6) with an 503 HTTP GET to the AZ URI and receives as Response JSON 504 "authorization" object (Section 4.4.5) with a fresh access token. 506 3. GS APIs 508 *Client Authentication* 510 All GS APIs except for GS Options require the Client to authenticate. 511 Authentication mechanisms include: 513 * JOSE Authentication [JOSE_Authentication] 515 * [Others TBD]* 517 3.1. GS API Table 519 +==============+=============+========+=============================+ 520 | request | http method | uri | response | 521 +==============+=============+========+=============================+ 522 | GS Options | OPTIONS | GS URI | metadata | 523 +--------------+-------------+--------+-----------------------------+ 524 | Create Grant | POST | GS URI | interaction, | 525 | | | | wait, or grant | 526 +--------------+-------------+--------+-----------------------------+ 527 | Verify Grant | PATCH | Grant | grant | 528 | | | URI | | 529 +--------------+-------------+--------+-----------------------------+ 530 | Read Grant | GET | Grant | wait, or grant | 531 | | | URI | | 532 +--------------+-------------+--------+-----------------------------+ 533 | Read AuthZ | GET | AZ URI | authorization | 534 +--------------+-------------+--------+-----------------------------+ 536 Table 1 538 3.2. Create Grant 540 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 541 document to the GS URI. This is a Grant Request. 543 The JSON document MUST include the following from the Request JSON 544 Section 3.5: 546 * iat 548 * nonce 550 * uri - MUST be set to the GS URI 552 * method - MUST be "POST" 554 * client 556 and MAY include the following from Request JSON Section 3.5 558 * user 560 * interaction 561 * authorizations 563 * claims 565 The GS MUST respond with one of Grant Response Section 4.1, 566 Interaction Response Section 4.2, Wait Response Section 4.3, or one 567 of the following errors: 569 * TBD 571 from Error Responses Section 7. 573 Following is a non-normative example of a web application Client 574 requesting identity claims about the User and read access to the 575 User's contacts: 577 Example 1 579 { 580 "iat" : 15790460234, 581 "uri" : "https://as.example/endpoint", 582 "method" : "POST, 583 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 584 "client": { 585 "display": { 586 "name" : "SPA Display Name", 587 "uri" : "https://spa.example/about" 588 } 589 }, 590 "interaction": { 591 "redirect": { 592 "completion_uri" : "https://web.example/return" 593 }, 594 "global" : { 595 "ui_locals" : "de" 596 } 597 }, 598 "authorizations": { 599 "type" : "oauth_scope", 600 "scope" : "read_contacts" 601 }, 602 "claims": { 603 "oidc": { 604 "id_token" : { 605 "email" : { "essential" : true }, 606 "email_verified" : { "essential" : true } 607 }, 608 "userinfo" : { 609 "name" : { "essential" : true }, 610 "picture" : null 611 } 612 } 613 } 614 } 616 Following is a non-normative example of a device Client requesting 617 two different access tokens, one request with "oauth_scope", the 618 other with "oauth_rich": 620 Example 2 622 { 623 "iat" : 15790460234, 624 "uri" : "https://as.example/endpoint", 625 "method" : "POST, 626 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 627 "client": { 628 "id" : "di3872h34dkJW" 629 }, 630 "interaction": { 631 "indirect": { 632 "information_uri": "https://device.example/c/indirect" 633 }, 634 "user_code": { 635 "information_uri": "https://device.example/c/user_code" 636 } 637 }, 638 "authorizations": { 639 "play_music": { 640 "type" : "oauth_scope", 641 "scope" : "play_music", 642 }, 643 "read_user_info: { 644 "type" : "oauth_rich", 645 "authorization_details" [ 646 { 647 "type": "customer_information", 648 "locations": [ 649 "https://example.com/customers", 650 ] 651 "actions": [ 652 "read" 653 ], 654 "datatypes": [ 655 "contacts", 656 "photos" 657 ] 658 } 659 ] 660 } 661 } 662 } 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* - one of the following values: "oauth_scope" or 796 "oauth_rich". Extensions MAY define additional types, and the 797 required attributes. This attribute is REQUIRED. 799 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 800 section 3.3. MUST be included if type is "oauth_scope". MAY be 801 included if type is "oauth_rich". 803 * *authorization_details* - an authorization_details JSON array of 804 objects per [RAR]. MUST be included if type is "oauth_rich". 805 MUST not be included if type is "oauth_scope" 807 _[Editor: details may change as the RAR document evolves]_ 809 3.5.6. "claims" Object 811 Includes one or more of the following: 813 * *oidc* - an object that contains one or both of the following 814 objects: 816 - *userinfo* - Claims that will be returned as a JSON object 818 - *id_token* - Claims that will be included in the returned ID 819 Token. If the null value, an ID Token will be returned 820 containing no additional Claims. 822 The contents of the userinfo and id_token objects are Claims as 823 defined in [OIDC] Section 5. 825 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 826 per [OIDC4IA]. 828 * *vc* - _[Editor: define how W3C Verifiable Credentials can be 829 requested.]_[W3C_VC] 831 3.6. Read Authorization 833 The Client acquires and refreshes an Authorization by doing an HTTP 834 GET to the corresponding AZ URI. 836 The GS MUST respond with a Authorization JSON document Section 4.5, 837 or one of the following errors: 839 * TBD 841 from Error Responses Section 7. 843 3.7. GS Options 845 The Client can get the metadata for the GS by doing an HTTP OPTIONS 846 of the corresponding GS URI. This is the only API where the GS MAY 847 respond to an unauthenticated request. 849 The GS MUST respond with the the following JSON document: 851 * *uri* - the GS URI. 853 * *client_authentication* - a JSON array of the Client 854 Authentication mechanisms supported by the GS 856 * *interactions* - a JSON array of the interaction modes supported 857 by the GS. 859 * *authorization* - an object containing the authorizations the 860 Client may request from the GS, if any. 862 - Details TBD 864 * *claims* - an object containing the identity claims the Client may 865 request from the GS, if any, and what public keys the claims will 866 be signed with. 868 - Details TBD 870 * *algorithms* - a JSON array of the cryptographic algorithms 871 supported by the GS. [details TBD]* 873 * *features* - an object containing feature support 875 - *authorizations* - boolean indicating if a request for more 876 than one authorization in a request is supported. 878 or one of the following errors: 880 * TBD 882 from Error Responses Section 7. 884 4. GS Responses 886 There are three successful responses to a Grant Request: Grant 887 Response, Interaction Response, or Wait Response. 889 4.1. Grant Response 891 The Grant Response MUST include the following from the Response JSON 892 Section 4.4 894 * iat 896 * nonce 898 * uri 900 and MAY include the following from the Response JSON Section 4.4 902 * client.handle 903 * authorization or authorizations 905 * claims 907 * expires_in 909 * warnings 911 Example non-normative Grant Response JSON document for Example 1 in 912 Section 3.2: 914 { 915 "iat" : 15790460234, 916 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 917 "uri" : "https://as.example/endpoint/grant/example1", 918 "expires_in" : 300 919 "authorizations": { 920 "access": { 921 "type" : "oauth_scope", 922 "scope" : "read_contacts" 923 }, 924 "expires_in" : 3600, 925 "mechanism" : "bearer", 926 "token" : "eyJJ2D6.example.access.token.mZf9p" 927 }, 928 "claims": { 929 "oidc": { 930 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 931 "userinfo" : { 932 "name" : "John Doe", 933 "picture" : "https://photos.example/p/eyJzdkiO" 934 } 935 } 936 } 937 } 939 Note in this example the access token can not be refreshed, and 940 expires in an hour. 942 Example non-normative Grant Response JSON document for Example 2 in 943 Section 3.2: 945 { 946 "iat" : 15790460234, 947 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 948 "uri" : "https://as.example/endpoint/grant/example2", 949 "authorizations": { 950 "play_music": { "uri" : "https://as.example/endpoint/authz/example2" }, 951 "read_user_info: { "uri" " "https://as.example/endpoint/authz/"} 952 } 953 } 955 Note in this example the GS only provided the AZ URIs, and Client 956 must acquire the Authorizations per Section 3.6 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 1003 * wait 1005 and MAY include the following from the Response JSON Section 4.4 1007 * warnings 1009 A non-normative example of Wait Response follows: 1011 { 1012 "iat" : 15790460234, 1013 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1014 "uri" : "https://as.example/endpoint/grant/example5", 1015 "wait" : 300 1016 } 1018 4.4. Response JSON 1020 Details of the JSON document: 1022 * *iat* - the time of the response as a NumericDate. 1024 * *nonce* - the nonce that was included in the Request JSON 1025 Section 3.5. 1027 * *uri* - the Grant URI. 1029 * *wait* - a numeric value representing the number of seconds the 1030 Client should want before making a Read Grant request to the Grant 1031 URI. 1033 * *expires_in* - a numeric value specifying how many seconds until 1034 the Grant expires. This attribute is OPTIONAL. 1036 4.4.1. "client" Object 1038 The GS may 1040 4.4.2. "interaction" Object 1042 If the GS wants the Client to start the interaction, the GS MUST 1043 return an interaction object containing one or more interaction mode 1044 responses per Section 5 to one or more of the interaction mode 1045 requests provided by the Client. 1047 4.4.3. "user" Object 1049 * *exists* - a boolean value indicating if the GS has a user with 1050 one or more of the provided identifiers in the Request 1051 user.identifiers object Section 3.5.3 1053 4.4.4. "authorizations" Object 1055 The authorizations object MUST contain either an authorization 1056 response object Section 4.4.5, or a key / value pair for each key in 1057 the Grant Request "authorizations" objectSection 3.5.4, and the value 1058 is an authorization response object Section 4.4.5. 1060 4.4.5. Authorization response Object 1062 The authorization response object MUST contain only a "uri" attribute 1063 or the following from Authorization JSON Section 4.5: 1065 * mechanism 1067 * token 1069 The authorization object MAY contain any of the following from 1070 Authorization JSON Section 4.5: 1072 * access 1074 * expires_in 1076 * uri 1078 If there is no "uri" attribute, the access token can not be 1079 refreshed. If only the "uri" attribute is present, the Client MUST 1080 acquire the Authorization per Section 3.6 1082 4.4.6. "claims" Object 1084 The claims object is a response to the Grant Request "claims" object 1085 Section 3.5.6. 1087 * *oidc* 1088 - *id_token* - an OpenID Connect ID Token containing the Claims 1089 the User consented to be released. 1091 - *userinfo* - the Claims the User consented to be released. 1093 Claims are defined in [OIDC] Section 5. 1095 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1096 per [OIDC4IA]. 1098 * *vc* 1100 The verified claims the user consented to be released. _[Editor: 1101 details TBD]_ 1103 4.4.7. "warnings" JSON Array 1105 Includes zero or more warnings from Section 8, 1107 4.5. Authorization JSON 1109 The Authorization JSON is a Grant Response Authorization Object 1110 Section 4.4.5 or the response to a Read AuthZ request by the Client 1111 Section 3.6. 1113 * *mechanism* - the RS access mechanism. This document defines the 1114 "bearer" mechanism as defined in Section 6 1116 * *token* - the access token for accessing an RS. 1118 * *expires_in* - a numeric value specifying how many seconds until 1119 the access token expires. 1121 * *uri* - the AZ URI. Used to acquire or refresh an authorization. 1123 * *access* - an object containing the access granted: 1125 - *type* - the type of claim request: "oauth_scope" or 1126 "oauth_rich". See the "type" object in Section 3.5.4 for 1127 details. This attribute is REQUIRED. 1129 - *scope* - the scopes the Client was granted authorization for. 1130 This will be all, or a subset, of what was requested. This 1131 attribute is OPTIONAL. 1133 - *authorization_details* - the authorization details granted per 1134 [RAR]. This attribute is OPTIONAL if "type" is "oauth_rich". 1136 _[Editor: would an optional expiry for the Authorization be useful?]_ 1138 The following is a non-normative example of Authorization JSON: 1140 { 1141 "mechanism" : "bearer", 1142 "token" : "eyJJ2D6.example.access.token.mZf9p" 1143 "expires_in" : 3600, 1144 "uri" : "https://as.example/endpoint/authz/example2", 1145 "access": { 1146 "type" : "oauth_scope", 1147 "scope" : "read_calendar write_calendar" 1148 } 1149 } 1151 4.6. Response Verification 1153 On receipt of a response, the Client MUST verify the following: 1155 * TBD 1157 5. Interaction Modes 1159 This document defines three interaction modes: "redirect", 1160 "indirect", and "user_code". Extensions may define additional 1161 interaction modes. 1163 The "global" attribute is reserved in the interaction object for 1164 attributes that apply to all interaction modes. 1166 5.1. "redirect" 1168 A Redirect Interaction is characterized by the Client redirecting the 1169 User's browser to the GS, the GS interacting with the User, and then 1170 GS redirecting the User's browser back to the Client. The GS 1171 correlates the Grant Request with the unique redirect_uri, and the 1172 Client correlates the Grant Request with the unique completion_uri. 1174 *The request "interaction" object contains:* 1176 * *completion_uri* a unique URI at the Client that the GS will 1177 return the User to. The URI MUST not contain the "nonce" from the 1178 Grant Request, and MUST not be guessable. This attribute is 1179 REQUIRED. 1181 *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?]_ 1235 *The request "interaction" object contains:* 1237 * *information_uri* an OPTIONAL URI that the GS will redirect the 1238 User's browser to after GS interaction. 1240 *The response "interaction" object contains:* 1242 * *code* the code the Client displays to the User to enter at the 1243 display_uri. This attribute is REQUIRED. 1245 * *display_uri* the URI the Client displays to the User to load in a 1246 browser to enter the code. 1248 6. RS Access 1250 The mechanism the Client MUST use to access an RS is in the 1251 Authorization JSON "mechanism" attribute Section 4.4.5. 1253 The "bearer" mechanism is defined in Section 2.1 of [RFC6750] 1255 The "jose" and "jose+body" mechanisms are defined in 1256 [JOSE_Authentication] 1258 A non-normative "bearer" example of the HTTP request headers follows: 1260 GET /calendar HTTP/2 1261 Host: calendar.example 1262 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1264 7. Error Responses 1266 * TBD 1268 8. Warnings 1270 Warnings assist a Client in detecting non-fatal errors. 1272 * TBD 1274 9. Extensibility 1276 This standard can be extended in a number of areas: 1278 * *Client Authentication Mechanisms* 1280 - An extension could define other mechanisms for the Client to 1281 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1282 Signing. Constrained environments could use CBOR [RFC7049] 1283 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1284 [RFC8323] instead of HTTP/2. 1286 * *Grant* 1288 - An extension can define new objects in the Grant Request and 1289 Grant Response JSON that return new URIs. 1291 * *Top Level* 1293 - Top level objects SHOULD only be defined to represent 1294 functionality other the existing top level objects and 1295 attributes. 1297 * *"client" Object* 1299 - Additional information about the Client that the GS would 1300 require related to an extension. 1302 * *"user" Object* 1304 - Additional information about the User that the GS would require 1305 related to an extension. 1307 * *"authorization" Object* 1309 - Additional authorization schemas in addition to OAuth 2.0 1310 scopes and RAR. 1312 * *"claims" Object* 1314 - Additional claim schemas in addition to OpenID Connect claims 1315 and Verified Credentials. 1317 * *interaction modes* 1319 - Additional types of interactions a Client can start with the 1320 User. 1322 * *Continuous Authentication* 1324 - An extension could define a mechanism for the Client to 1325 regularly provide continuous authentication signals and receive 1326 responses. 1328 _[Editor: do we specify access token introspection in this document, 1329 or leave that to an extension?]_ 1331 10. Rational 1333 1. *Why do Clients now always use Asymetric cryptography? Why not 1334 keep the client secret?* 1336 In the past, asymetric cryptography was relatively computational 1337 expensive. Modern browsers now have asymetric cryptographic 1338 APIs available, and modern hardware has significantly reduced 1339 the computational impact. 1341 2. *Why have both Client ID and Client Handle?* 1343 While they both refer to a Client in the protocol, the Client ID 1344 refers to a pre-registered client,and the Client Handle is 1345 specific to an instance of a Dynamic Client. Using separate 1346 terms clearly differentiates which identifier is being presented 1347 to the GS. 1349 3. *Why allow Client and GS to negotiate the user interaction 1350 mode?* 1352 The Client knows what interaction modes it is capable of, and 1353 the GS knows which interaction modes it will permit for a given 1354 Grant Request. The Client can then present the intersection to 1355 the User to choose which one is preferred. For example, while a 1356 device based Client may be willing to do both "indirect" and 1357 "user_code", a GS may not enable "indirect" for concern of a 1358 session fixation attack. Additional interaction modes will 1359 likely become available which allows new modes to be negotiated 1360 between Client and GS as each adds additional interaction modes. 1362 4. *Why have both claims and authorizations?* 1364 There are use cases for each that are independent: 1365 authenticating a user and providing claims vs granting access to 1366 a resource. A request for an authorization returns an access 1367 token which may have full CRUD capabilities, while a request for 1368 a claim returns the claim about the User - with no create, 1369 update or delete capabilities. While the UserInfo endpoint in 1370 OIDC may be thought of as a resource, separating the concepts 1371 and how they are requested keeps each of them simpler in the 1372 Editor's opinion. :) 1374 5. *Why do some of the JSON objects only have one child, such as 1375 the identifiers object in the user object in the Grant Request?* 1377 It is difficult to forecast future use cases. Having more 1378 resolution may mean the difference between a simple extension, 1379 and a convoluted extension. For example, the "global" object in 1380 the "interaction" object allows new global parameters to be 1381 added without impacting new interaction modes. 1383 6. *Why is the "iss" included in the "oidc" identifier object? 1384 Would the "sub" not be enough for the GS to identify the User?* 1386 This decouples the GS from the OpenID Provider (OP). The GS 1387 identifier is the GS URI, which is the endpoint at the GS. The 1388 OP issuer identifier will likely not be the same as the GS URI. 1389 The GS may also provide claims from multiple OPs. 1391 7. *Why is there not a UserInfo endpoint as there is with OpenID 1392 Connect?* 1394 Since the Client can Read Grant at any time, it get the same 1395 functionality as the UserInfo endpoint, without the Client 1396 having to manage a separate access token and refresh token. If 1397 the Client would like additional claims, it can Update Grant, 1398 and the GS will let the Client know if an interaction is 1399 required to get any of the additional claims, which the Client 1400 can then start. 1402 _[Editor: is there some other reason to have the UserInfo 1403 endpoint?]_ 1405 8. *Why use URIs for the Grant and Authorization?* 1407 * Grant URI and AZ URI are defined to start with the GS URI, 1408 allowing the Client, and GS to determine which GS a Grant or 1409 Authorization belongs to. 1411 * URIs also enable a RESTful interface to the GS functionality. 1413 * A large scale GS can easily separate out the services that 1414 provide functionality as routing of requests can be done at 1415 the HTTP layer based on URI and HTTP method. This allows a 1416 separation of concerns, independent deployment, and 1417 resiliency. 1419 9. *Why use the OPTIONS method on the GS URI? Why not use a .well- 1420 known mechanism?* 1422 Having the GS URI endpoint respond to the metadata allows the GS 1423 to provide Client specific results using the same Client 1424 authentication used for other requests to the GS. It also 1425 reduces the risk of a mismatch between the advertised metadata, 1426 and the actual metadata. A .well-known discovery mechanism may 1427 be defined to resolve from a hostname to the GS URI. 1429 10. *Why is there a Verify Grant? The Client can protect itself 1430 from session fixation without it.* 1432 Client implementations may not always follow the best practices. 1433 The Verify Grant allows the GS to ensure there is not a session 1434 fixation as the instance of the Client making creating the Grant 1435 is the one that gets the verification code in the redirect. 1437 11. Acknowledgments 1439 This draft derives many of its concepts from Justin Richer's 1440 Transactional Authorization draft [TxAuth]. 1442 Additional thanks to Justin Richer and Annabelle Richard Backman for 1443 their strong critique of earlier drafts. 1445 12. IANA Considerations 1447 TBD 1449 13. Security Considerations 1451 TBD 1453 14. References 1455 14.1. Normative References 1457 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1458 Requirement Levels", BCP 14, RFC 2119, 1459 DOI 10.17487/RFC2119, March 1997, 1460 . 1462 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1463 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1464 . 1466 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1467 DOI 10.17487/RFC5322, October 2008, 1468 . 1470 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1471 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 1472 . 1474 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1475 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1476 September 2009, . 1478 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1479 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1480 . 1482 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1483 Framework: Bearer Token Usage", RFC 6750, 1484 DOI 10.17487/RFC6750, October 2012, 1485 . 1487 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1488 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1489 . 1491 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1492 Interchange Format", STD 90, RFC 8259, 1493 DOI 10.17487/RFC8259, December 2017, 1494 . 1496 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1497 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1498 . 1500 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1501 Assurance 1.0", October 2019, . 1504 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1505 Rich Authorization Requests", January 2020, 1506 . 1508 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1509 Credentials Data Model 1.0", November 2019, 1510 . 1512 [JOSE_Authentication] 1513 Hardt, D., "JOSE Authentication", June 2020, 1514 . 1516 [GNAP_Advanced] 1517 Hardt, D., "The Grant Negotiation and Authorization 1518 Protocol - Advanced Features", June 2020, 1519 . 1521 14.2. Informative References 1523 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1524 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1525 October 2013, . 1527 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1528 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1529 . 1531 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1532 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1533 Application Protocol) over TCP, TLS, and WebSockets", 1534 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1535 . 1537 [browser_based_apps] 1538 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1539 Apps", September 2019, . 1542 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1543 identification and data capture techniques - QR Code bar 1544 code symbology specification", February 2015, 1545 . 1547 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 1548 . 1551 Appendix A. Document History 1553 A.1. draft-hardt-xauth-protocol-00 1555 * Initial version 1557 A.2. draft-hardt-xauth-protocol-01 1559 * text clean up 1561 * added OIDC4IA claims 1563 * added "jws" method for accessing a resource. 1565 * renamed Initiation Request -> Grant Request 1567 * renamed Initiation Response -> Interaction Response 1569 * renamed Completion Request -> Authorization Request 1571 * renamed Completion Response -> Grant Request 1573 * renamed completion handle -> authorization handle 1575 * added Authentication Request, Authentication Response, 1576 authentication handle 1578 A.3. draft-hardt-xauth-protocol-02 1580 * major rewrite 1582 * handles are now URIs 1584 * the collection of claims and authorizations are a Grant 1586 * an Authorization is its own type 1588 * lots of sequences added 1590 A.4. draft-hardt-xauth-protocol-03 1592 * fixed RO definition 1594 * improved language in Rationals 1596 * added user code interaction method, and aligned qrcode interaction 1597 method 1599 * added information_uri for code flows 1601 A.5. draft-hardt-xauth-protocol-04 1603 * renamed interaction uris to have purpose specific names 1605 A.6. draft-hardt-xauth-protocol-05 1607 * separated claims from identifiers in request user object 1609 * simplified reciprocal grant flow 1611 * reduced interactions to redirect and indirect 1613 * simplified interaction parameters 1615 * added in language for Client to verify interaction completion 1617 * added Verify Grant API and Interaction Nonce 1619 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 1620 operation. 1622 A.7. draft-hardt-xauth-protocol-06 1624 * fixup examples to match specification 1626 A.8. draft-hardt-xauth-protocol-07 1628 * refactored interaction request and response syntax, and enabled 1629 interaction mode negotiation 1631 * generation of client handle by GS for dynamic clients 1633 * renamed title to Grant Negotiation and Authorization Protocol. 1634 Preserved draft-hardt-xauth-protocol filename to ease tracking 1635 changes. 1637 * changed Authorizations to be key / value pairs (aka dictionary) 1638 instead of a JSON array 1640 A.9. draft-hardt-xauth-protocol-08 1642 * split document into three documents: core, advanced, and JOSE 1643 authentication. 1645 * grouped access granted into "access" object in Authorization JSON 1647 * added warnings object to the Grant Response JSON 1649 A.10. draft-hardt-xauth-protocol-09 1651 * added editorial note that this document should be referred to as 1652 XAuth 1654 A.11. draft-hardt-xauth-protocol-10 1656 * added example of RAR authorization request 1658 * fixed typos 1660 A.12. draft-hardt-xauth-protocol-11 1662 * renamed authorization_uri to interaction_uri to avoid confusion 1663 with AZ URI 1665 * made URI names more consistent 1667 - renamed completion_uri to information_uri 1669 - renamed redirect_uri to completion_uri 1671 - renamed interaction_uri to redirect_uri 1673 - renamed short_uri to indirect_uri 1675 * editorial fixes 1677 * renamed http verb to method 1679 * added Verify Grant and verification parameters 1681 A.13. draft-hardt-xauth-protocol-11 1683 * removed authorization object, and made authorizations object 1684 polymorphic 1686 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1688 *Changed Features* 1690 The major changes between GNAP and OAuth 2.0 and OpenID Connect are: 1692 * The Client always uses a private asymetric key to authenticate to 1693 the GS. There is no client secret. i 1695 * The Client initiates the protocol by making a signed request 1696 directly to the GS instead of redirecting the User to the GS. 1698 * The Client does not pass any parameters in redirecting the User to 1699 the GS. 1701 * The refresh_token has been replaced with a AZ URI that both 1702 represents the authorization, and is the URI for obtaining a fresh 1703 access token. 1705 * The Client can request identity claims to be returned independent 1706 of the ID Token. There is no UserInfo endpoint to query claims as 1707 there is in OpenID Connect. 1709 * The GS URI is the token endpoint. 1711 *Preserved Features* 1713 * GNAP reuses the scopes, Client IDs, and access tokens of OAuth 1714 2.0. 1716 * GNAP reuses the Client IDs, Claims and ID Token of OpenID Connect. 1718 * No change is required by the Client or the RS for accessing 1719 existing bearer token protected APIs. 1721 *New Features* 1723 * All Client calls to the GS are authenticated with asymetric 1724 cryptography 1726 * A Grant represents both the user identity claims and RS access 1727 granted to the Client. 1729 * Support for scannable code initiated interactions. 1731 * Highly extensible per Section 9. 1733 Author's Address 1735 Dick Hardt (editor) 1736 SignIn.Org 1737 United States 1739 Email: dick.hardt@gmail.com