idnits 2.17.1 draft-hardt-xauth-protocol-02.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 225: '...egistered Client MAY be interacting wi...' RFC 2119 keyword, line 232: '... Dynamic Client MUST be interacting w...' RFC 2119 keyword, line 278: '... MUST start with the GS URI....' RFC 2119 keyword, line 284: '.... The AuthZ URI MUST start with the G...' RFC 2119 keyword, line 767: '... The Client MAY create, read, update...' (65 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 February 2020) is 1538 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 792, but not defined == Unused Reference: 'RFC7516' is defined on line 2185, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC' -- Possible downref: Non-RFC (?) normative reference: ref. 'OIDC4IA' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 8 February 2020 5 Expires: 11 August 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-02 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 11 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 . . . . . . . . . . . . . . . 23 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 . . . . . . . . . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . . . 31 107 7.4.3. "authorization" Object . . . . . . . . . . . . . . . 32 108 7.4.4. "authorizations" Object . . . . . . . . . . . . . . . 32 109 7.4.5. "claims" Object . . . . . . . . . . . . . . . . . . . 32 110 7.4.6. "reciprocal" Object . . . . . . . . . . . . . . . . . 33 111 7.4.7. Interaction Types . . . . . . . . . . . . . . . . . . 33 112 7.4.8. Signing and Encryption . . . . . . . . . . . . . . . 34 113 7.5. Response Verification . . . . . . . . . . . . . . . . . . 34 114 8. RS Access . . . . . . . . . . . . . . . . . . . . . . . . . . 34 115 8.1. Bearer Token . . . . . . . . . . . . . . . . . . . . . . 34 116 9. Error Responses . . . . . . . . . . . . . . . . . . . . . . . 35 117 10. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 35 118 10.1. GS Access . . . . . . . . . . . . . . . . . . . . . . . 35 119 10.1.1. Authorization Header . . . . . . . . . . . . . . . . 36 120 10.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . 37 121 10.1.3. Public Key Resolution . . . . . . . . . . . . . . . 37 122 10.2. RS Access . . . . . . . . . . . . . . . . . . . . . . . 38 123 10.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . 38 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 . . . . . . . . . . . . . . . . . . . 41 128 10.4. Response Signing . . . . . . . . . . . . . . . . . . . . 41 129 10.5. Response Encryption . . . . . . . . . . . . . . . . . . 42 130 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42 131 12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 43 132 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 133 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 134 15. Security Considerations . . . . . . . . . . . . . . . . . . . 47 135 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 136 16.1. Normative References . . . . . . . . . . . . . . . . . . 47 137 16.2. Informative References . . . . . . . . . . . . . . . . . 48 138 Appendix A. Document History . . . . . . . . . . . . . . . . . . 49 139 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 49 140 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 50 141 A.3. draft-hardt-xauth-protocol-02 . . . . . . . . . . . . . . 50 143 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 50 144 Appendix C. Open Questions . . . . . . . . . . . . . . . . . . . 51 145 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 51 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 188 2.1. Parties 190 The parties and their relationships to each other: 192 +--------+ +------------+ 193 | User | | Resource | 194 | | | Owner (RO) | 195 +--------+ +------------+ 196 | \ / | 197 | \ / | 198 | \ / | 199 | \ / | 200 +--------+ +---------------+ +------------+ 201 | Client |---->| Grant | _ _ | Resource | 202 | |<----| Server (GS) | | Server | 203 | | +---------------+ | (RS) | 204 | |-------------------------->| | 205 | |<--------------------------| | 206 +--------+ +------------+ 208 * *User* - the person interacting with the Client who has delegated 209 access to identity claims about themselves to the Grant Server 210 (GS), and can authenticate at the GS. 212 * *Client* - requests a Grant from the GS to access one or more 213 Resource Servers (RSs), and/or identity claims about the User. 214 The Client can create, retrieve, update, and delete a Grant. When 215 a Grant is created, the Client receives from the GS the granted 216 access token(s) for the RS(s), and identity claims about the User. 217 The Client uses an access token to access the RS. There are two 218 types of Clients: Registered Clients and Dynamic Clients. All 219 Clients have a key to authenticate with the Grant Server. 221 * *Registered Client* - a Client that has registered with the GS and 222 has a Client ID to identify itself, and can prove it possesses a 223 key that is linked to the Client ID. The GS may have different 224 policies for what different Registered Clients can request. A 225 Registered Client MAY be interacting with a User. 227 * *Dynamic Client* - a Client that has not been registered with the 228 GS, and each instance will generate it's own key pair so it can 229 prove it is the same instance of the Client on subsequent 230 requests, and to requests of a Resource Server. A single-page 231 application with no server is an example of a Dynamic Client. A 232 Dynamic Client MUST be interacting with a User. 234 * *Grant Server* (GS) - manages Grants for access to APIs at RSs and 235 release of identity claims about the User. The GS may require 236 explicit consent from the RO or User to provide these to the 237 Client. An GS may support Registered Clients and/or Dynamic 238 Clients. The GS is a combination of the Authorization Server (AS) 239 in OAuth 2.0, and the OpenID Provider (OP) in OpenID Connect. 241 * *Resource Server* (RS) - has API resources that require an access 242 token from the GS. Owned by the Resource Owner. 244 * *Resource Owner* (RO) - owns the RS, and has delegated RS access 245 management to the GS. The RO may be the same entity as the User, 246 or may be a different entity that the GS interacts with 247 independently. GS and RO interactions are out of scope of this 248 document. 250 2.2. Reused Terms 252 * *access token* - an access token as defined in [RFC6749] 253 Section 1.4. 255 * *Claim* - a Claim as defined in [OIDC] Section 5. Claims may be 256 issued by the GS, or by other issuers. 258 * *Client ID* - a GS unique identifier for a Registered Client as 259 defined in [RFC6749] Section 2.2. 261 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 263 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 265 * *authN* - short for authentication. 267 * *authZ* - short for authorization. 269 2.3. New Terms 271 * *GS URI* - the endpoint at the GS the Client calls to create a 272 Grant. The unique identifier for the GS. 274 * *Grant* - the user identity claims and/or RS authorizations the GS 275 has granted to the Client. 277 * *Grant URI* - the URI that represents the Grant. The Grant URI 278 MUST start with the GS URI. 280 * *Authorization* - the access granted by the RO to the Client. 281 Contains an access token. 283 * *AuthZ URI* - the URI that represents the Authorization the Client 284 was granted by the RO. The AuthZ URI MUST start with the GS URI. 285 The AuthZ URI is used to refresh, update, and delete an access 286 token. 288 * *interaction* - [Editor: what do we really mean by this term?] 290 3. Sequences 292 Before any sequence, the Client needs to be manually or 293 programmatically configured for the GS. See GS Options Section 5.9 294 for details on acquiring GS metadata. 296 [Editor: a plethora of sequences are included to illustrate all the 297 different actions. Many of these could potentially be moved to a use 298 case document in the future.] 300 3.1. Create Grant 302 The Client requests a Grant from the GS that requires User 303 interaction: 305 +--------+ +-------+ 306 | Client | | GS | 307 | |--(1)--- Create Grant ----------->| | 308 | | | (2) | 309 | |<--- Interaction Response ---(3)--| eval | 310 | | | | 311 | |--(4)--- Read Grant ------------->| | +------+ 312 | | | | | User | 313 | |--(5)--- Interaction Transfer --- | - - - | ------->| | 314 | | | |<--(6)-->| | 315 | | | | authN | | 316 | | | |<--(7)-->| | 317 | | | | authZ | | 318 | |<--- Interaction Transfer ---(8)- | - - - | --------| | 319 | | | | | | 320 | |<--------- Grant Response ---(9)--| | +------+ 321 | | | | 322 +--------+ +-------+ 324 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 325 and sends it with an HTTP POST to the GS GS URI. 327 2. *Grant Request Evaluation* The GS processes the request to 328 determine if it will send a Interaction Response, Wait Response, 329 or a Grant Response. The GS determines that interaction with the 330 User is required and sends an Interaction Response. (For 331 readability, this step is not described in the following 332 sequences) 334 3. *Interaction Response* The GS sends an Interaction Response 335 (Section 7.2) containing the Grant URI and an interaction object. 337 4. *Read Grant* The Client does an HTTP GET of the Grant URI 338 (Section 5.2). 340 5. *Interaction Transfer* The Client transfers User interaction to 341 the GS. 343 6. *User Authentication* The GS authenticates the User. 345 7. *User Authorization* If required, the GS interacts with the User 346 to determine which identity claims and/or authorizations in the 347 Grant Request are to be granted. 349 8. *Interaction Transfer* The GS transfers User interaction to the 350 Client. 352 9. *Grant Response* The GS responds with a Grant Response 353 (Section 7.1). 355 3.2. Reciprocal Grant 357 Party A and Party B are both a Client and a GS, and each Client would 358 like a Grant for the other GS. Party A starts off being the Client 359 per Create Grant Section 3.1. Party B then includes a Reciprocal 360 Request in its Grant Response. Party A then gets authorization from 361 the User and returns a Grant URI to Party B. Party A and B swap 362 roles, and Party B's Client obtains the Grant from Party A's GS. 364 Party A Party B 365 +--------+ +--------+ 366 | Client | | GS | 367 ~ ~ ~ ~ ~ ~ Same as steps 1 - 8 of ~ ~ ~ ~ ~ ~ 368 +------+ | | Create Grant above | | 369 | User | | | | | 370 | |<----- | - - - | -- Interaction Transfer ------- | | 371 | | | | | | 372 | | | |<------- Grant Response ---(1)---| | 373 | | | | Reciprocal Grant Request | | 374 | |<-(2)->| | | | 375 | | AuthZ | |---(3)--- Update Grant --------->| | 376 +------+ | | Reciprocal Grant Response | | 377 | | | | 378 | |<-- Empty Grant Response ---(4)--| | 379 | | | | 380 +--------+ (5) Swap Roles +--------+ 381 | GS | | Client | 382 | |<------------ Read Grant ---(6)--| | 383 | | | | 384 | |--(7)--- Grant Response -------->| | 385 | | | | 386 +--------+ +--------+ 388 1. *Grant Response* Party B responds with a Grant Response including 389 a Reciprocal Object Section 7.4.6 requesting its own Grant. 391 2. *User Authorization* If required, Party A interacts with the User 392 to determine which identity claims and/or authorizations in the 393 Grant Request are to be granted to Party B. 395 3. *Update Grant* Party A sends an Update Grant request containing 396 the Grant URI in the Reciprocal object Section 5.5.7. 398 4. *Grant Response* Party B responds with an Empty Grant Response as 399 there were no other requests in the Update Grant. 401 5. *Swap Roles* Party A now acts as a GS, Party B as a Client. 403 6. *Read Grant* Party B does an HTTP GET of the Grant URI 404 (Section 5.2). 406 7. *Grant Response* Party A responds with a Grant Response 407 (Section 7.1). 409 3.3. GS Initiated Grant 411 The User is at the GS, and wants to interact with a Registered 412 Client. The GS can redirect the User to the Client: 414 +--------+ +-------+ +------+ 415 | Client | | GS | | User | 416 | | | |<--(1)-->| | 417 | | | | | | 418 | |<----- GS Initiation Redirect --- | - - - | --(2)---| | 419 | (3) | | | | | 420 | verify |--(4)--- Read Grant ------------->| | +------+ 421 | | | | 422 | |<--------- Grant Response --(5)---| | 423 | | | | 424 +--------+ +-------+ 426 1. *User Interaction* The GS interacts with the User to determine 427 the Client and what identity claims and authorizations to 428 provide. The GS creates a Grant and corresponding Grant URI. 430 2. *GS Initiated Redirect* The GS redirects the User to the Client's 431 interaction_uri, adding a query parameter with the name "Grant 432 URI" and the value being the URL encoded Grant URI. 434 3. *Client Verification* The Client verifies the Grant URI is from 435 an GS the Client trusts, and starts with the GS GS URI. 437 4. *Read Grant* The Client does an HTTP GET of the Grant URI 438 (Section 5.2). 440 5. *Grant Response* The GS responds with a Grant Response 441 (Section 7.1). 443 See Section 6 for more details. 445 3.4. Create and Update 447 The Client requests an identity claim to determine who the User is. 448 Once the Client learns who the User is, and the Client updates the 449 Grant for additional identity claims which the GS prompts the User 450 for and returns to the Client. Once those are received, the Client 451 updates the Grant with the remaining identity claims required. 453 +--------+ +-------+ 454 | Client | | GS | 455 | |--(1)--- Create Grant ----------->| | 456 | | "interaction"."keep":true | | 457 | | | | 458 | |<--- Interaction Response ---(2)--| | 459 | | | | 460 | |--(3)--- Read Grant ------------->| | +------+ 461 | | | | | User | 462 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 463 | | | | | | 464 | | | |<--(5)-->| | 465 | | | | authN | | 466 | |<--------- Grant Response ---(6)--| | | | 467 | (7) | | | | | 468 | eval |--(8)--- Update Grant ----------->| | | | 469 | | "interaction"."keep":true | |<--(9)-->| | 470 | | | | authZ | | 471 | |<--------- Grant Response --(10)--| | | | 472 | (11) | | | | | 473 | eval |--(12)-- Update Grant ----------->| | | | 474 | | "interaction"."keep":false | |<--(13)->| | 475 | | | | authZ | | 476 | | | | | | 477 | |<--- Interaction Transfer --(14)- | - - - | --------| | 478 | | | | | | 479 | |<--------- Grant Response --(15)--| | +------+ 480 | | | | 481 +--------+ +-------+ 483 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 484 including an identity claim and "interaction"."keep":true, and 485 sends it with an HTTP POST to the GS GS URI. 487 2. *Interaction Response* The GS sends an Interaction Response 488 (Section 7.2) containing the Grant URI, an interaction object, 489 and "interaction"."keep":true. 491 3. *Read Grant* The Client does an HTTP GET of the Grant URI 492 (Section 5.2). 494 4. *Interaction Transfer* The Client transfers User interaction to 495 the GS. 497 5. *User Authentication* The GS authenticates the User. 499 6. *Grant Response* The GS responds with a Grant Response 500 (Section 7.1) including the identity claim from User 501 authentication and "interaction"."keep":true. 503 7. *Grant Evaluation* The Client queries its User database and does 504 not find a User record matching the identity claim. 506 8. *Update Grant* The Client creates an Update Grant Request 507 (Section 5.3) including the initial identity claims required and 508 "interaction"."keep":true, and sends it with an HTTP PUT to the 509 Grant URI. 511 9. *User AuthN* The GS interacts with the User to determine which 512 identity claims in the Update Grant Request are to be granted. 514 10. *Grant Response* The GS responds with a Grant Response 515 (Section 7.1) including the identity claims released by the User 516 and "interaction"."keep":true. 518 11. *Grant Evaluation* The Client evaluates the identity claims in 519 the Grant Response and determines the remaining User identity 520 claim required. 522 12. *Update Grant* The Client creates an Update Grant Request 523 (Section 5.3) including the remaining required identity claims 524 and "interaction"."keep":false, and sends it with an HTTP PUT to 525 the Grant URI. 527 13. *User AuthZ* The GS interacts with the User to determine which 528 identity claims in the Update Grant Request are to be granted. 530 14. *Interaction Transfer* The GS transfers User interaction to the 531 Client. 533 15. *Grant Response* The GS responds with a Grant Response 534 (Section 7.1) including the identity claims released by the 535 User. 537 3.5. Create and Delete 539 The Client requests an identity claim to determine who the User is. 540 Once the Client learns who the User is, and the Client knows it has 541 all the identity claims and authorizations needed, the Client deletes 542 the Grant which prompts the GS to transfer the interaction back to 543 the Client. 545 +--------+ +-------+ 546 | Client | | GS | 547 | |--(1)--- Create Grant ----------->| | 548 | | "interaction"."keep":true | | 549 | | | | 550 | |<--- Interaction Response ---(2)--| | 551 | | | | 552 | |--(3)--- Read Grant ------------->| | +------+ 553 | | | | | User | 554 | |--(4)--- Interaction Transfer --- | - - - | ------->| | 555 | | | | | | 556 | | | |<--(5)-->| | 557 | | | | authN | | 558 | |<--------- Grant Response ---(6)--| | | | 559 | (7) | | | | | 560 | eval |--(8)--- Delete Grant ----------->| | | | 561 | |<------- Delete Response ---------| | | | 562 | | | | | | 563 | |<--- Interaction Transfer ---(9)- | - - - | --------| | 564 | | | | | | 565 +--------+ +-------+ +------+ 567 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 568 including an identity claim and "interaction"."keep":true, and 569 sends it with an HTTP POST to the GS GS URI. 571 2. *Interaction Response* The GS sends an Interaction Response 572 (Section 7.2) containing the Grant URI, an interaction object, 573 and "interaction"."keep":true. 575 3. *Read Grant* The Client does an HTTP GET of the Grant URI 576 (Section 5.2). 578 4. *Interaction Transfer* The Client transfers User interaction to 579 the GS. 581 5. *User Authentication* The GS authenticates the User. 583 6. *Grant Response* The GS responds with a Grant Response 584 (Section 7.1) including the identity claim from User 585 authentication and "interaction"."keep":true. 587 7. *Grant Evaluation* The Client queries its User database and finds 588 the User record matching the identity claim, and that no 589 additional claims or authorizations are required. 591 8. *Delete Grant* The Client no longer needs the Grant and decides 592 to Delete Grant (Section 5.4) by sending an HTTP DELETE to the 593 Grant URI. If the GS responds with success the Grant no longer 594 exists. 596 3.6. Create, Discover, and Delete 598 The Client wants to discover if the GS has a User with a given 599 identifier. If not, it will abort the request and not transfer 600 interaction to the GS. 602 +--------+ +-------+ 603 | Client | | GS | 604 | |--(1)--- Create Grant ----------->| | 605 | | "user"."exists":true | | 606 | | | | 607 | |<--- Interaction Response ---(2)--| | 608 | | "user"."exists":false | | 609 | | | | 610 | |--(3)--- Delete Grant ----------->| | 611 | |<------- Delete Response ---------| | 612 | | | | 613 +--------+ +-------+ 615 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 616 including an identity claim request, a User identifier, and 617 "user"."exists":true. The Client sends it with an HTTP POST to 618 the GS GS URI. 620 2. *Interaction Response* The GS sends an Interaction Response 621 (Section 7.2) containing the Grant URI, an interaction object, 622 and "user"."exists":false. 624 3. *Delete Grant* The Client determines the GS cannot fulfil its 625 Grant Request, and decides to Delete Grant (Section 5.4) by 626 sending an HTTP DELETE to the Grant URI. If the GS responds with 627 success the Grant no longer exists. 629 3.7. Create and Wait 631 The Client wants access to resources that require the GS to interact 632 with the RO, which may not happen immediately, so the GS instructs 633 the Client to wait and check back later. 635 +--------+ +-------+ 636 | Client | | GS | 637 | |--(1)--- Create Grant ----------->| | 638 | | | | 639 | |<---------- Wait Response ---(2)--| | +------+ 640 | (3) | | | | RO | 641 | Wait | | |<--(4)-->| | 642 | | | | authZ | | 643 | |--(5)--- Read Grant ------------->| | +------+ 644 | | | | 645 | |<--------- Grant Response --(6)---| | 646 | | | | 647 +--------+ +-------+ 649 1. *Create Grant* The Client creates a Grant Request (Section 5.1) 650 and sends it with an HTTP POST to the GS GS URI. 652 2. *Wait Response* The GS sends an Interaction Response 653 (Section 7.3) containing the Grant URI and wait time. 655 3. *Client Waits* The Client waits the wait time. 657 4. *RO AuthZ* The GS interacts with the RO to determine which 658 identity claims in the Grant Request are to be granted. 660 5. *Read Grant* The Client does an HTTP GET of the Grant URI 661 (Section 5.2). 663 6. *Grant Response* The GS responds with a Grant Response 664 (Section 7.1). 666 3.8. Read Grant 668 The Client wants to acquire fresh identity claims and authorizations 669 in the Grant. No User or RO interaction is required as no new 670 consent or authorization is required. 672 +--------+ +-------+ 673 | Client | | GS | 674 | |--(1)--- Read Grant ------------->| | 675 | | | | 676 | |<--------- Grant Response --(2)---| | 677 | | | | 678 +--------+ +-------+ 680 1. *Read Grant* The Client does an HTTP GET of the Grant URI 681 (Section 5.2). 683 2. *Grant Response* The GS responds with a Grant Response 684 (Section 7.1) containing updated identity claims and 685 authorizations. 687 3.9. Access Token Refresh 689 The Client has an access token and uses it to access resources at an 690 RS. The access token expires, and the Client acquires a fresh access 691 token from the GS. 693 +--------+ +----------+ 694 | Client | | Resource | 695 | |--(1)--- Access Resource --->| Server | 696 | |<------- Resource Response --| (RS) | 697 | | | | 698 | |--(2)--- Access Resource --->| | 699 | |<------- Error Response -----| | 700 | | | | 701 | | +----------+ +-------+ 702 | | | GS | 703 | |--(3)--- Refresh AuthZ ------------------->| | 704 | |<------- AuthZ Response -------------------| | 705 | | | | 706 +--------+ +-------+ 708 1. *Resource Request* The Client accesses the RS with the access 709 token per Section 8 and receives a response from the RS. 711 2. *Resource Request* The Client attempts to access the RS, but 712 receives an error indicating the access token has expired. 714 3. *Refresh AuthZ* If the Client received an AuthZ URI in the 715 Response JSON "authorization" object (Section 7.4.3), the Client 716 can Refresh AuthZ (Section 5.6) with an HTTP GET to the AuthZ URI 717 and receive an Response JSON "authorization" object" 718 (Section 7.4.3) with a fresh access token. 720 3.10. GS API Table 722 +--------------+-----------+--------+-----------------------------+ 723 | request | http verb | uri | response | 724 +==============+===========+========+=============================+ 725 | Create Grant | POST | GS URI | interaction, wait, or grant | 726 +--------------+-----------+--------+-----------------------------+ 727 | Read Grant | GET | Grant | wait, or grant | 728 | | | URI | | 729 +--------------+-----------+--------+-----------------------------+ 730 | Update Grant | PUT | Grant | interaction, wait, or grant | 731 | | | URI | | 732 +--------------+-----------+--------+-----------------------------+ 733 | Delete Grant | DELETE | Grant | success | 734 | | | URI | | 735 +--------------+-----------+--------+-----------------------------+ 736 | Refresh | GET | AuthZ | authorization | 737 | AuthZ | | URI | | 738 +--------------+-----------+--------+-----------------------------+ 739 | Update AuthZ | PUT | AuthZ | authorization | 740 | | | URI | | 741 +--------------+-----------+--------+-----------------------------+ 742 | Delete AuthZ | DELETE | AuthZ | success | 743 | | | URI | | 744 +--------------+-----------+--------+-----------------------------+ 745 | GS Options | OPTIONS | GS URI | metadata | 746 +--------------+-----------+--------+-----------------------------+ 747 | Grant | OPTIONS | Grant | metadata | 748 | Options | | URI | | 749 +--------------+-----------+--------+-----------------------------+ 750 | AuthZ | OPTIONS | AuthZ | metadata | 751 | Options | | URI | | 752 +--------------+-----------+--------+-----------------------------+ 754 Table 1 756 [ Editor: is there value in an API for listing a Client's Grants? 757 eg:] 759 List Grants GET GS URI JSON array of Grant URIs 761 4. Grant and AuthZ Life Cycle 763 [Editor: straw man for life cycles.] 765 *Grant life Cycle* 767 The Client MAY create, read, update, and delete Grants. A Grant 768 persists until it has expired, is deleted, or another Grant is 769 created for the same GS, Client, and User tuple. 771 At any point in time, there can only be one Grant for the GS, Client, 772 and User tuple. When a Client creates a Grant at the same GS for the 773 same User, the GS MUST invalidate a previous Grant for the Client at 774 that GS for that User. 776 *Authorization Life Cycle* 777 Authorizations are OPTIONALLY included in a Grant Response 778 "authorization" Object (Section 7.4.3), and are represented by an 779 AuthZ URI. If an AuthZ URI is included, the Client MAY refresh, 780 update, and delete Authorizations. 782 An Authorization will persist independent of the Grant, and persist 783 until invalidated by the GS per GS policy, or deleted by the Client. 785 5. GS APIs 787 *Client Authentication* 789 All APIs except for GS Options require the Client to authenticate. 791 This document defines the JOSE Authentication mechanism in 792 Section 10. Other mechanisms include [TBD]. 794 5.1. Create Grant 796 The Client creates a Grant by doing an HTTP POST of a JSON [RFC8259] 797 document to the GS URI. 799 The JSON document MUST include the following from the Request JSON 800 Section 5.5: 802 * iat 804 * nonce 806 * uri set to the GS URI 808 * client 810 and MAY include the following from Request JSON Section 5.5 812 * user 814 * interaction 816 * authorization or authorizations 818 * claims 820 * reciprocal 822 The GS MUST respond with one of Grant Response Section 7.1, 823 Interaction Response Section 7.2, Wait Response Section 7.3, or one 824 of the following errors: 826 * TBD 828 from Error Responses Section 9. 830 Following is a non-normative example where the Client wants to 831 interact with the User with a popup and is requesting identity claims 832 about the User and read access to the User's contacts: 834 Example 1 836 { 837 "iat" : 15790460234, 838 "uri" : "https://as.example/endpoint", 839 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 840 "client": { 841 "display": { 842 "name" : "SPA Display Name", 843 "uri" : "https://spa.example/about" 844 } 845 }, 846 "interaction": { 847 "type" : "popup" 848 }, 849 "authorization": { 850 "type" : "oauth_scope", 851 "scope" : "read_contacts" 852 }, 853 "claims": { 854 "oidc": { 855 "id_token" : { 856 "email" : { "essential" : true }, 857 "email_verified" : { "essential" : true } 858 }, 859 "userinfo" : { 860 "name" : { "essential" : true }, 861 "picture" : null 862 } 863 } 864 } 865 } 867 Following is a non-normative example where the Client is requesting 868 the GS to keep the interaction with the User after returning the ID 869 Token so the Client can update the Grant, and is also asking if the 870 user exists: 872 Example 2 874 { 875 "iat" : 15790460234, 876 "uri" : "https://as.example/endpoint", 877 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 878 "client": { 879 "id" : "di3872h34dkJW" 880 }, 881 "interaction": { 882 "keep" : true, 883 "type" : "redirect", 884 "uri" : "https://web.example/return" 885 }, 886 "user": { 887 "identifiers": { 888 "email" : "jane.doe@example.com" 889 }, 890 "exists" : true 891 }, 892 "claims" : { "oidc": { "id_token" : {} } } 893 } 895 5.2. Read Grant 897 The Client reads a Grant by doing an HTTP GET of the corresponding 898 Grant URI. 900 The GS MUST respond with one of Grant Response Section 7.1, 901 Interaction Response Section 7.2, Wait Response Section 7.3, or one 902 of the following errors: 904 * TBD 906 from Error Responses Section 9. 908 5.3. Update Grant 910 The Client updates a Grant by doing an HTTP PUT of a JSON document to 911 the corresponding Grant URI. 913 The JSON document MUST include the following from the Request JSON 914 Section 5.5 916 * iat 918 * uri set to the Grant URI 919 and MAY include the following from Request JSON Section 5.5 921 * user 923 * interaction 925 * authorization or authorizations 927 * claims 929 * reciprocal 931 The GS MUST respond with one of Grant Response Section 7.1, 932 Interaction Response Section 7.2, Wait Response Section 7.3, or one 933 of the following errors: 935 * TBD 937 from Error Responses Section 9. 939 Following is a non-normative example where the Client made an 940 "interaction"."keep":true request, and now wants to update the 941 request with additional claims: 943 Example 3 945 { 946 "iat" : 15790460234, 947 "uri" : "https://as.example/endpoint/grant/example3", 948 "claims": { 949 "oidc": { 950 "userinfo" : { 951 "email" : { "essential" : true }, 952 "name" : { "essential" : true }, 953 "picture" : null 954 } 955 } 956 } 957 } 959 5.4. Delete Grant 961 The Client deletes a Grant by doing an HTTP DELETE of the 962 corresponding Grant URI. 964 The GS MUST respond with OK 200, or one of the following errors: 966 * TBD 967 from Error Responses Section 9. 969 5.5. Request JSON 971 [Editor: do we want to reuse the JWT claims "iat", "jti", etc.? ] 973 * *iat* - the time of the request as a NumericDate. 975 * *nonce* - a unique identifier for this request. Note the Grant 976 Response MUST contain a matching nonce attribute value. 978 * *uri* - the GS URI if in a Create Grant Section 5.1, or the Grant 979 URI if in an Update Grant Section 5.3. 981 5.5.1. "client" Object 983 The client object MUST contain either the id attribute for Registered 984 Clients, or the display object for Dynamic Clients. 986 * *id* - the Client ID the GS has for the Registered Client. 988 * *display* - the display object contains the following attributes: 990 - *name* - a string that represents the Dynamic Client 992 - *uri* - a URI representing the Dynamic Client 994 [Editor: a max length for the name?] [Editor: a max length for the 995 URI?] 997 The name and uri will be displayed by the GS when prompting for 998 authorization. 1000 5.5.2. "interaction" Object 1002 The interaction object contains the type of interaction the Client 1003 will provide the User. Other attributes 1005 * *keep* - a JSON boolean. If set to the JSON value true, the GS 1006 will not transfer the User interaction back to the Client after 1007 processing the Grant request. The JSON value false is equivalent 1008 to the attribute not being present, and the GS will transfer the 1009 User interaction back to the Client after processing the request. 1010 This attribute is OPTIONAL 1012 - *type* - contains one of the following values: "popup", 1013 "redirect", or "qrcode". Details in Section 7.4.7. This 1014 attribute is REQUIRED. 1016 - *redirect_uri* - this attribute is REQUIRED if the type is 1017 "redirect". It is the URI that the Client requests the GS to 1018 redirect the User to after the GS has completed interacting 1019 with the User. If the Client manages session state in URIs, 1020 then the redirect_uri SHOULD contain that state. 1022 - *ui_locales* - End-User's preferred languages and scripts for 1023 the user interface, represented as a space-separated list of 1024 [RFC5646] language tag values, ordered by preference. This 1025 attribute is OPTIONAL. 1027 [Editor: do we need max pixels or max chars for qrcode interaction? 1028 Either passed to GS, or max specified values here?] 1030 [Editor: other possible interaction models could be a "webview", 1031 where the Client can display a web page, or just a "message", where 1032 the client can only display a text message] 1034 [Editor: we may need to include interaction types for iOS and Android 1035 as the mobile OS APIs evolve.] 1037 5.5.3. "user" Object 1039 * *exists* - MUST contain the JSON true value. Indicates the Client 1040 requests the GS to return a "user"."exists" value in an 1041 Interaction Response Section 7.2. This attribute is OPTIONAL, and 1042 MAY be ignored by the GS. 1044 * *identifiers* - REQUIRED if the exists attribute is present. The 1045 values MAY be used by the GS to improve the User experience. 1046 Contains one or more of the following identifiers for the User: 1048 - *phone_number* - contains a phone number per Section 5 of 1049 [RFC3966]. 1051 - *email* - contains an email address per [RFC5322]. 1053 - *oidc* - is an object containing both the "iss" and "sub" 1054 attributes from an OpenID Connect ID Token per [OIDC] 1055 Section 2. 1057 5.5.4. "authorization" Object 1059 * *type* - one of the following values: "oauth_scope" or 1060 "oauth_rich". This attribute is REQUIRED. 1062 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 1063 section 3.3. MUST be included if type is "oauth_scope" or 1064 "oauth_rich". 1066 * *authorization_details* - an authorization_details object per 1067 [RAR]. MUST be included if type is "oauth_rich". 1069 [Editor: details may change as the [RAR] document evolves] 1071 5.5.5. "authorizations" Object 1073 A JSON array of "authorization" objects. Only one of "authorization" 1074 or "authorizations" may be in the Request JSON. 1076 [Editor: instead of an array, we could have a Client defined 1077 dictionary of "authorization" objects] 1079 5.5.6. "claims" Object 1081 Includes one or more of the following: 1083 * *oidc* - an object that contains one or both of the following 1084 objects: 1086 - *userinfo* - Claims that will be returned as a JSON object 1088 - *id_token* - Claims that will be included in the returned ID 1089 Token. If the null value, an ID Token will be returned 1090 containing no additional Claims. 1092 The contents of the userinfo and id_token objects are Claims as 1093 defined in [OIDC] Section 5. 1095 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 1096 per [OIDC4IA]. 1098 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 1099 be requested.] 1101 5.5.7. "reciprocal" Object 1103 * *uri* - the Grant URI for the Reciprocal Grant. This attribute is 1104 REQUIRED. 1106 * *client* - the client object must contain the "id" attribute with 1107 the Client ID the Grant was issued to. This attribute is 1108 REQUIRED. 1110 * *authorization* - an authorization object per Section 7.4.3 in the 1111 Response JSON. 1113 * *authorizations* - an authorizations object per Section 7.4.4 in 1114 the Response JSON. 1116 * *claims* - a claims object per Section 7.4.5 in the Response JSON. 1118 [Editor: parameters for the Client to request it wants the Grant 1119 Response signed and/or encrypted?] 1121 5.6. Refresh Authorization 1123 The Client updates an Authorization by doing an HTTP GET to the 1124 corresponding AuthZ URI. 1126 The GS MUST respond with an Response JSON "authorization" object 1127 Section 7.4.3, or one of the following errors: 1129 * TBD 1131 from Error Responses Section 9. 1133 5.7. Update Authorization 1135 The Client updates an Authorization by doing an HTTP PUT to the 1136 corresponding AuthZ URI of the following JSON. All of the following 1137 MUST be included. 1139 * *iat* - the time of the response as a NumericDate. 1141 * *uri* - the AuthZ URI. 1143 * *authorization* - the new authorization requested per the Request 1144 JSON "authorization" object Section 5.5.4. 1146 The GS MUST respond with an Response JSON "authorization" object 1147 Section 7.4.3, or one of the following errors: 1149 * TBD 1151 from Error Responses Section 9. 1153 5.8. Delete Authorization 1155 The Client deletes an Authorization by doing an HTTP DELETE to the 1156 corresponding AuthZ URI. 1158 The GS MUST respond with OK 200, or one of the following errors: 1160 * TBD 1162 from Error Responses Section 9. 1164 5.9. GS Options 1166 The Client can get the metadata for the GS by doing an HTTP OPTIONS 1167 of the corresponding GS URI. This is the only API where the GS MAY 1168 respond to an unauthenticated request. 1170 The GS MUST respond with the the following JSON document: 1172 [Editor: this section is a work in progress] 1174 * *uri* - the GS URI. 1176 * *client_authentication* - an array of the Client Authentication 1177 mechanisms supported by the GS 1179 * *interactions* - an array of the interaction types supported by 1180 the GS. 1182 * *authorization* - an object containing the authorizations the 1183 Client may request from the GS, if any. 1185 - Details TBD 1187 * *claims* - an object containing the identity claims the Client may 1188 request from the GS, if any, and what public keys the claims will 1189 be signed with. 1191 - Details TBD 1193 * *algorithms* - a list of the cryptographic algorithms supported by 1194 the GS. 1196 * *features* - an object containing feature support 1198 - *user_exists* - boolean indicating if "user"."exists" is 1199 supported. 1201 - *authorizations* - boolean indicating if a request for multiple 1202 authorizations is supported. 1204 [Editor: keys used by Client to encrypt requests, or verify signed 1205 responses?] 1207 [Editor: namespace metadata for extensions?] 1209 or one of the following errors: 1211 * TBD 1213 from Error Responses Section 9. 1215 5.10. Grant Options 1217 The Client can get the metadata for the Grant by doing an HTTP 1218 OPTIONS of the corresponding Grant URI. 1220 The GS MUST respond with the the following JSON document: 1222 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1224 or one of the following errors: 1226 * TBD 1228 from Error Responses Section 9. 1230 5.11. AuthZ Options 1232 The Client can get the metadata for the AuthZ by doing an HTTP 1233 OPTIONS of the corresponding AuthZ URI. 1235 The GS MUST respond with the the following JSON document: 1237 * *verbs* - an array of the HTTP verbs supported at the GS URI. 1239 or one of the following errors: 1241 * TBD 1243 from Error Responses Section 9. 1245 5.12. Request Verification 1247 On receipt of a request, the GS MUST verify the following: 1249 * TBD 1251 6. GS Initiated Grant 1253 [Editor: In OAuth 2.0, all flows are initiated at the Client. If the 1254 AS wanted to initiate a flow, it redirected to the Client, that 1255 redirected back to the AS to initiate a flow. 1257 Here is a proposal to support GS initiated: authentication; just-in- 1258 time (JIT) provisioning; and authorization] 1260 *initiation_uri* A URI at the Client that contains no query or 1261 fragment. How the GS learns the Client initiation_uri is out of 1262 scope. 1264 The GS creates a Grant and Grant URI, and redirects the User to the 1265 initiation_uri with the query parameter "grant" and the value of 1266 Grant URI. 1268 See Section 3.3 for the sequence diagram. 1270 7. GS API Responses 1272 7.1. Grant Response 1274 The Grant Response MUST include the following from the Response JSON 1275 Section 7.4 1277 * iat 1279 * nonce 1281 * uri 1283 * expires_in 1285 and MAY include the following from the Response JSON Section 7.4 1287 * authorization or authorizations 1289 * claims 1291 * reciprocal 1293 Example non-normative Grant Response JSON document for Example 1 in 1294 Section 3.1: 1296 { 1297 "iat" : 15790460234, 1298 "nonce" : "f6a60810-3d07-41ac-81e7-b958c0dd21e4", 1299 "uri" : "https://as.example/endpoint/grant/example1", 1300 "expires_in" : 300 1301 "authorization": { 1302 "type" : "oauth_scope", 1303 "scope" : "read_contacts", 1304 "expires_in" : 3600, 1305 "mechanism" : "bearer", 1306 "token" : "eyJJ2D6.example.access.token.mZf9p" 1307 }, 1308 "claims": { 1309 "oidc": { 1310 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 1311 "userinfo" : { 1312 "name" : "John Doe", 1313 "picture" : "https://photos.example/p/eyJzdkiO" 1314 } 1315 } 1316 } 1317 } 1319 Example non-normative Grant Response JSON document for Example 2 in 1320 Section 3.1: 1322 { 1323 "iat" : 15790460234, 1324 "nonce" : "5c9360a5-9065-4f7b-a330-5713909e06c6", 1325 "uri" : "https://as.example/endpoint/grant/example2", 1326 "authorization": { 1327 "type" : "oauth_scope", 1328 "scope" : "read_calendar write_calendar", 1329 "expires_in" : 3600, 1330 "mechanism" : "jose", 1331 "token" : "eyJJ2D6.example.access.token.mZf9p" 1332 "certificate": { 1333 "x5u" : "https://as.example/cert/example2" 1334 }, 1335 "uri" : "https://as.example/endpoint/authz/example2" 1336 } 1337 } 1339 7.2. Interaction Response 1341 The Interaction Response MUST include the following from the Response 1342 JSON Section 7.4 1343 * iat 1345 * nonce 1347 * uri 1349 * interaction 1351 and MAY include the following from the Response JSON Section 7.4 1353 * user 1355 * wait 1357 A non-normative example of an Interaction Response follows: 1359 { 1360 "iat" : 15790460234, 1361 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1362 "uri" : "https://as.example/endpoint/grant/example4", 1363 "interaction" : { 1364 "type" : "popup", 1365 "uri" : "https://as.example/popup/example4" 1366 }, 1367 "user": { 1368 "exists" : true 1369 } 1370 } 1372 7.3. Wait Response 1374 The Wait Response MUST include the following from the Response JSON 1375 Section 7.4 1377 * iat 1379 * nonce 1381 * uri 1383 * wait 1385 A non-normative example of an Wait Response follows: 1387 { 1388 "iat" : 15790460234, 1389 "nonce" : "0d1998d8-fbfa-4879-b942-85a88bff1f3b", 1390 "uri" : "https://as.example/endpoint/grant/example5", 1391 "wait" : 300 1392 } 1394 7.4. Response JSON 1396 Details of the JSON document: 1398 * *iat* - the time of the response as a NumericDate. 1400 * *nonce* - the nonce that was included in the Request JSON 1401 Section 5.5. 1403 * *uri* - the Grant URI. 1405 * *wait* - a numeric value representing the number of seconds the 1406 Client should want before making a Read Grant request to the Grant 1407 URI. 1409 * *expires_in* - a numeric value specifying how many seconds until 1410 the Grant expires. This attribute is OPTIONAL. 1412 7.4.1. "interaction" Object 1414 If the GS wants the Client to start the interaction, the GS MUST 1415 select one of the interaction mechanisms provided by the Client in 1416 the Grant Request, and include the matching attribute in the 1417 interaction object: 1419 * *type* - this MUST match the type provided by the Client in the 1420 Grant Request client.interaction object. 1422 * *uri* - the URI to interact with the User per the type. This may 1423 be a temporary short URL if the type is qrcode so that it is easy 1424 to scan. 1426 * *message* - a text string to display to the User if type is 1427 qrcode. 1429 [Editor: do we specify a maximum length for the uri and message so 1430 that a device knows the maximum it needs to support? A smart device 1431 may have limited screen real estate.] 1433 7.4.2. "user" Object 1434 * *exists* - a boolean value indicating if the GS has a user with 1435 one or more of the provided identifiers in the Request 1436 "user"."identifiers" object Section 5.5.3 1438 7.4.3. "authorization" Object 1440 The "authorization" object is a response to the Request 1441 "authorization" object Section 5.5.4, the Refresh Authorization 1442 Section 5.6, or the Update Authorization Section 5.7. 1444 * *type* - the type of claim request: "oauth_scope" or "oauth_rich". 1445 See the "type" object in Section 5.5.4 for details. 1447 * *scope* - the scopes the Client was granted authorization for. 1448 This will be all, or a subset, of what was requested. This 1449 attribute is OPTIONAL. 1451 * *authorization_details* - the authorization details granted per 1452 [RAR]. Included if type is "oauth_rich". 1454 * *mechanism* - one of the access mechanisms: "bearer", "jose", or 1455 "jose+body". See Section 8 for details. 1457 * *token* - the access token for accessing an RS. This attribute is 1458 REQUIRED. 1460 * *expires_in* - a numeric value specifying how many seconds until 1461 the access token expires. This attribute is OPTIONAL. 1463 * *certificate* - MUST be included if the mechanism is "jose" or 1464 "jose+body". Contains the jwk header values for the Client to 1465 include in the JWS header when calling the RS using the "jose" or 1466 "jose+body" mechanisms. See Section 10.2.1. 1468 * *uri* - the AuthZ URI. Used to refresh, update, and delete the 1469 authorization. This attribute is OPTIONAL. 1471 [Editor: any value in an expiry for the Authorization?] 1473 7.4.4. "authorizations" Object 1475 A JSON array of authorization objects. Support for the 1476 authorizations object is OPTIONAL. 1478 7.4.5. "claims" Object 1480 The claims object is a response to the Request "claims" object 1481 Section 5.5.4. 1483 * *oidc* 1485 - *id_token* - an OpenID Connect ID Token containing the Claims 1486 the User consented to be released. 1488 - *userinfo* - the Claims the User consented to be released. 1490 Claims are defined in [OIDC] Section 5. 1492 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 1493 per [OIDC4IA]. 1495 * *vc* 1497 The verified claims the user consented to be released. [Editor: 1498 details TBD] 1500 7.4.6. "reciprocal" Object 1502 The following MUST be included 1504 * *nonce* - a unique identifier for this request. Note the Grant 1505 Response MUST contain a matching nonce attribute value. 1507 * *client* 1509 - *id* - the Client ID making the request 1511 One or more of the following objects from the Request JSON 1512 Section 5.5 are included: 1514 * *authorization* Section 7.4.3 1516 * *authorizations* Section 7.4.4 1518 * *claims* Section 7.4.5 1520 7.4.7. Interaction Types 1522 If the GS wants the Client to initiate the interaction with the User, 1523 then the GS will return an Interaction Response. The Client will 1524 initiate the interaction with the User in one of the following ways: 1526 * *popup* The Client will create a new popup child browser window 1527 containing the "interaction"."uri" attribute. [Editor: more 1528 details on how to do this] 1530 The GS will close the popup window when the interactions with the 1531 User are complete. [Editor: confirm GS can do this still on all 1532 browsers, or does Client need to close] 1534 * *redirect* The Client will redirect the User to the 1535 "interaction"."uri" attribute. When the GS interactions with the 1536 User are complete, the GS will redirect the User to the 1537 "interaction"."redirect_uri" attribute the Client provided in the 1538 Grant Request. 1540 * *qrcode* The Client will create a [QR_Code] of the 1541 "interaction"."uri" attribute and display the resulting graphic 1542 and the "interaction"."message" attribute as a character string. 1544 An GS MUST support the "popup", "redirect", and "qrcode" interaction 1545 types. 1547 7.4.8. Signing and Encryption 1549 [Editor: TBD - how response is signed and/or encrypted by the GS. Is 1550 there a generalized description, or is it mechanism specific?] 1552 7.5. Response Verification 1554 On receipt of a response, the Client MUST verify the following: 1556 * TBD 1558 8. RS Access 1560 This document specifies three different mechanisms for the Client to 1561 access an RS ("bearer", "jose", and "jose+body"). The "bearer" 1562 mechanism is defined in {BearerToken}. The "jose" and "jose+body" 1563 mechanisms are proof-of-possession mechanisms and are defined in 1564 Section 10.2.2 and Section 10.2.3 respectively. Additional proof-of- 1565 possession mechanisms may be defined in other documents. The 1566 mechanism the Client is to use with an RS is the Response JSON 1567 "authorization"."mechanism" attribute Section 7.4.3. 1569 8.1. Bearer Token 1571 If the access mechanism is "bearer", then the Client accesses the RS 1572 per Section 2.1 of [RFC6750] 1574 A non-normative example of the HTTP request headers follows: 1576 GET /calendar HTTP/2 1577 Host: calendar.example 1578 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1580 9. Error Responses 1582 * TBD 1584 10. JOSE Authentication 1586 How the Client authenticates to the GS and RS are independent of each 1587 other. One mechanism can be used to authenticate to the GS, and a 1588 different mechanism to authenticate to the RS. 1590 Other documents that specify other Client authentication mechanisms 1591 will replace this section. 1593 In the JOSE Authentication Mechanism, the Client authenticates by 1594 using its private key to sign a JSON document with JWS per [RFC7515] 1595 which results in a token using JOSE compact serialization. 1597 [Editor: are there advantages to using JSON serialization in the 1598 body?] 1600 Different instances of a Registered Clients MAY have different 1601 private keys, but certificates bind them to a public key the GS has 1602 for the Client ID. An instance of a Client will use the same private 1603 key for all signing. 1605 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 1606 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 1608 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 1610 The token may be included in an HTTP header, or as the HTTP message 1611 body. 1613 The following sections specify how the Client uses JOSE to 1614 authenticate to the GS and RS. 1616 10.1. GS Access 1618 The Client authenticates to the GS by passing either a signed header 1619 parameter, or a signed message body. The following table shows the 1620 verb, uri and token location for each Client request to the GS: 1622 +---------------+-----------+-----------+----------+ 1623 | request | http verb | uri | token in | 1624 +===============+===========+===========+==========+ 1625 | Create Grant | POST | GS URI | body | 1626 +---------------+-----------+-----------+----------+ 1627 | Read Grant | GET | Grant URI | header | 1628 +---------------+-----------+-----------+----------+ 1629 | Update Grant | PUT | Grant URI | body | 1630 +---------------+-----------+-----------+----------+ 1631 | Delete Grant | DELETE | Grant URI | success | 1632 +---------------+-----------+-----------+----------+ 1633 | Refresh AuthZ | GET | AuthZ URI | body | 1634 +---------------+-----------+-----------+----------+ 1635 | Update AuthZ | PUT | AuthZ URI | body | 1636 +---------------+-----------+-----------+----------+ 1637 | Delete AuthZ | DELETE | AuthZ URI | header | 1638 +---------------+-----------+-----------+----------+ 1639 | GS Options | OPTIONS | GS URI | header | 1640 +---------------+-----------+-----------+----------+ 1641 | Grant Options | OPTIONS | Grant URI | header | 1642 +---------------+-----------+-----------+----------+ 1643 | AuthZ Options | OPTIONS | AuthZ URI | header | 1644 +---------------+-----------+-----------+----------+ 1646 Table 2 1648 10.1.1. Authorization Header 1650 For requests with the token in the header, the JWS payload MUST 1651 contain the following attributes: 1653 *iat* - the time the token was created as a NumericDate. 1655 *jti* - a unique identifier for the token per [RFC7519] section 1656 4.1.7. 1658 *uri* - the value of the URI being called (GS URI, Grant URI, or 1659 AuthZ URI). 1661 *verb* - the HTTP verb being used in the call ("GET", "DELETE", 1662 "OPTIONS") 1664 The HTTP authorization header is set to the "jose" parameter followed 1665 by one or more white space characters, followed by the resulting 1666 token. 1668 A non-normative example of a JWS payload and the HTTP request 1669 follows: 1671 { 1672 "iat" : 15790460234, 1673 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1674 "uri" : "https://as.example/endpoint/grant/example6", 1675 "verb" : "GET" 1676 } 1678 GET /endpoint/example.grant HTTP/2 1679 Host: as.example 1680 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 1682 [Editor: make a real example token] 1684 *GS Verification* 1686 The GS MUST verify the token by: 1688 * TBD 1690 10.1.2. Signed Body 1692 For requests with the token in the body, the Client uses the Request 1693 JSON as the payload in a JWS. The resulting token is sent with the 1694 content-type set to "application/jose". 1696 A non-normative example (line breaks added to the body for 1697 readability): 1699 POST /endpoint HTTP/2 1700 Host: as.example 1701 Content-Type: application/jose 1702 Content-Length: 155 1704 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 1705 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 1706 Jf36POk6yJV_adQssw5c 1708 [Editor: make a real example token] 1710 *GS Verification* 1712 The GS MUST verify the token by: 1714 * TBD 1716 10.1.3. Public Key Resolution 1717 * *Registered Clients* can use any of the JWS header values to 1718 direct the GS to resolve the public key matching the private key 1719 used to the Client ID. The GS MAY restrict with JWS headers a 1720 Client can use. 1722 [Editor: would examples help here so that implementors understand the 1723 full range of options, and how an instance can have its own asymetric 1724 key pair] 1726 A non-normative example of a JOSE header for a Registered Client with 1727 a key identifier of "12": 1729 { 1730 "alg" : "ES256", 1731 "typ" : "JOSE", 1732 "kid" : "12" 1733 } 1735 * *Dynamic Clients* include their public key in the "jwk" JWS 1736 header. 1738 A non-normative example of a JOSE header for a Dynamic Client: 1740 { 1741 "alg" : "ES256", 1742 "typ" : "JOSE", 1743 "jwk" : { 1744 "kty" : "EC", 1745 "crv" : "P-256", 1746 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1747 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1748 } 1749 } 1751 10.2. RS Access 1753 In the "jose" mechanism Section 10.2.2, all Client requests to the RS 1754 include a proof-of-possession token in the HTTP authorization header. 1755 In the "jose+body" mechanism Section 10.2.3, the Client signs the 1756 JSON document in the request if the POST or PUT verbs are used, 1757 otherwise it is the same as the "jose" mechanism. 1759 10.2.1. JOSE header 1761 The GS provides the Client one or more JWS header parameters and 1762 values for a a certificate, or a reference to a certificate or 1763 certificate chain, that the RS can use to resolve the public key 1764 matching the private key being used by the Client. 1766 A non-normative examples JOSE header: 1768 { 1769 "alg" : "ES256", 1770 "typ" : "JOSE", 1771 "x5u" : "https://as.example/cert/example2" 1772 } 1774 [Editor: this enables Dynamic Clients to make proof-of-possession API 1775 calls the same as Registered Clients.] 1777 10.2.2. "jose" Mechanism 1779 The JWS payload MUST contain the following attributes: 1781 *iat* - the time the token was created as a NumericDate. 1783 *jti* - a unique identifier for the token per [RFC7519] section 1784 4.1.7. 1786 *uri* - the value of the RS URI being called. 1788 *verb* - the HTTP verb being used in the call 1790 *token* - the access token provided by the GS to the Client 1792 The HTTP authorization header is set to the "jose" parameter followed 1793 by one or more white space characters, followed by the resulting 1794 token. 1796 A non-normative example of a JWS payload and the HTTP request 1797 follows: 1799 { 1800 "iat" : 15790460234, 1801 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1802 "uri" : "https://calendar.example/calendar", 1803 "verb" : "GET", 1804 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 1805 } 1807 GET /calendar HTTP/2 1808 Host: calendar.example 1809 Authorization: jose eyJhbG.example.jose.token.adks 1811 [Editor: make a real example token] 1813 *RS Verification* 1814 The RS MUST verify the token by: 1816 * verify access token is bound to the public key - include key 1817 fingerprint in access token? 1819 * TBD 1821 10.2.3. "jose+body" Mechanism 1823 The "jose+body" mechanism can only be used if the content being sent 1824 to the RS is a JSON document. 1826 Any requests not sending a message body will use the "jose" mechanism 1827 Section 10.2.2. 1829 Requests sending a message body MUST have the following JWS payload: 1831 *iat* - the time the token was created as a NumericDate. 1833 *jti* - a unique identifier for the token per [RFC7519] section 1834 4.1.7. 1836 *uri* - the value of the RS URI being called. 1838 *verb* - the HTTP verb being used in the call 1840 *token* - the access token provided by the GS to the Client 1842 *body* - the message body being sent to the RS 1844 A non-normative example of a JWS payload and the HTTP request 1845 follows: 1847 { 1848 "iat" : 15790460234, 1849 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 1850 "uri" : "https://calendar.example/calendar", 1851 "verb" : "POST", 1852 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 1853 "payload" : { 1854 "event" : { 1855 "title" : "meeting with joe", 1856 "start_date_utc" : "2020-02-21 11:00:00", 1857 "end_date_utc" : "2020-02-21 11:00:00" 1858 } 1859 } 1860 } 1862 POST /calendar HTTP/2 1863 Host: calendar.example 1864 Content-Type: application/jose 1865 Content-Length: 155 1867 eyJhbGciOi.example.jose+body.adasdQssw5c 1869 [Editor: make a real example token] 1871 *RS Verification* 1873 The RS MUST verify the token by: 1875 * TBD 1877 10.2.4. Public Key Resolution 1879 The RS has a public key for the GS that it uses to verify the 1880 certificate or certificate chain the Client includes in the JWS 1881 header. 1883 10.3. Request Encryption 1885 [Editor: to be fleshed out] 1887 The Client encrypts a request when ??? using the GS public key 1888 returned as the ??? attribute in GS Options Section 5.9. 1890 10.4. Response Signing 1892 [Editor: to be fleshed out] 1893 The Client verifies a signed response ??? using the GS public key 1894 returned as the ??? attribute in GS Options Section 5.9. 1896 10.5. Response Encryption 1898 [Editor: to be fleshed out] 1900 The Client decrypts a response when ??? using the private key 1901 matching the public key included in the request as the ??? attribute 1902 in Section 5.5. 1904 11. Extensibility 1906 This standard can be extended in a number of areas: 1908 * *Client Authentication Mechanisms* 1910 - An extension could define other mechanisms for the Client to 1911 authenticate to the GS and/or RS such as Mutual TLS or HTTP 1912 Signing. Constrained environments could use CBOR [RFC7049] 1913 instead of JSON, and COSE [RFC8152] instead of JOSE, and CoAP 1914 [RFC8323] instead of HTTP/2. 1916 * *Grant* 1918 - An extension can define new objects in the Grant Request and 1919 Grant Response JSON. 1921 * *Top Level* 1923 - Top level objects SHOULD only be defined to represent 1924 functionality other the existing top level objects and 1925 attributes. 1927 * *"client" Object* 1929 - Additional information about the Client that the GS would 1930 require related to an extension. 1932 * *"user" Object* 1934 - Additional information about the User that the GS would require 1935 related to an extension. 1937 * *"authorization" Object* 1939 - Additional types of authorizations in addition to OAuth 2.0 1940 scopes and RAR. 1942 * *"claims" Object* 1944 - Additional types of identity claims in addition to OpenID 1945 Connect claims and Verified Credentials. 1947 * *Interaction types* 1949 - Additional types of interactions a Client can start with the 1950 User. 1952 * *Continuous Authentication* 1954 - An extension could define a mechanism for the Client to 1955 regularly provide continuous authentication signals and receive 1956 responses. 1958 [Editor: do we specify access token / handle introspection in this 1959 document, or leave that to an extension?] 1961 [Editor: do we specify access token / handle revocation in this 1962 document, or leave that to an extension?] 1964 12. Rational 1966 1. *Why is there only one mechanism for the Client to authenticate 1967 with the GS? Why not support other mechanisms?* 1969 Having choices requires implementers to understand which choice 1970 is preferable for them. Having one default mechanism in the 1971 document for the Client to authenticate simplifies most 1972 implementations. Deployments that have unique characteristics 1973 can select other mechanisms that are preferable in specific 1974 environments. 1976 2. *Why is the default Client authentication JOSE rather than 1977 MTLS?* 1979 MTLS cannot be used today by a Dynamic Client. MTLS requires 1980 the application to have access below what is typically the 1981 application layer, that is often not available on some 1982 platforms. JOSE is done at the application layer. Many GS 1983 deployments will be an application behind a proxy performing 1984 TLS, and there are risks in the proxy passing on the results of 1985 MTLS. 1987 3. *Why is the default Client authentication JOSE rather than HTTP 1988 signing?* 1989 There is currently no widely deployed open standard for HTTP 1990 signing. Additionally, HTTP signing requires passing all the 1991 relevant parts of the HTTP request to downstream services within 1992 an GS that may need to independently verify the Client identity. 1994 4. *What are the advantages of using JOSE for the Client to 1995 authenticate to the GS and a resource?* 1997 Both Registered Clients and Dynamic Clients can have a private 1998 key, eliminating the public Client issues in OAuth 2.0, as a 1999 Dynamic Client can create an ephemeral key pair. Using 2000 asymetric cryptography also allows each instance of a Registered 2001 Client to have its own private key if it can obtain a 2002 certificate binding its public key to the public key the GS has 2003 for the Client. Signed tokens can be passed to downstream 2004 components in a GS or RS to enable independent verification of 2005 the Client and its request. The GS Initiated Sequence Section 6 2006 requires a URL safe parameter, and JOSE is URL safe. 2008 5. *Why does the GS not return parameters to the Client in the 2009 redirect url?* 2011 Passing parameters via a browser redirection is the source of 2012 many of the security risks in OAuth 2.0. It also presents a 2013 challenge for smart devices. In this protocol, the redirection 2014 from the Client to the GS is to enable the GS to interact with 2015 the User, and the redirection back to the Client is to hand back 2016 interaction control to the Client if the redirection was a full 2017 browser redirect. Unlike OAuth 2.0, the identity of the Client 2018 is independent of the URI the GS redirects to. 2020 6. *Why is there not a UserInfo endpoint as there is with OpenID 2021 Connect?* 2023 Since the Client can Read Grant at any time, it get the same 2024 functionality as the UserInfo endpoint, without the Client 2025 having to manage a separate access token and refresh token. If 2026 the Client would like additional claims, it can Update Grant, 2027 and the GS will let the Client know if an interaction is 2028 required to get any of the additional claims, which the Client 2029 can then start. 2031 [Editor: is there some other reason to have the UserInfo 2032 endpoint?] 2034 7. *Why is there still a Client ID?* 2035 The GS needs an identifier to fetch the meta data associated 2036 with a Client such as the name and image to display to the User, 2037 and the policies on what a Client is allowed to do. The Client 2038 ID was used in OAuth 2.0 for the same purpose, which simplifies 2039 migration. Dynamic Clients do not have a Client ID. 2041 8. *Why have both claims and authorizations?* 2043 There are use cases for each that are independent: 2044 authenticating a user vs granting access to a resource. A 2045 request for an authorization returns an access token or handle, 2046 while a request for a claim returns the claim. 2048 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 2049 GS communication in ?*Section 10 2051 Knowing the GS supports HTTP/2 enables a Client to set up a 2052 connection faster. HTTP/2 will be more efficient when Clients 2053 have large numbers of access tokens and are frequently 2054 refreshing them at the GS as there will be less network traffic. 2055 Mandating TLS 1.3 similarly improves the performance and 2056 security of Clients and GS when setting up a TLS connection. 2058 10. *Why do some of the JSON objects only have one child, such as 2059 the identifiers object in the user object in the Grant Request?* 2061 It is difficult to forecast future use cases. Having more 2062 resolution may mean the difference between a simple extension, 2063 and a convoluted extension. 2065 11. *Why is the "iss" included in the "oidc" identifier object? 2066 Would the "sub" not be enough for the GS to identify the User?* 2068 This decouples the GS from the OpenID Provider (OP). The GS 2069 identifier is the GS URI, which is the endpoint at the GS. The 2070 OP issuer identifier will likely not be the same as the GS URI. 2071 The GS may also provide claims from multiple OPs. 2073 12. *Why complicate the sequence with "interaction"."keep"?* 2075 A common pattern is to use an GS to authenticate the User at the 2076 Client. The Client does not know a priori if the User is a new 2077 User, or a returning User. Asking a returning User to consent 2078 releasing identity claims and/or authorizations they have 2079 already provided is a poor User experience, as is sending the 2080 User back to the GS. The Client requesting identity first 2081 enables the Client to get a response from the GS while the GS is 2082 still interacting with the User, so that the Client can request 2083 any identity claims/or authorizations required or desired. 2084 Additionally, the claims a Client may want about a User may be 2085 dependent on some initial Claims. For example, if a User is in 2086 a particular country, additional or different Claims my be 2087 required by the Client 2089 13. *Why is there a "jose+body" RS access mechanism method for the 2090 Client?*Section 10.2.3 2092 There are numerous use cases where the RS wants non-repudiation 2093 and providence of the contents of an API call. For example, the 2094 UGS Service Supplier Framework for Authentication and 2095 Authorization [UTM]. 2097 14. *Why use URIs to instead of handles for the Grant and 2098 Authorization?* 2100 A URI is an identifier just like a handle that can contain GS 2101 information that is opaque to the Client - so it has all the 2102 features of a handle, plus it can be the URL that is resolved to 2103 manipulate a Grant or an Authorization. As the Grant URI and 2104 AuthZ URI are defined to start with the GS URI, the Client (and 2105 GS) can easily determine which GS a Grant or Authorization 2106 belong to. URIs also enable a RESTful interface to the GS 2107 functionality. 2109 15. *Why have an OPTIONS verb on the GS URI? Why not use a .well- 2110 known mechanism?* 2112 Having the GS URI endpoint respond to the metadata allows the GS 2113 to provide Client specific results using the same Client 2114 authentication used for other requests to the GS. It also 2115 reduces the risk of a mismatch between what the advertised 2116 metadata, and the actual metadata. A .well-known discovery 2117 mechanism may be defined to resolve from a hostname to the GS 2118 URI. 2120 16. *Why have an UPDATE, DELETE, and OPTIONS verbs on the AuthZ 2121 URI?* 2123 Maybe there are no use cases for them [that the editor knows 2124 of], but the GS can not implement, and they are available if use 2125 cases come up. 2127 17. *Why list explicit interactions, instead of the Client and GS 2128 negotiating interaction capabilities?* 2129 The Client knows what interactions it is capable of, and 2130 prefers. Telling the GS the interaction allows the GS to know 2131 what interaction the User will have. Knowing how the Client 2132 will transition the interaction will enable the GS to provider a 2133 better User experience. For example, the GS may want to provide 2134 a short URL if it knows the Client will be showing a QR code vs 2135 a redirect, or have a different layout if it is a popup vs a 2136 redirect. 2138 13. Acknowledgments 2140 This draft derives many of its concepts from Justin Richer's 2141 Transactional Authorization draft [TxAuth]. 2143 Additional thanks to Justin Richer for his strong critique of earlier 2144 drafts. 2146 14. IANA Considerations 2148 [ JOSE parameter for Authorization HTTP header ] 2150 TBD 2152 15. Security Considerations 2154 TBD 2156 16. References 2158 16.1. Normative References 2160 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 2161 RFC 3966, DOI 10.17487/RFC3966, December 2004, 2162 . 2164 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2165 DOI 10.17487/RFC5322, October 2008, 2166 . 2168 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 2169 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 2170 September 2009, . 2172 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 2173 RFC 6749, DOI 10.17487/RFC6749, October 2012, 2174 . 2176 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 2177 Framework: Bearer Token Usage", RFC 6750, 2178 DOI 10.17487/RFC6750, October 2012, 2179 . 2181 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2182 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2183 2015, . 2185 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2186 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2187 . 2189 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 2190 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 2191 . 2193 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2194 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2195 DOI 10.17487/RFC7540, May 2015, 2196 . 2198 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2199 Interchange Format", STD 90, RFC 8259, 2200 DOI 10.17487/RFC8259, December 2017, 2201 . 2203 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2204 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2205 . 2207 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 2208 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 2209 . 2211 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 2212 Assurance 1.0", October 2019, . 2215 16.2. Informative References 2217 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2218 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2219 October 2013, . 2221 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 2222 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 2223 . 2225 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2226 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2227 . 2229 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2230 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 2231 Application Protocol) over TCP, TLS, and WebSockets", 2232 RFC 8323, DOI 10.17487/RFC8323, February 2018, 2233 . 2235 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 2236 "OAuth 2.0 Device Authorization Grant", RFC 8628, 2237 DOI 10.17487/RFC8628, August 2019, 2238 . 2240 [browser_based_apps] 2241 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 2242 Apps", September 2019, . 2245 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 2246 Rich Authorization Requests", January 2020, 2247 . 2249 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 2250 Credentials Data Model 1.0", November 2019, 2251 . 2253 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 2254 identification and data capture techniques - QR Code bar 2255 code symbology specification", February 2015, 2256 . 2258 [TxAuth] Richer, J., "Transactional AuthN", December 2019, 2259 . 2262 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UGS Service 2263 Supplier Framework for Authentication and AuthN", 2264 September 2019, . 2267 Appendix A. Document History 2269 A.1. draft-hardt-xauth-protocol-00 2271 * Initial version 2273 A.2. draft-hardt-xauth-protocol-01 2275 * text clean up 2277 * added OIDC4IA claims 2279 * added "jws" method for accessing a resource. 2281 * renamed Initiation Request -> Grant Request 2283 * renamed Initiation Response -> Interaction Response 2285 * renamed Completion Request -> Authorization Request 2287 * renamed Completion Response -> Grant Request 2289 * renamed completion handle -> authorization handle 2291 * added Authentication Request, Authentication Response, 2292 authentication handle 2294 A.3. draft-hardt-xauth-protocol-02 2296 * handles are now URIs 2298 * the 2300 * the collection of claims and authorizations are a Grant 2302 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 2304 *Changed Features* 2306 The major changes between this protocol and OAuth 2.0 and OpenID 2307 Connect are: 2309 * The Client uses a private key to authenticate in this protocol 2310 instead of the client secret in OAuth 2.0 and OpenID Connect. 2312 * The Client initiates the protocol by making a signed request 2313 directly to the GS instead of redirecting the User to the GS. 2315 * The Client does not pass any parameters in redirecting the User to 2316 the GS, nor receive any parameters in the redirection back from 2317 the GS. 2319 * The refresh_token has been replaced with a AuthZ URI that both 2320 represents the access, and is the URI to call to refresh access. 2322 * The Client can request identity claims to be returned independent 2323 of the ID Token. There is no UserInfo endpoint to query claims as 2324 there is in OpenID Connect. 2326 * The GS URI is the token endpoint. CHECK!!!s 2328 *Preserved Features* 2330 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 2331 tokens of OAuth 2.0. 2333 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 2334 Connect. 2336 * No change is required by the Client or the RS for existing bearer 2337 token protected APIs. 2339 *New Features* 2341 * A Grant represents the user identity claims and RS access granted 2342 to the Client. 2344 * The Client can update, retrieve, and delete a Grant. 2346 * The GS can initiate a flow by creating a Grant and redirecting the 2347 User to the Client with the Grant URI. 2349 * The Client can discovery if an GS has a User with an identifier 2350 before the GS interacts with the User. 2352 * The Client can request the GS to first authenticate the User and 2353 return User identity claims, and then the Client can update Grant 2354 request based on the User identity. 2356 * Support for QR Code initiated interactions. 2358 * Each Client instance can have its own private / public key pair. 2360 * More Extensibility dimensions. 2362 Appendix C. Open Questions 2364 Author's Address 2365 Dick Hardt (editor) 2366 SignIn.Org 2367 United States 2369 Email: dick.hardt@gmail.com