Predefined roles and permissions — the naming format, worked role names, custom-role limits, service accounts as identity and as resource
How to name the thing you need. The permission format, the predefined-role format with real examples, the two roles that control impersonation, what the service-account identifier looks like, and the custom-role ceilings. Written so an agent holding a permission string can find the role that contains it, and vice versa.
markdownreferencev1BCVT-66E9stage: buildtrust: officialfamily: identityservice: iaminterface: anyrolespermissionspredefined rolescustom rolesbasic rolesservice accountimpersonationroles/iam.serviceAccountTokenCreatorroles/iam.serviceAccountUserroles/iam.workloadIdentityUser
Predefined roles and permissions
1. Two formats, and you will be given one and need the other
| Thing | Format | Real examples |
|---|---|---|
| permission | service.resource.verb | resourcemanager.projects.list, secretmanager.versions.access |
| predefined role | roles/<service>.<roleName> | roles/compute.admin, roles/storage.objectViewer, roles/cloudsql.client |
A refusal names the permission. A grant names the role. The hub's error catalogues
(reference/<family>/errors.md) are indexed by the refusal string, and each row names the role that carries
the permission, which is the lookup that is otherwise a console search.
2. Basic roles
Owner, Editor, Viewer. The roles reference warns they grant broad permissions and recommends granular
predefined alternatives; the IAM overview is blunter and calls them "highly permissive, unsuitable for
production". Never add one to close a permission error — that is coding around a refusal, and it grants
every service, not the one that failed.
3. Custom roles, and a contradiction worth knowing about
The roles reference describes custom roles as organization-scoped. The IAM quotas page counts them both ways — "custom roles per project: 300" and "custom roles per organization: 300" — under its own heading that "Limits cannot be changed". The two pages disagree about where a custom role lives.
The hub's reading: a custom role can be defined at project scope or at organization scope, the quotas page being the more specific of the two, and the 300 ceiling applies at each. Treat the roles reference's wording as the looser summary. Both pages were read 2026-10-21; if this matters to a design, check the create-custom-role page before you rely on either.
4. Service accounts: one object, two jobs
A service account is an account for an application or workload rather than a person. Two facts about it are the source of most confusion:
- as an identity it is a principal, and you grant it roles on other resources;
- as a resource it has its own allow policy, and you grant other principals roles on it.
"Give the pipeline access to the service account" and "give the service account access to the bucket" are therefore two different policy writes on two different objects.
Its identifier is address-shaped: a name, then the project id, then the .iam.gserviceaccount.com suffix —
written in this hub as ` <sa-name> at <project-id>.iam.gserviceaccount.com `, in two spans, because the
platform's address floor refuses a document carrying a complete address. It also carries a separate unique
id assigned at creation; that id, not the address, is what survives a delete-and-recreate, and it is what
IAM bindings resolve to.
The two impersonation roles, which are not interchangeable
| Role | What it lets the holder do |
|---|---|
roles/iam.serviceAccountTokenCreator | mint credentials as the service account (impersonate it) |
roles/iam.serviceAccountUser | attach the service account to a resource it creates (a VM, a Cloud Run service, a job) |
roles/iam.workloadIdentityUser | let an external or Kubernetes identity act as the service account, used by workload identity federation |
A deploy that fails with a permission error naming iam.serviceaccounts.actAs needs the second, not the
first. See guides/identity/fix-permission-denied.md.
5. Keys
The service-account overview states service account keys are "a security risk if not managed correctly" and
tells you to choose "a more secure alternative to service account keys whenever possible", naming three:
attached service accounts, Workload Identity Federation, and gcloud impersonation flags. The fixed
ceiling is 10 keys per service account.
This hub documents the keyless paths only: reference/identity/workload-identity-federation.md,
guides/identity/github-actions-without-keys.md, patterns/github-actions-to-google-cloud-keyless.md.