Webex Cloud-Connected UC Directory Service support

You can synchronize and manage users from cloud Active Directory (for example, Microsoft Entra ID) into on-premises or cloud hosted UC infrastructure like Cisco Unified Communications Manager (Unified Communications Manager) and Cisco Unity Connection (Unity Connection) with the Webex Cloud-Connected UC Directory Service. During synchronization, the system imports a list of users and associated user data from the Entra ID (or a similar Cloud Directory service) that is synchronized into the Webex Common Identity Service. You must select the Unified CM cluster from Control Hub that needs synchronization, select the appropriate Unified CM User ID field mapping, and then select the required synchronization agreement to perform synchronization.

Activate directory service

You must activate Directory Service for each cluster in Webex Cloud-Connected UC to allow synchronization and management of users from cloud into Unified Communications Manager.

By default, Directory Service is not enabled for all the onboarded clusters.
1

From the customer view in Control Hub, go to Services > Connected UC. On the UC Management card, click Inventory.

The list of cluster groups appears with the description, status, clusters, and nodes.

2

Click Details next to the cluster group to which the node belongs.

The Inventory page appears, showing the list of clusters belonging to the selected cluster group.

3

Click Details next to the cluster to which the particular product node belongs.

The Node name with the version, product, and status appears.

4

Click the ellipsis ⋮ icon next to Event History and choose Service Management.

The Service Management page appears with the list of services.

5

Use the toggle button to enable the Directory Service.

6

Click Submit.

Directory service

Directory service

Use the Directory Service card to synchronize users from cloud-based directories into Unified Communications Manager.

1

From the customer view in Control Hub, go to Services > Connected UC.

2

On the Directory Service card, click View clusters. The Directory Service page appears.

You can view the list of cluster details on this page.

View cluster details

View cluster details

From the Cluster selection page in Directory Service, choose a cluster to which you want to synchronize the user data with.

The Cluster selection page also provides the cluster details, status of provisioning, last synchronized state, the associated product, and the reason for failure, if any. You can select the local time zone; by default, the browser time zone is selected.

Cluster Details

Description

Cluster Name

The name of the cluster.

Status

Status of synchronization.

Last synced

Date of the last synchronization.

Product

Details of the product.
Provision Directory Service synchronization

Webex Cloud-Connected UC Directory Service synchronization allows you to import end user data from Webex Common Identity Service into the Unified Communications Manager database to display in the End User Configuration window.

Ensure that you don’t perform any provisioning operations during the scheduled Webex Cloud-Connected UC module upgrade.

In case you perform provisioning during module upgrade, steps 1, 2, or 3 might show error states after a certain period and the retry button appears after sometime. You can re-initiate provisioning by selecting the Retry button. Ensure that you verify the cluster status for upgrade completion before you retry provisioning.

1

From the Cluster selection page in Directory Service, choose a cluster that you want to provision for enabling synchronization.

2

Click Start Provisioning.

3

In the Field Mapping configuration window, ensure that the mapping chosen for the Unified CM User ID field uniquely identifies the user within the cluster after you start provisioning.

4

Choose the appropriate Unified CM User ID field mapping for synchronizing the user from Webex.

  • User ID field in Unified CM maps to email ID of the user in Webex.

  • Mail ID field in Unified CM maps to email ID of the user in Webex.

  • User ID field in Unified CM maps to email ID without domain part of the user in Webex.

    New user account will be created if the mapping cannot be done successfully for an existing user account in Unified CM. Email ID (or the ID part of the Email ID) of the user will be used as the unique identifier for the newly created user account.

5

Click Next.

6

Select an agreement from the drop-down list for creating a new synchronization agreement.

Once the new synchronization agreement is created, all the existing synchronization agreement(s) pointing to the on-premises directory are deleted. You can make changes to the new synchronization agreement after it’s created.

]
7

In the Agreement Preview section, review the agreement details (existing external LDAP directory details available in the Unified Communications Manager) before you start the synchronization.

