Update LDAP configuration

  • PUT /platform/configuration/security/realms/ldap/{realm_id}
Auth

Updates an existing LDAP configuration.

Path parameters

realm_id string required

The Elasticsearch Security realm identifier.

Query parameters

version string

When specified, checks for conflicts against the version stored in the persistent store (returned in 'x-cloud-resource-version' of the GET request)

Request body

The LDAP configuration

id string required

The identifier for the security realm

name string required

The friendly name of the security realm

urls string[] required

The LDAP URLs used to authenticate against, in the format ldap[s]://server:port. Note that ldap and ldaps protocols cannot be mixed together.

bind_anonymously boolean required

When true, bindDb credentials are ignored

bind_type enum required

The type of user binding to apply

Values: user_search user_templates

The group search configuration for the Elasticsearch security LDAP realm.

base_dn string

Specifies a container DN to search for groups in which the user has membership

scope enum

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.

Values: sub_tree one_level base
filter string

Specifies a filter to search for a group. When unspecified, the security 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 user_attribute.

user_attribute string

Specifies the user attribute that is fetched and provided as a parameter to the filter. When unspecified, the user DN is passed to the filter.

The user search configuration for the Elasticsearch security LDAP realm.

base_dn string

Specifies a container DN to search for users

scope enum

The scope of the user search. Valid values are sub_tree, one_level, or base. one_level only searches objects directly contained in the base_dn. sub_tree searches all objects contained in base_dn. base specifies that the base_dn is the user object, and that it is the only user considered. Defaults to sub_tree.

Values: sub_tree one_level base
filter string

Specifies the filter to search the directory and match an entry with the username provided by the user. Defaults to (uid={0}). {0} is substituted with the username provided when searching.

user_dn_templates string[]

The distinguished name template that replaces the user name with the string {0}. Only used when bind_type is set to 'user_templates'.

bind_dn string

The distinguished name of the user that is used to bind to the LDAP and perform searches. Only used when bind_type is set to 'user_search'.

bind_password string

The user password that is used to bind to the LDAP server. Only used when bind_type is set to 'user_search'.

user_group_attribute string

Specifies the attribute to examine on the user for group membership. If any 'group_search' settings are specified, this setting is ignored. Defaults to 'memberOf'.

load_balance object

The load balancing configuration for the Elasticsearch security LDAP realm.

type enum

The behavior to use when there are multiple LDAP URLs defined

Values: failover dns_failover round_robin dns_round_robin
cache_ttl string

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.

certificate_url string

The SSL trusted CA certificate bundle URL. The bundle should be a zip file containing a single keystore file 'keystore.ks' in the directory '/ldap/:id/truststore', where :id is the value of the [id] field.

certificate_url_truststore_password string

The password to the certificate bundle URL truststore

certificate_url_truststore_type enum

The format of the truststore file. Should be jks to use the Java Keystore format or PKCS12 to use PKCS#12 files. The default is jks.

Values: jks PKCS12
role_mappings object

The role mapping ruleset for the Elasticsearch security LDAP realm.

default_roles string[] required

The default roles applied to all users

rules object[] required

The role mapping rules to evaluate

type enum required

The type of role mapping rule

Values: user_dn group_dn
roles string[] required

The roles that are applied when the mapping rule is successfully evaluated

value string required

The value to match when evaluating this rule

enabled boolean

When true, enables the security realm

order integer · format: int32

The order that the security realm is evaluated

override_yaml string

Advanced configuration options in YAML format. Any settings defined here will override any configuration set via the API. Note that all keys should omit the 'xpack.security.authc.realms.ldap.{realm_id}' prefix. For example, when the realm ID is set to 'ldap1', the advanced configuration 'xpack.security.authc.realms.ldap.ldap1.ssl.verification_mode: full' should be added as 'ssl.verification_mode: full'.

Responses

The LDAP configuration was successfully updated

application/json

Response Type: object

Response headers

x-cloud-resource-version string

The resource version, which is used to avoid update conflicts with concurrent operations

x-cloud-resource-created string

The date-time when the resource was created (ISO format relative to UTC)

x-cloud-resource-last-modified string

The date-time when the resource was last modified (ISO format relative to UTC)

  • The realm id is already in use. (code: security_realm.id_conflict)
  • The selected id is not valid. (code: security_realm.invalid_id)
  • Order must be greater than zero. (code: security_realm.invalid_order)
  • Invalid Elasticsearch Security realm type. (code: security_realm.invalid_type)
  • The realm order is already in use. (code: security_realm.order_conflict)
  • Advanced YAML format is invalid. (code: security_realm.invalid_yaml)
  • The url format is invalid. (code: security_realm.invalid_url)
  • Invalid LDAP URL. (code: security_realm.ldap.invalid_url)
  • Invalid certificate bundle URL. (code: security_realm.invalid_bundle_url)
application/json
errors object[] required

A list of errors that occurred in the failing request

code string required

A structured code representing the error type that occurred

message string required

A human readable message describing the error that occurred

fields string[]

If the error can be tied to a specific field or fields in the user request, this lists those fields

Response headers

x-cloud-error-codes enum

The error codes associated with the response

The realm specified by {realm_id} cannot be found. (code: security_realm.not_found)

application/json
errors object[] required

A list of errors that occurred in the failing request

code string required

A structured code representing the error type that occurred

message string required

A human readable message describing the error that occurred

fields string[]

If the error can be tied to a specific field or fields in the user request, this lists those fields

Response headers

x-cloud-error-codes enum

The error codes associated with the response

There is a version conflict. (code: security_realm.version_conflict)

application/json
errors object[] required

A list of errors that occurred in the failing request

code string required

A structured code representing the error type that occurred

message string required

A human readable message describing the error that occurred

fields string[]

If the error can be tied to a specific field or fields in the user request, this lists those fields

Response headers

x-cloud-error-codes enum

The error codes associated with the response