0
# IP Override Management
1

2
Management of IP address overrides for testing and development environments. IP overrides allow specific IP addresses to be treated differently during reCAPTCHA assessments, enabling controlled testing scenarios and development workflows.
3

4
## Capabilities
5

6
### Add IP Override
7

8
Adds IP addresses to the override list for a specific key, allowing controlled testing behavior.
9

10
```python { .api }
11
def add_ip_override(
12
    request: AddIpOverrideRequest = None,
13
    *,
14
    parent: str = None,
15
    ip_override_data: IpOverrideData = None,
16
    retry: Union[retries.Retry, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE,
17
    timeout: Union[float, object] = _MethodDefault._DEFAULT_VALUE,
18
    metadata: Sequence[Tuple[str, str]] = ()
19
) -> AddIpOverrideResponse:
20
    """
21
    Adds an IP override for a key.
22

23
    Args:
24
        request: The request object for adding IP override
25
        parent: Required. The key name in format 'projects/{project}/keys/{key}'
26
        ip_override_data: Required. IP override configuration
27
        retry: Retry configuration for the request
28
        timeout: Timeout for the request in seconds
29
        metadata: Additional metadata for the request
30

31
    Returns:
32
        AddIpOverrideResponse: Confirmation of IP override addition
33

34
    Raises:
35
        google.api_core.exceptions.InvalidArgument: If IP override data is invalid
36
        google.api_core.exceptions.NotFound: If the key doesn't exist
37
        google.api_core.exceptions.PermissionDenied: If insufficient permissions
38
    """
39
```
40

41
#### Usage Example
42

43
```python
44
from google.cloud import recaptchaenterprise
45
from google.cloud.recaptchaenterprise_v1.types import IpOverrideData
46

47
client = recaptchaenterprise.RecaptchaEnterpriseServiceClient()
48

49
# Add IP override for testing
50
ip_override = IpOverrideData(
51
    ip="203.0.113.0/24",  # IP address or CIDR block
52
    override_type=IpOverrideData.OverrideType.ALLOW
53
)
54

55
request = recaptchaenterprise.AddIpOverrideRequest(
56
    parent="projects/your-project/keys/your-key-id",
57
    ip_override_data=ip_override
58
)
59

60
response = client.add_ip_override(request=request)
61
print("IP override added successfully")
62
```
63

64
### Remove IP Override
65

66
Removes IP addresses from the override list for a specific key.
67

68
```python { .api }
69
def remove_ip_override(
70
    request: RemoveIpOverrideRequest = None,
71
    *,
72
    parent: str = None,
73
    ip_override_data: IpOverrideData = None,
74
    retry: Union[retries.Retry, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE,
75
    timeout: Union[float, object] = _MethodDefault._DEFAULT_VALUE,
76
    metadata: Sequence[Tuple[str, str]] = ()
77
) -> RemoveIpOverrideResponse:
78
    """
79
    Removes an IP override for a key.
80

81
    Args:
82
        request: The request object for removing IP override
83
        parent: Required. The key name in format 'projects/{project}/keys/{key}'
84
        ip_override_data: Required. IP override to remove
85
        retry: Retry configuration for the request
86
        timeout: Timeout for the request in seconds
87
        metadata: Additional metadata for the request
88

89
    Returns:
90
        RemoveIpOverrideResponse: Confirmation of IP override removal
91

92
    Raises:
93
        google.api_core.exceptions.NotFound: If override or key doesn't exist
94
        google.api_core.exceptions.InvalidArgument: If IP override data is invalid
95
        google.api_core.exceptions.PermissionDenied: If insufficient permissions
96
    """
97
```
98

99
### List IP Overrides
100

101
Retrieves all IP overrides for a specific key with support for pagination.
102

