Skip to main content
Connect Auth0 to authenticate end users with your Char agent. Create an Auth0 application and configure Char for token validation.

Prerequisites

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

SDK References

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 Agent (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
See Auth0’s application settings reference for screenshots showing where to find these values.
4

Configure Char

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

Configuration Reference

Char 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 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 "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// Your Auth0 Client ID (must be in your Char allowed_audiences list)
const CLIENT_ID = 'a1b2c3d4e5f6g7h8i9j0';

const auth0 = await createAuth0Client({
  domain: 'acme.auth0.com',
  clientId: CLIENT_ID,
  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();

  const agent = document.querySelector("char-agent") as WebMCPAgentElement
    ?? document.createElement("char-agent") as WebMCPAgentElement;

  if (!agent.isConnected) {
    document.body.appendChild(agent);
  }

  // Use connect() - keeps token out of DOM
  agent.connect({ idToken: claims.__raw, clientId: CLIENT_ID });
}
Which Next.js approach? Use SSR with Ticket if you want to keep Auth0 JWTs server-side (more secure). Use SPA with JWT if you need the JWT client-side for other purposes or have a simpler client-side auth setup.

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, 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 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://usechar.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.

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