Keycloak

Connect Keycloak to authenticate end users with your Char widget. Create a Keycloak client, configure the realm, and set up Char for token validation.

Keycloak is an open-source identity and access management solution. This guide applies to self-hosted Keycloak instances and managed Keycloak services.

Prerequisites

A running Keycloak instance (version 18+ recommended)
Admin access to your Keycloak realm
Access to the Char dashboard

Quick Links

Keycloak Admin Console

Server Administration Guide

OIDC Documentation

OpenID Connect securing applications

Client Configuration

Client configuration guide

Keycloak JS Adapter

JavaScript adapter documentation

SDK References

keycloak-js

Official Keycloak JavaScript adapter

@react-keycloak/web

React bindings for Keycloak

oidc-client-ts

TypeScript OIDC client library

Configuration Steps

Access Your Keycloak Admin Console

Navigate to your Keycloak Admin Console (e.g., https://keycloak.yourcompany.com/admin)
Sign in with admin credentials
Select your realm from the dropdown (or create a new one)

The default realm is master, but it’s recommended to create a separate realm for your applications.

Create a Client

Navigate to Clients in the left sidebar
Click Create client
Configure the client:

Setting	Value
Client type	OpenID Connect
Client ID	`char-ai-widget` (or your preferred ID)

Click Next
Configure capability settings:

Setting	Value
Client authentication	Off (public client)
Authorization	Off
Standard flow	Enabled
Direct access grants	Enabled (optional)

Click Next
Configure login settings:

Setting	Value
Root URL	Your application’s base URL
Valid redirect URIs	Your callback URLs (e.g., `https://yourapp.com/*`)
Web origins	Your application origins (e.g., `https://yourapp.com`)

Click Save

Note Your Realm and Client ID

From your Keycloak Admin Console:

Realm name: Visible in the top-left dropdown
Client ID: The ID you configured when creating the client
Keycloak URL: Your Keycloak server URL (e.g., https://keycloak.yourcompany.com)

Find your realm and client settings in Keycloak

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your configuration:

Field	Value
Client ID	Your Keycloak Client ID
Issuer URL	`https://{keycloak-url}/realms/{realm-name}`

Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Keycloak Value	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	Client ID	`char-ai-widget`
Issuer URL	Realm issuer URL	`https://keycloak.yourcompany.com/realms/production`

For Keycloak versions prior to 17, the issuer URL format is different: https://{keycloak-url}/auth/realms/{realm-name}. The /auth prefix was removed in Keycloak 17+.

Token Requirements

Char validates Keycloak tokens with these requirements:

Claim	Requirement
`iss`	Must match `https://{keycloak-url}/realms/{realm}`
`aud`	Must include your configured Client ID
`sub`	Required - used as the user identifier (Keycloak user UUID)
`exp`	Must not be expired
`azp`	Authorized party (your Client ID)

Standard Keycloak ID Token Claims

Claim	Description
`sub`	Unique user identifier (UUID)
`preferred_username`	User’s username
`email`	User’s email address
`email_verified`	Whether email is verified
`name`	User’s full name
`given_name`	First name
`family_name`	Last name
`realm_access.roles`	Realm-level roles
`resource_access`	Client-specific roles

Example: Obtaining and Passing the Token

Keycloak JS Adapter
React (keycloak-js)
oidc-client-ts

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

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

keycloak.init({ onLoad: 'check-sso' }).then((authenticated) => {
  if (authenticated) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

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

    agent.setAttribute("auth-token", keycloak.idToken);
  }
});

// Handle token refresh
setInterval(() => {
  keycloak.updateToken(30).then((refreshed) => {
    if (refreshed) {
      console.log('Token refreshed');
    }
  });
}, 60000);

import { useKeycloak } from '@react-keycloak/web';
import { useEffect } from 'react';
import "@mcp-b/embedded-agent/web-component";

function App() {
  const { keycloak, initialized } = useKeycloak();

  useEffect(() => {
    if (initialized && keycloak.authenticated && keycloak.idToken) {
      const agent = document.querySelector("webmcp-agent");
      if (agent) {
        agent.setAttribute("auth-token", keycloak.idToken);
      }
    }
  }, [initialized, keycloak.authenticated, keycloak.idToken]);

  return <webmcp-agent />;
}

// App wrapper
import { ReactKeycloakProvider } from '@react-keycloak/web';
import Keycloak from 'keycloak-js';

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

function Root() {
  return (
    <ReactKeycloakProvider authClient={keycloak}>
      <App />
    </ReactKeycloakProvider>
  );
}

import { UserManager } from 'oidc-client-ts';
import "@mcp-b/embedded-agent/web-component";

const userManager = new UserManager({
  authority: 'https://keycloak.yourcompany.com/realms/production',
  client_id: 'char-ai-widget',
  redirect_uri: window.location.origin + '/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// After authentication callback
userManager.getUser().then((user) => {
  if (user && user.id_token) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

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

    agent.setAttribute("auth-token", user.id_token);
  }
});

Keycloak Roles

Keycloak roles are included in tokens automatically:

// Realm roles are in realm_access.roles
// Client roles are in resource_access.{client-id}.roles

const keycloak = new Keycloak(/* config */);

// After initialization
if (keycloak.hasRealmRole('admin')) {
  console.log('User is an admin');
}

if (keycloak.hasResourceRole('editor', 'char-ai-widget')) {
  console.log('User has editor role for this client');
}

Configuring Audience

By default, Keycloak includes the client ID in the azp (authorized party) claim but may not include it in aud. To ensure the aud claim contains your client ID:

Option 1: Use a Client Scope

Navigate to Client scopes → Create client scope
Name it char-ai-audience
Go to Mappers → Create mapper
Configure:

Setting	Value
Mapper type	Audience
Name	`char-ai-audience`
Included Client Audience	Your client ID
Add to ID token	On

Assign the scope to your client in Clients → Your client → Client scopes

Option 2: Protocol Mapper on Client

Go to Clients → Your client → Client scopes
Click on your client’s dedicated scope
Add a mapper of type Audience
Configure to include your client ID in the audience

Troubleshooting

INVALID_ISSUER error

The issuer URL doesn’t match:

Check Keycloak version: Use /auth/realms/{realm} for versions < 17, /realms/{realm} for 17+
Verify realm name: Realm names are case-sensitive
Check URL: Ensure no trailing slash
HTTPS: Use https:// for production

INVALID_AUDIENCE error

The token’s audience doesn’t include your client ID:

Configure an Audience mapper (see “Configuring Audience” section above)
Verify the Client ID matches exactly
Ensure you’re using the ID token, not the access token

JWKS_FETCH_FAILED error

Char couldn’t reach Keycloak’s JWKS endpoint:

JWKS endpoint: {issuer-url}/protocol/openid-connect/certs
Verify Keycloak is accessible from the internet
Check firewall rules and load balancer configuration
Use Test Connection in the dashboard

CORS errors with Keycloak

If you see CORS errors:

Verify Web origins in client settings includes your application origin
Use + as a special value to allow all redirect URI origins
Check your reverse proxy isn’t stripping CORS headers

Token refresh not working

If token refresh fails:

Ensure Standard flow is enabled on the client
Check refresh token validity in Realm settings → Tokens
Verify the refresh token hasn’t expired (default: 30 minutes idle)

High Availability Setup

For production Keycloak deployments:

Use a load balancer in front of multiple Keycloak nodes
Configure sticky sessions or distributed caching
Set up database replication for the Keycloak database
The issuer URL should use your load balancer’s domain

// Example with load-balanced Keycloak
const keycloak = new Keycloak({
  url: 'https://auth.yourcompany.com', // Load balancer URL
  realm: 'production',
  clientId: 'char-ai-widget',
});

Security Best Practices

Enable HTTPS for all Keycloak endpoints
Configure brute force protection in realm settings
Set appropriate token lifetimes (shorter for sensitive applications)
Use client scopes to minimize token claims
Enable MFA for users with elevated privileges
Regularly update Keycloak to patch security vulnerabilities
Audit login events using Keycloak’s event logging
Configure password policies appropriate for your security requirements

Introduction

How-to Guides

Explanation

Prerequisites

Quick Links

Keycloak Admin Console

OIDC Documentation

Client Configuration

Keycloak JS Adapter

SDK References

keycloak-js

@react-keycloak/web

oidc-client-ts

Configuration Steps

Configuration Reference

Token Requirements

Standard Keycloak ID Token Claims

Example: Obtaining and Passing the Token

Keycloak Roles

Configuring Audience

Option 1: Use a Client Scope

Option 2: Protocol Mapper on Client

Troubleshooting

High Availability Setup

Security Best Practices

Introduction

How-to Guides

Explanation

​Prerequisites

​Quick Links

Keycloak Admin Console

OIDC Documentation

Client Configuration

Keycloak JS Adapter

​SDK References

keycloak-js

@react-keycloak/web

oidc-client-ts

​Configuration Steps

​Configuration Reference

​Token Requirements

​Standard Keycloak ID Token Claims

​Example: Obtaining and Passing the Token

​Keycloak Roles

​Configuring Audience

​Option 1: Use a Client Scope

​Option 2: Protocol Mapper on Client

​Troubleshooting

​High Availability Setup

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Token Requirements

Standard Keycloak ID Token Claims

Example: Obtaining and Passing the Token

Keycloak Roles

Configuring Audience

Option 1: Use a Client Scope

Option 2: Protocol Mapper on Client

Troubleshooting

High Availability Setup

Security Best Practices