Skip to content

Commit 39f73c6

Browse files
lcawllcawl
committed
[DOCS] Removes redundant LDAP realm settings (#30193)
1 parent b40b9a3 commit 39f73c6

File tree

2 files changed

+110
-258
lines changed

2 files changed

+110
-258
lines changed

‎x-pack/docs/en/security/authentication/ldap-realm.asciidoc‎

Lines changed: 2 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -137,211 +137,13 @@ The `load_balance.type` setting can be used at the realm level to configure how
137137
{security} should interact with multiple LDAP servers. {security} supports both
138138
failover and load balancing modes of operation.
139139

140-
.Load Balancing and Failover Types
141-
|=======================
142-
| Type | | | Description
143-
| `failover` | | | The URLs specified are used in the order that they are specified.
144-
The first server that can be connected to will be used for all
145-
subsequent connections. If a connection to that server fails then
146-
the next server that a connection can be established to will be
147-
used for subsequent connections.
148-
| `dns_failover` | | | In this mode of operation, only a single URL may be specified.
149-
This URL must contain a DNS name. The system will be queried for
150-
all IP addresses that correspond to this DNS name. Connections to
151-
the LDAP server will always be tried in the order in which they
152-
were retrieved. This differs from `failover` in that there is no
153-
reordering of the list and if a server has failed at the beginning
154-
of the list, it will still be tried for each subsequent connection.
155-
| `round_robin` | | | Connections will continuously iterate through the list of provided
156-
URLs. If a server is unavailable, iterating through the list of
157-
URLs will continue until a successful connection is made.
158-
| `dns_round_robin` | | | In this mode of operation, only a single URL may be specified. This
159-
URL must contain a DNS name. The system will be queried for all IP
160-
addresses that correspond to this DNS name. Connections will
161-
continuously iterate through the list of addresses. If a server is
162-
unavailable, iterating through the list of URLs will continue until
163-
a successful connection is made.
164-
|=======================
140+
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
165141

166142

167143
[[ldap-settings]]
168144
===== LDAP Realm Settings
169145

170-
.Common LDAP Realm Settings
171-
[cols="4,^3,10"]
172-
|=======================
173-
| Setting | Required | Description
174-
| `type` | yes | Indicates the realm type. Must be set to `ldap`.
175-
| `order` | no | Indicates the priority of this realm within the realm
176-
chain. Realms with a lower order are consulted first.
177-
Although not required, we recommend explicitly
178-
setting this value when you configure multiple realms.
179-
Defaults to `Integer.MAX_VALUE`.
180-
| `enabled` | no | Indicates whether this realm is enabled or disabled.
181-
Enables you to disable a realm without removing its
182-
configuration. Defaults to `true`.
183-
| `url` | yes | Specifies one or more LDAP URLs of the form of
184-
`ldap[s]://<server>:<port>`. Multiple URLs can be
185-
defined using a comma separated value or array syntax:
186-
`[ "ldaps://server1:636", "ldaps://server2:636" ]`.
187-
`ldaps` and `ldap` URL protocols cannot be mixed in
188-
the same realm.
189-
| `load_balance.type` | no | The behavior to use when there are multiple LDAP URLs
190-
defined. For supported values see
191-
<<ldap-load-balancing, LDAP load balancing and failover types>>.
192-
| `load_balance.cache_ttl` | no | When using `dns_failover` or `dns_round_robin` as the
193-
load balancing type, this setting controls the amount of time
194-
to cache DNS lookups. Defaults to `1h`.
195-
| `user_group_attribute` | no | Specifies the attribute to examine on the user for group
196-
membership. The default is `memberOf`. This setting will
197-
be ignored if any `group_search` settings are specified.
198-
| `group_search.base_dn` | no | Specifies a container DN to search for groups in which
199-
the user has membership. When this element is absent,
200-
Security searches for the attribute specified by
201-
`user_group_attribute` set on the user to determine
202-
group membership.
203-
| `group_search.scope` | no | Specifies whether the group search should be
204-
`sub_tree`, `one_level` or `base`. `one_level` only
205-
searches objects directly contained within the
206-
`base_dn`. The default `sub_tree` searches all objects
207-
contained under `base_dn`. `base` specifies that the
208-
`base_dn` is a group object, and that it is the only
209-
group considered.
210-
| `group_search.filter` | no | Specifies a filter to use to lookup a group. If not
211-
set, the realm searches for `group`,
212-
`groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the
213-
attributes `member`, `memberOf`, or `memberUid`. Any instance of
214-
`{0}` in the filter is replaced by the user
215-
attribute defined in `group_search.user_attribute`
216-
| `group_search.user_attribute` | no | Specifies the user attribute that is fetched and
217-
provided as a parameter to the filter. If not set,
218-
the user DN is passed to the filter.
219-
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP groups
220-
should be used as role names and assigned to the user.
221-
A group is considered to be _unmapped_ if it is not referenced
222-
in any <<mapping-roles-file, role-mapping files>> (API based
223-
role-mappings are not considered).
224-
Defaults to `false`.
225-
| `timeout.tcp_connect` | no | Specifies the TCP connect timeout period for establishing an
226-
LDAP connection. An `s` at the end indicates seconds, or `ms`
227-
indicates milliseconds. Defaults to `5s` (5 seconds).
228-
| `timeout.tcp_read` | no | Specifies the TCP read timeout period after establishing an LDAP connection.
229-
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
230-
Defaults to `5s` (5 seconds).
231-
| `timeout.ldap_search` | no | Specifies the LDAP Server enforced timeout period for an LDAP search.
232-
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
233-
Defaults to `5s` (5 seconds).
234-
| `files.role_mapping` | no | Specifies the path and file name for the
235-
<<ldap-role-mapping, YAML role mapping configuration file>>.
236-
Defaults to `ES_HOME/config/x-pack/role_mapping.yml`.
237-
| `follow_referrals` | no | Specifies whether {security} should follow referrals
238-
returned by the LDAP server. Referrals are URLs returned by
239-
the server that are to be used to continue the LDAP operation
240-
(e.g. search). Defaults to `true`.
241-
| `metadata` | no | Specifies the list of additional LDAP attributes that should
242-
be stored in the `metadata` of an authenticated user.
243-
| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the LDAP
244-
server requires client authentication. `ssl.key` and `ssl.keystore.path`
245-
may not be used at the same time.
246-
| `ssl.key_passphrase` | no | Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.
247-
| `ssl.certificate` | no | Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the
248-
key if the LDAP server requires client authentication.
249-
| `ssl.certificate_authorities` | no | Specifies the paths to the PEM encoded certificate authority certificates that
250-
should be trusted. `ssl.certificate_authorities` and `ssl.truststore.path` may not be used
251-
at the same time.
252-
| `ssl.keystore.path` | no | The path to the Java Keystore file that contains a private key and certificate. `ssl.key` and
253-
`ssl.keystore.path` may not be used at the same time.
254-
| `ssl.keystore.password` | no | The password to the keystore.
255-
| `ssl.keystore.key_password` | no | The password for the key in the keystore. Defaults to the keystore password.
256-
| `ssl.truststore.path` | no | The path to the Java Keystore file that contains the certificates to trust.
257-
`ssl.certificate_authorities` and `ssl.truststore.path` may not be used at the same time.
258-
| `ssl.truststore.password` | no | The password to the truststore.
259-
| `ssl.verification_mode` | no | Specifies the type of verification to be performed when
260-
connecting to a LDAP server using `ldaps`. When
261-
set to `full`, the hostname or IP address used in the `url`
262-
must match one of the names in the certificate or the
263-
connection will not be allowed. Due to their potential security impact,
264-
`ssl` settings are not exposed via the
265-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
266-
Values are `none`, `certificate`, and `full`. Defaults to `full`.
267-
See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
268-
for an explanation of these values.
269-
| `ssl.supported_protocols` | no | Specifies the supported protocols for SSL/TLS.
270-
| `ssl.cipher_suites` | no | Specifies the cipher suites that should be supported when communicating
271-
with the LDAP server.
272-
| `cache.ttl` | no | Specifies the time-to-live for cached user entries. A
273-
user's credentials are cached for this period of time.
274-
Specify the time period using the standard Elasticsearch
275-
{ref}/common-options.html#time-units[time units].
276-
Defaults to `20m`.
277-
| `cache.max_users` | no | Specifies the maximum number of user entries that can be
278-
stored in the cache at one time. Defaults to 100,000.
279-
| `cache.hash_algo` | no | Specifies the hashing algorithm that is used for the
280-
cached user credentials. See
281-
<<cache-hash-algo, Cache hash algorithms>> for the possible
282-
values. (Expert Setting).
283-
|=======================
284-
285-
.User Search Mode Settings
286-
|=======================
287-
| Setting | Required | Description
288-
| `bind_dn` | no | The DN of the user that is used to bind to the LDAP
289-
and perform searches. If not specified, an anonymous
290-
bind is attempted. Due to its potential security
291-
impact, `bind_dn` is not exposed via the
292-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
293-
| `bind_password` | no | The password for the user that is used to bind to the
294-
LDAP directory. Due to its potential security impact,
295-
`bind_password` is not exposed via the
296-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
297-
*Deprecated.* Use `secure_bind_password` instead.
298-
| `secure_bind_password` | no | ({ref}/secure-settings.html[Secure])
299-
The password for the user that is used to bind to LDAP directory.
300-
| `user_search.base_dn` | yes | Specifies a container DN to search for users.
301-
| `user_search.scope` | no | The scope of the user search. Valid values are `sub_tree`,
302-
`one_level` or `base`. `one_level` only searches objects
303-
directly contained within the `base_dn`. `sub_tree` searches
304-
all objects contained under `base_dn`. `base` specifies
305-
that the `base_dn` is the user object, and that it is the
306-
only user considered. Defaults to `sub_tree`.
307-
| `user_search.filter` | no | Specifies the filter used to search the directory in attempt to match
308-
an entry with the username provided by the user. Defaults to `(uid={0})`.
309-
`{0}` is substituted with the username provided when searching.
310-
| `user_search.attribute` | no | This setting is deprecated; use `user_search.filter` instead.
311-
Specifies the attribute to match with the username presented
312-
to. Defaults to `uid`.
313-
| `user_search.pool.enabled` | no | Enables or disables connection pooling for user search. When
314-
disabled a new connection is created for every search. The
315-
default is `true`.
316-
| `user_search.pool.size` | no | Specifies the maximum number of connections to the LDAP
317-
server to allow in the connection pool. Defaults to `20`.
318-
| `user_search.pool.initial_size` | no | The initial number of connections to create to the LDAP
319-
server on startup. Defaults to `0`. Values greater than `0`
320-
could cause startup failures if the LDAP server is down.
321-
| `user_search.pool.health_check.enabled` | no | Enables or disables a health check on LDAP connections in
322-
the connection pool. Connections are checked in the
323-
background at the specified interval. Defaults to `true`.
324-
| `user_search.pool.health_check.dn` | no/yes | Specifies the distinguished name to retrieve as part of
325-
the health check. Defaults to the value of `bind_dn`.
326-
This setting is required when `bind_dn` is not configured.
327-
| `user_search.pool.health_check.interval` | no | How often to perform background checks of connections in
328-
the pool. Defaults to `60s`.
329-
|=======================
330-
331-
.User Templates Mode Settings
332-
[cols="4,^3,10"]
333-
|=======================
334-
| Setting | Required | Description
335-
| `user_dn_templates` | yes | Specifies the DN template that replaces the
336-
user name with the string `{0}`. This element
337-
is multivalued, allowing for multiple user
338-
contexts.
339-
|=======================
340-
341-
342-
NOTE: If any settings starting with `user_search` are specified, the
343-
`user_dn_templates` the settings are ignored.
344-
146+
See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].
345147

346148
[[mapping-roles-ldap]]
347149
==== Mapping LDAP Groups to Roles

0 commit comments

Comments
 (0)