Skip to main content

Google Workspace Integration

Connect Google Workspace (formerly G Suite) or Google Cloud Identity to authenticate end users interacting with your Char AI widget. This guide covers creating OAuth credentials in Google Cloud Console and configuring Char AI for token validation.

Prerequisites

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

Configuration Steps

1

Create a Google Cloud Project

If you don’t have a project already:
  1. Go to the Google Cloud Console
  2. Click the project dropdown and select New Project
  3. Enter a project name and click Create
  4. Select your new project from the dropdown
2

Configure OAuth Consent Screen

  1. Navigate to APIs & ServicesOAuth consent screen
  2. Select Internal (for Google Workspace users only) or External
  3. Fill in the required information:
FieldValue
App nameChar AI Widget
User support emailYour support email
Developer contactYour email
  1. Add scopes: openid, email, profile
  2. 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.
3

Create OAuth Client ID

  1. Navigate to APIs & ServicesCredentials
  2. Click Create CredentialsOAuth client ID
  3. Configure the client:
SettingValue
Application typeWeb application
NameChar AI Widget
Authorized JavaScript originsYour application’s origin(s)
Authorized redirect URIsYour callback URL(s)
  1. Click Create
4

Note Your Client ID

After creating the OAuth client, copy the Client ID.
Google Cloud OAuth Client ID

Copy your Client ID from the OAuth client details

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

Configure Char AI

In the Char AI Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Google as the provider
  3. Enter your Client ID from Step 4
  4. (Domain field is not required for Google)
  5. Click Test Connection to verify
  6. Click Save Changes

Configuration Reference

Char AI FieldGoogle ValueExample
Provider TypeGooglegoogle
Client IDOAuth Client ID123456789012-abcdefg.apps.googleusercontent.com
DomainNot required-
Google uses a fixed issuer URL (https://accounts.google.com), so no domain configuration is needed.

Token Requirements

Char AI validates Google tokens with these requirements:
ClaimRequirement
issMust be https://accounts.google.com
audMust include your configured Client ID
subRequired - used as the user identifier
expMust not be expired
hd(Optional) Hosted domain for Google Workspace

Example: Obtaining and Passing the Token

import { CharWidget } from '@char-ai/widget';

// Initialize Google Identity Services
google.accounts.id.initialize({
  client_id: '123456789012-abcdefg.apps.googleusercontent.com',
  callback: handleCredentialResponse,
});

function handleCredentialResponse(response) {
  // response.credential is the ID token
  CharWidget.init({
    siteId: 'your-site-id',
    userToken: response.credential,
  });
}

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

Restricting to Google Workspace Domain

To ensure only users from your Google Workspace organization can authenticate:
  1. In Google Cloud Console, set the OAuth consent screen to Internal
  2. 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

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
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
Char AI couldn’t reach Google’s JWKS endpoint:
  • This is rare for Google - check network connectivity
  • Use Test Connection in the dashboard to verify
If you only want Google Workspace users:
  • Set the OAuth consent screen to Internal in Google Cloud Console
  • Validate the hd claim in your application before initializing the widget

Security Best Practices

  • 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

Google Workspace Admin Settings

In the Google Admin Console, you can:
  1. Require 2-Step Verification for all users
  2. Manage third-party app access to control which apps can use Google Sign-In
  3. View audit logs to monitor sign-in activity
  4. Configure security alerts for suspicious activity
Navigate to SecurityAuthentication to manage these settings.