You can view the following details:

  • Group information

  • Applied Feature group template with universal line and device templates

  • Line and mask details to synced phone numbers for inserted users

  • Newly provisioned users and their extensions

  • Standard User Fields to be Synchronized section. The following user fields are synchronized from Webex Common Identity Service into Unified Communications Manager:

    Unified Communications User Fields SynchronizedWebex Common Identity Service User Fields Synchronized

    User ID

    User Name is synchronized if the "User ID field in Unified CM maps to email ID of the user in Webex" option is chosen.

    Existing User ID (Mail ID in Unified CM) from the Unified Communications Manager database that matches with the Mail ID in Webex Common Identity Service if the "Mail ID field in Unified CM maps to email ID of the user in Webex" option is chosen.

    Mail ID without the domain part if the "User ID field in Unified CM maps to email ID without domain part of the user in Webex" option is chosen.

    First Name

    name.givenName

    Last Name

    name.familyName

    Display Name

    displayName

    Phone Number

    phoneNumbers.work

    Mobile Number

    phoneNumbers.mobile

    Mail ID

    emails

    Title

    title

  • Hostname or IP address of the directory server

Click Next to select the group filter.

8

From the Select groups drop-down list, select the specific group(s) that you want to synchronize. Click the Select all groups check box if you want to select all the user groups.

By default, all the users are synchronized. If you don't select any group, all the users and associated user data will be synchronized automatically.

For Nested groups in a directory, users must select the subset user group specifically during provisioning as they aren’t included by default with the parent group. You need to verify for any repetitive nesting (if any) to ensure that only the required users are included during provisioning.

Any modifications to the synchronization agreement, for example, removing a target user or group will not be propagated during periodic synchronization. You should disable the Directory Service for that cluster from Control Hub and then re-provision the cluster again with the new or modified synchronization agreement.

9

Click Next to prepare the synchronization process.

10

In the Enable Synchronization window, enable the synchronization once the system successfully copies the user data into a temporary storage space in Unified CM and a new synchronization agreement is created (after steps 1 and 2 as seen in the below screenshot).

11

The Download report download option allows you to view the results partially. To fetch the complete reports for the Unified CM cluster, execute the following CLI command: file get activelog /cm/trace/CIService/log4j/DryRunResults.csv. Here, the dry run result for Unified CM shows the following:

  • New Users—Users present on Webex Identity Service and not present in Unified CM Database

  • Users Matched—Users present on Webex Identity Service as well as in Unified CM Database

  • Mismatched Users—Users present in Unified CM Database but not present on Webex Identity Service

You can check the report and decide whether you want to retain the same list of users and add or delete users. Based on the decision, you can stop the process and revert the provisioning changes.

Any updates made to the user data in the cloud directory after Directory Synchronization will be updated in the next synchronization period. This is because the cloud directory is synchronized periodically once in a day.

12

After the synchronization agreement verification, click Preview in Unified CM to sign in to your on-premises infrastructure and make changes to the newly created synchronization agreement.

VPN access is required.

You can only edit the Group information for Unified CM. You cannot rename the agreement or modify any of the details.

13

Check the check box to agree to the terms that the synchronization agreement is reviewed and verified in Unified CM.

14

Click Enable Synchronization to proceed with the synchronization.

During synchronization, you won’t be able to perform any action until completion. Once the synchronization is completed for a particular cluster, the Directory Service page lists this cluster with a Provisioned state. At this point, you've successfully authorized Entra ID to provision and synchronize Webex users into UC infrastructure and completed the steps to set up synchronization.

15

After the initial provisioning is completed, periodic synchronization happens every 24 hours. Any changes made in the cloud directory will be propagated to the clusters during this period.

You must enable synchronization within 20 hours from the time the new agreement is created. LDAP synchronized users become inactive and removed after 24 hours of inactivity. Users won’t be able to log in and use the Unified CM services.

