diff --git a/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc index 073ba6f1ee0..26ded72958f 100644 --- a/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc @@ -6,26 +6,15 @@ 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. -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 -<> 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. -If you are configuring multiple realms, you should -explicitly set the `order` attribute. See <> for all of the -options you can set for a `pki` realm. +`xpack.security.authc.realms.pki` namespace. If you are configuring multiple +realms, you should explicitly set the `order` attribute. See +<> for all of the options you can set for a `pki` realm. + -- For example, the following snippet shows the most basic `pki` realm configuration: @@ -44,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] @@ -71,6 +66,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 <>. + . 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. @@ -80,6 +79,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 @@ -95,22 +99,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 - <> 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 <>. 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] ------------------------------------------------------------ @@ -135,25 +139,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 <> 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 +<> 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] -------------------------------------------------- @@ -169,10 +171,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] ------------------------------------------------------------ @@ -182,9 +181,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. @@ -206,47 +210,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 -<> -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}). +<> section. In this scenario, when you enable TLS, +it is mandatory that you <>. -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: -NOTE: {kib} also needs to be -{kibana-ref}/kibana-authentication.html#pki-authentication[configured to allow -PKI certificate authentication]. +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + token.enabled: true + realms: + pki: + pki1: + order: 1 + delegation.enabled: true + truststore: + path: "pki1_truststore.jks" +------------------------------------------------------------ + +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 <> or <>. -However, if you use the <>, -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 <>, 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] -------------------------------------------------- @@ -269,5 +286,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. diff --git a/x-pack/docs/en/security/authentication/pki-realm.asciidoc b/x-pack/docs/en/security/authentication/pki-realm.asciidoc index 3d06492f4a1..6119b57aea9 100644 --- a/x-pack/docs/en/security/authentication/pki-realm.asciidoc +++ b/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 <>. You can also use PKI certificates to authenticate to {kib}, however this