Skip to content

Commit

Permalink
[DOCS] Removes redundant LDAP realm settings (#30193)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lcawl
lcawl committed Apr 30, 2018
1 parent eea10f1 commit f92d533
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 258 deletions.
202 changes: 2 additions & 200 deletions x-pack/docs/en/security/authentication/ldap-realm.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,211 +137,13 @@ The `load_balance.type` setting can be used at the realm level to configure how
{security} should interact with multiple LDAP servers. {security} supports both
failover and load balancing modes of operation.

.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 LDAP 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].


[[ldap-settings]]
===== LDAP Realm Settings

.Common LDAP Realm Settings
[cols="4,^3,10"]
|=======================
| Setting | Required | Description
| `type` | yes | Indicates the realm type. Must be set to `ldap`.
| `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`.
| `url` | yes | Specifies one or more LDAP URLs of the form of
`ldap[s]://<server>:<port>`. Multiple URLs can be
defined using a comma separated value or array syntax:
`[ "ldaps://server1:636", "ldaps://server2:636" ]`.
`ldaps` and `ldap` URL protocols cannot be mixed in
the same realm.
| `load_balance.type` | no | The behavior to use when there are multiple LDAP URLs
defined. For supported values see
<<ldap-load-balancing, LDAP load balancing and failover types>>.
| `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_group_attribute` | no | Specifies the attribute to examine on the user for group
membership. The default is `memberOf`. This setting will
be ignored if any `group_search` settings are specified.
| `group_search.base_dn` | no | Specifies a container DN to search for groups in which
the user has membership. When this element is absent,
Security searches for the attribute specified by
`user_group_attribute` set on the user to determine
group membership.
| `group_search.scope` | no | Specifies whether the group search should be
`sub_tree`, `one_level` or `base`. `one_level` only
searches objects directly contained within the
`base_dn`. The default `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.
| `group_search.filter` | no | Specifies a filter to use to lookup a group. If not
set, the realm searches for `group`,
`groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the
attributes `member`, `memberOf`, or `memberUid`. Any instance of
`{0}` in the filter is replaced by the user
attribute defined in `group_search.user_attribute`
| `group_search.user_attribute` | no | Specifies the user attribute that is fetched and
provided as a parameter to the filter. If not set,
the user DN is passed to the filter.
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP 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`.
| `timeout.tcp_connect` | no | Specifies the TCP connect timeout period for establishing an
LDAP connection. An `s` at the end indicates seconds, or `ms`
indicates milliseconds. Defaults to `5s` (5 seconds).
| `timeout.tcp_read` | no | Specifies the TCP read timeout period after establishing an LDAP connection.
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds).
| `timeout.ldap_search` | no | Specifies the LDAP Server enforced timeout period for an LDAP search.
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds).
| `files.role_mapping` | no | Specifies the path and file name for the
<<ldap-role-mapping, YAML role mapping configuration file>>.
Defaults to `ES_HOME/config/x-pack/role_mapping.yml`.
| `follow_referrals` | no | Specifies whether {security} 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). 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 LDAP
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 LDAP 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 a LDAP 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 SSL/TLS.
| `ssl.cipher_suites` | no | Specifies the cipher suites that should be supported when communicating
with the LDAP 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).
|=======================

.User Search Mode Settings
|=======================
| Setting | Required | Description
| `bind_dn` | no | The DN of the user that is used to bind to the LDAP
and perform searches. If not specified, an anonymous
bind is attempted. 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 the
LDAP 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 LDAP directory.
| `user_search.base_dn` | yes | Specifies a container DN to search for users.
| `user_search.scope` | no | The scope of the user search. Valid values are `sub_tree`,
`one_level` or `base`. `one_level` only searches objects
directly contained within the `base_dn`. `sub_tree` searches
all objects contained under `base_dn`. `base` specifies
that the `base_dn` is the user object, and that it is the
only user considered. Defaults to `sub_tree`.
| `user_search.filter` | no | Specifies the filter used to search the directory in attempt to match
an entry with the username provided by the user. Defaults to `(uid={0})`.
`{0}` is substituted with the username provided when searching.
| `user_search.attribute` | no | This setting is deprecated; use `user_search.filter` instead.
Specifies the attribute to match with the username presented
to. Defaults to `uid`.
| `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`.
| `user_search.pool.size` | no | Specifies the maximum number of connections to the LDAP
server to allow in the connection pool. Defaults to `20`.
| `user_search.pool.initial_size` | no | The initial number of connections to create to the LDAP
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 LDAP 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/yes | Specifies the distinguished name to retrieve as part of
the health check. Defaults to the value of `bind_dn`.
This setting is required when `bind_dn` is not configured.
| `user_search.pool.health_check.interval` | no | How often to perform background checks of connections in
the pool. Defaults to `60s`.
|=======================

.User Templates Mode Settings
[cols="4,^3,10"]
|=======================
| Setting | Required | Description
| `user_dn_templates` | yes | Specifies the DN template that replaces the
user name with the string `{0}`. This element
is multivalued, allowing for multiple user
contexts.
|=======================


NOTE: If any settings starting with `user_search` are specified, the
`user_dn_templates` the settings are ignored.

See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].

[[mapping-roles-ldap]]
==== Mapping LDAP Groups to Roles
Expand Down
Loading

0 comments on commit f92d533

Please sign in to comment.