honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Removes redundant Active Directory realm settings (#30190)

This commit is contained in:
Lisa Cawley 2018-04-30 08:52:21 -07:00 committed by GitHub
parent 05160e6cd8
commit e95a7aa6f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 67 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
x-pack/docs/en/security/authentication/active-directory-realm.asciidoc
View File

@ -169,186 +169,14 @@ domain name from the NetBIOS name.
===== Load Balancing and Failover ===== Load Balancing and Failover
The `load_balance.type` setting can be used at the realm level to configure how 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 {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 See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
|=======================
| 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.
|=======================
[[ad-settings]] [[ad-settings]]
===== Active Directory Realm Settings ===== Active Directory Realm Settings
[cols="4,^3,10"] See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings].
|=======================
| 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).
|=======================
[[mapping-roles-ad]] [[mapping-roles-ad]]
==== Mapping Active Directory Users and Groups to Roles ==== Mapping Active Directory Users and Groups to Roles

96
x-pack/docs/en/settings/security-settings.asciidoc
View File

@ -441,13 +441,21 @@ table for all possible values. Defaults to `ssha256`.
[float] [float]
===== Active Directory realm settings ===== 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`:: `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`:: `load_balance.type`::
The behavior to use when there are multiple LDAP URLs defined. For supported 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]. values see <<load-balancing,load balancing and failover types>>.
Defaults to `failover`. Defaults to `failover`.
`load_balance.cache_ttl`:: `load_balance.cache_ttl`::
When using `dns_failover` or `dns_round_robin` as the load balancing type, 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`. to `1h`.
`domain_name`:: `domain_name`::
The domain name of Active Directory. The cluster can derive the URL and The domain name of Active Directory. If the the `url` and `user_search_dn`
`user_search_dn` fields from values in this element if those fields are not settings are not specified, the cluster can derive those values from this
otherwise specified. Required. setting. Required.
`bind_dn`:: `bind_dn`::
The DN of the user that will be used to bind to Active Directory and perform searches. The DN of the user that is used to bind to Active Directory and perform searches.
Defaults to Empty. Defaults to Empty. Due to its potential security impact, `bind_dn` is not
exposed via the <<cluster-nodes-info,nodes info API>>.
`bind_password`:: `bind_password`::
The password for the user that will be used to bind to Active Directory. deprecated[6.3] Use `secure_bind_password` instead. The password for the user
Defaults to Empty. that is used to bind to Active Directory. Defaults to Empty. Due to its
*Deprecated.* Use `secure_bind_password` instead. potential security impact, `bind_password` is not exposed via the
<<cluster-nodes-info,nodes info API>>.
`secure_bind_password` (<<secure-settings,Secure>>):: `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. Defaults to Empty.
`unmapped_groups_as_roles`:: `unmapped_groups_as_roles`::
Takes a boolean variable. When this element is set to `true`, the names of any If set to `true`, the names of any unmapped Active Directory groups are used as
LDAP groups that are not referenced in a role-mapping _file_ are used as role role names and assigned to the user. A group is considered _unmapped_ when it
names and assigned to the user. Defaults to `false`. is not referenced in any role-mapping files. API-based role mappings are not
considered. Defaults to `false`.
`files.role_mapping`:: `files.role_mapping`::
The {xpack-ref}/security-files.html[location] for the YAML 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`:: `user_search.base_dn`::
The context to search for a user. Defaults to the root 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`:: `user_search.filter`::
Specifies a filter to use to lookup a user given a username. The default Specifies a filter to use to lookup a user given a username. The default
filter looks up `user` objects with either `sAMAccountName` or 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`:: `user_search.upn_filter`::
Specifies a filter to use to lookup a user given a user principal name. Specifies a filter to use to lookup a user given a user principal name.
The default filter looks up `user` objects with The default filter looks up `user` objects with
a matching `userPrincipalName`. If specified, this 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 `(&(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`:: `user_search.down_level_filter`::
Specifies a filter to use to lookup a user given a down level logon name 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 (DOMAIN\user). The default filter looks up `user` objects with a matching
`sAMAccountName` in the domain provided. If specified, this `sAMAccountName` in the domain provided. 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)(sAMAccountName={0}))`. `(&(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`:: `user_search.pool.enabled`::
Enables or disables connection pooling for user search. When Enables or disables connection pooling for user search. When
@ -523,16 +539,18 @@ connection pool. Defaults to `20`.
`user_search.pool.initial_size`:: `user_search.pool.initial_size`::
The initial number of connections to create to the Active Directory server on startup. 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`:: `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. pool. Connections are checked in the background at the specified interval.
Defaults to `true`. Defaults to `true`.
`user_search.pool.health_check.dn`:: `user_search.pool.health_check.dn`::
The distinguished name to be retrieved as part of the health check. 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`:: `user_search.pool.health_check.interval`::
The interval to perform background checks of connections in the pool. The interval to perform background checks of connections in the pool.
@ -540,7 +558,7 @@ Defaults to `60s`.
`group_search.base_dn`:: `group_search.base_dn`::
The context to search for groups in which the user has membership. Defaults 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`:: `group_search.scope`::
Specifies whether the group search should be `sub_tree`, `one_level` or Specifies whether the group search should be `sub_tree`, `one_level` or
@ -570,13 +588,18 @@ Defaults to `5s` (5 seconds ).
`ssl.certificate`:: `ssl.certificate`::
Path to a PEM encoded file containing the certificate (or certificate chain) 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`:: `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`:: `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`:: `ssl.key_passphrase`::
The passphrase that is used to decrypt the private key. This value is 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`:: `ssl.keystore.path`::
The path to the Java Keystore file that contains a private key and certificate. 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`:: `ssl.keystore.type`::
The format of the keystore file. Should be either `jks` to use the Java 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`:: `ssl.truststore.path`::
The path to the Java Keystore file that contains the certificates to trust. 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`:: `ssl.truststore.type`::
The format of the truststore file. Should be either `jks` to use the Java 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. these values.
`ssl.supported_protocols`:: `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`. `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[ 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 Java Cryptography Architecture documentation]. Defaults to the value of
`xpack.ssl.cipher_suites`. `xpack.ssl.cipher_suites`.
@ -646,9 +673,14 @@ Specifies the maximum number of user entries that the cache can contain.
Defaults to `100000`. Defaults to `100000`.
`cache.hash_algo`:: `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`. 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]] [[ref-pki-settings]]
[float] [float]
===== PKI realm settings ===== PKI realm settings
@ -684,7 +716,7 @@ documentation for more information. This setting cannot be used with
`files.role_mapping`:: `files.role_mapping`::
Specifies the {xpack-ref}/security-files.html[location] of the Specifies the {xpack-ref}/security-files.html[location] of the
{xpack-ref}/mapping-roles.html[YAML role mapping configuration file]. {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`:: `cache.ttl`::
Specifies the time-to-live for cached user entries. A user and a hash of its Specifies the time-to-live for cached user entries. A user and a hash of its