Google Cloud IAM: Principals, Roles, Policies, and Service Accounts

IAM Access Model

An IAM allow policy binds a principal to a role on a resource. The role contributes permissions, the resource defines scope, and hierarchy inheritance can extend a binding from an organization, folder, or project to descendants.

Human users should normally receive access through groups. Workloads should use dedicated service accounts and short-lived credentials. Basic roles such as Owner and Editor are too broad for routine production access.

IAM Scope

A project-level binding is convenient, but it reaches every supported resource below that project. Prefer a service-level or individual-resource binding when one database, bucket, secret, or service is the true boundary.

Predefined roles are maintained by Google and usually express job functions better than basic roles. Create a custom role only when no predefined role fits, then monitor removed or deprecated permissions as the API evolves.

Principal	Typical identity	Credential direction
Person	Managed user in a group	Interactive sign-in with organizational controls
Google Cloud workload	Attached service account	Platform-issued short-lived token
External workload	Federated principal	Workload identity federation
Google-managed service	Service agent	Managed by the platform; protect its required role

Keyless Workload Identity

A service account is an identity that a workload can act as. Grant it only the roles required by the application, then attach it to Cloud Run, Compute Engine, GKE, or another runtime. Permission to use a service account is separate from permissions held by that account.

Downloaded keys are long-lived secrets that can escape through source control, build logs, backups, and developer machines. Use attached identities, service account impersonation, or federation unless a documented constraint leaves no safer option.

Grant one service account access to one secret

PROJECT_ID=tl-cloud-lab
SA="orders-api@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create orders-api \
  --project="$PROJECT_ID" \
  --display-name="Orders API runtime"

gcloud secrets add-iam-policy-binding db-password \
  --project="$PROJECT_ID" \
  --member="serviceAccount:${SA}" \
  --role="roles/secretmanager.secretAccessor"

The binding is on the secret, not the entire project.
The runtime still needs permission to act as this service account.

Permission Denials

Capture the exact principal, permission, resource name, project, timestamp, and request ID. Then inspect inherited allow bindings, deny policies, principal access boundaries, organization constraints, token age, and service-specific authorization.

Do not test by adding Owner. That destroys the evidence needed to find the missing permission and can conceal an incorrect project or resource path.

Effective Access Evaluation

An IAM decision begins with a principal requesting a permission on a resource. Allow policies bind principals to roles, and roles collect permissions. Policies inherited from folders and the organization can grant access far below their attachment point. Deny policies, principal access boundary policies, IAM Conditions, and organization policy constraints solve different control problems, so an allow binding alone never describes the entire result.

Troubleshoot with the exact principal, permission, full resource name, and request context. Confirm whether the caller is a user, group, service account, service agent, workforce identity, or workload identity. Then inspect direct and inherited policies, conditional expressions, deny rules, service-specific authorization, and impersonation hops. Group membership and policy changes can take time to propagate, so record timestamps before repeatedly editing access.

Grant roles at the narrowest stable scope that supports the job. A project-level role is easier to manage than hundreds of resource bindings but has a wider blast radius. Folder-level grants are appropriate for central teams only when every descendant should inherit them. Basic Owner, Editor, and Viewer roles are usually too broad for application access; prefer predefined roles and create custom roles only when a stable permission set cannot be expressed safely.

Ask which permission is missing, not which broad role makes the error disappear.
Use groups for workforce access and review group ownership.
Test conditional access both inside and outside the allowed context.
Use Policy Troubleshooter and audit logs as evidence, not intuition.

Service Account Boundaries

A service account is both a principal that can receive roles and a resource that other principals may be allowed to impersonate. Those two sides create different attack paths. Restrict what the service account can access, and separately restrict who can attach, impersonate, mint tokens for, or manage that account. The ability to deploy a workload as a powerful service account can be equivalent to possessing its privileges.

Create a single-purpose service account for each workload identity boundary instead of sharing one account across unrelated services. Give it roles on the resources it calls, not broad roles in the project that happens to contain it. Keep the account near the resources it serves when practical, document its owner and purpose, and disable unused accounts before deletion so unexpected dependencies can be detected.

