Clarity Connect Federation - Use Azure AD For Authentication Customer Steps
Subject
This Knowledge Base Article will provide detailed information on how to configure Azure Active Directory integration with Clarity Connect. If you're unfamiliar with Azure Active Directory it's highly recommended that you seek out help from your project manager or support when going through the steps below.
These steps only cover the customer's portion of the process. The hosting steps are to be completed by the project manager, tier 3 support, or the engineering team.
Note that admin access to Azure Active Directory is required to proceed with the steps below.
Version of Connect
4.1.7 and up
Table of Content
1. Azure Active Directory Authentication vs Windows Authentication
2. Azure Application Registration
2.1. How to get the AAD_TenantName?
2.2. Create App Registration for Admin Site
2.3 Create App Registration for Web API, Metrics, and Dashboard
2.4 Create User Impersonation scope for Web API
2.5 Add Web API Permissions and Grant Consent (Metrics, Dashboard)
2.6 Create Metrics Client Secret
2.7 Additional permissions and configuration for the Dashboard
3.1. Connect Runtime requirement
4. Agent workstation configuration
4.2. Internet Zone configuration
4.3. Infinite Loop When Logging In
Guidelines
1. Azure Active Directory Authentication VS Windows Authentication
Clarity Connect can be configured to use either AAD authentication or Windows authentication. Please note that it is not supported for a particular set of users to use Windows Authentication while others are using AAD authentication.
2. Azure Application Registration
To enable the integration between AAD and Clarity Connect, it is necessary to create four registered applications within the Azure Portal. Each application offers different functionalities that will be explained further in the article.
Note: During app registration process, specific values need to be noted, as they will need to be updated directly in the Clarity Connect Runtime database.
2.1. How to get the AAD_TenantName?
The AAD tenant name can be located by doing the following:
1. Log into https://portal.azure.com
2. Click on the Azure Active Directory blade and then on Domain Names tab.
3. Find and copy your tenant name under the Name section (it will end in .onmicrosoft.com):
2.2 Create App Registration for Admin Site
Admin Site application registration allows users to authenticate against Azure AD when accessing Connect Admin Site. After authenticating, users get an access token with their UPN (User Principal Name, i.e. username@domain.com). The Admin Site finds the Connect Agent profile with a LoginName that matches that UPN.
Proceed with the following steps to create App Registration for Admin Site:
1. In the Azure Portal, navigate to the Azure Active Directory blade
2. Click on the App registrations link in the left hand panel and then on New registration as displayed:
3. A new window will appear where the following values should be entered:
Name: Connect {ConnectInstanceName} Admin Site Example: Connect ExampleCustomer Admin Site
Redirect URI: {Admin Site URL} Example: https://examplecustomer.ctcontactcen...ClarityConnect
(NOTE "examplecustomer" should be replaced with your Clarity instance name. If you're not sure what this is, please ask your project manager or support)
4. Click on Create as displayed:
5. At this point, the App Registration for the Admin Website has been created, and you will now see the Overview screen for the registration.
6. Copy the Application (client) ID. This value will be used for the SQL Script - AAD_AdminSiteApplicationId.
7. Click on the Authentication link in the left hand panel, and check the "ID tokens" and “Access tokens” items in the Implicit Grant section towards the bottom:
8. Click on the Expose an API link in the left hand panel, and click "Set" at the top to generate a new Application ID URI. Copy the generated URI. This value will be used for the SQL Script - AAD_AdminSiteAppIdUri.
9. Click on the API permissions link in the left hand panel, and select the option to "Grant admin consent for" the delegated permissions.
2.3 Create App Registration for Web API, Metrics, and Dashboard, following the same steps as in 2.2. Gather the Application (client) ID and Application ID URI for the SQL script for each respective registration.
NOTE: The Reply URL is not needed in the Web API and Metrics registrations.
In the "Dashboard App Registration", two Reply URLs need to be added
Example: https://examplecustomer.ctcontactcen...ard/token.html
Example: https://examplecustomer.ctcontactcen...ard/index.html
(NOTE "examplecustomer" should be replaced with your Clarity instance name. If you're not sure what this is, please ask your project manager or support)
2.4 Create User Impersonation scope for Web API
The App Registration for Web API will establish the Web API as a resource that is protected by Azure AD. Other app registrations (Dashboard and Metrics) are granted permissions to access the Web API resources in order to access tokens for AAD to perform Web API method calls.
1. Return to the Web API app registration and select the Expose an API link in the left hand panel.
2. Click the "Add a scope" as shown in the image above and fill in the details similar to the following:
3. Click "Add scope" to complete the operation.
2.5 Add Web API Permissions and Grant Consent (Metrics, Dashboard)
1. Return to Metrics and Dashboard app registrations, and for each, select the "API permissions" link.
2. Click the "Add a permission" button to request API permissions. Select "My APIs" to reveal the Web API registration.
3. Select the permission scope created in step 2.4 and click "Add permissions".
4. Once the permissions are added, grant admin consent for the newly added permissions by clicking "Grant admin consent for...".
2.6 Create Metrics Client Secret
Since the Metrics application runs as a background application on the server, rather than the direct context of a user, the Metrics application will require a Client Secret to be stored in the database and used by the Metrics Service.
1. Return to the Metrics app registration and select the Certificates & Secrets link.
2. Create a client secret with the desired expiration (it is recommended to select "Never") and be sure to copy the generated value before leaving the page, as this will be the only time it is exposed in the UI.
2.7 Additional permissions and configuration for the Dashboard
1. Return to the Dashboard app registration and select the API Permissions link.
2. Click "Add a permission" and select Skype For Business.
3. Select all permissions in both the Delegated Permissions and Application Permissions tabs.
4. Once the permissions are added, grant admin consent for the newly added permissions by selecting "Grand admin consent for...".
5. Select to the Manifest link in the Dashboard registration and click "Edit." Change the oauth2AllowImplicitFlow value from false to true and click "Save":
3. SQL configuration values
In order to setup Azure integration, it is necessary to update specific settings in the Connect Runtime dbo.config table. In the attachment is the SQL configuration update script that needs to be executed against Connect Runtime database. By deploying the attached SQL script, the AAD Authentication will be enabled for all users.
SQL Worksheet:
Configuration Name |
Configuration Value Examples |
AAD_TenantName |
examplecustomer.onmicrosoft.com |
AAD_AdminSiteApplicationId |
d4804011-8c23-4bc6-9119-a831d7faf9fb |
AAD_AdminSiteAppIdUri |
|
AAD_WebApiApplicationId |
a79f99fc-97a5-40b0-a3c4-d27c0124b30z |
AAD_WebApiAppIdUri |
|
AAD_MetricsApplicationId |
1858df5a-9d30-4478-b461-8eec7e9e1bf4 |
AAD_MetricsAppIdUri |
|
AAD_MetricsAppKey |
-vR.@/lttg0upa7SXzXAuBf05h.4/1:v |
AAD_DashboardApplicationId |
c342eaf0-8eb7-4ed3-b17b-60dd3250b73f |
AAD_DashboardAppIdUri |
4. Agent workstation configuration
In order for Azure AD login to succeed on the Web Agent Console for IE and Edge browsers, the Connect Admin Console URL needs to be in the same Internet Security Zone as the Azure AD login authority. Otherwise, the Azure AD login session cookies cannot be included in silent token acquire requests from the Web Console.
4.1 Trusted Sites
In a typical Connect deployment, via group policy or by running the Agent Console installer file, the Connect Agent PCs should already have the Connect Admin Console URL in Trusted Sites on the Agent's PC. Therefore the Azure AD login authority URL, https://login.microsoftonline.com, has to be in Trusted Sites as well. This can be deployed individually during testing, via Group policy or via a Registry file. Ensure the Connect Admin Console URL is in Trusted Sites (ie https://examplecustomer.ctcontactcenter.com)
Example registry entry:
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings\ZoneMap\EscDomains\login.microsoftonline.com]
"http"=dword:00000002
"https"=dword:00000002
[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings\ZoneMap\Domains\login.microsoftonline.com]
"http"=dword:00000002
"https"=dword:00000002
To add the Azure AD login authority URL on a single machine, please perform the following:
1. In Internet Explorer, open Settings > Internet options:
2. Navigate to the Security tab and select Trusted sites
3. Add https://login.microsoftonline.com to Trusted sites and click OK to accept the changes.
4.2. Internet Zone configuration
If the Agent PCs do not have the Admin Console URL in Trusted Sites, it is mandatory for the Azure AD login authority URL to be excluded from the Trusted Sites list.
Note: Keep in mind that for the Edge browser, Protected Mode must be turned off for the Internet Zone for Web Console login to work as expected. This is only applicable for the above scenario.
4.3 Infinite Loop When Logging In
This is related to the problem described above. If the security zone setup is correct but you get stuck with a loading screen or infinite redirect loop logging into the Connect website or Web Agent Console, make sure you are entering an https:// address in the browser's address bar. You MUST hit all Connect websites and the Web Agent Console via HTTPS or else the security settings in IE will prevent the Azure AD login cookies from working with the HTTP Connect site.
4.4. Warning message: The current webpage is trying to open a site in your Trusted sites list. Do you want to allow this?
If during the sign-in process the below error message is presented, ensure https://login.windows.net is added to the list of your Trusted Sites: