gcp-iam

For the GitHub Actions caller side of Workload Identity Federation (permissions: id-token: write, google-github-actions/auth setup, the OIDC token shape), see the github-actions-pipelines skill. This skill covers the GCP side: pool provider attribute conditions, service account iam.workloadIdentityUser bindings, impersonation chains.

GCP IAM Inheritance

When to invoke

Symptoms:

• permission denied: <permission> on resource <X> despite the user being "in the right group at the org level."
• iam.serviceAccounts.getAccessToken denied during Workload Identity, ESO sync, or CI/CD.
• A service account can get a resource but not list siblings (or vice versa).
• gcloud projects get-iam-policy <project> shows no binding for the user, but the user can log into the project console.
• Cross-project SA impersonation works for human users via gcloud auth login but fails from a workload.

The trap this prevents: assuming GCP IAM is additive across the hierarchy in all directions. It is — but with caveats around conditional bindings, deny policies, audit-log filtering, and the fact that some permissions only apply at specific resource levels.

The inheritance model (the part that does work)

Organization
  └── Folder(s)
        └── Project(s)
              └── Resource(s)   (Bucket, BQ Dataset, GCE Instance, etc.)

Rule: A role granted at level N applies to N and everything below it. Permissions are added — never subtracted (except by Deny policies, see below).

So roles/storage.admin granted at the folder level grants storage.admin on every project under that folder. This is the "obvious" inheritance and it does work as expected.

Why "group at org" sometimes fails to grant project access

Common reasons users report "I'm in the group but it doesn't work":

1. The group has no IAM binding at any level. Group membership alone grants nothing. The group must appear as a principal in an IAM binding somewhere in the hierarchy.

   # Find every binding that includes a group, project or higher
   gcloud projects get-iam-policy <project> \
     --flatten="bindings[].members" \
     --filter="bindings.members:group:<group-email>" \
     --format="value(bindings.role)"
   
   gcloud organizations get-iam-policy <org-id> \
     --flatten="bindings[].members" \
     --filter="bindings.members:group:<group-email>" \
     --format="value(bindings.role)"