> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zscaler Internet Access

> Connect your Zscaler Internet Access (ZIA) tenant to Oleria to discover users, administrators, groups, and admin roles, and manage group membership and administrator access.

Connect Zscaler Internet Access (ZIA) to Oleria to see who your ZIA tenant knows about and who can administer it: the users ZIA applies policy to, the administrators who sign in to the ZIA Admin Portal, the groups users belong to, and the admin role each administrator holds. Oleria reads this from the ZIA API, either through Zscaler OneAPI with an OAuth2 client or with a ZIA administrator's credentials and API key.

<Note>
  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](/integrations/zscaler) for that setup.
</Note>

## 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.

Departments, locations, policies, and activity aren't synced.

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

| ZIA permission | Used for | Access |
| :- | :- | :- |
| User Management | Users, groups, and group membership. Required. Also used to add users to and remove users from groups. | **Full** to use the group remediation actions. **View Only** is enough for discovery. |
| Administrator Management | Administrators and their role assignments. Also used to disable and enable administrators and to change an administrator's role. | **Full** to use the administrator remediation actions. **View Only** is enough for discovery. |
| Role Management | Admin roles. | **View Only** or higher. |

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.

<Note>
  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.
</Note>

## Create credentials in Zscaler

Choose one authentication method. **OAuth2 (Client Credentials)** is the default.

<Tabs>
  <Tab title="OAuth2 (Client Credentials)">
    <Steps>
      <Step title="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](#permissions), and select **Save**. Then activate the change in ZIA.
      </Step>

      <Step title="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`.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Assign the API role">
        Under resources, select the ZIA API role you created, then select **Save**.
      </Step>

      <Step title="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`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Username & Password">
    <Steps>
      <Step title="Create an administrator for Oleria">
        In the ZIA Admin Portal, go to **Administration** -> **Administrator Management** and add an administrator for Oleria. Assign an admin role that has the permissions listed in [Permissions](#permissions), and give the administrator a password. Then activate the change in ZIA.
      </Step>

      <Step title="Get the API key">
        Go to **Administration** -> **Cloud Service API Security**. On the **Cloud Service API Key** tab, copy the existing API key, or select **Add API Key** to create one.
      </Step>

      <Step title="Find your cloud name">
        Your cloud name is the part of your ZIA Admin Portal address between `admin.` and `.net`. For example, if you sign in at `admin.zscalertwo.net`, your cloud name is `zscalertwo`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Connect Zscaler Internet Access to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Zscaler Internet Access**.
  </Step>

  <Step title="Complete the connection form">
    Select your authentication method, then fill in the fields for that method:

    | Field | Notes |
    | :- | :- |
    | Authentication Method | Required. **OAuth2 (Client Credentials)** or **Username & Password**. |
    | Client ID | Required for OAuth2. The client ID of the ZIdentity API client. |
    | Client Secret | Required for OAuth2. The secret you added to the API client. |
    | Vanity Domain | Required for OAuth2. Your ZIdentity vanity domain only, for example `acme` - not a full URL. Letters, digits, and hyphens only. |
    | Username | Required for Username & Password. The ZIA administrator's login name. |
    | Password | Required for Username & Password. The administrator's password. |
    | API Key | Required for Username & Password. The key from **Cloud Service API Security**. |
    | Cloud | Required for Username & Password. Your ZIA cloud name only, for example `zscalertwo` - not a full URL. Letters, digits, and hyphens only. |
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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](#permissions) in ZIA, activate the change, and the next sync includes them.

<Note>
  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.
</Note>

## Remediation actions

Oleria can take the following actions in ZIA:

| Action | What it does | Revert |
| :- | :- | :- |
| Disable user accounts | Disables an administrator's ZIA Admin Portal account. Administrators only. | Supported - re-enables the administrator. |
| Enable user accounts | Re-enables a disabled administrator. Administrators only. | Supported - disables the administrator again. |
| Add user to role | Changes an administrator's admin role to the selected role. An administrator holds exactly one role, so this replaces their current role. Administrators only. | Not supported - ZIA has no "no role" state. Assign the previous role again instead. |
| Add user to group | Adds a user to a ZIA group. Users only. If the user is already in the group, the membership isn't changed, but Oleria still activates any pending changes. | Supported - removes the user from the group. |
| Remove user from group | Removes a user from a ZIA group. Users only. If the user isn't in the group, the membership isn't changed, but Oleria still activates any pending changes. | Supported - adds the user back to the group. |

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.

<Note>
  * 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.
</Note>

## 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.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.