0
# grpc-google-iam-v1
1

2
A gRPC client library providing Python protocol buffer definitions and service stubs for Google Cloud Identity and Access Management (IAM) services. This low-level library enables direct interaction with IAM APIs for managing access control policies, role bindings, and permission evaluation across Google Cloud resources.
3

4
## Package Information
5

6
- **Package Name**: grpc-google-iam-v1
7
- **Language**: Python
8
- **Installation**: `pip install grpc-google-iam-v1`
9
- **Python Support**: >= 3.7
10

11
## Core Imports
12

13
```python
14
from google.iam.v1 import policy_pb2
15
from google.iam.v1 import iam_policy_pb2
16
from google.iam.v1 import iam_policy_pb2_grpc
17
from google.iam.v1 import options_pb2
18
```
19

20
For audit and logging:
21

22
```python
23
from google.iam.v1.logging import audit_data_pb2
24
```
25

26
For resource policy members:
27

28
```python
29
from google.iam.v1 import resource_policy_member_pb2
30
```
31

32
## Basic Usage
33

34
```python
35
import grpc
36
from google.iam.v1 import policy_pb2
37
from google.iam.v1 import iam_policy_pb2
38
from google.iam.v1 import iam_policy_pb2_grpc
39

40
# Create a gRPC channel to your service
41
channel = grpc.insecure_channel('your-service-endpoint:443')
42

43
# Create client stub
44
client = iam_policy_pb2_grpc.IAMPolicyStub(channel)
45

46
# Create a policy with role bindings
47
policy = policy_pb2.Policy()
48
binding = policy_pb2.Binding()
49
binding.role = "roles/viewer"
50
binding.members.extend(["user:alice@example.com", "serviceAccount:my-service@project.iam.gserviceaccount.com"])
51
policy.bindings.append(binding)
52

53
# Set IAM policy on a resource
54
set_request = iam_policy_pb2.SetIamPolicyRequest()
55
set_request.resource = "projects/my-project/topics/my-topic"
56
set_request.policy.CopyFrom(policy)
57

58
response = client.SetIamPolicy(set_request)
59
print(f"Policy set with etag: {response.etag}")
60

61
# Get IAM policy from a resource
62
get_request = iam_policy_pb2.GetIamPolicyRequest()
63
get_request.resource = "projects/my-project/topics/my-topic"
64

65
policy_response = client.GetIamPolicy(get_request)
66
print(f"Retrieved policy with {len(policy_response.bindings)} bindings")
67

68
# Test permissions on a resource
69
test_request = iam_policy_pb2.TestIamPermissionsRequest()
70
test_request.resource = "projects/my-project/topics/my-topic"
71
test_request.permissions.extend(["pubsub.topics.get", "pubsub.topics.publish"])
72

73
permissions_response = client.TestIamPermissions(test_request)
74
print(f"User has permissions: {list(permissions_response.permissions)}")
75
```
76

77
## Architecture
78

79
This library follows Google's protocol buffer and gRPC patterns:
80

81
- **Protocol Buffer Messages**: Structured data types for IAM policies, bindings, and requests
82
- **gRPC Service Stubs**: Client interfaces for remote IAM service calls
83
- **Namespace Organization**: Uses google.iam.v1 namespace following Google's conventions
84
- **Generated Code**: All classes are auto-generated from .proto definitions
85

86
The library provides both client-side stubs for making IAM service calls and server-side servicer base classes for implementing IAM services.
87

88
## Capabilities
89

90
### IAM Policy Management
91

92
Core IAM policy data structures and operations for managing access control policies with role bindings, conditions, and audit configurations.
93

94
```python { .api }
95
class Policy:
96
    version: int
97
    bindings: List[Binding]
98
    audit_configs: List[AuditConfig]
99
    etag: bytes
100

101
class Binding:
102
    role: str
103
    members: List[str]
104
    condition: google.type.Expr
105
```
106

107
[IAM Policies](./iam-policies.md)
108

109
### gRPC Service Operations
110

111
Client and server classes for IAM policy service operations including setting, getting, and testing permissions on Google Cloud resources.
112

113
```python { .api }
114
class IAMPolicyStub:
115
    def __init__(self, channel): ...
116
    def SetIamPolicy(self, request: SetIamPolicyRequest) -> Policy: ...
117
    def GetIamPolicy(self, request: GetIamPolicyRequest) -> Policy: ...
118
    def TestIamPermissions(self, request: TestIamPermissionsRequest) -> TestIamPermissionsResponse: ...
119
```
120

121
[gRPC Services](./grpc-services.md)
122

123
### Audit and Logging
124

125
Support for audit trails and policy change tracking through specialized message types for logging IAM operations and policy modifications.
126

127
```python { .api }
128
class AuditData:
129
    policy_delta: PolicyDelta
130

131
class PolicyDelta:
132
    binding_deltas: List[BindingDelta]
133
    audit_config_deltas: List[AuditConfigDelta]
134
```
135

136
[Audit and Logging](./audit-logging.md)
137

138
## Types
139

140
### Core Request/Response Types
141

142
```python { .api }
143
class SetIamPolicyRequest:
144
    resource: str
145
    policy: Policy
146
    update_mask: google.protobuf.FieldMask
147

148
class GetIamPolicyRequest:
149
    resource: str
150
    options: GetPolicyOptions
151

152
class TestIamPermissionsRequest:
153
    resource: str
154
    permissions: List[str]
155

156
class TestIamPermissionsResponse:
157
    permissions: List[str]
158
```
159

160
### Configuration Types
161

162
```python { .api }
163
class GetPolicyOptions:
164
    requested_policy_version: int
165

166
class ResourcePolicyMember:
167
    iam_policy_name_principal: str  # output only
168
    iam_policy_uid_principal: str   # output only
169
```