Azure AD: 8x8 Single Sign-On (SSO) and User Provisioning (SCIM) Configuration

Updated: 09/21/2024

Objective

Configure Microsoft Azure SAML 2.0 SSO for Admin Console.
Instructions and information covered in this article include:

Applies To

  • 8x8 Admin Console
  • Microsoft Azure Active Directory (Azure AD)
  • Single Sign-On (SSO)
  • User Provisioning (SCIM)

Features

  • SSO allows users to authenticate into any 8x8 application using their corporate Azure AD credentials.
  • User Provisioning allows:
    • Users from Azure AD to be created in 8x8 automatically without the need to re-key common user details.
    • Updates to user details made in Azure AD to be automatically pushed to 8x8.
    • Deactivation of users in 8x8 by disabling their account in Azure AD.
    • Existing users created directly in Admin Console can be linked to their Azure AD counterparts.

Prerequisites

To use the 8x8 Azure AD Integration you need:
  • Any 8x8 X Series subscription
  • Azure Active Directory of any subscription level
Note: On-premise Active Directory is not supported directly, but can be used in a “hybrid” Azure AD environment where users are synced from on-premise AD to Azure AD via an Azure AD Connect agent.

Limitations

Known limitations for the current release:
  • Assignment of X Series licenses must still be completed from Admin Console, either individually or in bulk using a CSV upload.
  • The user’s phone and extension numbers set in Admin Console cannot be synced back to Azure AD through the 8x8 app. This is due to limitations of Microsoft’s implementation of User Provisioning which does not allow for data to be retrieved back into Azure AD.
  • The user's Site cannot be modified once it is set.
  • Deleting a user in Azure AD does not delete that user in Admin Console. You must delete the user manually from Admin Console.

Considerations for Existing Deployments

Several factors to consider for existing deployments include managing user names and separating Single Sign-On from user provisioning.

Usernames

If you already have several 8x8 users set up in Admin Console and their usernames (as shown in Admin Console) are different from their usernames in Azure AD, please read this section carefully.
In order to link existing 8x8 users with their Azure AD equivalents, they must have the same username in both Azure AD and Admin Console. If your users already log in to 8x8 apps with their Azure AD credentials via SSO, then their 8x8 usernames can be updated to match with no disruption to the users. However, if your users currently log in with their 8x8 username (for example, they are not using their Azure AD credentials via Single Sign-On) then we strongly recommend enabling SSO and switching your users over to logging in with their Azure AD credentials via Single Sign-On before enabling user provisioning. This allows alignment of the usernames without further disruption and also provides the benefits of Single Sign-On.

Separation of Single Sign-On from User Provisioning

If you already have an established user base using an earlier version of the application for Single Sign-On and you want to phase in user provisioning with a smaller subset of users, you can install a second instance of the 8x8 app into your Azure AD environment, with one configured for SSO and the other configured for User Provisioning. With this scheme you can assign users or groups to the two apps independently.

Procedure

Configuring User SSO Login

Below are instructions for configuring your Azure AD service and 8x8 Admin Console for Microsoft user login to your 8x8 applications. If you have already configured Azure SSO login to 8x8 applications, and want to apply SCIM user provisioning to 8x8 Admin Console, skip to User Provisioning Configuration (SCIM).

Add the 8x8 App to Azure

  1. Log in to the Azure Active Directory admin center.
  2. In Enterprise applications click New application.
    clipboard_ee0b3ee20539236489458a5c87ba22579.png
  3. In the Azure AD Gallery, search for 8x8. The icon will have a red background with white text. 
    clipboard_eae4cfad8ca082d69da2b0175709c4c28.png
  4. Select the 8x8 app, optionally rename it, and click Create.
  5. Configure Single Sign-On by following the instructions belowNote: For reference, Microsoft has an older, less up-to-date article regarding this process, here: Tutorial: Azure AD SSO integration with 8x8.
    clipboard_ecbdaf0323cc7b2b0abeeeff496b8a2a7.png

Azure SSO Configuration

  1. In the Azure Active Directory admin center > Enterprise applications, click on 8x8 and click Single sign-on.
  2. Click SAML.
    clipboard_e58d1f539f60b2fdb9ba0346b6156cffd.png
  3. In Basic SAML Configuration, click Edit.
    clipboard_e49527391480d266f03910dc48cb697c3.png
