Skip to content

Commit 7d5641d

Browse files
authored
feat(credentials): keyless Google Workspace domain-wide delegation via IAM signJwt (#9933)
* feat(credentials): domain-wide delegation for keyless Google credentials A keyless (workload identity federation) google-service-account credential can now opt into domain-wide delegation with an optional `delegation` ({ user, services }) in its keyless configuration. Runs for a delegated Workspace service (Gmail, Drive, Docs, Sheets, Calendar) exchange Sim's token at STS, have IAM signJwt the JWT-bearer assertion for the service account with sub set to the delegated user, and exchange it at oauth2.googleapis.com/token. The credential acts only as its own user: a different Impersonated Account is refused before Google is contacted. Saving a delegated credential mints a delegated token per service and makes one cheap read as the user; the stray-subject pin probe also checks signJwt. Tokens are cached per credential, secret version, delegated user, and scopes. Credentials saved without delegation store exactly the same secret and resolve exactly as before; BigQuery and Vertex AI keep the service account token path. * feat(integrations): offer keyless domain-wide delegation in the Google service account dialog The Gmail, Google Drive, Google Docs, Google Sheets, and Google Calendar integrations now offer the keyless (Workload Identity Federation) mode, with a Domain-wide delegation picker preselecting the service the dialog was opened for and a required Workspace user. The dialog lists the scopes to authorize in the Admin console, and its gcloud commands grant roles/iam.serviceAccountTokenCreator (which includes signJwt) instead of roles/iam.workloadIdentityUser when delegation is on. Other Workspace services keep the JSON key only. * docs(integrations): document keyless Google domain-wide delegation * fix(credentials): mint delegated keyless tokens only for authorized scopes A keyless credential with domain-wide delegation now signs an assertion only for the scopes its delegated services authorize, and refuses any other scope before contacting Google (a Gmail read-only connector, the admin directory scopes, cloud-platform). A requested read-only scope is minted as the authorized read-write scope that covers it, so the Drive file picker works for a credential delegated for Drive, Docs, or Sheets. The delegated assertion is exchanged through the same transport a JSON key uses (bounded read, retries on 429 and 5xx within a budget), sharing its list of diagnostic error codes. Saving checks Drive, Docs, and Sheets, which share scopes and a read, once, and the pin probe signs for every delegated scope. A stored secret naming a delegated service a later release adds stays readable: that service authorizes nothing here, and Google Cloud tokens and the known services keep working. An unreadable secret fails in the shared service-account codes. * fix(integrations): keep a keyless Google credential's delegation on reconnect Preparing a reconnect of a keyless Google credential now returns its stored Workspace user and delegated services to the credential's admin (neither is secret), and the dialog opens on them, adding the service it was opened for. Reconnecting no longer silently drops delegation. A dialog opened for a delegable service requires that service to be delegated. * docs(integrations): note keyless delegation scope limits and least-privilege role * fix(credentials): serve the Gmail label picker and name the right fix for keyless delegation A read-only Gmail request is minted as the authorized gmail.modify scope, an Impersonated Account is compared trimmed, and each documented token-endpoint refusal gets its own copy instead of always pointing at the Admin console. The stored secret is parsed in one place and the save-time read shares the POST helper's redirect and timeout guards. * refactor(credentials): read reconnect fields through the per-provider map The prepare use case no longer branches on the Google provider: each provider's reader returns everything a reconnect reopens on. The dialog takes the stored delegation type from the contract, and one helper says which services a keyless Google credential serves. * docs(integrations): describe scope-level keyless delegation and new refusal messages * fix(integrations): offer Gmail keyless delegation from the Integrations page and chat card Both entry points pass the OAuth provider id (google-email) where the dialog compared against service ids (gmail), so Gmail never offered keyless mode there and a keyless reconnect from chat was refused. The shared helpers and the dialog now map either id through googleDelegationServiceFor. * fix(credentials): mint calendar for the Calendar connector's delegated calendar.events.readonly The Calendar connector requests calendar.events.readonly, whose read-write sibling calendar.events is not what a Calendar delegation authorizes, so every keyless delegated Calendar connector token was refused. Map it to calendar, the authorized scope Google documents as covering it. * docs(integrations): note the Calendar connector's read-only events scope is served keylessly
1 parent 0d77c23 commit 7d5641d

17 files changed

Lines changed: 1684 additions & 173 deletions

‎apps/docs/content/docs/integrations/google-service-account.mdx‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Google service accounts can access shared resources directly or impersonate a Go
1111

1212
For example, you could build a workflow that iterates through a list of employees, impersonates each one to read their Google Docs, and uploads the contents to a shared knowledge base — all without requiring any of those users to sign in.
1313

14-
For Google Cloud APIs such as BigQuery and Vertex AI, you can skip the JSON key entirely: see [Keyless Google Cloud access](#keyless-google-cloud-access).
14+
For Google Cloud APIs such as BigQuery and Vertex AI, and for Gmail, Drive, Docs, Sheets, and Calendar through domain-wide delegation, you can skip the JSON key entirely: see [Keyless Google Cloud access](#keyless-google-cloud-access) and [Keyless domain-wide delegation](#keyless-domain-wide-delegation).
1515

1616
## Prerequisites
1717

@@ -180,7 +180,7 @@ A credential can serve multiple supported Google services when their APIs and sc
180180
A Google service account credential can also be **keyless**: Sim stores no key. Instead, your Google Cloud project trusts Sim through [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers). On each run, Sim signs a short-lived token for this credential's own subject, exchanges it at Google's Security Token Service for a federated token, and uses that to impersonate your service account. The service account's IAM roles decide what workflows can do, exactly as with a JSON key.
181181

182182
<Callout type="info">
183-
Keyless credentials work with Google Cloud APIs that the service account calls as itself: **BigQuery**, and **Vertex AI** in every block that runs a Vertex model (pick the credential in its **Google Cloud Account** field). They can't use domain-wide delegation, so Gmail, Drive, Sheets, Calendar, and other Google Workspace blocks don't offer them, and a keyless credential refuses an **Impersonated Account**. Use a JSON key for those.
183+
Keyless credentials work with Google Cloud APIs that the service account calls as itself: **BigQuery**, and **Vertex AI** in every block that runs a Vertex model (pick the credential in its **Google Cloud Account** field). With [keyless domain-wide delegation](#keyless-domain-wide-delegation) they also work with **Gmail**, **Google Drive**, **Google Docs**, **Google Sheets**, and **Google Calendar**, acting as one Workspace user. Other Google Workspace blocks need a JSON key.
184184
</Callout>
185185

186186
<Steps>
@@ -233,12 +233,46 @@ Self-hosted deployments need `WORKLOAD_IDENTITY_SIGNING_KEY` set and an `https`
233233

234234
### From the API or CLI [#keyless-api-cli]
235235

236-
Run `sim credentials keyless-subject google-service-account`, trust the printed subject as above, then add `projectNumber`, `poolId`, `providerId`, and `serviceAccountEmail` to its `keylessConfig` and pass it to `sim credentials create google-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it. As in the dialog, keyless works only for Google Cloud services such as BigQuery and Vertex AI, not Google Workspace blocks.
236+
Run `sim credentials keyless-subject google-service-account`, trust the printed subject as above, then add `projectNumber`, `poolId`, `providerId`, and `serviceAccountEmail` to its `keylessConfig` and pass it to `sim credentials create google-service-account`. See [the CLI credentials reference](/cli/credentials) for the full two-step example; the proof expires after 24 hours and works only for the user who requested it. For domain-wide delegation, also add `"delegation": {"user": "alice@yourcompany.com", "services": ["gmail", "google-drive"]}`, listing any of `gmail`, `google-drive`, `google-docs`, `google-sheets`, and `google-calendar`.
237+
238+
### Keyless domain-wide delegation [#keyless-domain-wide-delegation]
239+
240+
A keyless credential can also act as one Google Workspace user in Gmail, Google Drive, Google Docs, Google Sheets, and Google Calendar, without a JSON key. Google's [domain-wide delegation guidance](https://knowledge.workspace.google.com/admin/apps/domain-wide-delegation-best-practices) recommends this: on each run, Sim exchanges its token at STS as above, then asks the IAM Service Account Credentials API to [sign](https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signJwt) the same delegation assertion a JSON key would sign, with your user as its subject, and exchanges it at Google's OAuth token endpoint.
241+
242+
<Steps>
243+
<Step>
244+
Set up the keyless credential as above, from the Gmail, Google Drive, Google Docs, Google Sheets, or Google Calendar integration. Under **Domain-wide delegation**, choose the services the credential may use, and enter the **Workspace user** it acts as.
245+
</Step>
246+
<Step>
247+
Grant the subject `roles/iam.serviceAccountTokenCreator` on the service account instead of `roles/iam.workloadIdentityUser`; the setup commands do this when delegation is on. Signing needs the `iam.serviceAccounts.signJwt` permission, which Service Account Token Creator includes and Workload Identity User does not. Token Creator also grants permissions Sim doesn't use, such as `iam.serviceAccounts.signBlob`; for least privilege, grant a [custom role](https://cloud.google.com/iam/docs/creating-custom-roles) with just `iam.serviceAccounts.signJwt` and `iam.serviceAccounts.getAccessToken` (the second keeps BigQuery and Vertex AI working with the same credential).
248+
</Step>
249+
<Step>
250+
In the Google Cloud console, enable each service's API (see the [scopes reference](#scopes-reference)) in the project that owns the service account, and copy the service account's numeric **Unique ID** (its OAuth 2 client ID).
251+
</Step>
252+
<Step>
253+
Have a Google Workspace super administrator authorize that client ID in the Admin console under **Security** → **Access and data control** → **API controls** → **Manage Domain Wide Delegation**, for the scopes the dialog lists under **Scopes to authorize**.
254+
</Step>
255+
<Step>
256+
Save in Sim. For each service, Sim signs in as the Workspace user and makes one read (the Gmail profile, Drive's account details, or the first calendar in the calendar list), so a missing role or authorization, or a disabled Gmail, Drive, or Calendar API, shows up now rather than in a run. Google Docs and Google Sheets use Drive's scopes and are checked through the Drive API only: enable the Google Docs API and Google Sheets API yourself, since a disabled one shows up only in a run.
257+
</Step>
258+
</Steps>
259+
260+
<Callout type="warn">
261+
A keyless credential acts only as the Workspace user you entered. A workflow that sets a different **Impersonated Account** is refused; create one credential per user. To add a service or change the user, reconnect the credential and authorize any new scopes first; reconnecting opens on the credential's current user and services.
262+
</Callout>
237263

238264
### Troubleshooting keyless access
239265

240266
- **"Google Cloud refused Sim's token for this workload identity provider":** the project number, pool ID, or provider ID doesn't match; the provider is disabled, has allowed audiences set, or uses a different issuer; or its attribute condition doesn't allow this credential's subject.
241267
- **"Google Cloud could not fetch the signing keys from Sim's issuer":** the issuer isn't reachable over public HTTPS (self-hosted deployments).
242268
- **"The service account … does not let this credential impersonate it":** run the `add-iam-policy-binding` command with the exact member shown, and enable the IAM Service Account Credentials API.
243269
- **"This service account also trusts other Sim credentials":** remove any `principalSet` binding for the pool from the service account and keep the attribute condition.
244-
- **A block fails with "This credential cannot be used here":** the block is a Google Workspace block or sets an **Impersonated Account**. Use a JSON key credential for it.
270+
- **"… does not let this credential sign for it, which domain-wide delegation needs":** grant `roles/iam.serviceAccountTokenCreator` on the service account to the exact `principal://…/subject/SUBJECT` member, and enable the IAM Service Account Credentials API.
271+
- **"Google Workspace has not authorized this service account's domain-wide delegation":** authorize the service account's client ID for every scope the dialog lists in the Admin console. New authorizations can take a while to apply.
272+
- **"Your Google Workspace admin policies block one or more of these scopes":** a Workspace administrator must allow the service account's client ID under **API controls**, third-party app access.
273+
- **"Google reports the service account … is disabled" (or "was deleted"):** enable the service account in Google Cloud under **IAM & Admin > Service Accounts**, or restore a deleted one within 30 days.
274+
- **"Google refused to sign in as …":** the address isn't an active user in your Workspace domain.
275+
- **"… but the Gmail API refused the request" (or Drive, Calendar):** enable that API in the project that owns the service account, and check the user has the service.
276+
- **A block fails with "This credential cannot be used here":** the block needs scopes the credential's delegation doesn't authorize (or it isn't BigQuery or Vertex AI), or it sets an **Impersonated Account** other than the credential's Workspace user. Reconnect the credential with that block's service, or use a JSON key.
277+
278+
A keyless credential is used only for the scopes listed under **Scopes to authorize**, and Sim refuses anything else before contacting Google. Like Google, Sim authorizes by scope, not by block: Drive, Docs, and Sheets share those scopes, so a credential delegated for any of them also serves the other two and their file pickers, which ask for read-only Drive access that the authorized `drive` scope covers. Read-only Gmail access, which the Gmail label picker and knowledge base connector ask for, is served with the authorized `gmail.modify` scope, and the Google Calendar knowledge base connector's read-only events access with the authorized `calendar` scope. Knowledge base connectors that need other scopes, such as the admin directory scopes, need a JSON key.

‎apps/sim/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal/connect-service-account-modal.tsx‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@ import {
2727
getClientCredentialAccountDescriptor,
2828
} from '@/lib/credentials/client-credential-accounts/descriptors'
2929
import {
30-
GOOGLE_KEYLESS_SERVICES,
30+
googleDelegationServiceFor,
3131
googleKeylessOffer,
32+
isGoogleKeylessService,
3233
} from '@/lib/credentials/google-workload-identity'
3334
import type { ServiceAccountSecretFields } from '@/lib/credentials/service-account-secret'
3435
import {
@@ -54,7 +55,8 @@ import { ClientCredentialsFields } from '@/app/workspace/[workspaceId]/integrati
5455
import { DatabricksAccountModal } from '@/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal/databricks-account-modal'
5556
import {
5657
buildGoogleKeylessConfig,
57-
EMPTY_GOOGLE_KEYLESS_INPUT,
58+
emptyGoogleKeylessInput,
59+
GOOGLE_DELEGATION_SERVICE_NAMES,
5860
GoogleKeylessFields,
5961
type GoogleKeylessInput,
6062
isGoogleKeylessInputComplete,
@@ -180,8 +182,9 @@ interface ConnectServiceAccountModalProps {
180182
/** Existing description, used to seed reconnect-capable modals. */
181183
credentialDescription?: string
182184
/**
183-
* The OAuth service the dialog was opened for (`google-bigquery`). A Google service account
184-
* offers keyless setup only for a Google Cloud service.
185+
* The OAuth service or provider id the dialog was opened for (`google-bigquery`, `gmail` or
186+
* `google-email`). A Google service account offers keyless setup only for a Google Cloud
187+
* service or a Workspace service it can delegate.
185188
*/
186189
oauthServiceId?: string
187190
/** Called with the new credential id after a successful create (token-paste providers). */
@@ -643,9 +646,10 @@ type GoogleAuthType = 'json_key' | 'workload_identity'
643646
/**
644647
* Google service-account flow. Accepts the raw JSON key (paste or drag/drop)
645648
* and validates against the shared `serviceAccountJsonSchema` so the same
646-
* shape errors render here as in the server route. For a Google Cloud service
647-
* (or a keyless credential being reconnected) on a deployment that can sign
648-
* workload-identity tokens, it also offers keyless Workload Identity Federation.
649+
* shape errors render here as in the server route. For a Google Cloud service,
650+
* a Workspace service it can delegate (or a keyless credential being
651+
* reconnected) on a deployment that can sign workload-identity tokens, it also
652+
* offers keyless Workload Identity Federation.
649653
*/
650654
function GoogleServiceAccountModal(props: GoogleServiceAccountModalProps) {
651655
if (!props.open) return null
@@ -670,13 +674,14 @@ function GoogleServiceAccountModalForm({
670674
oauthServiceId,
671675
onCreated,
672676
}: GoogleServiceAccountModalProps) {
673-
const cloudService = Boolean(oauthServiceId && GOOGLE_KEYLESS_SERVICES.has(oauthServiceId))
677+
const delegableService = googleDelegationServiceFor(oauthServiceId)
678+
const keylessService = Boolean(oauthServiceId && isGoogleKeylessService(oauthServiceId))
674679
const keyless = useKeylessSetup({
675680
provider: 'google',
676681
workspaceId,
677682
organizationId,
678683
credentialId,
679-
enabled: cloudService || Boolean(credentialId),
684+
enabled: keylessService || Boolean(credentialId),
680685
})
681686
const keylessSubmit = useSavedConnectionSubmit({
682687
providerId: GOOGLE_SERVICE_ACCOUNT_PROVIDER_ID,
@@ -696,7 +701,11 @@ function GoogleServiceAccountModalForm({
696701
const authType: GoogleAuthType = offerKeyless
697702
? (selectedAuthType ?? keyless.reconnectAuthType ?? 'json_key')
698703
: 'json_key'
699-
const [keylessInput, setKeylessInput] = useState<GoogleKeylessInput>(EMPTY_GOOGLE_KEYLESS_INPUT)
704+
// Untouched, the form follows the reconnected credential's stored delegation, which
705+
// arrives with the keyless setup the keyless fields wait for.
706+
const [editedKeylessInput, setKeylessInput] = useState<GoogleKeylessInput | null>(null)
707+
const keylessInput =
708+
editedKeylessInput ?? emptyGoogleKeylessInput(oauthServiceId, keyless.reconnectDelegation)
700709
const [jsonInput, setJsonInput] = useState('')
701710
const [uploadedFileName, setUploadedFileName] = useState<string | null>(null)
702711
const [displayName, setDisplayName] = useState(initialDisplayName ?? '')
@@ -791,7 +800,7 @@ function GoogleServiceAccountModalForm({
791800
const isDisabled =
792801
cloudOnly ||
793802
(authType === 'workload_identity'
794-
? isPending || !keyless.ready || !isGoogleKeylessInputComplete(keylessInput)
803+
? isPending || !keyless.ready || !isGoogleKeylessInputComplete(keylessInput, delegableService)
795804
: !jsonInput.trim() || isPending)
796805
const submitError = authType === 'workload_identity' ? keylessSubmit.error : error
797806

@@ -825,7 +834,7 @@ function GoogleServiceAccountModalForm({
825834
required
826835
hint={
827836
authType === 'workload_identity'
828-
? 'No key is stored. Sim signs a short-lived token your workload identity provider trusts, then impersonates the service account. Google Cloud APIs only, without domain-wide delegation.'
837+
? 'No key is stored. Sim signs a short-lived token your workload identity provider trusts, then impersonates the service account: Google Cloud APIs, and Google Workspace services through domain-wide delegation.'
829838
: undefined
830839
}
831840
/>
@@ -844,8 +853,9 @@ function GoogleServiceAccountModalForm({
844853

845854
{cloudOnly && (
846855
<ChipModalDescription>
847-
This keyless credential works only with Google Cloud services (BigQuery, Vertex AI).
848-
Reconnect it from one of those integrations or from the credential’s own page.
856+
This keyless credential works only with Google Cloud services (BigQuery, Vertex AI) and,
857+
through domain-wide delegation, {GOOGLE_DELEGATION_SERVICE_NAMES}. Reconnect it from one
858+
of those integrations or from the credential’s own page.
849859
</ChipModalDescription>
850860
)}
851861

0 commit comments

Comments
 (0)