SSO (Single Sign-On)

Allow your chatbot users to sign in with their organization's identity provider (Azure AD, Okta, etc.) using OpenID Connect (OIDC).

Overview

SSO lets your users authenticate using their existing corporate credentials — no separate account needed. WizChat supports any OIDC-compatible provider.

Provider	Status
Azure AD (Entra ID)	Fully supported
Okta	Fully supported
Google Workspace	Fully supported
Any OIDC provider	Supported via custom configuration

Prerequisites

Before setting up SSO, you need:

• A WizChat chatbot with authentication enabled
• Admin access to your identity provider (Azure AD, Okta, etc.)
• The following values from your identity provider:
  • Client ID (Application ID)
  • Client Secret
  • Issuer URL (OIDC discovery endpoint)

---

Step 1: Configure Your Identity Provider

Azure AD (Microsoft Entra ID)

1. Go to the Azure Portal → App Registrations

2. Click New Registration

3. Fill in:

   • Name: Your chatbot name (e.g., "My Company Chatbot")
   • Supported account types: Choose based on your needs
     • Single tenant — only your organization
     • Multitenant — any Azure AD organization
   • Redirect URI: Select Web and enter:

     https://auth-us.wizchat.app/__/auth/handler

     EU Region

     If your chatbot is deployed in the EU region, use:

     https://auth-eu.wizchat.app/__/auth/handler

4. Click Register

5. Note the Application (client) ID — this is your Client ID

   Common Mistake

   Use the Application (client) ID, not the Directory (tenant) ID. These are different values on the same page. Using the wrong one will cause an AADSTS700016 error.

