> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-via-webhook-setup-for-workbench.md). # Zscaler Internet Access (via Webhook) Setup for Workbench {% hint style="info" %} This setup guide is for Zscaler ZIA users connecting via a webhook. If you are connecting via a SIEM, go to the [Zscaler Internet Access (ZIA) (via SIEM) setup guide](/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-zia-via-siem-setup-for-workbench.md). {% endhint %} In this guide, you will generate the webhook credentials in Workbench and then add them to your Zscaler console. This allows our SOC analysts to gain access to your Zscaler events. ## Prerequisites 1. You must have a Zscaler account with a Super Admin role (or equivalent), as you must be able to configure and activate changes in the Zscaler console. 2. You must have the [Nanolog Streaming Service (NSS)](https://help.zscaler.com/zia/understanding-nanolog-streaming-service) from Zscaler, and specifically [Cloud NSS Feeds](https://help.zscaler.com/zia/about-cloud-nss-feeds). 3. You must *not* have an existing Cloud NSS Feed already set up for your web logs, as Zscaler currently only supports a single Cloud NSS feed per type (web/firewall). * If you already have an existing feed, you must set up this integration via a SIEM connection instead. Refer to the [Zscaler ZIA via SIEM Setup for Workbench](/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-zia-via-siem-setup-for-workbench.md) guide for more information. ## Step 1: Add Zscaler (via Webhook) as a Security Device in Workbench You must first add the security device in Workbench so that Expel can generate your webhook credentials. You will need to come back to your device at the very end of this process to enable console access (you will find instructions later in this guide). 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F). 2. In the side menu, navigate to **Organization Settings** > **Security Devices**. 3. Select **Add Security Device**. 4. In the search box, type “Zscaler” and then select the **Zscaler (via Webhook)** integration. 5. Complete the fields as follows: * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Zscaler”; this name will display in Workbench under the Name column, and is a text string that you can filter on. * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations. * **Connection Settings** cannot be edited and will be empty; you will find your webhook credentials here after you have added the device. * Select **Save**. 6. Select **Set up later** from the console access dropdown. 7. Select **Save**. You will receive a message stating that your credentials are being generated. 8. Select **Done** to close the window. ## Step 2: Obtain the Webhook Credentials Your new security device now has its webhook credentials available. You'll need to copy and save them, and then also convert the login credentials to a base64-encoded string (our webhook endpoint requires the HTTP authorization header). 1. Still on the Security Devices page, locate the device you created in the prior section. 2. Select the arrow beside the device name, and then select **View details** from the dropdown menu (if you need help with this process, see [View Security Device Details](/connect-your-technology/security-devices/manage-security-devices.md#view-security-device-details)). 3. Select the **Information** screen, and then look for **Connection Settings**. * **If you are unable to see these settings,** [**contact support**](/support/how-to-reach-us.md) **for help obtaining your webhook credentials.** 4. View and save the following values, which you will need when you configure the Cloud NSS feed in the next section: * Webhook Password * Webhook URL * Webhook Username 5. Now, format your login credentials as a base64-encoded string and **save the output**. You can achieve this through one of the following methods, **replacing username:password with your values** (for security reasons, we do NOT recommend using an online Base64 encoding website): * On **Windows** systems, open PowerShell and run: ``` [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password")) ``` * On **UNIX-like** systems, open Terminal and run: ``` printf "%s" "username:password" | base64 ``` * The output should look something like this: **dGVzdHVzZXI6dGVzdHBhc3N3b3Jk** ## Step 3: Set Up the Webhook Connection in Zscaler You will now add the webhook to Zscaler so that it can send events to Workbench. You'll do this via your Cloud NSS feed. {% hint style="warning" %} Remember that you must **not** have already set up Cloud NSS for your web logs. {% endhint %} 1. In the ZIA Admin Portal, navigate to **Administration > Settings > Cloud Configuration > Nanolog Streaming Service**. 2. Select the **Cloud NSS Feeds** tab. 3. Select **Add** **Cloud NSS Feed**. 4. In the **General** section, complete the fields as follows: * **Feed Name** - enter "EXPEL\_SECURITY". * **NSS Type** - select NSS for Web. * **Status** - select Enabled. * **SIEM Rate** - select Unlimited. 5. In the **SIEM Connectivity** section, complete the fields as follows: * **SIEM Type** - select Other. * **OAuth 2.0 Authentication** - make sure this is set to **Disabled**. * **Max Batch Size** - make sure this is set to 512 KB. * **API URL** - enter the webhook URL you saved in [Step 2](#h_01jz8e373jjt05ywdsre2c08dm). * **HTTP Header Key 1** - enter "Content-Encoding". * **HTTP Header Value 1** - enter "gzip". * **HTTP Header Key 2** - enter "Authorization". * **HTTP Header Value 2** - enter "Basic" and then a space, and then add your base64-encoded credentials you saved in [Step 2](#h_01jz8e373jjt05ywdsre2c08dm). The entry should look like something like: **Basic dGVzdHVzZXI6dGVzdHBhc3N3b3Jk** 6. In the **Formatting** section, complete the fields as follows: * **Log Type** - select Web Log. * **Feed Output Type** - select JSON. * **JSON Array Notation** - make sure this is set to Disabled. * **Feed Escape Character** - enter ,\\" * **Feed Output** - copy and paste the following code: ``` \{"event":\{"datetime": "%d{yy}-%02d{mth}-%02d{dd} %02d{hh}:%02d{mm}:%02d{ss}","vendor": "Zscaler","product": "NSS","feed": "WebLogs","vendorversion": "%s{productversion}","event_id": "%d{recordid}","user": "%s{elogin}","department": "%s{edepartment}","appname": "%s{appname}","appclass": "%s{appclass}","app_status": "%s{app_status}","fileclass": "%s{fileclass}","filetype": "%s{filetype}","filename": "%s{efilename}","transactionsize": "%d{totalsize}","responsesize": "%d{respsize}","requestsize": "%d{reqsize}","requestmethod": "%s{reqmethod}","status": "%s{respcode}","refererURL": "%s{ereferer}","useragent": "%s{eua}","fqdn": "%s{ehost}","url": "%s{eurl}","contenttype": "%s{contenttype}","srcip": "%s{cip}","srcpubip": "%s{cintip}","srcport": "%d{clt_sport}","dstip": "%s{sip}","dstport": "%d{srv_dport}","protocol": "%s{proto}","location": "%s{elocation}","ruletype": "%s{ruletype}","reason": "%s{reason}","action": "%s{action}","filehash": "%s{bamd5}","score": "%d{riskscore}","threatseverity": "%s{threatseverity}","threatname": "%s{threatname}","threatcategory": "%s{malwarecat}","threatclass": "%s{malwareclass}","urlclass": "%s{urlclass}","urlsupercategory": "%s{urlsupercat}","urlcategory": "%s{urlcat}","deviceowner": "%s{deviceowner}","devicehostname": "%s{edevicehostname}"\}\} ``` * **Timezone** - leave as GMT. 7. No web log filters are required, so you can now select **Save.** 8. Make sure to **activate the changes** so that they are propagated through the Zscaler cloud. If you need help with this step, see [Saving and Activating Changes in the ZIA Admin Portal](https://help.zscaler.com/zia/saving-and-activating-changes-zia-admin-portal) in the Zscaler documentation. ## Step 4: Verify the Webhook Connectivity First, check the webhook connectivity within the ZIA Admin Portal: 1. Still on the **Cloud NSS Feeds tab**, locate your newly created "EXPEL\_SECURITY" Cloud NSS Feed. 2. In the **Last Connectivity Test** column, check for a "Last Validation Successful on \" message. * If you do not see a validation message or if it is not yet showing as valid, select the **cloud** icon to test the connection. * If you are unable to validate the connection, go to [Troubleshooting](#h_01jz8e374drkah5bqz4p20x7ng) for help. Next, check to make sure the corresponding Expel Alerts are showing up in Workbench: 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F). 2. In the side menu, navigate to **Dashboards > Alert Analysis**. 3. Scroll to the device you want to check and select the **Expel Alerts** tab to reveal more alert information. *It can take 36 to 72 hours for alerts to appear after setup, as we* [*tune your device*](/workbench-reference/alerts/how-expel-alerts-work.md)*.* * If you still do not see any activity after device tuning, go to [Troubleshooting](#h_01jz8e374drkah5bqz4p20x7ng) for help. ## Step 5: Enable Console Access in Zscaler Enabling console access is a multi-step process. The first two steps are performed in Zscaler. [Why do we need console access?](/connect-your-technology/about-integrations/why-expel-asks-for-console-access.md) ### Create the Administrator Role The first step is to create an administrator role for Expel in Zscaler. 1. Still in the ZIA Admin Portal, navigate to **Administration** **> Administration Controls > Role Management**. 2. Select **Add Administrator Role**. 3. In the Administrator Role and Permissions sections: * Enter "Expel" for the name. * Do not enable Permissions for Executive Insights. * Make sure the Logs Limit is set to **Unrestricted**. * Enable **View-Only access** for Reporting, Alerts, Dashboard, and Insights. * Make sure Device Information and User Names are set to **Visible**.
Zscaler Administrator Role and Permissions configuration as described above.
4. Scroll down to **Policy & Components** and verify the following settings within each sub-tab: * **Security** - set to **View-Only** access. * **Access Control** - set both Policy Control and Policy Components to **View-Only** access. * **Data Protection** - set both Policy Control and Policy Components to **View-Only** access. * **Decryption** - set both Policy Control and Policy Components to **View-Only** access. * **URL Categories** - set to **View-Only** access. * **Shared Policy Components** - set to **View-Only** access. 5. Select **Cloud Configuration & Integration**, and verify the following settings within each sub-tab: * **Integrations** - set to **View-Only** access. * **Cloud Configuration** - set to **View-Only** access. 6. Select **Traffic Forwarding**, and verify the following settings: * Set Traffic Forwarding, Traffic Forwarding Methods, and Traffic Forwarding Components to **View-Only** access. 7. Select **Administration Controls**, and verify the following settings: * Set Administration Controls and Backup Controls to **View-Only** access. 8. Select **Reporting Data**, and verify the following settings: * Set Reporting Data to **View-Only** access. 9. Save and activate your changes. ### Create the Expel User Now, you must create a new Expel user, and assign the administrator role you just created. {% hint style="info" %} These steps describe the process for creating a new local user, which is our recommended option. If you would like to use your own identity provider (IdP) instead, refer to [the Zscaler documentation](https://help.zscaler.com/zia/about-identity-providers) for instructions. {% endhint %} 1. Still in the ZIA Admin Portal, navigate to **Administration > Administration Controls >** **Administrator Management**. 2. Select **Add Administrator**. 3. Configure the credentials as follows: * **Login ID** - enter "Expel" and leave the domain as is (it should be your domain). *Make note of this login ID, as you will need it in the next section.* * **Email** - enter "soc+\@expel.io". * For example, if your organization were Acme Corp, the format would be "". * **Name** - enter "Expel". * **Role** - select **Expel** (this is the role you created in the previous section). * **Status** - select **Enabled**. * **Scope** - select **Organization**. * **Executive Insights App Access** - leave it as disabled. * **Choose to Receive Updates** - leave all as disabled. * **Set Password** - enter a password. *Make note of this password, as you will need it in the next section.* 4. Select **Save**. ## Step 6: Enable Console Access in Workbench The next step is to edit the security device and add the new Expel user's credentials. **Make sure you have the login ID and password from the previous section before you begin**. 1. Back in Workbench, navigate to **Organization Settings** > **Security Devices**. 2. Locate the Zscaler ZIA (via Webhook) device you added in [Step 1](#h_01jz8e373f6vd5ma98mqnsezc6). 3. Use the device's dropdown menu to select **Edit**. If you need help with this step, see [Manage Security Devices](/connect-your-technology/security-devices/manage-security-devices.md). 4. Complete the Console Login fields as follows: * **Console URL** - enter your Zscaler console URL * **Username** - enter the Expel user's Login ID. * **Password** - enter Expel user's password. * **Two-factor secret key** - leave blank. 5. Select **Save**. ## Troubleshooting If your Cloud NSS Feed will not connect and validate, first check your feed configuration. 1. Make sure your feed status is set to **Enabled**. 2. Make sure you have copied the webhook URL correctly. If necessary, go back into the security device in Workbench to verify that you have the correct URL. 3. Make sure your HTTP header key and token values are entered correctly. 4. Make sure you copied the feed output correctly. Next, check your base-64 encoded credentials. 1. Go back into the security device in Workbench and verify that you have the correct webhook username and password. 2. Decode your base-64 encoded credentials and make sure they match the webhook credentials. * On Windows systems, open PowerShell and run: ``` [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('your-base64-string')) ``` * On UNIX-like systems, open Terminal and run: ``` printf "%s" "your-base64-string" | base64 -d ``` If you are still unable to successfully connect via the webhook, or if you have successfully verified your webhook but your device is showing no alerts in Workbench after 72 hours, [contact support](/support/how-to-reach-us.md) for help. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.expel.io/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-via-webhook-setup-for-workbench.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.