Custom OIDC

Connect any OpenID Connect (OIDC) compliant identity provider to authenticate end users with your Char agent. This guide covers the requirements and configuration for custom OIDC providers.

Prerequisites

An OIDC-compliant identity provider
Access to configure applications in your IDP
Your IDP’s OIDC discovery URL or issuer URL
Access to the Char dashboard

Supported Providers

Custom OIDC integration works with any provider that:

Supports OpenID Connect 1.0
Publishes a /.well-known/openid-configuration discovery document
Uses RS256, RS384, RS512, ES256, ES384, or ES512 for token signing
Provides a JWKS endpoint for public key retrieval

Examples of compatible providers include: Keycloak, PingFederate, OneLogin, JumpCloud, Duo, ForgeRock, Cognito, and many others.

SDK References

These generic OIDC libraries work with any compliant identity provider:

oidc-client-ts

TypeScript OIDC client library

react-oidc-context

React context for OIDC authentication

OIDC Requirements

Your identity provider must support these OIDC features:

Feature	Requirement
Discovery document	`/.well-known/openid-configuration` endpoint
JWKS endpoint	Published in discovery document
Token signing	RS256, RS384, RS512, ES256, ES384, or ES512
ID tokens	Must include `sub`, `iss`, `aud`, `exp` claims
HTTPS	Issuer URL must use HTTPS

Configuration Steps

Locate Your Issuer URL

Find your OIDC provider’s issuer URL. This is typically in your IDP’s documentation or settings.Common patterns:

https://idp.yourcompany.com
https://auth.yourcompany.com/realms/main
https://yourcompany.onelogin.com/oidc/2

The issuer URL should have a discovery document at {issuer}/.well-known/openid-configuration.

Verify Discovery Document

Test that your discovery document is accessible:

curl https://your-issuer-url/.well-known/openid-configuration | jq

The response should include at minimum:

{
  "issuer": "https://your-issuer-url",
  "jwks_uri": "https://your-issuer-url/.well-known/jwks.json",
  "authorization_endpoint": "https://your-issuer-url/authorize",
  "token_endpoint": "https://your-issuer-url/token",
  "id_token_signing_alg_values_supported": ["RS256"]
}

Create an OIDC Application

In your identity provider, create a new application/client:

