[DOCS] Adds PKI delegation.enabled example (#53030)

Author: lcawl

x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc

@@ -3,26 +3,18 @@
 
 To use PKI in {es}, you configure a PKI realm, enable client authentication on
 the desired network layers (transport or http), and map the Distinguished Names
-(DNs) from the Subject field in the user certificates to roles. You create the mappings in a role mapping file or use the role mappings API.
+(DNs) from the Subject field in the user certificates to roles. You create the
+mappings in a role mapping file or use the role mappings API.
 
-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
-<<pki-realm-for-proxied-clients,allow delegation>> and to
-{kibana-ref}/kibana-authentication.html#pki-authentication[enable PKI authentication in {kib}].
-
-You can also use a combination of PKI and username/password authentication. For
+TIP: You can use a combination of PKI and username/password authentication. For
 example, you can enable SSL/TLS on the transport layer and define a PKI realm to
 require transport clients to authenticate with X.509 certificates, while still
-authenticating HTTP traffic using username and password credentials. You can
-also set `xpack.security.transport.ssl.client_authentication` to `optional` to
-allow clients without certificates to authenticate with other credentials.
-
-IMPORTANT: You must enable SSL/TLS with client authentication to use PKI when
-clients connect directly to {es}.
+authenticating HTTP traffic using username and password credentials.
 
 . Add a realm configuration for a `pki` realm to `elasticsearch.yml` under the
-`xpack.security.authc.realms.pki` namespace.
-You must explicitly set the `order` attribute. See <<ref-pki-settings>> for all
-of the options you can set for a `pki` realm.
+`xpack.security.authc.realms.pki` namespace. You must explicitly set the `order`
+attribute. See <<ref-pki-settings>> for all of the options you can set for a
+`pki` realm.
 +
 --
 For example, the following snippet shows the most basic `pki` realm configuration:
@@ -41,15 +33,21 @@ xpack:
 With this configuration, any certificate trusted by the {es} SSL/TLS layer is
 accepted for authentication. The username is the common name (CN) extracted
 from the DN in the Subject field of the end-entity certificate. This
-configuration does not permit PKI authentication to {kib}.
+configuration is not sufficient to permit PKI authentication to {kib};
+additional steps are required.
 
 IMPORTANT: 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.
 
-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
+--
+
+. Optional: 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:
 
 [source, yaml]
@@ -69,6 +67,10 @@ client's certificate, then the realm does not authenticate the certificate.
 
 --
 
+. 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-realm-for-proxied-clients>>.
+
 . 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.
@@ -78,6 +80,11 @@ restart for last.
 . Enable client authentication on the desired network layers (transport or http).
 +
 --
+IMPORTANT: To use PKI when clients connect directly to {es}, you must enable
+SSL/TLS with client authentication. That is to say, you must set   `xpack.security.transport.ssl.client_authentication` and
+`xpack.security.http.ssl.client_authentication` to `optional` or `required`. If
+the setting value is `optional`, clients without certificates can authenticate
+with other credentials.
 
 When clients connect directly to {es} and are not proxy-authenticated, the PKI
 realm relies on the TLS settings of the node's network interface. The realm can
@@ -93,22 +100,22 @@ In particular this means:
   `client_authentication` to `optional` or `required`.
 * The interface must _trust_ the certificate that is presented by the client
   by configuring either the `truststore` or `certificate_authorities` paths,
-  or by setting `verification_mode` to `none`. See 
-  <<ssl-tls-settings,`ssl.verification_mode`>> for an explanation of this
-  setting.
+  or by setting `verification_mode` to `none`.
 * The _protocols_ supported by the interface must be compatible with those
   used by the client.
+  
+For an explanation of these settings, see <<ssl-tls-settings>>.
 
 The relevant network interface (transport or http) must be configured to trust
-any certificate that is to be used within the PKI realm. However, it is possible to
-configure the PKI realm to trust only a _subset_ of the certificates accepted
+any certificate that is to be used within the PKI realm. However, it is possible
+to configure the PKI realm to trust only a _subset_ of the certificates accepted
 by the network interface. This is useful when the SSL/TLS layer trusts clients 
 with certificates that are signed by a different CA than the one that signs your 
 users' certificates.
 
 To configure the PKI realm with its own truststore, specify the
 `truststore.path` option. The path must be located within the Elasticsearch
-configuration directory (ES_PATH_CONF). For example:
+configuration directory (`ES_PATH_CONF`). For example:
 
 [source, yaml]
 ------------------------------------------------------------
@@ -134,25 +141,23 @@ xpack.security.authc.realms.pki.pki1.truststore.secure_password
 ------------------------------------------------------------
 
 The `certificate_authorities` option can be used as an alternative to the
-`truststore.path` setting, when the certificate files are PEM formatted
-. The setting accepts a list. The two options are exclusive, they cannot be both used
+`truststore.path` setting, when the certificate files are PEM formatted. The
+setting accepts a list. The two options are exclusive, they cannot be both used
 simultaneously.
 --
 
 . Map roles for PKI users.
 +
 --
-You map roles for PKI users through the <<security-role-mapping-apis,role
-mapping APIs>> or by using a file stored on each node. Both configuration
-options are merged together. When a user authenticates against a PKI realm, the
-privileges for that user are the union of all privileges defined by the roles
-to which the user is mapped.
+You map roles for PKI users through the
+<<security-role-mapping-apis,role mapping APIs>> or by using a file stored on
+each node. Both configuration options are merged together. When a user
+authenticates against a PKI realm, the privileges for that user are the union of
+all privileges defined by the roles to which the user is mapped.
 
 You identify a user by the distinguished name in their certificate.
 For example, the following mapping configuration maps `John Doe` to the
-`user` role:
-
-Using the role-mapping API:
+`user` role using the role mapping API:
 
 [source,console]
 --------------------------------------------------
@@ -168,10 +173,7 @@ PUT /_security/role_mapping/users
 
 <1> The distinguished name (DN) of a PKI user.
 
-Or, alternatively, configured inside a role-mapping file. The file's path
-defaults to `ES_PATH_CONF/role_mapping.yml`. You can specify a different path (which must be within
-ES_PATH_CONF) by using the `files.role_mapping` realm setting (e.g.
-`xpack.security.authc.realms.pki.pki1.files.role_mapping`):
+Alternatively, use a role-mapping file. For example:
 
 [source, yaml]
 ------------------------------------------------------------
@@ -181,9 +183,14 @@ user: <1>
 <1> The name of a role.
 <2> The distinguished name (DN) of a PKI user.
 
+The file's path defaults to `ES_PATH_CONF/role_mapping.yml`. You can specify a
+different path (which must be within `ES_PATH_CONF`) by using the
+`files.role_mapping` realm setting (e.g.
+`xpack.security.authc.realms.pki.pki1.files.role_mapping`).
+
 The distinguished name for a PKI user follows X.500 naming conventions which
 place the most specific fields (like `cn` or `uid`) at the beginning of the
-name, and the most general fields (like `o` or `dc`) at the end of the name.
+name and the most general fields (like `o` or `dc`) at the end of the name.
 Some tools, such as _openssl_, may print out the subject name in a different
 format.
 
@@ -205,47 +212,60 @@ alternative to role mapping.
 
 By default, the PKI realm relies on the node's network interface to perform the
 SSL/TLS handshake and extract the client certificate. This behaviour requires
-that that clients connect directly to {es} so that their SSL connection is
-terminated by the {es} node.  If SSL/TLS authenticatication is to be performed
-by {kib}, the PKI realm must be configured to permit delegation.
+that clients connect directly to {es} so that their SSL connection is terminated
+by the {es} node.  If SSL/TLS authentication is to be performed by {kib}, the
+PKI realm must be configured to permit delegation.
 
 Specifically, when clients presenting X.509 certificates connect to {kib},
 {kib} performs the SSL/TLS authentication. {kib} then forwards the client's
-certificate chain, by calling an {es} API, to have them further validated by
+certificate chain (by calling an {es} API) to have them further validated by
 the PKI realms that have been configured for delegation.
 
 To permit authentication delegation for a specific {es} PKI realm, start by
 configuring the realm for the usual case, as detailed in the
-<<pki-realm-for-direct-clients>>
-section. Note that you must explicitly configure a `truststore` (or,
-equivalently `certificate_authorities`) even though it is the same trust
-configuration that you have configured on the network layer.  Afterwards,
-simply toggle the `delegation.enabled` realm setting to `true`.  This realm is
-now allowed to validate delegated PKI authentication (after restarting {es}).
+<<pki-realm-for-direct-clients>> section. In this scenario, when you enable TLS,
+it is mandatory that you <<tls-http,encrypt HTTP client communications>>.
 
-NOTE: PKI authentication delegation requires that the
-`xpack.security.authc.token.enabled` setting be `true` and that SSL/TLS be
-configured (without SSL/TLS client authentication).
+You must also explicitly configure a `truststore` (or, equivalently
+`certificate_authorities`) even though it is the same trust configuration that
+you have configured on the network layer. The
+`xpack.security.authc.token.enabled` and `delegation.enabled` settings must also
+be `true`. For example:
+
+[source, yaml]
+------------------------------------------------------------
+xpack:
+  security:
+    authc:
+      token.enabled: true
+      realms:
+        pki:
+          pki1:
+            order: 1
+            delegation.enabled: true
+            truststore:
+              path: "pki1_truststore.jks"
+------------------------------------------------------------
 
-NOTE: {kib} also needs to be
-{kibana-ref}/kibana-authentication.html#pki-authentication[configured to allow
-PKI certificate authentication].
+After you restart {es}, this realm can validate delegated PKI authentication.
+You must then 
+{kibana-ref}/kibana-authentication.html#pki-authentication[configure {kib} to allow PKI certificate authentication].
 
 A PKI realm with `delegation.enabled` still works unchanged for clients
