Syncing users and groups with Microsoft Active Directory

In the PowerShell terminal:

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

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

   Result:

   Example config file downloaded to C:\ProgramData\YcIdentityHubSyncAgent\config.yaml. Modify it with your values
   yc-identityhub-sync-agent is installed to C:\Program Files\YcIdentityHubSyncAgent\bin\yc-identityhub-sync-agent.exe
   Config file is located at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml
   
   Status   Name               DisplayName
   ------   ----               -----------
   Stopped  yc-identityhub-... Yandex Identity Hub Sync Agent
   yc-identityhub-sync-agent installed as Windows service 'yc-identityhub-sync-agent' (not started automatically)
   1. Modify the config file at C:\ProgramData\YcIdentityHubSyncAgent\config.yaml with your values
   2. Run: Start-Service yc-identityhub-sync-agent
   

2. Copy to your server the file with service account's authorized key you saved earlier. You can do it using any suitable tool.

3. Use any text editor to open the agent's YAML configuration file (config.yaml) located at C:\ProgramData\YcIdentityHubSyncAgent\ and add the following configuration to it:

   # Default configuration for yc-identityhub-sync-agent
   # This is a template - please update with your actual values
   
   userpool_id: "<user_pool_ID>"
   cloud_credentials_file_path: "<path_to_file_with_authorized_key>"
   replication_tokens_path: "<path_to_directory_with_process_tokens>"
   working_directory: "<path_to_agent_working_directory>"
   
   # Active Directory replication API client settings
   drsr:
     host: "<domain_controller_IP_address>"
     username: "username"
     password: "password"
   
   # LDAP client settings
   ldap:
     host: "ldap://<domain_controller_IP_address>:389"
     username: "ldap_username"
     password: "ldap_password"
   
   # Logger configuration
   logger:
     level: <logging_level>
     format: <output_format>
     file:
       filename: "<log_file_path>"
       maxsize: 30
       maxbackups: 10
   
   # Sync settings
   sync_settings:
     interval: "600s"
     allow_to_capture_users: true
     allow_to_capture_groups: true
     # Remove the following line if you don't need to replace domain
     replacement_domain: "<user_pool_domain>"
     filter:
       domain: "<Active_Directory_domain_name>"
       organization_units:
         - OU=IdPUsersOU,DC=example,DC=com
         - OU=IdPGroupsOU,DC=example,DC=com
   

   Where:

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

   • cloud_credentials_file_path: Path to the file containing the authorized key of the service account in Yandex Cloud. Here is an example:

     • /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.

   • replication_tokens_path: Path to the directory storing tokens with info about the current progress of full synchronization processes. This is an optional parameter.

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

     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)

     Note

     If the cloud_credentials_file_path, replication_tokens_path, and/or logger.level parameters specify paths other than that specified in working_directory, the system use the paths specified in cloud_credentials_file_path, replication_tokens_path, and/or logger.level.

   • drsr: DRSR protocol settings for Active Directory authentication of a user with permissions to replicate folder data.

   • ldap: LDAP protocol settings for Active Directory authentication of a user with permissions to replicate folder data.

   • logger: Synchronization logging settings:

     • level: Logging level. The possible values are:

       • debug
       • info
       • warn
       • error
       • dpanic
       • panic
       • fatal

     • format: Event info output format. This is an optional parameter. 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 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 parameter. 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 parameter. If you do not provide the file settings, logs will be output to the stdout stream and not saved to files.

   • sync_settings: Synchronization settings:

     • interval: Incremental synchronization frequency. This is an optional parameter. 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 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 Identity Hub users to match their corresponding Active Directory accounts.
       • false: Synchronization agent will not update existing 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 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 Identity Hub user groups to match their corresponding Active Directory groups.
       • false: Synchronization agent will not update existing 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 Identity Hub user pool to which synchronized users and groups belong, e.g., newdomain.idp.yandexcloud.net.

       This is an optional parameter. 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.

     • 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 organizational units (OUs) in the Active Directory folder in which the agent will synchronize users and groups.

       If object filtering is not configured, Identity Hub AD Sync Agent will attempt to synchronize all available objects in the Active Directory folder.

       Note

       If a user or group no longer matches the specified filters during synchronization, e.g., if moved to a different organizational unit within Active Directory, such a user or group will be removed from Identity Hub.

4. Start the synchronization agent's service:

   Start-Service yc-identityhub-sync-agent
   

5. To make sure syncing is in progress, look up the agent's log file, e.g.,

   cat C:\ProgramData\YcIdentityHubSyncAgent\identity_hub.log
   

   You can also view the synchronization results in the Yandex Identity Hub interface: new users and groups from Active Directory should appear in the selected user pool.

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

   Stop-Service yc-identityhub-sync-agent
   

   This will stop user and group syncing.