This page covers the Zscaler Internet Access integration, which connects to the ZIA API directly. The separate Zscaler integration uses ZIA’s SCIM endpoint instead - see Zscaler for that setup.
What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your ZIA tenant:- Users - the users ZIA applies policy to, with name, email, and whether the account is enabled. Users that ZIA reports as disabled or deleted appear as disabled. Users ZIA flags as administrators are marked as admins.
- Administrators - the administrator accounts that sign in to the ZIA Admin Portal, with login name, email, enabled status, and admin role. ZIA keeps administrators separate from users, so Oleria shows them as separate accounts, even when a user and an administrator share an email address.
- Groups - ZIA user groups, with their description. Groups synced from your identity provider are distinguished from groups created in ZIA.
- Admin roles - the roles that control what administrators can do in ZIA. Predefined roles are distinguished from custom roles.
- Group membership - which users belong to each group.
- Role assignments - which admin role each administrator holds.
Prerequisites
- A Zscaler Internet Access tenant. The OAuth2 (Client Credentials) method requires a commercial Zscaler cloud.
- For the OAuth2 (Client Credentials) method: access to the ZIA Admin Portal to create an API role, and to the ZIdentity Admin Portal to create an API client. Your tenant must use ZIdentity for OneAPI.
- For the Username & Password method: a ZIA administrator account for Oleria, and an admin role that includes the Authentication Configuration functional scope to view or create the ZIA API key.
- Admin access on the Oleria platform to add a new integration.
Permissions
The API role (OAuth2) or the administrator’s admin role (Username & Password) controls what Oleria can read and change:
Only User Management is required to connect. If the role can’t read administrators, groups, or admin roles, Oleria still connects and syncs users, and marks the sync as partially completed.
Use a dedicated API role or administrator account for this integration rather than a person’s account. With Username & Password, each change Oleria makes is activated in ZIA, which also activates any edits that same administrator saved in the Admin Portal but didn’t activate.
Create credentials in Zscaler
Choose one authentication method. OAuth2 (Client Credentials) is the default.- OAuth2 (Client Credentials)
- Username & Password
1
Create an API role in ZIA
In the ZIA Admin Portal, go to Administration -> Role Management and select Add API Role. Give it a name such as
Oleria, set the permissions listed in Permissions, and select Save. Then activate the change in ZIA.2
Create an API client in ZIdentity
In the ZIdentity Admin Portal, go to Administration -> API Configuration -> OneAPI -> API Clients and select Add API Client. Give the client a name such as
Oleria.3
Add a client secret
Under client authentication, add a Secret. Copy the secret: Zscaler shows it only once. Note its expiry date, because you need to update the secret in Oleria before it expires.
4
Assign the API role
Under resources, select the ZIA API role you created, then select Save.
5
Copy the client details
Copy the API client’s Client ID. Note your ZIdentity vanity domain - the subdomain of your ZIdentity sign-in address, for example
acme in acme.zslogin.net.Connect Zscaler Internet Access to Oleria
1
Open the integration
Go to your Oleria workspace, select Integrations -> select Zscaler Internet Access.
2
Complete the connection form
Select your authentication method, then fill in the fields for that method:
3
Authenticate
Select Authenticate to validate and save the integration. Oleria requests an access token (OAuth2) or signs in to ZIA (Username & Password), then reads users, groups, administrators, and admin roles to confirm access. Oleria refuses to connect if it can’t read users.
When you edit the integration later, you can change only the Client Secret, Password, or API Key. To change the authentication method, vanity domain, client ID, username, or cloud, connect a new instance.
Verify the integration
Confirm the Zscaler Internet Access instance appears on the Connected tab of your Oleria Integrations page. After the first sync completes, review the discovered users, administrators, groups, and admin roles in your Oleria workspace. If the sync is marked as partially completed, the API role or admin role can’t read administrators, groups, or admin roles. Add the missing permission from Permissions in ZIA, activate the change, and the next sync includes them.If you rotate the client secret, change the administrator’s password, or regenerate the API key, update it in Oleria by editing the integration. Discovery stops until you do.
Remediation actions
Oleria can take the following actions in ZIA:
ZIA saves changes as pending until they’re activated. Oleria activates each change right away, so it takes effect without anyone activating it in the Admin Portal. Activation publishes all of the integration’s pending changes, which can include changes Oleria didn’t make: with Username & Password, edits the same administrator saved in the Admin Portal; with OAuth2 (Client Credentials), possibly other pending changes in your tenant.
ZIA limits how often changes can be activated. If an action hits the limit, Oleria retries for about 11 minutes before the action fails. You can retry a failed action.
- Oleria checks that it can read the target account before an action runs, but it can’t check write access in advance. If the role has View Only access, the action fails when Oleria makes the change.
- Zscaler documents that API roles can’t modify administrators. With OAuth2 (Client Credentials), the administrator actions are expected to fail. Use Username & Password if you need them.
- Users can’t be disabled. ZIA users are usually provisioned by your identity provider, so disable them there.
Known limitations
- Group changes on IdP-managed users may not stick. If your identity provider provisions ZIA users, ZIA may reject a group change for those users, or your identity provider may overwrite it on its next sync. Change their groups in your identity provider instead.
- Simultaneous changes to the same user can conflict. ZIA replaces the whole user record on each change, so two group changes to the same user at the same time can lose one of them.
- Removed permissions look like deletions. If you remove a permission after earlier syncs, the administrators, groups, admin roles, or role assignments Oleria can no longer read disappear from Oleria as if they were deleted in ZIA. If admin roles can’t be read, administrators’ role assignments disappear too. The partially completed sync status shows why.
- No activity or last sign-in. Oleria doesn’t sync ZIA’s admin audit log or users’ sign-in times.
- MFA and SSO aren’t shown. Oleria doesn’t show MFA status for any ZIA account. SSO status isn’t shown for administrators, or for users synced from an identity provider.
- Government and beta clouds aren’t supported with OAuth2. OAuth2 connections work only with commercial Zscaler clouds.