Prerequisites
Introduction
This guide covers setting up SSO in Cognigy.AI with Azure AD as the Identity Provider. After completing this guide, your users can log in to Cognigy.AI through Azure AD and will automatically get a user in Cognigy.AI complete with access control.
Premium Feature
You need to have an Azure premium subscription to use the Active Directory SSO service!
Creating an Application in Azure AD
The first step is to create an Enterprise application in Azure AD that is used to connect to Cognigy.AI. To create an Enterprise application, login into the Azure Portal, navigate to Azure Active Directory (AD), and click on Enterprise application.
You can now click the + New application button to create your new Cognigy.AI application.
Creating a new Enterprise application
The Add an Application panel should open, in which you have to click on Non-gallery application. Give your application a name and click on Add. The creation process can take some time, so let's wait.
Creating your new non-gallery application
Configuring Single Sign-on for the Application in Azure AD
To configure SSO for your newly created application, click on Single sign-on, followed by clicking on the SAML option displayed.
Choosing the SSO mode
We can now start adjusting the SSO configuration.
Basic SAML Configuration
The first thing we adjust is the Basic SAML Configuration
. To configure the Sign on URL, the Entity ID, and the Reply URL. All of these fields should be set to the SSO URL
(See Cognigy.AI SSO documentation):
- Identifier (Entry ID)
- Reply URL
- Sign on URL
Note that the current <api-url> for the SSO URL in the Cognigy.AI app environment is api-app.cognigy.ai (omits the /new/ as per other API requests).
Add User Attributes and Claims
To properly implement SSO with Cognigy.AI, you need to configure the user attributes. It is required that the following fields are set on the user:
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress: user.mail
- firstName: user.givenname
- lastName: user.surname
- role: user.assignedroles
- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name: user.userprincipalname
The role will be used to grant the user the proper access rights in Cognigy.AI. Later, we will add the supported roles to the app.
Correct configuration for user attributes
User Attributes Summary
Configuring SSO in Cognigy.AI
After configuring SSO in Azure AD, we are finally ready to create an SSO configuration for your organization in Cognigy.AI. You do this by sending a POST request to the URL:
https://<api-your-environment>/v2.0/identityprovider/configure
(for example, https://api-app.cognigy.ai/new/v2.0/identityprovider/configure) and attach the following JSON payload to the request with your unique values (see below):
{
"idpType": "saml",
"idpIssuer": "string",
"idpLoginEndpoint": "string",
"idpCertificate": "string"
}
API Authentication
Read our API reference guide for information about how to send authenticated API requests to Cognigy.AI. You need to create an API-Key for the first user, which you need to set up SSO for your organization.
To do this, you need some information from Azure AD, which you will find on the Single Sign-on page in your enterprise application in Azure AD.
idpIssuer
The idpIssuer is Identifier (Entity ID)
in Azure AD.
idpLoginEndpoint
The idpLoginEndpoint is Login URL
in Azure AD. You will find this URL at the bottom of the Single Sign-on Configuration page.
The Login URL
idpCertificate
This is the certificate that Azure AD uses to sign the SAML requests. There is a download link in the SAML Signing Certificate
paper. You need to download the Base64 certificate.
Certificate download
After downloading the certificate, despite the format already being base64 you must again base64 encode it without newlines.
On Linux, you can do this by running the following command
cat ./path-to-file | base64 -w0
On Mac, you will need to use -b0
instead, as -w0
is not supported.
The output of the command above should be used as the idpCertificate.
You can now send the POST request with the information you collected from Azure AD. An example payload is below:
{
"idpIssuer": "https://api-<your-environment>.cognigy.ai/auth/saml/login/5baaa0e1e62856c84f884883",
"idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-0ffb-****-******/saml2",
"idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlDOERDQ0FkaWdBd0lCQWdJUWM3RFNuaXdMdTdoTTJwR0V3YTFXR1RBTkJna3Foa2lHOXcwQkFRc0ZBREEwTVRJd01BWURWUVFEDQpFeWxOYVdOeWIzTnZablFnUVhwMWNtVWdSbVZrWlhKaGRHVmtJRk5UVHlCRFpYSjBhV1pwWTJGMFpUQWVGdzB4T1RBeE1UZ3hNRE0yDQpNelJhRncweU1qQXhNVGd4TURNMk16UmFNRFF4TWpBd0JnTlZCQU1US1UxcFkzSnZjMjltZENCQmVuVnlaU0JHWldSbGNtRjBaV1FnDQpVMU5QSUVObGNuUnBabWxqWVhSbE1JSUJJakFOQmdrcWhraUc********************************************************************************6cHFYDQo4K1ZOdVVhdUxJNEpodXZlR29GMDViaGxzQVVRVkNXTTJTN2tqazJ0enNwck8xZjJScXYvSHp2K1IxVFRHWlRQMlB4U0lVcm9tS3JLDQoxcnRmT2NUU1I0bE5QblVJM2hEag0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ0K"
}
Configuring User Roles
To configure user roles for the users in Cognigy.AI, we first have to add the supported roles to the app manifest. To do this, navigate to Azure Active Directory > App Registrations and open your app. Now click the edit manifest button and paste the JSON below into the appRoles
array. If you want to know more about the permissions related to each role, read the official Cognigy documentation.
{
"allowedMemberTypes": [
"User"
],
"displayName": "Admin",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc1",
"isEnabled": true,
"description": "The Admin role in Cognigy.AI",
"value": "admin"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "API Keys",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc2",
"isEnabled": true,
"description": "The Api Keys role in Cognigy.AI",
"value": "apiKeys"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Base",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc3",
"isEnabled": true,
"description": "The base role in Cognigy.AI",
"value": "base_role"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Full Support User",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc4",
"isEnabled": true,
"description": "Admin privileges, no user assignments in Cognigy.AI",
"value": "fullSupportUser"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "OData",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc5",
"isEnabled": true,
"description": "The OData role in Cognigy.AI",
"value": "odata"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Project Manager",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc6",
"isEnabled": true,
"description": "The Project Manager role in Cognigy.AI",
"value": "projectManager"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "User Manager",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc7",
"isEnabled": true,
"description": "The User Manager role in Cognigy.AI",
"value": "userManager"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Administrator",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc8",
"isEnabled": true,
"description": "The Administrator role in Live Agent",
"value": "liveAgentAdmin"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Agent",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bc9",
"isEnabled": true,
"description": "The Agent role in Live Agent",
"value": "liveAgentAgent"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Supervisor",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bd1",
"isEnabled": true,
"description": "The Supervisor role in Live Agent",
"value": "liveagentSupervisor"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "View user details",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bd2",
"isEnabled": true,
"description": "The role to view user details in Cognigy.AI",
"value": "userDetailsViewer"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Voice Gateway User",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bd3",
"isEnabled": true,
"description": "The Account scope in Voice Gateway",
"value": "voiceGatewayUser"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Basic Support User",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bd4",
"isEnabled": true,
"description": "Partial Admin, read-only, no assignments, no OData/API, no Knowledge AI in Cognigy.AI",
"value": "basicSupportUser"
},
{
"allowedMemberTypes": [
"User"
],
"displayName": "Project Assigner",
"id": "8d17fe88-c0ca-4903-ae2a-a51098998bd5",
"isEnabled": true,
"description": "Assigns Agents, read-only access, no global roles, limited features in Cognigy.AI",
"value": "projectAssigner"
}
Adding new App Roles to the application
You should also delete the preconfigured User
role from the appRoles array.
SSO User Roles - Best Practice
Most users will be created with either the Admin role (for organization administrators) or the Base role (for standard users). Additional access for standard users will be built up using the project-level access rights via the agent members feature within Cognigy.AI.
After adding the JSON, click save and navigate back to your application in Azure Active Directory > Enterprise applications > Your Application. Here you can click Users & Groups
in the menu on the left side. In this view, you can add users and assign them one of the roles you just configured. When the user logs into Cognigy.AI via SSO for the first time, a user with that role will be created in Cognigy.AI.
User with configured role
You're now done configuring Single Sign-on for Azure AD, and your users can now log in to Cognigy.AI through Azure AD
Service Provider Initiated Single Logout is supported with Azure Active Directory from Cognigy.AI version 4.25.0
Comments
0 comments