idnits 2.17.1 draft-ietf-oauth-mtls-00.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 9, 2017) is 2537 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 (-10) exists of draft-ietf-oauth-discovery-04 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 J. Bradley 4 Intended status: Standards Track Ping Identity 5 Expires: November 10, 2017 N. Sakimura 6 Nomura Research Institute 7 T. Lodderstedt 8 YES Europe AG 9 May 9, 2017 11 Mutual TLS Profiles for OAuth Clients 12 draft-ietf-oauth-mtls-00 14 Abstract 16 This document describes Transport Layer Security (TLS) mutual 17 authentication using X.509 certificates as a mechanism for both OAuth 18 client authentication to the token endpoint as well as for sender 19 constrained access to OAuth protected resources. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on November 10, 2017. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 57 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Mutual TLS for Client Authentication . . . . . . . . . . . . 3 59 2.1. Mutual TLS Client Authentication to the Token Endpoint . 3 60 2.2. Authorization Server Metadata . . . . . . . . . . . . . . 4 61 2.3. Dynamic Client Registration . . . . . . . . . . . . . . . 4 62 3. Mutual TLS Sender Constrained Resources Access . . . . . . . 5 63 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method 64 for JWT . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 66 4.1. JWT Confirmation Methods Registration . . . . . . . . . . 6 67 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 68 4.2. Token Endpoint Authentication Method Registration . . . . 6 69 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 70 4.3. OAuth Dynamic Client Registration Metadata Registration . 6 71 4.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 72 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 73 5.1. TLS Versions and Best Practices . . . . . . . . . . . . . 7 74 5.2. Client Identity Binding . . . . . . . . . . . . . . . . . 7 75 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 77 6.2. Informative References . . . . . . . . . . . . . . . . . 8 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 79 Appendix B. Document(s) History . . . . . . . . . . . . . . . . 9 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 82 1. Introduction 84 This document describes Transport Layer Security (TLS) mutual 85 authentication using X.509 certificates as a mechanism for both OAuth 86 client authentication to the token endpoint as well as for sender 87 constrained access to OAuth protected resources. 89 The OAuth 2.0 Authorization Framework [RFC6749] defines a shared 90 secret method of client authentication but also allows for the 91 definition and use of additional client authentication mechanisms 92 when interacting with the authorization server's token endpoint. 93 This document describes an additional mechanism of client 94 authentication utilizing mutual TLS [RFC5246] certificate-based 95 authentication, which provides better security characteristics than 96 shared secrets. 98 Mutual TLS sender constrained access to protected resources ensures 99 that only the party in possession of the private key corresponding to 100 the certificate can utilize the access token to get access to the 101 associated resources. Such a constraint is unlike the case of the 102 basic bearer token described in [RFC6750], where any party in 103 possession of the access token can use it to access the associated 104 resources. Mutual TLS sender constrained access prevents the use of 105 stolen access tokens by binding the access token to the client's 106 certificate. 108 Mutual TLS sender constrained access tokens and mutual TLS client 109 authentication are distinct mechanisms that don't necessarily need to 110 be deployed together. 112 1.1. Requirements Notation and Conventions 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in RFC 117 2119 [RFC2119]. 119 1.2. Terminology 121 This specification uses the following phrases interchangeably: 123 Transport Layer Security (TLS) Mutual Authentication 125 Mutual TLS 127 Mutual TLS X.509 client certificate authentication 129 These phrases all refer to the process whereby a client uses it's 130 X.509 certificate to authenticate itself with a server when 131 negotiating a TLS session. In TLS 1.2 [RFC5246] this requires the 132 client to send Client Certificate and Certificate Verify messages 133 during the TLS handshake and for the server to verify these messages. 135 2. Mutual TLS for Client Authentication 137 2.1. Mutual TLS Client Authentication to the Token Endpoint 139 The following section defines, as an extension of OAuth 2.0, 140 Section 2.3 [RFC6749], the use of mutual TLS X.509 client 141 certificates as client credentials. The requirement of mutual TLS 142 for client authentications is determined by the authorization server 143 based on policy or configuration for the given client (regardless of 144 whether the client was dynamically registered or statically 145 configured or otherwise established). OAuth 2.0 requires that access 146 token requests by the client to the token endpoint use TLS. In order 147 to utilize TLS for client authentication, the TLS connection MUST 148 have been established or reestablished with mutual X.509 certificate 149 authentication (i.e. the Client Certificate and Certificate Verify 150 messages are sent during the TLS Handshake [RFC5246]). 152 For all access token requests to the token endpoint, regardless of 153 the grant type used, the client MUST include the "client_id" 154 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 155 presence of the "client_id" parameter enables the authorization 156 server to easily identify the client independently from the content 157 of the certificate and allows for trust models to vary as appropriate 158 for a given deployment. The authorization server can locate the 159 client configuration by the client identifier and check the 160 certificate presented in the TLS Handshake against the expected 161 credentials for that client. As described in Section 5.2, the 162 authorization server MUST enforce some method of binding a 163 certificate to a client. 165 2.2. Authorization Server Metadata 167 "tls_client_auth" is used as a new value of the 168 "token_endpoint_auth_methods_supported" metadata parameter to 169 indicate server support for mutual TLS as a client authentication 170 method in authorization server metadata such as [OpenID.Discovery] 171 and [I-D.ietf-oauth-discovery]. 173 2.3. Dynamic Client Registration 175 This draft adds the following values and metadata parameters to the 176 OAuth 2.0 Dynamic Client Registration [RFC7591]. 178 The value "tls_client_auth" is used to indicate the client's 179 intention to use mutual TLS as an authentication method to the token 180 endpoint for the "token_endpoint_auth_method" client metadata field. 182 For authorization servers that associate certificates with clients 183 using subject information in the certificate, the following two new 184 string metadata parameters can be used: 186 tls_client_auth_subject_dn The expected subject distinguished name 187 of the client certificate can be represented using 188 "tls_client_auth_subject_dn". 190 tls_client_auth_issuer_dn The metadata parameter 191 "tls_client_auth_issuer_dn" can optionally be used to constrain 192 the expected distinguished name of the root issuer of the client 193 certificate. 195 For authorization servers that use the key or full certificate to 196 associate clients with certificate, the existing "jwks_uri" or "jwks" 197 metadata parameters from [RFC7591] shall be used. 199 3. Mutual TLS Sender Constrained Resources Access 201 When mutual TLS X.509 client certificate authentication is used at 202 the token endpoint, the authorization server is able to bind the 203 issued access token to the client certificate. Such a binding is 204 accomplished by associating a hash of the certificate with the token 205 in a way that can be accessed by the protected resource, such as 206 embedding the certificate hash in the issued access token directly, 207 using the syntax described in Section 3.1, or through token 208 introspection [RFC7662]. The specific method for associating the 209 certificate with the access token is determined by the authorization 210 server and the protected resource, and is beyond the scope for this 211 specification. 213 The client makes protected resource requests as described in 214 [RFC6750], however, those requests MUST be made over a mutually 215 authenticated TLS connection using the same certificate that was used 216 to authenticate to the token endpoint. 218 The protected resource MUST obtain the client certificate used for 219 TLS authentication and MUST verify that the hash of that certificate 220 exactly matches the hash of the certificate associated with the 221 access token. If the hash values do not match, the resource access 222 attempt MUST be rejected with an error. 224 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT 226 When access tokens are represented as a JSON Web Tokens 227 (JWT)[RFC7519], the certificate hash information SHOULD be 228 represented using the "x5t#S256" confirmation method member defined 229 herein. 231 To represent the hash of a certificate in a JWT, this specification 232 defines the new JWT Confirmation Method RFC 7800 [RFC7800] member 233 "x5t#S256" for the X.509 Certificate SHA-256 Thumbprint. The value 234 of the "x5t#S256" member is a base64url-encoded SHA-256[SHS] hash 235 (a.k.a. thumbprint or digest) of the DER encoding of the X.509 236 certificate[RFC5280] (note that certificate thumbprints are also 237 sometimes also known as certificate fingerprints). 239 The following is an example of a JWT payload containing an "x5t#S256" 240 certificate thumbprint confirmation method. 242 { 243 "iss": "https://server.example.com", 244 "aud": "https://resource.example.org", 245 "sub": "ty.webb@example.com", 246 "exp": 1493726400, 247 "nbf": 1493722800, 248 "cnf":{ 249 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 250 } 251 } 253 Figure 1: Example claims of a Certificate Thumbprint Constrained JWT. 255 4. IANA Considerations 257 4.1. JWT Confirmation Methods Registration 259 This specification requests registration of the following value in 260 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 261 JWT "cnf" member values established by [RFC7800]. 263 4.1.1. Registry Contents 265 o Confirmation Method Value: "x5t#S256" 266 o Confirmation Method Description: X.509 Certificate SHA-256 267 Thumbprint 268 o Change Controller: IESG 269 o Specification Document(s): Section 3.1 of [[ this specification ]] 271 4.2. Token Endpoint Authentication Method Registration 273 This specification requests registration of the following value in 274 the IANA "OAuth Token Endpoint Authentication Methods" registry 275 [IANA.OAuth.Parameters] established by [RFC7591]. 277 4.2.1. Registry Contents 279 o Token Endpoint Authentication Method Name: "tls_client_auth" 280 o Change Controller: IESG 281 o Specification Document(s): Section 2.2 of [[ this specification ]] 283 4.3. OAuth Dynamic Client Registration Metadata Registration 285 This specification requests registration of the following client 286 metadata definitions in the IANA "OAuth Dynamic Client Registration 287 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 289 4.3.1. Registry Contents 291 o Client Metadata Name: "tls_client_auth_subject_dn" 292 o Client Metadata Description: String value specifying the expected 293 subject distinguished name of the client certificate. 294 o Change Controller: IESG 295 o Specification Document(s): Section 2.3 of [[ this specification ]] 297 o Client Metadata Name: "tls_client_auth_issuer_dn" 298 o Client Metadata Description: String value specifying the expected 299 distinguished name of the root issuer of the client certificate 300 o Change Controller: IESG 301 o Specification Document(s): Section 2.3 of [[ this specification ]] 303 5. Security Considerations 305 5.1. TLS Versions and Best Practices 307 TLS 1.2 [RFC5246] is cited in this document because, at the time of 308 writing, it is latest version that is widely deployed. However, this 309 document is applicable with other TLS versions supporting 310 certificate-based client authentication. Implementation security 311 considerations for TLS, including version recommendations, can be 312 found in Recommendations for Secure Use of Transport Layer Security 313 (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 315 5.2. Client Identity Binding 317 No specific method of binding a certificate to a client identifier at 318 the token endoint is prescribed by this document. However, some 319 method MUST be employed so that, in addition to proving possession of 320 the private key corresponding to the certificate, the client identity 321 is also bound to the certificate. One such binding would be to 322 configure for the client a value that the certificate must contain in 323 the subject field or the subjectAltName extension and possibly a 324 restricted set of trust anchors. An alternative method would be to 325 configure a public key for the client directly that would have to 326 match the subject public key info of the certificate. 328 6. References 330 6.1. Normative References 332 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 333 "Recommendations for Secure Use of Transport Layer 334 Security (TLS) and Datagram Transport Layer Security 335 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 336 2015, . 338 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 339 Requirement Levels", BCP 14, RFC 2119, 340 DOI 10.17487/RFC2119, March 1997, 341 . 343 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 344 (TLS) Protocol Version 1.2", RFC 5246, 345 DOI 10.17487/RFC5246, August 2008, 346 . 348 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 349 Housley, R., and W. Polk, "Internet X.509 Public Key 350 Infrastructure Certificate and Certificate Revocation List 351 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 352 . 354 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 355 RFC 6749, DOI 10.17487/RFC6749, October 2012, 356 . 358 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 359 Framework: Bearer Token Usage", RFC 6750, 360 DOI 10.17487/RFC6750, October 2012, 361 . 363 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 364 Possession Key Semantics for JSON Web Tokens (JWTs)", 365 RFC 7800, DOI 10.17487/RFC7800, April 2016, 366 . 368 [SHS] National Institute of Standards and Technology, "Secure 369 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 370 . 373 6.2. Informative References 375 [I-D.ietf-oauth-discovery] 376 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 377 Authorization Server Metadata", draft-ietf-oauth- 378 discovery-04 (work in progress), August 2016. 380 [IANA.JWT.Claims] 381 IANA, "JSON Web Token Claims", 382 . 384 [IANA.OAuth.Parameters] 385 IANA, "OAuth Parameters", 386 . 388 [OpenID.Discovery] 389 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 390 Connect Discovery 1.0", February 2014. 392 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 393 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 394 . 396 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 397 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 398 RFC 7591, DOI 10.17487/RFC7591, July 2015, 399 . 401 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 402 RFC 7662, DOI 10.17487/RFC7662, October 2015, 403 . 405 Appendix A. Acknowledgements 407 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in the 408 original design and development work on a mutual TLS client 409 authentication implementation that informed some of the content of 410 this document. 412 Additionally, the authors would like to thank the following people 413 for their input and contributions to the specification: Sergey 414 Beryozkin, Vladimir Dzhuvinov, Samuel Erdtman, Phil Hunt, Sean 415 Leonard, Kepeng Li, James Manger, Jim Manico, Nov Matake, Sascha 416 Preibisch, Justin Richer, Dave Tonge, and Hannes Tschofenig. 418 Appendix B. Document(s) History 420 [[ to be removed by the RFC Editor before publication as an RFC ]] 422 draft-ietf-oauth-mtls-00 424 o Created the initial working group version from draft-campbell- 425 oauth-mtls 427 draft-campbell-oauth-mtls-01 429 o Fix some typos. 430 o Add to the acknowledgements list. 432 o Add a Mutual TLS sender constrained protected resource access 433 method and a x5t#S256 cnf method for JWT access tokens (concepts 434 taken in part from draft-sakimura-oauth-jpop-04). 435 o Fixed "token_endpoint_auth_methods_supported" to 436 "token_endpoint_auth_method" for client metadata. 437 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 438 client metadata parameters and mention using "jwks_uri" or "jwks". 439 o Say that the authentication method is determined by client policy 440 regardless of whether the client was dynamically registered or 441 statically configured. 442 o Expand acknowledgements to those that participated in discussions 443 around draft-campbell-oauth-tls-client-auth-00 444 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 446 draft-campbell-oauth-tls-client-auth-00 448 o Initial draft. 450 Authors' Addresses 452 Brian Campbell 453 Ping Identity 455 Email: brian.d.campbell@gmail.com 457 John Bradley 458 Ping Identity 460 Email: ve7jtb@ve7jtb.com 461 URI: http://www.thread-safe.com/ 463 Nat Sakimura 464 Nomura Research Institute 466 Email: n-sakimura@nri.co.jp 467 URI: https://nat.sakimura.org/ 469 Torsten Lodderstedt 470 YES Europe AG 472 Email: torsten@lodderstedt.net