# Auth0 - OpenID Connect

**Cognigy Support**

January 12, 2024

## Introduction

This guide covers how to setup SSO in Cognigy.AI with **Auth0** as the Identity Provider using the **OpenID Connect protocol**. After completing this guide, your users can login to Cognigy.AI through Auth0 and will automatically have a user account created for them in Cognigy.AI that is assigned a Cognigy.AI access role as defined by the administrator in Auth0.

**SSO Options with Auth0**

When setting up SSO with Auth0, you can choose between two different SSO protocols. This article covers the **OpenID Connect** protocol. For **SAML 2.0**, please refer to the following article:

- [Auth0 - SAML2.0](https://support.cognigy.com/hc/en-us/articles/360018693139)

## Creating an Application in Auth0

The first step is to create an application in Auth0 that is used to connect to Cognigy.AI. Login to Auth0 and select "Applications" then "+ Create Application".

_Creating a new Application in Auth0_

After clicking on "Create Application", select the **Regular Web Application** type and give your application a suitable name, e.g. <Business Unit Name> Cognigy.AI.

_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 **Application URI** section. You will require the following information from the Cognigy.AI instance that you are using to complete this section:

- <API ADDRESS>: This is the address that all api requests are sent to for your Cognigy.ai instance, e.g. "api-trial.cognigy.ai"
- <ORGANIZATION ID>: This can be retrieved by accessing the "My Profile" page in Cognigy.AI, selecting the three dot menu in the top right of the page, and clicking "Copy Organization Id".

In this section of your Auth0 application settings, enter the following URI's in the designated fields:

- **Application Login URI**

```
https://<API ADDRESS>/auth/oidc/login/<ORGANIZATION ID>
```

- **Application Callback URLs**

```
https://<API ADDRESS>/auth/oidc/login/callback/<ORGANIZATION ID>
```

- **Allowed Logout URLs**

```
https://<FRONTEND_URL>/slo/<organisationId>
```

- **Allowed Web Origins**

```
https://*.cognigy.ai
```

- **Allowed Origins (CORS)**

```
https://*.cognigy.ai
```

_Configuring the Application URIs in Auth0 Application Settings_

This completes the setup for the application in Auth0. Ensure you select "Save Changes" before exiting page.

## Configuring SSO in Cognigy.AI

After configuring SSO in Auth0, 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 ADDRESS>/v2.0/identityprovider/configure
```

(e.g. [https://api-trial.cognigy.ai/new/v2.0/identityprovider/configure](https://api-demo.cognigy.ai/security/identityprovider "")) and attach the following JSON payload to the request with your unique values (see below):

```
{
  "idpType": "oidc",
  "idpIssuer": "<AUTH0 DOMAIN>",
  "idpClientId": "<AUTH0 APPLICATION CLIENT ID>",
  "idpClientSecret": "<AUTH0 APPLICATION CLIENT SECRET>",
  "idpIdTokenSignedResponseAlg": "RS256",
  "idpTokenEndpointAuthMethod": "client_secret_basic"
}
```

**API Authentication**

Read our [API reference guide](https://api-trial.cognigy.ai/openapi#post-/v2.0/identityprovider/configure) 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 Auth0, open the settings menu for the Application you created earlier. The Basic Information section includes the <AUTH0 DOMAIN>, <AUTH0 APPLICATION CLIENT ID> and <AUTH0 APPLICATION CLIENT SECRET>.

_Auth0 Application Basic Information_

## Logging into Cognigy.AI

You're now done configuring Single Sign-on for Auth0.

**First Login Must be with the Identity Provider**

The first time a user is logging into Cognigy.AI with SSO, they must first login via the IDP website. This process creates a Cognigy.AI user for them so that future logins can be directly via the Cognigy.AI interface.

Alternatively, you can provide an adjusted login URL to the user containing the organisation Id. Use the following format:

```
https://<YOUR COGNIGY.AI DOMAIN>/login/?organisationId=<YOUR ORGANISATION ID>
```

Your users can now login to Cognigy.AI through Auth0 by clicking on the **LOGIN WITH SSO button** in the **Cognigy.AI login screen**.

### Table of contents

- Introduction
- Creating an Application in Auth0
- Configuring Single Sign-on for the Application in Auth0
- Configuring SSO in Cognigy.AI
- Logging into Cognigy.AI