[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > Concepts > [Syncing with external directory services](index.md) > Identity Hub AD Sync Agent

# Identity Hub AD Sync Agent


Identity Hub AD Sync Agent reads user and user group data in the [selected](#agent-config) organization units (OUs) in the Active Directory directory and syncs it with user and user group data in the Yandex Identity Hub [pool](../user-pools.md).

The synchronization agent installation script is available for the following operation systems:

* [Linux](https://storage.yandexcloud.net/yc-identityhub-sync/install.sh)
* [Windows](https://storage.yandexcloud.net/yc-identityhub-sync/install.ps1)

### Authenticating to Active Directory {#agent-ad-auth}

On the Active Directory side, the synchronization agent gets user and group data as the account [created](index.md#dc-setup) in the Active Directory domain. To get this data, the agent uses [LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/) and [DRSR](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-drsr/). The requests go to the Active Directory domain controller address specified in the agent [configuration](#agent-config).

Regardless of the host operating system running the synchronization agent, agent authentication on the Active Directory side can be performed using a domain username and password or via [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)) version 5.

Additionally, when installing Identity Hub AD Sync Agent on a Windows server, you can configure agent authentication on the Active Directory side using a [gMSA account](*gmsa_account).

{% note tip %}

A gMSA account is the preferred authentication method for Active Directory, as it eliminates the need to store passwords in the agent configuration file or retain Kerberos keys on the server.

{% endnote %}

### Authenticating to Yandex Cloud {#agent-yc-auth}

On the Yandex Cloud side, the synchronization agent manages users and user groups as a [service account](../../../iam/concepts/users/service-accounts.md) with [permissions](index.md#yc-setup) for syncing. Requests to Yandex Cloud go to public endpoint `https://organization-manager.api.cloud.yandex.net` over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). To authenticate in the Yandex Cloud API, the agent uses a service account authorized key or, only if installed on a Compute Cloud VM, a service account [IAM token](../../../iam/concepts/authorization/iam-token.md) [obtained](../../../compute/operations/vm-metadata/get-vm-metadata.md#example5) via the VM [metadata service](../../../compute/concepts/vm-metadata.md).

### Synchronization process {#sync-process}

During the synchronization process, Identity Hub AD Sync Agent can create, update, or delete users and user groups in Yandex Identity Hub. Yandex Identity Hub users and groups are synced with Active Directory users and groups in two stages: [full](#full-sync) and [incremental](#incremental-sync) synchronization.

During syncing, the user pool may be found to contain a user or user group with names identical to those of the user or user group that need to be synced, in which case, depending on the [current settings](#agent-config), the agent will either overwrite the data from Active Directory for the existing Yandex Identity Hub user or group or return an error message.

#### Full (primary) synchronization {#full-sync}

When performing a full synchronization, the agent reads the data of all users, groups, and their attributes in the [selected](#agent-config) organization units in the Active Directory directory and creates the same users and groups with the same attributes in the Yandex Identity Hub user pool.

The full synchronization process for a large number of [objects](index.md#sync-objects) may take a long time. If it gets interrupted due to an error, you can restart the agent to resume synchronization from where the previous attempt was interrupted. The agent tracks the progress of full synchronization using process token files in the running agent's directory:

* `main_sync_replication_token.json`
* `password_hash_replication_token.json`
* `user_control_replication_token.json`

After full synchronization is successfully completed, the agent, run as a standalone service or OS service, proceeds to continuously perform incremental synchronization.

{% note tip %}

You run full synchronization again by deleting the mentioned process token files and restarting the agent.

{% endnote %}

#### Incremental synchronization {#incremental-sync}

The running agent performs incremental synchronization continuously with the following frequency:

* _Syncing user passwords and states_: The agent tracks the lock/unlock status of users in the Active Directory domain and user password changes and transfers these updates to Yandex Identity Hub every few seconds. You cannot change the frequency for this synchronization type.
* _Syncing other values_: The agent tracks other changes in properties, attributes, and parameters of users and groups at an interval [specified](#agent-config) in the agent's configuration file.

#### Dry run {#dry-run}

You can test Identity Hub AD Sync Agent through the dry-run mode. Use this mode to try out the changes you make to the agent's configuration before applying them.

In dry run mode, the agent does not alter the data of Yandex Identity Hub users and groups. Instead, it tests all operations caused by changes to the agent's configuration and [logs](#logging) the results of these tests.

For more information on how to dry run the agent, see [Test the agent configuration changes](../../operations/sync-ad.md#dry-run).

### Tracked changes {#tracked-changes}

During continuous synchronization, the agent tracks the following changes in Active Directory and transfers them to Yandex Identity Hub:

* Creating, editing, locking, unlocking, and deleting users.
* Creating, editing, and deleting user groups.
* Changing user and user group attributes.
* Adding users to groups and removing them from groups.
* Changing user passwords.

If there is a value in the **accountExpires** field on the Active Directory side for a user account, the agent will synchronize this value with the **Deactivation date** (`expires_at`) field in the local Yandex Identity Hub user's settings. Once the time set in this field is reached, the local Yandex Identity Hub user will be automatically [deactivated](../../operations/user-pools/deactivate-user.md).

In this case, to reactivate the user, update or delete the **accountExpires** field value for the user’s account on the Active Directory side.

### Synchronization logging {#logging}

Identity Hub AD Sync Agent logs the events taking place during synchronization.

By default, the event and error info is fed into the [standard stream](https://en.wikipedia.org/wiki/Standard_streams) named `stdout`. You can configure saving logs to files in the agent's [configuration](#agent-config).

By default, the event info is output in text format, whether using the standard output stream or a file; you can, however, change it to [JSON](https://en.wikipedia.org/wiki/JSON) in the agent's configuration.

In the agent's [configuration](#agent-config), you can also configure log export to a Yandex Cloud Logging [log group](../../../logging/concepts/log-group.md).

Additionally, you can set the following logging conditions in the agent's configuration:

* `debug`
* `info`
* `warn`
* `error`
* `dpanic`
* `panic`
* `fatal`

### Validating permissions for authentication files {#auth-data-security}

Upon startup, the synchronization agent can validate access permissions assigned to files utilized by the agent that contain sensitive data:

* The [agent configuration](#agent-config) file may contain the password for the user account under which the agent runs synchronization on the Active Directory side.
* The `keytab` file contains the encryption keys required for authentication in Active Directory via Kerberos.
* The service account [authorized key](../../../iam/concepts/authorization/key.md) file contains the key that grants access to Yandex Cloud.

If permission validation is enabled, the synchronization agent checks compliance with the following conditions upon startup:

{% list tabs group=operating_system %}

- Linux {#linux}

  * The files are owned by the user under which the agent is running.
  * Read and write permissions for the files are only granted to their owner (`chmod 600`).

- Windows {#windows}

  * Inheritance of access permissions is disabled for the files.
  * Only the `System` and `Local Administrator` subjects, and/or subjects belonging to the `BUILTIN\Administrators` group, have `FullAccess` to the files.
  * Only the user under which the agent is running has read permission for the files.

{% endlist %}

If the agent detects a violation of these conditions upon startup, execution terminates with an error.

You can enable or disable permission validation for sensitive files using the agent's `check_config_permissions` configuration setting.

### Agent configuration {#agent-config}

The Identity Hub AD Sync Agent configuration depends on the [authentication type](#agent-ad-auth) used by the agent on the Active Directory side and uses the following format in the [YAML](https://yaml.org/) file:

{% list tabs group=authentication_linux %}

- On behalf of a gMSA account {#gmsa-windows}

  {% note info %}
  
  Authentication with a [gMSA account](*gmsa_account) is available only when installing the synchronization agent on a Windows server and is the preferred authentication method when using Windows servers.
  
  {% endnote %}

  ```yml
  # Default configuration for yc-identityhub-sync-agent
  # This is a template - please update with your actual values
  
  userpool_id: "<user_pool_ID>"
  working_directory: "<path_to_agent_working_directory>"
  
  # Validate config, static credentials, and configured keytab file permissions at startup.
  check_config_permissions: true|false
  
  # Yandex Cloud authentication settings
  
  # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
  # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
  cloud_credentials_file_path: "<path_to_file_with_authorized_key>"
  
  # Enable the use_metadata_service parameter for authentication via IAM tokens
  # (only available when the agent is installed on a Compute Cloud VM).
  # If `true`, the cloud_credentials_file_path parameter will be ignored.
  use_metadata_service: true|false
  
  # Enable Password Writeback so the agent can synchronize password changes
  # back from Yandex Identity Hub to Active Directory.
  enable_password_writeback: true|false
  
  # Enable the Dry Run mode.
  # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
  # Instead, all pending operations will be saved to the current log file location.
  dry_run:
    enabled: true|false
  
  # Active Directory replication API client settings
  drsr:
    host: "<domain_controller_address>"
    use_windows_identity: true
  
  # LDAP client settings
  ldap:
    host: "ldaps://<domain_controller_address>:636"
    certificate_path: "<path_to_CA_certificate>"
    insecure_skip_verify: false|true
    use_windows_identity: true
  
  # Logger configuration
  logger:
    level: "<logging_level>"
    format: "plain|json"
    file:
      filename: "<log_file_path>"
      maxsize: 30
      maxbackups: 10
    cloud_logger:
      log_group_id: <log_group_ID>
  
  # Sync settings
  sync_settings:
    interval: "600s"
    allow_to_capture_users: true|false
    allow_to_capture_groups: true|false
    # Remove the replacement_domain line if you don't need to replace domain
    replacement_domain: "<user_pool_domain>"
    # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
    # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
    user_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
      # to custom mapping ('CustomAttributeName' --> 'full_name')
      - source: "CustomAttributeName"
        target: "FullName"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'given_name'
      - source: ""
        target: "GivenName"
        type: "empty"
    # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
    # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
    group_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
      # to custom mapping ('CustomAttributeName' --> 'name')
      - source: "CustomAttributeName"
        target: "Name"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'description'
      - source: ""
        target: "Description"
        type: "empty"
    filter:
      domain: "<Active_Directory_domain_name>"
      organization_units:
        - OU=IdPUsersOU,DC=example,DC=com
        - OU=IdPGroupsOU,DC=example,DC=com
      groups:
        - "GroupName1"
        - "GroupName2"
    remove_user_behavior: "remove|block"
  ```

  {% cut "Configuration breakdown" %}

  * `userpool_id`: ID of the [user pool](../user-pools.md) in Yandex Identity Hub.
  
  * `working_directory`: Path to the directory that stores the files the agent needs to operate. This is an optional setting.
  
      If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
  
      * `/etc/yc-identityhub-sync-agent/` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\` (for Windows)
  
  * `check_config_permissions`: Controls whether to [check access permissions](sync-agent.md#auth-data-security) for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
  
      * `true`: Enables checking access permissions to the agent configuration files containing sensitive data.
      * `false`: Disables checking access permissions to the agent configuration files. This is a default value.
  
  * `cloud_credentials_file_path`: Path to the file containing the [authorized key](../../../iam/concepts/authorization/key.md) of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.
  
      Examples of values:
  
      * `/etc/yc-identityhub-sync-agent/authorized_key.json` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json` (for Windows)
  
      In the `cloud_credentials_file_path` settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
      {% note info %}
  
      If `cloud_credentials_file_path` and/or `logger.file.filename` specify paths different from the one specified in `working_directory`, the system will use the paths specified in `cloud_credentials_file_path` and/or `logger.file.filename` for the selected entities.
  
      {% endnote %}
  
  * `use_metadata_service`: Controls agent authentication in the Yandex Cloud API using an [IAM token](../../../iam/concepts/authorization/iam-token.md) and enables the agent to obtain IAM tokens via the VM [metadata service](../../../compute/concepts/vm-metadata.md).
  
      The possible values are:
  
      * `true`: Synchronization agent will use the VM metadata service to obtain the service account IAM tokens for authentication in the Yandex Cloud API The `cloud_credentials_file_path` value will be ignored.
  
          To obtain IAM tokens, the agent must run on a Yandex Compute Cloud VM instance to which a service account with the [relevant access permissions](index.md#yc-setup) is attached.
      * `false`: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in `cloud_credentials_file_path`.
  
  * `enable_password_writeback`: Manages user [password writeback](index.md#password-writeback) in Active Directory.
  
      {% note info %}
      
      The password writeback feature is currently at the [Preview](../../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.
      
      {% endnote %}
  
      The possible values are:
  
      * `true`: When attempting to change the password of a synchronized user in Yandex Identity Hub ([password change](../../operations/manage-account.md#edit-password) by the user or [password reset](../../operations/user-pools/reset-user-password.md#reset) by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
      * `false`: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a [full sync](sync-agent.md#full-sync) after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.
  
  * `dry_run`: [Dry run](sync-agent.md#dry-run) settings for the agent:
  
      * `enabled: true`: Dry run mode on. The agent does not make any changes to Yandex Identity Hub user or group data. Instead, it tests all operations from the agent’s configuration, and [logs](sync-agent.md#logging) the results of these tests.
      * `enabled: false`: The agent runs normally, making the required changes to Yandex Identity Hub user and group data.
  
  * `drsr`: [DRSR](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-drsr/) protocol settings for Active Directory authentication of a [gMSA account](*gmsa_account) with [permissions](index.md#dc-setup) to replicate folder data:
  
      * `host`: Domain or IP address of the Active Directory domain controller.
      * `use_windows_identity: true`: Enforces authentication in Active Directory using a gMSA account for the synchronization agent.
  
          {% note warning %}
          
          To enable the synchronization agent to authenticate in Active Directory using a gMSA account, make sure the agent service on your server is running under that same gMSA account.
          
          {% endnote %}
  
  * `ldap`: [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority)/[LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/) protocol settings for Active Directory authentication:
  
      {% note warning %}
  
      You can connect to a domain controller over `LDAPS` or `LDAP`. `LDAPS` is the recommended and safe option. Use `LDAP` only for setup and testing.
  
      {% endnote %}
  
      * `host`: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  
          * For `LDAPS`: `ldaps://` is the schema and `636` is the port number.
          * For `LDAP`: `ldap://` is the schema and `389` is the port number.
      * `certificate_path`: Path to the file with the CA root certificate used to sign the domain controller's certificate. This is an optional settings.
  
          Specify this option if you are using the `LDAPS` protocol, and the root certificate is not in the system trusted certificate store.
  
          If the `working_directory` parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
      * `insecure_skip_verify`: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional settings. The possible values are:
  
          * `false`: Certificate validation errors will not be ignored. This is a default value.
          * `true`: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.
      * `use_windows_identity: true` is a parameter that requires the synchronization agent to authenticate on the Active Directory side on behalf of the [gMSA account](*gmsa_account).
  
          {% note warning %}
          
          To enable the synchronization agent to authenticate in Active Directory using a gMSA account, make sure the agent service on your server is running under that same gMSA account.
          
          {% endnote %}
  
  * `logger`: Synchronization [logging](sync-agent.md#logging) settings:
  
      * `level`: Logging level. The possible values are:
  
          * `debug`
          * `info`
          * `warn`
          * `error`
          * `dpanic`
          * `panic`
          * `fatal`
  
      * `format`: Event info output format into a standard stream or file. This is an optional setting. The possible values are:
  
          * `plain`: Output the info as plain text. This is a default value.
          * `json`: Output the info in [JSON](https://en.wikipedia.org/wiki/JSON) format.
      * `file`: Settings for saving logs to files:
  
          * `filename`: Path to the file for logging synchronization events.
  
              In the `filename` setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
              This is an optional setting. The default file name is `identity_hub.log`.
          * `maxsize`: Maximum size of a single log file, in MB.
          * `maxbackups`: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  
          This is an optional setting. If no settings are specified in the `file` section, events will not be saved to files.
      * `cloud_logger`: Settings for saving logs to a Yandex Cloud Logging [log group](../../../logging/concepts/log-group.md):
  
          * `log_group_id`: ID of the log group to export the synchronization agent logs to.
          
          This is an optional setting. If no settings are specified in the `cloud_logger` section, events will export to a log group.
  
          To export synchronization agent logs to a log group, assign to the service account the additional `logging.writer` [role](../../../logging/security/index.md#logging-writer) for the log group or [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) containing it.
  
      {% note info %}
  
      If no settings are specified in the `logger.file` and `logger.cloud_logger` sections, the event and error info will be fed into a standard stream named `stdout`; otherwise, the logs will be saved to files and/or the log group.
  
      {% endnote %}
  
  * `sync_settings`: Synchronization settings:
  
      * `interval`: [Incremental synchronization](sync-agent.md#incremental-sync) frequency. This is an optional setting. The default value is 240 seconds.
  
          {% note info %}
  
          Password and user status synchronization in Active Directory takes place every few seconds at a fixed interval which does not depend on the `interval` value.
  
          {% endnote %}
  
      * `allow_to_capture_users`: Enables updating an existing user in the Yandex Identity Hub user pool if their login matches that of a Active Directory user being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub users to match their corresponding Active Directory accounts.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub users. If it detects matching logins in the user pool and Active Directory, the synchronization will throw an error.
      * `allow_to_capture_groups`: Enables updating an existing Yandex Identity Hub user group if its name matches that of a Active Directory group being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub user groups to match their corresponding Active Directory groups.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub groups. If it detects matching group names in the pool and Active Directory, the synchronization will throw an error.
      * `replacement_domain`: [Domain](../domains.md) associated with the Yandex Identity Hub user pool to which synchronized users and groups belong, e.g., `newdomain.idp.yandexcloud.net`.
  
          This is an optional setting. Specify the `replacement_domain` value only if the domain name associated with the user pool does not match the domain name on the Active Directory domain controller.
      * `user_attribute_mapping`: User attribute mapping settings:
  
          * `source`: User attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `user_attribute_mapping` value only if you need to map user attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `group_attribute_mapping`: User group attribute mapping settings:
  
          * `source`: User group attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User group attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `group_attribute_mapping` value only if you need to map user group attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `filter`: Settings for filtering objects to synchronize on the Active Directory side:
  
          * `domain`: Domain name in the Active Directory domain controller where the agent will synchronize users and groups.
          * `organization_units`: List of _organization units_ (OUs) in the Active Directory folder in which the agent will synchronize users and groups.
          * `groups`: List of user groups in the Active Directory folder in which the agent will synchronize users. You can specify one or more groups; filtering by multiple groups will use the `OR` logic.
  
              {% note info %}
  
              The `groups` parameter only affects user synchronization and not user group synchronization settings.
  
              {% endnote %}
  
          If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all [available objects](index.md#sync-objects) in the Active Directory folder.
      * `remove_user_behavior`: Controls what action should be applied to users on the Yandex Cloud side if the corresponding ones on the Active Directory side were deleted or ceased to satisfy the conditions specified in `sync_settings.filter` (e.g., if moved to another organization unit). This is an optional setting. The possible values are:
  
          * `remove`: Users who were deleted ceased to satisfy the filter criteria will be deleted on the Yandex Identity Hub side. This is the default action.
          * `block`: Users who were deleted ceased to satisfy the filter criteria will be deactivated on the Yandex Identity Hub side.
  
      {% note info %}
  
      If synchronization reveals that a Active Directory user group was deleted or ceased to satisfy the filter criteria (e.g., if moved to another organization unit), such a group will be deleted on the Yandex Identity Hub side.
  
      {% endnote %}

  {% endcut %}

- Using a username and password {#password_linux}

  ```yml
  # Default configuration for yc-identityhub-sync-agent
  # This is a template - please update with your actual values
  
  userpool_id: "<user_pool_ID>"
  working_directory: "<path_to_agent_working_directory>"
  
  # Validate config, static credentials, and configured keytab file permissions at startup.
  check_config_permissions: true|false
  
  # Yandex Cloud authentication settings
  
  # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
  # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
  cloud_credentials_file_path: "<path_to_file_with_authorized_key>"
  
  # Enable the use_metadata_service parameter for authentication via IAM tokens
  # (only available when the agent is installed on a Compute Cloud VM).
  # If `true`, the cloud_credentials_file_path parameter will be ignored.
  use_metadata_service: true|false
  
  # Enable Password Writeback so the agent can synchronize password changes
  # back from Yandex Identity Hub to Active Directory.
  enable_password_writeback: true|false
  
  # Enable the Dry Run mode.
  # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
  # Instead, all pending operations will be saved to the current log file location.
  dry_run:
    enabled: true|false
  
  # Active Directory replication API client settings
  drsr:
    host: "<domain_controller_address>"
    username: "<Active_Directory_user_sAMAccountName>"
    password: "password"
  
  # LDAP client settings
  ldap:
    host: "ldaps://<domain_controller_address>:636"
    username: "<Active_Directory_user_DN>"
    password: "<Active_Directory_user_password>"
    certificate_path: "<path_to_CA_certificate>"
    insecure_skip_verify: false|true
  
  # Logger configuration
  logger:
    level: "<logging_level>"
    format: "plain|json"
    file:
      filename: "<log_file_path>"
      maxsize: 30
      maxbackups: 10
    cloud_logger:
      log_group_id: <log_group_ID>
  
  # Sync settings
  sync_settings:
    interval: "600s"
    allow_to_capture_users: true|false
    allow_to_capture_groups: true|false
    # Remove the replacement_domain line if you don't need to replace domain
    replacement_domain: "<user_pool_domain>"
    # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
    # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
    user_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
      # to custom mapping ('CustomAttributeName' --> 'full_name')
      - source: "CustomAttributeName"
        target: "FullName"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'given_name'
      - source: ""
        target: "GivenName"
        type: "empty"
    # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
    # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
    group_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
      # to custom mapping ('CustomAttributeName' --> 'name')
      - source: "CustomAttributeName"
        target: "Name"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'description'
      - source: ""
        target: "Description"
        type: "empty"
    filter:
      domain: "<Active_Directory_domain_name>"
      organization_units:
        - OU=IdPUsersOU,DC=example,DC=com
        - OU=IdPGroupsOU,DC=example,DC=com
      groups:
        - "GroupName1"
        - "GroupName2"
    remove_user_behavior: "remove|block"
  ```

  {% cut "Configuration breakdown" %}

  * `userpool_id`: ID of the [user pool](../user-pools.md) in Yandex Identity Hub.
  
  * `working_directory`: Path to the directory that stores the files the agent needs to operate. This is an optional setting.
  
      If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
  
      * `/etc/yc-identityhub-sync-agent/` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\` (for Windows)
  
  * `check_config_permissions`: Controls whether to [check access permissions](sync-agent.md#auth-data-security) for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
  
      * `true`: Enables checking access permissions to the agent configuration files containing sensitive data.
      * `false`: Disables checking access permissions to the agent configuration files. This is a default value.
  
  * `cloud_credentials_file_path`: Path to the file containing the [authorized key](../../../iam/concepts/authorization/key.md) of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.
  
      Examples of values:
  
      * `/etc/yc-identityhub-sync-agent/authorized_key.json` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json` (for Windows)
  
      In the `cloud_credentials_file_path` settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
      {% note info %}
  
      If `cloud_credentials_file_path` and/or `logger.file.filename` specify paths different from the one specified in `working_directory`, the system will use the paths specified in `cloud_credentials_file_path` and/or `logger.file.filename` for the selected entities.
  
      {% endnote %}
  
  * `use_metadata_service`: Controls agent authentication in the Yandex Cloud API using an [IAM token](../../../iam/concepts/authorization/iam-token.md) and enables the agent to obtain IAM tokens via the VM [metadata service](../../../compute/concepts/vm-metadata.md).
  
      The possible values are:
  
      * `true`: Synchronization agent will use the VM metadata service to obtain the service account IAM tokens for authentication in the Yandex Cloud API The `cloud_credentials_file_path` value will be ignored.
  
          To obtain IAM tokens, the agent must run on a Yandex Compute Cloud VM instance to which a service account with the [relevant access permissions](index.md#yc-setup) is attached.
      * `false`: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in `cloud_credentials_file_path`.
  
  * `enable_password_writeback`: Manages user [password writeback](index.md#password-writeback) in Active Directory.
  
      {% note info %}
      
      The password writeback feature is currently at the [Preview](../../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.
      
      {% endnote %}
  
      The possible values are:
  
      * `true`: When attempting to change the password of a synchronized user in Yandex Identity Hub ([password change](../../operations/manage-account.md#edit-password) by the user or [password reset](../../operations/user-pools/reset-user-password.md#reset) by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
      * `false`: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a [full sync](sync-agent.md#full-sync) after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.
  
  * `dry_run`: [Dry run](sync-agent.md#dry-run) settings for the agent:
  
      * `enabled: true`: Dry run mode on. The agent does not make any changes to Yandex Identity Hub user or group data. Instead, it tests all operations from the agent’s configuration, and [logs](sync-agent.md#logging) the results of these tests.
      * `enabled: false`: The agent runs normally, making the required changes to Yandex Identity Hub user and group data.
  
  * `drsr`: [DRSR](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-drsr/) protocol settings for Active Directory authentication of a [user](index.md#dc-setup) with permissions to replicate folder data:
  
      * `host`: Domain or IP address of the Active Directory domain controller.
      * `username`: `sAMAccountName` of the Active Directory domain user with data replication permissions [assigned](index.md#dc-setup).
      * `password`: Active Directory domain user password.
  
  * `ldap`: [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority)/[LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/) protocol settings for Active Directory authentication:
  
      {% note warning %}
  
      You can connect to a domain controller over `LDAPS` or `LDAP`. `LDAPS` is the recommended and safe option. Use `LDAP` only for setup and testing.
  
      {% endnote %}
  
      * `host`: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  
          * For `LDAPS`: `ldaps://` is the schema and `636` is the port number.
          * For `LDAP`: `ldap://` is the schema and `389` is the port number.
      * `username`: [DN](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) of the Active Directory domain user with data replication permissions [assigned](index.md#dc-setup).
      * `password`: Active Directory domain user password.
      * `certificate_path`: Path to the file containing the root certificate of the certification authority (CA) which signed the domain controller's certificate. This is an optional setting.
  
          Specify this option if you are using the `LDAPS` protocol, and the root certificate is not in the system trusted certificate store.
  
          If the `working_directory` parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
      * `insecure_skip_verify`: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional setting. The possible values are:
  
          * `false`: Certificate validation errors will not be ignored. This is a default value.
          * `true`: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.
  
  * `logger`: Synchronization [logging](sync-agent.md#logging) settings:
  
      * `level`: Logging level. The possible values are:
  
          * `debug`
          * `info`
          * `warn`
          * `error`
          * `dpanic`
          * `panic`
          * `fatal`
  
      * `format`: Event info output format into a standard stream or file. This is an optional setting. The possible values are:
  
          * `plain`: Output the info as plain text. This is a default value.
          * `json`: Output the info in [JSON](https://en.wikipedia.org/wiki/JSON) format.
      * `file`: Settings for saving logs to files:
  
          * `filename`: Path to the file for logging synchronization events.
  
              In the `filename` setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
              This is an optional setting. The default file name is `identity_hub.log`.
          * `maxsize`: Maximum size of a single log file, in MB.
          * `maxbackups`: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  
          This is an optional setting. If no settings are specified in the `file` section, events will not be saved to files.
      * `cloud_logger`: Settings for saving logs to a Yandex Cloud Logging [log group](../../../logging/concepts/log-group.md):
  
          * `log_group_id`: ID of the log group to export the synchronization agent logs to.
          
          This is an optional setting. If no settings are specified in the `cloud_logger` section, events will export to a log group.
  
          To export synchronization agent logs to a log group, assign to the service account the additional `logging.writer` [role](../../../logging/security/index.md#logging-writer) for the log group or [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) containing it.
  
      {% note info %}
  
      If no settings are specified in the `logger.file` and `logger.cloud_logger` sections, the event and error info will be fed into a standard stream named `stdout`; otherwise, the logs will be saved to files and/or the log group.
  
      {% endnote %}
  
  * `sync_settings`: Synchronization settings:
  
      * `interval`: [Incremental synchronization](sync-agent.md#incremental-sync) frequency. This is an optional setting. The default value is 240 seconds.
  
          {% note info %}
  
          Password and user status synchronization in Active Directory takes place every few seconds at a fixed interval which does not depend on the `interval` value.
  
          {% endnote %}
  
      * `allow_to_capture_users`: Enables updating an existing user in the Yandex Identity Hub user pool if their login matches that of a Active Directory user being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub users to match their corresponding Active Directory accounts.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub users. If it detects matching logins in the user pool and Active Directory, the synchronization will throw an error.
      * `allow_to_capture_groups`: Enables updating an existing Yandex Identity Hub user group if its name matches that of a Active Directory group being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub user groups to match their corresponding Active Directory groups.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub groups. If it detects matching group names in the pool and Active Directory, the synchronization will throw an error.
      * `replacement_domain`: [Domain](../domains.md) associated with the Yandex Identity Hub user pool to which synchronized users and groups belong, e.g., `newdomain.idp.yandexcloud.net`.
  
          This is an optional setting. Specify the `replacement_domain` value only if the domain name associated with the user pool does not match the domain name on the Active Directory domain controller.
      * `user_attribute_mapping`: User attribute mapping settings:
  
          * `source`: User attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `user_attribute_mapping` value only if you need to map user attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `group_attribute_mapping`: User group attribute mapping settings:
  
          * `source`: User group attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User group attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `group_attribute_mapping` value only if you need to map user group attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `filter`: Settings for filtering objects to synchronize on the Active Directory side:
  
          * `domain`: Domain name in the Active Directory domain controller where the agent will synchronize users and groups.
          * `organization_units`: List of _organization units_ (OUs) in the Active Directory folder in which the agent will synchronize users and groups.
          * `groups`: List of user groups in the Active Directory folder in which the agent will synchronize users. You can specify one or more groups; filtering by multiple groups will use the `OR` logic.
  
              {% note info %}
  
              The `groups` parameter only affects user synchronization and not user group synchronization settings.
  
              {% endnote %}
  
          If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all [available objects](index.md#sync-objects) in the Active Directory folder.
      * `remove_user_behavior`: Controls what action should be applied to users on the Yandex Cloud side if the corresponding ones on the Active Directory side were deleted or ceased to satisfy the conditions specified in `sync_settings.filter` (e.g., if moved to another organization unit). This is an optional setting. The possible values are:
  
          * `remove`: Users who were deleted ceased to satisfy the filter criteria will be deleted on the Yandex Identity Hub side. This is the default action.
          * `block`: Users who were deleted ceased to satisfy the filter criteria will be deactivated on the Yandex Identity Hub side.
  
      {% note info %}
  
      If synchronization reveals that a Active Directory user group was deleted or ceased to satisfy the filter criteria (e.g., if moved to another organization unit), such a group will be deleted on the Yandex Identity Hub side.
  
      {% endnote %}

  {% endcut %}

- Using Kerberos {#kerberos_linux}

  {% note info %}

  If you are going to use [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)) for [authentication](sync-agent.md#agent-ad-auth) on the Active Directory side, you should manually install the required components and create the encryption keys file named `keytab`.

  {% endnote %}

  ```yml
  # Default configuration for yc-identityhub-sync-agent
  # This is a template - please update with your actual values
  
  userpool_id: "<user_pool_ID>"
  working_directory: "<path_to_agent_working_directory>"
  
  # Validate config, static credentials, and configured keytab file permissions at startup.
  check_config_permissions: true|false
  
  # Yandex Cloud authentication settings
  
  # Use the cloud_credentials_file_path parameter for authentication via an authorized key.
  # If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
  cloud_credentials_file_path: "<path_to_file_with_authorized_key>"
  
  # Enable the use_metadata_service parameter for authentication via IAM tokens
  # (only available when the agent is installed on a Compute Cloud VM).
  # If `true`, the cloud_credentials_file_path parameter will be ignored.
  use_metadata_service: true|false
  
  # Enable Password Writeback so the agent can synchronize password changes
  # back from Yandex Identity Hub to Active Directory.
  enable_password_writeback: true|false
  
  # Enable the Dry Run mode.
  # If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
  # Instead, all pending operations will be saved to the current log file location.
  dry_run:
    enabled: true|false
  
  # Active Directory replication API client settings
  drsr:
    host: "<domain_controller_address>"
    use_kerberos: true
  
  # LDAP client settings
  ldap:
    host: "ldaps://<domain_controller_address>:636"
    certificate_path: "<path_to_CA_certificate>"
    insecure_skip_verify: false|true
    use_kerberos: true
  
  # Kerberos settings
  kerberos:
    keytab_path: "<keytab_file_path>"
    principal: "<user_SPN_in_Active_Directory>"
    krb5_config_path: "<Kerberos_configuration_file_path>"  # optional, the default location is /etc/krb5.conf or whatever path is set in the KRB5_CONFIG environment variable
    disable_pa_fx_fast: true
  
  # Logger configuration
  logger:
    level: "<logging_level>"
    format: "plain|json"
    file:
      filename: "<log_file_path>"
      maxsize: 30
      maxbackups: 10
    cloud_logger:
      log_group_id: <log_group_ID>
  
  # Sync settings
  sync_settings:
    interval: "600s"
    allow_to_capture_users: true|false
    allow_to_capture_groups: true|false
    # Remove the replacement_domain line if you don't need to replace domain
    replacement_domain: "<user_pool_domain>"
    # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
    # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
    user_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
      # to custom mapping ('CustomAttributeName' --> 'full_name')
      - source: "CustomAttributeName"
        target: "FullName"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'given_name'
      - source: ""
        target: "GivenName"
        type: "empty"
    # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
    # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
    group_attribute_mapping:
      # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
      # to custom mapping ('CustomAttributeName' --> 'name')
      - source: "CustomAttributeName"
        target: "Name"
        type: "direct"
      # The following syntax allows to disable synchronization for attribute 'description'
      - source: ""
        target: "Description"
        type: "empty"
    filter:
      domain: "<Active_Directory_domain_name>"
      organization_units:
        - OU=IdPUsersOU,DC=example,DC=com
        - OU=IdPGroupsOU,DC=example,DC=com
      groups:
        - "GroupName1"
        - "GroupName2"
    remove_user_behavior: "remove|block"
  ```

  {% cut "Configuration breakdown" %}

  * `userpool_id`: ID of the [user pool](../user-pools.md) in Yandex Identity Hub.
  
  * `working_directory`: Path to the directory that stores the files the agent needs to operate. This is an optional setting.
  
      If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
  
      * `/etc/yc-identityhub-sync-agent/` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\` (for Windows)
  
  * `check_config_permissions`: Controls whether to [check access permissions](sync-agent.md#auth-data-security) for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
  
      * `true`: Enables checking access permissions to the agent configuration files containing sensitive data.
      * `false`: Disables checking access permissions to the agent configuration files. This is a default value.
  
  * `cloud_credentials_file_path`: Path to the file containing the [authorized key](../../../iam/concepts/authorization/key.md) of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.
  
      Examples of values:
  
      * `/etc/yc-identityhub-sync-agent/authorized_key.json` (for Linux)
      * `C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json` (for Windows)
  
      In the `cloud_credentials_file_path` settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
      {% note info %}
  
      If `cloud_credentials_file_path` and/or `logger.file.filename` specify paths different from the one specified in `working_directory`, the system will use the paths specified in `cloud_credentials_file_path` and/or `logger.file.filename` for the selected entities.
  
      {% endnote %}
  
  * `use_metadata_service`: Controls agent authentication in the Yandex Cloud API using an [IAM token](../../../iam/concepts/authorization/iam-token.md) and enables the agent to obtain IAM tokens via the VM [metadata service](../../../compute/concepts/vm-metadata.md).
  
      The possible values are:
  
      * `true`: Synchronization agent will use the VM metadata service to obtain the service account IAM tokens for authentication in the Yandex Cloud API The `cloud_credentials_file_path` value will be ignored.
  
          To obtain IAM tokens, the agent must run on a Yandex Compute Cloud VM instance to which a service account with the [relevant access permissions](index.md#yc-setup) is attached.
      * `false`: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in `cloud_credentials_file_path`.
  
  * `enable_password_writeback`: Manages user [password writeback](index.md#password-writeback) in Active Directory.
  
      {% note info %}
      
      The password writeback feature is currently at the [Preview](../../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.
      
      {% endnote %}
  
      The possible values are:
  
      * `true`: When attempting to change the password of a synchronized user in Yandex Identity Hub ([password change](../../operations/manage-account.md#edit-password) by the user or [password reset](../../operations/user-pools/reset-user-password.md#reset) by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
      * `false`: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a [full sync](sync-agent.md#full-sync) after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.
  
  * `dry_run`: [Dry run](sync-agent.md#dry-run) settings for the agent:
  
      * `enabled: true`: Dry run mode on. The agent does not make any changes to Yandex Identity Hub user or group data. Instead, it tests all operations from the agent’s configuration, and [logs](sync-agent.md#logging) the results of these tests.
      * `enabled: false`: The agent runs normally, making the required changes to Yandex Identity Hub user and group data.
  
  * `drsr`: [DRSR](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-drsr/) protocol settings for Active Directory authentication using Kerberos.
  
  * `ldap`: [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority)/[LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/) settings for Active Directory authentication using Kerberos:
  
      {% note warning %}
  
      You can connect to a domain controller over `LDAPS` or `LDAP`. `LDAPS` is the recommended and safe option. Use `LDAP` only for setup and testing.
  
      {% endnote %}
  
      * `host`: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  
          * For `LDAPS`: `ldaps://` is the schema and `636` is the port number.
          * For `LDAP`: `ldap://` is the schema and `389` is the port number.
      * `certificate_path`: Path to the file with the CA root certificate used to sign the domain controller's certificate. This is an optional settings.
  
          Specify this option if you are using the `LDAPS` protocol, and the root certificate is not in the system trusted certificate store.
  
          If the `working_directory` parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
      * `insecure_skip_verify`: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional setting. The possible values are:
  
          * `false`: Certificate validation errors will not be ignored. This is a default value.
          * `true`: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.
      * `use_kerberos`: This settings indicates the need to use the Kerberos protocol for user authentication on the Active Directory side.
  
  * `kerberos`: Settings of the Kerberos protocol for authentication on the Active Directory side:
  
      * `keytab_path`: Path to the `keytab` file containing the encryption keys.
      * `principal`: [SPN](https://learn.microsoft.com/en-us/windows/win32/ad/service-principal-names) of the user account to connect to Active Directory.
      * `krb5_config_path`: Path to the Kerberos configuration file. This is an optional parameter. The default value is the `/etc/krb5.conf` path or the value set in the `KRB5_CONFIG` environment variable.
      * `disable_pa_fx_fast: true`: Parameter that manages the [FAST](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/hh831747(v=ws.11)#kerberos-armoring-flexible-authentication-secure-tunneling-fast) mode.
  
  * `logger`: Synchronization [logging](sync-agent.md#logging) settings:
  
      * `level`: Logging level. The possible values are:
  
          * `debug`
          * `info`
          * `warn`
          * `error`
          * `dpanic`
          * `panic`
          * `fatal`
  
      * `format`: Event info output format into a standard stream or file. This is an optional setting. The possible values are:
  
          * `plain`: Output the info as plain text. This is a default value.
          * `json`: Output the info in [JSON](https://en.wikipedia.org/wiki/JSON) format.
      * `file`: Settings for saving logs to files:
  
          * `filename`: Path to the file for logging synchronization events.
  
              In the `filename` setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
  
              This is an optional setting. The default file name is `identity_hub.log`.
          * `maxsize`: Maximum size of a single log file, in MB.
          * `maxbackups`: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  
          This is an optional setting. If no settings are specified in the `file` section, events will not be saved to files.
      * `cloud_logger`: Settings for saving logs to a Yandex Cloud Logging [log group](../../../logging/concepts/log-group.md):
  
          * `log_group_id`: ID of the log group to export the synchronization agent logs to.
          
          This is an optional setting. If no settings are specified in the `cloud_logger` section, events will export to a log group.
  
          To export synchronization agent logs to a log group, assign to the service account the additional `logging.writer` [role](../../../logging/security/index.md#logging-writer) for the log group or [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) containing it.
  
      {% note info %}
  
      If no settings are specified in the `logger.file` and `logger.cloud_logger` sections, the event and error info will be fed into a standard stream named `stdout`; otherwise, the logs will be saved to files and/or the log group.
  
      {% endnote %}
  
  * `sync_settings`: Synchronization settings:
  
      * `interval`: [Incremental synchronization](sync-agent.md#incremental-sync) frequency. This is an optional setting. The default value is 240 seconds.
  
          {% note info %}
  
          Password and user status synchronization in Active Directory takes place every few seconds at a fixed interval which does not depend on the `interval` value.
  
          {% endnote %}
  
      * `allow_to_capture_users`: Enables updating an existing user in the Yandex Identity Hub user pool if their login matches that of a Active Directory user being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub users to match their corresponding Active Directory accounts.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub users. If it detects matching logins in the user pool and Active Directory, the synchronization will throw an error.
      * `allow_to_capture_groups`: Enables updating an existing Yandex Identity Hub user group if its name matches that of a Active Directory group being synchronized. The possible values are:
  
          * `true`: Synchronization agent will update existing Yandex Identity Hub user groups to match their corresponding Active Directory groups.
          * `false`: Synchronization agent will not update existing Yandex Identity Hub groups. If it detects matching group names in the pool and Active Directory, the synchronization will throw an error.
      * `replacement_domain`: [Domain](../domains.md) associated with the Yandex Identity Hub user pool to which synchronized users and groups belong, e.g., `newdomain.idp.yandexcloud.net`.
  
          This is an optional setting. Specify the `replacement_domain` value only if the domain name associated with the user pool does not match the domain name on the Active Directory domain controller.
      * `user_attribute_mapping`: User attribute mapping settings:
  
          * `source`: User attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `user_attribute_mapping` value only if you need to map user attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `group_attribute_mapping`: User group attribute mapping settings:
  
          * `source`: User group attribute name obtained from Active Directory and different from the [default](index.md#sync-objects) one.
  
              To disable attribute synchronization, leave empty: `source: ""`.
          * `target`: Name of the attribute in Yandex Cloud you want to configure mapping with (or disable synchronization for). For the list of available values, see **User group attributes** in [Synchronization objects](index.md#sync-objects).
          * `type`: Selecting an action to take with the specified attribute. The possible values are:
  
              * `direct`: Configure attribute mapping.
              * `empty`: Disable attribute synchronization.
  
          This is an optional setting. You should specify the `group_attribute_mapping` value only if you need to map user group attribute names different from the Active Directory default ones or to disable synchronization of individual attributes.
      * `filter`: Settings for filtering objects to synchronize on the Active Directory side:
  
          * `domain`: Domain name in the Active Directory domain controller where the agent will synchronize users and groups.
          * `organization_units`: List of _organization units_ (OUs) in the Active Directory folder in which the agent will synchronize users and groups.
          * `groups`: List of user groups in the Active Directory folder in which the agent will synchronize users. You can specify one or more groups; filtering by multiple groups will use the `OR` logic.
  
              {% note info %}
  
              The `groups` parameter only affects user synchronization and not user group synchronization settings.
  
              {% endnote %}
  
          If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all [available objects](index.md#sync-objects) in the Active Directory folder.
      * `remove_user_behavior`: Controls what action should be applied to users on the Yandex Cloud side if the corresponding ones on the Active Directory side were deleted or ceased to satisfy the conditions specified in `sync_settings.filter` (e.g., if moved to another organization unit). This is an optional setting. The possible values are:
  
          * `remove`: Users who were deleted ceased to satisfy the filter criteria will be deleted on the Yandex Identity Hub side. This is the default action.
          * `block`: Users who were deleted ceased to satisfy the filter criteria will be deactivated on the Yandex Identity Hub side.
  
      {% note info %}
  
      If synchronization reveals that a Active Directory user group was deleted or ceased to satisfy the filter criteria (e.g., if moved to another organization unit), such a group will be deleted on the Yandex Identity Hub side.
  
      {% endnote %}

  {% endcut %}

{% endlist %}


#### Useful links {#see-also}

* [Syncing users and groups with Microsoft Active Directory](index.md)
* [Syncing users and groups with Microsoft Active Directory](../../operations/sync-ad.md)

[*gmsa_account]: A gMSA (group Managed Service Account) is a type of account in Microsoft Active Directory with passwords managed automatically by the domain controller. This simplifies running and operating the same service (SPN) on different servers. For more information, see [this Microsoft article](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-managed-service-accounts/group-managed-service-accounts/group-managed-service-accounts-overview).