idnits 2.17.1 draft-campbell-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 (March 30, 2017) is 2578 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: October 1, 2017 N. Sakimura 6 Nomura Research Institute 7 T. Lodderstedt 8 YES Europe AG 9 March 30, 2017 11 Mutual TLS Profiles for OAuth Clients 12 draft-campbell-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 October 1, 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 2. Mutual TLS for Client Authentication . . . . . . . . . . . . 3 58 2.1. Mutual TLS Client Authentication to the Token Endpoint . 3 59 2.2. Authorization Server Metadata . . . . . . . . . . . . . . 4 60 2.3. Dynamic Client Registration . . . . . . . . . . . . . . . 4 61 3. Mutual TLS Sender Constrained Resources Access . . . . . . . 4 62 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method 63 for JWT . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 65 4.1. JWT Confirmation Methods Registration . . . . . . . . . . 6 66 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 67 4.2. Token Endpoint Authentication Method Registration . . . . 6 68 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 69 4.3. OAuth Dynamic Client Registration Metadata Registration . 6 70 4.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 72 5.1. TLS Versions and Best Practices . . . . . . . . . . . . . 7 73 5.2. Client Identity Binding . . . . . . . . . . . . . . . . . 7 74 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 75 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 76 6.2. Informative References . . . . . . . . . . . . . . . . . 8 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 78 Appendix B. Document(s) History . . . . . . . . . . . . . . . . 9 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 81 1. Introduction 83 This document describes Transport Layer Security (TLS) mutual 84 authentication using X.509 certificates as a mechanism for both OAuth 85 client authentication to the token endpoint as well as for sender 86 constrained access to OAuth protected resources. 88 The OAuth 2.0 Authorization Framework [RFC6749] defines a shared 89 secret method of client authentication but also allows for the 90 definition and use of additional client authentication mechanisms 91 when interacting with the authorization server's token endpoint. 92 This document describes an additional mechanism of client 93 authentication utilizing mutual TLS [RFC5246] certificate-based 94 authentication, which provides better security characteristics than 95 shared secrets. 97 Mutual TLS sender constrained access to protected resources ensures 98 that only the party in possession of the private key corresponding to 99 the certificate can utilize the access token to get access to the 100 associated resources. Such a constraint is unlike the case of the 101 basic bearer token described in [RFC6750], where any party in 102 possession of the access token can use it to access the associated 103 resources. Mutual TLS sender constrained access prevents the use of 104 stolen access tokens by binding the access token to the client's 105 certificate. 107 Mutual TLS sender constrained access tokens and mutual TLS client 108 authentication are distinct mechanisms that can don't necessarily 109 need to be deployed together. 111 1.1. Requirements Notation and Conventions 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in RFC 116 2119 [RFC2119]. 118 2. Mutual TLS for Client Authentication 120 2.1. Mutual TLS Client Authentication to the Token Endpoint 122 The following section defines, as an extension of OAuth 2.0, 123 Section 2.3 [RFC6749], the use of mutual TLS as client credentials. 124 The requirement of mutual TLS for client authentications is 125 determined by the authorization server based on policy or 126 configuration for the given client (regardless of whether the client 127 was dynamically registered or statically configured or otherwise 128 established). OAuth 2.0 requires that access token requests by the 129 client to the token endpoint use TLS. In order to utilize TLS for 130 client authentication, the TLS connection MUST have been established 131 or reestablished with mutual X.509 certificate authentication (i.e. 132 the Client Certificate and Certificate Verify messages are sent 133 during the TLS Handshake [RFC5246]). 135 For all access token requests to the token endpoint, regardless of 136 the grant type used, the client MUST include the "client_id" 137 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 138 presence of the "client_id" parameter enables the authorization 139 server to easily identify the client independently from the content 140 of the certificate and allows for trust models to vary as appropriate 141 for a given deployment. The authorization server can locate the 142 client configuration by the client identifier and check the 143 certificate presented in the TLS Handshake against the expected 144 credentials for that client. As described in Section 5.2, the 145 authorization server MUST enforce some method of binding a 146 certificate to a client. 148 2.2. Authorization Server Metadata 150 "tls_client_auth" is used as a new value of the 151 "token_endpoint_auth_methods_supported" metadata parameter to 152 indicate server support for mutual TLS as a client authentication 153 method in authorization server metadata such as [OpenID.Discovery] 154 and [I-D.ietf-oauth-discovery]. 156 2.3. Dynamic Client Registration 158 This draft adds the following values and metadata parameters to the 159 OAuth 2.0 Dynamic Client Registration [RFC7591]. 161 The value "tls_client_auth" is used to indicate the client's 162 intention to use mutual TLS as an authentication method to the token 163 endpoint for the "token_endpoint_auth_method" client metadata field. 165 For authorization servers that associate certificates with clients 166 using subject information in the certificate, the following two new 167 string metadata parameters can be used: 169 tls_client_auth_subject_dn The expected subject distinguished name 170 of the client certificate can be represented using 171 "tls_client_auth_subject_dn". 173 tls_client_auth_issuer_dn The metadata parameter 174 "tls_client_auth_issuer_dn" can optionally be used to constrain 175 the expected distinguished name of the root issuer of the client 176 certificate. 178 For authorization servers that use the key or full certificate to 179 associate clients with certificate, the existing "jwks_uri" or "jwks" 180 metadata parameters from [RFC7591] shall be used. 182 3. Mutual TLS Sender Constrained Resources Access 184 When mutual TLS X.509 client certificate authentication is used at 185 the token endpoint, the authorization server is able to bind the 186 issued access token to the client certificate. Such a binding is 187 accomplished by associating a hash of the certificate with the token 188 in a way that can be accessed by the protected resource, such as 189 embedding the certificate hash in the issued access token directly, 190 using the syntax described in Section 3.1, or through token 191 introspection [RFC7662]. The specific method for associating the 192 certificate with the access token is determined by the authorization 193 server and the protected resource, and is beyond the scope for this 194 specification. 196 The client makes protected resource requests as described in 197 [RFC6750], however, those requests MUST be made over a mutually 198 authenticated TLS connection using the same certificate that was used 199 to authenticate to the token endpoint. 201 The protected resource MUST obtain the client certificate used for 202 TLS authentication and MUST verify that the hash of that certificate 203 exactly matches the hash of the certificate associated with the 204 access token. If the hash values do not match, the resource access 205 attempt MUST be rejected with an error. 207 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT 209 When access tokens are represented as a JSON Web Tokens 210 (JWT)[RFC7519], the certificate hash information SHOULD be 211 represented using the "x5t#S256" confirmation method member defined 212 herein. 214 To represent the hash of a certificate in a JWT, this specification 215 defines the new JWT Confirmation Method RFC 7800 [RFC7800] member 216 "x5t#S256" for the X.509 Certificate SHA-256 Thumbprint. The value 217 of the "x5t#S256" member is a base64url-encoded SHA-256[SHS] hash 218 (a.k.a. thumbprint or digest) of the DER encoding of the X.509 219 certificate[RFC5280] (note that certificate thumbprints are also 220 sometimes also known as certificate fingerprints). 222 The following is an example of a JWT payload containing an "x5t#S256" 223 certificate thumbprint confirmation method. 225 { 226 "iss": "https://server.example.com", 227 "aud": "https://resource.example.org", 228 "sub": "ty.webb@example.com", 229 "exp": "1493726400", 230 "nbf": "1493722800", 231 "cnf":{ 232 "x5t#s256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 233 } 234 } 236 Figure 1: Example claims of a Certificate Thumbprint Constrained JWT. 238 4. IANA Considerations 240 4.1. JWT Confirmation Methods Registration 242 This specification requests registration of the following value in 243 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 244 JWT "cnf" member values established by [RFC7800]. 246 4.1.1. Registry Contents 248 o Confirmation Method Value: "x5t#S256" 249 o Confirmation Method Description: X.509 Certificate SHA-256 250 Thumbprint 251 o Change Controller: IESG 252 o Specification Document(s): Section 3.1 of [[ this specification ]] 254 4.2. Token Endpoint Authentication Method Registration 256 This specification requests registration of the following value in 257 the IANA "OAuth Token Endpoint Authentication Methods" registry 258 [IANA.OAuth.Parameters] established by [RFC7591]. 260 4.2.1. Registry Contents 262 o Token Endpoint Authentication Method Name: "tls_client_auth" 263 o Change Controller: IESG 264 o Specification Document(s): Section 2.2 of [[ this specification ]] 266 4.3. OAuth Dynamic Client Registration Metadata Registration 268 This specification requests registration of the following client 269 metadata definitions in the IANA "OAuth Dynamic Client Registration 270 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 272 4.3.1. Registry Contents 274 o Client Metadata Name: "tls_client_auth_subject_dn" 275 o Client Metadata Description: String value specifying the expected 276 subject distinguished name of the client certificate. 277 o Change Controller: IESG 278 o Specification Document(s): Section 2.3 of [[ this specification ]] 280 o Client Metadata Name: "tls_client_auth_issuer_dn" 281 o Client Metadata Description: String value specifying the expected 282 distinguished name of the root issuer of the client certificate 283 o Change Controller: IESG 284 o Specification Document(s): Section 2.3 of [[ this specification ]] 286 5. Security Considerations 288 5.1. TLS Versions and Best Practices 290 TLS 1.2 [RFC5246] is cited in this document because, at the time of 291 writing, it is latest version that is widely deployed. However, this 292 document is applicable with other TLS versions supporting 293 certificate-based client authentication. Implementation security 294 considerations for TLS, including version recommendations, can be 295 found in Recommendations for Secure Use of Transport Layer Security 296 (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 298 5.2. Client Identity Binding 300 No specific method of binding a certificate to a client identifier at 301 the token endoint is prescribed by this document. However, some 302 method MUST be employed so that, in addition to proving possession of 303 the private key corresponding to the certificate, the client identity 304 is also bound to the certificate. One such binding would be to 305 configure for the client a value that the certificate must contain in 306 the subject field or the subjectAltName extension and possibly a 307 restricted set of trust anchors. An alternative method would be to 308 configure a public key for the client directly that would have to 309 match the subject public key info of the certificate. 311 6. References 313 6.1. Normative References 315 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 316 "Recommendations for Secure Use of Transport Layer 317 Security (TLS) and Datagram Transport Layer Security 318 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 319 2015, . 321 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 322 Requirement Levels", BCP 14, RFC 2119, 323 DOI 10.17487/RFC2119, March 1997, 324 . 326 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 327 (TLS) Protocol Version 1.2", RFC 5246, 328 DOI 10.17487/RFC5246, August 2008, 329 . 331 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 332 Housley, R., and W. Polk, "Internet X.509 Public Key 333 Infrastructure Certificate and Certificate Revocation List 334 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 335 . 337 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 338 RFC 6749, DOI 10.17487/RFC6749, October 2012, 339 . 341 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 342 Framework: Bearer Token Usage", RFC 6750, 343 DOI 10.17487/RFC6750, October 2012, 344 . 346 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 347 Possession Key Semantics for JSON Web Tokens (JWTs)", 348 RFC 7800, DOI 10.17487/RFC7800, April 2016, 349 . 351 [SHS] National Institute of Standards and Technology, "Secure 352 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 353 . 356 6.2. Informative References 358 [I-D.ietf-oauth-discovery] 359 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 360 Authorization Server Metadata", draft-ietf-oauth- 361 discovery-04 (work in progress), August 2016. 363 [IANA.JWT.Claims] 364 IANA, "JSON Web Token Claims", 365 . 367 [IANA.OAuth.Parameters] 368 IANA, "OAuth Parameters", 369 . 371 [OpenID.Discovery] 372 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 373 Connect Discovery 1.0", February 2014. 375 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 376 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 377 . 379 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 380 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 381 RFC 7591, DOI 10.17487/RFC7591, July 2015, 382 . 384 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 385 RFC 7662, DOI 10.17487/RFC7662, October 2015, 386 . 388 Appendix A. Acknowledgements 390 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in the 391 original design and development work on a mutual TLS client 392 authentication implementation that informed some of the content of 393 this document. 395 Additionally, the authors would like to thank the following people 396 for their input and contributions to the specification: Sergey 397 Beryozkin, Vladimir Dzhuvinov, Samuel Erdtman, Phil Hunt, Sean 398 Leonard, Jim Manico, Sascha Preibisch, Justin Richer, and Hannes 399 Tschofenig. 401 Appendix B. Document(s) History 403 [[ to be removed by the RFC Editor before publication as an RFC ]] 405 draft-campbell-oauth-mtls-00 407 o Add a Mutual TLS sender constrained protected resource access 408 method and a x5t#s256 cnf method for JWT access tokens (concepts 409 taken in part from draft-sakimura-oauth-jpop-04). 410 o Fixed "token_endpoint_auth_methods_supported" to 411 "token_endpoint_auth_method" for client metadata. 412 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 413 client metadata parameters and mention using "jwks_uri" or "jwks". 414 o Say that the authentication method is determined by client policy 415 regardless of whether the client was dynamically registered or 416 statically configured. 417 o Expand acknowledgements to those that participated in discussions 418 around draft-campbell-oauth-tls-client-auth-00 419 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 421 draft-campbell-oauth-tls-client-auth-00 423 o Initial draft. 425 Authors' Addresses 427 Brian Campbell 428 Ping Identity 430 Email: brian.d.campbell@gmail.com 432 John Bradley 433 Ping Identity 435 Email: ve7jtb@ve7jtb.com 436 URI: http://www.thread-safe.com/ 438 Nat Sakimura 439 Nomura Research Institute 441 Email: n-sakimura@nri.co.jp 442 URI: https://nat.sakimura.org/ 444 Torsten Lodderstedt 445 YES Europe AG 447 Email: torsten@lodderstedt.net