Gen3 Admin Google Sso Setup Runbook

Google SSO Setup Runbook (Control Panel + Tenant App)

Product: GT Edge AI (GT AI OS 3.0)
Identity provider: Google OAuth / OpenID Connect
Scope: Control Panel admin login and tenant workspace login
MFA policy: No GT two-factor step after SSO (Require GT two-factor after SSO stays unchecked)

This runbook is written for first-time operators. Replace example hostnames with the URLs shown on your deployment’s SSO Providers → Auth runtime tab.

---

Before you start

What you need

Item	Why
Super Admin (or write-capable) Control Panel login	Configure SSO providers
Google Cloud project with billing enabled (or Workspace admin access)	Create OAuth client
Your Control Panel public URL	Example: https://ctp.example.com
Your tenant app public URL	Example: https://gt.example.com
Test Google accounts whose email matches GT user records	SSO links by verified email

Important GT Edge AI rules

1. Two redirect URIs in Google. Control Panel and tenant app use different callback URLs. Register both in Google Cloud Console.
2. Accounts must exist first (recommended mode: Existing account by email). Create Control Panel operator accounts and tenant accounts in Users before testing SSO.
3. No MFA after SSO for this runbook: leave Require GT two-factor after SSO unchecked. Password login still honors each user’s local MFA setting; SSO does not add a GT MFA prompt unless you turn that checkbox on.
4. Protect real client secrets. Google shows the OAuth client secret only once; copy it immediately into GT. Use fake values in training screenshots; redact real secrets before sharing docs externally.

Copy these URLs from GT (do not guess)

1. Sign in to the Control Panel.
2. Open SSO Providers (/dashboard/sso).
3. Select the Auth runtime tab.
4. Copy and save:
   • Control Panel upstream OIDC callback
   • Tenant upstream OIDC callback
   • Control Panel public URL
   • Tenant app public URL

Example shape (your hostnames will differ):

Control Panel callback:  https://ctp.example.com/api/control-panel/oidc/upstream/callback
Tenant callback:         https://gt.example.com/api/tenant/auth/broker/upstream/callback

---

Step 1 — Create matching GT user accounts

SSO in this runbook uses Existing account by email: Google must return a verified email that already exists in GT.

1A. Control Panel operator test account

1. Open Users in the Control Panel.
2. Select Control Panel accounts.
3. Click Add User.
4. Enter the Google email you will test with (for example admin@yourcompany.com).
5. Assign a role (for example Super Admin or Environment Admin).
6. Set status to Active and save.

1B. Tenant workspace test account

1. Still on Users, select Tenant accounts.
2. Click Add User.
3. Enter the Google email for tenant testing (can be the same or a different mailbox).
4. Assign a tenant role (for example Tenant User).
5. Save.

---

Step 2 — Confirm Google Auth Platform audience (one-time)

Google now manages OAuth under Google Auth Platform in Cloud Console. Before creating a client, confirm your project’s audience policy fits your deployment.

1. Open Google Cloud Console and select your project (for example GT AI OS Development).
2. In the left menu under Google Auth Platform, open Audience (and Branding if you need app name/support email changes).
3. Choose the access model that matches your rollout:
   • Internal — only users in your Google Workspace organization (simplest for company-only access).
   • External — any Google account; add Test users until the app is published for production.
4. Ensure standard OIDC scopes are allowed: openid, email, profile.

If your project already shows “OAuth access is restricted to the users within your organization” when you create a client, the audience is already Internal — you can skip straight to Step 3.

---

Step 3 — Create the Google OAuth client

1. Open Google Auth Platform → Clients in your project.
2. Click + Create client.

3. On Create OAuth client ID, set Application type to Web application.

4. Enter a Name you will recognize later (for example GT Edge AI SSO or your deployment hostname). This name is for console identification only; end users do not see it.

5. Under Authorized redirect URIs, click + Add URI twice and paste both URLs from GT Auth runtime (Step “Before you start”):

   • Control Panel upstream OIDC callback
   • Tenant upstream OIDC callback

   The screenshot below uses example-url.com as a placeholder. Replace both URIs with your real Control Panel and tenant hostnames from GT — character-for-character, no typos.

