--- cuppy_hub: gcp cuppy_path: reference/identity/predefined-roles-and-permissions.md cuppy_section: docs cuppy_doc: BCVT-66E9 cuppy_doc_uuid: 053ea1e7-9883-4a6f-9e71-e86cfbe73c52 cuppy_permalink: https://cuppy.io/gcp/d/BCVT-66E9 cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/gcp/docs/reference/identity/predefined-roles-and-permissions cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: a4c0658ea1d17694670bc091c4a315da1472a606c07527f108717014ee6a6839 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # 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/.` | `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//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 `` `` at `.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`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 91 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/gcp/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.