idnits 2.17.1 draft-ietf-oauth-mtls-13.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 (February 25, 2019) is 1877 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) ** Obsolete normative reference: RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' == Outdated reference: A later version (-08) exists of draft-ietf-oauth-token-binding-06 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group B. Campbell 3 Internet-Draft Ping Identity 4 Intended status: Standards Track J. Bradley 5 Expires: August 29, 2019 Yubico 6 N. Sakimura 7 Nomura Research Institute 8 T. Lodderstedt 9 YES.com AG 10 February 25, 2019 12 OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound 13 Access Tokens 14 draft-ietf-oauth-mtls-13 16 Abstract 18 This document describes OAuth client authentication and certificate- 19 bound access tokens using mutual Transport Layer Security (TLS) 20 authentication with X.509 certificates. OAuth clients are provided a 21 mechanism for authentication to the authorization server using mutual 22 TLS, based on either self-signed certificates or public key 23 infrastructure (PKI). OAuth authorization servers are provided a 24 mechanism for binding access tokens to a client's mutual TLS 25 certificate, and OAuth protected resources are provided a method for 26 ensuring that such an access token presented to it was issued to the 27 client presenting the token. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on August 29, 2019. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Requirements Notation and Conventions . . . . . . . . . . 5 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 66 2. Mutual TLS for OAuth Client Authentication . . . . . . . . . 5 67 2.1. PKI Mutual TLS Method . . . . . . . . . . . . . . . . . . 6 68 2.1.1. PKI Method Metadata Value . . . . . . . . . . . . . . 6 69 2.1.2. Client Registration Metadata . . . . . . . . . . . . 6 70 2.2. Self-Signed Certificate Mutual TLS Method . . . . . . . . 7 71 2.2.1. Self-Signed Method Metadata Value . . . . . . . . . . 8 72 2.2.2. Client Registration Metadata . . . . . . . . . . . . 8 73 3. Mutual TLS Client Certificate Bound Access Tokens . . . . . . 8 74 3.1. JWT Certificate Thumbprint Confirmation Method . . . . . 9 75 3.2. Confirmation Method for Token Introspection . . . . . . . 10 76 3.3. Authorization Server Metadata . . . . . . . . . . . . . . 11 77 3.4. Client Registration Metadata . . . . . . . . . . . . . . 11 78 4. Public Clients and Certificate Bound Tokens . . . . . . . . . 11 79 5. Metadata for Mutual TLS Endpoint Aliases . . . . . . . . . . 12 80 6. Implementation Considerations . . . . . . . . . . . . . . . . 13 81 6.1. Authorization Server . . . . . . . . . . . . . . . . . . 14 82 6.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 14 83 6.3. Certificate Expiration and Bound Access Tokens . . . . . 15 84 6.4. Implicit Grant Unsupported . . . . . . . . . . . . . . . 15 85 6.5. TLS Termination . . . . . . . . . . . . . . . . . . . . . 15 86 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 87 7.1. Certificate Thumbprint Binding . . . . . . . . . . . . . 15 88 7.2. TLS Versions and Best Practices . . . . . . . . . . . . . 16 89 7.3. X.509 Certificate Spoofing . . . . . . . . . . . . . . . 16 90 7.4. X.509 Certificate Parsing and Validation Complexity . . . 16 91 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 92 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 93 9.1. JWT Confirmation Methods Registration . . . . . . . . . . 17 94 9.2. Authorization Server Metadata Registration . . . . . . . 17 95 9.3. Token Endpoint Authentication Method Registration . . . . 18 96 9.4. Token Introspection Response Registration . . . . . . . . 18 97 9.5. Dynamic Client Registration Metadata Registration . . . . 19 98 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 99 10.1. Normative References . . . . . . . . . . . . . . . . . . 20 100 10.2. Informative References . . . . . . . . . . . . . . . . . 21 101 Appendix A. Example "cnf" Claim, Certificate and JWK . . . . . . 22 102 Appendix B. Relationship to Token Binding . . . . . . . . . . . 23 103 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 24 104 Appendix D. Document(s) History . . . . . . . . . . . . . . . . 24 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 107 1. Introduction 109 The OAuth 2.0 Authorization Framework [RFC6749] enables third-party 110 client applications to obtain delegated access to protected 111 resources. In the prototypical abstract OAuth flow, illustrated in 112 Figure 1, the client obtains an access token from an entity known as 113 an authorization server and then uses that token when accessing 114 protected resources, such as HTTPS APIs. 116 +--------+ +---------------+ 117 | | | | 118 | |<--(A)-- Get an access token --->| Authorization | 119 | | | Server | 120 | | | | 121 | | +---------------+ 122 | | ^ 123 | | | 124 | | 125 | | (C) | 126 | Client | Validate the 127 | | access token | 128 | | 129 | | | 130 | | v 131 | | +---------------+ 132 | | | (C) | 133 | | | | 134 | |<--(B)-- Use the access token -->| Protected | 135 | | | Resource | 136 | | | | 137 +--------+ +---------------+ 139 Figure 1: Abstract OAuth 2.0 Protocol Flow 141 The flow illustrated in Figure 1 includes the following steps: 143 (A) The client makes an HTTPS "POST" request to the authorization 144 server and presents a credential representing the authorization 145 grant. For certain types of clients (those that have been 146 issued or otherwise established a set of client credentials) the 147 request must be authenticated. In the response, the 148 authorization server issues an access token to the client. 150 (B) The client includes the access token when making a request to 151 access a protected resource. 153 (C) The protected resource validates the access token in order to 154 authorize the request. In some cases, such as when the token is 155 self-contained and cryptographically secured, the validation can 156 be done locally by the protected resource. While other cases 157 require that the protected resource call out to the 158 authorization server to determine the state of the token and 159 obtain meta-information about it. 161 Layering on the abstract flow above, this document standardizes 162 enhanced security options for OAuth 2.0 utilizing client certificate 163 based mutual TLS. Section 2 provides options for authenticating the 164 request in step (A). While step (C) is supported with semantics to 165 express the binding of the token to the client certificate for both 166 local and remote processing in Section 3.1 and Section 3.2 167 respectively. This ensures that, as described in Section 3, 168 protected resource access in step (B) is only possible by the 169 legitimate client bearing the access token and holding the private 170 key corresponding to the certificate. 172 OAuth 2.0 defines a shared secret method of client authentication but 173 also allows for definition and use of additional client 174 authentication mechanisms when interacting directly with the 175 authorization server. This document describes an additional 176 mechanism of client authentication utilizing mutual TLS certificate- 177 based authentication, which provides better security characteristics 178 than shared secrets. While [RFC6749] documents client authentication 179 for requests to the token endpoint, extensions to OAuth 2.0 (such as 180 Introspection [RFC7662], Revocation [RFC7009], and the Backchannel 181 Authentication Endpoint in [OpenID.CIBA]) define endpoints that also 182 utilize client authentication and the mutual TLS methods defined 183 herein are applicable to those endpoints as well. 185 Mutual TLS certificate-bound access tokens ensure that only the party 186 in possession of the private key corresponding to the certificate can 187 utilize the token to access the associated resources. Such a 188 constraint is sometimes referred to as key confirmation, proof-of- 189 possession, or holder-of-key and is unlike the case of the bearer 190 token described in [RFC6750], where any party in possession of the 191 access token can use it to access the associated resources. Binding 192 an access token to the client's certificate prevents the use of 193 stolen access tokens or replay of access tokens by unauthorized 194 parties. 196 Mutual TLS certificate-bound access tokens and mutual TLS client 197 authentication are distinct mechanisms, which are complementary but 198 don't necessarily need to be deployed or used together. 200 1.1. Requirements Notation and Conventions 202 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 203 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 204 "OPTIONAL" in this document are to be interpreted as described in BCP 205 14 [RFC2119] [RFC8174] when, and only when, they appear in all 206 capitals, as shown here. 208 1.2. Terminology 210 Throughout this document the term "mutual TLS" refers to the process 211 whereby a client presents its X.509 certificate and proves possession 212 of the corresponding private key to a server when negotiating a TLS 213 session. In contemporary versions of TLS [RFC8446] [RFC5246] this 214 requires that the client send the Certificate and CertificateVerify 215 messages during the handshake and for the server to verify the 216 CertificateVerify and Finished messages. 218 2. Mutual TLS for OAuth Client Authentication 220 This section defines, as an extension of OAuth 2.0, Section 2.3 221 [RFC6749], two distinct methods of using mutual TLS X.509 client 222 certificates as client credentials. The requirement of mutual TLS 223 for client authentication is determined by the authorization server 224 based on policy or configuration for the given client (regardless of 225 whether the client was dynamically registered, statically configured, 226 or otherwise established). 228 In order to utilize TLS for OAuth client authentication, the TLS 229 connection between the client and the authorization server MUST have 230 been established or reestablished with mutual TLS X.509 certificate 231 authentication (i.e. the Client Certificate and Certificate Verify 232 messages are sent during the TLS Handshake). 234 For all requests to the authorization server utilizing mutual TLS 235 client authentication, the client MUST include the "client_id" 236 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 237 presence of the "client_id" parameter enables the authorization 238 server to easily identify the client independently from the content 239 of the certificate. The authorization server can locate the client 240 configuration using the client identifier and check the certificate 241 presented in the TLS Handshake against the expected credentials for 242 that client. The authorization server MUST enforce the binding 243 between client and certificate as described in either Section 2.1 or 244 Section 2.2 below. 246 2.1. PKI Mutual TLS Method 248 The PKI (public key infrastructure) method of mutual TLS OAuth client 249 authentication adheres to the way in which X.509 certificates are 250 traditionally used for authentication. It relies on a subject 251 distinguished name (DN) or a subject alternative name (SAN) and 252 validated certificate chain [RFC5280] to authenticate the client. 253 The TLS handshake is utilized to validate the client's possession of 254 the private key corresponding to the public key in the certificate 255 and to validate the corresponding certificate chain. The client is 256 successfully authenticated if the subject information in the 257 certificate matches the expected subject configured or registered for 258 that particular client (note that a predictable treatment of DN 259 values, such as the distinguishedNameMatch rule from [RFC4517], is 260 needed in comparing the certificate's subject DN to the client's 261 registered DN). Revocation checking is possible with the PKI method 262 but if and how to check a certificate's revocation status is a 263 deployment decision at the discretion of the authorization server. 264 Clients can rotate their X.509 certificates without the need to 265 modify the respective authentication data at the authorization server 266 by obtaining a new certificate with the same subject from a trusted 267 certificate authority (CA). 269 2.1.1. PKI Method Metadata Value 271 For the PKI method of mutual TLS client authentication, this 272 specification defines and registers the following authentication 273 method metadata value into the "OAuth Token Endpoint Authentication 274 Methods" registry [IANA.OAuth.Parameters]. 276 tls_client_auth 277 Indicates that client authentication to the authorization server 278 will occur with mutual TLS utilizing the PKI method of associating 279 a certificate to a client. 281 2.1.2. Client Registration Metadata 283 In order to convey the expected subject of the certificate, the 284 following metadata parameters are introduced for the OAuth 2.0 285 Dynamic Client Registration Protocol [RFC7591] in support of the PKI 286 method of mutual TLS client authentication. A client using the 287 "tls_client_auth" authentication method MUST use exactly one of the 288 below metadata parameters to indicate the certificate subject value 289 that the authorization server is to expect when authenticating the 290 respective client. 292 tls_client_auth_subject_dn 293 An [RFC4514] string representation of the expected subject 294 distinguished name of the certificate, which the OAuth client will 295 use in mutual TLS authentication. 297 tls_client_auth_san_dns 298 A string containing the value of an expected dNSName SAN entry in 299 the certificate, which the OAuth client will use in mutual TLS 300 authentication. 302 tls_client_auth_san_uri 303 A string containing the value of an expected 304 uniformResourceIdentifier SAN entry in the certificate, which the 305 OAuth client will use in mutual TLS authentication. 307 tls_client_auth_san_ip 308 A string representation of an IP address in either dotted decimal 309 notation (for IPv4) or colon-delimited hexadecimal (for IPv6, as 310 defined in [RFC4291] section 2.2) that is expected to be present 311 as an iPAddress SAN entry in the certificate, which the OAuth 312 client will use in mutual TLS authentication. 314 tls_client_auth_san_email 315 A string containing the value of an expected rfc822Name SAN entry 316 in the certificate, which the OAuth client will use in mutual TLS 317 authentication. 319 2.2. Self-Signed Certificate Mutual TLS Method 321 This method of mutual TLS OAuth client authentication is intended to 322 support client authentication using self-signed certificates. As 323 pre-requisite, the client registers its X.509 certificates (using 324 "jwks" defined in [RFC7591]) or a trusted source for its X.509 325 certificates (using "jwks_uri" from [RFC7591]) with the authorization 326 server. During authentication, TLS is utilized to validate the 327 client's possession of the private key corresponding to the public 328 key presented within the certificate in the respective TLS handshake. 329 In contrast to the PKI method, the client's certificate chain is not 330 validated by the server in this case. The client is successfully 331 authenticated if the certificate that it presented during the 332 handshake matches one of the certificates configured or registered 333 for that particular client. The Self-Signed Certificate method 334 allows the use of mutual TLS to authenticate clients without the need 335 to maintain a PKI. When used in conjunction with a "jwks_uri" for 336 the client, it also allows the client to rotate its X.509 337 certificates without the need to change its respective authentication 338 data directly with the authorization server. 340 2.2.1. Self-Signed Method Metadata Value 342 For the Self-Signed Certificate method of mutual TLS client 343 authentication, this specification defines and registers the 344 following authentication method metadata value into the "OAuth Token 345 Endpoint Authentication Methods" registry [IANA.OAuth.Parameters]. 347 self_signed_tls_client_auth 348 Indicates that client authentication to the authorization server 349 will occur using mutual TLS with the client utilizing a self- 350 signed certificate. 352 2.2.2. Client Registration Metadata 354 For the Self-Signed Certificate method of binding a certificate with 355 a client using mutual TLS client authentication, the existing 356 "jwks_uri" or "jwks" metadata parameters from [RFC7591] are used to 357 convey the client's certificates via JSON Web Key (JWK) in a JWK Set 358 (JWKS) [RFC7517]. The "jwks" metadata parameter is a JWK Set 359 containing the client's public keys as an array of JWKs while the 360 "jwks_uri" parameter is a URL that references a client's JWK Set. A 361 certificate is represented with the "x5c" parameter of an individual 362 JWK within the set. Note that the members of the JWK representing 363 the public key (e.g. "n" and "e" for RSA, "x" and "y" for EC) are 364 required parameters per [RFC7518] so will be present even though they 365 are not utilized in this context. Also note that that sec 4.7 of 366 [RFC7517] requires that the key in the first certificate of the "x5c" 367 parameter match the public key represented by those other members of 368 the JWK. 370 3. Mutual TLS Client Certificate Bound Access Tokens 372 When mutual TLS is used by the client on the connection to the token 373 endpoint, the authorization server is able to bind the issued access 374 token to the client certificate. Such a binding is accomplished by 375 associating the certificate with the token in a way that can be 376 accessed by the protected resource, such as embedding the certificate 377 hash in the issued access token directly, using the syntax described 378 in Section 3.1, or through token introspection as described in 379 Section 3.2. Binding the access token to the client certificate in 380 that fashion has the benefit of decoupling that binding from the 381 client's authentication with the authorization server, which enables 382 mutual TLS during protected resource access to serve purely as a 383 proof-of-possession mechanism. Other methods of associating a 384 certificate with an access token are possible, per agreement by the 385 authorization server and the protected resource, but are beyond the 386 scope of this specification. 388 The client makes protected resource requests as described in 389 [RFC6750], however, those requests MUST be made over a mutually 390 authenticated TLS connection using the same certificate that was used 391 for mutual TLS at the token endpoint. 393 The protected resource MUST obtain, from its TLS implementation 394 layer, the client certificate used for mutual TLS and MUST verify 395 that the certificate matches the certificate associated with the 396 access token. If they do not match, the resource access attempt MUST 397 be rejected with an error per [RFC6750] using an HTTP 401 status code 398 and the "invalid_token" error code. 400 Metadata to convey server and client capabilities for mutual TLS 401 client certificate-bound access tokens is defined in Section 3.3 and 402 Section 3.4 respectively. 404 3.1. JWT Certificate Thumbprint Confirmation Method 406 When access tokens are represented as JSON Web Tokens (JWT)[RFC7519], 407 the certificate hash information SHOULD be represented using the 408 "x5t#S256" confirmation method member defined herein. 410 To represent the hash of a certificate in a JWT, this specification 411 defines the new JWT Confirmation Method [RFC7800] member "x5t#S256" 412 for the X.509 Certificate SHA-256 Thumbprint. The value of the 413 "x5t#S256" member is a base64url-encoded [RFC4648] SHA-256 [SHS] hash 414 (a.k.a. thumbprint, fingerprint or digest) of the DER encoding of the 415 X.509 certificate [RFC5280]. The base64url-encoded value MUST omit 416 all trailing pad '=' characters and MUST NOT include any line breaks, 417 whitespace, or other additional characters. 419 The following is an example of a JWT payload containing an "x5t#S256" 420 certificate thumbprint confirmation method. 422 { 423 "iss": "https://server.example.com", 424 "sub": "ty.webb@example.com", 425 "exp": 1493726400, 426 "nbf": 1493722800, 427 "cnf":{ 428 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 429 } 430 } 432 Figure 2: Example JWT Claims Set with an X.509 Certificate Thumbprint 433 Confirmation Method 435 3.2. Confirmation Method for Token Introspection 437 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 438 protected resource to query an authorization server about the active 439 state of an access token as well as to determine meta-information 440 about the token. 442 For a mutual TLS client certificate-bound access token, the hash of 443 the certificate to which the token is bound is conveyed to the 444 protected resource as meta-information in a token introspection 445 response. The hash is conveyed using the same "cnf" with "x5t#S256" 446 member structure as the certificate SHA-256 thumbprint confirmation 447 method, described in Section 3.1, as a top-level member of the 448 introspection response JSON. The protected resource compares that 449 certificate hash to a hash of the client certificate used for mutual 450 TLS authentication and rejects the request, if they do not match. 452 The following is an example of an introspection response for an 453 active token with an "x5t#S256" certificate thumbprint confirmation 454 method. 456 HTTP/1.1 200 OK 457 Content-Type: application/json 459 { 460 "active": true, 461 "iss": "https://server.example.com", 462 "sub": "ty.webb@example.com", 463 "exp": 1493726400, 464 "nbf": 1493722800, 465 "cnf":{ 466 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 467 } 468 } 470 Figure 3: Example Introspection Response for a Certificate Bound 471 Access Token 473 3.3. Authorization Server Metadata 475 This document introduces the following new authorization server 476 metadata parameter to signal the server's capability to issue 477 certificate bound access tokens: 479 tls_client_certificate_bound_access_tokens 480 OPTIONAL. Boolean value indicating server support for mutual TLS 481 client certificate-bound access tokens. If omitted, the default 482 value is "false". 484 3.4. Client Registration Metadata 486 The following new client metadata parameter is introduced to convey 487 the client's intention to use certificate bound access tokens: 489 tls_client_certificate_bound_access_tokens 490 OPTIONAL. Boolean value used to indicate the client's intention 491 to use mutual TLS client certificate-bound access tokens. If 492 omitted, the default value is "false". 494 4. Public Clients and Certificate Bound Tokens 496 Mutual TLS OAuth client authentication and certificate-bound access 497 tokens can be used independently of each other. Use of certificate- 498 bound access tokens without mutual TLS OAuth client authentication, 499 for example, is possible in support of binding access tokens to a TLS 500 client certificate for public clients (those without authentication 501 credentials associated with the "client_id"). The authorization 502 server would configure the TLS stack in the same manner as for the 503 Self-Signed Certificate method such that it does not verify that the 504 certificate presented by the client during the handshake is signed by 505 a trusted CA. Individual instances of a client would create a self- 506 signed certificate for mutual TLS with both the authorization server 507 and resource server. The authorization server would not use the 508 mutual TLS certificate to authenticate the client at the OAuth layer 509 but would bind the issued access token to that certificate, for which 510 the client has proven possession of the corresponding private key. 511 The access token is then bound to the certificate and can only be 512 used by the client possessing the certificate and corresponding 513 private key and utilizing them to negotiate mutual TLS on connections 514 to the resource server. When the authorization server issues a 515 refresh token to such a client, it SHOULD also bind the refresh token 516 to the respective certificate. And check the binding when the 517 refresh token is presented to get new access tokens. The 518 implementation details of the binding the refresh token are at the 519 discretion of the authorization server. 521 5. Metadata for Mutual TLS Endpoint Aliases 523 The process of negotiating client certificate-based mutual TLS 524 involves a TLS server requesting a certificate from the TLS client 525 (the client does not provide one unsolicited). Although a server can 526 be configured such that client certificates are optional, meaning 527 that the connection is allowed to continue when the client does not 528 provide a certificate, the act of a server requesting a certificate 529 can result in undesirable behavior from some clients. This is 530 particularly true of web browsers as TLS clients, which will 531 typically present the end-user with an intrusive certificate 532 selection interface when the server requests a certificate. 534 Authorization servers supporting both clients using mutual TLS and 535 conventional clients MAY chose to isolate the server side mutual TLS 536 behaviour to only clients intending to do mutual TLS, thus avoiding 537 any undesirable effects it might have on conventional clients. The 538 following authorization server metadata parameter is introduced to 539 facilitate such separation: 541 mtls_endpoint_aliases 542 OPTIONAL. A JSON object containing alternative authorization 543 server endpoints that, when present, an OAuth client intending to 544 do mutual TLS uses in preference to the conventional endpoints. 545 The parameter value itself consists of one or more endpoint 546 parameters, such as "token_endpoint", "revocation_endpoint", 547 "introspection_endpoint", etc., conventionally defined for the 548 top-level of authorization server metadata. An OAuth client 549 intending to do mutual TLS (for OAuth client authentication and/or 550 to acquire or use certificate-bound tokens) when making a request 551 directly to the authorization server MUST use the alias URL of the 552 endpoint within the "mtls_endpoint_aliases", when present, in 553 preference to the endpoint URL of the same name at top-level of 554 metadata. When an endpoint is not present in 555 "mtls_endpoint_aliases", then the client uses the conventional 556 endpoint URL defined at the top-level of the authorization server 557 metadata. Metadata parameters within "mtls_endpoint_aliases" that 558 do not define endpoints to which an OAuth client makes a direct 559 request have no meaning and SHOULD be ignored. 561 Below is an example of an authorization server metatdata document 562 with the "mtls_endpoint_aliases" parameter, which indicates aliases 563 for the token, revocation, and introspection endpoints that an OAuth 564 client intending to do mutual TLS would in preference to the 565 conventional token, revocation, and introspection endpoints. Note 566 that the endpoints in "mtls_endpoint_aliases" use a different host 567 than their conventional counterparts, which allows the authorization 568 server (via SNI or actual distinct hosts) to differentiate its TLS 569 behavior as appropriate. 571 { 572 "issuer": "https://server.example.com", 573 "authorization_endpoint": "https://server.example.com/authz", 574 "token_endpoint": "https://server.example.com/token", 575 "introspection_endpoint": "https://server.example.com/introspect", 576 "revocation_endpoint": "https://server.example.com/revo", 577 "jwks_uri": "https://server.example.com/jwks", 578 "response_types_supported": ["code"], 579 "response_modes_supported": ["fragment","query","form_post"], 580 "grant_types_supported": ["authorization_code", "refresh_token"], 581 "token_endpoint_auth_methods_supported": 582 ["tls_client_auth","client_secret_basic","none"], 583 "tls_client_certificate_bound_access_tokens": true 584 "mtls_endpoint_aliases": { 585 "token_endpoint": "https://mtls.example.com/token", 586 "revocation_endpoint": "https://mtls.example.com/revo", 587 "introspection_endpoint": "https://mtls.example.com/introspect" 588 } 589 } 591 Figure 4: Example Authorization Server Metadata with Mutual TLS 592 Endpoint Aliases 594 6. Implementation Considerations 595 6.1. Authorization Server 597 The authorization server needs to set up its TLS configuration 598 appropriately for the OAuth client authentication methods it 599 supports. 601 An authorization server that supports mutual TLS client 602 authentication and other client authentication methods or public 603 clients in parallel would make mutual TLS optional (i.e. allowing a 604 handshake to continue after the server requests a client certificate 605 but the client does not send one). 607 In order to support the Self-Signed Certificate method, the 608 authorization server would configure the TLS stack in such a way that 609 it does not verify whether the certificate presented by the client 610 during the handshake is signed by a trusted CA certificate. 612 As described in Section 3, the authorization server binds the issued 613 access token to the TLS client certificate, which means that it will 614 only issue certificate-bound tokens for a certificate which the 615 client has proven possession of the corresponding private key. 617 The authorization server may also consider hosting the token 618 endpoint, and other endpoints requiring client authentication, on a 619 separate host name or port in order to prevent unintended impact on 620 the TLS behavior of its other endpoints, e.g. the authorization 621 endpoint. As described in Section 5, it may further isolate any 622 potential impact of the server requesting client certificates by 623 offering a distinct set of endpoints on a separate host or port, 624 which are aliases for the originals that a client intending to do 625 mutual TLS will use in preference to the conventional endpoints. 627 6.2. Resource Server 629 OAuth divides the roles and responsibilities such that the resource 630 server relies on the authorization server to perform client 631 authentication and obtain resource owner (end-user) authorization. 632 The resource server makes authorization decisions based on the access 633 token presented by the client but does not directly authenticate the 634 client per se. The the manner in which an access token is bound to 635 the client certificate decouples it from the specific method that the 636 client used to authenticate with the authorization server. Mutual 637 TLS during protected resource access can therefore serve purely as a 638 proof-of-possession mechanism. As such, it is not necessary for the 639 resource server to validate the trust chain of the client's 640 certificate in any of the methods defined in this document. The 641 resource server would therefore configure the TLS stack in a way that 642 it does not verify whether the certificate presented by the client 643 during the handshake is signed by a trusted CA certificate. 645 6.3. Certificate Expiration and Bound Access Tokens 647 As described in Section 3, an access token is bound to a specific 648 client certificate, which means that the same certificate must be 649 used for mutual TLS on protected resource access. It also implies 650 that access tokens are invalidated when a client updates the 651 certificate, which can be handled similar to expired access tokens 652 where the client requests a new access token (typically with a 653 refresh token) and retries the protected resource request. 655 6.4. Implicit Grant Unsupported 657 This document describes binding an access token to the client 658 certificate presented on the TLS connection from the client to the 659 authorization server's token endpoint, however, such binding of 660 access tokens issued directly from the authorization endpoint via the 661 implicit grant flow is explicitly out of scope. End users interact 662 directly with the authorization endpoint using a web browser and the 663 use of client certificates in user's browsers bring operational and 664 usability issues, which make it undesirable to support certificate- 665 bound access tokens issued in the implicit grant flow. 666 Implementations wanting to employ certificate-bound access tokens 667 should utilize grant types that involve the client making an access 668 token request directly to the token endpoint (e.g. the authorization 669 code and refresh token grant types). 671 6.5. TLS Termination 673 An authorization server or resource server MAY choose to terminate 674 TLS connections at a load balancer, reverse proxy, or other network 675 intermediary. How the client certificate metadata is securely 676 communicated between the intermediary and the application server in 677 this case is out of scope of this specification. 679 7. Security Considerations 681 7.1. Certificate Thumbprint Binding 683 The binding between the certificate and access token specified in 684 Section 3.1 uses a cryptographic hash of the certificate. It relies 685 on the hash function having sufficient preimage and second-preimage 686 resistance so as to make it computationally infeasible to find or 687 create another certificate that produces to the same hash output 688 value. The SHA-256 hash function was used because it meets the 689 aforementioned requirement while being widely available. If, in the 690 future, certificate thumbprints need to be computed using hash 691 function(s) other than SHA-256, it is suggested that additional 692 related JWT confirmation methods members be defined for that purpose 693 and registered in the the IANA "JWT Confirmation Methods" registry 694 [IANA.JWT.Claims] for JWT "cnf" member values. 696 7.2. TLS Versions and Best Practices 698 In the abstract this document is applicable with any TLS version 699 supporting certificate-based client authentication. Both TLS 1.3 700 [RFC8446] and TLS 1.2 [RFC5246] are cited herein because, at the time 701 of writing, 1.3 is the newest version while 1.2 is the most widely 702 deployed. General implementation and security considerations for 703 TLS, including version recommendations, can be found in [BCP195]. 705 7.3. X.509 Certificate Spoofing 707 If the PKI method of client authentication is used, an attacker could 708 try to impersonate a client using a certificate with the same subject 709 (DN or SAN) but issued by a different CA, which the authorization 710 server trusts. To cope with that threat, the authorization server 711 SHOULD only accept as trust anchors a limited number of CAs whose 712 certificate issuance policy meets its security requirements. There 713 is an assumption then that the client and server agree on the set of 714 trust anchors that the server uses to create and validate the 715 certificate chain. Without this assumption the use of a subject to 716 identify the client certificate would open the server up to 717 certificate spoofing attacks. 719 7.4. X.509 Certificate Parsing and Validation Complexity 721 Parsing and validation of X.509 certificates and certificate chains 722 is complex and implementation mistakes have previously exposed 723 security vulnerabilities. Complexities of validation include (but 724 are not limited to) [CX5P] [DCW] [RFC5280]: 726 o checking of Basic Constraints, basic and extended Key Usage 727 constraints, validity periods, and critical extensions; 729 o handling of null-terminator bytes and non-canonical string 730 representations in subject names; 732 o handling of wildcard patterns in subject names; 734 o recursive verification of certificate chains and checking 735 certificate revocation. 737 For these reasons, implementors SHOULD use an established and well- 738 tested X.509 library (such as one used by an established TLS library) 739 for validation of X.509 certificate chains and SHOULD NOT attempt to 740 write their own X.509 certificate validation procedures. 742 8. Privacy Considerations 744 In TLS versions prior to 1.3, the client's certificate is sent 745 unencrypted in the initial handshake and can potentially be used by 746 third parties to monitor, track, and correlate client activity. This 747 is likely of little concern for clients that act on behalf of a 748 significant number of end-users because individual user activity will 749 not be discernible amidst the client activity as a whole. However, 750 clients that act on behalf of a single end-user, such as a native 751 application on a mobile device, should use TLS version 1.3 whenever 752 possible or consider the potential privacy implications of using 753 mutual TLS on earlier versions. 755 9. IANA Considerations 757 9.1. JWT Confirmation Methods Registration 759 This specification requests registration of the following value in 760 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 761 JWT "cnf" member values established by [RFC7800]. 763 o Confirmation Method Value: "x5t#S256" 764 o Confirmation Method Description: X.509 Certificate SHA-256 765 Thumbprint 766 o Change Controller: IESG 767 o Specification Document(s): Section 3.1 of [[ this specification ]] 769 9.2. Authorization Server Metadata Registration 771 This specification requests registration of the following value in 772 the IANA "OAuth Authorization Server Metadata" registry 773 [IANA.OAuth.Parameters] established by [RFC8414]. 775 o Metadata Name: "tls_client_certificate_bound_access_tokens" 776 o Metadata Description: Indicates authorization server support for 777 mutual TLS client certificate-bound access tokens. 778 o Change Controller: IESG 779 o Specification Document(s): Section 3.3 of [[ this specification ]] 781 o Metadata Name: "mtls_endpoint_aliases" 782 o Metadata Description: JSON object containing alternative 783 authorization server endpoints, which a client intending to do 784 mutual TLS will use in preference to the conventional endpoints. 786 o Change Controller: IESG 787 o Specification Document(s): Section 5 of [[ this specification ]] 789 9.3. Token Endpoint Authentication Method Registration 791 This specification requests registration of the following value in 792 the IANA "OAuth Token Endpoint Authentication Methods" registry 793 [IANA.OAuth.Parameters] established by [RFC7591]. 795 o Token Endpoint Authentication Method Name: "tls_client_auth" 796 o Change Controller: IESG 797 o Specification Document(s): Section 2.1.1 of [[ this specification 798 ]] 800 o Token Endpoint Authentication Method Name: 801 "self_signed_tls_client_auth" 802 o Change Controller: IESG 803 o Specification Document(s): Section 2.2.1 of [[ this specification 804 ]] 806 9.4. Token Introspection Response Registration 808 Proof-of-Possession Key Semantics for JSON Web Tokens [RFC7800] 809 defined the "cnf" (confirmation) claim, which enables confirmation 810 key information to be carried in a JWT. However, the same proof-of- 811 possession semantics are also useful for introspected access tokens 812 whereby the protected resource obtains the confirmation key data as 813 meta-information of a token introspection response and uses that 814 information in verifying proof-of-possession. Therefore this 815 specification defines and registers proof-of-possession semantics for 816 OAuth 2.0 Token Introspection [RFC7662] using the "cnf" structure. 817 When included as a top-level member of an OAuth token introspection 818 response, "cnf" has the same semantics and format as the claim of the 819 same name defined in [RFC7800]. While this specification only 820 explicitly uses the "x5t#S256" confirmation method member (see 821 Section 3.2), it needs to define and register the higher level "cnf" 822 structure as an introspection response member in order to define and 823 use the more specific certificate thumbprint confirmation method. 825 As such, this specification requests registration of the following 826 value in the IANA "OAuth Token Introspection Response" registry 827 [IANA.OAuth.Parameters] established by [RFC7662]. 829 o Claim Name: "cnf" 830 o Claim Description: Confirmation 831 o Change Controller: IESG 832 o Specification Document(s): [RFC7800] and [[ this specification ]] 834 9.5. Dynamic Client Registration Metadata Registration 836 This specification requests registration of the following client 837 metadata definitions in the IANA "OAuth Dynamic Client Registration 838 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 840 o Client Metadata Name: "tls_client_certificate_bound_access_tokens" 841 o Client Metadata Description: Indicates the client's intention to 842 use mutual TLS client certificate-bound access tokens. 843 o Change Controller: IESG 844 o Specification Document(s): Section 3.4 of [[ this specification ]] 846 o Client Metadata Name: "tls_client_auth_subject_dn" 847 o Client Metadata Description: String value specifying the expected 848 subject DN of the client certificate. 849 o Change Controller: IESG 850 o Specification Document(s): Section 2.1.2 of [[ this specification 851 ]] 853 o Client Metadata Name: "tls_client_auth_san_dns" 854 o Client Metadata Description: String value specifying the expected 855 dNSName SAN entry in the client certificate. 856 o Change Controller: IESG 857 o Specification Document(s): Section 2.1.2 of [[ this specification 858 ]] 860 o Client Metadata Name: "tls_client_auth_san_uri" 861 o Client Metadata Description: String value specifying the expected 862 uniformResourceIdentifier SAN entry in the client certificate. 863 o Change Controller: IESG 864 o Specification Document(s): Section 2.1.2 of [[ this specification 865 ]] 867 o Client Metadata Name: "tls_client_auth_san_ip" 868 o Client Metadata Description: String value specifying the expected 869 iPAddress SAN entry in the client certificate. 870 o Change Controller: IESG 871 o Specification Document(s): Section 2.1.2 of [[ this specification 872 ]] 874 o Client Metadata Name: "tls_client_auth_san_email" 875 o Client Metadata Description: String value specifying the expected 876 rfc822Name SAN entry in the client certificate. 877 o Change Controller: IESG 878 o Specification Document(s): Section 2.1.2 of [[ this specification 879 ]] 881 10. References 883 10.1. Normative References 885 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 886 "Recommendations for Secure Use of Transport Layer 887 Security (TLS) and Datagram Transport Layer Security 888 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 889 2015, . 891 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 892 Requirement Levels", BCP 14, RFC 2119, 893 DOI 10.17487/RFC2119, March 1997, 894 . 896 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 897 (LDAP): String Representation of Distinguished Names", 898 RFC 4514, DOI 10.17487/RFC4514, June 2006, 899 . 901 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 902 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 903 . 905 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 906 (TLS) Protocol Version 1.2", RFC 5246, 907 DOI 10.17487/RFC5246, August 2008, 908 . 910 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 911 Housley, R., and W. Polk, "Internet X.509 Public Key 912 Infrastructure Certificate and Certificate Revocation List 913 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 914 . 916 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 917 RFC 6749, DOI 10.17487/RFC6749, October 2012, 918 . 920 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 921 Framework: Bearer Token Usage", RFC 6750, 922 DOI 10.17487/RFC6750, October 2012, 923 . 925 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 926 Possession Key Semantics for JSON Web Tokens (JWTs)", 927 RFC 7800, DOI 10.17487/RFC7800, April 2016, 928 . 930 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 931 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 932 . 934 [SHS] National Institute of Standards and Technology, "Secure 935 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 936 . 939 10.2. Informative References 941 [CX5P] Wong, D., "Common x509 certificate validation/creation 942 pitfalls", September 2016, 943 . 946 [DCW] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 947 D., and V. Shmatikov, "The Most Dangerous Code in the 948 World: Validating SSL Certificates in Non-Browser 949 Software", 950 . 952 [I-D.ietf-oauth-token-binding] 953 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 954 "OAuth 2.0 Token Binding", draft-ietf-oauth-token- 955 binding-06 (work in progress), March 2018. 957 [IANA.JWT.Claims] 958 IANA, "JSON Web Token Claims", 959 . 961 [IANA.OAuth.Parameters] 962 IANA, "OAuth Parameters", 963 . 965 [OpenID.CIBA] 966 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 967 Campbell, "OpenID Connect Client Initiated Backchannel 968 Authentication Flow - Core 1.0", January 2019, 969 . 972 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 973 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 974 2006, . 976 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 977 (LDAP): Syntaxes and Matching Rules", RFC 4517, 978 DOI 10.17487/RFC4517, June 2006, 979 . 981 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 982 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 983 August 2013, . 985 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 986 DOI 10.17487/RFC7517, May 2015, 987 . 989 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 990 DOI 10.17487/RFC7518, May 2015, 991 . 993 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 994 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 995 . 997 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 998 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 999 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1000 . 1002 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1003 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1004 . 1006 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1007 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1008 May 2017, . 1010 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1011 Authorization Server Metadata", RFC 8414, 1012 DOI 10.17487/RFC8414, June 2018, 1013 . 1015 Appendix A. Example "cnf" Claim, Certificate and JWK 1017 For reference, an "x5t#S256" value and the X.509 Certificate from 1018 which it was calculated are provided in the following example 1019 figures. A JWK representation of the certificate's public key along 1020 with the "x5c" member is also provided. 1022 "cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"} 1024 Figure 5: x5t#S256 Confirmation Claim 1026 -----BEGIN CERTIFICATE----- 1027 MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx 1028 ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG 1029 SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ 1030 /Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID 1031 SQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2eXZOV 1032 bUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY= 1033 -----END CERTIFICATE----- 1035 Figure 6: PEM Encoded Self-Signed Certificate 1037 { 1038 "kty":"EC", 1039 "x":"1yfLHCpXqFjxCeHHHMVDTcLscpb07KUxudBmOMn8C7Q", 1040 "y":"8_coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8", 1041 "crv":"P-256", 1042 "x5c":[ 1043 "MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTA 1044 xODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGBy 1045 qGSM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZ 1046 jjJ/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0E 1047 AwIDSQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2 1048 eXZOVbUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY=" 1049 ] 1050 } 1052 Figure 7: JSON Web Key 1054 Appendix B. Relationship to Token Binding 1056 OAuth 2.0 Token Binding [I-D.ietf-oauth-token-binding] enables the 1057 application of Token Binding to the various artifacts and tokens 1058 employed throughout OAuth. That includes binding of an access token 1059 to a Token Binding key, which bears some similarities in motivation 1060 and design to the mutual TLS client certificate-bound access tokens 1061 defined in this document. Both documents define what is often called 1062 a proof-of-possession security mechanism for access tokens, whereby a 1063 client must demonstrate possession of cryptographic keying material 1064 when accessing a protected resource. The details differ somewhat 1065 between the two documents but both have the authorization server bind 1066 the access token that it issues to an asymmetric key pair held by the 1067 client. The client then proves possession of the private key from 1068 that pair with respect to the TLS connection over which the protected 1069 resource is accessed. 1071 Token Binding uses bare keys that are generated on the client, which 1072 avoids many of the difficulties of creating, distributing, and 1073 managing certificates used in this specification. However, at the 1074 time of writing, Token Binding is fairly new and there is relatively 1075 little support for it in available application development platforms 1076 and tooling. Until better support for the underlying core Token 1077 Binding specifications exists, practical implementations of OAuth 2.0 1078 Token Binding are infeasible. Mutual TLS, on the other hand, has 1079 been around for some time and enjoys widespread support in web 1080 servers and development platforms. As a consequence, OAuth 2.0 1081 Mutual TLS Client Authentication and Certificate Bound Access Tokens 1082 can be built and deployed now using existing platforms and tools. In 1083 the future, the two specifications are likely to be deployed in 1084 parallel for solving similar problems in different environments. 1085 Authorization servers may even support both specifications 1086 simultaneously using different proof-of-possession mechanisms for 1087 tokens issued to different clients. 1089 Appendix C. Acknowledgements 1091 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in 1092 design and development work on a mutual TLS OAuth client 1093 authentication implementation, which predates this document. 1094 Experience and learning from that work informed some of the content 1095 of this document. 1097 This specification was developed within the OAuth Working Group under 1098 the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with 1099 Eric Rescorla and Benjamin Kaduk serving as Security Area Directors. 1100 Additionally, the following individuals contributed ideas, feedback, 1101 and wording that helped shape this specification: Sergey Beryozkin, 1102 Ralph Bragg, Sophie Bremer, Vladimir Dzhuvinov, Samuel Erdtman, Evan 1103 Gilman, Leif Johansson, Michael Jones, Phil Hunt, Benjamin Kaduk, 1104 Takahiko Kawasaki, Sean Leonard, Kepeng Li, Neil Madden, James 1105 Manger, Jim Manico, Nov Matake, Sascha Preibisch, Eric Rescorla, 1106 Justin Richer, Filip Skokan, Dave Tonge, and Hannes Tschofenig. 1108 Appendix D. Document(s) History 1110 [[ to be removed by the RFC Editor before publication as an RFC ]] 1112 draft-ietf-oauth-mtls-13 1114 o Add an abstract protocol flow and diagram to serve as an overview 1115 of OAuth in general and baseline to describe the various ways in 1116 which the mechanisms defined herein are intended to be used. 1117 o A little bit less of that German influence. 1119 o Rework the TLS references a bit and, in the Terminology section, 1120 clean up the description of what messages are sent and verified in 1121 the handshake to do 'mutual TLS'. 1122 o Move the explanation about "cnf" introspection registration into 1123 the IANA Considerations. 1124 o Add CIBA as an informational reference and additional example of 1125 an OAuth extension that defines an endpoint that utilizes client 1126 authentication. 1127 o Shorten a few of the section titles. 1128 o Add new client metadata values to allow for the use of a SAN in 1129 the PKI MTLS client authentication method. 1130 o Add privacy considerations attempting to discuss the implications 1131 of the client cert being sent in the clear in TLS 1.2. 1132 o Changed the 'Certificate Bound Access Tokens Without Client 1133 Authentication' section to 'Public Clients and Certificate Bound 1134 Tokens' and moved it up to be a top level section while adding 1135 discussion of binding refresh tokens for public clients. 1136 o Reword/restructure the main PKI method section somewhat to 1137 (hopefully) improve readability. 1138 o Reword/restructure the Self-Signed method section a bit to 1139 (hopefully) make it more comprehensible. 1140 o Reword the AS and RS Implementation Considerations somewhat to 1141 (hopefully) improve readability. 1142 o Clarify that the protected protected resource obtains the client 1143 certificate used for mutual TLS from its TLS implementation layer. 1144 o Add Security Considerations section about the certificate 1145 thumbprint binding that includes the hash algorithm agility 1146 recommendation. 1147 o Add an "mtls_endpoint_aliases" AS metadata parameter that is a 1148 JSON object containing alternative authorization server endpoints, 1149 which a client intending to do mutual TLS will use in preference 1150 to the conventional endpoints. 1151 o Minor editorial updates. 1153 draft-ietf-oauth-mtls-12 1155 o Add an example certificate, JWK, and confirmation method claim. 1156 o Minor editorial updates based on implementer feedback. 1157 o Additional Acknowledgements. 1159 draft-ietf-oauth-mtls-11 1161 o Editorial updates. 1162 o Mention/reference TLS 1.3 RFC8446 in the TLS Versions and Best 1163 Practices section. 1165 draft-ietf-oauth-mtls-10 1166 o Update draft-ietf-oauth-discovery reference to RFC8414 1168 draft-ietf-oauth-mtls-09 1170 o Change "single certificates" to "self-signed certificates" in the 1171 Abstract 1173 draft-ietf-oauth-mtls-08 1175 o Incorporate clarifications and editorial improvements from Justin 1176 Richer's WGLC review 1177 o Drop the use of the "sender constrained" terminology per WGLC 1178 feedback from Neil Madden (including changing the metadata 1179 parameters from mutual_tls_sender_constrained_access_tokens to 1180 tls_client_certificate_bound_access_tokens) 1181 o Add a new security considerations section on X.509 parsing and 1182 validation per WGLC feedback from Neil Madden and Benjamin Kaduk 1183 o Note that a server can terminate TLS at a load balancer, reverse 1184 proxy, etc. but how the client certificate metadata is securely 1185 communicated to the backend is out of scope per WGLC feedback 1186 o Note that revocation checking is at the discretion of the AS per 1187 WGLC feedback 1188 o Editorial updates and clarifications 1189 o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf- 1190 oauth-token-binding to -06 1191 o Add folks involved in WGLC feedback to the acknowledgements list 1193 draft-ietf-oauth-mtls-07 1195 o Update to use the boilerplate from RFC 8174 1197 draft-ietf-oauth-mtls-06 1199 o Add an appendix section describing the relationship of this 1200 document to OAuth Token Binding as requested during the the 1201 Singapore meeting https://datatracker.ietf.org/doc/minutes- 1202 100-oauth/ 1203 o Add an explicit note that the implicit flow is not supported for 1204 obtaining certificate bound access tokens as discussed at the 1205 Singapore meeting https://datatracker.ietf.org/doc/minutes- 1206 100-oauth/ 1207 o Add/incorporate text to the Security Considerations on Certificate 1208 Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/ 1209 V26070X-6OtbVSeUz_7W2k94vCo 1210 o Changed the title to be more descriptive 1211 o Move the Security Considerations section to before the IANA 1212 Considerations 1214 o Elaborated on certificate-bound access tokens a bit more in the 1215 Abstract 1216 o Update draft-ietf-oauth-discovery reference to -08 1218 draft-ietf-oauth-mtls-05 1220 o Editorial fixes 1222 draft-ietf-oauth-mtls-04 1224 o Change the name of the 'Public Key method' to the more accurate 1225 'Self-Signed Certificate method' and also change the associated 1226 authentication method metadata value to 1227 "self_signed_tls_client_auth". 1228 o Removed the "tls_client_auth_root_dn" client metadata field as 1229 discussed in https://mailarchive.ietf.org/arch/msg/oauth/ 1230 swDV2y0be6o8czGKQi1eJV-g8qc 1231 o Update draft-ietf-oauth-discovery reference to -07 1232 o Clarify that MTLS client authentication isn't exclusive to the 1233 token endpoint and can be used with other endpoints, e.g. RFC 1234 7009 revocation and 7662 introspection, that utilize client 1235 authentication as discussed in 1236 https://mailarchive.ietf.org/arch/msg/oauth/ 1237 bZ6mft0G7D3ccebhOxnEYUv4puI 1238 o Reorganize the document somewhat in an attempt to more clearly 1239 make a distinction between mTLS client authentication and 1240 certificate-bound access tokens as well as a more clear 1241 delineation between the two (PKI/Public key) methods for client 1242 authentication 1243 o Editorial fixes and clarifications 1245 draft-ietf-oauth-mtls-03 1247 o Introduced metadata and client registration parameter to publish 1248 and request support for mutual TLS sender constrained access 1249 tokens 1250 o Added description of two methods of binding the cert and client, 1251 PKI and Public Key. 1252 o Indicated that the "tls_client_auth" authentication method is for 1253 the PKI method and introduced "pub_key_tls_client_auth" for the 1254 Public Key method 1255 o Added implementation considerations, mainly regarding TLS stack 1256 configuration and trust chain validation, as well as how to to do 1257 binding of access tokens to a TLS client certificate for public 1258 clients, and considerations around certificate-bound access tokens 1259 o Added new section to security considerations on cert spoofing 1260 o Add text suggesting that a new cnf member be defined in the 1261 future, if hash function(s) other than SHA-256 need to be used for 1262 certificate thumbprints 1264 draft-ietf-oauth-mtls-02 1266 o Fixed editorial issue https://mailarchive.ietf.org/arch/msg/oauth/ 1267 U46UMEh8XIOQnvXY9pHFq1MKPns 1268 o Changed the title (hopefully "Mutual TLS Profile for OAuth 2.0" is 1269 better than "Mutual TLS Profiles for OAuth Clients"). 1271 draft-ietf-oauth-mtls-01 1273 o Added more explicit details of using RFC 7662 token introspection 1274 with mutual TLS sender constrained access tokens. 1275 o Added an IANA OAuth Token Introspection Response Registration 1276 request for "cnf". 1277 o Specify that tls_client_auth_subject_dn and 1278 tls_client_auth_root_dn are RFC 4514 String Representation of 1279 Distinguished Names. 1280 o Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn. 1281 o Changed the text in the Section 3 to not be specific about using a 1282 hash of the cert. 1283 o Changed the abbreviated title to 'OAuth Mutual TLS' (previously 1284 was the acronym MTLSPOC). 1286 draft-ietf-oauth-mtls-00 1288 o Created the initial working group version from draft-campbell- 1289 oauth-mtls 1291 draft-campbell-oauth-mtls-01 1293 o Fix some typos. 1294 o Add to the acknowledgements list. 1296 draft-campbell-oauth-mtls-00 1298 o Add a Mutual TLS sender constrained protected resource access 1299 method and a x5t#S256 cnf method for JWT access tokens (concepts 1300 taken in part from draft-sakimura-oauth-jpop-04). 1301 o Fixed "token_endpoint_auth_methods_supported" to 1302 "token_endpoint_auth_method" for client metadata. 1303 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 1304 client metadata parameters and mention using "jwks_uri" or "jwks". 1305 o Say that the authentication method is determined by client policy 1306 regardless of whether the client was dynamically registered or 1307 statically configured. 1309 o Expand acknowledgements to those that participated in discussions 1310 around draft-campbell-oauth-tls-client-auth-00 1311 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 1313 draft-campbell-oauth-tls-client-auth-00 1315 o Initial draft. 1317 Authors' Addresses 1319 Brian Campbell 1320 Ping Identity 1322 Email: brian.d.campbell@gmail.com 1324 John Bradley 1325 Yubico 1327 Email: ve7jtb@ve7jtb.com 1328 URI: http://www.thread-safe.com/ 1330 Nat Sakimura 1331 Nomura Research Institute 1333 Email: n-sakimura@nri.co.jp 1334 URI: https://nat.sakimura.org/ 1336 Torsten Lodderstedt 1337 YES.com AG 1339 Email: torsten@lodderstedt.net