Okta

Requirements
✔ SSO URL (Get it here)

Introduction

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

Creating an Application in Okta

In order to create an application in Okta, navigate to Applications > Applications and click onCreate New App. In the popup that opens, you have to select Web as the platform and select SAML 2.0 as the sign on method.

Creating an application

After clicking Create a new form will open where you can give the application a name, e.g. Cognigy.AI

Naming the application

Click on Next to start configuring the SAML settings.

Configuring SSO in Okta

The first thing you need to input is the Single Sign On URL and the Audience URI. They both need to be equal to the SSO Url (See Cognigy.AI SSO documentation).

You then need to change the Application username to be Email.

Configuring SSO

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

Encrypting the SAML requests

You can optionally choose to enable encryption of the SAML requests from Okta. To do this, you have to click on Show Advanced Settings, change the Assertion Encryption value to be Encrypted and upload a certificate. The private key of the certificate will be needed later when configuring SSO in Cognigy.AI

Adding encryption to the SAML requests

We can now add the required Attribute Statements for the application. The required attributes are:

• firstName: user.firstName
• lastName: user.lastName
• role: appuser.role

We will add the role as a profile field to the application in a later step.

Adding attribute statements

In the next step, you will be asked a few questions about the app integration. Simply answer that you are integrating with an internal app and click next.

Integration questions

Configuring SSO in Cognigy.AI

After configuring SSO in Okta, 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",
  "decryptionPrivateKey": "string"
}

In order to do this, you need some information from Okta, which you will find by navigating to the Sign On page in your application in Okta and clicking on View Setup Instructions in the yellow box.

Viewing the SAML Setup instructions in Okta

After clicking the button, a page will open with all the necessary information you need:

SAML setup instructions

You can now collect the information you need to create the SSO configuration in Cognigy.AI:

idpIssuer
The idpIssuer is the Identity Provider Issuer in Okta.

idpLoginEndpoint
The idpLoginEndpoint is the Identity Provider Single Sign On URL in Okta.

idpCertificate
This is the certificate that Okta uses to sign the SAML requests. Download the X.509 Certificate. After downloading the certificate, you need to base64 encode it 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.

decryptionPrivateKey
In case you chose to enable encryption for the SAML requests, then you also need to include a decryptionPrivateKey field in the request. To do this, you need to base64 encode the private key that matches the public key you uploaded to Okta and include it in the request.

You can now send the POST request to Cognigy.AI with the information you collected from Okta. An example payload is below:

JSON

{
    "idpLoginEndpoint": "https://dev-467122.oktapreview.com/app/cognigydev467122_cognigyai_2/exkjgn4ciarOVVUNi0h7/sso/saml",
    "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURwRENDQW95Z0F3SUJBZ0lHQVdoTU52M3FNQTBHQ1NxR1NJYjNEUUVCQ3dVQU1JR1NNUXN3Q1FZRFZRUUdFd0pWVXpFVE1CRUcNCkExVUVDQXdLUTJGc2FXWnZjbTVwWVRFV01CUUdBMVVFQnd3TlUyRnVJRVp5WVc1amFYTmpiekVOTUFzR0ExVUVDZ3dFVDJ0MFlURVUNCk1CSUdBMVVFQ3d3TFUxTlBVSEp2ZG1sa1pYSXhFekFSQmdOVkJBTU1DbVJsZGkwME5qY3hNakl4SERBYUJna3Foa2lHOXcwQkNRRVcNCkRXbHVabTlBYjJ0MFlTNWpiMjB3SGhjTk1Ua3dNVEUwTVRFMU16VTRXaGNOTWprd01URTBNVEUxTkRVNFdqQ0JrakVMTUFrR0ExVUUNCkJoTUNWVk14RXpBUkJnTlZCQWdNQ2tOaGJHbG1iM0p1YVdFeEZqQVVCZ05WQkFjTURWTmhiaUJHY21GdVkybHpZMjh4RFRBTEJnTlYNCkJBb01CRTlyZEdFeEZEQVNCZ05WQkFzTUMxTlRUMUJ5YjNacFpHVnlNUk13RVFZRFZRUUREQXBrWlhZdE5EWTNNVEl5TVJ3d0dnWUoNCktvWklodmNOQVFrQkZnMXBibVp2UUc5cmRHRXVZMjl0TUlJQklqQU5CZ2txaGtpRzl3*********************************************************************************R1lxbUtTcC94NTgzMTdIejMNCjVzckJXelNwa1JhZEJWNlI5SHora1ZLakRQMVBFZGgvN0h6b0tIMmJCdDE0VHJ4LytFQ2kyYVpwdmU3MDhhRWowR3lCVWhkZ1hpTnANCnFxM3JaOEJkdjFkQUdQRUdLQ3JQN2dLTzNJVnNDMVpWTFMwVzRRSURBUUFCTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFCZGNWSUsNCkpMZDVGdGl1RGNEMU1oYXU3WHN6dnVhd2U3bEUxcDJrSVFlSm5Cdk1zVjdRVmVZMk1weGl5UmRDREI5dHJkQ055TkR6R3BGZEsrb3oNCmRZTUplKzVycXQ0YnFLM1BGMko3TjJUKy91UVJMbkhEbzByRU9salBIRzJUZFR0SlUrSytHUEY3a2UvQmhmUVNvVk42TnR0NGlST2YNClRjTGVSUi9PSzVjdWJVUDFUVWg1NWpSL3NZTXNlMk9aeUNYSlgyOGVXK3hDS3A5dXJUeUhUS09mT0hjRSs3NTBQWFBObWJCOXNUQysNClV5RUYvaTREeUM4VDRLSG95bG1DRU54TUhqSzFTaTYwNHkvc1ZIT0R5MjlwejlkS2gwUlRLcjVUcmdkZ1pMTG5LTlhqeEM1M0pXdjgNCmk1Q2FYaTJmTHVMdE9ldXNHRjZXa3VCeGtMQVkrR0tZDQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
    "idpIssuer": "http://www.okta.com/exkjgn4ciarOVVUNi0h73"
}

