Skip to main content
Connect Firebase Authentication to authenticate end users with your Char widget. Configure your Firebase project and set up Char for token validation.
Firebase uses a unique token format. Firebase ID tokens use Google’s project-based issuer URL and require specific audience configuration. Ensure you follow this guide carefully.

Prerequisites

  • A Firebase project with Authentication enabled
  • At least one sign-in method configured in Firebase
  • Access to the Char dashboard

SDK References

Configuration Steps

1

Set Up Firebase Authentication

  1. Go to the Firebase Console
  2. Select your project (or create a new one)
  3. Navigate to BuildAuthentication
  4. Click Get started if not already enabled
  5. Enable your desired sign-in methods (Email/Password, Google, etc.)
2

Note Your Project ID

From the Firebase Console:
  1. Click the gear iconProject settings
  2. Find your Project ID in the General tab
Firebase Project Settings

Find your Project ID in Firebase settings

Your Project ID is used to construct the issuer URL. It’s different from the Web API Key.
3

Get Your Firebase Config

In Project settingsGeneral:
  1. Scroll to Your apps
  2. If no web app exists, click Add appWeb
  3. Note the configuration values, especially projectId
// Firebase config object
const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id", // ← This is your Project ID
  // ...other config
};
4

Configure Char

In the Char Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Custom OIDC as the provider
  3. Enter your configuration:
FieldValue
Client IDYour Firebase Project ID
Issuer URLhttps://securetoken.google.com/{project-id}
  1. Click Test Connection to verify
  2. Click Save Changes

Configuration Reference

Char FieldFirebase ValueExample
Provider TypeCustom OIDCcustom_oidc
Client IDFirebase Project IDmy-app-12345
Issuer URLSecure Token issuerhttps://securetoken.google.com/my-app-12345
Firebase ID tokens use https://securetoken.google.com/{project-id} as the issuer, and the audience (aud) is your Project ID. This is different from Google OAuth tokens.

Token Requirements

Char validates Firebase tokens with these requirements:
ClaimRequirement
issMust be https://securetoken.google.com/{project-id}
audMust be your Firebase Project ID
subRequired - Firebase user UID
expMust not be expired
auth_timeMust be in the past

Standard Firebase ID Token Claims

ClaimDescription
subFirebase user UID (unique identifier)
emailUser’s email address
email_verifiedWhether email is verified
nameUser’s display name
pictureUser’s photo URL
firebase.sign_in_providerAuthentication provider used
firebase.identitiesLinked identity providers

Example: Obtaining and Passing the Token

import { initializeApp } from 'firebase/app';
import { getAuth, onAuthStateChanged, getIdToken } from 'firebase/auth';
import "@mcp-b/embedded-agent/web-component";

const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
};

const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

onAuthStateChanged(auth, async (user) => {
  if (user) {
    const idToken = await getIdToken(user);

    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

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

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

Token Refresh

Firebase ID tokens expire after 1 hour. Handle token refresh:
import { getAuth, getIdToken } from 'firebase/auth';

const auth = getAuth();

// Force refresh to get a new token
async function refreshToken() {
  const user = auth.currentUser;
  if (user) {
    // Pass true to force refresh
    const newToken = await getIdToken(user, true);
    return newToken;
  }
  return null;
}

// Set up automatic refresh before expiration
setInterval(async () => {
  const newToken = await refreshToken();
  if (newToken) {
    const agent = document.querySelector("webmcp-agent");
    if (agent) {
      agent.setAttribute("auth-token", newToken);
    }
  }
}, 55 * 60 * 1000); // Refresh every 55 minutes

Custom Claims

Add custom claims using Firebase Admin SDK:
// Server-side: Set custom claims
import { getAuth } from 'firebase-admin/auth';

await getAuth().setCustomUserClaims(uid, {
  role: 'admin',
  team: 'engineering',
  subscription: 'premium',
});

// Client-side: Access custom claims
const user = auth.currentUser;
const tokenResult = await user.getIdTokenResult();
console.log('Role:', tokenResult.claims.role);
Custom claims are included in the ID token. Changes take effect on the next token refresh (force refresh with getIdToken(user, true)).

Multiple Authentication Providers

Firebase supports linking multiple authentication providers:
// User signed in with email can link Google
import { GoogleAuthProvider, linkWithPopup } from 'firebase/auth';

const googleProvider = new GoogleAuthProvider();
const result = await linkWithPopup(auth.currentUser, googleProvider);

// The ID token will include all linked identities in firebase.identities

Troubleshooting

The issuer URL format is incorrect:
  1. Use the correct format: https://securetoken.google.com/{project-id}
  2. Verify Project ID: Found in Firebase Console → Project settings
  3. No trailing slash: The URL should not end with /
  4. Case sensitivity: Project IDs are lowercase
The token’s audience doesn’t match:
  • The audience must be your Firebase Project ID (not API key)
  • Verify you’re using getIdToken(), not getAccessToken()
  • Check the Project ID in the Char configuration matches exactly
Char couldn’t reach Google’s JWKS endpoint:
  • Firebase uses Google’s public keys at https://www.googleapis.com/service_accounts/v1/jwk/[email protected]
  • This should always be accessible; if not, check your network configuration
Firebase tokens expire after 1 hour:
  • Implement automatic token refresh (see “Token Refresh” section)
  • Use getIdToken(user, true) to force a fresh token
  • Consider checking exp claim before making requests
If custom claims aren’t in the token:
  • Custom claims require a token refresh to take effect
  • Call getIdToken(user, true) after setting claims
  • Check claims were set correctly using Admin SDK
  • Custom claim keys cannot start with reserved prefixes (firebase:, google:)

Firebase vs Google OAuth

Don’t confuse Firebase Auth with Google OAuth. They use different issuers and token formats:
ProviderIssuer URLAudience
Firebase Authhttps://securetoken.google.com/{project-id}Project ID
Google OAuthhttps://accounts.google.comClient ID
If you’re using the Google sign-in provider within Firebase, you still use Firebase tokens (not Google OAuth tokens).

Security Best Practices

  • Enable email verification for email/password authentication
  • Configure authorized domains in Firebase Console → Authentication → Settings
  • Use security rules for Firestore/Realtime Database access control
  • Enable App Check to protect against abuse
  • Monitor usage in Firebase Console for unusual patterns
  • Set session duration appropriately in Firebase Console
  • Implement proper sign-out to invalidate sessions