idnits 2.17.00 (12 Aug 2021) /tmp/idnits58275/draft-ietf-oauth-mtls-17.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 == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (August 22, 2019) is 996 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 5246 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'X690' -- No information found for draft-ietf-oauth-token-binding - is the name correct? Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 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: February 23, 2020 Yubico 6 N. Sakimura 7 Nomura Research Institute 8 T. Lodderstedt 9 YES.com AG 10 August 22, 2019 12 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound 13 Access Tokens 14 draft-ietf-oauth-mtls-17 16 Abstract 18 This document describes OAuth client authentication and certificate- 19 bound access and refresh tokens using mutual Transport Layer Security 20 (TLS) authentication with X.509 certificates. OAuth clients are 21 provided a mechanism for authentication to the authorization server 22 using mutual TLS, based on either self-signed certificates or public 23 key 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 February 23, 2020. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Requirements Notation and Conventions . . . . . . . . . . 5 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 66 2. Mutual TLS for OAuth Client Authentication . . . . . . . . . 5 67 2.1. PKI Mutual-TLS Method . . . . . . . . . . . . . . . . . . 6 68 2.1.1. PKI Method Metadata Value . . . . . . . . . . . . . . 7 69 2.1.2. Client Registration Metadata . . . . . . . . . . . . 7 70 2.2. Self-Signed Certificate Mutual-TLS Method . . . . . . . . 8 71 2.2.1. Self-Signed Method Metadata Value . . . . . . . . . . 8 72 2.2.2. Client Registration Metadata . . . . . . . . . . . . 8 73 3. Mutual-TLS Client Certificate-Bound Access Tokens . . . . . . 9 74 3.1. JWT Certificate Thumbprint Confirmation Method . . . . . 10 75 3.2. Confirmation Method for Token Introspection . . . . . . . 11 76 3.3. Authorization Server Metadata . . . . . . . . . . . . . . 12 77 3.4. Client Registration Metadata . . . . . . . . . . . . . . 12 78 4. Public Clients and Certificate-Bound Tokens . . . . . . . . . 13 79 5. Metadata for Mutual-TLS Endpoint Aliases . . . . . . . . . . 13 80 6. Implementation Considerations . . . . . . . . . . . . . . . . 15 81 6.1. Authorization Server . . . . . . . . . . . . . . . . . . 15 82 6.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 16 83 6.3. Certificate Expiration and Bound Access Tokens . . . . . 16 84 6.4. Implicit Grant Unsupported . . . . . . . . . . . . . . . 16 85 6.5. TLS Termination . . . . . . . . . . . . . . . . . . . . . 17 86 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 87 7.1. Certificate-Bound Refresh Tokens . . . . . . . . . . . . 17 88 7.2. Certificate Thumbprint Binding . . . . . . . . . . . . . 17 89 7.3. TLS Versions and Best Practices . . . . . . . . . . . . . 18 90 7.4. X.509 Certificate Spoofing . . . . . . . . . . . . . . . 18 91 7.5. X.509 Certificate Parsing and Validation Complexity . . . 18 92 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 19 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 94 9.1. JWT Confirmation Methods Registration . . . . . . . . . . 19 95 9.2. Authorization Server Metadata Registration . . . . . . . 19 96 9.3. Token Endpoint Authentication Method Registration . . . . 20 97 9.4. Token Introspection Response Registration . . . . . . . . 20 98 9.5. Dynamic Client Registration Metadata Registration . . . . 21 99 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 100 10.1. Normative References . . . . . . . . . . . . . . . . . . 22 101 10.2. Informative References . . . . . . . . . . . . . . . . . 24 102 Appendix A. Example "cnf" Claim, Certificate and JWK . . . . . . 25 103 Appendix B. Relationship to Token Binding . . . . . . . . . . . 26 104 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 26 105 Appendix D. Document(s) History . . . . . . . . . . . . . . . . 27 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 108 1. Introduction 110 The OAuth 2.0 Authorization Framework [RFC6749] enables third-party 111 client applications to obtain delegated access to protected 112 resources. In the prototypical abstract OAuth flow, illustrated in 113 Figure 1, the client obtains an access token from an entity known as 114 an authorization server and then uses that token when accessing 115 protected resources, such as HTTPS APIs. 117 +--------+ +---------------+ 118 | | | | 119 | |<--(A)-- Get an access token --->| Authorization | 120 | | | Server | 121 | | | | 122 | | +---------------+ 123 | | ^ 124 | | | 125 | | 126 | | (C) | 127 | Client | Validate the 128 | | access token | 129 | | 130 | | | 131 | | v 132 | | +---------------+ 133 | | | (C) | 134 | | | | 135 | |<--(B)-- Use the access token -->| Protected | 136 | | | Resource | 137 | | | | 138 +--------+ +---------------+ 140 Figure 1: Abstract OAuth 2.0 Protocol Flow 142 The flow illustrated in Figure 1 includes the following steps: 144 (A) The client makes an HTTPS "POST" request to the authorization 145 server and presents a credential representing the authorization 146 grant. For certain types of clients (those that have been 147 issued or otherwise established a set of client credentials) the 148 request must be authenticated. In the response, the 149 authorization server issues an access token to the client. 151 (B) The client includes the access token when making a request to 152 access a protected resource. 154 (C) The protected resource validates the access token in order to 155 authorize the request. In some cases, such as when the token is 156 self-contained and cryptographically secured, the validation can 157 be done locally by the protected resource. Other cases require 158 that the protected resource call out to the authorization server 159 to determine the state of the token and obtain meta-information 160 about it. 162 Layering on the abstract flow above, this document standardizes 163 enhanced security options for OAuth 2.0 utilizing client-certificate- 164 based mutual TLS. Section 2 provides options for authenticating the 165 request in step (A). Step (C) is supported with semantics to express 166 the binding of the token to the client certificate for both local and 167 remote processing in Section 3.1 and Section 3.2 respectively. This 168 ensures that, as described in Section 3, protected resource access in 169 step (B) is only possible by the legitimate client using a 170 certificate-bound token and holding the private key corresponding to 171 the certificate. 173 OAuth 2.0 defines a shared-secret method of client authentication but 174 also allows for definition and use of additional client 175 authentication mechanisms when interacting directly with the 176 authorization server. This document describes an additional 177 mechanism of client authentication utilizing mutual-TLS certificate- 178 based authentication, which provides better security characteristics 179 than shared secrets. While [RFC6749] documents client authentication 180 for requests to the token endpoint, extensions to OAuth 2.0 (such as 181 Introspection [RFC7662], Revocation [RFC7009], and the Backchannel 182 Authentication Endpoint in [OpenID.CIBA]) define endpoints that also 183 utilize client authentication and the mutual TLS methods defined 184 herein are applicable to those endpoints as well. 186 Mutual-TLS certificate-bound access tokens ensure that only the party 187 in possession of the private key corresponding to the certificate can 188 utilize the token to access the associated resources. Such a 189 constraint is sometimes referred to as key confirmation, proof-of- 190 possession, or holder-of-key and is unlike the case of the bearer 191 token described in [RFC6750], where any party in possession of the 192 access token can use it to access the associated resources. Binding 193 an access token to the client's certificate prevents the use of 194 stolen access tokens or replay of access tokens by unauthorized 195 parties. 197 Mutual-TLS certificate-bound access tokens and mutual-TLS client 198 authentication are distinct mechanisms, which are complementary but 199 don't necessarily need to be deployed or used together. 201 Additional client metadata parameters are introduced by this document 202 in support of certificate-bound access tokens and mutual-TLS client 203 authentication. The authorization server can obtain client metadata 204 via the Dynamic Client Registration Protocol [RFC7591], which defines 205 mechanisms for dynamically registering OAuth 2.0 client metadata with 206 authorization servers. Also the metadata defined by RFC7591, and 207 registered extensions to it, imply a general data model for clients 208 that is useful for authorization server implementations even when the 209 Dynamic Client Registration Protocol isn't in play. Such 210 implementations will typically have some sort of user interface 211 available for managing client configuration. 213 1.1. Requirements Notation and Conventions 215 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 216 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 217 "OPTIONAL" in this document are to be interpreted as described in BCP 218 14 [RFC2119] [RFC8174] when, and only when, they appear in all 219 capitals, as shown here. 221 1.2. Terminology 223 Throughout this document the term "mutual TLS" refers to the process 224 whereby, in addition to the normal TLS server authentication with a 225 certificate, a client presents its X.509 certificate and proves 226 possession of the corresponding private key to a server when 227 negotiating a TLS session. In contemporary versions of TLS [RFC8446] 228 [RFC5246] this requires that the client send the Certificate and 229 CertificateVerify messages during the handshake and for the server to 230 verify the CertificateVerify and Finished messages. 232 2. Mutual TLS for OAuth Client Authentication 234 This section defines, as an extension of OAuth 2.0, Section 2.3 235 [RFC6749], two distinct methods of using mutual-TLS X.509 client 236 certificates as client credentials. The requirement of mutual TLS 237 for client authentication is determined by the authorization server 238 based on policy or configuration for the given client (regardless of 239 whether the client was dynamically registered, statically configured, 240 or otherwise established). 242 In order to utilize TLS for OAuth client authentication, the TLS 243 connection between the client and the authorization server MUST have 244 been established or reestablished with mutual-TLS X.509 certificate 245 authentication (i.e. the Client Certificate and Certificate Verify 246 messages are sent during the TLS Handshake). 248 For all requests to the authorization server utilizing mutual-TLS 249 client authentication, the client MUST include the "client_id" 250 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 251 presence of the "client_id" parameter enables the authorization 252 server to easily identify the client independently from the content 253 of the certificate. The authorization server can locate the client 254 configuration using the client identifier and check the certificate 255 presented in the TLS Handshake against the expected credentials for 256 that client. The authorization server MUST enforce the binding 257 between client and certificate as described in either Section 2.1 or 258 Section 2.2 below. If no certificate is presented or that which is 259 presented doesn't match that which is expected for the given 260 "client_id", the authorization server returns a normal OAuth 2.0 261 error response per Section 5.2 of RFC6749 [RFC6749] with the 262 "invalid_client" error code to indicate failed client authentication. 264 2.1. PKI Mutual-TLS Method 266 The PKI (public key infrastructure) method of mutual-TLS OAuth client 267 authentication adheres to the way in which X.509 certificates are 268 traditionally used for authentication. It relies on a validated 269 certificate chain [RFC5280] and a single subject distinguished name 270 (DN) or a single subject alternative name (SAN) to authenticate the 271 client. Only one subject name value of any type is used for each 272 client. The TLS handshake is utilized to validate the client's 273 possession of the private key corresponding to the public key in the 274 certificate and to validate the corresponding certificate chain. The 275 client is successfully authenticated if the subject information in 276 the certificate matches the single expected subject configured or 277 registered for that particular client (note that a predictable 278 treatment of DN values, such as the distinguishedNameMatch rule from 279 [RFC4517], is needed in comparing the certificate's subject DN to the 280 client's registered DN). Revocation checking is possible with the 281 PKI method but if and how to check a certificate's revocation status 282 is a deployment decision at the discretion of the authorization 283 server. Clients can rotate their X.509 certificates without the need 284 to modify the respective authentication data at the authorization 285 server by obtaining a new certificate with the same subject from a 286 trusted certificate authority (CA). 288 2.1.1. PKI Method Metadata Value 290 For the PKI method of mutual-TLS client authentication, this 291 specification defines and registers the following authentication 292 method metadata value into the "OAuth Token Endpoint Authentication 293 Methods" registry [IANA.OAuth.Parameters]. 295 tls_client_auth 296 Indicates that client authentication to the authorization server 297 will occur with mutual TLS utilizing the PKI method of associating 298 a certificate to a client. 300 2.1.2. Client Registration Metadata 302 In order to convey the expected subject of the certificate, the 303 following metadata parameters are introduced for the OAuth 2.0 304 Dynamic Client Registration Protocol [RFC7591] in support of the PKI 305 method of mutual-TLS client authentication. A client using the 306 "tls_client_auth" authentication method MUST use exactly one of the 307 below metadata parameters to indicate the certificate subject value 308 that the authorization server is to expect when authenticating the 309 respective client. 311 tls_client_auth_subject_dn 312 An [RFC4514] string representation of the expected subject 313 distinguished name of the certificate, which the OAuth client will 314 use in mutual-TLS authentication. 316 tls_client_auth_san_dns 317 A string containing the value of an expected dNSName SAN entry in 318 the certificate, which the OAuth client will use in mutual-TLS 319 authentication. 321 tls_client_auth_san_uri 322 A string containing the value of an expected 323 uniformResourceIdentifier SAN entry in the certificate, which the 324 OAuth client will use in mutual-TLS authentication. 326 tls_client_auth_san_ip 327 A string representation of an IP address in either dotted decimal 328 notation (for IPv4) or colon-delimited hexadecimal (for IPv6, as 329 defined in [RFC5952]) that is expected to be present as an 330 iPAddress SAN entry in the certificate, which the OAuth client 331 will use in mutual-TLS authentication. Per section 8 of [RFC5952] 332 the IP address comparison of the value in this parameter and the 333 SAN entry in the certificate is to be done in binary format. 335 tls_client_auth_san_email 336 A string containing the value of an expected rfc822Name SAN entry 337 in the certificate, which the OAuth client will use in mutual-TLS 338 authentication. 340 2.2. Self-Signed Certificate Mutual-TLS Method 342 This method of mutual-TLS OAuth client authentication is intended to 343 support client authentication using self-signed certificates. As a 344 prerequisite, the client registers its X.509 certificates (using 345 "jwks" defined in [RFC7591]) or a reference to a trusted source for 346 its X.509 certificates (using "jwks_uri" from [RFC7591]) with the 347 authorization server. During authentication, TLS is utilized to 348 validate the client's possession of the private key corresponding to 349 the public key presented within the certificate in the respective TLS 350 handshake. In contrast to the PKI method, the client's certificate 351 chain is not validated by the server in this case. The client is 352 successfully authenticated if the certificate that it presented 353 during the handshake matches one of the certificates configured or 354 registered for that particular client. The Self-Signed Certificate 355 method allows the use of mutual TLS to authenticate clients without 356 the need to maintain a PKI. When used in conjunction with a 357 "jwks_uri" for the client, it also allows the client to rotate its 358 X.509 certificates without the need to change its respective 359 authentication data directly with the authorization server. 361 2.2.1. Self-Signed Method Metadata Value 363 For the Self-Signed Certificate method of mutual-TLS client 364 authentication, this specification defines and registers the 365 following authentication method metadata value into the "OAuth Token 366 Endpoint Authentication Methods" registry [IANA.OAuth.Parameters]. 368 self_signed_tls_client_auth 369 Indicates that client authentication to the authorization server 370 will occur using mutual TLS with the client utilizing a self- 371 signed certificate. 373 2.2.2. Client Registration Metadata 375 For the Self-Signed Certificate method of binding a certificate with 376 a client using mutual TLS client authentication, the existing 377 "jwks_uri" or "jwks" metadata parameters from [RFC7591] are used to 378 convey the client's certificates via JSON Web Key (JWK) in a JWK Set 379 (JWKS) [RFC7517]. The "jwks" metadata parameter is a JWK Set 380 containing the client's public keys as an array of JWKs while the 381 "jwks_uri" parameter is a URL that references a client's JWK Set. A 382 certificate is represented with the "x5c" parameter of an individual 383 JWK within the set. Note that the members of the JWK representing 384 the public key (e.g. "n" and "e" for RSA, "x" and "y" for EC) are 385 required parameters per [RFC7518] so will be present even though they 386 are not utilized in this context. Also note that that Section 4.7 of 387 [RFC7517] requires that the key in the first certificate of the "x5c" 388 parameter match the public key represented by those other members of 389 the JWK. 391 3. Mutual-TLS Client Certificate-Bound Access Tokens 393 When mutual TLS is used by the client on the connection to the token 394 endpoint, the authorization server is able to bind the issued access 395 token to the client certificate. Such a binding is accomplished by 396 associating the certificate with the token in a way that can be 397 accessed by the protected resource, such as embedding the certificate 398 hash in the issued access token directly, using the syntax described 399 in Section 3.1, or through token introspection as described in 400 Section 3.2. Binding the access token to the client certificate in 401 that fashion has the benefit of decoupling that binding from the 402 client's authentication with the authorization server, which enables 403 mutual TLS during protected resource access to serve purely as a 404 proof-of-possession mechanism. Other methods of associating a 405 certificate with an access token are possible, per agreement by the 406 authorization server and the protected resource, but are beyond the 407 scope of this specification. 409 In order for a resource server to use certificate-bound access 410 tokens, it must have advance knowledge that mutual TLS is to be used 411 for some or all resource accesses. In particular, the access token 412 itself cannot be used as input to the decision of whether or not to 413 request mutual TLS, since from the TLS perspective those are 414 "Application Data", only exchanged after the TLS handshake has been 415 completed, and the initial CertificateRequest occurs during the 416 handshake, before the Application Data is available. Although 417 subsequent opportunities for a TLS client to present a certificate 418 may be available, e.g., via TLS 1.2 renegotiation [RFC5246] or TLS 419 1.3 post-handshake authentication [RFC8446], this document makes no 420 provision for their usage. It is expected to be common that a 421 mutual-TLS-using resource server will require mutual TLS for all 422 resources hosted thereupon, or will serve mutual-TLS-protected and 423 regular resources on separate hostname+port combinations, though 424 other workflows are possible. How resource server policy is 425 synchronized with the AS is out of scope for this document. 427 Within the scope of an mutual-TLS-protected resource-access flow, the 428 client makes protected resource requests as described in [RFC6750], 429 however, those requests MUST be made over a mutually authenticated 430 TLS connection using the same certificate that was used for mutual 431 TLS at the token endpoint. 433 The protected resource MUST obtain, from its TLS implementation 434 layer, the client certificate used for mutual TLS and MUST verify 435 that the certificate matches the certificate associated with the 436 access token. If they do not match, the resource access attempt MUST 437 be rejected with an error per [RFC6750] using an HTTP 401 status code 438 and the "invalid_token" error code. 440 Metadata to convey server and client capabilities for mutual-TLS 441 client certificate-bound access tokens is defined in Section 3.3 and 442 Section 3.4 respectively. 444 3.1. JWT Certificate Thumbprint Confirmation Method 446 When access tokens are represented as JSON Web Tokens (JWT)[RFC7519], 447 the certificate hash information SHOULD be represented using the 448 "x5t#S256" confirmation method member defined herein. 450 To represent the hash of a certificate in a JWT, this specification 451 defines the new JWT Confirmation Method [RFC7800] member "x5t#S256" 452 for the X.509 Certificate SHA-256 Thumbprint. The value of the 453 "x5t#S256" member is a base64url-encoded [RFC4648] SHA-256 [SHS] hash 454 (a.k.a. thumbprint, fingerprint or digest) of the DER encoding [X690] 455 of the X.509 certificate [RFC5280]. The base64url-encoded value MUST 456 omit all trailing pad '=' characters and MUST NOT include any line 457 breaks, whitespace, or other additional characters. 459 The following is an example of a JWT payload containing an "x5t#S256" 460 certificate thumbprint confirmation method. The new JWT content 461 introduced by this specification is the "cnf" confirmation method 462 claim at the bottom of the example that has the "x5t#S256" 463 confirmation method member containing the value that is the hash of 464 the client certificate to which the access token is bound. 466 { 467 "iss": "https://server.example.com", 468 "sub": "ty.webb@example.com", 469 "exp": 1493726400, 470 "nbf": 1493722800, 471 "cnf":{ 472 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 473 } 474 } 476 Figure 2: Example JWT Claims Set with an X.509 Certificate Thumbprint 477 Confirmation Method 479 3.2. Confirmation Method for Token Introspection 481 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 482 protected resource to query an authorization server about the active 483 state of an access token as well as to determine meta-information 484 about the token. 486 For a mutual-TLS client certificate-bound access token, the hash of 487 the certificate to which the token is bound is conveyed to the 488 protected resource as meta-information in a token introspection 489 response. The hash is conveyed using the same "cnf" with "x5t#S256" 490 member structure as the certificate SHA-256 thumbprint confirmation 491 method, described in Section 3.1, as a top-level member of the 492 introspection response JSON. The protected resource compares that 493 certificate hash to a hash of the client certificate used for mutual- 494 TLS authentication and rejects the request, if they do not match. 496 The following is an example of an introspection response for an 497 active token with an "x5t#S256" certificate thumbprint confirmation 498 method. The new introspection response content introduced by this 499 specification is the "cnf" confirmation method at the bottom of the 500 example that has the "x5t#S256" confirmation method member containing 501 the value that is the hash of the client certificate to which the 502 access token is bound. 504 HTTP/1.1 200 OK 505 Content-Type: application/json 507 { 508 "active": true, 509 "iss": "https://server.example.com", 510 "sub": "ty.webb@example.com", 511 "exp": 1493726400, 512 "nbf": 1493722800, 513 "cnf":{ 514 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 515 } 516 } 518 Figure 3: Example Introspection Response for a Certificate-Bound 519 Access Token 521 3.3. Authorization Server Metadata 523 This document introduces the following new authorization server 524 metadata [RFC8414] parameter to signal the server's capability to 525 issue certificate bound access tokens: 527 tls_client_certificate_bound_access_tokens 528 OPTIONAL. Boolean value indicating server support for mutual-TLS 529 client certificate-bound access tokens. If omitted, the default 530 value is "false". 532 3.4. Client Registration Metadata 534 The following new client metadata parameter is introduced to convey 535 the client's intention to use certificate bound access tokens: 537 tls_client_certificate_bound_access_tokens 538 OPTIONAL. Boolean value used to indicate the client's intention 539 to use mutual-TLS client certificate-bound access tokens. If 540 omitted, the default value is "false". 542 Note that, if a client that has indicated the intention to use 543 mutual-TLS client certificate-bound tokens makes a request to the 544 token endpoint over a non-mutual-TLS connection, it is at the 545 authorization server's discretion as to whether to return an error or 546 issue an unbound token. 548 4. Public Clients and Certificate-Bound Tokens 550 Mutual-TLS OAuth client authentication and certificate-bound access 551 tokens can be used independently of each other. Use of certificate- 552 bound access tokens without mutual-TLS OAuth client authentication, 553 for example, is possible in support of binding access tokens to a TLS 554 client certificate for public clients (those without authentication 555 credentials associated with the "client_id"). The authorization 556 server would configure the TLS stack in the same manner as for the 557 Self-Signed Certificate method such that it does not verify that the 558 certificate presented by the client during the handshake is signed by 559 a trusted CA. Individual instances of a client would create a self- 560 signed certificate for mutual TLS with both the authorization server 561 and resource server. The authorization server would not use the 562 mutual-TLS certificate to authenticate the client at the OAuth layer 563 but would bind the issued access token to that certificate, for which 564 the client has proven possession of the corresponding private key. 565 The access token is then bound to the certificate and can only be 566 used by the client possessing the certificate and corresponding 567 private key and utilizing them to negotiate mutual TLS on connections 568 to the resource server. When the authorization server issues a 569 refresh token to such a client, it SHOULD also bind the refresh token 570 to the respective certificate. And check the binding when the 571 refresh token is presented to get new access tokens. The 572 implementation details of the binding the refresh token are at the 573 discretion of the authorization server. 575 5. Metadata for Mutual-TLS Endpoint Aliases 577 The process of negotiating client certificate-based mutual TLS 578 involves a TLS server requesting a certificate from the TLS client 579 (the client does not provide one unsolicited). Although a server can 580 be configured such that client certificates are optional, meaning 581 that the connection is allowed to continue when the client does not 582 provide a certificate, the act of a server requesting a certificate 583 can result in undesirable behavior from some clients. This is 584 particularly true of web browsers as TLS clients, which will 585 typically present the end-user with an intrusive certificate 586 selection interface when the server requests a certificate. 588 Authorization servers supporting both clients using mutual TLS and 589 conventional clients MAY chose to isolate the server side mutual-TLS 590 behavior to only clients intending to do mutual TLS, thus avoiding 591 any undesirable effects it might have on conventional clients. The 592 following authorization server metadata parameter is introduced to 593 facilitate such separation: 595 mtls_endpoint_aliases 596 OPTIONAL. A JSON object containing alternative authorization 597 server endpoints that, when present, an OAuth client intending to 598 do mutual TLS uses in preference to the conventional endpoints. 599 The parameter value itself consists of one or more endpoint 600 parameters, such as "token_endpoint", "revocation_endpoint", 601 "introspection_endpoint", etc., conventionally defined for the 602 top-level of authorization server metadata. An OAuth client 603 intending to do mutual TLS (for OAuth client authentication and/or 604 to acquire or use certificate-bound tokens) when making a request 605 directly to the authorization server MUST use the alias URL of the 606 endpoint within the "mtls_endpoint_aliases", when present, in 607 preference to the endpoint URL of the same name at top-level of 608 metadata. When an endpoint is not present in 609 "mtls_endpoint_aliases", then the client uses the conventional 610 endpoint URL defined at the top-level of the authorization server 611 metadata. Metadata parameters within "mtls_endpoint_aliases" that 612 do not define endpoints to which an OAuth client makes a direct 613 request have no meaning and SHOULD be ignored. 615 Below is an example of an authorization server metadata document with 616 the "mtls_endpoint_aliases" parameter, which indicates aliases for 617 the token, revocation, and introspection endpoints that an OAuth 618 client intending to do mutual TLS would in preference to the 619 conventional token, revocation, and introspection endpoints. Note 620 that the endpoints in "mtls_endpoint_aliases" use a different host 621 than their conventional counterparts, which allows the authorization 622 server (via TLS "server_name" extension [RFC6066] or actual distinct 623 hosts) to differentiate its TLS behavior as appropriate. 625 { 626 "issuer": "https://server.example.com", 627 "authorization_endpoint": "https://server.example.com/authz", 628 "token_endpoint": "https://server.example.com/token", 629 "introspection_endpoint": "https://server.example.com/introspect", 630 "revocation_endpoint": "https://server.example.com/revo", 631 "jwks_uri": "https://server.example.com/jwks", 632 "response_types_supported": ["code"], 633 "response_modes_supported": ["fragment","query","form_post"], 634 "grant_types_supported": ["authorization_code", "refresh_token"], 635 "token_endpoint_auth_methods_supported": 636 ["tls_client_auth","client_secret_basic","none"], 637 "tls_client_certificate_bound_access_tokens": true 638 "mtls_endpoint_aliases": { 639 "token_endpoint": "https://mtls.example.com/token", 640 "revocation_endpoint": "https://mtls.example.com/revo", 641 "introspection_endpoint": "https://mtls.example.com/introspect" 642 } 643 } 645 Figure 4: Example Authorization Server Metadata with Mutual-TLS 646 Endpoint Aliases 648 6. Implementation Considerations 650 6.1. Authorization Server 652 The authorization server needs to set up its TLS configuration 653 appropriately for the OAuth client authentication methods it 654 supports. 656 An authorization server that supports mutual-TLS client 657 authentication and other client authentication methods or public 658 clients in parallel would make mutual TLS optional (i.e. allowing a 659 handshake to continue after the server requests a client certificate 660 but the client does not send one). 662 In order to support the Self-Signed Certificate method alone, the 663 authorization server would configure the TLS stack in such a way that 664 it does not verify whether the certificate presented by the client 665 during the handshake is signed by a trusted CA certificate. 667 As described in Section 3, the authorization server binds the issued 668 access token to the TLS client certificate, which means that it will 669 only issue certificate-bound tokens for a certificate which the 670 client has proven possession of the corresponding private key. 672 The authorization server may also consider hosting the token 673 endpoint, and other endpoints requiring client authentication, on a 674 separate host name or port in order to prevent unintended impact on 675 the TLS behavior of its other endpoints, e.g. the authorization 676 endpoint. As described in Section 5, it may further isolate any 677 potential impact of the server requesting client certificates by 678 offering a distinct set of endpoints on a separate host or port, 679 which are aliases for the originals that a client intending to do 680 mutual TLS will use in preference to the conventional endpoints. 682 6.2. Resource Server 684 OAuth divides the roles and responsibilities such that the resource 685 server relies on the authorization server to perform client 686 authentication and obtain resource owner (end-user) authorization. 687 The resource server makes authorization decisions based on the access 688 token presented by the client but does not directly authenticate the 689 client per se. The manner in which an access token is bound to the 690 client certificate and how a protected resource verifies the proof- 691 of-possession decouples that from the specific method that the client 692 used to authenticate with the authorization server. Mutual TLS 693 during protected resource access can therefore serve purely as a 694 proof-of-possession mechanism. As such, it is not necessary for the 695 resource server to validate the trust chain of the client's 696 certificate in any of the methods defined in this document. The 697 resource server would therefore configure the TLS stack in a way that 698 it does not verify whether the certificate presented by the client 699 during the handshake is signed by a trusted CA certificate. 701 6.3. Certificate Expiration and Bound Access Tokens 703 As described in Section 3, an access token is bound to a specific 704 client certificate, which means that the same certificate must be 705 used for mutual TLS on protected resource access. It also implies 706 that access tokens are invalidated when a client updates the 707 certificate, which can be handled similar to expired access tokens 708 where the client requests a new access token (typically with a 709 refresh token) and retries the protected resource request. 711 6.4. Implicit Grant Unsupported 713 This document describes binding an access token to the client 714 certificate presented on the TLS connection from the client to the 715 authorization server's token endpoint, however, such binding of 716 access tokens issued directly from the authorization endpoint via the 717 implicit grant flow is explicitly out of scope. End users interact 718 directly with the authorization endpoint using a web browser and the 719 use of client certificates in user's browsers bring operational and 720 usability issues, which make it undesirable to support certificate- 721 bound access tokens issued in the implicit grant flow. 722 Implementations wanting to employ certificate-bound access tokens 723 should utilize grant types that involve the client making an access 724 token request directly to the token endpoint (e.g. the authorization 725 code and refresh token grant types). 727 6.5. TLS Termination 729 An authorization server or resource server MAY choose to terminate 730 TLS connections at a load balancer, reverse proxy, or other network 731 intermediary. How the client certificate metadata is securely 732 communicated between the intermediary and the application server in 733 this case is out of scope of this specification. 735 7. Security Considerations 737 7.1. Certificate-Bound Refresh Tokens 739 The OAuth 2.0 Authorization Framework [RFC6749] requires that an 740 authorization server bind refresh tokens to the client to which they 741 were issued and that confidential clients (those having established 742 authentication credentials with the authorization server) 743 authenticate to the AS when presenting a refresh token. As a result, 744 refresh tokens are indirectly certificate-bound by way of the client 745 ID and the associated requirement for (certificate-based) 746 authentication to the authorization server when issued to clients 747 utilizing the "tls_client_auth" or "self_signed_tls_client_auth" 748 methods of client authentication. Section 4 describes certificate- 749 bound refresh tokens issued to public clients (those without 750 authentication credentials associated with the "client_id"). 752 7.2. Certificate Thumbprint Binding 754 The binding between the certificate and access token specified in 755 Section 3.1 uses a cryptographic hash of the certificate. It relies 756 on the hash function having sufficient second-preimage resistance so 757 as to make it computationally infeasible to find or create another 758 certificate that produces to the same hash output value. The SHA-256 759 hash function was used because it meets the aforementioned 760 requirement while being widely available. If, in the future, 761 certificate thumbprints need to be computed using hash function(s) 762 other than SHA-256, it is suggested that additional related JWT 763 confirmation methods members be defined for that purpose and 764 registered in the IANA "JWT Confirmation Methods" registry 765 [IANA.JWT.Claims] for JWT "cnf" member values. 767 Community knowledge about the strength of various algorithms and 768 feasible attacks can change suddenly, and experience shows that a 769 document about security is a point-in-time statement. Readers are 770 advised to seek out any errata or updates that apply to this 771 document. 773 7.3. TLS Versions and Best Practices 775 In the abstract this document is applicable with any TLS version 776 supporting certificate-based client authentication. Both TLS 1.3 777 [RFC8446] and TLS 1.2 [RFC5246] are cited herein because, at the time 778 of writing, 1.3 is the newest version while 1.2 is the most widely 779 deployed. General implementation and security considerations for 780 TLS, including version recommendations, can be found in [BCP195]. 782 TLS certificate validation (for both client and server certificates) 783 requires a local database of trusted certificate authorities (CAs). 784 Decisions about what CAs to trust and how to make such a 785 determination of trust are out of scope for this document. 787 7.4. X.509 Certificate Spoofing 789 If the PKI method of client authentication is used, an attacker could 790 try to impersonate a client using a certificate with the same subject 791 (DN or SAN) but issued by a different CA, which the authorization 792 server trusts. To cope with that threat, the authorization server 793 SHOULD only accept as trust anchors a limited number of CAs whose 794 certificate issuance policy meets its security requirements. There 795 is an assumption then that the client and server agree out of band on 796 the set of trust anchors that the server uses to create and validate 797 the certificate chain. Without this assumption the use of a subject 798 to identify the client certificate would open the server up to 799 certificate spoofing attacks. 801 7.5. X.509 Certificate Parsing and Validation Complexity 803 Parsing and validation of X.509 certificates and certificate chains 804 is complex and implementation mistakes have previously exposed 805 security vulnerabilities. Complexities of validation include (but 806 are not limited to) [CX5P] [DCW] [RFC5280]: 808 o checking of Basic Constraints, basic and extended Key Usage 809 constraints, validity periods, and critical extensions; 811 o handling of embedded NUL bytes in ASN.1 counted-length strings, 812 and non-canonical or non-normalized string representations in 813 subject names; 815 o handling of wildcard patterns in subject names; 817 o recursive verification of certificate chains and checking 818 certificate revocation. 820 For these reasons, implementors SHOULD use an established and well- 821 tested X.509 library (such as one used by an established TLS library) 822 for validation of X.509 certificate chains and SHOULD NOT attempt to 823 write their own X.509 certificate validation procedures. 825 8. Privacy Considerations 827 In TLS versions prior to 1.3, the client's certificate is sent 828 unencrypted in the initial handshake and can potentially be used by 829 third parties to monitor, track, and correlate client activity. This 830 is likely of little concern for clients that act on behalf of a 831 significant number of end-users because individual user activity will 832 not be discernible amidst the client activity as a whole. However, 833 clients that act on behalf of a single end-user, such as a native 834 application on a mobile device, should use TLS version 1.3 whenever 835 possible or consider the potential privacy implications of using 836 mutual TLS on earlier versions. 838 9. IANA Considerations 840 9.1. JWT Confirmation Methods Registration 842 This specification requests registration of the following value in 843 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 844 JWT "cnf" member values established by [RFC7800]. 846 o Confirmation Method Value: "x5t#S256" 847 o Confirmation Method Description: X.509 Certificate SHA-256 848 Thumbprint 849 o Change Controller: IESG 850 o Specification Document(s): Section 3.1 of [[ this specification ]] 852 9.2. Authorization Server Metadata Registration 854 This specification requests registration of the following values in 855 the IANA "OAuth Authorization Server Metadata" registry 856 [IANA.OAuth.Parameters] established by [RFC8414]. 858 o Metadata Name: "tls_client_certificate_bound_access_tokens" 859 o Metadata Description: Indicates authorization server support for 860 mutual-TLS client certificate-bound access tokens. 861 o Change Controller: IESG 862 o Specification Document(s): Section 3.3 of [[ this specification ]] 863 o Metadata Name: "mtls_endpoint_aliases" 864 o Metadata Description: JSON object containing alternative 865 authorization server endpoints, which a client intending to do 866 mutual TLS will use in preference to the conventional endpoints. 867 o Change Controller: IESG 868 o Specification Document(s): Section 5 of [[ this specification ]] 870 9.3. Token Endpoint Authentication Method Registration 872 This specification requests registration of the following values in 873 the IANA "OAuth Token Endpoint Authentication Methods" registry 874 [IANA.OAuth.Parameters] established by [RFC7591]. 876 o Token Endpoint Authentication Method Name: "tls_client_auth" 877 o Change Controller: IESG 878 o Specification Document(s): Section 2.1.1 of [[ this specification 879 ]] 881 o Token Endpoint Authentication Method Name: 882 "self_signed_tls_client_auth" 883 o Change Controller: IESG 884 o Specification Document(s): Section 2.2.1 of [[ this specification 885 ]] 887 9.4. Token Introspection Response Registration 889 Proof-of-Possession Key Semantics for JSON Web Tokens [RFC7800] 890 defined the "cnf" (confirmation) claim, which enables confirmation 891 key information to be carried in a JWT. However, the same proof-of- 892 possession semantics are also useful for introspected access tokens 893 whereby the protected resource obtains the confirmation key data as 894 meta-information of a token introspection response and uses that 895 information in verifying proof-of-possession. Therefore this 896 specification defines and registers proof-of-possession semantics for 897 OAuth 2.0 Token Introspection [RFC7662] using the "cnf" structure. 898 When included as a top-level member of an OAuth token introspection 899 response, "cnf" has the same semantics and format as the claim of the 900 same name defined in [RFC7800]. While this specification only 901 explicitly uses the "x5t#S256" confirmation method member (see 902 Section 3.2), it needs to define and register the higher level "cnf" 903 structure as an introspection response member in order to define and 904 use the more specific certificate thumbprint confirmation method. 906 As such, this specification requests registration of the following 907 value in the IANA "OAuth Token Introspection Response" registry 908 [IANA.OAuth.Parameters] established by [RFC7662]. 910 o Claim Name: "cnf" 911 o Claim Description: Confirmation 912 o Change Controller: IESG 913 o Specification Document(s): [RFC7800] and [[ this specification ]] 915 9.5. Dynamic Client Registration Metadata Registration 917 This specification requests registration of the following client 918 metadata definitions in the IANA "OAuth Dynamic Client Registration 919 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 921 o Client Metadata Name: "tls_client_certificate_bound_access_tokens" 922 o Client Metadata Description: Indicates the client's intention to 923 use mutual-TLS client certificate-bound access tokens. 924 o Change Controller: IESG 925 o Specification Document(s): Section 3.4 of [[ this specification ]] 927 o Client Metadata Name: "tls_client_auth_subject_dn" 928 o Client Metadata Description: String value specifying the expected 929 subject DN of the client certificate. 930 o Change Controller: IESG 931 o Specification Document(s): Section 2.1.2 of [[ this specification 932 ]] 934 o Client Metadata Name: "tls_client_auth_san_dns" 935 o Client Metadata Description: String value specifying the expected 936 dNSName SAN entry in the client certificate. 937 o Change Controller: IESG 938 o Specification Document(s): Section 2.1.2 of [[ this specification 939 ]] 941 o Client Metadata Name: "tls_client_auth_san_uri" 942 o Client Metadata Description: String value specifying the expected 943 uniformResourceIdentifier SAN entry in the client certificate. 944 o Change Controller: IESG 945 o Specification Document(s): Section 2.1.2 of [[ this specification 946 ]] 948 o Client Metadata Name: "tls_client_auth_san_ip" 949 o Client Metadata Description: String value specifying the expected 950 iPAddress SAN entry in the client certificate. 951 o Change Controller: IESG 952 o Specification Document(s): Section 2.1.2 of [[ this specification 953 ]] 955 o Client Metadata Name: "tls_client_auth_san_email" 956 o Client Metadata Description: String value specifying the expected 957 rfc822Name SAN entry in the client certificate. 958 o Change Controller: IESG 959 o Specification Document(s): Section 2.1.2 of [[ this specification 960 ]] 962 10. References 964 10.1. Normative References 966 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 967 "Recommendations for Secure Use of Transport Layer 968 Security (TLS) and Datagram Transport Layer Security 969 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 970 2015, . 972 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 973 Requirement Levels", BCP 14, RFC 2119, 974 DOI 10.17487/RFC2119, March 1997, 975 . 977 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 978 (LDAP): String Representation of Distinguished Names", 979 RFC 4514, DOI 10.17487/RFC4514, June 2006, 980 . 982 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 983 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 984 . 986 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 987 (TLS) Protocol Version 1.2", RFC 5246, 988 DOI 10.17487/RFC5246, August 2008, 989 . 991 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 992 Housley, R., and W. Polk, "Internet X.509 Public Key 993 Infrastructure Certificate and Certificate Revocation List 994 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 995 . 997 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 998 RFC 6749, DOI 10.17487/RFC6749, October 2012, 999 . 1001 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1002 Framework: Bearer Token Usage", RFC 6750, 1003 DOI 10.17487/RFC6750, October 2012, 1004 . 1006 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1007 DOI 10.17487/RFC7517, May 2015, 1008 . 1010 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1011 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 1012 . 1014 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 1015 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 1016 RFC 7591, DOI 10.17487/RFC7591, July 2015, 1017 . 1019 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 1020 RFC 7662, DOI 10.17487/RFC7662, October 2015, 1021 . 1023 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 1024 Possession Key Semantics for JSON Web Tokens (JWTs)", 1025 RFC 7800, DOI 10.17487/RFC7800, April 2016, 1026 . 1028 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1029 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1030 May 2017, . 1032 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 1033 Authorization Server Metadata", RFC 8414, 1034 DOI 10.17487/RFC8414, June 2018, 1035 . 1037 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1038 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1039 . 1041 [SHS] National Institute of Standards and Technology, "Secure 1042 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 1043 . 1046 [X690] International Telephone and Telegraph Consultative 1047 Committee, "ASN.1 encoding rules: Specification of basic 1048 encoding Rules (BER), Canonical encoding rules (CER) and 1049 Distinguished encoding rules (DER)", CCITT Recommendation 1050 X.690, July 2015. 1052 10.2. Informative References 1054 [CX5P] Wong, D., "Common x509 certificate validation/creation 1055 pitfalls", September 2016, 1056 . 1059 [DCW] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 1060 D., and V. Shmatikov, "The Most Dangerous Code in the 1061 World: Validating SSL Certificates in Non-Browser 1062 Software", 1063 . 1065 [I-D.ietf-oauth-token-binding] 1066 Jones, M., Campbell, B., Bradley, J., and W. Denniss, 1067 "OAuth 2.0 Token Binding", draft-ietf-oauth-token- 1068 binding-06 (work in progress), March 2018. 1070 [IANA.JWT.Claims] 1071 IANA, "JSON Web Token Claims", 1072 . 1074 [IANA.OAuth.Parameters] 1075 IANA, "OAuth Parameters", 1076 . 1078 [OpenID.CIBA] 1079 Fernandez, G., Walter, F., Nennker, A., Tonge, D., and B. 1080 Campbell, "OpenID Connect Client Initiated Backchannel 1081 Authentication Flow - Core 1.0", January 2019, 1082 . 1085 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol 1086 (LDAP): Syntaxes and Matching Rules", RFC 4517, 1087 DOI 10.17487/RFC4517, June 2006, 1088 . 1090 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1091 Address Text Representation", RFC 5952, 1092 DOI 10.17487/RFC5952, August 2010, 1093 . 1095 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1096 Extensions: Extension Definitions", RFC 6066, 1097 DOI 10.17487/RFC6066, January 2011, 1098 . 1100 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 1101 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 1102 August 2013, . 1104 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1105 DOI 10.17487/RFC7518, May 2015, 1106 . 1108 Appendix A. Example "cnf" Claim, Certificate and JWK 1110 For reference, an "x5t#S256" value and the X.509 Certificate from 1111 which it was calculated are provided in the following examples, 1112 Figure 5 and Figure 6 respectively. A JWK representation of the 1113 certificate's public key along with the "x5c" member is also provided 1114 in Figure 7. 1116 "cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"} 1118 Figure 5: x5t#S256 Confirmation Claim 1120 -----BEGIN CERTIFICATE----- 1121 MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx 1122 ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG 1123 SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ 1124 /Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID 1125 SQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2eXZOV 1126 bUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY= 1127 -----END CERTIFICATE----- 1129 Figure 6: PEM Encoded Self-Signed Certificate 1131 { 1132 "kty":"EC", 1133 "x":"1yfLHCpXqFjxCeHHHMVDTcLscpb07KUxudBmOMn8C7Q", 1134 "y":"8_coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8", 1135 "crv":"P-256", 1136 "x5c":[ 1137 "MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTA 1138 xODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGBy 1139 qGSM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZ 1140 jjJ/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0E 1141 AwIDSQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2 1142 eXZOVbUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY=" 1143 ] 1144 } 1146 Figure 7: JSON Web Key 1148 Appendix B. Relationship to Token Binding 1150 OAuth 2.0 Token Binding [I-D.ietf-oauth-token-binding] enables the 1151 application of Token Binding to the various artifacts and tokens 1152 employed throughout OAuth. That includes binding of an access token 1153 to a Token Binding key, which bears some similarities in motivation 1154 and design to the mutual-TLS client certificate-bound access tokens 1155 defined in this document. Both documents define what is often called 1156 a proof-of-possession security mechanism for access tokens, whereby a 1157 client must demonstrate possession of cryptographic keying material 1158 when accessing a protected resource. The details differ somewhat 1159 between the two documents but both have the authorization server bind 1160 the access token that it issues to an asymmetric key pair held by the 1161 client. The client then proves possession of the private key from 1162 that pair with respect to the TLS connection over which the protected 1163 resource is accessed. 1165 Token Binding uses bare keys that are generated on the client, which 1166 avoids many of the difficulties of creating, distributing, and 1167 managing certificates used in this specification. However, at the 1168 time of writing, Token Binding is fairly new and there is relatively 1169 little support for it in available application development platforms 1170 and tooling. Until better support for the underlying core Token 1171 Binding specifications exists, practical implementations of OAuth 2.0 1172 Token Binding are infeasible. Mutual TLS, on the other hand, has 1173 been around for some time and enjoys widespread support in web 1174 servers and development platforms. As a consequence, OAuth 2.0 1175 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens 1176 can be built and deployed now using existing platforms and tools. In 1177 the future, the two specifications are likely to be deployed in 1178 parallel for solving similar problems in different environments. 1179 Authorization servers may even support both specifications 1180 simultaneously using different proof-of-possession mechanisms for 1181 tokens issued to different clients. 1183 Appendix C. Acknowledgements 1185 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in 1186 design and development work on a mutual-TLS OAuth client 1187 authentication implementation, which predates this document. 1188 Experience and learning from that work informed some of the content 1189 of this document. 1191 This specification was developed within the OAuth Working Group under 1192 the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with 1193 Eric Rescorla, Benjamin Kaduk, and Roman Danyliw serving as Security 1194 Area Directors. Additionally, the following individuals contributed 1195 ideas, feedback, and wording that helped shape this specification: 1197 Vittorio Bertocci, Sergey Beryozkin, Ralph Bragg, Sophie Bremer, 1198 Roman Danyliw, Vladimir Dzhuvinov, Samuel Erdtman, Evan Gilman, Leif 1199 Johansson, Michael Jones, Phil Hunt, Benjamin Kaduk, Takahiko 1200 Kawasaki, Sean Leonard, Kepeng Li, Neil Madden, James Manger, Jim 1201 Manico, Nov Matake, Sascha Preibisch, Eric Rescorla, Justin Richer, 1202 Vincent Roca, Filip Skokan, Dave Tonge, and Hannes Tschofenig. 1204 Appendix D. Document(s) History 1206 [[ to be removed by the RFC Editor before publication as an RFC ]] 1208 draft-ietf-oauth-mtls-17 1210 o Updates from IESG ballot position comments. 1212 draft-ietf-oauth-mtls-16 1214 o Editorial updates from last call review. 1216 draft-ietf-oauth-mtls-15 1218 o Editorial updates from second AD review. 1220 draft-ietf-oauth-mtls-14 1222 o Editorial clarifications around there being only a single subject 1223 registered/configured per client for the tls_client_auth method. 1224 o Add a brief explanation about how, with tls_client_auth and 1225 self_signed_tls_client_auth, refresh tokens are certificate-bound 1226 indirectly via the client authentication. 1227 o Add mention of refresh tokens in the abstract. 1229 draft-ietf-oauth-mtls-13 1231 o Add an abstract protocol flow and diagram to serve as an overview 1232 of OAuth in general and baseline to describe the various ways in 1233 which the mechanisms defined herein are intended to be used. 1234 o A little bit less of that German influence. 1235 o Rework the TLS references a bit and, in the Terminology section, 1236 clean up the description of what messages are sent and verified in 1237 the handshake to do 'mutual TLS'. 1238 o Move the explanation about "cnf" introspection registration into 1239 the IANA Considerations. 1240 o Add CIBA as an informational reference and additional example of 1241 an OAuth extension that defines an endpoint that utilizes client 1242 authentication. 1243 o Shorten a few of the section titles. 1245 o Add new client metadata values to allow for the use of a SAN in 1246 the PKI MTLS client authentication method. 1247 o Add privacy considerations attempting to discuss the implications 1248 of the client cert being sent in the clear in TLS 1.2. 1249 o Changed the 'Certificate Bound Access Tokens Without Client 1250 Authentication' section to 'Public Clients and Certificate-Bound 1251 Tokens' and moved it up to be a top level section while adding 1252 discussion of binding refresh tokens for public clients. 1253 o Reword/restructure the main PKI method section somewhat to 1254 (hopefully) improve readability. 1255 o Reword/restructure the Self-Signed method section a bit to 1256 (hopefully) make it more comprehensible. 1257 o Reword the AS and RS Implementation Considerations somewhat to 1258 (hopefully) improve readability. 1259 o Clarify that the protected resource obtains the client certificate 1260 used for mutual TLS from its TLS implementation layer. 1261 o Add Security Considerations section about the certificate 1262 thumbprint binding that includes the hash algorithm agility 1263 recommendation. 1264 o Add an "mtls_endpoint_aliases" AS metadata parameter that is a 1265 JSON object containing alternative authorization server endpoints, 1266 which a client intending to do mutual TLS will use in preference 1267 to the conventional endpoints. 1268 o Minor editorial updates. 1270 draft-ietf-oauth-mtls-12 1272 o Add an example certificate, JWK, and confirmation method claim. 1273 o Minor editorial updates based on implementer feedback. 1274 o Additional Acknowledgements. 1276 draft-ietf-oauth-mtls-11 1278 o Editorial updates. 1279 o Mention/reference TLS 1.3 RFC8446 in the TLS Versions and Best 1280 Practices section. 1282 draft-ietf-oauth-mtls-10 1284 o Update draft-ietf-oauth-discovery reference to RFC8414 1286 draft-ietf-oauth-mtls-09 1288 o Change "single certificates" to "self-signed certificates" in the 1289 Abstract 1291 draft-ietf-oauth-mtls-08 1292 o Incorporate clarifications and editorial improvements from Justin 1293 Richer's WGLC review 1294 o Drop the use of the "sender constrained" terminology per WGLC 1295 feedback from Neil Madden (including changing the metadata 1296 parameters from mutual_tls_sender_constrained_access_tokens to 1297 tls_client_certificate_bound_access_tokens) 1298 o Add a new security considerations section on X.509 parsing and 1299 validation per WGLC feedback from Neil Madden and Benjamin Kaduk 1300 o Note that a server can terminate TLS at a load balancer, reverse 1301 proxy, etc. but how the client certificate metadata is securely 1302 communicated to the backend is out of scope per WGLC feedback 1303 o Note that revocation checking is at the discretion of the AS per 1304 WGLC feedback 1305 o Editorial updates and clarifications 1306 o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf- 1307 oauth-token-binding to -06 1308 o Add folks involved in WGLC feedback to the acknowledgements list 1310 draft-ietf-oauth-mtls-07 1312 o Update to use the boilerplate from RFC 8174 1314 draft-ietf-oauth-mtls-06 1316 o Add an appendix section describing the relationship of this 1317 document to OAuth Token Binding as requested during the Singapore 1318 meeting https://datatracker.ietf.org/doc/minutes-100-oauth/ 1319 o Add an explicit note that the implicit flow is not supported for 1320 obtaining certificate bound access tokens as discussed at the 1321 Singapore meeting https://datatracker.ietf.org/doc/minutes- 1322 100-oauth/ 1323 o Add/incorporate text to the Security Considerations on Certificate 1324 Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/ 1325 V26070X-6OtbVSeUz_7W2k94vCo 1326 o Changed the title to be more descriptive 1327 o Move the Security Considerations section to before the IANA 1328 Considerations 1329 o Elaborated on certificate-bound access tokens a bit more in the 1330 Abstract 1331 o Update draft-ietf-oauth-discovery reference to -08 1333 draft-ietf-oauth-mtls-05 1335 o Editorial fixes 1337 draft-ietf-oauth-mtls-04 1338 o Change the name of the 'Public Key method' to the more accurate 1339 'Self-Signed Certificate method' and also change the associated 1340 authentication method metadata value to 1341 "self_signed_tls_client_auth". 1342 o Removed the "tls_client_auth_root_dn" client metadata field as 1343 discussed in https://mailarchive.ietf.org/arch/msg/oauth/ 1344 swDV2y0be6o8czGKQi1eJV-g8qc 1345 o Update draft-ietf-oauth-discovery reference to -07 1346 o Clarify that MTLS client authentication isn't exclusive to the 1347 token endpoint and can be used with other endpoints, e.g. RFC 1348 7009 revocation and 7662 introspection, that utilize client 1349 authentication as discussed in 1350 https://mailarchive.ietf.org/arch/msg/oauth/ 1351 bZ6mft0G7D3ccebhOxnEYUv4puI 1352 o Reorganize the document somewhat in an attempt to more clearly 1353 make a distinction between mTLS client authentication and 1354 certificate-bound access tokens as well as a more clear 1355 delineation between the two (PKI/Public key) methods for client 1356 authentication 1357 o Editorial fixes and clarifications 1359 draft-ietf-oauth-mtls-03 1361 o Introduced metadata and client registration parameter to publish 1362 and request support for mutual TLS sender constrained access 1363 tokens 1364 o Added description of two methods of binding the cert and client, 1365 PKI and Public Key. 1366 o Indicated that the "tls_client_auth" authentication method is for 1367 the PKI method and introduced "pub_key_tls_client_auth" for the 1368 Public Key method 1369 o Added implementation considerations, mainly regarding TLS stack 1370 configuration and trust chain validation, as well as how to to do 1371 binding of access tokens to a TLS client certificate for public 1372 clients, and considerations around certificate-bound access tokens 1373 o Added new section to security considerations on cert spoofing 1374 o Add text suggesting that a new cnf member be defined in the 1375 future, if hash function(s) other than SHA-256 need to be used for 1376 certificate thumbprints 1378 draft-ietf-oauth-mtls-02 1380 o Fixed editorial issue https://mailarchive.ietf.org/arch/msg/oauth/ 1381 U46UMEh8XIOQnvXY9pHFq1MKPns 1382 o Changed the title (hopefully "Mutual TLS Profile for OAuth 2.0" is 1383 better than "Mutual TLS Profiles for OAuth Clients"). 1385 draft-ietf-oauth-mtls-01 1386 o Added more explicit details of using RFC 7662 token introspection 1387 with mutual TLS sender constrained access tokens. 1388 o Added an IANA OAuth Token Introspection Response Registration 1389 request for "cnf". 1390 o Specify that tls_client_auth_subject_dn and 1391 tls_client_auth_root_dn are RFC 4514 String Representation of 1392 Distinguished Names. 1393 o Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn. 1394 o Changed the text in the Section 3 to not be specific about using a 1395 hash of the cert. 1396 o Changed the abbreviated title to 'OAuth Mutual TLS' (previously 1397 was the acronym MTLSPOC). 1399 draft-ietf-oauth-mtls-00 1401 o Created the initial working group version from draft-campbell- 1402 oauth-mtls 1404 draft-campbell-oauth-mtls-01 1406 o Fix some typos. 1407 o Add to the acknowledgements list. 1409 draft-campbell-oauth-mtls-00 1411 o Add a Mutual TLS sender constrained protected resource access 1412 method and a x5t#S256 cnf method for JWT access tokens (concepts 1413 taken in part from draft-sakimura-oauth-jpop-04). 1414 o Fixed "token_endpoint_auth_methods_supported" to 1415 "token_endpoint_auth_method" for client metadata. 1416 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 1417 client metadata parameters and mention using "jwks_uri" or "jwks". 1418 o Say that the authentication method is determined by client policy 1419 regardless of whether the client was dynamically registered or 1420 statically configured. 1421 o Expand acknowledgements to those that participated in discussions 1422 around draft-campbell-oauth-tls-client-auth-00 1423 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 1425 draft-campbell-oauth-tls-client-auth-00 1427 o Initial draft. 1429 Authors' Addresses 1430 Brian Campbell 1431 Ping Identity 1433 Email: brian.d.campbell@gmail.com 1435 John Bradley 1436 Yubico 1438 Email: ve7jtb@ve7jtb.com 1439 URI: http://www.thread-safe.com/ 1441 Nat Sakimura 1442 Nomura Research Institute 1444 Email: n-sakimura@nri.co.jp 1445 URI: https://nat.sakimura.org/ 1447 Torsten Lodderstedt 1448 YES.com AG 1450 Email: torsten@lodderstedt.net