# Synchronize Active Directory Users to Cloud Voice Once Cloud Voice is connected to Active Directory (AD), you can define a rule that decides which AD users become extensions on the phone system. Cloud Voice creates an extension for every user the rule covers and, on each synchronization afterward, applies any changes made in the directory so the two stay aligned. There are two ways to build the rule: - [Sync a range of AD users automatically](#sync-a-range-of-ad-users-automatically), pick a scope (all users, an organizational unit, a group, or a search filter) and let Cloud Voice create and number the extensions for you. - [Sync specific AD users manually](#sync-specific-ad-users-manually), search the directory, choose individual users, and pair each one with the extension you want. ## Before you begin You must have already [integrated Cloud Voice with Active Directory](/pbx/integrations/ad/integrate-cloud-voice-cloud-voice-with-active-directory/). :::note The number of AD users you can synchronize is capped by the number of extensions your Cloud Voice system is allowed to create. ::: ## Sync a range of AD users automatically Define the set of AD users to bring in and an auto-assignment rule for extension numbers. Cloud Voice then matches users to extensions on its own during each synchronization. 1. Sign in to the Cloud Voice management portal and go to **Integrations > Collaboration**. 2. In the **User Synchronization** section, turn the switch on. ![User Synchronization toggle in the enabled position](/images/pbx/turn-on-user-sync.png) 3. Open the **User Range for Extension Auto Creation** drop-down list and choose which AD users to synchronize and create extensions for. ![User Range for Extension Auto Creation drop-down list](/images/pbx/user-sync-create-ext-1.png) | Option | What it does | | --- | --- | | All Users | Brings in every AD user in the connected directory and creates an extension for each. | | Users in Specific Organizational Unit | Brings in the users in one or more organizational units. Choose them in the **Organizational Units** drop-down list. | | Users in Specific Group | Brings in the users in one or more groups. Choose them in the **Group** drop-down list. | | Users Searched by Filter | Brings in the users that match an LDAP search filter you enter in the **Search Filter for User** field. | If you pick **Users in Specific Organizational Unit**, select the units to include: ![Organizational Units selected for synchronization](/images/pbx/sync-user-in-ou.png) If you pick **Users in Specific Group**, select the groups to include: ![Groups selected for synchronization](/images/pbx/sync-users-in-group.png) If you pick **Users Searched by Filter**, enter your LDAP filter. For example, `(&(objectCategory=person)(objectClass=user)(cn=sales*))` returns users whose name begins with "sales". ![LDAP search filter entered for user synchronization](/images/pbx/sync-users-by-filter.png) :::note If you later narrow the range of users you sync, the **Auto delete the Extensions no longer in sync** option controls what happens to extensions that fall outside the new scope. ![Auto delete extensions no longer in sync option](/images/pbx/auto-delete-unsync-users.png) - Selected: those extensions are removed at the next synchronization. - Cleared: those extensions stay and become fully managed by Cloud Voice. ::: 4. In the **User's Extension Number** drop-down list, set the rule for numbering the extensions. ![User's Extension Number assignment options](/images/pbx/user-sync-assign-ext.png) | Option | What it does | | --- | --- | | Assign Automatically | Numbers extensions sequentially from a starting value you set in the **Start Extension Number from** field. | | Read Specific Property Value | Reads each user's extension number from an AD property, so users who already have a number keep it instead of getting a new one. Name the property (for example, `ipPhone`) in the **Property Name** field. | :::tip For AD property names, see Microsoft's [Active Directory user object attributes](https://docs.microsoft.com/en-us/windows/win32/ad/user-object-user-interface-mapping). ::: 5. In the **Delete the Extension when its associated user account is** drop-down list, choose the AD account states that make Cloud Voice stop syncing a user and remove their extension. ![Account states that trigger extension deletion](/images/pbx/auto-delete-when-ext.png) | Option | What it does | | --- | --- | | Expired | Stops syncing and deletes the extension when the AD account expires. | | Disabled | Stops syncing and deletes the extension when the AD account is disabled. | | Deleted | Stops syncing and deletes the extension when the AD account is deleted. | :::caution Any state you select here deletes the linked extension automatically. For example, if you choose **Disabled**, disabling that person's account in Active Directory removes their Cloud Voice extension (along with its settings and voicemail) at the next synchronization. A deleted extension cannot be recovered. ::: 6. Decide how to handle the **Auto associate Extensions with the Users that share the same email address** option, which governs AD users whose email matches an existing Cloud Voice extension. The email is read from the AD field you set for the **Email Address** mapping in the **Map** section. - Selected: the matching AD user is synced and linked to that extension, and the extension's user details are overwritten with the values from AD. - Cleared: the matching AD user is not synced, because Cloud Voice does not allow duplicate email addresses on extensions. :::note For security, we recommend preventing AD users from changing their own email addresses. ::: 7. To email a welcome message to each synced user, select **Send Welcome Email automatically after an extension is created**. 8. In the **Map** section, choose and pair the fields for the user details you want to carry over from AD. ![Field mapping between Active Directory and Cloud Voice extensions](/images/pbx/user-mapping.png) :::note - Use Microsoft's [Active Directory user object attributes](https://docs.microsoft.com/en-us/windows/win32/ad/user-object-user-interface-mapping) reference to fill in the Active Directory field names. - Turning off mapping for a field leaves it out of the sync, and you can then edit that field directly on the extension in Cloud Voice. ::: 9. Click **Save**. :::note - The first time you save these settings, Cloud Voice runs the initial synchronization right away. - After that, you can [run a synchronization manually](/pbx/integrations/ad/manually-perform-a-directory-synchronization/) or let the [scheduled synchronization](/pbx/integrations/ad/schedule-automatic-directory-synchronization/) handle it. ::: ## Sync specific AD users manually Set the search scope, pick the exact AD users you want, and assign each one an extension by hand. 1. Sign in to the Cloud Voice management portal and go to **Integrations > Collaboration**. 2. In the **User Synchronization** section, turn the switch on. ![User Synchronization toggle in the enabled position](/images/pbx/turn-on-user-sync.png) 3. In the **User Range for Extension Auto Creation** drop-down list, choose **Specific Users**. ![Specific Users selected in the User Range drop-down list](/images/pbx/sync-specific-ad-user.png) :::note If you later change which users you sync, the **Auto delete the Extensions no longer in sync** option controls what happens to extensions that fall out of scope. ![Auto delete extensions no longer in sync option](/images/pbx/auto-delete-unsync-users-1.png) - Selected: those extensions are removed at the next synchronization. - Cleared: those extensions stay and become fully managed by Cloud Voice. ::: 4. In the **Search Criteria** drop-down list, set where Cloud Voice looks for AD users. | Option | What it does | | --- | --- | | Search Users by Organizational Unit | Searches within the organizational units you select in the **Organizational Unit** drop-down list. | | Search Users by Group | Searches within the groups you select in the **Group** drop-down list. | If you search by organizational unit, choose the units: ![Organizational unit chosen as the search scope](/images/pbx/specify-ad-ou.png) If you search by group, choose the groups: ![Group chosen as the search scope](/images/pbx/specify-ad-group.png) 5. Click **Search AD Users**. Cloud Voice searches the scope you set and lists the matches in the **Search Result List**. ![Matching AD users shown in the search result list](/images/pbx/search-ad-users-to-list.png) :::tip Use the **Search** field in the top-right corner to jump to a user by name. ::: 6. Select the users you want and click **Synchronize to PBX**. They move into the **Synchronization List**. ![AD users selected for synchronization](/images/pbx/select-desired-ad-user.png) 7. For each user, open the **Associate with Extension** drop-down list next to their name and pick the extension to assign. ![Associate with Extension drop-down list beside a synced user](/images/pbx/assign-ad-user-ext.png) :::tip To break a link, select the user and click **Disassociate** at the top of the list. The user is separated from the extension after you save. ::: 8. In the **Delete the Extension when its associated user account is** drop-down list, choose the AD account states that make Cloud Voice stop syncing a user and remove their extension. ![Account states that trigger extension deletion](/images/pbx/auto-delete-when-ext.png) | Option | What it does | | --- | --- | | Expired | Stops syncing and deletes the extension when the AD account expires. | | Disabled | Stops syncing and deletes the extension when the AD account is disabled. | | Deleted | Stops syncing and deletes the extension when the AD account is deleted. | :::caution Any state you select here deletes the linked extension automatically. For example, if you choose **Disabled**, disabling that person's account in Active Directory removes their Cloud Voice extension (along with its settings and voicemail) at the next synchronization. A deleted extension cannot be recovered. ::: 9. To email a welcome message to each synced user, select **Send Welcome Email automatically after an extension is created**. 10. In the **Map** section, choose and pair the fields for the user details you want to carry over from AD. ![Field mapping between Active Directory and Cloud Voice extensions](/images/pbx/user-mapping.png) :::note - Use Microsoft's [Active Directory user object attributes](https://docs.microsoft.com/en-us/windows/win32/ad/user-object-user-interface-mapping) reference to fill in the Active Directory field names. - Turning off mapping for a field leaves it out of the sync, and you can then edit that field directly on the extension in Cloud Voice. ::: 11. Click **Save**. :::note - The first time you save these settings, Cloud Voice runs the initial synchronization right away. - After that, you can [run a synchronization manually](/pbx/integrations/ad/manually-perform-a-directory-synchronization/) or let the [scheduled synchronization](/pbx/integrations/ad/schedule-automatic-directory-synchronization/) handle it. ::: ## Result Your custom synchronization rule is now in place. On each run, Cloud Voice queries Active Directory over LDAP using your rule and pulls in the matching users along with their latest details. After a synchronization: - You can review the outcome in the **User Synchronization** section. ![Synchronization results in the User Synchronization section](/images/pbx/user-sync-result.png) - Extensions tied to AD users carry a marker ![Directory-linked extension marker](/images/pbx/logo.png) and cannot be deleted by hand in Cloud Voice. - When field mapping is enabled, the following details on those extensions can no longer be edited directly in Cloud Voice, change them in Active Directory instead, and they update on the next synchronization: - Last name - First name - Email Address - Mobile Number - Job Title - Avatar ## What to do next To let synced users sign in to the Cloud Voice App with their AD domain accounts, see [Allow Users to Sign In to the Cloud Voice App with AD Domain Accounts](/pbx/integrations/ad/allow-users-to-log-in-to-cloud-voice-app-uc-clients-with-ad-domain-accounts/).