Configure Artifactory for PTC

JFrog Artifactory Configuration

This section covers the JFrog Artifactory side of PTC setup: create remote repositories, ensure Curation is enabled, register each package type with Package Reroute through the REST API (which auto-enrolls the repository in Curation by default), and verify the redirect endpoint. Complete this before security edge redirect rules are activated; see Deployment Sequence.

Important — PTC repo_key must be a remote repository: The Package Reroute repo_key must point to a remote repository. Virtual repositories are not supported as the PTC repo_key.

Complete the following procedures in order (after Prerequisites):

• Step 1: Create a Remote Repository
• Step 2: Ensure JFrog Curation Is Enabled
• Step 3: Register Repositories with Package Reroute (Mandatory)
• Step 4: Verify the Redirect Endpoint

Repository Architecture

PTC requires the following repository structure:

• Remote Repository: Proxies and caches packages from the upstream public registry, and is the only supported repo_key target for Package Reroute. JFrog Curation policies apply at this layer when Curation is enabled for that remote.

The Package Reroute repo_key must point to a remote repository. Virtual repositories are not supported as the repo_key target—they prevent JFrog from tracking consumption accurately and from configuring Curation automatically on the upstream-facing repository.

Step 1: Create a Remote Repository

The steps below use npm and registry.npmjs.org as a worked example. For each other package type you support, create a remote repository of the matching package type with that ecosystem's public registry URL, then map each type in the Package Reroute Config API the same way.

To create a remote repository for PTC:

1. Navigate to Administration > Repositories > Remote.
2. Click New Remote Repository.
3. Package Type: Select npm.
4. Repository Key: Enter a descriptive name, for example npm-remote-registry.
5. URL: https://registry.npmjs.org
6. Click Create.

The remote repository is created and ready to map in the Package Reroute Config API.

Step 2: Ensure JFrog Curation Is Enabled

Make sure JFrog Curation is enabled in your Artifactory instance before calling the Package Reroute API in Step 3. The API auto-enrolls the target remote repository in Curation when linked_curation is true (the default), so you do not need to connect individual repositories to Curation manually.

To skip Curation enrollment for a specific repository, send linked_curation: false in the Step 3 request body.

For how to enable and configure Curation, see Configure JFrog Curation.

Step 3: Register Repositories with Package Reroute (Mandatory)

This step is mandatory. After the remote repository exists and Curation is enabled (see Step 2), map each package type you enable to that remote repository's repo_key using the Update Registry Configuration API (PUT /artifactory/api/package-reroute/config/{type}). See Package Reroute Config API.

This API call does three things: it tells PTC which Artifactory remote repository to use for each package type, creates the _package-reroute system user that handles redirected traffic, and (by default) auto-enrolls the repository in Curation. PTC does not work until this step completes.

The repo_key must reference a remote repository. Virtual repositories are not supported.

Supported type values are npm, pypi, docker, huggingfaceml, gems (RubyGems), and cargo (Rust). Repeat the call for every ecosystem you roll out.

To register npm with Package Reroute:

1. Use the remote repository key from Step 1 (for example npm-remote-registry) as the repo_key.
2. Call PUT /artifactory/api/package-reroute/config/npm with that key in the request body.
3. Confirm the response returns HTTP 200 and the same repo_key.
4. Optionally call Get Registry Configuration (GET /artifactory/api/package-reroute/config/{type}) or Get Full Configuration (GET /artifactory/api/package-reroute/config) to verify the mapping. See Package Reroute Config API.

curl -X PUT "https://<YOUR_ARTIFACTORY_URL>/artifactory/api/package-reroute/config/npm" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"repo_key": "npm-remote-registry"}'

Where:

• <YOUR_ARTIFACTORY_URL>: Your JFrog Platform hostname (for example acme.jfrog.io)
• <token>: Admin JWT or use Basic authentication per Package Reroute Config API
• repo_key: The remote repository key from Step 1

Package Reroute is configured for npm. Repeat PUT /artifactory/api/package-reroute/config/{type} for each additional package type (for example pypi, docker, huggingfaceml, gems, cargo) before you enable security edge redirect rules for those ecosystems.

By default (linked_curation: true), a successful call also auto-enrolls the target remote repository in Curation. Send linked_curation: false in the request body to register the repository for reroute without enrolling it in Curation.

Error responses

The Update Registry Configuration API (PUT /artifactory/api/package-reroute/config/{type}) returns the following errors when the request cannot be applied:

Step 4: Verify the Redirect Endpoint

The /artifactory/api/package-reroute entry point on the JFrog Router is where security edge-redirected client traffic lands. It is product-defined and not customer-configurable. You can validate it before redirect rules are enabled by calling Artifactory directly with the same query shape your security edge will append (url= original registry URL, percent-encoded).

To verify the package-reroute redirect endpoint:

Build https://<hostname>/artifactory/api/package-reroute?url=<percent-encoded-upstream-url> using your Artifactory hostname. Percent-encode the value of url (for https://registry.npmjs.org/express use https%3A%2F%2Fregistry.npmjs.org%2Fexpress). Example (fictional tenant acme.jfrog.io):

curl -v "https://<YOUR_ARTIFACTORY_URL>/artifactory/api/package-reroute?url=https%3A%2F%2Fregistry.npmjs.org%2Fexpress"

Where:

• <YOUR_ARTIFACTORY_URL>: Your JFrog Platform hostname (for example acme.jfrog.io)

Use your own hostname. The Router path is /artifactory/api/package-reroute. If an encoded url fails in your shell, try single-quoting the full URL or passing --data-urlencode via curl -G.

Expected: HTTP 302 or 307 with a Location header pointing to an Artifactory URL (typically under /artifactory/api/npm/<your-remote>/... for the express package, not still on registry.npmjs.org). Do not use curl -L if you only want to inspect the first hop.

If the response is not 302/307, see Verify the Redirect Endpoint troubleshooting for the common causes (401/403, 407, 404, very long url= values).

For details on how to find and interpret PTC reroute lines in Artifactory's system logs, see Package Reroute Logs for PTC.

Frequently Asked Questions

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

Related Topics

• Package Traffic Controller (PTC) overview
• Prerequisites and Installation Script
• Configure Zscaler ZIA