Zscaler Security Configuration Guide: ZIA, ZPA, Admin Access and API Keys

A Zscaler tenant decides what every user can reach on the internet and inside private networks, so whoever controls its admin portal or API credentials controls the organisation's security policy. This guide covers the configuration that governs who and what can change Zscaler Internet Access (ZIA) and Zscaler Private Access (ZPA): admin roles, rank and scope, SSO-only admin sign-in, OneAPI clients in ZIdentity versus the legacy API key frameworks, App Connector provisioning keys, log streaming and the activation model. It is written for network, security and platform engineers who run or audit a Zscaler deployment. Product behaviour is taken from Zscaler's own documentation and official provider references; the guide explains settings and trade-offs and does not compare or recommend vendors.

Key takeaways

• Move automation to OneAPI clients. ZIdentity API clients use the OAuth 2.0 client credentials flow with a client secret or a private key, replacing the legacy ZIA pattern of admin username, password and obfuscated API key.
• Use rank and scope, not just roles. ZIA admin rank limits which admins and rule orders an admin can manage, and admin scope can restrict an admin to departments, locations or location groups.
• Force SSO for administrators. When SAML authentication for admins is enabled, password login can be switched off per admin, so joiners, leavers and MFA are governed by your identity provider.
• Treat provisioning keys as credentials. A ZPA provisioning key enrols App Connectors or Private Service Edges; cap its usage, restrict it by IP and disable it once enrolment is done.
• Stream logs and watch the activation path. Send ZIA logs through NSS and ZPA logs through the Log Streaming Service to your SIEM, and remember that ZIA changes stay pending until a tenant-wide activation.

How identity and access work in Zscaler

Zscaler has two quite different identity planes, and they are often managed by different teams.

• Administrators (control plane): people who sign in to the ZIA and ZPA admin portals. In ZIA each admin has a role (permissions), an optional rank and a scope. Admins can authenticate with a password or through SAML SSO to your identity provider. Auditor accounts are a separate read-only type that does not take a scope.
• API clients (control plane automation): on tenants migrated to ZIdentity, OneAPI clients obtain OAuth 2.0 access tokens with the client credentials flow, authenticating with a client secret or a signed JWT from a private key. Access is granted by API roles: in ZIA you create the role under Administration > Role Management > Add API Role, and it then appears in ZIdentity under Integration > API Resources (Sync Now forces the sync). Tenants not yet migrated use the legacy frameworks.
• End users and workloads (data plane): users authenticated to ZIA and ZPA through your IdP, usually via Client Connector, and infrastructure components such as App Connectors and Private Service Edges that enrol with provisioning keys and certificates. ZPA policies decide which users reach which application segments.

Admin roles and privileged access

A ZIA admin role combines access levels for functional areas with a list of feature permissions. The access areas include policy, alerting, dashboard, reporting, analysis, user names, device information and admin accounts, each set to read-write or read-only (or none where offered). Feature permissions include items such as SSL_POLICY, AUTHENTICATION_SETTINGS, ADVANCED_SETTINGS, NSS_CONFIGURATION, APIKEY_MANAGEMENT, USER_MANAGEMENT and REMOTE_ASSISTANCE_MANAGEMENT. Role types include organisation admin, Executive Insights and SD-WAN roles.

• SSO-only sign-in: once SAML authentication for admins is enabled, set password login to disallowed for each admin (the is_password_login_allowed attribute in the API), which forces SSO. Keep one or two break-glass admins with password login and a strong second factor, stored and monitored as emergency accounts. See the Break-Glass Account Guide.
• Auditors: use the auditor account type for internal audit and assessors instead of read-only copies of admin roles.
• Disable, do not share: admins have a disabled flag; disable leavers immediately and never share an admin login between people or between a person and a script.
• Microtenants in ZPA: where licensed, ZPA microtenants separate configuration for business units, so delegated admins and API clients only see their own resources.
• Admin MFA: require phishing-resistant MFA for admin sign-in at your identity provider. See the Identity Provider and SSO Security Guide and the SAML Security Guide.