After the Entra ID provisioning is completed for a certain cluster, you cannot create any new synchronization agreements or modify any configuration settings for the same cluster except for the group settings. If you want to create a new synchronization agreement for the same cluster, you should go to the Service Management page and disable the Directory Service. You can then create a new agreement for provisioning.

If synchronization fails for any reason, the latest provisioning changes will reflect in the next synchronization period the next day.

  • If you are using Entra ID IdP during SSO authentication after successful provisioning, ensure that you configure the right Claims in the Entra ID IdP. For example, during provisioning, if option 1 is selected for the userid mapping, ensure that user.userprincipalname is set as the UID in the ‘Additional Claims’ section.

  • The following attributes are synced from Webex Common Identity Service into Unified Communications Manager:

    Unified Communications User Fields SynchronizedWebex Common Identity Service User Fields Synchronized

    User ID

    User Name is synchronized if the "User ID field in Unified CM maps to email ID of the user in Webex" option is chosen.

    Existing User ID (Mail ID in Unified CM) from the Unified Communications Manager database that matches with the Mail ID in Webex Common Identity Service if the "Mail ID field in Unified CM maps to email ID of the user in Webex" option is chosen.

    Mail ID without the domain part if the "User ID field in Unified CM maps to email ID without domain part of the user in Webex" option is chosen.

    First Name

    name.givenName

    Last Name

    name.familyName

    Display Name

    displayName

    Phone Number

    phoneNumbers.work

    Mobile Number

    phoneNumbers.mobile

    Mail ID

    emails

    Title

    title

  • Any updates made to the user data in the cloud directory after Directory Synchronization will be updated in the next synchronization period. This is because the cloud directory is synchronized periodically once in a day.

  • Single sign-on (SSO) must be used for logins. This document only covers single sign-on (SSO) integration.

  • Before reprovisioning any cluster from Control Hub, we recommend that you manually stop the Dirsync Service from the Cisco Unified Serviceability GUI.

  • After reprovisioning, if you see that the users marked as Mismatched Users are the same as New Users (users sharing the same mail ID), we recommend that you wait for a maximum of 48 hours for the synchronization changes to take effect. If you want to see the updated changes immediately, ensure that you perform the following before reprovisioning:

    1. Disable the Directory Service from the Service Management page in Control Hub.

    2. Delete the Webex Common Identity Service synchronization agreement from Unified CM.

    3. Disable the Enable Synchronizing from LDAP Server check box in the LDAP System Configuration page in Cisco Unified CM Administration user interface.

    4. Delete the end users from the End User window.

    5. Enable the Directory Service from the Service Management page in Control Hub.

Provision status

Provision status

On the Directory Service dashboard, you can view and track the status of your cluster and review errors.

The following table lists the provision status, description, and the corresponding actions.

Table 1. Provisioning Status

Provision Status

Description

Processing

The provisioning is in progress.

Action Required

Take necessary steps if there's any manual intervention required for a particular cluster. For example,

  • If you want to continue or abandon synchronization after dry run.

  • After the new agreement is created, check for any notifications, and take necessary actions as required.

Error

If there's any action required in the 'Enable Synchronization' wizard, check them and if required, take necessary actions.

In the event of errors during any stages of provisioning, the administrator should audit the Events History page in Cisco Webex Control Hub for the service: Directory Service. This helps you to isolate, debug, and troubleshoot the possible issues. To access events, see Access the Event History for Hybrid Services.

For more information on the various events types and their details, see the 'Events and Possible Resolutions' table below.

Provisioned

The cluster provisioning is complete.

Not provisioned

The cluster provisioning hasn’t started yet.
Table 2. Events and Resolutions

Events

Action Required

Periodic Sync Failed

Ensure that you wait for the completion of next day's periodic synchronization. Verify that the synchronization is completed successfully. If the issue persists, contact Cisco TAC support.

Data Copy Failure

Click Retry button to continue data transfer. If the issue persists, contact Cisco TAC support.

Sync Agreement Failure

