Syncing users and groups with Microsoft Active Directory

In the Linux terminal:

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

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

   Result:

   Example config file downloaded to /etc/yc-identityhub-sync-agent/config.yaml. Modify it with your values
   Service installed as yc-identityhub-sync-agent
   To start the service: sudo systemctl start yc-identityhub-sync-agent
   To enable the service to start on boot: sudo systemctl enable yc-identityhub-sync-agent
   To check service status: sudo systemctl status yc-identityhub-sync-agent
   yc-identityhub-sync-agent is installed to /usr/bin/yc-identityhub-sync-agent
   

2. Optionally, if you are going to use the authorized key of the service account to authenticate the agent in the Yandex Cloud API, copy the previously saved authorized key file to your server.

   Do it using the scp command or any other suitable tool.

3. Use any text editor to open the YAML file containing the synchronization agent's configuration. This example uses the nano editor:

   nano /etc/yc-identityhub-sync-agent/config.yaml
   

4. Specify the synchronization agent's configuration in the YAML file:

   # 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
   
   # 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 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 in Yandex Identity Hub.

   • replication_tokens_path: Path to the directory storing tokens with info about the current progress of full synchronization 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 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

     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.

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

   • 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 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 settings:

     • level: Logging level. The possible values are:

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

     • format: Event info output format. 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 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 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 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.

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

   sudo systemctl start yc-identityhub-sync-agent
   

6. To make sure syncing is in progress, look up the agent's log file. Here is an example:

   sudo cat /etc/yc-identityhub-sync-agent/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.

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

   sudo systemctl stop yc-identityhub-sync-agent
   

   This will stop user and group syncing.