Gateco connects to Google Workspace or Cloud Identity via the Google Admin SDK using domain-wide delegation (DWD). DWD allows a GCP service account to impersonate a domain super-admin and read users and groups from your directory for identity-aware retrieval. This guide walks through both the GCP Console setup and the Google Admin console authorization needed to enable RAG access control based on your Google Workspace groups.
GCP Cloud Identity integration requires the Growth plan or above. Admin SDK API calls are free within your Google Workspace subscription.
Step 1 — Enable the Admin SDK API
- Open GCP Console → APIs & Services → Library.
- Search for "Admin SDK API" and click Enable.
- The API is called admin.googleapis.com in CLI contexts.
# Alternative: enable via gcloud CLI
gcloud services enable admin.googleapis.com --project=YOUR_PROJECT_IDStep 2 — Create a service account
- Go to IAM & Admin → Service Accounts → Create service account.
- Name: gateco. Click Create and continue.
- Grant the role: roles/iam.serviceAccountTokenCreator (required for DWD token issuance).
- Click Done.
Step 3 — Download the service account key
- Click into the service account you just created.
- Go to Keys → Add key → Create new key → JSON.
- Save the downloaded file securely.
- Convert the JSON key to single-line format for use in environment variables.
python3 -c "import json, sys; print(json.dumps(json.load(open('path/to/key.json'))))"GCP_SERVICE_ACCOUNT_JSON must be valid JSON on a single line. Newlines inside the private_key field must remain as \n escape sequences, not literal newlines. Use the command above to ensure correct formatting.
Step 4 — Enable domain-wide delegation
Back in GCP Console:
- Go to IAM & Admin → Service Accounts and click into your service account.
- Click Edit (pencil icon).
- Check "Enable Google Workspace domain-wide delegation".
- Click Save.
- Note the Unique ID shown on the service account page (a long number, e.g. 103675186029495848977). You will use this in Step 5.
Step 5 — Authorize delegation in Google Admin console
- Open Google Admin console at admin.google.com.
- Navigate to Security → Access and data control → API controls.
- Click Manage domain-wide delegation → Add new.
- Enter the service account Unique ID from Step 4 in the Client ID field.
- Add all three OAuth scopes (comma-separated) from the box below.
- Click Authorize.
https://www.googleapis.com/auth/admin.directory.user.readonly,
https://www.googleapis.com/auth/admin.directory.group.readonly,
https://www.googleapis.com/auth/admin.directory.group.member.readonlyThese three scopes are read-only. Gateco only reads users and groups — it never modifies your directory.
Step 6 — Add credentials to Gateco
- Navigate to Identity Providers → Add provider → GCP Cloud Identity.
- Enter the values from the table below.
- Click Test connection.
- Click Save.
| Field | Value |
|---|---|
Domain | Your Google Workspace primary domain (e.g. yourcompany.com) |
Admin Email | Super-admin email to impersonate (e.g. admin@yourcompany.com) |
Service Account JSON | The single-line JSON from Step 3 |
How Gateco uses your Cloud Identity data
| Cloud Identity field | Gateco principal field | Use in policy conditions |
|---|---|---|
primaryEmail | email | principal.email |
name.givenName + familyName | display_name | Display only |
organizations[0].department | attributes.department | principal.attributes.department |
Group membership | groups array | principal.groups |
Policy conditions reference the group name without the domain (e.g. "engineering", not "engineering@yourcompany.com"). The adapter strips the domain suffix. The department field reads from organizations[0].department — set it under Employee information in the Google Admin console user profile.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
403: Not Authorized to access this resource | DWD not authorized in Google Admin console | Go to admin.google.com → Security → API controls → DWD and verify all three scopes are present for the correct Client ID |
0 users returned after successful connection | GCP_DOMAIN does not match primary Workspace domain | Check Admin console → Account → Account settings → Profile for the correct primary domain |
department attribute empty on synced principals | Department set in wrong profile section | Set department under User profile → Employee information → Department (not under custom attributes) |
GCP_SERVICE_ACCOUNT_JSON is not valid JSON | Private key has literal newlines | Re-run the python3 single-line converter command from Step 3 |