[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > Concepts > Syncing with external directory services > Overview

# Syncing users and groups with Microsoft Active Directory


If your company uses [Microsoft Active Directory](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview) 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](../../operations/sync-ad.md) the users and groups created in your Active Directory directory with Yandex Identity Hub.

{% note info %}

Currently, you can only sync Active Directory users with [local Yandex Cloud users](../../../iam/concepts/users/accounts.md#local) within [user pools](../user-pools.md).

{% endnote %}

User and group synchronization is performed by the Identity Hub AD Sync Agent, which can be run on any [Linux](https://en.wikipedia.org/wiki/Linux) or [Windows](https://en.wikipedia.org/wiki/Microsoft_Windows) server.

How synchronization works:

```mermaid
flowchart TB
    A["Identity Hub AD Sync Agent"]
    subgraph B [organization-manager.api.cloud.yandex.net]
    D["Yandex Cloud API"]
    end
    subgraph C [Domain Controller IP address]
    E["Active Directory Domain Controller"]
    end
    A e1@==>|"TCP 443 (HTTPS)"|B
    A e2@==>|"TCP 389 (LDAP)<br/>TCP 636 (LDAPS)<br/>TCP 135 (MSRPC)<br/>TCP 49152:65535<br/>(MSRPC dynamic)<br/>TCP/UDP 53 (Kerberos)<br/>TCP/UDP 88 (Kerberos)"|C
    class B myStyle
    class C myStyle
    e1@{ curve: linear }
    e2@{ curve: linear }
    classDef myStyle fill:transparent,stroke-width:0
```

On the server the synchronization agent is [running](../../operations/sync-ad.md) on, the following network ports must be open for incoming and outgoing traffic:

* To access the Yandex Cloud API:

    * `443 (TCP)`: For [HTTPS](https://en.wikipedia.org/wiki/HTTPS).

* To access the Active Directory domain controller:

    * `389 (TCP)`: For [LDAP](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/).
    * `636 (TCP)`: For [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority).
    * `135 (TCP)`: For [MSRPC](https://learn.microsoft.com/en-us/windows/win32/rpc/rpc-start-page).
    * `49152:65535 (TCP)`: Port range for MSRPC dynamic.
    * `53 (TCP/UDP)` and `88 (TCP/UDP)`: For [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)).

## Synchronization objects {#sync-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 </br>in [agent configuration](sync-agent.md#agent-config) | Attribute name in Active Directory </br>(default) | Attribute name </br>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](sync-agent.md#agent-config) 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 </br>in [agent configuration](sync-agent.md#agent-config) | Attribute name in Active Directory </br>(default) | Attribute name </br>in Yandex Identity Hub
    --- | --- | ---
    `Name` | `name` | `name`
    `Description` | `description` | `description`
    N/A | `ObjectGUID` | `external_id`

    In the `group_attribute_mapping` [agent configuration](sync-agent.md#agent-config) 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](https://en.wikipedia.org/wiki/Hash_function)**.

    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](https://en.wikipedia.org/wiki/Argon2) algorithm.

    {% note alert %}

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

    {% endnote %}

### Password writeback in Active Directory {#password-writeback}

{% note info %}

The password writeback feature is currently at the [Preview](../../../overview/concepts/launch-stages.md) stage. To request access, contact [support](https://center.yandex.cloud/support) or your account manager.

{% endnote %}

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](../../operations/manage-account.md#edit-password) in Yandex Identity Hub.
* Organization administrator [reset the password](../../operations/user-pools/reset-user-password.md#reset) 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.
1. 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.
1. If the attempt to change the password in Active Directory is successful, the user's password changes accordingly in Yandex Identity Hub.
1. 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 synchronization {#sync-setup}

To implement Yandex Identity Hub user and group synchronization with Active Directory, you need to do the presetting both on the [domain controller](https://en.wikipedia.org/wiki/Domain_controller_(Windows)) side with Active Directory services deployed and on the Yandex Cloud side.

If you are going to use [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)) for [authentication](sync-agent.md#agent-ad-auth) 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 setup {#dc-setup}

For the synchronization [agent](sync-agent.md) to work correctly on the Active Directory side, do the following:

1. Create a domain user account or [gMSA account](*gmsa_account) your agent will use to run synchronization.
1. 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`
1. 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](https://learn.microsoft.com/en-us/windows/win32/api/_ldap/).
    * `636 (TCP)`: For [LDAPS](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/enable-ldap-over-ssl-3rd-certification-authority).
    * `135 (TCP)`: For [MSRPC](https://learn.microsoft.com/en-us/windows/win32/rpc/rpc-start-page).
    * `49152:65535 (TCP)`: Port range for MSRPC dynamic.
    * `53 (TCP/UDP)` and `88 (TCP/UDP)`: For [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)).

1. Optionally, if you intend to set up authentication using [Kerberos](https://en.wikipedia.org/wiki/Kerberos_(protocol)), set up [SPN](https://learn.microsoft.com/en-us/windows/win32/ad/service-principal-names).

### Yandex Cloud side setup {#yc-setup}

For the synchronization [agent](sync-agent.md) to work correctly on the Yandex Cloud side, do the following:

* [Create](../../../iam/operations/sa/create.md) a service account for synchronization on the Yandex Identity Hub side.
* [Assign](../../../iam/operations/sa/assign-role-for-sa.md#binding-role-organization) the following [roles](../../../iam/concepts/access-control/roles.md) to the service account for the [organization](../organization.md) the user pool is in:

    * [`organization-manager.userpools.syncAgent`](../../security/index.md#organization-manager-userpools-syncAgent)
    * [`organization-manager.groups.viewer`](../../security/index.md#organization-manager-groups-viewer)
    * [`organization-manager.groups.externalCreator`](../../security/index.md#organization-manager-groups-externalCreator)
    * [`organization-manager.groups.externalConverter`](../../security/index.md#organization-manager-groups-externalConverter)
    
    If you intend to export synchronization agent logs to a Yandex Cloud Logging [log group](../../../logging/concepts/log-group.md), assign to your account the additional `logging.writer` [role](../../../logging/security/index.md#logging-writer) for the log group or [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) containing it.

* Optionally, [create](../../../iam/operations/authentication/manage-authorized-keys.md#create-authorized-key) and save an [authorized key](../../../iam/concepts/authorization/key.md) for the service account.

    {% note warning %}
    
    No authorized key is required if the synchronization agent is installed on a Yandex Compute Cloud [VM](../../../compute/concepts/vm.md) to which a service account with the relevant access permissions is attached.
    
    {% endnote %}

#### Useful links {#see-also}

* [Identity Hub AD Sync Agent](sync-agent.md)
* [Syncing users and groups with Microsoft Active Directory](../../operations/sync-ad.md)

[*gmsa_account]: A gMSA (group Managed Service Account) is a type of account in Microsoft Active Directory with passwords managed automatically by the domain controller. This simplifies running and operating the same service (SPN) on different servers. For more information, see [this Microsoft article](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/group-managed-service-accounts/group-managed-service-accounts/group-managed-service-accounts-overview).