Identity Hub AD Sync Agent

Written by

Improved by

Updated at September 8, 2026

Identity Hub AD Sync Agent reads user and user group data in the selected organization units (OUs) in the Active Directory directory and syncs it with user and user group data in the Yandex Identity Hub pool.

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

Authenticating to Active Directory

On the Active Directory side, the synchronization agent gets user and group data as the account created in the Active Directory domain. To get this data, the agent uses LDAP and DRSR. The requests go to the Active Directory domain controller address specified in the agent configuration.

Regardless of the host operating system running the synchronization agent, agent authentication on the Active Directory side can be performed using a domain username and password or via Kerberos version 5.

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

Tip

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

Authenticating to Yandex Cloud

On the Yandex Cloud side, the synchronization agent manages users and user groups as a service account with permissions for syncing. Requests to Yandex Cloud go to public endpoint https://organization-manager.api.cloud.yandex.net over HTTPS. To authenticate in the Yandex Cloud API, the agent uses a service account authorized key or, only if installed on a Compute Cloud VM, a service account IAM token obtained via the VM metadata service.

Synchronization process

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

During syncing, the user pool may be found to contain a user or user group with names identical to those of the user or user group that need to be synced, in which case, depending on the current settings, 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

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

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

main_sync_replication_token.json
password_hash_replication_token.json
user_control_replication_token.json

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

Tip

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

Incremental synchronization

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

Syncing user passwords and states: The agent tracks the lock/unlock status of users in the Active Directory domain and user password changes and transfers these updates to Yandex Identity Hub every few seconds. You cannot change the frequency for this synchronization type.
Syncing other values: The agent tracks other changes in properties, attributes, and parameters of users and groups at an interval specified in the agent's configuration file.

Dry run

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

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

For more information on how to dry run the agent, see Test the agent configuration changes.

Tracked changes

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

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

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

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

Synchronization logging

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 named stdout. You can configure saving logs to files in the agent's configuration.

By default, the event info is output in text format, whether using the standard output stream or a file; you can, however, change it to JSON in the agent's configuration.

In the agent's configuration, you can also configure log export to a Yandex Cloud Logging log group.

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

debug
info
warn
error
dpanic
panic
fatal

Validating permissions for authentication files

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

The agent configuration file may contain the password for the user account under which the agent runs synchronization on the Active Directory side.
The keytab file contains the encryption keys required for authentication in Active Directory via Kerberos.
The service account authorized key file contains the key that grants access to Yandex Cloud.

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

Linux

Windows

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

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

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

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

Agent configuration

The Identity Hub AD Sync Agent configuration depends on the authentication type used by the agent on the Active Directory side and uses the following format in the YAML file:

On behalf of a gMSA account

Using a username and password

Using Kerberos

Note

Authentication with a gMSA account is available only when installing the synchronization agent on a Windows server and is the preferred authentication method when using Windows servers.

# Default configuration for yc-identityhub-sync-agent
# This is a template - please update with your actual values

userpool_id: "<user_pool_ID>"
working_directory: "<path_to_agent_working_directory>"

# Validate config, static credentials, and configured keytab file permissions at startup.
check_config_permissions: true|false

# Yandex Cloud authentication settings

# Use the cloud_credentials_file_path parameter for authentication via an authorized key.
# If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
cloud_credentials_file_path: "<path_to_file_with_authorized_key>"

# Enable the use_metadata_service parameter for authentication via IAM tokens
# (only available when the agent is installed on a Compute Cloud VM).
# If `true`, the cloud_credentials_file_path parameter will be ignored.
use_metadata_service: true|false

# Enable Password Writeback so the agent can synchronize password changes
# back from Yandex Identity Hub to Active Directory.
enable_password_writeback: true|false

# Enable the Dry Run mode.
# If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
# Instead, all pending operations will be saved to the current log file location.
dry_run:
  enabled: true|false

# Active Directory replication API client settings
drsr:
  host: "<domain_controller_address>"
  use_windows_identity: true

# LDAP client settings
ldap:
  host: "ldaps://<domain_controller_address>:636"
  certificate_path: "<path_to_CA_certificate>"
  insecure_skip_verify: false|true
  use_windows_identity: true

