Google Workspace

Connect Google Workspace (formerly G Suite) or Google Cloud Identity to authenticate end users with your Char agent. Create OAuth credentials in Google Cloud Console and configure Char for token validation.

Prerequisites

A Google Workspace or Google Cloud Identity account
Admin access to Google Cloud Console
Access to the Char dashboard

Quick Links

Google Cloud Console

APIs & Services Credentials

Google Admin Console

Google Workspace Admin Console

OAuth 2.0 Guide

Google OAuth 2.0 for Client-side Apps

Google Identity Services

SDK References

Google Identity Services

GIS JavaScript API Reference

@react-oauth/google

Google OAuth for React

Configuration Steps

Create a Google Cloud Project

If you don’t have a project already:

Go to the Google Cloud Console
Click the project dropdown and select New Project
Enter a project name and click Create
Select your new project from the dropdown

Configure OAuth Consent Screen

Navigate to APIs & Services → OAuth consent screen
Select Internal (for Google Workspace users only) or External
Fill in the required information:

Field	Value
App name	`Char Agent`
User support email	Your support email
Developer contact	Your email

Add scopes: openid, email, profile
Click Save and Continue through the remaining steps

For Internal apps, only users in your Google Workspace organization can authenticate. This is the recommended setting for enterprise use.

Create OAuth Client ID

Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
Configure the client:

Setting	Value
Application type	Web application
Name	`Char Agent`
Authorized JavaScript origins	Your application’s origin(s)
Authorized redirect URIs	Your callback URL(s)

Click Create

Note Your Client ID

After creating the OAuth client, copy the Client ID from the confirmation dialog or the Credentials page.

See Google’s create credentials guide for step-by-step instructions with screenshots.

Keep the Client Secret secure, but note that Char only needs the Client ID for token validation (public key verification).

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Google as the provider
Enter your Client ID from Step 4
(Domain field is not required for Google)
Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	Google Value	Example
Provider Type	Google	`google`
Client ID	OAuth Client ID	`123456789012-abcdefg.apps.googleusercontent.com`
Domain	Not required	-

Google uses a fixed issuer URL (https://accounts.google.com), so no domain configuration is needed.

Token Requirements

Char validates Google tokens with these requirements:

Claim	Requirement
`iss`	Must be `https://accounts.google.com`
`aud`	Must include your configured Client ID
`sub`	Required - used as the user identifier
`exp`	Must not be expired
`hd`	(Optional) Hosted domain for Google Workspace

Example: Obtaining and Passing the Token

Google Identity Services (New)
React (Google Identity)
SSR (Ticket Exchange)
Firebase Authentication

import "@mcp-b/char/web-component";

const CLIENT_ID = '123456789012-abcdefg.apps.googleusercontent.com';

// Initialize Google Identity Services
google.accounts.id.initialize({
  client_id: CLIENT_ID,
  callback: handleCredentialResponse,
});

function handleCredentialResponse(response) {
  // response.credential is the ID token
  const agent =
    document.querySelector("char-agent") ?? document.createElement("char-agent");

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

  // Use connect() - keeps token out of DOM
  agent.connect({ idToken: response.credential, clientId: CLIENT_ID });
}

// Render sign-in button
google.accounts.id.renderButton(
  document.getElementById('google-signin'),
  { theme: 'outline', size: 'large' }
);

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

// Add to your global.d.ts or inline
declare const google: {
  accounts: {
    id: {
      initialize: (config: { client_id: string; callback: (response: { credential: string }) => void }) => void;
      renderButton: (element: HTMLElement | null, options: { theme: string; size: string }) => void;
    };
  };
};

const CLIENT_ID = '123456789012-abcdefg.apps.googleusercontent.com';

function App() {
  const agentRef = useRef<WebMCPAgentElement>(null);

  const handleCredentialResponse = useCallback((response: { credential: string }) => {
    agentRef.current?.connect({ idToken: response.credential, clientId: CLIENT_ID });
  }, []);

  useEffect(() => {
    // Load Google Identity Services script
    const script = document.createElement('script');
    script.src = 'https://accounts.google.com/gsi/client';
    script.async = true;
    script.defer = true;
    document.body.appendChild(script);

    script.onload = () => {
      google.accounts.id.initialize({
        client_id: CLIENT_ID,
        callback: handleCredentialResponse,
      });
      google.accounts.id.renderButton(
        document.getElementById('google-signin'),
        { theme: 'outline', size: 'large' }
      );
    };

    return () => {
      document.body.removeChild(script);
    };
  }, [handleCredentialResponse]);

  return (
    <>
      <div id="google-signin" />
      <char-agent ref={agentRef} />
    </>
  );
}

For server-side rendered applications, exchange the Google JWT for a short-lived ticket instead of passing it to the client:

// app/dashboard/page.tsx (Server Component)
import { redirect } from 'next/navigation';
import { CharAgent } from './char-agent';

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

export default async function Dashboard() {
  const session = await getGoogleSession(); // Your server-side Google session helper
  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.

import { initializeApp } from 'firebase/app';
import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';
import "@mcp-b/char/web-component";
import type { WebMCPAgentElement } from "@mcp-b/char/web-component";

const app = initializeApp({
  apiKey: 'your-api-key',
  authDomain: 'your-project.firebaseapp.com',
  projectId: 'your-project',
});

const auth = getAuth(app);
const provider = new GoogleAuthProvider();

const CLIENT_ID = 'your-project-id';

async function signIn() {
  const result = await signInWithPopup(auth, provider);
  const idToken = await result.user.getIdToken();

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

When using Firebase Auth, the token issuer will be https://securetoken.google.com/{project-id}. You may need to use Custom OIDC configuration instead of Google for Firebase tokens.

SPA vs SSR: Use connect({ idToken, clientId }) for SPAs to keep tokens out of the DOM. Use connect({ ticketAuth }) for SSR apps where authentication happens server-side.

Restricting to Google Workspace Domain

To ensure only users from your Google Workspace organization can authenticate:

In Google Cloud Console, set the OAuth consent screen to Internal
Optionally, validate the hd (hosted domain) claim in your application:

// Decode token to check hosted domain (validation happens server-side)
const payload = JSON.parse(atob(token.split('.')[1]));
if (payload.hd !== 'yourcompany.com') {
  throw new Error('User not from authorized domain');
}

The hd claim is only present for Google Workspace accounts, not personal Gmail accounts.

Troubleshooting

INVALID_ISSUER error

The token issuer doesn’t match Google’s expected issuer:

Verify you’re using a Google OAuth token, not a Firebase token
Check that the token comes from Google Sign-In, not another provider

INVALID_AUDIENCE error

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

Ensure the Client ID matches your Google OAuth client exactly
Verify the credential is an ID token (not an access token)
Check that your OAuth client is the one used for sign-in

JWKS_FETCH_FAILED error

Char couldn’t reach Google’s JWKS endpoint:

This is rare for Google - check network connectivity
Use Test Connection in the dashboard to verify

Users from personal Gmail can sign in

Consent screen shows as unverified

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 Google JWTs for short-lived tickets server-side
Use Internal consent screen for enterprise apps to restrict access to your organization
Enable 2-Step Verification in Google Workspace Admin Console
Use the latest Google Identity Services library (not the deprecated Google Sign-In)
Validate the hd claim if you need to restrict to specific domains
Review third-party app access in Google Workspace Admin Console
Enable security alerts in Google Workspace for suspicious sign-in attempts