103
```python { .api }
104
def list_ip_overrides(
105
    request: ListIpOverridesRequest = None,
106
    *,
107
    parent: str = None,
108
    retry: Union[retries.Retry, gapic_v1.method._MethodDefault] = _MethodDefault._DEFAULT_VALUE,
109
    timeout: Union[float, object] = _MethodDefault._DEFAULT_VALUE,
110
    metadata: Sequence[Tuple[str, str]] = ()
111
) -> ListIpOverridesResponse:
112
    """
113
    Lists IP overrides for a key.
114

115
    Args:
116
        request: The request object for listing IP overrides
117
        parent: Required. The key name in format 'projects/{project}/keys/{key}'
118
        retry: Retry configuration for the request
119
        timeout: Timeout for the request in seconds
120
        metadata: Additional metadata for the request
121

122
    Returns:
123
        ListIpOverridesResponse: List of IP overrides for the key
124

125
    Raises:
126
        google.api_core.exceptions.NotFound: If the key doesn't exist
127
        google.api_core.exceptions.PermissionDenied: If insufficient permissions
128
    """
129
```
130

131
## Request and Response Types
132

133
### IpOverrideData
134

135
```python { .api }
136
class IpOverrideData:
137
    """IP override configuration data."""
138
    ip: str                           # IP address or CIDR block
139
    override_type: OverrideType       # Type of override behavior
140

141
class OverrideType(Enum):
142
    """Types of IP override behavior."""
143
    OVERRIDE_TYPE_UNSPECIFIED = 0
144
    ALLOW = 1                         # Always allow (bypass normal assessment)
145
```
146

147
### Request Types
148

149
```python { .api }
150
class AddIpOverrideRequest:
151
    """Request message for adding an IP override."""
152
    parent: str                       # Required. Key name in format 'projects/{project}/keys/{key}'
153
    ip_override_data: IpOverrideData  # Required. IP override configuration
154

155
class AddIpOverrideResponse:
156
    """Response message for adding an IP override."""
157
    pass  # Empty response confirming addition
158

159
class RemoveIpOverrideRequest:
160
    """Request message for removing an IP override."""
161
    parent: str                       # Required. Key name
162
    ip_override_data: IpOverrideData  # Required. IP override to remove
163

164
class RemoveIpOverrideResponse:
165
    """Response message for removing an IP override."""
166
    pass  # Empty response confirming removal
167

168
class ListIpOverridesRequest:
169
    """Request message for listing IP overrides."""
170
    parent: str                       # Required. Key name
171
    page_size: int                   # Optional. Maximum results per page
172
    page_token: str                  # Optional. Pagination token
173

174
class ListIpOverridesResponse:
175
    """Response message for listing IP overrides."""
176
    ip_overrides: List[IpOverrideData]  # List of IP overrides
177
    next_page_token: str             # Token for next page of results
178
```
179

180
## Usage Examples
181

182
### Development Environment Setup
183

184
```python
185
# Add development office IP ranges
186
dev_office_override = IpOverrideData(
187
    ip="192.168.1.0/24",
188
    override_type=IpOverrideData.OverrideType.ALLOW
189
)
190

191
client.add_ip_override(
192
    parent="projects/your-project/keys/dev-key",
193
    ip_override_data=dev_office_override
194
)
195

196
# Add specific developer IP
197
dev_home_override = IpOverrideData(
198
    ip="203.0.113.42",
199
    override_type=IpOverrideData.OverrideType.ALLOW
200
)
201

202
client.add_ip_override(
203
    parent="projects/your-project/keys/dev-key",
204
    ip_override_data=dev_home_override
205
)
206
```
207

208
### Testing Environment Configuration
209

210
```python
211
# Add testing infrastructure IPs
212
test_server_override = IpOverrideData(
213
    ip="10.0.0.0/16",  # Internal test network
214
    override_type=IpOverrideData.OverrideType.ALLOW
215
)
216

217
client.add_ip_override(
218
    parent="projects/your-project/keys/test-key",
219
    ip_override_data=test_server_override
220
)
221

222
# Add CI/CD pipeline IPs
223
ci_override = IpOverrideData(
224
    ip="198.51.100.10",  # CI server IP
225
    override_type=IpOverrideData.OverrideType.ALLOW
226
)
227

228
client.add_ip_override(
229
    parent="projects/your-project/keys/test-key",
230
    ip_override_data=ci_override
231
)
232
```
233

