> For the complete documentation index, see [llms.txt](https://docs.aisera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisera.com/aisera-platform/channels/aisera-webchat/webchat-sso-saml-and-oauth2-sso-integration-with-auth0.md).

# Webchat SSO-SAML and OAuth2-SSO Integration with Auth0

Webchat supports Auth0 as an SSO provider, allowing users to authenticate through your Auth0 tenant before accessing the bot. Two authentication modes are available depending on how and where the webchat is deployed:

### Choose one of the following two SSO options for Webchat:

* [**SSO-SAML (Auth0)**](https://docs.aisera.com/aisera-platform/channels/aisera-webchat/webchat-sso-saml-and-oauth2-sso-integration-with-auth0#to-set-up-sso-saml-in-auth0)
* [**OAuth2 - SSO (Auth0)**](https://docs.aisera.com/aisera-platform/channels/aisera-webchat/webchat-sso-saml-and-oauth2-sso-integration-with-auth0#to-set-up-sso-oauth2-using-auth0)

## To set up SSO-SAML (in Auth0)

Before configuring Auth0 SSO in the Aisera Admin UI, make sure the prerequisites are set up in your Auth0 tenant.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before configuring Auth0 SSO in the Aisera Admin UI, ensure the following are set up in your Auth0 tenant:

* Add the **webchat's parent page URL** to Auth0's **Allowed Callback URLs**
  * Example: `https://yoursite.com/support`
* Add the **parent page origin** to Auth0's **Allowed Web Origins**
* You have the Auth0 **Domain** and **Client ID** for your application

### In the Auth0 Dashboard:

1\. Login to Auth0 dashboard <https://manage.auth0.com/dashboard/>

2\. Navigate to **Dashboard > Applications > Applications**.

3\. Click on  **+ Create Application**.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfD6HVus_9fbIPjmr-d0QA8qbiFspTQsB9Vix6SDWs5esOWdt6eDJ-riUG0aaQ-zsIi-gnEqq0UnZDGfb4HE6BY6Tl-PN5YrsV3_Q5i-2P6yDsSC99mfVJGYx6DqUCcc90v9ESvBf1iIRR-vHajC6IdY3An_5313UeogBve3pqrNGRKJ0Dx?key=7iL2ZOh7YBQmH-tJCPo89Q" alt=""><figcaption><p>Creating Auth0 Applications</p></figcaption></figure>

1. Set your apps Name and Select “Regular Web Applications”

<div align="left"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfpGyu2ZxQKwXEK5lPejwidROi0hd7pKyvTnRpjlCaBDkhmwDYeTRCIKmL0aURuZpGePOqq6G_xSmVEVq4pv7mkeUPTxgxEq1VOKLGQtz5dPutu2KT3U-aYQQgNDckjTwjlkGM8KMJrfzSwt3C0UEP5b-KNdNeJcotblDJ95jBGIBSTchfbrA?key=7iL2ZOh7YBQmH-tJCPo89Q" alt="" width="563"><figcaption></figcaption></figure></div>

4\. Go directly to the Settings tab

<div align="left"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfliiZXkPz_HvDOhDA23J1SHFiCaKucTd1rpDXSToJMlrFhWve9kbFtjulAETEDIEsoSccz5YX_NBPfMNOOHOLqj0n64trQ5L9aIu3-SbvryrNgq19tVKOSE8oDgSHFEfkFYDOdxQoXrae0lfjkv8lxvG0dK80j8CvsDMMQzHEDWOfsa0QCvg?key=7iL2ZOh7YBQmH-tJCPo89Q" alt=""><figcaption></figcaption></figure></div>

5\. Go to section “Application URIs” and set the required value in Allowed Callback URLs

Callback URLs need to be in the syntax: `{vanityUrl}/aisera/ssoLoginCallback,`

such as: `https://acme.chatbot.aisera.cloud/aisera/ssoLoginCallback`

<div align="left"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcy0Fhxe0SWCnVXbM23R0D-DDzfonXh-sPcXczgYzOuQpfCpt_3N4siR_OkVvsmq2l0xjjmq9pG3p9NocZcdVG9_QcVIrAq2mZfirq6-HS-f4nR2tF9ypP9n4aAOua3dUzBTOfia3Mc45WHpVs_VHfgeT5RDGE6JNzBLXJ3swWx15ldfZA63Uk?key=7iL2ZOh7YBQmH-tJCPo89Q" alt="" width="563"><figcaption></figcaption></figure></div>

6\. Scroll to “Advanced Settings” and select the tab “Endpoints”

<div align="left"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcq8Q2hd81454LVbtH_BVwjG8PkmPWtDusuGSIej0YJZtROZTYQfuVJlUTSGHQyl7CWcXR-udY2IDtVAdfSeXlVGUA70WN_nsf_QK9-OFl4d_J-fId_NNvCEVqCMnatzSpCXfApUlMcMnxEYRz3YAxHv1q6DWcC2SWFZdG3vjK8-4ky0OkiqQ?key=7iL2ZOh7YBQmH-tJCPo89Q" alt=""><figcaption></figcaption></figure></div>

7\. Copy the SAML Protocol URL

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfQMDOfHqxZAcK6cdYBldT7x_AvmphfYqGYij6oz8In6SXspfMQqjWqwK9f-fsPZNg9rgh1YyHci1VkoYmhqpjnZdoe4eTmK0adXCOIMR084iY4nYmby_uatO8SpY5VPbbcP_pSsPfzD_28KZKJkiuQeCUE31jkQ0oHtOwWA1neRrqCL8Xi1Q?key=7iL2ZOh7YBQmH-tJCPo89Q" alt=""><figcaption></figcaption></figure>

8\. Move to the “Certificates” tab and copy the “Signing Certificate”

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfmMyCFvp0Mx13r-JMYZX508sQknOVARsvKKNrmUQ10zGeeroeG4MCKy_BNCJ9Swso7QiVAxpxGuOLDxYyotTlDjk5W6VLsSvo2iGoRFFb_xd-RvfWaiheJx8US6TFqL58Pp7MxCmVScMa5e0vNj6ArB-0JAdXJx3Nkyr_ka2i11XyNtGsIVgM?key=7iL2ZOh7YBQmH-tJCPo89Q" alt=""><figcaption></figcaption></figure>

### Setting up SSO for a channel in Admin Console

1. Open Aisera Admin UI and go to  **Settings > Channels > New Channel** to set up a new Webchat channel
2. Under the **Authentication** tab, select **SSO** and provide:\
   \
   **Login URL:** SAML Protocol URL\
   **ACS URL:** The identity provider's SSO URL used by Aisera to authenticate.\
   **Issuer:** The Aisera Entity ID. If none specified, it is generated based on the cluster as 'aisera-saml-{clusterType}'. (such as, aisera-saml-staging or aisera-saml-prod)\
   **IFrame embedding:** If checked then the SSO authentication form is displayed in the same window instead of opening a separate one. You may need to configure the identity provider to allow iframe embedding for this to work.\
   **Skip compression:** If checked, the SAML request from Aisera will not be compressed.\
   **x509 Certificate:** Signing Certificate

<figure><img src="/files/UFRMQzUaAAy1q0IpqMcB" alt=""><figcaption><p>Webchat Details Window</p></figcaption></figure>

***

3. Fill in the following fields:

| Field                | Description                                              |
| -------------------- | -------------------------------------------------------- |
| **Domain**           | Your Auth0 tenant domain (e.g., `yourcompany.auth0.com`) |
| **Client ID**        | The Application Client ID from your Auth0 dashboard      |
| **IFrame Embedding** | Controls the authentication mode — see below             |

| **Mode**                       | **How It Works**                                  | **Best For**                                                          |
| ------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------- |
| **IFrame (default)**           | Authentication happens within the webchat widget  | Desktop browsers, full-page web applications                          |
| **Popup (iFrame not checked)** | Authentication opens in a separate browser window | iOS devices, mobile browsers, webchat embedded inside another website |

#### iFrame Embedding Checkbox <a href="#iframe-embedding-checkbox" id="iframe-embedding-checkbox"></a>

| Setting               | Behavior                                                     |
| --------------------- | ------------------------------------------------------------ |
| **Checked** (default) | Authentication runs inside the webchat widget (IFrame mode)  |
| **Unchecked**         | Authentication opens in a separate popup window (Popup mode) |

#### iFrame Mode (checkbox checked — default) <a href="#iframe-mode-checkbox-checked-default" id="iframe-mode-checkbox-checked-default"></a>

Use this when:

* Users access the webchat on a **desktop browser** (Chrome, Firefox, Edge, Safari on Mac)
* The webchat is hosted directly on your website (not embedded inside another site)

#### Popup Mode (IFrame Mode checkbox unchecked) <a href="#popup-mode-checkbox-unchecked" id="popup-mode-checkbox-unchecked"></a>

Use this when:

* Users access the webchat on **iOS devices** (iPhone or iPad — any browser)
* The webchat is **embedded inside another website or portal** that has a different domain
* Users report authentication failures, bot detection errors, or getting stuck on login on mobile

> **Why iOS requires popup mode:** Apple's Safari on iOS restricts how websites can store login information when running inside embedded widgets. This restriction silently breaks the default IFrame authentication. The popup mode opens authentication in a full browser window, which is not affected by this restriction.<br>

4. Fill in the remaining values for the SSO section and click **OK**.

### User Experience <a href="#user-experience" id="user-experience"></a>

#### IFrame Mode <a href="#iframe-mode" id="iframe-mode"></a>

1. User opens the webchat
2. Authentication happens automatically inside the widget
3. User is logged in and the chat view appears

#### Popup Mode <a href="#popup-mode" id="popup-mode"></a>

1. User opens the webchat
2. A login popup window opens automatically
3. User authenticates in the popup — the window closes on its own
4. Chat view appears with the user's profile loaded

**If the browser blocks the popup:**

* The webchat displays: *"It seems popups are blocked. Click here to log in."*
* A **Login** button also appears as a fallback
* Clicking either option re-opens the authentication window
* The user may need to allow popups for the site in their browser settings

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

| Symptom                                               | Likely Cause                                    | Recommended Action                                                                     |
| ----------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| Auth0 login fails on iPhone or iPad                   | IFrame mode is active; iOS blocks it            | Uncheck **IFrame Embedding** in the channel config                                     |
| Login works on desktop but not mobile                 | Same as above                                   | Uncheck **IFrame Embedding**                                                           |
| "Bot detection challenge" error after login           | Auth0 bot detection triggered in iframe context | Uncheck **IFrame Embedding** to use popup mode                                         |
| Popup opens but user is not logged in after it closes | Auth0 callback URL not configured               | Add the parent page URL to Auth0 Allowed Callback URLs                                 |
| "Popups are blocked" message appears immediately      | Browser popup blocker is enabled                | User should allow popups for the site, then click Login                                |
| Webchat language does not change after login          | User preferred language not set in the system   | Verify the user's preferred language is configured in the user profile settings        |
| Login works, but user sees a generic name/greeting    | Auth0 is not returning the user's full name     | Ensure the Auth0 application is configured to include the `name` claim in the ID token |

### Summary: Which Mode to Choose <a href="#summary-which-mode-to-choose" id="summary-which-mode-to-choose"></a>

| Deployment Scenario                        | Recommended Setting                                  |
| ------------------------------------------ | ---------------------------------------------------- |
| Desktop web application                    | IFrame Embedding **checked** (default)               |
| iOS mobile users                           | IFrame Embedding **unchecked**                       |
| Webchat embedded inside a customer portal  | IFrame Embedding **unchecked**                       |
| Mixed (desktop + mobile users)             | IFrame Embedding **unchecked** (popup works on both) |
| Authentication failures on mobile reported | IFrame Embedding **unchecked**                       |

***

## To set up SSO-OAuth2 (using Auth0)

1. Set your apps **Name** and Select **Single Page Applications** using your **Auth0** application.

<div align="left"><figure><img src="/files/p1ynaJQwgMHvpnJaAKbS" alt="" width="563"><figcaption><p>Auth0 Application Types</p></figcaption></figure></div>

2. Go to the **Settings** tab<br>

<div align="left"><figure><img src="/files/X6LdxbQyCqSXOqnuvo1c" alt="" width="563"><figcaption></figcaption></figure></div>

3. Go to section “**Application URIs**” and set the <`vanityUrl>` as value in **Allowed Callback URLs.**\
   Need to be in the form of\
   such as, `https://acme.chatbot.aisera.cloud/`

<div align="left"><figure><img src="/files/tkgPckdWl9YkyuTHEo4q" alt="" width="563"><figcaption></figcaption></figure></div>

4. In **Cross-Origin Authentication** enable **Allow Cross-Origin Authentication** and set the vanity URL as value in **Allowed Origins (CORS)**

<figure><img src="/files/UBIjzg1TwCooIOJ0LZgQ" alt=""><figcaption><p>Allow Cross-Origin Communication</p></figcaption></figure>

5. **IMPORTANT!**: In order to allow Cross-Origin Authentication the **Universal Login Experience** needs to be set to “**Classic**”.
6. Go to **Branding > Universal Login Settings** and select **Classic**.

<figure><img src="/files/PBmWF523yPIogf06olmA" alt=""><figcaption><p>Universal Login</p></figcaption></figure>

7. Open Aisera Admin UI and go to **Settings** > **Channels** > **New Channel** to setup a new webchat channel.
8. In Authentication select **SSO-Auht0** and provide
   * **Domain**: Copy from **Auth0 > App > Settings**
   * **Client ID**: Copy from **Auth0 > App > Settings**

<figure><img src="/files/kEm0oDkxRxNGFd4k9w41" alt=""><figcaption><p>OAuth2-SSO Option</p></figcaption></figure>

7. Finish the channel setup and add the channel to an Aisera App.