{"id":507,"library":"grpc-google-iam-v1","title":"Google Cloud IAM gRPC Client Library","description":"The `grpc-google-iam-v1` library provides the low-level gRPC client and Protocol Buffer definitions for interacting with the Google Cloud Identity and Access Management (IAM) API. It handles the underlying gRPC communication and data serialization/deserialization. As per Google's official recommendation, this library is generally not intended for direct use by application developers. Instead, the higher-level, idiomatic Python clients like `google-cloud-iam` (which might delegate to `google-cloud-resource-manager` or `google-cloud-iam-admin` for specific IAM operations) should be used. The current version is 0.14.3, and it's part of the regularly updated google-cloud-python ecosystem.","status":"active","version":"0.14.3","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python","tags":["google-cloud","iam","grpc","client-library","low-level"],"install":[{"cmd":"pip install grpc-google-iam-v1","lang":"bash","label":"Install grpc-google-iam-v1"}],"dependencies":[{"reason":"Provides core Google API utilities, including gRPC support and retry mechanisms.","package":"google-api-core","optional":false},{"reason":"Enhances Protocol Buffer messages with Pythonic behaviors.","package":"proto-plus","optional":false},{"reason":"Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data.","package":"protobuf","optional":false},{"reason":"The Python gRPC library for high-performance remote procedure calls.","package":"grpcio","optional":false},{"reason":"gRPC status codes and error details.","package":"grpcio-status","optional":false}],"imports":[{"note":"This is the low-level gRPC stub. Most applications should use a higher-level client like `google.cloud.resourcemanager_v3.ProjectsClient` for idiomatic IAM policy management.","symbol":"IamPolicyStub","correct":"from google.iam.v1 import iam_policy_pb2_grpc"},{"note":"Protobuf message definition for IAM policies. Used by both low-level gRPC and higher-level clients.","symbol":"Policy","correct":"from google.iam.v1 import policy_pb2"},{"note":"Protobuf message definition for getting IAM policies. Used by both low-level gRPC and higher-level clients.","symbol":"GetIamPolicyRequest","correct":"from google.iam.v1 import iam_policy_pb2"}],"quickstart":{"code":"import os\nfrom google.cloud import resourcemanager_v3\nfrom google.iam.v1 import iam_policy_pb2, policy_pb2\n\n# NOTE: This quickstart demonstrates how to manage IAM policies using the\n# recommended `google-cloud-resource-manager` library, which is built on top of\n# the underlying IAM Policy API (v1) that `grpc-google-iam-v1` implements.\n# Direct usage of `grpc-google-iam-v1` is generally discouraged.\n\n# Set your Google Cloud project ID. Ensure you have authenticated\n# (e.g., `gcloud auth application-default login` or GOOGLE_APPLICATION_CREDENTIALS)\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\nif project_id == 'your-gcp-project-id':\n    raise ValueError(\"Please set the 'GOOGLE_CLOUD_PROJECT' environment variable or replace 'your-gcp-project-id'.\")\n\nproject_resource = f'projects/{project_id}'\n\ntry:\n    # Initialize the Resource Manager client\n    client = resourcemanager_v3.ProjectsClient()\n\n    # 1. Get the current IAM policy for the project\n    get_request = iam_policy_pb2.GetIamPolicyRequest(resource=project_resource)\n    current_policy = client.get_iam_policy(request=get_request)\n    print(f\"Current policy for {project_resource}:\")\n    print(current_policy)\n\n    # 2. Modify the policy (e.g., add a new member with a role)\n    # IMPORTANT: Always read the existing policy, modify it, then write it back\n    # to avoid overwriting changes made by others. Use etag for concurrency control.\n    new_policy = policy_pb2.Policy(version=current_policy.version, etag=current_policy.etag)\n    new_policy.bindings.extend(current_policy.bindings)\n\n    # Example: Add a new member (e.g., a user or service account) with the Viewer role\n    # Replace 'user:example@example.com' with a valid member ID\n    new_member = \"user:example@example.com\"\n    new_role = \"roles/viewer\"\n\n    found_binding = False\n    for binding in new_policy.bindings:\n        if binding.role == new_role:\n            if new_member not in binding.members:\n                binding.members.append(new_member)\n                print(f\"Added {new_member} to role {new_role}.\")\n            else:\n                print(f\"{new_member} already in role {new_role}.\")\n            found_binding = True\n            break\n\n    if not found_binding:\n        new_binding = policy_pb2.Binding(role=new_role, members=[new_member])\n        new_policy.bindings.append(new_binding)\n        print(f\"Created new binding for role {new_role} and added {new_member}.\")\n\n    # 3. Set the modified IAM policy\n    set_request = iam_policy_pb2.SetIamPolicyRequest(\n        resource=project_resource,\n        policy=new_policy,\n        update_mask=iam_policy_pb2.FieldMask(paths=[\"bindings\", \"etag\"])\n    )\n    updated_policy = client.set_iam_policy(request=set_request)\n    print(f\"\\nUpdated policy for {project_resource}:\")\n    print(updated_policy)\n\n    # 4. Clean up: Remove the added member (optional)\n    cleanup_policy = policy_pb2.Policy(version=updated_policy.version, etag=updated_policy.etag)\n    cleanup_policy.bindings.extend(updated_policy.bindings)\n\n    for binding in cleanup_policy.bindings:\n        if binding.role == new_role and new_member in binding.members:\n            binding.members.remove(new_member)\n            print(f\"\\nRemoved {new_member} from role {new_role}.\")\n            break\n\n    cleanup_request = iam_policy_pb2.SetIamPolicyRequest(\n        resource=project_resource,\n        policy=cleanup_policy,\n        update_mask=iam_policy_pb2.FieldMask(paths=[\"bindings\", \"etag\"])\n    )\n    client.set_iam_policy(request=cleanup_request)\n    print(\"Cleanup complete.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure 'GOOGLE_CLOUD_PROJECT' is set and you have 'roles/resourcemanager.projectIamAdmin' or equivalent permissions.\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically get, modify, and set an IAM policy on a Google Cloud project using the higher-level `google-cloud-resource-manager` library. This is the recommended approach for interacting with IAM policies in Python, as `grpc-google-iam-v1` is a low-level client. The example shows how to retrieve the current policy, add a 'Viewer' role binding for a specified member, and then clean up by removing that member. Ensure you have authenticated to Google Cloud and set the `GOOGLE_CLOUD_PROJECT` environment variable."},"warnings":[{"fix":"Install `google-cloud-iam` (`pip install google-cloud-iam`) and use its provided client classes (e.g., `from google.cloud import resourcemanager_v3`).","message":"This library (`grpc-google-iam-v1`) is a low-level gRPC client and is generally not recommended for direct application use. For idiomatic Python interaction with Google Cloud IAM, prefer using the `google-cloud-iam` client library, or more specific clients like `google-cloud-resource-manager` for project-level policies, or `google-cloud-iam-admin` for service account/custom role management. [5, 6]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always retrieve the current policy (including its `etag`) before making modifications. Include the `etag` in your `SetIamPolicyRequest` to ensure optimistic concurrency control. For conditional bindings, always specify `version=3` in the Policy object.","message":"IAM Policy versions and `etag` field are crucial for safe updates. If you modify an IAM policy (especially with conditional bindings) without specifying the correct `etag` from the latest `get_iam_policy` call, your changes might overwrite concurrent updates or lead to unintended loss of conditional bindings. Version 3 policies *require* the `etag` for updates. [24]","severity":"breaking","affected_versions":"All versions where IAM Policy V3 is used (IAM Policy API), particularly when updating policies."},{"fix":"Use a virtual environment for each project. Explicitly pin major versions of your Google Cloud client libraries (e.g., `google-cloud-compute==X.*`, `google-cloud-storage==Y.*`) in `requirements.txt` to mitigate unexpected dependency resolution issues.","message":"Dependency conflicts, especially with `grpc-google-iam-v1`, have historically been a source of issues within the `google-cloud-python` ecosystem when different high-level client libraries pinned incompatible versions. While this is less common with newer releases, it can still occur if mixing older versions or non-standard packages. [20]","severity":"gotcha","affected_versions":"Potentially any version, especially when integrating with other Google Cloud client libraries or third-party packages that have specific `grpcio` or `protobuf` requirements."},{"fix":"Verify authentication setup: `gcloud auth application-default print-access-token` should return a token. Check IAM permissions for the principal making the API calls against the specific resource.","message":"Authentication is a common point of failure. Ensure your environment variables (`GOOGLE_APPLICATION_CREDENTIALS`) or `gcloud` configuration (`gcloud auth application-default login`) are correctly set up, and that the authenticated principal has the necessary IAM permissions (e.g., `roles/resourcemanager.projectIamAdmin` for managing project policies).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:29:06.129Z","next_check":"2026-06-26T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.34,"mem_mb":9.3,"disk_size":"41.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":7.6,"disk_size":"39M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":10.3,"disk_size":"44.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":9.1,"disk_size":"42M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.9,"mem_mb":10.2,"disk_size":"35.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":9.2,"disk_size":"34M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":10.5,"disk_size":"35.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":9.4,"disk_size":"33M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":9.3,"disk_size":"41.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":7.6,"disk_size":"39M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}