-
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 6 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. | ||
|
||
|
@@ -101,15 +103,15 @@ For the steps in this section, imagine you have the following files: | |
To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: | ||
|
||
1. Configure {{fleet}} settings. These settings are applied to all {{fleet}}-managed {{agent}}s. | ||
2. In {{kib}}, open the main menu, then click **Management > {{fleet}} > Settings**. | ||
2. In {{kib}}, open the main menu, then select **Management > {{fleet}} > Settings**. | ||
|
||
1. Under **{{fleet-server}} hosts**, specify the URLs {{agent}}s will use to connect to {{fleet-server}}. For example, [https://192.0.2.1:8220](https://192.0.2.1:8220), where 192.0.2.1 is the host IP where you will install {{fleet-server}}. | ||
|
||
::::{tip} | ||
For host settings, use the `https` protocol. DNS-based names are also allowed. | ||
:::: | ||
|
||
2. Under **Outputs**, search for the default output, then click the **Edit** icon in the **Action** column. | ||
2. Under **Outputs**, search for the default output, then select the **Edit** icon in the **Action** column. | ||
3. In the **Hosts** field, specify the {{es}} URLs where {{agent}}s will send data. For example, [https://192.0.2.0:9200](https://192.0.2.0:9200). | ||
4. Specify either a CA certificate or CA fingerprint to connect securely {{es}}: | ||
|
||
|
@@ -156,7 +158,7 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: | |
|
||
1. Install an {{agent}} as a {{fleet-server}} on the host and configure it to use TLS: | ||
|
||
1. If you don’t already have a {{fleet-server}} service token, click the **Agents** tab in {{fleet}} and follow the instructions to generate the service token now. | ||
1. If you don’t already have a {{fleet-server}} service token, select the **Agents** tab in {{fleet}} and follow the instructions to generate the service token now. | ||
|
||
::::{tip} | ||
The in-product installation steps are incomplete. Before running the `install` command, add the settings shown in the next step. | ||
|
@@ -268,6 +270,38 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: | |
`certificate-authorities` | ||
: CA certificate to use to connect to {{fleet-server}}. This is the CA used to [generate a certificate and key](#generate-fleet-server-certs) for {{fleet-server}}. | ||
|
||
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. | ||
Don’t have an enrollment token? On the **Agents** tab in {{fleet}}, select **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**. | ||
2. Under **{{fleet-server}} hosts**, select **Add host** or edit an existing host. | ||
3. Expand the **SSL options** section. | ||
|
||
### SSL options | ||
|
||
These are 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}} might cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents. | ||
|
||
::: |
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**, select **Add host** or edit an existing host. | ||
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}} might cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents. | ||
::: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that the these should be
-fleet-server-es-cert
and-fleet-server-es-cert-key
. The--elastic-agent-cert
are the ones available under theoutput
section of fleet settings