idnits 2.17.00 (12 Aug 2021) /tmp/idnits30391/draft-hardt-xauth-protocol-05.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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 5. If not interaction.verify, the Client creates and sets a a unique completion browser cookie and binds it to the completion URI. The cookie MUST not be able to be used to derive the Completion URI. -- The document date (7 March 2020) is 805 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 941, but not defined == Unused Reference: 'RFC7516' is defined on line 2468, 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 (~~), 5 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 7 March 2020 5 Expires: 8 September 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-05 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 Note to Readers 25 Source for this draft and an issue tracker can be found at 26 https://github.com/dickhardt/hardt-xauth-protocol 27 (https://github.com/dickhardt/hardt-xauth-protocol). 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 8 September 2020. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 1.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6 65 1.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 66 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 7 67 2. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 2.1. Create and Verify Grant . . . . . . . . . . . . . . . . . 8 69 2.2. Create and Read Grant - Redirect . . . . . . . . . . . . 10 70 2.3. Create and Read Grant - Indirect . . . . . . . . . . . . 11 71 2.4. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . 11 72 2.5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . 12 73 2.6. Create and Update . . . . . . . . . . . . . . . . . . . . 13 74 2.7. Create and Delete . . . . . . . . . . . . . . . . . . . . 15 75 2.8. Create, Discover, and Delete . . . . . . . . . . . . . . 17 76 2.9. Create and Wait . . . . . . . . . . . . . . . . . . . . . 17 77 2.10. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 18 78 2.11. Resource Server Access . . . . . . . . . . . . . . . . . 19 79 2.12. GS API Table . . . . . . . . . . . . . . . . . . . . . . 20 80 3. Grant and AuthZ Life Cycle . . . . . . . . . . . . . . . . . 20 81 4. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 4.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 21 83 4.2. Verify Grant . . . . . . . . . . . . . . . . . . . . . . 24 84 4.3. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 24 85 4.4. Update Grant . . . . . . . . . . . . . . . . . . . . . . 25 86 4.5. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 26 87 4.6. Request JSON . . . . . . . . . . . . . . . . . . . . . . 26 88 4.6.1. "client" Object . . . . . . . . . . . . . . . . . . . 26 89 4.6.2. "interaction" Object . . . . . . . . . . . . . . . . 27 90 4.6.3. "user" Object . . . . . . . . . . . . . . . . . . . . 28 91 4.6.4. "authorization" Object . . . . . . . . . . . . . . . 28 92 4.6.5. "authorizations" Object . . . . . . . . . . . . . . . 28 93 4.6.6. "claims" Object . . . . . . . . . . . . . . . . . . . 29 94 4.6.7. "verification" Object . . . . . . . . . . . . . . . . 29 95 4.7. Read Authorization . . . . . . . . . . . . . . . . . . . 29 96 4.8. Update Authorization . . . . . . . . . . . . . . . . . . 30 97 4.9. Delete Authorization . . . . . . . . . . . . . . . . . . 30 98 4.10. GS Options . . . . . . . . . . . . . . . . . . . . . . . 30 99 4.11. Grant Options . . . . . . . . . . . . . . . . . . . . . . 31 100 4.12. AuthZ Options . . . . . . . . . . . . . . . . . . . . . . 32 101 4.13. Request Verification . . . . . . . . . . . . . . . . . . 32 102 5. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 32 103 6. GS API Responses . . . . . . . . . . . . . . . . . . . . . . 32 104 6.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 32 105 6.2. Interaction Response . . . . . . . . . . . . . . . . . . 34 106 6.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 34 107 6.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 35 108 6.4.1. "interaction" Object . . . . . . . . . . . . . . . . 35 109 6.4.2. "user" Object . . . . . . . . . . . . . . . . . . . . 36 110 6.4.3. "authorization" Object . . . . . . . . . . . . . . . 36 111 6.4.4. "authorizations" Object . . . . . . . . . . . . . . . 36 112 6.4.5. "claims" Object . . . . . . . . . . . . . . . . . . . 36 113 6.5. Authorization JSON . . . . . . . . . . . . . . . . . . . 37 114 6.5.1. Signing and Encryption . . . . . . . . . . . . . . . 38 115 6.6. Response Verification . . . . . . . . . . . . . . . . . . 38 116 7. Interactions . . . . . . . . . . . . . . . . . . . . . . . . 38 117 7.1. Redirect Interaction . . . . . . . . . . . . . . . . . . 38 118 7.2. Indirect Interaction . . . . . . . . . . . . . . . . . . 40 119 8. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 40 120 8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 41 121 9. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 41 122 10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 41 123 10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 42 124 10.1.1. Authorization Header . . . . . . . . . . . . . . . . 42 125 10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 43 126 10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 44 127 10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 45 128 10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 45 129 10.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 45 130 10.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . 46 131 10.2.4. Public Key Resolution . . . . . . . . . . . . . . . 47 132 10.3. Request Encryption . . . . . . . . . . . . . . . . . . . 48 133 10.4. Response Signing . . . . . . . . . . . . . . . . . . . . 48 134 10.5. Response Encryption . . . . . . . . . . . . . . . . . . 48 135 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 48 136 12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 49 137 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 138 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 139 15. Security Considerations . . . . . . . . . . . . . . . . . . . 54 140 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 141 16.1. Normative References . . . . . . . . . . . . . . . . . . 54 142 16.2. Informative References . . . . . . . . . . . . . . . . . 55 143 Appendix A. Document History . . . . . . . . . . . . . . . . . . 56 144 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 56 145 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 56 146 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 57 147 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 57 148 A.5. draft-hardt-xauth-protocol-04 . . . . . . . . . . . . . . 57 149 A.6. draft-hardt-xauth-protocol-05 . . . . . . . . . . . . . . 57 150 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 58 151 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 59 153 1. Introduction 155 This protocol supports the widely deployed use cases supported by 156 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 157 extension of OAuth 2.0, as well as other extensions, and other use 158 cases that are not supported, such as acquiring multiple access 159 tokens at the same time, and updating the request during user 160 interaction. This protocol also addresses many of the security 161 issues in OAuth 2.0 by having parameters securely sent directly 162 between parties, rather than via a browser redirection. 164 The technology landscape has changed since OAuth 2.0 was initially 165 drafted. More interactions happen on mobile devices than PCs. 166 Modern browsers now directly support asymetric cryptographic 167 functions. Standards have emerged for signing and encrypting tokens 168 with rich payloads (JOSE) that are widely deployed. 170 Additional use cases are now being served with extensions to OAuth 171 2.0: OpenID Connect added support for authentication and releasing 172 identity claims; [RFC8252] added support for native apps; [RFC8628] 173 added support for smart devices; and support for [browser_based_apps] 174 is being worked on. There are numerous efforts on adding proof-of- 175 possession to resource access. 177 This protocol simplifies the overall architectural model, takes 178 advantage of today's technology landscape, provides support for all 179 the widely deployed use cases, and offers numerous extension points. 181 While this protocol is not backwards compatible with OAuth 2.0, it 182 strives to minimize the migration effort. 184 This protocol centers around a Grant, a representation of the 185 collection of user identity claims and/or resource authorizations the 186 Client is requesting, and the resulting identity claims and/or 187 resource authorizations granted by the Grant Server. 189 [Editor: suggestions on how to improve this are welcome!] 191 [Editor: suggestions for other names than XAuth are welcome!] 193 1.1. Parties 195 The parties and their relationships to each other: 197 +--------+ +------------+ 198 | User | | Resource | 199 | | | Owner (RO) | 200 +--------+ +------------+ 201 | \ / | 202 | \ / | 203 | \ / | 204 | \ / | 205 +--------+ +---------------+ +------------+ 206 | Client |---->| Grant | _ _ | Resource | 207 | |<----| Server (GS) | | Server | 208 | | +---------------+ | (RS) | 209 | |-------------------------->| | 210 | |<--------------------------| | 211 +--------+ +------------+ 213 * *User* - the person interacting with the Client who has delegated 214 access to identity claims about themselves to the Grant Server 215 (GS), and can authenticate at the GS. 217 * *Client* - requests a Grant from the GS to access one or more 218 Resource Servers (RSs), and/or identity claims about the User. 219 The Client can create, verify, retrieve, update, and delete a 220 Grant. When a Grant is created, the Client receives from the GS 221 the granted access token(s) for the RS(s), and identity claims 222 about the User. The Client uses an access token to access the RS. 223 There are two types of Clients: Registered Clients and Dynamic 224 Clients. All Clients have a key to authenticate with the Grant 225 Server. 227 * *Registered Client* - a Client that has registered with the GS and 228 has a Client ID to identify itself, and can prove it possesses a 229 key that is linked to the Client ID. The GS may have different 230 policies for what different Registered Clients can request. A 231 Registered Client MAY be interacting with a User. 233 * *Dynamic Client* - a Client that has not been registered with the 234 GS, and each instance will generate it's own key pair so it can 235 prove it is the same instance of the Client on subsequent 236 requests, and to requests of a Resource Server that require proof- 237 of-possession access. A single-page application with no active 238 server component is an example of a Dynamic Client. A Dynamic 239 Client MUST be interacting with a User. 241 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 242 release of identity claims about the User. The GS may require 243 explicit consent from the RO or User to provide these to the 244 Client. A GS may support Registered Clients and/or Dynamic 245 Clients. The GS is a combination of the Authorization Server (AS) 246 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 248 * *Resource Server* (RS) - has API resources that require an access 249 token from the GS. Some, or all of the resources are owned by the 250 Resource Owner. 252 * *Resource Owner* (RO) - owns resources at the RS, and has 253 delegated RS access management to the GS. The RO may be the same 254 entity as the User, or may be a different entity that the GS 255 interacts with independently. GS and RO interactions are out of 256 scope of this document. 258 1.2. Reused Terms 260 * *access token* - an access token as defined in [RFC6749] 261 Section 1.4. 263 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 264 issued by the GS, or by other issuers. 266 * *Client ID* - a GS unique identifier for a Registered Client as 267 defined in [RFC6749] Section 2.2. 269 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 271 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 273 * *authN* - short for authentication. 275 * *authZ* - short for authorization. 277 1.3. New Terms 279 * *GS URI* - the endpoint at the GS the Client calls to create a 280 Grant, and is the unique identifier for the GS. 282 * *Grant* - the user identity claims and/or RS authorizations the GS 283 has granted to the Client. 285 * *Grant URI* - the URI that represents the Grant. The Grant URI 286 MUST start with the GS URI. 288 * *Authorization* - the access granted by the RO to the Client. 289 Contains an access token. 291 * *Authorization URI* (AZ URI) - the URI that represents the 292 Authorization the Client was granted by the RO. The AZ URI MUST 293 start with the GS URI. The AZ URI is used to read, update, and 294 delete an access token. 296 * *Redirect Interaction* - characterized by the GS returning the 297 User back to the Client that started the interaction. 299 * *Indirect Interaction* - characterized by the GS not being able to 300 return the User back to the Client that started the interaction. 302 * *Redirect URI* - a URI at the GS that the Client will redirect the 303 User to in a Redirect Interaction. This URI is unique is unique 304 to an outstanding Create Grant request. 306 * *Completion URI* - the URI at the Client that the GS will redirect 307 the User back to in a Redirect Interaction. If the Client has not 308 set the interaction.verify flag, this URI is unique to the Create 309 Grant request made by the Client. 311 * *Information URI* - the URI the GS will redirect the User to after 312 an Indirect Interaction. 314 * *Short URI* - a URI at the GS that is used in Indirect 315 Interactions. The URI may be presented to the User as a scannable 316 code, or loaded in a system browser by the Client. The URI has a 317 maximum length of TBD bytes, and is unique to an outstanding 318 Create Grant request. 320 * *Code URI* - a URI at the GS presented to the User by the Client 321 for the User to enter the User Code in an Indirect Interaction. 323 * *User Code* - a string generated by the GS that is is unique to an 324 outstanding Create Grant request in an Indirect Interaction. 326 1.4. Notational Conventions 328 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 329 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 330 specification are to be interpreted as described in [RFC2119]. 332 Certain security-related terms are to be understood in the sense 333 defined in [RFC4949]. These terms include, but are not limited to, 334 "attack", "authentication", "authorization", "certificate", 335 "confidentiality", "credential", "encryption", "identity", "sign", 336 "signature", "trust", "validate", and "verify". 338 Unless otherwise noted, all the protocol parameter names and values 339 are case sensitive. 341 Some protocol parameters are parts of a JSON document, and are 342 referred to in JavaScript notation. For example, foo.bar refers to 343 the "bar" boolean attribute in the "foo" object in the following 344 example JSON document: 346 { 347 "foo" : { 348 "bar": true 349 } 350 } 352 2. Sequences 354 Before any sequence, the Client needs to be manually or 355 programmatically configured for the GS. See GS Options Section 4.10 356 for details on acquiring GS metadata. 358 [Editor: a plethora of sequences are included to illustrate all the 359 different use cases that are supported. Many sequences are similar, 360 and show a slightly different sequence that can support different use 361 cases. These could potentially be moved to a use case document in 362 the future.] 364 2.1. Create and Verify Grant 366 A Dynamic Client wants a Grant from the User using a Redirect 367 Interaction: 369 +--------+ +-------+ 370 | Client | | GS | 371 | |--(1)--- Create Grant ----------->| | 372 | | | | 373 | |<--- Interaction Response ---(2)--| | +------+ 374 | | | | | User | 375 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 376 | | | | | | 377 | | | |<--(4)-->| | 378 | | | | authN | | 379 | | | |<--(5)-->| | 380 | | | | authZ | | 381 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 382 | | | | | | 383 | |--(7)--- Verify Grant ----------->| | +------+ 384 | | | | 385 | |<--------- Grant Response ---(8)--| | 386 | | | | 387 +--------+ +-------+ 389 1. *Create Grant* The Client creates a Request JSON document 390 Section 4.6 and makes a Create Grant request (Section 4.1) by 391 sending the JSON with an HTTP POST to the GS URI. 393 2. *Interaction Response* The GS determines that interaction with 394 the User is required and sends an Interaction Response 395 (Section 6.2) containing the Grant URI and an interaction object. 397 3. *Interaction Transfer* The Client redirects the User to the 398 Redirect URI at the GS. 400 4. *User Authentication* The GS authenticates the User. 402 5. *User Authorization* If required, the GS interacts with the User 403 to determine which identity claims and/or authorizations in the 404 Grant Request are to be granted. 406 6. *Interaction Transfer* The GS redirects the User to the 407 Completion URI at the Client, passing an Interaction Nonce. 409 7. *Read Grant* The Client creates a JSON document containing a 410 verification object Section 4.6.7 and does a Verify Grant 411 Section 4.2 request by HTTP PATCH with the document to the Grant 412 URI. 414 8. *Grant Response* The GS responds with a Grant Response 415 (Section 6.1). 417 2.2. Create and Read Grant - Redirect 419 A Registered Client wants a Grant from the User using a Redirect 420 Interaction: 422 +--------+ +-------+ 423 | Client | | GS | 424 | |--(1)--- Create Grant ----------->| | 425 | | | | 426 | |<--- Interaction Response ---(2)--| | 427 | | | | 428 | |--(3)--- Read Grant ------------->| | +------+ 429 | | | | | User | 430 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 431 | | | | | | 432 | | | |<--(5)-->| | 433 | | | | authN | | 434 | | | |<--(6)-->| | 435 | | | | authZ | | 436 | |<--------- Grant Response ---(7)--| | | | 437 | | | | | | 438 | |<--- Interaction Transfer ---(8)- | - - - | --------| | 439 | | | | | | 440 +--------+ +-------+ +------+ 442 1. *Create Grant* The Client makes a Create Grant request 443 (Section 4.1) to the GS URI. 445 2. *Interaction Response* The GS determines that interaction with 446 the User is required and sends an Interaction Response 447 (Section 6.2) containing the Grant URI and an interaction object. 449 3. *Read Grant* The Client does an HTTP GET of the Grant URI 450 (Section 4.3). 452 4. *Interaction Transfer* The Client transfers User interaction to 453 the GS. 455 5. *User Authentication* The GS authenticates the User. 457 6. *User Authorization* If required, the GS interacts with the User 458 to determine which identity claims and/or authorizations in the 459 Grant Request are to be granted. 461 7. *Grant Response* The GS responds with a Grant Response 462 (Section 6.1). 464 8. *Interaction Transfer* The GS redirects the User to the 465 Completion URI of the Client. The Client verifies it is the same 466 User that it transferred to the GS. 468 2.3. Create and Read Grant - Indirect 470 A Registered Client wants a Grant from the User using an Indirect 471 Interaction: 473 +--------+ +-------+ 474 | Client | | GS | 475 | |--(1)--- Create Grant ----------->| | 476 | | | | 477 | |<--- Interaction Response ---(2)--| | 478 | | | | 479 | |--(3)--- Read Grant ------------->| | +------+ 480 | | | | | User | 481 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 482 | | | | | | 483 | | | |<--(5)-->| | 484 | | | | authN | | 485 | | | |<--(6)-->| | 486 | | | | authZ | | 487 | |<--------- Grant Response ---(7)--| | | | 488 +--------+ | | | | 489 | | | | 490 +--------+ | | | | 491 | Info |<--- Interaction Transfer ---(8)- | - - - | --------| | 492 | Server | | | | | 493 +--------+ +-------+ +------+ 495 The sequence is the same except: 497 * In step (4) the User either scans a bar code or uses a separate 498 device to navigate to the Code URI and enters the User Code. 500 * In step (8) the GS redirects the User to the Information URI 501 provided by the Client. 503 2.4. Reciprocal Grant 505 Party A and Party B are both a Client and a GS, and each Client would 506 like a Grant for the other GS. The sequence starts off the same as 507 in Section 2.2, but Party B makes a Create Grant Request before 508 sending a Grant Response: 510 Party A Party B 511 +--------+ +--------+ 512 | Client | | GS | 513 ~ ~ ~ ~ ~ ~ Same as steps 1 - 6 of ~ ~ ~ ~ ~ ~ 514 +------+ | | Create and Read Grant above | | 515 | User | | | | | 516 | | | GS |<--------- Create Grant ---(1)---| Client | 517 | | | | | | 518 | | | |<------- Grant Response ---(2)---| | 519 | | | | | | 520 | |<----- | - - - | -- Interaction Transfer --(3)---| | 521 | | | | | | 522 | |<-(4)->| | | | 523 | | AuthZ | | | | 524 +------+ | GS |--(5)--- Grant Response -------->| Client | 525 | | | | 526 +--------+ +--------+ 528 1. *Create Grant* Party B creates a Grant Request (Section 4.1) with 529 user.reciprocal set to the Party B Grant URI that will be in the 530 step (2) Grant Response, and sends it with an HTTP POST to the 531 Party A GS URI. This enables Party A to link the reciprocal 532 Grants. 534 2. *Grant Response* Party B responds to Party A's Create Grant 535 Request with a Grant Response that includes the Party B Grant 536 URI. 538 3. *Interaction Transfer* Party B redirects the User to the 539 Completion URI at Party A. 541 4. *User Authorization* If required, Party A interacts with the User 542 to determine which identity claims and/or authorizations in Party 543 B's Create Grant Request are to be granted. 545 5. *Grant Response* Party A responds with a Grant Response 546 (Section 6.1). 548 2.5. GS Initiated Grant 550 The User is at the GS, and wants to interact with a Registered 551 Client. The GS can redirect the User to the Client: 553 +--------+ +-------+ +------+ 554 | Client | | GS | | User | 555 | | | |<--(1)-->| | 556 | | | | | | 557 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 558 | (3) | | | | | 559 | verify |--(4)--- Read Grant ------------->| | +------+ 560 | | | | 561 | |<--------- Grant Response --(5)---| | 562 | | | | 563 +--------+ +-------+ 565 1. *User Interaction* The GS interacts with the User to determine 566 the Client and what identity claims and authorizations to 567 provide. The GS creates a Grant and corresponding Grant URI. 569 2. *GS Initiated Redirect* The GS redirects the User to the Client's 570 interaction_uri, adding a query parameter with the name "Grant 571 URI" and the value being the URL encoded Grant URI. 573 3. *Client Verification* The Client verifies the Grant URI is from 574 an GS the Client trusts, and starts with the GS GS URI. 576 4. *Read Grant* The Client does an HTTP GET of the Grant URI 577 (Section 4.3). 579 5. *Grant Response* The GS responds with a Grant Response 580 (Section 6.1). 582 See Section 5 for more details. 584 2.6. Create and Update 586 The Client requests an identity claim to determine who the User is. 587 Once the Client learns who the User is, and the Client updates the 588 Grant for additional identity claims which the GS prompts the User 589 for and returns to the Client. Once those are received, the Client 590 updates the Grant with the remaining identity claims required. 592 +--------+ +-------+ 593 | Client | | GS | 594 | |--(1)--- Create Grant ----------->| | 595 | | interaction.keep:true | | 596 | | | | 597 | |<--- Interaction Response ---(2)--| | 598 | | | | 599 | |--(3)--- Read Grant ------------->| | +------+ 600 | | | | | User | 601 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 602 | | | | | | 603 | | | |<--(5)-->| | 604 | | | | authN | | 605 | |<--------- Grant Response ---(6)--| | | | 606 | (7) | | | | | 607 | eval |--(8)--- Update Grant ----------->| | | | 608 | | interaction.keep:true | |<--(9)-->| | 609 | | | | authZ | | 610 | |<--------- Grant Response --(10)--| | | | 611 | (11) | | | | | 612 | eval |--(12)-- Update Grant ----------->| | | | 613 | | interaction.keep:false | |<--(13)->| | 614 | | | | authZ | | 615 | | | | | | 616 | |<--- Interaction Transfer --(14)- | - - - | --------| | 617 | | | | | | 618 | |<--------- Grant Response --(15)--| | +------+ 619 | | | | 620 +--------+ +-------+ 622 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 623 including an identity claim and interaction.keep:true, and sends 624 it with an HTTP POST to the GS GS URI. 626 2. *Interaction Response* The GS sends an Interaction Response 627 (Section 6.2) containing the Grant URI, an interaction object, 628 and interaction.keep:true. 630 3. *Read Grant* The Client does an HTTP GET of the Grant URI 631 (Section 4.3). 633 4. *Interaction Transfer* The Client transfers User interaction to 634 the GS. 636 5. *User Authentication* The GS authenticates the User. 638 6. *Grant Response* The GS responds with a Grant Response 639 (Section 6.1) including the identity claim from User 640 authentication and interaction.keep:true. 642 7. *Grant Evaluation* The Client queries its User database and does 643 not find a User record matching the identity claim. 645 8. *Update Grant* The Client creates an Update Grant Request 646 (Section 4.4) including the initial identity claims required and 647 interaction.keep:true, and sends it with an HTTP PUT to the 648 Grant URI. 650 9. *User AuthN* The GS interacts with the User to determine which 651 identity claims in the Update Grant Request are to be granted. 653 10. *Grant Response* The GS responds with a Grant Response 654 (Section 6.1) including the identity claims released by the User 655 and interaction.keep:true. 657 11. *Grant Evaluation* The Client evaluates the identity claims in 658 the Grant Response and determines the remaining User identity 659 claim required. 661 12. *Update Grant* The Client creates an Update Grant Request 662 (Section 4.4) including the remaining required identity claims 663 and interaction.keep:false, and sends it with an HTTP PUT to the 664 Grant URI. 666 13. *User AuthZ* The GS interacts with the User to determine which 667 identity claims in the Update Grant Request are to be granted. 669 14. *Interaction Transfer* The GS transfers User interaction to the 670 Client. 672 15. *Grant Response* The GS responds with a Grant Response 673 (Section 6.1) including the identity claims released by the 674 User. 676 2.7. Create and Delete 678 The Client requests an identity claim to determine who the User is. 679 Once the Client learns who the User is, and the Client knows it 680 already has all the identity claims and authorizations needed for the 681 User, the Client deletes the Grant which prompts the GS to transfer 682 the interaction back to the Client. (If the Client did not already 683 have what was needed, the Client would follow the Create and Update 684 sequence Section 2.6 ) 685 +--------+ +-------+ 686 | Client | | GS | 687 | |--(1)--- Create Grant ----------->| | 688 | | interaction.keep:true | | 689 | | | | 690 | |<--- Interaction Response ---(2)--| | 691 | | | | 692 | |--(3)--- Read Grant ------------->| | +------+ 693 | | | | | User | 694 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 695 | | | | | | 696 | | | |<--(5)-->| | 697 | | | | authN | | 698 | |<--------- Grant Response ---(6)--| | | | 699 | (7) | | | | | 700 | eval |--(8)--- Delete Grant ----------->| | | | 701 | |<------- Delete Response ---------| | | | 702 | | | | | | 703 | |<--- Interaction Transfer ---(9)- | - - - | --------| | 704 | | | | | | 705 +--------+ +-------+ +------+ 707 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 708 including an identity claim and interaction.keep:true, and sends 709 it with an HTTP POST to the GS GS URI. 711 2. *Interaction Response* The GS sends an Interaction Response 712 (Section 6.2) containing the Grant URI, an interaction object, 713 and interaction.keep:true. 715 3. *Read Grant* The Client does an HTTP GET of the Grant URI 716 (Section 4.3). 718 4. *Interaction Transfer* The Client transfers User interaction to 719 the GS. 721 5. *User Authentication* The GS authenticates the User. 723 6. *Grant Response* The GS responds with a Grant Response 724 (Section 6.1) including the identity claim from User 725 authentication and interaction.keep:true. 727 7. *Grant Evaluation* The Client queries its User database and finds 728 the User record matching the identity claim, and that no 729 additional claims or authorizations are required. 731 8. *Delete Grant* The Client no longer needs the Grant and decides 732 to Delete Grant (Section 4.5) by sending an HTTP DELETE to the 733 Grant URI. If the GS responds with success the Grant no longer 734 exists. 736 2.8. Create, Discover, and Delete 738 The Client wants to discover if the GS has a User with a given 739 identifier. If not, it will abort the request and not transfer 740 interaction to the GS. 742 +--------+ +-------+ 743 | Client | | GS | 744 | |--(1)--- Create Grant ----------->| | 745 | | user.exists:true | | 746 | | | | 747 | |<--- Interaction Response ---(2)--| | 748 | | user.exists:false | | 749 | | | | 750 | |--(3)--- Delete Grant ----------->| | 751 | |<------- Delete Response ---------| | 752 | | | | 753 +--------+ +-------+ 755 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 756 including an identity claim request, a User identifier, and 757 user.exists:true. The Client sends it with an HTTP POST to the 758 GS GS URI. 760 2. *Interaction Response* The GS sends an Interaction Response 761 (Section 6.2) containing the Grant URI, an interaction object, 762 and user.exists:false. 764 3. *Delete Grant* The Client determines the GS cannot fulfil its 765 Grant Request, and decides to Delete Grant (Section 4.5) by 766 sending an HTTP DELETE to the Grant URI. If the GS responds with 767 success the Grant no longer exists. 769 2.9. Create and Wait 771 The Client wants access to resources that require the GS to interact 772 with the RO, which may not happen immediately, so the GS instructs 773 the Client to wait and check back later. 775 +--------+ +-------+ 776 | Client | | GS | 777 | |--(1)--- Create Grant ----------->| | 778 | | | | 779 | |<---------- Wait Response ---(2)--| | +------+ 780 | (3) | | | | RO | 781 | Wait | | |<--(4)-->| | 782 | | | | AuthZ | | 783 | |--(5)--- Read Grant ------------->| | +------+ 784 | | | | 785 | |<--------- Grant Response --(6)---| | 786 | | | | 787 +--------+ +-------+ 789 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 790 and sends it with an HTTP POST to the GS GS URI. 792 2. *Wait Response* The GS sends an Interaction Response 793 (Section 6.3) containing the Grant URI and wait time. 795 3. *Client Waits* The Client waits the wait time. 797 4. *RO AuthZ* The GS interacts with the RO to determine which 798 identity claims in the Grant Request are to be granted. 800 5. *Read Grant* The Client does an HTTP GET of the Grant URI 801 (Section 4.3). 803 6. *Grant Response* The GS responds with a Grant Response 804 (Section 6.1). 806 2.10. Read Grant 808 The Client wants to re-acquire the identity claims and authorizations 809 in the Grant. No User or RO interaction is required as no new 810 consent or authorization is required. 812 +--------+ +-------+ 813 | Client | | GS | 814 | |--(1)--- Read Grant ------------->| | 815 | | | | 816 | |<--------- Grant Response --(2)---| | 817 | | | | 818 +--------+ +-------+ 820 1. *Read Grant* The Client does an HTTP GET of the Grant URI 821 (Section 4.3). 823 2. *Grant Response* The GS responds with a Grant Response 824 (Section 6.1) containing updated identity claims and 825 authorizations. 827 2.11. Resource Server Access 829 The Client received an AZ URI from the GS. The Client acquires an 830 access token, calls the RS, and later the access token expires. The 831 Client then gets a fresh access token. 833 +--------+ +-------+ 834 | Client | | GS | 835 | |--(1)--- Read AuthZ ---------------------->| | 836 | |<------- AuthZ Response -------------------| | 837 | | | | 838 | | +----------+ | | 839 | | | Resource | | | 840 | |--(2)--- Access Resource --->| Server | | | 841 | |<------- Resource Response --| (RS) | | | 842 | | | | | | 843 | |--(3)--- Access Resource --->| | | | 844 | |<------- Error Response -----| | | | 845 | | | | | | 846 | | +----------+ | | 847 | | | | 848 | |--(4)--- Read AuthZ ---------------------->| | 849 | |<------- AuthZ Response -------------------| | 850 | | | | 851 +--------+ +-------+ 853 1. *Read AuthZ* The Client makes a Read AuthZ (Section 4.7) with an 854 HTTP GET to the AZ URI and receives an Response JSON 855 "authorization" object (Section 6.4.3) with a fresh access token. 857 2. *Resource Request* The Client accesses the RS with the access 858 token per Section 8 and receives a response from the RS. 860 3. *Resource Request* The Client attempts to access the RS, but 861 receives an error indicating the access token has expired. 863 4. *Read AuthZ* The Client makes another Read AuthZ (Section 4.7) 864 with an HTTP GET to the AZ URI and receives an Response JSON 865 "authorization" object (Section 6.4.3) with a fresh access token. 867 2.12. GS API Table 869 +--------------+-----------+--------+-----------------------------+ 870 | request | http verb | uri | response | 871 +==============+===========+========+=============================+ 872 | Create Grant | POST | GS URI | interaction, wait, or grant | 873 +--------------+-----------+--------+-----------------------------+ 874 | Verify Grant | PATCH | Grant | grant | 875 | | | URI | | 876 +--------------+-----------+--------+-----------------------------+ 877 | Read Grant | GET | Grant | wait, or grant | 878 | | | URI | | 879 +--------------+-----------+--------+-----------------------------+ 880 | Update Grant | PUT | Grant | interaction, wait, or grant | 881 | | | URI | | 882 +--------------+-----------+--------+-----------------------------+ 883 | Delete Grant | DELETE | Grant | success | 884 | | | URI | | 885 +--------------+-----------+--------+-----------------------------+ 886 | Read AuthZ | GET | AZ URI | authorization | 887 +--------------+-----------+--------+-----------------------------+ 888 | Update AuthZ | PUT | AZ URI | authorization | 889 +--------------+-----------+--------+-----------------------------+ 890 | Delete AuthZ | DELETE | AZ URI | success | 891 +--------------+-----------+--------+-----------------------------+ 892 | GS Options | OPTIONS | GS URI | metadata | 893 +--------------+-----------+--------+-----------------------------+ 894 | Grant | OPTIONS | Grant | metadata | 895 | Options | | URI | | 896 +--------------+-----------+--------+-----------------------------+ 897 | AuthZ | OPTIONS | AZ URI | metadata | 898 | Options | | | | 899 +--------------+-----------+--------+-----------------------------+ 901 Table 1 903 [ Editor: is there value in an API for listing a Client's Grants? 904 eg:] 906 List Grants GET GS URI JSON array of Grant URIs 908 3. Grant and AuthZ Life Cycle 910 [Editor: straw man for life cycles.] 912 *Grant life Cycle* 913 The Client MAY create, read, update, and delete Grants. A Grant 914 persists until it has expired, is deleted, or another Grant is 915 created for the same GS, Client, and User tuple. 917 At any point in time, there can only be one Grant for the GS, Client, 918 and User tuple. When a Client creates a Grant at the same GS for the 919 same User, the GS MUST invalidate a previous Grant for the Client at 920 that GS for that User. 922 *Authorization Life Cycle* 924 An Authorization are represented by an AZ URI and are MAY be included 925 in a Grant Response "authorization" Object (Section 6.4.3) or as a 926 member of the Grant Response "authorizations" list. If a Client 927 receives an Authorization, the Client MUST be able to do a Read AuthZ 928 request Section 4.7, and MAY be able to update Section 4.8 and delete 929 Section 4.9 depending on GS policy. 931 An Authorization will persist independent of the Grant, and persist 932 until invalidated by the GS per GS policy, or deleted by the Client. 934 4. GS APIs 936 *Client Authentication* 938 All APIs except for GS Options require the Client to authenticate. 940 This document defines the JOSE Authentication mechanism in 941 Section 10. Other mechanisms include [TBD]. 943 4.1. Create Grant 945 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 946 document to the GS URI. 948 The JSON document MUST include the following from the Request JSON 949 Section 4.6: 951 * iat 953 * nonce 955 * uri set to the GS URI 957 * client 959 and MAY include the following from Request JSON Section 4.6 960 * user 962 * interaction 964 * authorization or authorizations 966 * claims 968 The GS MUST respond with one of Grant Response Section 6.1, 969 Interaction Response Section 6.2, Wait Response Section 6.3, or one 970 of the following errors: 972 * TBD 974 from Error Responses Section 9. 976 Following is a non-normative example where the Client wants to 977 interact with the User with a popup and is requesting identity claims 978 about the User and read access to the User's contacts: 980 Example 1 982 { 983 "iat" : 15790460234, 984 "uri" : "https://as.example/endpoint", 985 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 986 "client": { 987 "display": { 988 "name" : "SPA Display Name", 989 "uri" : "https://spa.example/about" 990 } 991 }, 992 "interaction": { 993 "type" : "popup" 994 }, 995 "authorization": { 996 "type" : "oauth_scope", 997 "scope" : "read_contacts" 998 }, 999 "claims": { 1000 "oidc": { 1001 "id_token" : { 1002 "email" : { "essential" : true }, 1003 "email_verified" : { "essential" : true } 1004 }, 1005 "userinfo" : { 1006 "name" : { "essential" : true }, 1007 "picture" : null 1008 } 1009 } 1010 } 1011 } 1013 Following is a non-normative example where the Client is requesting 1014 the GS to keep the interaction with the User after returning the ID 1015 Token so the Client can update the Grant, and is also asking if the 1016 user exists: 1018 Example 2 1020 { 1021 "iat" : 15790460234, 1022 "uri" : "https://as.example/endpoint", 1023 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1024 "client": { 1025 "id" : "di3872h34dkJW" 1026 }, 1027 "interaction": { 1028 "keep" : true, 1029 "type" : "redirect", 1030 "redirect_uri" : "https://web.example/return" 1031 }, 1032 "user": { 1033 "identifiers": { 1034 "email" : "jane.doe@example.com" 1035 }, 1036 "exists" : true 1037 }, 1038 "claims" : { "oidc": { "id_token" : {} } } 1039 } 1041 4.2. Verify Grant 1043 The Client verifies a Grant by doing an HTTP PATCH of a JSON document 1044 to the corresponding Grant URI. 1046 The JSON document MUST contain verification.nonce per Section 4.6.7. 1047 Following is a non-normative example: 1049 { 1050 "verification": { "nonce":"55e8a90f-a563-426d-8c35-d6d8ed54afeb" } 1051 } 1053 The GS MUST respond with one of Grant Response Section 6.1 or one of 1054 the following errors: 1056 * TBD 1058 from Error Responses Section 9. 1060 4.3. Read Grant 1062 The Client reads a Grant by doing an HTTP GET of the corresponding 1063 Grant URI. 1065 The GS MUST respond with one of Grant Response Section 6.1, Wait 1066 Response Section 6.3, or one of the following errors: 1068 * TBD 1070 from Error Responses Section 9. 1072 4.4. Update Grant 1074 The Client updates a Grant by doing an HTTP PUT of a JSON document to 1075 the corresponding Grant URI. 1077 The JSON document MUST include the following from the Request JSON 1078 Section 4.6 1080 * iat 1082 * uri set to the Grant URI 1084 and MAY include the following from Request JSON Section 4.6 1086 * user 1088 * interaction 1090 * authorization or authorizations 1092 * claims 1094 The GS MUST respond with one of Grant Response Section 6.1, 1095 Interaction Response Section 6.2, Wait Response Section 6.3, or one 1096 of the following errors: 1098 * TBD 1100 from Error Responses Section 9. 1102 Following is a non-normative example where the Client made an 1103 interaction.keep:true request, and now wants to update the request 1104 with additional claims: 1106 Example 3 1108 { 1109 "iat" : 15790460234, 1110 "uri" : "https://as.example/endpoint/grant/example3", 1111 "claims": { 1112 "oidc": { 1113 "userinfo" : { 1114 "email" : { "essential" : true }, 1115 "name" : { "essential" : true }, 1116 "picture" : null 1117 } 1118 } 1119 } 1120 } 1122 4.5. Delete Grant 1124 The Client deletes a Grant by doing an HTTP DELETE of the 1125 corresponding Grant URI. 1127 The GS MUST respond with OK 200, or one of the following errors: 1129 * TBD 1131 from Error Responses Section 9. 1133 4.6. Request JSON 1135 [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ] 1137 * *iat* - the time of the request as a NumericDate. 1139 * *nonce* - a unique identifier for this request. Note the Grant 1140 Response MUST contain a matching nonce attribute value. 1142 * *uri* - the GS URI if in a Create Grant Section 4.1, or the Grant 1143 URI if in an Update Grant Section 4.4. 1145 4.6.1. "client" Object 1147 The client object MUST contain either the id attribute for Registered 1148 Clients, or the display object for Dynamic Clients. 1150 * *id* - the Client ID the GS has for the Registered Client. 1152 * *display* - the display object contains the following attributes: 1154 - *name* - a string that represents the Dynamic Client 1156 - *uri* - a URI representing the Dynamic Client 1158 The name and uri will be displayed by the GS when prompting for 1159 authorization. 1161 [Editor: a max length for the name and URI so a GS can reserve 1162 appropriate space?] 1164 4.6.2. "interaction" Object 1166 The interaction object contains the type of interaction the Client 1167 will provide the User. Other attributes 1169 * *keep* - a JSON boolean. If set to the JSON value true, the GS 1170 will not transfer the User interaction back to the Client after 1171 processing the Grant request. The JSON value false is equivalent 1172 to the attribute not being present, and the GS will transfer the 1173 User interaction back to the Client after processing the request. 1174 This attribute is OPTIONAL 1176 * *type* - contains one of the following values: "redirect" or 1177 "indirect". Details in Section 7. This attribute is REQUIRED. 1179 [Editor: do we want this to be an array of types the Client can 1180 support? This would only be the case if the GS is not able to 1181 support all types and negotiation is required. Is that required?] 1183 * *completion_uri* - this attribute is REQUIRED if the type is 1184 "redirect". It is the URI that the Client requests the GS to 1185 redirect the User to after the GS has completed interacting with 1186 the User. If the Client manages session state in URIs, then the 1187 redirect_uri SHOULD contain that state. 1189 * *information_uri* - this attribute is OPTIONAL and is ignored 1190 unless the type is "indirect". This is the URI the Client would 1191 like the GS to redirect the User to after the interaction with the 1192 User is complete. 1194 * *ui_locales* - End-User's preferred languages and scripts for the 1195 user interface, represented as a space-separated list of [RFC5646] 1196 language tag values, ordered by preference. This attribute is 1197 OPTIONAL. 1199 * *verify* - a boolean value. If set to the JSON value true, the GS 1200 will return a nonce value with the Completion URI. 1202 4.6.3. "user" Object 1204 * *exists* - if present, MUST contain the JSON true value. 1205 Indicates the Client requests the GS to return a user.exists value 1206 in an Interaction Response Section 6.2. This attribute is 1207 OPTIONAL, and MAY be ignored by the GS. 1209 * *identifiers* - REQUIRED if the exists attribute is present. The 1210 values MAY be used by the GS to improve the User experience. 1211 Contains one or more of the following identifiers for the User: 1213 - *phone_number* - contains a phone number per Section 5 of 1214 [RFC3966]. 1216 - *email* - contains an email address per [RFC5322]. 1218 - *oidc* - is an object containing both the "iss" and "sub" 1219 attributes from an OpenID Connect ID Token [OIDC] Section 2. 1221 * *claims* - an optional object containing one or more assertions 1222 the Client has about the User. 1224 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 1225 Section 2. 1227 * *reciprocal* - indicates this Grant Request or Update is the 1228 reciprocal of another Grant. Contains the Grant URI of the 1229 reciprocal Grant. 1231 4.6.4. "authorization" Object 1233 * *type* - one of the following values: "oauth_scope" or 1234 "oauth_rich". This attribute is REQUIRED. 1236 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1237 section 3.3. MUST be included if type is "oauth_scope" or 1238 "oauth_rich". 1240 * *authorization_details* - an authorization_details object per 1241 [RAR]. MUST be included if type is "oauth_rich". 1243 [Editor: details may change as the [RAR] document evolves] 1245 4.6.5. "authorizations" Object 1247 A JSON array of "authorization" objects. Only one of "authorization" 1248 or "authorizations" may be in the Request JSON. 1250 [Editor: instead of an array, we could have a Client defined 1251 dictionary of "authorization" objects] 1253 4.6.6. "claims" Object 1255 Includes one or more of the following: 1257 * *oidc* - an object that contains one or both of the following 1258 objects: 1260 - *userinfo* - Claims that will be returned as a JSON object 1262 - *id_token* - Claims that will be included in the returned ID 1263 Token. If the null value, an ID Token will be returned 1264 containing no additional Claims. 1266 The contents of the userinfo and id_token objects are Claims as 1267 defined in [OIDC] Section 5. 1269 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1270 per [OIDC4IA]. 1272 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1273 be requested.] 1275 4.6.7. "verification" Object 1277 The verification Object is used with the Verify Grant Section 4.2. 1279 * *nonce* the Interaction Nonce received from the GS via the 1280 Completion URI. This attribute MUST only be used in the Verify 1281 Grant Section 4.2. 1283 [Editor: parameters for the Client to request it wants the Grant 1284 Response signed and/or encrypted?] 1286 4.7. Read Authorization 1288 The Client acquires an Authorization by doing an HTTP GET to the 1289 corresponding AZ URI. 1291 The GS MUST respond with a Authorization JSON document Section 6.5, 1292 or one of the following errors: 1294 * TBD 1296 from Error Responses Section 9. 1298 4.8. Update Authorization 1300 The Client updates an Authorization by doing an HTTP PUT to the 1301 corresponding AZ URI of the following JSON. All of the following 1302 MUST be included. 1304 * *iat* - the time of the response as a NumericDate. 1306 * *uri* - the AZ URI. 1308 * *authorization* - the new authorization requested per the Request 1309 JSON "authorization" object Section 4.6.4. 1311 The GS MUST respond with a Authorization JSON document Section 6.5, 1312 or one of the following errors: 1314 * TBD 1316 from Error Responses Section 9. 1318 4.9. Delete Authorization 1320 The Client deletes an Authorization by doing an HTTP DELETE to the 1321 corresponding AZ URI. 1323 The GS MUST respond with OK 200, or one of the following errors: 1325 * TBD 1327 from Error Responses Section 9. 1329 4.10. GS Options 1331 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1332 of the corresponding GS URI. This is the only API where the GS MAY 1333 respond to an unauthenticated request. 1335 The GS MUST respond with the the following JSON document: 1337 [Editor: this section is a work in progress] 1339 * *uri* - the GS URI. 1341 * *client_authentication* - an array of the Client Authentication 1342 mechanisms supported by the GS 1344 * *interactions* - an array of the interaction types supported by 1345 the GS. 1347 * *authorization* - an object containing the authorizations the 1348 Client may request from the GS, if any. 1350 - Details TBD 1352 * *claims* - an object containing the identity claims the Client may 1353 request from the GS, if any, and what public keys the claims will 1354 be signed with. 1356 - Details TBD 1358 * *algorithms* - a list of the cryptographic algorithms supported by 1359 the GS. 1361 * *features* - an object containing feature support 1363 - *user_exists* - boolean indicating if user.exists is supported. 1365 - *authorizations* - boolean indicating if a request for multiple 1366 authorizations is supported. 1368 [Editor: keys used by Client to encrypt requests, or verify signed 1369 responses?] 1371 [Editor: namespace metadata for extensions?] 1373 or one of the following errors: 1375 * TBD 1377 from Error Responses Section 9. 1379 4.11. Grant Options 1381 The Client can get the metadata for the Grant by doing an HTTP 1382 OPTIONS of the corresponding Grant URI. 1384 The GS MUST respond with the the following JSON document: 1386 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1388 or one of the following errors: 1390 * TBD 1392 from Error Responses Section 9. 1394 4.12. AuthZ Options 1396 The Client can get the metadata for the AuthZ by doing an HTTP 1397 OPTIONS of the corresponding AZ URI. 1399 The GS MUST respond with the the following JSON document: 1401 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1403 or one of the following errors: 1405 * TBD 1407 from Error Responses Section 9. 1409 4.13. Request Verification 1411 On receipt of a request, the GS MUST verify the following: 1413 * TBD 1415 5. GS Initiated Grant 1417 [Editor: In OAuth 2.0, all flows are initiated at the Client. If the 1418 AS wanted to initiate a flow, it redirected to the Client, that 1419 redirected back to the AS to initiate a flow. 1421 Here is a proposal to support GS initiated: authentication; just-in- 1422 time (JIT) provisioning; and authorization] 1424 *initiation_uri* A URI at the Client that contains no query or 1425 fragment. How the GS learns the Client initiation_uri is out of 1426 scope. 1428 The GS creates a Grant and Grant URI, and redirects the User to the 1429 initiation_uri with the query parameter "grant" and the value of 1430 Grant URI. 1432 See Section 2.5 for the sequence diagram. 1434 6. GS API Responses 1436 6.1. Grant Response 1438 The Grant Response MUST include the following from the Response JSON 1439 Section 6.4 1441 * iat 1442 * nonce 1444 * uri 1446 * expires_in 1448 and MAY include the following from the Response JSON Section 6.4 1450 * authorization or authorizations 1452 * claims 1454 Example non-normative Grant Response JSON document for Example 1 in 1455 Section 4.1: 1457 { 1458 "iat" : 15790460234, 1459 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1460 "uri" : "https://as.example/endpoint/grant/example1", 1461 "expires_in" : 300 1462 "authorization": { 1463 "type" : "oauth_scope", 1464 "scope" : "read_contacts", 1465 "expires_in" : 3600, 1466 "mechanism" : "bearer", 1467 "token" : "eyJJ2D6.example.access.token.mZf9p" 1468 }, 1469 "claims": { 1470 "oidc": { 1471 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1472 "userinfo" : { 1473 "name" : "John Doe", 1474 "picture" : "https://photos.example/p/eyJzdkiO" 1475 } 1476 } 1477 } 1478 } 1480 Example non-normative Grant Response JSON document for Example 2 in 1481 Section 4.1: 1483 { 1484 "iat" : 15790460234, 1485 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1486 "uri" : "https://as.example/endpoint/grant/example2", 1487 "authorization": { 1488 "uri" : "https://as.example/endpoint/authz/example2" 1489 } 1490 } 1492 6.2. Interaction Response 1494 The Interaction Response MUST include the following from the Response 1495 JSON Section 6.4 1497 * iat 1499 * nonce 1501 * uri 1503 * interaction 1505 and MAY include the following from the Response JSON Section 6.4 1507 * user 1509 * wait 1511 A non-normative example of an Interaction Response follows: 1513 { 1514 "iat" : 15790460234, 1515 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1516 "uri" : "https://as.example/endpoint/grant/example4", 1517 "interaction" : { 1518 "type" : "popup", 1519 "authorization_uri" : "https://as.example/popup/example4" 1520 }, 1521 "user": { 1522 "exists" : true 1523 } 1524 } 1526 6.3. Wait Response 1528 The Wait Response MUST include the following from the Response JSON 1529 Section 6.4 1530 * iat 1532 * nonce 1534 * uri 1536 * wait 1538 A non-normative example of Wait Response follows: 1540 { 1541 "iat" : 15790460234, 1542 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1543 "uri" : "https://as.example/endpoint/grant/example5", 1544 "wait" : 300 1545 } 1547 6.4. Response JSON 1549 Details of the JSON document: 1551 * *iat* - the time of the response as a NumericDate. 1553 * *nonce* - the nonce that was included in the Request JSON 1554 Section 4.6. 1556 * *uri* - the Grant URI. 1558 * *wait* - a numeric value representing the number of seconds the 1559 Client should want before making a Read Grant request to the Grant 1560 URI. 1562 * *expires_in* - a numeric value specifying how many seconds until 1563 the Grant expires. This attribute is OPTIONAL. 1565 6.4.1. "interaction" Object 1567 If the GS wants the Client to start the interaction, the GS MUST 1568 return the interaction mechanism provided by the Client in the Grant 1569 Request, and include the required attributes in the interaction 1570 object: 1572 * *type* - this MUST match the type provided by the Client in the 1573 Grant Request client.interaction object. 1575 * *authorization_uri* - the URI to redirect the user to or load in 1576 the popup. Must be included if type is "redirect" 1578 * *display_uri* - the URI to be displayed to the User for them to 1579 navigate to and enter the code. Must be included if type is 1580 "indirect" 1582 * *user_code* - a text string of the code to display to the User. 1583 Must be included if type is "indirect". 1585 * *short_uri* - the URI to show as scannable code. MUST be included 1586 if type is "indirect" 1588 [Editor: do we specify a maximum length for the display_uri and code 1589 so that a device knows the maximum it needs to support? A smart 1590 device may have limited screen real estate.] 1592 The authorization_uri, qr_uri, and user_code MUST be unique and only 1593 match the associated Grant URI. 1595 TBD: entropy and other security considerations for the 1596 authorization_uri, qr_uri, and the user_code. 1598 See Interaction Types Section 7 for details. 1600 6.4.2. "user" Object 1602 * *exists* - a boolean value indicating if the GS has a user with 1603 one or more of the provided identifiers in the Request 1604 user.identifiers object Section 4.6.3 1606 6.4.3. "authorization" Object 1608 The Response JSON authorization object is a subset of the 1609 Authorization JSON Section 6.5. It contains only the AZ URI if the 1610 Client is able to read, update and/or delete the Authorization. 1611 Alternatively, it contains the Authorization JSON excluding the AZ 1612 URI. See Grant Response Section 6.1 for non-normative examples. 1614 6.4.4. "authorizations" Object 1616 A JSON array of authorization objects. Support for the 1617 authorizations object is OPTIONAL. 1619 6.4.5. "claims" Object 1621 The claims object is a response to the Request "claims" object 1622 Section 4.6.4. 1624 * *oidc* 1625 - *id_token* - an OpenID Connect ID Token containing the Claims 1626 the User consented to be released. 1628 - *userinfo* - the Claims the User consented to be released. 1630 Claims are defined in [OIDC] Section 5. 1632 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1633 per [OIDC4IA]. 1635 * *vc* 1637 The verified claims the user consented to be released. [Editor: 1638 details TBD] 1640 6.5. Authorization JSON 1642 The Authorization JSON is a response to a Read AuthZ request by the 1643 Client Section 4.7. A subset of the Authorization JSON is included 1644 in the "authorization" object Section 4.6.4 and "authorizations" list 1645 members Section 6.4.4. 1647 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1648 See the "type" object in Section 4.6.4 for details. 1650 * *scope* - the scopes the Client was granted authorization for. 1651 This will be all, or a subset, of what was requested. This 1652 attribute is OPTIONAL. 1654 * *authorization_details* - the authorization details granted per 1655 [RAR]. Included if type is "oauth_rich". 1657 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1658 "jose+body". See Section 8 for details. 1660 * *token* - the access token for accessing an RS. This attribute is 1661 REQUIRED. 1663 * *expires_in* - a numeric value specifying how many seconds until 1664 the access token expires. This attribute is OPTIONAL. 1666 * *certificate* - MUST be included if the mechanism is "jose" or 1667 "jose+body". Contains the jwk header values for the Client to 1668 include in the JWS header when calling the RS using the "jose" or 1669 "jose+body" mechanisms. See Section 10.2.1. 1671 * *uri* - the AZ URI. Used to get, update, and delete the 1672 authorization. This will be the same URI that was used in a Read 1673 Authorization or Update Authorization request. This attribute is 1674 REQUIRED unless it is in a Response JSON, 1676 [Editor: any value in an expiry for the Authorization?] 1678 The following is a non-normative example of an Authorization JSON 1679 document: 1681 { 1682 "type" : "oauth_scope", 1683 "scope" : "read_calendar write_calendar", 1684 "mechanism" : "jose", 1685 "token" : "eyJJ2D6.example.access.token.mZf9p" 1686 "expires_in" : 3600, 1687 "certificate": { 1688 "x5u" : "https://as.example/cert/example2" 1689 }, 1690 "uri" : "https://as.example/endpoint/authz/example2" 1691 } 1693 6.5.1. Signing and Encryption 1695 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1696 there a generalized description, or is it mechanism specific?] 1698 6.6. Response Verification 1700 On receipt of a response, the Client MUST verify the following: 1702 * TBD 1704 7. Interactions 1706 There are two types of interactions that a Client can initiate with a 1707 GS: redirect and indirect. Extensions may define additional 1708 interaction types. 1710 7.1. Redirect Interaction 1712 A Redirect Interaction is characterized by the GS returning the User 1713 back to the Client that started the interaction. After a redirect 1714 back from the GS, the Client may be able to securely verify the 1715 returning User is the same as the User the Client redirected to the 1716 GS by verifying a unique Completion URI is associated with a browser 1717 cookie set prior to the redirection. Clients that are not able to 1718 securely verify the returning User, or do not want to, verify the 1719 User by making a Verify Grant call to the GS, passing the Interaction 1720 Nonce. The Client signals to the GS that it requires an Interaction 1721 Nonce by setting interaction.verify to true. Following is the 1722 Redirect Interaction sequence: 1724 1. If not interaction.verify, the Client creates a unique 1725 Completion URI. 1727 2. The Client creates a Grant Request setting interaction.type to 1728 "redirect" and interaction.completion_uri to the Completion URI, 1729 and makes a Create Grant request. 1731 3. The GS creates a Grant with a unique Grant URI and Authorization 1732 URI and binds them to the Completion URI. 1734 4. The GS creates an Interaction Response setting interaction.type 1735 to "redirect" and interaction.authorization_uri to the 1736 Authorization URI and returns it to the Client. 1738 5. If not interaction.verify, the Client creates and sets a a 1739 unique completion browser cookie and binds it to the completion 1740 URI. The cookie MUST not be able to be used to derive the 1741 Completion URI. 1743 6. The Client redirects the User's browser to the Authorization URI 1744 using any available browser redirect mechanism. 1746 7. The GS locates the Grant bound to the Authorization URI. 1748 8. The GS interacts with the User. 1750 9. If interaction.verify, the GS creates an Interaction Nonce, 1751 binds it to the Grant, and appends it to the Completion URI as 1752 the "nonce" query parameter. 1754 10. The GS redirects the User's browser to the Completion URI using 1755 any available browser redirect mechanism. 1757 11. If not interaction.verify, the Client confirms the completion 1758 browser cookie is bound to the Completion URI. 1760 12. If interaction.verify, the Client makes a Verify Grant call with 1761 the Interaction Nonce, and the Grant. 1763 A GS MUST support the Redirect Interaction type. 1765 7.2. Indirect Interaction 1767 An Indirect Interaction is characterized by the GS not being able to 1768 return the User back to the Client that started the interaction. 1769 There are two mechanisms for a User to identify the Client's Create 1770 Grant request at the GS: Short URI or User Code. 1772 1. Generation 1774 1. The GS generates a Short URI and User Code unique to the 1775 Grant. 1777 2. The GS sends the Short URI, Code URI, and User Code to the 1778 Client. 1780 2. Display 1782 1. If possible, the Client MAY display the Short URI to the User 1783 as a scannable code such as a [QR_Code]. The User MAY then 1784 scan the image that will open the Short URI on the User's 1785 scanning device. 1787 2. The Client MAY optionally launch a system browser to open the 1788 Short URI. 1790 3. The Client MUST display the User Code and instructions to 1791 enter it at the Code URI. The User MAY navigate a browser on 1792 a separate device to the Code URI. 1794 If the User arrived at the GS via the Short URI, the GS will use the 1795 Short URI to identify the Create Grant request, and then authenticate 1796 the User. 1798 If the User arrived at the GS via the Code URI, the GS will 1799 authenticate the User, and then prompt the User to enter the User 1800 Code, which the GS will then use to identify the Create Grant 1801 request. 1803 [Editor: we may need to include interaction types for iOS and Android 1804 as the mobile OS APIs evolve.] 1806 8. RS Access 1808 This document specifies three different mechanisms for the Client to 1809 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1810 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1811 mechanisms are proof-of-possession mechanisms and are defined in 1812 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1813 possession mechanisms may be defined in other documents. The 1814 mechanism the Client is to use with an RS is the Response JSON 1815 authorization.mechanism attribute Section 6.4.3. 1817 8.1. Bearer Token 1819 If the access mechanism is "bearer", then the Client accesses the RS 1820 per Section 2.1 of [RFC6750] 1822 A non-normative example of the HTTP request headers follows: 1824 GET /calendar HTTP/2 1825 Host: calendar.example 1826 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1828 9. Error Responses 1830 * TBD 1832 10. JOSE Authentication 1834 How the Client authenticates to the GS and RS are independent of each 1835 other. One mechanism can be used to authenticate to the GS, and a 1836 different mechanism to authenticate to the RS. 1838 Other documents that specify other Client authentication mechanisms 1839 will replace this section. 1841 In the JOSE Authentication Mechanism, the Client authenticates by 1842 using its private key to sign a JSON document with JWS per [RFC7515] 1843 which results in a token using JOSE compact serialization. 1845 [Editor: are there advantages to using JSON serialization in the 1846 body?] 1848 Different instances of a Registered Client MAY have different private 1849 keys, but each instance has a certificate to bind its private key to 1850 to a public key the GS has for the Client ID. An instance of a 1851 Client will use the same private key for all signing operations. 1853 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1854 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1856 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1858 The token may be included in an HTTP header, or as the HTTP message 1859 body. 1861 The following sections specify how the Client uses JOSE to 1862 authenticate to the GS and RS. 1864 10.1. GS Access 1866 The Client authenticates to the GS by passing either a signed header 1867 parameter, or a signed message body. The following table shows the 1868 verb, uri and token location for each Client request to the GS: 1870 +---------------+-----------+-----------+----------+ 1871 | request | http verb | uri | token in | 1872 +===============+===========+===========+==========+ 1873 | Create Grant | POST | GS URI | body | 1874 +---------------+-----------+-----------+----------+ 1875 | Verify Grant | PATCH | Grant URI | body | 1876 +---------------+-----------+-----------+----------+ 1877 | Read Grant | GET | Grant URI | header | 1878 +---------------+-----------+-----------+----------+ 1879 | Update Grant | PUT | Grant URI | body | 1880 +---------------+-----------+-----------+----------+ 1881 | Delete Grant | DELETE | Grant URI | header | 1882 +---------------+-----------+-----------+----------+ 1883 | Read AuthZ | GET | AZ URI | header | 1884 +---------------+-----------+-----------+----------+ 1885 | Update AuthZ | PUT | AZ URI | body | 1886 +---------------+-----------+-----------+----------+ 1887 | Delete AuthZ | DELETE | AZ URI | header | 1888 +---------------+-----------+-----------+----------+ 1889 | GS Options | OPTIONS | GS URI | header | 1890 +---------------+-----------+-----------+----------+ 1891 | Grant Options | OPTIONS | Grant URI | header | 1892 +---------------+-----------+-----------+----------+ 1893 | AuthZ Options | OPTIONS | AZ URI | header | 1894 +---------------+-----------+-----------+----------+ 1896 Table 2 1898 10.1.1. Authorization Header 1900 For requests with the token in the header, the JWS payload MUST 1901 contain the following attributes: 1903 *iat* - the time the token was created as a NumericDate. 1905 *jti* - a unique identifier for the token per [RFC7519] section 1906 4.1.7. 1908 *uri* - the value of the URI being called (GS URI, Grant URI, or AZ 1909 URI). 1911 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1912 "OPTIONS") 1914 The HTTP authorization header is set to the "jose" parameter followed 1915 by one or more white space characters, followed by the resulting 1916 token. 1918 A non-normative example of a JWS payload and the HTTP request 1919 follows: 1921 { 1922 "iat" : 15790460234, 1923 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1924 "uri" : "https://as.example/endpoint/grant/example6", 1925 "verb" : "GET" 1926 } 1928 GET /endpoint/example.grant HTTP/2 1929 Host: as.example 1930 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1932 [Editor: make a real example token] 1934 *GS Verification* 1936 The GS MUST verify the token by: 1938 * TBD 1940 10.1.2. Signed Body 1942 For requests with the token in the body, the Client uses the Request 1943 JSON as the payload in a JWS. The resulting token is sent with the 1944 content-type set to "application/jose". 1946 A non-normative example (line breaks added to the body for 1947 readability): 1949 POST /endpoint HTTP/2 1950 Host: as.example 1951 Content-Type: application/jose 1952 Content-Length: 155 1954 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1955 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1956 Jf36POk6yJV_adQssw5c 1958 [Editor: make a real example token] 1960 *GS Verification* 1962 The GS MUST verify the token by: 1964 * TBD 1966 10.1.3. Public Key Resolution 1968 * *Registered Clients* can use any of the JWS header values to 1969 direct the GS to resolve the public key matching the private key 1970 used to the Client ID. The GS MAY restrict with JWS headers a 1971 Client can use. 1973 [Editor: would examples help here so that implementors understand the 1974 full range of options, and how an instance can have its own asymetric 1975 key pair] 1977 A non-normative example of a JOSE header for a Registered Client with 1978 a key identifier of "12": 1980 { 1981 "alg" : "ES256", 1982 "typ" : "JOSE", 1983 "kid" : "12" 1984 } 1986 * *Dynamic Clients* include their public key in the "jwk" JWS 1987 header. 1989 A non-normative example of a JOSE header for a Dynamic Client: 1991 { 1992 "alg" : "ES256", 1993 "typ" : "JOSE", 1994 "jwk" : { 1995 "kty" : "EC", 1996 "crv" : "P-256", 1997 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1998 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1999 } 2000 } 2002 10.2. RS Access 2004 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 2005 include a proof-of-possession token in the HTTP authorization header. 2006 In the "jose+body" mechanism Section 10.2.3, the Client signs the 2007 JSON document in the request if the POST or PUT verbs are used, 2008 otherwise it is the same as the "jose" mechanism. 2010 10.2.1. JOSE header 2012 The GS provides the Client one or more JWS header parameters and 2013 values for a a certificate, or a reference to a certificate or 2014 certificate chain, that the RS can use to resolve the public key 2015 matching the private key being used by the Client. 2017 A non-normative examples JOSE header: 2019 { 2020 "alg" : "ES256", 2021 "typ" : "JOSE", 2022 "x5u" : "https://as.example/cert/example2" 2023 } 2025 [Editor: this enables Dynamic Clients to make proof-of-possession API 2026 calls the same as Registered Clients.] 2028 10.2.2. "jose" Mechanism 2030 The JWS payload MUST contain the following attributes: 2032 *iat* - the time the token was created as a NumericDate. 2034 *jti* - a unique identifier for the token per [RFC7519] section 2035 4.1.7. 2037 *uri* - the value of the RS URI being called. 2039 *verb* - the HTTP verb being used in the call 2041 *token* - the access token provided by the GS to the Client 2043 The HTTP authorization header is set to the "jose" parameter followed 2044 by one or more white space characters, followed by the resulting 2045 token. 2047 A non-normative example of a JWS payload and the HTTP request 2048 follows: 2050 { 2051 "iat" : 15790460234, 2052 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 2053 "uri" : "https://calendar.example/calendar", 2054 "verb" : "GET", 2055 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 2056 } 2058 GET /calendar HTTP/2 2059 Host: calendar.example 2060 Authorization: jose eyJhbG.example.jose.token.adks 2062 [Editor: make a real example token] 2064 *RS Verification* 2066 The RS MUST verify the token by: 2068 * verify access token is bound to the public key - include key 2069 fingerprint in access token? 2071 * TBD 2073 10.2.3. "jose+body" Mechanism 2075 The "jose+body" mechanism can only be used if the content being sent 2076 to the RS is a JSON document. 2078 Any requests not sending a message body will use the "jose" mechanism 2079 Section 10.2.2. 2081 Requests sending a message body MUST have the following JWS payload: 2083 *iat* - the time the token was created as a NumericDate. 2085 *jti* - a unique identifier for the token per [RFC7519] section 2086 4.1.7. 2088 *uri* - the value of the RS URI being called. 2090 *verb* - the HTTP verb being used in the call 2092 *token* - the access token provided by the GS to the Client 2094 *body* - the message body being sent to the RS 2096 A non-normative example of a JWS payload and the HTTP request 2097 follows: 2099 { 2100 "iat" : 15790460234, 2101 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 2102 "uri" : "https://calendar.example/calendar", 2103 "verb" : "POST", 2104 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 2105 "payload" : { 2106 "event" : { 2107 "title" : "meeting with joe", 2108 "start_date_utc" : "2020-02-21 11:00:00", 2109 "end_date_utc" : "2020-02-21 11:00:00" 2110 } 2111 } 2112 } 2114 POST /calendar HTTP/2 2115 Host: calendar.example 2116 Content-Type: application/jose 2117 Content-Length: 155 2119 eyJhbGciOi.example.jose+body.adasdQssw5c 2121 [Editor: make a real example token] 2123 *RS Verification* 2125 The RS MUST verify the token by: 2127 * TBD 2129 10.2.4. Public Key Resolution 2131 The RS has a public key for the GS that it uses to verify the 2132 certificate or certificate chain the Client includes in the JWS 2133 header. 2135 10.3. Request Encryption 2137 [Editor: to be fleshed out] 2139 The Client encrypts a request when ??? using the GS public key 2140 returned as the ??? attribute in GS Options Section 4.10. 2142 10.4. Response Signing 2144 [Editor: to be fleshed out] 2146 The Client verifies a signed response ??? using the GS public key 2147 returned as the ??? attribute in GS Options Section 4.10. 2149 10.5. Response Encryption 2151 [Editor: to be fleshed out] 2153 The Client decrypts a response when ??? using the private key 2154 matching the public key included in the request as the ??? attribute 2155 in Section 4.6. 2157 11. Extensibility 2159 This standard can be extended in a number of areas: 2161 * *Client Authentication Mechanisms* 2163 - An extension could define other mechanisms for the Client to 2164 authenticate to the GS and/or RS such as Mutual TLS or HTTP 2165 Signing. Constrained environments could use CBOR [RFC7049] 2166 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 2167 [RFC8323] instead of HTTP/2. 2169 * *Grant* 2171 - An extension can define new objects in the Grant Request and 2172 Grant Response JSON. 2174 * *Top Level* 2176 - Top level objects SHOULD only be defined to represent 2177 functionality other the existing top level objects and 2178 attributes. 2180 * *"client" Object* 2181 - Additional information about the Client that the GS would 2182 require related to an extension. 2184 * *"user" Object* 2186 - Additional information about the User that the GS would require 2187 related to an extension. 2189 * *"authorization" Object* 2191 - Additional types of authorizations in addition to OAuth 2.0 2192 scopes and RAR. 2194 * *"claims" Object* 2196 - Additional types of identity claims in addition to OpenID 2197 Connect claims and Verified Credentials. 2199 * *Interaction types* 2201 - Additional types of interactions a Client can start with the 2202 User. 2204 * *Continuous Authentication* 2206 - An extension could define a mechanism for the Client to 2207 regularly provide continuous authentication signals and receive 2208 responses. 2210 [Editor: do we specify access token / handle introspection in this 2211 document, or leave that to an extension?] 2213 [Editor: do we specify access token / handle revocation in this 2214 document, or leave that to an extension?] 2216 12. Rational 2218 1. *Why is there only one mechanism for the Client to authenticate 2219 with the GS? Why not support other mechanisms?* 2221 Having choices requires implementers to understand which choice 2222 is preferable for them. Having one default mechanism in the 2223 document for the Client to authenticate simplifies most 2224 implementations. Deployments that have unique characteristics 2225 can select other mechanisms that are preferable in specific 2226 environments. 2228 2. *Why is the default Client authentication JOSE rather than 2229 MTLS?* 2231 MTLS cannot be used today by a Dynamic Client. MTLS requires 2232 the application to have access below what is typically the 2233 application layer, that is often not available on some 2234 platforms. JOSE is done at the application layer. Many GS 2235 deployments will be an application behind a proxy performing 2236 TLS, and there are risks in the proxy passing on the results of 2237 MTLS. 2239 3. *Why is the default Client authentication JOSE rather than HTTP 2240 signing?* 2242 There is currently no widely deployed open standard for HTTP 2243 signing. Additionally, HTTP signing requires passing all the 2244 relevant parts of the HTTP request to downstream services within 2245 an GS that may need to independently verify the Client identity. 2247 4. *What are the advantages of using JOSE for the Client to 2248 authenticate to the GS and a resource?* 2250 Both Registered Clients and Dynamic Clients can have a private 2251 key, eliminating the public Client issues in OAuth 2.0, as a 2252 Dynamic Client can create an ephemeral key pair. Using 2253 asymetric cryptography also allows each instance of a Registered 2254 Client to have its own private key if it can obtain a 2255 certificate binding its public key to the public key the GS has 2256 for the Client. Signed tokens can be passed to downstream 2257 components in a GS or RS to enable independent verification of 2258 the Client and its request. The GS Initiated Sequence Section 5 2259 requires a URL safe parameter, and JOSE is URL safe. 2261 5. *Why does the GS not return parameters to the Client in the 2262 redirect url?* 2264 Passing parameters via a browser redirection is the source of 2265 many of the security risks in OAuth 2.0. It also presents a 2266 challenge for smart devices. In this protocol, the redirection 2267 from the Client to the GS is to enable the GS to interact with 2268 the User, and the redirection back to the Client is to hand back 2269 interaction control to the Client if the redirection was a full 2270 browser redirect. Unlike OAuth 2.0, the identity of the Client 2271 is independent of the URI the GS redirects to. 2273 6. *Why is there not a UserInfo endpoint as there is with OpenID 2274 Connect?* 2275 Since the Client can Read Grant at any time, it get the same 2276 functionality as the UserInfo endpoint, without the Client 2277 having to manage a separate access token and refresh token. If 2278 the Client would like additional claims, it can Update Grant, 2279 and the GS will let the Client know if an interaction is 2280 required to get any of the additional claims, which the Client 2281 can then start. 2283 [Editor: is there some other reason to have the UserInfo 2284 endpoint?] 2286 7. *Why is there still a Client ID?* 2288 The GS needs an identifier to fetch the meta data associated 2289 with a Client such as the name and image to display to the User, 2290 and the policies on what a Client is allowed to do. The Client 2291 ID was used in OAuth 2.0 for the same purpose, which simplifies 2292 migration. Dynamic Clients do not have a Client ID. 2294 8. *Why have both claims and authorizations?* 2296 There are use cases for each that are independent: 2297 authenticating a user and providing claims vs granting access to 2298 a resource. A request for an authorization returns an access 2299 token which may have full CRUD capabilities, while a request for 2300 a claim returns the claim about the User - with no create, 2301 update or delete capabilities. While the UserInfo endpoint in 2302 OIDC may be thought of as a resource, separating the concepts 2303 and how they are requested keeps each of them simpler in the 2304 Editor's opinion. :) 2306 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2307 GS communication in ?*Section 10 2309 Knowing the GS supports HTTP/2 enables a Client to set up a 2310 connection faster. HTTP/2 will be more efficient when Clients 2311 have large numbers of access tokens and are frequently 2312 refreshing them at the GS as there will be less network traffic. 2313 Mandating TLS 1.3 similarly improves the performance and 2314 security of Clients and GS when setting up a TLS connection. 2316 10. *Why do some of the JSON objects only have one child, such as 2317 the identifiers object in the user object in the Grant Request?* 2319 It is difficult to forecast future use cases. Having more 2320 resolution may mean the difference between a simple extension, 2321 and a convoluted extension. 2323 11. *Why is the "iss" included in the "oidc" identifier object? 2324 Would the "sub" not be enough for the GS to identify the User?* 2326 This decouples the GS from the OpenID Provider (OP). The GS 2327 identifier is the GS URI, which is the endpoint at the GS. The 2328 OP issuer identifier will likely not be the same as the GS URI. 2329 The GS may also provide claims from multiple OPs. 2331 12. *Why complicate things with interaction.keep?* 2333 The common sequence has a back and forth between the Client and 2334 the GS, and the Client can update the Grant and have a new 2335 interaction. Keeping the interaction provides a more seamless 2336 user experience where the results from the first request 2337 determine subsequent requests. For example, a common pattern is 2338 to use a GS to authenticate the User at the Client, and to 2339 register the User at the Client using additional claims from the 2340 GS. The Client does not know a priori if the User is a new 2341 User, or a returning User. Asking a returning User to consent 2342 releasing claims they have already provided is a poor User 2343 experience, as is sending the User back to the GS. The Client 2344 requesting identity first enables the Client to get a response 2345 from the GS while the GS is still interacting with the User, so 2346 that the Client can request additional claims only if needed. 2347 Additionally, the claims a Client may want about a User may be 2348 dependent on some initial Claims. For example, if a User is in 2349 a particular country, additional or different Claims my be 2350 required by the Client. 2352 There are also benefits for the GS. Today, a GS usually keeps 2353 track of which claims a Client has requested for a User. 2354 Storing this information for all Clients a User uses may be 2355 undesirable for a GS that does not want to have that information 2356 about the User. Keeping the interaction allows the Client to 2357 track what information it has about the User, and the GS can 2358 remain stateless. 2360 13. *Why is there a "jose+body" RS access mechanism method for the 2361 Client?*Section 10.2.3 2363 There are numerous use cases where the RS wants non-repudiation 2364 and providence of the contents of an API call. For example, the 2365 UGS Service Supplier Framework for Authentication and 2366 Authorization [UTM]. 2368 14. *Why use URIs to instead of handles for the Grant and 2369 Authorization?* 2370 A URI is an identifier just like a handle that can contain GS 2371 information that is opaque to the Client - so it has all the 2372 features of a handle, plus it can be the URL that is resolved to 2373 manipulate a Grant or an Authorization. As the Grant URI and AZ 2374 URI are defined to start with the GS URI, the Client (and GS) 2375 can easily determine which GS a Grant or Authorization belong 2376 to. URIs also enable a RESTful interface to the GS 2377 functionality. 2379 15. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 2380 known mechanism?* 2382 Having the GS URI endpoint respond to the metadata allows the GS 2383 to provide Client specific results using the same Client 2384 authentication used for other requests to the GS. It also 2385 reduces the risk of a mismatch between what the advertised 2386 metadata, and the actual metadata. A .well-known discovery 2387 mechanism may be defined to resolve from a hostname to the GS 2388 URI. 2390 16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AZ URI?* 2392 Maybe there are no use cases for them [that the editor knows 2393 of], but the GS can not implement, and they are available if use 2394 cases come up. 2396 17. *Why list explicit interactions, instead of the Client and GS 2397 negotiating interaction capabilities?* 2399 The Client knows what interactions it is capable of, and 2400 prefers. Telling the GS the interaction allows the GS to know 2401 what interaction the User will have. Knowing how the Client 2402 will transition the interaction will enable the GS to provider a 2403 better User experience. For example, the GS may want to provide 2404 a short URL if it knows the Client will be showing a QR code vs 2405 a redirect, or have a different layout if it is a popup vs a 2406 redirect. 2408 [Editor: are there use cases where the Client would want to 2409 provide a list of interaction types so the GS can select which 2410 one it can support? ] 2412 13. Acknowledgments 2414 This draft derives many of its concepts from Justin Richer's 2415 Transactional Authorization draft [TxAuth]. 2417 Additional thanks to Justin Richer and Annabelle Richard Backman for 2418 their strong critique of earlier drafts. 2420 14. IANA Considerations 2422 [ JOSE parameter for Authorization HTTP header ] 2424 TBD 2426 15. Security Considerations 2428 TBD 2430 16. References 2432 16.1. Normative References 2434 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2435 Requirement Levels", BCP 14, RFC 2119, 2436 DOI 10.17487/RFC2119, March 1997, 2437 . 2439 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2440 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2441 . 2443 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2444 DOI 10.17487/RFC5322, October 2008, 2445 . 2447 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2448 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2449 . 2451 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2452 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2453 September 2009, . 2455 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2456 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2457 . 2459 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2460 Framework: Bearer Token Usage", RFC 6750, 2461 DOI 10.17487/RFC6750, October 2012, 2462 . 2464 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2465 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2466 2015, . 2468 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2469 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2470 . 2472 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2473 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2474 . 2476 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2477 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2478 DOI 10.17487/RFC7540, May 2015, 2479 . 2481 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2482 Interchange Format", STD 90, RFC 8259, 2483 DOI 10.17487/RFC8259, December 2017, 2484 . 2486 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2487 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2488 . 2490 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2491 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2492 . 2494 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2495 Assurance 1.0", October 2019, . 2498 16.2. Informative References 2500 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2501 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2502 October 2013, . 2504 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2505 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2506 . 2508 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2509 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2510 . 2512 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2513 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2514 Application Protocol) over TCP, TLS, and WebSockets", 2515 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2516 . 2518 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2519 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2520 DOI 10.17487/RFC8628, August 2019, 2521 . 2523 [browser_based_apps] 2524 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2525 Apps", September 2019, . 2528 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2529 Rich Authorization Requests", January 2020, 2530 . 2532 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2533 Credentials Data Model 1.0", November 2019, 2534 . 2536 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2537 identification and data capture techniques - QR Code bar 2538 code symbology specification", February 2015, 2539 . 2541 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2542 . 2545 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2546 Supplier Framework for Authentication and AuthN", 2547 September 2019, . 2550 Appendix A. Document History 2552 A.1. draft-hardt-xauth-protocol-00 2554 * Initial version 2556 A.2. draft-hardt-xauth-protocol-01 2558 * text clean up 2559 * added OIDC4IA claims 2561 * added "jws" method for accessing a resource. 2563 * renamed Initiation Request -> Grant Request 2565 * renamed Initiation Response -> Interaction Response 2567 * renamed Completion Request -> Authorization Request 2569 * renamed Completion Response -> Grant Request 2571 * renamed completion handle -> authorization handle 2573 * added Authentication Request, Authentication Response, 2574 authentication handle 2576 A.3. draft-hardt-xauth-protocol-02 2578 * major rewrite 2580 * handles are now URIs 2582 * the collection of claims and authorizations are a Grant 2584 * an Authorization is its own type 2586 * lots of sequences added 2588 A.4. draft-hardt-xauth-protocol-03 2590 * fixed RO definition 2592 * improved language in Rationals 2594 * added user code interaction method, and aligned qrcode interaction 2595 method 2597 * added completion_uri for code flows 2599 A.5. draft-hardt-xauth-protocol-04 2601 * renamed interaction uris to have purpose specific names 2603 A.6. draft-hardt-xauth-protocol-05 2605 * separated claims from identifiers in request user object 2606 * simplified reciprocal grant flow 2608 * reduced interactions to redirect and indirect 2610 * simplified interaction parameters 2612 * added in language for Client to verify interaction completion 2614 * added Verify Grant API and Interaction Nonce 2616 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 2617 operation. 2619 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2621 *Changed Features* 2623 The major changes between this protocol and OAuth 2.0 and OpenID 2624 Connect are: 2626 * The Client allows uses a private key to authenticate in this 2627 protocol instead of the client secret in OAuth 2.0 and OpenID 2628 Connect. 2630 * The Client initiates the protocol by making a signed request 2631 directly to the GS instead of redirecting the User to the GS. 2633 * The Client does not pass any parameters in redirecting the User to 2634 the GS, and optionally only receives an interaction nonce in the 2635 redirection back from the GS. 2637 * The refresh_token has been replaced with a AZ URI that both 2638 represents the authorization, and is the URI for obtaining a fresh 2639 access token. 2641 * The Client can request identity claims to be returned independent 2642 of the ID Token. There is no UserInfo endpoint to query claims as 2643 there is in OpenID Connect. 2645 * The GS URI is the token endpoint. 2647 *Preserved Features* 2649 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2650 tokens of OAuth 2.0. 2652 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2653 Connect. 2655 * No change is required by the Client or the RS for accessing 2656 existing bearer token protected APIs. 2658 *New Features* 2660 * A Grant represents both the user identity claims and RS access 2661 granted to the Client. 2663 * The Client can verify, update, retrieve, and delete a Grant. 2665 * The GS can initiate a flow by creating a Grant and redirecting the 2666 User to the Client with the Grant URI. 2668 * The Client can discovery if a GS has a User with an identifier 2669 before the GS interacts with the User. 2671 * The Client can request the GS to first authenticate the User and 2672 return User identity claims, and then the Client can update Grant 2673 request based on the User identity. 2675 * Support for scannable code initiated interactions. 2677 * Each Client instance can have its own private / public key pair. 2679 * Highly extensible per Section 11. 2681 Author's Address 2683 Dick Hardt (editor) 2684 SignIn.Org 2685 United States 2687 Email: dick.hardt@gmail.com