Requirements
✔ SSO URL (Get it here)

Introduction

This guide covers how to setup SSO in Cognigy.AI with Azure AD as the Identity Provider. After completing this guide, your users can login 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 in order 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. In order 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 on 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

In order 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. We here need 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).

10._Basic_SAML_Config.PNG

Setting the basic SAML configuration

*Please note the current <api-url> for the SSO URL in the Cognigy.AI trial environment is api-trial.cognigy.ai (omits the /new/ as per other API requests).

10._Basic_SAML_Config_1.PNG

Basic SAML configuration

Add User Attributes and Claims

In order 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:

The role will be used to grant the user the proper access rights in Cognigy.AI. In a later step, 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 organisation in Cognigy.AI. You do this by sending a POST request to the URL:

https://<api-url>/v2.0/identityprovider/configure

(e.g. https://api-trial.cognigy.ai/new/v2.0/identityprovider/configure) and attach the following JSON payload to the request with your unique values (see below):

{
  "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.

In order 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 the Identifier (Entity ID) in Azure AD.

idpLoginEndpoint
The idpLoginEndpoint is the 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, you need to base64 encode it without newlines. In Linux, you can do this by running the following command

cat ./path-to-file | base64 -w0

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-trial.cognigy.ai/new/auth/saml/login/5baaa0e1e62856c84f884883",
  "idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-0ffb-****-******/saml2",
  "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlDOERDQ0FkaWdBd0lCQWdJUWM3RFNuaXdMdTdoTTJwR0V3YTFXR1RBTkJna3Foa2lHOXcwQkFRc0ZBREEwTVRJd01BWURWUVFEDQpFeWxOYVdOeWIzTnZablFnUVhwMWNtVWdSbVZrWlhKaGRHVmtJRk5UVHlCRFpYSjBhV1pwWTJGMFpUQWVGdzB4T1RBeE1UZ3hNRE0yDQpNelJhRncweU1qQXhNVGd4TURNMk16UmFNRFF4TWpBd0JnTlZCQU1US1UxcFkzSnZjMjltZENCQmVuVnlaU0JHWldSbGNtRjBaV1FnDQpVMU5QSUVObGNuUnBabWxqWVhSbE1JSUJJakFOQmdrcWhraUc********************************************************************************6cHFYDQo4K1ZOdVVhdUxJNEpodXZlR29GMDViaGxzQVVRVkNXTTJTN2tqazJ0enNwck8xZjJScXYvSHp2K1IxVFRHWlRQMlB4U0lVcm9tS3JLDQoxcnRmT2NUU1I0bE5QblVJM2hEag0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ0K"
}

Configuring User Roles

In order to configure user roles for the users in Cognigy.AI, we first have to add the supported roles to the app manifest. In order to do this, navigate to Azure Active Directory > App Registrations and open your app. Now click on the edit manifest button and paste the JSON below into the appRoles array.

    {
      "allowedMemberTypes": [
        "User"
      ],
      "displayName": "Admin",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc7",
      "isEnabled": true,
      "description": "The admin role in Cognigy.AI",
      "value": "admin"
    },
{ "allowedMemberTypes": [ "User" ], "displayName": "API Keys", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc6", "isEnabled": true, "description": "The api keys role in Cognigy.AI", "value": "apiKeys" }, { "allowedMemberTypes": [ "User" ], "displayName": "Base", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc5", "isEnabled": true, "description": "The base role in Cognigy.AI", "value": "base_role" },
{ "allowedMemberTypes": [ "User" ], "displayName": "Livechat", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc4", "isEnabled": true, "description": "The livechat role in Cognigy.AI", "value": "livechat" },
{ "allowedMemberTypes": [ "User" ], "displayName": "Odata", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc3", "isEnabled": true, "description": "The odata role in Cognigy.AI", "value": "odata" }, { "allowedMemberTypes": [ "User" ], "displayName": "Project Manager", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc2", "isEnabled": true, "description": "The project manager role in Cognigy.AI", "value": "projectManager" }, { "allowedMemberTypes": [ "User" ], "displayName": "User Manager", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc1", "isEnabled": true, "description": "The user manager role in Cognigy.AI", "value": "userManager" }

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

The majority of 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 on Users & Groups from the menu on the left. In this view, you can add users and assign them one of the roles you just configured. When the user then 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 login to Cognigy.AI through Azure AD


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

Comments

0 comments

Please sign in to leave a comment.