diff --git a/shield/docs/public/configuring-auditing.asciidoc b/shield/docs/public/configuring-auditing.asciidoc index 8fc9a342264..0c13c9399b7 100644 --- a/shield/docs/public/configuring-auditing.asciidoc +++ b/shield/docs/public/configuring-auditing.asciidoc @@ -207,7 +207,7 @@ The following tables describe the possible attributes each entry type can carry [float] === Audit Logs Settings -As mentioned above, the audit logs are configured in the `logging.yml` file located in `ES_HOME/config/shield`. The following snippet shows the default logging configuration: +As mentioned above, the audit logs are configured in the `logging.yml` file located in `CONFIG_DIR/shield`. The following snippet shows the default logging configuration: [[logging-file]] diff --git a/shield/docs/public/configuring-clients-integrations/java.asciidoc b/shield/docs/public/configuring-clients-integrations/java.asciidoc index e41c63ce90a..ca995e75ee7 100644 --- a/shield/docs/public/configuring-clients-integrations/java.asciidoc +++ b/shield/docs/public/configuring-clients-integrations/java.asciidoc @@ -82,9 +82,14 @@ dependencies { import org.elasticsearch.client.transport.TransportClient; ... -TransportClient client = new TransportClient(ImmutableSettings.builder() - .put("cluster.name", "myClusterName") - .put("shield.user", "transport_client_user:changeme") +TransportClient client = TransportClient.builder() + .settings(Settings.builder() + .put("cluster.name", "myClusterName") + .put("shield.user", "transport_client_user:changeme") + .put("plugin.types", "org.elasticsearch.shield.ShieldPlugin") + .put("path.home", "/path/to/client/home") + ... + .build()) .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301)); ------------------------------------------------------------------------------------------------- @@ -97,15 +102,23 @@ For example, the following snippet adds the `Authorization` header to a search r + [source,java] -------------------------------------------------------------------------------------------------- -import org.elasticsearch.shield.authc.support.SecuredString; import org.elasticsearch.client.transport.TransportClient; +import org.elasticsearch.common.settings.Settings; +import org.elasticsearch.common.transport.InetSocketTransportAddress; +import org.elasticsearch.shield.authc.support.SecuredString; import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue; ... -TransportClient client = new TransportClient(ImmutableSettings.builder() - .put("shield.user", "transport_client_user:changeme") - ... +TransportClient client = TransportClient.builder() + .settings(Settings.builder() + .put("cluster.name", "myClusterName") + .put("shield.user", "transport_client_user:changeme") + .put("plugin.types", "org.elasticsearch.shield.ShieldPlugin") + .put("path.home", "/path/to/client/home") + ... + .build()) + .build() .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301)); @@ -126,15 +139,19 @@ NOTE: Client authentication is enabled by default. For information about disabli import org.elasticsearch.client.transport.TransportClient; ... -TransportClient client = new TransportClient(ImmutableSettings.builder() - .put("cluster.name", "myClusterName") - .put("shield.user", "transport_client_user:changeme") - .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) - .put("shield.ssl.keystore.password", "password") - ... +TransportClient client = TransportClient.builder() + .settings(Settings.builder() + .put("cluster.name", "myClusterName") + .put("plugin.types", "org.elasticsearch.shield.ShieldPlugin") + .put("shield.user", "transport_client_user:changeme") + .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) + .put("shield.ssl.keystore.password", "password") + .put("path.home", "/path/to/client/home") + ... + .build()); -------------------------------------------------------------------------------------------------- + -(1) The `client.jks` keystore must contain the client's signed CA certificate and the CA certificate. +(1) The `client.jks` keystore must contain the client's signed certificate and the CA certificate. + .. Enable the SSL transport by setting `shield.transport.ssl` to `true` in the client configuration. + @@ -143,12 +160,17 @@ TransportClient client = new TransportClient(ImmutableSettings.builder() import org.elasticsearch.client.transport.TransportClient; ... -TransportClient client = new TransportClient(ImmutableSettings.builder() - .put("cluster.name", "myClusterName") - .put("shield.user", "transport_client_user:changeme") - .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) - .put("shield.ssl.keystore.password", "password") - .put("shield.transport.ssl", "true")) +TransportClient client = TransportClient.builder() + .settings(Settings.builder() + .put("cluster.name", "myClusterName") + .put("shield.user", "transport_client_user:changeme") + .put("shield.ssl.keystore.path", "/path/to/client.jks") (1) + .put("shield.ssl.keystore.password", "password") + .put("shield.transport.ssl", "true") + .put("plugin.types", "org.elasticsearch.shield.ShieldPlugin") + .put("path.home", "/path/to/client/home") + ... + .build()) .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301)); -------------------------------------------------------------------------------------------------- @@ -166,12 +188,17 @@ If you are not using client authentication and sign the Elasticsearch node certi import org.elasticsearch.client.transport.TransportClient; ... -TransportClient client = new TransportClient(ImmutableSettings.builder() - .put("cluster.name", "myClusterName") - .put("shield.user", "test_user:changeme") - .put("shield.ssl.truststore.path", "/path/to/truststore.jks") (1) - .put("shield.ssl.truststore.password", "password") - .put("shield.transport.ssl", "true")) +TransportClient client = TransportClient.builder() + .settings(Settings.builder() + .put("cluster.name", "myClusterName") + .put("shield.user", "test_user:changeme") + .put("shield.ssl.truststore.path", "/path/to/truststore.jks") (1) + .put("shield.ssl.truststore.password", "password") + .put("shield.transport.ssl", "true") + .put("plugin.types", "org.elasticsearch.shield.ShieldPlugin") + .put("path.home", "/path/to/client/home") + ... + .build()) .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301)); ------------------------------------------------------------------------------------------------------ @@ -198,7 +225,7 @@ The following example shows how you can clear Shield's realm caches using `Shiel import static org.elasticsearch.node.NodeBuilder.*; ... -Client client = ... // create the client (either transport or node) +Client client = ... // create the transport client ShieldClient shieldClient = new ShieldClient(client); ClearRealmCacheResponse response = shieldClient.authc().prepareClearRealmCache() diff --git a/shield/docs/public/configuring-rbac.asciidoc b/shield/docs/public/configuring-rbac.asciidoc index 948e810c8eb..ed8e95b678b 100644 --- a/shield/docs/public/configuring-rbac.asciidoc +++ b/shield/docs/public/configuring-rbac.asciidoc @@ -25,7 +25,7 @@ As an administrator, you will need to define the roles that you want to use, the [[defining-roles]] === Defining Roles -Roles are defined in the role definition file `roles.yml` located in `ES_HOME/config/shield`. +Roles are defined in the role definition file `roles.yml` located in `CONFIG_DIR/shield`. This is a YAML file where each entry defines the unique role name and the cluster and indices permissions associated with it. diff --git a/shield/docs/public/getting-started/enable-message-authentication.asciidoc b/shield/docs/public/getting-started/enable-message-authentication.asciidoc index f92e89d0ce0..83e407521ee 100644 --- a/shield/docs/public/getting-started/enable-message-authentication.asciidoc +++ b/shield/docs/public/getting-started/enable-message-authentication.asciidoc @@ -12,9 +12,7 @@ To enable message authentication: bin/shield/syskeygen ---------------- + -This creates a system key file in `ES_HOME/config/shield/system_key`. You -can customize this file's location by changing the value of the `shield.system_key.file` setting in -`elasticsearch.yml`. +This creates a system key file in `CONFIG_DIR/shield/system_key`. . Copy the genererated system key to the rest of the nodes in the cluster. diff --git a/shield/docs/public/managing-users.asciidoc b/shield/docs/public/managing-users.asciidoc index 3dd8077d841..ea034190e38 100644 --- a/shield/docs/public/managing-users.asciidoc +++ b/shield/docs/public/managing-users.asciidoc @@ -140,7 +140,7 @@ userdel [float] === About `esusers` -The `esusers` tool manipulates two files, `users` and `users_roles`, in `ES_HOME/config/shield/`. These two files store all user data for the _esusers_ realm and are read by Shield +The `esusers` tool manipulates two files, `users` and `users_roles`, in `CONFIG_DIR/shield/`. These two files store all user data for the _esusers_ realm and are read by Shield on startup. By default, Shield checks these files for changes every 5 seconds. You can change this default behavior by changing the diff --git a/shield/docs/public/reference.asciidoc b/shield/docs/public/reference.asciidoc index 4635816a123..0fbb4c7d102 100644 --- a/shield/docs/public/reference.asciidoc +++ b/shield/docs/public/reference.asciidoc @@ -163,7 +163,7 @@ The parameters listed in this section are configured in the `config/elasticsearc [options="header"] |====== | Name | Default | Description -| `shield.system_key.file` |`ES_HOME/config/shield/system_key` | Sets the location of the `system_key` file. For more information, see <>. +| `shield.system_key.file` |`CONFIG_DIR/shield/system_key` | Sets the <> of the `system_key` file. For more information, see <>. |====== [[ref-anonymous-access]] @@ -221,8 +221,8 @@ shield.authc.realms: [options="header"] |====== | Name | Required | Default | Description -| `files.users` | no | `ES_HOME/config/shield/users` | The location of the <> file. -| `files.users_roles` | no | `ES_HOME/config/shield/users_roles`| The location of the <> file. +| `files.users` | no | `CONFIG_DIR/shield/users` | The <> of the <> file. +| `files.users_roles` | no | `CONFIG_DIR/shield/users_roles`| The <> of the <> file. | `cache.ttl` | no | `20m` | The time-to-live for cached user entries--user credentials are cached for this configured period of time. Defaults to `20m`. Specify values using the standard Elasticsearch {ref}/common-options.html#time-units[time units]. | `cache.max_users` | no | 100000 | The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. | `cache.hash_algo` | no | `ssha256` | (Expert Setting) The hashing algorithm that is used for the in-memory cached user credentials. See the <> table for all possible values. @@ -251,7 +251,7 @@ shield.authc.realms: | `group_search.filter` | no | See description | When not set, the realm will search for `group`, `groupOfNames`, or `groupOfUniqueNames`, with the attributes `member` or `memberOf`. Any instance of `{0}` in the filter will be replaced by the user attribute defined in `group_search.user_attribute` | `group_search.user_attribute` | no | Empty | Specifies the user attribute that will be fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter. | `unmapped_groups_as_roles` | no | false | Takes a boolean variable. When this element is set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. THe default value is `false`. -| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | The path and file name for the <>. +| `files.role_mapping` | no | `CONFIG_DIR/shield/users/role_mapping.yml` | The <> for the <>. | `follow_referrals` | no | `true` | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). | `connect_timeout` | no | "5s" - for 5 seconds | The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. | `read_timeout` | no | "5s" - for 5 seconds | The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds. @@ -271,7 +271,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user | `url` | no | `ldap://:389` | A URL in the format `ldap[s]://:` If not specified the URL will be derived from the domain_name, assuming clear-text `ldap` and port `389` (e.g. `ldap://:389`). | `domain_name` | yes | - | The domain name of Active Directory. The cluster can derive the URL and `user_search_dn` fields from values in this element if those fields are not otherwise specified. | `unmapped_groups_as_roles` | no | false | Takes a boolean variable. When this element is set to `true`, the names of any unmapped groups and the user's relative distinguished name are used as role names and assigned to the user. THe default value is `false`. -| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | The path and file name for the <>. +| `files.role_mapping` | no | `CONFIG_DIR/shield/users/role_mapping.yml` | The <> for the <>. | `user_search.base_dn` | no | Root of Active Directory | The context to search for a user. The default value for this element is the root of the Active Directory domain. | `user_search.scope` | no | `sub_tree` | Specifies whether the user search should be `sub_tree`, `one_level` or `base`. `one_level` only searches users directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a user object, and that it is the only user considered. | `user_search.filter` | no | See description | Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName` @@ -296,7 +296,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user | `truststore.path` | no | `shield.ssl.keystore` | The path of a truststore to use. The default truststore is the one defined by <> | `truststore.password` | no | - | The password to the truststore. Must be provided if `truststore.path` is set. | `truststore.algorithm` | no | SunX509 | Algorithm for the trustsore. Default is `SunX509` -| `files.role_mapping` | no | `ES_HOME/config/shield/users/role_mapping.yml` | Specifies the path and file name for the <>. +| `files.role_mapping` | no | `CONFIG_DIR/shield/users/role_mapping.yml` | Specifies the <> for the <>. |====== [[ref-cache-hash-algo]] @@ -324,7 +324,7 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user [options="header"] |====== | Name | Default | Description -| `shield.authz.store.file.roles` | `ES_HOME/config/shield/users/roles.yml` | The location of the roles definition file. +| `shield.authz.store.file.roles` | `CONFIG_DIR/shield/users/roles.yml` | The <> of the roles definition file. |====== [[ref-ssl-tls-settings]] @@ -392,13 +392,18 @@ NOTE: `user_dn_templates` is required to operate in user template mode and `user The Shield security plugin uses the following files: -* `config/shield/roles.yml` defines the roles in use on the cluster (read more <>). -* `config/shield/users` defines the hashed passwords for users on the cluster (read more <>). -* `config/shield/users_roles` defines the role assignments for users on the cluster (read more <>). -* `config/shield/role_mapping.yml` defines the role assignments for a Distinguished Name (DN) to a role. This allows for +* `CONFIG_DIR/shield/roles.yml` defines the roles in use on the cluster (read more <>). +* `CONFIG_DIR/shield/users` defines the hashed passwords for users on the cluster (read more <>). +* `CONFIG_DIR/shield/users_roles` defines the role assignments for users on the cluster (read more <>). +* `CONFIG_DIR/shield/role_mapping.yml` defines the role assignments for a Distinguished Name (DN) to a role. This allows for LDAP and Active Directory groups and users and PKI users to be mapped to roles (read more <>). -* `config/shield/logging.yml` contains audit information (read more <>). -* `config/shield/system_key` holds a cluster secret key used for message authentication. For more information, see <>. +* `CONFIG_DIR/shield/logging.yml` contains audit information (read more <>). +* `CONFIG_DIR/shield/system_key` holds a cluster secret key used for message authentication. For more information, see <>. + +[[ref-shield-files-location]] +IMPORTANT: Any files that Shield uses must be stored in the Elasticsearch {ref}/setup-dir-layout.html#setup-dir-layout[configuration directory]. +Elasticsearch runs with restricted permissions and is only permitted to read from the locations configured in the directory +layout for enhanced security. Several of these files are in the YAML format. When you edit these files, be aware that YAML is indentation-level sensitive and indentation errors can lead to configuration errors. Avoid the tab character to set indentation levels, diff --git a/shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc b/shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc index e314ae0ff8a..396280d472f 100644 --- a/shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc +++ b/shield/docs/public/setting-up-authentication/configuring-active-directory-realm.asciidoc @@ -64,7 +64,7 @@ shield: | `group_search.base_dn` | no | Specifies the context to search for groups in which the user has membership. The default value for this element is the root of the Active Directory domain. | `group_search.scope` | no | Specifies whether the group search should be `sub_tree` (default), `one_level` or `base`. `one_level` searches for groups directly contained within the `base_dn`. `sub_tree` searches all objects contained under `base_dn`. `base` specifies that the `base_dn` is a group object, and that it is the only group considered. | `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`. -| `files.role_mapping` | no | Specifies the path and file name for the <>. By default it is `ES_HOME/config/shield/users/role_mapping.yml`. +| `files.role_mapping` | no | Specifies the <> for the <>. By default it is `CONFIG_DIR/shield/users/role_mapping.yml`. | `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`. | `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`. | `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]) diff --git a/shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc b/shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc index 60bb2c869e2..b7ab0fb528b 100644 --- a/shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc +++ b/shield/docs/public/setting-up-authentication/configuring-esusers-realm.asciidoc @@ -29,8 +29,8 @@ shield: | `type` | yes | Indicates the realm type and must be set to `esusers`. | `order` | no | Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`. | `enabled` | no | Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`. -| `files.users` | no | Points to the location of the `users` file where the users and their passwords are stored. By default, it is `ES_HOME/config/shield/users`. -| `files.users_roles` | no | Points to the location of the `users_roles` file where the users and their roles are stored. By default, it is `ES_HOME/config/shield/users_roles`. +| `files.users` | no | Points to the <> of the `users` file where the users and their passwords are stored. By default, it is `CONFIG_DIR/shield/users`. +| `files.users_roles` | no | Points to the <> of the `users_roles` file where the users and their roles are stored. By default, it is `CONFIG_DIR/shield/users_roles`. | `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]). | `cache.max_users` | no | Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. | `cache.hash_algo` | no | (Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see <> for possible values). diff --git a/shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc b/shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc index ff17f5007a6..6048eaf8b6d 100644 --- a/shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc +++ b/shield/docs/public/setting-up-authentication/configuring-ldap-realm.asciidoc @@ -101,7 +101,7 @@ shield: | `unmapped_groups_as_roles` | no | When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`. | `connect_timeout` | no | The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds | `read_timeout` | no | The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds -| `files.role_mapping` | no | Specifies the path and file name for the <>. By default, it is `ES_HOME/config/shield/role_mapping.yml`. +| `files.role_mapping` | no | Specifies the <> for the <>. By default, it is `CONFIG_DIR/shield/role_mapping.yml`. | `follow_referrals` | no | Boolean value that specifies whether Shield should follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Default is `true`. | `hostname_verification` | no | When set to `true`, hostname verification will be performed when connecting to a LDAP server. The hostname or IP address used in the `url` must match one of the names in the certificate or the connection will not be allowed. Defaults to `true`. | `cache.ttl` | no | Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard Elasticsearch {ref}/common-options.html#time-units[time units]). diff --git a/shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc b/shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc index efb70813491..361b3230263 100644 --- a/shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc +++ b/shield/docs/public/setting-up-authentication/configuring-pki-realm.asciidoc @@ -73,6 +73,6 @@ shield: | `truststore.path` | no | The path of a truststore to use. The default truststore is the one defined by <> | `truststore.password` | no | The password to the truststore. Must be provided if `truststore.path` is set. | `truststore.algorithm` | no | Algorithm for the trustsore. Default is `SunX509` -| `files.role_mapping` | no | Specifies the path and file name for the <>. By default, it is `ES_HOME/config/shield/role_mapping.yml`. +| `files.role_mapping` | no | Specifies the <> for the <>. By default, it is `CONFIG_DIR/shield/role_mapping.yml`. |======================= diff --git a/shield/docs/public/troubleshooting.asciidoc b/shield/docs/public/troubleshooting.asciidoc index 6e94c22d354..1e15894b28e 100644 --- a/shield/docs/public/troubleshooting.asciidoc +++ b/shield/docs/public/troubleshooting.asciidoc @@ -99,8 +99,8 @@ misconfigured. See <> for more. |====================== -To help track down these possibilities, add `shield.authc: DEBUG` to the `logging.yml` configuration file in `ES_HOME/config/shield/`. A successful -authentication should produce debug statements that list groups and role mappings. +To help track down these possibilities, add `shield.authc: DEBUG` to the `logging.yml` configuration file in `CONFIG_DIR`. +A successful authentication should produce debug statements that list groups and role mappings. --