# Logger configuration
logger:
  level: "<logging_level>"
  format: "plain|json"
  file:
    filename: "<log_file_path>"
    maxsize: 30
    maxbackups: 10
  cloud_logger:
    log_group_id: <log_group_ID>

# Sync settings
sync_settings:
  interval: "600s"
  allow_to_capture_users: true|false
  allow_to_capture_groups: true|false
  # Remove the replacement_domain line if you don't need to replace domain
  replacement_domain: "<user_pool_domain>"
  # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
  # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
  user_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
    # to custom mapping ('CustomAttributeName' --> 'full_name')
    - source: "CustomAttributeName"
      target: "FullName"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'given_name'
    - source: ""
      target: "GivenName"
      type: "empty"
  # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
  # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
  group_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
    # to custom mapping ('CustomAttributeName' --> 'name')
    - source: "CustomAttributeName"
      target: "Name"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'description'
    - source: ""
      target: "Description"
      type: "empty"
  filter:
    domain: "<Active_Directory_domain_name>"
    organization_units:
      - OU=IdPUsersOU,DC=example,DC=com
      - OU=IdPGroupsOU,DC=example,DC=com
    groups:
      - "GroupName1"
      - "GroupName2"
  remove_user_behavior: "remove|block"

Configuration breakdown

userpool_id: ID of the user pool in Yandex Identity Hub.

working_directory: Path to the directory that stores the files the agent needs to operate. This is an optional setting.