-connecting directly to {es}. Directly authenticated users, and users that are PKI
+connecting directly to {es}. Directly authenticated users and users that are PKI
 authenticated by delegation to {kib} both follow the same
 <<mapping-roles,role mapping rules>> or
 <<authorization_realms,authorization realms configurations>>.
 
-However, if you use the <<security-role-mapping-apis,role mapping APIs>>,
-you can distinguish between users that are authenticated by delegation and
-users that are authenticated directly. The former have the
-extra fields `pki_delegated_by_user` and `pki_delegated_by_realm` in the user's
-metadata. In the common setup, where authentication is delegated to {kib}, the
-values of these fields are `kibana` and `reserved`, respectively. For example,
-the following role mapping rule will assign the `role_for_pki1_direct` role to
-all users that have been authenticated directly by the `pki1` realm, by
-connecting to {es} instead of going through {kib}:
+If you use the <<security-role-mapping-apis,role mapping APIs>>, however, you
+can distinguish between users that are authenticated by delegation and users
+that are authenticated directly. The former have the extra fields
+`pki_delegated_by_user` and `pki_delegated_by_realm` in the user's metadata. In
+the common setup, where authentication is delegated to {kib}, the values of
+these fields are `kibana` and `reserved`, respectively. For example, the
+following role mapping rule assigns the `role_for_pki1_direct` role to all users
+that have been authenticated directly by the `pki1` realm, by connecting to {es}
+instead of going through {kib}:
 
 [source,console]
 --------------------------------------------------
@@ -268,5 +288,5 @@ PUT /_security/role_mapping/direct_pki_only
 }
 --------------------------------------------------
 
-<1> only when this metadata field is set (it is *not* `null`) the user has been
-authenticated in the delegation scenario.
+<1> If this metadata field is set (that is to say, it is *not* `null`), the user
+has been authenticated in the delegation scenario.

x-pack/docs/en/security/authentication/pki-realm.asciidoc

@@ -3,9 +3,9 @@
 === PKI user authentication
 
 You can configure {es} to use Public Key Infrastructure (PKI) certificates to
-authenticate users. This requires clients connecting directly to {es} to
-present X.509 certificates. The certificates must first be accepted for
-authentication on the SSL/TLS layer on {es}. Only then they are optionally
+authenticate users. In this scenario, clients connecting directly to {es} must
+present X.509 certificates. First, the certificates must be accepted for
+authentication on the SSL/TLS layer on {es}. Then they are optionally
 further validated by a PKI realm. See <<pki-realm-for-direct-clients>>.
 
 You can also use PKI certificates to authenticate to {kib}, however this