IAM Policies and Bindings

IAM policies are the mechanism by which roles are granted to members on resources. Understanding how policies work — including inheritance, the additive model, and deny policies — is essential for designing secure access control.

---

Policy Structure

An IAM policy is a JSON document attached to a resource. It contains an array of bindings, each mapping members to a role:

{
  "version": 3,
  "bindings": [
    {
      "role": "roles/storage.objectViewer",
      "members": [
        "user:alice@example.com",
        "group:analysts@example.com"
      ]
    },
    {
      "role": "roles/storage.admin",
      "members": [
        "serviceAccount:storage-sa@my-project.iam.gserviceaccount.com"
      ],
      "condition": {
        "title": "Expires in 90 days",
        "expression": "request.time < timestamp('2025-06-01T00:00:00Z')"
      }
    }
  ],
  "etag": "BwXmq..."
}

Policy Fields

Field	Purpose
version	Policy schema version (use 3 for conditions support)
bindings	Array of role-to-member mappings
role	The IAM role being granted
members	Array of identities receiving the role
condition	Optional — restricts when the binding is active
etag	Concurrency control — prevents overwriting concurrent changes

---

Managing Policies with gcloud

Viewing a Policy

# View project IAM policy
gcloud projects get-iam-policy my-project

# JSON format
gcloud projects get-iam-policy my-project --format=json > policy.json

# View policy for a specific resource
gcloud storage buckets get-iam-policy gs://my-bucket
gcloud compute instances get-iam-policy my-vm --zone=europe-west2-a

Adding a Binding

# Grant a role to a user at the project level
gcloud projects add-iam-policy-binding my-project \
  --member="user:alice@example.com" \
  --role="roles/storage.objectViewer"

# Grant a role to a group on a specific bucket
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="group:analysts@example.com" \
  --role="roles/storage.objectViewer"

# Grant a role to a service account
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:my-sa@my-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Removing a Binding

gcloud projects remove-iam-policy-binding my-project \
  --member="user:alice@example.com" \
  --role="roles/storage.objectViewer"

Set vs Add

Method	Behaviour	Risk
add-iam-policy-binding	Adds a single binding; preserves existing bindings	Low — additive
set-iam-policy	Replaces the ENTIRE policy with a new one	High — can delete existing bindings

Always prefer add-iam-policy-binding and remove-iam-policy-binding. Use set-iam-policy only for bulk changes with proper etag handling.

---

Policy Inheritance

Policies are inherited down the resource hierarchy:

Organisation
  → Policy: roles/viewer to group:all-staff@co.com
  │
  ├── Folder: Engineering
  │   → Policy: roles/compute.admin to group:engineers@co.com
  │   │
  │   └── Project: eng-prod
  │       → Policy: roles/cloudsql.admin to user:dba@co.com
  │       │
  │       Result on eng-prod:
  │       - all-staff@co.com has roles/viewer (inherited from org)
  │       - engineers@co.com has roles/compute.admin (inherited from folder)
  │       - dba@co.com has roles/cloudsql.admin (set directly)

Inheritance Rules