Zscaler Internet Access: Using FQDN Groups

Note: This guide is intended for customers who are unable to leverage WitnessAI's custom URL categories due to conflicts with existing URL categories or Zscaler's URL categorization limitations (e.g., when a URL is present in multiple categories). In this deployment model, WitnessAI pushes the sanctioned AI domains to the customer's Zscaler tenant as an FQDN Address Object Group (Destination Group of type Wildcard FQDN) via API, instead of custom URL categories.

Click here for the installation guide for Zscaler Internet Access Using URL Groups.

Quick Summary

The Zscaler configurations required to integrate WitnessAI using FQDN Address Groups are:

Admin Role (scoped to IP & FQDN Groups)
Admin Account in ZIA or ZIdentity
Cloud Service API Key
Proxy Setup
SSL Inspection & Forwarding Control (referencing the FQDN Address Group)

⚠️

Advanced Cloud Firewall subscription required for user- or group-scoped forwarding.

The Forwarding Control rule created in this guide can only be scoped to specific users, groups, departments or device groups if the Zscaler tenant has an Advanced Cloud Firewall subscription.

Without it, the rule cannot be limited to a user population and must be applied by location or to all users. If you intend to roll WitnessAI out to a subset of users, confirm the subscription on your Zscaler tenant before proceeding. See About Forwarding Control in the Zscaler Help Portal.

Pre-Requisites

Zscaler License: The tenant must have an Advanced Cloud Firewall license.
API credentials (service account + Cloud Service API Key) or Client ID & Secret to be provided to the WitnessAI account team.
WitnessAI will push the FQDN Address Object Group to the customer's Zscaler tenant via API. The group is then referenced in the SSL Inspection and Forwarding Control policies.
Z-Tunnel 1.0 / PAC users: Firewall processing for Z-Tunnel 1.0 and PAC Road Warriors must be enabled in ZIA Advanced Settings for the Forwarding Control rule to apply to those users. This is a tenant-wide setting. See Enable Firewall Processing for Z-Tunnel 1.0 and PAC Traffic below.

Create admin role

Create an Admin Role under Administration → Administrator Management → Administrator Role → Add Administrator Role

Name → WitnessAI-API-Role
Enable Permissions for Executive Insights → Disabled
Permissions

Logs Limit (Days) → Unrestricted
Dashboard Access → View Only
Reporting Access → None
Insights Access → None
Alerts Access → None
User Names → Obfuscated
Device Information → Obfuscated
Gen AI Prompt → Obfuscated

Policy & Components → Shared Policy Components → Custom

IP & FQDN Groups → Full
Browser Isolation → None
Device Management → None
Time Intervals → None

Set all other scopes as None or View Only, then Save.

Note: Unlike the URL-category-based integration, this role does not require Custom URL Category Management permissions. The only Full permission required is IP & FQDN Groups under Shared Policy Components.

Create admin account

Create a new admin account under Administration → Administrator Management → Administrators → Add Administrator and attach the above created admin role.

Login ID → svc_witnessai_zia
Role → WitnessAI-API-Role
Password → Set password, then Save

Note: If SAML authentication is enabled for admin logins, the 'Password-Based Login' option must be enabled to override this setting and allow the use of a password.

Configure service account for ZIdentity Managed Admins

