Virtual Assistant (Bot Authentication)

The Virtual Assistant page under Bot Authentication controls how end users are authenticated when they open your bot on the web channel (the standalone Web App and the embeddable chat widget). From this single screen you choose an authentication method, restrict access by email domain, wire up one or many identity providers (IDPs), and set session behaviour.

All settings on this page are saved against the bot's channels.web.auth configuration and take effect on the next end-user login.

Availability & permissions

The page is visible only when all of the following are true:

• Config Manager is enabled for the workspace (otherwise the entire Authentication group is hidden).
• The signed-in dashboard user holds the authentication permission.
• The workspace is not on a Trial license — Authentication is hidden for trial workspaces.

If the page is missing for a user, check these three gates first.

Choosing an authentication method

The first control on the page is Select authentication method, which sets the primary strategy for the web channel. The rest of the form changes based on this choice.

Add allowed domains appears for every method. This is the whitelist of email domains permitted to sign in (for example company.com). Enter one or more domains; users outside this list are normally denied at the domain gate. (Domain behaviour can be softened by policy flags — see Relationship with General Settings.)

SSO

Selecting SSO reveals Select SSO type, with two options:

• Single IDP SSO — the bot points at one SAML application for all users.
• Multiple IDP SSO — the bot routes users to different SAML applications based on their email domain.

SAML applications shown in the dropdowns are the ones already registered under Bot Authentication → SAML Apps. Each option maps to that application's Entity ID.

Single IDP SSO

Pick one application in Select SAML App. Every user who passes the allowed-domains check is sent to that provider's sign-in URL. The chosen application's Entity ID is stored at sso.entityId.

Multiple IDP SSO

This is the configuration for organisations that use different identity providers for different regions, business units, or acquired companies — for example Okta for the US and Azure AD for the EU.

When you choose Multiple IDP SSO, a repeatable mapping table appears. Add one row per identity provider:

Use Add more to add further providers. Each saved row is persisted to the multipleIDPSso array as { entityId, domains[], isDefaultApp }, and the bot is flagged with isMultipleIDPSso: true.

How routing works at login

Multi-IDP resolution happens server-side, by email domain:

1. Because more than one IDP is possible, the Web App presents an email-entry step first (rather than jumping straight to a provider).
2. The backend extracts the domain from the address the user typed.
3. It matches that domain against the domains list of each row in the multipleIDPSso mapping.
4. On a match, the user is redirected to that application's SAML sign-in URL (its Entity ID).
5. On no match, the user falls back to the row flagged Set as default app.
6. After a successful assertion at the IDP, the client exchanges the one-time verify token for a session token and the chat loads.

[email protected]
        │
        ▼
 extract domain ──► "eu.company.com"
        │
        ▼
 match against multipleIDPSso[].domains
        │
   ┌────┴─────────────┐
 match             no match
   │                   │
   ▼                   ▼
route to that     route to the
IDP's Entity ID   "default app" row

SAML profile & attribute mapping (SSO only)

When SSO is selected, three optional blocks let you capture and map data from the SAML assertion.

Save SAML profile

Turn on Save SAML profile to capture named attributes from the assertion. In Add SAML profile fields, list the attributes to store (for example firstName, department). Stored under sso.saveSamlProfile.

Create integrations user

Available once Save SAML profile is on. Enabling Create integrations user lets you map SAML attributes to downstream integration profile fields so a user is created or updated in connected systems automatically. Each mapping row is a pair:

Login field mappers

Login field mappers map authentication attributes to internal profile attributes for the active session. Each row is an Auth field → Profile field pair. Useful when the IDP's attribute names differ from Leena's profile fields.

Successful login message

Optional free-text message shown to users after a successful SSO login. Stored at sso.loginSuccessMessage.

OAuth

Selecting OAuth shows the OAuth provider dropdown. The web Virtual Assistant supports Azure AD as the OAuth provider. The selection is stored at oauth.provider.

Custom authentication

Selecting Custom reveals a Channel authorization expression code editor (JavaScript). Use this when the VA is embedded in a portal that already authenticates the user — the expression validates the incoming session before the chat proceeds.

{
  "type": "expression",
  "value": "auth.provider === 'internal-portal' && user.groups.includes('employees')"
}

The expression is saved at custom.expr and evaluated by the backend during the web-chat handshake.

Shared settings

These controls apply across methods.

Allow login via mobile number

Available for OTP, SSO, and OAuth. When on, users may sign in with a registered mobile number in addition to email.

Send test OTP

A helper block (OTP/SSO/OAuth) for verifying delivery before go-live. Enter a mobile number or email and trigger a test — the dashboard calls POST /api/bots/{botId}/send-test-otp. Entries are validated for format before sending.

Session timeout (token expiry on inactivity)

Toggle Allow token expiry / timeout and set Session timeout (in seconds; default 120) to expire idle sessions. Stored at tokenExpiryInactivity as { isEnabled, duration }.

Custom SMS provider

If the bot has a custom SMS provider configured, the OTP setup renders additional provider-specific fields so you can tune those values inline.

Relationship with General Settings

channels.web.auth is shared by two editors, and they update it differently:

• This page (Auth Method editor) owns method configuration — type, domains, sso, oauth, otp, multipleIDPSso, and so on. Saving here replaces the method configuration.
• General Settings (Authentication → General Settings) owns cross-cutting policy flags and updates only those keys. These include:
  • isRestricted — limit access to users synced from integrations.
  • allowOtpForUnregisteredDomains — route non-free, unregistered corporate domains to OTP instead of hard-denying them (useful alongside SSO/OAuth).
  • authExpression — an AND/OR rule tree (e.g. department = HR OR location = London) evaluated during sign-in.

API reference

Multiple IDP SSO payload shape

{
  "auth": {
    "type": "sso",
    "isMultipleIDPSso": true,
    "domains": ["us.company.com", "eu.company.com"],
    "multipleIDPSso": [
      {
        "entityId": "https://okta.company.com/us-app",
        "domains": ["us.company.com", "global.company.com"],
        "isDefaultApp": false
      },
      {
        "entityId": "https://sts.windows.net/eu-tenant",
        "domains": ["eu.company.com"],
        "isDefaultApp": true
      }
    ],
    "tokenExpiryInactivity": { "isEnabled": true, "duration": 3600 }
  }
}

Troubleshooting

Related pages

• SAML Apps (create, edit, metadata) — Bot Authentication
• General Settings & Auth Expressions — Bot Authentication
• Mobile / Desktop App Authentication — Bot Authentication
• Virtual Assistant Web Config (appearance & widget) — Global Settings