-
Notifications
You must be signed in to change notification settings - Fork 163
Add TLS/mTLS UI configuration options for Fleet Server #2193
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 5 commits
79319c2
4941675
02b5192
acec9ee
e59c39a
8cc1ae5
28096e5
0f1d91f
3bb613a
55cca5a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -42,7 +42,6 @@ When you run {{agent}} with the {{elastic-defend}} integration, the [TLS certifi | |
:::: | ||
|
||
|
||
|
||
## Generate a custom certificate and private key for {{fleet-server}} [generate-fleet-server-certs] | ||
|
||
This section describes how to use the `certutil` tool provided by {{es}}, but you can use whatever process you typically use to generate PEM-formatted certificates. | ||
|
@@ -84,8 +83,11 @@ This section describes how to use the `certutil` tool provided by {{es}}, but yo | |
Store the files in a secure location. You’ll need these files later to encrypt traffic between {{agent}}s and {{fleet-server}}. | ||
|
||
|
||
## Configure SSL/TLS using CLI [fleet-server-ssl-cli-settings] | ||
|
||
Use the CLI to configure SSL or TLS when installing or enrolling {{fleet-server}}. This method gives you granular control over certificate paths, verification modes, and authentication behavior. | ||
|
||
## Encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}} [_encrypt_traffic_between_agents_fleet_server_and_es] | ||
### Encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}} [_encrypt_traffic_between_agents_fleet_server_and_es] | ||
|
||
{{fleet-server}} needs a CA certificate or the CA fingerprint to connect securely to {{es}}. It also needs to expose a {{fleet-server}} certificate so other {{agent}}s can connect to it securely. | ||
|
||
|
@@ -271,3 +273,35 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: | |
Don’t have an enrollment token? On the **Agents** tab in {{fleet}}, click **Add agent**. Under **Enroll and start the Elastic Agent**, follow the in-product installation steps, making sure that you add the `--certificate-authorities` option before you run the command. | ||
|
||
|
||
## Configure SSL/TLS using {{kib}} [fleet-server-ssl-ui-settings] | ||
```{applies_to} | ||
stack: ga 9.1 | ||
``` | ||
|
||
You can configure SSL/TLS settings for {{fleet-server}} hosts directly in the {{fleet}} UI, without relying on CLI flags or policy overrides. | ||
|
||
To access these settings: | ||
|
||
1. In **Kibana**, go to **Management** > **Fleet** > **Settings**. | ||
alexandra5000 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
2. Under **{{fleet-server}} hosts**, click **Add host** or edit an existing host. | ||
alexandra5000 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
3. Expand the **SSL options** section. | ||
|
||
### SSL options | ||
|
||
The following table shows the available UI fields and their CLI equivalents: | ||
alexandra5000 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
| **UI Field** | **CLI Flag** | **Purpose** | | ||
|--------------------------------------------------|---------------------------------------|-------------| | ||
| Client SSL Certificate | `--elastic-agent-cert` | {{agent}} client certificate to use with {{fleet-server}} during mTLS authentication. | | ||
| Client SSL Certificate key | `--elastic-agent-cert-key` | {{agent}} client private key to use with {{fleet-server}} during mTLS authentication. This field uses secret storage and requires {{fleet-server}} v8.12.0 or later. You can optionally choose to store the value as plain text instead. | | ||
|
||
| Server SSL certificate authorities (optional) | `--certificate-authorities` | Comma-separated list of root certificates for server verification used by {{agent}} and {{fleet-server}}. | | ||
| SSL certificate for {{es}} | `--fleet-server-es-cert` | Client certificate for {{fleet-server}} to use when connecting to {{es}}. | | ||
| SSL certificate key for {{es}} | `--fleet-server-es-cert-key` | Client private key for {{fleet-server}} to use when connecting to {{es}}. | | ||
| {{es}} Certificate Authorities (optional) | `--fleet-server-es-ca` | Path to certificate authority for {{fleet-server}} to use to communicate with {{es}}. | | ||
| Enable client authentication | `--fleet-server-client-auth=required`| Requires {{agent}} to present a valid client certificate when connecting to {{fleet-server}}. | | ||
|
||
The {{fleet}} UI doesn't currently allow editing the {{fleet-server}}’s own exposed TLS certificate (`--fleet-server-cert`, `--fleet-server-cert-key`). These are only configurable using the CLI either during the initial installation or later. | ||
|
||
|
||
:::{warning} | ||
Editing SSL or proxy settings for an existing {{fleet-server}} may cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents. | ||
alexandra5000 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
::: |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -30,6 +30,9 @@ elastic-agent install --url=https://your-fleet-server.elastic.co:443 \ | |
--fleet-server-port=8220 | ||
``` | ||
|
||
You can also configure a one-way TLS connection using {{kib}}. Refer to [Configure TLS settings in the Fleet UI](#tls-ui-settings) for more information. {applies_to}`stack: ga 9.1` | ||
|
||
|
||
{{agent}} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from {{fleet-server}}. | ||
|
||
During the TLS connection setup, {{fleet-server}} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate. | ||
|
@@ -74,6 +77,9 @@ elastic-agent install --url=https://your-fleet-server.elastic.co:443 \ | |
--fleet-server-port=8220 | ||
``` | ||
|
||
You can also configure a mutual TLS connection using {{kib}}. Refer to [Configure TLS settings in the Fleet UI](#tls-ui-settings) for more information. {applies_to}`stack: ga 9.1` | ||
|
||
|
||
As with the [one-way TLS example](#one-way-tls-connection), {{agent}} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from the {{fleet-server}}. {{fleet-server}} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate. | ||
|
||
To establish a mutual TLS connection, the agent presents its certificate, `agent-cert`, and {{fleet-server}} validates this certificate using the `agent-ca` that it has stored in memory. | ||
|
@@ -97,3 +103,35 @@ Note that you can also configure mutual TLS for {{fleet-server}} and {{agent}} [ | |
:alt: Diagram of mutual TLS connection between components | ||
::: | ||
|
||
## Configure TLS/mTLS settings in the Fleet UI [tls-ui-settings] | ||
```{applies_to} | ||
stack: ga 9.1 | ||
``` | ||
|
||
You can configure TLS and mutual TLS (mTLS) settings for {{fleet-server}} hosts using the {{fleet}} UI instead of CLI flags. This approach simplifies certificate configuration. | ||
|
||
To access these settings: | ||
|
||
1. In **Kibana**, go to **Management** > **Fleet** > **Settings**. | ||
2. Under **Fleet Server hosts**, click **Add host** or edit an existing host. | ||
alexandra5000 marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
3. Expand the **SSL options** section. | ||
|
||
### SSL options | ||
|
||
|
||
The following table shows the available UI fields and their CLI equivalents: | ||
|
||
| **UI Field** | **CLI Flag** | **Purpose** | | ||
|--------------------------------------------------|---------------------------------------|-------------| | ||
| Client SSL Certificate | `--elastic-agent-cert` | {{agent}} client certificate to use with {{fleet-server}} during mTLS authentication. | | ||
| Client SSL Certificate key | `--elastic-agent-cert-key` | {{agent}} client private key to use with {{fleet-server}} during mTLS authentication. This field uses secret storage and requires {{fleet-server}} v8.12.0 or later. You can optionally choose to store the value as plain text instead. | | ||
| Server SSL certificate authorities (optional) | `--certificate-authorities` | Comma-separated list of root certificates for server verification used by {{agent}} and {{fleet-server}}. | | ||
| SSL certificate for {{es}} | `--fleet-server-es-cert` | Client certificate for {{fleet-server}} to use when connecting to {{es}}. | | ||
| SSL certificate key for {{es}} | `--fleet-server-es-cert-key` | Client private key for {{fleet-server}} to use when connecting to {{es}}. | | ||
| {{es}} Certificate Authorities (optional) | `--fleet-server-es-ca` | Path to certificate authority for {{fleet-server}} to use to communicate with {{es}}. | | ||
| Enable client authentication | `--fleet-server-client-auth=required`| Requires {{agent}} to present a valid client certificate when connecting to {{fleet-server}}. | | ||
|
||
The {{fleet}} UI doesn't currently allow editing the {{fleet-server}}’s own exposed TLS certificate (`--fleet-server-cert`, `--fleet-server-cert-key`). These are only configurable using the CLI either during the initial installation or later. | ||
|
||
:::{warning} | ||
Editing SSL or proxy settings for an existing {{fleet-server}} may cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents. | ||
::: |
Uh oh!
There was an error while loading. Please reload this page.