Mutual Transport Layer Security (mTLS) provides a higher level of security and trust compared to one-way TLS, where only the server presents a certificate. It ensures that not only the server is who it claims to be, but the client is also authenticated. This is particularly valuable in scenarios where both parties need to establish trust and validate each other’s identities, such as in secure API communication, web services, or remote authentication.
For a summary of flow by which TLS is established between components using either one-way or mutual TLS, refer to [tls-overview].
With mutual TLS the following authentication and certification verification occurs:
-
Client Authentication: The client presents its digital certificate to the server during the TLS handshake. This certificate is issued by a trusted Certificate Authority (CA) and contains the client’s public key.
-
Server Authentication: The server also presents its digital certificate to the client, proving its identity and sharing its public key. The server’s certificate is also issued by a trusted CA.
-
Certificate Verification: Both the client and server verify each other’s certificates by checking the digital signatures against the CAs' public key (note that the client and server need not use the same CA).
{fleet}-managed {agent} has two main connections to ensure correct operations:
-
Connectivity to {fleet-server} (the control plane, to check in, download policies, and similar).
-
Connectivity to an Output (the data plane, such as {es} or {ls}).
In order to bootstrap, {agent} initially must establish a secure connection to the {fleet-server}, which can reside on-premises or in {ecloud}. This connectivity verification process ensures the agent’s authenticity. Once verified, the agent receives the policy configuration. This policy download equips the agent with the knowledge of the other components it needs to engage with. For instance, it gains insights into the output destinations it should write data to.
When mTLS is required, the secure setup between {agent}, {fleet}, and {fleet-server} is configured through the following steps:
-
mTLS is enabled.
-
The initial mTLS connection between {agent} and {fleet-server} is configured when {agent} is enrolled, using the parameters passed through the
elastic-agent installorelastic-agent enrollcommand. -
Once enrollment has completed, {agent} downloads the initial {agent} policy from {fleet-server}.
-
If the {agent} policy contains mTLS configuration settings, those settings will take precedence over those used during enrollment: This includes both the mTLS settings used for connectivity between {agent} and {fleet-server} (and the {fleet} application in {kib}, for {fleet}-managed {agent}), and the settings used between {agent} and it’s specified output.
-
If the {agent} policy does not contain any TLS, mTLS, or proxy configuration settings, these settings will remain as they were specified when {agent} enrolled. Note that the initial TLS, mTLS, or proxy configuration settings can not be removed through the {agent} policy; they can only be updated.
-
|
Important
|
When you run {agent} with the {elastic-defend} integration, the TLS certificates used to connect to {fleet-server} and {es} need to be generated using RSA. For a full list of available algorithms to use when configuring TLS or mTLS, see Configure SSL/TLS for standalone {agents}. These settings are available for both standalone and {fleet}-managed {agent}. |
Refer to the steps in Configure SSL/TLS for self-managed {fleet-server}s. To configure mutual TLS, include the following additional parameters when you install {agent} and {fleet-server}.
During {agent} installation on premise use the following options:
|
List of CA certificates that are trusted when {fleet-server} connects to {agent} |
|
{agent} certificate to present to {fleet-server} during authentication |
|
{agent} certificate key to present to {fleet-server} |
|
The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server} |
During {fleet-server} installation on-premise {fleet-server} authenticates with {es} and {agents}. You can use the following CLI options to facilitate these secure connections:
|
CA to use for the {es} connection |
|
{fleet-server} certificate to present to {es} |
|
{fleet-server} certificate key to present to {es} |
|
List of CA certificates that are trusted when {agent} connects to {fleet-server} and when {fleet-server} validates the {agent} identity. |
|
{fleet-server} certificate to present to {agents} during authentication |
|
{fleet-server}'s private certificate key used to decrypt the certificate |
In {kib}, navigate to {fleet}, open the Settings tab, and choose the Output that you’d like to configure. In the Advanced YAML configuration, add the following settings:
|
List of CA certificates that are trusted when {fleet-server} connects to {agent} |
|
This certificate will be passed down to all the agents that have this output configured in their policy. This certificate is used by the agent when establishing mTLS to the output. You may either apply the full certificate, in which case all the agents get the same certificate OR alternatively point to a local directory on the agent where the certificate resides, if the certificates are to be unique per agent. |
|
This certificate key will be passed down to all the agents that have this output configured in their policy. The certificate key is used to decrypt the SSL certificate. |
|
Important
|
Note the following when you specify these SSL settings:
|
In the Advanced YAML configuration these settings should be added in the following format:
ssl.certificate_authorities:
- /path/to/ca
ssl.certificate: /path/to/cert
ssl.key: /path/to/cert_keyOR
ssl.certificate_authorities:
- /path/to/ca
ssl.certificate: /path/to/cert
ssl.key: /path/to/cert_key
In this deployment model, all traffic ingress into {ecloud} has its TLS connection terminated at the {ecloud} boundary. Since this termination is not handled on a per-tenant basis, a client-specific certificate can NOT be used at this point.
We currently don’t support mTLS in this deployment model. An alternate deployment model is shown below where you can deploy your own secure proxy where TLS connections are terminated.
In this scenario, where you have access to the proxy, you can configure mTLS between the agent and your proxy.
During {agent} installation on premise use the following options:
|
List of CA certificates that are trusted when {agent} connects to {fleet-server} or to the proxy between {agent} and {fleet-server} |
|
{agent} certificate to present during authentication to {fleet-server} or to the proxy between {agent} and {fleet-server} |
|
{agent}'s private certificate key used to decrypt the certificate |
|
The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server} |
In some scenarios you may want to deploy {fleet-server} on your own premises. In this case, you’re able to provide your own certificates and certificate authority to enable mTLS between {fleet-server} and {agent}.
However, as with the {fleet-server} on {ecloud} use case, the data plane TLS connections terminate at the {ecloud} boundary. {ecloud} is not a multi-tenanted service and therefore can’t provide per-user certificates.
Similar to the {fleet-server} on {ecloud} use case, a secure proxy can be placed in such an environment to terminate the TLS connections and satisfy the mTLS requirements.
During {agent} installation on premise use the following options, similar to {agent} deployment on premises:
|
List of CA certificates that are trusted for when {agent} connects to {fleet-server} |
|
{agent} certificate to present to {fleet-server} during authentication |
|
{agent}'s private certificate key used to decrypt the certificate |
|
The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server} |
During {fleet-server} installation on-premise use the following options so that {fleet-server} can authenticate itself to the agent and then also to the secure proxy server:
|
CA to use for the {es} connection, via secure proxy. This CA is used to authenticate the TLS connection from a secure proxy |
|
List of CA certificates that are trusted when {agent} connects to {fleet-server} |
|
{fleet-server} certificate to present to {agents} during authentication |
|
{fleet-server}'s private certificate key used to decrypt the certificate |
This is the same as what’s described for on premise deployments. The main difference is that you need to use certificates that are accepted by the secure proxy, as the mTLS is set up between the agent and the secure proxy.