How to configure Google Workspace

Overview

This guide walks you through creating a Google Cloud service account with domain-wide delegation that Dex can use to manage a customer's Google Workspace tenant. At the end you will have four values to paste into the Add tenant dialog:

1. Service account email (e.g., dex@my-project.iam.gserviceaccount.com)
2. Private key (the private_key field from the JSON key file)
3. Admin email (a Google Workspace super admin to impersonate)
4. Primary domain (e.g., customer.com)

The process takes about 10–15 minutes and requires both Google Cloud project owner access and Google Workspace super admin access on the customer's tenant.

Before You Start

You will need:

• A user account with Super Administrator rights on the customer's Google Workspace tenant.
• Access to Google Cloud Console (https://console.cloud.google.com) — either an existing project for this customer or permission to create a new one.
• About 15 minutes.

The service account lives inside a Google Cloud project. You can use an existing project or create a dedicated one. We recommend a dedicated project so it is easy to manage and revoke.

1. Sign in to https://console.cloud.google.com.
2. Click the project picker at the top of the page → New Project.
3. Fill in:
   • Project name: Dex Integration (or any name you prefer).
   • Organization / Location: choose the customer's Google org if applicable.
4. Click Create and wait a few seconds, then select the new project from the project picker.

Dex calls the Google Workspace Admin SDK Directory API. It must be enabled on the project.

1. In the Cloud Console, go to APIs & Services → Library.
2. Search for Admin SDK API.
3. Click it, then click Enable.

1. In the Cloud Console, go to IAM & Admin → Service Accounts.
2. Click + Create Service Account.
3. Fill in:
   • Service account name: dex
   • Service account ID: leave the auto-generated value (e.g., dex).
   • Description: Dex integration service account
4. Click Create and Continue.
5. On the Grant this service account access to project step — leave the roles blank and click Continue. (Dex does not need any Google Cloud IAM roles; all access is granted in Step 5 via domain-wide delegation in Workspace.)
6. On the Grant users access to this service account step — leave blank and click Done.

You should now see your new service account in the list. Copy the email address that looks like:

dex@<your-project-id>.iam.gserviceaccount.com

Paste it into the Dex Add tenant dialog as the Service account email field.

1. In the service accounts list, click your new dex service account.
2. Open the Keys tab.
3. Click Add Key → Create new key.
4. Choose JSON and click Create.
5. A JSON file is downloaded to your machine. Keep it safe — it grants admin-level access and Google does not store the private portion.

Open the downloaded JSON file in a text editor. You will see something like:

{
  "type": "service_account",
  "project_id": "my-project",
  "private_key_id": "abc123…",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ…\n-----END PRIVATE KEY-----\n",
  "client_email": "dex@my-project.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  …
}

From this file you will use two values:

Domain-wide delegation lets the service account impersonate users in the customer's Workspace. This is the step that grants real access — the JSON key alone is not enough.

5a. Copy the service account's Client ID

You need the client_id value from the JSON file (a 21-digit number). You can also find it in Cloud Console → IAM & Admin → Service Accounts → click your service account → Details tab → Unique ID.

5b. Authorize the scopes in Workspace Admin

1. Sign in to the Google Workspace Admin console at https://admin.google.com as a Super Administrator of the customer tenant.
2. Go to Security → Access and data control → API controls.
3. Under Domain-wide delegation, click Manage Domain Wide Delegation.
4. Click Add new.
5. Fill in:
   • Client ID: paste the 21-digit Client ID from Step 5a.
   • OAuth scopes: paste the comma-separated list from the table below — all six scopes.
6. Click Authorize.

Required OAuth scopes

Dex's validator checks every one of these scopes. If any are missing, you will get an INSUFFICIENT_SCOPES error.

Copy-paste form (use this in the OAuth scopes field — comma-separated, no spaces):

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.device.mobile,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.resource.calendar

The service account must impersonate a real Google Workspace super admin when calling the Directory API. This is the Admin email field in the Dex dialog.

1. Sign in to https://admin.google.com.
2. Go to Directory → Users.
3. Find or create a super admin user (Account → Admin roles and privileges → must show Super Admin).
4. Note this user's email address.

Paste this email into the Dex Add tenant dialog as the Admin email field.

The Primary domain is the customer's main verified domain in Workspace (e.g., customer.com, not customer.onmicrosoft.com).

1. In the Workspace Admin console, go to Account → Domains → Manage domains.
2. The row marked Primary is the value you need.

Paste it into the Dex Add tenant dialog as the Primary domain field.

1. Return to the Dex Add tenant dialog.
2. Enter an Organization name (label for your MSP dashboard — does not need to match the Workspace name).
3. Select Google Workspace.
4. Paste the four values:
   • Service account email → from Step 3
   • Private key → the private_key field from the JSON file (Step 4)
   • Admin email → super admin to impersonate (Step 6)
   • Primary domain → customer's main domain (Step 7)
5. Click Add Tenant.

Dex will:

Troubleshooting

Rotating the key later

Service account keys do not expire by default, but you should rotate them periodically per your security policy.

1. In Cloud Console → IAM & Admin → Service Accounts, open the dex service account → Keys tab.
2. Click Add Key → Create new key → JSON to download a new key.
3. In the Dex MSP dashboard, open the tenant and update the Private key field with the new private_key value.
4. Once Dex confirms the new key works, return to the Keys tab and delete the old key.

The service account email, Client ID, and authorized scopes remain unchanged — you only update the private key on both sides.