Prerequisites
- An account with the admin role in Cognigy.
- The organization ID of your Cognigy organization, referred to as
<organization-id>in the examples. You can copy this ID from the My Profile page by clicking
- The API base URL of your Cognigy installation, referred to as
<api-base-url>in the examples. - Your Cognigy URL, referred to as
<cognigy-url>in the examples. For example, for the trial environment, this URL ishttps://trial.cognigy.ai/. - An API key for sending configuration requests to the Cognigy API.
- Administrator access to the IdP tenant that you want to integrate with Cognigy.
- For Okta, you need an X.509 certificate. For more information, read Okta’s documentation about app certificate use.
Limitations
- An organization can have only one SSO configuration. To replace an SSO configuration, delete it, then create another one. For more information, read Change an SSO Configuration in Cognigy.
- Only Microsoft Entra ID and OneLogin support single logout for Cognigy.
Create an IdP App
To configure an IdP app, follow these steps:- Auth0 - OpenID Connect
- Auth0 - SAML 2.0
- Microsoft Entra ID
- Google
- Okta
- OneLogin
- Log in to the Auth0 Dashboard and select your tenant.
- In the left-side menu, go to Applications > Applications and click + Create Application.
-
Enter a name, for example,
Cognigy, select Regular Web Applications as the app type, and click Create. -
Go to the Settings tab and copy the values from the fields in the Basic Information section. You will use them later to configure the IdP in Cognigy:
- Domain — used in the
idpIssuerparameter in the request payload. - Client ID — used in the
idpClientIdparameter in the request payload. - Client Secret — used in the
idpClientSecretparameter in the request payload.
- Domain — used in the
-
On the Settings tab, configure the following using the API base URL and organization ID from the Prerequisites section:
- Application Login URI — enter
https://<api-base-url>/auth/oidc/callback/<organization-id>. - Allowed Callback URLs — enter
https://<api-base-url>/auth/oidc/login/callback/<organization-id>. - Allowed Logout URLs — enter
https://<api-base-url>/logout/<organization-id>. - Allowed Web Origins — enter
https://*.cognigy.ai. - Allowed Origins (CORS) — enter
https://*.cognigy.ai.
- Application Login URI — enter
1
Set Up an App
- Log in to the Auth0 Dashboard and select your tenant.
- In the left-side menu, go to Applications > Applications and click + Create Application.
-
Enter a name, for example,
Cognigy, select Single Page Web Applications as the app type, and click Create. -
Go to the Settings tab, configure the following using the API base URL and organization ID from the Prerequisites section:
- Application Login URI — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Allowed Callback URLs — enter
https://<api-base-url>/auth/oidc/login/callback/<organization-id>.
- Application Login URI — enter
-
On the Addons tab, activate the SAML2 Web App add-on. Auth0 opens the add-on settings dialog. From the Usage tab, copy and save the values from the following fields for later use in the API request payload to configure the IdP in Cognigy:
-
Issuer — used in the
idpIssuerparameter in the request payload. -
Identity Provider Login URL — used in the
idpLoginEndpointparameter in the request payload. -
Identity Provider Certificate — used in the
idpCertificateparameter in the request payload. Click Download Auth0 certificate. Base64-encode the certificate without line breaks. You can use the following terminal command:[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))base64 -i ./<path-to-certificate> | tr -d '\n'cat ./<path-to-certificate> | base64 -w0
-
Issuer — used in the
2
Map Roles
For each user which you want to apply SSO to, set
user_metadata to map the user’s name and Cognigy role. To do so, follow these steps:-
Go to User Management > Users, select the user, scroll to the Metadata section, and paste the following JSON into the user_metadata field:
The
{ "family_name": "<LAST NAME>", "given_name": "<FIRST NAME>", "role": "<COGNIGY_ROLE>" }rolevalue must match a role in Cognigy, for example,adminorbase_role. - Go to Actions > Library, click Create Action, and configure the following:
- Name — enter a name.
- Login / Post Login — activate this option.
-
In the editor, paste the following code:
exports.onExecutePostLogin = async (event, api) => { const userMetadata = event.user.user_metadata || {}; api.samlResponse.setAttribute( "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", event.user.email ); api.samlResponse.setAttribute("firstName", userMetadata.given_name || ""); api.samlResponse.setAttribute("lastName", userMetadata.family_name || ""); api.samlResponse.setAttribute("role", userMetadata.role || ""); };
- Deploy the Action.
1
Set Up an App
- Log in to the Azure portal with an administrator account and navigate to Microsoft Entra ID.
- In the top bar, click + Add and select Enterprise applications. The Browse Microsoft Entra Gallery page opens.
- In the top bar, click + Create your own application.
-
Enter a name, for example,
Cognigy, select Integrate any other app you don’t find in the gallery (Non-gallery), and click Create. - On the new app page, open Single sign-on in the left navigation and select SAML as the sign-on method.
-
In the Basic SAML Configuration section, click Edit and configure the following:
- Identifier (Entity ID) — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Reply URL (Assertion Consumer Service URL) — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Sign on URL — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - (Optional) Logout Url — enter
https://<cognigy-url>/slo/<organization-id>.
- Identifier (Entity ID) — enter
- Click Save.
2
Map User Attributes
-
In the User Attributes and Claims section, click Edit and confirm that the following claims are mapped to the user’s profile attributes:
Cognigy uses the email claim to identify the user and to create the Cognigy account on the first login.
Claim name Value http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameuser.givennamehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameuser.surname
3
Get Authentication Data
-
In the SAML Signing Certificate section, locate Certificate (Base64) and click Download. Save the file locally. Use this certificate as
idpCertificatein the API request to configure the IdP in Cognigy. You need to encode the certificate as base64 without newlines beforehand. To do so, use the following terminal command:[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))base64 -i ./<path-to-certificate> | tr -d '\n'cat ./<path-to-certificate> | base64 -w0 -
In the Set up
<application name>section, copy the following values to be used in the API request to configure the IdP in Cognigy:
- Login URL — used in the
idpLoginEndpointparameter in the request payload. - (Optional) Logout URL — used in the
idpLogoutUrlparameter in the request payload when you enable single logout.
4
Assign Roles
-
In the top bar, search for
App registrationsand select this option. - In the All applications tab, search for the app you created and select it.
-
In the left-side menu, go to Manage > Manifest and deactivate the default
Userandmsiam_accessroles. To do so:- Set
isEnabledtofalsefor theUserandmsiam_accessroles, for example:"appRoles": [ { "allowedMemberTypes": [ "User" ], "description": "User", "displayName": "User", "id": "18d14569-c3bd-439b-9a66-3a2aee01d14f", "isEnabled": false, "origin": "Application", "value": null }, { "allowedMemberTypes": [ "User" ], "description": "msiam_access", "displayName": "msiam_access", "id": "b9632174-c057-4f7e-951b-be3adc52bfe6", "isEnabled": false, "origin": "Application", "value": null } ] - In the left-side menu, go to Manage > App roles, select the User role, and click Delete on the right-side pane. Do the same for the
msiam_accessrole.
- Set
-
Paste the following JSON code in the
appRolesarray:Roles Array
{ "allowedMemberTypes": [ "User" ], "displayName": "Admin", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc1", "isEnabled": true, "description": "The Admin role in Cognigy", "value": "admin" }, { "allowedMemberTypes": [ "User" ], "displayName": "API Keys", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc2", "isEnabled": true, "description": "The apiKeys role in Cognigy", "value": "apiKeys" }, { "allowedMemberTypes": [ "User" ], "displayName": "Base", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc3", "isEnabled": true, "description": "The base role in Cognigy", "value": "base_role" }, { "allowedMemberTypes": [ "User" ], "displayName": "Full Support User", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc4", "isEnabled": true, "description": "Admin privileges, no user assignments in Cognigy", "value": "fullSupportUser" }, { "allowedMemberTypes": [ "User" ], "displayName": "OData", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc5", "isEnabled": true, "description": "The OData role in Cognigy", "value": "odata" }, { "allowedMemberTypes": [ "User" ], "displayName": "Project Manager", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc6", "isEnabled": true, "description": "The Project Manager role in Cognigy", "value": "projectManager" }, { "allowedMemberTypes": [ "User" ], "displayName": "User Manager", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc7", "isEnabled": true, "description": "The User Manager role in Cognigy", "value": "userManager" }, { "allowedMemberTypes": [ "User" ], "displayName": "Administrator", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc8", "isEnabled": true, "description": "The Administrator role in Live Agent", "value": "liveAgentAdmin" }, { "allowedMemberTypes": [ "User" ], "displayName": "Agent", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bc9", "isEnabled": true, "description": "The Agent role in Live Agent", "value": "liveAgentAgent" }, { "allowedMemberTypes": [ "User" ], "displayName": "Supervisor", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bd1", "isEnabled": true, "description": "The Supervisor role in Live Agent", "value": "liveagentSupervisor" }, { "allowedMemberTypes": [ "User" ], "displayName": "View user details", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bd2", "isEnabled": true, "description": "The role to view user details in Cognigy", "value": "userDetailsViewer" }, { "allowedMemberTypes": [ "User" ], "displayName": "Voice Gateway User", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bd3", "isEnabled": true, "description": "The Account scope in Voice Gateway", "value": "voiceGatewayUser" }, { "allowedMemberTypes": [ "User" ], "displayName": "Basic Support User", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bd4", "isEnabled": true, "description": "Partial Admin, read-only, no assignments, no OData/API, no Knowledge AI in Cognigy", "value": "basicSupportUser" }, { "allowedMemberTypes": [ "User" ], "displayName": "Project Assigner", "id": "8d17fe88-c0ca-4903-ae2a-a51098998bd5", "isEnabled": true, "description": "Assigns Agents, read-only access, no global roles, limited features in Cognigy", "value": "projectAssigner" } - In the left-side menu, go to Users and groups and assign the app to the users or groups that must have access to Cognigy through SSO.
1
Add a Custom Attribute
You need to add a custom attribute that Cognigy uses when the user logs in for the first time. To do so, follow these steps:
- Log in to the Google Admin console.
- In the left-side menu, go to Directory > Users.
- At the top of the Users list, click More options > Manage user attributes.
-
Click the Add Custom Attribute button and configure the following:
-
Category — enter a unique name to identify the custom attribute, for example,
Cognigy SSO. - Description — enter a relevant description of the custom attribute.
-
In the Custom fields section, configure three custom fields with the following values:
Name Info type Visibility Number of values First Name Text Visible to user and admin Single value Last Name Text Visible to user and admin Single value Role Text Visible to user and admin Single value
If a user doesn’t have a role assigned, Cognigy assignsbase_roleto the user. -
Category — enter a unique name to identify the custom attribute, for example,
- Click Add.
2
Set Up an App
- In the left-side menu, go to Apps > SAML Apps.
- Click the plus button in the lower-right corner and select Setup My Own Custom App.
-
In the Google IdP Information dialog, copy the SSO URL value and download the certificate. You’ll use the SSO URL as
idpLoginEndpointand the certificate asidpCertificatein the API request to configure the IdP in Cognigy. You need to encode the certificate as base64 without newlines beforehand. To do so, use the following terminal command:Click Next.[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))base64 -i ./<path-to-certificate> | tr -d '\n'cat ./<path-to-certificate> | base64 -w0 -
Enter a name for the app, for example,
Cognigy, and click Next. -
On the service provider details page, configure the following:
- ACS URL — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Entity ID — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Signed Response — select the checkbox.
- Name ID Format — set to
EMAIL.
- ACS URL — enter
- On the Attribute Mapping page, add the following attribute mappings so that Cognigy receives the user’s first name, last name, and role from Google:
| Service Provider Attribute | Custom Attribute | Field |
|---|---|---|
firstName | Cognigy SSO | First Name |
lastName | Cognigy SSO | Last Name |
role | Cognigy SSO | Role |
- Click Finish, then activate the app for the users or organizational units that must have access to Cognigy through Google SSO.
1
Set Up an App
- Log in to your Okta Admin Console with an administrator account.
- In the left-side menu, go to Applications > Applications and click Create New App.
- Select SAML 2.0 as the sign-on method and click Create.
-
On the General Settings tab, enter an app name, for example,
Cognigy SSO, optionally upload a logo, and click Next. -
On the Configure SAML tab, configure the following:
- Single sign-on URL — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Use this for Recipient URL and Destination URL — keep selected.
- Audience URI (SP Entity ID) — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - Name ID format — select Unspecified.
- Application username — select Email.
- Update application username on — select Create and update.
- Single sign-on URL — enter
- (Optional) To encrypt SAML requests, click Show Advanced Settings, set Assertion Encryption to Encrypted, and upload an X.509 certificate. You will need the private key of this certificate to register the IdP in Cognigy.
2
Map User Attributes
-
In the Attribute Statements section, add the following attributes so that Cognigy receives the user profile data it needs to create the account:
Click Next.
Name Name format Value emailUnspecified user.emailfirstNameUnspecified user.firstNamelastNameUnspecified user.lastName - On the Feedback tab, select I’m an Okta customer adding an internal app and click Finish.
3
Get Authentication Data
- On the Applications page, select the app you created, then open the Sign On tab.
-
In the SAML Signing Certificates section, click View Setup Instructions or Identity Provider metadata and copy the following values:
-
Identity Provider Single Sign-On URL — used in the
idpLoginEndpointparameter in the request payload. -
Identity Provider Issuer — used in the
idpIssuerparameter in the request payload. -
X.509 Certificate — used in the
idpCertificateparameter in the request payload. You need to encode the certificate as base64 without newlines beforehand. If you enabled SAML request encryption, you also need to encode the private key as base64. You can use the following terminal command:[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate-or-private-key"))base64 -i ./<path-to-certificate-or-private-key> | tr -d '\n'cat ./<path-to-certificate-or-private-key> | base64 -w0
-
Identity Provider Single Sign-On URL — used in the
4
Assign Users
- In the left-side menu of the Admin Console, go to Directory > Profile Editor, and click Profile next to the profile of the app you created.
-
Click Add Attribute and configure the following:
- Data type — select string.
- Display name — enter
Role. - Variable name — enter
role. - (Optional) Description — enter a relevant description, for example,
The role of the user in Cognigy. - Enum — activate Define enumerated list of values.
- Attribute member — enter a display name and the value of the role to which SSO applies, for example,
Base Roleandbase_role. The value must match a role in Cognigy. - Attribute required — select this option.
Click Save.
- Go to Applications > Applications and select the app you created.
- On the Assignments tab, click the Edit button next to the user’s name and assign the role they should have in Cognigy. This user can log in via SSO.
1
Set Up an App
- Log in to your OneLogin Administration portal with an administrator account.
- In the top bar, click Applications, then click Add App in the upper-right corner.
-
Search for
SAML Custom Connector (Advanced)in the search field and select this option. -
In the Display Name field, enter a name that identifies the integration, for example,
Cognigy SSO. Optionally upload icons. Click Save. -
On the new app page, click the Configuration tab in the left-side menu and configure the following:
- ACS (Consumer) URL — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - ACS (Consumer) URL Validator — enter
https://<api-base-url>/auth/saml/login/<organization-id>. - (Optional) Single Logout URL — enter
https://<cognigy-url>/slo/<organization-id>.
- ACS (Consumer) URL — enter
-
In the left-side menu, go to the Parameters tab, configure the following parameter and value pairs, and select the Include in SAML assertion option for each pair:
Click Save to apply the attribute mapping.
Parameter Value emailEmail firstNameFirst Name lastNameLast Name roleUser Role
2
Get Authentication Data
-
In the left-side menu, go to the SSO tab and copy the following values:
-
X.509 Certificate — click View Details and download the certificate. You will use its contents as
idpCertificate. You need to encode the certificate as base64 without newlines beforehand. You can use the following terminal command:[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\path-to-certificate"))base64 -i ./<path-to-certificate> | tr -d '\n'cat ./<path-to-certificate> | base64 -w0 -
Issuer URL — used in the
idpIssuerparameter in the request payload. -
SAML 2.0 Endpoint (HTTP) — used in the
idpLoginEndpointparameter in the request payload. -
(Optional) SLO Endpoint — used in the
idpLogoutEndpointparameter in the request payload.
-
X.509 Certificate — click View Details and download the certificate. You will use its contents as
- In the left-side menu, navigate to Users > Roles and click New Role.
-
Add the following Cognigy roles one by one, select the app you created, and click Save:
adminapiKeysbase_rolelivechatodataprojectManageruserManager
- In the left-side menu, go to the Users tab and select a user for SSO. On the user page, enter the role they have in Cognigy in the role field. The role must match the roles you configured in step 3.
- Click Save. The user can log in via SSO.
Configure SSO in Cognigy
After the SSO app is ready, use thePOST /v2.0/identityprovider/configure method to register the SSO configuration in Cognigy.
- Auth0 - OpenID Connect
- Auth0 - SAML 2.0
- Microsoft Entra ID
- Google
- Okta
- OneLogin
Send the API request with the following parameters:
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— the Domain value you copied earlier from the Settings tab.idpClientId— the Client ID value you copied earlier from the Settings tab.idpClientSecret— the Client Secret value you copied earlier from the Settings tab.
API Request Example
API Request Example
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "oidc",
"idpIssuer": "<DOMAIN>",
"idpClientId": "<CLIENT ID>",
"idpClientSecret": "<CLIENT SECRET>",
"idpIdTokenSignedResponseAlg": "RS256",
"idpTokenEndpointAuthMethod": "client_secret_basic"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "oidc",
idpIssuer: "<DOMAIN>", // Domain from the Auth0 app Settings tab
idpClientId: "<CLIENT ID>", // Client ID from the Auth0 app Settings tab
idpClientSecret: "<CLIENT SECRET>", // Client Secret from the Auth0 app Settings tab
idpIdTokenSignedResponseAlg: "RS256",
idpTokenEndpointAuthMethod: "client_secret_basic"
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "oidc",
"idpIssuer": "<DOMAIN>", # Domain from the Auth0 app Settings tab
"idpClientId": "<CLIENT ID>", # Client ID from the Auth0 app Settings tab
"idpClientSecret": "<CLIENT SECRET>", # Client Secret from the Auth0 app Settings tab
"idpIdTokenSignedResponseAlg": "RS256",
"idpTokenEndpointAuthMethod": "client_secret_basic"
}
)
Send the API request with the following data:
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— the Issuer value you copied earlier from the Usage tab of the SAML2 Web App add-on.idpLoginEndpoint— the Identity Provider Login URL you copied earlier from the Usage tab of the SAML2 Web App add-on.idpCertificate— the Identity Provider Certificate you copied earlier from the Usage tab of the SAML2 Web App add-on, including theBEGIN/ENDmarkers, with real line breaks replaced by\n.idpIdentifierFormat— the NameID format. Useurn:oasis:names:tc:SAML:1.1:nameid-format:emailAddressto match the add-on settings.
API Request Example
API Request Example
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "urn:<your-tenant>.auth0.com",
"idpLoginEndpoint": "https://<your-tenant>.auth0.com/samlp/<client-id>",
"idpCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-body>\n-----END CERTIFICATE-----",
"idpIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpLoginEndpoint: "https://<your-tenant>.auth0.com/samlp/<client-id>", // Identity Provider Login URL from the Auth0 add-on Usage tab
idpIssuer: "urn:<your-tenant>.auth0.com", // Identity Provider Issuer from the Auth0 add-on Usage tab
idpCertificate: "-----BEGIN CERTIFICATE-----\n<certificate-body>\n-----END CERTIFICATE-----", // Identity Provider Certificate from the Auth0 add-on Usage tab
idpIdentifierFormat: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpLoginEndpoint": "https://<your-tenant>.auth0.com/samlp/<client-id>", # Identity Provider Login URL from the Auth0 add-on Usage tab
"idpIssuer": "urn:<your-tenant>.auth0.com", # Identity Provider Issuer from the Auth0 add-on Usage tab
"idpCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-body>\n-----END CERTIFICATE-----", # Identity Provider Certificate from the Auth0 add-on Usage tab
"idpIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
}
)
Send the API request with the following data:
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— usehttps://<api-base-url>/auth/saml/login/<organization-id>.idpLoginEndpoint— the Login URL you copied earlier from the Set up<application name>section.idpCertificate— the certificate you downloaded earlier from the SAML Signing Certificate section, base64-encoded as a single continuous string with no line breaks.- (Optional)
idpLogoutUrl— the Logout URL you copied earlier from the Set up<application name>section.
API Request Example
API Request Example
curl -X POST "https://<api-base-url>/v2.0/identityprovider/configure" \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "https://<api-base-url>/auth/saml/login/<organization-id>",
"idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2",
"idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
"idpLogoutUrl": "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpIssuer: "https://<api-base-url>/auth/saml/login/<organization-id>", // Cognigy SSO URL
idpLoginEndpoint: "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2", // Login URL from the Set up `<application name>` section
idpCertificate: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...", // Base64-encoded contents of the downloaded .crt file
idpLogoutUrl: "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2" // Logout URL from the Set up `<application name>` section (optional, for SP-initiated SLO)
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpIssuer": "https://<api-base-url>/auth/saml/login/<organization-id>", # Cognigy SSO URL
"idpLoginEndpoint": "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2", # Login URL from the Set up `<application name>` section
"idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...", # Base64-encoded contents of the downloaded .crt file
"idpLogoutUrl": "https://login.microsoftonline.com/4a7853bd-xxxx-xxxx-xxxx-xxxxxxxxxxxx/saml2" # Logout URL from the Set up `<application name>` section (optional, for SP-initiated SLO)
}
)
Don’t include the PEM header, the PEM footer, or any newline characters in the certificate you submit to Cognigy. A malformed certificate string causes the SSO configuration request to fail.
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— usehttps://<api-base-url>/auth/saml/login/<organization-id>.idpLoginEndpoint— the SSO URL value you copied earlier from the Google IdP Information dialog.idpCertificate— the certificate you downloaded earlier from the Google IdP Information dialog, base64-encoded as a single continuous string with no line breaks.
API Request Example
API Request Example
curl -X POST "https://<api-base-url>/v2.0/identityprovider/configure" \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "https://<api-base-url>/auth/saml/login/<organization-id>",
"idpLoginEndpoint": "https://accounts.google.com/o/saml2/idp?idpid=XXXX",
"idpCertificate": "MIIDdTCCAl2gAwIBAgIJAKx..."
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpIssuer: "https://<api-base-url>/auth/saml/login/<organization-id>", // Cognigy SSO URL
idpLoginEndpoint: "https://accounts.google.com/o/saml2/idp?idpid=XXXX", // SSO URL from Google IdP Information dialog in the Google Admin console
idpCertificate: "MIIDdTCCAl2gAwIBAgIJAKx..." // Certificate from Google IdP Information dialog, base64-encoded on a single line
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpIssuer": "https://<api-base-url>/auth/saml/login/<organization-id>", # Cognigy SSO URL
"idpLoginEndpoint": "https://accounts.google.com/o/saml2/idp?idpid=XXXX", # SSO URL from Google IdP Information dialog in the Google Admin console
"idpCertificate": "MIIDdTCCAl2gAwIBAgIJAKx..." # Certificate from Google IdP Information dialog, base64-encoded on a single line
}
)
Send the API request with the following data:
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— the Identity Provider Issuer value you copied from the SAML setup instructions page.idpLoginEndpoint— the Identity Provider Single Sign-On URL value you copied from the SAML setup instructions page.- For encrypted SAML requests:
idpCertificate— X.509 Certificate you uploaded under Show Advanced Settings > Assertion Encryption, base64-encoded as a single continuous string with no line breaks.decryptionPrivateKey— the private key matching the X.509 certificate you uploaded under Show Advanced Settings > Assertion Encryption and base64-encoded as a single continuous string.
API Request Example (Without Encryption)
API Request Example (Without Encryption)
curl -X POST "https://<api-base-url>/v2.0/identityprovider/configure" \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "<OKTA_IDENTITY_PROVIDER_ISSUER>",
"idpLoginEndpoint": "<OKTA_SINGLE_SIGN_ON_URL>"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpIssuer: "<OKTA_IDENTITY_PROVIDER_ISSUER>", // Identity Provider Issuer from the Okta Sign On tab
idpLoginEndpoint: "<OKTA_SINGLE_SIGN_ON_URL>" // Identity Provider Single Sign-On URL from the Okta Sign On tab
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpIssuer": "<OKTA_IDENTITY_PROVIDER_ISSUER>", # Identity Provider Issuer from the Okta Sign On tab
"idpLoginEndpoint": "<OKTA_SINGLE_SIGN_ON_URL>" # Identity Provider Single Sign-On URL from the Okta Sign On tab
}
)
API Request Example (With Encryption)
API Request Example (With Encryption)
curl -X POST "https://<api-base-url>/v2.0/identityprovider/configure" \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "<OKTA_IDENTITY_PROVIDER_ISSUER>",
"idpLoginEndpoint": "<OKTA_SINGLE_SIGN_ON_URL>",
"idpCertificate": "<OKTA_X509_CERTIFICATE>",
"decryptionPrivateKey": "<OKTA_PRIVATE_KEY>"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpIssuer: "<OKTA_IDENTITY_PROVIDER_ISSUER>", // Identity Provider Issuer from the Okta Sign On tab
idpLoginEndpoint: "<OKTA_SINGLE_SIGN_ON_URL>", // Identity Provider Single Sign-On URL from the Okta Sign On tab
idpCertificate: "<OKTA_X509_CERTIFICATE>", // X.509 Certificate from the Okta Sign On tab, base64-encoded on a single line
decryptionPrivateKey: "<OKTA_PRIVATE_KEY>" // Private key matching the certificate uploaded to Okta, base64-encoded on a single line
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpIssuer": "<OKTA_IDENTITY_PROVIDER_ISSUER>", # Identity Provider Issuer from the Okta Sign On tab
"idpLoginEndpoint": "<OKTA_SINGLE_SIGN_ON_URL>", # Identity Provider Single Sign-On URL from the Okta Sign On tab
"idpCertificate": "<OKTA_X509_CERTIFICATE>", # X.509 Certificate from the Okta Sign On tab, base64-encoded on a single line
"decryptionPrivateKey": "<OKTA_PRIVATE_KEY>" # Private key matching the certificate uploaded to Okta, base64-encoded on a single line
}
)
Send the API request with the following data:
X-API-Keyheader — the API key from the Prerequisites section.idpIssuer— the Issuer URL you copied earlier from the SSO tab of the OneLogin app.idpLoginEndpoint— the SAML 2.0 Endpoint (HTTP) you copied earlier from the SSO tab of the OneLogin app.idpCertificate— the X.509 Certificate you encoded earlier from the SSO tab of the OneLogin app, base64-encoded as a single continuous string with no line breaks.- (Optional)
idpLogoutEndpoint— the SLO Endpoint you copied earlier from the SSO tab of the OneLogin app.
API Request Example
API Request Example
curl -X POST "https://<api-base-url>/v2.0/identityprovider/configure" \
-H "Content-Type: application/json" \
-H "X-API-Key: <your-api-token>" \
-d '{
"idpType": "saml",
"idpIssuer": "https://app.onelogin.com/saml/metadata/<id>",
"idpLoginEndpoint": "https://<subdomain>.onelogin.com/trust/saml2/http-post/sso/<id>",
"idpCertificate": "<ONELOGIN_X509_CERTIFICATE>",
"idpLogoutEndpoint": "https://<subdomain>.onelogin.com/trust/saml2/http-redirect/slo/<id>"
}'
const response = await fetch("https://<api-base-url>/v2.0/identityprovider/configure", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
body: JSON.stringify({
idpType: "saml",
idpIssuer: "https://app.onelogin.com/saml/metadata/<id>", // Issuer URL from the OneLogin SSO tab
idpLoginEndpoint: "https://<subdomain>.onelogin.com/trust/saml2/http-post/sso/<id>", // SAML 2.0 Endpoint (HTTP) from the OneLogin SSO tab
idpCertificate: "<ONELOGIN_X509_CERTIFICATE>", // X.509 Certificate from the OneLogin SSO tab, base64-encoded on a single line
idpLogoutEndpoint: "https://<subdomain>.onelogin.com/trust/saml2/http-redirect/slo/<id>" // SLO Endpoint from the OneLogin SSO tab (optional)
})
});
import requests
response = requests.post(
"https://<api-base-url>/v2.0/identityprovider/configure",
headers={
"Content-Type": "application/json",
"X-API-Key": "<your-api-token>"
},
json={
"idpType": "saml",
"idpIssuer": "https://app.onelogin.com/saml/metadata/<id>", # Issuer URL from the OneLogin SSO tab
"idpLoginEndpoint": "https://<subdomain>.onelogin.com/trust/saml2/http-post/sso/<id>", # SAML 2.0 Endpoint (HTTP) from the OneLogin SSO tab
"idpCertificate": "<ONELOGIN_X509_CERTIFICATE>", # X.509 Certificate from the OneLogin SSO tab, base64-encoded on a single line
"idpLogoutEndpoint": "https://<subdomain>.onelogin.com/trust/saml2/http-redirect/slo/<id>" # SLO Endpoint from the OneLogin SSO tab (optional)
}
)
Test the SSO Login
- On the Cognigy login page, enter the email address of a user assigned to the IdP app and click Log in with SSO. Cognigy redirects you to the IdP and prompts you for your IdP credentials. After authentication, the IdP redirects back to Cognigy and logs you in.
- Click the user icon in the lower-left corner and select Logout.
- Enter your email address again and click Log in with SSO. This time, you are logged in directly without re-entering your IdP credentials.