Federation over JFrog Bridge

Federated Repositories with JFrog Bridge enables secure, encrypted communication between JFrog Platform environments without complex networking requirements. This lets Repository Federation work seamlessly between SaaS and self-managed Artifactory environments, without VPN or public exposure.

It operates transparently within the JFrog Platform, allowing platform services to communicate with services running on another environment over a private channel. It doesn't require 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. 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 both 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 the Bridge endpoint

Access requirements:

• Admin access to both the SaaS and self-managed environments
• kubectl or SSH access to the self-managed cluster
• A Bridge-compatible pairing token (see 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
• Step 2: Pair Environments
• Step 3: Test Federation

Step 1: Configure Federated Base URL

Point the Federation Base URL to the Bridge endpoint so the self-managed and SaaS environments can communicate through Bridge.

On self-managed:

To configure the Federated Base URL:

• Set the Federation base URL to point to the Bridge endpoint. For more information, see Change the Base URL in Federated Repositories.

  Text

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

  Where:

  • <Bridge_ID>: The identifier of the Bridge configured between the environments

Step 2: Pair Environments

Federation requires two-way trust between environments. Complete both of the following bindings.

Binding 1: SaaS to self-managed

To create this binding:

1. Generate a pairing token on SaaS:

   Shell

   curl -u <user>:<password> --location --request POST \
    'https://<saas-url>/artifactory/api/v1/service_trust/pairing/federated-repo/*' \
    --data ''

2. Import the returned token to the self-managed environment:

   Shell

   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>"
    }'

   Where:

   • <user>: Your JFrog Platform admin username
   • <password>: Your JFrog Platform admin password
   • <saas-url>: The hostname of your SaaS environment
   • <self-managed-url>: The hostname of your self-managed environment
   • <access-token>: The pairing token returned by the previous command

Binding 2: Self-managed to SaaS

This binding requires accessing the self-managed instance directly.

To create this binding:

1. Access the self-managed instance and generate a pairing token from inside it:

   Shell

   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"

2. Import the returned token to SaaS:

   Shell

   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>"
     }'

   Where:

   • <user>: Your JFrog Platform admin username
   • <password>: Your JFrog Platform admin password
   • <Bridge_ID>: The identifier of your configured Bridge
   • <saas-url>: The hostname of your SaaS environment
   • <access-token>: The pairing token returned by the previous command

Step 3: Test Federation

Confirm that Federation over Bridge is working by creating a test repository and syncing an artifact between environments.

To test Federation over Bridge:

1. Create a Federated repository on SaaS.

2. Add a member with the URL:

   Text

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

   Where:

   • <Bridge_ID>: The identifier of your configured Bridge
   • <repo-name>: The name of the Federated repository you created in step 1

   For example:

   Text

   http://localhost:8046/bridge-prod-01/artifactory/my-federated-repo

   📘

   When adding a self-hosted member from the SaaS side, use the URL tab. The Deployments tab isn't supported for Bridge members. Adding a SaaS member from the self-hosted side is a regular flow and doesn't require any Bridge-specific steps.

3. Upload an artifact to the SaaS repository.

4. Verify the artifact appears on the self-managed repository.

Verification

Success Indicators

• Bridge endpoint responds to ping.
• Pairing completes without errors.
• Artifacts sync between environments.
• No 400 or 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 and repository sync (SaaS):

curl -u admin:password https://<saas-url>/artifactory/api/federation/status
curl -u admin:password https://<saas-url>/artifactory/api/repositories/<repo-name>

Troubleshooting

Common Issues

The following table lists common issues, their causes, and their solutions.

Debug Checklist

Run through this checklist if you're 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 in 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), adding 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 you experience slow federation or timeouts:

1. Check connection pool size: Verify the Bridge client has sufficient connections.
2. Monitor network latency: High latency between environments directly impacts sync times.
3. Review artifact sizes: Very large artifacts may require timeout adjustments.
4. Check resource allocation: Ensure pods have adequate CPU and 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

This section provides answers to frequently asked questions.

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

Related Topics

• Federated Repositories Overview
• Best Practices
• RTFS Configuration Reference
• Migration Rollback