OAuth Working Group                                          B. Campbell
Internet-Draft                                                J. Bradley
Intended status: Standards Track                           Ping Identity
Expires: November 10, 2017                                   N. Sakimura
                                               Nomura Research Institute
                                                          T. Lodderstedt
                                                           YES Europe AG
                                                             May 9, 2017


                 Mutual TLS Profiles for OAuth Clients
                        draft-ietf-oauth-mtls-00

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 November 10, 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 November 10, 2017               [Page 1]


Internet-Draft                   MTLSPOC                        May 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
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   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  . . . . . . .   5
     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 . . . . . . . . . . . . . . . . . .   7
   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 November 10, 2017               [Page 2]


Internet-Draft                   MTLSPOC                        May 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].

1.2.  Terminology

   This specification uses the following phrases interchangeably:

      Transport Layer Security (TLS) Mutual Authentication

      Mutual TLS

      Mutual TLS X.509 client certificate authentication

   These phrases all refer to the process whereby a client uses it's
   X.509 certificate to authenticate itself with a server when
   negotiating a TLS session.  In TLS 1.2 [RFC5246] this requires the
   client to send Client Certificate and Certificate Verify messages
   during the TLS handshake and for the server to verify these messages.

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 X.509 client
   certificates 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



Campbell, et al.        Expires November 10, 2017               [Page 3]


Internet-Draft                   MTLSPOC                        May 2017


   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
   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.



Campbell, et al.        Expires November 10, 2017               [Page 4]


Internet-Draft                   MTLSPOC                        May 2017


   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
   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.





Campbell, et al.        Expires November 10, 2017               [Page 5]


Internet-Draft                   MTLSPOC                        May 2017


   {
     "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.

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]:





Campbell, et al.        Expires November 10, 2017               [Page 6]


Internet-Draft                   MTLSPOC                        May 2017


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 ]]

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, <http://www.rfc-editor.org/info/bcp195>.



Campbell, et al.        Expires November 10, 2017               [Page 7]


Internet-Draft                   MTLSPOC                        May 2017


   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008,
              <http://www.rfc-editor.org/info/rfc5246>.

   [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,
              <http://www.rfc-editor.org/info/rfc5280>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <http://www.rfc-editor.org/info/rfc6749>.

   [RFC6750]  Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
              Framework: Bearer Token Usage", RFC 6750,
              DOI 10.17487/RFC6750, October 2012,
              <http://www.rfc-editor.org/info/rfc6750>.

   [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,
              <http://www.rfc-editor.org/info/rfc7800>.

   [SHS]      National Institute of Standards and Technology, "Secure
              Hash Standard (SHS)", FIPS PUB 180-4, March 2012,
              <http://csrc.nist.gov/publications/fips/fips180-4/
              fips-180-4.pdf>.

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",
              <http://www.iana.org/assignments/jwt>.






Campbell, et al.        Expires November 10, 2017               [Page 8]


Internet-Draft                   MTLSPOC                        May 2017


   [IANA.OAuth.Parameters]
              IANA, "OAuth Parameters",
              <http://www.iana.org/assignments/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,
              <http://www.rfc-editor.org/info/rfc7519>.

   [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,
              <http://www.rfc-editor.org/info/rfc7591>.

   [RFC7662]  Richer, J., Ed., "OAuth 2.0 Token Introspection",
              RFC 7662, DOI 10.17487/RFC7662, October 2015,
              <http://www.rfc-editor.org/info/rfc7662>.

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, James Manger, 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-ietf-oauth-mtls-00

   o  Created the initial working group version from draft-campbell-
      oauth-mtls

   draft-campbell-oauth-mtls-01

   o  Fix some typos.
   o  Add to the acknowledgements list.




Campbell, et al.        Expires November 10, 2017               [Page 9]


Internet-Draft                   MTLSPOC                        May 2017


   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

   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 November 10, 2017              [Page 10]