Introduction

The integration of Microsoft Entra ID, formerly known as Azure Active Directory or Azure AD, allows enabling login with corporate identities in wolkvox applications.

With this integration, users of wolkvox Manager and wolkvox Agent can authenticate using their Entra ID credentials, facilitating a centralized, secure login aligned with the organization's identity policies.

This configuration helps improve security, simplify user access, and leverage the authentication and identity management capabilities of Microsoft Entra ID.

---

Configuration

Configuration in the Entra ID Portal

1. Log in to the Microsoft Azure portal
   • Access the Microsoft Azure portal with an account that has administrative permissions over the Microsoft Entra ID tenant.
   • From the homepage, go to Microsoft Entra ID.

1. Within Microsoft Entra ID, go to the "Enterprise Applications" section. Then, in the left-side menu, select the "All Applications" option.
2. Click on "New Application".

1. In the Microsoft Entra gallery, select the option "Create your own application".
2. A side panel will open to create the application. There, you must complete the initial information.
   • In the field "What is the name of your application?", enter the name by which you want to identify the integration. You can use a name that easily identifies the application as the integration between Microsoft Entra ID and wolkvox. For example: 'Wolkvox SSO' or a name defined by your organization.
   • For the question "What are you looking to do with your application?", select the option: Register an application to integrate with Microsoft Entra ID (an application you are developing). Then click "Create".

• After creating the application, the "Register an application" screen will open.
• In this section, you must validate or complete the application name and configure the supported account types.
• In the Supported Account Types section, select the option: "Accounts in this organizational directory only".
• This option configures the application as single-tenant, meaning only users from the company's organizational directory can use this application to authenticate.
• Then, register the redirect URI that will be used to return the authentication response after the user logs in successfully. In this configuration, ensure you include the required URIs for the integration, including those associated with MSAL and NativeClient. Also, ensure that the Application ID is included in the redirect URIs where required.
• Once this information is completed, click "Register".

After registering the application, return to the section: Enterprise Applications > All Applications.

Use the search field to find the application you just created.

When it appears in the results, click on the application name to access its configuration.

Within the application, go to the "Overview" section.

In the properties block, you will find the following data:

• Application ID: Unique identifier of the application registered in Microsoft Entra ID.
• Object ID: Unique identifier of the application object within the directory.

You must copy and save these values, as they will be necessary to complete the integration configuration in wolkvox Manager.

In the left-side menu of the application, go to the "API Permissions" section.

Then click on "Add a permission".

Select Microsoft Graph as the API to configure.

1. In the permission request window, select the "Delegated permissions" option. This type of permission allows the application to access the API as the logged-in user. In the list of Microsoft Graph permissions, find and select the following permissions:
2. User.Read: Allows signing in and reading the user's profile.
3. User.ReadBasic.All: Allows reading the basic profiles of all users.

After selecting the permissions, add them to the application.

Once the permissions are added, return to the API Permissions section.

If your organization's configuration requires it, click on "Grant admin consent" to authorize the configured permissions.

Upon completion, the permissions must be granted for the organization.

1. In the left-side menu, go to the "Authentication" section. In this section, the platforms that can receive authentication responses after the user logs in successfully are configured.
2. In Platform Configurations, add or validate the platform:
   • Mobile and desktop applications: Within this platform, the necessary redirect URIs for the integration must be configured. Ensure you include the URIs associated with:
     • MSAL.
     • NativeClient.
     • URIs that include the Application ID where applicable.
   • This configuration allows the authentication flow to complete correctly when users log in using Microsoft Entra ID.

Important: Set the supported account type as single-tenant.

---

How to Activate Microsoft Entra ID in wolkvox Manager

After configuring the application in Microsoft Entra ID, you must activate the integration from wolkvox Manager and link each user to their corporate Entra ID account.

