Google

Requirements
✔ SSO URL (Get it here)

Introduction

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

Adding Custom User Attributes in Google

The first thing you need to do is to add the necessary custom user attributes that Cognigy.AI needs to create the user when they login the first time. To do this, open the menu on the left and navigate to Users > Manage user attributes.

Click on the Add Custom Attribute button in the top right corner to start adding your custom attributes. The user needs to have the following custom attributes set:

• First Name
• Last Name
• Role

If the user already has a First Name and Last Name set, then you don't have to create them again.

The role field determines which role the user will have in Cognigy.AI. The supported roles within Cognigy.AI are as follows: admin, developer, advanced_editor, marketer and basic. You can read more about user roles here. If a user does not have a role assigned, then they will be created as a user with the basic role in Cognigy.AI

Adding the neccessary custom attributes

Creating an Application in Google

The first step is to create a new SAML app within Google. To do this, open the side menu panel of Google and navigate to Apps > SAML Apps. On this page, you can click on the button in the lower right corner to create a new app.

Creating a new SAML App

This will open a modal with a lot of different applications you can choose to create.

Creating your own SAML APP

Click on the button in the lower left corner Setup My Own Custom App to complete step 1.

Creating a custom SAML application

In step 2, you have to copy the SSO URL and download the Certificate under Option 1, since we need this for later when setting up the identityProvider configuration in Cognigy.AI. Then click on Next.

Naming the SAML App

In step 3 you have to provide a name for the Saml App (e.g. Cognigy). Then proceed to the next step.

Providing SP Details

In step 4, you need to insert the SSO URL (See Cognigy.AI SSO documentation) in the ACS URL and Entity ID fields. You also need to check the Signed Response checkbox and set the Name ID Format to EMAIL

*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).

Adding attribute mapping

In step 5, you need to create the attribute mapping for the attributes we created in the previous section. The mapping need to be as follows:

• firstName -> The first name of the user
• lastName -> The last name of the user
• role -> The role the user should have within Cognigy.AI.

You have now finished creating the Cognigy.AI SAML App in Google. The last thing to do is to activate the application, and you can then proceed to creating the necessary configuration within Cognigy.AI

Configure SSO in Cognigy.AI

After configuring SSO in Google, 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"
}

idpIssuer
The idpIssuer is the Entity ID of the SAML App, which is equal to the SSO URL (See Cognigy.AI SSO documentation).

idpLoginEndpoint
The idpLoginEndpoint is the SSO URL that you copied in step 1 of the SAML App creation. Looks something like https://accounts.google.com/o/saml2/idp?idpid=XXXX

idpCertificate
The idpCertificate is the certificate that you downloaded in step 1 of the SAML App creation. You need to base64 encode the certificate without newlines. In Linux, you can do this by running the following command:

Shell

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 to Cognigy.AI with the information you collected from Google. An example payload is below:

{
    "idpLoginEndpoint": "https://accounts.google.com/o/saml2/idp?idpid=C01h0p2y5",
    "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURkRENDQWx5Z0F3SUJBZ0lHQVdwOTRoS2dNQTBHQ1NxR1NJYjNEUUVCQ3dVQU1Ic3hGREFTQmdOVkJBb1RDMGR2YjJkc1pTQkoKYm1NdU1SWXdGQVlEVlFRSEV3MU5iM1Z1ZEdGcGJpQldhV1YzTVE4d0RRWURWUVFERXdaSGIyOW5iR1V4R0RBV0JnTlZCQXNURDBkdgpiMmRzWlNCR2IzSWdWMjl5YXpFTE1Ba0dBMVVFQmhNQ1ZWTXhFekFSQmdOVkJBZ1RDa05oYkdsbWIzSnVhV0V3SGhjTk1Ua3dOVEF6Ck1UTXlPRFE0V2hjTk1qUXdOVEF4TVRNeU9EUTRXakI3TVJRd0VnWUR********************************************************************************vWSt2NUhYTG56M05DUE8wSmFHWDUyN2U1V2JOU2lFL2oyMmpDUDRNL2gya0Jjd1RxaTB5Zk5tMGZubVFQdWZITnllaWkKRTN1VWkyc2t5UFp2N0UxbGdaRk9mZ3NhMEw2d0pYZkdzMDVjaWkyM1h3bGZQWWlOeXVEMjRNdjVDMTM1MzZRbEx4R0FhcGo5dFB2QQpxLzgzY0ZETUJGUS9EQWdKWVV6S0ZXRHltOGtndG5NUTNjSlpBRkNhcWo2R0JRcEdSbVQxVlBaTmtmcEozMUVtbDV4dHRkSnl0VVVIClZsQjRoc3lYVHJBeE9pc1laSjRwQ2Zjbm9YUjk2MmVrS1B0bVJHTUhQS3VkCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=",
    "idpIssuer": "https://api-trial.cognigy.ai/new/auth/saml/login/5af5babcdc3b005391f80afe"
}

You now have configured Single Sign-on for Google, and your users can now login to Cognigy.AI through Google