--- type: api title: Get LDAP configuration description: Retrieves a single LDAP security realm configuration. url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/cloud-enterprise/v3/operation/operation-get-ldap-configuration resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/cloud-enterprise/v3/operation/operation-get-ldap-configuration products: - Elastic Cloud Enterprise --- # Get LDAP configuration Authentication: required ## Paths - `GET` `/platform/configuration/security/realms/ldap/{realm_id}` #### Path parameters - `realm_id` (string) — required The Elasticsearch Security realm identifier. ## Description Retrieves a single LDAP security realm configuration. ## Responses #### `200` The LDAP configuration was successfully retrieved `application/json` - `id` (string) The identifier for the security realm - `name` (string) The friendly name of the security realm - `urls` (string[]) 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) When true, bindDb credentials are ignored - `bind_type` (enum) The type of user binding to apply Values: `user_search`, `user_templates` - `group_search` (object) 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. - `user_search` (object) 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[]) The default roles applied to all users - `rules` (object[]) The role mapping rules to evaluate - `type` (enum) The type of role mapping rule Values: `user_dn`, `group_dn` - `roles` (string[]) The roles that are applied when the mapping rule is successfully evaluated - `value` (string) 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'. ##### 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) #### `404` The realm specified by {realm_id} cannot be found. (code: `security_realm.not_found`) `application/json` - `errors` (object[]) 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 #### curl ```curl curl -X GET "${API_URL}/platform/configuration/security/realms/ldap/${REALM_ID}" \ -u "${USERNAME}:${PASSWORD}" ``` ## Response examples #### 200 `application/json` Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields. ```json { "id": "string", "name": "string", "urls": [ "string" ], "bind_anonymously": false, "bind_type": "user_search", "group_search": { "base_dn": "string", "scope": "sub_tree", "filter": "string", "user_attribute": "string" }, "user_search": { "base_dn": "string", "scope": "sub_tree", "filter": "string" }, "user_dn_templates": [ "string" ], "bind_dn": "string", "bind_password": "string", "user_group_attribute": "string", "load_balance": { "type": "failover", "cache_ttl": "string" }, "certificate_url": "string", "certificate_url_truststore_password": "string", "certificate_url_truststore_type": "jks", "role_mappings": { "default_roles": [ "string" ], "rules": [ { "type": "user_dn", "roles": [ "string" ], "value": "string" } ] }, "enabled": false, "order": 0, "override_yaml": "string" } ``` #### 404 `application/json` Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields. ```json { "errors": [ { "code": "string", "message": "string", "fields": [ "string" ] } ] } ```