idnits 2.17.1 draft-thornburgh-fwk-dc-token-iss-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 May 2020) is 1430 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission M. Thornburgh 3 Internet-Draft Adobe 4 Intended status: Experimental 19 May 2020 5 Expires: 20 November 2020 7 A Framework For Decentralized Bearer Token Issuance in HTTP 8 draft-thornburgh-fwk-dc-token-iss-00 10 Abstract 12 This memo describes a protocol framework for HTTP clients to obtain 13 bearer tokens for accessing restricted resources, where in some 14 applications the client may not have prior knowledge of, or a direct 15 relationship with, the resource server's authorization infrastructure 16 (such as in decentralized identity systems). Semi-concrete 17 applications of the framework using proof-of-possession and TLS 18 client certificate mechanisms are also described. 20 Author's Note 22 This work is an independent contribution and is not associated with, 23 or endorsed by, Adobe. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 20 November 2020. 42 Copyright Notice 44 Copyright (c) 2020 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . 4 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 59 2. General Framework . . . . . . . . . . . . . . . . . . . . . . 5 60 2.1. Nonce Considerations . . . . . . . . . . . . . . . . . . 6 61 2.2. Common Token Response . . . . . . . . . . . . . . . . . . 7 62 2.3. Common Mechanism Flow . . . . . . . . . . . . . . . . . . 7 63 3. Proof-of-Possession Mechanism . . . . . . . . . . . . . . . . 8 64 3.1. Proof Token . . . . . . . . . . . . . . . . . . . . . . . 8 65 3.2. Proof-of-Possession API . . . . . . . . . . . . . . . . . 9 66 3.3. Proof-of-Possession Example . . . . . . . . . . . . . . . 10 67 4. TLS Client Certificate Mechanism . . . . . . . . . . . . . . 13 68 4.1. Client Certificate API . . . . . . . . . . . . . . . . . 13 69 4.2. Client Certificate Example . . . . . . . . . . . . . . . 14 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 72 7. Normative References . . . . . . . . . . . . . . . . . . . . 17 73 8. Informative References . . . . . . . . . . . . . . . . . . . 17 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 76 1. Introduction 78 This memo describes a general protocol framework for HTTP clients to 79 obtain bearer tokens (Section 1.2 of [RFC6750]) from a resource 80 server's authorization service in order to access protected resources 81 on the server. This framework is especially intended for systems 82 (such as decentralized identity systems like [WebID], and 83 decentralized social or mashup data systems like the Solid project 84 (https://solidproject.org)) where the client might not have prior 85 knowledge of, or a preexisting direct relationship with, the 86 authorization service for the resource server; however, it can be 87 applied in other use cases as well. 89 The protocol includes a method for the client to discover the 90 nature(s) of principals (such as identities, capabilities, sender- 91 constrained access tokens, or verifiable credentials) that the server 92 expects to interact with, and methods for the client to discover the 93 API endpoint URIs for multiple potential mechanisms for obtaining 94 bearer tokens. The framework is constructed to mitigate man-in-the- 95 middle token-stealing attacks. 97 This memo defines two mechanisms within the framework for a client to 98 obtain a bearer token: one using a cryptographic proof-of-possession, 99 and one using TLS [RFC8446] client certificates. These mechanisms 100 retain generality, and must be further refined in other 101 specifications according to the application and the nature of the 102 principals expected by the servers. Other mechanisms within the 103 framework are also possible. 105 1.1. Motivation 107 This work was originally motivated by a desire to address security, 108 semantic, and operational shortcomings in an experimental, 109 decentralized, application-layer authentication scheme for the Solid 110 project (https://solidproject.org) that was based on [WebID], OpenID 111 Connect [OpenID.Core], and proof-of-possession key semantics 112 [RFC7800]. 114 An explicit goal of the solution is to leverage the benefits of 115 bearer tokens for accessing restricted resources: 117 * The token can encapsulate (by direct encoding or by reference) 118 exactly and only the implementation-specific and deployment- 119 specific properties needed to make access control decisions in the 120 resource server; 122 * The effort (including computational, cryptographic, and network) 123 required to establish a client's identity and authorizations can 124 be done once by the client and the authorization service, compiled 125 to a token, and this effort amortized over many requests to the 126 same resource server, with simple revalidation and lifetime 127 semantics that can be influenced by both parties; specifically: 129 - The server's authorization system chooses an expiration period 130 for the token, and can also revoke it at any time, to cause a 131 reauthentication and revalidation; 133 - The client can forget the token at any time and acquire a new 134 one to cause a reauthentication and revalidation; this can be 135 particularly advantageous if the client acquires new 136 privileges, authorizations, or endorsements that might 137 otherwise be subject to unknown caching policies in an access 138 controller; 140 * The representation of the token can be optimized for network 141 transmission and for decoding, verification, and processing 142 according to the server's implementation; 144 * HTTP header compression schemes such as HPACK [RFC7541] can reduce 145 network resource consumption when a token is reused for multiple 146 requests in the same origin. 148 As work progressed, a general form emerged that could address 149 multiple use cases beyond the original motivator. 151 1.1.1. Use Cases 153 It is envisioned that the framework described in this memo can be 154 used in at least the following cases, with appropriate further 155 specification, to realize the benefits listed above: 157 * Decentralized identity systems such as WebID and Decentralized 158 Identifiers [DID]; 160 * Centralized or decentralized authorization systems based on 161 Verifiable Credentials [VC]; 163 * Authenticated access to a multitude of decentralized, 164 uncoordinated resource servers, such as for social or mashup data 165 applications; 167 * Identity systems based on aspects of a TLS client certificate, 168 without requiring use of that certificate for all accesses to a 169 resource server (particularly in browser-based applications, to 170 allow selective unauthenticated access to non-protected resources 171 within the limitations of negotiating client certificates in TLS); 173 * Obtaining an audience-constrained bearer token given a sender- 174 constrained access credential or capability issued by a central 175 authority; 177 * Obtaining an audience-constrained bearer token in a centralized, 178 federated, or confederated identity system given an identity bound 179 with a pre-shared public key. 181 This list of use cases should not be construed as exhaustive or 182 limiting. Other effective applications of this framework are 183 possible. 185 1.2. Terminology 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 189 "OPTIONAL" in this document are to be interpreted as described in BCP 190 14 [RFC2119] [RFC8174] when, and only when, they appear in all 191 capitals, as shown here. 193 The term "bearer token" in this document has the meaning described in 194 [RFC6750]. 196 The term "protection space" in this document has the meaning 197 described in Section 2.2 of [RFC7235]. 199 2. General Framework 201 The server challenges an unauthenticated client (Section 2.1 of 202 [RFC7235]) with an HTTP "401" response, including a "WWW- 203 Authenticate" response header with the "Bearer" _auth-scheme_ 204 (Section 3 of [RFC6750]), and comprising parameters including how to 205 use one or more token acquisition mechanisms. The client examines 206 the challenge and determines which mechanisms, if any, it is able to 207 use to acquire a bearer token. If possible, the client uses a 208 compatible mechanism, including attributes of the original request 209 and the challenge, to request a bearer token. The token will have a 210 stated lifetime and will be valid for accesses within the same 211 protection space as the original request, until the token expires or 212 is revoked. 214 A "WWW-Authenticate" challenge for any mechanism includes at least 215 these _auth-params_: 217 "scope" REQUIRED: A space-delimited list of case-sensitive strings, 218 each a well-known or server-defined value indicating the nature(s) 219 of the principal expected to be used when requesting a bearer 220 token. To avoid ambiguity, server-defined scopes SHOULD be URIs. 222 "nonce" REQUIRED: An opaque (to the client) string to be included 223 unmodified when requesting a bearer token. See Section 2.1 for 224 considerations on constructing the challenge nonce. 226 "error" If present, a reason code indicating that the request had a 227 problem other than not presenting an access token. The following 228 reason codes are initially defined: 230 "invalid_token" A bearer token was presented, but it was expired, 231 revoked, or otherwise not recognized as valid. 233 "proof_required" An access token requiring proof-of-possession of 234 a key (but potentially otherwise valid) was presented. 236 Additionally, one or more mechanism-specific _auth-params_ are 237 included in the challenge to indicate the availability of that 238 mechanism and its unique parameters (usually the URI at which to use 239 the mechanism). This memo defines two mechanism-specific _auth- 240 params_: 242 "token_pop_endpoint" If present, the Proof-of-Possession mechanism 243 (Section 3) is available. The parameter value is the URI at which 244 to exchange a proof-of-possession for a bearer token. 246 "client_cert_endpoint" If present, the TLS Client Certificate 247 mechanism (Section 4) is available. The parameter value is the 248 URI at which to request a bearer token. 250 The challenge can include other _auth-params_ (such as "realm"), 251 including ones for other mechanisms. Unrecognized _auth-params_ 252 SHOULD be ignored. 254 If a request is made for a resource within a protection space and 255 that request includes an "Authorization" header with an invalid 256 "Bearer" token, the resource server SHOULD reply with an HTTP "401" 257 response and "WWW-Authenticate" header as above, even if processing 258 the request doesn't otherwise require authorization. This is to 259 allow a client to obtain a fresh bearer token proactively (for 260 example, before the current token expires, to avoid delaying a real 261 request by the user). 263 2.1. Nonce Considerations 265 The nonce in the "WWW-Authenticate" challenge SHOULD have the 266 following properties: 268 * Be cryptographically strong and unguessable; 270 * Be recognizable when returned in a token request as having been 271 issued for this protection space (for example, by recording the 272 nonce in a database, or including a cryptographic signature); 274 * Be valid for a limited (short) time; 276 * Be redeemable at most once; 277 * Be coupled to the original request URI in a recognizable way. 279 2.2. Common Token Response 281 It is anticipated that most mechanisms (especially ones that use an 282 HTTP API) will respond to a token request using a common response 283 format. Both of the mechanisms described in this memo use the common 284 format described in this section, which is substantially the same as 285 the format described in Section 5 of [RFC6749]. 287 A successful common response is an HTTP "200" response with Content- 288 Type "application/json", and having a response body in JSON [RFC8259] 289 format encoding a JSON object with at least the following members: 291 "access_token" An opaque (to the client) string; a bearer access 292 token (Section 1.1 of [RFC6750]) which can be used for requests in 293 the same protection space as the original request; 295 "expires_in" The number of seconds from the "Date" of this response 296 after which the "access_token" will no longer be valid; 298 "token_type" A case-insensitive string identifying the kind of token 299 returned in this response. This value MUST be "Bearer". 301 If there is a problem with the request, the response SHALL be an HTTP 302 "400" response with Content-Type "application/json", and having a 303 response body in JSON format encoding a JSON object with at least an 304 "error" member, and others as appropriate, whose keys and values are 305 defined in Section 5.2 of [RFC6749]. 307 Additional members MAY be included in a successful or unsuccessful 308 response object depending on the scope(s) from the challenge, the 309 mechanism used, and the implementation. Unrecognized response object 310 members SHOULD be ignored. 312 2.3. Common Mechanism Flow 314 It is anticipated that most mechanisms will comprise a simple 315 mechanism-specific API endpoint and respond with a Common Response 316 (Section 2.2). The abstract flow for a client to acquire a bearer 317 token in the common way is illustrated in Figure 1. 319 Client Mechanism Endpoint Resource Server 320 | | | 321 |-- request URI ------------------------------------------->| 322 |<------------------------------ 401 Bearer nonce, scope, --| 323 | | endpoints | 324 |determine compatibility, | | 325 |prepare token request | | 326 |-- POST token request------->| | 327 | |validate request, | 328 | |issue token | 329 |<--------- Common Response --| | 330 | | | 331 | | 332 |-- request URI with access_token ------------------------->| 333 | validate & translate token,| 334 | apply access controls| 335 | | 336 |<--------------------------------------- answer resource --| 338 Figure 1: Common Protocol Flow Sequence Diagram 340 Note that the "validate request" step can involve complex operations 341 and include fetching supplemental information from external sources, 342 depending on the semantics of the mechanism, scopes, and principal. 344 3. Proof-of-Possession Mechanism 346 The client recognizes the availability of, and its compatibility 347 with, this mechanism, by recognizing combinations of challenge scopes 348 with which it is compatible, the presence of the 349 "token_pop_endpoint", and control of an appropriate principal having 350 proof-of-possession semantics (for example, an access token bound to 351 a proof-of-possession key, or a JSON Web Token (JWT) [RFC7519] with a 352 "cnf" claim [RFC7800]) and compatibility with the same combination of 353 challenge scopes. 355 The client constructs and signs a _proof-token_ (Section 3.1). 357 The client sends the _proof-token_ to the "token_pop_endpoint" API 358 URI with HTTP "POST" (Section 3.2). The API endpoint validates the 359 request including the _proof-token_, and if appropriate, it responds 360 with a bearer token. 362 3.1. Proof Token 364 The _proof-token_ is a JWT [RFC7519], with a signature proving 365 possesion of the key bound to the client's principal, and having the 366 following claims: 368 "sub" REQUIRED: The client's principal (having proof-of-possession 369 semantics and compatible with a combination of the challenge 370 scopes); 372 "aud" REQUIRED: The absolute URI (Section 4.3 of [RFC3986]), 373 including scheme, authority (host and optional port), path, and 374 query, but not including fragment identifier, corresponding to the 375 original request that resulted in the HTTP "401" challenge; if 376 this claim is an array, it MUST have exactly one element; 378 "nonce" REQUIRED: The nonce from the "WWW-Authenticate" challenge; 380 "jti" RECOMMENDED: Use of this claim is recommended so that the 381 client can salt the _proof-token_'s signature; the verifier can 382 ignore this claim, if present; 384 "exp" OPTIONAL: If present, this claim MUST NOT be after the 385 expiration time of the "sub" (if it has one), and MUST NOT be 386 before the current time on the verifier; ordinarily the validity 387 of the nonce is sufficient to establish not-before and not-after 388 constraints on the proof, so this claim isn't usually necessary 389 (and clocks on end-user devices, where _proof-tokens_ are likely 390 to be generated, are notoriously inaccurate). The issuer MAY take 391 the expiration periods of the _proof-token_ and the "sub" into 392 account when determining the expiration period of the bearer token 393 it issues, but it is not required to do so and is free to issue 394 bearer tokens with any expiration period. 396 Additional claims can appear in the _proof-token_ according to, and 397 conditioned on, the semantics of the scope(s). Unrecognized or 398 incompatible claims SHOULD be ignored. 400 3.2. Proof-of-Possession API 402 This API endpoint is implemented by the authorization server 403 (Section 1.1 of [RFC6749]) for the protection space of the original 404 request. 406 The client uses this API by making an HTTP "POST" request to the 407 "token_pop_endpoint" URI. The request body has Content-Type 408 "application/x-www-form-urlencoded" and includes at least the 409 following parameter: 411 "proof_token" REQUIRED: A _proof-token_ (Section 3.1) as described 412 above. 414 Additional parameters can be sent according to, and conditioned on, 415 the semantics of the scope(s). Unrecognized or incompatible 416 parameters SHOULD be ignored. 418 The authorization server verifies the request: 420 1. Parse the "proof_token" parameter and find its claims; 422 2. Verify that the "proof_token"'s signature matches the proof-of- 423 possession key associated with the "sub" claim, and that it 424 hasn't expired; 426 3. Verify that the "aud" claim is an absolute URI for a resource in 427 a protection space for which this endpoint is responsible; 429 4. Verify the "nonce" claim (for example, by confirming that it was 430 really issued by this system and not too far in the past, that it 431 hasn't been redeemed yet, and that it was issued for a request 432 for the "aud" claim); 434 5. Verify the validity and authenticity of the "sub" claim according 435 to its kind and the semantics of the relevant scope(s); 437 6. Perform any other processing, verification, and validation 438 appropriate to the relevant scope(s), additional claims, or 439 additional parameters. 441 If the request is verified, the authorization server issues a bearer 442 "access_token" valid for the protection space of the original request 443 and for a limited time. The authorization server responds using the 444 common response format (Section 2.2). 446 3.3. Proof-of-Possession Example 448 Note: This section is not normative. 450 A client (for example, an in-browser application working on behalf of 451 a user) attempts an HTTP request to a resource server for an access- 452 restricted URI initially without presenting any special credentials: 454 GET /some/restricted/resource HTTP/1.1 455 Host: www.example 456 Origin: https://app.example 458 The resource server does not allow this request without 459 authorization. It generates an unguessable, opaque nonce that the 460 server will be able to later recognize as having generated. The 461 server responds with an HTTP "401" Unauthorized message, and includes 462 the protection space identifier (realm), the nonce, the appropriate 463 scopes, and at least the "token_pop_endpoint" in the "WWW- 464 Authenticate" response header with the "Bearer" method. The server 465 also includes an HTML response body to allow the user to perform a 466 first-party login using another method, for cases where the resource 467 was navigated to directly in the browser: 469 HTTP/1.1 401 Unauthorized 470 WWW-Authenticate: Bearer realm="/auth/", 471 scope="webid openid", 472 nonce="j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk", 473 token_pop_endpoint="/auth/webid-pop", 474 client_cert_endpoint="https://webid-tls.example/auth/webid-tls" 475 Access-Control-Allow-Origin: https://app.example 476 Access-Control-Expose-Headers: WWW-Authenticate 477 Date: Mon, 6 May 2019 01:48:48 GMT 478 Content-type: text/html 480 Human first-party login page... 482 The client recognizes the response as compatible with this mechanism 483 by recognizing the scheme as "Bearer", compatible scopes (in this 484 example, "openid" and "webid"), and the presence of the "nonce" and 485 the "token_pop_endpoint". 487 The client controls a principal appropriate to the scopes (in this 488 example, a JWT substantially similar to an OpenID Connect ID Token 489 [OpenID.Core] and containing a confirmation key [RFC7800]) and 490 determines to use the proof-of-possession mechanism. 492 The client creates a new _proof-token_ JWT as described above 493 (Section 3.1), setting its "aud" claim to the absolute URI of the 494 original request, the "nonce" claim to the "nonce" parameter from the 495 "WWW-Authenticate" response header, the "sub" claim to its ID Token, 496 includes other claims as appropriate to the scopes ("iss" in this 497 example), and signs this _proof-token_ with the proof-of-possession 498 key bound to its principal and with a signing algorithm compatible 499 with the signing key and the scopes: 501 { 502 "typ": "JWT", 503 "alg": "RS256" 504 } 505 . 506 { 507 "sub": "eyJhbGciOiJ...", 508 "aud": "https://www.example/some/restricted/resource", 509 "nonce": "j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk", 510 "jti": "1C49A92C-C260-4F76-9D7B-E81AE13037B8", 511 "iss": "https://app.example/oauth/code" 512 } 513 . 514 RS256-signature-here 516 The client sends a request to the "token_pop_endpoint" URI and 517 includes the _proof-token_: 519 POST /auth/webid-pop 520 Host: www.example 521 Origin: https://app.example 522 Content-type: application/x-www-form-urlencoded 524 proof_token=eyJ0eXAiOiJKV1QiCg... 526 The "token_pop_endpoint" verifies the request as described in 527 Section 3.2, determines that the request is good, and issues a bearer 528 token: 530 HTTP/1.1 200 531 Content-type: application/json; charset=utf-8 532 Cache-control: no-cache, no-store 533 Pragma: no-cache 534 Access-Control-Allow-Origin: https://app.example 535 Date: Mon, 6 May 2019 01:48:50 GMT 537 { 538 "access_token": "RPAOmgrWb5wD7DzloDjZ7Ain", 539 "expires_in": 1800, 540 "token_type": "Bearer" 541 } 543 The client can now use the "access_token" in an "Authorization" 544 header for requests to resources in the same protection space as the 545 original request until the access token expires or is revoked: 547 GET /some/restricted/resource HTTP/1.1 548 Host: www.example 549 Origin: https://app.example 550 Authorization: Bearer RPAOmgrWb5wD7DzloDjZ7Ain 552 The server validates and translates the bearer token in its 553 implementation-specific way, and makes a determination whether to 554 grant the requested access. 556 4. TLS Client Certificate Mechanism 558 The client recognizes the availability of, and its compatibility 559 with, this mechanism, by recognizing combinations of challenge scopes 560 with which it is compatible, the presence of the 561 "client_cert_endpoint", and either direct control of an appropriate 562 TLS [RFC8446] client certificate and its signing key, or in the case 563 of browser-based Javascript applications, an assumption that such a 564 certificate is configured into the browser and that it will be 565 selected by the user. 567 The client constructs and sends a token request to the 568 "client_cert_endpoint" API URI with HTTP "POST" (Section 4.1), using 569 its TLS client certificate. 571 The API endpoint validates the request, including aspects of the 572 client certificate, and if appropriate, it responds with a bearer 573 token. 575 4.1. Client Certificate API 577 This API endpoint is implemented by the authorization server for the 578 protection space of the original request. 580 The client uses this API by making an HTTP "POST" request to the 581 "client_cert_endpoint" URI. The request body has Content-Type 582 "application/x-www-form-urlencoded" and includes at least the 583 following parameters: 585 "uri" REQUIRED: The absolute URI, including scheme, authority (host 586 and optional port), path, and query, but not including fragment 587 identifier, corresponding to the original request that resulted in 588 the HTTP "401" response; 590 "nonce" REQUIRED: The nonce from the "WWW-Authenticate" challenge. 592 Additional parameters can be sent according to, and conditioned on, 593 the semantics of the scope(s). Unrecognized or incompatible 594 parameters SHOULD be ignored. 596 A TLS client certificate is REQUIRED when communicating with this API 597 endpoint. That means the origin of this API endpoint will probably 598 be different from that of the original request URI so that the server 599 can request a client certificate in a distinct TLS connection 600 handshake (Section 4.3.2 of [RFC8446]). 602 The authorization server verifies the request: 604 1. Verify that "uri" is an absolute URI and is in a protection space 605 for which this endpoint is responsible; 607 2. Verify the "nonce" (for example, confirming that it was really 608 generated by this system, not too far in the past, that it hasn't 609 been redeemed yet, and if possible that it corresponds to a 610 request for "uri"); 612 3. Verify the validity and authenticity of the client certificate 613 (beyond those validations required for the TLS connection) 614 according to the semantics of the relevant scope(s); 616 4. Perform any other processing, verification, and validation 617 appropriate to the relevant scope(s) or additional parameters. 619 If the request is acceptable, the authorization server issues a 620 bearer "access_token" valid for the protection space of the original 621 request and for a limited time. The authorization server responds 622 using the common response format (Section 2.2). 624 4.2. Client Certificate Example 626 Note: This section is not normative. 628 A client (for example, an in-browser application working on behalf of 629 a user) attempts an HTTP request to a resource server for an access- 630 restricted URI initially without presenting any special credentials: 632 GET /some/restricted/resource HTTP/1.1 633 Host: www.example 634 Origin: https://app.example 636 The resource server does not allow this request without 637 authorization. It generates an unguessable, opaque nonce that the 638 authorization server will be able to later recognize as having 639 generated. The server responds with an HTTP "401" Unauthorized 640 message, and includes the protection space identifier (realm), the 641 nonce, the appropriate scopes, and at least the 642 "client_cert_endpoint" in the "WWW-Authenticate" response header with 643 the "Bearer" method. The server also includes an HTML response body 644 to allow the user to perform a first-party login using another 645 method, for cases where the resource was navigated to directly in the 646 browser: 648 HTTP/1.1 401 Unauthorized 649 WWW-Authenticate: Bearer realm="/auth/", 650 scope="webid openid", 651 nonce="j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk", 652 token_pop_endpoint="/auth/webid-pop", 653 client_cert_endpoint="https://webid-tls.example/auth/webid-tls" 654 Access-Control-Allow-Origin: https://app.example 655 Access-Control-Expose-Headers: WWW-Authenticate 656 Date: Mon, 6 May 2019 01:48:48 GMT 657 Content-type: text/html 659 Human first-party login page... 661 The client recognizes the response as compatible with this mechanism 662 by recognizing the scheme as "Bearer", compatible scopes (in this 663 example, "webid"), and the presence of the "nonce" and the 664 "client_cert_endpoint". 666 The client determines to use the client certificate mechanism (for 667 example, by being configured by the user to do so when available, 668 with the assumption the user will choose an appropriate certificate 669 when prompted by the browser). 671 The client sends, using its TLS client certificate, a token request 672 to the "client_cert_endpoint" URI and includes the required 673 parameters: 675 POST /auth/webid-tls HTTP/1.1 676 Host: webid-tls.example 677 Origin: https://app.example 678 Content-type: application/x-www-form-urlencoded 680 uri=https://www.example/some/restricted/resource 681 &nonce=j16C4SOLQWFor3VYUtZWnrUr5AG5uwDF7q9RFsDk 683 The "client_cert_endpoint" verifies the request as described in 684 Section 4.1 (in this example, with scope "webid", the validation and 685 processing steps further comprise establishing and validating the 686 user's WebID according to [WebID-TLS]). The endpoint determines that 687 the request is good, and issues a bearer token: 689 HTTP/1.1 200 690 Content-type: application/json; charset=utf-8 691 Cache-control: no-cache, no-store 692 Pragma: no-cache 693 Access-Control-Allow-Origin: https://app.example 694 Date: Mon, 6 May 2019 01:48:50 GMT 696 { 697 "access_token": "RPAOmgrWb5wD7DzloDjZ7Ain", 698 "expires_in": 1800, 699 "token_type": "Bearer" 700 } 702 The client can now use the "access_token" in an "Authorization" 703 header for requests to resources in the same protection space as the 704 original request until the bearer token expires or is revoked: 706 GET /some/restricted/resource HTTP/1.1 707 Host: www.example 708 Origin: https://app.example 709 Authorization: Bearer RPAOmgrWb5wD7DzloDjZ7Ain 711 The server validates and translates the bearer token in its 712 implementation-specific way, and makes a determination whether to 713 grant the requested access. 715 5. IANA Considerations 717 TBD. Mechanism parameters "token_pop_endpoint" and 718 "client_cert_endpoint" for auth-scheme "Bearer". 720 6. Security Considerations 722 When using the Proof-of-Possession mechanism (Section 3), the scope 723 designer should carefully consider whether additional information 724 should go in the _proof-token_ (which would therefore be signed) or 725 can be "POST" parameters (which would not be signed). The safe 726 choice (which therefore SHOULD be the default) is to include any 727 additional information in the _proof-token_. 729 Bearer tokens can be shared freely with other parties by an 730 application. Therefore, a bearer token obtained with the TLS Client 731 Certificate mechanism (Section 4) MUST NOT be construed to carry the 732 same weight when authenticating an HTTP request as if the client used 733 the corresponding client certificate for the request's connection. 734 However, particularly for browser-based applications where the 735 application and the resource server(s) are not associated with each 736 other, the user typically doesn't audit the data being sent in HTTP 737 requests (even when a client certificate is used), so the portion of 738 the application running in the browser could be receiving data from 739 anywhere else and sending it over HTTP using the user's client 740 certificate anyway. 742 Security considerations specific to challenge scopes are beyond the 743 purview of this memo. 745 7. Normative References 747 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 748 Requirement Levels", BCP 14, RFC 2119, 749 DOI 10.17487/RFC2119, March 1997, 750 . 752 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 753 Resource Identifier (URI): Generic Syntax", STD 66, 754 RFC 3986, DOI 10.17487/RFC3986, January 2005, 755 . 757 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 758 RFC 6749, DOI 10.17487/RFC6749, October 2012, 759 . 761 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 762 Framework: Bearer Token Usage", RFC 6750, 763 DOI 10.17487/RFC6750, October 2012, 764 . 766 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 767 Protocol (HTTP/1.1): Authentication", RFC 7235, 768 DOI 10.17487/RFC7235, June 2014, 769 . 771 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 772 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 773 . 775 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 776 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 777 May 2017, . 779 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 780 Interchange Format", STD 90, RFC 8259, 781 DOI 10.17487/RFC8259, December 2017, 782 . 784 8. Informative References 786 [DID] Reed, D., Sporny, M., Longley, D., Allen, C., Grant, R., 787 and M. Sabadello, "Decentralized Identifiers (DIDs) v1.0", 788 April 2020, . 790 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 791 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 792 . 794 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 795 Possession Key Semantics for JSON Web Tokens (JWTs)", 796 RFC 7800, DOI 10.17487/RFC7800, April 2016, 797 . 799 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 800 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 801 . 803 [OpenID.Core] 804 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 805 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 806 . 808 [WebID] Sambra, A., Story, H., Berners-Lee, T., and S. Corlosquet, 809 Ed., "WebID 1.0: Web Identity and Discovery", March 2014, 810 . 812 [WebID-TLS] 813 Inkster, T., Story, H., Harbulot, B., Corlosquet, S., Ed., 814 and A. Sambra, Ed., "WebID Authentication over TLS", March 815 2014, . 817 [VC] Sporny, M., Longley, D., Chadwick, D., Noble, G., Ed., 818 Burnett, D., Ed., and B. Zundel, Ed., "Verifiable 819 Credentials Data Model 1.0", November 2019, 820 . 822 Author's Address 824 Michael C. Thornburgh 825 Adobe 826 345 Park Avenue 827 San Jose, CA 95110-2704 828 United States of America 830 Phone: +1 408 536 6000 831 Email: mthornbu@adobe.com 832 URI: https://zenomt.zenomt.com/card.ttl#me