6. Authorized JavaScript origins are optional for this GT broker flow; redirect URIs are the critical field.
7. Click Create.
8. In the OAuth client created dialog, copy Client ID and Client secret immediately. Google shows the secret only once. Paste them into the GT Add SSO provider form in Step 4.

Optional: restrict to one Google Workspace domain

If all users are on one Workspace domain (for example yourcompany.com), you can enforce that later in GT using Google hosted domain (hd) on the SSO provider form. You do not need a separate Google client for that.

---

Step 4 — Add the Google provider in GT Edge AI

1. Control Panel → SSO Providers.
2. Under Preset starters, click Google OIDC (or Load preset on the Google card).

3. The editor opens with a Setup runbook banner. Confirm the Copy from GT into Google section lists your callback URLs (same values as Step 3).
4. Paste from Google into GT:
   • Client ID → Client ID
   • Client secret → Client secret
5. Confirm preset defaults (normally correct for Google):

Field	Value
Display name	Google
Protocol	OIDC
Issuer	https://accounts.google.com
Discovery URL	https://accounts.google.com/.well-known/openid-configuration
Scopes	openid profile email
Account linking	Verified email
Browser sign-in mode	Existing account by email
Required claim key	email_verified
Required claim value	true

6. Login surfaces — check both:
   • ☑ Show on Control Panel login
   • ☑ Show on tenant login
7. MFA — leave unchecked:
   • ☐ Require GT two-factor after SSO
8. Enabled — check ☑ Enabled.
9. Click Save.

Optional domain lockdown

• Google hosted domain (hd): enter your Workspace domain (for example yourcompany.com) to hint Google’s account picker.
• Allowed email domains: comma-separated list of domains GT will accept (for example yourcompany.com).

---

Step 5 — Validate the provider

1. On SSO Providers → Providers, find your Google row.
2. Click Validate.
3. Confirm Last validation result shows OK (discovery/JWKS checks pass).

If validation fails, re-check Client ID/secret, discovery URL, and network egress from the cluster to accounts.google.com.

---

Step 6 — Test Control Panel SSO

1. Open a private/incognito browser window.
2. Go to your Control Panel login URL (for example https://ctp.example.com/login).
3. Click the Google sign-in card.
4. Choose the Google account whose email matches the Control Panel accounts user from Step 1A.
5. After consent, you should land in the Control Panel dashboard without a GT /login/2fa prompt.

---

Step 7 — Test tenant app SSO

1. Open a new private/incognito window.
2. Go to your tenant app login URL (for example https://gt.example.com/login).
3. Click the Google sign-in card.
4. Sign in with the Google account that matches the Tenant accounts user from Step 1B.
5. You should reach tenant workspace content (for example Agents) without a GT MFA step.

---

Troubleshooting

Symptom	Likely cause	Fix
redirect_uri_mismatch from Google	Callback URL typo or missing URI in Google client	Paste exact URLs from Auth runtime; no trailing slash differences
Google login works but GT rejects user	Email not in GT or not verified	Create user with same email; confirm email_verified=true claim
Google button missing on login	Provider disabled or surface hidden	Enable provider; check Show on Control Panel login / Show on tenant login
GT MFA prompt after SSO	Require GT two-factor after SSO enabled	Edit provider; uncheck that box
Access blocked: app not verified (External consent)	Test user not listed	Add account under OAuth consent Test users
Tenant SSO fails, CP works	Only one redirect URI in Google	Add tenant upstream callback URI

---

Quick reference — values to register in Google

Google field	GT source
Authorized redirect URI #1	Control Panel upstream OIDC callback (Auth runtime)
Authorized redirect URI #2	Tenant upstream OIDC callback (Auth runtime)
OAuth scopes	openid, email, profile (via consent screen)

Quick reference — values to paste into GT

GT field	Google source
Client ID	OAuth client Client ID
Client secret	OAuth client Client secret

---

Related pages

• SSO Providers
• Users
• Access Logs