{"id":1495,"library":"google-cloud-iam","title":"Google Cloud IAM Client Library","description":"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.","status":"active","version":"2.22.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-iam","tags":["Google Cloud","IAM","Identity and Access Management","Security","Workload Identity Federation"],"install":[{"cmd":"pip install google-cloud-iam","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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`).","wrong":"from google.cloud import iam_admin_v1","symbol":"IAMClient","correct":"from google.cloud import iam_v2"}],"quickstart":{"code":"import os\nfrom google.cloud import iam_v2\n\n# Set your Google Cloud Organization ID as an environment variable, e.g., GCP_ORGANIZATION_ID=1234567890\norganization_id = os.environ.get(\"GCP_ORGANIZATION_ID\", \"your-organization-id\")\n\nif organization_id == \"your-organization-id\":\n    print(\"Warning: Please set the GCP_ORGANIZATION_ID environment variable to run this example.\")\n    print(\"This quickstart for 'google-cloud-iam' focuses on Workload Identity Federation (WIF).\")\n    print(\"For general IAM policy management, consider 'google-cloud-iam-admin' or service-specific clients.\")\nelse:\n    try:\n        # Authenticate using Application Default Credentials (ADC)\n        # e.g., by running `gcloud auth application-default login` or setting `GOOGLE_APPLICATION_CREDENTIALS`.\n        client = iam_v2.IAMClient()\n\n        # The parent resource for listing Workload Identity Pools is in the format 'organizations/{organization_id}/locations/global'\n        parent = client.common_location_path(organization=organization_id, location=\"global\")\n\n        print(f\"Listing Workload Identity Pools in organization {organization_id} (location: global):\")\n        for pool in client.list_workload_identity_pools(parent=parent):\n            print(f\"- Pool Name: {pool.name}, Display Name: {pool.display_name}, State: {pool.state.name}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Ensure the service account or user running this code has 'iam.workloadIdentityPools.list' permission.\")\n        print(\"Also, verify that the 'GCP_ORGANIZATION_ID' is correct and accessible.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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()`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Authentication is critical for Google Cloud client libraries. Improper or missing authentication credentials will lead to `google.auth.exceptions.DefaultCredentialsError` or `PermissionDenied` errors.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}