OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access TokensPing Identitybrian.d.campbell@gmail.comYubicove7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research Instituten-sakimura@nri.co.jphttps://nat.sakimura.org/YES.com AGtorsten@lodderstedt.net
Security
OAuth Working GroupJSON Web TokenJWTMTLSMutual TLSproof-of-possessionproof-of-possession access tokenkey confirmed access tokencertificate-bound access tokenclient certificateX.509 Client Certificate Authenticationkey confirmationconfirmation methodholder-of-keyOAuth
This document describes OAuth client authentication and certificate-bound
access and refresh tokens using mutual Transport Layer Security (TLS)
authentication with X.509 certificates. OAuth clients are provided a
mechanism for authentication to the authorization server using mutual TLS,
based on either self-signed certificates or public key infrastructure (PKI).
OAuth authorization servers are provided a mechanism for binding access
tokens to a client's mutual-TLS certificate, and OAuth protected resources
are provided a method for ensuring that such an access token presented to it
was issued to the client presenting the token.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by
the Internet Engineering Steering Group (IESG). Further
information on Internet Standards is available in Section 2 of
RFC 7841.
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
.
Copyright Notice
Copyright (c) 2020 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
() 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 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
Introduction
The OAuth 2.0 Authorization Framework enables third-party
client applications to obtain delegated access to protected resources.
In the prototypical abstract OAuth flow, illustrated in ,
the client obtains an access token from an entity known as an
authorization server and then uses that token when accessing protected resources,
such as HTTPS APIs.
Abstract OAuth 2.0 Protocol Flow
+--------+ +---------------+
| | | |
| |<--(A)-- Get an access token --->| Authorization |
| | | Server |
| | | |
| | +---------------+
| | ^
| | |
| |
| | (C) |
| Client | Validate the
| | access token |
| |
| | |
| | v
| | +---------------+
| | | (C) |
| | | |
| |<--(B)-- Use the access token -->| Protected |
| | | Resource |
| | | |
+--------+ +---------------+
The flow illustrated in includes the following steps:
The client makes an HTTPS POST request to
the authorization server and presents
a credential representing the authorization grant. For
certain types of clients (those that have been issued or otherwise established
a set of client credentials) the request must be authenticated.
In the response, the authorization server issues an access token to the client.
The client includes the access token when making a request to access a protected resource.
The protected resource validates the access token in order to authorize the request.
In some cases, such as when the token is self-contained and cryptographically secured,
the validation can be done locally by the protected resource. Other cases require
that the protected resource call out to the authorization server to determine the state
of the token and obtain metainformation about it.
Layering on the abstract flow above, this document standardizes enhanced
security options for OAuth 2.0 utilizing client-certificate-based mutual
TLS. provides options for
authenticating the request in Step
(A). Step (C) is supported with semantics
to express the binding of the token to the client certificate for both local
and remote processing in Sections and
, respectively. This ensures
that, as described in , protected resource access in Step
(B) is only possible by the legitimate client using a
certificate-bound token and holding the private key corresponding to the
certificate.
OAuth 2.0
defines a shared-secret method of client authentication but also
allows for defining and using additional client authentication mechanisms
when interacting directly with the authorization server.
This document describes an additional mechanism of client authentication utilizing
mutual-TLS certificate-based authentication that provides
better security characteristics than shared secrets.
While documents client authentication for requests to the token endpoint,
extensions to OAuth 2.0 (such as Introspection ,
Revocation , and the Backchannel Authentication Endpoint
in ) define endpoints that also utilize client authentication,
and the mutual-TLS methods defined herein are applicable to those endpoints as well.
Mutual-TLS certificate-bound access tokens ensure that
only the party in possession of the
private key corresponding to the certificate can utilize the token to
access the associated resources. Such a constraint is
sometimes referred to as key confirmation, proof-of-possession, or holder-of-key
and is unlike the case of the
bearer token described in , where any party in
possession of the access token can use it to access the associated resources.
Binding an access token to the client's certificate
prevents the use of stolen access tokens or replay of access tokens
by unauthorized parties.
Mutual-TLS certificate-bound access tokens and mutual-TLS client authentication
are distinct mechanisms that are complementary but 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 , which defines mechanisms for dynamically registering
OAuth 2.0 client metadata with authorization servers.
Also the metadata defined by , 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.
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 BCP 14
when, and only when, they appear in all capitals, as shown here.
Terminology
Throughout this document the term "mutual TLS" refers to the process whereby, in addition to the normal TLS
server authentication with a certificate, a client presents its X.509 certificate
and proves possession of the corresponding private key to a server when negotiating a TLS session.
In contemporary versions of TLS , this requires that the client send
the Certificate and CertificateVerify messages during the handshake and
for the server to verify the CertificateVerify and Finished messages.
Mutual TLS for OAuth Client Authentication
This section defines, as an extension of
OAuth 2.0, two distinct methods of using
mutual-TLS X.509 client certificates as client credentials.
The requirement of mutual TLS for client authentication is determined by the authorization server,
based on policy or configuration for the given client (regardless of whether the client was dynamically
registered, statically configured, or otherwise established).
In order to utilize TLS for OAuth client authentication, the TLS
connection between the client and the authorization server MUST have been established or re-established
with mutual-TLS X.509 certificate authentication
(i.e., the client Certificate and CertificateVerify messages are sent during
the TLS handshake).
For all requests to the authorization server utilizing mutual-TLS client
authentication, the client MUST include the
client_id parameter described in OAuth 2.0. The presence of the
client_id parameter enables the authorization server to easily
identify the client independently from the content of the certificate. The
authorization server can locate the client configuration using the client
identifier and check the certificate presented in the TLS handshake against
the expected credentials for that client. The authorization server
MUST enforce the binding between client and certificate, as
described in either Section or below. If no certificate is
presented, or that which is presented doesn't match that which is expected
for the given client_id, the authorization server returns a normal
OAuth 2.0 error response per with the invalid_client error code to
indicate failed client authentication.
PKI Mutual-TLS Method
The PKI (public key infrastructure) method of mutual-TLS OAuth client authentication
adheres to the way in which X.509 certificates are traditionally used
for authentication. It relies on a validated certificate chain
and a single subject distinguished name (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.
The TLS handshake is utilized to validate the client's possession
of the private key corresponding to the public key in the certificate and to
validate the corresponding certificate chain. The client is successfully authenticated
if the subject information in the certificate matches the single expected subject configured or
registered for that particular client
(note that a predictable treatment of DN values, such as the distinguishedNameMatch
rule from , is needed in comparing the
certificate's subject DN to the client's registered DN).
Revocation checking is possible with the PKI method but if and how to check a certificate's
revocation status is a deployment decision at the discretion of the authorization server.
Clients can rotate their X.509 certificates
without the need to modify the respective authentication data at the authorization
server by obtaining a new certificate with the same subject from a trusted certificate authority (CA).
PKI Method Metadata Value
For the PKI method of mutual-TLS client authentication, this specification
defines and registers the following authentication method metadata
value into the "OAuth Token Endpoint Authentication Methods" registry
.
tls_client_auth
Indicates that client authentication to the authorization server will occur with
mutual TLS utilizing the PKI method of associating a certificate to a client.
Client Registration Metadata
In order to convey the expected subject of the certificate,
the following metadata
parameters are introduced for the
OAuth 2.0 Dynamic Client Registration Protocol in support of
the PKI method of mutual-TLS client authentication.
A client using the tls_client_auth authentication method MUST use
exactly one of the below metadata parameters to indicate the certificate subject value that
the authorization server is to expect when authenticating the respective client.
tls_client_auth_subject_dn
A string representation -- as defined in -- of the expected subject distinguished
name of the certificate that the OAuth client will use in mutual-TLS authentication.
tls_client_auth_san_dns
A string containing the value of an expected dNSName SAN entry
in the certificate that the OAuth client will use in mutual-TLS
authentication.
tls_client_auth_san_uri
A string containing the value of an expected
uniformResourceIdentifier SAN entry in the certificate that
the OAuth client will use in mutual-TLS authentication.
tls_client_auth_san_ip
A string representation of an IP address in either dotted
decimal notation (for IPv4) or colon-delimited hexadecimal (for
IPv6, as defined in )
that is expected to be present as an iPAddress SAN entry in the
certificate that the OAuth client will use in mutual-TLS
authentication. Per , the IP address comparison of the value in
this parameter and the SAN entry in the certificate is to be
done in binary format.
tls_client_auth_san_email
A string containing the value of an expected rfc822Name SAN
entry in the certificate that the OAuth client will use in
mutual-TLS authentication.
Self-Signed Certificate Mutual-TLS Method
This method of mutual-TLS OAuth client authentication
is intended to support client authentication using self-signed certificates.
As a prerequisite, the client registers its X.509 certificates
(using jwks defined in ) or a reference to a trusted source
for its X.509 certificates (using jwks_uri from )
with the authorization server. During authentication,
TLS is utilized to validate the client's possession of the private key
corresponding to the public key presented within the certificate in the respective TLS handshake. In
contrast to the PKI method, the client's certificate chain is not validated by the server in this case.
The client is successfully authenticated if the
certificate that it presented during the handshake matches one of the certificates
configured or registered for that particular client.
The Self-Signed Certificate method allows the use of mutual TLS to authenticate clients without
the need to maintain a PKI. When used in conjunction with a jwks_uri for the
client, it also allows the client to rotate its X.509 certificates without the
need to change its respective authentication data directly with the authorization server.
Self-Signed Method Metadata Value
For the Self-Signed Certificate method of mutual-TLS client authentication, this specification
defines and registers the following authentication method metadata
value into the "OAuth Token Endpoint Authentication Methods" registry
.
self_signed_tls_client_auth
Indicates that client authentication to the authorization server will occur using
mutual TLS with the client utilizing a self-signed certificate.
Client Registration Metadata
For the Self-Signed Certificate method of binding a certificate with
a client using mutual-TLS client authentication, the existing
jwks_uri or jwks metadata parameters from are used to convey the client's
certificates via JSON Web Key (JWK) in a JWK Set . The jwks metadata
parameter is a JWK Set 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 certificate is represented with
the x5c parameter of an individual 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 Elliptic Curve (EC)) are required
parameters per so will be
present even though they are not utilized in this context. Also note
that requires that the key in the first certificate of
the x5c parameter match the public key represented by those
other members of the JWK.
Mutual-TLS Client Certificate-Bound Access Tokens
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 token to the client certificate.
Such a binding is accomplished by associating 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 ,
or through token introspection as described in .
Binding the access token to the client certificate in that fashion has the benefit of
decoupling that binding from the client's authentication with the
authorization server, which enables mutual TLS during protected resource access to
serve purely as a proof-of-possession mechanism.
Other methods of associating a certificate with an access token are possible,
per agreement by the authorization server and the protected resource, but are
beyond the scope of this specification.
In order for a resource server to use certificate-bound access tokens, it
must have advance knowledge that mutual TLS is to be used for some or all
resource accesses.
In particular, the access token
itself cannot be used as input to the decision of whether or not to
request mutual TLS because (from the TLS perspective) it is
"Application Data", only exchanged after the TLS handshake has been
completed, and the initial CertificateRequest occurs during the
handshake, before the Application Data is available.
Although subsequent opportunities for a TLS client to
present a certificate may be available, e.g., via TLS 1.2 renegotiation
or TLS 1.3 post-handshake authentication , this document
makes no provision for their usage. It is expected to be common that a
mutual-TLS-using resource server will require mutual TLS for all resources hosted
thereupon or will serve mutual-TLS-protected and regular resources on separate
hostname and port combinations, though other workflows are possible.
How
resource server policy is synchronized with the authorization server (AS) is out of scope for this
document.
Within the scope of a mutual-TLS-protected resource-access flow,
the client makes protected resource requests, as described in ,
however, those requests MUST be made over a mutually authenticated TLS connection
using the same certificate that was used for mutual TLS at the token endpoint.
The protected resource MUST obtain, from its TLS implementation layer, the client certificate
used for mutual TLS
and MUST verify that the certificate matches the
certificate associated with the access token. If they do not match,
the resource access attempt MUST be rejected with an error, per ,
using an HTTP 401 status code and the invalid_token error code.
Metadata to convey server and client capabilities for mutual-TLS client certificate-bound access tokens
is defined in Sections and , respectively.
JWT Certificate Thumbprint Confirmation Method
When access tokens are represented as JSON Web Tokens (JWT) ,
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 member x5t#S256 for the X.509
Certificate SHA-256 Thumbprint. The value of the x5t#S256 member
is a base64url-encoded SHA-256
hash (a.k.a., thumbprint, fingerprint,
or digest) of the DER encoding of
the X.509 certificate . The
base64url-encoded value MUST omit all trailing pad '='
characters and MUST NOT include any line breaks,
whitespace, or other additional characters.
The following is an example of a JWT payload containing an x5t#S256 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.
Example JWT Claims Set with an X.509 Certificate Thumbprint Confirmation Method
{
"iss": "https://server.example.com",
"sub": "ty.webb@example.com",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}
Confirmation Method for Token Introspection
OAuth 2.0 Token Introspection defines a
method for a protected resource to query
an authorization server about the active state of an
access token as well as to determine metainformation about the token.
For a mutual-TLS client certificate-bound access token, the hash of the
certificate to which the token is bound
is conveyed to the protected resource as metainformation
in a token introspection response. The hash is conveyed using the same
cnf with x5t#S256 member structure as the
certificate SHA-256 thumbprint confirmation method, described in
, as a top-level member of the introspection response JSON.
The protected resource compares
that certificate hash to a hash of the client certificate used for
mutual-TLS authentication
and rejects the request if they do not match.
The following is an example of an introspection response for an active token with
an x5t#S256 certificate thumbprint
confirmation 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.
Example Introspection Response for a Certificate-Bound Access Token
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"iss": "https://server.example.com",
"sub": "ty.webb@example.com",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}
Authorization Server MetadataThis document introduces the following new authorization server
metadata parameter to signal the server's capability to issue certificate-bound access tokens:
tls_client_certificate_bound_access_tokens
OPTIONAL. Boolean value indicating server support for
mutual-TLS client certificate-bound access tokens. If omitted, the
default value is false.
Client Registration MetadataThe following new client
metadata parameter is introduced to convey the client's intention to use certificate-bound access tokens:
tls_client_certificate_bound_access_tokens
OPTIONAL. Boolean value used to indicate the client's intention
to use mutual-TLS client certificate-bound access tokens.
If omitted, the default value is false.
Note that if a client that has indicated the intention to use mutual-TLS client certificate-bound tokens
makes a request to the token endpoint over a non-mutual-TLS connection,
it is at the authorization server's discretion as to whether to return an error or issue an unbound token.
Public Clients and Certificate-Bound Tokens
Mutual-TLS OAuth client authentication and certificate-bound access tokens
can be used independently of each other.
Use of certificate-bound access tokens without mutual-TLS OAuth client authentication, for example,
is possible in support of binding access tokens to a TLS client certificate for public clients (those without
authentication credentials associated with the client_id).
The authorization server would configure the TLS stack in the same manner as for the Self-Signed Certificate method
such that it does not verify that the certificate presented by the client during the handshake is
signed by a trusted CA. Individual instances of a client would create a self-signed
certificate for mutual TLS with both the authorization server and resource server. The authorization
server would not use the mutual-TLS certificate to authenticate the client at the OAuth layer
but would bind the issued access token
to the certificate for which the client has proven possession of the corresponding private key.
The access token is then bound to the certificate and can only be used by the client
possessing the certificate and corresponding private key and utilizing them to negotiate mutual TLS on
connections to the resource server.
When the authorization server issues a refresh token to such a client, it SHOULD also bind the refresh token
to the respective certificate and check the binding when the refresh token is presented to get new
access tokens.
The implementation details of the binding of the refresh token are at the discretion of the authorization
server.
Metadata for Mutual-TLS Endpoint Aliases
The process of negotiating client certificate-based mutual TLS involves a TLS server requesting a certificate
from the TLS client (the client does not provide one unsolicited). Although a server can be configured
such that client certificates are optional, meaning that the connection is allowed to continue when the client
does not provide a certificate, the act of a server requesting a certificate can result in undesirable
behavior from some clients. This is particularly true of web browsers as TLS clients, which will typically
present the end user with an intrusive certificate selection interface when the server requests a certificate.
Authorization servers supporting both clients using mutual TLS and conventional clients MAY chose to
isolate the server side mutual-TLS behavior to only clients intending to do mutual TLS, thus
avoiding any undesirable effects it might have on conventional clients. The following authorization server
metadata parameter is introduced to facilitate such separation:
mtls_endpoint_aliases
OPTIONAL.
A JSON object containing alternative authorization server endpoints that,
when present, an OAuth client intending to do mutual TLS
uses in preference to the conventional endpoints.
The parameter value itself consists of one or more endpoint parameters,
such as token_endpoint,
revocation_endpoint,
introspection_endpoint, etc., conventionally defined for the
top level of authorization server metadata.
An OAuth client intending to do mutual TLS
(for OAuth client authentication and/or to acquire or use certificate-bound tokens)
when making a request directly to the authorization server MUST
use the alias URL of the endpoint within the mtls_endpoint_aliases, when present,
in preference to the endpoint URL of the same name at the top level of metadata.
When an endpoint is not present in
mtls_endpoint_aliases, then the client uses the conventional endpoint URL
defined at the top level of the authorization server metadata. Metadata parameters within
mtls_endpoint_aliases that do not define
endpoints to which an OAuth client makes a direct request have no meaning and SHOULD be ignored.
Below is an example of an authorization server metadata document with the
mtls_endpoint_aliases parameter, which indicates aliases for the
token, revocation, and introspection endpoints that an OAuth client intending to do mutual TLS
would use in preference to the conventional token, revocation, and
introspection endpoints.
Note that the endpoints in mtls_endpoint_aliases use a different
host than their conventional counterparts, which allows the authorization server
(via TLS server_name extension or actual distinct hosts) to differentiate its TLS behavior as appropriate.
Example Authorization Server Metadata with Mutual-TLS Endpoint Aliases
{
"issuer": "https://server.example.com",
"authorization_endpoint": "https://server.example.com/authz",
"token_endpoint": "https://server.example.com/token",
"introspection_endpoint": "https://server.example.com/introspect",
"revocation_endpoint": "https://server.example.com/revo",
"jwks_uri": "https://server.example.com/jwks",
"response_types_supported": ["code"],
"response_modes_supported": ["fragment","query","form_post"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"token_endpoint_auth_methods_supported":
["tls_client_auth","client_secret_basic","none"],
"tls_client_certificate_bound_access_tokens": true,
"mtls_endpoint_aliases": {
"token_endpoint": "https://mtls.example.com/token",
"revocation_endpoint": "https://mtls.example.com/revo",
"introspection_endpoint": "https://mtls.example.com/introspect"
}
}
Implementation ConsiderationsAuthorization ServerThe authorization server needs to set up its TLS configuration appropriately
for the OAuth client authentication methods it supports.An authorization server that supports mutual-TLS client authentication
and other client authentication methods or public clients in parallel would make mutual TLS
optional (i.e., allowing a handshake to continue after the server requests a client certificate
but the client does not send one).In order to support the Self-Signed Certificate method alone, the authorization server
would configure the TLS stack in such a way that it does not verify whether the
certificate presented by the client during the handshake is signed by a trusted CA
certificate.As described in , the authorization server
binds the issued access token to the TLS client certificate, which means that it
will only issue certificate-bound tokens for a
certificate that the client has proven possession of the corresponding private key.The authorization server may also consider hosting the token endpoint
and other endpoints requiring client authentication on
a separate host name or port in order to prevent unintended impact on the TLS behavior of
its other endpoints, e.g., the authorization endpoint. As described in ,
it may further isolate any potential impact of the server requesting client certificates by
offering a distinct set of endpoints on a separate host or port, which are aliases for
the originals that a client intending to do mutual TLS will use in preference to the conventional endpoints.Resource Server
OAuth divides the roles and responsibilities such that the resource server relies
on the authorization server to perform client authentication and obtain resource-owner (end-user)
authorization. The resource server makes authorization decisions based on the access token
presented by the client but does not directly authenticate the client per se.
The manner in which an access token is bound to the client certificate and how a protected resource verifies the proof-of-possession
decouples that from the specific method that the client used to authenticate with the
authorization server. Mutual TLS during protected resource access can, therefore,
serve purely as a proof-of-possession mechanism.
As such, it is not necessary for the resource server to validate
the trust chain of the client's certificate in any of the methods
defined in this document.
The resource server would, therefore, configure the TLS stack
in a way that it does not verify whether the certificate presented by the client
during the handshake is signed by a trusted CA certificate.
Certificate Expiration and Bound Access Tokens
As described in ,
an access token is bound to a specific client certificate, which means that
the same certificate must be used for mutual TLS on protected resource access.
It also implies that access tokens are invalidated when a client updates the certificate,
which can be handled similarly to expired access tokens where the client
requests a new access token (typically with a refresh token) and retries the protected resource
request.
Implicit Grant Unsupported
This document describes binding an access token to the
client certificate presented on the TLS connection from the client to the
authorization server's token endpoint,
however, such binding of access tokens issued directly from the authorization
endpoint via the implicit grant flow is explicitly out of scope.
End users interact directly with the authorization endpoint using a web browser,
and the use of client certificates in user's browsers bring operational and
usability issues that make it undesirable to support certificate-bound access
tokens issued in the implicit grant flow. Implementations wanting to employ
certificate-bound access tokens should utilize grant types
that involve the client making an access token request directly to the token endpoint
(e.g., the authorization code and refresh token grant types).
TLS Termination
An authorization server or resource server MAY choose to terminate TLS connections at a load balancer,
reverse proxy, or other network intermediary. How the client certificate metadata is securely
communicated between the intermediary and the application server, in this case, is out of scope of this specification.
Security ConsiderationsCertificate-Bound Refresh TokensThe OAuth 2.0 Authorization Framework requires that an authorization server (AS)
bind refresh tokens to the client to which they were issued and that confidential clients
(those having established authentication credentials with the AS) authenticate to
the AS when presenting a refresh token. As a result, refresh tokens are indirectly certificate-bound by way of the
client ID and the associated requirement for (certificate-based) authentication to the AS when
issued to clients utilizing the tls_client_auth or
self_signed_tls_client_auth methods of client authentication.
describes certificate-bound refresh tokens issued to public clients (those without
authentication credentials associated with the client_id).
Certificate Thumbprint Binding
The binding between the certificate and access token specified in uses
a cryptographic hash of the certificate. It relies on the hash function having sufficient
second-preimage resistance so as to make it computationally infeasible to
find or create another certificate that produces to the same hash output value.
The SHA-256 hash function was used because it meets the aforementioned requirement while being widely available.
If, in the future, certificate thumbprints need to be computed using
hash function(s) other than SHA-256, it is suggested that, for additional
related JWT confirmation methods, members be defined for that purpose
and registered in the IANA "JWT Confirmation Methods" registry
for JWT cnf member values.
Community knowledge about the strength of various algorithms and
feasible attacks can change suddenly, and experience shows that a
document about security is a point-in-time
statement. Readers are advised to seek out any errata or updates
that apply to this document.
TLS Versions and Best Practices
This document is applicable with any TLS version supporting certificate-based client authentication.
Both TLS 1.3 and TLS 1.2 are cited herein, because,
at the time of writing, 1.3 is the newest version, while 1.2 is the most widely deployed.
General implementation and security considerations for TLS, including version recommendations,
can be found in .
TLS certificate validation
(for both client and server certificates) requires a local database of
trusted certificate authorities (CAs). Decisions about what CAs to trust
and how to make such a determination of trust are out of scope for this
document.
X.509 Certificate Spoofing
If the PKI method of client authentication is used, an attacker could try to impersonate a client using
a certificate with the same subject (DN or SAN) but issued by a
different CA that the authorization server trusts.
To cope with that threat, the authorization server SHOULD only accept, as trust anchors,
a limited number of CAs whose certificate issuance policy meets its security requirements.
There is an assumption then that the client and server agree out of band on the set
of trust anchors that the server uses to create and validate the
certificate chain. Without this assumption the use of a subject
to identify the client certificate would open the server up to
certificate spoofing attacks.
X.509 Certificate Parsing and Validation Complexity
Parsing and validation of X.509 certificates and certificate chains
is complex, and implementation
mistakes have previously exposed security vulnerabilities.
Complexities of validation include (but are not limited to)
:
checking of basic constraints, basic and extended key usage constraints, validity periods, and critical extensions;
handling of embedded NUL bytes in ASN.1 counted-length strings and non-canonical or non-normalized string representations in subject names;
handling of wildcard patterns in subject names;
recursive verification of certificate chains and checking certificate revocation.
For these reasons, implementors SHOULD use an established and well-tested X.509 library
(such as one used by an established TLS library) for validation of X.509 certificate chains
and SHOULD NOT attempt to write their own X.509 certificate validation procedures.
Privacy Considerations
In TLS versions prior to 1.3, the client's certificate is sent unencrypted in the initial handshake and
can potentially be used by third parties to monitor, track, and correlate client activity.
This is likely of little concern for clients that act on behalf of a
significant number of end users because
individual user activity will not be discernible amidst the client activity as a whole.
However, clients that act on behalf of a single end user, such as a native application on a mobile device,
should use TLS version 1.3 whenever possible or consider the potential privacy implications of using mutual TLS on
earlier versions.
IANA ConsiderationsJWT Confirmation Methods Registration
Per this specification, the following value has been registered
in the IANA "JWT Confirmation Methods" registry
for JWT cnf member values
established by .
Confirmation Method Value:
x5t#S256
Confirmation Method Description:
X.509 Certificate SHA-256 Thumbprint
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Authorization Server Metadata Registration
Per this specification, the following values have been registered
in the IANA "OAuth Authorization Server Metadata" registry
established by .
Metadata Name:
tls_client_certificate_bound_access_tokens
Metadata Description:
Indicates authorization server
support for mutual-TLS client certificate-bound access tokens.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Metadata Name:
mtls_endpoint_aliases
Metadata Description:
JSON object containing alternative
authorization server endpoints, which a client
intending to do mutual TLS will use in preference to the conventional endpoints.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Token Endpoint Authentication Method Registration
Per this specification, the following values have been registered
in the IANA "OAuth Token Endpoint Authentication Methods" registry
established by .
Token Endpoint Authentication Method Name:
tls_client_auth
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Token Endpoint Authentication Method Name:
self_signed_tls_client_auth
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Token Introspection Response Registration
"Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)" defined the
cnf (confirmation) claim that enables
confirmation key information to be carried in a JWT.
However, the same proof-of-possession semantics are also useful for introspected access tokens
whereby the protected resource obtains the confirmation key data as metainformation
of a token introspection response and uses that information in verifying proof-of-possession.
Therefore, this specification defines and registers proof-of-possession semantics for
OAuth 2.0 Token Introspection using the cnf
structure.
When included as a top-level member of an OAuth token introspection response, cnf
has the same semantics and format as the claim of the same name defined in .
While this specification only explicitly uses the x5t#S256
confirmation method member (see ), it needs to define and register
the higher-level cnf
structure as an introspection response member in order to define and use the more specific
certificate thumbprint confirmation method.
As such, the following values have been registered
in the IANA "OAuth Token Introspection Response" registry
established by .
Claim Name:
cnf
Claim Description:
Confirmation
Change Controller:
IESG
Specification Document(s):
and RFC 8705
Dynamic Client Registration Metadata Registration
Per this specification, the following client metadata definitions
have been registered in the IANA "OAuth Dynamic Client Registration Metadata" registry
established by :
Client Metadata Name:
tls_client_certificate_bound_access_tokens
Client Metadata Description:
Indicates the client's
intention to use mutual-TLS client certificate-bound access
tokens.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Client Metadata Name:
tls_client_auth_subject_dn
Client Metadata Description:
String value specifying
the expected subject DN of the client certificate.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Client Metadata Name:
tls_client_auth_san_dns
Client Metadata Description:
String value specifying
the expected dNSName SAN entry in the client certificate.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Client Metadata Name:
tls_client_auth_san_uri
Client Metadata Description:
String value specifying
the expected uniformResourceIdentifier SAN entry in the client
certificate.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Client Metadata Name:
tls_client_auth_san_ip
Client Metadata Description:
String value specifying
the expected iPAddress SAN entry in the client certificate.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
Client Metadata Name:
tls_client_auth_san_email
Client Metadata Description:
String value specifying
the expected rfc822Name SAN entry in the client certificate.
Change Controller:
IESG
Specification Document(s):
of RFC 8705
ReferencesNormative ReferencesRecommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished NamesThe X.500 Directory uses distinguished names (DNs) as primary keys to entries in the directory. This document defines the string representation used in the Lightweight Directory Access Protocol (LDAP) to transfer distinguished names. The string representation is designed to give a clean representation of commonly used distinguished names, while being able to represent any distinguished name. [STANDARDS-TRACK]The Base16, Base32, and Base64 Data EncodingsThis document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]The Transport Layer Security (TLS) Protocol Version 1.2This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK]Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) ProfileThis memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK]The OAuth 2.0 Authorization FrameworkThe OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK]The OAuth 2.0 Authorization Framework: Bearer Token UsageThis specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK]JSON Web Key (JWK)A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification.JSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.OAuth 2.0 Dynamic Client Registration ProtocolThis specification defines mechanisms for dynamically registering OAuth 2.0 clients with authorization servers. Registration requests send a set of desired client metadata values to the authorization server. The resulting registration responses return a client identifier to use at the authorization server and the client metadata values registered for the client. The client can then use this registration information to communicate with the authorization server using the OAuth 2.0 protocol. This specification also defines a set of common client metadata fields and values for clients to use during registration.OAuth 2.0 Token IntrospectionThis specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.OAuth 2.0 Authorization Server MetadataThis specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities.The Transport Layer Security (TLS) Protocol Version 1.3This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations.Secure Hash Standard (SHS)National Institute of Standards and Technology (NIST)Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)ITU-TInformative ReferencesCommon x509 certificate validation/creation pitfallsThe Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser SoftwareJSON Web Token ClaimsIANAOAuth ParametersIANAOpenID Connect Client Initiated Backchannel Authentication Flow - Core 1.0Telefonica I+Dgonzalo.fernandezrodriguez@telefonica.comDeutsche Telekom AGF.Walter@telekom.deDeutsche Telekom AGaxel.nennker@telekom.deMoneyhubdave.tonge@moneyhub.comPing Identitybcampbell@pingidentity.comLightweight Directory Access Protocol (LDAP): Syntaxes and Matching RulesEach attribute stored in a Lightweight Directory Access Protocol (LDAP) directory, whose values may be transferred in the LDAP protocol, has a defined syntax that constrains the structure and format of its values. The comparison semantics for values of a syntax are not part of the syntax definition but are instead provided through separately defined matching rules. Matching rules specify an argument, an assertion value, which also has a defined syntax. This document defines a base set of syntaxes and matching rules for use in defining attributes for LDAP directories. [STANDARDS-TRACK]A Recommendation for IPv6 Address Text RepresentationAs IPv6 deployment increases, there will be a dramatic increase in the need to use IPv6 addresses in text. While the IPv6 address architecture in Section 2.2 of RFC 4291 describes a flexible model for text representation of an IPv6 address, this flexibility has been causing problems for operators, system engineers, and users. This document defines a canonical textual representation format. It does not define a format for internal storage, such as within an application or database. It is expected that the canonical format will be followed by humans and systems when representing IPv6 addresses as text, but all implementations must accept and be able to handle any legitimate RFC 4291 format. [STANDARDS-TRACK]Transport Layer Security (TLS) Extensions: Extension DefinitionsThis document provides specifications for existing TLS extensions. It is a companion document for RFC 5246, "The Transport Layer Security (TLS) Protocol Version 1.2". The extensions specified are server_name, max_fragment_length, client_certificate_url, trusted_ca_keys, truncated_hmac, and status_request. [STANDARDS-TRACK]OAuth 2.0 Token RevocationThis document proposes an additional endpoint for OAuth authorization servers, which allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. This allows the authorization server to clean up security credentials. A revocation request will invalidate the actual token and, if applicable, other tokens based on the same authorization grant.JSON Web Algorithms (JWA)This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers.OAuth 2.0 Token BindingThis specification enables OAuth 2.0 implementations to apply Token Binding to Access Tokens, Authorization Codes, Refresh Tokens, JWT Authorization Grants, and JWT Client Authentication. This cryptographically binds these tokens to a client's Token Binding key pair, possession of which is proven on the TLS connections over which the tokens are intended to be used. This use of Token Binding protects these tokens from man-in-the-middle and token export and replay attacks.Work in ProgressExample "cnf" Claim, Certificate, and JWK
For reference, an x5t#S256 value and the X.509 certificate
from which it was calculated are provided in the following examples,
Figures and , respectively. A JWK representation of the
certificate's public key along with the x5c member is also
provided in .
x5t#S256 Confirmation Claim
"cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"}
PEM Encoded Self-Signed Certificate
-----BEGIN CERTIFICATE-----
MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx
ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ
/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID
SQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2eXZOV
bUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY=
-----END CERTIFICATE-----JSON Web Key
{
"kty":"EC",
"x":"1yfLHCpXqFjxCeHHHMVDTcLscpb07KUxudBmOMn8C7Q",
"y":"8_coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8",
"crv":"P-256",
"x5c":[
"MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTA
xODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGBy
qGSM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZ
jjJ/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0E
AwIDSQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2
eXZOVbUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY="
]
}Relationship to Token Binding
OAuth 2.0 Token Binding
enables the application of Token Binding to the various artifacts and tokens employed throughout OAuth.
That includes binding of an access token to a Token Binding key, which bears some similarities in motivation
and design to the mutual-TLS client certificate-bound access tokens defined in this document.
Both documents define what is often called a proof-of-possession security mechanism
for access tokens, whereby a client must demonstrate possession of cryptographic keying
material when accessing a protected resource. The details differ somewhat between the two documents but both
have the authorization server bind the access token that it issues to an asymmetric key pair
held by the client. The client then proves possession of the private key from that pair
with respect to the TLS connection over which the protected resource is accessed.
Token Binding uses bare keys that are generated on the client,
which avoids many of the difficulties of creating, distributing, and managing certificates
used in this specification. However, at the time of
writing, Token Binding is fairly new, and there is relatively little support for it in available
application development platforms and tooling. Until better support for the underlying
core Token Binding specifications exists, practical implementations of OAuth 2.0 Token Binding
are infeasible.
Mutual TLS, on the other hand, has been around for some time and enjoys
widespread support in web servers and development platforms. As a consequence, OAuth 2.0 Mutual-TLS
Client Authentication and Certificate-Bound Access Tokens can be
built and deployed now using existing platforms and tools.
In the future, the two specifications are likely to be
deployed in parallel for solving similar problems in different environments.
Authorization servers may even support both specifications simultaneously using different
proof-of-possession mechanisms for tokens issued to different clients.
Acknowledgements
Scott "not Tomlinson" Tomilson and were involved in
design and development work on a mutual-TLS OAuth client authentication
implementation that predates this document. Experience and learning from that work
informed some of the content of this document.
This specification was developed within the OAuth Working Group
under the chairmanship of
and with ,
, and
serving as Security Area Directors. Additionally, the following
individuals contributed ideas, feedback, and wording
that helped shape this specification:
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
and
.
Authors' AddressesPing Identitybrian.d.campbell@gmail.comYubicove7jtb@ve7jtb.comhttp://www.thread-safe.com/Nomura Research Instituten-sakimura@nri.co.jphttps://nat.sakimura.org/YES.com AGtorsten@lodderstedt.net