Internet DRAFT - draft-campbell-oauth-mtls
draft-campbell-oauth-mtls
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, <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 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,
<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 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,
<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, 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]