Try JFrog
Guides
Contact SupportTry JFrog
Start typing to search…
  1. Platform Administration
  2. JFrog Bridge

Federated Repositories with JFrog Bridge

Federated Repositories with JFrog Bridge

Federated Repositories with JFrog Bridge enables secure, encrypted communication between JFrog Platform environments without complex networking requirements. This feature allows Repository Federation to work seamlessly between SaaS and self-managed Artifactory environments.

It operates transparently within the JFrog Platform, allowing platform services to communicate with services running on another environment over a private channel — without requiring inbound network access, public exposure, or complex VPN configurations.

Prerequisites

Before you begin, ensure you have a Bridge configured between your environments. For instructions on setting up a Bridge, see Add a JFrog Bridge.

Environment Requirements

  • You must have Bridge installed and configured. For setup instructions, see Add a JFrog Bridge.
    You should receive a Bridge URL such as http://localhost:8046/bridge-<Bridge_ID> that will be used as a federation Base URL to the self-managed environment.

SaaS Environment:

As Federation over Bridge is in early adopter stage, contact JFrog Support to verify that Bridge is enabled on your SaaS environment.

Self-Managed Environment:

  • RTFS enabled with Bridge feature flags:
    • artifactory.rtfs.bridge.url.enabled — set in Artifactory system.yaml
    • rtfs.bridge.url.enabled — set in RTFS system.yaml
  • Artifactory version 7.133.13 or higher (bundling RTFS 1.15.13)
  • Federated Base URL configured to point to Bridge endpoint

Note: Self-hosted Bridge federation support is available starting with Artifactory 7.133.13 (rolling out from March 16, 2026).

Access Requirements:

  • Admin access to both SaaS and self-managed environments
  • kubectl or SSH access to self-managed cluster
  • New Bridge-compatible pairing token (see Establish Trust — Service Trust Pairing for creation instructions)

Setup Guide

Before you begin, ensure all prerequisites are met and your Bridge is configured.

Step 1: Configure Federated Base URL

On Self-Managed:

Set the Federation base URL to point to the Bridge endpoint. For instructions, see Change the Federated Base URL.

Set the federated base URL to:

http://localhost:8046/bridge-<Bridge_ID>/artifactory

Important: Changing the Federated Base URL affects all existing federations on this instance. A self-managed environment configured with a Bridge Federated Base URL can only federate with SaaS. Self-hosted to self-hosted federation over Bridge is not currently supported and will be revisited in a future release

Step 2: Pair Environments

Federation requires two-way trust between environments. Complete both bindings below.

Binding 1: SaaS to Self-Managed

  1. Generate a pairing token on SaaS:
curl -u <user>:<password> --location --request POST \
 'https://<saas-url>/artifactory/api/v1/service_trust/pairing/federated-repo/*' \
 --data ''
  1. Import the returned token to the self-managed environment:
curl -u <user>:<password> --location --request PUT \
 'https://<self-managed-url>/artifactory/api/v1/service_trust/pairing/federated-repo/*' \
 --header 'Content-Type: application/json' \
 --data '{
   "pairing_token": "<access-token>"
 }'

Binding 2: Self-Managed to SaaS

This binding requires accessing the self-managed instance directly.

  1. Access the self-managed instance and Generate a pairing token inside:
curl -u<user>:<password> -X POST \ "http://localhost:8081/artifactory/api/v1/service_trust/pairing/federated-repo/*" \
-H "X-JFrog-Override-Base-Url: http://localhost:8046/bridge-<Bridge_ID>" \
-H "Accept: application/json"
  1. Import the returned token to SaaS:
curl -u<user>:<password> --location --request PUT 'https://<saas-url>/artifactory/api/v1/service_trust/pairing/federated-repo/*' \
--header 'Content-Type: application/json' \
--data '{
"pairing_token": "<access-token>"
}'

Step 3: Test Federation

  1. Create federated repository on SaaS
  2. Add member with URL:
http://localhost:8046/bridge-<Bridge_ID>/artifactory/<repo-name>

Note: When adding a self-hosted member from the SaaS side, use the URL tab — the Deployment tab is not supported for Bridge members.

Note: Adding a SaaS member from the self-hosted side is a regular flow and does not require any Bridge-specific steps.

  1. Upload artifact to SaaS repository
  2. Verify artifact appears on self-managed repository

Verification

Success Indicators

  • Bridge endpoint responds to ping
  • Pairing completes without errors
  • Artifacts sync between environments
  • No 400/404 errors on federation operations

Health Check Commands

Check Bridge Status (SaaS):

curl https://<saas-url>/bridge-<Bridge_ID>/access/api/v1/system/ping

Check Federation Status:

# On SaaS
curl -u admin:password https://<saas-url>/artifactory/api/federation/status

# Verify repository sync
curl -u admin:password https://<saas-url>/artifactory/api/repositories/<repo-name>

Troubleshooting

Common Issues

Issue: "Adding members from same host is not allowed"
Symptoms: Error appears when adding members from the same host
Cause: Bridge feature flags are not enabled
Solution: Enable the following Bridge feature flags, then retry:

  • artifactory.rtfs.bridge.url.enabled (Artifactory)
  • rtfs.bridge.url.enabled (RTFS)

Issue: "Federated service is not fully operational yet"

Symptoms: 400 error when accessing Bridge endpoint
Cause: RTFS still initializing
Solution: Wait five to ten minutes, then retry

Issue: 404 on Bridge Endpoint

Symptoms: Bridge endpoint returns 404 Not Found
Cause: Feature flags not enabled or incorrect URL format
Solution:

  • Verify feature flags are enabled on both Artifactory and RTFS
  • Check URL format includes /bridge-<Bridge_ID>/