Google-managed service agents perform operations for services and are not interchangeable with application service accounts. Avoid modifying their roles without product-specific guidance. Default service accounts may receive automatic grants in older or permissive setups; inspect them explicitly and prevent automatic broad grants through organization policy where appropriate.

Separate runtime, deployment, migration, and break-glass identities.
Grant token-creation rights only to reviewed callers.
Monitor service-account use from unexpected sources.
Document service agents before changing their inherited access.

Keyless Workload Authentication

Workloads on Google Cloud should normally use the identity attached to their runtime and obtain short-lived credentials through the metadata service or platform integration. External workloads and CI systems should use Workload Identity Federation to exchange an existing OIDC, SAML, X.509, AWS, or Azure identity for Google credentials. This removes long-lived private keys from build variables and rotation inventories.

A federation pool establishes a trust domain, a provider validates external assertions, attribute mappings translate claims, and attribute conditions reject identities outside the intended repository, branch, tenant, account, or environment. Grant either direct resource access to federated principals or allow a tightly scoped set to impersonate a service account. Never grant an entire pool access merely because initial testing is easier.

If a service-account key is temporarily unavoidable, constrain its privileges, store it in an approved secret system, record the consumer, detect exposure, rotate it, and set a removal date. Disabling a suspected key is usually safer than waiting for an investigation to finish. Key age alone is a weak control if copied credentials can remain undetected.

Prefer ambient platform identity over exported credential files.
Validate issuer, audience, subject, and environment claims in federation.
Use separate pools or providers where trust boundaries differ.
Alert on new keys and unexpected token minting.

Access Lifecycle and Evidence

Joiner, mover, and leaver workflows should modify group membership and privileged eligibility, not scatter individual bindings. Time-bound elevation is safer than permanent administration when the work is occasional. For sensitive roles, require approval, ticket context, a short duration, and a post-action review. Emergency access should use a separate monitored path and be tested before an incident.

Cloud Audit Logs answer different questions by log type. Admin Activity records administrative changes and is always written; Data Access records reads and writes but can require explicit configuration and can generate substantial volume. System Event and Policy Denied logs provide other evidence. Centralize required logs in a protected project, control who can disable sinks, and align retention with investigation and compliance needs.

Review access by starting from critical resources and asking which principals can read data, change policy, deploy code, impersonate workloads, or destroy recovery copies. Role recommendations can identify unused permissions, but removal still needs application context and rollback. Test revoked access from a fresh token because an existing credential may remain valid until it expires.

Give every privileged group an owner and review cadence.
Capture policy changes and token activity in protected logs.
Revoke dormant grants and verify the application still works.
Preserve an approved, monitored emergency-access procedure.

Privilege Review Scenario

Review a production deployment path end to end: who can modify source, trigger the build, change the build identity, write the artifact, approve promotion, deploy the service, select its runtime service account, and edit that account's roles. A principal with two individually modest permissions can sometimes combine them into effective administration.

Record toxic combinations and break them through separate projects, identities, approvals, or deny controls. Validate the reduced design by attempting impersonation and deployment from a test principal. Preserve enough audit evidence to attribute the initiating user through every service-account hop.

Review permission combinations, not roles in isolation.
Trace the original actor through impersonation.
Retest after pipeline or service-account changes.

IAM Policy Examples

Debug an Effective IAM Denial

A workload identity can access one secret in development but receives permission denied in production.

Debug an Effective IAM Denial

Constraints: Projects inherit organization policy; conditions and deny policies may override an apparent role grant.
Decision: Inspect principal identity, token audience, allow bindings, conditions, deny policies, and resource hierarchy.
Verification: Policy Troubleshooter explains the decision and the corrected binding grants only the named production secret.
Failure test: Request a second secret and confirm the narrower binding denies it.

Output

Expected evidence: Policy Troubleshooter explains the decision and the corrected binding grants only the named production secret.

This is a worked engineering decision, so the result is operational evidence rather than terminal output.

Before you move on