docs: add optional serviceAccountTokenCreator role for WIF + Data Explorer (GCP)#1568
docs: add optional serviceAccountTokenCreator role for WIF + Data Explorer (GCP)#1568MichaelTansiniSeqera wants to merge 2 commits into
Conversation
…rer on GCP When WIF credentials are used for Data Explorer, Platform has no embedded private key and must call the GCP IAM signBlob API to generate presigned URLs. roles/iam.serviceAccountTokenCreator on the SA itself is required for this to succeed. Without it, file viewing and download fail silently with a signing error. Running pipelines is unaffected. Updates both Cloud and Enterprise Google Cloud Batch docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for seqera-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Switch from self-grant (serviceAccount:SA_EMAIL) to the WIF pool principal (principalSet://...) for the serviceAccountTokenCreator binding. This scopes the permission to federated identities from the pool rather than the SA itself, matching what actually calls signBlob at runtime and making it easier to narrow scope per workspace later. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
||
| ```bash | ||
| gcloud iam service-accounts add-iam-policy-binding SA_EMAIL \ | ||
| --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*" \ |
There was a problem hiding this comment.
Worth mirroring step 5's "all pool identities or a specific workspace" framing here too.
The wildcard principalSet://.../POOL_ID/* grants signing to every identity in the pool, which is fine as a starting point, but customers running production setups will likely want to scope it down to the same workspace-level principal they're using for workloadIdentityUser.
Suggest adding a short note below the gcloud block, e.g.:
As with step 5, you can scope this binding to a specific workspace by replacing
principalSet://.../POOL_ID/*withprincipal://.../POOL_ID/subject/org:{ORG_ID}:wsp:{WORKSPACE_ID}:workflow.
| --role="roles/iam.serviceAccountTokenCreator" | ||
| ``` | ||
|
|
||
| Replace `SA_EMAIL`, `PROJECT_NUMBER`, and `POOL_ID` with your values. Without this role, viewing or downloading file contents in Data Explorer fails with a signing error. Running pipelines is not affected. |
There was a problem hiding this comment.
"Signing error" is hard to grep for. Customers who hit this only see an opaque error ID in the UI and end up searching Grafana for the underlying message. Worth including the exact log phrase so Google searches for the error land here directly:
Without this role, viewing or downloading file contents in Data Explorer fails. The Platform backend logs the underlying error as
SigningException: Failed to sign the provided bytescaused byPermission 'iam.serviceAccounts.signBlob' denied. Running pipelines is not affected.
(Both strings come from upstream Google libraries. SigningException is from com.google.auth.ServiceAccountSigner and the permission-denial wording is GCP IAM's own API error response. They've been stable across recent SDK versions, so pinning the doc to them should be durable.)
| 3. Set the Allowed audiences. If left empty, GCP derives a default audience from the provider resource path in the format `//iam.googleapis.com/projects/{PROJECT}/locations/global/workloadIdentityPools/{POOL}/providers/{PROVIDER}`. If you specify a custom value, it must match exactly what you enter in the Token audience field when creating the Google WIF credential in Seqera. | ||
| 4. Define an attribute mapping and condition. At a minimum set `google.subject=assertion.sub`. This maps the subject claim from Seqera's JWT to GCP's identity space. For more information see [here](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#mappings-and-conditions) | ||
| 5. Grant `roles/iam.workloadIdentityUser` on the service account created above to the Workload Identity Pool principal. This can be set for all pool identities or for a specific workspace. | ||
| 6. If you use the same WIF credential for Data Explorer, grant `roles/iam.serviceAccountTokenCreator` on the service account to the Workload Identity Pool principal: |
jonmarti
left a comment
jonmarti
left a comment
There was a problem hiding this comment.
LGTM. Technical content is accurate and matches the diagnosis we landed on in the Slack thread with the customer that hit this:
- ✅ Correct role:
roles/iam.serviceAccountTokenCreator - ✅ Correct binding shape:
--memberis the WIF principal (not the SA self-grant workaround the customer initially applied) - ✅ Symmetric with the step 5
workloadIdentityUserbinding on the same SA - ✅ Correctly flagged as optional — pipelines work without it; only Data Explorer file content access triggers
signBlob
Only two small suggestions left
2 participants
Summary
roles/iam.serviceAccountTokenCreatoris optional — required only when the same WIF credential is used for Data Explorer file preview/downloadWhy
With a stored SA JSON key, Platform signs presigned URLs locally using the embedded private key. With WIF there is no local private key, so Platform calls the GCP IAM
signBlobAPI instead. That API requiresiam.serviceAccounts.signBlob, which is not included inroles/iam.workloadIdentityUser. Without this role, Data Explorer returns an opaque error code on file open/download.Changes
platform-cloud/docs/compute-envs/google-cloud-batch.mdplatform-enterprise_docs/compute-envs/google-cloud-batch.md🤖 Generated with Claude Code