Lessons · ZPA series · Scenarios
This lesson is ticket triage: one user, one FQDN, one timestamp, one status code. Architecture and inside-out tunnels live on fundamentals. FQDN/port object design is Application Segments. Enrollment, provisioning key and broker TLS is App Connector troubleshooting.
ZPA fundamentals · App segments · App Connector troubleshooting · Access Policy
ZPA is a brokered user-to-app path, default deny. Client Connector must show Private Access / ZPA_State=ON. Access Policy must Allow the SAML/SCIM group for that Application Segment. A healthy App Connector is then selected from the Server Group’s Connector Group and must resolve and connect to the FQDN/port in the segment. Proof: Logs › Insights › Diagnostics › User Activity (Access Policy Name, Application Segment, App Connector, Internal Status Code) plus sudo systemctl status zpa-connector and connector-side nslookup / nc. Lab: finance.lab.internal TCP 443, segment as-finance, connector ac-dc1-01.
Why a green connector is not the app
The day-one ticket is always the same: “Connector is green, so ZPA is broken.” Wrong. Health on Configuration & Control › Private Infrastructure › App Connector Management › App Connectors means ac-dc1-01 enrolled and holds a control connection to a ZPA Service Edge on TCP 443. It does not mean the Server Group includes that Connector Group, that as-finance lists TCP 443, or that policy allowed this user.
Four silent-fail states look identical from the laptop (timeout or “can’t reach app”):
- ZIA works.
ZPA_Stateis OFF or the app profile has no Private Access entitlement. User Activity is empty because no private-app request was made. - Tile appears; click returns deny. Status
BRK_MT_SETUP_FAIL_REJECTED_BY_POLICYorBRK_MT_SETUP_FAIL_NO_POLICY_FOUND. Connector health is irrelevant until policy Allows. - Policy Allows; no App Connector is selected for that Server Group. “No healthy connector” for this app while other private apps work.
- A connector is selected; it cannot resolve
finance.lab.internalor TCP 443 is filtered on the DC firewall. Health stays green.
If ZCC never shows the finance tile, the break is entitlement, SCIM group, or Access Policy criteria. Restarting zpa-connector burns an hour and leaves User Activity still empty.
Four objects on every ticket
Keep the four names separate. Mixing them is how “open it like a VPN” answers get written.
Client Connector
ZCC app profile with Private Access. Proof: ZCC UI Private Access = connected, Windows ZPA_State=ON. ZIA green is a different service.
Access Policy
Default deny. Criteria: SAML attributes / SCIM groups, posture, client type, Application Segment / Segment Group. Action Allow or Block. Rule order matters.
Application Segment
as-finance = FQDN/IP + TCP/UDP ports. Bound to Segment Group sg-finance and Server Group srv-dc1. More-specific FQDN wins; missing port does not fall through.
App Connector
ac-dc1-01 in Connector Group acg-dc1. Outbound-only to the Service Edge. It DNS-resolves and connects to the private app. Green = cloud, not backend.
Client Connector must be entitled. Policy must Allow this user to this segment. A healthy connector in the bound Connector Group must be selected. That connector must resolve and reach the FQDN and port. No selected connector, no app — even if the dashboard is green.
Symptom to status code
One user, one FQDN, one timestamp. Open Diagnostics before you edit. Status codes are prefixed: CLT Client Connector, SE Service Edge / policy, AC App Connector, CA Central Authority.
Read left → right, then the gold bar. Empty User Activity is a Client Connector problem. A deny code is policy. A selected connector with a later AC error is path, not policy.
| Status / symptom | Layer | First move |
|---|---|---|
| ZCC signed in, no Private Access, User Activity empty | Client Connector | App profile / ZPA entitlement. Compare a working user. Re-auth after profile change. |
BRK_MT_SETUP_FAIL_REJECTED_BY_POLICY | Access Policy | Read matched rule. SAML/SCIM group vs GRP-FINANCE. Do not touch connectors. |
BRK_MT_SETUP_FAIL_REJECTED_BY_POLICY_POSTURE_FAILED | Posture on policy | Failed check (OS / disk / EDR). Remediate device or scoped exception — not the main Allow rule. |
BRK_MT_SETUP_FAIL_NO_POLICY_FOUND | Policy or disabled object | No Allow for this app, or Application Segment / Segment Group disabled. |
BRK_MT_SETUP_FAIL_SAML_EXPIRED | Timeout policy | User re-authenticates. Not a connector outage. |
| No App Connector on the User Activity row | Binding | Server Group srv-dc1 must list Connector Group acg-dc1 with a healthy member. |
AST_MT_SETUP_ERR_APP_NOT_FOUND | Connector config | Connector cannot find the application in its config. Re-auth; check segment enabled and synced. |
AST_MT_SETUP_ERR_AST_CFG_DISABLE / pause-for-upgrade | App Connector | Disabled in Admin Portal, or paused for upgrade. Wait or enable. Do not rewrite the FQDN. |
Which layer to open first
Pick the layer the status code already named. Editing the other three is how you get a second outage.
Four columns, four tickets. Policy deny is not a DNS problem. Missing port is not a connector outage.
| Need | Use | Skip |
|---|---|---|
| ZIA works, no ZPA apps | ZCC app profile with Private Access; tenant mapping; client version | Access Policy edits. No request exists yet. |
| One user denied, peers work | Compare SAML/SCIM groups, posture, rule order for ap-finance-allow | Restarting ac-dc1-01. |
| One app: no healthy connector; others fine | That app’s Server Group → Connector Group bind; capacity in acg-dc1 | Moving the app into a catch-all Connector Group “to make it work.” |
| Works by IP, fails by name | DNS from the connector. Segment must include the FQDN. | Blaming laptop DNS. ZPA does not use the user’s resolver for the backend lookup. |
| Login 443 works, API 8443 fails | Add TCP 8443 to as-finance (or a dedicated segment) | Wildcard domain + all ports. |
Runbook Side A / B / C
Side A is Client Connector entitlement. Side B is Access Policy plus Application Segment. Side C is App Connector selection and backend proof. Do not start at C because the dashboard is green.
Side A — Client Connector
-
Private Access is a different service from ZIA
On the endpoint: ZCC shows Private Access connected. Windows registry
ZPA_State=ON(notOFF,SERVER_DOWN_ERROR,INTERNET_UNREACHABLE_ERROR). Capture app profile name, cloud, client version. Source: Zscaler Help — Zscaler Client Connector: Windows Registry Keys. -
Compare a working user
Same IdP group
GRP-FINANCE, same ZCC app profile, same device posture class. If the working user has Private Access and this user does not, stop — policy and connectors will not invent entitlement.
rem ZCC UI: Private Access = connected, finance tile listed reg query HKLM\SOFTWARE\Zscaler\Zscaler /v ZPA_State rem expect ZPA_State REG_SZ ON nslookup finance.lab.internal rem laptop DNS is NOT the ZPA backend resolver — record it only to compare later
Side B — Access Policy then Application Segment
Policy › Access Policy › ap-finance-allow
ap-finance-allow
Source: Zscaler Help — About Access Policy; Viewing Policy Usage Details. Default deny sits under the last Allow. A disabled Application Segment or Segment Group returns BRK_MT_SETUP_FAIL_NO_POLICY_FOUND even when this rule looks correct.
-
Read the deny, do not guess it
Logs › Insights › Diagnostics, Log Type User Activity. Filter user +
finance.lab.internal+ the ticket timestamp. Copy Access Policy Name, Action, Application Segment, Internal Status Code. If Action is Block /REJECTED_BY_POLICY, fix criteria or order. Re-authenticate after SCIM catch-up — ZPA evaluates the group it has, not the IdP UI from ten minutes ago. -
Segment FQDN and ports — after policy Allows
as-finance: FQDNfinance.lab.internal, TCP 443 (and 8443 if the API is in scope). Server Groupsrv-dc1. Do not add*.lab.internalTCP 1–65535 to “cover” a missing port. If a more-specific segment already owns the FQDN with a short port list, Client Connector matches that segment and drops unmatched ports.
Applications › Application Segments › as-finance
as-finance
Source: Zscaler Help — Configuring Defined Application Segments; About Application Access. Server Group must include the App Connector Group that can actually reach 10.20.20.80. Health Reporting On Access / Continuous is not a substitute for nc from the connector.
Side C — prove the connector
-
Was a connector selected?
Same User Activity row: App Connector name must be
ac-dc1-01(or another member ofacg-dc1). Empty name = Server Group missing the Connector Group, all members unhealthy, or the connector disabled / paused for upgrade. Check App Connector Status diagnostics and App Connectors last-seen. Source: Zscaler Help — Viewing App Connector Status Diagnostics; Managing Deployed App Connectors. -
Control plane vs data plane
On
ac-dc1-01:sudo systemctl status zpa-connectormust show parent andzpa-connector-child. Parent-only is not healthy. Control connection to the broker on TCP 443 is the green dashboard. Then, from that same host, resolve and connect to the app. -
Connector-side DNS and port
nslookup finance.lab.internalmust return 10.20.20.80 from the DC resolver thezscaleruser can read (/etc/resolv.confpermissions).nc -vz finance.lab.internal 443must succeed. Laptop DNS success is not this test.
sudo systemctl status zpa-connector # Active: active (running) # CGroup must list zpa-connector AND zpa-connector-child timedatectl status # NTP in sync — skew breaks enrollment / TLS nslookup finance.lab.internal # 10.20.20.80 — if NXDOMAIN here, laptop nslookup is irrelevant nc -vz finance.lab.internal 443 nc -vz finance.lab.internal 8443 # Connection to 10.20.20.80 443 port [tcp/https] succeeded! sudo tail -n 200 /var/log/messages | grep -i zpa
User Activity for the same user/app/timestamp: Action Allow, Access Policy ap-finance-allow, Application Segment as-finance, App Connector ac-dc1-01, Internal Status Code a setup/terminate success (not REJECTED_BY_POLICY). Connector nc to 443 succeeds. That is the close — not a green Health widget.
One flow after go-live
ram.dixit@techclick.in on ZCC, ZPA_State=ON, opens https://finance.lab.internal. Client Connector matches Application Segment as-finance (FQDN + TCP 443). Service Edge evaluates Access Policy: SAML group GRP-FINANCE hits ap-finance-allow → Allow. Server Group srv-dc1 names Connector Group acg-dc1. Healthy ac-dc1-01 is selected. Connector resolves finance.lab.internal to 10.20.20.80 and opens TCP 443. Microtunnel completes. User Activity records policy, segment, connector, status.
If a more-specific segment as-finance-api exists for the same FQDN with only TCP 8843, a :443 request matches that segment and dies on the missing port. Client Connector does not retry the broader as-finance. That is the overlapping-segment ticket — clean the FQDN/port matrix, do not stack another Allow rule.
Logs › Insights › Diagnostics · Log Type: User Activity
Session · finance.lab.internal
Source: Zscaler Help — Accessing User Activity Diagnostics; Accessing Live Logs (Analytics › Live Logs for the retest window). BRK_MT_TERMINATED is a completed session, not a crash. If Action is Block, stop at policy. If App Connector is blank, stop at binding. Live Logs during a controlled retest beats scrolling 24h of Diagnostics.
Traps + proof
| Symptom | Likely cause | Proof |
|---|---|---|
| ZIA works, no ZPA tile | App profile without Private Access; ZPA_State OFF | Registry / ZCC UI. User Activity empty for that window. |
| Tile missing for one user | SCIM/SAML group not on the user ZPA sees; nested group never flattened | Compare IdP vs ZPA user record. Re-auth after sync. Do not clone a per-user Allow. |
| Click → access denied | Matched Block, posture fail, or no policy / disabled segment | REJECTED_BY_POLICY / _POSTURE_FAILED / NO_POLICY_FOUND on User Activity. |
| Connector green, one app down | Wrong Connector Group on that Server Group, or backend path | User Activity App Connector blank vs named. Then nc from that host. |
| Works by IP, not FQDN | Connector DNS / missing FQDN on the segment | nslookup on ac-dc1-01 vs laptop. Segment domain list. |
| 443 works, 8443 fails | Port not on the matched segment; or a more-specific FQDN stole the match | User Activity Application:Port. Audit overlapping segments. |
| All private apps die | Connector outbound 443 / NTP / enrollment, not one segment | App Connector Status: Disconnected. systemctl status parent-only or stopped. |
| BYOD blocked, managed laptop works | Posture on the Allow rule is doing its job | REJECTED_BY_POLICY_POSTURE_FAILED. Scoped Browser Access / VDI — do not strip posture from production. |
That is a VPN. ZPA’s contract is named FQDN + named ports + named Connector Group. Wildcards plus all ports hide the next overlap and dump unrelated apps onto the same policy. Add the missing port or split the segment.
- Working user vs affected user: ZCC profile,
ZPA_State, IdP/SCIM group, posture class. - Launch
https://finance.lab.internalonce. Note UTC timestamp. - Diagnostics › User Activity: Allow,
ap-finance-allow,as-finance,ac-dc1-01, Server 10.20.20.80. - On
ac-dc1-01: parent+child, NTP,nslookup finance.lab.internal→ 10.20.20.80,nc -vz443 (and 8443 if in the segment). - If you edited policy or SCIM: user re-auth, then the same launch. Old sessions and stale groups are not a new proof.
Knowledge check
Six judgment items. Submit once. Reasons point back at the section to re-read.
Sources
- Zscaler Help — Understanding Private Access Session Status Codes (CLT / SE / AC prefixes;
BRK_MT_SETUP_FAIL_REJECTED_BY_POLICY,_POSTURE_FAILED,NO_POLICY_FOUND,AST_MT_SETUP_ERR_APP_NOT_FOUND, pause-for-upgrade, connector disabled) - Zscaler Help — Understanding Application Access / About Application Access (more-specific FQDN wins; missing port does not fall through)
- Zscaler Help — Configuring Defined Application Segments (FQDN, ports, health reporting, ICMP caveats)
- Zscaler Help — Accessing User Activity Diagnostics; Accessing Live Logs (Analytics › Live Logs; Access Policy Name, Application Segment, App Connector)
- Zscaler Help — Viewing App Connector Status Diagnostics
- Zscaler Help — Managing Deployed App Connectors (
systemctl status zpa-connector, parent + child) - Zscaler Help — Zscaler Client Connector: Windows Registry Keys (
ZPA_State) - Zscaler Help — Troubleshooting App Connectors; ZPA App Connector troubleshooting runbook
Related: ZPA fundamentals · Application Segments · App Connector troubleshooting · Access Policy · DNS and app discovery · Connector groups and Service Edge · Connector green, app down