zpa-application-segment-onboard

name	zpa-application_segment-onboard
description	End-to-end onboarding of a new application in Zscaler Private Access. Walks through the complete dependency chain: (1) App connector group, (2) Server group, (3) Segment group, (4) Application segment with domain names and ports, (5) Access policy rule to grant user/group access. Use when an administrator needs to make an internal application accessible through ZPA.

ZPA: Onboard Application

Keywords

onboard application, new application, add application, zpa application, publish application, application segment, private access, zpa setup, application access, zero trust application

Overview

Onboard a new application in Zscaler Private Access by walking through the full resource dependency chain. This skill creates all required ZPA constructs -- from connector groups to access policies -- ensuring the application is reachable and properly secured.

Use this skill when: An administrator wants to make a new internal application accessible through ZPA, or needs a guided walkthrough of the full ZPA application onboarding process.

---

Workflow

Follow this 8-step process for complete application onboarding. Step 0 is new — it picks the segmentation pattern, which then drives the right defaults in every later step.

Step 0: Classify the Application (baseline alignment)

Before creating anything, ask the administrator one question: what kind of application is this? The answer drives the defaults for AC group, server group, segment group, and health_reporting mode. Reference: ZPA Baseline Recommendations v1.0 §App Segmentation Recommendations.

Class	Examples	App Connector Group	Server Group	Health Reporting
Standard (general business app)	Wiki, ticketing, internal SaaS	Communal, per location	Communal per location, dynamic_discovery=True	ON_ACCESS
Sensitive / regulated (Finance, HR, Legal, PCI)	Workday, SAP HCM, financial systems	Dedicated isolated secure-enclave AC group	Dedicated SG bound to enclave AC group only	ON_ACCESS (use CONTINUOUS only for multi-DC critical)
Global (one app, accessed from everywhere)	AD DCs, NTP, internally LB'd web	All location AC groups	Global SG spanning all AC groups	ON_ACCESS
Discovery (wildcard for unknown apps)	*.corp.example.com	All communal AC groups	Global Discovery SG	NONE (high volume; per doc page 23)
SIPA (third-party IP allow-listed)	Vendor portals requiring fixed source IP	Dedicated SIPA AC group (separate egress IPs)	SIPA SG bound to SIPA AC group only	ON_ACCESS

Why this matters: the defaults in this skill historically used health_reporting="ON_ACCESS" for everything. That is wrong for Discovery (should be NONE to avoid probe storms across all communal AC groups) and may be wrong for critical multi-DC apps (where CONTINUOUS lets ZPA route users to the closest healthy server). Pick the class first, then the rest of the workflow uses the right defaults.

If the administrator is unsure, default to Standard and tell them they can re-classify later by updating the segment.

---

Step 1: Gather Application Details

Collect the following from the administrator:

Required:

• Application name
• Domain name(s) or IP address(es) the application runs on
• TCP and/or UDP port(s) (e.g., 443, 80, 8080, 3389)
• Who should have access (users, groups, or departments)

Optional:

• Description and purpose of the application
• Geographic location of the application servers
• Whether to reuse existing ZPA resources (connector groups, server groups, segment groups)
• Health check requirements
• Whether CNAME resolution is needed

---

Step 2: Set Up App Connector Group

Check for existing connector groups or create a new one.

List existing:

zpa_list_app_connector_groups()
```text

**Create if needed:**

```text
zpa_create_app_connector_group(
  name="<location>-Connectors",
  description="Connectors serving <application_name>",
  enabled=True,
  latitude="<lat>",
  longitude="<lon>",
  location="<datacenter_or_office>",
  country_code="<country>"
)
```text

Save the connector group `id` for the next step.

---

### Step 3: Set Up Server Group

Check for existing server groups or create a new one.

**List existing:**

```text
zpa_list_server_groups()
```text

**Create if needed:**

```text
zpa_create_server_group(
  name="<application_name>-Servers",
  description="Server group for <application_name>",
  app_connector_group_ids=["<connector_group_id>"],
  enabled=True,
  dynamic_discovery=True
)
```text

Save the server group `id` for Step 5.

---

### Step 4: Set Up Segment Group

Segment groups logically organize application segments. Check for an existing one or create a new one.

**List existing:**

```text
zpa_list_segment_groups()
```text

**Create if needed:**

```text
zpa_create_segment_group(
  name="<application_name>-Segment-Group",
  description="Segment group for <application_name>",
  enabled=True
)
```text

Save the segment group `id` for the next step.

---

### Step 5: Create Application Segment

This is the core resource that defines the application's reachability.

```text
zpa_create_application_segment(
  name="<application_name>",
  description="<description>",
  segment_group_id="<segment_group_id>",
  domain_names=["app.internal.example.com"],
  tcp_port_range=[{"from": "443", "to": "443"}, {"from": "80", "to": "80"}],
  server_group_ids=["<server_group_id>"],
  enabled=True,
  health_reporting="<from_step_0>",
  is_cname_enabled=True
)
```text

**Set `health_reporting` from the Step 0 classification:**

| Class | `health_reporting` value |
|---|---|
| Standard | `"ON_ACCESS"` |
| Sensitive (single-DC) | `"ON_ACCESS"` |
| Sensitive (multi-DC critical) | `"CONTINUOUS"` |
| Global | `"ON_ACCESS"` |
| **Discovery** | **`"NONE"`** |
| SIPA | `"ON_ACCESS"` |

`CONTINUOUS` generates one probe per connector in every bound AC group every interval — avoid it on segments bound to large AC groups.

**Port configuration options:**

For single ports:

```text
tcp_port_range=[{"from": "443", "to": "443"}]
```text

For port ranges:

```text
tcp_port_range=[{"from": "8000", "to": "8999"}]
```text

For UDP (e.g., DNS):

```text
udp_port_range=[{"from": "53", "to": "53"}]
```text

For mixed TCP+UDP:

```text
tcp_port_range=[{"from": "443", "to": "443"}],
udp_port_range=[{"from": "53", "to": "53"}]
```text

Save the application segment `id` for the access policy.

---

### Step 6: Create Access Policy Rule

Grant access to the application for specific users or groups.

First, look up the identity entities to reference in the policy:

```text
get_zpa_scim_group(search="<group_name>")
get_zpa_saml_attribute(search="<attribute_name>")
```text

Then create the access policy rule:

```text
zpa_create_access_policy_rule(
  name="Allow <group> to <application_name>",
  description="Grants <group> access to <application_name>",
  action_type="ALLOW",
  conditions={
    "operands": [
      {
        "objectType": "APP",
        "values": ["<application_segment_id>"]
      },
      {
        "objectType": "SCIM_GROUP",
        "values": ["<scim_group_id>"]
      }
    ]
  }
)
```text

**Common action types:**

- `ALLOW` -- permit access
- `DENY` -- block access
- `REQUIRE_APPROVAL` -- require explicit approval before access

---

### Step 7: Verify and Summarize

Verify each resource was created correctly:

```text
zpa_get_app_connector_group(group_id="<id>")
zpa_get_server_group(group_id="<id>")
zpa_get_segment_group(group_id="<id>")
zpa_get_application_segment(segment_id="<id>")
zpa_get_access_policy_rule(rule_id="<id>")
```text

#### Present Summary

```text
Application onboarding complete.

