# OneLogin

**Cognigy Support**  
February 24, 2021

**Requirements**  
✔ SSO URL ( [Get it here](https://docs.cognigy.com/docs/single-sign-on-1#section-getting-the-sso-url ""))  
✔ SLO URL ( [Get it here](https://docs.cognigy.com/docs/single-sign-on-1#section-getting-the-slo-url ""))

## Introduction

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

## Creating an Application in OneLogin

The first step is to create a new app within OneLogin. To do this, open the _Applications_ panel of OneLogin which will display a list of your existing apps. On this page, you can click on the `Add App` button at the top right of the page to create a new app.

_Creating a new App_

This will open a page with a lot of different application types you can choose to create:

_Finding the correct application type_

Search for `SAML` and choose the `SAML Test Connector (Advanced)` application. After choosing the correct application type, input the name and icons (optional) you want to use to represent your Cognigy.AI SAML application within OneLogin and click on `SAVE`.

_Creating a custom SAML application_

## Configuring Single Sign-on for the Application in OneLogin

### Configuration

We can now create the SAML configuration for the application. Open the _configuration_ tab and add the Cognigy.AI **`SSO URL`** (See [Cognigy.AI SSO documentation](https://docs.cognigy.com/docs/single-sign-on-1#getting-the-sso-url)) into both of the following fields:

- **`ACS (Consumer) URL Validator`**  
- **`ACS (Consumer) URL`**

OneLogin also requires the Cognigy.AI `SLO URL` (See [Cognigy.AI SSO documentation](https://docs.cognigy.com/docs/single-sign-on-1#getting-the-slo-url)) to be entered as the:

- **`Single Logout URL`**

_Adding the Cognigy SSO and SLO URLs to the configuration settings_

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

### Parameters

In order to properly implement SSO with Cognigy.AI, you need to configure the parameters assigned to the user during SSO. Navigate to the _Parameters_ tab within your new application and select the "+" in the top right of the page to add a new parameter. It is required that the following parameters are added:

- NameID value: Email  
- firstName: First Name  
- lastName: Last Name  
- role: User Roles

_Creating the firstName user parameter_

**Include in SAML Assertion**

It is VERY important that the `Include in SAML assertion` checkbox is checked when creating the parameters

The role will be used to grant the user the proper access rights in Cognigy.AI. In a later step, we will add the supported roles to the app.

_Correct configuration for user parameters_

## Configure SSO in Cognigy.AI

After configuring SSO in OneLogin, 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](https://api-demo.cognigy.ai/security/identityprovider "")) and attach the following JSON payload to the request with your unique values (see below):

```
{
  "idpIssuer": string,
  "idpLoginEndpoint": string,
  "idpCertificate": string,
  "idpLogoutEndpoint": string
}
```

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

In order to do this, you need some information from OneLogin, which you will find on the SSO page in your application in OneLogin.

_SSO configuration in OneLogin_

**idpIssuer**

The idpIssuer is the `Issuer URL` in OneLogin.

**idpLoginEndpoint**

The idpLoginEndpoint is the `SAML 2.0 Endpoint (HTTP)` in OneLogin,

**idpCertificate**

This is the certificate that OneLogin uses to sign the SAML requests. Below the `X.509 Certificate` field in OneLogin there is a `View Details` button. Click this button and you will be redirected to a page where you can download the certificate.

_Click "View Details" to access the certificate_

_Downloading the IDP 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.

**idpLogoutEndpoint**

The idpLogoutEndpoint is the `SLO Endpoint` in OneLogin.

* * *

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

```
{
    "idpLoginEndpoint": "https://cognigy.onelogin.com/trust/saml2/http-post/sso/******",
    "idpCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCgo=",  
    "idpIssuer": "https://app.onelogin.com/saml/metadata/31beeb04-********-b8aa-b637b4fbfc01",
    "idpLogoutEndpoint": "https://cognigy.onelogin.com/trust/saml2/http-redirect/slo/******"
}
```

## Configuring User Roles

In order to configure user roles for the users in Cognigy.AI, you either have to add the supported roles as `User Roles` in OneLogin, or assign the role to each user of your app manually. Alternatively, you can also assign one global role to your app by using a Macro so that all users have the same role within Cognigy.AI.

The supported roles within Cognigy.AI are as follows: admin, apiKeys, base_role, livechat, odata, projectManager and userManager. You can read more about user roles here: [Access Control](https://docs.cognigy.com/docs/access-control "")

### Editing User Roles in OneLogin

To edit the user roles within OneLogin, navigate to Users > Roles and click on `New Role`. In the text field that appears, input one of the supported Cognigy.AI roles as listed above and assign your app to the role.

_Creating a new role in OneLogin_

### Adding User Roles Manually

You can also add the roles to each user, who uses the app, manually. To do this, navigate to your app in OneLogin and click on the `Users` tab. Here you can click on each user assigned to your app and change their role manually. However, this will display warnings.

_Manually editing roles for users in OneLogin_

You're now done configuring Single Sign-on for OneLogin, and your users can now login to Cognigy.AI through OneLogin.