Google Workspace — pilot runbook

Who this is for: School IT admin or SchoolRota tenant owner
Time: about 2–4 hours (depends on whether Google is the directory of record)
What you'll achieve: Staff can sign in with Google (OIDC); roster sync via SCIM where your architecture supports it

Read this first

Google Workspace does not expose a first-class SCIM endpoint to arbitrary apps the way Entra and Okta do. Most schools use one of these patterns:

Pattern	SCIM source	SSO
A — Google primary	Third-party bridge or manual CSV import	Google OIDC
B — Entra/Okta primary	Entra or Okta SCIM	Google or Entra/Okta SSO
C — Pilot only	Manual Admin invites	Google OIDC

This runbook covers Pattern A (Google SSO + best-effort SCIM) and notes where to use Entra/Okta instead.

Prerequisites

Requirement	Notes
SchoolRota tenant owner	Break-glass admin
Google admin	Super Admin in Google Workspace
Google Cloud project	For OAuth client (SSO)
Pilot users	Small test group in Google

Step 0 — Collect SchoolRota values

Sign in as tenant owner → Admin.

Setting	Where to copy
SCIM base URL	Admin → SCIM provisioning
SCIM bearer token	Generate if using SCIM bridge
OIDC redirect URI	https://{host}/api/auth/oidc/callback

---

Part 1 — SSO with Google (OIDC)

This is the primary integration path for Google-first schools.

1.1 Google Cloud OAuth client

1. Google Cloud Console → select or create a project
2. APIs & Services → OAuth consent screen
   • User type: Internal (Workspace only) for a single school
   • App name: SchoolRota
   • Support email: your IT contact
3. Credentials → Create credentials → OAuth client ID
4. Application type: Web application
5. Name: SchoolRota SSO
6. Authorized redirect URIs: https://{host}/api/auth/oidc/callback
7. Create → note Client ID and Client secret

1.2 Save OIDC config in SchoolRota

Admin → Single sign-on (OIDC):

Field	Value
Issuer URL	https://accounts.google.com
Client ID	Google OAuth client ID
Client secret	Google OAuth client secret
Group → role map	JSON (see Part 3)
Active	When ready

Save. Login page shows Sign in with Google.

1.3 First sign-in behaviour

• If the user does not exist yet, SchoolRota creates a user and staff profile on first Google login (JIT provisioning)
• If the user was imported or invited with the same email, Google login links to that account
• Email comes from the email claim (Google always sends this for Workspace users)

---

Part 2 — Roster sync (SCIM options)

Choose the path that matches your school.

Option A — SCIM bridge (Google as directory)

Use a provisioning bridge that speaks SCIM toward SchoolRota, for example:

• A Google Workspace provisioning partner that supports custom SCIM 2.0
• An identity sync tool your trust already uses

Configure the bridge with:

Setting	Value
Endpoint URL	SchoolRota SCIM base URL
Authentication	Bearer token from Admin
User mapping	Primary email → userName; given/family name → name; suspended → active (invert: active = not suspended)

Verify users appear in SchoolRota Admin and audit log shows SCIM events.

Option B — Entra or Okta owns the roster (common)

Many Google Workspace schools still provision staff from Entra ID or Okta (HR / trust standard). In that case:

• Follow the Entra pilot runbook or Okta pilot runbook for SCIM
• Use Google OIDC here only for sign-in, or use Entra/Okta SSO if that is your login standard

Do not configure two SCIM sources into the same SchoolRota tenant.

Option C — Manual roster for pilot

For a short pilot without SCIM:

1. Admin → Invite user for each pilot staff member (same email as their Google account)
2. Enable Google SSO (Part 1)
3. Pilot users sign in with Google instead of the temporary password

Move to SCIM or CSV import before full go-live.

Option D — CSV import

For bulk load without SCIM, use Importing staff, then enable Google SSO for login.

---

Part 3 — Groups and roles

Google OIDC does not include Workspace group membership in the token by default. Role options:

Recommended — Google Groups + manual map (SSO)

1. Create Google Groups: schoolrota-admin@, schoolrota-duty-lead@, etc.
2. Add pilot users to groups for your own administration
3. In SchoolRota Admin, map group names if your IdP emits them in the token (often requires extra Google Cloud / Workspace setup)

Example Admin JSON (when groups appear in claims):

{
  "schoolrota-admin@yourschool.org": "admin",
  "schoolrota-duty-lead@yourschool.org": "duty_lead",
  "schoolrota-staff@yourschool.org": "staff"
}

Alternative — SCIM groups via bridge

If your SCIM bridge syncs Google Groups, use display names containing Admin, Duty Lead, Office, or Viewer for automatic role mapping (same rules as SCIM provisioning).

Alternative — Per-user role at invite

For small pilots, set role when inviting users in Admin; SSO preserves role unless a higher mapped role applies.

---

Part 4 — Pilot test checklist

SSO (required)

• [ ] OAuth consent screen configured (Internal)
• [ ] Redirect URI matches SchoolRota callback exactly
• [ ] Sign in with Google visible on login page
• [ ] Pilot user signs in with @school.org account
• [ ] User lands in portal with correct staff profile
• [ ] Audit log: auth.login_sso

Roster (pick one path)

• [ ] SCIM bridge: test user synced to Admin
  or
• [ ] Manual invite: same email as Google account, Google login works
  or
• [ ] Entra/Okta SCIM: user exists before Google login

Roles

• [ ] User has expected role (via invite, SCIM group, or claim map)
• [ ] Tenant owner break-glass login still works

---

Google-specific troubleshooting

Symptom	Likely cause	Fix
redirect_uri_mismatch	OAuth client URI typo	Must match Admin callback exactly
Access blocked / consent	External user type	Use Internal consent for Workspace
Sign-in works, no user	JIT blocked by email domain	Use Workspace accounts on allowed domain
Wrong role	No groups in token	Use SCIM groups, invite role, or Entra/Okta for roles
Duplicate account	Invited with different email	Use same primary email as Google
SCIM not available	No bridge	Use Entra/Okta SCIM or CSV import

---

Choosing the right architecture

Google Workspace only, need auto-sync?
  → SCIM bridge OR CSV import + Google SSO

Trust standard is Entra/Okta?
  → SCIM from Entra/Okta + Google OR Entra/Okta SSO

Small pilot?
  → Manual invite + Google SSO

Related

• SCIM provisioning
• SSO setup
• Importing staff
• Microsoft Entra pilot runbook
• Okta pilot runbook
• Troubleshooting