idnits 2.17.00 (12 Aug 2021) /tmp/idnits36375/draft-hardt-xauth-protocol-01.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 38 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 182: '... Client MAY be interacting with a...' RFC 2119 keyword, line 188: '...ent. The Client MUST be interacting w...' RFC 2119 keyword, line 485: '... REQUIRED....' RFC 2119 keyword, line 490: '... REQUIRED. Note the AS Response MUS...' RFC 2119 keyword, line 495: '...he client object MUST contain either t...' (43 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The client object MUST contain either the client_id attribute for Registered Clients, or the display object for Dynamic Clients. If the Client can interact with the User, then an interaction object MUST be included. If there is an authentication handle, then the client object MUST not be included. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The user and identifiers objects MAY be included to improve the user experience by the AS. The AS MUST authenticate the User independent of these values. The user object MUST not be included if there is an authentication handle. -- The document date (29 January 2020) is 843 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 570, but not defined -- 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 (~~), 4 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 29 January 2020 5 Expires: 1 August 2020 7 The XAuth Protocol 8 draft-hardt-xauth-protocol-01 10 Abstract 12 Client software often desires resources or identity claims that are 13 managed independent of the client. This protocol allows a user and/ 14 or resource owner to delegate resource authorization and/or release 15 of identity claims to an authorization server. Client software can 16 then request access to resources and/or identity claims by calling 17 the authorization server. The authorization server acquires consent 18 and authorization from the user and/or resource owner if required, 19 and then returns the authorization and identity claims that were 20 approved. This protocol can be extended to support alternative 21 client authentication mechanisms, authorizations, claims, and 22 interactions. 24 [Editor: suggestions on how to improve this are welcome!] 26 [Editor: suggestions for other names than XAuth are welcome!] 28 Note to Readers 30 Source for this draft and an issue tracker can be found at 31 https://github.com/dickhardt/hardt-xauth-protocol 32 (https://github.com/dickhardt/hardt-xauth-protocol). 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 1 August 2020. 50 Copyright Notice 52 Copyright (c) 2020 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Simplified BSD License text 61 as described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2.1. Parties . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2.2. Handles . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 2.3. Reused Terms . . . . . . . . . . . . . . . . . . . . . . 5 71 2.4. Sequence . . . . . . . . . . . . . . . . . . . . . . . . 6 72 3. AS Request JSON . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.1. Top Level Attributes . . . . . . . . . . . . . . . . . . 11 74 3.2. "client" Object . . . . . . . . . . . . . . . . . . . . . 11 75 3.3. "user" Object . . . . . . . . . . . . . . . . . . . . . . 12 76 3.4. "authentication" Object . . . . . . . . . . . . . . . . . 13 77 3.5. "authorizations" Object . . . . . . . . . . . . . . . . . 13 78 3.6. "claims" Object . . . . . . . . . . . . . . . . . . . . . 14 79 3.7. Authorization Types . . . . . . . . . . . . . . . . . . . 14 80 4. Interaction Response JSON . . . . . . . . . . . . . . . . . . 14 81 4.1. "user" Object . . . . . . . . . . . . . . . . . . . . . . 15 82 4.2. "interaction" Object . . . . . . . . . . . . . . . . . . 15 83 4.3. "authorization" Object . . . . . . . . . . . . . . . . . 16 84 4.4. "authentication" Object . . . . . . . . . . . . . . . . . 16 85 5. Interaction Types . . . . . . . . . . . . . . . . . . . . . . 16 86 5.1. "popup" Type . . . . . . . . . . . . . . . . . . . . . . 16 87 5.2. "redirect" Type . . . . . . . . . . . . . . . . . . . . . 17 88 5.3. "qrcode" Type . . . . . . . . . . . . . . . . . . . . . . 17 89 6. AS Response JSON . . . . . . . . . . . . . . . . . . . . . . 17 90 6.1. Top Level Attributes . . . . . . . . . . . . . . . . . . 18 91 6.2. "authorizations" Object . . . . . . . . . . . . . . . . . 18 92 6.3. "claims" Object . . . . . . . . . . . . . . . . . . . . . 19 93 6.4. Access Methods . . . . . . . . . . . . . . . . . . . . . 20 94 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 20 95 8. JOSE Client Authentication . . . . . . . . . . . . . . . . . 20 96 8.1. JOSE Headers . . . . . . . . . . . . . . . . . . . . . . 21 97 8.2. Authentication Request Token . . . . . . . . . . . . . . 23 98 8.3. Authorization Request Token . . . . . . . . . . . . . . . 24 99 8.4. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 25 100 8.5. JOSE Access Token . . . . . . . . . . . . . . . . . . . . 25 101 8.6. HTTP Authorization JOSE Header . . . . . . . . . . . . . 26 102 8.7. JOSE Token Verification . . . . . . . . . . . . . . . . . 26 103 8.8. AS Request . . . . . . . . . . . . . . . . . . . . . . . 26 104 8.9. Interaction Response . . . . . . . . . . . . . . . . . . 26 105 8.10. Deletion Request . . . . . . . . . . . . . . . . . . . . 27 106 8.11. Authentication Request . . . . . . . . . . . . . . . . . 27 107 8.12. Authentication Response . . . . . . . . . . . . . . . . . 27 108 8.13. Authorization Request . . . . . . . . . . . . . . . . . . 27 109 8.14. AS Response . . . . . . . . . . . . . . . . . . . . . . . 28 110 8.15. Bearer Token RS Access . . . . . . . . . . . . . . . . . 28 111 8.16. Proof-of-possession RS Access . . . . . . . . . . . . . . 29 112 8.17. JOSE Body RS Access . . . . . . . . . . . . . . . . . . . 29 113 8.18. Access Refresh . . . . . . . . . . . . . . . . . . . . . 29 114 9. Error Messages . . . . . . . . . . . . . . . . . . . . . . . 30 115 10. AS Initiated Sequence . . . . . . . . . . . . . . . . . . . . 30 116 10.1. Initiation Token . . . . . . . . . . . . . . . . . . . . 32 117 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 32 118 12. Rational . . . . . . . . . . . . . . . . . . . . . . . . . . 33 119 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 120 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 121 15. Security Considerations . . . . . . . . . . . . . . . . . . . 36 122 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 123 16.1. Normative References . . . . . . . . . . . . . . . . . . 36 124 16.2. Informative References . . . . . . . . . . . . . . . . . 38 125 Appendix A. Document History . . . . . . . . . . . . . . . . . . 39 126 A.1. draft-hardt-xauth-protocol-00 . . . . . . . . . . . . . . 39 127 A.2. draft-hardt-xauth-protocol-01 . . . . . . . . . . . . . . 39 128 Appendix B. Comparison with OAuth 2.0 and OpenID Connect . . . . 39 129 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 131 1. Introduction 133 This protocol supports the widely deployed use cases supported by 134 OAuth 2.0 [RFC6749] & [RFC6750], and OpenID Connect [OIDC], an 135 extension of OAuth 2.0, as well as other extensions, and other use 136 cases that are not supported, such as requesting multiple 137 authorizations in one request. This protocol also addresses many of 138 the security issues in OAuth 2.0 by having parameters securely sent 139 directly between parties, rather than via a browser redirection. 141 The technology landscape has changed since OAuth 2.0 was initially 142 drafted. More interactions happen on mobile devices than PCs. 143 Modern browsers now directly support asymetric cryptographic 144 functions. Standards have emerged for signing and encrypting tokens 145 with rich payloads (JOSE) that are widely deployed. 147 Additional use cases are now being served with extensions to OAuth 148 2.0: OpenID Connect added support for authentication and releasing 149 identity claims; [RFC8252] added support for native apps; [RFC8628] 150 added support for smart devices; and support for [browser_based_apps] 151 is being worked on. There are numerous efforts on adding proof-of- 152 possession to resource access. 154 This protocol simplifies the overall architectural model, takes 155 advantage of today's technology landscape, provides support for all 156 the widely deployed use cases, and offers numerous extension points. 158 The 160 While this protocol is not backwards compatible with OAuth 2.0, it 161 strives to minimize the migration effort. 163 2. Protocol 165 2.1. Parties 167 * *Authorization Server* (AS) - manages Client authorization to API 168 resources and release of identity claims about the User. The AS 169 may require explicit consent from the RO or User to provide these 170 to the Client. 172 * *Client* - requests authorization to API resources, and/or 173 identity claims about the User. There are two types of Clients: 174 Registered Clients and Dynamic Clients. An AS may support only 175 one or both types. All Clients have a key to authenticate with 176 the AS. 178 * *Registered Client* - a Client that has registered with the AS and 179 has a Client ID to identify itself, and can prove it possesses a 180 key that is linked to the Client ID. The AS may have different 181 policies for what different Registered Clients can request. The 182 Client MAY be interacting with a User. 184 * *Dynamic Client* - a Client that has not been registered with the 185 AS, and each instance will generate it's own key pair so it can 186 prove it is the same instance of the Client on subsequent 187 requests. A single-page application with no server is an example 188 of a Dynamic Client. The Client MUST be interacting with a User. 190 * *User* - the person who has delegated making identity claims about 191 themselves to the AS, and is interacting with the Client. 193 * *Resource Server* (RS) - has API resources that require an access 194 token from the AS for access. 196 * *Resource Owner* (RO) - owns the RS, and has delegated RS access 197 token creation to the AS. The RO may be the same entity as the 198 User, or may be a different entity that the AS interacts with 199 independent of the Client. 201 2.2. Handles 203 Handles are strings issued by the AS to the Client that are opaque to 204 the Client. 206 * *authorization handle* - represents the client request. Presented 207 back to the AS in an Authorization Request. 209 * *authentication handle* - represents the client request for 210 authentication first. Presented back to the AS in an 211 Authentication Request, or in the subsequent AS Request. 213 * *access handle* - represents the access the AS has granted the 214 Client to the RS. The Client proves possession of its key when 215 presenting an access handle to access an RS. The RS is able to 216 understand the authorizations represented by the access handle 217 directly, or through an introspection call. The RS is able to 218 verify the access handle was issued to the Client that presented 219 it. 221 * *refresh handle* - represents the access the AS has granted the 222 Client to a RS. Presented back to the AS when the Client wants a 223 fresh access token or access handle. 225 When presenting any of the above handles, the Client always proves 226 possession of its key. 228 2.3. Reused Terms 230 * *access token* - an access token as defined in [RFC6749] 231 Section 1.4. 233 * *Claims* - Claims as defined in [OIDC] Section 5. 235 * *Client ID* - an AS unique identifier for a Registered Client as 236 defined in [RFC6749] Section 2.2. 238 * *ID Token* - an ID Token as defined in [OIDC] Section 2. 240 * *NumericDate* - a NumericDate as defined in [RFC7519] Section 2. 242 2.4. Sequence 244 1. *AS Discovery* (Section 7) The Client discovers the AS end 245 point, keys, supported claims and authorizations, and other 246 capabilities. Some, or all of this information could be 247 manually preconfigured, or dynamically obtained. Dynamic AS 248 discovery is out of scope of this document. 250 2. *AS Request* (Section 8.8) The Client creates an AS Request 251 (Section 3) for authorization to API resources and/or identity 252 claims about the User and sends it with an HTTP POST to the AS 253 endpoint. The Client includes requests authentication first if 254 the Client wants the AS to authenticate the User prior to 255 requesting additional claims and authorizations. 257 3. *AS Request Evaluation* The AS processes the request and 258 determines if it needs to interact with the RO or User. If 259 interaction is required, the AS returns an Interaction Response 260 (Section 4), if no interaction is required it returns an AS 261 Response (Section 6). 263 4. *Interaction Response* (Section 8.9) The AS will send an 264 authentication object unless the Client sent authentication 265 first, in which case the AS will send an authentication object. 266 If the AS wants the Client to initiate the User interaction, it 267 will include an interaction object. If authentication first, 268 the Client will next send (6) Authentication Request, otherwise 269 an Authorization Request. 271 5. *Authorization Request* (Section 8.13) The Client creates an 272 authorization request token Section 8.3 and does a GET of the 273 authorization uri, after waiting for any authorization wait 274 time. The Client then listens for (13) AS Response. 276 6. *Authentication Request* (Section 8.11) The Client creates an 277 authentication request token and does a GET of the 278 authentication uri. The Client then listens for (9) 279 Authentication Response. 281 7. *Interaction* If the AS sent interaction instructions to the 282 Client, the Client executes them. 284 8. *User Authentication* The AS authenticates the User. If Client 285 requested authentication first, the AS responds to the 286 Authentication Request with an (9) Authentication Response, 287 otherwise the AS performs any needed authorizations per step 288 (10). 290 9. *Authentication Response* (Section 8.12) The AS sends an AS 291 Response containing the identity claims the Client requested. 293 10. *AS Request 2* The Client uses the returned identity claims to 294 look up the User in its internal database and determines what, 295 if any, claims and/or authorizations it would like to request 296 and includes them in a new AS Request, as well as the 297 authentication handle. If Client wants not additional claims 298 and/or authorizations, the Client sets the claims object to the 299 JSON null value. The Client then listens for (13) AS Response. 301 11. *Authorization* If required, the AS interacts with the User and/ 302 or RO to determine which of any of the authorizations and 303 identity claims requests made by the Client are to be granted. 305 12. *Redirect* If the Client did a full browser redirect to the AS, 306 the AS redirects the User back to the redirect_uri supplied by 307 the Client, otherwise the AS closes its popup window, or informs 308 the User the interaction is complete. 310 13. *AS Response* (Section 8.14) The AS responds to the Client with 311 a AS Response (Section 6) containing authorized RS access tokens 312 and User identity claims. The AS may provide refresh handles 313 and uris for each access token if they are authorized. If 314 proof-of-possession is required for accessing the RS, the AS 315 will provide access handles instead of access tokens. If the AS 316 has not completed the interaction, it will instead return a 317 retry response for the Client to make a new Authorization 318 Request. 320 14. *Resource Request* (Section 8.15, Section 8.16, & Section 8.17) 321 The Client access the RS using a bearer token, a proof-of- 322 possession token, or a signed request. 324 15. *Access Refresh* (Section 8.18) If the Client received a refresh 325 handle and uri, it sends the refresh handle to the refresh uri, 326 and receives a fresh access token or handle. 328 *Sequence Diagram* 329 +--------+ +---------------+ 330 | |<-(1)------- Discovery ------------------->| Authorization | 331 | | | Server | 332 | |--(2)------- AS Request ------------------>| | 333 | | | (3) Request | 334 | | | Evaluation | 335 | |<-(4)------- Interaction Response ---------| | 336 | | | | 337 | |--(5)------- Authorization Request ------->| -------+ | 338 | | or | | | 339 | |--(6)------- Authentication Request ------>| ---+ | | 340 | | | | | | 341 | | +--------+ | | | | 342 | |--(7)--------->| User |<------------(8)--| | | | 343 | | Interaction +--------+ Authentication | | | | 344 | Client | | | | | 345 | | | | | | 346 | |<-(9)------- Authentication Response ------|<---+ | | 347 | | | | | 348 | |--(10)------ AS Request 2 ---------------->| -------+ | 349 | | | | | 350 | | +--------+ | | | 351 | |<-(12)---------| User |<-----------(11)--| | | 352 | | Redirect | / RO | Authorization | | | 353 | | +--------+ | | | 354 | | | | | 355 | |<-(13)------ AS Response ------------------|<-------+ | 356 | | | | 357 | | +----------+ | | 358 | |--(14)-- Resource Request -->| Resource | | | 359 | |<------ Resource Response ---| Server | | | 360 | | +----------+ | | 361 | | | | 362 | |--(15)------- Refresh Request ------------>| | 363 | |<----------- Refresh Response -------------| | 364 +--------+ +---------------+ 366 3. AS Request JSON 368 Following is a non-normative JSON [RFC8259] document example where 369 the Client wants to interact with the User with a popup and is 370 requesting identity claims about the User and read access to the 371 User's contacts: 373 Example 1 375 { 376 "as" :"https://as.example", 377 "iat" :"1579046092", 378 "nonce" :"f6a60810-3d07-41ac-81e7-b958c0dd21e4", 379 "client": { 380 "display": { 381 "name" :"SPA Display Name", 382 "uri" :"https://spa.example/about" 383 }, 384 "interaction": { 385 "type" :"popup" 386 } 387 }, 388 "authorizations": { 389 "type" :"oauth_scope", 390 "scope" :"read_contacts" 391 }, 392 "claims": { 393 "oidc": { 394 "id_token" : { 395 "email" : { "essential" : true }, 396 "email_verified" : { "essential" : true } 397 }, 398 "userinfo" : { 399 "name" : { "essential" : true }, 400 "picture" : null 401 } 402 } 403 } 404 } 406 Following is a non-normative example where the Client has previously 407 authenticated the User, and is requesting additional authorization: 409 Example 2 411 { 412 "as" :"https://as.example", 413 "iat" :"1579046092", 414 "nonce" :"0d1998d8-fbfa-4879-b942-85a88bff1f3b", 415 "client": { 416 "id" : "di3872h34dkJW", 417 "interaction": { 418 "type" : "redirect", 419 "uri" : "https://web.example/return" 420 } 421 }, 422 "user": { 423 "identifiers": { 424 "oidc": { 425 "iss" :"https://as.example", 426 "sub" :"123456789" 427 } 428 } 429 }, 430 "authorizations": { 431 "type" :"oauth_scope", 432 "scope" :"read_calendar write_calendar" 433 } 434 } 436 Following is a non-normative example where the Client is requesting 437 authorization first: 439 Example 3 441 { 442 "as" :"https://as.example", 443 "iat" :"1579046092", 444 "nonce" :"5c9360a5-9065-4f7b-a330-5713909e06c6", 445 "client": { 446 "id" : "di3872h34dkJW", 447 "interaction": { 448 "type" : "redirect", 449 "uri" : "https://web.example/return" 450 } 451 }, 452 "authentication": { 453 "first": true 454 }, 455 "claims": { "oidc": { "id_token" : {} } } 456 } 457 Following is a non-normative example where the Client previously 458 requested authorization first (Example 3), the response was a new 459 User, and now makes the following AS Request: 461 Example 4 463 { 464 "as" :"https://as.example", 465 "iat" :"1579046092", 466 "nonce" :"0a74f51f-514a-4821-b71f-01c252223f2f", 467 "authentication": { 468 "handle": "eyJhb958.example.authentication.handle.9yf3szM" 469 }, 470 "claims": { 471 "oidc": { 472 "userinfo" : { 473 "email" : { "essential" : true }, 474 "phone_number" : { "essential" : true }, 475 "name" : { "essential" : true }, 476 "picture" : null 477 } 478 } 479 } 480 } 482 3.1. Top Level Attributes 484 *as* - the unique string identifier for the AS. This attribute is 485 REQUIRED. 487 *iat* - the time of the request as a NumericDate. 489 *nonce* - a unique identifier for this request. This attribute is 490 REQUIRED. Note the AS Response MUST contain a matching nonce 491 attribute. 493 3.2. "client" Object 495 The client object MUST contain either the client_id attribute for 496 Registered Clients, or the display object for Dynamic Clients. If 497 the Client can interact with the User, then an interaction object 498 MUST be included. If there is an authentication handle, then the 499 client object MUST not be included. 501 *client_id* - the identifier the AS has for the Registered Client. 503 *display* - the display object contains the following attributes: 505 * *name* - a string that represents the Dynamic Client 507 [Editor: a max length for the name?] 509 * *uri* - a URI representing the Dynamic Client 511 [Editor: a max length for the URI?] 513 The name and uri will be displayed by the AS when prompting for 514 authorization. 516 *interaction* - the interaction object contains the type of 517 interaction the Client will provide the User. Other attributes are 518 dependent on the interaction type value. 520 * *type* - contains one of the following values: "popup", 521 "redirect", or "qrcode". Details in Section 5. 523 * *redirect_uri* - this attribute is included if the type is 524 "redirect". It is the URI that the Client requests the AS to 525 redirect the User to after the AS has completed interacting with 526 the User. If the Client manages session state in URIs, then the 527 redirect_uri should contain that state. 529 * *ui_locales* - End-User's preferred languages and scripts for the 530 user interface, represented as a space-separated list of [RFC5646] 531 language tag values, ordered by preference. 533 [Editor: do we need max pixels or max chars for qrcode interaction? 534 Either passed to AS, or max specified values here?] 536 [Editor: other possible interaction models could be a "webview", 537 where the Client can display a web page, or just a "message", where 538 the client can only display a text message] 540 [Editor: we may need to include interaction types for iOS and Android 541 as the mobile OS APIs evolve.] 543 [Editor: does the Client include parameters if it wants the AS 544 Response signed and/or encrypted?] 546 3.3. "user" Object 548 The user object is optional. 550 *identifiers* - the identifiers object contains one or more of the 551 following identifiers for the User: 553 * *phone_number* - contains a phone number per Section 5 of 554 [RFC3966]. 556 * *email* - contains an email address per [RFC5322]. 558 * *oidc* - is an object containing both the "iss" and "sub" 559 attributes from an OpenID Connect ID Token per [OIDC] Section 2. 561 The user and identifiers objects MAY be included to improve the user 562 experience by the AS. The AS MUST authenticate the User independent 563 of these values. The user object MUST not be included if there is an 564 authentication handle. 566 *discovery* - MUST contain the JSON true value. Indicates the Client 567 requests the AS to return a "discovered" attribute in the Interaction 568 Response if the AS has a User at the AS with one or more of the 569 identifiers. This attribute is OPTIONAL. Support of the discovery 570 attribute by the AS is OPTIONAL. The AS MAY return the [TBD] error 571 if discovery is not supported, or ignore the request. 573 3.4. "authentication" Object 575 This OPTIONAL object MUST contain one of the following attributes: 577 * *first* - Must have the JSON value true. Indicates the Client is 578 requesting authentication first, and an authentication object in 579 the Interaction Response. If present, the AS will ignore the 580 authorizations object. [Editor: any use case where the Client 581 needs an authorization at Authentication?] The Client SHOULD 582 limit the claims requested to only those needed to identify the 583 User at the Client. [Editor: this works if it is only a directed 584 identifier, but consent would be required to return a verified 585 phone or email. Hmmm.] 587 * *handle* - the authentication handle. MUST be included in the AS 588 Request following an Authentication Response. 590 3.5. "authorizations" Object 592 The optional authorizations object contains a dictionary of resource 593 objects the Client is requesting authorization to access. The 594 authorizations object may contain one or more of: 596 * *type* - one of the following values: "oauth_scope", "oauth_rich", 597 or "oauth_rich_list". See Section 3.7 for details. 599 * *scope* - a string containing the OAuth 2.0 scope per [RFC6749] 600 section 3.3. Present if type is "oauth_scope" or "oauth_rich". 602 * *authorization_details* - an authorization_details object per 603 [RAR]. Present if type is "oauth_rich". 605 * *list* - an array of objects containing "scope" and 606 "authorization_details". Present if type is "oauth_rich_list". 607 Used when requesting multiple access tokens and/or handles. 609 [Editor: details may change as the [RAR] document evolves] 611 3.6. "claims" Object 613 The optional claims object contains one or more identity claims being 614 requested. The claims may contain: 616 * *oidc* - an object that contains one or both of the following 617 objects: 619 - *userinfo* - Claims that will be returned as a JSON object 621 - *id_token* - Claims that will be included in the returned ID 622 Token. If the null value, an ID Token will be returned 623 containing no additional Claims. 625 The contents of the userinfo and id_token objects are Claims as 626 defined in [OIDC] Section 5. 628 * *oidc4ia* - OpenID Connect for Identity Assurance claims request 629 per [OIDC4IA]. 631 * *vc* - [Editor: define how W3C Verifiable Credentials [W3C_VC] can 632 be requested.] 634 3.7. Authorization Types 636 * *oauth_scope* - an OAuth 2.0 authorization request per [RFC6749] 637 section 3.3 639 * *oauth_rich* - a rich authorization request per [RAR] 641 * *oauth_rich_list* - a list of rich authorization requests 643 4. Interaction Response JSON 645 A non-normative example of an Interaction Response follows: 647 { 648 "user": { 649 "discovered": true 650 }, 651 "interaction": { 652 "type" : "popup", 653 "uri" : "https://as.example/endpoint/ey5gs32..." 654 }, 655 "authorization": { 656 "handle" : "eyJhb958.example.authorization.handle.9yf3szM", 657 "uri" : "https://as.example/authorization/ey7snHGs", 658 "wait" : "10" 659 } 660 } 662 4.1. "user" Object 664 MUST contain one of "authorization" object, or "authentication" 665 object. 667 * *discovery* - if the AS Request included a discovery attribute, 668 then the AS MAY return a "user" object with the "discovered" 669 property set to the JSON value true if one or more of the 670 identifiers provided in the AS Request identify a User at the AS, 671 or the JSON value false if not. If the Client received a false 672 return, it may 674 [Editor: reference a security consideration for this functionality.] 676 4.2. "interaction" Object 678 If the AS wants the Client to start the interaction, the AS MUST 679 select one of the interaction mechanisms provided by the Client in 680 the AS Request, and include the matching attribute in the interaction 681 object: 683 * *type* - this MUST match the type provided by the Client in the AS 684 Request client.interaction object. 686 * *uri* - the URI to interact with the User per the type. This may 687 be a temporary short URL if the type is qrcode so that it is easy 688 to scan. 690 * *message* - a text string to display to the User if type is 691 qrcode. 693 [Editor: do we specify a maximum length for the uri and message so 694 that a device knows the maximum it needs to support? A smart device 695 may have limited screen real estate.] 697 4.3. "authorization" Object 699 The authorization object has the following attributes: 701 * *handle* - the authorization handle. This attribute is REQUIRED. 703 * *uri* - the authorization URI. This attribute is REQUIRED. 705 * *wait* - the amount of time in integer seconds the Client MUST 706 wait before making the Authorization Request. This attribute is 707 OPTIONAL. 709 4.4. "authentication" Object 711 Returned if the Client requested authentication first. The 712 authentication object has the following attributes: 714 * *handle* - the authentication handle. This attribute is REQUIRED. 716 * *uri* - the authentication URI. This attribute is REQUIRED. 718 5. Interaction Types 720 If the AS wants the Client to initiate the interaction with the User, 721 then the AS will return an interaction object Section 4.2 so that the 722 Client can can hand off interactions with the User to the AS. The 723 Client will initiate the interaction with the User in one of the 724 following ways: 726 5.1. "popup" Type 728 The Client will create a new popup child browser window containing 729 the value of the uri attribute of the interaction object. [Editor: 730 more details on how to do this] 732 The AS will close the window when the interactions with the User are 733 complete. [Editor: confirm AS can do this still on all browsers, or 734 does Client need to close] 736 The AS MAY respond to an outstanding Authorization Request 737 Section 8.13 before the popup window has been closed. 739 5.2. "redirect" Type 741 The Client will redirect the User to the value of the uri attribute 742 of the interaction object. When the AS interactions with the User 743 are complete, the AS will redirect the User to the redirect_uri the 744 Client provided in the AS Request. 746 If the Client made a Authorization Request when starting the 747 interaction, the AS MAY respond to the Authorization Request 748 Section 8.13 before the User has been redirected back to the Client. 750 5.3. "qrcode" Type 752 The Client will create a [QR_Code] of the uri attribute of the 753 interaction object and display the resulting graphic and the message 754 attribute of the interaction object as a text string. 756 6. AS Response JSON 758 Example non-normative AS Response JSON document for Example 1 in 759 Section 3: 761 { 762 "iat":"15790460234", 763 "nonce":"f6a60810-3d07-41ac-81e7-b958c0dd21e4", 764 "authorizations": { 765 "type" : "oauth_scope", 766 "scope" : "read_contacts", 767 "expires_in" : "3600", 768 "method" : "bearer", 769 "token" : "eyJJ2D6.example.access.token.mZf9p" 770 }, 771 "claims": { 772 "oidc": { 773 "id_token" : "eyJhbUzI1N.example.id.token.YRw5DFdbW", 774 "userinfo" : { 775 "name" : "John Doe", 776 "picture" : "https://photos.example/p/eyJzdkiO" 777 } 778 } 779 } 780 } 782 Example non-normative AS Response JSON document for Example 2 in 783 Section 3: 785 { 786 "iat" :"15790460234", 787 "nonce" :"0d1998d8-fbfa-4879-b942-85a88bff1f3b", 788 "authorizations": { 789 "type" : "oauth_scope", 790 "scope" : "read_calendar write_calendar", 791 "expires_in" : "3600", 792 "method" : "pop", 793 "access": { 794 "handle" : "ey.example.access.handle.9yf3szM", 795 "jwk": { 796 "x5u" : "https://as.example/jwk/VBUEOIQA82" 797 } 798 }, 799 "refresh": { 800 "handle" : "ey.example.refresh.handle.Jl4FzM", 801 "uri" : "https://as.example/refresh/eyj34" 802 } 803 } 804 } 806 Details of the JSON document: 808 6.1. Top Level Attributes 810 *iat* - the time of the response as a NumericDate. 812 *nonce* - the nonce that was included in the AS Request JSON 813 Section 3. 815 6.2. "authorizations" Object 817 There is an authorizations object in the AS Response if there was an 818 authorizations object in the AS Request. 820 * *type* - the type of claim request: "oauth_scope", "oauth_rich", 821 or "oauth_rich_list". See Section 3.7 for details. 823 * *list* - an array of objects if the type was "oauth_rich_list". 824 The objects have the following attributes just as if the type was 825 "oauth_rich" 827 * *scope* - the scopes the Client was granted authorization for. 828 This will be all, or a subset, of what was requested. 830 * *authorization_details* - the authorization details granted. Only 831 returned for "oauth_rich" and "oauth_rich_list". 833 * *method* - the access method: "bearer", "pop", or "jws". See 834 Section 6.4 for details. 836 * *token* - an access token for accessing the resource(s). Included 837 if the access method is "bearer". 839 * *expires_in* - an optional value specifying how many seconds until 840 the access token or handle expire. 842 * *refresh* - an optional object containing parameters required to 843 refresh an access token or handle. See refresh request 844 Section 8.18. 846 - *handle* - an refresh handle used to create the JSON refresh 847 token. 849 - *uri* - the refresh uri the Client will use to refresh. 851 * *access* - an object containing the parameters needed to access 852 resources requiring proof-of-possession. Included if the access 853 method is "pop". 855 - *handle* - the access handle. 857 - *jwk* - the jwk object to use. 859 6.3. "claims" Object 861 There is a claims object in the AS Response if there was a claims 862 object in the AS Request. 864 * *oidc* 866 - *id_token* - an OpenID Connect ID Token containing the Claims 867 the User consented to be released. 869 - *userinfo* - the Claims the User consented to be released. 871 Claims are defined in [OIDC] Section 5. 873 * *oidc4ia* - OpenID Connect for Identity Assurance claims response 874 per [OIDC4IA]. 876 * *vc* 878 The verified claims the user consented to be released. [Editor: 879 details TBD] 881 6.4. Access Methods 883 The are three different methods for the Client to access an RS: 885 * *bearer* - the AS provides a bearer access token that the Client 886 can use to access an RS per Section 8.15. 888 * *pop* - the AS provides an access handle that the Client presents 889 in a proof-of-possession RS access request per Section 8.16. 891 * *pop_body* - the Client signs the JSON payload sent to the RS per 892 Section 8.17. 894 In the AS Response, the AS will return the method the Client MUST use 895 when accessing the RS. 897 7. Discovery 899 The Client obtains the following metadata about the AS prior to 900 initiating a request: 902 *Endpoint* - the endpoint of the AS. 904 *"as"* - the unique string identifier for the AS. 906 *Algorithms* - the asymetric cryptographic algorithms supported by 907 the AS. 909 *Authorizations* - the authorizations the Client may request, if any. 911 *Identity Claims* - the identity claims the Client may request, if 912 any, and what public keys the claims will be signed with. 914 The client may also obtain information about how the AS will sign 915 and/or encrypt the AS Response, as well as any other metadata 916 required for extensions to this protocol, as defined in those 917 extension specifications. 919 8. JOSE Client Authentication 921 The default mechanism for the Client to authenticate to the AS and 922 the RS is signing a JSON document with JWS per [RFC7515]. The 923 resulting tokens always use compact serialization. 925 It is expected that extensions to this protocol that specify a 926 different mechanism for the Client to authenticate, would over ride 927 this section. 929 The Authorization Request JSON is signed with JWS and passed as the 930 body of the POST. 932 The authorization, refresh, and access handles are signed with JWS 933 resulting in authorization request, refresh, and access tokens 934 respectively. These JOSE tokens are passed in the HTTP Authorization 935 header with the "JOSE" parameter per Section 8.6. 937 The Client will use the same private key to create all tokens. 939 The Client and the AS MUST both use HTTP/2 ([RFC7540]) or later, and 940 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 942 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 944 8.1. JOSE Headers 946 A non-normative example of a JOSE header for a Registered Client 947 using a key id to identify the Client's public key: 949 { 950 "alg":"ES256", 951 "typ":"JOSE", 952 "kid":"1" 953 } 955 A non-normative example of a JOSE header for a Registered Client 956 using a certificate to assert the Client's public key: 958 { 959 "alg":"ES256", 960 "typ":"JOSE", 961 "jwk": 962 {"kty":"RSA", 963 "use":"sig", 964 "kid":"1b94c", 965 "n":"vrjOfz9Ccdgx5nQudyhdoR17V-IubWMeOZCwX_jj0hgAsz2J_pqYW08 966 PLbK_PdiVGKPrqzmDIsLI7sA25VEnHU1uCLNwBuUiCO11_-7dYbsr4iJmG0Q 967 u2j8DsVyT1azpJC_NG84Ty5KKthuCaPod7iI7w0LK9orSMhBEwwZDCxTWq4a 968 YWAchc8t-emd9qOvWtVMDC2BXksRngh6X5bUYLy6AyHKvj-nUy1wgzjYQDwH 969 MTplCoLtU-o-8SNnZ1tmRoGE9uJkBLdh5gFENabWnU5m1ZqZPdwS-qo-meMv 970 VfJb6jJVWRpl2SUtCnYG2C32qvbWbjZ_jBPD5eunqsIo1vQ", 971 "e":"AQAB", 972 "x5c": 973 ["MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBBQUAMGIxCzAJB 974 gNVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYD 975 VQQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1 976 wYmVsbDAeFw0xMzAyMjEyMzI5MTVaFw0xODA4MTQyMjI5MTVaMGIxCzAJBg 977 NVBAYTAlVTMQswCQYDVQQIEwJDTzEPMA0GA1UEBxMGRGVudmVyMRwwGgYDV 978 QQKExNQaW5nIElkZW50aXR5IENvcnAuMRcwFQYDVQQDEw5CcmlhbiBDYW1w 979 YmVsbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAL64zn8/QnH 980 YMeZ0LncoXaEde1fiLm1jHjmQsF/449IYALM9if6amFtPDy2yvz3YlRij66 981 s5gyLCyO7ANuVRJx1NbgizcAblIgjtdf/u3WG7K+IiZhtELto/A7Fck9Ws6 982 SQvzRvOE8uSirYbgmj6He4iO8NCyvaK0jIQRMMGQwsU1quGmFgHIXPLfnpn 983 fajr1rVTAwtgV5LEZ4Iel+W1GC8ugMhyr4/p1MtcIM42EA8BzE6ZQqC7VPq 984 PvEjZ2dbZkaBhPbiZAS3YeYBRDWm1p1OZtWamT3cEvqqPpnjL1XyW+oyVVk 985 aZdklLQp2Btgt9qr21m42f4wTw+Xrp6rCKNb0CAwEAATANBgkqhkiG9w0BA 986 QUFAAOCAQEAh8zGlfSlcI0o3rYDPBB07aXNswb4ECNIKG0CETTUxmXl9KUL 987 +9gGlqCz5iWLOgWsnrcKcY0vXPG9J1r9AqBNTqNgHq2G03X09266X5CpOe1 988 zFo+Owb1zxtp3PehFdfQJ610CDLEaS9V9Rqp17hCyybEpOGVwe8fnk+fbEL 989 2Bo3UPGrpsHzUoaGpDftmWssZkhpBJKVMJyf/RuP2SmmaIzmnw9JiSlYhzo 990 4tpzd5rFXhjRbg4zW9C+2qok+2+qDM1iJ684gPHMIY8aLWrdgQTxkumGmTq 991 gawR+N5MDtdPTEQ0XfIBc2cJEUyMTY5MPvACWpkA6SdS4xSvdXK3IVfOWA=="] 992 } 993 } 995 [Editor: the jwk above was copy and pasted from the JWK example. 996 Replace? ] 998 The certificate could be signed by the AS, allowing the AS to verify 999 the signature using the AS public key, or the certificate could be 1000 signed by a private key the AS has bound to the Registered Client, 1001 allowing each instance of the Registered Client to have its own 1002 asymetric key pair. 1004 A non-normative example of a JOSE header for a Dynamic Client 1005 including the public key generated by the Client that matches its its 1006 private key: 1008 { 1009 "alg":"ES256", 1010 "typ":"JOSE", 1011 "jwk":{ 1012 "kty":"EC", 1013 "crv":"P-256", 1014 "x":"Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 1015 "y":"GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 1016 } 1017 } 1019 A non-normative example of a JOSE header for a JOSE access token for 1020 a Client accessing an RS that requires proof-of-possession: 1022 { 1023 "alg":"ES256", 1024 "typ":"JOSE", 1025 "jwk":{ 1026 "x5u":"https://as.example/jwk/VBUEOIQA82" 1027 } 1028 } 1030 The "jwk" object in a JOSE access token Section 8.5 MUST be the AS 1031 jwk object the AS provided with the access handle. 1033 This decouples how the AS communicates the Client's public key to the 1034 RS from how the AS asserts the Client's public key. The RS can have 1035 a consistent mechanism assert the Client's public key across all 1036 Clients. 1038 One advantage of this is the AS can create a certificate of a Dynamic 1039 Client's public key, and pass it by value or reference to the Client 1040 to present to the RS. 1042 All JOSE headers MUST have: + the "alg" attribute. + the "typ" 1043 attribute set to "jose". + either a "kid" or "jwk" attribute. 1045 [Editor: should we use indicate the type of token (authorization, 1046 refresh, access) using "typ" or "cty"?] 1048 8.2. Authentication Request Token 1050 A non-normative example of a payload follows: 1052 { 1053 "as" :"https://as.example", 1054 "type" :"authentication", 1055 "iat" :"1579046092", 1056 "jti" :"f6d72254-4f23-417f-b55e-14ad323b1dc1", 1057 "handle":"eyJhb958.example.authentication.handle.9yf3szM" 1058 } 1060 The payload of the authentication token contains: 1062 *as* - the unique string identifier for the AS. 1064 *type* - the string "authentication", indicating the type of token. 1066 *iat* - the time the authentication token was created as a 1067 NumericDate. 1069 *jti* - a unique identifier for the authentication token per 1070 [RFC7519] section 4.1.7. 1072 *handle* the authentication handle the AS provided the Client in the 1073 Interaction Response Section 4. 1075 8.3. Authorization Request Token 1077 A non-normative example of a payload follows: 1079 { 1080 "as" :"https://as.example", 1081 "type" :"authorization", 1082 "iat" :"1579046092", 1083 "jti" :"f6d72254-4f23-417f-b55e-14ad323b1dc1", 1084 "handle":"eyJhb958.example.authorization.handle.9yf3szM" 1085 } 1087 The payload of the authorization token contains: 1089 *as* - the unique string identifier for the AS. 1091 *type* - the string "authorization", indicating the type of token. 1093 *iat* - the time the authorization token was created as a 1094 NumericDate. 1096 *jti* - a unique identifier for the authorization token per [RFC7519] 1097 section 4.1.7. 1099 *handle* the authorization handle the AS provided the Client in the 1100 Interaction Response Section 4. 1102 8.4. Refresh Token 1104 A non-normative example of a payload follows: 1106 { 1107 "as" :"https://as.example", 1108 "type" :"refresh", 1109 "iat" :"1579049876", 1110 "jti" :"4342046d-83c4-4725-8c72-e9a49245f791", 1111 "handle":"eyJhb958.example.refresh.handle.9yf3szM" 1112 } 1114 The payload of the authorization token contains: 1116 *as* - the unique string identifier for the AS. 1118 *type* - the string "refresh", indicating the type of token. 1120 *iat* - the time the refresh request token was created as a 1121 NumericDate. 1123 *jti* - a unique identifier for the refresh request token. 1125 *handle* the refresh handle the AS provided the Client in the AS 1126 Response Section 6 or access refresh response Section 8.18. 1128 8.5. JOSE Access Token 1130 The "jwk" object in a JOSE access token header MUST be set to the 1131 "jwk" value the AS provided for the access handle. 1133 A non-normative example of a payload follows: 1135 { 1136 "type" :"access", 1137 "iat" :"1579046092", 1138 "jti" :"5ef47057-08f9-4763-be8d-162824d43dfb", 1139 "handle":"eyJhb958.example.access.handle.9yf3szM" 1140 } 1142 The payload of the JOSE access token contains: 1144 *type* - the string "access", indicating the type of token. 1146 *iat* - the time the JOSE access token was created as a NumericDate. 1148 *jti* - a unique identifier for the JOSE access token. 1150 *handle* the access handle the AS provided the Client in the AS 1151 Response Section 6 or access refresh response Section 8.18. 1153 [Editor: should we include the called URI in the token?] 1155 8.6. HTTP Authorization JOSE Header 1157 The Client authenticates requests by setting the HTTP Authorization 1158 header to include the "JOSE" parameter, followed by one or more space 1159 characters, followed by the appropriate JOSE token. 1161 A non-normative example: 1163 Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW 1165 The authorization request token, refresh request token, and the JOSE 1166 access token are all passed in this manner. 1168 8.7. JOSE Token Verification 1170 TBD 1172 8.8. AS Request 1174 The Client creates a JSON document per Section 3, signs it using JWS 1175 [RFC7515], and sends the JWS token to the AS end point using HTTP 1176 POST, with a content-type of application/jose. 1178 * *Payload Encryption* 1180 The AS may require the AS Request to be encrypted. If so, the JWS 1181 token is encrypted per JWE [RFC7516] using the public key and 1182 algorithm specified by the AS. 1184 8.9. Interaction Response 1186 If the Client set the authenticate_first flag, the response includes 1187 an authentication object, otherwise it includes an authorization 1188 object. If the AS wants the Client to initiate the User interaction, 1189 it sends an interaction object. 1191 If no interaction is required the AS will return an AS Response per 1192 Section 8.14, otherwise the AS will return an Interaction Response 1193 per Section 4. 1195 If the AS wants the Client to start the interaction, an interaction 1196 object will be returned in the response. 1198 * *Error Responses* 1200 The AS MAY respond with one of the following errors defined in 1201 Section 9: 1203 TBD 1205 8.10. Deletion Request 1207 The Client MAY delete an outstanding request using the authorization 1208 token by making an HTTP DELETE call to the authorization uri, setting 1209 the HTTP Authorization header per Section 8.6 with the authorization 1210 request token. 1212 A non-normative deletion request example: 1214 DELETE /authorization/ey7snHGs HTTP/2 1215 Host: as.example 1216 Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW 1218 * *Error Responses* 1220 The AS MAY respond with one of the following errors defined in 1221 Section 9: 1223 TBD 1225 8.11. Authentication Request 1227 Section 8.2 1229 8.12. Authentication Response 1231 8.13. Authorization Request 1233 The Client makes an HTTP GET call to the authorization uri, setting 1234 the HTTP Authorization header per Section 8.6 with the authorization 1235 request token. 1237 A non-normative Authorization Request example: 1239 GET /authorization/ey7snHGs HTTP/2 1240 Host: as.example 1241 Authorization: JOSE eyJhb.example.authorization.token.haDwskpFDBW 1243 8.14. AS Response 1245 The AS verifies the authorization request token, and then provides a 1246 response according to what the User and/or RO have authorized if 1247 required. If no signature or encryption was required, the AS will 1248 respond with a JSON document with content-type set to application/ 1249 json. 1251 * *Response Signing* 1253 The AS MAY sign the response with a JWS per [RFC7515] and the private 1254 key matching the public key the AS defined as its AS Response signing 1255 key. The AS will respond with the content-type set to application/ 1256 jose. 1258 * *Response Encryption* 1260 The AS MAY encrypt the response using the public key provided by the 1261 Client, using JWE per [RFC7516]. The AS will respond with the 1262 content-type set to application/jose. 1264 * *Error Responses* 1266 The AS MAY respond with one of the following errors defined in 1267 Section 9: 1269 TBD 1271 8.15. Bearer Token RS Access 1273 If the access method in the AS Response authorizations object 1274 Section 6.2 was "bearer", then the Client accesses the RS per 1275 Section 2.1 of [RFC6750] 1277 A non-normative example of the HTTP request headers follows: 1279 GET /calendar HTTP/2 1280 Host: calendar.example 1281 Authorization: bearer eyJJ2D6.example.access.token.mZf9pTSpA 1283 * *Error Responses* 1285 TBD 1287 8.16. Proof-of-possession RS Access 1289 If the access method in the AS Response authorizations object 1290 Section 6.2 was "pop", then the Client creates a JOSE access token 1291 per Section 8.5 for each call to the RS, setting the HTTP 1292 Authorization header per Section 8.6 with the JOSE access token. 1294 A non-normative example of the HTTP request headers follows: 1296 GET /calendar HTTP/2 1297 Host: calendar.example 1298 Authorization: JOSE eyJhbG.example.JOSE.access.token.kwwQb958 1300 * *Error Responses* 1302 TBD 1304 8.17. JOSE Body RS Access 1306 If the access method in the AS Response authorizations object 1307 Section 6.2 was "pop_body", then the Client creates a JOSE access 1308 token per Section 8.5 for each call to the RS, setting the HTTP 1309 Authorization header per Section 8.6 with the JOSE access token. 1311 The Client creates a JSON document per the RS requirements. The 1312 document MUST include the access handle. The CLient then signs the 1313 document using JWS [RFC7515], and sends the resulting compact 1314 notation JWS token to the RS end point using HTTP POST, with a 1315 content-type of application/jose. Note this is similar to the AS 1316 Request Section 8.8. 1318 [Editor: any isues here? Anything missing that MUST be in the 1319 payload? Would an HTTP Authorization header make sense?] 1321 8.18. Access Refresh 1323 If the Client received a refresh handle and uri from the AS in the 1324 Interaction Response, and it wants a fresh access token or handle, it 1325 creates a refresh request token per Section 8.4. setting the HTTP 1326 Authorization header per Section 8.6 with the refresh request token. 1327 The AS will then respond with a refresh response. 1329 * *Refresh Response* 1331 A non-normative example refresh response with an access handle: 1333 { 1334 "type" : "oauth_scope", 1335 "scope" : "read_calendar write_calendar", 1336 "expires_in" : "3600", 1337 "method" : "pop", 1338 "access": { 1339 "handle" : "ey.example.access.handle.9yf3iWszM", 1340 "jwk": { 1341 "x5u" : "https://as.example/jwk/VBUEOIQA82" 1342 } 1343 }, 1344 "refresh": { 1345 "handle" : "ey.example.refresh.handle.4SkjIi", 1346 "uri" : "https://as.example/refresh/eyJl4FzM" 1347 } 1348 } 1350 The refresh response is the same as the authorizations object 1351 Section 6.2 in the AS Response. 1353 If a new refresh handle and/or refresh uri is returned, the Client 1354 MUST use the new refresh handle and/or refresh uri 1356 [Editor: are there other results relevant for [RAR]?] 1358 * *Error Responses* 1360 The AS MAY respond with one of the following errors defined in 1361 Section 9: 1363 TBD 1365 9. Error Messages 1367 [Editor: return "wait" time in AS Response when AS wants Client to 1368 wait before retying a Authorization Request. The Client MUST 1369 generate a fresh authorization token when retrying the Authorization 1370 Request. ] 1372 TBD 1374 10. AS Initiated Sequence 1376 [Editor: AS initiated flows have been challenging to implement as 1377 OAuth 2.0 did not directly support them, so deployments bounced back 1378 and forth between the Client and AS to create a Client initiated 1379 flow. Here is a proposal to support AS initiated: authentication; 1380 just-in-time (JIT) provisioning; and authorization] 1381 In this sequence the User starts at the AS, and then based on User 1382 input, the AS redirects the User to a Client, passing an initiation 1383 token Section 10.1, and then the Client retrieves authorizations and/ 1384 or identity claims about the User. The Client MUST be a Registered 1385 Client. The sequence follows: 1387 1. The User is interacting at the AS and wants to use the Client, 1388 and provide the Client identity claims and/or authorizations from 1389 the AS that the Client has pre-configured. 1391 2. The AS creates a authorization handle and uri representing the 1392 identity claims and authorizations to be provided to the Client. 1393 The AS creates an initiation token containing the AS identifier, 1394 the authorization handle, and the authorization uri. 1396 3. The AS redirects the User to a URI the Client has configured to 1397 accept initiation tokens, passing the initiation token as a query 1398 parameters with the name "token". 1400 4. The Client verifies the initiation token. 1402 5. The Client makes an Authorization Request per Section 8.13. 1404 6. The AS responds with an AS Response JSON document Section 6 per 1405 Section 8.14. 1407 The Client now has the User identity claims and/or authorizations. 1408 If Client policy permits, the Client can perform JIT provisioning if 1409 the User is new to the Client. 1411 *AS Initiated Sequence Diagram* 1413 +--------+ +-------------+ +---------------+ 1414 | | | | | | 1415 | | | User |-------(1)-->| | 1416 | | | | | | 1417 | | +-------------+ | (2) | 1418 | | /\ | | 1419 | Client |<--- initiation ---/ \-------------(3)---| Authorization | 1420 | | token | Server | 1421 | (4) | | | 1422 | | | | 1423 | |--(5)------- Authorization Request ------>| | 1424 | | | | 1425 | |<-(6)------- AS Response -----------------| | 1426 | | | | 1427 +--------+ +---------------+ 1429 10.1. Initiation Token 1431 A non-normative example of an initiation token payload follows: 1433 { 1434 "as": "https://as.example", 1435 "authorization": { 1436 "handle" : "eyJhb958.example.authorization.handle.9yf3szM", 1437 "uri" : "https://as.example/authorization/ey7snHGs" 1438 } 1439 } 1441 * *as* - the "as" identifier for the AS. This attribute is 1442 REQUIRED. 1444 * *authorization* - the authorization object has the following 1445 attributes: 1447 - *handle* - the authorization handle. This attribute is 1448 REQUIRED. 1450 - *uri* - the authorization URI. This attribute is REQUIRED. 1452 The initiation token is signed with JWS and uses the compact 1453 serialization. 1455 11. Extensibility 1457 This standard can be extended in a number of areas: 1459 * *Client Authentication Mechanisms* 1461 An extension could define other mechanisms for the Client to 1462 authenticate and replace JOSE in Section 8 with Mutual TLS or HTTP 1463 Signing. Constrained environments could use CBOR [RFC7049] instead 1464 of JSON, and COSE [RFC8152] instead of JOSE, and CoAP [RFC8323] 1465 instead of HTTP/2. 1467 * *AS Request* 1469 An additional top level object could be added to the AS Request 1470 payload if the AS can manage delegations other than authorizations or 1471 claims, or some other functionality. 1473 * *"client" Object* 1475 Additional information about the Client that the AS would require 1476 related to an extension. 1478 * *"user" Object* 1480 Additional information about the Client that the AS would require 1481 related to an extension. 1483 * *"authorizations" Object* 1485 Additional types of authorizations in addition to OAuth 2.0 scopes 1486 and RAR. 1488 * *"claims" Object* 1490 Additional types of identity claims in addition to OpenID Connect 1491 claims and Verified Credentials. 1493 * *Interaction* 1495 Additional mechanisms for the Client to start an interaction with the 1496 User. 1498 * *Access Methods* 1500 Additional mechanisms for the Client to present authorization to a 1501 resource. 1503 * *Continuous Authentication* 1505 An extension could define a new handle for the Client to use to 1506 regularly provide continuous authentication signals and receive 1507 responses. 1509 [Editor: do we specify access token / handle introspection in this 1510 document, or leave that to an extension?] 1512 [Editor: do we specify access token / handle revocation in this 1513 document, or leave that to an extension?] 1515 12. Rational 1517 1. *Why is there only one mechanism for the Client to authenticate 1518 with the AS? Why not support other mechanisms?* 1520 Having choices requires implementers to understand which choice 1521 is preferable for them. Having one default mechanism in the 1522 document for the Client to authenticate simplifies most 1523 implementations. Extensions can specify other mechanisms that 1524 are preferable in specific environments. 1526 2. *Why is the default Client authentication JOSE rather than 1527 MTLS?* 1529 MTLS cannot be used today by a Dynamic Client. MTLS requires 1530 the application to have access below what is typically the 1531 application layer, that is often not available on some 1532 platforms. JOSE is done at the application layer. Many AS 1533 deployments will be an application behind a proxy performing 1534 TLS, and there are risks in the proxy passing on the results of 1535 MTLS. 1537 3. *Why is the default Client authentication JOSE rather than HTTP 1538 signing?* 1540 There is currently no widely deployed open standard for HTTP 1541 signing. Additionally, HTTP signing requires passing all the 1542 relevant parts of the HTTP request to downstream services within 1543 an AS that may need to independently verify the Client identity. 1545 4. *What are the advantages of using JOSE for the Client to 1546 authenticate to the AS and a resource?* 1548 Both Registered Clients and Dynamic Clients can have a private 1549 key, eliminating the public Client issues in OAuth 2.0, as a 1550 Dynamic Client can create an ephemeral key pair. Using 1551 asymetric cryptography also allows each instance of a Registered 1552 Client to have its own private key if it can obtain a 1553 certificate binding its public key to the public key the AS has 1554 for the Client. Signed tokens can be passed to downstream 1555 components in a AS or RS to enable independent verification of 1556 the Client and its request. The AS Initiated Sequence 1557 Section 10 requires a URL safe parameter, and JOSE is URL safe. 1559 5. *Why does the AS not return parameters to the Client in the 1560 redirect url?* 1562 Passing parameters via a browser redirection is the source of 1563 many of the security risks in OAuth 2.0. It also presents a 1564 challenge for smart devices. In this protocol, the redirection 1565 from the Client to the AS is to enable the AS to interact with 1566 the User, and the redirection back to the Client is to hand back 1567 interaction control to the Client if the redirection was a full 1568 browser redirect. Unlike OAuth 2.0, the identity of the Client 1569 is independent of the URI the AS redirects to. 1571 6. *Why is there not a UserInfo endpoint as there is with OpenID 1572 Connect?* 1573 In OpenID Connect, obtaining claims over the redirect or the 1574 Token Endpoint are problematic. The redirect is limited in 1575 size, and is not secure. The Token Endpoint is intended to 1576 return tokens, and is limited by the "application/x-www-form- 1577 urlencoded" format. A UserInfo endpoint returns "application/ 1578 json", and can return rich claims, just as the authorization uri 1579 in this protocol. 1581 [Editor: is there some other reason to have the UserInfo 1582 endpoint? What are industry best practices now? ] 1584 7. *Why is there still a Client ID? Could we not use a fingerprint 1585 of the public key to identify the Client?* 1587 Some AS deployments do not allow calls from Registered Clients, 1588 and provide different functionality to different Clients. A 1589 permanent identifier for the Client is needed for the Client 1590 developer and the AS admin to ensure they are referring to the 1591 same Client. The Client ID was used in OAuth 2.0, and it served 1592 the same purpose. 1594 8. *Why have both claims and authorizations?* 1596 There are use cases for each that are independent: 1597 authenticating a user vs granting access to a resource. A 1598 request for an authorization returns an access token or handle, 1599 while a request for a claim returns the claim. 1601 9. *Why specify HTTP/2 or later and TLS 1.3 or later for Client and 1602 AS communication in ?*Section 8 1604 Knowing the AS supports HTTP/2 enables a Client to set up a 1605 connection faster. HTTP/2 will be more efficient when Clients 1606 have large numbers of access tokens and are frequently 1607 refreshing them at the AS as there will be less network traffic. 1608 Mandating TLS 1.3 similarly improves the performance and 1609 security of Clients and AS when setting up a TLS connection. 1611 10. *Why do some of the JSON objects only have one child, such as 1612 the identifiers object in the user object in the AS Request?* 1614 It is difficult to forecast future use cases. Having more 1615 resolution may mean the difference between a simple extension, 1616 and a convoluted extension. 1618 11. *Why is the "iss" included in the "oidc" identifier object? 1619 Would the "sub" not be enough for the AS to identify the User?* 1620 The AS may use another AS to authenticate Users. The "iss" and 1621 "sub" combination is required to uniquely identify the User for 1622 any AS. 1624 12. *Why complicate the sequence with authentication first?* 1626 A common pattern is to use an AS to authenticate the User at the 1627 Client. The Client does not know a priori if the User is a new 1628 User, or a returning User. Asking a returning User to consent 1629 releasing identity claims and/or authorizations they have 1630 already provided is a poor User experience, as is sending the 1631 User back to the AS. The Client requesting identity first 1632 enables the Client to get a response from the AS while the AS is 1633 still interacting with the User, so that the Client can request 1634 any identity claims/or authorizations required or desired. 1636 13. *Why is there a JOSE Body access method for the 1637 Client?*Section 8.17 1639 There are numerous use cases where the RS wants non-repudiation 1640 and providence of API calls. For example, the UAS Service 1641 Supplier Framework for Authentication and Authorization [UTM]. 1643 13. Acknowledgments 1645 This draft derives many of its concepts from Justin Richer's 1646 Transactional Authorization draft [TxAuth]. 1648 Additional thanks to Justin Richer for his strong critique of earlier 1649 drafts. 1651 14. IANA Considerations 1653 [ JOSE parameter for Authorization HTTP header ] 1655 TBD 1657 15. Security Considerations 1659 TBD 1661 16. References 1663 16.1. Normative References 1665 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 1666 RFC 3966, DOI 10.17487/RFC3966, December 2004, 1667 . 1669 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1670 DOI 10.17487/RFC5322, October 2008, 1671 . 1673 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 1674 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 1675 September 2009, . 1677 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1678 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1679 . 1681 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1682 Framework: Bearer Token Usage", RFC 6750, 1683 DOI 10.17487/RFC6750, October 2012, 1684 . 1686 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1687 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 1688 2015, . 1690 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1691 RFC 7516, DOI 10.17487/RFC7516, May 2015, 1692 . 1694 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1695 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1696 . 1698 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1699 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1700 DOI 10.17487/RFC7540, May 2015, 1701 . 1703 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1704 Interchange Format", STD 90, RFC 8259, 1705 DOI 10.17487/RFC8259, December 2017, 1706 . 1708 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1709 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1710 . 1712 [OIDC] Sakimora, N., Bradley, J., Jones, M., de Medeiros, B., and 1713 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 1714 . 1716 [OIDC4IA] Lodderstedt, T. and D. Fett, "OpenID Connect for Identity 1717 Assurance 1.0", October 2019, . 1720 16.2. Informative References 1722 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1723 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1724 October 2013, . 1726 [RFC8252] Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", 1727 BCP 212, RFC 8252, DOI 10.17487/RFC8252, October 2017, 1728 . 1730 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1731 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1732 . 1734 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1735 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 1736 Application Protocol) over TCP, TLS, and WebSockets", 1737 RFC 8323, DOI 10.17487/RFC8323, February 2018, 1738 . 1740 [RFC8628] Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, 1741 "OAuth 2.0 Device Authorization Grant", RFC 8628, 1742 DOI 10.17487/RFC8628, August 2019, 1743 . 1745 [browser_based_apps] 1746 Parecki, A. and D. Waite, "OAuth 2.0 for Browser-Based 1747 Apps", September 2019, . 1750 [RAR] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 1751 Rich Authorization Requests", January 2020, 1752 . 1754 [W3C_VC] Sporny, M., Noble, G., and D. Chadwick, "Verifiable 1755 Credentials Data Model 1.0", November 2019, 1756 . 1758 [QR_Code] "ISO/IEC 18004:2015 - Information technology - Automatic 1759 identification and data capture techniques - QR Code bar 1760 code symbology specification", February 2015, 1761 . 1763 [TxAuth] Richer, J., "Transactional Authorization", December 2019, 1764 . 1767 [UTM] Rios, J., Smith, I., and P. Venkatesen, "UAS Service 1768 Supplier Framework for Authentication and Authorization", 1769 September 2019, . 1772 Appendix A. Document History 1774 A.1. draft-hardt-xauth-protocol-00 1776 * Initial version 1778 A.2. draft-hardt-xauth-protocol-01 1780 * text clean up 1782 * added OIDC4IA claims 1784 * added "jws" method for accessing a resource. 1786 * renamed Initiation Request -> AS Request 1788 * renamed Initiation Response -> Interaction Response 1790 * renamed Completion Request -> Authorization Request 1792 * renamed Completion Response -> AS Request 1794 * renamed completion handle -> authorization handle 1796 * added Authentication Request, Authentication Response, 1797 authentication handle 1799 Appendix B. Comparison with OAuth 2.0 and OpenID Connect 1801 *Changed Features* 1803 The major differences between this protocol and OAuth 2.0 and OpenID 1804 Connect are: 1806 * The Client uses a private key to authenticate in this protocol 1807 instead of the client secret in OAuth 2.0 and OpenID Connect. 1809 * The Client initiates the protocol by making a signed request 1810 directly to the AS instead of redirecting the User to the AS. 1812 * The Client does not receive any parameters from a redirection of 1813 the User back from the AS. 1815 * Refreshing an access token requires creating a refresh token from 1816 a refresh handle, rather than an authenticated call with a refresh 1817 token. 1819 * The Client can request identity claims to be returned independent 1820 of the ID Token. There is no UserInfo endpoint to query claims as 1821 there is in OpenID Connect. 1823 *Preserved Features* 1825 * This protocol reuses the OAuth 2.0 scopes, Client IDs, and access 1826 tokens of OAuth 2.0. 1828 * This protocol reuses the Client IDs, Claims and ID Token of OpenID 1829 Connect. 1831 * No change is required by the Client or the RS for existing APIs. 1833 Author's Address 1835 Dick Hardt (editor) 1836 SignIn.Org 1837 United States 1839 Email: dick.hardt@gmail.com