Single Sign-on with Azure Active Directory

SSO URL (Get it here)


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.


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

In order 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. 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 you have from the previous guide


Setting the basic SAML configuration


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.


Correct configuration for user attributes

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:///security/identityprovider (e.g. with the following JSON payload:

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

The idpIssuer is the Identifier (Entity ID) in Azure AD.

The idpLoginEndpoint is the Login URL in Azure AD. You will find this URL at the bottom of the Single Sign-on configuration page.


The Login URL

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, 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": "",
  "idpLoginEndpoint": "****-******/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": [
      "displayName": "Marketer",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc7",
      "isEnabled": true,
      "description": "The marketer role in COGNIGY.AI",
      "value": "marketer"
      "allowedMemberTypes": [
      "displayName": "Basic",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc6",
      "isEnabled": true,
      "description": "The basic role in COGNIGY.AI",
      "value": "basic"
      "allowedMemberTypes": [
      "displayName": "Advanced Editor",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc5",
      "isEnabled": true,
      "description": "The advanced editor role in COGNIGY.AI",
      "value": "advanced_editor"
      "allowedMemberTypes": [
      "displayName": "Admin",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc4",
      "isEnabled": true,
      "description": "The admin role in COGNIGY.AI",
      "value": "admin"
      "allowedMemberTypes": [
      "displayName": "Developer",
      "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc3",
      "isEnabled": true,
      "description": "The developer role in COGNIGY.AI",
      "value": "developer"

Adding new App Roles to the application

You should also delete the preconfigured User role from the appRoles array.

After adding the JSON, click save and navigate back to your application in Azure Active Directory > Enterprise applications > . In here you can click on Users & Groups in 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.


Users with configured roles

You're now done configuring Single Sign-on for Azure AD, and your users can now login to COGNIGY.AI through Azure AD