Skip to main content
All CollectionsOnboarding and Configuration Guides
Onboarding Guide - Zscaler
Onboarding Guide - Zscaler
Reco Product Management avatar
Written by Reco Product Management
Updated over 3 weeks ago

Prerequisites

  • You must have an API subscription. If you do not have a subscription, submit a Zscaler Support ticket.

  • You must have the API Roles configured in the ZIA Admin Portal.

    To configure API roles:

    1. Go to Administration > Role Management.

    2. Click Add API Role.

      A screenshot of the Add API Role button in the Role Management page

      The Add API Role window appears:

      Adding an API Role in the ZIA Admin Portal

    3. In the Add API Role window:

      Enter a name for the API role and select the following permissions (everything else can be turned off):

      • Policy access -> View only

      • Administrators Access -> Full

      Select the following functional scopes (everything else can be turned off):

      • Access Control (Web and Mobile) > Policy and Resource Management functional scope

      • Authentication Configuration > User Management functional scope

      Please refer to the following links to Zscaler's documentation, which detail the required permissions for each endpoint we utilize:

    4. Click Save and activate the change.

      The API role is created and an internal API user is automatically created for the role in the format of oauth-<rolename>$@<orgid>.<cloud_domain>. For example, [email protected] is used as the User context in any API operation. It is also displayed in the audit log for any API operation that is authenticated by an external OAuth 2.0 authentication server. However, this internal user is not displayed on the Administrator Management or User Management pages in the ZIA Admin Portal.

      After the API role is created, define that role as a Scope on the authorization server. You must configure the Scope value in the <Zscaler Cloud Name>::<Org ID>::<API Role> format, where:

      • Zscaler Cloud Name represents the cloud on which your organization is provisioned.

      • Org ID represents your organization ID obtained from the ZIA Admin Portal (under Administration > Company Profile).

      • API Role represents an API role configured in the Add API Role window in the ZIA Admin Portal.

Integrate Zscaler with Reco

  1. Retrieve your Zscaler cloud name

    Check which Zscaler cloud name was provisioned for your organization.

    Example values:

    • zscalerbeta.net

    • zscalerone.net

    • zscalertwo.net

    • zscalerthree.net

    • zscaler.net

    • zscloud.net

    To locate your cloud name:

    1. Log in to the ZIA Admin Portal using your admin credentials. You must be assigned an admin role that includes the Authentication Configuration functional scope.

    2. Go to Administration > Cloud Service API Security.

    3. On the OAuth 2.0 Authorization Servers tab, the cloud name is displayed within the table. Copy and save it for later
      ​

  2. Retrieve Client ID, Client Secret, Organization ID and API Role.

    • Client ID: A unique, public identifier issued to the client application during registration with the authorization server. It is obtained from the OAuth 2.0 service console. Copy and save it for later.

    • Client Secret: A secret string used by the client application for authenticating with the authorization server. It is obtained from the OAuth 2.0 service console. Copy and save it for later.

  3. If you use Okta as your auth provider, retrieve the following as well:

    • Organization ID: represents your organization ID obtained from the ZIA Admin Portal (under Administration > Company Profile)

    • API Role: represents an API role configured in the ZIA Admin Portal (under Administration > Authentication > Role Management). Copy and save it for later.

  4. If you use Microsoft Entra as your auth provider, retrieve Application ID URI with the help of this guide.

  5. Retrieve Token URI - endpoint that we will use to get a bearer token for zscaler public api. Please consult documentation of your Oauth2.0 provider on how to retrieve this uri.
    ​Example:

    If you use Okta as your auth provider, consult this guide to find your domain. Your token uri will look something similar to:

    https://{yourOktaDomain}/oauth2/v1/token
    ​If you are using a custom authorization server, the endpoint would look like:

    https://{yourOktaDomain}/oauth2/{authorizationServerId}/v1/token

    Here, authorizationServerId is the identifier for your custom authorization server

  6. Fill in the Cloud Name, Client ID, Client Secret and Token URI that were copied previously

  7. If you use Okta, fill in the Organization ID and API Role values

  8. If you use Microsoft Entra, fill in the Application ID URI value

  9. Click on "Connect"

Did this answer your question?