zia-onboard-location

What this skill does

# 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:**

```text
zia_list_locations()
```text

**Check existing static IPs:**

```text
zia_list_static_ips()
```text

**Check existing VPN credentials:**

```text
zia_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.

```text
zia_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:**

```text
zia_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)

```text
zia_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)

```text
zia_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:**

```text
zia_get_vpn_credential(credential_id="<returned_id>")
```text

---

### Step 5: Create the Location

#### With UFQDN VPN Credentials

```text
zia_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

```text
zia_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:**

```text
zia_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).

```text
zia_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:

```text
zia_activate_configuration()
```text

---

### Step 8: Verify and Summarize

```text
Location 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 Zscaler
2. Verify traffic is flowing through the ZIA service
3. 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 Setting