Configure Zscaler ZIA for PTC

Zscaler ZIA Configuration Guide

Zscaler owns the Admin Portal navigation, rule types, and defaults. UI labels can vary by version and tenant, so use this as a workflow guide and confirm exact options in Zscaler’s current ZIA documentation.

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.

Zscaler Requirements

The following Zscaler-specific requirements must be met before you configure ZIA rules. (Artifactory and workstation install-script requirements that are shared across SASE are covered in Prerequisites and Installation Script.)

ZIA Admin Portal Access: You need administrative access to the Zscaler Internet Access (ZIA) Admin Portal to create URL categories, SSL inspection rules, and URL filtering rules.

Zscaler Client Connector (ZCC): ZCC must be deployed on all developer workstations that will be part of the PTC solution. ZCC routes network traffic through Zscaler for inspection.

Z-Tunnel Mode and SSL Inspection (Zscaler): PTC depends on ZIA being able to SSL-inspect the HTTPS flows to the public registries you intercept so URL filtering can redirect those requests to Artifactory. Confirm tunnel mode, forwarding behavior, and SSL inspection eligibility with Zscaler. For example, see About Z-Tunnel 1.0 and Z-Tunnel 2.0. If SSL inspection cannot be applied to the relevant client traffic, the redirect flow will not work as intended.

CA Certificate: The Zscaler CA certificate is already distributed to the developer machine by ZCC. However, some package managers and applications still need the certificate in an application-specific trust store or PEM path. MDM is optional: use MDM (for example, Intune and Jamf), other deployment tooling, or controlled manual steps, especially for labs and pilots. At enterprise scale, automated distribution is strongly recommended. The certificate file must be copied to a location with user-level read access, not a root-only location (see Before Step 2: Verify trust stores for your package clients for details). For detailed instructions, see Adding Custom Certificate to an Application-Specific Trust Store.

Target Group (Scoped Deployments Only): If you plan to scope PTC to a specific group (for example, R&D), ensure the target group exists in Zscaler. Groups can be configured via:

• Directory Sync / SCIM: Synced from your identity provider
• Local: Created manually under Administration > User Management > Groups in the ZIA Admin Portal

Important: Workstation trust for Zscaler TLS inspection must be in place before you turn on ZIA rules for registry traffic; otherwise installs fail. 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 and Redirect Rule
• Step 4: Save and Activate Changes

No-Inspection Rule for Artifactory Traffic (Optional)

Optional: if you want ZIA to skip SSL inspection for traffic destined for your Artifactory hostname, add a no-inspection (SSL inspection bypass) rule for that host. For JFrog Cloud this is typically *.jfrog.io. Self-hosted deployments use their own DNS name.

Inspecting Artifactory traffic itself does not affect the redirect flow. The redirect works as long as the redirected request to /package-reroute is not itself rerouted back. If your existing ZIA configuration could match on the Artifactory host and redirect it again, exclude the Artifactory host from the redirect rule (or add the no-inspection rule above).

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 Public Registry Hostnames reference 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:

• Configure Workstation for PTC 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: Containers and Virtual Environments and Docker’s Using Docker with Zscaler when Docker 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 and 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.

Key redirect settings:

• Protocols: Use HTTPS only for redirected registry traffic.
• Request methods: Allow GET and HEAD. Keep POST excluded for registry redirect rules. Hugging Face exception: if you redirect Hugging Face traffic, create a separate URL filtering rule for huggingface.co with GET only — do not include HEAD. See Docker, Hugging Face, and Other Types.
• Redirect URL: Use <YOUR_ARTIFACTORY_URL>/package-reroute with no trailing slash before query parameters.

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

After configuration, ZIA intercepts matching GET and HEAD requests and redirects them to <YOUR_ARTIFACTORY_URL>/package-reroute. Artifactory then resolves the request through the configured remote repository.

For a complete flow diagram and scoped or unscoped behavior, see Package Traffic Controller (PTC) overview.

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 pointing at your Artifactory host (for example acme.jfrog.io and your npm-remote-registry API path) rather than registry.npmjs.org — that confirms the redirect. Then confirm the express package appears in the remote NPM repository's cached artifacts, and (if Curation is enabled for the remote) an Approved entry appears under Curation > Audit.

Rollback Process

If PTC needs to be reverted on the Zscaler side, you have two options: stop redirects only (the quick path) or do a full ZIA rollback. The JFrog Artifactory configuration does not need to be rolled back in either case.

Quick Rollback (Stop Redirects Only)

Stop redirecting by removing every registry hostname you added for PTC from the custom URL category (for example JFrog_Target_Registries) across all ecosystems you enabled, or disable the URL Filtering redirect rule that targets that category. Activate the policy change in ZIA. You typically do not need to change Artifactory for this quick path (see Note on Artifactory Configuration).

Full ZIA Rollback

To perform a full ZIA rollback:

1. Navigate to Policy > URL & Cloud App Control > URL Filtering Policy in ZIA.
2. Find the redirect rule (for example Redirect_Registries_to_Artifactory).
3. Disable or delete the rule.
4. Click Activate Change.
5. Navigate to Policy > SSL Inspection in ZIA.
6. Find the inspection rule (for example Inspect_JFrog_Registries).
7. Disable or delete the rule.
8. Click Activate Change.
9. (Optional) Navigate to Administration > URL Categories in ZIA, find JFrog_Target_Registries, and delete the category (only after removing all rules that reference it).

Verify Rollback on a Workstation

# Should show the original registry CA, not Zscaler CA
openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org 2>/dev/null | openssl x509 -noout -issuer

# Package install should work directly against public registry (optional: --loglevel verbose to inspect GET targets)
npm install express --loglevel verbose

Note on Artifactory Configuration

The JFrog Artifactory configuration (repositories, Curation policies, anonymous access) does not need to be rolled back. These settings can remain in place without affecting developers once the Zscaler redirect is disabled.

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
• Supported Security Edges
• Configuration by Package Type