Update Active Directory configuration

PUT /platform/configuration/security/realms/active-directory/{realm_id}
Basic auth Api key

Updates an existing Active Directory 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)

application/json

Body Required

The Active Directory configuration

  • id string Required

    The identifier for the security realm

  • name string Required

    The friendly name of the security realm

  • urls array[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 object

    The Active Directory group search configuration

    Hide group_search attributes Show group_search attributes object
    • base_dn string

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

    • scope string

      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 are sub_tree, one_level, or base.

  • user_search object

    The Active Directory user search configuration.

    Hide user_search attributes Show user_search attributes object
    • base_dn string

      Specifies a container DN to search for users

    • scope string

      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 are sub_tree, one_level, or 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

    The Active Directory load balancing behavior

    Hide load_balance attributes Show load_balance attributes object
    • type string

      The behavior to use when there are multiple Active Directory URLs defined

      Values are failover, dns_failover, round_robin, or 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 string

    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 are jks or PKCS12.

  • role_mappings object

    The role mapping rules associated with the security realm

    Hide role_mappings attributes Show role_mappings attributes object
    • default_roles array[string] Required

      The default roles applied to all users

    • rules array[object] Required

      The role mapping rules to evaluate

      Elasticsearch Security Active Directory role mapping rule

      Hide rules attributes Show rules attributes object
      • type string Required

        The type of role mapping rule

        Values are user_dn or group_dn.

      • roles array[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(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'.

Responses

  • 200 application/json

    The Active Directory configuration was successfully updated

    Hide headers attributes Show headers attributes
    • 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 application/json
    • 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)
    Hide headers attribute Show headers attribute
    • x-cloud-error-codes string

      The error codes associated with the response

      Values are security_realm.id_conflict, security_realm.invalid_id, security_realm.invalid_order, security_realm.invalid_type, security_realm.order_conflict, security_realm.invalid_yaml, security_realm.invalid_url, security_realm.active_directory.invalid_url, or security_realm.invalid_bundle_url.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • 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 array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields
  • 404 application/json

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

    Hide headers attribute Show headers attribute
    • x-cloud-error-codes string

      The error codes associated with the response

      Value is security_realm.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • 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 array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields
  • 409 application/json

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

    Hide headers attribute Show headers attribute
    • x-cloud-error-codes string

      The error codes associated with the response

      Value is security_realm.version_conflict.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • 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 array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields
PUT /platform/configuration/security/realms/active-directory/{realm_id} 
curl \
 --request PUT 'https://{{hostname}}/api/v1/platform/configuration/security/realms/active-directory/{realm_id}' \
 --user "username:password" \
 --header "Content-Type: application/json" \
 --data '{"id":"string","name":"string","urls":["string"],"domain_name":"string","bind_anonymously":true,"group_search":{"base_dn":"string","scope":"sub_tree"},"user_search":{"base_dn":"string","scope":"sub_tree","filter":"string"},"bind_dn":"string","bind_password":"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":true,"order":42,"override_yaml":"string"}'