In Basic SAML Configuration, perform the following steps:
  1. In Identifier (Entity ID), click Add identifier.
  2. Add the following URL into the blank field. This entry should be marked as Default, and there should be no other Identifier entries.
    • https://sso.8x8.com/saml2
      clipboard_e44715983302b434efe1461af7f07980e.png
  3. In the Reply URL box, click Add reply URL.
  4. Enter the same URL as for the Identifier. This entry should be marked as Default, and there is no need to modify the Index field.
    • https://sso.8x8.com/saml2
      clipboard_ecd75ccf032b360fab4e092799c68e344.png
  5. Click Save.
Your Basic SAML Configuration should appear as in the screenshot below:
clipboard_e845362482544142b3984c1bcb3ed4883.png
  1. Next, in SAML Signing Certificate > Certificate (Base64) click Download, and save the 8x8.cer certificate file onto your computer. You'll apply the certificate later, when configuring Single Sign-On in the 8x8 Admin Console.
    • Critical: Use only the Base64 certificate for configuring Single Sign-On Integration in the 8x8 Admin Console. User single sign-on will fail if you apply other available certificate types.
      clipboard_e0160ee33121aeed67a1c07ea38fd64c3.png
  2. In Set up 8x8, click on Configuration URLs to expand the section (as needed).
  3. Individually click the Copy to clipboard icon for each of the URLs you will use, and paste them into a text editor. You'll need these URLs later, when configuring Single Sign-On Integration in the 8x8 Admin Console.
    • Login URL
    • Azure AD Identifier
    • Logout URL
Important: The Logout URL is optional for 8x8 SSO. If it is applied in 8x8 Admin Console, users logging out of 8x8 services will also be logged out of all Microsoft services. If users or administrators receive a Microsoft error code AADSTS750054 during logout of any 8x8 application, replace the default tenant-specific Azure Logout URL in the Sign-out page URL field of your 8x8 Admin Console Configuration with the following URL:
  • https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0
clipboard_e9b1696c14d3a1004c9a5033b88f687a3.png

Assigning Azure AD Users

  1. In the Azure portal, select Enterprise applications, and then select All applications.
  2. In the applications list, click 8x8.
    clipboard_eda28e69250e0d30126c38f87b22084d4.png
  3. In Manage, click Users and groups.
  4. Click Add user/group.
    clipboard_ed80ef4707c83c240b4cee49b7d6278c1.png
  5. Click None Selected to open the Users and groups selection dialogue.
  6. Click on the users and/or groups you wish to log into 8x8 services using SSO.
  7. Click Select and then Assign to complete the assignment of the 8x8 app to users/groups.
    clipboard_e48f8e7e358fef056347d07f92e4d5ad0.png

8x8 Admin Console Configuration

  1. First, log in to the 8x8 Admin Console.
  2. From the Home page, click Identity and Security.
    clipboard_e70dbc70ffdaefee2247adfe02672c7f4.png
  3. In Single Sign-On Integration (SSO), click the slider to enable
    clipboard_e197b8335ab436a998ef5c0b405d02b2b.png
     SSO integration.
  4. Select Microsoft Azure AD.
    clipboard_eaf8c5278585c5f13a7e0698794711e53.png
  5. Now you'll apply the URLs and signing certificate that you previously obtained from the 8x8 app in Azure:
    1. Copy and paste the Azure Login URL to the 8x8 Sign-in page URL field.
    2. Copy and paste the Azure Azure AD Identifier to the 8x8 IDP Issuer URL/URN field.
    3. (Optional) Copy and paste the Azure Logout URL to the 8x8 Sign-out page URL field.
    4. In Certificate in use, click on Click to attach and select the Base64 certificate file that you previously downloaded from Azure.
    5. Click Save to apply your 8x8 SSO configuration.
Important: If users or administrators receive a Microsoft error code AADSTS750054 during logout of any 8x8 application, replace the default tenant-specific Azure Logout URL in the Sign-out page URL section with the following URL:
  • https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0
clipboard_e5f8285832b77e0fed18b94b01a7e3a48.png

User Provisioning Configuration (SCIM)

Below are instructions for configuring user provisioning from Microsoft Azure AD to 8x8 Admin Console.
User provisioning (SCIM) from Azure to 8x8 is not required, but aids in user administration. Without this automated user provisioning, administrators must manually create and manage users in both Azure and 8x8 Admin Console.
IMPORTANT:
New users provisioned through any SCIM process – such as through Azure or Okta – must be manually assigned an 8x8 X Series license in the 8x8 Admin Console. The SCIM user provisioning process does not apply X series licenses to users.
ALSO:
New users who are provisioned through SCIM will not automatically be made visible in the Company directory. This must also be manually configured for the user(s) in the 8x8 Admin Console.

8x8 Admin Console

  1. First, log in to the 8x8 Admin Console.
  2. From the Home page, click Identity and Security.
    clipboard_e50bf3764504b1fb3cf275f4378a68c88.png
  3. In User Provisioning Integration (SCIM), click the slider to enable
    clipboard_ebcb55bfb3dea1fec335aea32aacb56c7.png
     SCIM integration.
  4. Select Microsoft Azure AD.
  5. In the Microsoft Azure AD User Provisioning section, click the Copy button
    clipboard_e99a48d943ed6da05acbf2396e0bb437f.png
     for each of the following sections and paste the copied information into a text editor. You'll apply this information in Azure to enable provisioning of users to 8x8:
    • 8x8 URL
    • 8x8 API Token
      clipboard_e8ab3d38a80feef7f6cf3ac89b11f69e5.png
  6. Click Advanced settings to expand that section.
  7. Click the drop-down menu and select the appropriate user retrieval option:
    • All users
      • Retrieves users created in and synced from Azure and users created directly in 8x8 Admin Console, thereby allowing Azure to take control of 8x8 user profiles if the login IDs in both locations are identical.
    • Only users created by the identity provider
      • Limits user retrieval to only those users created in and synced from Azure.
        clipboard_ee21dab94794326b1915423d0d6857b45.png
  8. Click Save to complete your changes in the 8x8 Admin Console.

Azure Active Directory

  1. Return to the Azure Active Directory admin center.
  2. Navigate to the Provisioning blade of your installed 8x8 app.
    clipboard_e0e926ef36f5ce30d650e95a2951cb1b4.png
  3. Click Get started.
    clipboard_ea7c34409f31530bc8251f7cb1ba468f4.png
  4. Change the Provisioning Mode to Automatic.
  5. Paste the 8x8 URL value you copied from 8x8 Admin Console in the previous section into the Tenant URL field.
  6. Paste the 8x8 API Token value you copied from 8x8 Admin Console in the previous section into the Secret Token field.
    clipboard_e283ab2e18d6e1d521e492a8118322175.png
  7. Click Test Connection. You should receive a success confirmation message.
  8. Click Save to complete this configuration.
    clipboard_ea3880125c752f372b3793b5e136fee58.png
User Provisioning Configuration Options
Create a user
To create a user in 8x8, assign them to the 8x8 App. New users will appear in Admin Console when the next Azure AD sync cycle runs.
Note: 8x8 recommends that each AD user to be assigned to 8x8 has their Office attribute (physicalDeliveryOfficeName) set to the name of the 8x8 Site they belong to. For this, you can simply copy the site name from Admin Console into.
Azure AD provisioning activity typically runs on a 40 minute cycle. Please allow one hour between assigning a user to the 8x8 app before the user appears in Admin Console.
Any unlicensed 8x8 users are visible along with their contact number to the licensed users in their corporate directory. If you do not intend to assign an 8x8 license to the created user then no further action is required.
To configure a user with an X Series service you must sign into Admin Console and assign an X Series license to the user. Then edit the user individually , or in bulk, using the Edit feature.
User changes
Whenever an Azure AD user that has been assigned to the 8x8 app is updated, Azure AD automatically pushes any changes to 8x8.
Deactivate and activate a user
If a user has their Block sign in (isSoftDeleted) attribute set to Yes in Azure AD, they are deactivated in 8x8 and are no longer able to make or receive phone calls (except Emergency calls). They are also not able to log in to any applications. Existing login sessions expire within half an hour. The user is not deleted and they retain their X Series license and settings.
When you unblock a sign-in for a user in Azure AD it also re-activates that user in 8x8.
Delete a user
Deleting a user in Azure AD is a two-stage process:
  1. Initial deletion is a soft-delete which moves the user to the “Deleted users” blade in Azure AD. This causes the user to be deactivated in 8x8 (This is similar to blocking sign-in from Azure AD).
  2. When a user is fully deleted from Azure AD, nothing further happens to the 8x8 user. If the user had not already been deactivated, then the user is deactivated at this point, but not deleted. It is not possible to delete an 8x8 user via the integration, you need to do this individually in Admin Console.
