Custom OIDC Integration

Connect any OpenID Connect (OIDC) compliant identity provider to authenticate end users interacting with your Char AI widget. 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 AI 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.

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 AI

In the Char AI 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 AI Field	Description	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Your OIDC application’s client ID	`char-ai-widget`
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 AI 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-widget`
Client Protocol	openid-connect
Access Type	public
Valid Redirect URIs	Your app URLs
Web Origins	Your app origins

Configure Char AI

Use these values:

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

import Keycloak from 'keycloak-js';
import { CharWidget } from '@char-ai/widget';

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

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

if (keycloak.authenticated) {
  CharWidget.init({
    siteId: 'your-site-id',
    userToken: keycloak.idToken,
  });
}

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 AI

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 { CharWidget } from '@char-ai/widget';

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

// After authentication
const cognitoUser = userPool.getCurrentUser();
cognitoUser.getSession((err, session) => {
  if (session.isValid()) {
    CharWidget.init({
      siteId: 'your-site-id',
      userToken: session.getIdToken().getJwtToken(),
    });
  }
});

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 AI Widget
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 AI

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 AI 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 AI 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 widget.

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

Getting Started

Core Concepts

Guides

Identity Providers

Custom OIDC

Custom OIDC Integration

Prerequisites

Supported Providers

OIDC Requirements

Configuration Steps

Configuration Reference

Token Requirements

Example: Keycloak Integration

Example: AWS Cognito Integration

Example: OneLogin Integration

Troubleshooting

Security Considerations

Testing Your Configuration

Getting Started

Core Concepts

Guides

Identity Providers

​Custom OIDC Integration

​Prerequisites

​Supported Providers

​OIDC Requirements

​Configuration Steps

​Configuration Reference

​Token Requirements

​Example: Keycloak Integration

​Example: AWS Cognito Integration

​Example: OneLogin Integration

​Troubleshooting

​Security Considerations

​Testing Your Configuration

Custom OIDC Integration

Prerequisites

Supported Providers

OIDC Requirements

Configuration Steps

Configuration Reference

Token Requirements

Example: Keycloak Integration

Example: AWS Cognito Integration

Example: OneLogin Integration

Troubleshooting

Security Considerations

Testing Your Configuration