Integrations, API tokens and service accounts

Zscaler configuration is increasingly managed as code through the official Terraform providers, SDKs and integrations with SIEM, SOAR and endpoint tools. Each of these is a non-human identity with policy-changing power.

OneAPI and ZIdentity

1. One API client per integration: separate clients for Terraform, SOAR playbooks and reporting jobs, so each can be revoked and attributed on its own.
2. Dedicated API roles: create narrow API roles in ZIA (and the equivalent in ZPA) for each client. A reporting integration needs read-only access; a SOAR playbook that blocks URLs needs custom URL category permissions, not admin account management.
3. Private key over secret: Zscaler's own provider guidance says to prefer private_key over client_secret where you can manage keys, and not to set both. Keep the key in a vault or HSM.
4. Inject credentials at runtime: read ZSCALER_CLIENT_ID and the secret or key from environment variables injected from a secrets manager at job start, ideally reached through the CI system's OIDC federation. Never hard-code them in provider blocks, tfvars or command-line arguments, which end up in shell history and CI logs.
5. Protect state: provider credentials are not written to Terraform state, but secrets set as resource attributes, such as VPN pre-shared keys or admin passwords, are stored there in plain text. Use an encrypted, access-controlled backend.
6. Rotate: the provider guidance recommends rotating static credentials every 90 days at most. Rotate immediately after any suspected exposure.

Legacy frameworks

• ZIA legacy API: authenticates with an admin's login name and password plus the API key, which the client obfuscates with a timestamp before sending. This ties automation to an admin account; create a dedicated API admin with a narrow role, exclude it from interactive use, and plan migration to OneAPI.
• ZPA legacy API: uses a client ID, client secret and customer ID. Assign each key an owner and an expiry review date, and replace with OneAPI clients when the tenant is migrated.
• API session timeout: the ZIA API session timeout defaults to 5 minutes and can be raised to 20. ZIA activates pending changes when an API session ends, so long automation runs can partially activate. Plan activation explicitly rather than leaving it to timeouts.

App Connectors and provisioning keys

• Scope each key: a provisioning key is tied to an association type (connector group, service edge group and others) and an enrolment certificate. Set max_usage to the number of components you intend to deploy and an IP allow list (ip_acl) for the network they enrol from.
• Disable after use: set the key to disabled once enrolment finishes and watch its usage count. An unexpected increase means a component you did not deploy has joined the tenant.
• Harden connector hosts: App Connectors make outbound connections to the Zscaler cloud and sit next to the applications they publish, so treat their hosts as sensitive servers: patch them, restrict local logins and monitor them as you would a jump host.

Integration credentials in SaaS control planes have been the entry point in real incidents. In the Cloudflare Thanksgiving Breach 2023, service credentials left unrotated after a third-party breach gave an attacker access to internal tools. The same discipline applies to Zscaler API clients: inventory, last-used data and rotation after any exposure. See the API Key Management Guide and the Service Account Security Guide.

Logging and detection

• ZIA Nanolog Streaming Service (NSS): NSS servers stream web logs (NSS_FOR_WEB) or firewall logs (NSS_FOR_FIREWALL) to your SIEM. Monitor NSS health; a server state of unhealthy means you are blind for that log type.
• ZPA Log Streaming Service (LSS): streams ZPA user activity, user status, App Connector status and related logs to a log receiver. Include connector status so that new or unexpected connectors are visible.
• Admin audit logs: both admin portals keep audit logs of admin actions. Export or query them regularly and correlate with your IdP sign-in logs for the same admins.
• Coverage: confirm every location, tunnel and Client Connector population appears in logs; gaps usually mean traffic is bypassing the service. See the SIEM Guide and the Log Management and Retention Guide.

Metrics that show the controls are working

• Admins with password login allowed: target only the documented break-glass accounts.
• Full-permission admins: absolute count, reviewed monthly.
• Integrations on OneAPI: percentage of integrations off the legacy API frameworks.
• API credentials older than 90 days: count of client secrets and legacy keys past the rotation target.
• Enabled provisioning keys with unused capacity: target zero outside planned deployments.
• Log stream health: hours of NSS or LSS outage per month.

