diff --git a/docs/en/installing-xes.asciidoc b/docs/en/installing-xes.asciidoc index e71bc947369..5faecd228ff 100644 --- a/docs/en/installing-xes.asciidoc +++ b/docs/en/installing-xes.asciidoc @@ -82,7 +82,10 @@ Continue with installation? [y/N]y ---------------------------------------------------------- -- -. If you have disabled automatic index creation in {es}, configure +. {xpack} will try to automatically create a number of indices within {es}. +By default, {es} is configured to allow automatic index creation, and no +additional steps are required. However, if you have disabled automatic index +creation in {es}, you must configure {ref}/docs-index_.html#index-creation[`action.auto_create_index`] in `elasticsearch.yml` to allow {xpack} to create the following indices: + @@ -92,6 +95,16 @@ Continue with installation? [y/N]y action.auto_create_index: .security,.monitoring*,.watches,.triggered_watches,.watcher-history*,.ml* ----------------------------------------------------------- -- ++ +[IMPORTANT] +============================================================================= +If you are using https://www.elastic.co/products/logstash[Logstash] +or https://www.elastic.co/products/beats[Beats] then you will most likely +require additional index names in your `action.auto_create_index` setting, and +the exact value will depend on your local configuration. If you are unsure of +the correct value for your environment, you may consider setting the value to + `*` which will allow automatic creation of all indices. +============================================================================= . Start {es}. + diff --git a/docs/en/security/authentication/pki-realm.asciidoc b/docs/en/security/authentication/pki-realm.asciidoc index 57c2a7435df..fbfae67ada1 100644 --- a/docs/en/security/authentication/pki-realm.asciidoc +++ b/docs/en/security/authentication/pki-realm.asciidoc @@ -65,11 +65,40 @@ xpack: username_pattern: "EMAILADDRESS=(.*?)(?:,|$)" ------------------------------------------------------------ + -You can also specify which truststore to use for authentication. 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 specify the -location of the truststore, specify the `truststore.path` option: -+ +. 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`. +* 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: @@ -83,35 +112,41 @@ xpack: password: "x-pack-test-password" ------------------------------------------------------------ -. Restart Elasticsearch. +The `certificate_authorities` option may be used as an alternative to the +`truststore.path` setting. + [[pki-settings]] ===== PKI Realm Settings [cols="4,^3,10"] |======================= -| Setting | Required | Description -| `type` | yes | Indicates the realm type. Must be set to `pki`. -| `order` | no | Indicates the priority of this realm within the realm - chain. Realms with a lower order are consulted first. - Although not required, we recommend explicitly - setting this value when you configure multiple realms. - Defaults to `Integer.MAX_VALUE`. -| `enabled` | no | Indicates whether this realm is enabled or disabled. - Enables you to disable a realm without removing its - configuration. Defaults to `true`. -| `username_pattern` | no | Specifies the regular expression pattern used to extract - the username from the certificate DN. The first match - group is used as the username. Defaults to `CN=(.*?)(?:,\|$)`. -| `truststore.path` | no | The path to the truststore. Defaults to the path - defined by {ref}/security-settings.html#ssl-tls-settings[SSL/TLS settings]. -| `truststore.password` | no/yes | Specifies the password for the truststore. Must be - provided if `truststore.path` is set. -| `truststore.algorithm` | no | Specifies the algorithm used for the truststore. - Defaults to `SunX509`. -| `files.role_mapping` | no | Specifies the <> - for the <>. - Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`. +| Setting | Required | Description +| `type` | yes | Indicates the realm type. Must be set to `pki`. +| `order` | no | Indicates the priority of this realm within the realm + chain. Realms with a lower order are consulted first. + Although not required, we recommend explicitly + setting this value when you configure multiple realms. + Defaults to `Integer.MAX_VALUE`. +| `enabled` | no | Indicates whether this realm is enabled or disabled. + Enables you to disable a realm without removing its + configuration. Defaults to `true`. +| `username_pattern` | no | Specifies the regular expression pattern used to extract + the username from the certificate DN. The first match + group is used as the username. Defaults to `CN=(.*?)(?:,\|$)`. +| `certificate_authorities` | no | List of paths to the PEM encoded certificate files + that should be trusted. + This setting may not be used with `truststore.path`. +| `truststore.path` | no | The path to the truststore. Defaults to the path + defined by {ref}/security-settings.html#ssl-tls-settings[SSL/TLS settings]. + This setting may not be used with `certificate_authorities`. +| `truststore.password` | no/yes | Specifies the password for the truststore. Must be + provided if `truststore.path` is set. +| `truststore.algorithm` | no | Specifies the algorithm used for the truststore. + Defaults to `SunX509`. +| `files.role_mapping` | no | Specifies the <> + for the <>. + Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`. |======================= [[assigning-roles-pki]] @@ -151,4 +186,16 @@ user: <1> <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. + For more information, see <>. diff --git a/docs/en/security/authorization/mapping-roles.asciidoc b/docs/en/security/authorization/mapping-roles.asciidoc index 3106c16fb72..86cd76797ca 100644 --- a/docs/en/security/authorization/mapping-roles.asciidoc +++ b/docs/en/security/authorization/mapping-roles.asciidoc @@ -258,6 +258,12 @@ are values. The mappings can have a many-to-many relationship. When you map role to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user. +By default, {security} checks role mapping files for changes every 5 seconds. +You can change this default behavior by changing the +`resource.reload.interval.high` setting in the `elasticsearch.yml` file +(as this is a common setting in Elasticsearch, changing its value may effect +other schedules in the system). + ==== Realm Specific Details [float] [[ldap-role-mapping]] diff --git a/docs/en/security/authorization/run-as-privilege.asciidoc b/docs/en/security/authorization/run-as-privilege.asciidoc index fb9d159a786..0db5b53a9dd 100644 --- a/docs/en/security/authorization/run-as-privilege.asciidoc +++ b/docs/en/security/authorization/run-as-privilege.asciidoc @@ -8,8 +8,10 @@ users, you can use the _run as_ mechanism to restrict data access according to To "run as" (impersonate) another user, you must be able to retrieve the user from the realm you use to authenticate. Both the internal `native` and `file` realms -support this out of the box. The LDAP realm however must be configured to enable -user search. For more information, see <>. +support this out of the box. The LDAP realm however must be configured to run in +_user search_ mode. For more information, see +<>. +The Active Directory and PKI realms do not support "run as". To submit requests on behalf of other users, you need to have the `run_as` permission. For example, the following role grants permission to submit request diff --git a/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc b/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc index 9df51383959..8afb089ce9c 100644 --- a/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc +++ b/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc @@ -13,7 +13,7 @@ to `elasticsearch.yml`: -------------------------------------------------- transport.profiles.client: <1> port: 9500-9600 <2> - shield: + xpack.security: type: client <3> -------------------------------------------------- <1> `client` is the name of this example profile diff --git a/docs/en/security/tribe-clients-integrations/logstash.asciidoc b/docs/en/security/tribe-clients-integrations/logstash.asciidoc index 9cbfa30368c..5c5f064f332 100644 --- a/docs/en/security/tribe-clients-integrations/logstash.asciidoc +++ b/docs/en/security/tribe-clients-integrations/logstash.asciidoc @@ -73,22 +73,27 @@ plugins in your Logstash `.conf` file. For example: + [source,js] -------------------------------------------------- -input { +input { + elasticsearch { ... user => logstash_internal password => x-pack-test-password } +} filter { + elasticsearch { ... user => logstash_internal password => x-pack-test-password } +} output { elasticsearch { ... user => logstash_internal password => x-pack-test-password } +} -------------------------------------------------- [float] diff --git a/docs/en/settings/security-settings.asciidoc b/docs/en/settings/security-settings.asciidoc index 2cc4836cada..89a5ad62bdb 100644 --- a/docs/en/settings/security-settings.asciidoc +++ b/docs/en/settings/security-settings.asciidoc @@ -494,10 +494,12 @@ Defaults to `CN=(.*?)(?:,\|$)` `certificate_authorities`:: List of PEM certificate files that should be used to authenticate a user's certificate as trusted. Defaults to the trusted certificates configured for SSL. +See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information. This setting may not be used with `truststore.path`. `truststore.path`:: The path of a truststore to use. Defaults to the trusted certificates configured for SSL. +See the {xpack-ref}/pki-realm.html#pki-ssl-config[SSL settings] section of the PKI realm documentation for more information. This setting may not be used with `certificate_authorities`. `truststore.password`::