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)

• OAuth2 - SSO (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

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.

Creating Auth0 Applications

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

4. Go directly to the Settings tab

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

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

7. Copy the SAML Protocol URL

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

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

Webchat Details Window

---

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

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)

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)

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.

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

User Experience

IFrame Mode

1. User opens the webchat

2. Authentication happens automatically inside the widget

3. User is logged in and the chat view appears

Popup Mode

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

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

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.

Auth0 Application Types

1. Go to the Settings tab

1. 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/

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

Allow Cross-Origin Communication

1. IMPORTANT!: In order to allow Cross-Origin Authentication the Universal Login Experience needs to be set to “Classic”.

2. Go to Branding > Universal Login Settings and select Classic.

Universal Login

1. Open Aisera Admin UI and go to Settings > Channels > New Channel to setup a new webchat channel.

2. In Authentication select SSO-Auht0 and provide

   • Domain: Copy from Auth0 > App > Settings

   • Client ID: Copy from Auth0 > App > Settings

OAuth2-SSO Option

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