17 Apr 2023

The goal of this document is to outline the steps needed to automate end-user management in the Voice product suite of Enreach for Enterprises. The automation is implemented by utilizing the built-in provisioning tools in the Microsoft Azure AD.

This document is applicable starting from Voice Portal version 2.136 and onwards.

Introduction to Azure AD integration

Enreach provides identity management service, which allows customers to enable single sign-on authentication (SSO) to the end users, using existing Azure AD instance. Customers can automate end-user provisioning and control the data flow towards Enreach cloud services.

Integration from Azure AD is implemented using the SCIM protocol as provided by Microsoft Azure.

Voice Portal by Enreach (or “Portal”) is the OSS/BSS platform at Enreach for Enterprises. It is the engine that orchestrates the service provisioning in the Enreach Voice product family. It is also the endpoint for the SCIM integrations with Azure AD.

Voice Portal by Enreach provides the following integration models for user accounts:

automatic user identity synchronization for SSO (single sign-on with Azure AD credentials)
automatic user data synchronization (making user information available in Enreach services)
automatic user provisioning (create and update users as they are managed in AD)
contact directory synchronization (copy user information from AD to the internal phone book).

The level of integration is defined by configuration in Voice Portal.

Customer must create two AD user groups that will be used for different purposes;

AD group for user accounts provisioned as active users in Enreach Voice platform
AD group for user accounts synchronized into the contact directory. The contact directory group is optional and needed only if the selected users need to be maintained in the internal phone book.

What is SCIM?

SCIM (System for Cross-domain Identity Management) is a protocol used for automating the process of user provisioning and deprovisioning in enterprise applications. In Azure AD, SCIM is used to synchronize user accounts between Azure AD and the identity management service in Voice Portal by Enreach.

When SCIM is enabled in Azure AD, administrators no longer need to manually create and manage user accounts in Enreach cloud, as changes made in Azure AD will be automatically reflected to Voice Portal.

SCIM works by establishing a connection from Azure AD to the SCIM endpoint in Voice Portal. When a change is made to a user account in Azure AD, such as a user being added or removed from a group, Azure AD sends a SCIM message to Voice Portal, which then uses this message to create, update, or delete the corresponding user account in the platform.

SCIM provides a standardized way of automating the user provisioning process, which can help to reduce errors and save time for administrators. By enabling SCIM in Azure AD, organizations can improve the security and efficiency of their identity management processes.

Description of the Azure SCIM implementation is available form Microsoft:

What is SSO?

SSO (Single Sign-On) is a mechanism that allows end-users to authenticate themselves once and access multiple applications without the need to repeatedly enter their credentials. In the context of Azure AD and Enreach Voice services, SSO refers to the ability of users to access Enreach cloud applications using the same credentials as in corporate applications.

Overview of the provisioning process

The following illustration introduces the components involved in the integration model.

Microsoft Azure AD provides tools for enabling automatic provisioning for enterprise applications. Voice Portal is introduced as an enterprise application and further configured for automatic provisioning.

Identity management in Voice Portal

In the following chapters we explain the SCIM integration models available in Voice Portal.

In general, there are two categories how the AD users can be provisioned to the Enreach Voice platform:

user service provisioning, including
- automatic identity synchronization
- automatic user data synchronization
- automatic user provisioning of new users
contact directory provisioning
- user data will be copied as contact cards to the internal phone book.

The corresponding AD groups must be created. The names of these groups are then configured in the Voice Portal and the group membership dictates how the AD user account is processed in the synchronization process.

Automatic identity synchronization

Automatic identity synchronization refers to the lowest level of SCIM integration. Only the technical identity (“objectId”) of an end user is shared to Voice Portal. This attribute is required by the Enreach identity service when enabling the SSO to the end users.

The users in Azure AD are mapped by their username, which must use the email address format. In practice, the “userPrincipalName” attribute in Azure AD must be the email address of a user.

Automatic user data synchronization

In automatic user data synchronization, in addition to the identity information, the SCIM protocol synchronizes the selected AD attributes to the corresponding user data fields in Voice Portal, and thus makes this data available to the Enreach Voice services.

Microsoft Azure provides tools for mapping the required AD attributes to SCIM data objects.

Respectively, Voice Portal provides tools for mapping the required SCIM data attributes to the required data fields in Voice Portal user objects.

