[Yandex Cloud documentation](../../index.md) > [Yandex Identity Hub](../index.md) > Concepts > Syncing 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 them manually. Instead, you can [sync](../operations/sync-ad.md) the users and groups created in your Active Directory folder with Yandex Identity Hub.

{% note info %}

Currently, you can only sync Active Directory users with [local Yandex Cloud users](../../iam/concepts/users/accounts.md#local) within [user pools](user-pools.md).

{% endnote %}

User and group synchronization is performed by the Identity Hub AD Sync Agent, which can be run on any [Linux](https://en.wikipedia.org/wiki/Linux) or [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) server.

How synchronization works:

```mermaid
flowchart TB
    A["Identity Hub AD Sync Agent"]
    subgraph B [organization-manager.api.cloud.yandex.net]
    D["Yandex Cloud API"]
    end
    subgraph C [Domain Controller IP address]
    E["Active Directory Domain Controller"]
    end
    A e1@==>|"TCP 443 (HTTPS)"|B
    A e2@==>|"TCP 389 (LDAP)<br/>TCP 636 (LDAPS)<br/>TCP 135 (MSRPC)<br/>TCP 49152:65535<br/>(MSRPC dynamic)<br/>TCP/UDP 53 (Kerberos)<br/>TCP/UDP 88 (Kerberos)"|C
    class B myStyle
    class C myStyle
    e1@{ curve: linear }
    e2@{ curve: linear }
    classDef myStyle fill:transparent,stroke-width:0
```

On the server the synchronization agent is [running](../operations/sync-ad.md) on, the following network ports must be open for incoming and outgoing traffic:

* To access the Yandex Cloud API:

    * `443 (TCP)`: 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 %}

## Synchronization objects {#sync-objects}

The Identity Hub AD Sync Agent syncs the following objects with the Active Directory folder:

* **Users**.
* **User attributes**.

    User attribute mapping table:

    Attribute name </br>in [agent configuration](#agent-config) | Attribute name in Active Directory </br>(default) | Attribute name </br>in Yandex Identity Hub
    --- | --- | ---
    `FullName` | `displayName` | `full_name`
    `GivenName` | `givenName` | `given_name`
    `FamilyName` | `sn` | `family_name`
    `Email` | `mail` | `email`
    `PhoneNumber` | `telephoneNumber` | `phone_number`
    `Username` | `userPrincipalName` | `username`
    `EmployeeId` | `employeeID` | `employee_id`
    `Department` | `department` | `department`
    `JobTitle` | `title` | `job_title`
    `CompanyName` | `company` | `company_name`
    no data | `ObjectGUID` | `external_id`

    In the `user_attribute_mapping` [agent configuration](#agent-config) parameter, you can map user attribute names different from the Active Directory default ones or disable synchronization of individual attributes.
* **User groups**.
* **User group attributes**.

    User group attribute mapping table:

    Attribute name </br>in [agent configuration](#agent-config) | Attribute name in Active Directory </br>(default) | Attribute name </br>in Yandex Identity Hub
    --- | --- | ---
    `Name` | `name` | `name`
    `Description` | `description` | `description`
    no data | `ObjectGUID` | `external_id`

    In the `group_attribute_mapping` [agent configuration](#agent-config) parameter, you can map user group attribute names different from the Active Directory default ones or disable synchronization of individual attributes.
* **User memberships in groups**.
* **[User password hashes](https://en.wikipedia.org/wiki/Hash_function)**.

    Active Directory stores user passwords as hashes, not plaintext. Yandex Cloud collects the user password hash from the Active Directory folder and generates its own one based on it using the modern hack-proof [Argon2](https://en.wikipedia.org/wiki/Argon2) algorithm.

    {% note alert %}

    Yandex Cloud does not store user passwords as plaintext in its databases.

    {% endnote %}

## Setting up synchronization {#sync-setup}

To implement Yandex Identity Hub user and group synchronization with Active Directory, you need to do the presetting both on the [domain controller](https://en.wikipedia.org/wiki/Domain_controller_(Windows)) side with Active Directory services deployed and on the Yandex Cloud side.

### Active Directory domain controller side setup {#dc-setup}

For the synchronization [agent](#sync-agent) to work correctly on the Active Directory side, do the following:

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).

### Yandex Cloud side setup {#yc-setup}

For the synchronization [agent](#sync-agent) to work correctly on the Yandex Cloud side, do the following:

* [Create](../../iam/operations/sa/create.md) a service account for synchronization on the Yandex Identity Hub side.
* [Assign](../../iam/operations/sa/assign-role-for-sa.md#binding-role-organization) the following [roles](../../iam/concepts/access-control/roles.md) to the service account for the [organization](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.

* Optionally, [create](../../iam/operations/authentication/manage-authorized-keys.md#create-authorized-key) and save an [authorized key](../../iam/concepts/authorization/key.md) for the service account.

    {% 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 %}

## Identity Hub AD Sync Agent agent {#sync-agent}

Identity Hub AD Sync Agent reads user and user group data in the [selected](#agent-config) Organization Units (OU) in the Active Directory folder 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 user [created](#dc-setup) in the Active Directory domain. To get this data, the agent uses the [LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/) and [DRSR](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-drsr/) protocols. The requests go to the Active Directory domain controller address specified in the agent [configuration](#agent-config).

To authenticate your synchronization agent to Active Directory, you can use either the domain user name and password or Kerberos version 5.

{% note info %}

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

{% 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](#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 instance, 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 to stages: [primary synchronization](#full-sync) and [incremental synchronization](#incremental-sync).

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 [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 folder and creates the same users and groups with the same attributes in the Yandex Identity Hub user pool.

The primary synchronization process for a large number of [objects](#sync-objects) may take a long time. If the full synchronization process is 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 execute a partial (incremental) synchronization.

{% note tip %}

You can restart the full synchronization process. Do it by deleting the mentioned process token files and restarting the agent.

{% endnote %}

#### Partial (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 at an interval of several 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 [set](#agent-config) in the agent's configuration file.

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

Identity Hub AD Sync Agent can be dry run. 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.

### 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, but you can 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`

### Agent configuration {#agent-config}

The synchronization agent's configuration depends on the authentication type the agent uses in Active Directory and is set in a [YAML](https://yaml.org/) file in the following format:

{% 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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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 %}


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

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