And here is an example payload with a decryptionPrivateKey:

{
    "decryptionPrivateKey": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUpRd0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQ1Mwd2dna3BBZ0VBQW9JQ0FRREZCVnIyRUNDSFdkajkKYXN5ZjlwaHE5WnhHN1NMNEVhQ2cxMVlQLzBpUnZEZXl5WlpvOVA4ODh0OGIzYm50MWJkbTdLV3JrazdScGtzOApCKzgweDZzYVovVGNGUTlwUGx0NFpUSllNMUI1cGxESTcwMVZncHFnRzlObmVtcE5IUzB1UzVQc3M4d3VsSnZUCkhwazNLQlIzOVZEeElTL3ZXZm9tZ1VNNmc1alo4Z09PYjZ4eGF4UWxKWjRkcXNRZWFoMm5QZjdHamFBN29wRmIKRDNRYkxQMG0reGZudzhtOW9sUFg0N0sxV0JhNmZLeG9RRjk5YmJVaThWT1YrK1h5VXg3MXNaeGhpd1JkZFJvVQpKWnBjN0FjajZ5YU1BdEFpL242OG10S0VXNFBDbm54Sm8vVzFqOXVyK2ZVNDNRTnhQaDc1VDZjaHZJd2I5ek1wCkxyRzNwRWRybUdmSDZVbG9rNkF6a3kyaVd6TjZuQnRLeUlTVWpETWFYdFI2YXhuakQ5TlppTEhoMzRyVjVkY1cKdDlUR1lBMVJSY0ZtcytiYnY5L09yaGJxQ2Q3UjQvUWd5bGVzSEpBdG1nZEdrMkRWV2dyKzJMaFFVZ2taTk1TZgplMi9ZZzdxVm5sVWNnZWhlci90U21JcHBmdEx1R0pReUM0aUdEelA5MDRDdkhKdG5uN1ZlenJKRUJ6Yk13VVF2CmVUL1JJSEJxeFBQVDZxZGgrRGtLakZla0trV0xrMkN6UnN6cWI3RDc5Nzl3YzA5aVoxb3MwbWxWenlmL0NDRjAKSHBDOUZTL1AzVHV0T0VqTDRxVDZaek1OaUZOM25Zd21UVnd0QXNGVS9ZTm9vcFc4ZFNXdjBnaWNDT2JPNDVmNwprdVdLSlEzekJzMUQrT1hydHB2YjY5d0gyTkJTcndJREFRQUJBb0lDQURwOGwzOGFWSDI1cDFlN1g1bFErL2dzCmgwTHEzSW1sdWZobFZGQVZhWGFSMkRzRDZ0bW5lU21mczZtekRhSFQ0c  *********************************************************************************VzSTUzb3kvQUt4c0w5Q2Fma1N2WThoUWI2MGF2UENDaApwbUFsQW9JQkFCeEdoM1FxMXM2N2NPeDk3VjRLdGM5c2hReVFGWW9jQWtsbG9VWDR0UkxtQlFIVXFuMXZZd3R5CjUvWHpJdDVZSEl6a3dTU1krb3ZsMVBMVmlpS2hBazhrdE5pNjB5VE9nNnFrdUp6WGM4U3NHL1M3MzUwTXlnTmQKYVA0R2paZm5uNTYxTW10V2tOckZCRWhYTUpBTnJ6R0tyTExLUWx0dmtyeVQyQXJweUlZb29lT2JVSmNjMTJuTgpWRnk1OHhvK0pZRWxIamlGd2RONUR3N0V6YU0wNG8yallnbUxHSDZ2UkE5SzRHd2JlbWdtb2p2dnZRMVJBa1VBCldTZ2o2VGtkL3BsbVROV2RNVFNpYTBwTEtROUhUOUl3K0tEV2htMXNWY2dIZC9jUzVzd1VvVFFkakFhdzlhd1QKTS9sd0xYQWh6eURtTUNaRmsvU1M3V3Fnek1RWlJBND0KLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLQo=",
    "idpLoginEndpoint": "https://dev-467122.oktapreview.com/app/cognigydev467122_cognigyai_2/exkjgn4ciarOVVUNi0h7/sso/saml",
    "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURwRENDQW95Z0F3SUJBZ0lHQVdoTU52M3FNQTBHQ1NxR1NJYjNEUUVCQ3dVQU1JR1NNUXN3Q1FZRFZRUUdFd0pWVXpFVE1CRUcNCkExVUVDQXdLUTJGc2FXWnZjbTVwWVRFV01CUUdBMVVFQnd3TlUyRnVJRVp5WVc1amFYTmpiekVOTUFzR0ExVUVDZ3dFVDJ0MFlURVUNCk1CSUdBMVVFQ3d3TFUxTlBVSEp2ZG1sa1pYSXhFekFSQmdOVkJBTU1DbVJsZGkwME5qY3hNakl4SERBYUJna3Foa2lHOXcwQkNRRVcNCkRXbHVabTlBYjJ0MFlTNWpiMjB3SGhjTk1Ua3dNVEUwTVRFMU16VTRXaGNOTWprd01URTBNVEUxTkRVNFdqQ0JrakVMTUFrR0ExVUUNCkJoTUNWVk14RXpBUkJnTlZCQWdNQ2tOaGJHbG1iM0p1YVdFeEZqQVVCZ05WQkFjTURWTmhiaUJHY21GdVkybHpZMjh4RFRBTEJnTlYNCkJBb01CRTlyZEdFeEZEQVNCZ05WQkFzTUMxTlRUMUJ5YjNacFpHVnlNUk13RVFZRFZRUUREQXBrWlhZdE5EWTNNVEl5TVJ3d0dnWUoNCktvWklodmNOQVFrQkZnMXBibVp2UUc5cmRHRXVZMjl0TUlJQklqQU5CZ2txaGtpRzl3*********************************************************************************R1lxbUtTcC94NTgzMTdIejMNCjVzckJXelNwa1JhZEJWNlI5SHora1ZLakRQMVBFZGgvN0h6b0tIMmJCdDE0VHJ4LytFQ2kyYVpwdmU3MDhhRWowR3lCVWhkZ1hpTnANCnFxM3JaOEJkdjFkQUdQRUdLQ3JQN2dLTzNJVnNDMVpWTFMwVzRRSURBUUFCTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFCZGNWSUsNCkpMZDVGdGl1RGNEMU1oYXU3WHN6dnVhd2U3bEUxcDJrSVFlSm5Cdk1zVjdRVmVZMk1weGl5UmRDREI5dHJkQ055TkR6R3BGZEsrb3oNCmRZTUplKzVycXQ0YnFLM1BGMko3TjJUKy91UVJMbkhEbzByRU9salBIRzJUZFR0SlUrSytHUEY3a2UvQmhmUVNvVk42TnR0NGlST2YNClRjTGVSUi9PSzVjdWJVUDFUVWg1NWpSL3NZTXNlMk9aeUNYSlgyOGVXK3hDS3A5dXJUeUhUS09mT0hjRSs3NTBQWFBObWJCOXNUQysNClV5RUYvaTREeUM4VDRLSG95bG1DRU54TUhqSzFTaTYwNHkvc1ZIT0R5MjlwejlkS2gwUlRLcjVUcmdkZ1pMTG5LTlhqeEM1M0pXdjgNCmk1Q2FYaTJmTHVMdE9ldXNHRjZXa3VCeGtMQVkrR0tZDQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
    "idpIssuer": "http://www.okta.com/exkjgn4ciarOVVUNi0h73"
  }

Configuring User Roles

In order to configure user roles for the users in Cognigy.AI, you have to add a profile field to your app. To do this, navigate to Directory > Profile Editor and edit the profile for the Cognigy.AI application.

Profile editor in Okta

Now click on Add Attribute to add Role as a new profile field to the app.

Adding roles to the app profile

In the form that opens, you need to input the following information:

• The variable name has to be "role"
• You can check the checbox for Enum and input the following supported roles: admin, apiKeys, base_role, livechat, odata, projectmanager and userManager in the value fields. The display name can be anything but the value must match the aforementioned strings.
• Check the checkbox for Attribute required

After saving the new profile field, navigate back to your app, open the tab Assignments, edit a profile and give them a role.

Assigning roles to users

This user can now login to Cognigy.AI via Okta and will have the assigned role in Cognigy.AI.