Identity Providers - Cognigy Documentation

Cognigy.AI integrates with popular identity providers (IdPs) to let users in your organization log in with single sign-on (SSO) without the need for individual credentials. You can use the following IdPs:

Auth0 with OpenID Connect
Auth0 with SAML 2.0
Microsoft Entra ID
Google
Okta
OneLogin

For more information about about protocol-level details, see Single Sign-on with SAML 2.0.

Prerequisites

An account with the admin role in Cognigy.AI.
The organization ID of your Cognigy.AI organization, referred to as <organization-id> in the examples. You can copy this ID from the My Profile page by clicking > Copy Organization ID.
The API base URL of your Cognigy.AI installation, referred to as <api-base-url> in the examples.
Your Cognigy.AI URL, referred to as <cognigy-url> in the examples. For example, for the trial environment, this URL is https://trial.cognigy.ai/.
An API key for sending configuration requests to the Cognigy.AI API.
Administrator access to the IdP tenant that you want to integrate with Cognigy.AI.
For Okta, you need an X.509 certificate. For more information, read Okta’s documentation about app certificate use.

Limitations

An organization can have only one SSO configuration. To replace an SSO configuration, delete it, then create another one. For more information, read Change an SSO Configuration in Cognigy.AI.
Only Microsoft Entra ID and OneLogin support single logout for Cognigy.AI.

Create an IdP App

To configure an IdP app, follow these steps:

Log in to the Auth0 Dashboard and select your tenant.
In the left-side menu, go to Applications > Applications and click + Create Application.
Enter a name, for example, Cognigy.AI, select Regular Web Applications as the app type, and click Create.
Go to the Settings tab and copy the values from the fields in the Basic Information section. You will use them later to configure the IdP in Cognigy.AI:
- Domain — used in the idpIssuer parameter in the request payload.
- Client ID — used in the idpClientId parameter in the request payload.
- Client Secret — used in the idpClientSecret parameter in the request payload.
On the Settings tab, configure the following using the API base URL and organization ID from the Prerequisites section:
- Application Login URI — enter https://<api-base-url>/auth/oidc/callback/<organization-id>.
- Allowed Callback URLs — enter https://<api-base-url>/auth/oidc/login/callback/<organization-id>.
- Allowed Logout URLs — enter https://<api-base-url>/logout/<organization-id>.
- Allowed Web Origins — enter https://*.cognigy.ai.
- Allowed Origins (CORS) — enter https://*.cognigy.ai.

Set Up an App

Log in to the Auth0 Dashboard and select your tenant.
In the left-side menu, go to Applications > Applications and click + Create Application.
Enter a name, for example, Cognigy.AI, select Single Page Web Applications as the app type, and click Create.
Go to the Settings tab, configure the following using the API base URL and organization ID from the Prerequisites section:
- Application Login URI — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Allowed Callback URLs — enter https://<api-base-url>/auth/oidc/login/callback/<organization-id>.
On the Addons tab, activate the SAML2 Web App add-on. Auth0 opens the add-on settings dialog. From the Usage tab, copy and save the values from the following fields for later use in the API request payload to configure the IdP in Cognigy.AI:
- Issuer — used in the idpIssuer parameter in the request payload.
- Identity Provider Login URL — used in the idpLoginEndpoint parameter in the request payload.
- Identity Provider Certificate — used in the idpCertificate parameter in the request payload. Click Download Auth0 certificate. Base64-encode the certificate without line breaks. You can use the following terminal command:
  [Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))

Map Roles

For each user which you want to apply SSO to, set user_metadata to map the user’s name and Cognigy.AI role. To do so, follow these steps:

Go to User Management > Users, select the user, scroll to the Metadata section, and paste the following JSON into the user_metadata field:
```
{
  "family_name": "<LAST NAME>",
  "given_name": "<FIRST NAME>",
  "role": "<COGNIGY_ROLE>"
}
```
The role value must match a role in Cognigy.AI, for example, admin or base_role.
Go to Actions > Library, click Create Action, and configure the following:

Name — enter a name.
Login / Post Login — activate this option.

In the editor, paste the following code:

exports.onExecutePostLogin = async (event, api) => {
  const userMetadata = event.user.user_metadata || {};

  api.samlResponse.setAttribute(
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    event.user.email
  );
  api.samlResponse.setAttribute("firstName", userMetadata.given_name || "");
  api.samlResponse.setAttribute("lastName", userMetadata.family_name || "");
  api.samlResponse.setAttribute("role", userMetadata.role || "");
};

Deploy the Action.

Set Up an App

Log in to the Azure portal with an administrator account and navigate to Microsoft Entra ID.
In the top bar, click + Add and select Enterprise applications. The Browse Microsoft Entra Gallery page opens.
In the top bar, click + Create your own application.
Enter a name, for example, Cognigy.AI, select Integrate any other app you don’t find in the gallery (Non-gallery), and click Create.
On the new app page, open Single sign-on in the left navigation and select SAML as the sign-on method.
In the Basic SAML Configuration section, click Edit and configure the following:
- Identifier (Entity ID) — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Reply URL (Assertion Consumer Service URL) — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Sign on URL — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- (Optional) Logout Url — enter https://<cognigy-url>/slo/<organization-id>.
Click Save.

