Configure Microsoft Entra ID for Genesys Cloud SCIM (Identity Management)

To use Genesys Cloud SCIM (Identity Management), configure Microsoft Entra ID to sync user entities to Genesys Cloud. In Microsoft Entra ID, create an enterprise application that you configure to work with the SCIM APIs. Then assign users and groups to this enterprise application. 

• Token generation
• Application setup
• Provisioning
• Mappings (optional)
• Users and groups
• Scope (optional)

Token generation

Generate a token to use for Provisioning.

1. Open Postman.
2. Import the Genesys Cloud Client Credentials collection for the appropriate collection format from the following links:
   • Collection Format v1: https://www.getpostman.com/collections/06d3bac569ec729f0a59
   • Collection Format v2: https://www.getpostman.com/collections/b4f0048c7fc833b914c2
3. Replace {{environment}} in the POST API call with the login URL where your Genesys Cloud organization is located, for example, https://login.mypurecloud.com/oauth/token. For a list of regional URLs, see Platform API (Genesys Cloud Developer Center). 
4. Under Authorization, add the following information:
   1. Username: Enter the Client ID from the Genesys Cloud OAuth client you created.
   2. Password: Enter the Client Secret from the Genesys Cloud OAuth client you created.
5. Click Send. Your access token appears in the response body. Use this token when you provision Microsoft Entra ID. See the Provisioning section.

Application setup

Add the Genesys Cloud for Azure application.

1. Log in to Microsoft Entra ID.
2. In the left column, click Enterprise applications.
3. Click New application. 
4. Search for and click Genesys Cloud for Azure.
5. Click Create. 

Provisioning

Enter admin credentials and test the connection.

1. In the left column under Manage, click Provisioning.
2. Click Get Started.
3. From the Provisioning Mode menu, select Automatic.
4. Under Admin Credentials, add the following information:
   1. Tenant URL: Enter the URL of the SCIM endpoint: https://{domain}/api/v2/scim/v2/.

      Use the domain associated with the location of your Genesys Cloud organization:

      Genesys Cloud region	Domain
      Americas (Canada)	api.cac1.pure.cloud
      Americas (Sao Paulo)	api.sae1.pure.cloud
      Americas (US East)	api.mypurecloud.com
      FedRAMP	api.use2.us-gov-pure.cloud
      Americas (US West)	api.usw2.pure.cloud
      Asia Pacific (Mumbai)	api.aps1.pure.cloud
      Asia Pacific (Seoul)	api.apne2.pure.cloud
      Asia Pacific (Sydney)	api.mypurecloud.com.au
      Asia Pacific (Osaka)	api.apne3.pure.cloud
      Asia Pacific (Tokyo)	api.mypurecloud.jp
      EMEA (Dublin)	api.mypurecloud.ie
      EMEA (Frankfurt)	api.mypurecloud.de
      EMEA (London)	api.euw2.pure.cloud
      EMEA (Zurich)	api.euc2.pure.cloud
      EMEA (UAE)	api.mec1.pure.cloud

   2. Secret Token: Enter the bearer token. The bearer token is the access token returned when you made an API call in Postman. See the Token generation section.
5. Click Test Connection.
6. Click Save.
7. Under Status, click On next to Provisioning Status.
8. Click Save.

Mappings (optional)

The Microsoft Entra ID application automatically configures mappings for groups and users. You can modify these mappings or add new attributes to the existing mappings.