If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
- /etc/yc-identityhub-sync-agent/ (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\ (for Windows)

check_config_permissions: Controls whether to check access permissions for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
- true: Enables checking access permissions to the agent configuration files containing sensitive data.
- false: Disables checking access permissions to the agent configuration files. This is a default value.

cloud_credentials_file_path: Path to the file containing the authorized key of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.

Examples of values:
- /etc/yc-identityhub-sync-agent/authorized_key.json (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json (for Windows)
In the cloud_credentials_file_path settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.

Note

If cloud_credentials_file_path and/or logger.file.filename specify paths different from the one specified in working_directory, the system will use the paths specified in cloud_credentials_file_path and/or logger.file.filename for the selected entities.

use_metadata_service: Controls agent authentication in the Yandex Cloud API using an IAM token and enables the agent to obtain IAM tokens via the VM metadata service.

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 is attached.
- false: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in cloud_credentials_file_path.

enable_password_writeback: Manages user password writeback in Active Directory.

Note

The password writeback feature is currently at the Preview stage. To request access, contact support or your account manager.

The possible values are:
- true: When attempting to change the password of a synchronized user in Yandex Identity Hub (password change by the user or password reset by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
- false: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a full sync after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.

dry_run: Dry run 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 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 protocol settings for Active Directory authentication of a gMSA account with permissions to replicate folder data:
- host: Domain or IP address of the Active Directory domain controller.
- use_windows_identity: true: Enforces authentication in Active Directory using a gMSA account for the synchronization agent.
  
  Warning
  
  To enable the synchronization agent to authenticate in Active Directory using a gMSA account, make sure the agent service on your server is running under that same gMSA account.

ldap: LDAPS/LDAP protocol settings for Active Directory authentication:

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.
- host: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  - For LDAPS: ldaps:// is the schema and 636 is the port number.
  - For LDAP: ldap:// is the schema and 389 is the port number.
- certificate_path: Path to the file with the CA root certificate used to sign the domain controller's certificate. This is an optional settings.
  
  Specify this option if you are using the LDAPS protocol, and the root certificate is not in the system trusted certificate store.
  
  If the working_directory parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
- insecure_skip_verify: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional settings. The possible values are:
  - false: Certificate validation errors will not be ignored. This is a default value.
  - true: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.
- use_windows_identity: true is a parameter that requires the synchronization agent to authenticate on the Active Directory side on behalf of the gMSA account.
  
  Warning
  
  To enable the synchronization agent to authenticate in Active Directory using a gMSA account, make sure the agent service on your server is running under that same gMSA account.

logger: Synchronization 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 format.
- file: Settings for saving logs to files:
  - filename: Path to the file for logging synchronization events.
    
    In the filename setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.
    
    This is an optional setting. The default file name is identity_hub.log.
  - maxsize: Maximum size of a single log file, in MB.
  - maxbackups: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  This is an optional setting. If no settings are specified in the file section, events will not be saved to files.
- cloud_logger: Settings for saving logs to a Yandex Cloud Logging log group:
  - log_group_id: ID of the log group to export the synchronization agent logs to.
  This is an optional setting. If no settings are specified in the cloud_logger section, events will export to a log group.
  
  To export synchronization agent logs to a log group, assign to the service account the additional logging.writer role for the log group or folder containing it.
Note

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.

sync_settings: Synchronization settings:
- interval: Incremental synchronization frequency. This is an optional setting. The default value is 240 seconds.
  
  Note
  
  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.
- 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 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 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.
  - 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 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.
  - 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
    
    The groups parameter only affects user synchronization and not user group synchronization settings.
  If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all available 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

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.

# Default configuration for yc-identityhub-sync-agent
# This is a template - please update with your actual values

userpool_id: "<user_pool_ID>"
working_directory: "<path_to_agent_working_directory>"

# Validate config, static credentials, and configured keytab file permissions at startup.
check_config_permissions: true|false

# Yandex Cloud authentication settings

# Use the cloud_credentials_file_path parameter for authentication via an authorized key.
# If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
cloud_credentials_file_path: "<path_to_file_with_authorized_key>"

# Enable the use_metadata_service parameter for authentication via IAM tokens
# (only available when the agent is installed on a Compute Cloud VM).
# If `true`, the cloud_credentials_file_path parameter will be ignored.
use_metadata_service: true|false

# Enable Password Writeback so the agent can synchronize password changes
# back from Yandex Identity Hub to Active Directory.
enable_password_writeback: true|false

# Enable the Dry Run mode.
# If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
# Instead, all pending operations will be saved to the current log file location.
dry_run:
  enabled: true|false

# Active Directory replication API client settings
drsr:
  host: "<domain_controller_address>"
  username: "<Active_Directory_user_sAMAccountName>"
  password: "password"

# LDAP client settings
ldap:
  host: "ldaps://<domain_controller_address>:636"
  username: "<Active_Directory_user_DN>"
  password: "<Active_Directory_user_password>"
  certificate_path: "<path_to_CA_certificate>"
  insecure_skip_verify: false|true

# Logger configuration
logger:
  level: "<logging_level>"
  format: "plain|json"
  file:
    filename: "<log_file_path>"
    maxsize: 30
    maxbackups: 10
  cloud_logger:
    log_group_id: <log_group_ID>

# Sync settings
sync_settings:
  interval: "600s"
  allow_to_capture_users: true|false
  allow_to_capture_groups: true|false
  # Remove the replacement_domain line if you don't need to replace domain
  replacement_domain: "<user_pool_domain>"
  # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
  # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
  user_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
    # to custom mapping ('CustomAttributeName' --> 'full_name')
    - source: "CustomAttributeName"
      target: "FullName"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'given_name'
    - source: ""
      target: "GivenName"
      type: "empty"
  # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
  # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
  group_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
    # to custom mapping ('CustomAttributeName' --> 'name')
    - source: "CustomAttributeName"
      target: "Name"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'description'
    - source: ""
      target: "Description"
      type: "empty"
  filter:
    domain: "<Active_Directory_domain_name>"
    organization_units:
      - OU=IdPUsersOU,DC=example,DC=com
      - OU=IdPGroupsOU,DC=example,DC=com
    groups:
      - "GroupName1"
      - "GroupName2"
  remove_user_behavior: "remove|block"

Configuration breakdown

userpool_id: ID of the user pool in Yandex Identity Hub.

working_directory: Path to the directory that stores the files the agent needs to operate. This is an optional setting.

If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
- /etc/yc-identityhub-sync-agent/ (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\ (for Windows)

check_config_permissions: Controls whether to check access permissions for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
- true: Enables checking access permissions to the agent configuration files containing sensitive data.
- false: Disables checking access permissions to the agent configuration files. This is a default value.

cloud_credentials_file_path: Path to the file containing the authorized key of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.

Examples of values:
- /etc/yc-identityhub-sync-agent/authorized_key.json (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json (for Windows)
In the cloud_credentials_file_path settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.

Note

If cloud_credentials_file_path and/or logger.file.filename specify paths different from the one specified in working_directory, the system will use the paths specified in cloud_credentials_file_path and/or logger.file.filename for the selected entities.

use_metadata_service: Controls agent authentication in the Yandex Cloud API using an IAM token and enables the agent to obtain IAM tokens via the VM metadata service.

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 is attached.
- false: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in cloud_credentials_file_path.

enable_password_writeback: Manages user password writeback in Active Directory.

Note

The password writeback feature is currently at the Preview stage. To request access, contact support or your account manager.

The possible values are:
- true: When attempting to change the password of a synchronized user in Yandex Identity Hub (password change by the user or password reset by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
- false: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a full sync after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.

dry_run: Dry run 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 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 protocol settings for Active Directory authentication of a user with permissions to replicate folder data:
- host: Domain or IP address of the Active Directory domain controller.
- username: sAMAccountName of the Active Directory domain user with data replication permissions assigned.
- password: Active Directory domain user password.

ldap: LDAPS/LDAP protocol settings for Active Directory authentication:

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.
- host: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  - For LDAPS: ldaps:// is the schema and 636 is the port number.
  - For LDAP: ldap:// is the schema and 389 is the port number.
- username: DN of the Active Directory domain user with data replication permissions assigned.
- password: Active Directory domain user password.
- certificate_path: Path to the file containing the root certificate of the certification authority (CA) which signed the domain controller's certificate. This is an optional setting.
  
  Specify this option if you are using the LDAPS protocol, and the root certificate is not in the system trusted certificate store.
  
  If the working_directory parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
- insecure_skip_verify: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional setting. The possible values are:
  - false: Certificate validation errors will not be ignored. This is a default value.
  - true: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.

logger: Synchronization logging 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 format.
- file: Settings for saving logs to files:
  - filename: Path to the file for logging synchronization events.
    
    In the filename setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.
    
    This is an optional setting. The default file name is identity_hub.log.
  - maxsize: Maximum size of a single log file, in MB.
  - maxbackups: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  This is an optional setting. If no settings are specified in the file section, events will not be saved to files.
- cloud_logger: Settings for saving logs to a Yandex Cloud Logging log group:
  - log_group_id: ID of the log group to export the synchronization agent logs to.
  This is an optional setting. If no settings are specified in the cloud_logger section, events will export to a log group.
  
  To export synchronization agent logs to a log group, assign to the service account the additional logging.writer role for the log group or folder containing it.
Note

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.

sync_settings: Synchronization settings:
- interval: Incremental synchronization frequency. This is an optional setting. The default value is 240 seconds.
  
  Note
  
  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.
- 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 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 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.
  - 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 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.
  - 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
    
    The groups parameter only affects user synchronization and not user group synchronization settings.
  If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all available 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

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.

Note

If you are going to use Kerberos for authentication on the Active Directory side, you should manually install the required components and create the encryption keys file named keytab.

# Default configuration for yc-identityhub-sync-agent
# This is a template - please update with your actual values

userpool_id: "<user_pool_ID>"
working_directory: "<path_to_agent_working_directory>"

# Validate config, static credentials, and configured keytab file permissions at startup.
check_config_permissions: true|false

# Yandex Cloud authentication settings

# Use the cloud_credentials_file_path parameter for authentication via an authorized key.
# If you want the agent to authenticate via IAM tokens, remove the cloud_credentials_file_path line.
cloud_credentials_file_path: "<path_to_file_with_authorized_key>"

# Enable the use_metadata_service parameter for authentication via IAM tokens
# (only available when the agent is installed on a Compute Cloud VM).
# If `true`, the cloud_credentials_file_path parameter will be ignored.
use_metadata_service: true|false

# Enable Password Writeback so the agent can synchronize password changes
# back from Yandex Identity Hub to Active Directory.
enable_password_writeback: true|false

# Enable the Dry Run mode.
# If `true`, no changes will be applied to users or groups in Yandex Identity Hub.
# Instead, all pending operations will be saved to the current log file location.
dry_run:
  enabled: true|false

# Active Directory replication API client settings
drsr:
  host: "<domain_controller_address>"
  use_kerberos: true

# LDAP client settings
ldap:
  host: "ldaps://<domain_controller_address>:636"
  certificate_path: "<path_to_CA_certificate>"
  insecure_skip_verify: false|true
  use_kerberos: true

# Kerberos settings
kerberos:
  keytab_path: "<keytab_file_path>"
  principal: "<user_SPN_in_Active_Directory>"
  krb5_config_path: "<Kerberos_configuration_file_path>"  # optional, the default location is /etc/krb5.conf or whatever path is set in the KRB5_CONFIG environment variable
  disable_pa_fx_fast: true

# Logger configuration
logger:
  level: "<logging_level>"
  format: "plain|json"
  file:
    filename: "<log_file_path>"
    maxsize: 30
    maxbackups: 10
  cloud_logger:
    log_group_id: <log_group_ID>

# Sync settings
sync_settings:
  interval: "600s"
  allow_to_capture_users: true|false
  allow_to_capture_groups: true|false
  # Remove the replacement_domain line if you don't need to replace domain
  replacement_domain: "<user_pool_domain>"
  # Remove the user_attribute_mapping section if you don't need to remap default user attribute names
  # If you need remapping, the user_attribute_mapping section should only contain the attributes you need to remap
  user_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('displayName' --> 'full_name')
    # to custom mapping ('CustomAttributeName' --> 'full_name')
    - source: "CustomAttributeName"
      target: "FullName"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'given_name'
    - source: ""
      target: "GivenName"
      type: "empty"
  # Remove the group_attribute_mapping section if you don't need to remap default group attribute names
  # If you need remapping, the group_attribute_mapping section should only contain the attributes you need to remap
  group_attribute_mapping:
    # The following syntax allows to reconfigure the default mapping ('name' --> 'name')
    # to custom mapping ('CustomAttributeName' --> 'name')
    - source: "CustomAttributeName"
      target: "Name"
      type: "direct"
    # The following syntax allows to disable synchronization for attribute 'description'
    - source: ""
      target: "Description"
      type: "empty"
  filter:
    domain: "<Active_Directory_domain_name>"
    organization_units:
      - OU=IdPUsersOU,DC=example,DC=com
      - OU=IdPGroupsOU,DC=example,DC=com
    groups:
      - "GroupName1"
      - "GroupName2"
  remove_user_behavior: "remove|block"

Configuration breakdown

userpool_id: ID of the user pool in Yandex Identity Hub.

working_directory: Path to the directory that stores the files the agent needs to operate. This is an optional setting.

If this settings is not set, the system will use the directory containing the agent's executable as the working directory. By default, the agent's executable resides in the following directories:
- /etc/yc-identityhub-sync-agent/ (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\ (for Windows)

check_config_permissions: Controls whether to check access permissions for files with authentication credentials at agent startup. This is an optional settings. The possible values are:
- true: Enables checking access permissions to the agent configuration files containing sensitive data.
- false: Disables checking access permissions to the agent configuration files. This is a default value.

cloud_credentials_file_path: Path to the file containing the authorized key of the service account in Yandex Cloud. This is an optional setting used only for agent authentication in the Yandex Cloud API with an authorized key.

Examples of values:
- /etc/yc-identityhub-sync-agent/authorized_key.json (for Linux)
- C:\\ProgramData\\YcIdentityHubSyncAgent\\authorized_key.json (for Windows)
In the cloud_credentials_file_path settings, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.

Note

If cloud_credentials_file_path and/or logger.file.filename specify paths different from the one specified in working_directory, the system will use the paths specified in cloud_credentials_file_path and/or logger.file.filename for the selected entities.

use_metadata_service: Controls agent authentication in the Yandex Cloud API using an IAM token and enables the agent to obtain IAM tokens via the VM metadata service.

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 is attached.
- false: The synchronization agent will not obtain IAM tokens; to authenticate in the Yandex Cloud API, it will use the authorized key specified in cloud_credentials_file_path.

enable_password_writeback: Manages user password writeback in Active Directory.

Note

The password writeback feature is currently at the Preview stage. To request access, contact support or your account manager.

The possible values are:
- true: When attempting to change the password of a synchronized user in Yandex Identity Hub (password change by the user or password reset by the administrator), the agent first attempts to change the password of the corresponding user in Active Directory; only if this operation is successful will the password be changed in Yandex Identity Hub.
- false: When changing the password of a synchronized user in Yandex Identity Hub, the user's password remains unchanged in Active Directory. If you perform a full sync after changing the password, the agent replaces the updated password in Yandex Identity Hub with the one from Active Directory. This is also the default behavior where writeback is not enabled.

dry_run: Dry run 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 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 protocol settings for Active Directory authentication using Kerberos.

ldap: LDAPS/LDAP settings for Active Directory authentication using Kerberos:

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.
- host: Domain or IP address of the Active Directory domain controller. Specify the schema and port number depending on the protocol you use:
  - For LDAPS: ldaps:// is the schema and 636 is the port number.
  - For LDAP: ldap:// is the schema and 389 is the port number.
- certificate_path: Path to the file with the CA root certificate used to sign the domain controller's certificate. This is an optional settings.
  
  Specify this option if you are using the LDAPS protocol, and the root certificate is not in the system trusted certificate store.
  
  If the working_directory parameter specifies the path to the working directory, you can simply specify the certificate file name instead of its full path.
- insecure_skip_verify: Controls whether to ignore public key certificate validation errors when connecting to a domain controller. This is an optional setting. The possible values are:
  - false: Certificate validation errors will not be ignored. This is a default value.
  - true: The synchronization agent will ignore certificate validation errors. This may prove effective for synchronization setup and testing. Not recommended for general use.
- use_kerberos: This settings indicates the need to use the Kerberos protocol for user authentication on the Active Directory side.

kerberos: Settings of the Kerberos protocol for authentication on the Active Directory side:
- keytab_path: Path to the keytab file containing the encryption keys.
- principal: SPN of the user account to connect to Active Directory.
- krb5_config_path: Path to the Kerberos configuration file. This is an optional parameter. The default value is the /etc/krb5.conf path or the value set in the KRB5_CONFIG environment variable.
- disable_pa_fx_fast: true: Parameter that manages the FAST mode.

logger: Synchronization 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 format.
- file: Settings for saving logs to files:
  - filename: Path to the file for logging synchronization events.
    
    In the filename setting, you can provide only the file name instead of the full path. In this case, the system will save that file in the working directory specified in working_directory or, if none is specified, in the directory the agent's executable is in.
    
    This is an optional setting. The default file name is identity_hub.log.
  - maxsize: Maximum size of a single log file, in MB.
  - maxbackups: Maximum number of log files the agent will retain. When this limit is exceeded, the oldest file will be deleted.
  This is an optional setting. If no settings are specified in the file section, events will not be saved to files.
- cloud_logger: Settings for saving logs to a Yandex Cloud Logging log group:
  - log_group_id: ID of the log group to export the synchronization agent logs to.
  This is an optional setting. If no settings are specified in the cloud_logger section, events will export to a log group.
  
  To export synchronization agent logs to a log group, assign to the service account the additional logging.writer role for the log group or folder containing it.
Note

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.

sync_settings: Synchronization settings:
- interval: Incremental synchronization frequency. This is an optional setting. The default value is 240 seconds.
  
  Note
  
  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.
- 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 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 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.
  - 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 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.
  - 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
    
    The groups parameter only affects user synchronization and not user group synchronization settings.
  If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all available 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

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.

Identity Hub AD Sync Agent

Authenticating to Active Directory

Authenticating to Yandex Cloud

Synchronization process

Full (primary) synchronization

Incremental synchronization

Dry run

Tracked changes

Synchronization logging

Validating permissions for authentication files

Agent configuration

Useful links

Was the article helpful?

Identity Hub AD Sync Agent

Authenticating to Active DirectoryAuthenticating to Active Directory

Authenticating to Yandex CloudAuthenticating to Yandex Cloud

Synchronization processSynchronization process

Full (primary) synchronizationFull (primary) synchronization

Incremental synchronizationIncremental synchronization

Dry runDry run

Tracked changesTracked changes

Synchronization loggingSynchronization logging

Validating permissions for authentication filesValidating permissions for authentication files

Agent configurationAgent configuration

Useful linksUseful links

Was the article helpful?

Authenticating to Active Directory

Authenticating to Yandex Cloud

Synchronization process

Full (primary) synchronization

Incremental synchronization

Dry run

Tracked changes

Synchronization logging

Validating permissions for authentication files

Agent configuration

Useful links