OAuth 2.0 Mutual TLS Client Authentication (mTLS)

Learn what OAuth 2.0 Mutual TLS Client Authentication (mTLS) is. Find out how using client certificates can improve the security of your APIs and services.

mTLS OAuth Client Authentication in a Nutshell

Transport Security Layer (TLS) is a cryptographic protocol that provides security for communication over a network.

Websites or applications that want to utilize TLS must have a TLS certificate installed on the server. Mutual-TLS (mTLS) means that not only the server (in our case, the authorization server) must have its certificate, but also any client that wants to be authenticated must possess its own certificate.

There are two mTLS-based methods that you can use to authenticate your OAuth client with the SecureAuth:

To get to know how to enable mTLS-based client authentication methods, see the configuring mTLS documentation.

Certificate Bound Access Tokens

Using mTLS gives also a possibility to use certificate-bound access tokens. In this case, mTLS ensures that protected resources access is only possible by a legitmate client that uses certificate-bound JSON Web Token and holds a private key that corresponds to the certificate.

Constraints provided by the use of certificate-bound access tokens are sometimes called key confirmation, proof-of-possession, or holder-of-key. It is different to the possession of the bearer token (like in the case of the private_key_jwt client authentication method), where any party that possesses an access token can access associated resources. Having certificate-bound access tokens ensures that only a client that has the private key corresponding to the client's certificate can access the resources. The binding of an access token to the client's certificate prevents the resources from being accessed with the use of stolen tokens.

Prerequisites to MTLS Client Authentication

The authorization server enables client applications to use MTLS based client authentication methods.
A X.509 certificate was registered for the client (using the JSON Web Key Sets) in the authorization server or a reference to a trusted source for its X.509 certificates (using jwks_uri) was added to the authorization server's client's configuration. To know more, see the configuring mTLS documentation.
Client registration metadata is configured for the client's certificate. To know more, see the client registration metadata section.

tls_auth

Client certificates can be issued by Certificate Authorities. CA is a public key infrastructure (PKI) that both the client and the server trust. Clients can use different certificates as long as the client name and issuing certificate authority stay the same. When the client's certificate is issued by a Certificate Authority, the tls_auth client authentication method is used.

TLS connection between the client and the authorization server is established or reestablished with mutual TLS X.509 certificate authentication (for example, the Client Certificate and Certificate Verify messages are sent during the TLS Handshake).
1. The client verifies the digital signature of the server's certificate using the Certificate Authority public key. If the verification is successful, the client sends its certificate to the server.
2. The server verifies the digital signature of the client's certificate using the Certificate Authority public key.
The client makes a request for an access token to the authorization server's token endpoint.
The authorization server generates an access token and provides it to the client after a successful request validation.
Result: Client is authenticated using the tls_auth method.

self_signed_tls_auth

For the self_singed_tls_auth client authentication to happen, the following procedure must take place.

If there is no Public Key Infrastructure to trust, client certificates can still be used. A client may register a single certificate with the authorization server. During authentication, the authorization server checks if the client's certificate is valid and if it is still the same certificate that is issued for the client. In this case, the self_signed_tls_auth client authentication method is used.

TLS connection between the client and the authorization server is established or reestablished with mutual TLS X.509 certificate authentication (i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake).
1. The client verifies the digital signature of the SecureAuth certificate. If the verification is successful, the client sends its certificate to the server.
2. SecureAuth verifies the digital signature of the client's certificate if it is valid and if it is the certificate that was issued for the client.
The client makes a request for an access token to the token endpoint.
The authorization server generates an access token and provides it to the client after a successful request validation.
Result: Client is authenticated using the self_signed_tls_auth method.

Client Registration Metadata

Client registration metadata is used to convey the subject of the certificate.

For the tls_auth client authentication method, the client must use exactly one of below parameters to convey the subject of the certificate that SecureAuth expects when authenticating the client.

Parameter	Description
tls_client_auth_subject_dn	String representation of the expected subject distinguished name of the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_dns	String that contains the value of an expected `dNSName` SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_uri	String that contains the value of an expected `uniformResourceIdentifier` SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_ip	String representation of an IP address in either dotted decimal notation (for IPv4) or colon-delimited hexadecimal (for IPv6) that is expected to be present as an IP Address SAN entry in the certificate that the OAuth client uses in mTLS authentication.
tls_client_auth_san_email	String containing the value of an expected rfc822Name SAN entry in the certificate that the OAuth client will use in mTLS authentication.

For the self_signed_tls_auth client authentication method, the client can use the following method metadata:

Parameter	Description
self_signed_tls_client_auth	Indicates that client authentication to the authorization server occurs using mTLS with the client utilizing a self-signed certificate.

When To Use

In general, you should use TLS while transporting any non-public, sensitive user data. It includes authentication data like, for example, passwords or client secrets. TLS prevents this data from being modified or hijacked on its way from the client to the server.

It is recommended to use either the tls_auth or the self_singed_tls_auth method as an additional layer of security built on top of other client authentication methods to achieve the best security for your applications and resources.

In this section: