idnits 2.17.1 draft-ietf-oauth-mtls-08.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 (May 6, 2018) is 2181 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: November 7, 2018 Yubico 6 N. Sakimura 7 Nomura Research Institute 8 T. Lodderstedt 9 YES Europe AG 10 May 6, 2018 12 OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access 13 Tokens 14 draft-ietf-oauth-mtls-08 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 sever using mutual 22 TLS, based on either single certificates or public key infrastructure 23 (PKI). OAuth authorization servers are provided a mechanism for 24 binding access tokens to a client's mutual TLS certificate, and OAuth 25 protected resources are provided a method for ensuring that such an 26 access token presented to it was issued to the client presenting the 27 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 November 7, 2018. 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 . . . . . . . . . . . . . . . . . 15 101 Appendix A. Relationship to Token Binding . . . . . . . . . . . 17 102 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 17 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 sever 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 the 119 definition and use of additional client authentication mechanisms 120 when interacting directly with the authorization server. This 121 document describes an additional mechanism of client authentication 122 utilizing mutual TLS certificate-based authentication, which provides 123 better 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 the OAuth client will use in 233 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. Implementation security 529 considerations for TLS, including version recommendations, can be 530 found in Recommendations for Secure Use of Transport Layer Security 531 (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 533 5.2. X.509 Certificate Spoofing 535 If the PKI method of client authentication is used, an attacker could 536 try to impersonate a client using a certificate with the same subject 537 DN but issued by a different CA, which the authorization server 538 trusts. To cope with that threat, the authorization server should 539 only accept as trust anchors a limited number of CAs whose 540 certificate issuance policy meets its security requirements. There 541 is an assumption then that the client and server agree on the set of 542 trust anchors that the server uses to create and validate the 543 certificate chain. Without this assumption the use of a Subject DN 544 to identify the client certificate would open the server up to 545 certificate spoofing attacks. 547 5.3. X.509 Certificate Parsing and Validation Complexity 549 Parsing and validation of X.509 certificates and certificate chains 550 is complex and implementation mistakes have previously exposed 551 security vulnerabilities. Complexities of validation include (but 552 are not limited to) [X509Pitfalls] [DangerousCode] [RFC5280]: 554 o checking of Basic Constraints, basic and extended Key Usage 555 constraints, validity periods, and critical extensions; 557 o handling of null-terminator bytes and non-canonical string 558 representations in subject names; 560 o handling of wildcard patterns in subject names; 561 o recursive verification of certificate chains and checking 562 certificate revocation. 564 For these reasons, implementors SHOULD use an established and well- 565 tested X.509 library (such as one used by an established TLS library) 566 for validation of X.509 certificate chains and SHOULD NOT attempt to 567 write their own X.509 certificate validation procedures. 569 6. IANA Considerations 571 6.1. JWT Confirmation Methods Registration 573 This specification requests registration of the following value in 574 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 575 JWT "cnf" member values established by [RFC7800]. 577 o Confirmation Method Value: "x5t#S256" 578 o Confirmation Method Description: X.509 Certificate SHA-256 579 Thumbprint 580 o Change Controller: IESG 581 o Specification Document(s): Section 3.1 of [[ this specification ]] 583 6.2. OAuth Authorization Server Metadata Registration 585 This specification requests registration of the following value in 586 the IANA "OAuth Authorization Server Metadata" registry 587 [IANA.OAuth.Parameters] established by [I-D.ietf-oauth-discovery]. 589 o Metadata Name: "tls_client_certificate_bound_access_tokens" 590 o Metadata Description: Indicates authorization server support for 591 mutual TLS client certificate bound access tokens. 592 o Change Controller: IESG 593 o Specification Document(s): Section 3.3 of [[ this specification ]] 595 6.3. Token Endpoint Authentication Method Registration 597 This specification requests registration of the following value in 598 the IANA "OAuth Token Endpoint Authentication Methods" registry 599 [IANA.OAuth.Parameters] established by [RFC7591]. 601 o Token Endpoint Authentication Method Name: "tls_client_auth" 602 o Change Controller: IESG 603 o Specification Document(s): Section 2.1.1 of [[ this specification 604 ]] 606 o Token Endpoint Authentication Method Name: 607 "self_signed_tls_client_auth" 608 o Change Controller: IESG 609 o Specification Document(s): Section 2.2.1 of [[ this specification 610 ]] 612 6.4. OAuth Token Introspection Response Registration 614 This specification requests registration of the following value in 615 the IANA "OAuth Token Introspection Response" registry 616 [IANA.OAuth.Parameters] established by [RFC7662]. 618 o Claim Name: "cnf" 619 o Claim Description: Confirmation 620 o Change Controller: IESG 621 o Specification Document(s): Section 3.2 of [[ this specification ]] 623 6.5. OAuth Dynamic Client Registration Metadata Registration 625 This specification requests registration of the following client 626 metadata definitions in the IANA "OAuth Dynamic Client Registration 627 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 629 o Client Metadata Name: "tls_client_certificate_bound_access_tokens" 630 o Client Metadata Description: Indicates the client's intention to 631 use mutual TLS client certificate bound access tokens. 632 o Change Controller: IESG 633 o Specification Document(s): Section 3.4 of [[ this specification ]] 635 o Client Metadata Name: "tls_client_auth_subject_dn" 636 o Client Metadata Description: String value specifying the expected 637 subject distinguished name of the client certificate. 638 o Change Controller: IESG 639 o Specification Document(s): Section 2.1.2 of [[ this specification 640 ]] 642 7. References 644 7.1. Normative References 646 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 647 "Recommendations for Secure Use of Transport Layer 648 Security (TLS) and Datagram Transport Layer Security 649 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 650 2015, . 652 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 653 Requirement Levels", BCP 14, RFC 2119, 654 DOI 10.17487/RFC2119, March 1997, 655 . 657 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 658 (LDAP): String Representation of Distinguished Names", 659 RFC 4514, DOI 10.17487/RFC4514, June 2006, 660 . 662 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 663 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 664 . 666 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 667 (TLS) Protocol Version 1.2", RFC 5246, 668 DOI 10.17487/RFC5246, August 2008, 669 . 671 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 672 Housley, R., and W. Polk, "Internet X.509 Public Key 673 Infrastructure Certificate and Certificate Revocation List 674 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 675 . 677 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 678 RFC 6749, DOI 10.17487/RFC6749, October 2012, 679 . 681 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 682 Framework: Bearer Token Usage", RFC 6750, 683 DOI 10.17487/RFC6750, October 2012, 684 . 686 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 687 Possession Key Semantics for JSON Web Tokens (JWTs)", 688 RFC 7800, DOI 10.17487/RFC7800, April 2016, 689 . 691 [SHS] National Institute of Standards and Technology, "Secure 692 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 693 . 696 7.2. Informative References 698 [DangerousCode] 699 Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 700 D., and V. Shmatikov, "The Most Dangerous Code in the 701 World: Validating SSL Certificates in Non-Browser 702 Software", 703 . 705 [I-D.ietf-oauth-discovery] 706 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 707 Authorization Server Metadata", draft-ietf-oauth- 708 discovery-10 (work in progress), March 2018. 710 [I-D.ietf-oauth-token-binding] 711 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 712 "OAuth 2.0 Token Binding", draft-ietf-oauth-token- 713 binding-06 (work in progress), March 2018. 715 [IANA.JWT.Claims] 716 IANA, "JSON Web Token Claims", 717 . 719 [IANA.OAuth.Parameters] 720 IANA, "OAuth Parameters", 721 . 723 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 724 (LDAP): Syntaxes and Matching Rules", RFC 4517, 725 DOI 10.17487/RFC4517, June 2006, 726 . 728 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 729 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 730 August 2013, . 732 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 733 DOI 10.17487/RFC7517, May 2015, 734 . 736 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 737 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 738 . 740 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 741 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 742 RFC 7591, DOI 10.17487/RFC7591, July 2015, 743 . 745 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 746 RFC 7662, DOI 10.17487/RFC7662, October 2015, 747 . 749 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 750 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 751 May 2017, . 753 [X509Pitfalls] 754 Wong, D., "Common x509 certificate validation/creation 755 pitfalls", September 2016, 756 . 759 Appendix A. Relationship to Token Binding 761 OAuth 2.0 Token Binding [I-D.ietf-oauth-token-binding] enables the 762 application of Token Binding to the various artifacts and tokens 763 employed throughout OAuth. That includes binding of an access token 764 to a Token Binding key, which bears some similarities in motivation 765 and design to the mutual TLS client certificate bound access tokens 766 defined in this document. Both documents define what is often called 767 a proof-of-possession security mechanism for access tokens, whereby a 768 client must demonstrate possession of cryptographic keying material 769 when accessing a protected resource. The details differ somewhat 770 between the two documents but both have the authorization server bind 771 the access token that it issues to an asymmetric key pair held by the 772 client. The client then proves possession of the private key from 773 that pair with respect to the TLS connection over which the protected 774 resource is accessed. 776 Token Binding uses bare keys that are generated on the client, which 777 avoids many of the difficulties of creating, distributing, and 778 managing certificates used in this specification. However, at the 779 time of writing, Token Binding is fairly new and there is relatively 780 little support for it in available application development platforms 781 and tooling. Until better support for the underlying core Token 782 Binding specifications exists, practical implementations of OAuth 2.0 783 Token Binding are infeasible. Mutual TLS, on the other hand, has 784 been around for some time and enjoys widespread support in web 785 servers and development platforms. As a consequence, OAuth 2.0 786 Mutual TLS Client Authentication and Certificate Bound Access Tokens 787 can be built and deployed now using existing platforms and tools. In 788 the future, the two specifications are likely to be deployed in 789 parallel for solving similar problems in different environments. 790 Authorization servers may even support both specifications 791 simultaneously using different proof-of-possession mechanisms for 792 tokens issued to different clients. 794 Appendix B. Acknowledgements 796 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in 797 design and development work on a mutual TLS OAuth client 798 authentication implementation, which predates this document. 799 Experience and learning from that work informed some of the content 800 of this document. 802 Additionally, the authors would like to thank the following people 803 for their input and contributions to the specification: Sergey 804 Beryozkin, Vladimir Dzhuvinov, Samuel Erdtman, Leif Johansson, 805 Michael Jones, Phil Hunt, Benjamin Kaduk, Takahiko Kawasaki, Sean 806 Leonard, Kepeng Li, Neil Madden, James Manger, Jim Manico, Nov 807 Matake, Sascha Preibisch, Justin Richer, Dave Tonge, and Hannes 808 Tschofenig. 810 Appendix C. Document(s) History 812 [[ to be removed by the RFC Editor before publication as an RFC ]] 814 draft-ietf-oauth-mtls-08 816 o Incorporate clarifications and editorial improvements from Justin 817 Richer's WGLC review 818 o Drop the use of the "sender constrained" terminology per WGLC 819 feedback from Neil Madden (including changing the metadata 820 parameters from mutual_tls_sender_constrained_access_tokens to 821 tls_client_certificate_bound_access_tokens) 822 o Add a new security considerations section on X.509 parsing and 823 validation per WGLC feedback from Neil Madden and Benjamin Kaduk 824 o Note that a server can terminate TLS at a load balancer, reverse 825 proxy, etc. but how the client certificate metadata is securely 826 communicated to the backend is out of scope per WGLC feedback 827 o Note that revocation checking is at the discretion of the AS per 828 WGLC feedback 829 o Editorial updates and clarifications 830 o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf- 831 oauth-token-binding to -06 832 o Add folks involved in WGLC feedback to the acknowledgements list 834 draft-ietf-oauth-mtls-07 836 o Update to use the boilerplate from RFC 8174 838 draft-ietf-oauth-mtls-06 840 o Add an appendix section describing the relationship of this 841 document to OAuth Token Binding as requested during the the 842 Singapore meeting https://datatracker.ietf.org/doc/minutes- 843 100-oauth/ 844 o Add an explicit note that the implicit flow is not supported for 845 obtaining certificate bound access tokens as discussed at the 846 Singapore meeting https://datatracker.ietf.org/doc/minutes- 847 100-oauth/ 849 o Add/incorporate text to the Security Considerations on Certificate 850 Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/ 851 V26070X-6OtbVSeUz_7W2k94vCo 852 o Changed the title to be more descriptive 853 o Move the Security Considerations section to before the IANA 854 Considerations 855 o Elaborated on certificate bound access tokens a bit more in the 856 Abstract 857 o Update draft-ietf-oauth-discovery reference to -08 859 draft-ietf-oauth-mtls-05 861 o Editorial fixes 863 draft-ietf-oauth-mtls-04 865 o Change the name of the 'Public Key method' to the more accurate 866 'Self-Signed Certificate method' and also change the associated 867 authentication method metadata value to 868 "self_signed_tls_client_auth". 869 o Removed the "tls_client_auth_root_dn" client metadata field as 870 discussed in https://mailarchive.ietf.org/arch/msg/oauth/ 871 swDV2y0be6o8czGKQi1eJV-g8qc 872 o Update draft-ietf-oauth-discovery reference to -07 873 o Clarify that MTLS client authentication isn't exclusive to the 874 token endpoint and can be used with other endpoints, e.g. RFC 875 7009 revocation and 7662 introspection, that utilize client 876 authentication as discussed in 877 https://mailarchive.ietf.org/arch/msg/oauth/ 878 bZ6mft0G7D3ccebhOxnEYUv4puI 879 o Reorganize the document somewhat in an attempt to more clearly 880 make a distinction between mTLS client authentication and 881 certificate bound access tokens as well as a more clear 882 delineation between the two (PKI/Public key) methods for client 883 authentication 884 o Editorial fixes and clarifications 886 draft-ietf-oauth-mtls-03 888 o Introduced metadata and client registration parameter to publish 889 and request support for mutual TLS sender constrained access 890 tokens 891 o Added description of two methods of binding the cert and client, 892 PKI and Public Key. 893 o Indicated that the "tls_client_auth" authentication method is for 894 the PKI method and introduced "pub_key_tls_client_auth" for the 895 Public Key method 897 o Added implementation considerations, mainly regarding TLS stack 898 configuration and trust chain validation, as well as how to to do 899 binding of access tokens to a TLS client certificate for public 900 clients, and considerations around certificate bound access tokens 901 o Added new section to security considerations on cert spoofing 902 o Add text suggesting that a new cnf member be defined in the 903 future, if hash function(s) other than SHA-256 need to be used for 904 certificate thumbprints 906 draft-ietf-oauth-mtls-02 908 o Fixed editorial issue https://mailarchive.ietf.org/arch/msg/oauth/ 909 U46UMEh8XIOQnvXY9pHFq1MKPns 910 o Changed the title (hopefully "Mutual TLS Profile for OAuth 2.0" is 911 better than "Mutual TLS Profiles for OAuth Clients"). 913 draft-ietf-oauth-mtls-01 915 o Added more explicit details of using RFC 7662 token introspection 916 with mutual TLS sender constrained access tokens. 917 o Added an IANA OAuth Token Introspection Response Registration 918 request for "cnf". 919 o Specify that tls_client_auth_subject_dn and 920 tls_client_auth_root_dn are RFC 4514 String Representation of 921 Distinguished Names. 922 o Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn. 923 o Changed the text in the Section 3 to not be specific about using a 924 hash of the cert. 925 o Changed the abbreviated title to 'OAuth Mutual TLS' (previously 926 was the acronym MTLSPOC). 928 draft-ietf-oauth-mtls-00 930 o Created the initial working group version from draft-campbell- 931 oauth-mtls 933 draft-campbell-oauth-mtls-01 935 o Fix some typos. 936 o Add to the acknowledgements list. 938 draft-campbell-oauth-mtls-00 940 o Add a Mutual TLS sender constrained protected resource access 941 method and a x5t#S256 cnf method for JWT access tokens (concepts 942 taken in part from draft-sakimura-oauth-jpop-04). 943 o Fixed "token_endpoint_auth_methods_supported" to 944 "token_endpoint_auth_method" for client metadata. 946 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 947 client metadata parameters and mention using "jwks_uri" or "jwks". 948 o Say that the authentication method is determined by client policy 949 regardless of whether the client was dynamically registered or 950 statically configured. 951 o Expand acknowledgements to those that participated in discussions 952 around draft-campbell-oauth-tls-client-auth-00 953 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 955 draft-campbell-oauth-tls-client-auth-00 957 o Initial draft. 959 Authors' Addresses 961 Brian Campbell 962 Ping Identity 964 Email: brian.d.campbell@gmail.com 966 John Bradley 967 Yubico 969 Email: ve7jtb@ve7jtb.com 970 URI: http://www.thread-safe.com/ 972 Nat Sakimura 973 Nomura Research Institute 975 Email: n-sakimura@nri.co.jp 976 URI: https://nat.sakimura.org/ 978 Torsten Lodderstedt 979 YES Europe AG 981 Email: torsten@lodderstedt.net