idnits 2.17.00 (12 Aug 2021) /tmp/idnits27748/draft-hardt-xauth-protocol-07.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 87 instances of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (6 June 2020) is 714 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 923, but not defined == Unused Reference: 'RFC7516' is defined on line 2380, but no explicit reference was found in the text ** 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' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 6 June 2020 5 Expires: 8 December 2020 7 The Grant Negotiation and Authorization Protocol 8 draft-hardt-xauth-protocol-07 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 can be extended to support alternative authorizations, 21 claims, interactions, and client authentication mechanisms. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on 8 December 2020. 40 Copyright Notice 42 Copyright (c) 2020 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 47 license-info) in effect on the date of publication of this document. 48 Please review these documents carefully, as they describe your rights 49 and restrictions with respect to this document. Code Components 50 extracted from this document must include Simplified BSD License text 51 as described in Section 4.e of the Trust Legal Provisions and are 52 provided without warranty as described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 5 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. Create and Verify Grant . . . . . . . . . . . . . . . . . 8 63 2.2. Create and Read Grant - Redirect . . . . . . . . . . . . 9 64 2.3. Create and Read Grant - Indirect . . . . . . . . . . . . 10 65 2.4. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . 11 66 2.5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . 12 67 2.6. Create and Update . . . . . . . . . . . . . . . . . . . . 12 68 2.7. Create and Delete . . . . . . . . . . . . . . . . . . . . 14 69 2.8. Create, Discover, and Delete . . . . . . . . . . . . . . 16 70 2.9. Create and Wait . . . . . . . . . . . . . . . . . . . . . 16 71 2.10. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 17 72 2.11. Resource Server Access . . . . . . . . . . . . . . . . . 18 73 2.12. GS API Table . . . . . . . . . . . . . . . . . . . . . . 19 74 3. Grant and AuthZ Life Cycle . . . . . . . . . . . . . . . . . 19 75 4. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 4.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 20 77 4.2. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 23 78 4.3. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 24 79 4.4. Update Grant . . . . . . . . . . . . . . . . . . . . . . 24 80 4.5. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 25 81 4.6. Request JSON . . . . . . . . . . . . . . . . . . . . . . 25 82 4.6.1. "client" Object . . . . . . . . . . . . . . . . . . . 25 83 4.6.2. "interaction" Object . . . . . . . . . . . . . . . . 26 84 4.6.3. "user" Object . . . . . . . . . . . . . . . . . . . . 26 85 4.6.4. "authorization" Object . . . . . . . . . . . . . . . 27 86 4.6.5. "authorizations" Object . . . . . . . . . . . . . . . 27 87 4.6.6. "claims" Object . . . . . . . . . . . . . . . . . . . 27 88 4.6.7. "verification" Object . . . . . . . . . . . . . . . . 28 89 4.7. Read Authorization . . . . . . . . . . . . . . . . . . . 28 90 4.8. Update Authorization . . . . . . . . . . . . . . . . . . 28 91 4.9. Delete Authorization . . . . . . . . . . . . . . . . . . 29 92 4.10. GS Options . . . . . . . . . . . . . . . . . . . . . . . 29 93 4.11. Grant Options . . . . . . . . . . . . . . . . . . . . . . 30 94 4.12. AuthZ Options . . . . . . . . . . . . . . . . . . . . . . 30 95 4.13. Request Verification . . . . . . . . . . . . . . . . . . 30 96 5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 31 97 6. GS Responses . . . . . . . . . . . . . . . . . . . . . . . . 31 98 6.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 31 99 6.2. Interaction Response . . . . . . . . . . . . . . . . . . 32 100 6.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 33 101 6.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 34 102 6.4.1. "client" Object . . . . . . . . . . . . . . . . . . . 34 103 6.4.2. "interaction" Object . . . . . . . . . . . . . . . . 34 104 6.4.3. "user" Object . . . . . . . . . . . . . . . . . . . . 34 105 6.4.4. "authorization" Object . . . . . . . . . . . . . . . 34 106 6.4.5. "authorizations" Object . . . . . . . . . . . . . . . 34 107 6.4.6. "claims" Object . . . . . . . . . . . . . . . . . . . 35 108 6.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 35 109 6.5.1. Signing and Encryption . . . . . . . . . . . . . . . 36 110 6.6. Response Verification . . . . . . . . . . . . . . . . . . 36 111 7. interaction mode Objects . . . . . . . . . . . . . . . . . . 36 112 7.1. "redirect" mode . . . . . . . . . . . . . . . . . . . . . 37 113 7.1.1. request "interaction" object contains: . . . . . . . 37 114 7.1.2. response "interaction" object contains: . . . . . . . 37 115 7.2. "indirect" mode . . . . . . . . . . . . . . . . . . . . . 37 116 7.2.1. request "interaction" object contains: . . . . . . . 37 117 7.2.2. response "interaction" object contains: . . . . . . . 37 118 7.3. "user_code" mode . . . . . . . . . . . . . . . . . . . . 37 119 7.3.1. request "interaction" object contains: . . . . . . . 38 120 7.3.2. response "interaction" object contains: . . . . . . . 38 121 8. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 38 122 8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 38 123 9. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 38 124 10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 38 125 10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 39 126 10.1.1. Authorization Header . . . . . . . . . . . . . . . . 40 127 10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 41 128 10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 42 129 10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 42 130 10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 43 131 10.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 43 132 10.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . 44 133 10.2.4. Public Key Resolution . . . . . . . . . . . . . . . 45 134 10.3. Request Encryption . . . . . . . . . . . . . . . . . . . 45 135 10.4. Response Signing . . . . . . . . . . . . . . . . . . . . 45 136 10.5. Response Encryption . . . . . . . . . . . . . . . . . . 46 137 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46 138 12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 47 139 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 51 140 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 141 15. Security Considerations . . . . . . . . . . . . . . . . . . . 51 142 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 143 16.1. Normative References . . . . . . . . . . . . . . . . . . 51 144 16.2. Informative References . . . . . . . . . . . . . . . . . 53 146 Appendix A. Document History . . . . . . . . . . . . . . . . . . 54 147 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 54 148 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 54 149 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 55 150 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 55 151 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 55 152 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 55 153 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 55 154 A.8. draft-hardt-xauth-protocol-07 . . . . . . . . . . . . . . 56 155 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 56 156 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57 158 1. Introduction 160 This protocol supports the widely deployed use cases supported by 161 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 162 extension of OAuth 2.0, as well as other extensions, and other use 163 cases that are not supported, such as acquiring multiple access 164 tokens at the same time, and updating the request during user 165 interaction. This protocol also addresses many of the security 166 issues in OAuth 2.0 by having parameters securely sent directly 167 between parties, rather than via a browser redirection. 169 The technology landscape has changed since OAuth 2.0 was initially 170 drafted. More interactions happen on mobile devices than PCs. 171 Modern browsers now directly support asymetric cryptographic 172 functions. Standards have emerged for signing and encrypting tokens 173 with rich payloads (JOSE) that are widely deployed. 175 Additional use cases are now being served with extensions to OAuth 176 2.0: OpenID Connect added support for authentication and releasing 177 identity claims; [RFC8252] added support for native apps; [RFC8628] 178 added support for smart devices; and support for [browser_based_apps] 179 is being worked on. There are numerous efforts on adding proof-of- 180 possession to resource access. 182 This protocol simplifies the overall architectural model, takes 183 advantage of today's technology landscape, provides support for all 184 the widely deployed use cases, and offers numerous extension points. 186 While this protocol is not backwards compatible with OAuth 2.0, it 187 strives to minimize the migration effort. 189 This protocol centers around a Grant, a representation of the 190 collection of user identity claims and/or resource authorizations the 191 Client is requesting, and the resulting identity claims and/or 192 resource authorizations granted by the Grant Server. 194 [Editor: suggestions on how to improve this are welcome!] 196 [Editor: suggestions for other names than XAuth are welcome!] 198 1.1. Parties 200 The parties and their relationships to each other: 202 +--------+ +------------+ 203 | User | | Resource | 204 | | | Owner (RO) | 205 +--------+ +------------+ 206 | \ / | 207 | \ / | 208 | \ / | 209 | \ / | 210 +--------+ +---------------+ +------------+ 211 | Client |---->| Grant | _ _ | Resource | 212 | |<----| Server (GS) | | Server | 213 | | +---------------+ | (RS) | 214 | |-------------------------->| | 215 | |<--------------------------| | 216 +--------+ +------------+ 218 * *User* - the person interacting with the Client who has delegated 219 access to identity claims about themselves to the Grant Server 220 (GS), and can authenticate at the GS. 222 * *Client* - requests a Grant from the GS to access one or more 223 Resource Servers (RSs), and/or identity claims about the User. 224 The Client can create, verify, retrieve, update, and delete a 225 Grant. When a Grant is created, the Client receives from the GS 226 the granted access token(s) for the RS(s), and identity claims 227 about the User. The Client uses an access token to access the RS. 228 There are two types of Clients: Registered Clients and Dynamic 229 Clients. All Clients have a key to authenticate with the Grant 230 Server. 232 * *Registered Client* - a Client that has registered with the GS and 233 has a Client ID to identify itself, and can prove it possesses a 234 key that is linked to the Client ID. The GS may have different 235 policies for what different Registered Clients can request. A 236 Registered Client MAY be interacting with a User. 238 * *Dynamic Client* - a Client that has not been registered with the 239 GS, and each instance will generate it's own key pair so it can 240 prove it is the same instance of the Client on subsequent 241 requests, and to requests of a Resource Server that require proof- 242 of-possession access. A single-page application with no active 243 server component is an example of a Dynamic Client. A Dynamic 244 Client MUST be interacting with a User. 246 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 247 release of identity claims about the User. The GS may require 248 explicit consent from the RO or User to provide these to the 249 Client. A GS may support Registered Clients and/or Dynamic 250 Clients. The GS is a combination of the Authorization Server (AS) 251 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 253 * *Resource Server* (RS) - has API resources that require an access 254 token from the GS. Some, or all of the resources are owned by the 255 Resource Owner. 257 * *Resource Owner* (RO) - owns resources at the RS, and has 258 delegated RS access management to the GS. The RO may be the same 259 entity as the User, or may be a different entity that the GS 260 interacts with independently. GS and RO interactions are out of 261 scope of this document. 263 1.2. Reused Terms 265 * *access token* - an access token as defined in [RFC6749] 266 Section 1.4. 268 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 269 issued by the GS, or by other issuers. 271 * *Client ID* - a GS unique identifier for a Registered Client as 272 defined in [RFC6749] Section 2.2. 274 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 276 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 278 * *authN* - short for authentication. 280 * *authZ* - short for authorization. 282 1.3. New Terms 284 * *GS URI* - the endpoint at the GS the Client calls to create a 285 Grant, and is the unique identifier for the GS. 287 * *Grant* - the user identity claims and/or RS authorizations the GS 288 has granted to the Client. 290 * *Grant URI* - the URI that represents the Grant. The Grant URI 291 MUST start with the GS URI. 293 * *Authorization* - the access granted by the RO to the Client. 294 Contains an access token. 296 * *Authorization URI* (AZ URI) - the URI that represents the 297 Authorization the Client was granted by the RO. The AZ URI MUST 298 start with the GS URI. The AZ URI is used to read, update, and 299 delete an access token. 301 * *Interaction* - how the Client directs the User to interact with 302 the GS. This document defines the interaction modes redirect, 303 indirect, and user_code in Section 7 305 * *Client Handle* - a GS unique identifier for a Dynamic Client for 306 the Dynamic Client to refer to itself in subsequent requests. 308 1.4. Notational Conventions 310 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 311 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 312 specification are to be interpreted as described in [RFC2119]. 314 Certain security-related terms are to be understood in the sense 315 defined in [RFC4949]. These terms include, but are not limited to, 316 "attack", "authentication", "authorization", "certificate", 317 "confidentiality", "credential", "encryption", "identity", "sign", 318 "signature", "trust", "validate", and "verify". 320 Unless otherwise noted, all the protocol parameter names and values 321 are case sensitive. 323 Some protocol parameters are parts of a JSON document, and are 324 referred to in JavaScript notation. For example, foo.bar refers to 325 the "bar" boolean attribute in the "foo" object in the following 326 example JSON document: 328 { 329 "foo" : { 330 "bar": true 331 } 332 } 334 2. Sequences 336 Before any sequence, the Client needs to be manually or 337 programmatically configured for the GS. See GS Options Section 4.10 338 for details on acquiring GS metadata. 340 [Editor: a plethora of sequences are included to illustrate all the 341 different use cases that are supported. Many sequences are similar, 342 and show a slightly different sequence that can support different use 343 cases. These could potentially be moved to a use case document in 344 the future.] 346 2.1. Create and Verify Grant 348 A Dynamic Client wants a Grant from the User using a Redirect 349 Interaction: 351 +--------+ +-------+ 352 | Client | | GS | 353 | |--(1)--- Create Grant ----------->| | 354 | | | | 355 | |<--- Interaction Response ---(2)--| | +------+ 356 | | | | | User | 357 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 358 | | | | | | 359 | | | |<--(4)-->| | 360 | | | | authN | | 361 | | | |<--(5)-->| | 362 | | | | authZ | | 363 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 364 | | | | | | 365 | |--(7)--- Verify Grant ----------->| | +------+ 366 | | | | 367 | |<--------- Grant Response ---(8)--| | 368 | | | | 369 +--------+ +-------+ 371 1. *Create Grant* The Client creates a Request JSON document 372 Section 4.6 and makes a Create Grant request (Section 4.1) by 373 sending the JSON with an HTTP POST to the GS URI. 375 2. *Interaction Response* The GS determines that interaction with 376 the User is required and sends an Interaction Response 377 (Section 6.2) containing the Grant URI and an interaction object. 379 3. *Interaction Transfer* The Client redirects the User to the 380 Redirect URI at the GS. 382 4. *User Authentication* The GS authenticates the User. 384 5. *User Authorization* If required, the GS interacts with the User 385 to determine which identity claims and/or authorizations in the 386 Grant Request are to be granted. 388 6. *Interaction Transfer* The GS redirects the User to the 389 Completion URI at the Client, passing an Interaction Nonce. 391 7. *Read Grant* The Client creates a JSON document containing a 392 verification object Section 4.6.7 and does a Verify Grant 393 Section 4.2 request by HTTP PATCH with the document to the Grant 394 URI. 396 8. *Grant Response* The GS responds with a Grant Response 397 (Section 6.1). 399 2.2. Create and Read Grant - Redirect 401 A Registered Client wants a Grant from the User using a Redirect 402 Interaction: 404 +--------+ +-------+ 405 | Client | | GS | 406 | |--(1)--- Create Grant ----------->| | 407 | | | | 408 | |<--- Interaction Response ---(2)--| | 409 | | | | 410 | |--(3)--- Read Grant ------------->| | +------+ 411 | | | | | User | 412 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 413 | | | | | | 414 | | | |<--(5)-->| | 415 | | | | authN | | 416 | | | |<--(6)-->| | 417 | | | | authZ | | 418 | |<--------- Grant Response ---(7)--| | | | 419 | | | | | | 420 | |<--- Interaction Transfer ---(8)- | - - - | --------| | 421 | | | | | | 422 +--------+ +-------+ +------+ 424 1. *Create Grant* The Client makes a Create Grant request 425 (Section 4.1) to the GS URI. 427 2. *Interaction Response* The GS determines that interaction with 428 the User is required and sends an Interaction Response 429 (Section 6.2) containing the Grant URI and an interaction object. 431 3. *Read Grant* The Client does an HTTP GET of the Grant URI 432 (Section 4.3). 434 4. *Interaction Transfer* The Client transfers User interaction to 435 the GS. 437 5. *User Authentication* The GS authenticates the User. 439 6. *User Authorization* If required, the GS interacts with the User 440 to determine which identity claims and/or authorizations in the 441 Grant Request are to be granted. 443 7. *Grant Response* The GS responds with a Grant Response 444 (Section 6.1). 446 8. *Interaction Transfer* The GS redirects the User to the 447 Completion URI of the Client. The Client verifies it is the same 448 User that it transferred to the GS. 450 2.3. Create and Read Grant - Indirect 452 A Registered Client wants a Grant from the User using an Indirect 453 Interaction: 455 +--------+ +-------+ 456 | Client | | GS | 457 | |--(1)--- Create Grant ----------->| | 458 | | | | 459 | |<--- Interaction Response ---(2)--| | 460 | | | | 461 | |--(3)--- Read Grant ------------->| | +------+ 462 | | | | | User | 463 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 464 | | | | | | 465 | | | |<--(5)-->| | 466 | | | | authN | | 467 | | | |<--(6)-->| | 468 | | | | authZ | | 469 | |<--------- Grant Response ---(7)--| | | | 470 +--------+ | | | | 471 | | | | 472 +--------+ | | | | 473 | Info |<--- Interaction Transfer ---(8)- | - - - | --------| | 474 | Server | | | | | 475 +--------+ +-------+ +------+ 477 The sequence is the same except: 479 * In step (4) the User either scans a bar code or uses a separate 480 device to navigate to the Code URI and enters the User Code. 482 * In step (8) the GS redirects the User to the Information URI 483 provided by the Client. 485 2.4. Reciprocal Grant 487 Party A and Party B are both a Client and a GS, and each Client would 488 like a Grant for the other GS. The sequence starts off the same as 489 in Section 2.2, but Party B makes a Create Grant Request before 490 sending a Grant Response: 492 Party A Party B 493 +--------+ +--------+ 494 | Client | | GS | 495 ~ ~ ~ ~ ~ ~ Same as steps 1 - 6 of ~ ~ ~ ~ ~ ~ 496 +------+ | | Create and Read Grant above | | 497 | User | | | | | 498 | | | GS |<--------- Create Grant ---(1)---| Client | 499 | | | | | | 500 | | | |<------- Grant Response ---(2)---| | 501 | | | | | | 502 | |<----- | - - - | -- Interaction Transfer --(3)---| | 503 | | | | | | 504 | |<-(4)->| | | | 505 | | AuthZ | | | | 506 +------+ | GS |--(5)--- Grant Response -------->| Client | 507 | | | | 508 +--------+ +--------+ 510 1. *Create Grant* Party B creates a Grant Request (Section 4.1) with 511 user.reciprocal set to the Party B Grant URI that will be in the 512 step (2) Grant Response, and sends it with an HTTP POST to the 513 Party A GS URI. This enables Party A to link the reciprocal 514 Grants. 516 2. *Grant Response* Party B responds to Party A's Create Grant 517 Request with a Grant Response that includes the Party B Grant 518 URI. 520 3. *Interaction Transfer* Party B redirects the User to the 521 Completion URI at Party A. 523 4. *User Authorization* If required, Party A interacts with the User 524 to determine which identity claims and/or authorizations in Party 525 B's Create Grant Request are to be granted. 527 5. *Grant Response* Party A responds with a Grant Response 528 (Section 6.1). 530 2.5. GS Initiated Grant 532 The User is at the GS, and wants to interact with a Registered 533 Client. The GS can redirect the User to the Client: 535 +--------+ +-------+ +------+ 536 | Client | | GS | | User | 537 | | | |<--(1)-->| | 538 | | | | | | 539 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 540 | (3) | | | | | 541 | verify |--(4)--- Read Grant ------------->| | +------+ 542 | | | | 543 | |<--------- Grant Response --(5)---| | 544 | | | | 545 +--------+ +-------+ 547 1. *User Interaction* The GS interacts with the User to determine 548 the Client and what identity claims and authorizations to 549 provide. The GS creates a Grant and corresponding Grant URI. 551 2. *GS Initiated Redirect* The GS redirects the User to the Client's 552 interaction_uri, adding a query parameter with the name "Grant 553 URI" and the value being the URL encoded Grant URI. 555 3. *Client Verification* The Client verifies the Grant URI is from 556 an GS the Client trusts, and starts with the GS GS URI. 558 4. *Read Grant* The Client does an HTTP GET of the Grant URI 559 (Section 4.3). 561 5. *Grant Response* The GS responds with a Grant Response 562 (Section 6.1). 564 See Section 5 for more details. 566 2.6. Create and Update 568 The Client requests an identity claim to determine who the User is. 569 Once the Client learns who the User is, and the Client updates the 570 Grant for additional identity claims which the GS prompts the User 571 for and returns to the Client. Once those are received, the Client 572 updates the Grant with the remaining identity claims required. 574 +--------+ +-------+ 575 | Client | | GS | 576 | |--(1)--- Create Grant ----------->| | 577 | | interaction.keep:true | | 578 | | | | 579 | |<--- Interaction Response ---(2)--| | 580 | | | | 581 | |--(3)--- Read Grant ------------->| | +------+ 582 | | | | | User | 583 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 584 | | | | | | 585 | | | |<--(5)-->| | 586 | | | | authN | | 587 | |<--------- Grant Response ---(6)--| | | | 588 | (7) | | | | | 589 | eval |--(8)--- Update Grant ----------->| | | | 590 | | interaction.keep:true | |<--(9)-->| | 591 | | | | authZ | | 592 | |<--------- Grant Response --(10)--| | | | 593 | (11) | | | | | 594 | eval |--(12)-- Update Grant ----------->| | | | 595 | | interaction.keep:false | |<--(13)->| | 596 | | | | authZ | | 597 | | | | | | 598 | |<--- Interaction Transfer --(14)- | - - - | --------| | 599 | | | | | | 600 | |<--------- Grant Response --(15)--| | +------+ 601 | | | | 602 +--------+ +-------+ 604 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 605 including an identity claim and interaction.keep:true, and sends 606 it with an HTTP POST to the GS GS URI. 608 2. *Interaction Response* The GS sends an Interaction Response 609 (Section 6.2) containing the Grant URI, an interaction object, 610 and interaction.keep:true. 612 3. *Read Grant* The Client does an HTTP GET of the Grant URI 613 (Section 4.3). 615 4. *Interaction Transfer* The Client transfers User interaction to 616 the GS. 618 5. *User Authentication* The GS authenticates the User. 620 6. *Grant Response* The GS responds with a Grant Response 621 (Section 6.1) including the identity claim from User 622 authentication and interaction.keep:true. 624 7. *Grant Evaluation* The Client queries its User database and does 625 not find a User record matching the identity claim. 627 8. *Update Grant* The Client creates an Update Grant Request 628 (Section 4.4) including the initial identity claims required and 629 interaction.keep:true, and sends it with an HTTP PUT to the 630 Grant URI. 632 9. *User AuthN* The GS interacts with the User to determine which 633 identity claims in the Update Grant Request are to be granted. 635 10. *Grant Response* The GS responds with a Grant Response 636 (Section 6.1) including the identity claims released by the User 637 and interaction.keep:true. 639 11. *Grant Evaluation* The Client evaluates the identity claims in 640 the Grant Response and determines the remaining User identity 641 claim required. 643 12. *Update Grant* The Client creates an Update Grant Request 644 (Section 4.4) including the remaining required identity claims 645 and interaction.keep:false, and sends it with an HTTP PUT to the 646 Grant URI. 648 13. *User AuthZ* The GS interacts with the User to determine which 649 identity claims in the Update Grant Request are to be granted. 651 14. *Interaction Transfer* The GS transfers User interaction to the 652 Client. 654 15. *Grant Response* The GS responds with a Grant Response 655 (Section 6.1) including the identity claims released by the 656 User. 658 2.7. Create and Delete 660 The Client requests an identity claim to determine who the User is. 661 Once the Client learns who the User is, and the Client knows it 662 already has all the identity claims and authorizations needed for the 663 User, the Client deletes the Grant which prompts the GS to transfer 664 the interaction back to the Client. (If the Client did not already 665 have what was needed, the Client would follow the Create and Update 666 sequence Section 2.6 ) 667 +--------+ +-------+ 668 | Client | | GS | 669 | |--(1)--- Create Grant ----------->| | 670 | | interaction.keep:true | | 671 | | | | 672 | |<--- Interaction Response ---(2)--| | 673 | | | | 674 | |--(3)--- Read Grant ------------->| | +------+ 675 | | | | | User | 676 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 677 | | | | | | 678 | | | |<--(5)-->| | 679 | | | | authN | | 680 | |<--------- Grant Response ---(6)--| | | | 681 | (7) | | | | | 682 | eval |--(8)--- Delete Grant ----------->| | | | 683 | |<------- Delete Response ---------| | | | 684 | | | | | | 685 | |<--- Interaction Transfer ---(9)- | - - - | --------| | 686 | | | | | | 687 +--------+ +-------+ +------+ 689 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 690 including an identity claim and interaction.keep:true, and sends 691 it with an HTTP POST to the GS GS URI. 693 2. *Interaction Response* The GS sends an Interaction Response 694 (Section 6.2) containing the Grant URI, an interaction object, 695 and interaction.keep:true. 697 3. *Read Grant* The Client does an HTTP GET of the Grant URI 698 (Section 4.3). 700 4. *Interaction Transfer* The Client transfers User interaction to 701 the GS. 703 5. *User Authentication* The GS authenticates the User. 705 6. *Grant Response* The GS responds with a Grant Response 706 (Section 6.1) including the identity claim from User 707 authentication and interaction.keep:true. 709 7. *Grant Evaluation* The Client queries its User database and finds 710 the User record matching the identity claim, and that no 711 additional claims or authorizations are required. 713 8. *Delete Grant* The Client no longer needs the Grant and decides 714 to Delete Grant (Section 4.5) by sending an HTTP DELETE to the 715 Grant URI. If the GS responds with success the Grant no longer 716 exists. 718 2.8. Create, Discover, and Delete 720 The Client wants to discover if the GS has a User with a given 721 identifier. If not, it will abort the request and not transfer 722 interaction to the GS. 724 +--------+ +-------+ 725 | Client | | GS | 726 | |--(1)--- Create Grant ----------->| | 727 | | user.exists:true | | 728 | | | | 729 | |<--- Interaction Response ---(2)--| | 730 | | user.exists:false | | 731 | | | | 732 | |--(3)--- Delete Grant ----------->| | 733 | |<------- Delete Response ---------| | 734 | | | | 735 +--------+ +-------+ 737 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 738 including an identity claim request, a User identifier, and 739 user.exists:true. The Client sends it with an HTTP POST to the 740 GS GS URI. 742 2. *Interaction Response* The GS sends an Interaction Response 743 (Section 6.2) containing the Grant URI, an interaction object, 744 and user.exists:false. 746 3. *Delete Grant* The Client determines the GS cannot fulfil its 747 Grant Request, and decides to Delete Grant (Section 4.5) by 748 sending an HTTP DELETE to the Grant URI. If the GS responds with 749 success the Grant no longer exists. 751 2.9. Create and Wait 753 The Client wants access to resources that require the GS to interact 754 with the RO, which may not happen immediately, so the GS instructs 755 the Client to wait and check back later. 757 +--------+ +-------+ 758 | Client | | GS | 759 | |--(1)--- Create Grant ----------->| | 760 | | | | 761 | |<---------- Wait Response ---(2)--| | +------+ 762 | (3) | | | | RO | 763 | Wait | | |<--(4)-->| | 764 | | | | AuthZ | | 765 | |--(5)--- Read Grant ------------->| | +------+ 766 | | | | 767 | |<--------- Grant Response --(6)---| | 768 | | | | 769 +--------+ +-------+ 771 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 772 and sends it with an HTTP POST to the GS GS URI. 774 2. *Wait Response* The GS sends an Interaction Response 775 (Section 6.3) containing the Grant URI and wait time. 777 3. *Client Waits* The Client waits the wait time. 779 4. *RO AuthZ* The GS interacts with the RO to determine which 780 identity claims in the Grant Request are to be granted. 782 5. *Read Grant* The Client does an HTTP GET of the Grant URI 783 (Section 4.3). 785 6. *Grant Response* The GS responds with a Grant Response 786 (Section 6.1). 788 2.10. Read Grant 790 The Client wants to re-acquire the identity claims and authorizations 791 in the Grant. No User or RO interaction is required as no new 792 consent or authorization is required. 794 +--------+ +-------+ 795 | Client | | GS | 796 | |--(1)--- Read Grant ------------->| | 797 | | | | 798 | |<--------- Grant Response --(2)---| | 799 | | | | 800 +--------+ +-------+ 802 1. *Read Grant* The Client does an HTTP GET of the Grant URI 803 (Section 4.3). 805 2. *Grant Response* The GS responds with a Grant Response 806 (Section 6.1) containing updated identity claims and 807 authorizations. 809 2.11. Resource Server Access 811 The Client received an AZ URI from the GS. The Client acquires an 812 access token, calls the RS, and later the access token expires. The 813 Client then gets a fresh access token. 815 +--------+ +-------+ 816 | Client | | GS | 817 | |--(1)--- Read AuthZ ---------------------->| | 818 | |<------- AuthZ Response -------------------| | 819 | | | | 820 | | +----------+ | | 821 | | | Resource | | | 822 | |--(2)--- Access Resource --->| Server | | | 823 | |<------- Resource Response --| (RS) | | | 824 | | | | | | 825 | |--(3)--- Access Resource --->| | | | 826 | |<------- Error Response -----| | | | 827 | | | | | | 828 | | +----------+ | | 829 | | | | 830 | |--(4)--- Read AuthZ ---------------------->| | 831 | |<------- AuthZ Response -------------------| | 832 | | | | 833 +--------+ +-------+ 835 1. *Read AuthZ* The Client makes a Read AuthZ (Section 4.7) with an 836 HTTP GET to the AZ URI and receives an Response JSON 837 "authorization" object (Section 6.4.4) with a fresh access token. 839 2. *Resource Request* The Client accesses the RS with the access 840 token per Section 8 and receives a response from the RS. 842 3. *Resource Request* The Client attempts to access the RS, but 843 receives an error indicating the access token has expired. 845 4. *Read AuthZ* The Client makes another Read AuthZ (Section 4.7) 846 with an HTTP GET to the AZ URI and receives an Response JSON 847 "authorization" object (Section 6.4.4) with a fresh access token. 849 2.12. GS API Table 851 +--------------+-----------+--------+-----------------------------+ 852 | request | http verb | uri | response | 853 +==============+===========+========+=============================+ 854 | Create Grant | POST | GS URI | interaction, wait, or grant | 855 +--------------+-----------+--------+-----------------------------+ 856 | Verify Grant | PATCH | Grant | grant | 857 | | | URI | | 858 +--------------+-----------+--------+-----------------------------+ 859 | Read Grant | GET | Grant | wait, or grant | 860 | | | URI | | 861 +--------------+-----------+--------+-----------------------------+ 862 | Update Grant | PUT | Grant | interaction, wait, or grant | 863 | | | URI | | 864 +--------------+-----------+--------+-----------------------------+ 865 | Delete Grant | DELETE | Grant | success | 866 | | | URI | | 867 +--------------+-----------+--------+-----------------------------+ 868 | Read AuthZ | GET | AZ URI | authorization | 869 +--------------+-----------+--------+-----------------------------+ 870 | Update AuthZ | PUT | AZ URI | authorization | 871 +--------------+-----------+--------+-----------------------------+ 872 | Delete AuthZ | DELETE | AZ URI | success | 873 +--------------+-----------+--------+-----------------------------+ 874 | GS Options | OPTIONS | GS URI | metadata | 875 +--------------+-----------+--------+-----------------------------+ 876 | Grant | OPTIONS | Grant | metadata | 877 | Options | | URI | | 878 +--------------+-----------+--------+-----------------------------+ 879 | AuthZ | OPTIONS | AZ URI | metadata | 880 | Options | | | | 881 +--------------+-----------+--------+-----------------------------+ 883 Table 1 885 [ Editor: is there value in an API for listing a Client's Grants? 886 eg:] 888 List Grants GET GS URI JSON array of Grant URIs 890 3. Grant and AuthZ Life Cycle 892 [Editor: straw man for life cycles.] 894 *Grant life Cycle* 895 The Client MAY create, read, update, and delete Grants. A Grant 896 persists until it has expired, is deleted, or another Grant is 897 created for the same GS, Client, and User tuple. 899 At any point in time, there can only be one Grant for the GS, Client, 900 and User tuple. When a Client creates a Grant at the same GS for the 901 same User, the GS MUST invalidate a previous Grant for the Client at 902 that GS for that User. 904 *Authorization Life Cycle* 906 An Authorization are represented by an AZ URI and are MAY be included 907 in a Grant Response "authorization" Object (Section 6.4.4) or as a 908 member of the Grant Response "authorizations" list. If a Client 909 receives an Authorization, the Client MUST be able to do a Read AuthZ 910 request Section 4.7, and MAY be able to update Section 4.8 and delete 911 Section 4.9 depending on GS policy. 913 An Authorization will persist independent of the Grant, and persist 914 until invalidated by the GS per GS policy, or deleted by the Client. 916 4. GS APIs 918 *Client Authentication* 920 All APIs except for GS Options require the Client to authenticate. 922 This document defines the JOSE Authentication mechanism in 923 Section 10. Other mechanisms include [TBD]. 925 4.1. Create Grant 927 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 928 document to the GS URI. 930 The JSON document MUST include the following from the Request JSON 931 Section 4.6: 933 * iat 935 * nonce 937 * uri set to the GS URI 939 * client 941 and MAY include the following from Request JSON Section 4.6 942 * user 944 * interaction 946 * authorization or authorizations 948 * claims 950 The GS MUST respond with one of Grant Response Section 6.1, 951 Interaction Response Section 6.2, Wait Response Section 6.3, or one 952 of the following errors: 954 * TBD 956 from Error Responses Section 9. 958 Following is a non-normative example where the Client is requesting 959 identity claims about the User and read access to the User's 960 contacts: 962 Example 1 964 { 965 "iat" : 15790460234, 966 "uri" : "https://as.example/endpoint", 967 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 968 "client": { 969 "display": { 970 "name" : "SPA Display Name", 971 "uri" : "https://spa.example/about" 972 } 973 }, 974 "interaction": { 975 "redirect": { 976 "redirect_uri" : "https://web.example/return" 977 }, 978 "global" : { 979 "ui_locals" : "de" 980 } 981 }, 982 "authorization": { 983 "type" : "oauth_scope", 984 "scope" : "read_contacts" 985 }, 986 "claims": { 987 "oidc": { 988 "id_token" : { 989 "email" : { "essential" : true }, 990 "email_verified" : { "essential" : true } 991 }, 992 "userinfo" : { 993 "name" : { "essential" : true }, 994 "picture" : null 995 } 996 } 997 } 998 } 1000 Following is a non-normative example where the Client is requesting 1001 the GS to keep the interaction with the User after returning the ID 1002 Token so the Client can update the Grant, and is also asking if the 1003 user exists: 1005 Example 2 1007 { 1008 "iat" : 15790460234, 1009 "uri" : "https://as.example/endpoint", 1010 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1011 "client": { 1012 "id" : "di3872h34dkJW" 1013 }, 1014 "interaction": { 1015 "indirect": { 1016 "completion_uri": "https://device.example/completion" 1017 }, 1018 "user_code": { 1019 "completion_uri": "https://device.example/completion" 1020 } 1021 }, 1022 "user": { 1023 "identifiers": { 1024 "email" : "jane.doe@example.com" 1025 }, 1026 "exists" : true 1027 }, 1028 "claims" : { "oidc": { "id_token" : {} } } 1029 } 1031 4.2. Verify Grant 1033 The Client verifies a Grant by doing an HTTP PATCH of a JSON document 1034 to the corresponding Grant URI. 1036 The JSON document MUST contain verification.nonce per Section 4.6.7. 1037 Following is a non-normative example: 1039 { 1040 "verification": { "nonce":"55e8a90f-a563-426d-8c35-d6d8ed54afeb" } 1041 } 1043 The GS MUST respond with one of Grant Response Section 6.1 or one of 1044 the following errors: 1046 * TBD 1048 from Error Responses Section 9. 1050 4.3. Read Grant 1052 The Client reads a Grant by doing an HTTP GET of the corresponding 1053 Grant URI. 1055 The GS MUST respond with one of Grant Response Section 6.1, Wait 1056 Response Section 6.3, or one of the following errors: 1058 * TBD 1060 from Error Responses Section 9. 1062 4.4. Update Grant 1064 The Client updates a Grant by doing an HTTP PUT of a JSON document to 1065 the corresponding Grant URI. 1067 The JSON document MUST include the following from the Request JSON 1068 Section 4.6 1070 * iat 1072 * uri set to the Grant URI 1074 and MAY include the following from Request JSON Section 4.6 1076 * user 1078 * interaction 1080 * authorization or authorizations 1082 * claims 1084 The GS MUST respond with one of Grant Response Section 6.1, 1085 Interaction Response Section 6.2, Wait Response Section 6.3, or one 1086 of the following errors: 1088 * TBD 1090 from Error Responses Section 9. 1092 Following is a non-normative example where the Client made an 1093 interaction.keep:true request, and now wants to update the request 1094 with additional claims: 1096 Example 3 1098 { 1099 "iat" : 15790460234, 1100 "uri" : "https://as.example/endpoint/grant/example3", 1101 "claims": { 1102 "oidc": { 1103 "userinfo" : { 1104 "email" : { "essential" : true }, 1105 "name" : { "essential" : true }, 1106 "picture" : null 1107 } 1108 } 1109 } 1110 } 1112 4.5. Delete Grant 1114 The Client deletes a Grant by doing an HTTP DELETE of the 1115 corresponding Grant URI. 1117 The GS MUST respond with OK 200, or one of the following errors: 1119 * TBD 1121 from Error Responses Section 9. 1123 4.6. Request JSON 1125 [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ] 1127 * *iat* - the time of the request as a NumericDate. 1129 * *nonce* - a unique identifier for this request. Note the Grant 1130 Response MUST contain a matching nonce attribute value. 1132 * *uri* - the GS URI if in a Create Grant Section 4.1, or the Grant 1133 URI if in an Update Grant Section 4.4. 1135 4.6.1. "client" Object 1137 The client object MUST contain one of: the "id" attribute for a 1138 Registered Client, the "handle" attribute for a Dynamic Client, or 1139 the "display" object for Dynamic Clients. 1141 * *id* - the Client ID the GS has for a Registered Client. 1143 * *handle* = the Client Handle the GS previously provided a Dynamic 1144 Client 1146 * *display* - the display object contains the following attributes: 1148 - *name* - a string that represents the Dynamic Client 1150 - *uri* - a URI representing the Dynamic Client 1152 The name and uri will be displayed by the GS when prompting for 1153 authorization. 1155 [Editor: a max length for the name and URI so a GS can reserve 1156 appropriate space?] 1158 4.6.2. "interaction" Object 1160 The interaction object contains one or more interaction mode objects 1161 per Section 7 representing the interactions the Client is willing to 1162 provide the User. In addition to the interaction mode objects, the 1163 interaction object may contain the "global" object; 1165 * *global* - and optional object containing parameters that are 1166 applicable for all types of interactions. Only one attribute is 1167 defined in this document: 1169 - *ui_locales* - End-User's preferred languages and scripts for 1170 the user interface, represented as a space-separated list of 1171 [RFC5646] language tag values, ordered by preference. This 1172 attribute is OPTIONAL. 1174 [Editor: why is this not a JSON array? Why space-separated?] 1176 4.6.3. "user" Object 1178 * *exists* - if present, MUST contain the JSON true value. 1179 Indicates the Client requests the GS to return a user.exists value 1180 in an Interaction Response Section 6.2. This attribute is 1181 OPTIONAL, and MAY be ignored by the GS. 1183 * *identifiers* - REQUIRED if the exists attribute is present. The 1184 values MAY be used by the GS to improve the User experience. 1185 Contains one or more of the following identifiers for the User: 1187 - *phone_number* - contains a phone number per Section 5 of 1188 [RFC3966]. 1190 - *email* - contains an email address per [RFC5322]. 1192 - *oidc* - is an object containing both the "iss" and "sub" 1193 attributes from an OpenID Connect ID Token [OIDC] Section 2. 1195 * *claims* - an optional object containing one or more assertions 1196 the Client has about the User. 1198 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 1199 Section 2. 1201 * *reciprocal* - indicates this Grant Request or Update is the 1202 reciprocal of another Grant. Contains the Grant URI of the 1203 reciprocal Grant. 1205 4.6.4. "authorization" Object 1207 * *type* - one of the following values: "oauth_scope" or 1208 "oauth_rich". This attribute is REQUIRED. 1210 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1211 section 3.3. MUST be included if type is "oauth_scope" or 1212 "oauth_rich". 1214 * *authorization_details* - an authorization_details object per 1215 [RAR]. MUST be included if type is "oauth_rich". 1217 [Editor: details may change as the [RAR] document evolves] 1219 4.6.5. "authorizations" Object 1221 One or more key / value pairs, where each unique key is created by 1222 the client, and the value is an authorization object. 1224 4.6.6. "claims" Object 1226 Includes one or more of the following: 1228 * *oidc* - an object that contains one or both of the following 1229 objects: 1231 - *userinfo* - Claims that will be returned as a JSON object 1233 - *id_token* - Claims that will be included in the returned ID 1234 Token. If the null value, an ID Token will be returned 1235 containing no additional Claims. 1237 The contents of the userinfo and id_token objects are Claims as 1238 defined in [OIDC] Section 5. 1240 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1241 per [OIDC4IA]. 1243 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1244 be requested.] 1246 4.6.7. "verification" Object 1248 The verification Object is used with the Verify Grant Section 4.2. 1250 * *nonce* the Interaction Nonce received from the GS via the 1251 Completion URI. This attribute MUST only be used in the Verify 1252 Grant Section 4.2. 1254 [Editor: parameters for the Client to request it wants the Grant 1255 Response signed and/or encrypted?] 1257 4.7. Read Authorization 1259 The Client acquires an Authorization by doing an HTTP GET to the 1260 corresponding AZ URI. 1262 The GS MUST respond with a Authorization JSON document Section 6.5, 1263 or one of the following errors: 1265 * TBD 1267 from Error Responses Section 9. 1269 4.8. Update Authorization 1271 The Client updates an Authorization by doing an HTTP PUT to the 1272 corresponding AZ URI of the following JSON. All of the following 1273 MUST be included. 1275 * *iat* - the time of the response as a NumericDate. 1277 * *uri* - the AZ URI. 1279 * *authorization* - the new authorization requested per the Request 1280 JSON "authorization" object Section 4.6.4. 1282 The GS MUST respond with a Authorization JSON document Section 6.5, 1283 or one of the following errors: 1285 * TBD 1287 from Error Responses Section 9. 1289 4.9. Delete Authorization 1291 The Client deletes an Authorization by doing an HTTP DELETE to the 1292 corresponding AZ URI. 1294 The GS MUST respond with OK 200, or one of the following errors: 1296 * TBD 1298 from Error Responses Section 9. 1300 4.10. GS Options 1302 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1303 of the corresponding GS URI. This is the only API where the GS MAY 1304 respond to an unauthenticated request. 1306 The GS MUST respond with the the following JSON document: 1308 [Editor: this section is a work in progress] 1310 * *uri* - the GS URI. 1312 * *client_authentication* - an array of the Client Authentication 1313 mechanisms supported by the GS 1315 * *interactions* - an array of the interaction modes supported by 1316 the GS. 1318 * *authorization* - an object containing the authorizations the 1319 Client may request from the GS, if any. 1321 - Details TBD 1323 * *claims* - an object containing the identity claims the Client may 1324 request from the GS, if any, and what public keys the claims will 1325 be signed with. 1327 - Details TBD 1329 * *algorithms* - a list of the cryptographic algorithms supported by 1330 the GS. 1332 * *features* - an object containing feature support 1334 - *user_exists* - boolean indicating if user.exists is supported. 1336 - *authorizations* - boolean indicating if a request for more 1337 than one authorization in a request is supported. 1339 [Editor: keys used by Client to encrypt requests, or verify signed 1340 responses?] 1342 [Editor: namespace metadata for extensions?] 1344 or one of the following errors: 1346 * TBD 1348 from Error Responses Section 9. 1350 4.11. Grant Options 1352 The Client can get the metadata for the Grant by doing an HTTP 1353 OPTIONS of the corresponding Grant URI. 1355 The GS MUST respond with the the following JSON document: 1357 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1359 or one of the following errors: 1361 * TBD 1363 from Error Responses Section 9. 1365 4.12. AuthZ Options 1367 The Client can get the metadata for the AuthZ by doing an HTTP 1368 OPTIONS of the corresponding AZ URI. 1370 The GS MUST respond with the the following JSON document: 1372 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1374 or one of the following errors: 1376 * TBD 1378 from Error Responses Section 9. 1380 4.13. Request Verification 1382 On receipt of a request, the GS MUST verify the following: 1384 * TBD 1386 5. GS Initiated Grant 1388 [Editor: In OAuth 2.0, all flows are initiated at the Client. If the 1389 AS wanted to initiate a flow, it redirected to the Client, that 1390 redirected back to the AS to initiate a flow. 1392 Here is a proposal to support GS initiated: authentication; just-in- 1393 time (JIT) provisioning; and authorization] 1395 *initiation_uri* A URI at the Client that contains no query or 1396 fragment. How the GS learns the Client initiation_uri is out of 1397 scope. 1399 The GS creates a Grant and Grant URI, and redirects the User to the 1400 initiation_uri with the query parameter "grant" and the value of 1401 Grant URI. 1403 See Section 2.5 for the sequence diagram. 1405 6. GS Responses 1407 There are three successful responses to a grant request: Grant 1408 Response, Interaction Response, or Wait Response. 1410 6.1. Grant Response 1412 The Grant Response MUST include the following from the Response JSON 1413 Section 6.4 1415 * iat 1417 * nonce 1419 * uri 1421 and MAY include the following from the Response JSON Section 6.4 1423 * client.handle 1425 * authorization or authorizations 1427 * claims 1429 * expires_in 1430 Example non-normative Grant Response JSON document for Example 1 in 1431 Section 4.1: 1433 { 1434 "iat" : 15790460234, 1435 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1436 "uri" : "https://as.example/endpoint/grant/example1", 1437 "expires_in" : 300 1438 "authorization": { 1439 "type" : "oauth_scope", 1440 "scope" : "read_contacts", 1441 "expires_in" : 3600, 1442 "mechanism" : "bearer", 1443 "token" : "eyJJ2D6.example.access.token.mZf9p" 1444 }, 1445 "claims": { 1446 "oidc": { 1447 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1448 "userinfo" : { 1449 "name" : "John Doe", 1450 "picture" : "https://photos.example/p/eyJzdkiO" 1451 } 1452 } 1453 } 1454 } 1456 Example non-normative Grant Response JSON document for Example 2 in 1457 Section 4.1: 1459 { 1460 "iat" : 15790460234, 1461 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1462 "uri" : "https://as.example/endpoint/grant/example2", 1463 "authorization": { 1464 "uri" : "https://as.example/endpoint/authz/example2" 1465 } 1466 } 1468 6.2. Interaction Response 1470 The Interaction Response MUST include the following from the Response 1471 JSON Section 6.4 1473 * iat 1475 * nonce 1477 * uri 1478 * interaction 1480 and MAY include the following from the Response JSON Section 6.4 1482 * user 1484 * wait 1486 A non-normative example of an Interaction Response follows: 1488 { 1489 "iat" : 15790460234, 1490 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1491 "uri" : "https://as.example/endpoint/grant/example4", 1492 "interaction" : { 1493 ""redirect" : { 1494 "authorization_uri" : "https://as.example/i/example4" 1495 } 1496 }, 1497 "user": { 1498 "exists" : true 1499 } 1500 } 1502 6.3. Wait Response 1504 The Wait Response MUST include the following from the Response JSON 1505 Section 6.4 1507 * iat 1509 * nonce 1511 * uri 1513 * wait 1515 A non-normative example of Wait Response follows: 1517 { 1518 "iat" : 15790460234, 1519 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1520 "uri" : "https://as.example/endpoint/grant/example5", 1521 "wait" : 300 1522 } 1524 6.4. Response JSON 1526 Details of the JSON document: 1528 * *iat* - the time of the response as a NumericDate. 1530 * *nonce* - the nonce that was included in the Request JSON 1531 Section 4.6. 1533 * *uri* - the Grant URI. 1535 * *wait* - a numeric value representing the number of seconds the 1536 Client should want before making a Read Grant request to the Grant 1537 URI. 1539 * *expires_in* - a numeric value specifying how many seconds until 1540 the Grant expires. This attribute is OPTIONAL. 1542 6.4.1. "client" Object 1544 The GS may 1546 6.4.2. "interaction" Object 1548 If the GS wants the Client to start the interaction, the GS MUST 1549 return an interaction object containing one or more interaction mode 1550 responses per Section 7 to one or more of the interaction mode 1551 requests provided by the Client. 1553 6.4.3. "user" Object 1555 * *exists* - a boolean value indicating if the GS has a user with 1556 one or more of the provided identifiers in the Request 1557 user.identifiers object Section 4.6.3 1559 6.4.4. "authorization" Object 1561 The authorization object contains Authorization JSON Section 6.5. 1562 See Grant Response Section 6.1 for non-normative examples. 1564 6.4.5. "authorizations" Object 1566 A key / value pair for each key in the client's request 1567 authorizations object, and the value is Authorization JSON 1568 Section 6.5. 1570 6.4.6. "claims" Object 1572 The claims object is a response to the Request "claims" object 1573 Section 4.6.4. 1575 * *oidc* 1577 - *id_token* - an OpenID Connect ID Token containing the Claims 1578 the User consented to be released. 1580 - *userinfo* - the Claims the User consented to be released. 1582 Claims are defined in [OIDC] Section 5. 1584 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1585 per [OIDC4IA]. 1587 * *vc* 1589 The verified claims the user consented to be released. [Editor: 1590 details TBD] 1592 6.5. Authorization JSON 1594 The Authorization JSON is a response to a Read AuthZ request by the 1595 Client Section 4.7. A subset of the Authorization JSON is included 1596 in the "authorization" object Section 4.6.4 and "authorizations" list 1597 members Section 6.4.5. 1599 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1600 See the "type" object in Section 4.6.4 for details. This 1601 attribute is REQUIRED. 1603 * *scope* - the scopes the Client was granted authorization for. 1604 This will be all, or a subset, of what was requested. This 1605 attribute is OPTIONAL. 1607 * *authorization_details* - the authorization details granted per 1608 [RAR]. Included if type is "oauth_rich". 1610 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1611 "jose+body". See Section 8 for details. This attribute is 1612 REQUIRED. 1614 * *token* - the access token for accessing an RS. This attribute is 1615 REQUIRED. 1617 * *expires_in* - a numeric value specifying how many seconds until 1618 the access token expires. This attribute is OPTIONAL. 1620 * *certificate* - MUST be included if the mechanism is "jose" or 1621 "jose+body". Contains the jwk header values for the Client to 1622 include in the JWS header when calling the RS using the "jose" or 1623 "jose+body" mechanisms. See Section 10.2.1. 1625 * *uri* - the AZ URI. Used to refresh an authorization. This 1626 attribute is OPTIONAL. 1628 [Editor: would an optional expiry for the Authorization be useful?] 1630 The following is a non-normative example of an Authorization JSON 1631 document: 1633 { 1634 "type" : "oauth_scope", 1635 "scope" : "read_calendar write_calendar", 1636 "mechanism" : "jose", 1637 "token" : "eyJJ2D6.example.access.token.mZf9p" 1638 "expires_in" : 3600, 1639 "certificate": { 1640 "x5u" : "https://as.example/cert/example2" 1641 }, 1642 "uri" : "https://as.example/endpoint/authz/example2" 1643 } 1645 6.5.1. Signing and Encryption 1647 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1648 there a generalized description, or is it mechanism specific?] 1650 6.6. Response Verification 1652 On receipt of a response, the Client MUST verify the following: 1654 * TBD 1656 7. interaction mode Objects 1658 This document defines three interaction modes: "redirect", 1659 "indirect", and "user_code". Extensions may define additional 1660 interaction modes. 1662 The "global" attribute is reserved in the interaction object for 1663 attributes that apply to all interaction modes. 1665 7.1. "redirect" mode 1667 A Redirect Interaction is characterized by the Client redirecting the 1668 User's browser to the GS, the GS interacting with the User, and then 1669 GS redirecting the User's browser back to the Client. The GS 1670 correlates the Grant Request with the unique authorization_uri, and 1671 the Client correlates the Grant Request with the unique redirect_uri. 1673 7.1.1. request "interaction" object contains: 1675 *redirect_uri* a grant request request unique URI at the Client that 1676 the GS will return the User to. This attribute is REQUIRED. 1678 7.1.2. response "interaction" object contains: 1680 *authorization_uri* a grant request request unique URI at the GS that 1681 the Client will redirect the User to. This attribute is REQUIRED. 1683 7.2. "indirect" mode 1685 An Indirect Interaction is characterized by the Client causing the 1686 User's browser to load the short_uri at GS, the GS interacting with 1687 the User, and then the GS MAY optionally redirecting the User's 1688 Browser to a completion_uri. There is no mechanism for the GS to 1689 redirect the User's browser back to the Client. Examples of how the 1690 Client may initiate the interaction are encoding the short_uri as a 1691 code scannable by the User's mobile device, or launching a system 1692 browser from a command line interface (CLI) application. 1694 The "indirect" mode is susceptible to session fixation attacks. See 1695 TBD in the Security Considerations for details. 1697 7.2.1. request "interaction" object contains: 1699 *completion_uri* an OPTIONAL URI that the GS will redirect the User's 1700 browser to after GS interaction. 1702 7.2.2. response "interaction" object contains: 1704 *short_uri* the URI the Client will cause to load in the User's 1705 browser. The URI SHOULD be short enough to be easily encoded in a 1706 scannable code. [Editor: recommend a length?] 1708 7.3. "user_code" mode 1710 An Indirect Interaction is characterized by the Client displaying a 1711 code and a URI for the User to load in a browser and then enter the 1712 code. 1714 7.3.1. request "interaction" object contains: 1716 *completion_uri* an OPTIONAL URI that the GS will redirect the User's 1717 browser to after GS interaction. 1719 7.3.2. response "interaction" object contains: 1721 *code* the code the Client displays to the User to enter at the 1722 display_uri. This attribute is REQUIRED. 1724 *display_uri* the URI the Client displays to the User to load in a 1725 browser to enter the code. 1727 8. RS Access 1729 This document specifies three different mechanisms for the Client to 1730 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1731 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1732 mechanisms are proof-of-possession mechanisms and are defined in 1733 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1734 possession mechanisms may be defined in other documents. The 1735 mechanism the Client is to use with an RS is the Response JSON 1736 authorization.mechanism attribute Section 6.4.4. 1738 8.1. Bearer Token 1740 If the access mechanism is "bearer", then the Client accesses the RS 1741 per Section 2.1 of [RFC6750] 1743 A non-normative example of the HTTP request headers follows: 1745 GET /calendar HTTP/2 1746 Host: calendar.example 1747 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1749 9. Error Responses 1751 * TBD 1753 10. JOSE Authentication 1755 How the Client authenticates to the GS and RS are independent of each 1756 other. One mechanism can be used to authenticate to the GS, and a 1757 different mechanism to authenticate to the RS. 1759 Other documents that specify other Client authentication mechanisms 1760 will replace this section. 1762 In the JOSE Authentication Mechanism, the Client authenticates by 1763 using its private key to sign a JSON document with JWS per [RFC7515] 1764 which results in a token using JOSE compact serialization. 1766 [Editor: are there advantages to using JSON serialization in the 1767 body?] 1769 Different instances of a Registered Client MAY have different private 1770 keys, but each instance has a certificate to bind its private key to 1771 to a public key the GS has for the Client ID. An instance of a 1772 Client will use the same private key for all signing operations. 1774 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1775 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1777 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1779 The token may be included in an HTTP header, or as the HTTP message 1780 body. 1782 The following sections specify how the Client uses JOSE to 1783 authenticate to the GS and RS. 1785 10.1. GS Access 1787 The Client authenticates to the GS by passing either a signed header 1788 parameter, or a signed message body. The following table shows the 1789 verb, uri and token location for each Client request to the GS: 1791 +---------------+-----------+-----------+----------+ 1792 | request | http verb | uri | token in | 1793 +===============+===========+===========+==========+ 1794 | Create Grant | POST | GS URI | body | 1795 +---------------+-----------+-----------+----------+ 1796 | Verify Grant | PATCH | Grant URI | body | 1797 +---------------+-----------+-----------+----------+ 1798 | Read Grant | GET | Grant URI | header | 1799 +---------------+-----------+-----------+----------+ 1800 | Update Grant | PUT | Grant URI | body | 1801 +---------------+-----------+-----------+----------+ 1802 | Delete Grant | DELETE | Grant URI | header | 1803 +---------------+-----------+-----------+----------+ 1804 | Read AuthZ | GET | AZ URI | header | 1805 +---------------+-----------+-----------+----------+ 1806 | Update AuthZ | PUT | AZ URI | body | 1807 +---------------+-----------+-----------+----------+ 1808 | Delete AuthZ | DELETE | AZ URI | header | 1809 +---------------+-----------+-----------+----------+ 1810 | GS Options | OPTIONS | GS URI | header | 1811 +---------------+-----------+-----------+----------+ 1812 | Grant Options | OPTIONS | Grant URI | header | 1813 +---------------+-----------+-----------+----------+ 1814 | AuthZ Options | OPTIONS | AZ URI | header | 1815 +---------------+-----------+-----------+----------+ 1817 Table 2 1819 10.1.1. Authorization Header 1821 For requests with the token in the header, the JWS payload MUST 1822 contain the following attributes: 1824 *iat* - the time the token was created as a NumericDate. 1826 *jti* - a unique identifier for the token per [RFC7519] section 1827 4.1.7. 1829 *uri* - the value of the URI being called (GS URI, Grant URI, or AZ 1830 URI). 1832 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1833 "OPTIONS") 1835 The HTTP authorization header is set to the "jose" parameter followed 1836 by one or more white space characters, followed by the resulting 1837 token. 1839 A non-normative example of a JWS payload and the HTTP request 1840 follows: 1842 { 1843 "iat" : 15790460234, 1844 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1845 "uri" : "https://as.example/endpoint/grant/example6", 1846 "verb" : "GET" 1847 } 1849 GET /endpoint/example.grant HTTP/2 1850 Host: as.example 1851 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1853 [Editor: make a real example token] 1855 *GS Verification* 1857 The GS MUST verify the token by: 1859 * TBD 1861 10.1.2. Signed Body 1863 For requests with the token in the body, the Client uses the Request 1864 JSON as the payload in a JWS. The resulting token is sent with the 1865 content-type set to "application/jose". 1867 A non-normative example (line breaks added to the body for 1868 readability): 1870 POST /endpoint HTTP/2 1871 Host: as.example 1872 Content-Type: application/jose 1873 Content-Length: 155 1875 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1876 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1877 Jf36POk6yJV_adQssw5c 1879 [Editor: make a real example token] 1881 *GS Verification* 1883 The GS MUST verify the token by: 1885 * TBD 1887 10.1.3. Public Key Resolution 1889 * *Registered Clients* can use any of the JWS header values to 1890 direct the GS to resolve the public key matching the private key 1891 used to the Client ID. The GS MAY restrict with JWS headers a 1892 Client can use. 1894 [Editor: would examples help here so that implementors understand the 1895 full range of options, and how an instance can have its own asymetric 1896 key pair] 1898 A non-normative example of a JOSE header for a Registered Client with 1899 a key identifier of "12": 1901 { 1902 "alg" : "ES256", 1903 "typ" : "JOSE", 1904 "kid" : "12" 1905 } 1907 * *Dynamic Clients* include their public key in the "jwk" JWS 1908 header. 1910 A non-normative example of a JOSE header for a Dynamic Client: 1912 { 1913 "alg" : "ES256", 1914 "typ" : "JOSE", 1915 "jwk" : { 1916 "kty" : "EC", 1917 "crv" : "P-256", 1918 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1919 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1920 } 1921 } 1923 10.2. RS Access 1925 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 1926 include a proof-of-possession token in the HTTP authorization header. 1927 In the "jose+body" mechanism Section 10.2.3, the Client signs the 1928 JSON document in the request if the POST or PUT verbs are used, 1929 otherwise it is the same as the "jose" mechanism. 1931 10.2.1. JOSE header 1933 The GS provides the Client one or more JWS header parameters and 1934 values for a a certificate, or a reference to a certificate or 1935 certificate chain, that the RS can use to resolve the public key 1936 matching the private key being used by the Client. 1938 A non-normative examples JOSE header: 1940 { 1941 "alg" : "ES256", 1942 "typ" : "JOSE", 1943 "x5u" : "https://as.example/cert/example2" 1944 } 1946 [Editor: this enables Dynamic Clients to make proof-of-possession API 1947 calls the same as Registered Clients.] 1949 10.2.2. "jose" Mechanism 1951 The JWS payload MUST contain the following attributes: 1953 *iat* - the time the token was created as a NumericDate. 1955 *jti* - a unique identifier for the token per [RFC7519] section 1956 4.1.7. 1958 *uri* - the value of the RS URI being called. 1960 *verb* - the HTTP verb being used in the call 1962 *token* - the access token provided by the GS to the Client 1964 The HTTP authorization header is set to the "jose" parameter followed 1965 by one or more white space characters, followed by the resulting 1966 token. 1968 A non-normative example of a JWS payload and the HTTP request 1969 follows: 1971 { 1972 "iat" : 15790460234, 1973 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1974 "uri" : "https://calendar.example/calendar", 1975 "verb" : "GET", 1976 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 1977 } 1979 GET /calendar HTTP/2 1980 Host: calendar.example 1981 Authorization: jose eyJhbG.example.jose.token.adks 1983 [Editor: make a real example token] 1985 *RS Verification* 1987 The RS MUST verify the token by: 1989 * verify access token is bound to the public key - include key 1990 fingerprint in access token? 1992 * TBD 1994 10.2.3. "jose+body" Mechanism 1996 The "jose+body" mechanism can only be used if the content being sent 1997 to the RS is a JSON document. 1999 Any requests not sending a message body will use the "jose" mechanism 2000 Section 10.2.2. 2002 Requests sending a message body MUST have the following JWS payload: 2004 *iat* - the time the token was created as a NumericDate. 2006 *jti* - a unique identifier for the token per [RFC7519] section 2007 4.1.7. 2009 *uri* - the value of the RS URI being called. 2011 *verb* - the HTTP verb being used in the call 2013 *token* - the access token provided by the GS to the Client 2015 *body* - the message body being sent to the RS 2017 A non-normative example of a JWS payload and the HTTP request 2018 follows: 2020 { 2021 "iat" : 15790460234, 2022 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 2023 "uri" : "https://calendar.example/calendar", 2024 "verb" : "POST", 2025 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 2026 "payload" : { 2027 "event" : { 2028 "title" : "meeting with joe", 2029 "start_date_utc" : "2020-02-21 11:00:00", 2030 "end_date_utc" : "2020-02-21 11:00:00" 2031 } 2032 } 2033 } 2035 POST /calendar HTTP/2 2036 Host: calendar.example 2037 Content-Type: application/jose 2038 Content-Length: 155 2040 eyJhbGciOi.example.jose+body.adasdQssw5c 2042 [Editor: make a real example token] 2044 *RS Verification* 2046 The RS MUST verify the token by: 2048 * TBD 2050 10.2.4. Public Key Resolution 2052 The RS has a public key for the GS that it uses to verify the 2053 certificate or certificate chain the Client includes in the JWS 2054 header. 2056 10.3. Request Encryption 2058 [Editor: to be fleshed out] 2060 The Client encrypts a request when ??? using the GS public key 2061 returned as the ??? attribute in GS Options Section 4.10. 2063 10.4. Response Signing 2065 [Editor: to be fleshed out] 2066 The Client verifies a signed response ??? using the GS public key 2067 returned as the ??? attribute in GS Options Section 4.10. 2069 10.5. Response Encryption 2071 [Editor: to be fleshed out] 2073 The Client decrypts a response when ??? using the private key 2074 matching the public key included in the request as the ??? attribute 2075 in Section 4.6. 2077 11. Extensibility 2079 This standard can be extended in a number of areas: 2081 * *Client Authentication Mechanisms* 2083 - An extension could define other mechanisms for the Client to 2084 authenticate to the GS and/or RS such as Mutual TLS or HTTP 2085 Signing. Constrained environments could use CBOR [RFC7049] 2086 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 2087 [RFC8323] instead of HTTP/2. 2089 * *Grant* 2091 - An extension can define new objects in the Grant Request and 2092 Grant Response JSON. 2094 * *Top Level* 2096 - Top level objects SHOULD only be defined to represent 2097 functionality other the existing top level objects and 2098 attributes. 2100 * *"client" Object* 2102 - Additional information about the Client that the GS would 2103 require related to an extension. 2105 * *"user" Object* 2107 - Additional information about the User that the GS would require 2108 related to an extension. 2110 * *"authorization" Object* 2112 - Additional authorization schemas in addition to OAuth 2.0 2113 scopes and RAR. 2115 * *"claims" Object* 2117 - Additional claim schemas in addition to OpenID Connect claims 2118 and Verified Credentials. 2120 * *interaction modes* 2122 - Additional types of interactions a Client can start with the 2123 User. 2125 * *Continuous Authentication* 2127 - An extension could define a mechanism for the Client to 2128 regularly provide continuous authentication signals and receive 2129 responses. 2131 [Editor: do we specify access token / handle introspection in this 2132 document, or leave that to an extension?] 2134 [Editor: do we specify access token / handle revocation in this 2135 document, or leave that to an extension?] 2137 12. Rational 2139 1. *Why is there only one mechanism for the Client to authenticate 2140 with the GS? Why not support other mechanisms?* 2142 Having choices requires implementers to understand which choice 2143 is preferable for them. Having one default mechanism in the 2144 document for the Client to authenticate simplifies most 2145 implementations. Deployments that have unique characteristics 2146 can select other mechanisms that are preferable in specific 2147 environments. 2149 2. *Why is the default Client authentication JOSE rather than 2150 MTLS?* 2152 MTLS cannot be used today by a Dynamic Client. MTLS requires 2153 the application to have access below what is typically the 2154 application layer, that is often not available on some 2155 platforms. JOSE is done at the application layer. Many GS 2156 deployments will be an application behind a proxy performing 2157 TLS, and there are risks in the proxy passing on the results of 2158 MTLS. 2160 3. *Why is the default Client authentication JOSE rather than HTTP 2161 signing?* 2162 There is currently no widely deployed open standard for HTTP 2163 signing. Additionally, HTTP signing requires passing all the 2164 relevant parts of the HTTP request to downstream services within 2165 an GS that may need to independently verify the Client identity. 2167 4. *What are the advantages of using JOSE for the Client to 2168 authenticate to the GS and a resource?* 2170 Both Registered Clients and Dynamic Clients can have a private 2171 key, eliminating the public Client issues in OAuth 2.0, as a 2172 Dynamic Client can create an ephemeral key pair. Using 2173 asymetric cryptography also allows each instance of a Registered 2174 Client to have its own private key if it can obtain a 2175 certificate binding its public key to the public key the GS has 2176 for the Client. Signed tokens can be passed to downstream 2177 components in a GS or RS to enable independent verification of 2178 the Client and its request. The GS Initiated Sequence Section 5 2179 requires a URL safe parameter, and JOSE is URL safe. 2181 5. *Why does the GS not return parameters to the Client in the 2182 redirect url?* 2184 Passing parameters via a browser redirection is the source of 2185 many of the security risks in OAuth 2.0. It also presents a 2186 challenge for smart devices. In this protocol, the redirection 2187 from the Client to the GS is to enable the GS to interact with 2188 the User, and the redirection back to the Client is to hand back 2189 interaction control to the Client if the redirection was a full 2190 browser redirect. Unlike OAuth 2.0, the identity of the Client 2191 is independent of the URI the GS redirects to. 2193 6. *Why is there not a UserInfo endpoint as there is with OpenID 2194 Connect?* 2196 Since the Client can Read Grant at any time, it get the same 2197 functionality as the UserInfo endpoint, without the Client 2198 having to manage a separate access token and refresh token. If 2199 the Client would like additional claims, it can Update Grant, 2200 and the GS will let the Client know if an interaction is 2201 required to get any of the additional claims, which the Client 2202 can then start. 2204 [Editor: is there some other reason to have the UserInfo 2205 endpoint?] 2207 7. *Why is there still a Client ID?* 2208 The GS needs an identifier to fetch the meta data associated 2209 with a Client such as the name and image to display to the User, 2210 and the policies on what a Client is allowed to do. The Client 2211 ID was used in OAuth 2.0 for the same purpose, which simplifies 2212 migration. Dynamic Clients do not have a Client ID. 2214 8. *Why have both claims and authorizations?* 2216 There are use cases for each that are independent: 2217 authenticating a user and providing claims vs granting access to 2218 a resource. A request for an authorization returns an access 2219 token which may have full CRUD capabilities, while a request for 2220 a claim returns the claim about the User - with no create, 2221 update or delete capabilities. While the UserInfo endpoint in 2222 OIDC may be thought of as a resource, separating the concepts 2223 and how they are requested keeps each of them simpler in the 2224 Editor's opinion. :) 2226 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2227 GS communication in ?*Section 10 2229 Knowing the GS supports HTTP/2 enables a Client to set up a 2230 connection faster. HTTP/2 will be more efficient when Clients 2231 have large numbers of access tokens and are frequently 2232 refreshing them at the GS as there will be less network traffic. 2233 Mandating TLS 1.3 similarly improves the performance and 2234 security of Clients and GS when setting up a TLS connection. 2236 10. *Why do some of the JSON objects only have one child, such as 2237 the identifiers object in the user object in the Grant Request?* 2239 It is difficult to forecast future use cases. Having more 2240 resolution may mean the difference between a simple extension, 2241 and a convoluted extension. 2243 11. *Why is the "iss" included in the "oidc" identifier object? 2244 Would the "sub" not be enough for the GS to identify the User?* 2246 This decouples the GS from the OpenID Provider (OP). The GS 2247 identifier is the GS URI, which is the endpoint at the GS. The 2248 OP issuer identifier will likely not be the same as the GS URI. 2249 The GS may also provide claims from multiple OPs. 2251 12. *Why complicate things with interaction.keep?* 2253 The common sequence has a back and forth between the Client and 2254 the GS, and the Client can update the Grant and have a new 2255 interaction. Keeping the interaction provides a more seamless 2256 user experience where the results from the first request 2257 determine subsequent requests. For example, a common pattern is 2258 to use a GS to authenticate the User at the Client, and to 2259 register the User at the Client using additional claims from the 2260 GS. The Client does not know a priori if the User is a new 2261 User, or a returning User. Asking a returning User to consent 2262 releasing claims they have already provided is a poor User 2263 experience, as is sending the User back to the GS. The Client 2264 requesting identity first enables the Client to get a response 2265 from the GS while the GS is still interacting with the User, so 2266 that the Client can request additional claims only if needed. 2267 Additionally, the claims a Client may want about a User may be 2268 dependent on some initial Claims. For example, if a User is in 2269 a particular country, additional or different Claims my be 2270 required by the Client. 2272 There are also benefits for the GS. Today, a GS usually keeps 2273 track of which claims a Client has requested for a User. 2274 Storing this information for all Clients a User uses may be 2275 undesirable for a GS that does not want to have that information 2276 about the User. Keeping the interaction allows the Client to 2277 track what information it has about the User, and the GS can 2278 remain stateless. 2280 13. *Why is there a "jose+body" RS access mechanism method for the 2281 Client?*Section 10.2.3 2283 There are numerous use cases where the RS wants non-repudiation 2284 and providence of the contents of an API call. For example, the 2285 UGS Service Supplier Framework for Authentication and 2286 Authorization [UTM]. 2288 14. *Why use URIs to instead of handles for the Grant and 2289 Authorization?* 2291 A URI is an identifier just like a handle that can contain GS 2292 information that is opaque to the Client - so it has all the 2293 features of a handle, plus it can be the URL that is resolved to 2294 manipulate a Grant or an Authorization. As the Grant URI and AZ 2295 URI are defined to start with the GS URI, the Client (and GS) 2296 can easily determine which GS a Grant or Authorization belong 2297 to. URIs also enable a RESTful interface to the GS 2298 functionality. 2300 15. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 2301 known mechanism?* 2302 Having the GS URI endpoint respond to the metadata allows the GS 2303 to provide Client specific results using the same Client 2304 authentication used for other requests to the GS. It also 2305 reduces the risk of a mismatch between what the advertised 2306 metadata, and the actual metadata. A .well-known discovery 2307 mechanism may be defined to resolve from a hostname to the GS 2308 URI. 2310 16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AZ URI?* 2312 Maybe there are no use cases for them [that the editor knows 2313 of], but the GS can not implement, and they are available if use 2314 cases come up. 2316 17. *Why have both Client ID and Client Handle?* 2318 While they both refer to a Client in the protocol, the Client ID 2319 refers to a pre-registered client,and the Client Handle is 2320 specific to an instance of a Dynamic Client. Using separate 2321 terms clearly differentiates which identifier is being presented 2322 to the GS. 2324 13. Acknowledgments 2326 This draft derives many of its concepts from Justin Richer's 2327 Transactional Authorization draft [TxAuth]. 2329 Additional thanks to Justin Richer and Annabelle Richard Backman for 2330 their strong critique of earlier drafts. 2332 14. IANA Considerations 2334 [ JOSE parameter for Authorization HTTP header ] 2336 TBD 2338 15. Security Considerations 2340 TBD 2342 16. References 2344 16.1. Normative References 2346 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2347 Requirement Levels", BCP 14, RFC 2119, 2348 DOI 10.17487/RFC2119, March 1997, 2349 . 2351 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2352 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2353 . 2355 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2356 DOI 10.17487/RFC5322, October 2008, 2357 . 2359 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2360 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2361 . 2363 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2364 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2365 September 2009, . 2367 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2368 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2369 . 2371 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2372 Framework: Bearer Token Usage", RFC 6750, 2373 DOI 10.17487/RFC6750, October 2012, 2374 . 2376 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2377 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2378 2015, . 2380 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2381 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2382 . 2384 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2385 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2386 . 2388 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2389 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2390 DOI 10.17487/RFC7540, May 2015, 2391 . 2393 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2394 Interchange Format", STD 90, RFC 8259, 2395 DOI 10.17487/RFC8259, December 2017, 2396 . 2398 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2399 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2400 . 2402 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2403 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2404 . 2406 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2407 Assurance 1.0", October 2019, . 2410 16.2. Informative References 2412 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2413 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2414 October 2013, . 2416 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2417 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2418 . 2420 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2421 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2422 . 2424 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2425 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2426 Application Protocol) over TCP, TLS, and WebSockets", 2427 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2428 . 2430 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2431 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2432 DOI 10.17487/RFC8628, August 2019, 2433 . 2435 [browser_based_apps] 2436 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2437 Apps", September 2019, . 2440 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2441 Rich Authorization Requests", January 2020, 2442 . 2444 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2445 Credentials Data Model 1.0", November 2019, 2446 . 2448 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2449 identification and data capture techniques - QR Code bar 2450 code symbology specification", February 2015, 2451 . 2453 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2454 . 2457 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2458 Supplier Framework for Authentication and AuthN", 2459 September 2019, . 2462 Appendix A. Document History 2464 A.1. draft-hardt-xauth-protocol-00 2466 * Initial version 2468 A.2. draft-hardt-xauth-protocol-01 2470 * text clean up 2472 * added OIDC4IA claims 2474 * added "jws" method for accessing a resource. 2476 * renamed Initiation Request -> Grant Request 2478 * renamed Initiation Response -> Interaction Response 2480 * renamed Completion Request -> Authorization Request 2482 * renamed Completion Response -> Grant Request 2484 * renamed completion handle -> authorization handle 2486 * added Authentication Request, Authentication Response, 2487 authentication handle 2489 A.3. draft-hardt-xauth-protocol-02 2491 * major rewrite 2493 * handles are now URIs 2495 * the collection of claims and authorizations are a Grant 2497 * an Authorization is its own type 2499 * lots of sequences added 2501 A.4. draft-hardt-xauth-protocol-03 2503 * fixed RO definition 2505 * improved language in Rationals 2507 * added user code interaction method, and aligned qrcode interaction 2508 method 2510 * added completion_uri for code flows 2512 A.5. draft-hardt-xauth-protocol-04 2514 * renamed interaction uris to have purpose specific names 2516 A.6. draft-hardt-xauth-protocol-05 2518 * separated claims from identifiers in request user object 2520 * simplified reciprocal grant flow 2522 * reduced interactions to redirect and indirect 2524 * simplified interaction parameters 2526 * added in language for Client to verify interaction completion 2528 * added Verify Grant API and Interaction Nonce 2530 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 2531 operation. 2533 A.7. draft-hardt-xauth-protocol-06 2535 * fixup examples to match specification 2537 A.8. draft-hardt-xauth-protocol-07 2539 * refactored interaction request and response syntax, and enabled 2540 interaction mode negotiation 2542 * generation of client handle by GS for dynamic clients 2544 * renamed title to Grant Negotiation and Authorization Protocol. 2545 Preserved draft-hardt-xauth-protocol filename to ease tracking 2546 changes. 2548 * changed Authorizations to be key / value pairs (aka dictionary) 2549 instead of a JSON array 2551 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2553 *Changed Features* 2555 The major changes between this protocol and OAuth 2.0 and OpenID 2556 Connect are: 2558 * The Client allows uses a private key to authenticate in this 2559 protocol instead of the client secret in OAuth 2.0 and OpenID 2560 Connect. 2562 * The Client initiates the protocol by making a signed request 2563 directly to the GS instead of redirecting the User to the GS. 2565 * The Client does not pass any parameters in redirecting the User to 2566 the GS, and optionally only receives an interaction nonce in the 2567 redirection back from the GS. 2569 * The refresh_token has been replaced with a AZ URI that both 2570 represents the authorization, and is the URI for obtaining a fresh 2571 access token. 2573 * The Client can request identity claims to be returned independent 2574 of the ID Token. There is no UserInfo endpoint to query claims as 2575 there is in OpenID Connect. 2577 * The GS URI is the token endpoint. 2579 *Preserved Features* 2581 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2582 tokens of OAuth 2.0. 2584 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2585 Connect. 2587 * No change is required by the Client or the RS for accessing 2588 existing bearer token protected APIs. 2590 *New Features* 2592 * A Grant represents both the user identity claims and RS access 2593 granted to the Client. 2595 * The Client can verify, update, retrieve, and delete a Grant. 2597 * The GS can initiate a flow by creating a Grant and redirecting the 2598 User to the Client with the Grant URI. 2600 * The Client can discovery if a GS has a User with an identifier 2601 before the GS interacts with the User. 2603 * The Client can request the GS to first authenticate the User and 2604 return User identity claims, and then the Client can update Grant 2605 request based on the User identity. 2607 * Support for scannable code initiated interactions. 2609 * Each Client instance can have its own private / public key pair. 2611 * Highly extensible per Section 11. 2613 Author's Address 2615 Dick Hardt (editor) 2616 SignIn.Org 2617 United States 2619 Email: dick.hardt@gmail.com