[Yandex Cloud documentation](../../index.md) > [Yandex Identity Hub](../index.md) > [Step-by-step guides](index.md) > Syncing users and groups with Active Directory

# Syncing users and groups with Microsoft Active Directory


{% note info %}

This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage.

{% endnote %}

If your company uses [Microsoft Active Directory](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview) for user management and you want your users to be able to access Yandex Cloud, you do not need to create Yandex Cloud accounts for your users manually. Instead, you can [sync](../concepts/ad-sync.md) users and groups created in your Active Directory folder with Yandex Identity Hub.

## Prepare Yandex Identity Hub for synchronization {#prepare-org}

1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a [billing account](../../billing/concepts/billing-account.md) linked and its [status](../../billing/concepts/billing-account-statuses.md) is `ACTIVE` or `TRIAL_ACTIVE`. If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a [cloud](../../resource-manager/concepts/resources-hierarchy.md#cloud) to it.
1. [Create](user-pools/create-userpool.md) a user pool in Yandex Identity Hub and [associate](user-pools/add-domain.md#userpool) with it a [domain](../concepts/domains.md) identical to the one used in the Active Directory [domain controller](https://en.wikipedia.org/wiki/Domain_controller_(Windows)).

    Associating your own domain with a [user pool](../concepts/user-pools.md) is optional. You can choose to associate another domain or the default one instead. In which case you will have to set up domain replacement in the `replacement_domain` parameter when configuring the [synchronization agent](../concepts/ad-sync.md#sync-agent). For more information, see [Agent configuration](../concepts/ad-sync.md#agent-config).
1. [Create](../../iam/operations/sa/create.md) a service account and [assign](../../iam/operations/sa/assign-role-for-sa.md#binding-role-organization) to it the following roles for the [organization](../concepts/organization.md) the user pool is in:

    * [`organization-manager.userpools.syncAgent`](../security/index.md#organization-manager-userpools-syncAgent)
    * [`organization-manager.groups.viewer`](../security/index.md#organization-manager-groups-viewer)
    * [`organization-manager.groups.externalCreator`](../security/index.md#organization-manager-groups-externalCreator)
    * [`organization-manager.groups.externalConverter`](../security/index.md#organization-manager-groups-externalConverter)
    
    If you intend to export synchronization agent logs to a Yandex Cloud Logging [log group](../../logging/concepts/log-group.md), assign to your 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.
1. Optionally, [create](../../iam/operations/authentication/manage-authorized-keys.md#create-authorized-key) and save an [authorized key](../../iam/concepts/authorization/key.md) for your [service account](../../iam/concepts/users/service-accounts.md).

    {% note warning %}
    
    No authorized key is required if the synchronization agent is installed on a Yandex Compute Cloud [VM instance](../../compute/concepts/vm.md) to which a service account with the relevant access permissions is attached.
    
    {% endnote %}

## Prepare your Active Directory domain controller {#dc-setup}

1. Create a domain user your agent will use to run synchronization.
1. Grant the following permissions to this user:

    * `Replicating Directory Changes`
    * `Replicating Directory Changes All`
1. On the domain controller, open the network ports for incoming traffic from the IP address of the server hosting Identity Hub AD Sync Agent:

    * `389 (TCP)`: For [LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/).
    * `636 (TCP)`: For [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority).
    * `135 (TCP)`: For [MSRPC](https://learn.microsoft.com/en-us/windows/win32/rpc/rpc-start-page).
    * `49152:65535 (TCP)`: Port range for MSRPC dynamic.
    * `53 (TCP/UDP)` and `88 (TCP/UDP)`: For [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)).

1. Optionally, if you intend to set up authentication using the [Kerberos] protocol (https://en.wikipedia.org/wiki/Kerberos_(protocol)), set up [SPN](https://learn.microsoft.com/en-us/windows/win32/ad/service-principal-names).

## Configure and start the synchronization agent {#setup-agent}

You can install the [synchronization agent](../concepts/ad-sync.md#sync-agent) on any [Linux](https://en.wikipedia.org/wiki/Linux) or [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) server.

If you are installing a sync agent on a Yandex Compute Cloud [VM](../../compute/concepts/vm.md), [connect](../../compute/operations/vm-control/vm-connect-sa.md) the service account you created [earlier](#prepare-org) to that VM.

Before you start syncing, open the following network ports for incoming and outgoing network traffic on the server you are going to run the synchronization agent on:

* To access the Yandex Cloud API:

    * `443`: For [HTTPS](https://en.wikipedia.org/wiki/HTTPS).

* To access the Active Directory domain controller:

    * `389 (TCP)`: For [LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/).
    * `636 (TCP)`: For [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority).
    * `135 (TCP)`: For [MSRPC](https://learn.microsoft.com/en-us/windows/win32/rpc/rpc-start-page).
    * `49152:65535 (TCP)`: Port range for MSRPC dynamic.
    * `53 (TCP/UDP)` and `88 (TCP/UDP)`: For [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)).

If you plan to use the [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)) protocol for authentication on the Active Directory side, you should manually install the components required by this protocol and create the encryption keys file named `keytab`.

{% note info %}

You can currently use the Kerberos protocol only if you install the synchronization agent on a server running Linux.

{% endnote %}

To start syncing users and groups:

{% list tabs group=operating_system %}

- Linux {#linux}

  In the Linux terminal:

  1. To install the Identity Hub AD Sync Agent, run this command:

      ```bash
      curl https://storage.yandexcloud.net/yc-identityhub-sync/install.sh | bash
      ```

      Result:

      ```text
      Example config file downloaded to /etc/yc-identityhub-sync-agent/config.yaml. Modify it with your values
      Service installed as yc-identityhub-sync-agent
      To start the service: sudo systemctl start yc-identityhub-sync-agent
      To enable the service to start on boot: sudo systemctl enable yc-identityhub-sync-agent
      To check service status: sudo systemctl status yc-identityhub-sync-agent
      yc-identityhub-sync-agent is installed to /usr/bin/yc-identityhub-sync-agent
      ```
  1. Optionally, if you are going to use the authorized key of the service account to authenticate the agent in the Yandex Cloud API, copy the previously saved authorized key file to your server.

      Do it using the `scp` command or any other suitable tool.
  1. Use any text editor to open the [YAML](https://yaml.org/) file containing the synchronization agent's configuration. This example uses the `nano` editor:

      ```bash
      nano /etc/yc-identityhub-sync-agent/config.yaml
      ```
  1. Specify the synchronization agent's configuration in the file that opens. The configuration depends on the authentication type 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 %}

      - Authenticating by username and password {#password}

        ```yml
        # Default configuration for yc-identityhub-sync-agent
        # This is a template - please update with your actual values
        
        userpool_id: "<user_pool_ID>"
        replication_tokens_path: "<path_to_directory_with_process_tokens>"
        working_directory: "<path_to_agent_working_directory>"
        
        # 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 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: "username"
          password: "password"
        
        # LDAP client settings
        ldap:
          host: "ldaps://<domain_controller_address>:636"
          username: "<Active_Directory_username>"
          password: "<Active_Directory_user_password>"
          certificate_path: "<path_to_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"
        ```

        Where:

        * `userpool_id`: ID of the [user pool](../concepts/user-pools.md) in Yandex Identity Hub.
        * `replication_tokens_path`: Path to the directory storing tokens with info about the current progress of [full synchronization](../concepts/ad-sync.md#full-sync) processes. This is an optional setting.
        
            If this parameter is not set, the system will be saving the tokens in the agent's working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
        * `working_directory`: Path to the directory for other files the agent needs to operate. This is an optional setting.
        
            If this parameter 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)
        
        * `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` parameter, 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 the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters specify paths other than that specified in `working_directory`, the system will use the paths specified in the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters 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](../concepts/ad-sync.md#yc-setup) is attached.
            * `false`: 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`.
        * `dry_run`: [Dry run](../concepts/ad-sync.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](../concepts/ad-sync.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](#dc-setup) with permissions to replicate folder data.
        * `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`: Name of the Active Directory domain user with data replication permissions [assigned](#dc-setup).
            * `password`: Active Directory domain user password.
            * `certificate_path`: Path to the public key certificate file required to decrypt traffic from the domain controller. This is a required setting when using `LDAPS`.
        
                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](#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` parameter, 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 not be exported to the 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](../concepts/ad-sync.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](../concepts/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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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 %}

      - Kerberos authentication {#kerberos}

        {% note info %}

        You can currently use the Kerberos protocol only if you install the synchronization agent on a server running Linux.

        {% endnote %}

        ```yml
        # Default configuration for yc-identityhub-sync-agent
        # This is a template - please update with your actual values
        
        userpool_id: "<user_pool_ID>"
        replication_tokens_path: "<path_to_directory_with_process_tokens>"
        working_directory: "<path_to_agent_working_directory>"
        
        # 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 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_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"
        ```

        Where:

        * `userpool_id`: ID of the [user pool](../concepts/user-pools.md) in Yandex Identity Hub.
        * `replication_tokens_path`: Path to the directory storing tokens with info about the current progress of [full synchronization](../concepts/ad-sync.md#full-sync) processes. This is an optional setting.
        
            If this parameter is not set, the system will be saving the tokens in the agent's working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
        * `working_directory`: Path to the directory for other files the agent needs to operate. This is an optional setting.
        
            If this parameter 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)
        
        * `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` parameter, 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 the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters specify paths other than that specified in `working_directory`, the system will use the paths specified in the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters 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](../concepts/ad-sync.md#yc-setup) is attached.
            * `false`: 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`.
        * `dry_run`: [Dry run](../concepts/ad-sync.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](../concepts/ad-sync.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 public key certificate file required to decrypt traffic from the domain controller. This is a required setting when using `LDAPS`.
        
                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 parameter 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 setting. 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] mode (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).

        * `logger`: Synchronization [logging](#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` parameter, 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 not be exported to the 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](../concepts/ad-sync.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](../concepts/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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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 %}

      {% endlist %}

  1. Run the Identity Hub AD Sync Agent to start syncing:

      ```bash
      sudo systemctl start yc-identityhub-sync-agent
      ```
  1. To make sure syncing is in progress, look up the agent's log file. Here is an example:

      ```bash
      sudo cat /etc/yc-identityhub-sync-agent/identity_hub.log
      ```

      You can also view the synchronization results in the [Yandex Identity Hub](https://center.yandex.cloud/organization) interface: new users and groups from Active Directory should appear in the selected user pool.

  1. To stop syncing, stop the synchronization agent's process:

      ```bash
      sudo systemctl stop yc-identityhub-sync-agent
      ```

      This will stop user and group syncing.

- Windows {#windows}

  In the PowerShell terminal:

  1. To install the Identity Hub AD Sync Agent, run this command:

      ```bash
      iex (New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yc-identityhub-sync/install.ps1')
      ```

      Result:

      ```text
      Example config file downloaded to C:\ProgramData\YcIdentityHubSyncAgent\config.yaml. Modify it with your values
      yc-identityhub-sync-agent is installed to C:\Program Files\YcIdentityHubSyncAgent\bin\yc-identityhub-sync-agent.exe
      Config file is located at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml

      Status   Name               DisplayName
      ------   ----               -----------
      Stopped  yc-identityhub-... Yandex Identity Hub Sync Agent
      yc-identityhub-sync-agent installed as Windows service 'yc-identityhub-sync-agent' (not started automatically)
      1. Modify the config file at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml with your values
      2. Run: Start-Service yc-identityhub-sync-agent
      ```
  1. Copy to your server the file with service account's authorized key you saved earlier. You can do it using any suitable tool.
  1. Use any text editor to open the agent's [YAML](https://yaml.org/) configuration file (`config.yaml`) located at `C:\ProgramData\YcIdentityHubSyncAgent\` and add the following configuration to it:

      ```yml
      # Default configuration for yc-identityhub-sync-agent
      # This is a template - please update with your actual values
      
      userpool_id: "<user_pool_ID>"
      replication_tokens_path: "<path_to_directory_with_process_tokens>"
      working_directory: "<path_to_agent_working_directory>"
      
      # 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 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: "username"
        password: "password"
      
      # LDAP client settings
      ldap:
        host: "ldaps://<domain_controller_address>:636"
        username: "<Active_Directory_username>"
        password: "<Active_Directory_user_password>"
        certificate_path: "<path_to_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"
      ```

      Where:

      * `userpool_id`: ID of the [user pool](../concepts/user-pools.md) in Yandex Identity Hub.
      * `replication_tokens_path`: Path to the directory storing tokens with info about the current progress of [full synchronization](../concepts/ad-sync.md#full-sync) processes. This is an optional setting.
      
          If this parameter is not set, the system will be saving the tokens in the agent's working directory specified in `working_directory` or, if none is specified, in the directory the agent's executable is in.
      * `working_directory`: Path to the directory for other files the agent needs to operate. This is an optional setting.
      
          If this parameter 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)
      
      * `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` parameter, 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 the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters specify paths other than that specified in `working_directory`, the system will use the paths specified in the `cloud_credentials_file_path`, `replication_tokens_path`, and/or `logger.file.filename` parameters 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](../concepts/ad-sync.md#yc-setup) is attached.
          * `false`: 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`.
      * `dry_run`: [Dry run](../concepts/ad-sync.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](../concepts/ad-sync.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](#dc-setup) with permissions to replicate folder data.
      * `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`: Name of the Active Directory domain user with data replication permissions [assigned](#dc-setup).
          * `password`: Active Directory domain user password.
          * `certificate_path`: Path to the public key certificate file required to decrypt traffic from the domain controller. This is a required setting when using `LDAPS`.
      
              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](#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` parameter, 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 not be exported to the 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](../concepts/ad-sync.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](../concepts/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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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](../concepts/ad-sync.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 %}

  1. Start the synchronization agent's service:

      ```powershell
      Start-Service yc-identityhub-sync-agent
      ```
  1. To make sure syncing is in progress, look up the agent's log file. For example:

      ```bash
      cat C:\ProgramData\YcIdentityHubSyncAgent\identity_hub.log
      ```

      You can also view the synchronization results in the [Yandex Identity Hub](https://center.yandex.cloud/organization) interface: new users and groups from Active Directory should appear in the selected user pool.

  1. To stop the syncing process, stop the service you created:

      ```powershell
      Stop-Service yc-identityhub-sync-agent
      ```

      This will stop user and group syncing.

{% endlist %}

## Test the agent configuration changes {#dry-run}

Identity Hub AD Sync Agent agents can be [dry run](../concepts/ad-sync.md#dry-run). Use this mode to verify that the changes made to the agent configuration are correct before applying them in production.

To dry-run an agent:

{% list tabs group=operating_system %}

- Linux {#linux}

  1. In the Linux terminal, stop the synchronization agent service:

      ```bash
      sudo systemctl stop yc-identityhub-sync-agent
      ```
  1. Make the changes you want to test to the agent configuration.
  1. In the `dry_run` section of the agent configuration file, enable dry run mode:

      ```yml
      ...
      dry_run:
        enabled: true
      ...
      ```
  1. In the Linux terminal, run the agent executable manually and wait for it to complete:

      ```bash
      ./yc-identityhub-sync-agent \
        --config /etc/yc-identityhub-sync-agent/config.yaml
      ```

      As a result, the agent [logs](../concepts/ad-sync.md#logging) will record changes that must be made to Yandex Identity Hub user and group data to align with the agent configuration updates.
      
      For example:
      
      ```text
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Create. Successful: 10. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Update. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Delete. Successful: 2. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Activate. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Deactivate. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: PasswordHashUpdate. Successful: 300. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Create. Successful: 5. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Update. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Delete. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Memberships.			 Change type: Create. Successful: 30. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Memberships.			 Change type: Delete. Successful: 0. Failed: 0
      ```
      
      The example shows that, after synchronization starts, the system will apply these updates in Yandex Identity Hub:
      
      * Create 10 new users.
      * Delete two users.
      * Update password hashes for 300 users.
      * Create five user groups.
      * Add 30 new user group memberships.

  1. Review the log file. If there are no unexpected changes and the operations contain no errors, the changes made to the agent configuration are correct, and you can run the agent in production:

      1. Disable dry run mode by setting the field value to `enabled: false` in the `dry_run` section of the configuration file.
      1. In the Linux terminal, run Identity Hub AD Sync Agent to start syncing:

          ```bash
          sudo systemctl start yc-identityhub-sync-agent
          ```

- Windows {#windows}

  1. In the PowerShell terminal, stop the sync agent service:

      ```powershell
      Stop-Service yc-identityhub-sync-agent
      ```
  1. Make the changes you want to test to the agent configuration.
  1. In the `dry_run` section of the agent configuration file, enable dry run mode:

      ```yml
      ...
      dry_run:
        enabled: true
      ...
      ```
  1. In the PowerShell terminal, run the agent executable manually and wait for it to complete:

      ```powershell
      ./yc-identityhub-sync-agent.exe \
        --config C:\ProgramData\YcIdentityHubSyncAgent\config.yaml
      ```

      As a result, the agent [logs](../concepts/ad-sync.md#logging) will record changes that must be made to Yandex Identity Hub user and group data to align with the agent configuration updates.
      
      For example:
      
      ```text
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Create. Successful: 10. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Update. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Delete. Successful: 2. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Activate. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: Deactivate. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Users.			 Change type: PasswordHashUpdate. Successful: 300. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Create. Successful: 5. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Update. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Groups.			 Change type: Delete. Successful: 0. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Memberships.			 Change type: Create. Successful: 30. Failed: 0
      2026-04-22T06:46:35.504Zinfosynchronization/sync_process.go:542Would synchronize Memberships.			 Change type: Delete. Successful: 0. Failed: 0
      ```
      
      The example shows that, after synchronization starts, the system will apply these updates in Yandex Identity Hub:
      
      * Create 10 new users.
      * Delete two users.
      * Update password hashes for 300 users.
      * Create five user groups.
      * Add 30 new user group memberships.

  1. Review the log file. If there are no unexpected changes and the operations contain no errors, the changes made to the agent configuration are correct, and you can run the agent in production:

      1. Disable dry run mode by setting the field value to `enabled: false` in the `dry_run` section of the configuration file.
      1. In the PowerShell terminal, run Identity Hub AD Sync Agent to start syncing:

          ```powershell
          Start-Service yc-identityhub-sync-agent
          ```

{% endlist %}

#### See also {#see-also}

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