Click Retry button to retry the synchronization agreement creation. If the issue persists, contact Cisco TAC support.

Skipping Periodic Sync

No action required.

Data Transfer has Failed

Click Retry button to continue data transfer. If the issue persists, contact Cisco TAC support.

User Sync Mismatched

Check the Directory Synchronization logs in Unified CM for errors in User synchronization or contact Cisco TAC support for further assistance.

Users Provisioned Successfully

No action required.

Periodic Sync Data Transfer Successful

No action required.

Failed to fetch user details of some of the selected groups from Webex Common Identity.

Navigate to the Dashboard and select the cluster to get the failed groups details by clicking on the download link provided. Verify whether the users are present in Webex Common Identity and click Retry. Contact Cisco TAC support for further assistance.

Failed to fetch user details of all the selected groups from Webex Common Identity.

Click Retry button to continue data transfer. If the issue persists, contact Cisco TAC support for further assistance.
Troubleshooting synchronization issues

This section provides the necessary information and solutions to resolve some of the common issues that you might face during the various stages of synchronizing users from Control Hub into the Unified Communications Manager database.

Mismatched users

If you see mismatched users, enable synchronization within 20 hours after the new agreement is created. The existing users are marked inactive and are deleted from Unified CM after 24 hours of inactivity.

Error—Data Copy Failed. Please Retry

  • Communication between Cloud-Connected UC and Webex cloud is disrupted or unable to fetch user data from Webex cloud.

    Solution: To confirm whether your connectivity is successful to Cisco Cloud, check the status to these services at: https://status.webex.com/. Click Retry.

  • Communication between Cloud-Connected UC and Unified CM is disrupted or unable to push user data to Unified CM database.

    Solution: Check the network connectivity between Cloud-Connected UC and Unified CM and click Retry. If the issue persists, contact Cisco TAC support.

Error—Failed to Create Synchronization Agreement. Please Retry

  • Communication between Cloud-Connected UC and Unified CM is disrupted or unable to push the synchronization agreement data into the Unified CM database.

    Solution: Check the network connectivity between Cloud-Connected UC and Unified CM and click Retry. If the issue persists, contact Cisco TAC support.

  • Synchronization agreement wasn't created successfully.

Error–Failed to Enable Directory Synchronization. Please Retry

  • Communication between Cloud-Connected UC and Unified CM is disrupted, and the Cisco DirSync Service isn't triggered.

    Solution: Check the network connectivity between Cloud-Connected UC and Unified CM and click Retry. If the issue persists, contact Cisco TAC support.

Unable to get Synchronization agreement details. Please try after some time.

Communication between Cloud-Connected UC and Unified CM is disrupted.

Solution: Check the network connectivity between Cloud-Connected UC and Unified CM and click Retry. If the issue persists, contact Cisco TAC support.

Failed to fetch user data for selected groups

During first time provisioning, you might encounter issues in downloading user data from any of the specific group(s) that you had selected for synchronization. On the error message, click the download link to view details of the failed group information.

You can also download failed group information for clusters that are already provisioned from the Events History page in Cisco Webex Control Hub. Navigate to the Dashboard and select the cluster to get the failed groups details by clicking on the download link provided. Verify whether the users are present in Webex Common Identity and click Retry. Contact Cisco TAC support for further assistance.

Known issues and limitations for Webex Cloud-Connected UC directory service synchronization

Known issues and limitations for Webex Cloud-Connected UC directory service synchronization

If you're experiencing an issue with this feature, check to see if it's something that we already know about and have a recommended workaround.

  • You can disable the Directory Service for a cluster from Control Hub and then reenable the cluster again. We recommend that you wait for at least 60 seconds before activating the Directory Service for synchronization.

  • After deletion, in case you want to onboard the same Unified CM cluster to the organization again, you must first disable the Directory Service and then reprovision the same cluster.

  • During provisioning, the group details list doesn't populate due to synchronization issues with Webex Common Identity Service. Users are recommended to abandon provisioning and retry after some time.