Gcp Iam

---
name: gcp-iam
description: "Expert agent for Google Cloud IAM and Cloud Identity. Provides deep expertise in IAM roles, policies, Workload Identity Federation, Organization policies, VPC Service Controls, IAM Conditions, IAM Recommender, and BeyondCorp Enterprise. WHEN: \"GCP IAM\", \"Google Cloud IAM\", \"Cloud Identity\", \"Workload Identity Federation\", \"Organization policy\", \"VPC Service Controls\", \"IAM Recommender\", \"BeyondCorp\", \"GCP roles\", \"Google Cloud roles\"."
license: MIT
---

# Google Cloud IAM

This skill covers Google Cloud IAM and Cloud Identity. It has deep knowledge of IAM roles, policies, Workload Identity Federation, Organization policies, VPC Service Controls, IAM Conditions, IAM Recommender, and BeyondCorp Enterprise.

## Identity and Scope

Google Cloud IAM provides:
- **IAM policies** -- Bind members (users, groups, service accounts) to roles on resources
- **Roles** -- Predefined, custom, and basic roles with granular permissions
- **Service accounts** -- Machine identities for workloads
- **Workload Identity Federation** -- Authenticate external workloads without service account keys
- **Organization policies** -- Centralized constraints across the resource hierarchy
- **VPC Service Controls** -- Data exfiltration prevention perimeter
- **Cloud Identity** -- Google's directory and device management service
- **BeyondCorp Enterprise** -- Zero trust access to applications

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Policy authoring** -- IAM bindings, conditions, custom roles
   - **Architecture** -- Resource hierarchy, org policies, service perimeter
   - **Workload identity** -- External workload federation, service accounts
   - **Governance** -- IAM Recommender, Policy Analyzer, access troubleshooting
   - **Zero Trust** -- BeyondCorp, Identity-Aware Proxy

2. **Identify scope** -- Organization, folder, project, or resource level

3. **Analyze** -- Apply GCP IAM-specific reasoning. Consider the resource hierarchy, policy inheritance, and Google's additive-only policy model.

4. **Recommend** -- Provide actionable guidance with gcloud CLI commands and Terraform examples.

## Core Expertise

### Resource Hierarchy

GCP uses a hierarchical resource model:

```
Organization (example.com)
  |-- Folder: Production
  |     |-- Project: prod-app-1
  |     |     |-- Resources (GCE, GCS, GKE, etc.)
  |     |-- Project: prod-data-1
  |-- Folder: Staging
  |     |-- Project: staging-app-1
  |-- Folder: Sandbox
        |-- Project: dev-sandbox-1
```

**Policy inheritance:** IAM policies are inherited down the hierarchy. A role granted at the organization level applies to all folders, projects, and resources below it. Policies are additive -- you cannot deny at a lower level (unlike AWS SCPs).

**Important:** GCP IAM has no explicit Deny in IAM policies (IAM Deny policies are a separate feature in preview). To restrict access, remove bindings or use Organization policies and VPC Service Controls.

### IAM Policy Model

GCP IAM uses an allow-list model:

```yaml
# IAM policy binding
bindings:
- role: roles/storage.objectViewer
  members:
  - user:alice@example.com
  - group:data-analysts@example.com
  - serviceAccount:app-sa@project-id.iam.gserviceaccount.com
  condition:
    title: "Only production bucket"
    expression: "resource.name.startsWith('projects/_/buckets/prod-')"
```

**Member types:**

| Member | Format | Use Case |
|---|---|---|
| User | `user:email@example.com` | Individual Google account |
| Group | `group:name@example.com` | Google Group (recommended for access management) |
| Service account | `serviceAccount:sa@project.iam.gserviceaccount.com` | Machine identity |
| Domain | `domain:example.com` | All users in the Google Workspace domain |
| allUsers | `allUsers` | Anyone on the internet (use with extreme caution) |
| allAuthenticatedUsers | `allAuthenticatedUsers` | Any Google account (do not use for access control) |

### Roles

**Role types:**

| Type | Example | Characteristics |
|---|---|---|
| **Basic** | `roles/owner`, `roles/editor`, `roles/viewer` | Broad, thousands of permissions. Avoid in production. |
| **Predefined** | `roles/storage.objectViewer`, `roles/compute.admin` | Google-managed, service-specific, right-sized |
| **Custom** | `projects/my-project/roles/customRole` | Customer-defined, specific permissions |

```bash
# List predefined roles for a service
gcloud iam roles list --filter="name:roles/storage.*"

# Create a custom role
gcloud iam roles create customStorageReader \
  --project=my-project \
  --title="Custom Storage Reader" \
  --permissions=storage.objects.get,storage.objects.list,storage.buckets.get

# Grant role to a member
gcloud projects add-iam-policy-binding my-project \
  --member="group:data-team@example.com" \
  --role="roles/storage.objectViewer" \
  --condition='title=prod-only,expression=resource.name.startsWith("projects/_/buckets/prod-")'
```

### Service Accounts

Machine identities for GCP workloads:

**Types:**
- **Default service accounts** -- Auto-created per project (Compute Engine, App Engine). Over-privileged -- do not use.
- **User-managed** -- Created explicitly with specific permissions. Recommended.
- **Google-managed** -- Used by Google services internally (e.g., Cloud Build service agent).

**Best practices:**
- Create dedicated service accounts per workload (not shared)
- Grant minimum required roles
- Never export service account keys -- use Workload Identity or attached service accounts
- Use IAM Conditions to restrict service account impersonation
- Monitor service account key usage with IAM Recommender

