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