OAuth Working Group B. Campbell Internet-Draft J. Bradley Intended status: Standards Track Ping Identity Expires: October 12, 2017 N. Sakimura Nomura Research Institute T. Lodderstedt YES Europe AG April 10, 2017 Mutual TLS Profiles for OAuth Clients draft-campbell-oauth-mtls-01 Abstract This document describes Transport Layer Security (TLS) mutual authentication using X.509 certificates as a mechanism for both OAuth client authentication to the token endpoint as well as for sender constrained access to OAuth protected resources. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 12, 2017. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must Campbell, et al. Expires October 12, 2017 [Page 1] Internet-Draft MTLSPOC April 2017 include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 2. Mutual TLS for Client Authentication . . . . . . . . . . . . 3 2.1. Mutual TLS Client Authentication to the Token Endpoint . 3 2.2. Authorization Server Metadata . . . . . . . . . . . . . . 4 2.3. Dynamic Client Registration . . . . . . . . . . . . . . . 4 3. Mutual TLS Sender Constrained Resources Access . . . . . . . 4 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 4.1. JWT Confirmation Methods Registration . . . . . . . . . . 6 4.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 4.2. Token Endpoint Authentication Method Registration . . . . 6 4.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 4.3. OAuth Dynamic Client Registration Metadata Registration . 6 4.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 5.1. TLS Versions and Best Practices . . . . . . . . . . . . . 7 5.2. Client Identity Binding . . . . . . . . . . . . . . . . . 7 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 6.2. Informative References . . . . . . . . . . . . . . . . . 8 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 Appendix B. Document(s) History . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction This document describes Transport Layer Security (TLS) mutual authentication using X.509 certificates as a mechanism for both OAuth client authentication to the token endpoint as well as for sender constrained access to OAuth protected resources. The OAuth 2.0 Authorization Framework [RFC6749] defines a shared secret method of client authentication but also allows for the definition and use of additional client authentication mechanisms when interacting with the authorization server's token endpoint. This document describes an additional mechanism of client authentication utilizing mutual TLS [RFC5246] certificate-based authentication, which provides better security characteristics than shared secrets. Campbell, et al. Expires October 12, 2017 [Page 2] Internet-Draft MTLSPOC April 2017 Mutual TLS sender constrained access to protected resources ensures that only the party in possession of the private key corresponding to the certificate can utilize the access token to get access to the associated resources. Such a constraint is unlike the case of the basic bearer token described in [RFC6750], where any party in possession of the access token can use it to access the associated resources. Mutual TLS sender constrained access prevents the use of stolen access tokens by binding the access token to the client's certificate. Mutual TLS sender constrained access tokens and mutual TLS client authentication are distinct mechanisms that don't necessarily need to be deployed together. 1.1. Requirements Notation and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 2. Mutual TLS for Client Authentication 2.1. Mutual TLS Client Authentication to the Token Endpoint The following section defines, as an extension of OAuth 2.0, Section 2.3 [RFC6749], the use of mutual TLS as client credentials. The requirement of mutual TLS for client authentications is determined by the authorization server based on policy or configuration for the given client (regardless of whether the client was dynamically registered or statically configured or otherwise established). OAuth 2.0 requires that access token requests by the client to the token endpoint use TLS. In order to utilize TLS for client authentication, the TLS connection MUST have been established or reestablished with mutual X.509 certificate authentication (i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake [RFC5246]). For all access token requests to the token endpoint, regardless of the grant type used, the client MUST include the "client_id" parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The presence of the "client_id" parameter enables the authorization server to easily identify the client independently from the content of the certificate and allows for trust models to vary as appropriate for a given deployment. The authorization server can locate the client configuration by the client identifier and check the certificate presented in the TLS Handshake against the expected credentials for that client. As described in Section 5.2, the Campbell, et al. Expires October 12, 2017 [Page 3] Internet-Draft MTLSPOC April 2017 authorization server MUST enforce some method of binding a certificate to a client. 2.2. Authorization Server Metadata "tls_client_auth" is used as a new value of the "token_endpoint_auth_methods_supported" metadata parameter to indicate server support for mutual TLS as a client authentication method in authorization server metadata such as [OpenID.Discovery] and [I-D.ietf-oauth-discovery]. 2.3. Dynamic Client Registration This draft adds the following values and metadata parameters to the OAuth 2.0 Dynamic Client Registration [RFC7591]. The value "tls_client_auth" is used to indicate the client's intention to use mutual TLS as an authentication method to the token endpoint for the "token_endpoint_auth_method" client metadata field. For authorization servers that associate certificates with clients using subject information in the certificate, the following two new string metadata parameters can be used: tls_client_auth_subject_dn The expected subject distinguished name of the client certificate can be represented using "tls_client_auth_subject_dn". tls_client_auth_issuer_dn The metadata parameter "tls_client_auth_issuer_dn" can optionally be used to constrain the expected distinguished name of the root issuer of the client certificate. For authorization servers that use the key or full certificate to associate clients with certificate, the existing "jwks_uri" or "jwks" metadata parameters from [RFC7591] shall be used. 3. Mutual TLS Sender Constrained Resources Access When mutual TLS X.509 client certificate authentication is used at the token endpoint, the authorization server is able to bind the issued access token to the client certificate. Such a binding is accomplished by associating a hash of the certificate with the token in a way that can be accessed by the protected resource, such as embedding the certificate hash in the issued access token directly, using the syntax described in Section 3.1, or through token introspection [RFC7662]. The specific method for associating the certificate with the access token is determined by the authorization Campbell, et al. Expires October 12, 2017 [Page 4] Internet-Draft MTLSPOC April 2017 server and the protected resource, and is beyond the scope for this specification. The client makes protected resource requests as described in [RFC6750], however, those requests MUST be made over a mutually authenticated TLS connection using the same certificate that was used to authenticate to the token endpoint. The protected resource MUST obtain the client certificate used for TLS authentication and MUST verify that the hash of that certificate exactly matches the hash of the certificate associated with the access token. If the hash values do not match, the resource access attempt MUST be rejected with an error. 3.1. X.509 Certificate SHA-256 Thumbprint Confirmation Method for JWT When access tokens are represented as a JSON Web Tokens (JWT)[RFC7519], the certificate hash information SHOULD be represented using the "x5t#S256" confirmation method member defined herein. To represent the hash of a certificate in a JWT, this specification defines the new JWT Confirmation Method RFC 7800 [RFC7800] member "x5t#S256" for the X.509 Certificate SHA-256 Thumbprint. The value of the "x5t#S256" member is a base64url-encoded SHA-256[SHS] hash (a.k.a. thumbprint or digest) of the DER encoding of the X.509 certificate[RFC5280] (note that certificate thumbprints are also sometimes also known as certificate fingerprints). The following is an example of a JWT payload containing an "x5t#S256" certificate thumbprint confirmation method. { "iss": "https://server.example.com", "aud": "https://resource.example.org", "sub": "ty.webb@example.com", "exp": "1493726400", "nbf": "1493722800", "cnf":{ "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" } } Figure 1: Example claims of a Certificate Thumbprint Constrained JWT. Campbell, et al. Expires October 12, 2017 [Page 5] Internet-Draft MTLSPOC April 2017 4. IANA Considerations 4.1. JWT Confirmation Methods Registration This specification requests registration of the following value in the IANA "JWT Confirmation Methods" registry [IANA.JWT.Claims] for JWT "cnf" member values established by [RFC7800]. 4.1.1. Registry Contents o Confirmation Method Value: "x5t#S256" o Confirmation Method Description: X.509 Certificate SHA-256 Thumbprint o Change Controller: IESG o Specification Document(s): Section 3.1 of [[ this specification ]] 4.2. Token Endpoint Authentication Method Registration This specification requests registration of the following value in the IANA "OAuth Token Endpoint Authentication Methods" registry [IANA.OAuth.Parameters] established by [RFC7591]. 4.2.1. Registry Contents o Token Endpoint Authentication Method Name: "tls_client_auth" o Change Controller: IESG o Specification Document(s): Section 2.2 of [[ this specification ]] 4.3. OAuth Dynamic Client Registration Metadata Registration This specification requests registration of the following client metadata definitions in the IANA "OAuth Dynamic Client Registration Metadata" registry [IANA.OAuth.Parameters] established by [RFC7591]: 4.3.1. Registry Contents o Client Metadata Name: "tls_client_auth_subject_dn" o Client Metadata Description: String value specifying the expected subject distinguished name of the client certificate. o Change Controller: IESG o Specification Document(s): Section 2.3 of [[ this specification ]] o Client Metadata Name: "tls_client_auth_issuer_dn" o Client Metadata Description: String value specifying the expected distinguished name of the root issuer of the client certificate o Change Controller: IESG o Specification Document(s): Section 2.3 of [[ this specification ]] Campbell, et al. Expires October 12, 2017 [Page 6] Internet-Draft MTLSPOC April 2017 5. Security Considerations 5.1. TLS Versions and Best Practices TLS 1.2 [RFC5246] is cited in this document because, at the time of writing, it is latest version that is widely deployed. However, this document is applicable with other TLS versions supporting certificate-based client authentication. Implementation security considerations for TLS, including version recommendations, can be found in Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]. 5.2. Client Identity Binding No specific method of binding a certificate to a client identifier at the token endoint is prescribed by this document. However, some method MUST be employed so that, in addition to proving possession of the private key corresponding to the certificate, the client identity is also bound to the certificate. One such binding would be to configure for the client a value that the certificate must contain in the subject field or the subjectAltName extension and possibly a restricted set of trust anchors. An alternative method would be to configure a public key for the client directly that would have to match the subject public key info of the certificate. 6. References 6.1. Normative References [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, . Campbell, et al. Expires October 12, 2017 [Page 7] Internet-Draft MTLSPOC April 2017 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . [RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of- Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016, . [SHS] National Institute of Standards and Technology, "Secure Hash Standard (SHS)", FIPS PUB 180-4, March 2012, . 6.2. Informative References [I-D.ietf-oauth-discovery] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", draft-ietf-oauth- discovery-04 (work in progress), August 2016. [IANA.JWT.Claims] IANA, "JSON Web Token Claims", . [IANA.OAuth.Parameters] IANA, "OAuth Parameters", . [OpenID.Discovery] Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Connect Discovery 1.0", February 2014. [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . Campbell, et al. Expires October 12, 2017 [Page 8] Internet-Draft MTLSPOC April 2017 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, . [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, . Appendix A. Acknowledgements Scott "not Tomlinson" Tomilson and Matt Peterson were involved in the original design and development work on a mutual TLS client authentication implementation that informed some of the content of this document. Additionally, the authors would like to thank the following people for their input and contributions to the specification: Sergey Beryozkin, Vladimir Dzhuvinov, Samuel Erdtman, Phil Hunt, Sean Leonard, Kepeng Li, Jim Manico, Nov Matake, Sascha Preibisch, Justin Richer, Dave Tonge, and Hannes Tschofenig. Appendix B. Document(s) History [[ to be removed by the RFC Editor before publication as an RFC ]] draft-campbell-oauth-mtls-01 o Fix some typos. o Add to the acknowledgements list. draft-campbell-oauth-mtls-00 o Add a Mutual TLS sender constrained protected resource access method and a x5t#S256 cnf method for JWT access tokens (concepts taken in part from draft-sakimura-oauth-jpop-04). o Fixed "token_endpoint_auth_methods_supported" to "token_endpoint_auth_method" for client metadata. o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" client metadata parameters and mention using "jwks_uri" or "jwks". o Say that the authentication method is determined by client policy regardless of whether the client was dynamically registered or statically configured. o Expand acknowledgements to those that participated in discussions around draft-campbell-oauth-tls-client-auth-00 o Add Nat Sakimura and Torsten Lodderstedt to the author list. draft-campbell-oauth-tls-client-auth-00 Campbell, et al. Expires October 12, 2017 [Page 9] Internet-Draft MTLSPOC April 2017 o Initial draft. Authors' Addresses Brian Campbell Ping Identity Email: brian.d.campbell@gmail.com John Bradley Ping Identity Email: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/ Nat Sakimura Nomura Research Institute Email: n-sakimura@nri.co.jp URI: https://nat.sakimura.org/ Torsten Lodderstedt YES Europe AG Email: torsten@lodderstedt.net Campbell, et al. Expires October 12, 2017 [Page 10]