Skip to main content
Connect Logto to authenticate end users with your Char agent. Create a Logto application and configure Char for token validation.

Prerequisites

SDK References

Configuration Steps

1

Create an Application in Logto

  1. Sign in to the Logto Console (or your self-hosted instance)
  2. Navigate to Applications
  3. Click Create application
  4. Select the appropriate application type:
Application TypeUse Case
Single page appReact, Vue, Angular SPAs
Traditional web appNext.js, Express with server sessions
Native appiOS, Android, React Native
  1. Follow the setup wizard for your framework
2

Configure Application Settings

In your application’s settings, configure:
SettingValue
Redirect URIsYour application’s callback URL(s) (e.g., https://yourapp.com/callback)
Post sign-out redirect URIsWhere users land after logout
CORS allowed originsYour application’s origin(s)
3

Note Your Application Credentials

From the application settings, copy:
  1. App ID - Your application’s client ID
  2. Endpoint - Your Logto endpoint (e.g., https://your-tenant.logto.app or your self-hosted URL)
For traditional web apps, also copy the App Secret for server-side token exchange.
4

Configure Char

In the Char Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Custom OIDC as the provider
  3. Enter your Issuer URL (your Logto endpoint, e.g., https://your-tenant.logto.app/oidc)
  4. Enter your Client ID (App ID from Step 3)
  5. Click Test Connection to verify
  6. Click Save Changes

Configuration Reference

Char FieldLogto ValueExample
Provider TypeCustom OIDCoidc
Issuer URLLogto endpoint + /oidchttps://your-tenant.logto.app/oidc
Client IDApplication App IDabc123def456
Logto’s OIDC issuer URL is your endpoint followed by /oidc. The JWKS endpoint is at {endpoint}/oidc/jwks and discovery at {endpoint}/oidc/.well-known/openid-configuration.

Using Upstream Identity Providers

If you’re using Logto with social connectors (Google, GitHub, etc.) or enterprise SSO, Logto acts as your identity layer. Char validates Logto’s tokens, not the upstream provider’s tokens.

Understanding Auth Platforms vs Direct IDPs

Learn how auth platforms like Logto issue their own tokens after upstream OAuth flows

Token Requirements

Char validates Logto ID tokens with these requirements:
ClaimRequirement
issMust match {your-logto-endpoint}/oidc
audMust include your configured App ID
subRequired - used as the user identifier
expMust not be expired

Logto ID Token Claims

Logto ID tokens include standard OIDC claims based on requested scopes:
ScopeClaims Included
openidsub (user ID), iss, aud, exp, iat
profilename, picture, username
emailemail, email_verified
Example ID token payload:
{
  "sub": "user_abc123",
  "iss": "https://your-tenant.logto.app/oidc",
  "aud": "your-app-id",
  "exp": 1742975822,
  "iat": 1742974022,
  "name": "John Doe",
  "email": "[email protected]",
  "email_verified": true
}

Example: Obtaining and Passing the Token

import { LogtoProvider, useLogto } from "@logto/react";
import { useEffect, useRef } from "react";
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

// Configure the provider in your app root
const CLIENT_ID = "your-app-id";

const config = {
  endpoint: "https://your-tenant.logto.app",
  appId: CLIENT_ID,
};

function App() {
  return (
    <LogtoProvider config={config}>
      <Dashboard />
    </LogtoProvider>
  );
}

function Dashboard() {
  const { isAuthenticated, getIdTokenClaims } = useLogto();
  const agentRef = useRef<WebMCPAgentElement>(null);

  useEffect(() => {
    if (isAuthenticated && agentRef.current) {
      getIdTokenClaims().then((claims) => {
        if (claims?.__raw) {
          // Use connect() - keeps token out of DOM
          agentRef.current?.connect({ idToken: claims.__raw, clientId: CLIENT_ID });
        }
      });
    }
  }, [isAuthenticated, getIdTokenClaims]);

  return <char-agent ref={agentRef} />;
}
Which approach? Use Next.js SSR with Ticket if you want to keep Logto JWTs server-side (more secure). Use the React/Browser SDK if you have a client-side SPA.

Organizations and Multi-Tenancy

Logto supports multi-tenant applications with organizations:
// Request organization-scoped tokens
const config = {
  endpoint: "https://your-tenant.logto.app",
  appId: "your-app-id",
  scopes: ["openid", "profile", "email", "urn:logto:scope:organizations"],
};
Organization claims are included in tokens when users belong to organizations. See the organization token guide for details.

Custom Token Claims

Logto allows adding custom claims to tokens via the Console:
  1. Go to API resourcesLogto management API
  2. Configure custom JWT claims in the Machine to machine section
  3. Or use the Custom JWT feature for access tokens

Custom Token Claims

Learn how to add custom claims to Logto tokens

Troubleshooting

The token issuer doesn’t match your configured endpoint:
  • Verify the Issuer URL in Char includes /oidc suffix (e.g., https://your-tenant.logto.app/oidc)
  • Ensure you’re using the correct tenant URL
  • For self-hosted instances, verify your ENDPOINT configuration
The token’s aud claim doesn’t match your configured App ID:
  • Ensure the Client ID matches your Logto application’s App ID exactly
  • Verify you’re using the ID token (from getIdTokenClaims().__raw)
  • Check that the correct application is configured
Char couldn’t reach Logto’s JWKS endpoint:
  • Verify your Logto instance is accessible
  • Check that the endpoint URL is correct
  • For self-hosted: ensure /oidc/jwks is publicly accessible
  • Use Test Connection in the dashboard to verify
If you can’t get the ID token claims:
  • Ensure the user has completed the sign-in flow
  • Check that openid scope is included (it’s included by default)
  • Verify your redirect URIs match your application settings
For Next.js SDK:
  • The cookieSecret in your config must be at least 32 characters
  • Generate a secure secret: openssl rand -base64 32

Logto Features

Logto offers additional features that complement Char integration:
FeatureDescription
Multi-tenancyBuilt-in organization support for B2B apps
Enterprise SSOSAML and OIDC connections for enterprise customers
RBACRole-based access control with permissions
Social Login30+ social connectors (Google, GitHub, etc.)
PasswordlessEmail/SMS magic links and codes
MFATOTP and backup codes
WebhooksReal-time event notifications
Audit LogsTrack authentication events

Logto Documentation

Explore the full Logto documentation

Self-Hosting Logto

Logto can be self-hosted using Docker:
# Quick start with Docker
docker run -d \
  -p 3001:3001 \
  -p 3002:3002 \
  -e ENDPOINT=https://auth.yourapp.com \
  ghcr.io/logto-io/logto
For production deployments, see the self-hosting guide.

Security Best Practices

  • Use HTTPS for all endpoints in production
  • Configure CORS to restrict allowed origins
  • Set appropriate token expiration times
  • Enable MFA for enhanced security
  • Review audit logs regularly for suspicious activity
  • Use organizations for proper tenant isolation in B2B apps