234
### Managing IP Overrides
235

236
```python
237
# List all current overrides
238
list_request = recaptchaenterprise.ListIpOverridesRequest(
239
    parent="projects/your-project/keys/your-key"
240
)
241

242
response = client.list_ip_overrides(request=list_request)
243

244
print("Current IP overrides:")
245
for override in response.ip_overrides:
246
    print(f"  {override.ip} - {override.override_type}")
247

248
# Remove specific override
249
remove_request = recaptchaenterprise.RemoveIpOverrideRequest(
250
    parent="projects/your-project/keys/your-key",
251
    ip_override_data=IpOverrideData(
252
        ip="203.0.113.42",
253
        override_type=IpOverrideData.OverrideType.ALLOW
254
    )
255
)
256

257
client.remove_ip_override(request=remove_request)
258
print("IP override removed")
259
```
260

261
### Batch IP Override Management
262

263
```python
264
def add_multiple_ip_overrides(client, key_name, ip_addresses):
265
    """Add multiple IP overrides to a key."""
266
    for ip_addr in ip_addresses:
267
        override = IpOverrideData(
268
            ip=ip_addr,
269
            override_type=IpOverrideData.OverrideType.ALLOW
270
        )
271
        
272
        try:
273
            client.add_ip_override(
274
                parent=key_name,
275
                ip_override_data=override
276
            )
277
            print(f"Added override for {ip_addr}")
278
        except Exception as e:
279
            print(f"Failed to add override for {ip_addr}: {e}")
280

281
# Add development team IPs
282
dev_ips = [
283
    "203.0.113.10",
284
    "203.0.113.11", 
285
    "203.0.113.12",
286
    "192.168.0.0/24"
287
]
288

289
add_multiple_ip_overrides(
290
    client,
291
    "projects/your-project/keys/dev-key",
292
    dev_ips
293
)
294
```
295

296
### Cleanup and Maintenance
297

298
```python
299
def cleanup_ip_overrides(client, key_name):
300
    """Remove all IP overrides from a key."""
301
    # List all current overrides
302
    response = client.list_ip_overrides(parent=key_name)
303
    
304
    # Remove each override
305
    for override in response.ip_overrides:
306
        try:
307
            client.remove_ip_override(
308
                parent=key_name,
309
                ip_override_data=override
310
            )
311
            print(f"Removed override for {override.ip}")
312
        except Exception as e:
313
            print(f"Failed to remove override for {override.ip}: {e}")
314

315
# Clean up development key
316
cleanup_ip_overrides(client, "projects/your-project/keys/old-dev-key")
317
```
318

319
## IP Address Formats
320

321
### Supported Formats
322

323
```python
324
# Single IP address (IPv4)
325
single_ipv4 = IpOverrideData(
326
    ip="203.0.113.42",
327
    override_type=IpOverrideData.OverrideType.ALLOW
328
)
329

330
# CIDR block (IPv4)
331
cidr_ipv4 = IpOverrideData(
332
    ip="192.168.1.0/24",
333
    override_type=IpOverrideData.OverrideType.ALLOW
334
)
335

336
# Single IP address (IPv6)
337
single_ipv6 = IpOverrideData(
338
    ip="2001:db8::1",
339
    override_type=IpOverrideData.OverrideType.ALLOW
340
)
341

342
# CIDR block (IPv6)
343
cidr_ipv6 = IpOverrideData(
344
    ip="2001:db8::/32",
345
    override_type=IpOverrideData.OverrideType.ALLOW
346
)
347
```
348

349
### Common Network Ranges
350

