Single Sign-on with 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 on Add Application. 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 you got from the previous guide.
You then need to change the Application username to be Email.
Configuring SSO
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:///security/identityprovider (e.g. https://api-demo.cognigy.ai/security/identityprovider) with the following JSON payload:
{
"idpIssuer": string,
"idpLoginEndpoint": string,
"idpCertificate": string,
"decryptionPrivateKey"?: string
}
API Authentication
Read our API reference guide for information about how to send authenticated API requests to COGNIGY.AI
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:
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.
Optional private key
You should NOT include the private key in the request if the requests from Okta are not encrypted
You can now send the POST request to COGNIGY.AI with the information you collected from Okta. An example payload is below:
{
"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 role 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
Enumand input the following supported roles: admin, developer, advanced_editor, marketer and basic in the value fields. The display name you can write as you want. - 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
Updated over 3 years ago