This step applies to Zscaler tenants that have been migrated to ZIdentity (Zscaler's centralized identity service). Admin accounts migrated to ZIdentity will no longer be managed through the Admin Portal.

1. Create admin account

Go to ZIdentity Portal → Directory → Users → Add Users

Login ID → svc_witnessai_zia@company.com
Status → Enabled

Go to Add Users → Security Settings

Password Option → Set By Administrator
Password → Enter the password
Confirm Password → Repeat password

2. Add User Group

Go to ZIdentity Portal → Directory → User Groups → Add User Group

Name → WitnessAI-API-Group
Assign Users → svc_witnessai_zia

3. Attach the admin role to the group

Go to ZIdentity Portal → Administration → Entitlements → Administrative

Select → Zscaler Internet Access
Click → Assign Groups, then select WitnessAI-API-Group and attach role: WitnessAI-API-Role, then Next
Verify the group and role mapping, then Assign

Create Cloud Service API Key

Go to Administration → Cloud Service API Security → Cloud Service API Key.
Check if an API key already exists.

If no key exists, click Add API Key to generate one.

Note: Only one API key can be created per account. If a key already exists, the Add API Key button will be greyed out.

Once the above configuration is completed, please hand over the below details to the WitnessAI account team:

Administrator Login ID
Administrator Password
API Key
Base URL: zsapi.<cloudname>.net/api/v1

FQDN Address Group Provisioning (Performed by WitnessAI)

Once API access is validated, WitnessAI pushes an FQDN Address Object Group to the Zscaler tenant via API:

WitnessFwdFQDNs: A Destination Group of type Wildcard FQDN containing the sanctioned AI domains. This group is referenced in the SSL Inspection Policy and the Forwarding Control Policy.

The group is created under Administration → Firewall Filtering → IP & FQDN Groups → Destination IPv4 Groups and is kept up to date by WitnessAI as the sanctioned domain list evolves.

Proxy Setup

Install WitnessAI Provided Root Certificate

Click Administration → Root Certificates.
Click Add Root Certificate.
Name: Enter [WitnessRootCA].
Type: Enter [Proxy Chaining].
Content: Click [Choose File] and pick the WitnessAI-provided Root Certificate.
Once uploaded, click Save.

Note: WitnessAI can support a customer-provided Root Certificate. However, it is recommended that administrators create a unique Root Certificate specific for the WitnessAI platform and provide it to your WitnessAI account team.

Select Administration → Proxies & Gateways.
Select Add Proxy.

Update the Proxy Name to [WitnessAI_NetworkConnector].
For Proxy's Root Certificate, select the Root Certificate created in Step 2.
FQDN → connect.[tenantID].witness.ai
Port → 4128
Enable the Insert X-Authenticated-User switch.
Enable the Base64 Encoding for X-Authenticated-User value switch.

Go to Proxy Gateways

Click on + Add Gateway for Proxies
Gateway Name: Enter [WitnessConnect].
Fail Close: Click to [Disable].
Primary Proxy: Enter [WitnessConnect].

SSL Inspection Configuration

Navigate to Policy → SSL Inspection and click on Add SSL Inspection Rule.
Input the following information:

Rule Order: Place it above the Generic inspection/bypass rules.
Rule Name: [WitnessAI-Inspection Rule].
Rule Status: [Enabled].
Destination Groups: [WitnessFwdFQDNs]
Action: Inspect
Enable HTTP/2: Yes
Select: Save

Enable Firewall Processing for Z-Tunnel 1.0 and PAC Traffic

💡

Note: This step is only required if end users forward traffic to ZIA via Z-Tunnel 1.0 or a PAC file. Z-Tunnel 2.0 traffic is subject to Forwarding Control by default.

This is a tenant-wide setting. Enabling it applies all firewall rules to Z-Tunnel 1.0 and PAC traffic. Validate the impact of your existing Firewall rules on end-user traffic before enabling.

Navigate to Administration → Advanced Settings.
Under Firewall Settings for Z-Tunnel 1.0 and PAC (Road Warriors), enable Enable Firewall for Z-Tunnel 1.0 and PAC Road Warriors.

ZIA Advanced Settings page. Toggle highlighted for “Firewall Settings for Z-Tunnel 1.0 and PAC (Road Warriors)”

Select Save and Activate the change.

Reference: Zscaler: Configuring Advanced Settings: Firewall Settings for Z-Tunnel 1.0 and PAC (Road Warriors)

Network Connector Integration

Select: Policy → Forwarding Control.
Select Add Forwarding Rule.

Rule Order: Make this as high as possible.
Rule Name: Enter [WitnessForwarding].
Rule Status: Choose [Enabled].
Forwarding Method: Choose [Proxy Chaining]
General: [Define which user population will be inspected for AI].

Note: Scoping this rule by Users, Groups, Departments or Device Groups requires an Advanced Cloud Firewall subscription. Without it, scope by Location. Otherwise leave the criteria set to “Any”. See the Advanced Cloud Firewall banner at the top of this page.

Forward to Proxy Gateway: Choose [WitnessConnect].
Destination → Destination IPv4 Groups → [WitnessFwdFQDNs]
Select:

Note: Up to 1000 FQDN Address Groups can be referenced per rule.

Limits

Item	Limit
FQDN addresses per organization (with Advanced Cloud Firewall license)	16,000
FQDN addresses per organization (without Advanced Cloud Firewall license)	5,000
FQDN addresses per FQDN address group (with Advanced Cloud Firewall license)	8,000
FQDN addresses per FQDN address group (without Advanced Cloud Firewall license)	100
FQDN Address Groups per rule	1,000

References

Zscaler Internet Access FQDN Address Group Based Integration Quick Summary Pre-Requisites Create admin role Create admin account Configure service account for ZIdentity Managed Admins 1. Create admin account 2. Add User Group 3. Attach the admin role to the group Create Cloud Service API Key FQDN Address Group Provisioning (Performed by WitnessAI)Proxy Setup Install WitnessAI Provided Root Certificate SSL Inspection Configuration Enable Firewall Processing for Z-Tunnel 1.0 and PAC Traffic Network Connector Integration Limits References