Skip to main content

Auth0 Integration

Connect Auth0 to authenticate end users interacting with your Char AI widget. This guide covers creating an Auth0 application and configuring Char AI for token validation.

Prerequisites

  • An Auth0 account and tenant
  • Admin access to create applications in Auth0
  • Access to the Char AI dashboard

Configuration Steps

1

Create an Application in Auth0

  1. Sign in to the Auth0 Dashboard
  2. Navigate to ApplicationsApplications
  3. Click Create Application
  4. Configure the application:
SettingValue
NameChar AI Widget (or your preferred name)
Application TypeSingle Page Web Applications
  1. Click Create
2

Configure Application Settings

In your application’s Settings tab, configure:
SettingValue
Allowed Callback URLsYour application’s callback URL(s)
Allowed Logout URLsYour application’s logout URL(s)
Allowed Web OriginsYour application’s origin(s) for silent auth
Scroll down and click Save Changes.
3

Note Your Client ID and Domain

From the Settings tab, copy:
  1. Domain - Your Auth0 tenant domain (e.g., acme.auth0.com)
  2. Client ID - Your application’s client ID
Auth0 Application Settings

Find your Domain and Client ID in Auth0 application settings

4

Configure Char AI

In the Char AI Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Auth0 as the provider
  3. Enter your Client ID from Step 3
  4. Enter your Domain (e.g., acme.auth0.com)
  5. Click Test Connection to verify
  6. Click Save Changes

Configuration Reference

Char AI FieldAuth0 ValueExample
Provider TypeAuth0auth0
Client IDApplication Client IDa1b2c3d4e5f6g7h8i9j0
DomainAuth0 tenant domainacme.auth0.com
Auth0 supports regional domains. Depending on your tenant’s region, your domain might be:
  • acme.auth0.com (US)
  • acme.us.auth0.com (US regional)
  • acme.eu.auth0.com (EU)
  • acme.au.auth0.com (AU)

Token Requirements

Char AI validates Auth0 tokens with these requirements:
ClaimRequirement
issMust match https://{your-domain}/
audMust include your configured Client ID
subRequired - used as the user identifier
expMust not be expired

Example: Obtaining and Passing the Token

import { createAuth0Client } from '@auth0/auth0-spa-js';
import { CharWidget } from '@char-ai/widget';

const auth0 = await createAuth0Client({
  domain: 'acme.auth0.com',
  clientId: 'a1b2c3d4e5f6g7h8i9j0',
  authorizationParams: {
    redirect_uri: window.location.origin,
  },
});

// Check if user is authenticated
const isAuthenticated = await auth0.isAuthenticated();

if (isAuthenticated) {
  // Get the ID token claims
  const claims = await auth0.getIdTokenClaims();

  CharWidget.init({
    siteId: 'your-site-id',
    userToken: claims.__raw, // The raw ID token
  });
}

Custom Domains

If you’re using a custom domain with Auth0:
  1. Configure your custom domain in Auth0 Dashboard → SettingsCustom Domains
  2. Update your Auth0 SDK to use the custom domain
  3. In Char AI, use your custom domain (e.g., auth.yourcompany.com) as the domain
When using custom domains, the issuer claim will use your custom domain URL.

Troubleshooting

The token issuer doesn’t match your configured domain:
  • Verify the domain in Char matches your Auth0 tenant exactly
  • Check if you’re using a regional domain (e.g., acme.us.auth0.com)
  • If using a custom domain, ensure it’s configured in Char
The token’s aud claim doesn’t match your configured Client ID:
  • Ensure the Client ID matches your Auth0 application exactly
  • Verify you’re using the ID token (from getIdTokenClaims().__raw)
  • Check that your application type is “Single Page Web Applications”
Char AI couldn’t reach Auth0’s JWKS endpoint:
  • Verify your Auth0 domain is correct
  • Check that your tenant exists and is accessible
  • Use Test Connection in the dashboard to verify
If you can’t get the ID token:
  • Ensure the user has completed the login flow
  • Check that openid is included in your scopes
  • Verify your Allowed Callback URLs match your application

Auth0 Actions for Additional Claims

You can use Auth0 Actions to add custom claims to your tokens:
// Auth0 Action: Add custom claims to ID token
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://char.ai/';

  // Add custom claims
  api.idToken.setCustomClaim(`${namespace}role`, event.user.app_metadata.role);
  api.idToken.setCustomClaim(`${namespace}team`, event.user.app_metadata.team);
};
These custom claims will be available in the token passed to Char AI.

Security Best Practices

  • Enable MFA in Auth0 for enhanced security
  • Configure password policies appropriate for your security requirements
  • Use refresh token rotation for long-lived sessions
  • Review and remove unused applications regularly
  • Monitor Auth0 logs for suspicious activity
  • Enable anomaly detection in Auth0 to block suspicious IPs