```bash
# Create a service account
gcloud iam service-accounts create app-backend \
  --display-name="App Backend Service Account" \
  --project=my-project

# Grant role to service account
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:app-backend@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Impersonate a service account (for testing/admin)
gcloud config set auth/impersonate_service_account app-backend@my-project.iam.gserviceaccount.com
```

### Workload Identity Federation

Authenticate external workloads WITHOUT service account keys:

**Supported providers:**
- AWS (EC2 instance roles, ECS tasks)
- Azure (managed identities)
- GitHub Actions (OIDC tokens)
- Kubernetes (OIDC from non-GKE clusters)
- Any OIDC or SAML 2.0 identity provider

```bash
# Create workload identity pool
gcloud iam workload-identity-pools create github-pool \
  --location=global \
  --display-name="GitHub Actions Pool"

# Create provider for GitHub Actions
gcloud iam workload-identity-pools providers create-oidc github-provider \
  --location=global \
  --workload-identity-pool=github-pool \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --attribute-condition="assertion.repository == 'my-org/my-repo'"

# Grant permissions to federated identity
gcloud iam service-accounts add-iam-policy-binding \
  app-deploy@my-project.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUM/locations/global/workloadIdentityPools/github-pool/attribute.repository/my-org/my-repo"
```

### Organization Policies

Centralized constraints enforced across the resource hierarchy:

```bash
# Restrict resource locations
gcloud org-policies set-policy policy.yaml --organization=ORG_ID

# policy.yaml:
# constraint: constraints/gcp.resourceLocations
# listPolicy:
#   allowedValues:
#     - "in:us-locations"
#     - "in:eu-locations"

# Common constraints:
# constraints/iam.disableServiceAccountKeyCreation -- Prevent key export
# constraints/compute.vmExternalIpAccess -- Restrict public IPs on VMs
# constraints/gcp.resourceLocations -- Restrict deployment regions
# constraints/iam.allowedPolicyMemberDomains -- Restrict IAM to specific domains
# constraints/compute.requireShieldedVm -- Require Shielded VMs
```

### VPC Service Controls

Data exfiltration prevention perimeter:

- **Service perimeter** -- Boundary around GCP projects that restricts data movement
- **Protected services** -- BigQuery, Cloud Storage, GKE, and 100+ services
- **Ingress/Egress rules** -- Control access across the perimeter boundary
- **Access levels** -- Conditions for allowing access (IP range, device trust, identity)
- **Dry run mode** -- Test perimeter without enforcement

**Architecture:**
```
VPC Service Perimeter: "prod-perimeter"
  |-- Project: prod-data (BigQuery, GCS)
  |-- Project: prod-compute (GKE, GCE)
  |
  Ingress rules: Allow data-team@example.com from corporate IP range
  Egress rules: Allow export to specific approved external project
  
  Result: Data in prod-data CANNOT be copied to projects outside the perimeter
  unless an explicit egress rule allows it
```

### IAM Recommender

AI-powered recommendations for right-sizing permissions:

- Analyzes actual permission usage over 90 days
- Recommends removing unused permissions or replacing broad roles with narrower ones
- Provides role recommendations for service accounts and users
- Integrates with Security Command Center

```bash
# List recommendations
gcloud recommender recommendations list \
  --recommender=google.iam.policy.Recommender \
  --project=my-project \
  --location=global

# Apply a recommendation
gcloud recommender recommendations mark-claimed \
  --recommender=google.iam.policy.Recommender \
  --recommendation=RECOMMENDATION_ID \
  --project=my-project \
  --location=global
```

### IAM Conditions

Conditional role bindings based on attributes:

```
# Time-based access
expression: "request.time < timestamp('2024-12-31T00:00:00Z')"

# Resource name-based
expression: "resource.name.startsWith('projects/_/buckets/prod-')"

# Resource type-based  
expression: "resource.type == 'storage.googleapis.com/Bucket'"

# Combined conditions
expression: "resource.name.startsWith('projects/_/buckets/prod-') && request.time.getHours('America/New_York') >= 9 && request.time.getHours('America/New_York') <= 17"
```

### BeyondCorp Enterprise

Zero trust access to applications:

- **Identity-Aware Proxy (IAP)** -- Protects web applications and VMs with identity and context verification
- **Access levels** -- Define conditions (IP range, device state, OS version, encryption status)
- **BeyondCorp connectors** -- Extend zero trust access to on-premises applications
- **Endpoint Verification** -- Collect device posture from endpoints

```bash
# Enable IAP for a backend service
gcloud compute backend-services update my-backend \
  --iap=enabled --global

# Create an access level
gcloud access-context-manager levels create corporate-device \
  --title="Corporate Device" \
  --basic-level-spec=level.yaml

# level.yaml:
# conditions:
#   - devicePolicy:
#       requireScreenlock: true
#       osConstraints:
#         - osType: DESKTOP_WINDOWS
#           requireVerifiedChromeOs: false
#     ipSubnetworks:
#       - "10.0.0.0/8"
```

## Common Pitfalls

1. **Using basic roles (Owner/Editor/Viewer)** -- These grant thousands of permissions. Use predefined or custom roles instead.
2. **Exporting service account keys** -- Keys are long-lived credentials that can be leaked. Use Workload Identity Federation or attached service accounts.
3. **allUsers / allAuthenticatedUsers** -- These open resources to anyone. Use with extreme caution and only for intentionally public resources.
4. **Not using groups** -- Binding roles to individual users is unmanageable at scale. Use Google Groups for access management.
5. **Ignoring IAM Recommender** -- Recommender identifies over-provisioned access. Review recommendations regularly.
6. **No organization policies** -- Without org policies, any project can create public resources, export keys, or deploy in any region.
7. **VPC Service Controls without dry run** -- Deploying service perimeters without dry run mode can break legitimate access patterns. Always test first.