0
# IAM Policies
1

2
Core data structures for Google Cloud Identity and Access Management policies, including role bindings, audit configurations, and policy change tracking. These message types represent the fundamental building blocks of IAM access control.
3

4
## Capabilities
5

6
### Policy Structure
7

8
The main IAM policy message that contains role bindings, audit configurations, and metadata for access control on Google Cloud resources.
9

10
```python { .api }
11
class Policy:
12
    """
13
    Defines an Identity and Access Management (IAM) policy.
14
    
15
    Attributes:
16
        version (int): Policy format version (1 or 3)
17
        bindings (List[Binding]): Role bindings that bind members to roles
18
        audit_configs (List[AuditConfig]): Audit configurations for services
19
        etag (bytes): Entity tag for optimistic concurrency control
20
    """
21
    version: int
22
    bindings: List[Binding]
23
    audit_configs: List[AuditConfig]
24
    etag: bytes
25
```
26

27
### Role Bindings
28

29
Associates a list of members (users, groups, service accounts) with a role, optionally with conditional logic.
30

31
```python { .api }
32
class Binding:
33
    """
34
    Associates members with a role.
35
    
36
    Attributes:
37
        role (str): Role name (e.g., "roles/viewer", "roles/editor")
38
        members (List[str]): List of principals in format "user:email", "group:email", "serviceAccount:email"
39
        condition (google.type.Expr): Optional conditional expression for access
40
    """
41
    role: str
42
    members: List[str]
43
    condition: google.type.Expr
44
```
45

46
Usage example:
47

48
```python
49
from google.iam.v1 import policy_pb2
50

51
# Create a binding for viewer role
52
binding = policy_pb2.Binding()
53
binding.role = "roles/viewer"
54
binding.members.extend([
55
    "user:alice@example.com",
56
    "group:admins@example.com",
57
    "serviceAccount:my-service@project.iam.gserviceaccount.com"
58
])
59

60
# Add to policy
61
policy = policy_pb2.Policy()
62
policy.bindings.append(binding)
63
```
64

65
### Audit Configuration
66

67
Configures audit logging for specific services and log types.
68

69
```python { .api }
70
class AuditConfig:
71
    """
72
    Specifies audit logging configurations for a service.
73
    
74
    Attributes:
75
        service (str): Service name (e.g., "storage.googleapis.com")
76
        audit_log_configs (List[AuditLogConfig]): Audit log configurations
77
    """
78
    service: str
79
    audit_log_configs: List[AuditLogConfig]
80

81
class AuditLogConfig:
82
    """
83
    Configuration for a specific audit log type.
84
    
85
    Attributes:
86
        log_type (LogType): Type of audit log to generate
87
        exempted_members (List[str]): Members exempt from this audit log
88
    """
89
    log_type: LogType
90
    exempted_members: List[str]
91
```
92

93
### Audit Log Types
94

95
```python { .api }
96
class LogType:
97
    """
98
    Types of audit logs that can be generated.
99
    """
100
    LOG_TYPE_UNSPECIFIED = 0
101
    ADMIN_READ = 1      # Admin activity logs
102
    DATA_WRITE = 2      # Data access write logs  
103
    DATA_READ = 3       # Data access read logs
104
```
105

106
### Policy Changes
107

108
Represents changes to IAM policies for audit trails and incremental updates.
109

110
```python { .api }
111
class PolicyDelta:
112
    """
113
    Represents a set of changes to an IAM policy.
114
    
115
    Attributes:
116
        binding_deltas (List[BindingDelta]): Changes to role bindings
117
        audit_config_deltas (List[AuditConfigDelta]): Changes to audit configs
118
    """
119
    binding_deltas: List[BindingDelta]
120
    audit_config_deltas: List[AuditConfigDelta]
121

122
class BindingDelta:
123
    """
124
    Represents a change to a role binding.
125
    
126
    Attributes:
127
        action (Action): Whether to ADD or REMOVE the binding
128
        role (str): Role being modified
129
        member (str): Member being added or removed
130
        condition (google.type.Expr): Optional conditional logic
131
    """
132
    action: Action
133
    role: str
134
    member: str
135
    condition: google.type.Expr
136

137
class AuditConfigDelta:
138
    """
139
    Represents a change to audit configuration.
140
    
141
    Attributes:
142
        action (Action): Whether to ADD or REMOVE the configuration
143
        service (str): Service name
144
        exempted_member (str): Member to add or remove from exemption list
145
        log_type (str): Type of audit log being modified
146
    """
147
    action: Action
148
    service: str
149
    exempted_member: str
150
    log_type: str
151
```
152

