idnits 2.17.1 draft-ietf-oauth-mtls-01.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 26, 2017) is 2526 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 27, 2017 N. Sakimura 6 Nomura Research Institute 7 T. Lodderstedt 8 YES Europe AG 9 May 26, 2017 11 Mutual TLS Profiles for OAuth Clients 12 draft-ietf-oauth-mtls-01 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 27, 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 3.2. Confirmation Method for Token Introspection . . . . . . . 6 66 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 67 4.1. JWT Confirmation Methods Registration . . . . . . . . . . 7 68 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 7 69 4.2. Token Endpoint Authentication Method Registration . . . . 7 70 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 71 4.3. OAuth Token Introspection Response Registration . . . . . 8 72 4.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 73 4.4. OAuth Dynamic Client Registration Metadata Registration . 8 74 4.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 5.1. TLS Versions and Best Practices . . . . . . . . . . . . . 8 77 5.2. Client Identity Binding by the Authorization Server . . . 9 78 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 79 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 80 6.2. Informative References . . . . . . . . . . . . . . . . . 10 81 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 82 Appendix B. Document(s) History . . . . . . . . . . . . . . . . 11 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 85 1. Introduction 87 This document describes Transport Layer Security (TLS) mutual 88 authentication using X.509 certificates as a mechanism for both OAuth 89 client authentication to the token endpoint as well as for sender 90 constrained access to OAuth protected resources. 92 The OAuth 2.0 Authorization Framework [RFC6749] defines a shared 93 secret method of client authentication but also allows for the 94 definition and use of additional client authentication mechanisms 95 when interacting with the authorization server's token endpoint. 96 This document describes an additional mechanism of client 97 authentication utilizing mutual TLS [RFC5246] certificate-based 98 authentication, which provides better security characteristics than 99 shared secrets. 101 Mutual TLS sender constrained access to protected resources ensures 102 that only the party in possession of the private key corresponding to 103 the certificate can utilize the access token to get access to the 104 associated resources. Such a constraint is unlike the case of the 105 basic bearer token described in [RFC6750], where any party in 106 possession of the access token can use it to access the associated 107 resources. Mutual TLS sender constrained access binds the access 108 token to the client's certificate thus preventing the use of stolen 109 access tokens or replay of access tokens by unauthorized parties. 111 Mutual TLS sender constrained access tokens and mutual TLS client 112 authentication are distinct mechanisms that don't necessarily need to 113 be deployed together. 115 1.1. Requirements Notation and Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in RFC 120 2119 [RFC2119]. 122 1.2. Terminology 124 This specification uses the following phrases interchangeably: 126 Transport Layer Security (TLS) Mutual Authentication 128 Mutual TLS 130 These phrases all refer to the process whereby a client uses it's 131 X.509 certificate to authenticate itself with a server when 132 negotiating a TLS session. In TLS 1.2 [RFC5246] this requires the 133 client to send Client Certificate and Certificate Verify messages 134 during the TLS handshake and for the server to verify these messages. 136 2. Mutual TLS for Client Authentication 138 2.1. Mutual TLS Client Authentication to the Token Endpoint 140 The following section defines, as an extension of OAuth 2.0, 141 Section 2.3 [RFC6749], the use of mutual TLS X.509 client 142 certificates as client credentials. The requirement of mutual TLS 143 for client authentications is determined by the authorization server 144 based on policy or configuration for the given client (regardless of 145 whether the client was dynamically registered or statically 146 configured or otherwise established). OAuth 2.0 requires that access 147 token requests by the client to the token endpoint use TLS. In order 148 to utilize TLS for client authentication, the TLS connection MUST 149 have been established or reestablished with mutual X.509 certificate 150 authentication (i.e. the Client Certificate and Certificate Verify 151 messages are sent during the TLS Handshake [RFC5246]). 153 For all access token requests to the token endpoint, regardless of 154 the grant type used, the client MUST include the "client_id" 155 parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The 156 presence of the "client_id" parameter enables the authorization 157 server to easily identify the client independently from the content 158 of the certificate and allows for trust models to vary as appropriate 159 for a given deployment. The authorization server can locate the 160 client configuration by the client identifier and check the 161 certificate presented in the TLS Handshake against the expected 162 credentials for that client. As described in Section 5.2, the 163 authorization server MUST enforce some method of binding a 164 certificate to a client. 166 2.2. Authorization Server Metadata 168 "tls_client_auth" is used as a new value of the 169 "token_endpoint_auth_methods_supported" metadata parameter to 170 indicate server support for mutual TLS as a client authentication 171 method in authorization server metadata such as [OpenID.Discovery] 172 and [I-D.ietf-oauth-discovery]. 174 2.3. Dynamic Client Registration 176 This draft adds the following values and metadata parameters to OAuth 177 2.0 Dynamic Client Registration [RFC7591]. 179 The value "tls_client_auth" is used to indicate the client's 180 intention to use mutual TLS as an authentication method to the token 181 endpoint for the "token_endpoint_auth_method" client metadata field. 183 For authorization servers that associate certificates with clients 184 using subject information in the certificate, the following two new 185 metadata parameters can be used: 187 tls_client_auth_subject_dn 188 An [RFC4514] string representation of the expected subject 189 distinguished name of the certificate the OAuth client will use in 190 mutual TLS authentication. 192 tls_client_auth_root_dn 193 An [RFC4514] string representation of a distinguished name that 194 can optionally be used to constrain, for the given client, the 195 expected distinguished name of the root issuer of the client 196 certificate. 198 For authorization servers that use the key or full certificate to 199 associate clients with certificates, the existing "jwks_uri" or 200 "jwks" metadata parameters from [RFC7591] should be used. 202 3. Mutual TLS Sender Constrained Resources Access 204 When mutual TLS is used at the token endpoint, the authorization 205 server is able to bind the issued access token to the client 206 certificate. Such a binding is accomplished by associating the 207 certificate with the token in a way that can be accessed by the 208 protected resource, such as embedding the certificate hash in the 209 issued access token directly, using the syntax described in 210 Section 3.1, or through token introspection as described in 211 Section 3.2. Other methods of associating a certificate with an 212 access token are possible, per agreement by the authorization server 213 and the protected resource, but are beyond the scope of this 214 specification. 216 The client makes protected resource requests as described in 217 [RFC6750], however, those requests MUST be made over a mutually 218 authenticated TLS connection using the same certificate that was used 219 for mutual TLS at the token endpoint. 221 The protected resource MUST obtain the client certificate used for 222 mutual TLS authentication and MUST verify that the that certificate 223 matches the certificate associated with the access token. If they do 224 not match, the resource access attempt MUST be rejected with an 225 error. 227 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT 229 When access tokens are represented as a JSON Web Tokens 230 (JWT)[RFC7519], the certificate hash information SHOULD be 231 represented using the "x5t#S256" confirmation method member defined 232 herein. 234 To represent the hash of a certificate in a JWT, this specification 235 defines the new JWT Confirmation Method RFC 7800 [RFC7800] member 236 "x5t#S256" for the X.509 Certificate SHA-256 Thumbprint. The value 237 of the "x5t#S256" member is a base64url-encoded SHA-256[SHS] hash 238 (a.k.a. thumbprint or digest) of the DER encoding of the X.509 239 certificate[RFC5280] (note that certificate thumbprints are also 240 sometimes also known as certificate fingerprints). 242 The following is an example of a JWT payload containing an "x5t#S256" 243 certificate thumbprint confirmation method. 245 { 246 "iss": "https://server.example.com", 247 "sub": "ty.webb@example.com", 248 "exp": 1493726400, 249 "nbf": 1493722800, 250 "cnf":{ 251 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 252 } 253 } 255 Figure 1: Example claims of a Certificate Thumbprint Constrained JWT 257 3.2. Confirmation Method for Token Introspection 259 OAuth 2.0 Token Introspection [RFC7662] defines a method for a 260 protected resource to query an authorization server about the active 261 state of an access token as well as to determine meta-information 262 about the token. 264 For a mutual TLS sender constrained access token, the hash of the 265 certificate to which the token is bound is conveyed to the protected 266 resource as meta-information in a token introspection response. The 267 hash is conveyed using same structure as the certificate SHA-256 268 thumbprint confirmation method, described in Section 3.1, as a top- 269 level member of the introspection response JSON. The protected 270 resource compares that certificate hash to a hash of the client 271 certificate used for mutual TLS authentication and rejects the 272 request, if they do not match. 274 Proof-of-Possession Key Semantics for JSON Web Tokens [RFC7800] 275 defined the "cnf" (confirmation) claim, which enables confirmation 276 key information to be carried in a JWT. However, the same proof-of- 277 possession semantics are also useful for introspected access tokens 278 whereby the protected resource obtains the confirmation key data as 279 meta-information of a token introspection response and uses that 280 information in verifying proof-of-possession. Therefore this 281 specification defines and registers proof-of-possession semantics for 282 OAuth 2.0 Token Introspection [RFC7662] using the "cnf" structure. 283 When included as a top-level member of an OAuth token introspection 284 response, "cnf" has the same semantics and format as the the claim of 285 the same name defined in [RFC7800]. While this specification only 286 explicitly uses the "x5t#S256" confirmation method member, it needed 287 to define and register the higher level "cnf" structure as an 288 introspection response member in order to define and use its more 289 specific "x5t#S256" confirmation method. 291 The following is an example of an introspection response for an 292 active token with an "x5t#S256" certificate thumbprint confirmation 293 method. 295 HTTP/1.1 200 OK 296 Content-Type: application/json 298 { 299 "active": true, 300 "iss": "https://server.example.com", 301 "sub": "ty.webb@example.com", 302 "exp": 1493726400, 303 "nbf": 1493722800, 304 "cnf":{ 305 "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" 306 } 307 } 309 Figure 2: Example Introspection Response for a Certificate 310 Constrained Access Token 312 4. IANA Considerations 314 4.1. JWT Confirmation Methods Registration 316 This specification requests registration of the following value in 317 the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for 318 JWT "cnf" member values established by [RFC7800]. 320 4.1.1. Registry Contents 322 o Confirmation Method Value: "x5t#S256" 323 o Confirmation Method Description: X.509 Certificate SHA-256 324 Thumbprint 325 o Change Controller: IESG 326 o Specification Document(s): Section 3.1 of [[ this specification ]] 328 4.2. Token Endpoint Authentication Method Registration 330 This specification requests registration of the following value in 331 the IANA "OAuth Token Endpoint Authentication Methods" registry 332 [IANA.OAuth.Parameters] established by [RFC7591]. 334 4.2.1. Registry Contents 336 o Token Endpoint Authentication Method Name: "tls_client_auth" 337 o Change Controller: IESG 338 o Specification Document(s): Section 2.2 of [[ this specification ]] 340 4.3. OAuth Token Introspection Response Registration 342 This specification requests registration of the following value in 343 the IANA "OAuth Token Introspection Response" registry 344 [IANA.OAuth.Parameters] established by [RFC7662]. 346 4.3.1. Registry Contents 348 o Claim Name: "cnf" 349 o Claim Description: Confirmation 350 o Change Controller: IESG 351 o Specification Document(s): Section 3.2 of [[ this specification ]] 353 4.4. OAuth Dynamic Client Registration Metadata Registration 355 This specification requests registration of the following client 356 metadata definitions in the IANA "OAuth Dynamic Client Registration 357 Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 359 4.4.1. Registry Contents 361 o Client Metadata Name: "tls_client_auth_subject_dn" 362 o Client Metadata Description: String value specifying the expected 363 subject distinguished name of the client certificate. 364 o Change Controller: IESG 365 o Specification Document(s): Section 2.3 of [[ this specification ]] 367 o Client Metadata Name: "tls_client_auth_root_dn" 368 o Client Metadata Description: String value specifying the expected 369 distinguished name of the root issuer of the client certificate 370 o Change Controller: IESG 371 o Specification Document(s): Section 2.3 of [[ this specification ]] 373 5. Security Considerations 375 5.1. TLS Versions and Best Practices 377 TLS 1.2 [RFC5246] is cited in this document because, at the time of 378 writing, it is latest version that is widely deployed. However, this 379 document is applicable with other TLS versions supporting 380 certificate-based client authentication. Implementation security 381 considerations for TLS, including version recommendations, can be 382 found in Recommendations for Secure Use of Transport Layer Security 383 (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 385 5.2. Client Identity Binding by the Authorization Server 387 No specific method of binding a certificate to a client identifier at 388 the token endpoint is prescribed by this document. However, some 389 method MUST be employed so that, in addition to proving possession of 390 the private key corresponding to the certificate, the client identity 391 is also bound to the certificate. One such binding would be to 392 configure for the client a value that the certificate must contain in 393 the subject field and possibly the expected trust anchor. An 394 alternative method would be to configure a public key for the client 395 directly that would have to match the subject public key info of the 396 certificate. 398 6. References 400 6.1. Normative References 402 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 403 "Recommendations for Secure Use of Transport Layer 404 Security (TLS) and Datagram Transport Layer Security 405 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 406 2015, . 408 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 409 Requirement Levels", BCP 14, RFC 2119, 410 DOI 10.17487/RFC2119, March 1997, 411 . 413 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol 414 (LDAP): String Representation of Distinguished Names", 415 RFC 4514, DOI 10.17487/RFC4514, June 2006, 416 . 418 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 419 (TLS) Protocol Version 1.2", RFC 5246, 420 DOI 10.17487/RFC5246, August 2008, 421 . 423 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 424 Housley, R., and W. Polk, "Internet X.509 Public Key 425 Infrastructure Certificate and Certificate Revocation List 426 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 427 . 429 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 430 RFC 6749, DOI 10.17487/RFC6749, October 2012, 431 . 433 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 434 Framework: Bearer Token Usage", RFC 6750, 435 DOI 10.17487/RFC6750, October 2012, 436 . 438 [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- 439 Possession Key Semantics for JSON Web Tokens (JWTs)", 440 RFC 7800, DOI 10.17487/RFC7800, April 2016, 441 . 443 [SHS] National Institute of Standards and Technology, "Secure 444 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, 445 . 448 6.2. Informative References 450 [I-D.ietf-oauth-discovery] 451 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 452 Authorization Server Metadata", draft-ietf-oauth- 453 discovery-04 (work in progress), August 2016. 455 [IANA.JWT.Claims] 456 IANA, "JSON Web Token Claims", 457 . 459 [IANA.OAuth.Parameters] 460 IANA, "OAuth Parameters", 461 . 463 [OpenID.Discovery] 464 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 465 Connect Discovery 1.0", February 2014. 467 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 468 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 469 . 471 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 472 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 473 RFC 7591, DOI 10.17487/RFC7591, July 2015, 474 . 476 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 477 RFC 7662, DOI 10.17487/RFC7662, October 2015, 478 . 480 Appendix A. Acknowledgements 482 Scott "not Tomlinson" Tomilson and Matt Peterson were involved in 483 design and development work on a mutual TLS OAuth client 484 authentication implementation that informed some of the content of 485 this document. 487 Additionally, the authors would like to thank the following people 488 for their input and contributions to the specification: Sergey 489 Beryozkin, Vladimir Dzhuvinov, Samuel Erdtman, Phil Hunt, Sean 490 Leonard, Kepeng Li, James Manger, Jim Manico, Nov Matake, Sascha 491 Preibisch, Justin Richer, Dave Tonge, and Hannes Tschofenig. 493 Appendix B. Document(s) History 495 [[ to be removed by the RFC Editor before publication as an RFC ]] 497 draft-ietf-oauth-mtls-01 499 o Added more explicit details of using RFC 7662 token introspection 500 with mutual TLS sender constrained access tokens. 501 o Added an IANA OAuth Token Introspection Response Registration 502 request for "cnf". 503 o Specify that tls_client_auth_subject_dn and 504 tls_client_auth_root_dn are RFC 4514 String Representation of 505 Distinguished Names. 506 o Changed tls_client_auth_issuer_dn to tls_client_auth_root_dn. 507 o Changed the text in the Section 3 to not be specific about using a 508 hash of the cert. 509 o Changed the abbreviated title to 'OAuth Mutual TLS' (previously 510 was the acronym MTLSPOC). 512 draft-ietf-oauth-mtls-00 514 o Created the initial working group version from draft-campbell- 515 oauth-mtls 517 draft-campbell-oauth-mtls-01 519 o Fix some typos. 520 o Add to the acknowledgements list. 522 draft-campbell-oauth-mtls-00 523 o Add a Mutual TLS sender constrained protected resource access 524 method and a x5t#S256 cnf method for JWT access tokens (concepts 525 taken in part from draft-sakimura-oauth-jpop-04). 526 o Fixed "token_endpoint_auth_methods_supported" to 527 "token_endpoint_auth_method" for client metadata. 528 o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" 529 client metadata parameters and mention using "jwks_uri" or "jwks". 530 o Say that the authentication method is determined by client policy 531 regardless of whether the client was dynamically registered or 532 statically configured. 533 o Expand acknowledgements to those that participated in discussions 534 around draft-campbell-oauth-tls-client-auth-00 535 o Add Nat Sakimura and Torsten Lodderstedt to the author list. 537 draft-campbell-oauth-tls-client-auth-00 539 o Initial draft. 541 Authors' Addresses 543 Brian Campbell 544 Ping Identity 546 Email: brian.d.campbell@gmail.com 548 John Bradley 549 Ping Identity 551 Email: ve7jtb@ve7jtb.com 552 URI: http://www.thread-safe.com/ 554 Nat Sakimura 555 Nomura Research Institute 557 Email: n-sakimura@nri.co.jp 558 URI: https://nat.sakimura.org/ 560 Torsten Lodderstedt 561 YES Europe AG 563 Email: torsten@lodderstedt.net