1. Under Mappings, click the name of a mapping.
2. Delete, edit, or add a new mapping.

   This table shows the mappings of Microsoft Entra ID fields to SCIM fields.

   Note:

   • The mappings allow a one-way push from Microsoft Entra ID to Genesys Cloud. For a table that shows the relationship between SCIM and Genesys Cloud fields, see SCIM and Genesys Cloud field mappings.
   • If you are using Microsoft Teams integration with SCIM, then you must set additional field mappings to view the Microsoft Teams badge, view the external presence, and enable click-to-dial. For more information, see Configure the Microsoft Teams Integration.
   • When you synchronize data with Microsoft Entra ID, attempting to clear a previously synced field by mapping it to an empty value will not work. Microsoft’s sync process ignores empty values and leaves the original data intact in the SCIM implementation. This limitation requires careful planning to avoid persistent and unwanted data. Genesys recommends performing a pilot test to minimize potential errors with a small subset to verify configuration and attribute mapping. Any required modifications may involve manual adjustments for the synced test users.
   Show102550100entries

   field	SCIM field	Required	Notes
   userPrincipleName	userName	Yes	This field generates the main email address in Genesys Cloud.
   Not([IsSoftDeleted])	active	Yes
   displayName	displayName	Yes
   jobTitle	title	No
   manager	scimEnterpriseUser. manager.value	No	Full URN: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value
   department	scimEnterpriseUser. department	No	Full URN: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
   {Customer-dependent field}	scimEnterpriseUser. division	No	This field is the name of the division in SCIM and is mapped to the Genesys Cloud divisionId. This field does not create a division.
   mail	emails[type eq "work"].value	No
   StripSpaces([telephoneNumber])	phoneNumbers[type eq "work"].value1	No	You can map to a phone number with an extension or to an extension only. See the Extensions section.
   {Customer-dependent field}	phoneNumbers[type eq "work2"].value1	No	You can map to a phone number with an extension or to an extension only. See the Extensions section.

   Showing results

   1 - 10 of 25
   ¹ For Microsoft Entra ID fields, use StripSpaces with phone number mappings, for example, phoneNumbers[type eq "mobile"].value == StripSpaces([mobile]). The StripSpaces function standardizes the format of telephone numbers in Microsoft Entra ID. Standardization ensures that telephone numbers match the format of telephone numbers in Genesys Cloud and prevent erroneous user updates from occurring.

   Extensions

   You can set phone number fields to use phone numbers with extensions or extensions only. 

   1. Under Mapping type, select Expression.

   2. In the Expression box, add an expression for a phone number with an extension or an extension only.
      Important: Use any Microsoft Entra ID attribute in place of [telephoneNumber] or [attributeThatContainsExtension].

      • Extension only

        Join(";ext=", "tel:", StripSpaces([attributeThatContainsExtension]))

      • Phone number with an extension 

        IIF(IsNullOrEmpty(StripSpaces([attributeThatContainsExtension])), 
            StripSpaces([telephoneNumber]), 
            Join(";ext=", 
                Append("tel:", StripSpaces([telephoneNumber])),  
                StripSpaces([attributeThatContainsExtension])
            )
        )

   3. For new mappings, in the Target attribute box, add the SCIM field for the phone number attribute, for example, phoneNumbers[type eq "work2"].value.
   4. Click Ok.

   

3. Click Save.

For more information, see Customizing user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID in the Microsoft Entra ID documentation.

Users and groups

Add users and groups that you want to sync from Microsoft Entra ID to Genesys Cloud. 

1. In the left column under Manage, click Users and groups.

   A list of users and groups in your Microsoft Entra ID appears.

2. Click Add user.
3. Click Users and groups.
4. Select or search for any users and groups that you want to add to this application.
5. Click Select. 
6. Click Assign. 

For more information, see Managing user account provisioning for enterprise apps in the Microsoft Entra admin center in the Microsoft Entra ID documentation and What causes Genesys Cloud to change the status of a Microsoft Entra ID user to inactive or to delete a user?.

Scope (optional)

By default, Microsoft Entra ID sets the scope to Sync only assigned users and groups. You can change the scope so that Microsoft Entra ID syncs all users and groups to Genesys Cloud.

1. In the left column under Manage, click Provisioning.
2. In the Scope menu under Settings, select Sync all users and groups. 
3. Click Save.

The SCIM APIs now automatically sync user entities from your enterprise application to Genesys Cloud.

For information about Genesys Cloud SCIM (Identity Management), see About Genesys Cloud SCIM (Identity Management) and Genesys Cloud SCIM (Identity Management) overview (Genesys Cloud Developer Center).