351
```python
352
# Private IP ranges (RFC 1918)
353
private_ranges = [
354
    "10.0.0.0/8",      # Class A private
355
    "172.16.0.0/12",   # Class B private
356
    "192.168.0.0/16"   # Class C private
357
]
358

359
# Localhost ranges
360
localhost_ranges = [
361
    "127.0.0.0/8",     # IPv4 localhost
362
    "::1/128"          # IPv6 localhost
363
]
364

365
# Example corporate network
366
corporate_ranges = [
367
    "203.0.113.0/24",  # Office network
368
    "198.51.100.0/24", # Data center
369
    "192.0.2.0/24"     # Development lab
370
]
371
```
372

373
## Error Handling
374

375
```python
376
from google.api_core import exceptions
377

378
try:
379
    client.add_ip_override(request=request)
380
except exceptions.InvalidArgument as e:
381
    print(f"Invalid IP address format: {e}")
382
    # Check IP address syntax, CIDR notation
383
except exceptions.NotFound as e:
384
    print(f"Key not found: {e}")
385
    # Verify key name and project
386
except exceptions.AlreadyExists as e:
387
    print(f"IP override already exists: {e}")
388
    # Check for duplicate overrides
389

390
try:
391
    client.remove_ip_override(request=request)
392
except exceptions.NotFound as e:
393
    print(f"IP override not found: {e}")
394
    # Verify override exists before removal
395
```
396

397
## Best Practices
398

399
### Development Workflow
400
- Use separate keys for development and testing environments
401
- Add office and VPN IP ranges for development teams
402
- Include CI/CD system IPs for automated testing
403
- Document IP overrides with clear descriptions
404

405
### Security Considerations
406
- Regularly audit and cleanup unused IP overrides
407
- Use specific IP ranges rather than broad allowlists
408
- Monitor override usage through logging
409
- Remove overrides when no longer needed
410

411
### Testing Strategy
412
- Test applications with and without IP overrides
413
- Verify override behavior matches expectations
414
- Use IP overrides for controlled testing scenarios
415
- Validate production behavior without overrides
416

417
### Maintenance
418
- Regular review of active IP overrides
419
- Update IP ranges when network changes occur
420
- Remove overrides for decommissioned systems
421
- Document override purposes and ownership
422

423
## Integration with Development Workflows
424

425
### CI/CD Pipeline Integration
426

427
```python
428
import os
429

430
def setup_ci_ip_overrides():
431
    """Setup IP overrides for CI/CD environment."""
432
    client = recaptchaenterprise.RecaptchaEnterpriseServiceClient()
433
    
434
    ci_key = os.environ.get('RECAPTCHA_CI_KEY')
435
    ci_ips = os.environ.get('CI_IP_ADDRESSES', '').split(',')
436
    
437
    for ip in ci_ips:
438
        if ip.strip():
439
            override = IpOverrideData(
440
                ip=ip.strip(),
441
                override_type=IpOverrideData.OverrideType.ALLOW
442
            )
443
            
444
            client.add_ip_override(
445
                parent=ci_key,
446
                ip_override_data=override
447
            )
448

449
# Call during CI setup
450
setup_ci_ip_overrides()
451
```
452

453
### Local Development Helper
454

455
```python
456
def get_my_ip():
457
    """Get current public IP for development override."""
458
    import requests
459
    try:
460
        response = requests.get('https://api.ipify.org')
461
        return response.text.strip()
462
    except Exception:
463
        return None
464

465
def add_dev_ip_override(key_name):
466
    """Add current IP to development key overrides."""
467
    client = recaptchaenterprise.RecaptchaEnterpriseServiceClient()
468
    my_ip = get_my_ip()
469
    
470
    if my_ip:
471
        override = IpOverrideData(
472
            ip=my_ip,
473
            override_type=IpOverrideData.OverrideType.ALLOW
474
        )
475
        
476
        client.add_ip_override(
477
            parent=key_name,
478
            ip_override_data=override
479
        )
480
        print(f"Added IP override for {my_ip}")
481
    else:
482
        print("Could not determine current IP address")
483

484
# Add current IP to development key
485
add_dev_ip_override("projects/your-project/keys/dev-key")
486
```