< draft-ietf-oauth-mtls-14.txt   draft-ietf-oauth-mtls-15.txt >
OAuth Working Group B. Campbell OAuth Working Group B. Campbell
Internet-Draft Ping Identity Internet-Draft Ping Identity
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: October 13, 2019 Yubico Expires: January 4, 2020 Yubico
N. Sakimura N. Sakimura
Nomura Research Institute Nomura Research Institute
T. Lodderstedt T. Lodderstedt
YES.com AG YES.com AG
April 11, 2019 July 3, 2019
OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound
Access Tokens Access Tokens
draft-ietf-oauth-mtls-14 draft-ietf-oauth-mtls-15
Abstract Abstract
This document describes OAuth client authentication and certificate- This document describes OAuth client authentication and certificate-
bound access and refresh tokens using mutual Transport Layer Security bound access and refresh tokens using mutual Transport Layer Security
(TLS) authentication with X.509 certificates. OAuth clients are (TLS) authentication with X.509 certificates. OAuth clients are
provided a mechanism for authentication to the authorization server provided a mechanism for authentication to the authorization server
using mutual TLS, based on either self-signed certificates or public using mutual TLS, based on either self-signed certificates or public
key infrastructure (PKI). OAuth authorization servers are provided a key infrastructure (PKI). OAuth authorization servers are provided a
mechanism for binding access tokens to a client's mutual TLS mechanism for binding access tokens to a client's mutual TLS
skipping to change at page 1, line 45 skipping to change at page 1, line 45
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 13, 2019. This Internet-Draft will expire on January 4, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Notation and Conventions . . . . . . . . . . 5 1.1. Requirements Notation and Conventions . . . . . . . . . . 5
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2. Mutual TLS for OAuth Client Authentication . . . . . . . . . 5 2. Mutual TLS for OAuth Client Authentication . . . . . . . . . 5
2.1. PKI Mutual TLS Method . . . . . . . . . . . . . . . . . . 6 2.1. PKI Mutual TLS Method . . . . . . . . . . . . . . . . . . 6
2.1.1. PKI Method Metadata Value . . . . . . . . . . . . . . 6 2.1.1. PKI Method Metadata Value . . . . . . . . . . . . . . 7
2.1.2. Client Registration Metadata . . . . . . . . . . . . 7 2.1.2. Client Registration Metadata . . . . . . . . . . . . 7
2.2. Self-Signed Certificate Mutual TLS Method . . . . . . . . 7 2.2. Self-Signed Certificate Mutual TLS Method . . . . . . . . 8
2.2.1. Self-Signed Method Metadata Value . . . . . . . . . . 8 2.2.1. Self-Signed Method Metadata Value . . . . . . . . . . 8
2.2.2. Client Registration Metadata . . . . . . . . . . . . 8 2.2.2. Client Registration Metadata . . . . . . . . . . . . 8
3. Mutual TLS Client Certificate-Bound Access Tokens . . . . . . 8 3. Mutual TLS Client Certificate-Bound Access Tokens . . . . . . 9
3.1. JWT Certificate Thumbprint Confirmation Method . . . . . 9 3.1. JWT Certificate Thumbprint Confirmation Method . . . . . 9
3.2. Confirmation Method for Token Introspection . . . . . . . 10 3.2. Confirmation Method for Token Introspection . . . . . . . 10
3.3. Authorization Server Metadata . . . . . . . . . . . . . . 11 3.3. Authorization Server Metadata . . . . . . . . . . . . . . 11
3.4. Client Registration Metadata . . . . . . . . . . . . . . 11 3.4. Client Registration Metadata . . . . . . . . . . . . . . 11
4. Public Clients and Certificate-Bound Tokens . . . . . . . . . 11 4. Public Clients and Certificate-Bound Tokens . . . . . . . . . 12
5. Metadata for Mutual TLS Endpoint Aliases . . . . . . . . . . 12 5. Metadata for Mutual TLS Endpoint Aliases . . . . . . . . . . 12
6. Implementation Considerations . . . . . . . . . . . . . . . . 13 6. Implementation Considerations . . . . . . . . . . . . . . . . 14
6.1. Authorization Server . . . . . . . . . . . . . . . . . . 14 6.1. Authorization Server . . . . . . . . . . . . . . . . . . 14
6.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 14 6.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 15
6.3. Certificate Expiration and Bound Access Tokens . . . . . 15 6.3. Certificate Expiration and Bound Access Tokens . . . . . 15
6.4. Implicit Grant Unsupported . . . . . . . . . . . . . . . 15 6.4. Implicit Grant Unsupported . . . . . . . . . . . . . . . 15
6.5. TLS Termination . . . . . . . . . . . . . . . . . . . . . 15 6.5. TLS Termination . . . . . . . . . . . . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
7.1. Certificate-Bound Refresh Tokens . . . . . . . . . . . . 15 7.1. Certificate-Bound Refresh Tokens . . . . . . . . . . . . 16
7.2. Certificate Thumbprint Binding . . . . . . . . . . . . . 16 7.2. Certificate Thumbprint Binding . . . . . . . . . . . . . 16
7.3. TLS Versions and Best Practices . . . . . . . . . . . . . 16 7.3. TLS Versions and Best Practices . . . . . . . . . . . . . 17
7.4. X.509 Certificate Spoofing . . . . . . . . . . . . . . . 16 7.4. X.509 Certificate Spoofing . . . . . . . . . . . . . . . 17
7.5. X.509 Certificate Parsing and Validation Complexity . . . 16 7.5. X.509 Certificate Parsing and Validation Complexity . . . 17
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
9.1. JWT Confirmation Methods Registration . . . . . . . . . . 17 9.1. JWT Confirmation Methods Registration . . . . . . . . . . 18
9.2. Authorization Server Metadata Registration . . . . . . . 18 9.2. Authorization Server Metadata Registration . . . . . . . 18
9.3. Token Endpoint Authentication Method Registration . . . . 18 9.3. Token Endpoint Authentication Method Registration . . . . 19
9.4. Token Introspection Response Registration . . . . . . . . 18 9.4. Token Introspection Response Registration . . . . . . . . 19
9.5. Dynamic Client Registration Metadata Registration . . . . 19 9.5. Dynamic Client Registration Metadata Registration . . . . 20
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
10.1. Normative References . . . . . . . . . . . . . . . . . . 20 10.1. Normative References . . . . . . . . . . . . . . . . . . 21
10.2. Informative References . . . . . . . . . . . . . . . . . 21 10.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Example "cnf" Claim, Certificate and JWK . . . . . . 23 Appendix A. Example "cnf" Claim, Certificate and JWK . . . . . . 23
Appendix B. Relationship to Token Binding . . . . . . . . . . . 24 Appendix B. Relationship to Token Binding . . . . . . . . . . . 24
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 24 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 25
Appendix D. Document(s) History . . . . . . . . . . . . . . . . 25 Appendix D. Document(s) History . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction 1. Introduction
The OAuth 2.0 Authorization Framework [RFC6749] enables third-party The OAuth 2.0 Authorization Framework [RFC6749] enables third-party
client applications to obtain delegated access to protected client applications to obtain delegated access to protected
resources. In the prototypical abstract OAuth flow, illustrated in resources. In the prototypical abstract OAuth flow, illustrated in
Figure 1, the client obtains an access token from an entity known as Figure 1, the client obtains an access token from an entity known as
an authorization server and then uses that token when accessing an authorization server and then uses that token when accessing
protected resources, such as HTTPS APIs. protected resources, such as HTTPS APIs.
skipping to change at page 5, line 15 skipping to change at page 5, line 15
token described in [RFC6750], where any party in possession of the token described in [RFC6750], where any party in possession of the
access token can use it to access the associated resources. Binding access token can use it to access the associated resources. Binding
an access token to the client's certificate prevents the use of an access token to the client's certificate prevents the use of
stolen access tokens or replay of access tokens by unauthorized stolen access tokens or replay of access tokens by unauthorized
parties. parties.
Mutual TLS certificate-bound access tokens and mutual TLS client Mutual TLS certificate-bound access tokens and mutual TLS client
authentication are distinct mechanisms, which are complementary but authentication are distinct mechanisms, which are complementary but
don't necessarily need to be deployed or used together. don't necessarily need to be deployed or used together.
Additional client metadata parameters are introduced by this document
in support of certificate-bound access tokens and mutual TLS client
authentication. The authorization server can obtain client metadata
via the Dynamic Client Registration Protocol [RFC7591], which defines
mechanisms for dynamically registering OAuth 2.0 client metadata with
authorization servers. Also the metadata defined by RFC7591, and
registered extensions to it, imply a general data model for clients
that is useful for authorization server implementations even when the
Dynamic Client Registration Protocol isn't in play. Such
implementations will typically have some sort of user interface
available for managing client configuration.
1.1. Requirements Notation and Conventions 1.1. Requirements Notation and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
1.2. Terminology 1.2. Terminology
skipping to change at page 6, line 11 skipping to change at page 6, line 23
For all requests to the authorization server utilizing mutual TLS For all requests to the authorization server utilizing mutual TLS
client authentication, the client MUST include the "client_id" client authentication, the client MUST include the "client_id"
parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The parameter, described in OAuth 2.0, Section 2.2 [RFC6749]. The
presence of the "client_id" parameter enables the authorization presence of the "client_id" parameter enables the authorization
server to easily identify the client independently from the content server to easily identify the client independently from the content
of the certificate. The authorization server can locate the client of the certificate. The authorization server can locate the client
configuration using the client identifier and check the certificate configuration using the client identifier and check the certificate
presented in the TLS Handshake against the expected credentials for presented in the TLS Handshake against the expected credentials for
that client. The authorization server MUST enforce the binding that client. The authorization server MUST enforce the binding
between client and certificate as described in either Section 2.1 or between client and certificate as described in either Section 2.1 or
Section 2.2 below. Section 2.2 below. If the presented certificate doesn't match that
which is expected for the given "client_id", the authorization server
returns a normal OAuth 2.0 error response per Section 5.2 of RFC6749
[RFC6749] with the "invalid_client" error code to indicate failed
client authentication.
2.1. PKI Mutual TLS Method 2.1. PKI Mutual TLS Method
The PKI (public key infrastructure) method of mutual TLS OAuth client The PKI (public key infrastructure) method of mutual TLS OAuth client
authentication adheres to the way in which X.509 certificates are authentication adheres to the way in which X.509 certificates are
traditionally used for authentication. It relies on a validated traditionally used for authentication. It relies on a validated
certificate chain [RFC5280] and a single subject distinguished name certificate chain [RFC5280] and a single subject distinguished name
(DN) or a single subject alternative name (SAN) to authenticate the (DN) or a single subject alternative name (SAN) to authenticate the
client. Only one subject name value of any type is used for each client. Only one subject name value of any type is used for each
client. The TLS handshake is utilized to validate the client's client. The TLS handshake is utilized to validate the client's
skipping to change at page 7, line 46 skipping to change at page 8, line 11
client will use in mutual TLS authentication. client will use in mutual TLS authentication.
tls_client_auth_san_email tls_client_auth_san_email
A string containing the value of an expected rfc822Name SAN entry A string containing the value of an expected rfc822Name SAN entry
in the certificate, which the OAuth client will use in mutual TLS in the certificate, which the OAuth client will use in mutual TLS
authentication. authentication.
2.2. Self-Signed Certificate Mutual TLS Method 2.2. Self-Signed Certificate Mutual TLS Method
This method of mutual TLS OAuth client authentication is intended to This method of mutual TLS OAuth client authentication is intended to
support client authentication using self-signed certificates. As support client authentication using self-signed certificates. As a
pre-requisite, the client registers its X.509 certificates (using prerequisite, the client registers its X.509 certificates (using
"jwks" defined in [RFC7591]) or a trusted source for its X.509 "jwks" defined in [RFC7591]) or a reference to a trusted source for
certificates (using "jwks_uri" from [RFC7591]) with the authorization its X.509 certificates (using "jwks_uri" from [RFC7591]) with the
server. During authentication, TLS is utilized to validate the authorization server. During authentication, TLS is utilized to
client's possession of the private key corresponding to the public validate the client's possession of the private key corresponding to
key presented within the certificate in the respective TLS handshake. the public key presented within the certificate in the respective TLS
handshake. In contrast to the PKI method, the client's certificate
In contrast to the PKI method, the client's certificate chain is not chain is not validated by the server in this case. The client is
validated by the server in this case. The client is successfully successfully authenticated if the certificate that it presented
authenticated if the certificate that it presented during the during the handshake matches one of the certificates configured or
handshake matches one of the certificates configured or registered registered for that particular client. The Self-Signed Certificate
for that particular client. The Self-Signed Certificate method method allows the use of mutual TLS to authenticate clients without
allows the use of mutual TLS to authenticate clients without the need the need to maintain a PKI. When used in conjunction with a
to maintain a PKI. When used in conjunction with a "jwks_uri" for "jwks_uri" for the client, it also allows the client to rotate its
the client, it also allows the client to rotate its X.509 X.509 certificates without the need to change its respective
certificates without the need to change its respective authentication authentication data directly with the authorization server.
data directly with the authorization server.
2.2.1. Self-Signed Method Metadata Value 2.2.1. Self-Signed Method Metadata Value
For the Self-Signed Certificate method of mutual TLS client For the Self-Signed Certificate method of mutual TLS client
authentication, this specification defines and registers the authentication, this specification defines and registers the
following authentication method metadata value into the "OAuth Token following authentication method metadata value into the "OAuth Token
Endpoint Authentication Methods" registry [IANA.OAuth.Parameters]. Endpoint Authentication Methods" registry [IANA.OAuth.Parameters].
self_signed_tls_client_auth self_signed_tls_client_auth
Indicates that client authentication to the authorization server Indicates that client authentication to the authorization server
skipping to change at page 8, line 41 skipping to change at page 9, line 6
a client using mutual TLS client authentication, the existing a client using mutual TLS client authentication, the existing
"jwks_uri" or "jwks" metadata parameters from [RFC7591] are used to "jwks_uri" or "jwks" metadata parameters from [RFC7591] are used to
convey the client's certificates via JSON Web Key (JWK) in a JWK Set convey the client's certificates via JSON Web Key (JWK) in a JWK Set
(JWKS) [RFC7517]. The "jwks" metadata parameter is a JWK Set (JWKS) [RFC7517]. The "jwks" metadata parameter is a JWK Set
containing the client's public keys as an array of JWKs while the containing the client's public keys as an array of JWKs while the
"jwks_uri" parameter is a URL that references a client's JWK Set. A "jwks_uri" parameter is a URL that references a client's JWK Set. A
certificate is represented with the "x5c" parameter of an individual certificate is represented with the "x5c" parameter of an individual
JWK within the set. Note that the members of the JWK representing JWK within the set. Note that the members of the JWK representing
the public key (e.g. "n" and "e" for RSA, "x" and "y" for EC) are the public key (e.g. "n" and "e" for RSA, "x" and "y" for EC) are
required parameters per [RFC7518] so will be present even though they required parameters per [RFC7518] so will be present even though they
are not utilized in this context. Also note that that sec 4.7 of are not utilized in this context. Also note that that Section 4.7 of
[RFC7517] requires that the key in the first certificate of the "x5c" [RFC7517] requires that the key in the first certificate of the "x5c"
parameter match the public key represented by those other members of parameter match the public key represented by those other members of
the JWK. the JWK.
3. Mutual TLS Client Certificate-Bound Access Tokens 3. Mutual TLS Client Certificate-Bound Access Tokens
When mutual TLS is used by the client on the connection to the token When mutual TLS is used by the client on the connection to the token
endpoint, the authorization server is able to bind the issued access endpoint, the authorization server is able to bind the issued access
token to the client certificate. Such a binding is accomplished by token to the client certificate. Such a binding is accomplished by
associating the certificate with the token in a way that can be associating the certificate with the token in a way that can be
skipping to change at page 9, line 41 skipping to change at page 10, line 9
3.1. JWT Certificate Thumbprint Confirmation Method 3.1. JWT Certificate Thumbprint Confirmation Method
When access tokens are represented as JSON Web Tokens (JWT)[RFC7519], When access tokens are represented as JSON Web Tokens (JWT)[RFC7519],
the certificate hash information SHOULD be represented using the the certificate hash information SHOULD be represented using the
"x5t#S256" confirmation method member defined herein. "x5t#S256" confirmation method member defined herein.
To represent the hash of a certificate in a JWT, this specification To represent the hash of a certificate in a JWT, this specification
defines the new JWT Confirmation Method [RFC7800] member "x5t#S256" defines the new JWT Confirmation Method [RFC7800] member "x5t#S256"
for the X.509 Certificate SHA-256 Thumbprint. The value of the for the X.509 Certificate SHA-256 Thumbprint. The value of the
"x5t#S256" member is a base64url-encoded [RFC4648] SHA-256 [SHS] hash "x5t#S256" member is a base64url-encoded [RFC4648] SHA-256 [SHS] hash
(a.k.a. thumbprint, fingerprint or digest) of the DER encoding of the (a.k.a. thumbprint, fingerprint or digest) of the DER encoding [X690]
X.509 certificate [RFC5280]. The base64url-encoded value MUST omit of the X.509 certificate [RFC5280]. The base64url-encoded value MUST
all trailing pad '=' characters and MUST NOT include any line breaks, omit all trailing pad '=' characters and MUST NOT include any line
whitespace, or other additional characters. breaks, whitespace, or other additional characters.
The following is an example of a JWT payload containing an "x5t#S256" The following is an example of a JWT payload containing an "x5t#S256"
certificate thumbprint confirmation method. certificate thumbprint confirmation method. The new JWT content
introduced by this specification is the "cnf" confirmation method
claim at the bottom of the example that has the "x5t#S256"
confirmation method member containing the value that is the hash of
the client certificate to which the access token is bound.
{ {
"iss": "https://server.example.com", "iss": "https://server.example.com",
"sub": "ty.webb@example.com", "sub": "ty.webb@example.com",
"exp": 1493726400, "exp": 1493726400,
"nbf": 1493722800, "nbf": 1493722800,
"cnf":{ "cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
} }
} }
skipping to change at page 10, line 37 skipping to change at page 11, line 4
protected resource as meta-information in a token introspection protected resource as meta-information in a token introspection
response. The hash is conveyed using the same "cnf" with "x5t#S256" response. The hash is conveyed using the same "cnf" with "x5t#S256"
member structure as the certificate SHA-256 thumbprint confirmation member structure as the certificate SHA-256 thumbprint confirmation
method, described in Section 3.1, as a top-level member of the method, described in Section 3.1, as a top-level member of the
introspection response JSON. The protected resource compares that introspection response JSON. The protected resource compares that
certificate hash to a hash of the client certificate used for mutual certificate hash to a hash of the client certificate used for mutual
TLS authentication and rejects the request, if they do not match. TLS authentication and rejects the request, if they do not match.
The following is an example of an introspection response for an The following is an example of an introspection response for an
active token with an "x5t#S256" certificate thumbprint confirmation active token with an "x5t#S256" certificate thumbprint confirmation
method. method. The new introspection response content introduced by this
specification is the "cnf" confirmation method at the bottom of the
example that has the "x5t#S256" confirmation method member containing
the value that is the hash of the client certificate to which the
access token is bound.
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"active": true, "active": true,
"iss": "https://server.example.com", "iss": "https://server.example.com",
"sub": "ty.webb@example.com", "sub": "ty.webb@example.com",
"exp": 1493726400, "exp": 1493726400,
"nbf": 1493722800, "nbf": 1493722800,
skipping to change at page 13, line 13 skipping to change at page 13, line 23
directly to the authorization server MUST use the alias URL of the directly to the authorization server MUST use the alias URL of the
endpoint within the "mtls_endpoint_aliases", when present, in endpoint within the "mtls_endpoint_aliases", when present, in
preference to the endpoint URL of the same name at top-level of preference to the endpoint URL of the same name at top-level of
metadata. When an endpoint is not present in metadata. When an endpoint is not present in
"mtls_endpoint_aliases", then the client uses the conventional "mtls_endpoint_aliases", then the client uses the conventional
endpoint URL defined at the top-level of the authorization server endpoint URL defined at the top-level of the authorization server
metadata. Metadata parameters within "mtls_endpoint_aliases" that metadata. Metadata parameters within "mtls_endpoint_aliases" that
do not define endpoints to which an OAuth client makes a direct do not define endpoints to which an OAuth client makes a direct
request have no meaning and SHOULD be ignored. request have no meaning and SHOULD be ignored.
Below is an example of an authorization server metatdata document Below is an example of an authorization server metadata document with
with the "mtls_endpoint_aliases" parameter, which indicates aliases the "mtls_endpoint_aliases" parameter, which indicates aliases for
for the token, revocation, and introspection endpoints that an OAuth the token, revocation, and introspection endpoints that an OAuth
client intending to do mutual TLS would in preference to the client intending to do mutual TLS would in preference to the
conventional token, revocation, and introspection endpoints. Note conventional token, revocation, and introspection endpoints. Note
that the endpoints in "mtls_endpoint_aliases" use a different host that the endpoints in "mtls_endpoint_aliases" use a different host
than their conventional counterparts, which allows the authorization than their conventional counterparts, which allows the authorization
server (via SNI or actual distinct hosts) to differentiate its TLS server (via SNI or actual distinct hosts) to differentiate its TLS
behavior as appropriate. behavior as appropriate.
{ {
"issuer": "https://server.example.com", "issuer": "https://server.example.com",
"authorization_endpoint": "https://server.example.com/authz", "authorization_endpoint": "https://server.example.com/authz",
skipping to change at page 14, line 43 skipping to change at page 15, line 22
which are aliases for the originals that a client intending to do which are aliases for the originals that a client intending to do
mutual TLS will use in preference to the conventional endpoints. mutual TLS will use in preference to the conventional endpoints.
6.2. Resource Server 6.2. Resource Server
OAuth divides the roles and responsibilities such that the resource OAuth divides the roles and responsibilities such that the resource
server relies on the authorization server to perform client server relies on the authorization server to perform client
authentication and obtain resource owner (end-user) authorization. authentication and obtain resource owner (end-user) authorization.
The resource server makes authorization decisions based on the access The resource server makes authorization decisions based on the access
token presented by the client but does not directly authenticate the token presented by the client but does not directly authenticate the
client per se. The the manner in which an access token is bound to client per se. The manner in which an access token is bound to the
the client certificate decouples it from the specific method that the client certificate decouples it from the specific method that the
client used to authenticate with the authorization server. Mutual client used to authenticate with the authorization server. Mutual
TLS during protected resource access can therefore serve purely as a TLS during protected resource access can therefore serve purely as a
proof-of-possession mechanism. As such, it is not necessary for the proof-of-possession mechanism. As such, it is not necessary for the
resource server to validate the trust chain of the client's resource server to validate the trust chain of the client's
certificate in any of the methods defined in this document. The certificate in any of the methods defined in this document. The
resource server would therefore configure the TLS stack in a way that resource server would therefore configure the TLS stack in a way that
it does not verify whether the certificate presented by the client it does not verify whether the certificate presented by the client
during the handshake is signed by a trusted CA certificate. during the handshake is signed by a trusted CA certificate.
6.3. Certificate Expiration and Bound Access Tokens 6.3. Certificate Expiration and Bound Access Tokens
skipping to change at page 16, line 21 skipping to change at page 16, line 46
The binding between the certificate and access token specified in The binding between the certificate and access token specified in
Section 3.1 uses a cryptographic hash of the certificate. It relies Section 3.1 uses a cryptographic hash of the certificate. It relies
on the hash function having sufficient preimage and second-preimage on the hash function having sufficient preimage and second-preimage
resistance so as to make it computationally infeasible to find or resistance so as to make it computationally infeasible to find or
create another certificate that produces to the same hash output create another certificate that produces to the same hash output
value. The SHA-256 hash function was used because it meets the value. The SHA-256 hash function was used because it meets the
aforementioned requirement while being widely available. If, in the aforementioned requirement while being widely available. If, in the
future, certificate thumbprints need to be computed using hash future, certificate thumbprints need to be computed using hash
function(s) other than SHA-256, it is suggested that additional function(s) other than SHA-256, it is suggested that additional
related JWT confirmation methods members be defined for that purpose related JWT confirmation methods members be defined for that purpose
and registered in the the IANA "JWT Confirmation Methods" registry and registered in the IANA "JWT Confirmation Methods" registry
[IANA.JWT.Claims] for JWT "cnf" member values. [IANA.JWT.Claims] for JWT "cnf" member values.
7.3. TLS Versions and Best Practices 7.3. TLS Versions and Best Practices
In the abstract this document is applicable with any TLS version In the abstract this document is applicable with any TLS version
supporting certificate-based client authentication. Both TLS 1.3 supporting certificate-based client authentication. Both TLS 1.3
[RFC8446] and TLS 1.2 [RFC5246] are cited herein because, at the time [RFC8446] and TLS 1.2 [RFC5246] are cited herein because, at the time
of writing, 1.3 is the newest version while 1.2 is the most widely of writing, 1.3 is the newest version while 1.2 is the most widely
deployed. General implementation and security considerations for deployed. General implementation and security considerations for
TLS, including version recommendations, can be found in [BCP195]. TLS, including version recommendations, can be found in [BCP195].
skipping to change at page 21, line 28 skipping to change at page 22, line 14
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>. <https://www.rfc-editor.org/info/rfc8446>.
[SHS] National Institute of Standards and Technology, "Secure [SHS] National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-4, March 2012, Hash Standard (SHS)", FIPS PUB 180-4, March 2012,
<http://csrc.nist.gov/publications/fips/fips180-4/ <http://csrc.nist.gov/publications/fips/fips180-4/
fips-180-4.pdf>. fips-180-4.pdf>.
[X690] International Telephone and Telegraph Consultative
Committee, "ASN.1 encoding rules: Specification of basic
encoding Rules (BER), Canonical encoding rules (CER) and
Distinguished encoding rules (DER)", CCITT Recommendation
X.690, July 2015.
10.2. Informative References 10.2. Informative References
[CX5P] Wong, D., "Common x509 certificate validation/creation [CX5P] Wong, D., "Common x509 certificate validation/creation
pitfalls", September 2016, pitfalls", September 2016,
<https://www.cryptologie.net/article/374/ <https://www.cryptologie.net/article/374/
common-x509-certificate-validationcreation-pitfalls>. common-x509-certificate-validationcreation-pitfalls>.
[DCW] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, [DCW] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh,
D., and V. Shmatikov, "The Most Dangerous Code in the D., and V. Shmatikov, "The Most Dangerous Code in the
World: Validating SSL Certificates in Non-Browser World: Validating SSL Certificates in Non-Browser
skipping to change at page 23, line 13 skipping to change at page 23, line 51
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", RFC 8414, Authorization Server Metadata", RFC 8414,
DOI 10.17487/RFC8414, June 2018, DOI 10.17487/RFC8414, June 2018,
<https://www.rfc-editor.org/info/rfc8414>. <https://www.rfc-editor.org/info/rfc8414>.
Appendix A. Example "cnf" Claim, Certificate and JWK Appendix A. Example "cnf" Claim, Certificate and JWK
For reference, an "x5t#S256" value and the X.509 Certificate from For reference, an "x5t#S256" value and the X.509 Certificate from
which it was calculated are provided in the following example which it was calculated are provided in the following examples,
figures. A JWK representation of the certificate's public key along Figure 5 and Figure 6 respectively. A JWK representation of the
with the "x5c" member is also provided. certificate's public key along with the "x5c" member is also provided
in Figure 7.
"cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"} "cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"}
Figure 5: x5t#S256 Confirmation Claim Figure 5: x5t#S256 Confirmation Claim
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx
ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ
/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID /Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID
skipping to change at page 24, line 50 skipping to change at page 25, line 36
Appendix C. Acknowledgements Appendix C. Acknowledgements
Scott "not Tomlinson" Tomilson and Matt Peterson were involved in Scott "not Tomlinson" Tomilson and Matt Peterson were involved in
design and development work on a mutual TLS OAuth client design and development work on a mutual TLS OAuth client
authentication implementation, which predates this document. authentication implementation, which predates this document.
Experience and learning from that work informed some of the content Experience and learning from that work informed some of the content
of this document. of this document.
This specification was developed within the OAuth Working Group under This specification was developed within the OAuth Working Group under
the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with the chairmanship of Hannes Tschofenig and Rifaat Shekh-Yusef with
Eric Rescorla and Benjamin Kaduk serving as Security Area Directors. Eric Rescorla, Benjamin Kaduk, and Roman Danyliw serving as Security
Additionally, the following individuals contributed ideas, feedback, Area Directors. Additionally, the following individuals contributed
and wording that helped shape this specification: Vittorio Bertocci, ideas, feedback, and wording that helped shape this specification:
Sergey Beryozkin, Ralph Bragg, Sophie Bremer, Vladimir Dzhuvinov, Vittorio Bertocci, Sergey Beryozkin, Ralph Bragg, Sophie Bremer,
Samuel Erdtman, Evan Gilman, Leif Johansson, Michael Jones, Phil Roman Danyliw, Vladimir Dzhuvinov, Samuel Erdtman, Evan Gilman, Leif
Hunt, Benjamin Kaduk, Takahiko Kawasaki, Sean Leonard, Kepeng Li, Johansson, Michael Jones, Phil Hunt, Benjamin Kaduk, Takahiko
Neil Madden, James Manger, Jim Manico, Nov Matake, Sascha Preibisch, Kawasaki, Sean Leonard, Kepeng Li, Neil Madden, James Manger, Jim
Eric Rescorla, Justin Richer, Filip Skokan, Dave Tonge, and Hannes Manico, Nov Matake, Sascha Preibisch, Eric Rescorla, Justin Richer,
Tschofenig. Filip Skokan, Dave Tonge, and Hannes Tschofenig.
Appendix D. Document(s) History Appendix D. Document(s) History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
draft-ietf-oauth-mtls-15
o Editorial updates from second AD review.
draft-ietf-oauth-mtls-14 draft-ietf-oauth-mtls-14
o Editorial clarifications around there being only a single subject o Editorial clarifications around there being only a single subject
registered/configured per client for the tls_client_auth method. registered/configured per client for the tls_client_auth method.
o Add a brief explanation about how, with tls_client_auth and o Add a brief explanation about how, with tls_client_auth and
self_signed_tls_client_auth, refresh tokens are certificate-bound self_signed_tls_client_auth, refresh tokens are certificate-bound
indirectly via the client authentication. indirectly via the client authentication.
o Add mention of refresh tokens in the abstract. o Add mention of refresh tokens in the abstract.
draft-ietf-oauth-mtls-13 draft-ietf-oauth-mtls-13
skipping to change at page 27, line 15 skipping to change at page 28, line 4
o Note that revocation checking is at the discretion of the AS per o Note that revocation checking is at the discretion of the AS per
WGLC feedback WGLC feedback
o Editorial updates and clarifications o Editorial updates and clarifications
o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf- o Update draft-ietf-oauth-discovery reference to -10 and draft-ietf-
oauth-token-binding to -06 oauth-token-binding to -06
o Add folks involved in WGLC feedback to the acknowledgements list o Add folks involved in WGLC feedback to the acknowledgements list
draft-ietf-oauth-mtls-07 draft-ietf-oauth-mtls-07
o Update to use the boilerplate from RFC 8174 o Update to use the boilerplate from RFC 8174
draft-ietf-oauth-mtls-06
o Add an appendix section describing the relationship of this o Add an appendix section describing the relationship of this
document to OAuth Token Binding as requested during the the document to OAuth Token Binding as requested during the Singapore
Singapore meeting https://datatracker.ietf.org/doc/minutes- meeting https://datatracker.ietf.org/doc/minutes-100-oauth/
100-oauth/
o Add an explicit note that the implicit flow is not supported for o Add an explicit note that the implicit flow is not supported for
obtaining certificate bound access tokens as discussed at the obtaining certificate bound access tokens as discussed at the
Singapore meeting https://datatracker.ietf.org/doc/minutes- Singapore meeting https://datatracker.ietf.org/doc/minutes-
100-oauth/ 100-oauth/
o Add/incorporate text to the Security Considerations on Certificate o Add/incorporate text to the Security Considerations on Certificate
Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/ Spoofing as suggested https://mailarchive.ietf.org/arch/msg/oauth/
V26070X-6OtbVSeUz_7W2k94vCo V26070X-6OtbVSeUz_7W2k94vCo
o Changed the title to be more descriptive o Changed the title to be more descriptive
o Move the Security Considerations section to before the IANA o Move the Security Considerations section to before the IANA
Considerations Considerations
skipping to change at page 29, line 18 skipping to change at page 30, line 5
draft-ietf-oauth-mtls-00 draft-ietf-oauth-mtls-00
o Created the initial working group version from draft-campbell- o Created the initial working group version from draft-campbell-
oauth-mtls oauth-mtls
draft-campbell-oauth-mtls-01 draft-campbell-oauth-mtls-01
o Fix some typos. o Fix some typos.
o Add to the acknowledgements list. o Add to the acknowledgements list.
draft-campbell-oauth-mtls-00
o Add a Mutual TLS sender constrained protected resource access o Add a Mutual TLS sender constrained protected resource access
method and a x5t#S256 cnf method for JWT access tokens (concepts method and a x5t#S256 cnf method for JWT access tokens (concepts
taken in part from draft-sakimura-oauth-jpop-04). taken in part from draft-sakimura-oauth-jpop-04).
o Fixed "token_endpoint_auth_methods_supported" to o Fixed "token_endpoint_auth_methods_supported" to
"token_endpoint_auth_method" for client metadata. "token_endpoint_auth_method" for client metadata.
o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn" o Add "tls_client_auth_subject_dn" and "tls_client_auth_issuer_dn"
client metadata parameters and mention using "jwks_uri" or "jwks". client metadata parameters and mention using "jwks_uri" or "jwks".
o Say that the authentication method is determined by client policy o Say that the authentication method is determined by client policy
regardless of whether the client was dynamically registered or regardless of whether the client was dynamically registered or
statically configured. statically configured.
 End of changes. 32 change blocks. 
79 lines changed or deleted 106 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/