idnits 2.17.00 (12 Aug 2021) /tmp/idnits31312/draft-hardt-xauth-protocol-04.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 (19 February 2020) is 822 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 2240, 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 19 February 2020 5 Expires: 22 August 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-04 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 22 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . 24 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 . . . . . . . . . . . . . . . . . . 27 99 6. GS Initiated Grant . . . . . . . . . . . . . . . . . . . . . 28 100 7. GS API Responses . . . . . . . . . . . . . . . . . . . . . . 28 101 7.1. Grant Response . . . . . . . . . . . . . . . . . . . . . 28 102 7.2. Interaction Response . . . . . . . . . . . . . . . . . . 29 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 A.5. draft-hardt-xauth-protocol-03 . . . . . . . . . . . . . . 51 144 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 51 145 Appendix C. Open Questions . . . . . . . . . . . . . . . . . . . 53 146 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 53 148 1. Introduction 150 This protocol supports the widely deployed use cases supported by 151 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 152 extension of OAuth 2.0, as well as other extensions, and other use 153 cases that are not supported, such as acquiring multiple access 154 tokens at the same time, and updating the request during user 155 interaction. This protocol also addresses many of the security 156 issues in OAuth 2.0 by having parameters securely sent directly 157 between parties, rather than via a browser redirection. 159 The technology landscape has changed since OAuth 2.0 was initially 160 drafted. More interactions happen on mobile devices than PCs. 161 Modern browsers now directly support asymetric cryptographic 162 functions. Standards have emerged for signing and encrypting tokens 163 with rich payloads (JOSE) that are widely deployed. 165 Additional use cases are now being served with extensions to OAuth 166 2.0: OpenID Connect added support for authentication and releasing 167 identity claims; [RFC8252] added support for native apps; [RFC8628] 168 added support for smart devices; and support for [browser_based_apps] 169 is being worked on. There are numerous efforts on adding proof-of- 170 possession to resource access. 172 This protocol simplifies the overall architectural model, takes 173 advantage of today's technology landscape, provides support for all 174 the widely deployed use cases, and offers numerous extension points. 176 While this protocol is not backwards compatible with OAuth 2.0, it 177 strives to minimize the migration effort. 179 This protocol centers around a Grant, a representation of the 180 collection of user identity claims and/or resource authorizations the 181 Client is requesting, and the resulting identity claims and/or 182 resource authorizations granted by the Grant Server. 184 [Editor: suggestions on how to improve this are welcome!] 186 [Editor: suggestions for other names than XAuth are welcome!] 188 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 "redirect_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_id_token* - is an OpenID Connect ID Token per [OIDC] 1064 Section 2. 1066 5.5.4. "authorization" Object 1068 * *type* - one of the following values: "oauth_scope" or 1069 "oauth_rich". This attribute is REQUIRED. 1071 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1072 section 3.3. MUST be included if type is "oauth_scope" or 1073 "oauth_rich". 1075 * *authorization_details* - an authorization_details object per 1076 [RAR]. MUST be included if type is "oauth_rich". 1078 [Editor: details may change as the [RAR] document evolves] 1080 5.5.5. "authorizations" Object 1082 A JSON array of "authorization" objects. Only one of "authorization" 1083 or "authorizations" may be in the Request JSON. 1085 [Editor: instead of an array, we could have a Client defined 1086 dictionary of "authorization" objects] 1088 5.5.6. "claims" Object 1090 Includes one or more of the following: 1092 * *oidc* - an object that contains one or both of the following 1093 objects: 1095 - *userinfo* - Claims that will be returned as a JSON object 1097 - *id_token* - Claims that will be included in the returned ID 1098 Token. If the null value, an ID Token will be returned 1099 containing no additional Claims. 1101 The contents of the userinfo and id_token objects are Claims as 1102 defined in [OIDC] Section 5. 1104 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1105 per [OIDC4IA]. 1107 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1108 be requested.] 1110 5.5.7. "reciprocal" Object 1112 * *uri* - the Grant URI for the Reciprocal Grant. This attribute is 1113 REQUIRED. 1115 * *client* - the client object must contain the "id" attribute with 1116 the Client ID the Grant was issued to. This attribute is 1117 REQUIRED. 1119 * *authorization* - an authorization object per Section 7.4.3 in the 1120 Response JSON. 1122 * *authorizations* - an authorizations object per Section 7.4.4 in 1123 the Response JSON. 1125 * *claims* - a claims object per Section 7.4.5 in the Response JSON. 1127 [Editor: parameters for the Client to request it wants the Grant 1128 Response signed and/or encrypted?] 1130 5.6. Refresh Authorization 1132 The Client updates an Authorization by doing an HTTP GET to the 1133 corresponding AuthZ URI. 1135 The GS MUST respond with an Response JSON "authorization" object 1136 Section 7.4.3, or one of the following errors: 1138 * TBD 1140 from Error Responses Section 9. 1142 5.7. Update Authorization 1144 The Client updates an Authorization by doing an HTTP PUT to the 1145 corresponding AuthZ URI of the following JSON. All of the following 1146 MUST be included. 1148 * *iat* - the time of the response as a NumericDate. 1150 * *uri* - the AuthZ URI. 1152 * *authorization* - the new authorization requested per the Request 1153 JSON "authorization" object Section 5.5.4. 1155 The GS MUST respond with an Response JSON "authorization" object 1156 Section 7.4.3, or one of the following errors: 1158 * TBD 1160 from Error Responses Section 9. 1162 5.8. Delete Authorization 1164 The Client deletes an Authorization by doing an HTTP DELETE to the 1165 corresponding AuthZ URI. 1167 The GS MUST respond with OK 200, or one of the following errors: 1169 * TBD 1171 from Error Responses Section 9. 1173 5.9. GS Options 1175 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1176 of the corresponding GS URI. This is the only API where the GS MAY 1177 respond to an unauthenticated request. 1179 The GS MUST respond with the the following JSON document: 1181 [Editor: this section is a work in progress] 1183 * *uri* - the GS URI. 1185 * *client_authentication* - an array of the Client Authentication 1186 mechanisms supported by the GS 1188 * *interactions* - an array of the interaction types supported by 1189 the GS. 1191 * *authorization* - an object containing the authorizations the 1192 Client may request from the GS, if any. 1194 - Details TBD 1196 * *claims* - an object containing the identity claims the Client may 1197 request from the GS, if any, and what public keys the claims will 1198 be signed with. 1200 - Details TBD 1202 * *algorithms* - a list of the cryptographic algorithms supported by 1203 the GS. 1205 * *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 1302 Example non-normative Grant Response JSON document for Example 1 in 1303 Section 3.1: 1305 { 1306 "iat" : 15790460234, 1307 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1308 "uri" : "https://as.example/endpoint/grant/example1", 1309 "expires_in" : 300 1310 "authorization": { 1311 "type" : "oauth_scope", 1312 "scope" : "read_contacts", 1313 "expires_in" : 3600, 1314 "mechanism" : "bearer", 1315 "token" : "eyJJ2D6.example.access.token.mZf9p" 1316 }, 1317 "claims": { 1318 "oidc": { 1319 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1320 "userinfo" : { 1321 "name" : "John Doe", 1322 "picture" : "https://photos.example/p/eyJzdkiO" 1323 } 1324 } 1325 } 1326 } 1328 Example non-normative Grant Response JSON document for Example 2 in 1329 Section 3.1: 1331 { 1332 "iat" : 15790460234, 1333 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1334 "uri" : "https://as.example/endpoint/grant/example2", 1335 "authorization": { 1336 "type" : "oauth_scope", 1337 "scope" : "read_calendar write_calendar", 1338 "expires_in" : 3600, 1339 "mechanism" : "jose", 1340 "token" : "eyJJ2D6.example.access.token.mZf9p" 1341 "certificate": { 1342 "x5u" : "https://as.example/cert/example2" 1343 }, 1344 "uri" : "https://as.example/endpoint/authz/example2" 1345 } 1346 } 1348 7.2. Interaction Response 1350 The Interaction Response MUST include the following from the Response 1351 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 "authorization_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 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 * *authorization_uri* - the URI to redirect the user to or load in 1432 the popup. Must be included if type is "popup" and "redirect" 1434 * *display_uri* - the URI to be displayed to the User for them to 1435 navigate to and enter the code. Must be included if type is 1436 "qrcode" and "code" 1438 * *qr_uri* - the URI to show as a QR code. MUST be included if type 1439 is "qrcode" 1441 * *user_code* - a text string of the code to display to the User. 1442 Must be included if type is "qrcode" or "code". 1444 [Editor: do we specify a maximum length for the display_uri and code 1445 so that a device knows the maximum it needs to support? A smart 1446 device may have limited screen real estate.] 1448 The authorization_uri, qr_uri, and user_code MUST be unique and only 1449 match the associated Grant URI. 1451 TBD: entropy and other security considerations for the 1452 authorization_uri, qr_uri, and the user_code. 1454 See Interaction Types Section 7.4.7 for details. 1456 7.4.2. "user" Object 1458 * *exists* - a boolean value indicating if the GS has a user with 1459 one or more of the provided identifiers in the Request 1460 "user"."identifiers" object Section 5.5.3 1462 7.4.3. "authorization" Object 1464 The "authorization" object is a response to the Request 1465 "authorization" object Section 5.5.4, the Refresh Authorization 1466 Section 5.6, or the Update Authorization Section 5.7. 1468 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1469 See the "type" object in Section 5.5.4 for details. 1471 * *scope* - the scopes the Client was granted authorization for. 1472 This will be all, or a subset, of what was requested. This 1473 attribute is OPTIONAL. 1475 * *authorization_details* - the authorization details granted per 1476 [RAR]. Included if type is "oauth_rich". 1478 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1479 "jose+body". See Section 8 for details. 1481 * *token* - the access token for accessing an RS. This attribute is 1482 REQUIRED. 1484 * *expires_in* - a numeric value specifying how many seconds until 1485 the access token expires. This attribute is OPTIONAL. 1487 * *certificate* - MUST be included if the mechanism is "jose" or 1488 "jose+body". Contains the jwk header values for the Client to 1489 include in the JWS header when calling the RS using the "jose" or 1490 "jose+body" mechanisms. See Section 10.2.1. 1492 * *uri* - the AuthZ URI. Used to refresh, update, and delete the 1493 authorization. This attribute is OPTIONAL. 1495 [Editor: any value in an expiry for the Authorization?] 1497 7.4.4. "authorizations" Object 1499 A JSON array of authorization objects. Support for the 1500 authorizations object is OPTIONAL. 1502 7.4.5. "claims" Object 1504 The claims object is a response to the Request "claims" object 1505 Section 5.5.4. 1507 * *oidc* 1509 - *id_token* - an OpenID Connect ID Token containing the Claims 1510 the User consented to be released. 1512 - *userinfo* - the Claims the User consented to be released. 1514 Claims are defined in [OIDC] Section 5. 1516 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1517 per [OIDC4IA]. 1519 * *vc* 1521 The verified claims the user consented to be released. [Editor: 1522 details TBD] 1524 7.4.6. "reciprocal" Object 1526 The following MUST be included 1528 * *nonce* - a unique identifier for this request. Note the Grant 1529 Response MUST contain a matching nonce attribute value. 1531 * *client* 1533 - *id* - the Client ID making the request 1535 One or more of the following objects from the Request JSON 1536 Section 5.5 are included: 1538 * *authorization* Section 7.4.3 1539 * *authorizations* Section 7.4.4 1541 * *claims* Section 7.4.5 1543 7.4.7. Interaction Types 1545 If the GS wants the Client to initiate the interaction with the User, 1546 then the GS will return an Interaction Response. The Client will 1547 initiate the interaction with the User in one of the following ways: 1549 * *popup* The Client will create a new popup child browser window 1550 with URI contained in the "interaction"."authorization_uri" 1551 attribute. [Editor: more details on how to do this] The GS will 1552 close the popup window when the interactions with the User are 1553 complete. [Editor: confirm GS can stll do this on all browsers, 1554 or does Client need to close? If so, then Client needs to provide 1555 a redirect_uri.] 1557 * *redirect* The Client will redirect the User to the 1558 "interaction"."authorization_uri" attribute. When the GS 1559 interactions with the User are complete, the GS will redirect the 1560 User to the "interaction"."redirect_uri" attribute the Client 1561 provided in the Grant Request. 1563 * *qrcode* The Client will create a [QR_Code] of the 1564 "interaction"."qr" attribute and display the resulting graphic. 1565 The Client will also display the "interaction"."display_uri" and 1566 "interaction"."user_code" per the "code" type. 1568 * *code* The Client will display the "interaction"."user_code" 1569 contents and direct the User to navigate to the 1570 "interaction"."display_uri" value and enter the code. 1572 A GS MUST support the "popup", "redirect", "qrcode", and "code" 1573 interaction types. 1575 [Editor: is this too restrictive?] 1577 7.4.8. Signing and Encryption 1579 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1580 there a generalized description, or is it mechanism specific?] 1582 7.5. Response Verification 1584 On receipt of a response, the Client MUST verify the following: 1586 * TBD 1588 8. RS Access 1590 This document specifies three different mechanisms for the Client to 1591 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1592 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1593 mechanisms are proof-of-possession mechanisms and are defined in 1594 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1595 possession mechanisms may be defined in other documents. The 1596 mechanism the Client is to use with an RS is the Response JSON 1597 "authorization"."mechanism" attribute Section 7.4.3. 1599 8.1. Bearer Token 1601 If the access mechanism is "bearer", then the Client accesses the RS 1602 per Section 2.1 of [RFC6750] 1604 A non-normative example of the HTTP request headers follows: 1606 GET /calendar HTTP/2 1607 Host: calendar.example 1608 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1610 9. Error Responses 1612 * TBD 1614 10. JOSE Authentication 1616 How the Client authenticates to the GS and RS are independent of each 1617 other. One mechanism can be used to authenticate to the GS, and a 1618 different mechanism to authenticate to the RS. 1620 Other documents that specify other Client authentication mechanisms 1621 will replace this section. 1623 In the JOSE Authentication Mechanism, the Client authenticates by 1624 using its private key to sign a JSON document with JWS per [RFC7515] 1625 which results in a token using JOSE compact serialization. 1627 [Editor: are there advantages to using JSON serialization in the 1628 body?] 1630 Different instances of a Registered Clients MAY have different 1631 private keys, but certificates bind them to a public key the GS has 1632 for the Client ID. An instance of a Client will use the same private 1633 key for all signing. 1635 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1636 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1638 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1640 The token may be included in an HTTP header, or as the HTTP message 1641 body. 1643 The following sections specify how the Client uses JOSE to 1644 authenticate to the GS and RS. 1646 10.1. GS Access 1648 The Client authenticates to the GS by passing either a signed header 1649 parameter, or a signed message body. The following table shows the 1650 verb, uri and token location for each Client request to the GS: 1652 +---------------+-----------+-----------+----------+ 1653 | request | http verb | uri | token in | 1654 +===============+===========+===========+==========+ 1655 | Create Grant | POST | GS URI | body | 1656 +---------------+-----------+-----------+----------+ 1657 | Read Grant | GET | Grant URI | header | 1658 +---------------+-----------+-----------+----------+ 1659 | Update Grant | PUT | Grant URI | body | 1660 +---------------+-----------+-----------+----------+ 1661 | Delete Grant | DELETE | Grant URI | success | 1662 +---------------+-----------+-----------+----------+ 1663 | Refresh AuthZ | GET | AuthZ URI | body | 1664 +---------------+-----------+-----------+----------+ 1665 | Update AuthZ | PUT | AuthZ URI | body | 1666 +---------------+-----------+-----------+----------+ 1667 | Delete AuthZ | DELETE | AuthZ URI | header | 1668 +---------------+-----------+-----------+----------+ 1669 | GS Options | OPTIONS | GS URI | header | 1670 +---------------+-----------+-----------+----------+ 1671 | Grant Options | OPTIONS | Grant URI | header | 1672 +---------------+-----------+-----------+----------+ 1673 | AuthZ Options | OPTIONS | AuthZ URI | header | 1674 +---------------+-----------+-----------+----------+ 1676 Table 2 1678 10.1.1. Authorization Header 1680 For requests with the token in the header, the JWS payload MUST 1681 contain the following attributes: 1683 *iat* - the time the token was created as a NumericDate. 1685 *jti* - a unique identifier for the token per [RFC7519] section 1686 4.1.7. 1688 *uri* - the value of the URI being called (GS URI, Grant URI, or 1689 AuthZ URI). 1691 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1692 "OPTIONS") 1694 The HTTP authorization header is set to the "jose" parameter followed 1695 by one or more white space characters, followed by the resulting 1696 token. 1698 A non-normative example of a JWS payload and the HTTP request 1699 follows: 1701 { 1702 "iat" : 15790460234, 1703 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1704 "uri" : "https://as.example/endpoint/grant/example6", 1705 "verb" : "GET" 1706 } 1708 GET /endpoint/example.grant HTTP/2 1709 Host: as.example 1710 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1712 [Editor: make a real example token] 1714 *GS Verification* 1716 The GS MUST verify the token by: 1718 * TBD 1720 10.1.2. Signed Body 1722 For requests with the token in the body, the Client uses the Request 1723 JSON as the payload in a JWS. The resulting token is sent with the 1724 content-type set to "application/jose". 1726 A non-normative example (line breaks added to the body for 1727 readability): 1729 POST /endpoint HTTP/2 1730 Host: as.example 1731 Content-Type: application/jose 1732 Content-Length: 155 1734 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1735 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1736 Jf36POk6yJV_adQssw5c 1738 [Editor: make a real example token] 1740 *GS Verification* 1742 The GS MUST verify the token by: 1744 * TBD 1746 10.1.3. Public Key Resolution 1748 * *Registered Clients* can use any of the JWS header values to 1749 direct the GS to resolve the public key matching the private key 1750 used to the Client ID. The GS MAY restrict with JWS headers a 1751 Client can use. 1753 [Editor: would examples help here so that implementors understand the 1754 full range of options, and how an instance can have its own asymetric 1755 key pair] 1757 A non-normative example of a JOSE header for a Registered Client with 1758 a key identifier of "12": 1760 { 1761 "alg" : "ES256", 1762 "typ" : "JOSE", 1763 "kid" : "12" 1764 } 1766 * *Dynamic Clients* include their public key in the "jwk" JWS 1767 header. 1769 A non-normative example of a JOSE header for a Dynamic Client: 1771 { 1772 "alg" : "ES256", 1773 "typ" : "JOSE", 1774 "jwk" : { 1775 "kty" : "EC", 1776 "crv" : "P-256", 1777 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1778 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1779 } 1780 } 1782 10.2. RS Access 1784 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 1785 include a proof-of-possession token in the HTTP authorization header. 1786 In the "jose+body" mechanism Section 10.2.3, the Client signs the 1787 JSON document in the request if the POST or PUT verbs are used, 1788 otherwise it is the same as the "jose" mechanism. 1790 10.2.1. JOSE header 1792 The GS provides the Client one or more JWS header parameters and 1793 values for a a certificate, or a reference to a certificate or 1794 certificate chain, that the RS can use to resolve the public key 1795 matching the private key being used by the Client. 1797 A non-normative examples JOSE header: 1799 { 1800 "alg" : "ES256", 1801 "typ" : "JOSE", 1802 "x5u" : "https://as.example/cert/example2" 1803 } 1805 [Editor: this enables Dynamic Clients to make proof-of-possession API 1806 calls the same as Registered Clients.] 1808 10.2.2. "jose" Mechanism 1810 The JWS payload MUST contain the following attributes: 1812 *iat* - the time the token was created as a NumericDate. 1814 *jti* - a unique identifier for the token per [RFC7519] section 1815 4.1.7. 1817 *uri* - the value of the RS URI being called. 1819 *verb* - the HTTP verb being used in the call 1821 *token* - the access token provided by the GS to the Client 1823 The HTTP authorization header is set to the "jose" parameter followed 1824 by one or more white space characters, followed by the resulting 1825 token. 1827 A non-normative example of a JWS payload and the HTTP request 1828 follows: 1830 { 1831 "iat" : 15790460234, 1832 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1833 "uri" : "https://calendar.example/calendar", 1834 "verb" : "GET", 1835 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 1836 } 1838 GET /calendar HTTP/2 1839 Host: calendar.example 1840 Authorization: jose eyJhbG.example.jose.token.adks 1842 [Editor: make a real example token] 1844 *RS Verification* 1846 The RS MUST verify the token by: 1848 * verify access token is bound to the public key - include key 1849 fingerprint in access token? 1851 * TBD 1853 10.2.3. "jose+body" Mechanism 1855 The "jose+body" mechanism can only be used if the content being sent 1856 to the RS is a JSON document. 1858 Any requests not sending a message body will use the "jose" mechanism 1859 Section 10.2.2. 1861 Requests sending a message body MUST have the following JWS payload: 1863 *iat* - the time the token was created as a NumericDate. 1865 *jti* - a unique identifier for the token per [RFC7519] section 1866 4.1.7. 1868 *uri* - the value of the RS URI being called. 1870 *verb* - the HTTP verb being used in the call 1872 *token* - the access token provided by the GS to the Client 1874 *body* - the message body being sent to the RS 1876 A non-normative example of a JWS payload and the HTTP request 1877 follows: 1879 { 1880 "iat" : 15790460234, 1881 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1882 "uri" : "https://calendar.example/calendar", 1883 "verb" : "POST", 1884 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 1885 "payload" : { 1886 "event" : { 1887 "title" : "meeting with joe", 1888 "start_date_utc" : "2020-02-21 11:00:00", 1889 "end_date_utc" : "2020-02-21 11:00:00" 1890 } 1891 } 1892 } 1894 POST /calendar HTTP/2 1895 Host: calendar.example 1896 Content-Type: application/jose 1897 Content-Length: 155 1899 eyJhbGciOi.example.jose+body.adasdQssw5c 1901 [Editor: make a real example token] 1903 *RS Verification* 1905 The RS MUST verify the token by: 1907 * TBD 1909 10.2.4. Public Key Resolution 1911 The RS has a public key for the GS that it uses to verify the 1912 certificate or certificate chain the Client includes in the JWS 1913 header. 1915 10.3. Request Encryption 1917 [Editor: to be fleshed out] 1919 The Client encrypts a request when ??? using the GS public key 1920 returned as the ??? attribute in GS Options Section 5.9. 1922 10.4. Response Signing 1924 [Editor: to be fleshed out] 1926 The Client verifies a signed response ??? using the GS public key 1927 returned as the ??? attribute in GS Options Section 5.9. 1929 10.5. Response Encryption 1931 [Editor: to be fleshed out] 1933 The Client decrypts a response when ??? using the private key 1934 matching the public key included in the request as the ??? attribute 1935 in Section 5.5. 1937 11. Extensibility 1939 This standard can be extended in a number of areas: 1941 * *Client Authentication Mechanisms* 1943 - An extension could define other mechanisms for the Client to 1944 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1945 Signing. Constrained environments could use CBOR [RFC7049] 1946 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1947 [RFC8323] instead of HTTP/2. 1949 * *Grant* 1951 - An extension can define new objects in the Grant Request and 1952 Grant Response JSON. 1954 * *Top Level* 1956 - Top level objects SHOULD only be defined to represent 1957 functionality other the existing top level objects and 1958 attributes. 1960 * *"client" Object* 1961 - Additional information about the Client that the GS would 1962 require related to an extension. 1964 * *"user" Object* 1966 - Additional information about the User that the GS would require 1967 related to an extension. 1969 * *"authorization" Object* 1971 - Additional types of authorizations in addition to OAuth 2.0 1972 scopes and RAR. 1974 * *"claims" Object* 1976 - Additional types of identity claims in addition to OpenID 1977 Connect claims and Verified Credentials. 1979 * *Interaction types* 1981 - Additional types of interactions a Client can start with the 1982 User. 1984 * *Continuous Authentication* 1986 - An extension could define a mechanism for the Client to 1987 regularly provide continuous authentication signals and receive 1988 responses. 1990 [Editor: do we specify access token / handle introspection in this 1991 document, or leave that to an extension?] 1993 [Editor: do we specify access token / handle revocation in this 1994 document, or leave that to an extension?] 1996 12. Rational 1998 1. *Why is there only one mechanism for the Client to authenticate 1999 with the GS? Why not support other mechanisms?* 2001 Having choices requires implementers to understand which choice 2002 is preferable for them. Having one default mechanism in the 2003 document for the Client to authenticate simplifies most 2004 implementations. Deployments that have unique characteristics 2005 can select other mechanisms that are preferable in specific 2006 environments. 2008 2. *Why is the default Client authentication JOSE rather than 2009 MTLS?* 2011 MTLS cannot be used today by a Dynamic Client. MTLS requires 2012 the application to have access below what is typically the 2013 application layer, that is often not available on some 2014 platforms. JOSE is done at the application layer. Many GS 2015 deployments will be an application behind a proxy performing 2016 TLS, and there are risks in the proxy passing on the results of 2017 MTLS. 2019 3. *Why is the default Client authentication JOSE rather than HTTP 2020 signing?* 2022 There is currently no widely deployed open standard for HTTP 2023 signing. Additionally, HTTP signing requires passing all the 2024 relevant parts of the HTTP request to downstream services within 2025 an GS that may need to independently verify the Client identity. 2027 4. *What are the advantages of using JOSE for the Client to 2028 authenticate to the GS and a resource?* 2030 Both Registered Clients and Dynamic Clients can have a private 2031 key, eliminating the public Client issues in OAuth 2.0, as a 2032 Dynamic Client can create an ephemeral key pair. Using 2033 asymetric cryptography also allows each instance of a Registered 2034 Client to have its own private key if it can obtain a 2035 certificate binding its public key to the public key the GS has 2036 for the Client. Signed tokens can be passed to downstream 2037 components in a GS or RS to enable independent verification of 2038 the Client and its request. The GS Initiated Sequence Section 6 2039 requires a URL safe parameter, and JOSE is URL safe. 2041 5. *Why does the GS not return parameters to the Client in the 2042 redirect url?* 2044 Passing parameters via a browser redirection is the source of 2045 many of the security risks in OAuth 2.0. It also presents a 2046 challenge for smart devices. In this protocol, the redirection 2047 from the Client to the GS is to enable the GS to interact with 2048 the User, and the redirection back to the Client is to hand back 2049 interaction control to the Client if the redirection was a full 2050 browser redirect. Unlike OAuth 2.0, the identity of the Client 2051 is independent of the URI the GS redirects to. 2053 6. *Why is there not a UserInfo endpoint as there is with OpenID 2054 Connect?* 2055 Since the Client can Read Grant at any time, it get the same 2056 functionality as the UserInfo endpoint, without the Client 2057 having to manage a separate access token and refresh token. If 2058 the Client would like additional claims, it can Update Grant, 2059 and the GS will let the Client know if an interaction is 2060 required to get any of the additional claims, which the Client 2061 can then start. 2063 [Editor: is there some other reason to have the UserInfo 2064 endpoint?] 2066 7. *Why is there still a Client ID?* 2068 The GS needs an identifier to fetch the meta data associated 2069 with a Client such as the name and image to display to the User, 2070 and the policies on what a Client is allowed to do. The Client 2071 ID was used in OAuth 2.0 for the same purpose, which simplifies 2072 migration. Dynamic Clients do not have a Client ID. 2074 8. *Why have both claims and authorizations?* 2076 There are use cases for each that are independent: 2077 authenticating a user and providing claims vs granting access to 2078 a resource. A request for an authorization returns an access 2079 token which may have full CRUD capabilities, while a request for 2080 a claim returns the claim about the User - with no create, 2081 update or delete capabilities. While the UserInfo endpoint in 2082 OIDC may be thought of as a resource, separating the concepts 2083 and how they are requested keeps each of them simpler in the 2084 Editor's opinion. :) 2086 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2087 GS communication in ?*Section 10 2089 Knowing the GS supports HTTP/2 enables a Client to set up a 2090 connection faster. HTTP/2 will be more efficient when Clients 2091 have large numbers of access tokens and are frequently 2092 refreshing them at the GS as there will be less network traffic. 2093 Mandating TLS 1.3 similarly improves the performance and 2094 security of Clients and GS when setting up a TLS connection. 2096 10. *Why do some of the JSON objects only have one child, such as 2097 the identifiers object in the user object in the Grant Request?* 2099 It is difficult to forecast future use cases. Having more 2100 resolution may mean the difference between a simple extension, 2101 and a convoluted extension. 2103 11. *Why is the "iss" included in the "oidc" identifier object? 2104 Would the "sub" not be enough for the GS to identify the User?* 2106 This decouples the GS from the OpenID Provider (OP). The GS 2107 identifier is the GS URI, which is the endpoint at the GS. The 2108 OP issuer identifier will likely not be the same as the GS URI. 2109 The GS may also provide claims from multiple OPs. 2111 12. *Why complicate things with "interaction"."keep"?* 2113 The common sequence has a back and forth between the Client and 2114 the GS, and the Client can update the Grant and have a new 2115 interaction. Keeping the interaction provides a more seamless 2116 user experience where the results from the first request 2117 determine subsequent requests. For example, a common pattern is 2118 to use a GS to authenticate the User at the Client, and to 2119 register the User at the Client using additional claims from the 2120 GS. The Client does not know a priori if the User is a new 2121 User, or a returning User. Asking a returning User to consent 2122 releasing claims they have already provided is a poor User 2123 experience, as is sending the User back to the GS. The Client 2124 requesting identity first enables the Client to get a response 2125 from the GS while the GS is still interacting with the User, so 2126 that the Client can request additional claims only if needed. 2127 Additionally, the claims a Client may want about a User may be 2128 dependent on some initial Claims. For example, if a User is in 2129 a particular country, additional or different Claims my be 2130 required by the Client. 2132 There are also benefits for the GS. Today, a GS usually keeps 2133 track of which claims a Client has requested for a User. 2134 Storing this information for all Clients a User uses may be 2135 undesirable for a GS that does not want to have that information 2136 about the User. Keeping the interaction allows the Client to 2137 track what information it has about the User, and the GS can 2138 remain stateless. 2140 13. *Why is there a "jose+body" RS access mechanism method for the 2141 Client?*Section 10.2.3 2143 There are numerous use cases where the RS wants non-repudiation 2144 and providence of the contents of an API call. For example, the 2145 UGS Service Supplier Framework for Authentication and 2146 Authorization [UTM]. 2148 14. *Why use URIs to instead of handles for the Grant and 2149 Authorization?* 2150 A URI is an identifier just like a handle that can contain GS 2151 information that is opaque to the Client - so it has all the 2152 features of a handle, plus it can be the URL that is resolved to 2153 manipulate a Grant or an Authorization. As the Grant URI and 2154 AuthZ URI are defined to start with the GS URI, the Client (and 2155 GS) can easily determine which GS a Grant or Authorization 2156 belong to. URIs also enable a RESTful interface to the GS 2157 functionality. 2159 15. *Why use the OPTIONS verb on the GS URI? Why not use a .well- 2160 known mechanism?* 2162 Having the GS URI endpoint respond to the metadata allows the GS 2163 to provide Client specific results using the same Client 2164 authentication used for other requests to the GS. It also 2165 reduces the risk of a mismatch between what the advertised 2166 metadata, and the actual metadata. A .well-known discovery 2167 mechanism may be defined to resolve from a hostname to the GS 2168 URI. 2170 16. *Why support UPDATE, DELETE, and OPTIONS verbs on the AuthZ 2171 URI?* 2173 Maybe there are no use cases for them [that the editor knows 2174 of], but the GS can not implement, and they are available if use 2175 cases come up. 2177 17. *Why list explicit interactions, instead of the Client and GS 2178 negotiating interaction capabilities?* 2180 The Client knows what interactions it is capable of, and 2181 prefers. Telling the GS the interaction allows the GS to know 2182 what interaction the User will have. Knowing how the Client 2183 will transition the interaction will enable the GS to provider a 2184 better User experience. For example, the GS may want to provide 2185 a short URL if it knows the Client will be showing a QR code vs 2186 a redirect, or have a different layout if it is a popup vs a 2187 redirect. 2189 [Editor: are there use cases where the Client would want to 2190 provide a list of interaction types so the GS can select which 2191 one it can support? ] 2193 13. Acknowledgments 2195 This draft derives many of its concepts from Justin Richer's 2196 Transactional Authorization draft [TxAuth]. 2198 Additional thanks to Justin Richer and Annabelle Richard Backman for 2199 their strong critique of earlier drafts. 2201 14. IANA Considerations 2203 [ JOSE parameter for Authorization HTTP header ] 2205 TBD 2207 15. Security Considerations 2209 TBD 2211 16. References 2213 16.1. Normative References 2215 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2216 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2217 . 2219 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2220 DOI 10.17487/RFC5322, October 2008, 2221 . 2223 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2224 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2225 September 2009, . 2227 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2228 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2229 . 2231 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2232 Framework: Bearer Token Usage", RFC 6750, 2233 DOI 10.17487/RFC6750, October 2012, 2234 . 2236 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2237 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2238 2015, . 2240 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2241 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2242 . 2244 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2245 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2246 . 2248 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2249 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2250 DOI 10.17487/RFC7540, May 2015, 2251 . 2253 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2254 Interchange Format", STD 90, RFC 8259, 2255 DOI 10.17487/RFC8259, December 2017, 2256 . 2258 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2259 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2260 . 2262 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2263 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2264 . 2266 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2267 Assurance 1.0", October 2019, . 2270 16.2. Informative References 2272 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2273 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2274 October 2013, . 2276 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2277 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2278 . 2280 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2281 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2282 . 2284 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2285 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2286 Application Protocol) over TCP, TLS, and WebSockets", 2287 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2288 . 2290 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2291 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2292 DOI 10.17487/RFC8628, August 2019, 2293 . 2295 [browser_based_apps] 2296 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2297 Apps", September 2019, . 2300 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2301 Rich Authorization Requests", January 2020, 2302 . 2304 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2305 Credentials Data Model 1.0", November 2019, 2306 . 2308 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2309 identification and data capture techniques - QR Code bar 2310 code symbology specification", February 2015, 2311 . 2313 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2314 . 2317 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2318 Supplier Framework for Authentication and AuthN", 2319 September 2019, . 2322 Appendix A. Document History 2324 A.1. draft-hardt-xauth-protocol-00 2326 * Initial version 2328 A.2. draft-hardt-xauth-protocol-01 2330 * text clean up 2332 * added OIDC4IA claims 2334 * added "jws" method for accessing a resource. 2336 * renamed Initiation Request -> Grant Request 2338 * renamed Initiation Response -> Interaction Response 2339 * renamed Completion Request -> Authorization Request 2341 * renamed Completion Response -> Grant Request 2343 * renamed completion handle -> authorization handle 2345 * added Authentication Request, Authentication Response, 2346 authentication handle 2348 A.3. draft-hardt-xauth-protocol-02 2350 * major rewrite 2352 * handles are now URIs 2354 * the collection of claims and authorizations are a Grant 2356 * an Authorization is its own type 2358 * lots of sequences added 2360 A.4. draft-hardt-xauth-protocol-03 2362 * fixed RO definition 2364 * improved language in Rationals 2366 * added user code interaction method, and aligned qrcode interaction 2367 method 2369 * added completion_uri for code flows 2371 A.5. draft-hardt-xauth-protocol-03 2373 * renamed interaction uris to have purpose specific names 2375 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2377 *Changed Features* 2379 The major changes between this protocol and OAuth 2.0 and OpenID 2380 Connect are: 2382 * The Client uses a private key to authenticate in this protocol 2383 instead of the client secret in OAuth 2.0 and OpenID Connect. 2385 * The Client initiates the protocol by making a signed request 2386 directly to the GS instead of redirecting the User to the GS. 2388 * The Client does not pass any parameters in redirecting the User to 2389 the GS, nor receive any parameters in the redirection back from 2390 the GS. 2392 * The refresh_token has been replaced with a AuthZ URI that both 2393 represents the access, and is the URI to call to refresh access. 2395 * The Client can request identity claims to be returned independent 2396 of the ID Token. There is no UserInfo endpoint to query claims as 2397 there is in OpenID Connect. 2399 * The GS URI is the token endpoint. CHECK!!!s 2401 *Preserved Features* 2403 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2404 tokens of OAuth 2.0. 2406 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2407 Connect. 2409 * No change is required by the Client or the RS for existing bearer 2410 token protected APIs. 2412 *New Features* 2414 * A Grant represents the user identity claims and RS access granted 2415 to the Client. 2417 * The Client can update, retrieve, and delete a Grant. 2419 * The GS can initiate a flow by creating a Grant and redirecting the 2420 User to the Client with the Grant URI. 2422 * The Client can discovery if an GS has a User with an identifier 2423 before the GS interacts with the User. 2425 * The Client can request the GS to first authenticate the User and 2426 return User identity claims, and then the Client can update Grant 2427 request based on the User identity. 2429 * Support for QR Code initiated interactions. 2431 * Each Client instance can have its own private / public key pair. 2433 * More Extensibility dimensions. 2435 Appendix C. Open Questions 2437 Author's Address 2439 Dick Hardt (editor) 2440 SignIn.Org 2441 United States 2443 Email: dick.hardt@gmail.com