Hardening baseline

Phased rollout

1. Inventory (week 1): export ZIA and ZPA admins, roles, ranks and scopes; list every OneAPI client, legacy API key and provisioning key with its owner and last use.
2. Admin sign-in (weeks 1 to 3): enable SAML for admins, pilot SSO-only on a few admins, then disallow password login for the rest. Roll back for an individual admin by re-allowing password login from a break-glass account.
3. Least privilege (weeks 2 to 6): enable admin rank, split policy editing from admin management and SSL policy, add scopes for regional admins and move assessors to auditor accounts.
4. Machine credentials (weeks 3 to 10): create OneAPI clients with narrow API roles, move secrets or keys into a secrets manager, cut over each integration, then delete the legacy keys. Keep the legacy key for one change window as a rollback.
5. Connectors (weeks 4 to 8): set max usage and IP restrictions on provisioning keys, disable keys that are not in use and baseline connector counts per group.
6. Logging (weeks 1 to 4, in parallel): confirm NSS and LSS feeds, add the alerts above and test each by making a controlled change in a non-production tenant or out of hours.
7. Codify (ongoing): manage policy as code with peer review, and control activation explicitly so that a single reviewed run activates changes.

Decision guidance

• Client secret or private key: choose a private key where your tooling can sign JWTs and keep the key in a vault; use a client secret only where a tool cannot, and rotate it more often.
• Small organisations with a few admins: SSO-only sign-in, two break-glass admins, one OneAPI client per tool and NSS to whatever log platform you have is a sound start.
• Large or federated organisations: admin rank, department and location scopes, ZPA microtenants for business units, an approval workflow for API role creation, and SIEM detections on every admin and API change.
• Activation: for teams using infrastructure as code, a single controlled activation after a reviewed run is easier to audit than activation by session timeout.

Common misconfigurations

• Automation on a person's admin account: legacy ZIA API scripts that use an engineer's own login break when they leave, and the password often sits in a script.
• Everyone with full permissions: roles cloned from the default full admin role, with no rank or scope, so any admin can edit any rule or create admins.
• Password login left on after SSO: SAML enabled, but admins can still sign in with a local password that skips IdP MFA and offboarding.
• Provisioning keys left open: high max usage, no IP restriction and still enabled months after the connectors were deployed.
• Secrets in state and CI logs: client secrets passed as command-line variables or VPN pre-shared keys in an unencrypted state file.
• Broad SSL inspection bypasses: exemptions added to fix one application and never reviewed, removing inspection for whole categories.

Framework mapping

Practitioner checklist

• Enable SAML for admin sign-in and disallow password login for all but documented break-glass admins.
• Enable admin rank and assign department or location scopes to regional admins.
• Restrict admin account management, API key management, authentication and SSL policy permissions to named owners.
• Replace legacy ZIA and ZPA API keys with OneAPI clients, one per integration, each with a narrow API role.
• Prefer private key authentication and inject credentials from a secrets manager at runtime.
• Keep Terraform state encrypted and access-controlled, and rotate static credentials at least every 90 days.
• Set max usage and IP restrictions on provisioning keys and disable them after enrolment.
• Stream ZIA logs through NSS and ZPA logs through LSS, and alert on admin, API client, connector and log stream changes.
• Review SSL inspection exemptions and URL allow lists quarterly.

Standards and references

• Zscaler: Automation Hub, getting started with OneAPI
• Zscaler: ZIA Terraform provider documentation
• Zscaler: ZPA Terraform provider documentation
• NIST: SP 800-53 Rev. 5
• NIST: Cybersecurity Framework 2.0
• MITRE ATT&CK: Additional Cloud Credentials

Related NHI Mgmt Group resources: SASE and SSE Guide · ZTNA Guide · API Key Management Guide · Cloudflare Security Configuration Guide