Azure AD

Connect Microsoft Entra ID (formerly Azure Active Directory) to authenticate end users with your Char agent. Create an app registration and configure Char for token validation.

Prerequisites

A Microsoft Entra ID tenant (Azure AD)
Admin access to create app registrations
Access to the Char dashboard

Quick Links

Azure Portal

App registrations in Azure Portal

Entra Admin Center

Microsoft Entra Admin Center

Microsoft Docs

ID Token Claims

Token claims reference

SDK References

@azure/msal-browser

Microsoft Authentication Library for Browser

@azure/msal-react

MSAL React wrapper library

Configuration Steps

Sign in to the Azure Portal or Entra Admin Center
Navigate to Microsoft Entra ID → App registrations
Click New registration
Configure the registration:

Setting	Value
Name	`Char Agent` (or your preferred name)
Supported account types	Choose based on your needs (typically “Single tenant”)
Redirect URI	Select “Single-page application (SPA)” and enter your callback URL

Click Register

Note Your Application (Client) ID and Tenant ID

After registration, from the Overview page, copy:

Application (client) ID - This is your Client ID
Directory (tenant) ID - This is your Tenant ID (used as the domain in Char)

See Microsoft’s app registration guide for screenshots showing exactly where to find these values.

Configure Authentication Settings

Navigate to Authentication in your app registration:

Under Single-page application, verify your redirect URIs
Under Implicit grant and hybrid flows, ensure ID tokens is checked
Click Save

For production, use the Authorization Code flow with PKCE instead of implicit flow. The MSAL library handles this automatically.

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Azure AD as the provider
Enter your Application (client) ID as the Client ID
Enter your Directory (tenant) ID as the Tenant ID
Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Azure Value	Example
Provider Type	Azure AD	`azure`
Client ID	Application (client) ID	`12345678-1234-1234-1234-123456789012`
Tenant ID	Directory (tenant) ID	`87654321-4321-4321-4321-210987654321`

You can also use your verified domain name instead of the Tenant ID (e.g., contoso.onmicrosoft.com or a custom domain like contoso.com).

Token Requirements

Char validates Azure AD tokens with these requirements:

Claim	Requirement
`iss`	Must match `https://login.microsoftonline.com/{tenant-id}/v2.0`
`aud`	Must include your configured Application (client) ID
`sub`	Required - used as the user identifier
`exp`	Must not be expired

Example: Obtaining and Passing the Token

MSAL.js (Browser)
React (MSAL React)
SSR (Ticket Exchange)

import { PublicClientApplication } from '@azure/msal-browser';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

const CLIENT_ID = '12345678-1234-1234-1234-123456789012';

const msalConfig = {
  auth: {
    clientId: CLIENT_ID,
    authority: 'https://login.microsoftonline.com/87654321-4321-4321-4321-210987654321',
    redirectUri: window.location.origin,
  },
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

// After authentication
const account = msalInstance.getAllAccounts()[0];
const tokenResponse = await msalInstance.acquireTokenSilent({
  account,
  scopes: ['openid', 'profile', 'email'],
});

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: tokenResponse.idToken, clientId: CLIENT_ID });

import { useMsal, useAccount } from '@azure/msal-react';
import { useEffect, useRef } from 'react';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

const CLIENT_ID = '12345678-1234-1234-1234-123456789012';

function App() {
  const { instance, accounts } = useMsal();
  const account = useAccount(accounts[0] || {});
  const agentRef = useRef<WebMCPAgentElement>(null);

  useEffect(() => {
    if (account) {
      instance.acquireTokenSilent({
        account,
        scopes: ['openid', 'profile', 'email'],
      }).then((response) => {
        agentRef.current?.connect({ idToken: response.idToken, clientId: CLIENT_ID });
      });
    }
  }, [account, instance]);

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

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

// app/dashboard/page.tsx (Server Component)
import { getServerSession } from './msal-server'; // Your server MSAL helper
import { redirect } from 'next/navigation';
import { CharAgent } from './char-agent';

const CLIENT_ID = '12345678-1234-1234-1234-123456789012';

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({
      client_id: CLIENT_ID,
    }),
  });
  return response.json(); // { ticket, userId, orgId, expiresAt }
}

export default async function Dashboard() {
  const session = await getServerSession();
  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 MSAL sessions live on your server.

Multi-Tenant Configuration

If your application supports multiple Azure AD tenants:

Register your app with Accounts in any organizational directory
Use the common or organizations authority endpoint
Configure Char with your specific tenant ID where you want to validate tokens

Multi-tenant apps accept tokens from any tenant. For Char, you should configure a specific tenant ID to ensure only users from your organization can access the agent.

Troubleshooting

INVALID_ISSUER error

The token issuer doesn’t match your configured tenant:

Verify the Tenant ID in Char matches your Azure AD directory
Check that you’re using the v2.0 endpoint (MSAL uses this by default)
For multi-tenant apps, ensure you’ve configured the correct tenant

INVALID_AUDIENCE error

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

Ensure the Client ID matches your Application (client) ID exactly
Verify you’re using the ID token, not the access token
Check that your app registration has the correct redirect URI type (SPA)

JWKS_FETCH_FAILED error

Char couldn’t reach Azure’s JWKS endpoint:

Verify your Tenant ID is correct
Check network connectivity to login.microsoftonline.com
Use Test Connection in the dashboard to verify

Token acquisition fails silently

If acquireTokenSilent fails:

Ensure the user has previously authenticated interactively
Check that your scopes include openid
Verify the redirect URI matches your app registration
Try acquireTokenPopup or acquireTokenRedirect as a fallback

Security Best Practices

Use connect() for authentication - The connect({ idToken, clientId }) method keeps tokens out of the DOM
Use ticket exchange for SSR - For server-rendered pages, exchange Azure AD JWTs for short-lived tickets server-side
Use single-tenant configuration unless you specifically need multi-tenant support
Enable Conditional Access policies in Azure AD for additional security controls
Configure token lifetime appropriately in Azure AD
Monitor sign-in logs in Azure AD for suspicious activity
Regularly review app permissions and remove unnecessary scopes

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

Prerequisites

Quick Links

Azure Portal

Entra Admin Center

Microsoft Docs

ID Token Claims

SDK References

@azure/msal-browser

@azure/msal-react

Configuration Steps

Configuration Reference

Token Requirements

Example: Obtaining and Passing the Token

Multi-Tenant Configuration

Troubleshooting

Security Best Practices

Introduction

Getting Started

How-to Guides

Explanation

Private Beta

​Prerequisites

​Quick Links

Azure Portal

Entra Admin Center

Microsoft Docs

ID Token Claims

​SDK References

@azure/msal-browser

@azure/msal-react

​Configuration Steps

​Configuration Reference

​Token Requirements

​Example: Obtaining and Passing the Token

​Multi-Tenant Configuration

​Troubleshooting

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Token Requirements

Example: Obtaining and Passing the Token

Multi-Tenant Configuration

Troubleshooting

Security Best Practices