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
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
Sign in with Google documentation
Configuration Steps
1
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
2
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 AI Widget |
| 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.
3
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 AI Widget |
| Authorized JavaScript origins | Your application’s origin(s) |
| Authorized redirect URIs | Your callback URL(s) |
- Click Create
4
Note Your Client ID
After creating the OAuth client, copy the Client ID.

Copy your Client ID from the OAuth client details
5
Configure Char AI
In the Char AI 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 AI Field | Google Value | Example |
|---|---|---|
| Provider Type | 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 AI 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)
- Firebase Authentication
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:
The
hd claim is only present for Google Workspace accounts, not personal Gmail accounts.Troubleshooting
INVALID_ISSUER error
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
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
JWKS_FETCH_FAILED error
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
Users from personal Gmail can sign in
Users from personal Gmail can sign in
If you only want Google Workspace users:
- Set the OAuth consent screen to Internal in Google Cloud Console
- Validate the
hdclaim in your application before initializing the widget
Consent screen shows as unverified
Consent screen shows as unverified
For external apps:
- You may need to go through Google’s verification process for production use
- Internal apps don’t require verification
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
hdclaim 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:- Require 2-Step Verification for all users
- Manage third-party app access to control which apps can use Google Sign-In
- View audit logs to monitor sign-in activity
- Configure security alerts for suspicious activity

