# Synchronize Users from Microsoft Entra ID to Cloud Voice Once Cloud Voice is connected to Microsoft Entra ID, you can have the system pull user accounts from your directory and turn them into extensions. You choose which users are in scope, how their extension numbers are assigned, and which directory fields are copied onto each extension. From then on, Cloud Voice keeps those extensions aligned with the source accounts on every sync. You can work in one of two ways: synchronize a whole range of directory users at once and let Cloud Voice create their extensions automatically, or hand-pick individual users and map each one to a specific extension yourself. :::note The number of Entra ID users you can bring in is capped by how many extensions your Cloud Voice system is licensed to create. ::: ## Before you begin Cloud Voice must already be integrated with Microsoft Entra ID. Which integration guide applies depends on your system's firmware version: - Version **84.22.0.138** or later, see [Integrate Cloud Voice with Azure Active Directory](/pbx/integrations/azure-ad/integrate-cloud-voice-cloud-voice-with-azure-active-directory/). - A version earlier than **84.22.0.138**: see [Integrate Cloud Voice with Azure Active Directory (Legacy)](/pbx/integrations/azure-ad/integrate-cloud-voice-cloud-voice-with-azure-active-directory-legacy/). ## Synchronize a range of users Use this approach to sync everyone within a defined scope and let Cloud Voice provision extensions for them automatically. 1. Sign in to the Cloud Voice web portal and go to **Integrations > Collaboration**. 2. In the **User Synchronization** section, turn the switch on. ![The User Synchronization toggle switched to the on position](/images/pbx/turn-on-user-sync.png) 3. From the **User Range for Extension Auto Creation** drop-down list, choose which directory users should be synced and given extensions. ![The User Range for Extension Auto Creation drop-down showing the available scope options](/images/pbx/user-sync-rules.png) | Option | What it does | | --- | --- | | All Users | Syncs every user in Microsoft Entra ID and creates an extension for each one. | | Users of Specific Type | Syncs only the user type(s) you pick, then creates their extensions. Select the type(s) in the **User Type** drop-down list: **Member** covers all member accounts in your directory, and **Guest** covers all guest accounts. | | Users in Specific Group | Syncs the users belonging to the group(s) you pick, then creates their extensions. Select the group(s) in the **Group** drop-down list. | :::note If you later narrow or change the range, the **Auto delete the Extensions no longer in sync** option controls what happens to extensions whose users are no longer in scope. Select it to remove those extensions on the next sync, or leave it cleared to keep them and have Cloud Voice manage them from that point on. ![The Auto delete the Extensions no longer in sync checkbox](/images/pbx/auto-delete-unsync-users.png) ::: 4. From the **User's Extension Number** drop-down list, decide how extension numbers are assigned. ![The User's Extension Number drop-down with numbering options](/images/pbx/user-sync-ext-assignement.png) | Option | What it does | | --- | --- | | Assign Automatically | Numbers extensions sequentially from a starting point. Enter that value in the **Start Extension Number from** field. | | Read Specific Property Value | Takes each extension number from a directory property, which is useful when your users already have phone extensions recorded in Entra ID and you want to preserve them. Enter the property that holds the numbers (for example, `businessPhones`) in the **Property Name** field. | :::tip See [Microsoft's user resource reference](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties) for valid property names. ::: 5. From the **Delete the Extension when its associated user account is** drop-down list, pick the account state(s) that cause Cloud Voice to stop syncing a user and remove their extension. ![The drop-down for choosing which account states trigger extension deletion](/images/pbx/auto-delete-ext.png) | Option | What it does | | --- | --- | | Disabled | When an account is disabled in Entra ID, Cloud Voice stops syncing it and deletes the linked extension. | | Deleted | When an account is deleted in Entra ID, Cloud Voice stops syncing it and deletes the linked extension. | :::caution These states delete the linked extension, they do not just pause it. Choosing **Disabled** means an account that is only temporarily disabled in Entra ID (for example, a user on leave) loses its extension and any settings tied to it. Pick the state(s) that match how your organization manages accounts. ::: 6. Set the remaining synchronization options to suit your needs. ![Additional user synchronization options](/images/pbx/aad-options.png) | Option | What it does | | --- | --- | | Auto associate Extensions with the Users that share the same email address | Determines how Cloud Voice handles a directory user whose **User principal name** (UPN, usually the user's sign-in email) in Microsoft 365 matches the **Email Address** of an existing extension. Select it to sync those users and link them to the matching extensions. Leave it cleared and those users are skipped, since Cloud Voice does not permit duplicate email addresses. | | Send Welcome Email automatically after an extension is created | Determines whether a Cloud Voice App welcome email goes out to each synced user. | | User Avatar Synchronization | Determines whether Entra ID user avatars are copied to their extensions. This is a one-way copy from Entra ID into Cloud Voice; afterward the extension avatar is read-only and users cannot change it from the Cloud Voice App. | 7. In the **Map** section, choose the user fields to synchronize and match each one to its Cloud Voice extension field. :::note - Use [Microsoft's user resource reference](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties) to identify the correct Entra ID field names. - Any field (or all extension fields) with mapping turned off is left out of the sync, and you can edit that information directly on the extension in Cloud Voice instead. ::: ![The Map section pairing directory fields with extension fields](/images/pbx/user-mapping.png) 8. Click **Save**. :::note - The first time you save synchronization settings, Cloud Voice runs the initial sync right away. - After that, you can [run a directory synchronization manually](/pbx/integrations/azure-ad/manually-perform-a-directory-synchronization/) or wait for the [scheduled automatic synchronization](/pbx/integrations/azure-ad/schedule-automatic-directory-synchronization/). ::: ## Synchronize specific users Use this approach to define where Cloud Voice may look for directory users, then hand-pick the ones to sync and attach each to an extension yourself. 1. Sign in to the Cloud Voice web portal and go to **Integrations > Collaboration**. 2. In the **User Synchronization** section, turn the switch on. ![The User Synchronization toggle switched to the on position](/images/pbx/turn-on-user-sync.png) 3. From the **User Range for Extension Auto Creation** drop-down list, select **Specific Users**. ![Selecting Specific Users in the User Range drop-down](/images/pbx/sync-specific-ad-user.png) 4. Use the **Search Criteria** and **Group** drop-down lists to define where Cloud Voice should look for directory users. ![Setting the search criteria and group that scope the user search](/images/pbx/specify-ad-group.png) 5. Click **Search Users**. Cloud Voice queries Entra ID within the scope you set and lists the matches in the **Search Result List**. ![Users returned from the directory search shown in the result list](/images/pbx/search-ad-users-to-list.png) :::tip Type a username into the **Search** field in the top-right corner to jump to a specific user quickly. ::: 6. Select the user(s) you want, then click **Synchronize to PBX**. The chosen users move into the **Synchronization List**. ![Selecting users and adding them to the synchronization list](/images/pbx/select-desired-ad-user.png) 7. For each user, pick an extension from the **Associate with Extension** drop-down list beside them. ![Assigning an extension to a synced directory user](/images/pbx/assign-ad-user-ext.png) :::tip To break a link, select the user and click **Disassociate** above the list. The user is separated from the extension once you save. ::: 8. From the **Delete the Extension when its associated user account is** drop-down list, pick the account state(s) that cause Cloud Voice to stop syncing a user and remove their extension. ![The drop-down for choosing which account states trigger extension deletion](/images/pbx/auto-delete-ext.png) | Option | What it does | | --- | --- | | Disabled | When an account is disabled in Entra ID, Cloud Voice stops syncing it and deletes the linked extension. | | Deleted | When an account is deleted in Entra ID, Cloud Voice stops syncing it and deletes the linked extension. | :::caution These states delete the linked extension, they do not just pause it. Choosing **Disabled** means an account that is only temporarily disabled in Entra ID (for example, a user on leave) loses its extension and any settings tied to it. Pick the state(s) that match how your organization manages accounts. ::: 9. Set the remaining synchronization options to suit your needs. ![Synchronization options for hand-picked users](/images/pbx/aad-options-2.png) | Option | What it does | | --- | --- | | Send Welcome Email automatically after an extension is created | Determines whether a Cloud Voice App welcome email goes out to each synced user. | | User Avatar Synchronization | Determines whether Entra ID user avatars are copied to their extensions. This is a one-way copy from Entra ID into Cloud Voice; afterward the extension avatar is read-only and users cannot change it from the Cloud Voice App. | 10. In the **Map** section, choose the user fields to synchronize and match each one to its Cloud Voice extension field. :::note - Use [Microsoft's user resource reference](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties) to identify the correct Entra ID field names. - Any field (or all extension fields) with mapping turned off is left out of the sync, and you can edit that information directly on the extension in Cloud Voice instead. ::: ![The Map section pairing directory fields with extension fields](/images/pbx/user-mapping.png) 11. Click **Save**. :::note - The first time you save synchronization settings, Cloud Voice runs the initial sync right away. - After that, you can [run a directory synchronization manually](/pbx/integrations/azure-ad/manually-perform-a-directory-synchronization/) or wait for the [scheduled automatic synchronization](/pbx/integrations/azure-ad/schedule-automatic-directory-synchronization/). ::: ## What happens after synchronization Your synchronization rule is now in place. On each run, Cloud Voice queries Entra ID against the rule and brings in the matching users along with any updated details. After a sync: - You can review the outcome in the **User Synchronization** section. ![A prompt reporting the synchronization result](/images/pbx/sync-prompt.png) - Extensions tied to Entra ID users carry a Microsoft label ![Microsoft label](/images/pbx/microsoft.png) and cannot be deleted by hand in Cloud Voice. - When field mapping is enabled, the following details on a linked extension are read-only in Cloud Voice. They can only be changed in Entra ID and are pushed back to the extension on the next sync: - First name - Last name - Email Address - Mobile Number - Job Title ## Next steps To let synced users sign in to the Cloud Voice App with their Microsoft credentials, set up Single Sign-On. For details, see [Allow Users to Log in to the Cloud Voice App with SSO](/pbx/integrations/azure-ad/allow-users-to-log-in-to-cloud-voice-app-uc-clients-with-sso/).