Google Workspace SSO

Let your employees sign in with their Google Workspace account. Google OAuth is simpler than SAML — no metadata exchange and no signing certificate to rotate — but it carries no group claims, so it can't drive role assignment. To map groups to roles, use Google as a SAML identity provider via SAML SSO instead.

:::note Before you begin You need two things in place:

• Access to a Google Cloud project under your Workspace organization.
• Super-admin access to your workspace at <slug>.app.ontrackio.com/admin/settings.

Set aside 15–20 minutes. You configure the OAuth client in Google Cloud, then paste the credentials into OnTrackio. :::

What Google OAuth covers

Capability	Supported	Notes
Sign in with a corporate Google account	Yes	Adds a Continue with Google button on /login
First name, last name, and email from the Google profile	Yes	Cached on the user record
Avatar synced from the Google profile	Yes	Refreshed on every sign-in
Domain allowlist (only @acme.com accounts)	Yes	Configured per workspace
Just-in-time user provisioning	Yes	A new email creates a user with the employee role
External-collaborator bypass	Yes	A user flagged is_external skips the domain check
Group-based role assignment	No	OAuth carries no group claims — use SAML SSO
Auto-promote the first user to admin	No	Seed the first super-admin via the SUPER_ADMIN_EMAILS allowlist
Directory profile sync (job title, department, manager)	Optional	Requires Admin SDK access — see Optional: directory profile sync

:::warning No auto-promote on first sign-in The first user to complete sign-in is not promoted to admin. An attacker who reaches /auth/google/callback before your real admin would otherwise gain control. Grant the first super-admin through the SUPER_ADMIN_EMAILS allowlist, then run the database seeder. :::

Step 1 — Create the OAuth client in Google Cloud

1. Open the Google Cloud Console and select the Workspace-scoped project from the project picker, or create one.
2. Go to Google Auth Platform in the left navigation. On older projects this is APIs & Services → OAuth consent screen — the same screen, renamed in 2026.
3. Under Audience, set User type to Internal. This gates the client to your domain and skips Google's app-verification process. If you must use External, the app stays in testing until you publish and verify it — workable for a handful of test users, blocked past roughly 100.
4. Under Branding, fill in the fields below.

Field	Required	Notes
App name	Yes	What users see on the consent screen, for example OnTrackio ITAM
User support email	Yes	An address you monitor — Google requires it
App logo	No	Shown on the consent screen
Developer contact	Yes	An admin email

5. Under Data Access, keep the default scopes. OnTrackio requests only openid, profile, and email. These are non-sensitive and don't trigger Google's review.
6. Select Save.

Step 2 — Create the OAuth 2.0 client ID

1. Open Google Auth Platform → Clients. On older projects this is APIs & Services → Credentials.
2. Select Create client (older layout: Create credentials → OAuth client ID).
3. Set Application type to Web application. The form then expands to show Name, Authorized JavaScript origins, and Authorized redirect URIs.
4. Fill in the fields below.

Field	Value
Name	OnTrackio ITAM — shown only in the Google Cloud Console, not to users
Authorized JavaScript origins	https://<slug>.app.ontrackio.com — the host with no path
Authorized redirect URIs	https://<slug>.app.ontrackio.com/auth/google/callback — the host plus /auth/google/callback

:::warning One redirect URI per workspace Google does not support wildcard redirect URIs. Each workspace subdomain needs its own entry under Authorized redirect URIs. If you run more than one OnTrackio workspace, add a row for every <slug>. :::

5. Select Create. Google shows the new Client ID and Client secret.
6. Copy the client secret now, or download the JSON. Google displays the secret once — closing the dialog hides it for good, and you would have to create a new client to get another.

Step 3 — Configure Google Workspace SSO in OnTrackio

1. Sign in to OnTrackio as a super-admin.
2. Go to Admin → Settings → Integrations. The integration card grid opens.
3. Select the Google Workspace SSO card to open its configuration modal.
4. Fill in the fields below.