**Application:** <name>
- Domains: app.internal.example.com
- Ports: TCP 443, TCP 80
- Health Reporting: ON_ACCESS

**Infrastructure:**
- App Connector Group: <name> (ID: <id>)
- Server Group: <name> (ID: <id>)
- Segment Group: <name> (ID: <id>)

**Access Policy:**
- Rule: Allow <group> to <name>
- Action: ALLOW
- Granted To: <group_name>

**Resource Dependency Map:**
  App Connector Group ─► Server Group ─► Application Segment ◄─ Segment Group
                                                  │
                                                  ▼
                                         Access Policy Rule

**What happens next:**
1. Users in <group> can now reach <domain> on port(s) <ports> through ZPA
2. Traffic flows: User → ZPA Cloud → App Connector → Application Server
3. Monitor access in ZPA Admin Portal or via ZDX
```text

---

## Common Application Templates

### Web Application (HTTPS)

```text
domain_names=["webapp.internal.corp.com"]
tcp_port_range=[{"from": "443", "to": "443"}]
health_reporting="ON_ACCESS"
is_cname_enabled=True
```text

### Remote Desktop (RDP)

```text
domain_names=["rdp-server.internal.corp.com"]
tcp_port_range=[{"from": "3389", "to": "3389"}]
```text

### SSH Access

```text
domain_names=["bastion.internal.corp.com"]
tcp_port_range=[{"from": "22", "to": "22"}]
```text

### Database Access (PostgreSQL + MySQL)

```text
domain_names=["db.internal.corp.com"]
tcp_port_range=[{"from": "5432", "to": "5432"}, {"from": "3306", "to": "3306"}]
```text

### Multi-Service Application

```text
domain_names=["api.internal.corp.com", "web.internal.corp.com", "ws.internal.corp.com"]
tcp_port_range=[{"from": "80", "to": "80"}, {"from": "443", "to": "443"}, {"from": "8080", "to": "8443"}]
```text

---

## Edge Cases

### Reusing All Existing Resources

If the admin wants to add an application to existing infrastructure, skip Steps 2-4 and jump to Step 5 with existing IDs:

```text
zpa_list_server_groups()
zpa_list_segment_groups()

zpa_create_application_segment(
  name="New App",
  segment_group_id="<existing_segment_group_id>",
  server_group_ids=["<existing_server_group_id>"],
  domain_names=["newapp.internal.corp.com"],
  tcp_port_range=[{"from": "443", "to": "443"}]
)
```text

### Wildcard Domains

For applications with many subdomains:

```text
domain_names=["*.internal.corp.com"]
```text

### Multiple Access Policies

Create separate rules for different access levels:

```text
zpa_create_access_policy_rule(
  name="Admin Access - Full",
  action_type="ALLOW",
  conditions={...admin_conditions...}
)

zpa_create_access_policy_rule(
  name="Developer Access - Read Only Ports",
  action_type="ALLOW",
  conditions={...dev_conditions...}
)
```text

---

## When NOT to Use This Skill

- Modifying an existing application -- use individual update tools instead
- Just creating a server group -- use the "create-server-group" skill
- Troubleshooting connectivity -- use the "troubleshoot-user-connectivity" cross-product skill
- Listing or auditing existing applications -- use `zpa_list_application_segments()` directly

---

## Quick Reference

**Full dependency chain:**

1. `zpa_create_app_connector_group` (or reuse existing)
2. `zpa_create_server_group` (requires connector group IDs)
3. `zpa_create_segment_group` (or reuse existing)
4. `zpa_create_application_segment` (requires segment group ID + server group IDs)
5. `zpa_create_access_policy_rule` (references application segment)

**Verification tools:**

- `zpa_get_app_connector_group(group_id)`
- `zpa_get_server_group(group_id)`
- `zpa_get_segment_group(group_id)`
- `zpa_get_application_segment(segment_id)`
- `zpa_get_access_policy_rule(rule_id)`

**Identity lookup tools:**

- `get_zpa_scim_group(search)` -- find SCIM groups for policy conditions
- `get_zpa_saml_attribute(search)` -- find SAML attributes for policy conditions