feat(credentials): keyless Google Workspace domain-wide delegation via IAM signJwt

Merged
WA
3d ago
+1684-173

Summary

  • A keyless (Workload Identity Federation) Google service account credential can now use domain-wide delegation for Gmail, Google Drive, Google Docs, Google Sheets and Google Calendar, with no JSON key. The flow is: Sim token → STS → IAM Credentials signJwt (sub = the Workspace user) → jwt-bearer exchange at oauth2.googleapis.com/token.
  • Delegation is an optional, additive delegation: { user, services } in the keyless config. The credential acts only as its stored user. A run that sets a different Impersonated Account is refused before Google is contacted (the comparison ignores case and surrounding spaces).
  • Authorization is by scope, as Google's is. Any scope outside the delegated services' scopes is refused before Google is contacted, so Drive, Docs and Sheets, which share scopes, serve each other. A read-only scope is minted as the authorized scope that covers it: its read-write sibling (drive.readonly → drive, for the Drive picker), or gmail.modify for gmail.readonly (the Gmail label picker and the knowledge base connector).
  • Saving proves the whole chain: one delegated mint per scope set and one cheap read per service as the user. The stray-subject pin probe also checks that signJwt is refused. Token-endpoint refusals get copy for each of Google's documented error codes: Admin-console authorization for unauthorized_client and access_denied, admin policy, a disabled or deleted service account, and neutral copy for anything else.
  • The dialog offers keyless mode for these five services with a service picker and a Workspace user field. It works from every entry point: the block credential selector, the Integrations page and the chat connect card. The first passes a service id (gmail); the other two pass the OAuth provider id (google-email), and both are accepted. It lists the scopes to authorize in the Admin console, and its gcloud commands switch to roles/iam.serviceAccountTokenCreator, because roles/iam.workloadIdentityUser lacks iam.serviceAccounts.signJwt. A reconnect keeps the stored delegation, read through the per-provider reconnect map with no provider branch in the shared use case.
  • Tokens are cached by credential, secret version, delegated user and scopes. The assertion exchange reuses the JSON-key transport (redirect error, bounded read, retry budget).

Product update (if relevant)

Workspace admins can connect Gmail, Drive, Docs, Sheets and Calendar to one Workspace user without creating a service account key, which Google's DWD best practices recommend. Docs: Google service account → keyless domain-wide delegation.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Other: ___________

Testing

  • Unit tests against a fake Google (STS, IAM, token endpoint, Workspace reads). They cover:
    • the save chain and the per-service reads
    • refused roles and grants, and the pin probe
    • refused subject mismatch and scopes, plus scope-level authorization across Drive, Docs and Sheets
    • read-only scope minting (Drive picker, Gmail label picker)
    • the Impersonated Account trim
    • per-code token-refusal copy
    • retry, cache separation, and tolerance of a later release's services
    • the keyless offer and the services the dialog preselects when it is opened by provider id (google-email, from the Integrations page and the chat card)
  • Revert proof: the new tests fail on the pre-fix source.
  • Neighbouring credential, prepare-reconnect, token-resolution and OAuth suites are green. The OpenAPI, CLI and MCP generators are current, and the boundary, client-boundary, utils and comment-hygiene audits pass.
  • Reviewers: focus on backward compatibility. Credentials without delegation store and resolve exactly as before, BigQuery and Vertex AI are unchanged, and an old worker fails closed on a delegated secret. Also check the scope authorization in resolveGoogleWorkloadIdentityToken / delegatedMintScopes.
  • Not yet run against a live Workspace tenant. A staging proof is needed before announcing.

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)