Issue: Pairing Fails with Token Exception

Symptoms: Token validation error during pairing
Cause: Known issue with RTFS-to-RTFS pairing
Solution: Follow the pairing process in Establish Trust — Service Trust Pairing and verify both directions are completed.

Issue: Artifacts Not Syncing

Symptoms: Files uploaded to one side don't appear on the other
Cause: Federation not properly configured or connection issues
Solution:

  1. Verify pairing completed successfully
  2. Check federation member URL uses correct Bridge prefix
  3. Review logs for connection errors
  4. Verify base URLs are configured correctly

Debug Checklist

Run through this checklist if experiencing issues:

  • Feature flags enabled on SaaS (artifactory.rtfs.bridge.url.enabled)
  • RTFS enabled on self-managed (rtfs.enabled: true)
  • Base URLs configured correctly on both sides
  • Federation base URL includes Bridge prefix
  • Pairing tokens generated and imported successfully
  • Network connectivity exists (port 443)
  • Pods are running and healthy

Verify Configuration Format (system.yaml)

A common mistake is setting the feature flag value as a quoted string instead of a boolean.

Incorrect:

rtfs:
  bridge:
    url:
      enabled: 'true'

Correct:

rtfs:
  bridge:
    url:
      enabled: true

After restart, confirm the parameter appears as a boolean in startup logs:

rtfs.bridge.url.enabled = true

A quoted 'true' may not be interpreted as a boolean, leaving the feature effectively disabled.

Enable TRACE Logging

If federation using Bridge URLs is failing, enable TRACE logging to see how URLs are detected and processed.

RTFS — Edit logback.xml (/opt/jfrog/federation/var/etc/rtfs/logback.xml):

Add before </configuration>:

<logger name="org.jfrog.rtfs.common.utils.BridgeUrlProcessor" level="TRACE"/>
<logger name="org.jfrog.rtfs.common.utils.HttpUtils" level="TRACE"/>

Artifactory — Edit logback.xml:

<logger name="org.artifactory.addon.federated.utils.BridgeUrlProcessor" level="TRACE"/>
<logger name="org.artifactory.addon.federated" level="DEBUG"/>

After enabling TRACE, reproduce the issue and search logs:

grep -E "(BridgeUrlProcessor|Detected bridge URL|processed)" /opt/jfrog/federation/var/log/artifactory-federation-service.log

Expected RTFS output:

TRACE BridgeUrlProcessor - Detected bridge URL pattern, Input remoteUrl: http://localhost:8046/bridge-xyz/artifactory/my-repo
TRACE BridgeUrlProcessor - Bridge URL with /artifactory processed - returning: http://localhost:8046/bridge-xyz/artifactory

Expected Artifactory output:

TRACE BridgeUrlProcessor - Detected bridge URL pattern, Input remoteUrl: http://localhost:8046/bridge-xyz/artifactory/my-repo
TRACE BridgeUrlProcessor - Bridge URL with /artifactory processed - removed /artifactory, returning: http://localhost:8046/bridge-xyz

Collect Information for Support

When opening a support ticket, include:

  • rtfs.bridge.url.enabled value from startup logs (Artifactory and RTFS)
  • Relevant system.yaml sections
  • RTFS and Artifactory logs with TRACE enabled (filtered for BridgeUrlProcessor)
  • Repository name, Bridge URL being used, and full error message

Performance Considerations

Federation over Bridge introduces additional network hops compared to direct federation. Expect higher latency and lower throughput, particularly for large-scale artifact synchronization or high-frequency metadata operations. The degree of impact depends on the network distance between environments and artifact sizes.

If experiencing slow federation or timeouts:

  1. Check connection pool size — Verify Bridge client has sufficient connections
  2. Monitor network latency — High latency between environments will directly impact sync times
  3. Review artifact sizes — Very large artifacts may require timeout adjustments
  4. Check resource allocation — Ensure pods have adequate CPU/memory
  5. Test with your workload — Validate performance against your expected usage patterns before production rollout

API Reference

Pairing Endpoints

Create Pairing Token:

POST /artifactory/api/v1/service_trust/pairing/federated-repo/*
Authorization: Bearer <token>

Register Pairing Token:

PUT /artifactory/api/v1/service_trust/pairing/federated-repo/*
Content-Type: application/json
Authorization: Bearer <token>

{
  "pairing_token": "<pairing-token>"
}

Federation Status

Check Federation Status:

GET /artifactory/api/federation/status
Authorization: Bearer <token>

List Federation Members:

GET /artifactory/api/repositories/<repo-name>
Authorization: Bearer <token>

Configuration Reference

Base URL Format

Self-Managed Federation Base URL:

http://localhost:8046/bridge-<Bridge_ID>/artifactory

SaaS Base URL:

https://<your-instance>.jfrogdev.org/artifactory

Bridge URL Format

For SaaS to Self-Managed Communication:

http://localhost:8046/bridge-<Bridge_ID>/artifactory/<repo-name>

Frequently Asked Questions

Q: Do I need to configure anything on my firewall?
A: For firewall and network requirements, see Manage JFrog Bridges.

Q: What's the performance impact of using Bridge?
A: Federation over Bridge adds network overhead compared to direct federation. Expect higher latency, especially for large artifacts or high-frequency sync operations. Test with your specific workload and scale requirements before production deployment.

Q: What happens if the Bridge connection drops?
A: Federation operations will fail until the connection is restored. For details on Bridge reconnection behavior, see Manage JFrog Bridges.

For general Bridge questions (architecture, installation, VPN comparison), see Manage JFrog Bridges.

Updated 1 day ago