Select OIDC or OpenID Connect as the protocol
Select Single-Page Application or Public Client as the type
Configure redirect URIs for your application
Enable the openid, profile, and email scopes
Note the Client ID assigned to your application

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your Client ID from Step 3
Enter your Issuer URL (e.g., https://idp.yourcompany.com)
Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Description	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Your OIDC application’s client ID	`char-ai-agent`
Issuer URL	Full OIDC issuer URL (HTTPS required)	`https://idp.yourcompany.com`

The issuer URL must use HTTPS. HTTP issuers are rejected for security reasons.

Token Requirements

Char validates custom OIDC tokens with these requirements:

Claim	Requirement
`iss`	Must exactly match your configured issuer URL
`aud`	Must include your configured Client ID
`sub`	Required - used as the user identifier
`exp`	Must not be expired

Example: Keycloak Integration

Create a Client in Keycloak

Go to your Keycloak Admin Console
Select your realm
Navigate to Clients → Create
Configure:

Setting	Value
Client ID	`char-ai-agent`
Client Protocol	openid-connect
Access Type	public
Valid Redirect URIs	Your app URLs
Web Origins	Your app origins

Configure Char

Use these values:

Issuer URL: https://keycloak.yourcompany.com/realms/{realm-name}
Client ID: char-ai-agent

import Keycloak from 'keycloak-js';
import "@mcp-b/char/web-component";

const CLIENT_ID = 'char-ai-agent';

const keycloak = new Keycloak({
  url: 'https://keycloak.yourcompany.com',
  realm: 'your-realm',
  clientId: CLIENT_ID,
});

await keycloak.init({ onLoad: 'login-required' });

if (keycloak.authenticated) {
  const agent =
    document.querySelector("char-agent") ?? document.createElement("char-agent");

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

  agent.connect({ idToken: keycloak.idToken, clientId: CLIENT_ID });
}

Example: AWS Cognito Integration

Create a User Pool App Client

Go to AWS Cognito Console
Select your User Pool
Navigate to App integration → App clients
Create a new app client (public client, no secret)
Note the Client ID

Find Your Issuer URL

The Cognito issuer URL format is:

https://cognito-idp.{region}.amazonaws.com/{user-pool-id}

Configure Char

Issuer URL: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX
Client ID: Your Cognito app client ID

import { CognitoUserPool, CognitoUser, AuthenticationDetails } from 'amazon-cognito-identity-js';
import "@mcp-b/char/web-component";

const CLIENT_ID = 'your-client-id';

const userPool = new CognitoUserPool({
  UserPoolId: 'us-east-1_XXXXXXXXX',
  ClientId: CLIENT_ID,
});

// After authentication
const cognitoUser = userPool.getCurrentUser();
cognitoUser.getSession((err, session) => {
if (session.isValid()) {
    const agent =
      document.querySelector("char-agent") ?? document.createElement("char-agent");

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

    agent.connect({
      idToken: session.getIdToken().getJwtToken(),
      clientId: CLIENT_ID,
    });
}
});

Example: OneLogin Integration

Create an OIDC Application

Go to OneLogin Admin Portal
Navigate to Applications → Add App
Search for “OpenId Connect” and select it
Configure:

Setting	Value
Display Name	Char Agent
Redirect URI	Your app callback URL
Token Endpoint Auth	None (PKCE)

Find Your Issuer URL

The OneLogin issuer URL format is:

https://{subdomain}.onelogin.com/oidc/2

Configure Char

Issuer URL: https://yourcompany.onelogin.com/oidc/2
Client ID: Your OneLogin app client ID

Troubleshooting

INVALID_ISSUER error

The token’s iss claim doesn’t match your configured issuer:

Verify the issuer URL exactly matches (including trailing slash if present)
Check your IDP’s discovery document for the exact issuer value
Some IDPs include a trailing slash - match it exactly

INVALID_AUDIENCE error

The token’s aud claim doesn’t match:

Verify the Client ID matches your IDP application exactly
Check if your IDP includes multiple audiences - your Client ID must be one of them
Ensure you’re using the ID token, not the access token

JWKS_FETCH_FAILED error

Char couldn’t fetch your IDP’s public keys:

Verify your issuer URL is correct
Ensure the /.well-known/openid-configuration endpoint is accessible
Check that the jwks_uri in the discovery document is accessible
Test connectivity: curl {issuer}/.well-known/openid-configuration

INVALID_ALGORITHM error

Your IDP is using an unsupported signing algorithm:

Char supports: RS256, RS384, RS512, ES256, ES384, ES512
Configure your IDP to use one of these algorithms
Symmetric algorithms (HS256, etc.) are not supported for security reasons

KEY_NOT_FOUND error

The key ID in your token doesn’t match any keys in the JWKS:

Your IDP may have rotated keys - wait for JWKS cache to refresh (1 hour)
Check that your IDP’s JWKS endpoint includes the current signing key
Verify the token is freshly issued, not from a cache

Security Considerations

Critical: Always configure Client ID for audience validation. Without it, tokens from other applications using the same IDP could be used to access your agent.

Additional security best practices:

Use HTTPS for all IDP endpoints (required)
Keep token lifetimes short (recommended: 1 hour or less)
Implement token refresh in your application for long sessions
Validate tokens server-side if additional security is needed
Monitor authentication logs in your IDP for anomalies

Testing Your Configuration

Use the Test Connection button in the Char dashboard to verify:

The discovery document is accessible
The issuer URL is valid
The JWKS endpoint is reachable

For manual testing, you can verify the discovery document:

# Fetch and inspect the discovery document
curl -s https://your-issuer-url/.well-known/openid-configuration | jq

# Verify JWKS endpoint
curl -s $(curl -s https://your-issuer-url/.well-known/openid-configuration | jq -r '.jwks_uri') | jq

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

Custom OIDC

Prerequisites

Supported Providers

SDK References

oidc-client-ts

react-oidc-context

OIDC Requirements

Configuration Steps

Configuration Reference

Token Requirements

Example: Keycloak Integration

Example: AWS Cognito Integration

Example: OneLogin Integration

Troubleshooting

Security Considerations

Testing Your Configuration

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

​Prerequisites

​Supported Providers

​SDK References

oidc-client-ts

react-oidc-context

​OIDC Requirements

​Configuration Steps

​Configuration Reference

​Token Requirements

​Example: Keycloak Integration

​Example: AWS Cognito Integration

​Example: OneLogin Integration

​Troubleshooting

​Security Considerations

​Testing Your Configuration

Prerequisites

Supported Providers

SDK References

OIDC Requirements

Configuration Steps

Configuration Reference

Token Requirements

Example: Keycloak Integration

Example: AWS Cognito Integration

Example: OneLogin Integration

Troubleshooting

Security Considerations

Testing Your Configuration