1. From wolkvox Manager, click the Settings button, located in the top-right corner of the interface.
2. Then, go to the Integrations tab.
3. Within Integrations, select the "Entra ID" tab.
4. In this section, you will find the necessary fields to activate the integration with Microsoft Entra ID.
   • Check the box "Enable Microsoft Entra ID Integration".
   • Tenant ID: Corresponds to the identifier of the tenant or organizational directory of Microsoft Entra ID.
   • Client ID: Corresponds to the identifier of the application registered in Microsoft Entra ID.
   • In this same section, you will find the "Enable Single Sign-On" checkbox. When this checkbox is active, users of wolkvox Agent and wolkvox Manager will only be able to access these applications through Microsoft Entra ID. That is, Entra ID will be the only allowed login method for these users. If this checkbox is not active, users can continue using their own wolkvox credentials, according to the internal configuration and management of the operation. The administration, delivery, and control of wolkvox credentials will be the responsibility of each operation.
5. After completing the information and selecting the required options, click "Save" to apply the changes.

---

How to Link Agent-Type Users with Microsoft Entra ID

For an agent to log in to wolkvox Agent using Microsoft Entra ID, it is necessary to associate their wolkvox user with the corresponding UserPrincipalName in Entra ID.

1. From the left-side menu of wolkvox Manager, go to the "Agents & Skills" section.
2. Then, select the "Agents" tab.
3. Locate the agent you want to link with Microsoft Entra ID.
4. Right-click on the agent and select the option "Edit Agent Information".
5. In the edit modal window, go to the "Basic Information" tab.
6. In the SSO (Single Sign-On User) field, enter the "UserPrincipalName" of the user in Microsoft Entra ID. This value must correspond to the corporate user with which the agent will log in using Entra ID.
7. Click "Save" to apply the agent's linkage.

---

How to Link wolkvox Manager Users with Microsoft Entra ID

Administrative users of wolkvox Manager must also be linked to their corresponding account in Microsoft Entra ID.

1. From wolkvox Manager, click the "Settings" button, located in the top-right corner.
2. Within the settings window, select the "Users and Profiles" tab.
3. Then, go to the "Users" tab.
4. Locate the wolkvox Manager user you want to link with Microsoft Entra ID.
5. Right-click on the user and select the option "Edit User".
6. In the edit window, locate the "SSO" field. In this field, you must enter the UserPrincipalName of the user in Microsoft Entra ID. This value must correspond to the corporate user with which the person will log in to wolkvox Manager.
7. Click "Edit User" to apply the configuration.

---

How Login with Microsoft Entra ID Works

After activating the integration, wolkvox applications will show the option to log in with Microsoft Entra ID.

Login to wolkvox Agent

When opening wolkvox Agent, the user can select the "Login with Azure AD" option.

When clicking on this option, a Microsoft window will open to select an existing account or enter a different account.

The user must authenticate with the authorized corporate account in Microsoft Entra ID.

Login to wolkvox Manager

In wolkvox Manager, the login flow works equivalently. The user selects the login option with Azure AD or Microsoft Entra ID and completes the authentication from the Microsoft window.

If the login is successful, wolkvox validates that the authenticated UserPrincipalName is linked to an existing user in wolkvox Manager or wolkvox Agent, as appropriate.

When the validation is correct, the system allows access to the application.

---

Validations and Possible Login Errors

During the authentication process, errors related to credentials, user, authorization, or configuration may occur.

For example, Microsoft may display a message indicating that the username may be incorrect. In that case, you should validate that the user was entered correctly and that it exists within the Microsoft Entra ID directory.

It may also happen that the login to Microsoft is correct, but the user does not have their UserPrincipalName linked in wolkvox. In that case, wolkvox will not be able to complete the user validation, and the SSO field configuration for the corresponding user should be reviewed.

If an error occurs during the authentication process, the corresponding exception will be displayed, and login with wolkvox credentials will be re-enabled, as long as the operation's single login configuration allows it.

---

Authentication Security

The integration uses the OAuth 2.0 authentication method, which allows implementing a secure, standardized login flow based on corporate identities managed from Microsoft Entra ID.

With this configuration, wolkvox can validate user access based on authorized corporate credentials, maintaining a centralized login experience aligned with the organization's security policies.