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: "ldaps://<domain_controller_IP_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
   
   # Sync settings
   sync_settings:
     interval: "600s"
     allow_to_capture_users: true|false
     allow_to_capture_groups: true|false
     # 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
     remove_user_behavior: "remove|block"
   

   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. For 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: 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: 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.

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

     • 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 parameter. The possible values are:

       • remove: Users who were deleted ceased to satisfy the filter criteria will be deleted on the Identity Hub side. This is the default action.
       • block: Users who were deleted ceased to satisfy the filter criteria will be deactivated on the 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 Identity Hub side.

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. Here is an example:

   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.