Map User Attributes

In the User Attributes and Claims section, click Edit and confirm that the following claims are mapped to the user’s profile attributes:

Claim name	Value
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	`user.mail`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`	`user.givenname`
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`	`user.surname`

Cognigy.AI uses the email claim to identify the user and to create the Cognigy.AI account on the first login.

Get Authentication Data

In the SAML Signing Certificate section, locate Certificate (Base64) and click Download. Save the file locally. Use this certificate as idpCertificate in the API request to configure the IdP in Cognigy.AI. You need to encode the certificate as base64 without newlines beforehand. To do so, use the following terminal command:
[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))
In the Set up <application name> section, copy the following values to be used in the API request to configure the IdP in Cognigy.AI:

Login URL — used in the idpLoginEndpoint parameter in the request payload.
(Optional) Logout URL — used in the idpLogoutUrl parameter in the request payload when you enable single logout.

Assign Roles

In the top bar, search for App registrations and select this option.
In the All applications tab, search for the app you created and select it.

In the left-side menu, go to Manage > Manifest and deactivate the default User and msiam_access roles. To do so:

Set isEnabled to false for the User and msiam_access roles, for example:

"appRoles": [
  {
    "allowedMemberTypes": [
      "User"
    ],
    "description": "User",
    "displayName": "User",
    "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f",
    "isEnabled": false,
    "origin": "Application",
    "value": null
  },
  {
    "allowedMemberTypes": [
      "User"
    ],
    "description": "msiam_access",
    "displayName": "msiam_access",
    "id": "b9632174-c057-4f7e-951b-be3adc52bfe6",
    "isEnabled": false,
    "origin": "Application",
    "value": null
  }
]

In the left-side menu, go to Manage > App roles, select the User role, and click Delete on the right-side pane. Do the same for the msiam_access role.

Paste the following JSON code in the appRoles array:

Roles Array

{
  "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 apiKeys 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"
}

In the left-side menu, go to Users and groups and assign the app to the users or groups that must have access to Cognigy.AI through SSO.

Add a Custom Attribute

You need to add a custom attribute that Cognigy.AI uses when the user logs in for the first time. To do so, follow these steps:

Log in to the Google Admin console.
In the left-side menu, go to Directory > Users.
At the top of the Users list, click More options > Manage user attributes.
Click the Add Custom Attribute button and configure the following:
- Category — enter a unique name to identify the custom attribute, for example, Cognigy.AI SSO.
- Description — enter a relevant description of the custom attribute.
- In the Custom fields section, configure three custom fields with the following values:
  Name Info type Visibility Number of values
  First Name Text Visible to user and admin Single value
  Last Name Text Visible to user and admin Single value
  Role Text Visible to user and admin Single value
If a user doesn’t have a role assigned, Cognigy.AI assigns base_role to the user.
Click Add.

Name	Info type	Visibility	Number of values
First Name	Text	Visible to user and admin	Single value
Last Name	Text	Visible to user and admin	Single value
Role	Text	Visible to user and admin	Single value

Set Up an App

In the left-side menu, go to Apps > SAML Apps.
Click the plus button in the lower-right corner and select Setup My Own Custom App.
In the Google IdP Information dialog, copy the SSO URL value and download the certificate. You’ll use the SSO URL as idpLoginEndpoint and the certificate as idpCertificate in the API request to configure the IdP in Cognigy.AI. You need to encode the certificate as base64 without newlines beforehand. To do so, use the following terminal command:
[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))
Click Next.
Enter a name for the app, for example, Cognigy.AI, and click Next.
On the service provider details page, configure the following:
- ACS URL — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Entity ID — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Signed Response — select the checkbox.
- Name ID Format — set to EMAIL.
Click Next.
On the Attribute Mapping page, add the following attribute mappings so that Cognigy.AI receives the user’s first name, last name, and role from Google:

Service Provider Attribute	Custom Attribute	Field
`firstName`	Cognigy.AI SSO	First Name
`lastName`	Cognigy.AI SSO	Last Name
`role`	Cognigy.AI SSO	Role

Click Finish, then activate the app for the users or organizational units that must have access to Cognigy.AI through Google SSO.

Set Up an App

Log in to your Okta Admin Console with an administrator account.
In the left-side menu, go to Applications > Applications and click Create New App.
Select SAML 2.0 as the sign-on method and click Create.
On the General Settings tab, enter an app name, for example, Cognigy.AI SSO, optionally upload a logo, and click Next.
On the Configure SAML tab, configure the following:
- Single sign-on URL — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Use this for Recipient URL and Destination URL — keep selected.
- Audience URI (SP Entity ID) — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- Name ID format — select Unspecified.
- Application username — select Email.
- Update application username on — select Create and update.
(Optional) To encrypt SAML requests, click Show Advanced Settings, set Assertion Encryption to Encrypted, and upload an X.509 certificate. You will need the private key of this certificate to register the IdP in Cognigy.AI.