Automatic user provisioning

In the highest level of SCIM integration, the end users get automatically created and updated to Enreach services as they are managed in Azure AD. The Azure AD administrator has full control of which users and what data is reflected to Enreach cloud.

In the current SCIM implementation, the users are not automatically deleted from Enreach cloud. They are marked as inactive (“soft-deleted”) and must be processed manually.

Automatic contact directory synchronization

In automatic contact data synchronization, all the user data in the configured AD group will be synchronized to the contact directory of the customer in Enreach Voice platform. The contact directory is the internal phone book that can be used in the Voice clients for finding the colleagues and other contacts of interest.

Setting up SCIM provisioning in Voice Portal

The following chapters explain how to set up the SCIM integration between Enreach Voice platform and Azure AD. The setup process consists of two parts;

configuring identity service in Enreach Voice Portal
configuring Portal as an enterprise application in the Azure AD and enabling automatic provisioning.

Configuring identity service in Voice Portal

As a Voice Portal administrator, log into your customer account.

Identity management is currently available for selected customers only. In order to make the identity management service available, please contact your account manager.

In the sidebar menu, click on the item labeled “Identity” to access identity service management page.

If the identity management service is not active, you can activate it by clicking the “Activate service” button.

Connecting to Azure AD

When the identity service has been activated, the section for “Azure integration” is shown:

Configure the Azure AD instance by clicking the “Connect Azure AD…” button.

You will now be prompted to enter the domain name of your Azure AD instance:

Enter your Azure AD domain name and click “Connect to Azure AD”. In this document, we are using our example domain name “azdev.enreachvoice.com”.

Enabling SSO permissions in Azure AD

If adding the Azure AD instance information was successful, you will see an overview of the status of AD integration. On the top half of the page, you see the services currently activated for this AD integration.

The Azure AD authentication is enabled by default. It provides the SSO (single sign-on) service for Enreach Voice services.

In order to make the SSO functional, the corresponding permissions must be approved in your Azure AD configuration. See below.

The Azure AD tenant permissions for Enreach identity management can be activated by clicking “Give permissions for user authentication”. If you are not the Azure AD administrator, there is also a possibility to send the request directly to the AD admin via email.

Clicking the “Give permission for user authentication” directs you to the Azure AD admin center. You will be first requested to log in to your Azure tenant.

After successful login to Azure tenant, the request for permission approval will be shown.

Click “Accept” in order to allow “EnreachVoice” application to sign in and read user profiles. This consent is mandatory for smooth single sign-on experience for end-users.

If the permissions were granted successfully, you will be redirected back to Portal with message:

You can retry the permission grant any time if needed.

Configuring SCIM integration services

After granting the SSO permissions, you may continue with enabling the SCIM integration services.

You can do so by clicking the “Settings” button:

The settings page appears.

Generating SCIM token for Azure AD

In order to make Azure AD to communicate with Voice Portal, an authentication token needs to be generated. This token will be used in Azure AD when configuring the automatic provisioning for enterprise application.

Click on “Generate new token”. This will create a new bearer token that will be used later.

The new secret token is generated. This token will be used later when configuring the provisioning in the Azure AD.

Configuring the AD group names for mapping the users

The AD groups are used for mapping the users for provisioning or contact directory.

AD user provisioning group
- The users in this AD group will be treated as user accounts in Enreach Voice platform.
AD contact directory group
- The users in this AD group will be treated as contact cards to be synchronized to the internal phone book in the Enreach Voice platform. This is group is optional.

Now we need to choose the names for the to AD user groups that will be used for the accounts that will be provisioned to Enreach Voice services.

Click on “Edit group names” button.

Enter the names of the AD groups that you wish to use for this purpose and click “Save settings”.

In this example, we decided to use the following AD groups:

“Enreach Voice Accounts” for user provisioning
“Enreach Voice Contact Directory” for contact directory information.

These AD groups need to be configured in Azure at later steps.

Enabling synchronization modes

Next, Click on “Enable” for “Identity sync” and “User data sync”. This will enable user identity linking between Azure AD and Enreach identity service. This step is mandatory if you are using automated SSO.

Enabling the “User data sync” option allows synchronization of other user data attributes from Azure AD. Data is mapped according to the configuration as described in the “Data mapping” paragraph.

