[DOCS] Removes redundant Active Directory realm settings (#30190)
This commit is contained in:
Lisa Cawley
GitHub
parent
05160e6cd8
commit
e95a7aa6f0
|
|
@ -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]://<server>:<port>`.
|
||||
{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://<domain_name>: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 <<ad-load-balancing>>.
|
||||
| `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 <<mapping-roles-file, role-mapping files>> (API based
|
||||
role-mappings are not considered).
|
||||
Defaults to `false`.
|
||||
| `files.role_mapping` | no | Specifies the path and file name of the
|
||||
<<ldap-role-mapping, YAML role mapping configuration file>>.
|
||||
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 <<cache-hash-algo, Cache hash algorithms>> 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<<ref-realm-settings,settings that are valid for all realms>>, you can specify
|
||||
the following settings:
|
||||
|
||||
`url`::
|
||||
A URL in the format `ldap[s]://<server>:<port>`. Defaults to `ldap://<domain_name>:389`.
|
||||
An LDAP URL of the form `ldap[s]://<server>:<port>`. {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://<domain_name>: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 <<load-balancing,load balancing and failover types>>.
|
||||
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 <<cluster-nodes-info,nodes info API>>.
|
||||
|
||||
`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
|
||||
<<cluster-nodes-info,nodes info API>>.
|
||||
|
||||
`secure_bind_password` (<<secure-settings,Secure>>)::
|
||||
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 <<ssl-tls-settings,`xpack.ssl.verification_mode`>> 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue