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 Cloudentity:
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.
Require mTLS from Client Applications
Cloudentity comes with multi-tenant authorization server as a service.
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).
-
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.
-
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).
-
The client verifies the digital signature of the Cloudentity certificate. If the verification is successful, the client sends its certificate to the server.
-
Cloudentity 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_singed_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 Cloudentity 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.