You may also enable the “Create new users” option, which allows Voice Portal to automatically create new user accounts as they are provided in SCIM events from AD. This settings affects only user provisioning, the new contact directory entries are always created.

After completing these steps, the basic setup for SCIM integration is ready at Enreach side.

Next we will configure the Azure AD tenant.

Configuring Azure AD tenant for SCIM integration

Enabling SCIM provisioning in Azure AD involves a few steps.

Below is an overview of the process. Detailed instructions will follow in the next sections.

Sign in to the Azure AD admin center using your admin credentials.
Go to the “Applications” --> "Enterprise applications" section and create a new non-gallery application for Voice Portal (instructions for this are provided in the next chapter).
In the "Manage" section of the application's page, click on "Provisioning."
In the Provisioning page, select "Automatic" as the provisioning mode and then select "SCIM" as the provisioning type.
Provide the SCIM endpoint URL for the target application. This is the URL that Azure AD will use to communicate with the target application's SCIM API.
Provide the authentication details for the SCIM endpoint. This may include a client ID, client secret, username, and password, depending on the authentication method used by the target application.
Choose the provisioning scope for the target application. This determines which users and groups in Azure AD will be synchronized with the target application. Enreach Voice Portal requires that users are provisioned via AD group membership. Direct user assignments are not currently supported.
Map the Azure AD user attributes to the corresponding attributes in the target application's SCIM schema. This ensures that the user data is correctly synchronized between the systems.
Test the SCIM provisioning configuration by clicking on "Test Connection." This will check that Azure AD can successfully communicate with the target application's SCIM API.
Save the provisioning configuration and then turn on the provisioning status by sliding the "Provisioning Status" toggle to "On."

Once SCIM provisioning is enabled, Azure AD will automatically synchronize user data and manage user access within the target application based on the provisioning settings and mapping defined during the configuration process.

Step by step instructions are provided below.

Creating new enterprise application

Sign in to your Azure AD admin center: https://aad.portal.azure.com

Make sure that you log in to the same Azure AD tenant that has the domain name entered to Voice Portal.

After successful login, click on “Enterprise applications”.

The existing enterprise applications are listed.

Next we will be creating a new enterprise application which will represent the Voice Portal at Enreach. We will configure and activate the user provisioning using this application.

Create a new enterprise application by clicking the “+ New application” button.

In the page that appears, click on “+ Create your own application”.

New dialog will appear on the right side of the page.

In this dialog;

enter the name for the new SCIM application, for example “Enreach Voice Portal”. This name appear in your Azure AD management.
select “Integrate any other application you don’t find in the gallery (Non-gallery)”
click “Create”.

New enterprise application is now created.

Next, navigate to the “Properties”.

On the “Properties” page, make the following configrations:

Set “Enabled for users to sign-in?” setting to “No”.
Set “Visible to users?” setting to “No”.
Click “Save” to save changes.

Now the enterprise application is set up.

Configuring automatic provisioning

Next we will activate automatic provisioning, i.e. enable SCIM integration to Enreach Voice services.

On the enterprise application menu, click “Provisioning”.

In the provisioning page, click “Provisioning”.

Now we will configure the automatic provisioning, i.e. enable SCIM integration.

In the “Provisioning” page, configure the settings as follows:

Set “Provisioning mode” to “Automatic”.
Set “Tenant URL” by copying its value from Enreach Voice Portal (see next chapter)
Set “Secret Token” by copying its value from Enreach Voice Portal (see next chapter)
Check connection by clicking “Test Connection”
Verify that connection works.
Save configuration.

Obtaining “Tenant URL” and “Secret Token” from Voice Portal

In Enreach Voice Portal, navigate to the Azure AD settings in “Identity” section. Copy the “Tenant URL” and “Secret token” and paste them to the provisioning settings in Azure AD.

Please make sure you copy the correct tenant URL value from Voice Portal as it may vary depending on the environment.

Before enabling the SCIM provisioning, we will configure the basic data mapping.

On the “Provisioning” page, expand the “Mappings” section and click on “Provision Azure Active Directory Users”.

The “Attribute Mapping” page will open.

We will now enable identity synchronization by mapping the required attributes from AD to SCIM (= customappsso attribute).

There are few mandatory mappings required:

