How domain-wide delegation replaces per-mailbox credentials

If app passwords are unreachable by automation, something else has to produce a working sending credential. Domain-wide delegation is that something. It is a Google Workspace mechanism that lets a single service account act as any user in a Workspace, without that user ever signing in, consenting, or existing as anything other than a row in the directory.

It is also a genuinely large amount of trust to hand to one key, and this guide says so where it matters.

What it is

A service account is a non-human identity with its own key pair. Ordinarily it can only touch resources it has been granted directly. Domain-wide delegation changes that: a Workspace administrator authorises the service account’s client ID for a specific list of OAuth scopes, and from then on the service account can assert “I am this user” for any user in that Workspace, within those scopes.

The assertion is signed with the service account’s private key and exchanged at Google’s token endpoint for a short-lived access token scoped to that user. There is no consent screen, because the consent already happened once, at the Workspace level, when the administrator authorised the client ID.

The objection that matters

The first reasonable reaction to “a Google Cloud service account” is: if every new Workspace needs a manual Google Cloud change, this does not scale, and you have just moved the bottleneck.

That objection is correct in general. It does not apply here, and the reason is worth being precise about: there is one service account, not one per Workspace. It lives in Infrabox’s own Cloud project. Each Workspace merely authorises that same client ID. Nothing is created per Workspace, and nothing is created per customer.

The only recurring step is the third, and it is automated by driving the Admin Console — Security, API Controls, Domain-wide Delegation — because Google exposes no API for that surface. Everything below it is a plain HTTPS call.

Authorising a Workspace, carefully

Two details in that automation are easy to get wrong and unpleasant to debug.

It has to be idempotent, in the right direction

Re-submitting a client ID that is already authorised does not add to the grant — it replaces it. Submit a shorter scope list on a Workspace that was already working and you have silently narrowed its permissions, and nothing will fail until the next mailbox tries to send. So an already-authorised client ID is left untouched rather than refreshed, and success is confirmed by re-reading the authorisation table, never by trusting that the click landed.

The console is localised, and the button is not spelled one way

The confirm button in the delegation dialog reads AUTHORISE on a console running en-GB and AUTHORIZE on en-US. A selector matching only the US spelling works on some Workspace accounts and not others, which is the worst kind of failure: intermittent, environment-dependent, and invisible until you have a fleet.

Scopes are the blast radius

Delegation is unrestricted impersonation within whatever is granted. There is no per-user restriction, no approval step, no audit prompt. The service account can become any user in the Workspace for any scope on the list. That means the scope list is not a configuration detail — it is the security boundary, and every extra entry widens what a leaked key could do.

Infrabox authorises four, deliberately: sending and reading Gmail for the mailbox, and the directory access needed to create users and attach domains. Nothing about calendars, nothing about Drive, nothing about the wider Workspace.

Minting a credential, and why nothing is stored

When a mailbox needs to send, the service account asserts the mailbox user’s identity and receives a short-lived access token. That token is used and discarded.

There is deliberately no refresh token and no stored per-mailbox secret. With delegation there is nothing to refresh — a new token can always be minted from the service-account key — so persisting a long-lived per-mailbox credential would be pure liability with no corresponding benefit. One key exists, it is encrypted at rest, and it is the only thing that has to be protected.

This is a real difference from the app-password model, where every mailbox produces its own long-lived secret that has to be stored somewhere, shown to someone, and revoked individually if it leaks.

The step verifies, it does not assume

A token that mints successfully can still be useless, and this is not hypothetical. During the work that built this, the first live run produced a perfectly valid access token, and Gmail answered 403 — because the Gmail API had never been enabled on the Cloud project. The credential was real. It just could not do anything.

So the sending-credential step in the provisioning pipeline does not stop at minting. It calls Gmail with the token and checks that the profile that comes back belongs to the mailbox it asked for — a mismatch would mean holding a working credential for the wrong user, which is worse than holding none.

Failures are classified, because they need different people

unauthorized_client   permanent — this Workspace has not authorised the
                      client ID. Fix: run the delegation authoriser on it.
invalid_grant         permanent — the user may not exist, or the key may
                      have been revoked.
429 / 5xx / network   transient — retry.

The distinction is operational, not cosmetic. A permanent error means something is misconfigured and retrying forever will never help; a transient one means the opposite. Collapsing the two into a generic “auth failed” is how a one-line fix turns into a day of looking at the wrong thing.

What is still awkward about this

• Each new Workspace account has to be authorised. It is automated, but it is a step, and forgetting it produces unauthorized_client on every mailbox in that account at once.
• One key protects everything. The concentration that makes this scale is the same concentration that makes the key catastrophic to lose. It is encrypted at rest and stored outside the deployment, so it can be rotated without shipping a release — but the exposure is real and worth naming.
• Enabling it required lifting an org policy that Google sets by default specifically to stop service-account keys existing. That default is good advice for most projects. Choosing to override it is a deliberate trade, not an oversight.