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.

c60053f-new-app.pngCreating 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.

8ca8b54-new-app2.pngCreating 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.

8a64719-Screenshot_from_2019-02-15_13-49-11.pngChoosing 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.

userattributes.PNG

Correct configuration for user attributesuserattributesSummary.PNG

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.

a2e2c4e-Screenshot_from_2019-02-15_16-04-34.png

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.

f45d42a-Screenshot_from_2019-02-15_16-16-14.pngCertificate 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"
  }

11._Manifest__small_.PNG

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.

12._UserRoles.PNG

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

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful