Configure Zscaler ZIA

Zscaler ZIA Configuration Guide

Disclaimer — Zscaler UI and releases: The procedure below reflects how JFrog configured Zscaler Internet Access (ZIA) in a lab to exercise PTC. Zscaler owns the Admin Portal, navigation, rule types, and defaults; those elements can change across Zscaler versions, SKUs, and tenants without JFrog’s involvement or advance notice. Treat this chapter as a conceptual walkthrough (custom URL category → SSL inspection for that category → URL filtering redirect to <YOUR_ARTIFACTORY_URL>/package-reroute) and always confirm labels, menus, and options against Zscaler’s current ZIA documentation and your Zscaler administrator. JFrog does not control Zscaler’s product and cannot warrant that every screen matches your console.

This section details the steps to configure Zscaler Internet Access (ZIA) to redirect developer traffic to your Artifactory instance. Complete Configure Artifactory for PTC before proceeding.

Important: Workstation trust for Zscaler TLS inspection must be in place before you turn on ZIA rules for registry traffic, otherwise installs break. Follow this order:

1. Complete trust deployment per client and OS using scripts/README.md, Zscaler’s trust guidance, and your process (MDM optional)—see Before Step 2: Verify trust stores for your package clients.
2. Recommend that developers open new terminal sessions or restart IDEs so updated environment variables apply (full machine reboot is optional, not required—old shells keep the previous env until closed).
3. Then configure the ZIA rules in Step 1 through Step 4.

Complete the following procedures in order (after Configure Artifactory for PTC):

• Step 1: Create a Custom URL Category
• Before Step 2: Verify trust stores for your package clients
• Step 2: Enable SSL Inspection for the Category
• Step 3: Configure the Block & Redirect Rule
• Step 4: Save and Activate Changes

No-Inspection Rule for Artifactory Traffic (all deployments)

Create a no-inspection (SSL inspection bypass) rule in ZIA for traffic destined for your Artifactory hostname. For JFrog Cloud this is typically *.jfrog.io; self-hosted deployments use their own DNS name. This prevents ZIA from re-intercepting the redirected traffic on its way from the workstation to Artifactory, which would break the flow.

Reference: Public registry hostnames for the URL category

Add every HTTPS hostname your clients use for the package types you have enabled in Artifactory (Package Reroute / virtual repos). The table below lists typical defaults—confirm with TLS/SNI captures, package-manager docs, or Zscaler logs; corporate mirrors or private edge caches use different hosts. Scope must stay aligned with Supported Package Types (GA) and your entitlements.

This list is not exhaustive for the open internet—it is a starting point for PTC lab validation. JFrog does not control public registry or CDN hostnames; they can change. Re-verify when upgrading clients or regions.

Step 1: Create a Custom URL Category

Define the public registries you want to intercept and route to Artifactory.

To create a custom URL category for PTC:

1. Navigate to Administration > URL Categories.
2. Click Add URL Category.
3. Name: Enter a descriptive name, for example JFrog_Target_Registries.
4. URLs: Enter the domains for each ecosystem you redirect—use the reference table above and Supported Package Types (GA). Example when only npm (+ Yarn) is in scope: registry.npmjs.org and registry.yarnpkg.com.
5. Click Save.

The custom URL category is ready for SSL inspection and URL filtering rules.

Before Step 2: Verify trust stores for your package clients

SSL inspection will apply to every hostname in your custom URL category (reference table). Before you enable it in ZIA, your organization must ensure workstations trust TLS through Zscaler for each package client and OS you actually intercept (npm, PyPI, Docker, and so on). The right variables, trust stores, and validation steps differ by product and version; this guide does not maintain that matrix.

Use the following sources of truth instead:

• Installation Script and the PTC repository scripts/README.md — supported OSes, clients, environment variables, scripts, and tests
• Zscaler: Adding Custom Certificate to an Application-Specific Trust Store (also linked from Prerequisites)
• Containers: Docker and Virtual Environments and Docker’s Using Docker with Zscaler when OCI registries are in scope

Have IT or platform engineering smoke-test real installs (the same commands your developers use) on representative machines before widening SSL inspection. After changing trust or environment configuration, new shell sessions pick up updates—see Deployment Sequence, step 3.

Step 2: Enable SSL Inspection for the Category

Critical Step: Zscaler must decrypt the HTTPS traffic destined for these registries to inject the HTTP Redirect header.

To enable SSL inspection for the registry URL category:

1. Navigate to Policy > SSL Inspection.
2. Click Add SSL Inspection Rule.
3. Rule Name: Enter a descriptive name, for example Inspect_JFrog_Registries.
4. Rule Order: Ensure this rule is placed above any default rules that might bypass inspection.
5. URL Categories: Select the category created in Step 1 (JFrog_Target_Registries).
6. Action: Select Inspect.
7. Click Save.

SSL inspection applies to traffic matching your PTC URL category.

Scoped Deployment (Optional): To limit SSL inspection to a specific group (e.g., R&D):

1. In the same SSL Inspection rule, locate the Groups field.
2. Select your target group (e.g., R&D).

This ensures that only traffic from the selected group is inspected for redirection.

Step 3: Configure the Block & Redirect Rule

This step implements the routing logic. Zscaler "blocks" the request to the public registry but immediately provides a redirect response pointing to your Artifactory instance.

To create the block and redirect URL filtering rule:

1. Navigate to Policy > URL & Cloud App Control > URL Filtering Policy.
2. Click Add URL Filtering Rule.
3. Rule Name: Enter a descriptive name, for example Redirect_Registries_to_JFrog.
4. URL Categories: Select the category created in Step 1 (JFrog_Target_Registries).
5. Protocols: Choose HTTPS.
6. Request Methods (crucial):
   • Select GET and HEAD.
   • Do not select POST. Commands like npm audit use POST and must not be redirected, or they will fail.
   • Set User Agent to Other.
7. Action: Select Block.
8. Redirect URL: Enter your Artifactory redirect endpoint. Zscaler appends the original destination URL as the url query parameter (typically percent-encoded, consistent with the curl examples in Step 6: Verify the Redirect Endpoint).
   • Value: <YOUR_ARTIFACTORY_URL>/package-reroute (no trailing slash before the query string)
   • Example: https://<YOUR_ARTIFACTORY_URL>/package-reroute — Zscaler appends ?url=<percent-encoded-upstream> (product-defined path; not configurable)
9. Click Save and Activate Change.

Registry GET traffic is redirected to your Artifactory /package-reroute endpoint.

Scoped Deployment (Optional): To limit the redirect rule to a specific group:

1. In the same URL Filtering rule, locate the Groups field.
2. Select your target group (e.g., R&D).

Step 4: Save and Activate Changes

To save and activate ZIA policy changes:

1. Review all rules in the correct order:
   • SSL Inspection rule (Step 2) must be above default bypass rules.
   • URL Filtering rule (Step 3) must be active.
2. Click Activate Change if you have not already done so in Step 3.
3. Allow a few minutes for the policy to propagate to all Zscaler enforcement nodes.

ZIA policies are active and ready for end-to-end verification on pilot workstations.

Traffic Flow After Configuration

Once configured, the flow operates as follows:

1. Request: Developer runs npm install. The client requests https://registry.npmjs.org/package.
2. Interception: Zscaler intercepts the request via SSL Inspection.
3. URL Match: Zscaler matches the URL against the JFrog_Target_Registries category.
4. Redirect: Zscaler blocks the direct access and returns an HTTP 307 Redirect to:

<YOUR_ARTIFACTORY_URL>/package-reroute?url=https%3A%2F%2Fregistry.npmjs.org%2Fpackage

5. Resolution: The JFrog Artifactory parses the request and serves the package from the appropriate remote repository.

Scoped Deployment Summary:

End-to-End Verification

After both Artifactory and ZIA are configured, verify the full flow with ZCC running on a developer workstation and all Zscaler rules active:

npm install express --loglevel verbose

Where:

• express: A public npm package used as a smoke-test artifact

For example:

npm install lodash --loglevel verbose

In the verbose log, look for HTTP GET lines whose URL points at your Artifactory host (for example acme.jfrog.io and your npm-virtual-registry API path), not only at registry.npmjs.org—that confirms the client followed the redirect into JFrog. The install should complete successfully. Also verify by checking:

1. Artifactory UI: Navigate to the remote NPM repository. The express package should appear in the cached artifacts.
2. If Curation is enabled for that remote: Navigate to Curation > Audit—you should see an entry for the express package request with an Approved status (if Curation is off, there will be no Curation audit row; that is expected).

Frequently Asked Questions

This section provides answers to frequently asked questions about configuring Zscaler ZIA for Package Traffic Controller (PTC).

Related Topics

• Package Traffic Controller (PTC) overview
• Configure Artifactory for PTC
• Configuration by Package Type