Registry / gcp / google-cloud-iam

google-cloud-iam

JSON →
library2.25.0pypypi✓ verified 24d ago

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.

pip install google-cloud-iam
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-IAM
G
google-cloud-iam
gcppythonv2.25.0
Install
5.9s avg
Import
1425ms
Disk
74MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.25.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.642s · 75.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.9s · import 1.208s · 73MB
74MB installed
● package 74MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IAMClient
from google.cloud import iam_v2
from google.cloud import iam_admin_v1
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`).

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.")
Debug
Known issues
gotchaThe `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.
affects: All versions
gotchaAuthentication 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.
affects: All versions
gotchaIAM 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.
affects: All versions
gotchaQuickstart examples for `google-cloud-iam` often require specific environment variables to be set (e.g., `GCP_ORGANIZATION_ID`, `GCP_PROJECT_ID`). Failing to set these will prevent the examples from running or lead to configuration errors.
fix
Ensure all required environment variables for the quickstart or example are properly configured. Consult the example's source code or README for specific requirements.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud.iam'
The `google-cloud-iam` client library is either not installed in the current Python environment, or there's an issue with the Python path, or a deprecated `google-cloud` meta-package might be installed instead.
fix
Ensure the `google-cloud-iam` library is correctly installed using `pip install google-cloud-iam` within your active Python environment. If necessary, consider uninstalling potentially conflicting or deprecated `google-cloud` packages first (e.g., `pip uninstall google-cloud`).
403 Permission Denied
The authenticated principal (user, service account, or federated identity) lacks the necessary Identity and Access Management (IAM) permissions to perform the requested action on the specified Google Cloud resource.
fix
Identify the exact permission required for the operation (which is often detailed in the full error message) and grant an appropriate IAM role containing that permission to the principal at the correct resource hierarchy level (e.g., project, folder, organization, or specific resource).
INVALID_ARGUMENT: Role roles/<role_name> is not supported for this resource.
You are attempting to bind an IAM role to a resource type for which that specific role is not applicable, meaning the permissions within the role do not logically apply to that particular resource.
fix
Review the Google Cloud IAM roles and permissions documentation for the specific resource type you are targeting, and select a predefined or custom role that is valid and appropriate for that resource. For example, a role meant for Compute Engine might not be applicable to a service account.
The size of the entire mapped attributes exceeds the 16 KB limit.
When using Workload Identity Federation (WIF), the total size of the attributes (claims) received from your external Identity Provider (IdP) and mapped to Google Cloud attributes has exceeded the 16KB limit imposed by IAM.
fix
Collaborate with your IdP administrator to reduce the number of attributes or the size of attribute values being emitted by the IdP, ensuring only essential attributes are sent for federation with Google Cloud.
Upgrade
Version history
2.25.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
16
OpenAI (training)
1
Resources
google-cloud-iam — pip install google-cloud-iam · libregistry