Mutual TLS
The Mutual TLS authenticator is used to authenticate clients based on their TLS client certificates.
Overview#
A mutually authenticated TLS connection is established between a client and server whenever the client makes an initial request to the server. The TLS connection is created for communication on a port, hence the combination of hostname and port number will result in a unique TLS connection with its established client certificate.
To indicate to a client that a client certificate is allowed or required, the server sends a list of trusted Certificate Authorities. This list is based on client truststores that are configured for the Mutual TLS configuration of the Service Role
Given that the service role supersedes the profile configurations, it is important to understand that in any given deployment that provides a Token Profile as well as an Authentication Profile on the same host and port combination, the underlying Mutual TLS connection is shared between these profiles, and the TLS handshake will happen whenever a user connects to that host/port. So, a typical flow that starts with a request to the Token Profile’s authorize endpoint will create a new Mutual TLS connection that is based on the TLS handshake of that request. In effect, it will perform user authentication on that request already!
One has to be aware of this when using the Mutual TLS authenticator.
The Mutual TLS authenticator will look at the HTTPS connection to figure out the client certificate. If it finds it, it will add a PEM-encoded version of this certificate to the user’s Subject Authentication Attributes, using a configured attribute name. This way it can be used later in the authentication flow, for example by an Authentication Action or by a process on the Token- or SAML IDP profile.
If no client certificate could be found on the connection, authentication will fail.
Hence, the Mutual TLS authenticator does not have any user interaction.
It is the client truststores that are responsible for deciding which client certificates are trusted, so the Mutual TLS authenticator does not perform any kind of validation on the client certificate itself. The client truststores are configured on the Mutual TLS settings of the service role.
Configuration#
- Certificate Source (experimental) the source for the client certificate. Possible values:
- mutual-tls-connection: The client certificate is obtained from the servlet request. This is the default and recommended option.
- session: this is an experimental setting and should not be used unless instructed to do so by Curity Support.
- X509 Certificate Attribute Name: the name of the Subject Authentication Attribute where the PEM-encoded client
certificate will be stored. The default value is
x509_client_certificate.