Syncing users and groups with Microsoft Active Directory

If your company uses Microsoft Active Directory for user management and you want your users to be able to access Yandex Cloud, you do not need to create Yandex Cloud accounts for them manually. Instead, you can sync the users and groups created in your Active Directory directory with Yandex Identity Hub.

User and group synchronization is performed by the Identity Hub AD Sync Agent, which can be run on any Linux or Windows server.

How synchronization works:

On the server the synchronization agent is running on, the following network ports must be open for incoming and outgoing traffic:

• To access the Yandex Cloud API:

  • 443 (TCP): For HTTPS.

• To access the Active Directory domain controller:

  • 389 (TCP): For LDAP.
  • 636 (TCP): For LDAPS.
  • 135 (TCP): For MSRPC.
  • 49152:65535 (TCP): Port range for MSRPC dynamic.
  • 53 (TCP/UDP) and 88 (TCP/UDP): For Kerberos.

Synchronization objectsSynchronization objects

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

• Users.

• User attributes.

  User attribute mapping table:

  Attribute name in agent configuration	Attribute name in Active Directory (default)	Attribute name in Yandex Identity Hub
  FullName	displayName	full_name
  GivenName	givenName	given_name
  FamilyName	sn	family_name
  Email	mail	email
  PhoneNumber	telephoneNumber	phone_number
  Username	userPrincipalName	username
  EmployeeId	employeeID	employee_id
  Department	department	department
  JobTitle	title	job_title
  CompanyName	company	company_name
  N/A	ObjectGUID	external_id

  In the user_attribute_mapping agent configuration setting, you can map user attribute names different from the Active Directory default ones or disable synchronization of individual attributes.

• User groups.

• User group attributes.

  User group attribute mapping table:

  Attribute name in agent configuration	Attribute name in Active Directory (default)	Attribute name in Yandex Identity Hub
  Name	name	name
  Description	description	description
  N/A	ObjectGUID	external_id

  In the group_attribute_mapping agent configuration setting, you can map user group attribute names different from the Active Directory default ones or disable synchronization of individual attributes.

• User memberships in groups.

• User password hashes.

  Active Directory stores user passwords as hashes, not plain text. Yandex Cloud collects the user password hash from the Active Directory directory and generates its own one based on it using the modern hack-proof Argon2 algorithm.

  Alert

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

Password writeback in Active DirectoryPassword writeback in Active Directory

The sync agent can perform user password writeback in Active Directory. Password writeback ensures that a user's password gets updated in Active Directory once edited in Yandex Identity Hub in the following cases:

• User who is configured to sync with Active Directory edited their password in Yandex Identity Hub.
• Organization administrator reset the password for a user configured to sync with Active Directory.
• User who is configured to sync with Active Directory set a new password in Yandex Identity Hub after that user's password was reset by an administrator.

Password writeback proceeds in the following order:

1. A user or administrator initiate a change in the user's password in Yandex Identity Hub.

2. The sync agent attempts to update this user's password in Active Directory.

   An attempt to change the password in Active Directory may fail if the new password does not meet the requirements set in Active Directory security policies.

3. If the attempt to change the password in Active Directory is successful, the user's password changes accordingly in Yandex Identity Hub.

4. If the attempt to change the password in Active Directory fails, the user's password in Yandex Identity Hub also remains unchanged.

For password writeback to work, the Active Directory account on whose behalf the agent performs synchronization must also have the Change Password, Reset Password, and Write pwdLastSet permissions. Grant these permissions for the entire domain or for those organization units (OUs) that match the sync_settings.filter filters selected in the agent configuration.

Setting up synchronizationSetting up synchronization

To implement Yandex Identity Hub user and group synchronization with Active Directory, you need to do the presetting both on the domain controller side with Active Directory services deployed and on the Yandex Cloud side.

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.

Active Directory domain controller side setupActive Directory domain controller side setup

For the synchronization agent to work correctly on the Active Directory side, do the following:

1. Create a domain user account or gMSA account your agent will use to run synchronization.

2. Grant the following permissions to this account for the domain specified in the agent configuration under sync_settings.filter:

   • Replicating Directory Changes
   • Replicating Directory Changes All

   If using password writeback, you must also assign the following permissions to the service account, either for organization units (OUs) specified under sync_settings.filter in the agent configuration or for the entire domain:

   • Change Password
   • Reset Password
   • Write pwdLastSet

3. On the domain controller, open the network ports for incoming traffic from the IP address of the server hosting Identity Hub AD Sync Agent:

   • 389 (TCP): For LDAP.
   • 636 (TCP): For LDAPS.
   • 135 (TCP): For MSRPC.
   • 49152:65535 (TCP): Port range for MSRPC dynamic.
   • 53 (TCP/UDP) and 88 (TCP/UDP): For Kerberos.

4. Optionally, if you intend to set up authentication using Kerberos, set up SPN.

Yandex Cloud side setupYandex Cloud side setup

For the synchronization agent to work correctly on the Yandex Cloud side, do the following:

• Create a service account for synchronization on the Yandex Identity Hub side.

• Assign the following roles to the service account for the organization the user pool is in:

  • organization-manager.userpools.syncAgent
  • organization-manager.groups.viewer
  • organization-manager.groups.externalCreator
  • organization-manager.groups.externalConverter

  If you intend to export synchronization agent logs to a Yandex Cloud Logging log group, assign to your account the additional logging.writer role for the log group or folder containing it.

• Optionally, create and save an authorized key for the service account.

  Warning

  No authorized key is required if the synchronization agent is installed on a Yandex Compute Cloud VM to which a service account with the relevant access permissions is attached.

Useful linksUseful links

• Identity Hub AD Sync Agent
• Syncing users and groups with Microsoft Active Directory