Okta

Connect Okta to authenticate end users with your Char agent. Create an OIDC application in Okta and configure Char to validate tokens.

Prerequisites

An Okta organization (production or preview)
Admin access to create applications in Okta
Access to the Char dashboard

Quick Links

Okta Admin Console

OAuth 2.0 & OIDC Overview

OAuth 2.0 and OpenID Connect concepts

OIDC API Reference

OpenID Connect API documentation

Build SSO Integration

Single Sign-On integration guide

SDK References

@okta/okta-auth-js

Okta Auth JavaScript SDK

@okta/okta-react

Okta React SDK

Configuration Steps

Create an OIDC Application in Okta

Sign in to your Okta Admin Console
Navigate to Applications → Applications
Click Create App Integration
Select OIDC - OpenID Connect as the sign-in method
Select Single-Page Application as the application type
Click Next

Configure Application Settings

Configure your new application:

Setting	Value
App integration name	`Char Agent` (or your preferred name)
Grant type	Authorization Code (with PKCE)
Sign-in redirect URIs	Your application’s callback URL
Sign-out redirect URIs	Your application’s logout URL
Controlled access	Assign to appropriate groups or allow everyone

Click Save to create the application.

Note Your Client ID and Domain

After creating the application:

Copy the Client ID from the application’s General tab
Note your Okta domain (e.g., acme.okta.com or acme.oktapreview.com)

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Okta as the provider
Add your Client ID to the Allowed Client IDs list
Enter your Okta domain (e.g., acme.okta.com)
Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Okta Value	Example
Provider Type	Okta	`okta`
Client ID	Application Client ID	`0oa1b2c3d4e5f6g7h8i9`
Domain	Your Okta domain	`acme.okta.com`

Okta preview environments use *.oktapreview.com domains. Both production and preview domains are supported.

Token Requirements

Char validates Okta tokens with these requirements:

Claim	Requirement
`iss`	Must match `https://{your-domain}`
`aud`	Must include your configured Client ID
`sub`	Required - used as the user identifier
`exp`	Must not be expired

Example: Obtaining and Passing the Token

Once your Okta application is configured, obtain the ID token after authentication and pass it to the Char agent.

Okta Auth JS
React (Okta React SDK)
SSR (Ticket Exchange)

import OktaAuth from '@okta/okta-auth-js';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// Your Okta Client ID (must be in your Char allowed_audiences list)
const CLIENT_ID = '0oa1b2c3d4e5f6g7h8i9';

const oktaAuth = new OktaAuth({
  issuer: 'https://acme.okta.com',
  clientId: CLIENT_ID,
  redirectUri: window.location.origin + '/callback',
});

// After authentication
const tokens = await oktaAuth.tokenManager.getTokens();

const idToken = tokens.idToken?.idToken;
if (idToken) {
  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, clientId: CLIENT_ID });
}

import { useOktaAuth } from '@okta/okta-react';
import { useEffect, useRef } from 'react';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// Your Okta Client ID (must be in your Char allowed_audiences list)
const CLIENT_ID = '0oa1b2c3d4e5f6g7h8i9';

function App() {
  const { authState } = useOktaAuth();
  const agentRef = useRef<WebMCPAgentElement>(null);
  const idToken = authState?.idToken?.idToken;

  useEffect(() => {
    if (idToken) {
      agentRef.current?.connect({ idToken, clientId: CLIENT_ID });
    }
  }, [idToken]);

  if (!authState?.isAuthenticated) return null;

  return <char-agent ref={agentRef} />;
}

For server-side rendered applications where Okta sessions live on the server, exchange the Okta JWT for a short-lived ticket:

// app/dashboard/page.tsx (Server Component)
import { getSession } from './okta-session'; // Your server-side session helper
import { redirect } from 'next/navigation';
import { CharAgent } from './char-agent';

// Your Char organization ID (from the dashboard)
const ORG_ID = 'org_abc123';
// Your Okta Client ID (must be in your Char allowed_audiences list)
const CLIENT_ID = '0oa1b2c3d4e5f6g7h8i9';

async function getTicketAuth(idToken: string) {
  const response = await fetch('https://api.usechar.ai/api/auth/ticket', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${idToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      org_id: ORG_ID,      // Required for SSR (no Origin header)
      client_id: CLIENT_ID // Required for production
    }),
  });
  return response.json(); // { ticket, userId, orgId, expiresAt }
}

export default async function Dashboard() {
  const session = await getSession();
  if (!session?.idToken) redirect('/login');

  const ticketAuth = await getTicketAuth(session.idToken);

  return <CharAgent ticketAuth={ticketAuth} />;
}

// app/dashboard/char-agent.tsx
'use client';
import { useEffect, useRef } from 'react';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement, TicketAuth } from "@mcp-b/char/web-component";

export function CharAgent({ ticketAuth }: { ticketAuth: TicketAuth }) {
  const agentRef = useRef<WebMCPAgentElement>(null);

  useEffect(() => {
    agentRef.current?.connect({ ticketAuth });
  }, [ticketAuth]);

  return <char-agent ref={agentRef} />;
}

Tickets are opaque, single-use, and expire in 60 seconds. See SSR Authentication for full examples.

SPA vs SSR: Use connect({ idToken, clientId }) for SPAs to keep the JWT out of the DOM. Use connect({ ticketAuth }) for SSR apps where the Okta session lives on your server.

Troubleshooting

INVALID_ISSUER error

Verify your Okta domain is correctly configured:

Domain should not include https:// prefix
Domain should match exactly (e.g., acme.okta.com)
For preview environments, use *.oktapreview.com

INVALID_AUDIENCE error

The token’s aud claim doesn’t match your configured Client ID:

Ensure the Client ID in Char matches your Okta application exactly
Verify you’re using the ID token, not the access token
Check that your Okta application is configured as a Single-Page Application

JWKS_FETCH_FAILED error

Char couldn’t reach Okta’s JWKS endpoint:

Verify your Okta domain is correct
Check that Okta is accessible (not blocked by firewall)
Use Test Connection in the dashboard to verify connectivity

Token expired immediately

If tokens expire quickly:

Check your Okta application’s token lifetime settings
Consider refreshing tokens before they expire
Verify your server and Okta have synchronized clocks

Security Best Practices

Always configure allowed_audiences. Without audience validation, tokens from other applications in your Okta organization could be used to access your agent.

Use connect() for authentication - The connect({ idToken, clientId }) method keeps tokens out of the DOM
Use ticket exchange for SSR - Exchange your Okta JWT for a short-lived ticket server-side instead of passing the JWT to the client
Use HTTPS for all redirect URIs
Restrict application access to only the users/groups who need it
Regularly rotate tokens by implementing proper session management
Monitor Okta system logs for suspicious authentication attempts

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

Prerequisites

Quick Links

Okta Admin Console

OAuth 2.0 & OIDC Overview

OIDC API Reference

Build SSO Integration

SDK References

@okta/okta-auth-js

@okta/okta-react

Configuration Steps

Configuration Reference

Token Requirements

Example: Obtaining and Passing the Token

Troubleshooting

Security Best Practices

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

​Prerequisites

​Quick Links

Okta Admin Console

OAuth 2.0 & OIDC Overview

OIDC API Reference

Build SSO Integration

​SDK References

@okta/okta-auth-js

@okta/okta-react

​Configuration Steps

​Configuration Reference

​Token Requirements

​Example: Obtaining and Passing the Token

​Troubleshooting

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Token Requirements

Example: Obtaining and Passing the Token

Troubleshooting

Security Best Practices