Set up Google Workspace user sync + Sign in with Google

The Google Workspace integration in SimpleAMS does two things that can be enabled separately:

Directory sync - pull every active user in your domain into SimpleAMS so you can check assets out to real people without typing names manually. Uses a Google service account with domain-wide delegation.
Sign in with Google - your staff log into SimpleAMS with the same Google account they already use for email. Uses a standard OAuth Web Application client.

The two share one Google Cloud project. This guide walks the whole thing top-to-bottom; expect 20-30 minutes the first time.

Prerequisites

You are a Google Workspace super-admin for your domain. Regular admins can't grant domain-wide delegation.
You have a Google Cloud project with billing enabled. A free-tier project is fine - we only read directory data and won't bill.
You have admin access to the SimpleAMS workspace.

Part 1 - Create the Google Cloud project

Go to console.cloud.google.com.
Click the project picker (top-left) → New Project. Name it SimpleAMS Workspace Sync (or whatever you prefer). Pick the right organisation.
Select the new project so it's active.

Part 2 - Enable the Admin SDK API

In Cloud Console go to APIs & Services → Library.
Search for Admin SDK API.
Click it and press Enable.

This is the API that exposes Google Workspace user, group and org-unit data.

Part 3 - Create the service account (directory sync)

In Cloud Console go to IAM & Admin → Service Accounts → Create service account.
Name: simpleams-directory-sync. Description: Read-only directory sync into SimpleAMS.
Click Create and Continue. Skip the optional role grant (we don't need any project-level role).
Click Done.
Open the service account, go to the Keys tab.
Click Add Key → Create new key → JSON. Save the downloaded file safely - this is what SimpleAMS will paste in.
Back on the service account Details tab, expand Show domain-wide delegation and tick Enable Google Workspace Domain-wide Delegation. Save.
Copy the service account's Unique ID (the long numeric string under Details). You'll paste it in the next step.

Part 4 - Grant domain-wide delegation in the Workspace Admin console

Go to admin.google.com as a super-admin.
Navigate to Security → Access and data control → API controls → Manage Domain Wide Delegation.
Click Add new.
Client ID: paste the service account's Unique ID from the previous step.
OAuth scopes: paste this single line (no quotes):
```
https://www.googleapis.com/auth/admin.directory.user.readonly
```
Read-only is sufficient - SimpleAMS only reads, never modifies users.
Click Authorize.

Part 5 - Find your admin email and customer ID

Admin email: any super-admin email in your domain (e.g. admin@acme.com). The service account impersonates this account when calling the Admin SDK; the account itself isn't used to log in.
Customer ID: open admin.google.com → Account → Account settings → Profile. Copy the Customer ID (looks like C0xxxxxxx). Optional - leave it blank and SimpleAMS uses my_customer, which is fine for the vast majority of single-domain accounts.

Part 6 - (Optional but recommended) Create the OAuth client for SSO

Skip this part if you only want directory sync without single sign-on.

Still in Cloud Console: APIs & Services → OAuth consent screen.
Configure it as an Internal consent screen (only your Workspace users can use it). Fill in the app name, user support email and developer email. Save and continue.
Add the scope openid email profile. Save and continue. Submit.
Now: APIs & Services → Credentials → Create Credentials → OAuth client ID.
Application type: Web application. Name: SimpleAMS SSO.
Authorized redirect URIs: SimpleAMS shows the exact URI to paste in the integration screen. It looks like https://<yourworkspace>.simpleams.co.uk/auth/google/callback.
Save. Copy the Client ID and Client secret.

Part 7 - Paste everything into SimpleAMS

Open Settings → Integrations → Google Workspace.
Service account JSON: open the JSON file from Part 3 in a text editor and paste the whole thing into the textarea.
Admin email (to impersonate): paste the super-admin email from Part 5.
Customer ID (optional): paste your C0... ID, or leave blank.
OAuth client ID (for SSO) and OAuth client secret (for SSO): paste from Part 6 if you set up SSO.
Tick Enable this integration.
Click Save.

Part 8 - First sync and verification

Click Sync now. SimpleAMS calls the Admin SDK and creates a SimpleAMS staff row for every active Google Workspace user. Each row is linked back to the Google account by email + Google user id, so re-running doesn't duplicate.
Open Staff → All and confirm the headcount roughly matches your Workspace user count.
If you set up SSO, log out and try the Sign in with Google button on the login screen. The first time you do it, Google asks for consent; subsequent sign-ins are silent.

What gets synced

Name (primary name from Workspace).
Primary email (used as the identity key in SimpleAMS).
Job title and department if set in Workspace.
Active status - suspended Workspace users are deactivated in SimpleAMS on the next sync.

The sync is one-way: changes you make to a staff row in SimpleAMS do NOT push back into Google. If someone gets a new title in Workspace, the next daily sync brings it over.

Troubleshooting

403 Not Authorized on Sync now: The service account doesn't have domain-wide delegation, OR the scope you authorised in Part 4 doesn't match exactly. Re-check the scope - it must be https://www.googleapis.com/auth/admin.directory.user.readonly.
access_denied on the SSO consent screen: Your OAuth consent screen is set to External + Testing. Either switch it to Internal (recommended) or move it to Production.
redirect_uri_mismatch on the SSO sign-in: The Authorized redirect URI in Cloud Console must match the one shown in SimpleAMS exactly, including the workspace subdomain, scheme (https://) and path. Trailing slashes count.
Sync runs but the user list is empty: The admin email you're impersonating isn't a super-admin, OR the Workspace tenant has no active users in the customer's scope. Verify in admin.google.com → Directory → Users.

Security notes

The service account JSON is encrypted at rest in SimpleAMS using the workspace's app key. It's never echoed back in the UI or API.
The OAuth client secret is treated as a credential and encrypted the same way.
Both are scoped to your one Google Cloud project. Rotate them by creating a new key / client in Google Cloud and pasting the new values into SimpleAMS; the old ones can then be deleted in Google Cloud.
You can revoke directory access at any time by removing the delegation row in the Workspace Admin console - sync will fail at the next attempt and SimpleAMS will surface a clear error.

That's everything. If you hit something this guide doesn't cover, email hello@simpleams.co.uk with the exact error message and we'll come back within 48 hours.