OAuth Working Group                                          B. Campbell
Internet-Draft                                                J. Bradley
Intended status: Standards Track                           Ping Identity
Expires: October 1, 2017                                     N. Sakimura
                                               Nomura Research Institute
                                                          T. Lodderstedt
                                                           YES Europe AG
                                                          March 30, 2017


                 Mutual TLS Profiles for OAuth Clients
                      draft-campbell-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 October 1, 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 1, 2017                [Page 1]


Internet-Draft                   MTLSPOC                      March 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 1, 2017                [Page 2]


Internet-Draft                   MTLSPOC                      March 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 can 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 1, 2017                [Page 3]


Internet-Draft                   MTLSPOC                      March 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 1, 2017                [Page 4]


Internet-Draft                   MTLSPOC                      March 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 1, 2017                [Page 5]


Internet-Draft                   MTLSPOC                      March 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 1, 2017                [Page 6]


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

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







Campbell, et al.         Expires October 1, 2017                [Page 7]


Internet-Draft                   MTLSPOC                      March 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,
              <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>.

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




Campbell, et al.         Expires October 1, 2017                [Page 8]


Internet-Draft                   MTLSPOC                      March 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,
              <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, Jim Manico, Sascha Preibisch, Justin Richer, and Hannes
   Tschofenig.

Appendix B.  Document(s) History

   [[ to be removed by the RFC Editor before publication as an RFC ]]

   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.






Campbell, et al.         Expires October 1, 2017                [Page 9]


Internet-Draft                   MTLSPOC                      March 2017


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