6. Go to Certificates & Secrets → New client secret

   • Add a description and set expiry
   • Copy the Value immediately (it won't be shown again) — this is your Client Secret

7. Your Issuer URL is:

   https://login.microsoftonline.com/{TENANT_ID}/v2.0

   Replace {TENANT_ID} with your Directory (tenant) ID from the Overview page.

Okta

1. Log in to your Okta Admin Console
2. Go to Applications → Create App Integration
3. Select OIDC - OpenID Connect and Web Application
4. Fill in:
   • App integration name: Your chatbot name
   • Sign-in redirect URIs:

     https://auth-us.wizchat.app/__/auth/handler

   • Sign-out redirect URIs: Leave empty
5. Click Save
6. Note the Client ID and Client Secret
7. Your Issuer URL is:

   https://{YOUR_OKTA_DOMAIN}/oauth2/default

---

Step 2: Configure SSO in WizChat

1. Open your chatbot in the WizChat dashboard
2. Go to the Edit page
3. Scroll down to the SSO Configuration section
4. Fill in the fields:

Field	Description	Example
Provider	Your identity provider	azure-ad
Client ID	Application (client) ID from your provider	76525d59-e7e4-...
Client Secret	The secret you generated	abc123~...
Issuer URL	OIDC discovery endpoint	https://login.microsoftonline.com/{tenant}/v2.0
Display Name	Text shown on the SSO button	Sign in with Azure AD
SSO Only	Disable email/password login	Toggle on/off

5. Click Save SSO

No Redeploy Needed

SSO configuration is loaded dynamically from the database. Changes take effect within a few minutes — no redeploy required.

---

Step 3: Verify SSO

1. Open your chatbot URL in an incognito/private window
2. You should see the SSO login button with your configured display name
3. Click the button — you should be redirected to your identity provider's login page
4. After authenticating, you should be redirected back to the chatbot

sequenceDiagram
    participant U as User
    participant C as Chatbot
    participant IDP as Identity Provider
    U->>C: Visit chatbot URL
    C->>U: Show SSO login button
    U->>IDP: Click "Sign in with Azure AD"
    IDP->>U: Authenticate (email/password/MFA)
    IDP->>C: Return auth token
    C->>U: Access granted

---

SSO-Only Mode

When SSO Only is enabled:

• Email/password login is hidden
• Google Sign-In is hidden
• Only the SSO button is displayed
• Users already signed in with email/password are automatically signed out

This ensures all users authenticate through your corporate identity provider.

---

Azure AD Group-to-Scope Mapping

When using Knowledge Scopes with SSO, you can map Azure AD security groups to specific scopes. This lets you manage who can access which scopes entirely from Azure AD — no manual email/domain lists needed in WizChat.

How It Works

• Each Azure AD group is mapped to one or more Knowledge Scopes
• When a user signs in via SSO, their Azure AD group memberships are read from the token
• Only scopes mapped to the user's groups are visible and accessible
• Manual email/domain access controls are visually disabled (but preserved if you toggle back)

flowchart LR
    A[Azure AD Group] --> B[Group-Scope Mapping]
    B --> C[Knowledge Scope 1]
    B --> D[Knowledge Scope 2]
    E[User] --> F[Azure AD Login]
    F --> G{Member of group?}
    G -- Yes --> C
    G -- No --> H[Access Denied]

Step 1: Enable Group Fetching (API Permission)

This lets WizChat read your Azure AD groups so you can select them in the dashboard.

1. Go to the Azure Portal → App Registrations → your app
2. Go to API Permissions → click Add a permission
3. Select Microsoft Graph → Application permissions (not Delegated)
4. Search for Group.Read.All → check it → click Add permissions
5. Back on the API Permissions page, click "Grant admin consent for [your tenant]"
6. Confirm by clicking Yes

The status should change to a green checkmark "Granted for [your tenant]".

Admin Consent Required

The "Grant admin consent" button requires Global Administrator or Privileged Role Administrator role. If the button is greyed out, ask your Azure AD admin to grant consent. They can also do it by visiting:

https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={client-id}

Replace {tenant-id} and {client-id} with values from your App Registration's Overview page.

Step 1b: Include Groups in SSO Token

This puts group IDs into the login token so WizChat can check group membership at runtime.

1. In the same App Registration, go to Token Configuration
2. Click "+ Add groups claim"
3. Select "Groups assigned to the application" → click Save

Why "Groups assigned to the application"?

This limits the groups in the token to only those you've explicitly assigned to this app, avoiding the 200-group overage limit. You can assign groups under Enterprise Applications → your app → Users and groups → Add user/group.

Step 2: Configure Mappings in WizChat

1. Open your chatbot in the WizChat dashboard → Edit page
2. Ensure SSO is enabled and you have at least one Knowledge Scope configured
3. In the SSO section, toggle "Map Azure AD Groups to Knowledge Scopes"
4. Click "Fetch Groups from Azure AD" — WizChat will use your SSO credentials to retrieve your Azure AD groups
5. Select the groups you want to map by checking the checkbox next to each group
6. For each selected group, click the scope pills to assign which Knowledge Scopes that group can access
7. Click Update SSO to save

Manual Fallback

If the "Fetch Groups" button shows a permission error, ensure you completed Step 1 above. You can also click "Or add group IDs manually" to enter Group Object IDs by hand — find them in Azure Portal → Azure Active Directory → Groups → click the group → copy the Object ID.

Step 3: Verify

1. Assign a test user to one of the mapped Azure AD groups
2. Open the chatbot in an incognito window and sign in via SSO
3. Only the scopes mapped to the user's groups should be visible
4. A user not in any mapped group will see no scopes

Limitations

Scenario	Behavior
User belongs to >200 Azure AD groups	Access denied with a descriptive error — use application-scoped groups to avoid this
No groups claim in the token	All mapped scopes denied — ensure Token Configuration is set up
Group mapping enabled but no mappings configured	Falls back to standard email/domain access control
Non-SSO user (email/password) with mapping enabled	No group claims available — access denied to all mapped scopes

SSO-Only Mode Recommended

Group mapping works best with SSO-Only mode enabled. When SSO-Only is off, non-SSO users (email/password, Google) won't have Azure AD group claims and will be denied access to all mapped scopes.

---

Troubleshooting

AADSTS700016: Application not found

Cause: You entered the Tenant ID as the Client ID.

Fix: Go to Azure Portal → App Registrations → your app → copy the Application (client) ID (not the Directory/tenant ID) and update it in the SSO configuration.

AADSTS50011: Redirect URI mismatch

Cause: The redirect URI in Azure doesn't match what Firebase sends.

Fix: Add the correct redirect URI to your Azure App Registration:

• US region: https://auth-us.wizchat.app/__/auth/handler
• EU region: https://auth-eu.wizchat.app/__/auth/handler

Go to Azure Portal → App Registrations → your app → Authentication → Add the URI under Web redirect URIs.

SSO button not showing

• Verify SSO is enabled in the chatbot edit page
• Wait a few minutes for the dynamic config to propagate (up to 30 minutes)
• Try a hard refresh (Ctrl+Shift+R) on the chatbot page

User sees email verification screen instead of SSO

• If SSO-Only mode is enabled, existing email/password users will be automatically signed out
• Clear browser cookies for the chatbot domain and try again
• Verify that the SSO configuration is saved correctly

"Invalid provider configuration" error

• Verify the Issuer URL is correct and ends with /v2.0 for Azure AD
• Check that the Client Secret hasn't expired
• Ensure the App Registration in your identity provider is active

---

Related

• Authentication Setup
• Access Modes
• Managing Users