Google Cloud IAM Client Library

2.22.0 · active · verified Thu Apr 09

The `google-cloud-iam` client library provides access to the Google Cloud IAM API, primarily focusing on Workload Identity Federation (WIF) resources like Workload Identity Pools and Providers. It allows programmatic management of these resources. The current version is 2.22.0, and it follows the rapid release cadence typical of Google Cloud client libraries, with updates often coinciding with API changes.

Warnings

gotcha The `google-cloud-iam` library (specifically `iam_v2`) is primarily designed for Workload Identity Federation (WIF) management. If you intend to manage general IAM policies on projects, folders, organizations, or specific Google Cloud resources (like Cloud Storage buckets, Pub/Sub topics, or Compute Engine instances), you likely need the `google-cloud-iam-admin` library for the IAM Admin API, or the IAM methods provided directly by the specific service's client library (e.g., `google.cloud.storage.Client().get_iam_policy()`).
Fix: For general IAM policy management, install `google-cloud-iam-admin` (`pip install google-cloud-iam-admin`) and use `from google.cloud import iam_admin_v1`. For resource-specific policies, use the respective service client library.
gotcha Authentication is critical for Google Cloud client libraries. Improper or missing authentication credentials will lead to `google.auth.exceptions.DefaultCredentialsError` or `PermissionDenied` errors.
Fix: Ensure Application Default Credentials (ADC) are configured. Use `gcloud auth application-default login` for local development, or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path. For production, use managed identities like Service Accounts or Workload Identity.
gotcha IAM API calls often require resource names in a very specific format (e.g., `organizations/{organization_id}/locations/global` for Workload Identity Pools). Incorrect formatting will result in `google.api_core.exceptions.NotFound` or `InvalidArgument` errors.
Fix: Consult the API documentation for the exact resource name format required for each method. Use helper methods provided by the client (e.g., `client.common_location_path`) where available to construct correct paths.

Install

pip install google-cloud-iam Install latest version

Imports

IAMClient
```
from google.cloud import iam_v2
```
The `google-cloud-iam` library primarily exposes `iam_v2` and `iam_v2beta` clients for Workload Identity Federation. For general IAM administration (e.g., managing project-level policies, custom roles, or service accounts outside of WIF), you likely need `google-cloud-iam-admin` (which provides `iam_admin_v1.IAMAdminClient`).

Quickstart

This quickstart demonstrates how to initialize the `IAMClient` and list Workload Identity Pools within a Google Cloud Organization. It requires `GCP_ORGANIZATION_ID` to be set as an environment variable and relies on Application Default Credentials for authentication. It highlights the library's focus on Workload Identity Federation.

import os
from google.cloud import iam_v2

# Set your Google Cloud Organization ID as an environment variable, e.g., GCP_ORGANIZATION_ID=1234567890
organization_id = os.environ.get("GCP_ORGANIZATION_ID", "your-organization-id")

if organization_id == "your-organization-id":
    print("Warning: Please set the GCP_ORGANIZATION_ID environment variable to run this example.")
    print("This quickstart for 'google-cloud-iam' focuses on Workload Identity Federation (WIF).")
    print("For general IAM policy management, consider 'google-cloud-iam-admin' or service-specific clients.")
else:
    try:
        # Authenticate using Application Default Credentials (ADC)
        # e.g., by running `gcloud auth application-default login` or setting `GOOGLE_APPLICATION_CREDENTIALS`.
        client = iam_v2.IAMClient()

        # The parent resource for listing Workload Identity Pools is in the format 'organizations/{organization_id}/locations/global'
        parent = client.common_location_path(organization=organization_id, location="global")

        print(f"Listing Workload Identity Pools in organization {organization_id} (location: global):")
        for pool in client.list_workload_identity_pools(parent=parent):
            print(f"- Pool Name: {pool.name}, Display Name: {pool.display_name}, State: {pool.state.name}")

    except Exception as e:
        print(f"An error occurred: {e}")
        print("Ensure the service account or user running this code has 'iam.workloadIdentityPools.list' permission.")
        print("Also, verify that the 'GCP_ORGANIZATION_ID' is correct and accessible.")

view raw JSON →