Skip to content

Commit 12e131e

Browse files
lcawllcawl
committed
[DOCS] Removes redundant Active Directory realm settings (#30190)
1 parent f92d533 commit 12e131e

File tree

2 files changed

+67
-207
lines changed

2 files changed

+67
-207
lines changed

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

+3-175
Original file line numberDiff line numberDiff line change
@@ -169,186 +169,14 @@ domain name from the NetBIOS name.
169169
===== Load Balancing and Failover
170170
The `load_balance.type` setting can be used at the realm level to configure how
171171
{security} should interact with multiple Active Directory servers. Two modes of
172-
operation are supported: failover and load balancing
172+
operation are supported: failover and load balancing.
173173

174-
.Load Balancing and Failover Types
175-
|=======================
176-
| Type | | | Description
177-
| `failover` | | | The URLs specified are used in the order that they are
178-
specified. The first server that can be connected to will
179-
be used for all subsequent connections. If a connection to
180-
that server fails then the next server that a connection
181-
can be established to will be used for subsequent connections.
182-
| `dns_failover` | | | In this mode of operation, only a single URL may be specified.
183-
This URL must contain a DNS name. The system will be queried
184-
for all IP addresses that correspond to this DNS name.
185-
Connections to the Active Directory server will always be
186-
tried in the order in which they were retrieved. This differs
187-
from `failover` in that there is no reordering of the list
188-
and if a server has failed at the beginning of the list, it
189-
will still be tried for each subsequent connection.
190-
| `round_robin` | | | Connections will continuously iterate through the list of
191-
provided URLs. If a server is unavailable, iterating through
192-
the list of URLs will continue until a successful connection
193-
is made.
194-
| `dns_round_robin` | | | In this mode of operation, only a single URL may be specified.
195-
This URL must contain a DNS name. The system will be queried
196-
for all IP addresses that correspond to this DNS name.
197-
Connections will continuously iterate through the list of
198-
addresses. If a server is unavailable, iterating through the
199-
list of URLs will continue until a successful connection is
200-
made.
201-
|=======================
174+
See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings].
202175

203176
[[ad-settings]]
204177
===== Active Directory Realm Settings
205178