153
### Change Actions
154

155
```python { .api }
156
class Action:
157
    """
158
    Actions that can be performed on policy elements.
159
    """
160
    ACTION_UNSPECIFIED = 0
161
    ADD = 1      # Add the element
162
    REMOVE = 2   # Remove the element
163
```
164

165
## Usage Examples
166

167
### Creating a Complex Policy
168

169
```python
170
from google.iam.v1 import policy_pb2
171
from google.type import expr_pb2
172

173
# Create policy with multiple bindings
174
policy = policy_pb2.Policy()
175
policy.version = 3  # Required for conditional bindings
176

177
# Owner binding - unconditional
178
owner_binding = policy_pb2.Binding()
179
owner_binding.role = "roles/owner"
180
owner_binding.members.append("user:owner@example.com")
181
policy.bindings.append(owner_binding)
182

183
# Conditional viewer binding - only during business hours
184
viewer_binding = policy_pb2.Binding()
185
viewer_binding.role = "roles/viewer"
186
viewer_binding.members.extend([
187
    "user:alice@example.com",
188
    "user:bob@example.com"
189
])
190

191
# Add condition (business hours only)
192
condition = expr_pb2.Expr()
193
condition.title = "Business hours only"
194
condition.description = "Only allow access during business hours"
195
condition.expression = '''
196
    request.time.getHours() >= 9 && 
197
    request.time.getHours() <= 17 &&
198
    request.time.getDayOfWeek() >= 1 &&
199
    request.time.getDayOfWeek() <= 5
200
'''
201
viewer_binding.condition.CopyFrom(condition)
202
policy.bindings.append(viewer_binding)
203

204
# Add audit configuration
205
audit_config = policy_pb2.AuditConfig()
206
audit_config.service = "storage.googleapis.com"
207

208
# Admin read logs
209
admin_log_config = policy_pb2.AuditLogConfig()
210
admin_log_config.log_type = policy_pb2.AuditLogConfig.LogType.ADMIN_READ
211
audit_config.audit_log_configs.append(admin_log_config)
212

213
# Data write logs with exemptions
214
data_write_config = policy_pb2.AuditLogConfig()
215
data_write_config.log_type = policy_pb2.AuditLogConfig.LogType.DATA_WRITE
216
data_write_config.exempted_members.append("serviceAccount:backup@project.iam.gserviceaccount.com")
217
audit_config.audit_log_configs.append(data_write_config)
218

219
policy.audit_configs.append(audit_config)
220
```
221

222
### Policy Delta for Incremental Changes
223

224
```python
225
from google.iam.v1 import policy_pb2
226

227
# Create policy delta to add a new member
228
delta = policy_pb2.PolicyDelta()
229

230
# Add binding delta
231
binding_delta = policy_pb2.BindingDelta()
232
binding_delta.action = policy_pb2.BindingDelta.Action.ADD
233
binding_delta.role = "roles/viewer"
234
binding_delta.member = "user:newuser@example.com"
235
delta.binding_deltas.append(binding_delta)
236

237
# Add audit config delta
238
audit_delta = policy_pb2.AuditConfigDelta()
239
audit_delta.action = policy_pb2.AuditConfigDelta.Action.ADD
240
audit_delta.service = "pubsub.googleapis.com"
241
audit_delta.log_type = "DATA_READ"
242
audit_delta.exempted_member = "serviceAccount:reader@project.iam.gserviceaccount.com"
243
delta.audit_config_deltas.append(audit_delta)
244
```