Map User Attributes

In the Attribute Statements section, add the following attributes so that Cognigy.AI receives the user profile data it needs to create the account:
Name Name format Value
email Unspecified user.email
firstName Unspecified user.firstName
lastName Unspecified user.lastName
Click Next.
On the Feedback tab, select I’m an Okta customer adding an internal app and click Finish.

Name	Name format	Value
`email`	Unspecified	`user.email`
`firstName`	Unspecified	`user.firstName`
`lastName`	Unspecified	`user.lastName`

Get Authentication Data

On the Applications page, select the app you created, then open the Sign On tab.
In the SAML Signing Certificates section, click View Setup Instructions or Identity Provider metadata and copy the following values:
- Identity Provider Single Sign-On URL — used in the idpLoginEndpoint parameter in the request payload.
- Identity Provider Issuer — used in the idpIssuer parameter in the request payload.
- X.509 Certificate — used in the idpCertificate parameter in the request payload. You need to encode the certificate as base64 without newlines beforehand. If you enabled SAML request encryption, you also need to encode the private key as base64. You can use the following terminal command:
  [Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate-or-private-key"))

Assign Users

In the left-side menu of the Admin Console, go to Directory > Profile Editor, and click Profile next to the profile of the app you created.
Click Add Attribute and configure the following:
- Data type — select string.
- Display name — enter Role.
- Variable name — enter role.
- (Optional) Description — enter a relevant description, for example, The role of the user in Cognigy.AI.
- Enum — activate Define enumerated list of values.
- Attribute member — enter a display name and the value of the role to which SSO applies, for example, Base Role and base_role. The value must match a role in Cognigy.AI.
- Attribute required — select this option.
  Click Save.
Go to Applications > Applications and select the app you created.
On the Assignments tab, click the Edit button next to the user’s name and assign the role they should have in Cognigy.AI. This user can log in via SSO.

Set Up an App

Log in to your OneLogin Administration portal with an administrator account.
In the top bar, click Applications, then click Add App in the upper-right corner.
Search for SAML Custom Connector (Advanced) in the search field and select this option.
In the Display Name field, enter a name that identifies the integration, for example, Cognigy.AI SSO. Optionally upload icons. Click Save.
On the new app page, click the Configuration tab in the left-side menu and configure the following:
- ACS (Consumer) URL — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- ACS (Consumer) URL Validator — enter https://<api-base-url>/auth/saml/login/<organization-id>.
- (Optional) Single Logout URL — enter https://<cognigy-url>/slo/<organization-id>.
Click Save.
In the left-side menu, go to the Parameters tab, configure the following parameter and value pairs, and select the Include in SAML assertion option for each pair:
Parameter Value
email Email
firstName First Name
lastName Last Name
role User Role
Click Save to apply the attribute mapping.

Parameter	Value
`email`	Email
`firstName`	First Name
`lastName`	Last Name
`role`	User Role

Get Authentication Data

In the left-side menu, go to the SSO tab and copy the following values:
- X.509 Certificate — click View Details and download the certificate. You will use its contents as idpCertificate. You need to encode the certificate as base64 without newlines beforehand. You can use the following terminal command:
  [Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))
- Issuer URL — used in the idpIssuer parameter in the request payload.
- SAML 2.0 Endpoint (HTTP) — used in the idpLoginEndpoint parameter in the request payload.
- (Optional) SLO Endpoint — used in the idpLogoutEndpoint parameter in the request payload.
In the left-side menu, navigate to Users > Roles and click New Role.
Add the following Cognigy.AI roles one by one, select the app you created, and click Save:
- admin
- apiKeys
- base_role
- livechat
- odata
- projectManager
- userManager
In the left-side menu, go to the Users tab and select a user for SSO. On the user page, enter the role they have in Cognigy.AI in the role field. The role must match the roles you configured in step 3.
Click Save. The user can log in via SSO.

Configure SSO in Cognigy.AI

After the SSO app is ready, use the POST /v2.0/identityprovider/configure method to register the SSO configuration in Cognigy.AI.

Send the API request with the following parameters:

X-API-Key header — the API key from the Prerequisites section.
idpIssuer — the Domain value you copied earlier from the Settings tab.
idpClientId — the Client ID value you copied earlier from the Settings tab.
idpClientSecret — the Client Secret value you copied earlier from the Settings tab.

API Request Example

  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-token>" \
  -d '{
    "idpType": "oidc",
    "idpIssuer": "<DOMAIN>",
    "idpClientId": "<CLIENT ID>",
    "idpClientSecret": "<CLIENT SECRET>",
    "idpIdTokenSignedResponseAlg": "RS256",
    "idpTokenEndpointAuthMethod": "client_secret_basic"
  }'