206-
[cols="4,^3,10"]
207-
|=======================
208-
| Setting | Required | Description
209-
| `type` | yes | Indicates the realm type. Must be set to `active_directory`.
210-
| `order` | no | Indicates the priority of this realm within the realm chain.
211-
Realms with a lower order are consulted first. Although not
212-
required, we recommend explicitly setting this value when
213-
you configure multiple realms. Defaults to `Integer.MAX_VALUE`.
214-
| `enabled` | no | Indicates whether this realm is enabled or disabled. Enables
215-
you to disable a realm without removing its configuration.
216-
Defaults to `true`.
217-
| `domain_name` | yes | Specifies the domain name of the Active Directory. {security}
218-
uses the domain name to derive the LDAP URL and `user_search_dn`
219-
if those fields are not specified.
220-
| `url` | no/yes | Specifies an LDAP URL of the form `ldap[s]://<server>:<port>`.
221-
{security} attempts to authenticate against this URL. If the
222-
URL is not specified, it is derived from the `domain_name`,
223-
assuming an unencrypted connection to port 389. For example,
224-
`ldap://<domain_name>:389`. This settings is required when
225-
connecting using SSL/TLS or via a custom port.
226-
| `bind_dn` | no | The DN of the user that is used to bind to Active Directory
227-
and perform searches. Due to its potential security
228-
impact, `bind_dn` is not exposed via the
229-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
230-
| `bind_password` | no | The password for the user that is used to bind to
231-
Active Directory. Due to its potential security impact,
232-
`bind_password` is not exposed via the
233-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
234-
*Deprecated.* Use `secure_bind_password` instead.
235-
| `secure_bind_password` | no | ({ref}/secure-settings.html[Secure])
236-
The password for the user that is used to bind to Active Directory.
237-
| `load_balance.type` | no | The behavior to use when there are multiple LDAP URLs defined.
238-
For supported values see <<ad-load-balancing>>.
239-
| `load_balance.cache_ttl` | no | When using `dns_failover` or `dns_round_robin` as the load
240-
balancing type, this setting controls the amount of time to
241-
cache DNS lookups. Defaults to `1h`.
242-
| `user_search.base_dn` | no | Specifies the context to search for the user. Defaults to the
243-
root of the Active Directory domain.
244-
| `user_search.scope` | no | Specifies whether the user search should be `sub_tree` (default),
245-
`one_level`, or `base`. `sub_tree` searches all objects contained
246-
under `base_dn`. `one_level` only searches users directly
247-
contained within the `base_dn`. `base` specifies that the
248-
`base_dn` is a user object and that it is the only user considered.
249-
| `user_search.filter` | no | Specifies a filter to use to lookup a user given a username.
250-
The default filter looks up `user` objects with either
251-
`sAMAccountName` or `userPrincipalName`. If specified, this
252-
must be a valid LDAP user search filter, for example
253-
`(&(objectClass=user)(sAMAccountName={0}))`. For more
254-
information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].
255-
| `user_search.upn_filter` | no | Specifies a filter to use to lookup a user given a user principal name.
256-
The default filter looks up `user` objects with
257-
a matching `userPrincipalName`. If specified, this
258-
must be a valid LDAP user search filter, for example
259-
`(&(objectClass=user)(userPrincipalName={1}))`. `{1}` is
260-
the full user principal name provided by the user. For more
261-
information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].
262-
| `user_search.down_level_filter` | no | Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user).
263-
The default filter looks up `user` objects with a matching
264-
`sAMAccountName` in the domain provided. If specified, this
265-
must be a valid LDAP user search filter, for example
266-
`(&(objectClass=user)(sAMAccountName={0}))`. For more
267-
information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].
268-
| `user_search.pool.enabled` | no | Enables or disables connection pooling for user search. When
269-
disabled a new connection is created for every search. The
270-
default is `true` when `bind_dn` is provided.
271-
| `user_search.pool.size` | no | Specifies the maximum number of connections to Active Directory
272-
server to allow in the connection pool. Defaults to `20`.
273-
| `user_search.pool.initial_size` | no | The initial number of connections to create to Active Directory
274-
server on startup. Defaults to `0`. Values greater than `0`
275-
could cause startup failures if the LDAP server is down.
276-
| `user_search.pool.health_check.enabled` | no | Enables or disables a health check on Active Directory connections in
277-
the connection pool. Connections are checked in the
278-
background at the specified interval. Defaults to `true`.
279-
| `user_search.pool.health_check.dn` | no | Specifies the distinguished name to retrieve as part of
280-
the health check. Defaults to the value of `bind_dn` if present, and if
281-
not falls back to `user_search.base_dn`.
282-
| `user_search.pool.health_check.interval` | no | How often to perform background checks of connections in
283-
the pool. Defaults to `60s`.
284-
| `group_search.base_dn` | no | Specifies the context to search for groups in which the user
285-
has membership. Defaults to the root of the Active Directory
286-
domain.
287-
| `group_search.scope` | no | Specifies whether the group search should be `sub_tree` (default),
288-
`one_level` or `base`. `sub_tree` searches all objects contained
289-
under `base_dn`. `one_level` searches for groups directly
290-
contained within the `base_dn`. `base` specifies that the
291-
`base_dn` is a group object and that it is the only group considered.
292-
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped Active Directory
293-
groups should be used as role names and assigned to the user.
294-
A group is considered to be _unmapped_ if it is not referenced
295-
in any <<mapping-roles-file, role-mapping files>> (API based
296-
role-mappings are not considered).
297-
Defaults to `false`.
298-
| `files.role_mapping` | no | Specifies the path and file name of the
299-
<<ldap-role-mapping, YAML role mapping configuration file>>.
300-
Defaults to `ES_PATH_CONF/x-pack/role_mapping.yml`,
301-
where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations)
302-
or `/etc/elasticsearch` (package installations).
303-
| `follow_referrals` | no | Specifies whether {security} should follow referrals returned
304-
by the Active Directory server. Referrals are URLs returned by
305-
the server that are to be used to continue the LDAP operation
306-
(such as `search`). Defaults to `true`.
307-
| `metadata` | no | Specifies the list of additional LDAP attributes that should
308-
be stored in the `metadata` of an authenticated user.
309-
| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the Active Directory
310-
server requires client authentication. `ssl.key` and `ssl.keystore.path` may not be used at the
311-
same time.
312-
| `ssl.key_passphrase` | no | Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.
313-
| `ssl.certificate` | no | Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the key
314-
if the Active Directory server requires client authentication.
315-
| `ssl.certificate_authorities`| no | Specifies the paths to the PEM encoded certificate authority certificates that
316-
should be trusted. `ssl.certificate_authorities` and `ssl.truststore.path` may not be used at
317-
the same time.
318-
| `ssl.keystore.path` | no | The path to the Java Keystore file that contains a private key and certificate. `ssl.key` and
319-
`ssl.keystore.path` may not be used at the same time.
320-
| `ssl.keystore.password` | no | The password to the keystore.
321-
| `ssl.keystore.key_password`| no | The password for the key in the keystore. Defaults to the keystore password.
322-
| `ssl.truststore.path` | no | The path to the Java Keystore file that contains the certificates to trust.
323-
`ssl.certificate_authorities` and `ssl.truststore.path` may not be used at the same time.
324-
| `ssl.truststore.password` | no | The password to the truststore.
325-
| `ssl.verification_mode` | no | Specifies the type of verification to be performed when
326-
connecting to an Active Directory server using `ldaps`. When
327-
set to `full`, the hostname or IP address used in the `url`
328-
must match one of the names in the certificate or the
329-
connection will not be allowed. Due to their potential security impact,
330-
`ssl` settings are not exposed via the
331-
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
332-
+
333-
Values are `none`, `certificate`, and `full`. Defaults to `full`.
334-
+
335-
See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
336-
for an explanation of these values.
337-
| `ssl.supported_protocols` | no | Specifies the supported protocols for TLS/SSL.
338-
| `ssl.cipher_suites` | no | Specifies the cipher suites that should be supported when communicating
339-
with the Active Directory server.
340-
| `cache.ttl` | no | Specifies the time-to-live for cached user entries. A user's
341-
credentials are cached for this period of time. Specify the
342-
time period using the standard Elasticsearch
343-
{ref}/common-options.html#time-units[time units].
344-
Defaults to `20m`.
345-
| `cache.max_users` | no | Specifies the maximum number of user entries that can be
346-
stored in the cache at one time. Defaults to 100,000.
347-
| `cache.hash_algo` | no | Specifies the hashing algorithm that is used for the
348-
cached user credentials.
349-
See <<cache-hash-algo, Cache hash algorithms>> for the
350-
possible values. (Expert Setting).
351-
|=======================
179+
See {ref}/security-settings.html#ref-ad-settings[Active Directory Realm Settings].
352180

353181
[[mapping-roles-ad]]
354182
==== Mapping Active Directory Users and Groups to Roles

0 commit comments

Comments
 (0)