Prerequisites

• Get the SSO URL 

Introduction

This guide covers setting up SSO in Cognigy.AI with Microsoft Azure Entra ID (formerly Active Directory) as the Identity Provider. After completing this guide, your users can log in to Cognigy.AI via Microsoft Entra ID and will automatically get a user in Cognigy.AI complete with access control.

Creating an Application in Enterprise Application with Entra ID

The first step is to create an Enterprise application that is used to connect to Cognigy.AI. To create an Enterprise application, login into the Azure Portal, navigate to Microsoft Entra ID. 

Look for Microsoft Entra ID

You can now click the + Add and then Enterprise application to create your new Cognigy.AI application.

Creating a new Enterprise application

The Browse Microsoft Entra Gallery page should open, in which you have to click on + Create your own application.

Microsoft Entra Gallery Page

Give your application a name. Make sure you choose the option Integrate any other application you don't find in the gallery (Non-gallery) and click on Create. 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 Set up single sign on. 

SSO overview

Then 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 for details regarding the contents of these fields):

• Identifier (Entry ID)
• Reply URL
• Sign on URL

This will have the following pattern:

https://<api-url>/auth/saml/login/<organization-id>

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).

To configure the Logout URL simply use the SLO URL with the following pattern:

https://<frontend-url>/slo/<organization-id>

Basic SAML Configuration

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": "https://api-<your-environment>.cognigy.ai/auth/saml/login/<organization-id>", 
"idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-****-****-******/saml2", "idpCertificate":"LS0tLS**************************" 
}

Please keep in mind that the values in the above example might be significantly longer but have been shortened here for clarity.

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/<organization-id>",
  "idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-0ffb-****-******/saml2",
  "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlDOERDQ0**************"
}

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 App registrations and open your app by searching for it in All applications.

Navigate to App Registrations

Find app under All applications

Click on the app to open the overview. To find the Manifest option open up the Manage dropdown menu. Now 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. You might need to do this by manually manually disabling them in the manifest and then going into the App roles submenu of Manage and manually deleting them in the UI. 

Disable role in Manifest

Delete old App roles

After adding the JSON, click save and navigate back to your application in Enterprise applications and search for your application.

Find your application in Enterprise applications page

Here you can click Assign Users & Groups. 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

Login via Entra ID

You're now done configuring Single Sign-on for Microsoft Entra ID, and your users can now log in to Cognigy.AI through via Entra ID. Go to

https://<frontend-url>/login

and click on Login with SSO to reach the SSO login page: 

SSO Login Page

Service Provider Initiated Single Logout is supported with Microsoft Entra ID from Cognigy.AI version 4.25.0