Introduction
This guide covers how to set up SSO in Cognigy.AI with Auth0 as the Identity Provider. After completing this guide, your users can log in to Cognigy.AI through Auth0, which will automatically create a user account in your Cognigy.AI instance with a Cognigy.AI access role as defined by the administrator in Auth0.
Requirements
✔ SSO URL (Get it here)
SSO Options with Auth0
When setting up SSO with Auth0, you can choose between two different SSO protocols. This article covers the SAML2.0 protocol. For OpenID Connect, please refer to the following article:
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
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 version.
Creating your new Single Page Web Application
Configuring Single Sign-on for the Application in Auth0
After creating your new Single-Page Application, head over to the Settings tab and scroll down until you see the field
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 organization 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 the SAML2 WEB APP by clicking on the switch button.
Enabling the SAML2 WEB APP settings
This renders a pop-up window with the relevant information for your API request.
SAML2 Settings
idpIssuer
The idpIssuer is the Issuer
in Auth0.
idpLoginEndpoint
The idpLoginEndpoint is the Identity Provider Login URL
in Auth0.
idpCertificate
You can download the certificate by clicking 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 IDP certificate.
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
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 into the user_metadata JSON field.
{
"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.
Creating a new Rule
You can copy the following code snippet that helps 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 done configuring Single Sign-on for Auth0, and your users can now log in to Cognigy.AI through Auth0 by clicking the LOGIN WITH SSO button on the Cognigy.AI login screen.
Comments
0 comments