Administration restrictions in 8x8 Admin Console
When a user is created in 8x8 via the Azure AD app, 8x8 considers the user to be owned by Azure AD. This activates some administration restrictions in Admin Console, specifically preventing any changes to the key user attributes that are mastered in AD:
  • Username
  • First name
  • Last name
  • Email address
  • Deactivation and Activation
These restrictions are there to ensure your 8x8 users do not become out of sync with Azure AD.
Unassign users from the 8x8 app
When a user is unassigned from the 8x8 app in Azure AD, they are deactivated in the 8x8 app but not deleted.
Link an existing 8x8 user to Azure AD
If you create a user in 8x8 Admin Console directly, and there is an equivalent user in Azure AD, then assigning the Azure AD user to the 8x8 app in Azure AD is enough to link them providing the following criteria are met:
  • Their Username in Admin Console matches their User name (userPrincipalName) in Azure AD.
  • Upon initial assignment to the 8x8 app, Azure AD checks if the user’s attributes are in sync and updates the 8x8 user accordingly. At this point, Admin Console considers the user to be owned by Azure AD and prevents any changes to those attributes that are mapped from Azure AD. This restriction avoids data inconsistency by enforcing that changes are only made to the master data source of the user.
Disable the integration
If you want to temporarily disable the integration, navigate to the app in Azure AD. Click Stop provisioning and OK to confirm. 
clipboard_ea34d1ca06ade9fb95eec226f08e0001d.png
Site
Each 8x8 user created through the 8x8 Azure AD app must be associated with a Site before they can be assigned an X Series license. To do this, you need to ensure that the Office (physicalDeliveryOfficeName) attribute contains the exact name of one of your Sites from Admin Console.
In the default installation, Site is set from the Office (physicalDeliveryOfficeName) attribute in AD, but you can change this in app mappings to suit your AD environment if required.
If your 8x8 installation has only one Site, you can opt to hard-code its name in the 8x8 application's attribute mappings using a “Constant” mapping type. This avoids the need to set the Office (physicalDeliveryOfficeName) attribute for each user.
Note: A user's site cannot be modified once it is set. If you change the name of any of your Sites in 8x8 Admin Console, the synchronization of users is broken until their Office (physicalDeliveryOfficeName) attribute matches in AD.
Contact numbers
In the default installation, the AD user’s Office phone (telephoneNumber) and Mobile phone (mobile) attributes are passed to 8x8 as contact numbers and will be displayed to other 8x8 users in the following places:
  • Company directory of 8x8 Work for Desktop and Mobile
  • Contact Center directory
  • Switchboard Pro directory
Note: Contact numbers are not displayed in the directory of physical desk phones.

User Provisioning Attribute Mappings

Default attribute mappings

This table shows the default set of attribute mappings for user provisioning.
Azure AD Attribute Azure AD Portal Name System for Cross-domain
Identity Management (SCIM) Attribute
8x8 Admin Console Name
userPrincipalName User name userName Username
objectID Object ID externalId Not visible in Admin Console
mail Not visible in AD portal emails[type eq "work"].value Email
Not([IsSoftDeleted]) Block sign in active User is greyed out
Last name First name name.givenName givenName
First name Last name name.familyName surname
jobTitle Job title title Job title
department Department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department Department
mobile Mobile phone phoneNumbers[type eq "mobile"].value Personal contact number
telephoneNumber Office phone phoneNumbers[type eq "work"].value Not visible in Admin Console
physicalDeliveryOfficeName Office urn:8x8:scim:schemas:extension:8x8user:2.0:User:site Site

Advanced attribute mappings

This table displays additional attributes that are available but not mapped by default. Instructions for configuration of advanced mappings is outside the scope of this guide.
System for Cross-domain
Identity Management (SCIM) Attribute
Suggested Azure AD attribute Notes
locale PreferredLanguage PreferredLanguage may be set through the AzureAD powershell module
timezone User extension attribute