---
type: api
title: Update LDAP configuration
description: Updates an existing LDAP configuration.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/operation/operation-update-ldap-configuration
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/operation/operation-update-ldap-configuration
products:
  - Elastic Cloud Enterprise
---

# Update LDAP configuration

## Paths

- `PUT` `/platform/configuration/security/realms/ldap/{realm_id}`

- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/authentication#basicauth)
- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/authentication#apikey)

#### Path Parameters

- `realm_id` (string)
  The Elasticsearch Security realm identifier.

## Description

Updates an existing LDAP configuration.

## Query String 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

`application/json`

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`
- `group_search` ({} LdapGroupSearch) — optional
  The group search configuration for the Elasticsearch security LDAP realm.
  - `base_dn` (string) — optional
    Specifies a container DN to search for groups in which the user has membership
  - `scope` (enum) — optional
    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) — optional
    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) — optional
    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.
- `user_search` ({} LdapUserSearch) — optional
  The user search configuration for the Elasticsearch security LDAP realm.
  - `base_dn` (string) — optional
    Specifies a container DN to search for users
  - `scope` (enum) — optional
    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) — optional
    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) — optional
  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) — optional
  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) — optional
  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) — optional
  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` ({} LdapSecurityRealmLoadBalance) — optional
  The load balancing configuration for the Elasticsearch security LDAP realm.
  - `type` (enum) — optional
    The behavior to use when there are multiple LDAP URLs defined
    Values: `failover`, `dns_failover`, `round_robin`, `dns_round_robin`
  - `cache_ttl` (string) — optional
    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) — optional
  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) — optional
  The password to the certificate bundle URL truststore
- `certificate_url_truststore_type` (enum) — optional
  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` ({} LdapSecurityRealmRoleMappingRules) — optional
  The role mapping ruleset for the Elasticsearch security LDAP realm.
  - `default_roles` ([] string) — required
    The default roles applied to all users
  - `rules` ([] LdapSecurityRealmRoleMappingRule) — 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) — optional
  When true, enables the security realm
- `order` (integer) — optional
  The order that the security realm is evaluated
- `override_yaml` (string) — optional
  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

#### `200`

The LDAP configuration was successfully updated

`application/json`

Type: `EmptyResponse`

##### 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)

#### `400`

* 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` ([] BasicFailedReplyElement)
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    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

#### `404`

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

`application/json`

- `errors` ([] BasicFailedReplyElement)
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    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

#### `409`

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

`application/json`

- `errors` ([] BasicFailedReplyElement)
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    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

## Code Examples

#### Console

```console
PUT /platform/configuration/security/realms/ldap/{realm_id}
```

#### curl

```curl
curl -X PUT "/platform/configuration/security/realms/ldap/{realm_id}"
```