idnits 2.17.1 draft-hardt-xauth-protocol-06.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 (22 March 2020) is 1467 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 942, but not defined == Unused Reference: 'RFC7516' is defined on line 2454, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- 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) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 22 March 2020 5 Expires: 23 September 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-06 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 23 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 . . . . . . . . . . . . . . . . . . . . . 53 139 15. Security Considerations . . . . . . . . . . . . . . . . . . . 53 140 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 141 16.1. Normative References . . . . . . . . . . . . . . . . . . 53 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 A.7. draft-hardt-xauth-protocol-06 . . . . . . . . . . . . . . 57 151 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 58 152 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 59 154 1. Introduction 156 This protocol supports the widely deployed use cases supported by 157 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 158 extension of OAuth 2.0, as well as other extensions, and other use 159 cases that are not supported, such as acquiring multiple access 160 tokens at the same time, and updating the request during user 161 interaction. This protocol also addresses many of the security 162 issues in OAuth 2.0 by having parameters securely sent directly 163 between parties, rather than via a browser redirection. 165 The technology landscape has changed since OAuth 2.0 was initially 166 drafted. More interactions happen on mobile devices than PCs. 167 Modern browsers now directly support asymetric cryptographic 168 functions. Standards have emerged for signing and encrypting tokens 169 with rich payloads (JOSE) that are widely deployed. 171 Additional use cases are now being served with extensions to OAuth 172 2.0: OpenID Connect added support for authentication and releasing 173 identity claims; [RFC8252] added support for native apps; [RFC8628] 174 added support for smart devices; and support for [browser_based_apps] 175 is being worked on. There are numerous efforts on adding proof-of- 176 possession to resource access. 178 This protocol simplifies the overall architectural model, takes 179 advantage of today's technology landscape, provides support for all 180 the widely deployed use cases, and offers numerous extension points. 182 While this protocol is not backwards compatible with OAuth 2.0, it 183 strives to minimize the migration effort. 185 This protocol centers around a Grant, a representation of the 186 collection of user identity claims and/or resource authorizations the 187 Client is requesting, and the resulting identity claims and/or 188 resource authorizations granted by the Grant Server. 190 [Editor: suggestions on how to improve this are welcome!] 192 [Editor: suggestions for other names than XAuth are welcome!] 194 1.1. Parties 196 The parties and their relationships to each other: 198 +--------+ +------------+ 199 | User | | Resource | 200 | | | Owner (RO) | 201 +--------+ +------------+ 202 | \ / | 203 | \ / | 204 | \ / | 205 | \ / | 206 +--------+ +---------------+ +------------+ 207 | Client |---->| Grant | _ _ | Resource | 208 | |<----| Server (GS) | | Server | 209 | | +---------------+ | (RS) | 210 | |-------------------------->| | 211 | |<--------------------------| | 212 +--------+ +------------+ 214 * *User* - the person interacting with the Client who has delegated 215 access to identity claims about themselves to the Grant Server 216 (GS), and can authenticate at the GS. 218 * *Client* - requests a Grant from the GS to access one or more 219 Resource Servers (RSs), and/or identity claims about the User. 220 The Client can create, verify, retrieve, update, and delete a 221 Grant. When a Grant is created, the Client receives from the GS 222 the granted access token(s) for the RS(s), and identity claims 223 about the User. The Client uses an access token to access the RS. 224 There are two types of Clients: Registered Clients and Dynamic 225 Clients. All Clients have a key to authenticate with the Grant 226 Server. 228 * *Registered Client* - a Client that has registered with the GS and 229 has a Client ID to identify itself, and can prove it possesses a 230 key that is linked to the Client ID. The GS may have different 231 policies for what different Registered Clients can request. A 232 Registered Client MAY be interacting with a User. 234 * *Dynamic Client* - a Client that has not been registered with the 235 GS, and each instance will generate it's own key pair so it can 236 prove it is the same instance of the Client on subsequent 237 requests, and to requests of a Resource Server that require proof- 238 of-possession access. A single-page application with no active 239 server component is an example of a Dynamic Client. A Dynamic 240 Client MUST be interacting with a User. 242 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 243 release of identity claims about the User. The GS may require 244 explicit consent from the RO or User to provide these to the 245 Client. A GS may support Registered Clients and/or Dynamic 246 Clients. The GS is a combination of the Authorization Server (AS) 247 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 249 * *Resource Server* (RS) - has API resources that require an access 250 token from the GS. Some, or all of the resources are owned by the 251 Resource Owner. 253 * *Resource Owner* (RO) - owns resources at the RS, and has 254 delegated RS access management to the GS. The RO may be the same 255 entity as the User, or may be a different entity that the GS 256 interacts with independently. GS and RO interactions are out of 257 scope of this document. 259 1.2. Reused Terms 261 * *access token* - an access token as defined in [RFC6749] 262 Section 1.4. 264 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 265 issued by the GS, or by other issuers. 267 * *Client ID* - a GS unique identifier for a Registered Client as 268 defined in [RFC6749] Section 2.2. 270 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 272 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 274 * *authN* - short for authentication. 276 * *authZ* - short for authorization. 278 1.3. New Terms 280 * *GS URI* - the endpoint at the GS the Client calls to create a 281 Grant, and is the unique identifier for the GS. 283 * *Grant* - the user identity claims and/or RS authorizations the GS 284 has granted to the Client. 286 * *Grant URI* - the URI that represents the Grant. The Grant URI 287 MUST start with the GS URI. 289 * *Authorization* - the access granted by the RO to the Client. 290 Contains an access token. 292 * *Authorization URI* (AZ URI) - the URI that represents the 293 Authorization the Client was granted by the RO. The AZ URI MUST 294 start with the GS URI. The AZ URI is used to read, update, and 295 delete an access token. 297 * *Redirect Interaction* - characterized by the GS returning the 298 User back to the Client that started the interaction. 300 * *Indirect Interaction* - characterized by the GS not being able to 301 return the User back to the Client that started the interaction. 303 * *Redirect URI* - a URI at the GS that the Client will redirect the 304 User to in a Redirect Interaction. This URI is unique is unique 305 to an outstanding Create Grant request. 307 * *Completion URI* - the URI at the Client that the GS will redirect 308 the User back to in a Redirect Interaction. If the Client has not 309 set the interaction.verify flag, this URI is unique to the Create 310 Grant request made by the Client. 312 * *Information URI* - the URI the GS will redirect the User to after 313 an Indirect Interaction. 315 * *Short URI* - a URI at the GS that is used in Indirect 316 Interactions. The URI may be presented to the User as a scannable 317 code, or loaded in a system browser by the Client. The URI has a 318 maximum length of TBD bytes, and is unique to an outstanding 319 Create Grant request. 321 * *Code URI* - a URI at the GS presented to the User by the Client 322 for the User to enter the User Code in an Indirect Interaction. 324 * *User Code* - a string generated by the GS that is is unique to an 325 outstanding Create Grant request in an Indirect Interaction. 327 1.4. Notational Conventions 329 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 330 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 331 specification are to be interpreted as described in [RFC2119]. 333 Certain security-related terms are to be understood in the sense 334 defined in [RFC4949]. These terms include, but are not limited to, 335 "attack", "authentication", "authorization", "certificate", 336 "confidentiality", "credential", "encryption", "identity", "sign", 337 "signature", "trust", "validate", and "verify". 339 Unless otherwise noted, all the protocol parameter names and values 340 are case sensitive. 342 Some protocol parameters are parts of a JSON document, and are 343 referred to in JavaScript notation. For example, foo.bar refers to 344 the "bar" boolean attribute in the "foo" object in the following 345 example JSON document: 347 { 348 "foo" : { 349 "bar": true 350 } 351 } 353 2. Sequences 355 Before any sequence, the Client needs to be manually or 356 programmatically configured for the GS. See GS Options Section 4.10 357 for details on acquiring GS metadata. 359 [Editor: a plethora of sequences are included to illustrate all the 360 different use cases that are supported. Many sequences are similar, 361 and show a slightly different sequence that can support different use 362 cases. These could potentially be moved to a use case document in 363 the future.] 365 2.1. Create and Verify Grant 367 A Dynamic Client wants a Grant from the User using a Redirect 368 Interaction: 370 +--------+ +-------+ 371 | Client | | GS | 372 | |--(1)--- Create Grant ----------->| | 373 | | | | 374 | |<--- Interaction Response ---(2)--| | +------+ 375 | | | | | User | 376 | |--(3)--- Interaction Transfer --- | - - - | ------->| | 377 | | | | | | 378 | | | |<--(4)-->| | 379 | | | | authN | | 380 | | | |<--(5)-->| | 381 | | | | authZ | | 382 | |<--- Interaction Transfer ---(6)- | - - - | --------| | 383 | | | | | | 384 | |--(7)--- Verify Grant ----------->| | +------+ 385 | | | | 386 | |<--------- Grant Response ---(8)--| | 387 | | | | 388 +--------+ +-------+ 390 1. *Create Grant* The Client creates a Request JSON document 391 Section 4.6 and makes a Create Grant request (Section 4.1) by 392 sending the JSON with an HTTP POST to the GS URI. 394 2. *Interaction Response* The GS determines that interaction with 395 the User is required and sends an Interaction Response 396 (Section 6.2) containing the Grant URI and an interaction object. 398 3. *Interaction Transfer* The Client redirects the User to the 399 Redirect URI at the GS. 401 4. *User Authentication* The GS authenticates the User. 403 5. *User Authorization* If required, the GS interacts with the User 404 to determine which identity claims and/or authorizations in the 405 Grant Request are to be granted. 407 6. *Interaction Transfer* The GS redirects the User to the 408 Completion URI at the Client, passing an Interaction Nonce. 410 7. *Read Grant* The Client creates a JSON document containing a 411 verification object Section 4.6.7 and does a Verify Grant 412 Section 4.2 request by HTTP PATCH with the document to the Grant 413 URI. 415 8. *Grant Response* The GS responds with a Grant Response 416 (Section 6.1). 418 2.2. Create and Read Grant - Redirect 420 A Registered Client wants a Grant from the User using a Redirect 421 Interaction: 423 +--------+ +-------+ 424 | Client | | GS | 425 | |--(1)--- Create Grant ----------->| | 426 | | | | 427 | |<--- Interaction Response ---(2)--| | 428 | | | | 429 | |--(3)--- Read Grant ------------->| | +------+ 430 | | | | | User | 431 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 432 | | | | | | 433 | | | |<--(5)-->| | 434 | | | | authN | | 435 | | | |<--(6)-->| | 436 | | | | authZ | | 437 | |<--------- Grant Response ---(7)--| | | | 438 | | | | | | 439 | |<--- Interaction Transfer ---(8)- | - - - | --------| | 440 | | | | | | 441 +--------+ +-------+ +------+ 443 1. *Create Grant* The Client makes a Create Grant request 444 (Section 4.1) to the GS URI. 446 2. *Interaction Response* The GS determines that interaction with 447 the User is required and sends an Interaction Response 448 (Section 6.2) containing the Grant URI and an interaction object. 450 3. *Read Grant* The Client does an HTTP GET of the Grant URI 451 (Section 4.3). 453 4. *Interaction Transfer* The Client transfers User interaction to 454 the GS. 456 5. *User Authentication* The GS authenticates the User. 458 6. *User Authorization* If required, the GS interacts with the User 459 to determine which identity claims and/or authorizations in the 460 Grant Request are to be granted. 462 7. *Grant Response* The GS responds with a Grant Response 463 (Section 6.1). 465 8. *Interaction Transfer* The GS redirects the User to the 466 Completion URI of the Client. The Client verifies it is the same 467 User that it transferred to the GS. 469 2.3. Create and Read Grant - Indirect 471 A Registered Client wants a Grant from the User using an Indirect 472 Interaction: 474 +--------+ +-------+ 475 | Client | | GS | 476 | |--(1)--- Create Grant ----------->| | 477 | | | | 478 | |<--- Interaction Response ---(2)--| | 479 | | | | 480 | |--(3)--- Read Grant ------------->| | +------+ 481 | | | | | User | 482 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 483 | | | | | | 484 | | | |<--(5)-->| | 485 | | | | authN | | 486 | | | |<--(6)-->| | 487 | | | | authZ | | 488 | |<--------- Grant Response ---(7)--| | | | 489 +--------+ | | | | 490 | | | | 491 +--------+ | | | | 492 | Info |<--- Interaction Transfer ---(8)- | - - - | --------| | 493 | Server | | | | | 494 +--------+ +-------+ +------+ 496 The sequence is the same except: 498 * In step (4) the User either scans a bar code or uses a separate 499 device to navigate to the Code URI and enters the User Code. 501 * In step (8) the GS redirects the User to the Information URI 502 provided by the Client. 504 2.4. Reciprocal Grant 506 Party A and Party B are both a Client and a GS, and each Client would 507 like a Grant for the other GS. The sequence starts off the same as 508 in Section 2.2, but Party B makes a Create Grant Request before 509 sending a Grant Response: 511 Party A Party B 512 +--------+ +--------+ 513 | Client | | GS | 514 ~ ~ ~ ~ ~ ~ Same as steps 1 - 6 of ~ ~ ~ ~ ~ ~ 515 +------+ | | Create and Read Grant above | | 516 | User | | | | | 517 | | | GS |<--------- Create Grant ---(1)---| Client | 518 | | | | | | 519 | | | |<------- Grant Response ---(2)---| | 520 | | | | | | 521 | |<----- | - - - | -- Interaction Transfer --(3)---| | 522 | | | | | | 523 | |<-(4)->| | | | 524 | | AuthZ | | | | 525 +------+ | GS |--(5)--- Grant Response -------->| Client | 526 | | | | 527 +--------+ +--------+ 529 1. *Create Grant* Party B creates a Grant Request (Section 4.1) with 530 user.reciprocal set to the Party B Grant URI that will be in the 531 step (2) Grant Response, and sends it with an HTTP POST to the 532 Party A GS URI. This enables Party A to link the reciprocal 533 Grants. 535 2. *Grant Response* Party B responds to Party A's Create Grant 536 Request with a Grant Response that includes the Party B Grant 537 URI. 539 3. *Interaction Transfer* Party B redirects the User to the 540 Completion URI at Party A. 542 4. *User Authorization* If required, Party A interacts with the User 543 to determine which identity claims and/or authorizations in Party 544 B's Create Grant Request are to be granted. 546 5. *Grant Response* Party A responds with a Grant Response 547 (Section 6.1). 549 2.5. GS Initiated Grant 551 The User is at the GS, and wants to interact with a Registered 552 Client. The GS can redirect the User to the Client: 554 +--------+ +-------+ +------+ 555 | Client | | GS | | User | 556 | | | |<--(1)-->| | 557 | | | | | | 558 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 559 | (3) | | | | | 560 | verify |--(4)--- Read Grant ------------->| | +------+ 561 | | | | 562 | |<--------- Grant Response --(5)---| | 563 | | | | 564 +--------+ +-------+ 566 1. *User Interaction* The GS interacts with the User to determine 567 the Client and what identity claims and authorizations to 568 provide. The GS creates a Grant and corresponding Grant URI. 570 2. *GS Initiated Redirect* The GS redirects the User to the Client's 571 interaction_uri, adding a query parameter with the name "Grant 572 URI" and the value being the URL encoded Grant URI. 574 3. *Client Verification* The Client verifies the Grant URI is from 575 an GS the Client trusts, and starts with the GS GS URI. 577 4. *Read Grant* The Client does an HTTP GET of the Grant URI 578 (Section 4.3). 580 5. *Grant Response* The GS responds with a Grant Response 581 (Section 6.1). 583 See Section 5 for more details. 585 2.6. Create and Update 587 The Client requests an identity claim to determine who the User is. 588 Once the Client learns who the User is, and the Client updates the 589 Grant for additional identity claims which the GS prompts the User 590 for and returns to the Client. Once those are received, the Client 591 updates the Grant with the remaining identity claims required. 593 +--------+ +-------+ 594 | Client | | GS | 595 | |--(1)--- Create Grant ----------->| | 596 | | interaction.keep:true | | 597 | | | | 598 | |<--- Interaction Response ---(2)--| | 599 | | | | 600 | |--(3)--- Read Grant ------------->| | +------+ 601 | | | | | User | 602 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 603 | | | | | | 604 | | | |<--(5)-->| | 605 | | | | authN | | 606 | |<--------- Grant Response ---(6)--| | | | 607 | (7) | | | | | 608 | eval |--(8)--- Update Grant ----------->| | | | 609 | | interaction.keep:true | |<--(9)-->| | 610 | | | | authZ | | 611 | |<--------- Grant Response --(10)--| | | | 612 | (11) | | | | | 613 | eval |--(12)-- Update Grant ----------->| | | | 614 | | interaction.keep:false | |<--(13)->| | 615 | | | | authZ | | 616 | | | | | | 617 | |<--- Interaction Transfer --(14)- | - - - | --------| | 618 | | | | | | 619 | |<--------- Grant Response --(15)--| | +------+ 620 | | | | 621 +--------+ +-------+ 623 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 624 including an identity claim and interaction.keep:true, and sends 625 it with an HTTP POST to the GS GS URI. 627 2. *Interaction Response* The GS sends an Interaction Response 628 (Section 6.2) containing the Grant URI, an interaction object, 629 and interaction.keep:true. 631 3. *Read Grant* The Client does an HTTP GET of the Grant URI 632 (Section 4.3). 634 4. *Interaction Transfer* The Client transfers User interaction to 635 the GS. 637 5. *User Authentication* The GS authenticates the User. 639 6. *Grant Response* The GS responds with a Grant Response 640 (Section 6.1) including the identity claim from User 641 authentication and interaction.keep:true. 643 7. *Grant Evaluation* The Client queries its User database and does 644 not find a User record matching the identity claim. 646 8. *Update Grant* The Client creates an Update Grant Request 647 (Section 4.4) including the initial identity claims required and 648 interaction.keep:true, and sends it with an HTTP PUT to the 649 Grant URI. 651 9. *User AuthN* The GS interacts with the User to determine which 652 identity claims in the Update Grant Request are to be granted. 654 10. *Grant Response* The GS responds with a Grant Response 655 (Section 6.1) including the identity claims released by the User 656 and interaction.keep:true. 658 11. *Grant Evaluation* The Client evaluates the identity claims in 659 the Grant Response and determines the remaining User identity 660 claim required. 662 12. *Update Grant* The Client creates an Update Grant Request 663 (Section 4.4) including the remaining required identity claims 664 and interaction.keep:false, and sends it with an HTTP PUT to the 665 Grant URI. 667 13. *User AuthZ* The GS interacts with the User to determine which 668 identity claims in the Update Grant Request are to be granted. 670 14. *Interaction Transfer* The GS transfers User interaction to the 671 Client. 673 15. *Grant Response* The GS responds with a Grant Response 674 (Section 6.1) including the identity claims released by the 675 User. 677 2.7. Create and Delete 679 The Client requests an identity claim to determine who the User is. 680 Once the Client learns who the User is, and the Client knows it 681 already has all the identity claims and authorizations needed for the 682 User, the Client deletes the Grant which prompts the GS to transfer 683 the interaction back to the Client. (If the Client did not already 684 have what was needed, the Client would follow the Create and Update 685 sequence Section 2.6 ) 686 +--------+ +-------+ 687 | Client | | GS | 688 | |--(1)--- Create Grant ----------->| | 689 | | interaction.keep:true | | 690 | | | | 691 | |<--- Interaction Response ---(2)--| | 692 | | | | 693 | |--(3)--- Read Grant ------------->| | +------+ 694 | | | | | User | 695 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 696 | | | | | | 697 | | | |<--(5)-->| | 698 | | | | authN | | 699 | |<--------- Grant Response ---(6)--| | | | 700 | (7) | | | | | 701 | eval |--(8)--- Delete Grant ----------->| | | | 702 | |<------- Delete Response ---------| | | | 703 | | | | | | 704 | |<--- Interaction Transfer ---(9)- | - - - | --------| | 705 | | | | | | 706 +--------+ +-------+ +------+ 708 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 709 including an identity claim and interaction.keep:true, and sends 710 it with an HTTP POST to the GS GS URI. 712 2. *Interaction Response* The GS sends an Interaction Response 713 (Section 6.2) containing the Grant URI, an interaction object, 714 and interaction.keep:true. 716 3. *Read Grant* The Client does an HTTP GET of the Grant URI 717 (Section 4.3). 719 4. *Interaction Transfer* The Client transfers User interaction to 720 the GS. 722 5. *User Authentication* The GS authenticates the User. 724 6. *Grant Response* The GS responds with a Grant Response 725 (Section 6.1) including the identity claim from User 726 authentication and interaction.keep:true. 728 7. *Grant Evaluation* The Client queries its User database and finds 729 the User record matching the identity claim, and that no 730 additional claims or authorizations are required. 732 8. *Delete Grant* The Client no longer needs the Grant and decides 733 to Delete Grant (Section 4.5) by sending an HTTP DELETE to the 734 Grant URI. If the GS responds with success the Grant no longer 735 exists. 737 2.8. Create, Discover, and Delete 739 The Client wants to discover if the GS has a User with a given 740 identifier. If not, it will abort the request and not transfer 741 interaction to the GS. 743 +--------+ +-------+ 744 | Client | | GS | 745 | |--(1)--- Create Grant ----------->| | 746 | | user.exists:true | | 747 | | | | 748 | |<--- Interaction Response ---(2)--| | 749 | | user.exists:false | | 750 | | | | 751 | |--(3)--- Delete Grant ----------->| | 752 | |<------- Delete Response ---------| | 753 | | | | 754 +--------+ +-------+ 756 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 757 including an identity claim request, a User identifier, and 758 user.exists:true. The Client sends it with an HTTP POST to the 759 GS GS URI. 761 2. *Interaction Response* The GS sends an Interaction Response 762 (Section 6.2) containing the Grant URI, an interaction object, 763 and user.exists:false. 765 3. *Delete Grant* The Client determines the GS cannot fulfil its 766 Grant Request, and decides to Delete Grant (Section 4.5) by 767 sending an HTTP DELETE to the Grant URI. If the GS responds with 768 success the Grant no longer exists. 770 2.9. Create and Wait 772 The Client wants access to resources that require the GS to interact 773 with the RO, which may not happen immediately, so the GS instructs 774 the Client to wait and check back later. 776 +--------+ +-------+ 777 | Client | | GS | 778 | |--(1)--- Create Grant ----------->| | 779 | | | | 780 | |<---------- Wait Response ---(2)--| | +------+ 781 | (3) | | | | RO | 782 | Wait | | |<--(4)-->| | 783 | | | | AuthZ | | 784 | |--(5)--- Read Grant ------------->| | +------+ 785 | | | | 786 | |<--------- Grant Response --(6)---| | 787 | | | | 788 +--------+ +-------+ 790 1. *Create Grant* The Client creates a Grant Request (Section 4.1) 791 and sends it with an HTTP POST to the GS GS URI. 793 2. *Wait Response* The GS sends an Interaction Response 794 (Section 6.3) containing the Grant URI and wait time. 796 3. *Client Waits* The Client waits the wait time. 798 4. *RO AuthZ* The GS interacts with the RO to determine which 799 identity claims in the Grant Request are to be granted. 801 5. *Read Grant* The Client does an HTTP GET of the Grant URI 802 (Section 4.3). 804 6. *Grant Response* The GS responds with a Grant Response 805 (Section 6.1). 807 2.10. Read Grant 809 The Client wants to re-acquire the identity claims and authorizations 810 in the Grant. No User or RO interaction is required as no new 811 consent or authorization is required. 813 +--------+ +-------+ 814 | Client | | GS | 815 | |--(1)--- Read Grant ------------->| | 816 | | | | 817 | |<--------- Grant Response --(2)---| | 818 | | | | 819 +--------+ +-------+ 821 1. *Read Grant* The Client does an HTTP GET of the Grant URI 822 (Section 4.3). 824 2. *Grant Response* The GS responds with a Grant Response 825 (Section 6.1) containing updated identity claims and 826 authorizations. 828 2.11. Resource Server Access 830 The Client received an AZ URI from the GS. The Client acquires an 831 access token, calls the RS, and later the access token expires. The 832 Client then gets a fresh access token. 834 +--------+ +-------+ 835 | Client | | GS | 836 | |--(1)--- Read AuthZ ---------------------->| | 837 | |<------- AuthZ Response -------------------| | 838 | | | | 839 | | +----------+ | | 840 | | | Resource | | | 841 | |--(2)--- Access Resource --->| Server | | | 842 | |<------- Resource Response --| (RS) | | | 843 | | | | | | 844 | |--(3)--- Access Resource --->| | | | 845 | |<------- Error Response -----| | | | 846 | | | | | | 847 | | +----------+ | | 848 | | | | 849 | |--(4)--- Read AuthZ ---------------------->| | 850 | |<------- AuthZ Response -------------------| | 851 | | | | 852 +--------+ +-------+ 854 1. *Read AuthZ* The Client makes a Read AuthZ (Section 4.7) with an 855 HTTP GET to the AZ URI and receives an Response JSON 856 "authorization" object (Section 6.4.3) with a fresh access token. 858 2. *Resource Request* The Client accesses the RS with the access 859 token per Section 8 and receives a response from the RS. 861 3. *Resource Request* The Client attempts to access the RS, but 862 receives an error indicating the access token has expired. 864 4. *Read AuthZ* The Client makes another Read AuthZ (Section 4.7) 865 with an HTTP GET to the AZ URI and receives an Response JSON 866 "authorization" object (Section 6.4.3) with a fresh access token. 868 2.12. GS API Table 870 +--------------+-----------+--------+-----------------------------+ 871 | request | http verb | uri | response | 872 +==============+===========+========+=============================+ 873 | Create Grant | POST | GS URI | interaction, wait, or grant | 874 +--------------+-----------+--------+-----------------------------+ 875 | Verify Grant | PATCH | Grant | grant | 876 | | | URI | | 877 +--------------+-----------+--------+-----------------------------+ 878 | Read Grant | GET | Grant | wait, or grant | 879 | | | URI | | 880 +--------------+-----------+--------+-----------------------------+ 881 | Update Grant | PUT | Grant | interaction, wait, or grant | 882 | | | URI | | 883 +--------------+-----------+--------+-----------------------------+ 884 | Delete Grant | DELETE | Grant | success | 885 | | | URI | | 886 +--------------+-----------+--------+-----------------------------+ 887 | Read AuthZ | GET | AZ URI | authorization | 888 +--------------+-----------+--------+-----------------------------+ 889 | Update AuthZ | PUT | AZ URI | authorization | 890 +--------------+-----------+--------+-----------------------------+ 891 | Delete AuthZ | DELETE | AZ URI | success | 892 +--------------+-----------+--------+-----------------------------+ 893 | GS Options | OPTIONS | GS URI | metadata | 894 +--------------+-----------+--------+-----------------------------+ 895 | Grant | OPTIONS | Grant | metadata | 896 | Options | | URI | | 897 +--------------+-----------+--------+-----------------------------+ 898 | AuthZ | OPTIONS | AZ URI | metadata | 899 | Options | | | | 900 +--------------+-----------+--------+-----------------------------+ 902 Table 1 904 [ Editor: is there value in an API for listing a Client's Grants? 905 eg:] 907 List Grants GET GS URI JSON array of Grant URIs 909 3. Grant and AuthZ Life Cycle 911 [Editor: straw man for life cycles.] 913 *Grant life Cycle* 914 The Client MAY create, read, update, and delete Grants. A Grant 915 persists until it has expired, is deleted, or another Grant is 916 created for the same GS, Client, and User tuple. 918 At any point in time, there can only be one Grant for the GS, Client, 919 and User tuple. When a Client creates a Grant at the same GS for the 920 same User, the GS MUST invalidate a previous Grant for the Client at 921 that GS for that User. 923 *Authorization Life Cycle* 925 An Authorization are represented by an AZ URI and are MAY be included 926 in a Grant Response "authorization" Object (Section 6.4.3) or as a 927 member of the Grant Response "authorizations" list. If a Client 928 receives an Authorization, the Client MUST be able to do a Read AuthZ 929 request Section 4.7, and MAY be able to update Section 4.8 and delete 930 Section 4.9 depending on GS policy. 932 An Authorization will persist independent of the Grant, and persist 933 until invalidated by the GS per GS policy, or deleted by the Client. 935 4. GS APIs 937 *Client Authentication* 939 All APIs except for GS Options require the Client to authenticate. 941 This document defines the JOSE Authentication mechanism in 942 Section 10. Other mechanisms include [TBD]. 944 4.1. Create Grant 946 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 947 document to the GS URI. 949 The JSON document MUST include the following from the Request JSON 950 Section 4.6: 952 * iat 954 * nonce 956 * uri set to the GS URI 958 * client 960 and MAY include the following from Request JSON Section 4.6 961 * user 963 * interaction 965 * authorization or authorizations 967 * claims 969 The GS MUST respond with one of Grant Response Section 6.1, 970 Interaction Response Section 6.2, Wait Response Section 6.3, or one 971 of the following errors: 973 * TBD 975 from Error Responses Section 9. 977 Following is a non-normative example where the Client wants is 978 requesting identity claims about the User and read access to the 979 User's contacts: 981 Example 1 983 { 984 "iat" : 15790460234, 985 "uri" : "https://as.example/endpoint", 986 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 987 "client": { 988 "display": { 989 "name" : "SPA Display Name", 990 "uri" : "https://spa.example/about" 991 } 992 }, 993 "interaction": { 994 "type" : "redirect", 995 "completion_uri" : "https://web.example/return" 996 }, 997 "authorization": { 998 "type" : "oauth_scope", 999 "scope" : "read_contacts" 1000 }, 1001 "claims": { 1002 "oidc": { 1003 "id_token" : { 1004 "email" : { "essential" : true }, 1005 "email_verified" : { "essential" : true } 1006 }, 1007 "userinfo" : { 1008 "name" : { "essential" : true }, 1009 "picture" : null 1010 } 1011 } 1012 } 1013 } 1015 Following is a non-normative example where the Client is requesting 1016 the GS to keep the interaction with the User after returning the ID 1017 Token so the Client can update the Grant, and is also asking if the 1018 user exists: 1020 Example 2 1022 { 1023 "iat" : 15790460234, 1024 "uri" : "https://as.example/endpoint", 1025 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1026 "client": { 1027 "id" : "di3872h34dkJW" 1028 }, 1029 "interaction": { 1030 "keep" : true, 1031 "type" : "redirect", 1032 "completion_uri" : "https://web.example/return" 1033 }, 1034 "user": { 1035 "identifiers": { 1036 "email" : "jane.doe@example.com" 1037 }, 1038 "exists" : true 1039 }, 1040 "claims" : { "oidc": { "id_token" : {} } } 1041 } 1043 4.2. Verify Grant 1045 The Client verifies a Grant by doing an HTTP PATCH of a JSON document 1046 to the corresponding Grant URI. 1048 The JSON document MUST contain verification.nonce per Section 4.6.7. 1049 Following is a non-normative example: 1051 { 1052 "verification": { "nonce":"55e8a90f-a563-426d-8c35-d6d8ed54afeb" } 1053 } 1055 The GS MUST respond with one of Grant Response Section 6.1 or one of 1056 the following errors: 1058 * TBD 1060 from Error Responses Section 9. 1062 4.3. Read Grant 1064 The Client reads a Grant by doing an HTTP GET of the corresponding 1065 Grant URI. 1067 The GS MUST respond with one of Grant Response Section 6.1, Wait 1068 Response Section 6.3, or one of the following errors: 1070 * TBD 1072 from Error Responses Section 9. 1074 4.4. Update Grant 1076 The Client updates a Grant by doing an HTTP PUT of a JSON document to 1077 the corresponding Grant URI. 1079 The JSON document MUST include the following from the Request JSON 1080 Section 4.6 1082 * iat 1084 * uri set to the Grant URI 1086 and MAY include the following from Request JSON Section 4.6 1088 * user 1090 * interaction 1092 * authorization or authorizations 1094 * claims 1096 The GS MUST respond with one of Grant Response Section 6.1, 1097 Interaction Response Section 6.2, Wait Response Section 6.3, or one 1098 of the following errors: 1100 * TBD 1102 from Error Responses Section 9. 1104 Following is a non-normative example where the Client made an 1105 interaction.keep:true request, and now wants to update the request 1106 with additional claims: 1108 Example 3 1110 { 1111 "iat" : 15790460234, 1112 "uri" : "https://as.example/endpoint/grant/example3", 1113 "claims": { 1114 "oidc": { 1115 "userinfo" : { 1116 "email" : { "essential" : true }, 1117 "name" : { "essential" : true }, 1118 "picture" : null 1119 } 1120 } 1121 } 1122 } 1124 4.5. Delete Grant 1126 The Client deletes a Grant by doing an HTTP DELETE of the 1127 corresponding Grant URI. 1129 The GS MUST respond with OK 200, or one of the following errors: 1131 * TBD 1133 from Error Responses Section 9. 1135 4.6. Request JSON 1137 [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ] 1139 * *iat* - the time of the request as a NumericDate. 1141 * *nonce* - a unique identifier for this request. Note the Grant 1142 Response MUST contain a matching nonce attribute value. 1144 * *uri* - the GS URI if in a Create Grant Section 4.1, or the Grant 1145 URI if in an Update Grant Section 4.4. 1147 4.6.1. "client" Object 1149 The client object MUST contain either the id attribute for Registered 1150 Clients, or the display object for Dynamic Clients. 1152 * *id* - the Client ID the GS has for the Registered Client. 1154 * *display* - the display object contains the following attributes: 1156 - *name* - a string that represents the Dynamic Client 1158 - *uri* - a URI representing the Dynamic Client 1160 The name and uri will be displayed by the GS when prompting for 1161 authorization. 1163 [Editor: a max length for the name and URI so a GS can reserve 1164 appropriate space?] 1166 4.6.2. "interaction" Object 1168 The interaction object contains the type of interaction the Client 1169 will provide the User. Other attributes 1171 * *keep* - a JSON boolean. If set to the JSON value true, the GS 1172 will not transfer the User interaction back to the Client after 1173 processing the Grant request. The JSON value false is equivalent 1174 to the attribute not being present, and the GS will transfer the 1175 User interaction back to the Client after processing the request. 1176 This attribute is OPTIONAL 1178 * *type* - contains one of the following values: "redirect" or 1179 "indirect". Details in Section 7. This attribute is REQUIRED. 1181 [Editor: do we want this to be an array of types the Client can 1182 support? This would only be the case if the GS is not able to 1183 support all types and negotiation is required. Is that required?] 1185 * *completion_uri* - this attribute is REQUIRED if the type is 1186 "redirect". It is the URI that the Client requests the GS to 1187 redirect the User to after the GS has completed interacting with 1188 the User. If the Client manages session state in URIs, then the 1189 redirect_uri SHOULD contain that state. 1191 * *information_uri* - this attribute is OPTIONAL and is ignored 1192 unless the type is "indirect". This is the URI the Client would 1193 like the GS to redirect the User to after the interaction with the 1194 User is complete. 1196 * *ui_locales* - End-User's preferred languages and scripts for the 1197 user interface, represented as a space-separated list of [RFC5646] 1198 language tag values, ordered by preference. This attribute is 1199 OPTIONAL. 1201 * *verify* - a boolean value. If set to the JSON value true, the GS 1202 will return a nonce value with the Completion URI. 1204 4.6.3. "user" Object 1206 * *exists* - if present, MUST contain the JSON true value. 1207 Indicates the Client requests the GS to return a user.exists value 1208 in an Interaction Response Section 6.2. This attribute is 1209 OPTIONAL, and MAY be ignored by the GS. 1211 * *identifiers* - REQUIRED if the exists attribute is present. The 1212 values MAY be used by the GS to improve the User experience. 1213 Contains one or more of the following identifiers for the User: 1215 - *phone_number* - contains a phone number per Section 5 of 1216 [RFC3966]. 1218 - *email* - contains an email address per [RFC5322]. 1220 - *oidc* - is an object containing both the "iss" and "sub" 1221 attributes from an OpenID Connect ID Token [OIDC] Section 2. 1223 * *claims* - an optional object containing one or more assertions 1224 the Client has about the User. 1226 - *oidc_id_token* - an OpenID Connect ID Token per [OIDC] 1227 Section 2. 1229 * *reciprocal* - indicates this Grant Request or Update is the 1230 reciprocal of another Grant. Contains the Grant URI of the 1231 reciprocal Grant. 1233 4.6.4. "authorization" Object 1235 * *type* - one of the following values: "oauth_scope" or 1236 "oauth_rich". This attribute is REQUIRED. 1238 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1239 section 3.3. MUST be included if type is "oauth_scope" or 1240 "oauth_rich". 1242 * *authorization_details* - an authorization_details object per 1243 [RAR]. MUST be included if type is "oauth_rich". 1245 [Editor: details may change as the [RAR] document evolves] 1247 4.6.5. "authorizations" Object 1249 A JSON array of "authorization" objects. Only one of "authorization" 1250 or "authorizations" may be in the Request JSON. 1252 [Editor: instead of an array, we could have a Client defined 1253 dictionary of "authorization" objects] 1255 4.6.6. "claims" Object 1257 Includes one or more of the following: 1259 * *oidc* - an object that contains one or both of the following 1260 objects: 1262 - *userinfo* - Claims that will be returned as a JSON object 1264 - *id_token* - Claims that will be included in the returned ID 1265 Token. If the null value, an ID Token will be returned 1266 containing no additional Claims. 1268 The contents of the userinfo and id_token objects are Claims as 1269 defined in [OIDC] Section 5. 1271 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1272 per [OIDC4IA]. 1274 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1275 be requested.] 1277 4.6.7. "verification" Object 1279 The verification Object is used with the Verify Grant Section 4.2. 1281 * *nonce* the Interaction Nonce received from the GS via the 1282 Completion URI. This attribute MUST only be used in the Verify 1283 Grant Section 4.2. 1285 [Editor: parameters for the Client to request it wants the Grant 1286 Response signed and/or encrypted?] 1288 4.7. Read Authorization 1290 The Client acquires an Authorization by doing an HTTP GET to the 1291 corresponding AZ URI. 1293 The GS MUST respond with a Authorization JSON document Section 6.5, 1294 or one of the following errors: 1296 * TBD 1298 from Error Responses Section 9. 1300 4.8. Update Authorization 1302 The Client updates an Authorization by doing an HTTP PUT to the 1303 corresponding AZ URI of the following JSON. All of the following 1304 MUST be included. 1306 * *iat* - the time of the response as a NumericDate. 1308 * *uri* - the AZ URI. 1310 * *authorization* - the new authorization requested per the Request 1311 JSON "authorization" object Section 4.6.4. 1313 The GS MUST respond with a Authorization JSON document Section 6.5, 1314 or one of the following errors: 1316 * TBD 1318 from Error Responses Section 9. 1320 4.9. Delete Authorization 1322 The Client deletes an Authorization by doing an HTTP DELETE to the 1323 corresponding AZ URI. 1325 The GS MUST respond with OK 200, or one of the following errors: 1327 * TBD 1329 from Error Responses Section 9. 1331 4.10. GS Options 1333 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1334 of the corresponding GS URI. This is the only API where the GS MAY 1335 respond to an unauthenticated request. 1337 The GS MUST respond with the the following JSON document: 1339 [Editor: this section is a work in progress] 1341 * *uri* - the GS URI. 1343 * *client_authentication* - an array of the Client Authentication 1344 mechanisms supported by the GS 1346 * *interactions* - an array of the interaction types supported by 1347 the GS. 1349 * *authorization* - an object containing the authorizations the 1350 Client may request from the GS, if any. 1352 - Details TBD 1354 * *claims* - an object containing the identity claims the Client may 1355 request from the GS, if any, and what public keys the claims will 1356 be signed with. 1358 - Details TBD 1360 * *algorithms* - a list of the cryptographic algorithms supported by 1361 the GS. 1363 * *features* - an object containing feature support 1365 - *user_exists* - boolean indicating if user.exists is supported. 1367 - *authorizations* - boolean indicating if a request for multiple 1368 authorizations is supported. 1370 [Editor: keys used by Client to encrypt requests, or verify signed 1371 responses?] 1373 [Editor: namespace metadata for extensions?] 1375 or one of the following errors: 1377 * TBD 1379 from Error Responses Section 9. 1381 4.11. Grant Options 1383 The Client can get the metadata for the Grant by doing an HTTP 1384 OPTIONS of the corresponding Grant URI. 1386 The GS MUST respond with the the following JSON document: 1388 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1390 or one of the following errors: 1392 * TBD 1394 from Error Responses Section 9. 1396 4.12. AuthZ Options 1398 The Client can get the metadata for the AuthZ by doing an HTTP 1399 OPTIONS of the corresponding AZ URI. 1401 The GS MUST respond with the the following JSON document: 1403 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1405 or one of the following errors: 1407 * TBD 1409 from Error Responses Section 9. 1411 4.13. Request Verification 1413 On receipt of a request, the GS MUST verify the following: 1415 * TBD 1417 5. GS Initiated Grant 1419 [Editor: In OAuth 2.0, all flows are initiated at the Client. If the 1420 AS wanted to initiate a flow, it redirected to the Client, that 1421 redirected back to the AS to initiate a flow. 1423 Here is a proposal to support GS initiated: authentication; just-in- 1424 time (JIT) provisioning; and authorization] 1426 *initiation_uri* A URI at the Client that contains no query or 1427 fragment. How the GS learns the Client initiation_uri is out of 1428 scope. 1430 The GS creates a Grant and Grant URI, and redirects the User to the 1431 initiation_uri with the query parameter "grant" and the value of 1432 Grant URI. 1434 See Section 2.5 for the sequence diagram. 1436 6. GS API Responses 1438 6.1. Grant Response 1440 The Grant Response MUST include the following from the Response JSON 1441 Section 6.4 1443 * iat 1444 * nonce 1446 * uri 1448 and MAY include the following from the Response JSON Section 6.4 1450 * authorization or authorizations 1452 * claims 1454 * expires_in 1456 Example non-normative Grant Response JSON document for Example 1 in 1457 Section 4.1: 1459 { 1460 "iat" : 15790460234, 1461 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1462 "uri" : "https://as.example/endpoint/grant/example1", 1463 "expires_in" : 300 1464 "authorization": { 1465 "type" : "oauth_scope", 1466 "scope" : "read_contacts", 1467 "expires_in" : 3600, 1468 "mechanism" : "bearer", 1469 "token" : "eyJJ2D6.example.access.token.mZf9p" 1470 }, 1471 "claims": { 1472 "oidc": { 1473 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1474 "userinfo" : { 1475 "name" : "John Doe", 1476 "picture" : "https://photos.example/p/eyJzdkiO" 1477 } 1478 } 1479 } 1480 } 1482 Example non-normative Grant Response JSON document for Example 2 in 1483 Section 4.1: 1485 { 1486 "iat" : 15790460234, 1487 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1488 "uri" : "https://as.example/endpoint/grant/example2", 1489 "authorization": { 1490 "uri" : "https://as.example/endpoint/authz/example2" 1491 } 1492 } 1494 6.2. Interaction Response 1496 The Interaction Response MUST include the following from the Response 1497 JSON Section 6.4 1499 * iat 1501 * nonce 1503 * uri 1505 * interaction 1507 and MAY include the following from the Response JSON Section 6.4 1509 * user 1511 * wait 1513 A non-normative example of an Interaction Response follows: 1515 { 1516 "iat" : 15790460234, 1517 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1518 "uri" : "https://as.example/endpoint/grant/example4", 1519 "interaction" : { 1520 "type" : "redirect", 1521 "redirect_uri" : "https://as.example/i/example4" 1522 }, 1523 "user": { 1524 "exists" : true 1525 } 1526 } 1528 6.3. Wait Response 1530 The Wait Response MUST include the following from the Response JSON 1531 Section 6.4 1532 * iat 1534 * nonce 1536 * uri 1538 * wait 1540 A non-normative example of Wait Response follows: 1542 { 1543 "iat" : 15790460234, 1544 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1545 "uri" : "https://as.example/endpoint/grant/example5", 1546 "wait" : 300 1547 } 1549 6.4. Response JSON 1551 Details of the JSON document: 1553 * *iat* - the time of the response as a NumericDate. 1555 * *nonce* - the nonce that was included in the Request JSON 1556 Section 4.6. 1558 * *uri* - the Grant URI. 1560 * *wait* - a numeric value representing the number of seconds the 1561 Client should want before making a Read Grant request to the Grant 1562 URI. 1564 * *expires_in* - a numeric value specifying how many seconds until 1565 the Grant expires. This attribute is OPTIONAL. 1567 6.4.1. "interaction" Object 1569 If the GS wants the Client to start the interaction, the GS MUST 1570 return the interaction mechanism provided by the Client in the Grant 1571 Request, and include the required attributes in the interaction 1572 object: 1574 * *type* - this MUST match the type provided by the Client in the 1575 Grant Request client.interaction object. 1577 * *authorization_uri* - the URI to redirect the user to or load in 1578 the popup. Must be included if type is "redirect" 1580 * *display_uri* - the URI to be displayed to the User for them to 1581 navigate to and enter the code. Must be included if type is 1582 "indirect" 1584 * *user_code* - a text string of the code to display to the User. 1585 Must be included if type is "indirect". 1587 * *short_uri* - the URI to show as scannable code. MUST be included 1588 if type is "indirect" 1590 [Editor: do we specify a maximum length for the display_uri and code 1591 so that a device knows the maximum it needs to support? A smart 1592 device may have limited screen real estate.] 1594 The authorization_uri, qr_uri, and user_code MUST be unique and only 1595 match the associated Grant URI. 1597 TBD: entropy and other security considerations for the 1598 authorization_uri, qr_uri, and the user_code. 1600 See Interaction Types Section 7 for details. 1602 6.4.2. "user" Object 1604 * *exists* - a boolean value indicating if the GS has a user with 1605 one or more of the provided identifiers in the Request 1606 user.identifiers object Section 4.6.3 1608 6.4.3. "authorization" Object 1610 The Response JSON authorization object is a subset of the 1611 Authorization JSON Section 6.5. It contains only the AZ URI if the 1612 Client is able to read, update and/or delete the Authorization. 1613 Alternatively, it contains the Authorization JSON excluding the AZ 1614 URI. See Grant Response Section 6.1 for non-normative examples. 1616 6.4.4. "authorizations" Object 1618 A JSON array of authorization objects. Support for the 1619 authorizations object is OPTIONAL. 1621 6.4.5. "claims" Object 1623 The claims object is a response to the Request "claims" object 1624 Section 4.6.4. 1626 * *oidc* 1627 - *id_token* - an OpenID Connect ID Token containing the Claims 1628 the User consented to be released. 1630 - *userinfo* - the Claims the User consented to be released. 1632 Claims are defined in [OIDC] Section 5. 1634 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1635 per [OIDC4IA]. 1637 * *vc* 1639 The verified claims the user consented to be released. [Editor: 1640 details TBD] 1642 6.5. Authorization JSON 1644 The Authorization JSON is a response to a Read AuthZ request by the 1645 Client Section 4.7. A subset of the Authorization JSON is included 1646 in the "authorization" object Section 4.6.4 and "authorizations" list 1647 members Section 6.4.4. 1649 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1650 See the "type" object in Section 4.6.4 for details. 1652 * *scope* - the scopes the Client was granted authorization for. 1653 This will be all, or a subset, of what was requested. This 1654 attribute is OPTIONAL. 1656 * *authorization_details* - the authorization details granted per 1657 [RAR]. Included if type is "oauth_rich". 1659 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1660 "jose+body". See Section 8 for details. 1662 * *token* - the access token for accessing an RS. This attribute is 1663 REQUIRED. 1665 * *expires_in* - a numeric value specifying how many seconds until 1666 the access token expires. This attribute is OPTIONAL. 1668 * *certificate* - MUST be included if the mechanism is "jose" or 1669 "jose+body". Contains the jwk header values for the Client to 1670 include in the JWS header when calling the RS using the "jose" or 1671 "jose+body" mechanisms. See Section 10.2.1. 1673 * *uri* - the AZ URI. Used to get, update, and delete the 1674 authorization. This will be the same URI that was used in a Read 1675 Authorization or Update Authorization request. This attribute is 1676 REQUIRED unless it is in a Response JSON, 1678 [Editor: any value in an expiry for the Authorization?] 1680 The following is a non-normative example of an Authorization JSON 1681 document: 1683 { 1684 "type" : "oauth_scope", 1685 "scope" : "read_calendar write_calendar", 1686 "mechanism" : "jose", 1687 "token" : "eyJJ2D6.example.access.token.mZf9p" 1688 "expires_in" : 3600, 1689 "certificate": { 1690 "x5u" : "https://as.example/cert/example2" 1691 }, 1692 "uri" : "https://as.example/endpoint/authz/example2" 1693 } 1695 6.5.1. Signing and Encryption 1697 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1698 there a generalized description, or is it mechanism specific?] 1700 6.6. Response Verification 1702 On receipt of a response, the Client MUST verify the following: 1704 * TBD 1706 7. Interactions 1708 There are two types of interactions that a Client can initiate with a 1709 GS: redirect and indirect. Extensions may define additional 1710 interaction types. 1712 7.1. Redirect Interaction 1714 A Redirect Interaction is characterized by the GS returning the User 1715 back to the Client that started the interaction. After a redirect 1716 back from the GS, the Client may be able to securely verify the 1717 returning User is the same as the User the Client redirected to the 1718 GS by verifying a unique Completion URI is associated with a browser 1719 cookie set prior to the redirection. Clients that are not able to 1720 securely verify the returning User, or do not want to, verify the 1721 User by making a Verify Grant call to the GS, passing the Interaction 1722 Nonce. The Client signals to the GS that it requires an Interaction 1723 Nonce by setting interaction.verify to true. Following is the 1724 Redirect Interaction sequence: 1726 1. If not interaction.verify, the Client creates a unique 1727 Completion URI. 1729 2. The Client creates a Grant Request setting interaction.type to 1730 "redirect" and interaction.completion_uri to the Completion URI, 1731 and makes a Create Grant request. 1733 3. The GS creates a Grant with a unique Grant URI and Authorization 1734 URI and binds them to the Completion URI. 1736 4. The GS creates an Interaction Response setting interaction.type 1737 to "redirect" and interaction.authorization_uri to the 1738 Authorization URI and returns it to the Client. 1740 5. If not interaction.verify, the Client creates and sets a a 1741 unique completion browser cookie and binds it to the completion 1742 URI. The cookie MUST not be able to be used to derive the 1743 Completion URI. 1745 6. The Client redirects the User's browser to the Authorization URI 1746 using any available browser redirect mechanism. 1748 7. The GS locates the Grant bound to the Authorization URI. 1750 8. The GS interacts with the User. 1752 9. If interaction.verify, the GS creates an Interaction Nonce, 1753 binds it to the Grant, and appends it to the Completion URI as 1754 the "nonce" query parameter. 1756 10. The GS redirects the User's browser to the Completion URI using 1757 any available browser redirect mechanism. 1759 11. If not interaction.verify, the Client confirms the completion 1760 browser cookie is bound to the Completion URI. 1762 12. If interaction.verify, the Client makes a Verify Grant call with 1763 the Interaction Nonce, and the Grant. 1765 A GS MUST support the Redirect Interaction type. 1767 7.2. Indirect Interaction 1769 An Indirect Interaction is characterized by the GS not being able to 1770 return the User back to the Client that started the interaction. 1771 There are two mechanisms for a User to identify the Client's Create 1772 Grant request at the GS: Short URI or User Code. 1774 1. Generation 1776 1. The GS generates a Short URI and User Code unique to the 1777 Grant. 1779 2. The GS sends the Short URI, Code URI, and User Code to the 1780 Client. 1782 2. Display 1784 1. If possible, the Client MAY display the Short URI to the User 1785 as a scannable code such as a [QR_Code]. The User MAY then 1786 scan the image that will open the Short URI on the User's 1787 scanning device. 1789 2. The Client MAY optionally launch a system browser to open the 1790 Short URI. 1792 3. The Client MUST display the User Code and instructions to 1793 enter it at the Code URI. The User MAY navigate a browser on 1794 a separate device to the Code URI. 1796 If the User arrived at the GS via the Short URI, the GS will use the 1797 Short URI to identify the Create Grant request, and then authenticate 1798 the User. 1800 If the User arrived at the GS via the Code URI, the GS will 1801 authenticate the User, and then prompt the User to enter the User 1802 Code, which the GS will then use to identify the Create Grant 1803 request. 1805 [Editor: we may need to include interaction types for iOS and Android 1806 as the mobile OS APIs evolve.] 1808 8. RS Access 1810 This document specifies three different mechanisms for the Client to 1811 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1812 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1813 mechanisms are proof-of-possession mechanisms and are defined in 1814 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1815 possession mechanisms may be defined in other documents. The 1816 mechanism the Client is to use with an RS is the Response JSON 1817 authorization.mechanism attribute Section 6.4.3. 1819 8.1. Bearer Token 1821 If the access mechanism is "bearer", then the Client accesses the RS 1822 per Section 2.1 of [RFC6750] 1824 A non-normative example of the HTTP request headers follows: 1826 GET /calendar HTTP/2 1827 Host: calendar.example 1828 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1830 9. Error Responses 1832 * TBD 1834 10. JOSE Authentication 1836 How the Client authenticates to the GS and RS are independent of each 1837 other. One mechanism can be used to authenticate to the GS, and a 1838 different mechanism to authenticate to the RS. 1840 Other documents that specify other Client authentication mechanisms 1841 will replace this section. 1843 In the JOSE Authentication Mechanism, the Client authenticates by 1844 using its private key to sign a JSON document with JWS per [RFC7515] 1845 which results in a token using JOSE compact serialization. 1847 [Editor: are there advantages to using JSON serialization in the 1848 body?] 1850 Different instances of a Registered Client MAY have different private 1851 keys, but each instance has a certificate to bind its private key to 1852 to a public key the GS has for the Client ID. An instance of a 1853 Client will use the same private key for all signing operations. 1855 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1856 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1858 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1860 The token may be included in an HTTP header, or as the HTTP message 1861 body. 1863 The following sections specify how the Client uses JOSE to 1864 authenticate to the GS and RS. 1866 10.1. GS Access 1868 The Client authenticates to the GS by passing either a signed header 1869 parameter, or a signed message body. The following table shows the 1870 verb, uri and token location for each Client request to the GS: 1872 +---------------+-----------+-----------+----------+ 1873 | request | http verb | uri | token in | 1874 +===============+===========+===========+==========+ 1875 | Create Grant | POST | GS URI | body | 1876 +---------------+-----------+-----------+----------+ 1877 | Verify Grant | PATCH | Grant URI | body | 1878 +---------------+-----------+-----------+----------+ 1879 | Read Grant | GET | Grant URI | header | 1880 +---------------+-----------+-----------+----------+ 1881 | Update Grant | PUT | Grant URI | body | 1882 +---------------+-----------+-----------+----------+ 1883 | Delete Grant | DELETE | Grant URI | header | 1884 +---------------+-----------+-----------+----------+ 1885 | Read AuthZ | GET | AZ URI | header | 1886 +---------------+-----------+-----------+----------+ 1887 | Update AuthZ | PUT | AZ URI | body | 1888 +---------------+-----------+-----------+----------+ 1889 | Delete AuthZ | DELETE | AZ URI | header | 1890 +---------------+-----------+-----------+----------+ 1891 | GS Options | OPTIONS | GS URI | header | 1892 +---------------+-----------+-----------+----------+ 1893 | Grant Options | OPTIONS | Grant URI | header | 1894 +---------------+-----------+-----------+----------+ 1895 | AuthZ Options | OPTIONS | AZ URI | header | 1896 +---------------+-----------+-----------+----------+ 1898 Table 2 1900 10.1.1. Authorization Header 1902 For requests with the token in the header, the JWS payload MUST 1903 contain the following attributes: 1905 *iat* - the time the token was created as a NumericDate. 1907 *jti* - a unique identifier for the token per [RFC7519] section 1908 4.1.7. 1910 *uri* - the value of the URI being called (GS URI, Grant URI, or AZ 1911 URI). 1913 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1914 "OPTIONS") 1916 The HTTP authorization header is set to the "jose" parameter followed 1917 by one or more white space characters, followed by the resulting 1918 token. 1920 A non-normative example of a JWS payload and the HTTP request 1921 follows: 1923 { 1924 "iat" : 15790460234, 1925 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1926 "uri" : "https://as.example/endpoint/grant/example6", 1927 "verb" : "GET" 1928 } 1930 GET /endpoint/example.grant HTTP/2 1931 Host: as.example 1932 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1934 [Editor: make a real example token] 1936 *GS Verification* 1938 The GS MUST verify the token by: 1940 * TBD 1942 10.1.2. Signed Body 1944 For requests with the token in the body, the Client uses the Request 1945 JSON as the payload in a JWS. The resulting token is sent with the 1946 content-type set to "application/jose". 1948 A non-normative example (line breaks added to the body for 1949 readability): 1951 POST /endpoint HTTP/2 1952 Host: as.example 1953 Content-Type: application/jose 1954 Content-Length: 155 1956 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1957 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1958 Jf36POk6yJV_adQssw5c 1960 [Editor: make a real example token] 1962 *GS Verification* 1964 The GS MUST verify the token by: 1966 * TBD 1968 10.1.3. Public Key Resolution 1970 * *Registered Clients* can use any of the JWS header values to 1971 direct the GS to resolve the public key matching the private key 1972 used to the Client ID. The GS MAY restrict with JWS headers a 1973 Client can use. 1975 [Editor: would examples help here so that implementors understand the 1976 full range of options, and how an instance can have its own asymetric 1977 key pair] 1979 A non-normative example of a JOSE header for a Registered Client with 1980 a key identifier of "12": 1982 { 1983 "alg" : "ES256", 1984 "typ" : "JOSE", 1985 "kid" : "12" 1986 } 1988 * *Dynamic Clients* include their public key in the "jwk" JWS 1989 header. 1991 A non-normative example of a JOSE header for a Dynamic Client: 1993 { 1994 "alg" : "ES256", 1995 "typ" : "JOSE", 1996 "jwk" : { 1997 "kty" : "EC", 1998 "crv" : "P-256", 1999 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 2000 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 2001 } 2002 } 2004 10.2. RS Access 2006 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 2007 include a proof-of-possession token in the HTTP authorization header. 2008 In the "jose+body" mechanism Section 10.2.3, the Client signs the 2009 JSON document in the request if the POST or PUT verbs are used, 2010 otherwise it is the same as the "jose" mechanism. 2012 10.2.1. JOSE header 2014 The GS provides the Client one or more JWS header parameters and 2015 values for a a certificate, or a reference to a certificate or 2016 certificate chain, that the RS can use to resolve the public key 2017 matching the private key being used by the Client. 2019 A non-normative examples JOSE header: 2021 { 2022 "alg" : "ES256", 2023 "typ" : "JOSE", 2024 "x5u" : "https://as.example/cert/example2" 2025 } 2027 [Editor: this enables Dynamic Clients to make proof-of-possession API 2028 calls the same as Registered Clients.] 2030 10.2.2. "jose" Mechanism 2032 The JWS payload MUST contain the following attributes: 2034 *iat* - the time the token was created as a NumericDate. 2036 *jti* - a unique identifier for the token per [RFC7519] section 2037 4.1.7. 2039 *uri* - the value of the RS URI being called. 2041 *verb* - the HTTP verb being used in the call 2043 *token* - the access token provided by the GS to the Client 2045 The HTTP authorization header is set to the "jose" parameter followed 2046 by one or more white space characters, followed by the resulting 2047 token. 2049 A non-normative example of a JWS payload and the HTTP request 2050 follows: 2052 { 2053 "iat" : 15790460234, 2054 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 2055 "uri" : "https://calendar.example/calendar", 2056 "verb" : "GET", 2057 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 2058 } 2060 GET /calendar HTTP/2 2061 Host: calendar.example 2062 Authorization: jose eyJhbG.example.jose.token.adks 2064 [Editor: make a real example token] 2066 *RS Verification* 2068 The RS MUST verify the token by: 2070 * verify access token is bound to the public key - include key 2071 fingerprint in access token? 2073 * TBD 2075 10.2.3. "jose+body" Mechanism 2077 The "jose+body" mechanism can only be used if the content being sent 2078 to the RS is a JSON document. 2080 Any requests not sending a message body will use the "jose" mechanism 2081 Section 10.2.2. 2083 Requests sending a message body MUST have the following JWS payload: 2085 *iat* - the time the token was created as a NumericDate. 2087 *jti* - a unique identifier for the token per [RFC7519] section 2088 4.1.7. 2090 *uri* - the value of the RS URI being called. 2092 *verb* - the HTTP verb being used in the call 2094 *token* - the access token provided by the GS to the Client 2096 *body* - the message body being sent to the RS 2098 A non-normative example of a JWS payload and the HTTP request 2099 follows: 2101 { 2102 "iat" : 15790460234, 2103 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 2104 "uri" : "https://calendar.example/calendar", 2105 "verb" : "POST", 2106 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 2107 "payload" : { 2108 "event" : { 2109 "title" : "meeting with joe", 2110 "start_date_utc" : "2020-02-21 11:00:00", 2111 "end_date_utc" : "2020-02-21 11:00:00" 2112 } 2113 } 2114 } 2116 POST /calendar HTTP/2 2117 Host: calendar.example 2118 Content-Type: application/jose 2119 Content-Length: 155 2121 eyJhbGciOi.example.jose+body.adasdQssw5c 2123 [Editor: make a real example token] 2125 *RS Verification* 2127 The RS MUST verify the token by: 2129 * TBD 2131 10.2.4. Public Key Resolution 2133 The RS has a public key for the GS that it uses to verify the 2134 certificate or certificate chain the Client includes in the JWS 2135 header. 2137 10.3. Request Encryption 2139 [Editor: to be fleshed out] 2141 The Client encrypts a request when ??? using the GS public key 2142 returned as the ??? attribute in GS Options Section 4.10. 2144 10.4. Response Signing 2146 [Editor: to be fleshed out] 2148 The Client verifies a signed response ??? using the GS public key 2149 returned as the ??? attribute in GS Options Section 4.10. 2151 10.5. Response Encryption 2153 [Editor: to be fleshed out] 2155 The Client decrypts a response when ??? using the private key 2156 matching the public key included in the request as the ??? attribute 2157 in Section 4.6. 2159 11. Extensibility 2161 This standard can be extended in a number of areas: 2163 * *Client Authentication Mechanisms* 2165 - An extension could define other mechanisms for the Client to 2166 authenticate to the GS and/or RS such as Mutual TLS or HTTP 2167 Signing. Constrained environments could use CBOR [RFC7049] 2168 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 2169 [RFC8323] instead of HTTP/2. 2171 * *Grant* 2173 - An extension can define new objects in the Grant Request and 2174 Grant Response JSON. 2176 * *Top Level* 2178 - Top level objects SHOULD only be defined to represent 2179 functionality other the existing top level objects and 2180 attributes. 2182 * *"client" Object* 2183 - Additional information about the Client that the GS would 2184 require related to an extension. 2186 * *"user" Object* 2188 - Additional information about the User that the GS would require 2189 related to an extension. 2191 * *"authorization" Object* 2193 - Additional types of authorizations in addition to OAuth 2.0 2194 scopes and RAR. 2196 * *"claims" Object* 2198 - Additional types of identity claims in addition to OpenID 2199 Connect claims and Verified Credentials. 2201 * *Interaction types* 2203 - Additional types of interactions a Client can start with the 2204 User. 2206 * *Continuous Authentication* 2208 - An extension could define a mechanism for the Client to 2209 regularly provide continuous authentication signals and receive 2210 responses. 2212 [Editor: do we specify access token / handle introspection in this 2213 document, or leave that to an extension?] 2215 [Editor: do we specify access token / handle revocation in this 2216 document, or leave that to an extension?] 2218 12. Rational 2220 1. *Why is there only one mechanism for the Client to authenticate 2221 with the GS? Why not support other mechanisms?* 2223 Having choices requires implementers to understand which choice 2224 is preferable for them. Having one default mechanism in the 2225 document for the Client to authenticate simplifies most 2226 implementations. Deployments that have unique characteristics 2227 can select other mechanisms that are preferable in specific 2228 environments. 2230 2. *Why is the default Client authentication JOSE rather than 2231 MTLS?* 2233 MTLS cannot be used today by a Dynamic Client. MTLS requires 2234 the application to have access below what is typically the 2235 application layer, that is often not available on some 2236 platforms. JOSE is done at the application layer. Many GS 2237 deployments will be an application behind a proxy performing 2238 TLS, and there are risks in the proxy passing on the results of 2239 MTLS. 2241 3. *Why is the default Client authentication JOSE rather than HTTP 2242 signing?* 2244 There is currently no widely deployed open standard for HTTP 2245 signing. Additionally, HTTP signing requires passing all the 2246 relevant parts of the HTTP request to downstream services within 2247 an GS that may need to independently verify the Client identity. 2249 4. *What are the advantages of using JOSE for the Client to 2250 authenticate to the GS and a resource?* 2252 Both Registered Clients and Dynamic Clients can have a private 2253 key, eliminating the public Client issues in OAuth 2.0, as a 2254 Dynamic Client can create an ephemeral key pair. Using 2255 asymetric cryptography also allows each instance of a Registered 2256 Client to have its own private key if it can obtain a 2257 certificate binding its public key to the public key the GS has 2258 for the Client. Signed tokens can be passed to downstream 2259 components in a GS or RS to enable independent verification of 2260 the Client and its request. The GS Initiated Sequence Section 5 2261 requires a URL safe parameter, and JOSE is URL safe. 2263 5. *Why does the GS not return parameters to the Client in the 2264 redirect url?* 2266 Passing parameters via a browser redirection is the source of 2267 many of the security risks in OAuth 2.0. It also presents a 2268 challenge for smart devices. In this protocol, the redirection 2269 from the Client to the GS is to enable the GS to interact with 2270 the User, and the redirection back to the Client is to hand back 2271 interaction control to the Client if the redirection was a full 2272 browser redirect. Unlike OAuth 2.0, the identity of the Client 2273 is independent of the URI the GS redirects to. 2275 6. *Why is there not a UserInfo endpoint as there is with OpenID 2276 Connect?* 2277 Since the Client can Read Grant at any time, it get the same 2278 functionality as the UserInfo endpoint, without the Client 2279 having to manage a separate access token and refresh token. If 2280 the Client would like additional claims, it can Update Grant, 2281 and the GS will let the Client know if an interaction is 2282 required to get any of the additional claims, which the Client 2283 can then start. 2285 [Editor: is there some other reason to have the UserInfo 2286 endpoint?] 2288 7. *Why is there still a Client ID?* 2290 The GS needs an identifier to fetch the meta data associated 2291 with a Client such as the name and image to display to the User, 2292 and the policies on what a Client is allowed to do. The Client 2293 ID was used in OAuth 2.0 for the same purpose, which simplifies 2294 migration. Dynamic Clients do not have a Client ID. 2296 8. *Why have both claims and authorizations?* 2298 There are use cases for each that are independent: 2299 authenticating a user and providing claims vs granting access to 2300 a resource. A request for an authorization returns an access 2301 token which may have full CRUD capabilities, while a request for 2302 a claim returns the claim about the User - with no create, 2303 update or delete capabilities. While the UserInfo endpoint in 2304 OIDC may be thought of as a resource, separating the concepts 2305 and how they are requested keeps each of them simpler in the 2306 Editor's opinion. :) 2308 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2309 GS communication in ?*Section 10 2311 Knowing the GS supports HTTP/2 enables a Client to set up a 2312 connection faster. HTTP/2 will be more efficient when Clients 2313 have large numbers of access tokens and are frequently 2314 refreshing them at the GS as there will be less network traffic. 2315 Mandating TLS 1.3 similarly improves the performance and 2316 security of Clients and GS when setting up a TLS connection. 2318 10. *Why do some of the JSON objects only have one child, such as 2319 the identifiers object in the user object in the Grant Request?* 2321 It is difficult to forecast future use cases. Having more 2322 resolution may mean the difference between a simple extension, 2323 and a convoluted extension. 2325 11. *Why is the "iss" included in the "oidc" identifier object? 2326 Would the "sub" not be enough for the GS to identify the User?* 2328 This decouples the GS from the OpenID Provider (OP). The GS 2329 identifier is the GS URI, which is the endpoint at the GS. The 2330 OP issuer identifier will likely not be the same as the GS URI. 2331 The GS may also provide claims from multiple OPs. 2333 12. *Why complicate things with interaction.keep?* 2335 The common sequence has a back and forth between the Client and 2336 the GS, and the Client can update the Grant and have a new 2337 interaction. Keeping the interaction provides a more seamless 2338 user experience where the results from the first request 2339 determine subsequent requests. For example, a common pattern is 2340 to use a GS to authenticate the User at the Client, and to 2341 register the User at the Client using additional claims from the 2342 GS. The Client does not know a priori if the User is a new 2343 User, or a returning User. Asking a returning User to consent 2344 releasing claims they have already provided is a poor User 2345 experience, as is sending the User back to the GS. The Client 2346 requesting identity first enables the Client to get a response 2347 from the GS while the GS is still interacting with the User, so 2348 that the Client can request additional claims only if needed. 2349 Additionally, the claims a Client may want about a User may be 2350 dependent on some initial Claims. For example, if a User is in 2351 a particular country, additional or different Claims my be 2352 required by the Client. 2354 There are also benefits for the GS. Today, a GS usually keeps 2355 track of which claims a Client has requested for a User. 2356 Storing this information for all Clients a User uses may be 2357 undesirable for a GS that does not want to have that information 2358 about the User. Keeping the interaction allows the Client to 2359 track what information it has about the User, and the GS can 2360 remain stateless. 2362 13. *Why is there a "jose+body" RS access mechanism method for the 2363 Client?*Section 10.2.3 2365 There are numerous use cases where the RS wants non-repudiation 2366 and providence of the contents of an API call. For example, the 2367 UGS Service Supplier Framework for Authentication and 2368 Authorization [UTM]. 2370 14. *Why use URIs to instead of handles for the Grant and 2371 Authorization?* 2372 A URI is an identifier just like a handle that can contain GS 2373 information that is opaque to the Client - so it has all the 2374 features of a handle, plus it can be the URL that is resolved to 2375 manipulate a Grant or an Authorization. As the Grant URI and AZ 2376 URI are defined to start with the GS URI, the Client (and GS) 2377 can easily determine which GS a Grant or Authorization belong 2378 to. URIs also enable a RESTful interface to the GS 2379 functionality. 2381 15. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 2382 known mechanism?* 2384 Having the GS URI endpoint respond to the metadata allows the GS 2385 to provide Client specific results using the same Client 2386 authentication used for other requests to the GS. It also 2387 reduces the risk of a mismatch between what the advertised 2388 metadata, and the actual metadata. A .well-known discovery 2389 mechanism may be defined to resolve from a hostname to the GS 2390 URI. 2392 16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AZ URI?* 2394 Maybe there are no use cases for them [that the editor knows 2395 of], but the GS can not implement, and they are available if use 2396 cases come up. 2398 13. Acknowledgments 2400 This draft derives many of its concepts from Justin Richer's 2401 Transactional Authorization draft [TxAuth]. 2403 Additional thanks to Justin Richer and Annabelle Richard Backman for 2404 their strong critique of earlier drafts. 2406 14. IANA Considerations 2408 [ JOSE parameter for Authorization HTTP header ] 2410 TBD 2412 15. Security Considerations 2414 TBD 2416 16. References 2418 16.1. Normative References 2420 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2421 Requirement Levels", BCP 14, RFC 2119, 2422 DOI 10.17487/RFC2119, March 1997, 2423 . 2425 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2426 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2427 . 2429 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2430 DOI 10.17487/RFC5322, October 2008, 2431 . 2433 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2434 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2435 . 2437 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2438 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2439 September 2009, . 2441 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2442 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2443 . 2445 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2446 Framework: Bearer Token Usage", RFC 6750, 2447 DOI 10.17487/RFC6750, October 2012, 2448 . 2450 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2451 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2452 2015, . 2454 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2455 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2456 . 2458 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2459 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2460 . 2462 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2463 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2464 DOI 10.17487/RFC7540, May 2015, 2465 . 2467 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2468 Interchange Format", STD 90, RFC 8259, 2469 DOI 10.17487/RFC8259, December 2017, 2470 . 2472 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2473 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2474 . 2476 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2477 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2478 . 2480 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2481 Assurance 1.0", October 2019, . 2484 16.2. Informative References 2486 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2487 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2488 October 2013, . 2490 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2491 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2492 . 2494 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2495 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2496 . 2498 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2499 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2500 Application Protocol) over TCP, TLS, and WebSockets", 2501 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2502 . 2504 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2505 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2506 DOI 10.17487/RFC8628, August 2019, 2507 . 2509 [browser_based_apps] 2510 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2511 Apps", September 2019, . 2514 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2515 Rich Authorization Requests", January 2020, 2516 . 2518 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2519 Credentials Data Model 1.0", November 2019, 2520 . 2522 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2523 identification and data capture techniques - QR Code bar 2524 code symbology specification", February 2015, 2525 . 2527 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2528 . 2531 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2532 Supplier Framework for Authentication and AuthN", 2533 September 2019, . 2536 Appendix A. Document History 2538 A.1. draft-hardt-xauth-protocol-00 2540 * Initial version 2542 A.2. draft-hardt-xauth-protocol-01 2544 * text clean up 2546 * added OIDC4IA claims 2548 * added "jws" method for accessing a resource. 2550 * renamed Initiation Request -> Grant Request 2552 * renamed Initiation Response -> Interaction Response 2554 * renamed Completion Request -> Authorization Request 2556 * renamed Completion Response -> Grant Request 2558 * renamed completion handle -> authorization handle 2560 * added Authentication Request, Authentication Response, 2561 authentication handle 2563 A.3. draft-hardt-xauth-protocol-02 2565 * major rewrite 2567 * handles are now URIs 2569 * the collection of claims and authorizations are a Grant 2571 * an Authorization is its own type 2573 * lots of sequences added 2575 A.4. draft-hardt-xauth-protocol-03 2577 * fixed RO definition 2579 * improved language in Rationals 2581 * added user code interaction method, and aligned qrcode interaction 2582 method 2584 * added completion_uri for code flows 2586 A.5. draft-hardt-xauth-protocol-04 2588 * renamed interaction uris to have purpose specific names 2590 A.6. draft-hardt-xauth-protocol-05 2592 * separated claims from identifiers in request user object 2594 * simplified reciprocal grant flow 2596 * reduced interactions to redirect and indirect 2598 * simplified interaction parameters 2600 * added in language for Client to verify interaction completion 2602 * added Verify Grant API and Interaction Nonce 2604 * replaced Refresh AuthZ with Read AuthZ. Read and refresh are same 2605 operation. 2607 A.7. draft-hardt-xauth-protocol-06 2609 * fixup examples to match specification 2611 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2613 *Changed Features* 2615 The major changes between this protocol and OAuth 2.0 and OpenID 2616 Connect are: 2618 * The Client allows uses a private key to authenticate in this 2619 protocol instead of the client secret in OAuth 2.0 and OpenID 2620 Connect. 2622 * The Client initiates the protocol by making a signed request 2623 directly to the GS instead of redirecting the User to the GS. 2625 * The Client does not pass any parameters in redirecting the User to 2626 the GS, and optionally only receives an interaction nonce in the 2627 redirection back from the GS. 2629 * The refresh_token has been replaced with a AZ URI that both 2630 represents the authorization, and is the URI for obtaining a fresh 2631 access token. 2633 * The Client can request identity claims to be returned independent 2634 of the ID Token. There is no UserInfo endpoint to query claims as 2635 there is in OpenID Connect. 2637 * The GS URI is the token endpoint. 2639 *Preserved Features* 2641 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2642 tokens of OAuth 2.0. 2644 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2645 Connect. 2647 * No change is required by the Client or the RS for accessing 2648 existing bearer token protected APIs. 2650 *New Features* 2652 * A Grant represents both the user identity claims and RS access 2653 granted to the Client. 2655 * The Client can verify, update, retrieve, and delete a Grant. 2657 * The GS can initiate a flow by creating a Grant and redirecting the 2658 User to the Client with the Grant URI. 2660 * The Client can discovery if a GS has a User with an identifier 2661 before the GS interacts with the User. 2663 * The Client can request the GS to first authenticate the User and 2664 return User identity claims, and then the Client can update Grant 2665 request based on the User identity. 2667 * Support for scannable code initiated interactions. 2669 * Each Client instance can have its own private / public key pair. 2671 * Highly extensible per Section 11. 2673 Author's Address 2675 Dick Hardt (editor) 2676 SignIn.Org 2677 United States 2679 Email: dick.hardt@gmail.com