Requirements
✔ SSO URL (Get it here)

Introduction

This guide covers how to setup SSO in Cognigy.AI with Auth0 as the Identity Provider. After completing this guide, your users can login to Cognigy.AI through Auth0 and will automatically get a user in Cognigy.AI complete with access control.

Creating an Application in Auth0

The first step is to create an Enterprise application in Auth0 that is used to connect to Cognigy.AI. I

mceclip0.png

Creating a new Application in Auth0

After clicking on Create Application, make sure to pick the Single Page Web Application type and give your application a suitable now.

 

mceclip1.png

Creating your new Single Page Web Application

 

Configuring Single Sign-on for the Application in Auth0

After creating your new Single Page Application, make head over to the Settings tab and scroll down until you see the field

 

mceclip3.png

Configuring the Allowed Callback URLs with your SSO URL

 

Configuring SSO in Cognigy.AI

After configuring SSO in Auth0, 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.

 

Finding the relevant information in Auth0. 

In the Application view, click on the Addons tab and make sure to enable SAML2 WEB APP by clicking on the switch button.

mceclip6.png

 

Enabling the SAML2 WEB APP settings

This renders a pop-up window with the relevant information for your API request. 

mceclip5.png

 

SAML2 Settings


idpIssuer
The idpIssuer is the Issuer in Auth0.

idpLoginEndpoint
The idpLoginEndpoint is the Identity Provider Login URLin  Auth0. 

idpCertificate
You can download the certificate by clickin on the Download Auth0 certifucate button. 

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 Auth0. An example payload is below:

{
  "idpIssuer": "urnn:dev-chxoja2p.eu.auth0.com",
  "idpLoginEndpoint": "https://dev-chxoja2p.eu.auth0.com/samlp/**********************",
  "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tDQpNSUlDOERDQ0FkaWdBd0lCQWdJUWM3RFNuaXdMdTdoTTJwR0V3YTFXR1RBTkJna3Foa2lHOXcwQkFRc0ZBREEwTVRJd01BWURWUVFEDQpFeWxOYVdOeWIzTnZablFnUVhwMWNtVWdSbVZrWlhKaGRHVmtJRk5UVHlCRFpYSjBhV1pwWTJGMFpUQWVGdzB4T1RBeE1UZ3hNRE0yDQpNelJhRncweU1qQXhNVGd4TURNMk16UmFNRFF4TWpBd0JnTlZCQU1US1UxcFkzSnZjMjltZENCQmVuVnlaU0JHWldSbGNtRjBaV1FnDQpVMU5QSUVObGNuUnBabWxqWVhSbE1JSUJJakFOQmdrcWhraUc********************************************************************************6cHFYDQo4K1ZOdVVhdUxJNEpodXZlR29GMDViaGxzQVVRVkNXTTJTN2tqazJ0enNwck8xZjJScXYvSHp2K1IxVFRHWlRQMlB4U0lVcm9tS3JLDQoxcnRmT2NU*******"
}

 

Configuring User Roles

In order to configure user roles for the users in Cognigy.AI, please navigate to the User Management view in Auth0 and scroll down until you see the section Metadata. Make sure to copy the following code in to the user_metadata JSON field.

mceclip7.png

{
"family_name": "Builder",
"given_name": "Bob",
"role": "admin"
}

 

Adding new App Roles to the application

 

Finally, create and enable a new Rule called AddUserMeta under the Rules menu of the Auth Pipeline section. 

mceclip8.png

                                                      Creating a new Rule

mceclip9.png

You can copy the following code snippet, that will help map the user schema.

function mapSamlAttributes(user, context, callback) {
context.samlConfiguration.mappings = {
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "email",
"firstName": "user_metadata.given_name",
"lastName": "user_metadata.family_name",
"role": "user_metadata.role"
};

callback(null, user, context);
}

 

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. 

You're now done configuring Single Sign-on for Auth0, and your users can now login to Cognigy.AI through Auth0 by clicking on the LOGIN WITH SSO button in the Cognigy.AI login screen

mceclip10.png


Comments

0 comments

Please sign in to leave a comment.

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