idnits 2.17.1 draft-ietf-oauth-mtls-11.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 (August 30, 2018) is 2066 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: March 3, 2019 Yubico 6 N. Sakimura 7 Nomura Research Institute 8 T. Lodderstedt 9 YES Europe AG 10 August 30, 2018 12 OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access 13 Tokens 14 draft-ietf-oauth-mtls-11 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 March 3, 2019. 46 Copyright Notice 48 Copyright (c) 2018 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 . . . . . . . . . . 4 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Mutual TLS for OAuth Client Authentication . . . . . . . . . 4 67 2.1. PKI Mutual TLS OAuth Client Authentication Method . . . . 5 68 2.1.1. PKI Authentication Method Metadata Value . . . . . . 5 69 2.1.2. Client Registration Metadata . . . . . . . . . . . . 5 70 2.2. Self-Signed Certificate Mutual TLS OAuth Client 71 Authentication Method . . . . . . . . . . . . . . . . . . 6 72 2.2.1. Self-Signed Certificate Authentication Method 73 Metadata Value . . . . . . . . . . . . . . . . . . . 6 74 2.2.2. Client Registration Metadata . . . . . . . . . . . . 6 75 3. Mutual TLS Client Certificate Bound Access Tokens . . . . . . 7 76 3.1. X.509 Certificate Thumbprint Confirmation Method for JWT 7 77 3.2. Confirmation Method for Token Introspection . . . . . . . 8 78 3.3. Authorization Server Metadata . . . . . . . . . . . . . . 9 79 3.4. Client Registration Metadata . . . . . . . . . . . . . . 10 80 4. Implementation Considerations . . . . . . . . . . . . . . . . 10 81 4.1. Authorization Server . . . . . . . . . . . . . . . . . . 10 82 4.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 10 83 4.3. Certificate Bound Access Tokens Without Client 84 Authentication . . . . . . . . . . . . . . . . . . . . . 10 85 4.4. Certificate Bound Access Tokens . . . . . . . . . . . . . 11 86 4.5. Implicit Grant Unsupported . . . . . . . . . . . . . . . 11 87 4.6. TLS Termination . . . . . . . . . . . . . . . . . . . . . 12 88 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 89 5.1. TLS Versions and Best Practices . . . . . . . . . . . . . 12 90 5.2. X.509 Certificate Spoofing . . . . . . . . . . . . . . . 12 91 5.3. X.509 Certificate Parsing and Validation Complexity . . . 12 92 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 93 6.1. JWT Confirmation Methods Registration . . . . . . . . . . 13 94 6.2. OAuth Authorization Server Metadata Registration . . . . 13 95 6.3. Token Endpoint Authentication Method Registration . . . . 13 96 6.4. OAuth Token Introspection Response Registration . . . . . 14 97 6.5. OAuth Dynamic Client Registration Metadata Registration . 14 98 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 99 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 100 7.2. Informative References . . . . . . . . . . . . . . . . . 16 101 Appendix A. Relationship to Token Binding . . . . . . . . . . . 17 102 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 18 103 Appendix C. Document(s) History . . . . . . . . . . . . . . . . 18 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 106 1. Introduction 108 This document describes OAuth client authentication and certificate 109 bound access tokens using mutual TLS [RFC5246] authentication with 110 X.509 certificates. OAuth clients are provided mechanisms for 111 authentication to the authorization server using mutual TLS. OAuth 112 authorization servers are provided a mechanism for binding access 113 tokens to a client's mutual TLS certificate, and OAuth protected 114 resources are provided a method for ensuring that such an access 115 token presented to it was issued to the client presenting the token. 117 The OAuth 2.0 Authorization Framework [RFC6749] defines a shared 118 secret method of client authentication but also allows for definition 119 and use of additional client authentication mechanisms when 120 interacting directly with the authorization server. This document 121 describes an additional mechanism of client authentication utilizing 122 mutual TLS certificate-based authentication, which provides better 123 security characteristics than shared secrets. While [RFC6749] 124 documents client authentication for requests to the token endpoint, 125 extensions to OAuth 2.0 (such as Introspection [RFC7662] and 126 Revocation [RFC7009]) define endpoints that also utilize client 127 authentication and the mutual TLS methods defined herein are 128 applicable to those endpoints as well. 130 Mutual TLS certificate bound access tokens ensure that only the party 131 in possession of the private key corresponding to the certificate can 132 utilize the token to access the associated resources. Such a 133 constraint is sometimes referred to as key confirmation, proof-of- 134 possession, or holder-of-key and is unlike the case of the bearer 135 token described in [RFC6750], where any party in possession of the 136 access token can use it to access the associated resources. Binding 137 an access token to the client's certificate prevents the use of 138 stolen access tokens or replay of access tokens by unauthorized 139 parties. 141 Mutual TLS certificate bound access tokens and mutual TLS client 142 authentication are distinct mechanisms, which are complementary but 143 don't necessarily need to be deployed or used together. 145 1.1. Requirements Notation and Conventions 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 1.2. Terminology 155 Mutual TLS refers to the process whereby a client presents its X.509 156 certificate and proves possession of the corresponding private key to 157 a server when negotiating a TLS session. In TLS 1.2 [RFC5246] this 158 requires the client to send Client Certificate and Certificate Verify 159 messages during the TLS handshake and for the server to verify these 160 messages. 162 2. Mutual TLS for OAuth Client Authentication 164 This section defines, as an extension of OAuth 2.0, Section 2.3 165 [RFC6749], two distinct methods of using mutual TLS X.509 client 166 certificates as client credentials. The requirement of mutual TLS 167 for client authentication is determined by the authorization server 168 based on policy or configuration for the given client (regardless of 169 whether the client was dynamically registered, statically configured, 170 or otherwise established). 172 In order to utilize TLS for OAuth client authentication, the TLS 173 connection between the client and the authorization server MUST have 174 been established or reestablished with mutual TLS X.509 certificate 175 authentication (i.e. the Client Certificate and Certificate Verify 176 messages are sent during the TLS Handshake [RFC5246]). 178 For all requests to the authorization server utilizing mutual TLS 179 client authentication, the client MUST include the "client_id" 180 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 181 presence of the "client_id" parameter enables the authorization 182 server to easily identify the client independently from the content 183 of the certificate. The authorization server can locate the client 184 configuration using the client identifier and check the certificate 185 presented in the TLS Handshake against the expected credentials for 186 that client. The authorization server MUST enforce the binding of a 187 certificate to a specific client as described in either Section 2.1 188 or Section 2.2 below. 190 2.1. PKI Mutual TLS OAuth Client Authentication Method 192 The PKI (public key infrastructure) method of mutual TLS OAuth client 193 authentication uses a subject distinguished name (DN) and validated 194 certificate chain to identify the client. The TLS handshake is 195 utilized to validate the client's possession of the private key 196 corresponding to the public key in the certificate and to validate 197 the corresponding certificate chain. The client is successfully 198 authenticated if the subject information in the certificate matches 199 the expected DN configured or registered for that particular client 200 (note that a predictable treatment of DN values, such as the 201 distinguishedNameMatch rule from [RFC4517], is needed in comparing 202 the certificate's subject DN to the client's registered DN). If and 203 how to check a certificate's revocation status is a deployment 204 decision at the discretion of the authorization server. The PKI 205 method facilitates the way X.509 certificates are traditionally being 206 used for authentication. It also allows the client to rotate its 207 X.509 certificates without the need to modify its respective 208 authentication data at the authorization server by obtaining a new 209 certificate with the same subject DN from a trusted certificate 210 authority (CA). 212 2.1.1. PKI Authentication Method Metadata Value 214 For the PKI method of mutual TLS client authentication, this 215 specification defines and registers the following authentication 216 method metadata value into the "OAuth Token Endpoint Authentication 217 Methods" registry [IANA.OAuth.Parameters]. 219 tls_client_auth 220 Indicates that client authentication to the authorization server 221 will occur with mutual TLS utilizing the PKI method of associating 222 a certificate to a client. 224 2.1.2. Client Registration Metadata 226 The following metadata parameter is introduced for the OAuth 2.0 227 Dynamic Client Registration Protocol [RFC7591] in support of the PKI 228 method of binding a certificate to a client: 230 tls_client_auth_subject_dn 231 An [RFC4514] string representation of the expected subject 232 distinguished name of the certificate, which the OAuth client will 233 use in mutual TLS authentication. 235 2.2. Self-Signed Certificate Mutual TLS OAuth Client Authentication 236 Method 238 This method of mutual TLS OAuth client authentication is intended to 239 support client authentication using self-signed certificates. As 240 pre-requisite, the client registers an X.509 certificate or a trusted 241 source for its X.509 certificates (such as the "jwks_uri" defined in 242 [RFC7591] that references a JSON Web Key [RFC7517] Set containing the 243 client's certificates and public keys) with the authorization server. 244 During authentication, TLS is utilized to validate the client's 245 possession of the private key corresponding to the public key 246 presented within the certificate in the respective TLS handshake. In 247 contrast to the PKI method, the client's certificate chain is not 248 validated by the server in this case. The client is successfully 249 authenticated if the subject public key info of the certificate 250 matches the subject public key info of one of the certificates 251 configured or registered for that particular client. The Self-Signed 252 Certificate method allows to use mutual TLS to authenticate clients 253 without the need to maintain a PKI. When used in conjunction with a 254 "jwks_uri" for the client, it also allows the client to rotate its 255 X.509 certificates without the need to change its respective 256 authentication data directly with the authorization server. 258 2.2.1. Self-Signed Certificate Authentication Method Metadata Value 260 For the Self-Signed Certificate method of mutual TLS client 261 authentication, this specification defines and registers the 262 following authentication method metadata value into the "OAuth Token 263 Endpoint Authentication Methods" registry [IANA.OAuth.Parameters]. 265 self_signed_tls_client_auth 266 Indicates that client authentication to the authorization server 267 will occur using mutual TLS with the client utilizing a self- 268 signed certificate. 270 2.2.2. Client Registration Metadata 272 For the Self-Signed Certificate method of binding a certificate to a 273 client using mutual TLS client authentication, the existing 274 "jwks_uri" or "jwks" metadata parameters from [RFC7591] are used to 275 convey the client's certificates and public keys, where the X.509 276 certificates are represented using the JSON Web Key (JWK) [RFC7517] 277 "x5c" parameter (note that Sec 4.7 of RFC 7517 requires that the key 278 in the first certificate of the "x5c" parameter must match the public 279 key represented by other members of the JWK). 281 3. Mutual TLS Client Certificate Bound Access Tokens 283 When mutual TLS is used by the client on the connection to the token 284 endpoint, the authorization server is able to bind the issued access 285 token to the client certificate. Such a binding is accomplished by 286 associating the certificate with the token in a way that can be 287 accessed by the protected resource, such as embedding the certificate 288 hash in the issued access token directly, using the syntax described 289 in Section 3.1, or through token introspection as described in 290 Section 3.2. Binding the access token to the client certificate in 291 that fashion has the benefit of decoupling that binding from the 292 client's authentication with the authorization server, which enables 293 mutual TLS during protected resource access to serve purely as a 294 proof-of-possession mechanism. Other methods of associating a 295 certificate with an access token are possible, per agreement by the 296 authorization server and the protected resource, but are beyond the 297 scope of this specification. 299 The client makes protected resource requests as described in 300 [RFC6750], however, those requests MUST be made over a mutually 301 authenticated TLS connection using the same certificate that was used 302 for mutual TLS at the token endpoint. 304 The protected resource MUST obtain the client certificate used for 305 mutual TLS authentication and MUST verify that the certificate 306 matches the certificate associated with the access token. If they do 307 not match, the resource access attempt MUST be rejected with an error 308 per [RFC6750] using an HTTP 401 status code and the "invalid_token" 309 error code. 311 Metadata to convey server and client capabilities for mutual TLS 312 client certificate bound access tokens is defined in Section 3.3 and 313 Section 3.4 respectively. 315 3.1. X.509 Certificate Thumbprint Confirmation Method for JWT 317 When access tokens are represented as JSON Web Tokens (JWT)[RFC7519], 318 the certificate hash information SHOULD be represented using the 319 "x5t#S256" confirmation method member defined herein. 321 To represent the hash of a certificate in a JWT, this specification 322 defines the new JWT Confirmation Method [RFC7800] member "x5t#S256" 323 for the X.509 Certificate SHA-256 Thumbprint. The value of the 324 "x5t#S256" member is the SHA-256[SHS] hash (a.k.a. thumbprint, 325 fingerprint or digest) of the DER encoding of the X.509 certificate 326 [RFC5280] base64url-encoded [RFC4648] with with all trailing pad '=' 327 characters omitted and without the inclusion of any line breaks, 328 whitespace, or other additional characters. 330 The following is an example of a JWT payload containing an "x5t#S256" 331 certificate thumbprint confirmation method. 333 { 334 "iss": "https://server.example.com", 335 "sub": "ty.webb@example.com", 336 "exp": 1493726400, 337 "nbf": 1493722800, 338 "cnf":{ 339 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 340 } 341 } 343 Figure 1: Example JWT Claims Set with an X.509 Certificate Thumbprint 344 Confirmation Method 346 If, in the future, certificate thumbprints need to be computed using 347 hash functions other than SHA-256, it is suggested that additional 348 related JWT confirmation methods members be defined for that purpose. 349 For example, a new "x5t#S512" (X.509 Certificate Thumbprint using 350 SHA-512) confirmation method member could be defined by registering 351 it in the the IANA "JWT Confirmation Methods" registry 352 [IANA.JWT.Claims] for JWT "cnf" member values established by 353 [RFC7800]. 355 3.2. Confirmation Method for Token Introspection 357 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 358 protected resource to query an authorization server about the active 359 state of an access token as well as to determine meta-information 360 about the token. 362 For a mutual TLS client certificate bound access token, the hash of 363 the certificate to which the token is bound is conveyed to the 364 protected resource as meta-information in a token introspection 365 response. The hash is conveyed using the same structure as the 366 certificate SHA-256 thumbprint confirmation method, described in 367 Section 3.1, as a top-level member of the introspection response 368 JSON. The protected resource compares that certificate hash to a 369 hash of the client certificate used for mutual TLS authentication and 370 rejects the request, if they do not match. 372 Proof-of-Possession Key Semantics for JSON Web Tokens [RFC7800] 373 defined the "cnf" (confirmation) claim, which enables confirmation 374 key information to be carried in a JWT. However, the same proof-of- 375 possession semantics are also useful for introspected access tokens 376 whereby the protected resource obtains the confirmation key data as 377 meta-information of a token introspection response and uses that 378 information in verifying proof-of-possession. Therefore this 379 specification defines and registers proof-of-possession semantics for 380 OAuth 2.0 Token Introspection [RFC7662] using the "cnf" structure. 381 When included as a top-level member of an OAuth token introspection 382 response, "cnf" has the same semantics and format as the claim of the 383 same name defined in [RFC7800]. While this specification only 384 explicitly uses the "x5t#S256" confirmation method member, it needed 385 to define and register the higher level "cnf" structure as an 386 introspection response member in order to define and use the more 387 specific certificate thumbprint confirmation method. 389 The following is an example of an introspection response for an 390 active token with an "x5t#S256" certificate thumbprint confirmation 391 method. 393 HTTP/1.1 200 OK 394 Content-Type: application/json 396 { 397 "active": true, 398 "iss": "https://server.example.com", 399 "sub": "ty.webb@example.com", 400 "exp": 1493726400, 401 "nbf": 1493722800, 402 "cnf":{ 403 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 404 } 405 } 407 Figure 2: Example Introspection Response for a Certificate Bound 408 Access Token 410 3.3. Authorization Server Metadata 412 This document introduces the following new authorization server 413 metadata parameter to signal the server's capability to issue 414 certificate bound access tokens: 416 tls_client_certificate_bound_access_tokens 417 OPTIONAL. Boolean value indicating server support for mutual TLS 418 client certificate bound access tokens. If omitted, the default 419 value is "false". 421 3.4. Client Registration Metadata 423 The following new client metadata parameter is introduced to convey 424 the client's intention to use certificate bound access tokens: 426 tls_client_certificate_bound_access_tokens 427 OPTIONAL. Boolean value used to indicate the client's intention 428 to use mutual TLS client certificate bound access tokens. If 429 omitted, the default value is "false". 431 4. Implementation Considerations 433 4.1. Authorization Server 435 The authorization server needs to set up its TLS configuration 436 appropriately for the binding methods it supports. 438 If the authorization server wants to support mutual TLS client 439 authentication and other client authentication methods in parallel, 440 it should make mutual TLS optional. 442 If the authorization server supports the Self-Signed Certificate 443 method, it should configure the TLS stack in a way that it does not 444 verify whether the certificate presented by the client during the 445 handshake is signed by a trusted CA certificate. 447 The authorization server may also consider hosting the token 448 endpoint, and other endpoints requiring client authentication, on a 449 separate host name or port in order to prevent unintended impact on 450 the TLS behavior of its other endpoints, e.g. the authorization 451 endpoint. 453 4.2. Resource Server 455 Since the resource server relies on the authorization server to 456 perform client authentication, there is no need for the resource 457 server to validate the trust chain of the client's certificate in any 458 of the methods defined in this document. Mutual TLS is used only as 459 a proof-of-possession mechanism during protected resource access. 460 The resource server should therefore configure the TLS stack in a way 461 that it does not verify whether the certificate presented by the 462 client during the handshake is signed by a trusted CA certificate. 464 4.3. Certificate Bound Access Tokens Without Client Authentication 466 Mutual TLS OAuth client authentication and mutual TLS client 467 certificate bound access tokens can be used independently of each 468 other. Use of certificate bound access tokens without mutual TLS 469 OAuth client authentication, for example, is possible in support of 470 binding access tokens to a TLS client certificate for public clients 471 or clients utilizing other methods of authentication to the 472 authorization server. The authorization server would configure the 473 TLS stack in the same manner as for the Self-Signed Certificate 474 method such that it does not verify that the certificate presented by 475 the client during the handshake is signed by a trusted CA. 476 Individual instances of a client would create a self-signed 477 certificate for mutual TLS with both the authorization server and 478 resource server. The authorization server would not use the mutual 479 TLS certificate to authenticate the client at the OAuth layer but 480 would bind the issued access token to that certificate, which the 481 client has proven possession of the corresponding private key. The 482 access token is then bound to the certificate and can only be used by 483 the client possessing the certificate and corresponding private key 484 and utilizing them to negotiate mutual TLS on connections to the 485 resource server. 487 4.4. Certificate Bound Access Tokens 489 As described in Section 3, an access token is bound to a specific 490 client certificate, which means that the same certificate must be 491 used for mutual TLS on protected resource access. It also implies 492 that access tokens are invalidated when a client updates the 493 certificate, which can be handled similar to expired access tokens 494 where the client requests a new access token (typically with a 495 refresh token) and retries the protected resource request. 497 4.5. Implicit Grant Unsupported 499 This document describes binding an access token to the client 500 certificate presented on the TLS connection from the client to the 501 authorization server's token endpoint, however, such binding of 502 access tokens issued directly from the authorization endpoint via the 503 implicit grant flow is explicitly out of scope. End users interact 504 directly with the authorization endpoint using a web browser and the 505 use of client certificates in user's browsers bring operational and 506 usability issues, which make it undesirable to support certificate 507 bound access tokens issued in the implicit grant flow. 508 Implementations wanting to employ certificate bound access tokens 509 should utilize grant types that involve the client making an access 510 token request directly to the token endpoint (e.g. the authorization 511 code and refresh token grant types). 513 4.6. TLS Termination 515 An authorization server or resource server MAY choose to terminate 516 TLS connections at a load balancer, reverse proxy, or other network 517 intermediary. How the client certificate metadata is securely 518 communicated between the intermediary and the application server in 519 this case is out of scope of this specification. 521 5. Security Considerations 523 5.1. TLS Versions and Best Practices 525 TLS 1.2 [RFC5246] is cited in this document because, at the time of 526 writing, it is the latest version that is widely deployed. However, 527 this document is applicable with other TLS versions supporting 528 certificate-based client authentication, including the relatively 529 recently published TLS 1.3 [RFC8446]. Implementation security 530 considerations for TLS, including version recommendations, can be 531 found in Recommendations for Secure Use of Transport Layer Security 532 (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 534 5.2. X.509 Certificate Spoofing 536 If the PKI method of client authentication is used, an attacker could 537 try to impersonate a client using a certificate with the same subject 538 DN but issued by a different CA, which the authorization server 539 trusts. To cope with that threat, the authorization server should 540 only accept as trust anchors a limited number of CAs whose 541 certificate issuance policy meets its security requirements. There 542 is an assumption then that the client and server agree on the set of 543 trust anchors that the server uses to create and validate the 544 certificate chain. Without this assumption the use of a Subject DN 545 to identify the client certificate would open the server up to 546 certificate spoofing attacks. 548 5.3. X.509 Certificate Parsing and Validation Complexity 550 Parsing and validation of X.509 certificates and certificate chains 551 is complex and implementation mistakes have previously exposed 552 security vulnerabilities. Complexities of validation include (but 553 are not limited to) [X509Pitfalls] [DangerousCode] [RFC5280]: 555 o checking of Basic Constraints, basic and extended Key Usage 556 constraints, validity periods, and critical extensions; 558 o handling of null-terminator bytes and non-canonical string 559 representations in subject names; 561 o handling of wildcard patterns in subject names; 563 o recursive verification of certificate chains and checking 564 certificate revocation. 566 For these reasons, implementors SHOULD use an established and well- 567 tested X.509 library (such as one used by an established TLS library) 568 for validation of X.509 certificate chains and SHOULD NOT attempt to 569 write their own X.509 certificate validation procedures. 571 6. IANA Considerations 573 6.1. JWT Confirmation Methods Registration 575 This specification requests registration of the following value in 576 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 577 JWT "cnf" member values established by [RFC7800]. 579 o Confirmation Method Value: "x5t#S256" 580 o Confirmation Method Description: X.509 Certificate SHA-256 581 Thumbprint 582 o Change Controller: IESG 583 o Specification Document(s): Section 3.1 of [[ this specification ]] 585 6.2. OAuth Authorization Server Metadata Registration 587 This specification requests registration of the following value in 588 the IANA "OAuth Authorization Server Metadata" registry 589 [IANA.OAuth.Parameters] established by [RFC8414]. 591 o Metadata Name: "tls_client_certificate_bound_access_tokens" 592 o Metadata Description: Indicates authorization server support for 593 mutual TLS client certificate bound access tokens. 594 o Change Controller: IESG 595 o Specification Document(s): Section 3.3 of [[ this specification ]] 597 6.3. Token Endpoint Authentication Method Registration 599 This specification requests registration of the following value in 600 the IANA "OAuth Token Endpoint Authentication Methods" registry 601 [IANA.OAuth.Parameters] established by [RFC7591]. 603 o Token Endpoint Authentication Method Name: "tls_client_auth" 604 o Change Controller: IESG 605 o Specification Document(s): Section 2.1.1 of [[ this specification 606 ]] 608 o Token Endpoint Authentication Method Name: 609 "self_signed_tls_client_auth" 610 o Change Controller: IESG 611 o Specification Document(s): Section 2.2.1 of [[ this specification 612 ]] 614 6.4. OAuth Token Introspection Response Registration 616 This specification requests registration of the following value in 617 the IANA "OAuth Token Introspection Response" registry 618 [IANA.OAuth.Parameters] established by [RFC7662]. 620 o Claim Name: "cnf" 621 o Claim Description: Confirmation 622 o Change Controller: IESG 623 o Specification Document(s): Section 3.2 of [[ this specification ]] 625 6.5. OAuth Dynamic Client Registration Metadata Registration 627 This specification requests registration of the following client 628 metadata definitions in the IANA "OAuth Dynamic Client Registration 629 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 631 o Client Metadata Name: "tls_client_certificate_bound_access_tokens" 632 o Client Metadata Description: Indicates the client's intention to 633 use mutual TLS client certificate bound access tokens. 634 o Change Controller: IESG 635 o Specification Document(s): Section 3.4 of [[ this specification ]] 637 o Client Metadata Name: "tls_client_auth_subject_dn" 638 o Client Metadata Description: String value specifying the expected 639 subject distinguished name of the client certificate. 640 o Change Controller: IESG 641 o Specification Document(s): Section 2.1.2 of [[ this specification 642 ]] 644 7. References 646 7.1. Normative References 648 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 649 "Recommendations for Secure Use of Transport Layer 650 Security (TLS) and Datagram Transport Layer Security 651 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 652 2015, . 654 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 655 Requirement Levels", BCP 14, RFC 2119, 656 DOI 10.17487/RFC2119, March 1997, 657 . 659 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 660 (LDAP): String Representation of Distinguished Names", 661 RFC 4514, DOI 10.17487/RFC4514, June 2006, 662 . 664 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 665 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 666 . 668 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 669 (TLS) Protocol Version 1.2", RFC 5246, 670 DOI 10.17487/RFC5246, August 2008, 671 . 673 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 674 Housley, R., and W. Polk, "Internet X.509 Public Key 675 Infrastructure Certificate and Certificate Revocation List 676 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 677 . 679 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 680 RFC 6749, DOI 10.17487/RFC6749, October 2012, 681 . 683 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 684 Framework: Bearer Token Usage", RFC 6750, 685 DOI 10.17487/RFC6750, October 2012, 686 . 688 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 689 Possession Key Semantics for JSON Web Tokens (JWTs)", 690 RFC 7800, DOI 10.17487/RFC7800, April 2016, 691 . 693 [SHS] National Institute of Standards and Technology, "Secure 694 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 695 . 698 7.2. Informative References 700 [DangerousCode] 701 Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 702 D., and V. Shmatikov, "The Most Dangerous Code in the 703 World: Validating SSL Certificates in Non-Browser 704 Software", 705 . 707 [I-D.ietf-oauth-token-binding] 708 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 709 "OAuth 2.0 Token Binding", draft-ietf-oauth-token- 710 binding-06 (work in progress), March 2018. 712 [IANA.JWT.Claims] 713 IANA, "JSON Web Token Claims", 714 . 716 [IANA.OAuth.Parameters] 717 IANA, "OAuth Parameters", 718 . 720 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 721 (LDAP): Syntaxes and Matching Rules", RFC 4517, 722 DOI 10.17487/RFC4517, June 2006, 723 . 725 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 726 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 727 August 2013, . 729 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 730 DOI 10.17487/RFC7517, May 2015, 731 . 733 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 734 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 735 . 737 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 738 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 739 RFC 7591, DOI 10.17487/RFC7591, July 2015, 740 . 742 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 743 RFC 7662, DOI 10.17487/RFC7662, October 2015, 744 . 746 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 747 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 748 May 2017, . 750 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 751 Authorization Server Metadata", RFC 8414, 752 DOI 10.17487/RFC8414, June 2018, 753 . 755 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 756 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 757 . 759 [X509Pitfalls] 760 Wong, D., "Common x509 certificate validation/creation 761 pitfalls", September 2016, 762 . 765 Appendix A. Relationship to Token Binding 767 OAuth 2.0 Token Binding [I-D.ietf-oauth-token-binding] enables the 768 application of Token Binding to the various artifacts and tokens 769 employed throughout OAuth. That includes binding of an access token 770 to a Token Binding key, which bears some similarities in motivation 771 and design to the mutual TLS client certificate bound access tokens 772 defined in this document. Both documents define what is often called 773 a proof-of-possession security mechanism for access tokens, whereby a 774 client must demonstrate possession of cryptographic keying material 775 when accessing a protected resource. The details differ somewhat 776 between the two documents but both have the authorization server bind 777 the access token that it issues to an asymmetric key pair held by the 778 client. The client then proves possession of the private key from 779 that pair with respect to the TLS connection over which the protected 780 resource is accessed. 782 Token Binding uses bare keys that are generated on the client, which 783 avoids many of the difficulties of creating, distributing, and 784 managing certificates used in this specification. However, at the 785 time of writing, Token Binding is fairly new and there is relatively 786 little support for it in available application development platforms 787 and tooling. Until better support for the underlying core Token 788 Binding specifications exists, practical implementations of OAuth 2.0 789 Token Binding are infeasible. Mutual TLS, on the other hand, has 790 been around for some time and enjoys widespread support in web 791 servers and development platforms. As a consequence, OAuth 2.0 792 Mutual TLS Client Authentication and Certificate Bound Access Tokens 793 can be built and deployed now using existing platforms and tools. In 794 the future, the two specifications are likely to be deployed in 795 parallel for solving similar problems in different environments. 796 Authorization servers may even support both specifications 797 simultaneously using different proof-of-possession mechanisms for 798 tokens issued to different clients. 800 Appendix B. Acknowledgements 802 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in 803 design and development work on a mutual TLS OAuth client 804 authentication implementation, which predates this document. 805 Experience and learning from that work informed some of the content 806 of this document. 808 Additionally, the authors would like to thank the following people 809 for their input and contributions to the specification: Sergey 810 Beryozkin, Sophie Bremer, Vladimir Dzhuvinov, Samuel Erdtman, Leif 811 Johansson, Michael Jones, Phil Hunt, Benjamin Kaduk, Takahiko 812 Kawasaki, Sean Leonard, Kepeng Li, Neil Madden, James Manger, Jim 813 Manico, Nov Matake, Sascha Preibisch, Justin Richer, Dave Tonge, and 814 Hannes Tschofenig. 816 Appendix C. Document(s) History 818 [[ to be removed by the RFC Editor before publication as an RFC ]] 820 draft-ietf-oauth-mtls-11 822 o Editorial updates. 823 o Mention/reference TLS 1.3 RFC8446 in the TLS Versions and Best 824 Practices section. 826 draft-ietf-oauth-mtls-10 828 o Update draft-ietf-oauth-discovery reference to RFC8414 830 draft-ietf-oauth-mtls-09 832 o Change "single certificates" to "self-signed certificates" in the 833 Abstract 835 draft-ietf-oauth-mtls-08 837 o Incorporate clarifications and editorial improvements from Justin 838 Richer's WGLC review 839 o Drop the use of the "sender constrained" terminology per WGLC 840 feedback from Neil Madden (including changing the metadata 841 parameters from mutual_tls_sender_constrained_access_tokens to 842 tls_client_certificate_bound_access_tokens) 843 o Add a new security considerations section on X.509 parsing and 844 validation per WGLC feedback from Neil Madden and Benjamin Kaduk 845 o Note that a server can terminate TLS at a load balancer, reverse 846 proxy, etc. but how the client certificate metadata is securely 847 communicated to the backend is out of scope per WGLC feedback 848 o Note that revocation checking is at the discretion of the AS per 849 WGLC feedback 850 o Editorial updates and clarifications 851 o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf- 852 oauth-token-binding to -06 853 o Add folks involved in WGLC feedback to the acknowledgements list 855 draft-ietf-oauth-mtls-07 857 o Update to use the boilerplate from RFC 8174 859 draft-ietf-oauth-mtls-06 861 o Add an appendix section describing the relationship of this 862 document to OAuth Token Binding as requested during the the 863 Singapore meeting https://datatracker.ietf.org/doc/minutes- 864 100-oauth/ 865 o Add an explicit note that the implicit flow is not supported for 866 obtaining certificate bound access tokens as discussed at the 867 Singapore meeting https://datatracker.ietf.org/doc/minutes- 868 100-oauth/ 869 o Add/incorporate text to the Security Considerations on Certificate 870 Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/ 871 V26070X-6OtbVSeUz_7W2k94vCo 872 o Changed the title to be more descriptive 873 o Move the Security Considerations section to before the IANA 874 Considerations 875 o Elaborated on certificate bound access tokens a bit more in the 876 Abstract 877 o Update draft-ietf-oauth-discovery reference to -08 879 draft-ietf-oauth-mtls-05 881 o Editorial fixes 883 draft-ietf-oauth-mtls-04 885 o Change the name of the 'Public Key method' to the more accurate 886 'Self-Signed Certificate method' and also change the associated 887 authentication method metadata value to 888 "self_signed_tls_client_auth". 890 o Removed the "tls_client_auth_root_dn" client metadata field as 891 discussed in https://mailarchive.ietf.org/arch/msg/oauth/ 892 swDV2y0be6o8czGKQi1eJV-g8qc 893 o Update draft-ietf-oauth-discovery reference to -07 894 o Clarify that MTLS client authentication isn't exclusive to the 895 token endpoint and can be used with other endpoints, e.g. RFC 896 7009 revocation and 7662 introspection, that utilize client 897 authentication as discussed in 898 https://mailarchive.ietf.org/arch/msg/oauth/ 899 bZ6mft0G7D3ccebhOxnEYUv4puI 900 o Reorganize the document somewhat in an attempt to more clearly 901 make a distinction between mTLS client authentication and 902 certificate bound access tokens as well as a more clear 903 delineation between the two (PKI/Public key) methods for client 904 authentication 905 o Editorial fixes and clarifications 907 draft-ietf-oauth-mtls-03 909 o Introduced metadata and client registration parameter to publish 910 and request support for mutual TLS sender constrained access 911 tokens 912 o Added description of two methods of binding the cert and client, 913 PKI and Public Key. 914 o Indicated that the "tls_client_auth" authentication method is for 915 the PKI method and introduced "pub_key_tls_client_auth" for the 916 Public Key method 917 o Added implementation considerations, mainly regarding TLS stack 918 configuration and trust chain validation, as well as how to to do 919 binding of access tokens to a TLS client certificate for public 920 clients, and considerations around certificate bound access tokens 921 o Added new section to security considerations on cert spoofing 922 o Add text suggesting that a new cnf member be defined in the 923 future, if hash function(s) other than SHA-256 need to be used for 924 certificate thumbprints 926 draft-ietf-oauth-mtls-02 928 o Fixed editorial issue https://mailarchive.ietf.org/arch/msg/oauth/ 929 U46UMEh8XIOQnvXY9pHFq1MKPns 930 o Changed the title (hopefully "Mutual TLS Profile for OAuth 2.0" is 931 better than "Mutual TLS Profiles for OAuth Clients"). 933 draft-ietf-oauth-mtls-01 935 o Added more explicit details of using RFC 7662 token introspection 936 with mutual TLS sender constrained access tokens. 938 o Added an IANA OAuth Token Introspection Response Registration 939 request for "cnf". 940 o Specify that tls_client_auth_subject_dn and 941 tls_client_auth_root_dn are RFC 4514 String Representation of 942 Distinguished Names. 943 o Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn. 944 o Changed the text in the Section 3 to not be specific about using a 945 hash of the cert. 946 o Changed the abbreviated title to 'OAuth Mutual TLS' (previously 947 was the acronym MTLSPOC). 949 draft-ietf-oauth-mtls-00 951 o Created the initial working group version from draft-campbell- 952 oauth-mtls 954 draft-campbell-oauth-mtls-01 956 o Fix some typos. 957 o Add to the acknowledgements list. 959 draft-campbell-oauth-mtls-00 961 o Add a Mutual TLS sender constrained protected resource access 962 method and a x5t#S256 cnf method for JWT access tokens (concepts 963 taken in part from draft-sakimura-oauth-jpop-04). 964 o Fixed "token_endpoint_auth_methods_supported" to 965 "token_endpoint_auth_method" for client metadata. 966 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 967 client metadata parameters and mention using "jwks_uri" or "jwks". 968 o Say that the authentication method is determined by client policy 969 regardless of whether the client was dynamically registered or 970 statically configured. 971 o Expand acknowledgements to those that participated in discussions 972 around draft-campbell-oauth-tls-client-auth-00 973 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 975 draft-campbell-oauth-tls-client-auth-00 977 o Initial draft. 979 Authors' Addresses 981 Brian Campbell 982 Ping Identity 984 Email: brian.d.campbell@gmail.com 985 John Bradley 986 Yubico 988 Email: ve7jtb@ve7jtb.com 989 URI: http://www.thread-safe.com/ 991 Nat Sakimura 992 Nomura Research Institute 994 Email: n-sakimura@nri.co.jp 995 URI: https://nat.sakimura.org/ 997 Torsten Lodderstedt 998 YES Europe AG 1000 Email: torsten@lodderstedt.net