From bb53b308290aef5bd1619b41d2c8dd332e6665ea Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Thu, 20 Nov 2025 11:44:22 -0800 Subject: [PATCH 1/7] Add details about username_rdn_name and username_rdn_oid to PKI security doc. --- .../users-roles/cluster-or-deployment-auth/pki.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index 76457afaff..b7701a4108 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -63,6 +63,21 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. :::: + Alternatively, username can be extracted from a specific RDN attribute in the Subject DN by using [username_rdn_name](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) or [username_rdn_oid](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings). When an RDN attribute configuration is provided, it supersedes `username_pattern`. + + For example, to extract the username from the `CN` RDN attribute: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + username_rdn_name: "CN" + ``` + 3. Optional: If you want the same users to also be authenticated using certificates when they connect to {{kib}}, you must configure the {{es}} PKI realm to allow delegation. See [PKI authentication for clients connecting to {{kib}}](#pki-realm-for-proxied-clients). 4. Restart {{es}} because realm configuration is not reloaded automatically. If you’re following through with the next steps, you might wish to hold the restart for last. 5. If you're using a self-managed cluster, then [enable SSL/TLS](../../security/secure-cluster-communications.md#encrypt-internode-communication). From 7407abc944f22cb5c59d398cbd28d9981a9f458c Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Thu, 20 Nov 2025 12:30:56 -0800 Subject: [PATCH 2/7] Rearrange the section related to certificate principal extraction in PKI doc --- .../cluster-or-deployment-auth/pki.md | 78 +++++++++++-------- 1 file changed, 45 insertions(+), 33 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index b7701a4108..d85265deb4 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -44,39 +44,51 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on When you configure realms in `elasticsearch.yml`, only the realms you specify are used for authentication. If you also want to use the `native` or `file` realms, you must include them in the realm chain. :::: -2. Optional: The username is defined by the [username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can specify a regex to extract the desired username. The regex is applied on the Subject DN. - - For example, the regex in the following configuration extracts the email address from the Subject DN: - - ```yaml - xpack: - security: - authc: - realms: - pki: - pki1: - order: 1 - username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" - ``` - - ::::{note} - If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. - :::: - - Alternatively, username can be extracted from a specific RDN attribute in the Subject DN by using [username_rdn_name](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) or [username_rdn_oid](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings). When an RDN attribute configuration is provided, it supersedes `username_pattern`. - - For example, to extract the username from the `CN` RDN attribute: - - ```yaml - xpack: - security: - authc: - realms: - pki: - pki1: - order: 1 - username_rdn_name: "CN" - ``` +2. Optional: The username is defined by the [username_pattern](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: + + * {applies_to}`stack: ga 9.1` Extract the username from a specific RDN attribute in the Subject DN. + * Specify a regex to extract the desired username. The regex is applied on the Subject DN. + + :::::{tab-set} + + ::::{tab-item} Specific RDN attribute + The username can be extracted from a specific RDN attribute in the Subject DN by using [username_rdn_name](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) or [username_rdn_oid](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings). When an RDN attribute configuration is provided, it supersedes `username_pattern`. + + For example, to extract the username from the `CN` RDN attribute: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + username_rdn_name: "CN" + ``` + :::: + + ::::{tab-item} Regex + Specify a regex to extract the desired username. The regex is applied on the Subject DN. + + For example, the regex in the following configuration extracts the email address from the Subject DN: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" + ``` + :::{note} + If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. + ::: + :::: + + ::::: 3. Optional: If you want the same users to also be authenticated using certificates when they connect to {{kib}}, you must configure the {{es}} PKI realm to allow delegation. See [PKI authentication for clients connecting to {{kib}}](#pki-realm-for-proxied-clients). 4. Restart {{es}} because realm configuration is not reloaded automatically. If you’re following through with the next steps, you might wish to hold the restart for last. From 63764e0cdf79b5549940ef31825a6052e26d054d Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Thu, 20 Nov 2025 12:56:26 -0800 Subject: [PATCH 3/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/pki.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/pki.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index d85265deb4..cbf7ce0f40 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -47,7 +47,7 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on 2. Optional: The username is defined by the [username_pattern](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: * {applies_to}`stack: ga 9.1` Extract the username from a specific RDN attribute in the Subject DN. - * Specify a regex to extract the desired username. The regex is applied on the Subject DN. + * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. :::::{tab-set} From c717dcca7ddfe5a2365e77edb1575084553c038a Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Thu, 20 Nov 2025 13:01:47 -0800 Subject: [PATCH 4/7] Replace tabs with spaces --- .../cluster-or-deployment-auth/pki.md | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index cbf7ce0f40..3649f61d36 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -47,9 +47,9 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on 2. Optional: The username is defined by the [username_pattern](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: * {applies_to}`stack: ga 9.1` Extract the username from a specific RDN attribute in the Subject DN. - * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. + * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. - :::::{tab-set} + :::::{tab-set} ::::{tab-item} Specific RDN attribute The username can be extracted from a specific RDN attribute in the Subject DN by using [username_rdn_name](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) or [username_rdn_oid](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings). When an RDN attribute configuration is provided, it supersedes `username_pattern`. @@ -68,27 +68,27 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on ``` :::: - ::::{tab-item} Regex - Specify a regex to extract the desired username. The regex is applied on the Subject DN. - - For example, the regex in the following configuration extracts the email address from the Subject DN: - - ```yaml - xpack: - security: - authc: - realms: - pki: - pki1: - order: 1 - username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" - ``` - :::{note} - If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. - ::: - :::: - - ::::: + ::::{tab-item} Regex + Specify a regex to extract the desired username. The regex is applied on the Subject DN. + + For example, the regex in the following configuration extracts the email address from the Subject DN: + + ```yaml + xpack: + security: + authc: + realms: + pki: + pki1: + order: 1 + username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" + ``` + :::{note} + If the regex is too restrictive and does not match the Subject DN of the client’s certificate, then the realm does not authenticate the certificate. + ::: + :::: + + ::::: 3. Optional: If you want the same users to also be authenticated using certificates when they connect to {{kib}}, you must configure the {{es}} PKI realm to allow delegation. See [PKI authentication for clients connecting to {{kib}}](#pki-realm-for-proxied-clients). 4. Restart {{es}} because realm configuration is not reloaded automatically. If you’re following through with the next steps, you might wish to hold the restart for last. From 8306f98958135bf9ff8026c8a58ed1c90372ddb4 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Fri, 21 Nov 2025 08:26:04 -0800 Subject: [PATCH 5/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/pki.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/pki.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index 3649f61d36..3c078c6d80 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -44,7 +44,7 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on When you configure realms in `elasticsearch.yml`, only the realms you specify are used for authentication. If you also want to use the `native` or `file` realms, you must include them in the realm chain. :::: -2. Optional: The username is defined by the [username_pattern](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings#ref-pki-settings). If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: +2. Optional: If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: * {applies_to}`stack: ga 9.1` Extract the username from a specific RDN attribute in the Subject DN. * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. From a78bf13099f71330c37caf6c1fae7b6e3b346551 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Fri, 21 Nov 2025 09:47:02 -0800 Subject: [PATCH 6/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/pki.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/pki.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index 3c078c6d80..8fcad8ee35 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -46,7 +46,7 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on 2. Optional: If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: - * {applies_to}`stack: ga 9.1` Extract the username from a specific RDN attribute in the Subject DN. + * {applies_to}`stack: ga 9.1` Extract the username from a specific relative distinguished name (RDN) attribute in the Subject DN. * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. :::::{tab-set} From fc077f5a1f9e2a8e394c84c52ddf9ed42a8dc95e Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Fri, 21 Nov 2025 09:57:32 -0800 Subject: [PATCH 7/7] Update deploy-manage/users-roles/cluster-or-deployment-auth/pki.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/users-roles/cluster-or-deployment-auth/pki.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md index 8fcad8ee35..ed4fee1d4a 100644 --- a/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md +++ b/deploy-manage/users-roles/cluster-or-deployment-auth/pki.md @@ -47,7 +47,7 @@ To use PKI in {{es}}, you configure a PKI realm, enable client authentication on 2. Optional: If you want to use something other than the CN of the Subject DN as the username, you can use one of the following methods to extract the username: * {applies_to}`stack: ga 9.1` Extract the username from a specific relative distinguished name (RDN) attribute in the Subject DN. - * Using the [[username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. + * Using the [username_pattern](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#ref-pki-settings) setting, specify a regex to extract the desired username. The regex is applied on the Subject DN. :::::{tab-set}