From e95a7aa6f0df00e71725c4888f107ab55b35916b Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 30 Apr 2018 08:52:21 -0700 Subject: [PATCH] [DOCS] Removes redundant Active Directory realm settings (#30190) --- .../active-directory-realm.asciidoc | 178 +----------------- .../en/settings/security-settings.asciidoc | 96 ++++++---- 2 files changed, 67 insertions(+), 207 deletions(-) diff --git a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc index 2aaca6def91..143156ca636 100644 --- a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc @@ -169,186 +169,14 @@ domain name from the NetBIOS name. ===== Load Balancing and Failover The `load_balance.type` setting can be used at the realm level to configure how {security} should interact with multiple Active Directory servers. Two modes of -operation are supported: failover and load balancing +operation are supported: failover and load balancing. -.Load Balancing and Failover Types -|======================= -| Type | | | Description -| `failover` | | | The URLs specified are used in the order that they are - specified. The first server that can be connected to will - be used for all subsequent connections. If a connection to - that server fails then the next server that a connection - can be established to will be used for subsequent connections. -| `dns_failover` | | | In this mode of operation, only a single URL may be specified. - This URL must contain a DNS name. The system will be queried - for all IP addresses that correspond to this DNS name. - Connections to the Active Directory server will always be - tried in the order in which they were retrieved. This differs - from `failover` in that there is no reordering of the list - and if a server has failed at the beginning of the list, it - will still be tried for each subsequent connection. -| `round_robin` | | | Connections will continuously iterate through the list of - provided URLs. If a server is unavailable, iterating through - the list of URLs will continue until a successful connection - is made. -| `dns_round_robin` | | | In this mode of operation, only a single URL may be specified. - This URL must contain a DNS name. The system will be queried - for all IP addresses that correspond to this DNS name. - Connections will continuously iterate through the list of - addresses. If a server is unavailable, iterating through the - list of URLs will continue until a successful connection is - made. -|======================= +See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings]. [[ad-settings]] ===== Active Directory Realm Settings -[cols="4,^3,10"] -|======================= -| Setting | Required | Description -| `type` | yes | Indicates the realm type. Must be set to `active_directory`. -| `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`. -| `domain_name` | yes | Specifies the domain name of the Active Directory. {security} - uses the domain name to derive the LDAP URL and `user_search_dn` - if those fields are not specified. -| `url` | no/yes | Specifies an LDAP URL of the form `ldap[s]://:`. - {security} attempts to authenticate against this URL. If the - URL is not specified, it is derived from the `domain_name`, - assuming an unencrypted connection to port 389. For example, - `ldap://:389`. This settings is required when - connecting using SSL/TLS or via a custom port. -| `bind_dn` | no | The DN of the user that is used to bind to Active Directory - and perform searches. Due to its potential security - impact, `bind_dn` is not exposed via the - {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API]. -| `bind_password` | no | The password for the user that is used to bind to - Active Directory. Due to its potential security impact, - `bind_password` is not exposed via the - {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API]. - *Deprecated.* Use `secure_bind_password` instead. -| `secure_bind_password` | no | ({ref}/secure-settings.html[Secure]) - The password for the user that is used to bind to Active Directory. -| `load_balance.type` | no | The behavior to use when there are multiple LDAP URLs defined. - For supported values see <>. -| `load_balance.cache_ttl` | no | When using `dns_failover` or `dns_round_robin` as the load - balancing type, this setting controls the amount of time to - cache DNS lookups. Defaults to `1h`. -| `user_search.base_dn` | no | Specifies the context to search for the user. Defaults to the - root of the Active Directory domain. -| `user_search.scope` | no | Specifies whether the user search should be `sub_tree` (default), - `one_level`, or `base`. `sub_tree` searches all objects contained - under `base_dn`. `one_level` only searches users directly - contained within the `base_dn`. `base` specifies that the - `base_dn` is a user object and that it is the only user considered. -| `user_search.filter` | no | Specifies a filter to use to lookup a user given a username. - The default filter looks up `user` objects with either - `sAMAccountName` or `userPrincipalName`. If specified, this - must be a valid LDAP user search filter, for example - `(&(objectClass=user)(sAMAccountName={0}))`. For more - information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. -| `user_search.upn_filter` | no | Specifies a filter to use to lookup a user given a user principal name. - The default filter looks up `user` objects with - a matching `userPrincipalName`. If specified, this - must be a valid LDAP user search filter, for example - `(&(objectClass=user)(userPrincipalName={1}))`. `{1}` is - the full user principal name provided by the user. For more - information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. -| `user_search.down_level_filter` | no | Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). - The default filter looks up `user` objects with a matching - `sAMAccountName` in the domain provided. If specified, this - must be a valid LDAP user search filter, for example - `(&(objectClass=user)(sAMAccountName={0}))`. For more - information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. -| `user_search.pool.enabled` | no | Enables or disables connection pooling for user search. When - disabled a new connection is created for every search. The - default is `true` when `bind_dn` is provided. -| `user_search.pool.size` | no | Specifies the maximum number of connections to Active Directory - server to allow in the connection pool. Defaults to `20`. -| `user_search.pool.initial_size` | no | The initial number of connections to create to Active Directory - server on startup. Defaults to `0`. Values greater than `0` - could cause startup failures if the LDAP server is down. -| `user_search.pool.health_check.enabled` | no | Enables or disables a health check on Active Directory connections in - the connection pool. Connections are checked in the - background at the specified interval. Defaults to `true`. -| `user_search.pool.health_check.dn` | no | Specifies the distinguished name to retrieve as part of - the health check. Defaults to the value of `bind_dn` if present, and if - not falls back to `user_search.base_dn`. -| `user_search.pool.health_check.interval` | no | How often to perform background checks of connections in - the pool. Defaults to `60s`. -| `group_search.base_dn` | no | Specifies the context to search for groups in which the user - has membership. Defaults to 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`. `sub_tree` searches all objects contained - under `base_dn`. `one_level` searches for groups directly - contained within the `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 | Specifies whether the names of any unmapped Active Directory - groups should be used as role names and assigned to the user. - A group is considered to be _unmapped_ if it is not referenced - in any <> (API based - role-mappings are not considered). - Defaults to `false`. -| `files.role_mapping` | no | Specifies the path and file name of the - <>. - Defaults to `ES_PATH_CONF/x-pack/role_mapping.yml`, - where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) - or `/etc/elasticsearch` (package installations). -| `follow_referrals` | no | Specifies whether {security} should follow referrals returned - by the Active Directory server. Referrals are URLs returned by - the server that are to be used to continue the LDAP operation - (such as `search`). Defaults to `true`. -| `metadata` | no | Specifies the list of additional LDAP attributes that should - be stored in the `metadata` of an authenticated user. -| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the Active Directory - server requires client authentication. `ssl.key` and `ssl.keystore.path` may not be used at the - same time. -| `ssl.key_passphrase` | no | Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. -| `ssl.certificate` | no | Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the key - if the Active Directory server requires client authentication. -| `ssl.certificate_authorities`| no | Specifies the paths to the PEM encoded certificate authority certificates that - should be trusted. `ssl.certificate_authorities` and `ssl.truststore.path` may not be used at - the same time. -| `ssl.keystore.path` | no | The path to the Java Keystore file that contains a private key and certificate. `ssl.key` and - `ssl.keystore.path` may not be used at the same time. -| `ssl.keystore.password` | no | The password to the keystore. -| `ssl.keystore.key_password`| no | The password for the key in the keystore. Defaults to the keystore password. -| `ssl.truststore.path` | no | The path to the Java Keystore file that contains the certificates to trust. - `ssl.certificate_authorities` and `ssl.truststore.path` may not be used at the same time. -| `ssl.truststore.password` | no | The password to the truststore. -| `ssl.verification_mode` | no | Specifies the type of verification to be performed when - connecting to an Active Directory server using `ldaps`. When - set to `full`, 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. Due to their potential security impact, - `ssl` settings are not exposed via the - {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API]. -+ - Values are `none`, `certificate`, and `full`. Defaults to `full`. -+ - See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`] - for an explanation of these values. -| `ssl.supported_protocols` | no | Specifies the supported protocols for TLS/SSL. -| `ssl.cipher_suites` | no | Specifies the cipher suites that should be supported when communicating - with the Active Directory server. -| `cache.ttl` | no | Specifies the time-to-live for cached user entries. A user's - credentials are cached for this period of time. Specify the - time period using the standard Elasticsearch - {ref}/common-options.html#time-units[time units]. - Defaults to `20m`. -| `cache.max_users` | no | Specifies the maximum number of user entries that can be - stored in the cache at one time. Defaults to 100,000. -| `cache.hash_algo` | no | Specifies the hashing algorithm that is used for the - cached user credentials. - See <> for the - possible values. (Expert Setting). -|======================= +See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings]. [[mapping-roles-ad]] ==== Mapping Active Directory Users and Groups to Roles diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 97413ed07bb..139e54467b7 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -441,13 +441,21 @@ table for all possible values. Defaults to `ssha256`. [float] ===== Active Directory realm settings +The `type` setting must be set to `active_directory`. In addition to the +<>, you can specify +the following settings: + `url`:: -A URL in the format `ldap[s]://:`. Defaults to `ldap://:389`. +An LDAP URL of the form `ldap[s]://:`. {security} attempts to +authenticate against this URL. If the URL is not specified, it is derived from +the `domain_name` setting and assumes an unencrypted connection to port 389. +Defaults to `ldap://:389`. This setting is required when connecting +using SSL/TLS or when using a custom port. `load_balance.type`:: The behavior to use when there are multiple LDAP URLs defined. For supported -values see {xpack-ref}/active-directory-realm.html#ad-load-balancing[load balancing and failover types]. -Defaults to `failover`. +values see <>. +Defaults to `failover`. `load_balance.cache_ttl`:: When using `dns_failover` or `dns_round_robin` as the load balancing type, @@ -455,31 +463,34 @@ this setting controls the amount of time to cache DNS lookups. Defaults to `1h`. `domain_name`:: -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. Required. +The domain name of Active Directory. If the the `url` and `user_search_dn` +settings are not specified, the cluster can derive those values from this +setting. Required. `bind_dn`:: -The DN of the user that will be used to bind to Active Directory and perform searches. -Defaults to Empty. +The DN of the user that is used to bind to Active Directory and perform searches. +Defaults to Empty. Due to its potential security impact, `bind_dn` is not +exposed via the <>. `bind_password`:: -The password for the user that will be used to bind to Active Directory. -Defaults to Empty. -*Deprecated.* Use `secure_bind_password` instead. +deprecated[6.3] Use `secure_bind_password` instead. The password for the user +that is used to bind to Active Directory. Defaults to Empty. Due to its +potential security impact, `bind_password` is not exposed via the +<>. `secure_bind_password` (<>):: -The password for the user that will be used to bind to Active Directory. +The password for the user that is used to bind to Active Directory. Defaults to Empty. `unmapped_groups_as_roles`:: -Takes a boolean variable. When this element is set to `true`, the names of any -LDAP groups that are not referenced in a role-mapping _file_ are used as role -names and assigned to the user. Defaults to `false`. +If set to `true`, the names of any unmapped Active Directory groups are used as +role names and assigned to the user. A group is considered _unmapped_ when it +is not referenced in any role-mapping files. API-based role mappings are not +considered. Defaults to `false`. `files.role_mapping`:: The {xpack-ref}/security-files.html[location] for the YAML -role mapping configuration file. Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`. +role mapping configuration file. Defaults to `CONFIG_DIR/role_mapping.yml`. `user_search.base_dn`:: The context to search for a user. Defaults to the root @@ -495,22 +506,27 @@ only user considered. Defaults to `sub_tree`. `user_search.filter`:: Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or -`userPrincipalName`. +`userPrincipalName`. If specified, this must be a valid LDAP user search filter. +For example `(&(objectClass=user)(sAMAccountName={0}))`. For more information, +see +https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.upn_filter`:: Specifies a filter to use to lookup a user given a user principal name. The default filter looks up `user` objects with a matching `userPrincipalName`. If specified, this -must be a valid LDAP user search filter, for example +must be a valid LDAP user search filter. For example, `(&(objectClass=user)(userPrincipalName={1}))`. `{1}` is the full user principal name -provided by the user. +provided by the user. For more information, see +https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.down_level_filter`:: Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up `user` objects with a matching `sAMAccountName` in the domain provided. If specified, this -must be a valid LDAP user search filter, for example -`(&(objectClass=user)(sAMAccountName={0}))`. +must be a valid LDAP user search filter. For example, +`(&(objectClass=user)(sAMAccountName={0}))`. For more information, see +https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. `user_search.pool.enabled`:: Enables or disables connection pooling for user search. When @@ -523,16 +539,18 @@ connection pool. Defaults to `20`. `user_search.pool.initial_size`:: The initial number of connections to create to the Active Directory server on startup. -Defaults to `0`. +Defaults to `0`. If the LDAP server is down, values greater than 0 +could cause startup failures. `user_search.pool.health_check.enabled`:: -Flag to enable or disable a health check on Active Directory connections in the connection +Enables or disables a health check on Active Directory connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to `true`. `user_search.pool.health_check.dn`:: The distinguished name to be retrieved as part of the health check. -Defaults to the value of `bind_dn` if it is a distinguished name. +Defaults to the value of `bind_dn` if that setting is present. Otherwise, it +defaults to the value of the `user_search.base_dn` setting. `user_search.pool.health_check.interval`:: The interval to perform background checks of connections in the pool. @@ -540,7 +558,7 @@ Defaults to `60s`. `group_search.base_dn`:: The context to search for groups in which the user has membership. Defaults -to the root of the Active Directory domain. +to the root of the Active Directory domain. `group_search.scope`:: Specifies whether the group search should be `sub_tree`, `one_level` or @@ -570,13 +588,18 @@ Defaults to `5s` (5 seconds ). `ssl.certificate`:: Path to a PEM encoded file containing the certificate (or certificate chain) -that will be presented to clients when they connect. +that will be presented to clients when they connect. `ssl.certificate_authorities`:: -List of paths to PEM encoded certificate files that should be trusted. +List of paths to PEM encoded certificate files that should be trusted. +`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the +same time. `ssl.key`:: -Path to the PEM encoded file containing the private key. +Path to the PEM encoded file containing the private key, which is used when the +Active Directory server requires client authentication. `ssl.key` and +`ssl.keystore.path` cannot be used at the same time. + `ssl.key_passphrase`:: The passphrase that is used to decrypt the private key. This value is @@ -600,6 +623,7 @@ The password to the keystore. `ssl.keystore.path`:: The path to the Java Keystore file that contains a private key and certificate. +`ssl.key` and `ssl.keystore.path` cannot be used at the same time. `ssl.keystore.type`:: The format of the keystore file. Should be either `jks` to use the Java @@ -613,6 +637,8 @@ The password to the truststore. `ssl.truststore.path`:: The path to the Java Keystore file that contains the certificates to trust. +`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the +same time. `ssl.truststore.type`:: The format of the truststore file. Should be either `jks` to use the Java @@ -627,10 +653,11 @@ See <> for an explanation of these values. `ssl.supported_protocols`:: -Supported protocols with versions. Defaults to the value of +Supported protocols for TLS/SSL (with versions). Defaults to the value of `xpack.ssl.supported_protocols`. -`ssl.cipher_suites`:: +`ssl.cipher_suites`:: Specifies the cipher suites that should be supported when +communicating with the Active Directory server. Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[ Java Cryptography Architecture documentation]. Defaults to the value of `xpack.ssl.cipher_suites`. @@ -646,9 +673,14 @@ Specifies the maximum number of user entries that the cache can contain. Defaults to `100000`. `cache.hash_algo`:: -(Expert Setting) Specifies the hashing algorithm that will be used for +(Expert Setting) Specifies the hashing algorithm that is used for the in-memory cached user credentials (see {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for all possible values). Defaults to `ssha256`. +`follow_referrals`:: +If set to `true` {security} follows referrals returned by the LDAP server. +Referrals are URLs returned by the server that are to be used to continue the +LDAP operation (such as `search`). Defaults to `true`. + [[ref-pki-settings]] [float] ===== PKI realm settings @@ -684,7 +716,7 @@ documentation for more information. This setting cannot be used with `files.role_mapping`:: Specifies the {xpack-ref}/security-files.html[location] of the {xpack-ref}/mapping-roles.html[YAML role mapping configuration file]. -Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`. +Defaults to `CONFIG_DIR/role_mapping.yml`. `cache.ttl`:: Specifies the time-to-live for cached user entries. A user and a hash of its