From f9c203a3cf5b041df51ff8949e8e56b755b114f5 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 1 May 2018 13:47:24 -0700 Subject: [PATCH] [DOCS] Adds PKI realm configuration details (#30225) --- .../configuring-pki-realm.asciidoc | 176 ++++++++++++++++++ .../authentication/pki-realm.asciidoc | 170 +---------------- .../docs/en/security/configuring-es.asciidoc | 2 + 3 files changed, 182 insertions(+), 166 deletions(-) create mode 100644 x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc diff --git a/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc new file mode 100644 index 0000000000000..f66a82b06641e --- /dev/null +++ b/x-pack/docs/en/security/authentication/configuring-pki-realm.asciidoc @@ -0,0 +1,176 @@ +[role="xpack"] +[[configuring-pki-realm]] +=== Configuring a PKI realm + +You can configure {security} to use Public Key Infrastructure (PKI) certificates +to authenticate users in {es}. This requires clients to present X.509 +certificates. + +NOTE: You cannot use PKI certificates to authenticate users in {kib}. + +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 user certificates to {security} roles in the role mapping file. + +You can also 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 and enable client authentication to use PKI. + +For more information, see {xpack-ref}/pki-realm.html[PKI User Authentication]. + +. Add a realm configuration of type `pki` to `elasticsearch.yml` under the +`xpack.security.authc.realms` namespace. At a minimum, you must set the realm +`type` to `pki`. If you are configuring multiple realms, you should also +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: + +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + realms: + pki1: + type: pki +------------------------------------------------------------ + +With this configuration, any certificate trusted by the SSL/TLS layer is accepted +for authentication. The username is the common name (CN) extracted from the DN +of the certificate. + +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 DN as the username, you +can specify a regex to extract the desired username. For example, the regex in +the following configuration extracts the email address from the DN: + +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + realms: + pki1: + type: pki + username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" +------------------------------------------------------------ +-- + +. Restart {es}. + +. <>. + +. Enable client authentication on the desired network layers (transport or http). ++ +-- +//TBD: This step might need to be split into a separate topic with additional details +//about setting up client authentication. +The PKI realm relies on the TLS settings of the node's network interface. The +realm can be configured to be more restrictive than the underlying network +connection - that is, it is possible to configure the node such that some +connections are accepted by the network interface but then fail to be +authenticated by the PKI realm. However, the reverse is not possible. The PKI +realm cannot authenticate a connection that has been refused by the network +interface. + +In particular this means: + +* The transport or http interface must request client certificates by setting + `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. +* The _protocols_ supported by the interface must be compatible with those + used by the client. + +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 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. For example: + +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + realms: + pki1: + type: pki + truststore: + path: "/path/to/pki_truststore.jks" + password: "x-pack-test-password" +------------------------------------------------------------ + +The `certificate_authorities` option can be used as an alternative to the +`truststore.path` setting. +-- + +. Map roles for PKI users. ++ +-- +You map roles for PKI users through the +<> or by using a file stored on +each node. 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: +[source,js] +-------------------------------------------------- +PUT _xpack/security/role_mapping/users +{ + "roles" : [ "user" ], + "rules" : { "field" : { + "dn" : "cn=John Doe,ou=example,o=com" <1> + } }, + "enabled": true +} +-------------------------------------------------- +// CONSOLE +<1> The distinguished name (DN) of a PKI user. + +Or, alternatively, configured in a role-mapping file: +[source, yaml] +------------------------------------------------------------ +user: <1> + - "cn=John Doe,ou=example,o=com" <2> +------------------------------------------------------------ +<1> The name of a role. +<2> The distinguished name (DN) of a PKI user. + +The disinguished 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. +Some tools, such as _openssl_, may print out the subject name in a different + format. + +One way that you can determine the correct DN for a certificate is to use the +<> (use the relevant PKI +certificate as the means of authentication) and inspect the metadata field in +the result. The user's distinguished name will be populated under the `pki_dn` +key. You can also use the authenticate API to validate your role mapping. + +For more information, see +{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles]. +-- \ No newline at end of file diff --git a/x-pack/docs/en/security/authentication/pki-realm.asciidoc b/x-pack/docs/en/security/authentication/pki-realm.asciidoc index 2971f6e388739..47f9670d840aa 100644 --- a/x-pack/docs/en/security/authentication/pki-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/pki-realm.asciidoc @@ -1,5 +1,5 @@ [[pki-realm]] -=== PKI User Authentication +=== PKI user authentication You can configure {security} to use Public Key Infrastructure (PKI) certificates to authenticate users in {es}. This requires clients to present X.509 @@ -12,171 +12,9 @@ the desired network layers (transport or http), and map the Distinguished Names (DNs) from the user certificates to {security} roles in the <>. -You can also 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 and enabled client authentication to use PKI. - For more information, see <>. - -==== PKI Realm Configuration - -Like other realms, you configure options for a `pki` realm under the -`xpack.security.authc.realms` namespace in `elasticsearch.yml`. - -To configure a `pki` realm: - -. Add a realm configuration of type `pki` to `elasticsearch.yml` under the -`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to -`pki`. If you are configuring multiple realms, you should also 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: -+ -[source, yaml] ------------------------------------------------------------- -xpack: - security: - authc: - realms: - pki1: - type: pki ------------------------------------------------------------- -+ -With this configuration, any certificate trusted by the SSL/TLS layer is accepted -for authentication. The username is the common name (CN) extracted from the DN -of the certificate. -+ -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 DN as the username, you -can specify a regex to extract the desired username. For example, the regex in -the following configuration extracts the email address from the DN: -+ -[source, yaml] ------------------------------------------------------------- -xpack: - security: - authc: - realms: - pki1: - type: pki - username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" ------------------------------------------------------------- -+ -. Restart Elasticsearch. - -[[pki-ssl-config]] -==== PKI and SSL Settings - -The PKI realm relies on the SSL settings of the node's network interface -(transport or http). The realm can be configured to be more restrictive than -the underlying network connection - that is, it is possible to configure the -node such that some connections are accepted by the network interface but then -fail to be authenticated by the PKI realm. However the reverse is not possible -- the PKI realm cannot authenticate a connection that has been refused by the -network interface. - -In particular this means: - -* The transport or http interface must request client certificates by setting - `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 {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`] -for an explanation of this setting. - -* The _protocols_ supported by the interface must be compatible with those - used by the client. - - -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 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 as below: - -[source, yaml] ------------------------------------------------------------- -xpack: - security: - authc: - realms: - pki1: - type: pki - truststore: - path: "/path/to/pki_truststore.jks" - password: "x-pack-test-password" ------------------------------------------------------------- - -The `certificate_authorities` option may be used as an alternative to the -`truststore.path` setting. - +See {ref}/configuring-pki-realm.html[Configuring a PKI realm]. [[pki-settings]] -===== PKI Realm Settings - -See {ref}/security-settings.html#ref-pki-settings[PKI Realm Settings]. - -[[assigning-roles-pki]] -==== Mapping Roles for PKI Users - -You map roles for PKI users through the -{ref}/security-api-role-mapping.html[role-mapping API], or by using a file stored on -each node. 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: -[source,js] --------------------------------------------------- -PUT _xpack/security/role_mapping/users -{ - "roles" : [ "user" ], - "rules" : { "field" : { - "dn" : "cn=John Doe,ou=example,o=com" <1> - } }, - "enabled": true -} --------------------------------------------------- -// CONSOLE -<1> The distinguished name (DN) of a PKI user. - -Or, alternatively, configured in a role-mapping file: -[source, yaml] ------------------------------------------------------------- -user: <1> - - "cn=John Doe,ou=example,o=com" <2> ------------------------------------------------------------- -<1> The name of a role. -<2> The distinguished name (DN) of a PKI user. - -The disinguished 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. -Some tools, such as _openssl_, may print out the subject name in a different - format. - -One way that you can determine the correct DN for a certificate is to use the -{ref}/security-api-authenticate.html[authenticate API] (use the relevant PKI -certificate as the means of authentication) and inspect the metadata field in -the result. The user's distinguished name will be populated under the `pki_dn` -key. You can also use the authenticate API to validate your role mapping. +==== PKI Realm Settings -For more information, see <>. +See {ref}/security-settings.html#ref-pki-settings[PKI realm settings]. diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index 3efc682216faf..81e9007d7500c 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -72,6 +72,7 @@ user API. . Choose which types of realms you want to use to authenticate users. ** <>. +** <>. . Set up roles and users to control access to {es}. For example, to grant _John Doe_ full access to all indices that match @@ -132,5 +133,6 @@ include::securing-communications/configuring-tls-docker.asciidoc[] include::securing-communications/enabling-cipher-suites.asciidoc[] include::securing-communications/separating-node-client-traffic.asciidoc[] include::authentication/configuring-active-directory-realm.asciidoc[] +include::authentication/configuring-pki-realm.asciidoc[] include::{xes-repo-dir}/settings/security-settings.asciidoc[] include::{xes-repo-dir}/settings/audit-settings.asciidoc[]