Get Active Directory configuration

  • GET /platform/configuration/security/realms/active-directory/{realm_id}
Auth

Retrieves a single Active Directory security realm configuration.

Path parameters

realm_id string required

The Elasticsearch Security realm identifier.

Responses

The Active Directory configuration was successfully retrieved

application/json
id string required

The identifier for the security realm

name string required

The friendly name of the security realm

urls string[] required

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

domain_name string required

Specifies the domain name of the Active Directory (the forest root domain name).

bind_anonymously boolean required

When true, bindDb credentials are ignored

Elasticsearch Security Active Directory realm group search configuration

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

Elasticsearch Security Active Directory realm user search configuration

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.

bind_dn string

The distinguished name of the user that is used to bind to the Active Directory and perform searches.

bind_password string

The user password that is used to bind to the Active Directory server.

load_balance object

Elasticsearch Security Active Directory load balancing configuration

type enum

The behavior to use when there are multiple Active Directory 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 '/active_directory/: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

Elasticsearch Security Active Directory role mapping rule set

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.active_directory.{realm_id}' prefix. For example, when the realm ID is set to 'ad1', the advanced configuration 'xpack.security.authc.realms.active_directory.ad1.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)

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