Field	Required	Default	Notes
Enable Google sign-in	Yes	Off	Turns the Continue with Google button on for /login
Client ID	Yes	—	From step 2, ends in .apps.googleusercontent.com
Client secret	Yes	—	From step 2, starts with GOCSPX-. Encrypted at rest
Redirect URI	No	https://<slug>.app.ontrackio.com/auth/google/callback	Override only if needed. Register this exact value in Google's Authorized redirect URIs
Allowed email domains	No	Any account	Comma-separated, for example acme.com, acme.io. Applies to every SSO provider, not Google alone. Leave blank to allow any verified account

5. Select Save changes in the main settings panel. The Google Workspace SSO card flips to Enabled, and the Continue with Google button appears on /login immediately.

:::tip Granting access to people outside your domains To let in a contractor whose email domain isn't on the allowlist, flag their user record as an external collaborator (is_external). External users skip the domain check, and the bypass is recorded in the audit log as a deliberate admin action. :::

Step 4 — Test the round-trip

1. Open an incognito window.
2. Go to https://<slug>.app.ontrackio.com/login. The Continue with Google button appears alongside your other sign-in methods.
3. Select Continue with Google and choose the account to sign in as. First-time consent for the OAuth client may appear — accept it.
4. Confirm the outcome:

Scenario	What happens
First-time user	Provisioned with the employee role, lands on /my
Returning user	last_login_at and last_login_ip updated, avatar refreshed, lands on the admin dashboard (if admin) or /my

5. Open Admin → Audit log and confirm the User signed in with Google SSO entry under the auth channel.

Optional: directory profile sync

To auto-populate fields such as job_title, department, and manager from your Workspace directory, enable the sync layer. On every Google sign-in, OnTrackio dispatches a non-blocking job that pulls the user's directory record and writes those fields back. The job handles its own errors, so a misconfigured directory API never blocks a sign-in.

1. In Google Cloud, enable the Admin SDK API on your project and grant the service account domain-wide delegation for the admin.directory.user.readonly scope.

2. Provide the service-account credentials one of two ways:

   • Settings UI — go to Admin → Settings → Integrations, open the Google Workspace card (the directory-sync card, separate from Google Workspace SSO), and fill in the fields below.
   • Environment variables — set the variables below on the server. Environment configuration takes precedence when both are present.

Setting field	Environment variable	Notes
Service-account JSON	GOOGLE_WORKSPACE_SERVICE_ACCOUNT_JSON	Full JSON from the service account's private-key download. Encrypted at rest
Impersonate admin email	GOOGLE_WORKSPACE_IMPERSONATE_ADMIN	A super-admin the service account acts on behalf of (required for domain-wide delegation)
—	GOOGLE_WORKSPACE_ENABLED	Set to true to arm the per-sign-in profile sync

3. Save. From then on, each Google sign-in refreshes the user's directory profile in the background.

Troubleshooting

Symptom	What to do
Google did not return an email address	The response is missing the email scope. Confirm email is enabled in the OAuth consent screen scopes, and that you used the OAuth 2.0 client (not a service account) for the redirect.
Access restricted. Ask your workspace admin to invite you first.	The email's domain isn't on the Allowed email domains list. Add the domain, or have an admin create the user with External collaborator checked.
redirect_uri_mismatch from Google	The registered redirect URI doesn't match what OnTrackio sent. Verify the entry is exactly https://<slug>.app.ontrackio.com/auth/google/callback, uses https://, has no trailing slash, and that each workspace subdomain has its own entry.
Continue with Google doesn't appear on /login	Either Google sign-in is disabled or the client ID is blank. In Admin → Settings → Integrations → Google Workspace SSO, confirm Enable Google sign-in is on and Client ID is filled.
Session expired. Please try again.	The OAuth flow took longer than the session lifetime, or the session cookie didn't survive the round-trip. Retry the sign-in; if it persists, check for a cookie-domain mismatch on your workspace subdomain.

Related

SAML SSOUse Google as a SAML provider to get group-to-role mapping.Read →Microsoft EntraWire up Microsoft Entra ID as an alternative SSO source.Read →Roles and permissionsSee which role JIT-provisioned users get and how to change it.Read →Logging inHow sign-in works across every enabled method.Read →