idnits 2.17.00 (12 Aug 2021) /tmp/idnits37942/draft-hardt-xauth-protocol-03.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 57 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 226: '...egistered Client MAY be interacting wi...' RFC 2119 keyword, line 233: '... Dynamic Client MUST be interacting w...' RFC 2119 keyword, line 279: '... MUST start with the GS URI....' RFC 2119 keyword, line 285: '.... The AuthZ URI MUST start with the G...' RFC 2119 keyword, line 768: '... The Client MAY create, read, update...' (68 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (18 February 2020) is 823 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 793, but not defined == Unused Reference: 'RFC7516' is defined on line 2232, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 18 February 2020 5 Expires: 21 August 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-03 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 21 August 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 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.2. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 6 66 2.3. New Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3. Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 7 69 3.2. Reciprocal Grant . . . . . . . . . . . . . . . . . . . . 8 70 3.3. GS Initiated Grant . . . . . . . . . . . . . . . . . . . 10 71 3.4. Create and Update . . . . . . . . . . . . . . . . . . . . 10 72 3.5. Create and Delete . . . . . . . . . . . . . . . . . . . . 12 73 3.6. Create, Discover, and Delete . . . . . . . . . . . . . . 14 74 3.7. Create and Wait . . . . . . . . . . . . . . . . . . . . . 14 75 3.8. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 15 76 3.9. Access Token Refresh . . . . . . . . . . . . . . . . . . 16 77 3.10. GS API Table . . . . . . . . . . . . . . . . . . . . . . 16 78 4. Grant and AuthZ Life Cycle . . . . . . . . . . . . . . . . . 17 79 5. GS APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 80 5.1. Create Grant . . . . . . . . . . . . . . . . . . . . . . 18 81 5.2. Read Grant . . . . . . . . . . . . . . . . . . . . . . . 20 82 5.3. Update Grant . . . . . . . . . . . . . . . . . . . . . . 20 83 5.4. Delete Grant . . . . . . . . . . . . . . . . . . . . . . 21 84 5.5. Request JSON . . . . . . . . . . . . . . . . . . . . . . 22 85 5.5.1. "client" Object . . . . . . . . . . . . . . . . . . . 22 86 5.5.2. "interaction" Object . . . . . . . . . . . . . . . . 22 87 5.5.3. "user" Object . . . . . . . . . . . . . . . . . . . . 23 88 5.5.4. "authorization" Object . . . . . . . . . . . . . . . 24 89 5.5.5. "authorizations" Object . . . . . . . . . . . . . . . 24 90 5.5.6. "claims" Object . . . . . . . . . . . . . . . . . . . 24 91 5.5.7. "reciprocal" Object . . . . . . . . . . . . . . . . . 25 92 5.6. Refresh Authorization . . . . . . . . . . . . . . . . . . 25 93 5.7. Update Authorization . . . . . . . . . . . . . . . . . . 25 94 5.8. Delete Authorization . . . . . . . . . . . . . . . . . . 26 95 5.9. GS Options . . . . . . . . . . . . . . . . . . . . . . . 26 96 5.10. Grant Options . . . . . . . . . . . . . . . . . . . . . . 27 97 5.11. AuthZ Options . . . . . . . . . . . . . . . . . . . . . . 27 98 5.12. Request Verification . . . . . . . . . . . . . . . . . . 28 99 6. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 28 100 7. GS API Responses . . . . . . . . . . . . . . . . . . . . . . 28 101 7.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 28 102 7.2. Interaction Response . . . . . . . . . . . . . . . . . . 30 103 7.3. Wait Response . . . . . . . . . . . . . . . . . . . . . . 30 104 7.4. Response JSON . . . . . . . . . . . . . . . . . . . . . . 31 105 7.4.1. "interaction" Object . . . . . . . . . . . . . . . . 31 106 7.4.2. "user" Object . . . . . . . . . . . . . . . . . . . . 32 107 7.4.3. "authorization" Object . . . . . . . . . . . . . . . 32 108 7.4.4. "authorizations" Object . . . . . . . . . . . . . . . 33 109 7.4.5. "claims" Object . . . . . . . . . . . . . . . . . . . 33 110 7.4.6. "reciprocal" Object . . . . . . . . . . . . . . . . . 33 111 7.4.7. Interaction Types . . . . . . . . . . . . . . . . . . 34 112 7.4.8. Signing and Encryption . . . . . . . . . . . . . . . 34 113 7.5. Response Verification . . . . . . . . . . . . . . . . . . 34 114 8. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 35 115 8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 35 116 9. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 35 117 10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 35 118 10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 36 119 10.1.1. Authorization Header . . . . . . . . . . . . . . . . 36 120 10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 37 121 10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 38 122 10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 39 123 10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 39 124 10.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 39 125 10.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . 40 126 10.2.4. Public Key Resolution . . . . . . . . . . . . . . . 41 127 10.3. Request Encryption . . . . . . . . . . . . . . . . . . . 42 128 10.4. Response Signing . . . . . . . . . . . . . . . . . . . . 42 129 10.5. Response Encryption . . . . . . . . . . . . . . . . . . 42 130 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42 131 12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 43 132 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 133 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 134 15. Security Considerations . . . . . . . . . . . . . . . . . . . 48 135 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 136 16.1. Normative References . . . . . . . . . . . . . . . . . . 48 137 16.2. Informative References . . . . . . . . . . . . . . . . . 49 138 Appendix A. Document History . . . . . . . . . . . . . . . . . . 50 139 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 50 140 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 50 141 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 51 142 A.4. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 51 143 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 51 144 Appendix C. Open Questions . . . . . . . . . . . . . . . . . . . 52 145 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 52 147 1. Introduction 149 This protocol supports the widely deployed use cases supported by 150 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 151 extension of OAuth 2.0, as well as other extensions, and other use 152 cases that are not supported, such as acquiring multiple access 153 tokens at the same time, and updating the request during user 154 interaction. This protocol also addresses many of the security 155 issues in OAuth 2.0 by having parameters securely sent directly 156 between parties, rather than via a browser redirection. 158 The technology landscape has changed since OAuth 2.0 was initially 159 drafted. More interactions happen on mobile devices than PCs. 160 Modern browsers now directly support asymetric cryptographic 161 functions. Standards have emerged for signing and encrypting tokens 162 with rich payloads (JOSE) that are widely deployed. 164 Additional use cases are now being served with extensions to OAuth 165 2.0: OpenID Connect added support for authentication and releasing 166 identity claims; [RFC8252] added support for native apps; [RFC8628] 167 added support for smart devices; and support for [browser_based_apps] 168 is being worked on. There are numerous efforts on adding proof-of- 169 possession to resource access. 171 This protocol simplifies the overall architectural model, takes 172 advantage of today's technology landscape, provides support for all 173 the widely deployed use cases, and offers numerous extension points. 175 While this protocol is not backwards compatible with OAuth 2.0, it 176 strives to minimize the migration effort. 178 This protocol centers around a Grant, a representation of the 179 collection of user identity claims and/or resource authorizations the 180 Client is requesting, and the resulting identity claims and/or 181 resource authorizations granted by the Grant Server. 183 [Editor: suggestions on how to improve this are welcome!] 185 [Editor: suggestions for other names than XAuth are welcome!] 187 2. Terminology 189 2.1. Parties 191 The parties and their relationships to each other: 193 +--------+ +------------+ 194 | User | | Resource | 195 | | | Owner (RO) | 196 +--------+ +------------+ 197 | \ / | 198 | \ / | 199 | \ / | 200 | \ / | 201 +--------+ +---------------+ +------------+ 202 | Client |---->| Grant | _ _ | Resource | 203 | |<----| Server (GS) | | Server | 204 | | +---------------+ | (RS) | 205 | |-------------------------->| | 206 | |<--------------------------| | 207 +--------+ +------------+ 209 * *User* - the person interacting with the Client who has delegated 210 access to identity claims about themselves to the Grant Server 211 (GS), and can authenticate at the GS. 213 * *Client* - requests a Grant from the GS to access one or more 214 Resource Servers (RSs), and/or identity claims about the User. 215 The Client can create, retrieve, update, and delete a Grant. When 216 a Grant is created, the Client receives from the GS the granted 217 access token(s) for the RS(s), and identity claims about the User. 218 The Client uses an access token to access the RS. There are two 219 types of Clients: Registered Clients and Dynamic Clients. All 220 Clients have a key to authenticate with the Grant Server. 222 * *Registered Client* - a Client that has registered with the GS and 223 has a Client ID to identify itself, and can prove it possesses a 224 key that is linked to the Client ID. The GS may have different 225 policies for what different Registered Clients can request. A 226 Registered Client MAY be interacting with a User. 228 * *Dynamic Client* - a Client that has not been registered with the 229 GS, and each instance will generate it's own key pair so it can 230 prove it is the same instance of the Client on subsequent 231 requests, and to requests of a Resource Server. A single-page 232 application with no server is an example of a Dynamic Client. A 233 Dynamic Client MUST be interacting with a User. 235 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 236 release of identity claims about the User. The GS may require 237 explicit consent from the RO or User to provide these to the 238 Client. An GS may support Registered Clients and/or Dynamic 239 Clients. The GS is a combination of the Authorization Server (AS) 240 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 242 * *Resource Server* (RS) - has API resources that require an access 243 token from the GS. Owned by the Resource Owner. 245 * *Resource Owner* (RO) - owns resources at the RS, and has 246 delegated RS access management to the GS. The RO may be the same 247 entity as the User, or may be a different entity that the GS 248 interacts with independently. GS and RO interactions are out of 249 scope of this document. 251 2.2. Reused Terms 253 * *access token* - an access token as defined in [RFC6749] 254 Section 1.4. 256 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 257 issued by the GS, or by other issuers. 259 * *Client ID* - a GS unique identifier for a Registered Client as 260 defined in [RFC6749] Section 2.2. 262 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 264 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 266 * *authN* - short for authentication. 268 * *authZ* - short for authorization. 270 2.3. New Terms 272 * *GS URI* - the endpoint at the GS the Client calls to create a 273 Grant. The unique identifier for the GS. 275 * *Grant* - the user identity claims and/or RS authorizations the GS 276 has granted to the Client. 278 * *Grant URI* - the URI that represents the Grant. The Grant URI 279 MUST start with the GS URI. 281 * *Authorization* - the access granted by the RO to the Client. 282 Contains an access token. 284 * *AuthZ URI* - the URI that represents the Authorization the Client 285 was granted by the RO. The AuthZ URI MUST start with the GS URI. 286 The AuthZ URI is used to refresh, update, and delete an access 287 token. 289 * *interaction* - [Editor: what do we really mean by this term?] 291 3. Sequences 293 Before any sequence, the Client needs to be manually or 294 programmatically configured for the GS. See GS Options Section 5.9 295 for details on acquiring GS metadata. 297 [Editor: a plethora of sequences are included to illustrate all the 298 different actions. Many of these could potentially be moved to a use 299 case document in the future.] 301 3.1. Create Grant 303 The Client requests a Grant from the GS that requires User 304 interaction: 306 +--------+ +-------+ 307 | Client | | GS | 308 | |--(1)--- Create Grant ----------->| | 309 | | | (2) | 310 | |<--- Interaction Response ---(3)--| eval | 311 | | | | 312 | |--(4)--- Read Grant ------------->| | +------+ 313 | | | | | User | 314 | |--(5)--- Interaction Transfer --- | - - - | ------->| | 315 | | | |<--(6)-->| | 316 | | | | authN | | 317 | | | |<--(7)-->| | 318 | | | | authZ | | 319 | |<--- Interaction Transfer ---(8)- | - - - | --------| | 320 | | | | | | 321 | |<--------- Grant Response ---(9)--| | +------+ 322 | | | | 323 +--------+ +-------+ 325 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 326 and sends it with an HTTP POST to the GS GS URI. 328 2. *Grant Request Evaluation* The GS processes the request to 329 determine if it will send a Interaction Response, Wait Response, 330 or a Grant Response. The GS determines that interaction with the 331 User is required and sends an Interaction Response. (For 332 readability, this step is not described in the following 333 sequences) 335 3. *Interaction Response* The GS sends an Interaction Response 336 (Section 7.2) containing the Grant URI and an interaction object. 338 4. *Read Grant* The Client does an HTTP GET of the Grant URI 339 (Section 5.2). 341 5. *Interaction Transfer* The Client transfers User interaction to 342 the GS. 344 6. *User Authentication* The GS authenticates the User. 346 7. *User Authorization* If required, the GS interacts with the User 347 to determine which identity claims and/or authorizations in the 348 Grant Request are to be granted. 350 8. *Interaction Transfer* The GS transfers User interaction to the 351 Client. 353 9. *Grant Response* The GS responds with a Grant Response 354 (Section 7.1). 356 3.2. Reciprocal Grant 358 Party A and Party B are both a Client and a GS, and each Client would 359 like a Grant for the other GS. Party A starts off being the Client 360 per Create Grant Section 3.1. Party B then includes a Reciprocal 361 Request in its Grant Response. Party A then gets authorization from 362 the User and returns a Grant URI to Party B. Party A and B swap 363 roles, and Party B's Client obtains the Grant from Party A's GS. 365 Party A Party B 366 +--------+ +--------+ 367 | Client | | GS | 368 ~ ~ ~ ~ ~ ~ Same as steps 1 - 8 of ~ ~ ~ ~ ~ ~ 369 +------+ | | Create Grant above | | 370 | User | | | | | 371 | |<----- | - - - | -- Interaction Transfer ------- | | 372 | | | | | | 373 | | | |<------- Grant Response ---(1)---| | 374 | | | | Reciprocal Grant Request | | 375 | |<-(2)->| | | | 376 | | AuthZ | |---(3)--- Update Grant --------->| | 377 +------+ | | Reciprocal Grant Response | | 378 | | | | 379 | |<-- Empty Grant Response ---(4)--| | 380 | | | | 381 +--------+ (5) Swap Roles +--------+ 382 | GS | | Client | 383 | |<------------ Read Grant ---(6)--| | 384 | | | | 385 | |--(7)--- Grant Response -------->| | 386 | | | | 387 +--------+ +--------+ 389 1. *Grant Response* Party B responds with a Grant Response including 390 a Reciprocal Object Section 7.4.6 requesting its own Grant. 392 2. *User Authorization* If required, Party A interacts with the User 393 to determine which identity claims and/or authorizations in the 394 Grant Request are to be granted to Party B. 396 3. *Update Grant* Party A sends an Update Grant request containing 397 the Grant URI in the Reciprocal object Section 5.5.7. 399 4. *Grant Response* Party B responds with an Empty Grant Response as 400 there were no other requests in the Update Grant. 402 5. *Swap Roles* Party A now acts as a GS, Party B as a Client. 404 6. *Read Grant* Party B does an HTTP GET of the Grant URI 405 (Section 5.2). 407 7. *Grant Response* Party A responds with a Grant Response 408 (Section 7.1). 410 3.3. GS Initiated Grant 412 The User is at the GS, and wants to interact with a Registered 413 Client. The GS can redirect the User to the Client: 415 +--------+ +-------+ +------+ 416 | Client | | GS | | User | 417 | | | |<--(1)-->| | 418 | | | | | | 419 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 420 | (3) | | | | | 421 | verify |--(4)--- Read Grant ------------->| | +------+ 422 | | | | 423 | |<--------- Grant Response --(5)---| | 424 | | | | 425 +--------+ +-------+ 427 1. *User Interaction* The GS interacts with the User to determine 428 the Client and what identity claims and authorizations to 429 provide. The GS creates a Grant and corresponding Grant URI. 431 2. *GS Initiated Redirect* The GS redirects the User to the Client's 432 interaction_uri, adding a query parameter with the name "Grant 433 URI" and the value being the URL encoded Grant URI. 435 3. *Client Verification* The Client verifies the Grant URI is from 436 an GS the Client trusts, and starts with the GS GS URI. 438 4. *Read Grant* The Client does an HTTP GET of the Grant URI 439 (Section 5.2). 441 5. *Grant Response* The GS responds with a Grant Response 442 (Section 7.1). 444 See Section 6 for more details. 446 3.4. Create and Update 448 The Client requests an identity claim to determine who the User is. 449 Once the Client learns who the User is, and the Client updates the 450 Grant for additional identity claims which the GS prompts the User 451 for and returns to the Client. Once those are received, the Client 452 updates the Grant with the remaining identity claims required. 454 +--------+ +-------+ 455 | Client | | GS | 456 | |--(1)--- Create Grant ----------->| | 457 | | "interaction"."keep":true | | 458 | | | | 459 | |<--- Interaction Response ---(2)--| | 460 | | | | 461 | |--(3)--- Read Grant ------------->| | +------+ 462 | | | | | User | 463 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 464 | | | | | | 465 | | | |<--(5)-->| | 466 | | | | authN | | 467 | |<--------- Grant Response ---(6)--| | | | 468 | (7) | | | | | 469 | eval |--(8)--- Update Grant ----------->| | | | 470 | | "interaction"."keep":true | |<--(9)-->| | 471 | | | | authZ | | 472 | |<--------- Grant Response --(10)--| | | | 473 | (11) | | | | | 474 | eval |--(12)-- Update Grant ----------->| | | | 475 | | "interaction"."keep":false | |<--(13)->| | 476 | | | | authZ | | 477 | | | | | | 478 | |<--- Interaction Transfer --(14)- | - - - | --------| | 479 | | | | | | 480 | |<--------- Grant Response --(15)--| | +------+ 481 | | | | 482 +--------+ +-------+ 484 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 485 including an identity claim and "interaction"."keep":true, and 486 sends it with an HTTP POST to the GS GS URI. 488 2. *Interaction Response* The GS sends an Interaction Response 489 (Section 7.2) containing the Grant URI, an interaction object, 490 and "interaction"."keep":true. 492 3. *Read Grant* The Client does an HTTP GET of the Grant URI 493 (Section 5.2). 495 4. *Interaction Transfer* The Client transfers User interaction to 496 the GS. 498 5. *User Authentication* The GS authenticates the User. 500 6. *Grant Response* The GS responds with a Grant Response 501 (Section 7.1) including the identity claim from User 502 authentication and "interaction"."keep":true. 504 7. *Grant Evaluation* The Client queries its User database and does 505 not find a User record matching the identity claim. 507 8. *Update Grant* The Client creates an Update Grant Request 508 (Section 5.3) including the initial identity claims required and 509 "interaction"."keep":true, and sends it with an HTTP PUT to the 510 Grant URI. 512 9. *User AuthN* The GS interacts with the User to determine which 513 identity claims in the Update Grant Request are to be granted. 515 10. *Grant Response* The GS responds with a Grant Response 516 (Section 7.1) including the identity claims released by the User 517 and "interaction"."keep":true. 519 11. *Grant Evaluation* The Client evaluates the identity claims in 520 the Grant Response and determines the remaining User identity 521 claim required. 523 12. *Update Grant* The Client creates an Update Grant Request 524 (Section 5.3) including the remaining required identity claims 525 and "interaction"."keep":false, and sends it with an HTTP PUT to 526 the Grant URI. 528 13. *User AuthZ* The GS interacts with the User to determine which 529 identity claims in the Update Grant Request are to be granted. 531 14. *Interaction Transfer* The GS transfers User interaction to the 532 Client. 534 15. *Grant Response* The GS responds with a Grant Response 535 (Section 7.1) including the identity claims released by the 536 User. 538 3.5. Create and Delete 540 The Client requests an identity claim to determine who the User is. 541 Once the Client learns who the User is, and the Client knows it has 542 all the identity claims and authorizations needed, the Client deletes 543 the Grant which prompts the GS to transfer the interaction back to 544 the Client. 546 +--------+ +-------+ 547 | Client | | GS | 548 | |--(1)--- Create Grant ----------->| | 549 | | "interaction"."keep":true | | 550 | | | | 551 | |<--- Interaction Response ---(2)--| | 552 | | | | 553 | |--(3)--- Read Grant ------------->| | +------+ 554 | | | | | User | 555 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 556 | | | | | | 557 | | | |<--(5)-->| | 558 | | | | authN | | 559 | |<--------- Grant Response ---(6)--| | | | 560 | (7) | | | | | 561 | eval |--(8)--- Delete Grant ----------->| | | | 562 | |<------- Delete Response ---------| | | | 563 | | | | | | 564 | |<--- Interaction Transfer ---(9)- | - - - | --------| | 565 | | | | | | 566 +--------+ +-------+ +------+ 568 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 569 including an identity claim and "interaction"."keep":true, and 570 sends it with an HTTP POST to the GS GS URI. 572 2. *Interaction Response* The GS sends an Interaction Response 573 (Section 7.2) containing the Grant URI, an interaction object, 574 and "interaction"."keep":true. 576 3. *Read Grant* The Client does an HTTP GET of the Grant URI 577 (Section 5.2). 579 4. *Interaction Transfer* The Client transfers User interaction to 580 the GS. 582 5. *User Authentication* The GS authenticates the User. 584 6. *Grant Response* The GS responds with a Grant Response 585 (Section 7.1) including the identity claim from User 586 authentication and "interaction"."keep":true. 588 7. *Grant Evaluation* The Client queries its User database and finds 589 the User record matching the identity claim, and that no 590 additional claims or authorizations are required. 592 8. *Delete Grant* The Client no longer needs the Grant and decides 593 to Delete Grant (Section 5.4) by sending an HTTP DELETE to the 594 Grant URI. If the GS responds with success the Grant no longer 595 exists. 597 3.6. Create, Discover, and Delete 599 The Client wants to discover if the GS has a User with a given 600 identifier. If not, it will abort the request and not transfer 601 interaction to the GS. 603 +--------+ +-------+ 604 | Client | | GS | 605 | |--(1)--- Create Grant ----------->| | 606 | | "user"."exists":true | | 607 | | | | 608 | |<--- Interaction Response ---(2)--| | 609 | | "user"."exists":false | | 610 | | | | 611 | |--(3)--- Delete Grant ----------->| | 612 | |<------- Delete Response ---------| | 613 | | | | 614 +--------+ +-------+ 616 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 617 including an identity claim request, a User identifier, and 618 "user"."exists":true. The Client sends it with an HTTP POST to 619 the GS GS URI. 621 2. *Interaction Response* The GS sends an Interaction Response 622 (Section 7.2) containing the Grant URI, an interaction object, 623 and "user"."exists":false. 625 3. *Delete Grant* The Client determines the GS cannot fulfil its 626 Grant Request, and decides to Delete Grant (Section 5.4) by 627 sending an HTTP DELETE to the Grant URI. If the GS responds with 628 success the Grant no longer exists. 630 3.7. Create and Wait 632 The Client wants access to resources that require the GS to interact 633 with the RO, which may not happen immediately, so the GS instructs 634 the Client to wait and check back later. 636 +--------+ +-------+ 637 | Client | | GS | 638 | |--(1)--- Create Grant ----------->| | 639 | | | | 640 | |<---------- Wait Response ---(2)--| | +------+ 641 | (3) | | | | RO | 642 | Wait | | |<--(4)-->| | 643 | | | | authZ | | 644 | |--(5)--- Read Grant ------------->| | +------+ 645 | | | | 646 | |<--------- Grant Response --(6)---| | 647 | | | | 648 +--------+ +-------+ 650 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 651 and sends it with an HTTP POST to the GS GS URI. 653 2. *Wait Response* The GS sends an Interaction Response 654 (Section 7.3) containing the Grant URI and wait time. 656 3. *Client Waits* The Client waits the wait time. 658 4. *RO AuthZ* The GS interacts with the RO to determine which 659 identity claims in the Grant Request are to be granted. 661 5. *Read Grant* The Client does an HTTP GET of the Grant URI 662 (Section 5.2). 664 6. *Grant Response* The GS responds with a Grant Response 665 (Section 7.1). 667 3.8. Read Grant 669 The Client wants to acquire fresh identity claims and authorizations 670 in the Grant. No User or RO interaction is required as no new 671 consent or authorization is required. 673 +--------+ +-------+ 674 | Client | | GS | 675 | |--(1)--- Read Grant ------------->| | 676 | | | | 677 | |<--------- Grant Response --(2)---| | 678 | | | | 679 +--------+ +-------+ 681 1. *Read Grant* The Client does an HTTP GET of the Grant URI 682 (Section 5.2). 684 2. *Grant Response* The GS responds with a Grant Response 685 (Section 7.1) containing updated identity claims and 686 authorizations. 688 3.9. Access Token Refresh 690 The Client has an access token and uses it to access resources at an 691 RS. The access token expires, and the Client acquires a fresh access 692 token from the GS. 694 +--------+ +----------+ 695 | Client | | Resource | 696 | |--(1)--- Access Resource --->| Server | 697 | |<------- Resource Response --| (RS) | 698 | | | | 699 | |--(2)--- Access Resource --->| | 700 | |<------- Error Response -----| | 701 | | | | 702 | | +----------+ +-------+ 703 | | | GS | 704 | |--(3)--- Refresh AuthZ ------------------->| | 705 | |<------- AuthZ Response -------------------| | 706 | | | | 707 +--------+ +-------+ 709 1. *Resource Request* The Client accesses the RS with the access 710 token per Section 8 and receives a response from the RS. 712 2. *Resource Request* The Client attempts to access the RS, but 713 receives an error indicating the access token has expired. 715 3. *Refresh AuthZ* If the Client received an AuthZ URI in the 716 Response JSON "authorization" object (Section 7.4.3), the Client 717 can Refresh AuthZ (Section 5.6) with an HTTP GET to the AuthZ URI 718 and receive an Response JSON "authorization" object" 719 (Section 7.4.3) with a fresh access token. 721 3.10. GS API Table 723 +--------------+-----------+--------+-----------------------------+ 724 | request | http verb | uri | response | 725 +==============+===========+========+=============================+ 726 | Create Grant | POST | GS URI | interaction, wait, or grant | 727 +--------------+-----------+--------+-----------------------------+ 728 | Read Grant | GET | Grant | wait, or grant | 729 | | | URI | | 730 +--------------+-----------+--------+-----------------------------+ 731 | Update Grant | PUT | Grant | interaction, wait, or grant | 732 | | | URI | | 733 +--------------+-----------+--------+-----------------------------+ 734 | Delete Grant | DELETE | Grant | success | 735 | | | URI | | 736 +--------------+-----------+--------+-----------------------------+ 737 | Refresh | GET | AuthZ | authorization | 738 | AuthZ | | URI | | 739 +--------------+-----------+--------+-----------------------------+ 740 | Update AuthZ | PUT | AuthZ | authorization | 741 | | | URI | | 742 +--------------+-----------+--------+-----------------------------+ 743 | Delete AuthZ | DELETE | AuthZ | success | 744 | | | URI | | 745 +--------------+-----------+--------+-----------------------------+ 746 | GS Options | OPTIONS | GS URI | metadata | 747 +--------------+-----------+--------+-----------------------------+ 748 | Grant | OPTIONS | Grant | metadata | 749 | Options | | URI | | 750 +--------------+-----------+--------+-----------------------------+ 751 | AuthZ | OPTIONS | AuthZ | metadata | 752 | Options | | URI | | 753 +--------------+-----------+--------+-----------------------------+ 755 Table 1 757 [ Editor: is there value in an API for listing a Client's Grants? 758 eg:] 760 List Grants GET GS URI JSON array of Grant URIs 762 4. Grant and AuthZ Life Cycle 764 [Editor: straw man for life cycles.] 766 *Grant life Cycle* 768 The Client MAY create, read, update, and delete Grants. A Grant 769 persists until it has expired, is deleted, or another Grant is 770 created for the same GS, Client, and User tuple. 772 At any point in time, there can only be one Grant for the GS, Client, 773 and User tuple. When a Client creates a Grant at the same GS for the 774 same User, the GS MUST invalidate a previous Grant for the Client at 775 that GS for that User. 777 *Authorization Life Cycle* 778 Authorizations are OPTIONALLY included in a Grant Response 779 "authorization" Object (Section 7.4.3), and are represented by an 780 AuthZ URI. If an AuthZ URI is included, the Client MAY refresh, 781 update, and delete Authorizations. 783 An Authorization will persist independent of the Grant, and persist 784 until invalidated by the GS per GS policy, or deleted by the Client. 786 5. GS APIs 788 *Client Authentication* 790 All APIs except for GS Options require the Client to authenticate. 792 This document defines the JOSE Authentication mechanism in 793 Section 10. Other mechanisms include [TBD]. 795 5.1. Create Grant 797 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 798 document to the GS URI. 800 The JSON document MUST include the following from the Request JSON 801 Section 5.5: 803 * iat 805 * nonce 807 * uri set to the GS URI 809 * client 811 and MAY include the following from Request JSON Section 5.5 813 * user 815 * interaction 817 * authorization or authorizations 819 * claims 821 * reciprocal 823 The GS MUST respond with one of Grant Response Section 7.1, 824 Interaction Response Section 7.2, Wait Response Section 7.3, or one 825 of the following errors: 827 * TBD 829 from Error Responses Section 9. 831 Following is a non-normative example where the Client wants to 832 interact with the User with a popup and is requesting identity claims 833 about the User and read access to the User's contacts: 835 Example 1 837 { 838 "iat" : 15790460234, 839 "uri" : "https://as.example/endpoint", 840 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 841 "client": { 842 "display": { 843 "name" : "SPA Display Name", 844 "uri" : "https://spa.example/about" 845 } 846 }, 847 "interaction": { 848 "type" : "popup" 849 }, 850 "authorization": { 851 "type" : "oauth_scope", 852 "scope" : "read_contacts" 853 }, 854 "claims": { 855 "oidc": { 856 "id_token" : { 857 "email" : { "essential" : true }, 858 "email_verified" : { "essential" : true } 859 }, 860 "userinfo" : { 861 "name" : { "essential" : true }, 862 "picture" : null 863 } 864 } 865 } 866 } 868 Following is a non-normative example where the Client is requesting 869 the GS to keep the interaction with the User after returning the ID 870 Token so the Client can update the Grant, and is also asking if the 871 user exists: 873 Example 2 875 { 876 "iat" : 15790460234, 877 "uri" : "https://as.example/endpoint", 878 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 879 "client": { 880 "id" : "di3872h34dkJW" 881 }, 882 "interaction": { 883 "keep" : true, 884 "type" : "redirect", 885 "uri" : "https://web.example/return" 886 }, 887 "user": { 888 "identifiers": { 889 "email" : "jane.doe@example.com" 890 }, 891 "exists" : true 892 }, 893 "claims" : { "oidc": { "id_token" : {} } } 894 } 896 5.2. Read Grant 898 The Client reads a Grant by doing an HTTP GET of the corresponding 899 Grant URI. 901 The GS MUST respond with one of Grant Response Section 7.1, 902 Interaction Response Section 7.2, Wait Response Section 7.3, or one 903 of the following errors: 905 * TBD 907 from Error Responses Section 9. 909 5.3. Update Grant 911 The Client updates a Grant by doing an HTTP PUT of a JSON document to 912 the corresponding Grant URI. 914 The JSON document MUST include the following from the Request JSON 915 Section 5.5 917 * iat 919 * uri set to the Grant URI 920 and MAY include the following from Request JSON Section 5.5 922 * user 924 * interaction 926 * authorization or authorizations 928 * claims 930 * reciprocal 932 The GS MUST respond with one of Grant Response Section 7.1, 933 Interaction Response Section 7.2, Wait Response Section 7.3, or one 934 of the following errors: 936 * TBD 938 from Error Responses Section 9. 940 Following is a non-normative example where the Client made an 941 "interaction"."keep":true request, and now wants to update the 942 request with additional claims: 944 Example 3 946 { 947 "iat" : 15790460234, 948 "uri" : "https://as.example/endpoint/grant/example3", 949 "claims": { 950 "oidc": { 951 "userinfo" : { 952 "email" : { "essential" : true }, 953 "name" : { "essential" : true }, 954 "picture" : null 955 } 956 } 957 } 958 } 960 5.4. Delete Grant 962 The Client deletes a Grant by doing an HTTP DELETE of the 963 corresponding Grant URI. 965 The GS MUST respond with OK 200, or one of the following errors: 967 * TBD 968 from Error Responses Section 9. 970 5.5. Request JSON 972 [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ] 974 * *iat* - the time of the request as a NumericDate. 976 * *nonce* - a unique identifier for this request. Note the Grant 977 Response MUST contain a matching nonce attribute value. 979 * *uri* - the GS URI if in a Create Grant Section 5.1, or the Grant 980 URI if in an Update Grant Section 5.3. 982 5.5.1. "client" Object 984 The client object MUST contain either the id attribute for Registered 985 Clients, or the display object for Dynamic Clients. 987 * *id* - the Client ID the GS has for the Registered Client. 989 * *display* - the display object contains the following attributes: 991 - *name* - a string that represents the Dynamic Client 993 - *uri* - a URI representing the Dynamic Client 995 [Editor: a max length for the name?] [Editor: a max length for the 996 URI?] 998 The name and uri will be displayed by the GS when prompting for 999 authorization. 1001 5.5.2. "interaction" Object 1003 The interaction object contains the type of interaction the Client 1004 will provide the User. Other attributes 1006 * *keep* - a JSON boolean. If set to the JSON value true, the GS 1007 will not transfer the User interaction back to the Client after 1008 processing the Grant request. The JSON value false is equivalent 1009 to the attribute not being present, and the GS will transfer the 1010 User interaction back to the Client after processing the request. 1011 This attribute is OPTIONAL 1013 * *type* - contains one of the following values: "popup", 1014 "redirect", "qrcode", or "code". Details in Section 7.4.7. This 1015 attribute is REQUIRED. 1017 [Editor: do we want this to be an array of types the Client can 1018 support? This would only be the case if the GS is not able to 1019 support all types and negotiation is required. Is that required?] 1021 * *redirect_uri* - this attribute is REQUIRED if the type is 1022 "redirect". It is the URI that the Client requests the GS to 1023 redirect the User to after the GS has completed interacting with 1024 the User. If the Client manages session state in URIs, then the 1025 redirect_uri SHOULD contain that state. 1027 * *completion_uri* - this attribute is OPTIONAL and is ignored 1028 unless the type is "qrcode" or "code". This is the URI the Client 1029 would like the GS to redirect the User to after the interaction 1030 with the User is complete. 1032 * *ui_locales* - End-User's preferred languages and scripts for the 1033 user interface, represented as a space-separated list of [RFC5646] 1034 language tag values, ordered by preference. This attribute is 1035 OPTIONAL. 1037 [Editor: do we need max pixels or max chars for qrcode interaction? 1038 Either passed to GS, or max specified values here?] 1040 [Editor: other possible interaction models could be a "webview", 1041 where the Client can display a web page, or just a "message", where 1042 the client can only display a text message] 1044 [Editor: we may need to include interaction types for iOS and Android 1045 as the mobile OS APIs evolve.] 1047 5.5.3. "user" Object 1049 * *exists* - MUST contain the JSON true value. Indicates the Client 1050 requests the GS to return a "user"."exists" value in an 1051 Interaction Response Section 7.2. This attribute is OPTIONAL, and 1052 MAY be ignored by the GS. 1054 * *identifiers* - REQUIRED if the exists attribute is present. The 1055 values MAY be used by the GS to improve the User experience. 1056 Contains one or more of the following identifiers for the User: 1058 - *phone_number* - contains a phone number per Section 5 of 1059 [RFC3966]. 1061 - *email* - contains an email address per [RFC5322]. 1063 - *oidc* - is an object containing both the "iss" and "sub" 1064 attributes from an OpenID Connect ID Token per [OIDC] 1065 Section 2. 1067 5.5.4. "authorization" Object 1069 * *type* - one of the following values: "oauth_scope" or 1070 "oauth_rich". This attribute is REQUIRED. 1072 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1073 section 3.3. MUST be included if type is "oauth_scope" or 1074 "oauth_rich". 1076 * *authorization_details* - an authorization_details object per 1077 [RAR]. MUST be included if type is "oauth_rich". 1079 [Editor: details may change as the [RAR] document evolves] 1081 5.5.5. "authorizations" Object 1083 A JSON array of "authorization" objects. Only one of "authorization" 1084 or "authorizations" may be in the Request JSON. 1086 [Editor: instead of an array, we could have a Client defined 1087 dictionary of "authorization" objects] 1089 5.5.6. "claims" Object 1091 Includes one or more of the following: 1093 * *oidc* - an object that contains one or both of the following 1094 objects: 1096 - *userinfo* - Claims that will be returned as a JSON object 1098 - *id_token* - Claims that will be included in the returned ID 1099 Token. If the null value, an ID Token will be returned 1100 containing no additional Claims. 1102 The contents of the userinfo and id_token objects are Claims as 1103 defined in [OIDC] Section 5. 1105 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1106 per [OIDC4IA]. 1108 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1109 be requested.] 1111 5.5.7. "reciprocal" Object 1113 * *uri* - the Grant URI for the Reciprocal Grant. This attribute is 1114 REQUIRED. 1116 * *client* - the client object must contain the "id" attribute with 1117 the Client ID the Grant was issued to. This attribute is 1118 REQUIRED. 1120 * *authorization* - an authorization object per Section 7.4.3 in the 1121 Response JSON. 1123 * *authorizations* - an authorizations object per Section 7.4.4 in 1124 the Response JSON. 1126 * *claims* - a claims object per Section 7.4.5 in the Response JSON. 1128 [Editor: parameters for the Client to request it wants the Grant 1129 Response signed and/or encrypted?] 1131 5.6. Refresh Authorization 1133 The Client updates an Authorization by doing an HTTP GET to the 1134 corresponding AuthZ URI. 1136 The GS MUST respond with an Response JSON "authorization" object 1137 Section 7.4.3, or one of the following errors: 1139 * TBD 1141 from Error Responses Section 9. 1143 5.7. Update Authorization 1145 The Client updates an Authorization by doing an HTTP PUT to the 1146 corresponding AuthZ URI of the following JSON. All of the following 1147 MUST be included. 1149 * *iat* - the time of the response as a NumericDate. 1151 * *uri* - the AuthZ URI. 1153 * *authorization* - the new authorization requested per the Request 1154 JSON "authorization" object Section 5.5.4. 1156 The GS MUST respond with an Response JSON "authorization" object 1157 Section 7.4.3, or one of the following errors: 1159 * TBD 1161 from Error Responses Section 9. 1163 5.8. Delete Authorization 1165 The Client deletes an Authorization by doing an HTTP DELETE to the 1166 corresponding AuthZ URI. 1168 The GS MUST respond with OK 200, or one of the following errors: 1170 * TBD 1172 from Error Responses Section 9. 1174 5.9. GS Options 1176 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1177 of the corresponding GS URI. This is the only API where the GS MAY 1178 respond to an unauthenticated request. 1180 The GS MUST respond with the the following JSON document: 1182 [Editor: this section is a work in progress] 1184 * *uri* - the GS URI. 1186 * *client_authentication* - an array of the Client Authentication 1187 mechanisms supported by the GS 1189 * *interactions* - an array of the interaction types supported by 1190 the GS. 1192 * *authorization* - an object containing the authorizations the 1193 Client may request from the GS, if any. 1195 - Details TBD 1197 * *claims* - an object containing the identity claims the Client may 1198 request from the GS, if any, and what public keys the claims will 1199 be signed with. 1201 - Details TBD 1203 * *algorithms* - a list of the cryptographic algorithms supported by 1204 the GS. 1206 * *features* - an object containing feature support 1207 - *user_exists* - boolean indicating if "user"."exists" is 1208 supported. 1210 - *authorizations* - boolean indicating if a request for multiple 1211 authorizations is supported. 1213 [Editor: keys used by Client to encrypt requests, or verify signed 1214 responses?] 1216 [Editor: namespace metadata for extensions?] 1218 or one of the following errors: 1220 * TBD 1222 from Error Responses Section 9. 1224 5.10. Grant Options 1226 The Client can get the metadata for the Grant by doing an HTTP 1227 OPTIONS of the corresponding Grant URI. 1229 The GS MUST respond with the the following JSON document: 1231 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1233 or one of the following errors: 1235 * TBD 1237 from Error Responses Section 9. 1239 5.11. AuthZ Options 1241 The Client can get the metadata for the AuthZ by doing an HTTP 1242 OPTIONS of the corresponding AuthZ URI. 1244 The GS MUST respond with the the following JSON document: 1246 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1248 or one of the following errors: 1250 * TBD 1252 from Error Responses Section 9. 1254 5.12. Request Verification 1256 On receipt of a request, the GS MUST verify the following: 1258 * TBD 1260 6. GS Initiated Grant 1262 [Editor: In OAuth 2.0, all flows are initiated at the Client. If the 1263 AS wanted to initiate a flow, it redirected to the Client, that 1264 redirected back to the AS to initiate a flow. 1266 Here is a proposal to support GS initiated: authentication; just-in- 1267 time (JIT) provisioning; and authorization] 1269 *initiation_uri* A URI at the Client that contains no query or 1270 fragment. How the GS learns the Client initiation_uri is out of 1271 scope. 1273 The GS creates a Grant and Grant URI, and redirects the User to the 1274 initiation_uri with the query parameter "grant" and the value of 1275 Grant URI. 1277 See Section 3.3 for the sequence diagram. 1279 7. GS API Responses 1281 7.1. Grant Response 1283 The Grant Response MUST include the following from the Response JSON 1284 Section 7.4 1286 * iat 1288 * nonce 1290 * uri 1292 * expires_in 1294 and MAY include the following from the Response JSON Section 7.4 1296 * authorization or authorizations 1298 * claims 1300 * reciprocal 1301 Example non-normative Grant Response JSON document for Example 1 in 1302 Section 3.1: 1304 { 1305 "iat" : 15790460234, 1306 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1307 "uri" : "https://as.example/endpoint/grant/example1", 1308 "expires_in" : 300 1309 "authorization": { 1310 "type" : "oauth_scope", 1311 "scope" : "read_contacts", 1312 "expires_in" : 3600, 1313 "mechanism" : "bearer", 1314 "token" : "eyJJ2D6.example.access.token.mZf9p" 1315 }, 1316 "claims": { 1317 "oidc": { 1318 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1319 "userinfo" : { 1320 "name" : "John Doe", 1321 "picture" : "https://photos.example/p/eyJzdkiO" 1322 } 1323 } 1324 } 1325 } 1327 Example non-normative Grant Response JSON document for Example 2 in 1328 Section 3.1: 1330 { 1331 "iat" : 15790460234, 1332 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1333 "uri" : "https://as.example/endpoint/grant/example2", 1334 "authorization": { 1335 "type" : "oauth_scope", 1336 "scope" : "read_calendar write_calendar", 1337 "expires_in" : 3600, 1338 "mechanism" : "jose", 1339 "token" : "eyJJ2D6.example.access.token.mZf9p" 1340 "certificate": { 1341 "x5u" : "https://as.example/cert/example2" 1342 }, 1343 "uri" : "https://as.example/endpoint/authz/example2" 1344 } 1345 } 1347 7.2. Interaction Response 1349 The Interaction Response MUST include the following from the Response 1350 JSON Section 7.4 1352 * iat 1354 * nonce 1356 * uri 1358 * interaction 1360 and MAY include the following from the Response JSON Section 7.4 1362 * user 1364 * wait 1366 A non-normative example of an Interaction Response follows: 1368 { 1369 "iat" : 15790460234, 1370 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1371 "uri" : "https://as.example/endpoint/grant/example4", 1372 "interaction" : { 1373 "type" : "popup", 1374 "uri" : "https://as.example/popup/example4" 1375 }, 1376 "user": { 1377 "exists" : true 1378 } 1379 } 1381 7.3. Wait Response 1383 The Wait Response MUST include the following from the Response JSON 1384 Section 7.4 1386 * iat 1388 * nonce 1390 * uri 1392 * wait 1394 A non-normative example of an Wait Response follows: 1396 { 1397 "iat" : 15790460234, 1398 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1399 "uri" : "https://as.example/endpoint/grant/example5", 1400 "wait" : 300 1401 } 1403 7.4. Response JSON 1405 Details of the JSON document: 1407 * *iat* - the time of the response as a NumericDate. 1409 * *nonce* - the nonce that was included in the Request JSON 1410 Section 5.5. 1412 * *uri* - the Grant URI. 1414 * *wait* - a numeric value representing the number of seconds the 1415 Client should want before making a Read Grant request to the Grant 1416 URI. 1418 * *expires_in* - a numeric value specifying how many seconds until 1419 the Grant expires. This attribute is OPTIONAL. 1421 7.4.1. "interaction" Object 1423 If the GS wants the Client to start the interaction, the GS MUST 1424 return the interaction mechanism provided by the Client in the Grant 1425 Request, and include the required attributes in the interaction 1426 object: 1428 * *type* - this MUST match the type provided by the Client in the 1429 Grant Request client.interaction object. 1431 * *uri* - the URI to redirect the user to, load in the popup, or 1432 show the User to navigate to. This attribute is REQUIRED. 1434 * *qr* - the URI to show as a QR code. MUST be included if type is 1435 "qrcode" 1437 * *code* - a text string of the code to display to the User if type 1438 is "qrcode" or "code". 1440 [Editor: do we specify a maximum length for the displayed uri and 1441 code so that a device knows the maximum it needs to support? A smart 1442 device may have limited screen real estate.] 1443 TBD: entropy and other security considerations for the redirect and 1444 popup URI, and the code. 1446 See Interaction Types Section 7.4.7 for details. 1448 7.4.2. "user" Object 1450 * *exists* - a boolean value indicating if the GS has a user with 1451 one or more of the provided identifiers in the Request 1452 "user"."identifiers" object Section 5.5.3 1454 7.4.3. "authorization" Object 1456 The "authorization" object is a response to the Request 1457 "authorization" object Section 5.5.4, the Refresh Authorization 1458 Section 5.6, or the Update Authorization Section 5.7. 1460 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1461 See the "type" object in Section 5.5.4 for details. 1463 * *scope* - the scopes the Client was granted authorization for. 1464 This will be all, or a subset, of what was requested. This 1465 attribute is OPTIONAL. 1467 * *authorization_details* - the authorization details granted per 1468 [RAR]. Included if type is "oauth_rich". 1470 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1471 "jose+body". See Section 8 for details. 1473 * *token* - the access token for accessing an RS. This attribute is 1474 REQUIRED. 1476 * *expires_in* - a numeric value specifying how many seconds until 1477 the access token expires. This attribute is OPTIONAL. 1479 * *certificate* - MUST be included if the mechanism is "jose" or 1480 "jose+body". Contains the jwk header values for the Client to 1481 include in the JWS header when calling the RS using the "jose" or 1482 "jose+body" mechanisms. See Section 10.2.1. 1484 * *uri* - the AuthZ URI. Used to refresh, update, and delete the 1485 authorization. This attribute is OPTIONAL. 1487 [Editor: any value in an expiry for the Authorization?] 1489 7.4.4. "authorizations" Object 1491 A JSON array of authorization objects. Support for the 1492 authorizations object is OPTIONAL. 1494 7.4.5. "claims" Object 1496 The claims object is a response to the Request "claims" object 1497 Section 5.5.4. 1499 * *oidc* 1501 - *id_token* - an OpenID Connect ID Token containing the Claims 1502 the User consented to be released. 1504 - *userinfo* - the Claims the User consented to be released. 1506 Claims are defined in [OIDC] Section 5. 1508 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1509 per [OIDC4IA]. 1511 * *vc* 1513 The verified claims the user consented to be released. [Editor: 1514 details TBD] 1516 7.4.6. "reciprocal" Object 1518 The following MUST be included 1520 * *nonce* - a unique identifier for this request. Note the Grant 1521 Response MUST contain a matching nonce attribute value. 1523 * *client* 1525 - *id* - the Client ID making the request 1527 One or more of the following objects from the Request JSON 1528 Section 5.5 are included: 1530 * *authorization* Section 7.4.3 1532 * *authorizations* Section 7.4.4 1534 * *claims* Section 7.4.5 1536 7.4.7. Interaction Types 1538 If the GS wants the Client to initiate the interaction with the User, 1539 then the GS will return an Interaction Response. The Client will 1540 initiate the interaction with the User in one of the following ways: 1542 * *popup* The Client will create a new popup child browser window 1543 with URI contained in the "interaction"."uri" attribute. [Editor: 1544 more details on how to do this] The GS will close the popup window 1545 when the interactions with the User are complete. [Editor: 1546 confirm GS can do this still on all browsers, or does Client need 1547 to close?] 1549 * *redirect* The Client will redirect the User to the 1550 "interaction"."uri" attribute. When the GS interactions with the 1551 User are complete, the GS will redirect the User to the 1552 "interaction"."redirect_uri" attribute the Client provided in the 1553 Grant Request. 1555 * *qrcode* The Client will create a [QR_Code] of the 1556 "interaction"."qr" attribute and display the resulting graphic. 1557 The CLient will also display the "interaction"."uri" and 1558 "interaction"."code" per the "code" type. 1560 * *code* The Client will display the "interaction"."code" contents 1561 and direct the User to navigate to the "interaction"."uri" value 1562 and enter the code. 1564 A GS MUST support the "popup", "redirect", "qrcode", and "code" 1565 interaction types. 1567 [Editor: is this too restrictive?] 1569 7.4.8. Signing and Encryption 1571 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1572 there a generalized description, or is it mechanism specific?] 1574 7.5. Response Verification 1576 On receipt of a response, the Client MUST verify the following: 1578 * TBD 1580 8. RS Access 1582 This document specifies three different mechanisms for the Client to 1583 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1584 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1585 mechanisms are proof-of-possession mechanisms and are defined in 1586 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1587 possession mechanisms may be defined in other documents. The 1588 mechanism the Client is to use with an RS is the Response JSON 1589 "authorization"."mechanism" attribute Section 7.4.3. 1591 8.1. Bearer Token 1593 If the access mechanism is "bearer", then the Client accesses the RS 1594 per Section 2.1 of [RFC6750] 1596 A non-normative example of the HTTP request headers follows: 1598 GET /calendar HTTP/2 1599 Host: calendar.example 1600 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1602 9. Error Responses 1604 * TBD 1606 10. JOSE Authentication 1608 How the Client authenticates to the GS and RS are independent of each 1609 other. One mechanism can be used to authenticate to the GS, and a 1610 different mechanism to authenticate to the RS. 1612 Other documents that specify other Client authentication mechanisms 1613 will replace this section. 1615 In the JOSE Authentication Mechanism, the Client authenticates by 1616 using its private key to sign a JSON document with JWS per [RFC7515] 1617 which results in a token using JOSE compact serialization. 1619 [Editor: are there advantages to using JSON serialization in the 1620 body?] 1622 Different instances of a Registered Clients MAY have different 1623 private keys, but certificates bind them to a public key the GS has 1624 for the Client ID. An instance of a Client will use the same private 1625 key for all signing. 1627 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1628 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1630 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1632 The token may be included in an HTTP header, or as the HTTP message 1633 body. 1635 The following sections specify how the Client uses JOSE to 1636 authenticate to the GS and RS. 1638 10.1. GS Access 1640 The Client authenticates to the GS by passing either a signed header 1641 parameter, or a signed message body. The following table shows the 1642 verb, uri and token location for each Client request to the GS: 1644 +---------------+-----------+-----------+----------+ 1645 | request | http verb | uri | token in | 1646 +===============+===========+===========+==========+ 1647 | Create Grant | POST | GS URI | body | 1648 +---------------+-----------+-----------+----------+ 1649 | Read Grant | GET | Grant URI | header | 1650 +---------------+-----------+-----------+----------+ 1651 | Update Grant | PUT | Grant URI | body | 1652 +---------------+-----------+-----------+----------+ 1653 | Delete Grant | DELETE | Grant URI | success | 1654 +---------------+-----------+-----------+----------+ 1655 | Refresh AuthZ | GET | AuthZ URI | body | 1656 +---------------+-----------+-----------+----------+ 1657 | Update AuthZ | PUT | AuthZ URI | body | 1658 +---------------+-----------+-----------+----------+ 1659 | Delete AuthZ | DELETE | AuthZ URI | header | 1660 +---------------+-----------+-----------+----------+ 1661 | GS Options | OPTIONS | GS URI | header | 1662 +---------------+-----------+-----------+----------+ 1663 | Grant Options | OPTIONS | Grant URI | header | 1664 +---------------+-----------+-----------+----------+ 1665 | AuthZ Options | OPTIONS | AuthZ URI | header | 1666 +---------------+-----------+-----------+----------+ 1668 Table 2 1670 10.1.1. Authorization Header 1672 For requests with the token in the header, the JWS payload MUST 1673 contain the following attributes: 1675 *iat* - the time the token was created as a NumericDate. 1677 *jti* - a unique identifier for the token per [RFC7519] section 1678 4.1.7. 1680 *uri* - the value of the URI being called (GS URI, Grant URI, or 1681 AuthZ URI). 1683 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1684 "OPTIONS") 1686 The HTTP authorization header is set to the "jose" parameter followed 1687 by one or more white space characters, followed by the resulting 1688 token. 1690 A non-normative example of a JWS payload and the HTTP request 1691 follows: 1693 { 1694 "iat" : 15790460234, 1695 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1696 "uri" : "https://as.example/endpoint/grant/example6", 1697 "verb" : "GET" 1698 } 1700 GET /endpoint/example.grant HTTP/2 1701 Host: as.example 1702 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1704 [Editor: make a real example token] 1706 *GS Verification* 1708 The GS MUST verify the token by: 1710 * TBD 1712 10.1.2. Signed Body 1714 For requests with the token in the body, the Client uses the Request 1715 JSON as the payload in a JWS. The resulting token is sent with the 1716 content-type set to "application/jose". 1718 A non-normative example (line breaks added to the body for 1719 readability): 1721 POST /endpoint HTTP/2 1722 Host: as.example 1723 Content-Type: application/jose 1724 Content-Length: 155 1726 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1727 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1728 Jf36POk6yJV_adQssw5c 1730 [Editor: make a real example token] 1732 *GS Verification* 1734 The GS MUST verify the token by: 1736 * TBD 1738 10.1.3. Public Key Resolution 1740 * *Registered Clients* can use any of the JWS header values to 1741 direct the GS to resolve the public key matching the private key 1742 used to the Client ID. The GS MAY restrict with JWS headers a 1743 Client can use. 1745 [Editor: would examples help here so that implementors understand the 1746 full range of options, and how an instance can have its own asymetric 1747 key pair] 1749 A non-normative example of a JOSE header for a Registered Client with 1750 a key identifier of "12": 1752 { 1753 "alg" : "ES256", 1754 "typ" : "JOSE", 1755 "kid" : "12" 1756 } 1758 * *Dynamic Clients* include their public key in the "jwk" JWS 1759 header. 1761 A non-normative example of a JOSE header for a Dynamic Client: 1763 { 1764 "alg" : "ES256", 1765 "typ" : "JOSE", 1766 "jwk" : { 1767 "kty" : "EC", 1768 "crv" : "P-256", 1769 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1770 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1771 } 1772 } 1774 10.2. RS Access 1776 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 1777 include a proof-of-possession token in the HTTP authorization header. 1778 In the "jose+body" mechanism Section 10.2.3, the Client signs the 1779 JSON document in the request if the POST or PUT verbs are used, 1780 otherwise it is the same as the "jose" mechanism. 1782 10.2.1. JOSE header 1784 The GS provides the Client one or more JWS header parameters and 1785 values for a a certificate, or a reference to a certificate or 1786 certificate chain, that the RS can use to resolve the public key 1787 matching the private key being used by the Client. 1789 A non-normative examples JOSE header: 1791 { 1792 "alg" : "ES256", 1793 "typ" : "JOSE", 1794 "x5u" : "https://as.example/cert/example2" 1795 } 1797 [Editor: this enables Dynamic Clients to make proof-of-possession API 1798 calls the same as Registered Clients.] 1800 10.2.2. "jose" Mechanism 1802 The JWS payload MUST contain the following attributes: 1804 *iat* - the time the token was created as a NumericDate. 1806 *jti* - a unique identifier for the token per [RFC7519] section 1807 4.1.7. 1809 *uri* - the value of the RS URI being called. 1811 *verb* - the HTTP verb being used in the call 1813 *token* - the access token provided by the GS to the Client 1815 The HTTP authorization header is set to the "jose" parameter followed 1816 by one or more white space characters, followed by the resulting 1817 token. 1819 A non-normative example of a JWS payload and the HTTP request 1820 follows: 1822 { 1823 "iat" : 15790460234, 1824 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1825 "uri" : "https://calendar.example/calendar", 1826 "verb" : "GET", 1827 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 1828 } 1830 GET /calendar HTTP/2 1831 Host: calendar.example 1832 Authorization: jose eyJhbG.example.jose.token.adks 1834 [Editor: make a real example token] 1836 *RS Verification* 1838 The RS MUST verify the token by: 1840 * verify access token is bound to the public key - include key 1841 fingerprint in access token? 1843 * TBD 1845 10.2.3. "jose+body" Mechanism 1847 The "jose+body" mechanism can only be used if the content being sent 1848 to the RS is a JSON document. 1850 Any requests not sending a message body will use the "jose" mechanism 1851 Section 10.2.2. 1853 Requests sending a message body MUST have the following JWS payload: 1855 *iat* - the time the token was created as a NumericDate. 1857 *jti* - a unique identifier for the token per [RFC7519] section 1858 4.1.7. 1860 *uri* - the value of the RS URI being called. 1862 *verb* - the HTTP verb being used in the call 1864 *token* - the access token provided by the GS to the Client 1866 *body* - the message body being sent to the RS 1868 A non-normative example of a JWS payload and the HTTP request 1869 follows: 1871 { 1872 "iat" : 15790460234, 1873 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1874 "uri" : "https://calendar.example/calendar", 1875 "verb" : "POST", 1876 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 1877 "payload" : { 1878 "event" : { 1879 "title" : "meeting with joe", 1880 "start_date_utc" : "2020-02-21 11:00:00", 1881 "end_date_utc" : "2020-02-21 11:00:00" 1882 } 1883 } 1884 } 1886 POST /calendar HTTP/2 1887 Host: calendar.example 1888 Content-Type: application/jose 1889 Content-Length: 155 1891 eyJhbGciOi.example.jose+body.adasdQssw5c 1893 [Editor: make a real example token] 1895 *RS Verification* 1897 The RS MUST verify the token by: 1899 * TBD 1901 10.2.4. Public Key Resolution 1903 The RS has a public key for the GS that it uses to verify the 1904 certificate or certificate chain the Client includes in the JWS 1905 header. 1907 10.3. Request Encryption 1909 [Editor: to be fleshed out] 1911 The Client encrypts a request when ??? using the GS public key 1912 returned as the ??? attribute in GS Options Section 5.9. 1914 10.4. Response Signing 1916 [Editor: to be fleshed out] 1918 The Client verifies a signed response ??? using the GS public key 1919 returned as the ??? attribute in GS Options Section 5.9. 1921 10.5. Response Encryption 1923 [Editor: to be fleshed out] 1925 The Client decrypts a response when ??? using the private key 1926 matching the public key included in the request as the ??? attribute 1927 in Section 5.5. 1929 11. Extensibility 1931 This standard can be extended in a number of areas: 1933 * *Client Authentication Mechanisms* 1935 - An extension could define other mechanisms for the Client to 1936 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1937 Signing. Constrained environments could use CBOR [RFC7049] 1938 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1939 [RFC8323] instead of HTTP/2. 1941 * *Grant* 1943 - An extension can define new objects in the Grant Request and 1944 Grant Response JSON. 1946 * *Top Level* 1948 - Top level objects SHOULD only be defined to represent 1949 functionality other the existing top level objects and 1950 attributes. 1952 * *"client" Object* 1953 - Additional information about the Client that the GS would 1954 require related to an extension. 1956 * *"user" Object* 1958 - Additional information about the User that the GS would require 1959 related to an extension. 1961 * *"authorization" Object* 1963 - Additional types of authorizations in addition to OAuth 2.0 1964 scopes and RAR. 1966 * *"claims" Object* 1968 - Additional types of identity claims in addition to OpenID 1969 Connect claims and Verified Credentials. 1971 * *Interaction types* 1973 - Additional types of interactions a Client can start with the 1974 User. 1976 * *Continuous Authentication* 1978 - An extension could define a mechanism for the Client to 1979 regularly provide continuous authentication signals and receive 1980 responses. 1982 [Editor: do we specify access token / handle introspection in this 1983 document, or leave that to an extension?] 1985 [Editor: do we specify access token / handle revocation in this 1986 document, or leave that to an extension?] 1988 12. Rational 1990 1. *Why is there only one mechanism for the Client to authenticate 1991 with the GS? Why not support other mechanisms?* 1993 Having choices requires implementers to understand which choice 1994 is preferable for them. Having one default mechanism in the 1995 document for the Client to authenticate simplifies most 1996 implementations. Deployments that have unique characteristics 1997 can select other mechanisms that are preferable in specific 1998 environments. 2000 2. *Why is the default Client authentication JOSE rather than 2001 MTLS?* 2003 MTLS cannot be used today by a Dynamic Client. MTLS requires 2004 the application to have access below what is typically the 2005 application layer, that is often not available on some 2006 platforms. JOSE is done at the application layer. Many GS 2007 deployments will be an application behind a proxy performing 2008 TLS, and there are risks in the proxy passing on the results of 2009 MTLS. 2011 3. *Why is the default Client authentication JOSE rather than HTTP 2012 signing?* 2014 There is currently no widely deployed open standard for HTTP 2015 signing. Additionally, HTTP signing requires passing all the 2016 relevant parts of the HTTP request to downstream services within 2017 an GS that may need to independently verify the Client identity. 2019 4. *What are the advantages of using JOSE for the Client to 2020 authenticate to the GS and a resource?* 2022 Both Registered Clients and Dynamic Clients can have a private 2023 key, eliminating the public Client issues in OAuth 2.0, as a 2024 Dynamic Client can create an ephemeral key pair. Using 2025 asymetric cryptography also allows each instance of a Registered 2026 Client to have its own private key if it can obtain a 2027 certificate binding its public key to the public key the GS has 2028 for the Client. Signed tokens can be passed to downstream 2029 components in a GS or RS to enable independent verification of 2030 the Client and its request. The GS Initiated Sequence Section 6 2031 requires a URL safe parameter, and JOSE is URL safe. 2033 5. *Why does the GS not return parameters to the Client in the 2034 redirect url?* 2036 Passing parameters via a browser redirection is the source of 2037 many of the security risks in OAuth 2.0. It also presents a 2038 challenge for smart devices. In this protocol, the redirection 2039 from the Client to the GS is to enable the GS to interact with 2040 the User, and the redirection back to the Client is to hand back 2041 interaction control to the Client if the redirection was a full 2042 browser redirect. Unlike OAuth 2.0, the identity of the Client 2043 is independent of the URI the GS redirects to. 2045 6. *Why is there not a UserInfo endpoint as there is with OpenID 2046 Connect?* 2047 Since the Client can Read Grant at any time, it get the same 2048 functionality as the UserInfo endpoint, without the Client 2049 having to manage a separate access token and refresh token. If 2050 the Client would like additional claims, it can Update Grant, 2051 and the GS will let the Client know if an interaction is 2052 required to get any of the additional claims, which the Client 2053 can then start. 2055 [Editor: is there some other reason to have the UserInfo 2056 endpoint?] 2058 7. *Why is there still a Client ID?* 2060 The GS needs an identifier to fetch the meta data associated 2061 with a Client such as the name and image to display to the User, 2062 and the policies on what a Client is allowed to do. The Client 2063 ID was used in OAuth 2.0 for the same purpose, which simplifies 2064 migration. Dynamic Clients do not have a Client ID. 2066 8. *Why have both claims and authorizations?* 2068 There are use cases for each that are independent: 2069 authenticating a user and providing claims vs granting access to 2070 a resource. A request for an authorization returns an access 2071 token which may have full CRUD capabilities, while a request for 2072 a claim returns the claim about the User - with no create, 2073 update or delete capabilities. While the UserInfo endpoint in 2074 OIDC may be thought of as a resource, separating the concepts 2075 and how they are requested keeps each of them simpler in the 2076 Editor's opinion. :) 2078 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2079 GS communication in ?*Section 10 2081 Knowing the GS supports HTTP/2 enables a Client to set up a 2082 connection faster. HTTP/2 will be more efficient when Clients 2083 have large numbers of access tokens and are frequently 2084 refreshing them at the GS as there will be less network traffic. 2085 Mandating TLS 1.3 similarly improves the performance and 2086 security of Clients and GS when setting up a TLS connection. 2088 10. *Why do some of the JSON objects only have one child, such as 2089 the identifiers object in the user object in the Grant Request?* 2091 It is difficult to forecast future use cases. Having more 2092 resolution may mean the difference between a simple extension, 2093 and a convoluted extension. 2095 11. *Why is the "iss" included in the "oidc" identifier object? 2096 Would the "sub" not be enough for the GS to identify the User?* 2098 This decouples the GS from the OpenID Provider (OP). The GS 2099 identifier is the GS URI, which is the endpoint at the GS. The 2100 OP issuer identifier will likely not be the same as the GS URI. 2101 The GS may also provide claims from multiple OPs. 2103 12. *Why complicate things with "interaction"."keep"?* 2105 The common sequence has a back and forth between the Client and 2106 the GS, and the Client can update the Grant and have a new 2107 interaction. Keeping the interaction provides a more seamless 2108 user experience where the results from the first request 2109 determine subsequent requests. For example, a common pattern is 2110 to use a GS to authenticate the User at the Client, and to 2111 register the User at the Client using additional claims from the 2112 GS. The Client does not know a priori if the User is a new 2113 User, or a returning User. Asking a returning User to consent 2114 releasing claims they have already provided is a poor User 2115 experience, as is sending the User back to the GS. The Client 2116 requesting identity first enables the Client to get a response 2117 from the GS while the GS is still interacting with the User, so 2118 that the Client can request additional claims only if needed. 2119 Additionally, the claims a Client may want about a User may be 2120 dependent on some initial Claims. For example, if a User is in 2121 a particular country, additional or different Claims my be 2122 required by the Client. 2124 There are also benefits for the GS. Today, a GS usually keeps 2125 track of which claims a Client has requested for a User. 2126 Storing this information for all Clients a User uses may be 2127 undesirable for a GS that does not want to have that information 2128 about the User. Keeping the interaction allows the Client to 2129 track what information it has about the User, and the GS can 2130 remain stateless. 2132 13. *Why is there a "jose+body" RS access mechanism method for the 2133 Client?*Section 10.2.3 2135 There are numerous use cases where the RS wants non-repudiation 2136 and providence of the contents of an API call. For example, the 2137 UGS Service Supplier Framework for Authentication and 2138 Authorization [UTM]. 2140 14. *Why use URIs to instead of handles for the Grant and 2141 Authorization?* 2142 A URI is an identifier just like a handle that can contain GS 2143 information that is opaque to the Client - so it has all the 2144 features of a handle, plus it can be the URL that is resolved to 2145 manipulate a Grant or an Authorization. As the Grant URI and 2146 AuthZ URI are defined to start with the GS URI, the Client (and 2147 GS) can easily determine which GS a Grant or Authorization 2148 belong to. URIs also enable a RESTful interface to the GS 2149 functionality. 2151 15. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 2152 known mechanism?* 2154 Having the GS URI endpoint respond to the metadata allows the GS 2155 to provide Client specific results using the same Client 2156 authentication used for other requests to the GS. It also 2157 reduces the risk of a mismatch between what the advertised 2158 metadata, and the actual metadata. A .well-known discovery 2159 mechanism may be defined to resolve from a hostname to the GS 2160 URI. 2162 16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AuthZ 2163 URI?* 2165 Maybe there are no use cases for them [that the editor knows 2166 of], but the GS can not implement, and they are available if use 2167 cases come up. 2169 17. *Why list explicit interactions, instead of the Client and GS 2170 negotiating interaction capabilities?* 2172 The Client knows what interactions it is capable of, and 2173 prefers. Telling the GS the interaction allows the GS to know 2174 what interaction the User will have. Knowing how the Client 2175 will transition the interaction will enable the GS to provider a 2176 better User experience. For example, the GS may want to provide 2177 a short URL if it knows the Client will be showing a QR code vs 2178 a redirect, or have a different layout if it is a popup vs a 2179 redirect. 2181 [Editor: are there use cases where the Client would want to 2182 provide a list of interaction types so the GS can select which 2183 one it can support? ] 2185 13. Acknowledgments 2187 This draft derives many of its concepts from Justin Richer's 2188 Transactional Authorization draft [TxAuth]. 2190 Additional thanks to Justin Richer and Annabelle Richard Backman for 2191 their strong critique of earlier drafts. 2193 14. IANA Considerations 2195 [ JOSE parameter for Authorization HTTP header ] 2197 TBD 2199 15. Security Considerations 2201 TBD 2203 16. References 2205 16.1. Normative References 2207 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2208 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2209 . 2211 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2212 DOI 10.17487/RFC5322, October 2008, 2213 . 2215 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2216 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2217 September 2009, . 2219 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2220 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2221 . 2223 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2224 Framework: Bearer Token Usage", RFC 6750, 2225 DOI 10.17487/RFC6750, October 2012, 2226 . 2228 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2229 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2230 2015, . 2232 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2233 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2234 . 2236 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2237 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2238 . 2240 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2241 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2242 DOI 10.17487/RFC7540, May 2015, 2243 . 2245 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2246 Interchange Format", STD 90, RFC 8259, 2247 DOI 10.17487/RFC8259, December 2017, 2248 . 2250 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2251 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2252 . 2254 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2255 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2256 . 2258 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2259 Assurance 1.0", October 2019, . 2262 16.2. Informative References 2264 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2265 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2266 October 2013, . 2268 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2269 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2270 . 2272 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2273 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2274 . 2276 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2277 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2278 Application Protocol) over TCP, TLS, and WebSockets", 2279 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2280 . 2282 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2283 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2284 DOI 10.17487/RFC8628, August 2019, 2285 . 2287 [browser_based_apps] 2288 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2289 Apps", September 2019, . 2292 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2293 Rich Authorization Requests", January 2020, 2294 . 2296 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2297 Credentials Data Model 1.0", November 2019, 2298 . 2300 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2301 identification and data capture techniques - QR Code bar 2302 code symbology specification", February 2015, 2303 . 2305 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2306 . 2309 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2310 Supplier Framework for Authentication and AuthN", 2311 September 2019, . 2314 Appendix A. Document History 2316 A.1. draft-hardt-xauth-protocol-00 2318 * Initial version 2320 A.2. draft-hardt-xauth-protocol-01 2322 * text clean up 2324 * added OIDC4IA claims 2326 * added "jws" method for accessing a resource. 2328 * renamed Initiation Request -> Grant Request 2330 * renamed Initiation Response -> Interaction Response 2331 * renamed Completion Request -> Authorization Request 2333 * renamed Completion Response -> Grant Request 2335 * renamed completion handle -> authorization handle 2337 * added Authentication Request, Authentication Response, 2338 authentication handle 2340 A.3. draft-hardt-xauth-protocol-02 2342 * major rewrite 2344 * handles are now URIs 2346 * the collection of claims and authorizations are a Grant 2348 * an Authorization is its own type 2350 * lots of sequences added 2352 A.4. draft-hardt-xauth-protocol-03 2354 * fixed RO definition 2356 * improved language in Rationals 2358 * added user code interaction method, and aligned qrcode interaction 2359 method 2361 * added completion_uri for code flows 2363 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2365 *Changed Features* 2367 The major changes between this protocol and OAuth 2.0 and OpenID 2368 Connect are: 2370 * The Client uses a private key to authenticate in this protocol 2371 instead of the client secret in OAuth 2.0 and OpenID Connect. 2373 * The Client initiates the protocol by making a signed request 2374 directly to the GS instead of redirecting the User to the GS. 2376 * The Client does not pass any parameters in redirecting the User to 2377 the GS, nor receive any parameters in the redirection back from 2378 the GS. 2380 * The refresh_token has been replaced with a AuthZ URI that both 2381 represents the access, and is the URI to call to refresh access. 2383 * The Client can request identity claims to be returned independent 2384 of the ID Token. There is no UserInfo endpoint to query claims as 2385 there is in OpenID Connect. 2387 * The GS URI is the token endpoint. CHECK!!!s 2389 *Preserved Features* 2391 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2392 tokens of OAuth 2.0. 2394 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2395 Connect. 2397 * No change is required by the Client or the RS for existing bearer 2398 token protected APIs. 2400 *New Features* 2402 * A Grant represents the user identity claims and RS access granted 2403 to the Client. 2405 * The Client can update, retrieve, and delete a Grant. 2407 * The GS can initiate a flow by creating a Grant and redirecting the 2408 User to the Client with the Grant URI. 2410 * The Client can discovery if an GS has a User with an identifier 2411 before the GS interacts with the User. 2413 * The Client can request the GS to first authenticate the User and 2414 return User identity claims, and then the Client can update Grant 2415 request based on the User identity. 2417 * Support for QR Code initiated interactions. 2419 * Each Client instance can have its own private / public key pair. 2421 * More Extensibility dimensions. 2423 Appendix C. Open Questions 2425 Author's Address 2426 Dick Hardt (editor) 2427 SignIn.Org 2428 United States 2430 Email: dick.hardt@gmail.com