---
type: api
title: Create Active Directory configuration
description: Creates a new Active Directory configuration.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-active-directory-configuration
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/cloud-enterprise/v4/operation/operation-create-active-directory-configuration
products:
  - Elastic Cloud Enterprise
---

# Create Active Directory configuration

## Paths

- `POST` `/platform/configuration/security/realms/active-directory`

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

## Description

Creates a new Active Directory configuration.

## Request Body

`application/json`

The Active Directory configuration

- `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
- `group_search` ({} ActiveDirectoryGroupSearch) — optional
  Elasticsearch Security Active Directory realm group search configuration
  - `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`
- `user_search` ({} ActiveDirectoryUserSearch) — optional
  Elasticsearch Security Active Directory realm user search configuration
  - `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.
- `bind_dn` (string) — optional
  The distinguished name of the user that is used to bind to the Active Directory and perform searches.
- `bind_password` (string) — optional
  The user password that is used to bind to the Active Directory server.
- `load_balance` ({} ActiveDirectorySecurityRealmLoadBalance) — optional
  Elasticsearch Security Active Directory load balancing configuration
  - `type` (enum) — optional
    The behavior to use when there are multiple Active Directory 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 '/active_directory/: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` ({} ActiveDirectorySecurityRealmRoleMappingRules) — optional
  Elasticsearch Security Active Directory role mapping rule set
  - `default_roles` ([] string) — required
    The default roles applied to all users
  - `rules` ([] ActiveDirectorySecurityRealmRoleMappingRule) — 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.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'.

## Responses

#### `201`

The Active Directory configuration was successfully created

`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 Active Directory URL. (code: `security_realm.active_directory.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

## Code Examples

#### Console

```console
POST /platform/configuration/security/realms/active-directory
```

#### curl

```curl
curl -X POST "/platform/configuration/security/realms/active-directory"
```