ZIA: Onboard Location
Keywords
onboard location, new location, add location, branch office, zia location, traffic forwarding, vpn credentials, static ip, ipsec tunnel, site onboarding, sub-location, office setup
Overview
Onboard a new location in Zscaler Internet Access by walking through the full traffic forwarding dependency chain. Locations require either static IPs or VPN credentials (or both) before they can be created. This skill covers both UFQDN-based and IP-based VPN credential flows, sub-location creation, and location configuration options.
Use this skill when: An administrator wants to add a new office, branch, or datacenter location to ZIA, configure traffic forwarding for a new site, or set up IPSec VPN tunnels for location-based security.
Dependency Chain
text
Static IP (optional, required for IP-based VPN) │ ▼VPN Credentials (UFQDN or IP type) │ ▼Location (references VPN credentials and/or static IPs) │ ▼Sub-Location (optional, references parent location)```text
**Two flows:**
- **UFQDN flow** (simpler): Create VPN credential (UFQDN) -> Create location with VPN credential- **IP flow** (full chain): Create static IP -> Create VPN credential (IP) referencing static IP -> Create location with both static IP and VPN credential
---
## Workflow
### Step 1: Gather Site Information
Ask the administrator:
**Required:**
- Location name (e.g., "USA_SJC_37", "London_Office_01")- Country (e.g., "UNITED_STATES", "CANADA", "UNITED_KINGDOM")- Timezone (e.g., "UNITED_STATES_AMERICA_LOS_ANGELES", "CANADA_AMERICA_VANCOUVER")- Traffic forwarding method: UFQDN-based VPN or IP-based VPN
**For UFQDN-based VPN:**
- FQDN identifier (e.g., "<[email protected]>")- Pre-shared key for the IPSec tunnel
**For IP-based VPN:**
- Public IP address of the site's egress point- Pre-shared key for the IPSec tunnel
**Optional:**
- Description- State (e.g., "California")- Profile: `CORPORATE`, `SERVER`, `GUESTWIFI`, `IOT`, `WORKLOAD`, or `NONE`- Authentication settings (auth_required, idle_time_in_minutes)- Firewall/IPS settings (ofw_enabled, ips_control)- Bandwidth limits (up_bandwidth, dn_bandwidth)- Surrogate IP settings- XFF forwarding
---
### Step 2: Check for Existing Resources
Before creating anything, list existing resources to avoid duplicates.
**Check existing locations:**
```textzia_list_locations()```text
**Check existing static IPs:**
```textzia_list_static_ips()```text
**Check existing VPN credentials:**
```textzia_list_vpn_credentials()```text
---
### Step 3: Create Static IP (IP-based VPN only)
If using IP-based VPN credentials, the static IP must be created first.
```textzia_create_static_ip( ip_address="203.0.113.10", routable_ip=True, comment="SJC-37 Office Egress IP", geo_override=False)```text
Save the returned `ip_address` and `id` for the next steps.
**Verify:**
```textzia_get_static_ip(static_ip_id="<returned_id>")```text
**Note:** Geolocation is automatically determined from the IP address. Set `geo_override=True` with explicit `latitude`/`longitude` only if you need custom coordinates.
---
### Step 4: Create VPN Credentials
#### Option A: UFQDN-Based VPN (simpler, no static IP needed)
```textzia_create_vpn_credential( credential_type="UFQDN", fqdn="[email protected]", pre_shared_key="<pre_shared_key>", comments="USA - San Jose IPSec Tunnel")```text
Save the returned `id` and `type` for the location creation.
#### Option B: IP-Based VPN (requires static IP from Step 3)
```textzia_create_vpn_credential( credential_type="IP", ip_address="203.0.113.10", pre_shared_key="<pre_shared_key>", comments="USA - San Jose IPSec Tunnel")```text
Save the returned `id` and `type`.
**Verify:**
```textzia_get_vpn_credential(credential_id="<returned_id>")```text
---
### Step 5: Create the Location
#### With UFQDN VPN Credentials
```textzia_create_location( location={ "name": "USA_SJC_37", "description": "San Jose Office - Branch 37", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_LOS_ANGELES", "state": "California", "profile": "CORPORATE", "authRequired": True, "idleTimeInMinutes": 720, "displayTimeUnit": "HOUR", "surrogateIP": True, "xffForwardEnabled": True, "ofwEnabled": True, "ipsControl": True, "vpnCredentials": [ { "id": <vpn_credential_id>, "type": "UFQDN" } ] })```text
#### With IP VPN Credentials and Static IP
```textzia_create_location( location={ "name": "USA_SJC_37", "description": "San Jose Office - Branch 37", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_LOS_ANGELES", "state": "California", "profile": "CORPORATE", "authRequired": True, "idleTimeInMinutes": 720, "displayTimeUnit": "HOUR", "surrogateIP": True, "xffForwardEnabled": True, "ofwEnabled": True, "ipsControl": True, "ipAddresses": ["203.0.113.10"], "vpnCredentials": [ { "id": <vpn_credential_id>, "type": "IP", "ipAddress": "203.0.113.10" } ] })```text
Save the returned location `id` for sub-location creation if needed.
**Verify:**
```textzia_get_location(location_id="<returned_id>")```text
---
### Step 6: Create Sub-Location (Optional)
Sub-locations segment traffic within a parent location (e.g., by subnet or VLAN).
```textzia_create_location( location={ "name": "USA_SJC37_Office-Branch01", "description": "SJC37 Office Branch 01 - Engineering VLAN", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_LOS_ANGELES", "profile": "CORPORATE", "parentId": <parent_location_id>, "authRequired": True, "idleTimeInMinutes": 720, "displayTimeUnit": "HOUR", "surrogateIP": True, "ofwEnabled": True, "ipAddresses": ["10.5.0.0-10.5.255.255"], "upBandwidth": 10000, "dnBandwidth": 10000 })```text
**Sub-location notes:**
- Must reference `parentId` of an existing location- Uses internal IP ranges (e.g., `10.5.0.0-10.5.255.255`) not public IPs- Can have different bandwidth limits and policy settings than the parent- Inherits VPN credentials from the parent location
---
### Step 7: Activate Configuration
After creating locations, activate the configuration to push changes to the Zscaler cloud:
```textzia_activate_configuration()```text
---
### Step 8: Verify and Summarize
```textLocation onboarding complete.
**Location:** USA_SJC_37- Country: United States- Timezone: US/Pacific- Profile: CORPORATE- Firewall: Enabled- IPS: Enabled- XFF Forwarding: Enabled
**Traffic Forwarding:**- Static IP: 203.0.113.10 (ID: <id>)- VPN Credential: IP-based (ID: <id>)- IPSec Tunnel: Configured
**Sub-Location:**- Name: USA_SJC37_Office-Branch01- IP Range: 10.5.0.0 - 10.5.255.255- Bandwidth: 10Mbps up / 10Mbps down
**Configuration:** Activated
**Next Steps:**1. Configure IPSec tunnel on the branch router pointing to Zscaler2. Verify traffic is flowing through the ZIA service3. Assign the location to URL filtering, firewall, or DLP rules if needed```text
---
## Location Configuration Options
### Profile Types
| Profile | Use Case ||---|---|| `CORPORATE` | Standard corporate office || `SERVER` | Data center or server farm || `GUESTWIFI` | Guest wireless network || `IOT` | IoT device network || `WORKLOAD` | Cloud workload (AWS, Azure) || `NONE` | Unassigned (default) |
### Security Settings
| Setting | Description | Recommended ||---|---|---|| `authRequired` | Enforce user authentication | `True` for CORPORATE || `ofwEnabled` | Enable cloud firewall | `True` || `ipsControl` | Enable IPS (requires firewall) | `True` || `surrogateIP` | Map users to device IPs | `True` for auth || `xffForwardEnabled` | Forward X-Forwarded-For header | `True` || `cautionEnabled` | Show caution notifications | Per policy |
### Authentication Settings
| Setting | Description ||---|---|| `idleTimeInMinutes` | Surrogate IP idle timeout (e.g., 720 = 12 hours) || `displayTimeUnit` | Display unit: `MINUTE`, `HOUR`, `DAY` || `surrogateRefreshTimeInMinutes` | Re-validate surrogate IP interval || `digestAuthEnabled` | Enable digest authentication || `kerberosAuth` | Enable Kerberos authentication |
---
## Ready-to-Use Templates
### Corporate Office (UFQDN VPN)
```python# Step 1: VPN Credentialzia_create_vpn_credential( credential_type="UFQDN", fqdn="[email protected]", pre_shared_key="<psk>", comments="London Office IPSec")
# Step 2: Locationzia_create_location(location={ "name": "UK_London_01", "description": "London Head Office", "country": "UNITED_KINGDOM", "tz": "EUROPE_LONDON", "profile": "CORPORATE", "authRequired": True, "idleTimeInMinutes": 720, "displayTimeUnit": "HOUR", "surrogateIP": True, "xffForwardEnabled": True, "ofwEnabled": True, "ipsControl": True, "vpnCredentials": [{"id": <vpn_id>, "type": "UFQDN"}]})```text
### Data Center (IP VPN with Static IP)
```python# Step 1: Static IPzia_create_static_ip( ip_address="198.51.100.1", routable_ip=True, comment="DC East Egress")
# Step 2: VPN Credentialzia_create_vpn_credential( credential_type="IP", ip_address="198.51.100.1", pre_shared_key="<psk>", comments="DC East IPSec")
# Step 3: Locationzia_create_location(location={ "name": "US_DC_East_01", "description": "US East Data Center", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_NEW_YORK", "profile": "SERVER", "ofwEnabled": True, "ipsControl": True, "ipAddresses": ["198.51.100.1"], "vpnCredentials": [{"id": <vpn_id>, "type": "IP", "ipAddress": "198.51.100.1"}]})```text
### Guest WiFi (minimal security)
```pythonzia_create_location(location={ "name": "US_SJC_GuestWifi", "description": "Guest WiFi - San Jose Office", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_LOS_ANGELES", "profile": "GUESTWIFI", "parentId": <parent_location_id>, "authRequired": False, "ofwEnabled": True, "ipsControl": False, "ipAddresses": ["10.100.0.0-10.100.255.255"]})```text
---
## Edge Cases
### Location Without VPN Credentials
A location can be created with only `ipAddresses` (no VPN credentials). This is for sites forwarding traffic via GRE tunnels or proxy chaining rather than IPSec VPN:
```textzia_create_location(location={ "name": "US_SJC_GRE", "country": "UNITED_STATES", "tz": "UNITED_STATES_AMERICA_LOS_ANGELES", "ipAddresses": ["203.0.113.10"]})```text
### Multiple VPN Credentials per Location
A location can have multiple VPN credentials for redundancy:
```json"vpnCredentials": [ {"id": <primary_vpn_id>, "type": "UFQDN"}, {"id": <secondary_vpn_id>, "type": "UFQDN"}]```text
### Sub-Location with Bandwidth Control
Sub-locations can enforce bandwidth limits in bytes:
```json"upBandwidth": 10000,"dnBandwidth": 10000```text
A value of `0` means no bandwidth enforcement.
---
## When NOT to Use This Skill
- Just creating a static IP (not a full location) -- use `zia_create_static_ip` directly- Just creating VPN credentials (not a location) -- use `zia_create_vpn_credential` directly- Looking up existing locations -- use `zia_list_locations` directly- Creating GRE tunnels -- use `zia_create_gre_tunnel` directly- Creating URL filtering or firewall rules for a location -- use the respective rule creation tools
---
## Quick Reference
**Dependency chain:**
1. `zia_create_static_ip(ip_address, ...)` -- only for IP-based VPN2. `zia_create_vpn_credential(credential_type, ...)` -- UFQDN or IP3. `zia_create_location(location={...})` -- the location itself4. `zia_create_location(location={..., "parentId": ...})` -- optional sub-location5. `zia_activate_configuration()` -- push changes live
**Verification tools:**
- `zia_list_locations()` -- list all locations- `zia_get_location(location_id)` -- get location details- `zia_list_static_ips()` -- list all static IPs- `zia_get_static_ip(static_ip_id)` -- get static IP details- `zia_list_vpn_credentials()` -- list all VPN credentials- `zia_get_vpn_credential(credential_id)` -- get credential details- `zia_get_activation_status()` -- check activation status
**VPN types:**
- `UFQDN`: Simpler, no static IP needed, identified by FQDN- `IP`: Requires static IP first, identified by IP address