AD attribute “userPrincipalName" must be mapped to SCIM attribute “userName”
AD attribute “objectId” must be mapped to SCIM attribute “externalId”

SCIM integration will not work if these conditions are not met.

Verify that “userPrincipalName” is mapped to “userName” and “Matching precedence” is set to “1”.

The “objectId” is not mapped to “externalId” by default. We must create new mapping rule for it.

Find the rule that has customappsso Attribute “externalId” mapped.

Click on the row to edit the rule.

Make the following changes to the rule:

Set “Source attribute” to “objectId”
Ensure that “Target attribute” is set to “externalId”.
Save changes by clicking “Ok”.

In the “Attribute Mapping” page, click “Save” to save the new mappings.

Attribute mapping is now ready for basic requirements.

Setting the scope for SCIM provisioning

You can control which AD groups are provisioned to Enreach Voice services by setting the scope of provisioning. This can be done in the “Provisioning” page, under section “Settings”.

Please note that in the users need to be provisioned via AD group memberships. Direct user assignments are not supported.

By default the “Scope” is set to “Sync only assigned users and groups”. You can change this at will.

Creating AD user groups for provisioning

Next we need to create the AD groups to be used in the user provisioning towards Enreach Voice platform. As stated earlier in this document, we need two groups; one for user provisioning and one for contact directory data.

Navigate to the “Groups” section in your AD admin center.

Create new AD groups

Use the same AD group name what you configured in Voice Portal. In this example, we chose the names

“Enreach Voice Accounts” for user provisioning
“Enreach Voice Contact Directory” for contact directory

These names can be chosen freely.

For “Enreach Voice Accounts”:

For “Enreach Voice Contact Directory”:

As the result, you have two new AD groups:

Assign users to the AD groups

For the user provisioning group, assign AD users you wish to get provisioned as active user accounts in the Voice Portal.

For the contact directory group, assign AD users whose data you need to have only as contact entries in the company wide contact directory.

Assigning AD user groups to the scope of SCIM provisioning

If your provisioning scope is “Sync only assigned users and groups”, you must explicitly assign the AD groups to the application “Enreach Voice Portal”.

In the “Provisioning” page, click on “Users and groups”.

Using this page, you can assign the AD groups to the enterprise application. The users that are members in these AD groups will provisioned to Enreach.

When you assign a group to an application, only users directly in the group will have access. The assignment does not cascade to nested groups.

Activating user provisioning

In the “Provisioning” page, click on “Overview”.

Click “Start provisioning”. Azure AD will now start user synchronization. Please note that it may take up to 40 minutes to receive data from Azure. This is due to restrictions on Azure AD.

The basic SCIM integration has now been set up.

There details of the synced data can be adjusted by further configuring the data mapping and scoping the users and groups to be provisioned.

Monitoring SCIM events in Voice Portal

The provisioning activity can be verified in Azure AD provisioning logs. It can also be verified in the Enreach Voice Portal.

Navigate to the Azure AD configuration page (“Identity” → “Azure AD” → “Manage…” → “Settings”).

In this page, click button “Manage SCIM data”.

The users and groups received from Azure AD can be seen on these pages.

Example of SCIM users view:

The user data is always received in SCIM as configured in the Azure AD mapping. Further processing will happen only as defined in the identity settings and group configurations.

Example of SCIM groups view:

Required SCIM attributes for user provisioning

There are some attributes that are required to be present, depending on the level of integration. The following SCIM attributes must be present in order to have functional SCIM integration:

Azure AD attribute	SCIM attribute	Portal
objectId	externalId	Azure user ID
userPrincipalName	userName	Username/Email
Switch([IsSoftDeleted], , "False", "True", "True", "False")	active	User is active
givenName	name.givenName	First name
surname	name.familyName	Last name

The complete list of the supported SCIM attributes is presented here:

/wiki/spaces/PORTAL/pages/2379579438

Configuring data mapping in Voice Portal

SCIM protocol transfers user data from the Azure AD. The data attributes from AD are mapped to corresponding data fields in the SCIM data model. As seen in previous chapters, this mapping can be configured in Azure provisioning.

Correspondingly, when the SCIM data is received from Azure, the data fields in SCIM are yet again mapped to the data fields in Enreach Portal. This mapping can also be configured.