Home / architect / hybrid-integration-architecture

hybrid-integration-architecture

Use this skill when designing hybrid on-premises-to-Salesforce integration architectures: DMZ relay patterns, reverse proxy configuration, VPN connectivity, and Salesforce Private Connect (AWS PrivateLink) topology.

v1.0.1
Salesforce Spring '25+
Updated 2026-10-03
Security
Reliability

hybrid-integration
on-premises
private-connect
dmz
network-topology
data-residency

Open the skill folder on GitHub

Hybrid Integration Architecture

Use this skill when designing the network topology for integrations between on-premises systems and Salesforce — including DMZ relay patterns, reverse proxy configurations, VPN-based connectivity, and Salesforce Private Connect. This skill covers network and connectivity architecture, not authentication mechanisms (see integration-security-architecture for mTLS and OAuth).

Before Starting

Gather this context before working on anything in this domain:

Is the Salesforce org on Hyperforce? Correction (2026-10-03): earlier text said Hyperforce uses ephemeral IPs and allowlisting is not viable. Salesforce publishes versioned per-region prefixes at https://ip-ranges.salesforce.com/ip-ranges.json; they change between versions and are shared by every org in the region, so an allowlist can supplement but never replace mTLS, OAuth, or Private Connect.
What is the on-premises system type: mainframe, ERP, database, or middleware?
Is the connection outbound from Salesforce to on-premises, inbound from on-premises to Salesforce, or bidirectional?
Are there data residency or regulated-industry requirements (HIPAA, GDPR, financial regulation) that require the integration data to remain within a specific geography or network boundary?
Is Salesforce Private Connect licensed? Private Connect requires support-assisted opt-in and carries separate add-on licensing (UNVERIFIED 2026-10-03: Help-only; confirm with the account team).

Questions to Ask Before Configuring

Ask these before drawing the topology. Each traces to a gotcha in references/gotchas.md.

Question	Why it matters	What a good answer adds	What a proper design adds over just doing it
"Where does the target system run, and can it be fronted by an AWS VPC endpoint service?"	Private Connect connections are `AwsPrivateLink` only (Gotcha 2); no native VPN exists (Gotcha 4)	The candidate pattern: Private Connect, DMZ relay, or public endpoint with strong auth	No design that depends on a capability the platform lacks
"Who owns provisioning on each side: the Salesforce admin and the AWS account owner?"	A deployed connection stays `Unprovisioned` until Provision runs and the AWS side accepts (Gotcha 2)	Named owners and a per-org runbook step	Sandboxes and production reach `Ready` predictably
"Which callouts hit the on-premises target today, and through which named credentials?"	Only `PrivateEndpoint` named credentials use the private path (Gotcha 3); Remote Site Settings open a side door (Gotcha 7)	A callout inventory with named credential type per callout	Every callout takes the private, authenticated path
"How is the caller's identity proven at the relay or endpoint?"	IP ranges are shared by every org in a region (Gotcha 1); WS-Security is unsupported (Gotcha 8)	Two-way SSL, OAuth, or gateway-injected credentials	Identity is cryptographic, not inferred from an address
"What latency does the relay add at peak, and is the call synchronous?"	Callouts default to 10 seconds and cap at 120 seconds per transaction (Gotcha 6)	Measured latency and a sync/async decision per call	Users do not hit timeouts at month end
"Which fields must stay unreadable outside the customer network, and which must stay filterable?"	Gateway tokenization breaks filtering (Gotcha 5)	A per-field searchable/non-searchable decision	Reports and duplicate rules keep working on the fields that need them

What a proper design adds over "just opening a firewall port": the caller is authenticated by certificate or token rather than address, every callout uses the intended path, and private connections are provisioned and checked per org as a runbook step.

Core Concepts

DMZ Relay Pattern for Outbound Callouts from Salesforce

When Salesforce makes outbound callouts to an on-premises system, the on-premises system is often behind a corporate firewall that does not accept inbound connections from the public internet. The DMZ relay pattern uses a relay server in the corporate DMZ to forward requests:

Salesforce callout goes to the DMZ relay host (a server in the corporate demilitarized zone with a public FQDN).
The relay (e.g., reverse proxy products such as IBM WebSeal or CA SiteMinder) authenticates the incoming request and forwards it to the internal on-premises system over the corporate LAN.
The response travels back through the relay to Salesforce.

The DMZ relay is the on-premises side of the architecture. Salesforce has no native VPN client — Salesforce cannot terminate a VPN tunnel. All on-premises connectivity from Salesforce must traverse through an internet-facing relay, a Private Connect endpoint, or an intermediary integration platform (MuleSoft Runtime Fabric) that handles the corporate network boundary.

Salesforce Private Connect (AWS PrivateLink)

Salesforce Private Connect provides a private network path between Salesforce (hosted on AWS) and the customer's AWS environment using AWS PrivateLink. This eliminates the public internet from the data path entirely:

Data does not traverse the public internet
No need to manage Salesforce-side IP allowlists (which change between published versions on Hyperforce)
Provides the strongest network-level isolation for regulated data

Key constraints:

Requires support-assisted opt-in — cannot be self-service enabled (UNVERIFIED 2026-10-03, Help-only)
Carries separate add-on licensing (UNVERIFIED 2026-10-03, Help-only)
Requires the customer environment to also be on AWS (or have AWS connectivity); the Metadata API OutboundNetworkConnection and InboundNetworkConnection types offer only AwsPrivateLink as a customer-usable connection type
Outbound connections name the customer's AwsVpcEndpointServiceName and Region; Salesforce returns the AwsVpcEndpointId. Inbound connections expose SourceIpRanges allocated by the Salesforce-managed VPC
Callouts use the private path only through a NamedCredential of type PrivateEndpoint that references the OutboundNetworkConnection (API 56.0 and later)
The existing integration-security-architecture skill covers Private Connect authentication details thoroughly; this skill covers the network topology decision

Private Connect is NOT the universal solution — it only applies when the on-premises system connects through AWS and the licensing is available.

On-Premises Encryption Gateways for Data Residency

For organizations with regulated data that cannot leave their network boundaries (e.g., HIPAA-protected health data, financial data under specific sovereignty requirements), on-premises encryption gateways (such as IBM DataPower or CipherCloud; Integration Patterns and Practices also lists Salesforce's own gateway and Computer Associates) can be placed between the corporate network and Salesforce:

Data from Salesforce travels to the encryption gateway in the customer DMZ.
The gateway encrypts or tokenizes sensitive fields before the data reaches internal systems (or vice versa for inbound).
The encryption keys never leave the customer's network — Salesforce stores only tokenized values.

This pattern requires that the Salesforce fields holding sensitive values are designed for tokenized data, and that all reporting and business logic use the tokenized representation or decrypt at the gateway layer.

Common Patterns

Pattern: Reverse Proxy Relay for On-Premises Salesforce Callouts

When to use: Salesforce must call an on-premises API or database that is not accessible on the public internet and Private Connect is not available.

How it works:

Deploy or configure a reverse proxy in the corporate DMZ (e.g., nginx, IBM WebSeal, CA SiteMinder, AWS API Gateway with VPC link).
Assign the relay a public FQDN with a valid TLS certificate.
In Salesforce, configure a Named Credential pointing to the relay's public FQDN, with a client certificate if the relay enforces two-way SSL.
The relay is configured to forward authenticated requests to the internal target over the internal network.
Correction (2026-10-03): earlier text said to add the relay FQDN to Remote Site Settings. The Apex Developer Guide ("Invoking Callouts Using Apex") says a callout whose endpoint is a named credential needs no remote site setting; leaving one in place lets any Apex call the relay without the named credential.

Why not VPN: Salesforce has no native VPN client and cannot terminate IPSec or SSL VPN tunnels. VPN connectivity must be managed by an intermediary (MuleSoft Runtime Fabric deployed in the customer network, or a relay in the DMZ).

Pattern: Private Connect for Regulated On-Premises Data (AWS-Connected)

When to use: Regulated data (HIPAA, financial sovereignty) must never traverse the public internet; customer environment connects to AWS.

How it works:

Customer enables Private Connect via Salesforce support request (requires add-on license; UNVERIFIED 2026-10-03).
Customer creates a VPC Endpoint Service in their AWS VPC pointing to their on-premises systems (via Direct Connect or Site-to-Site VPN to AWS).
An admin creates an OutboundNetworkConnection (connectionType = AwsPrivateLink, properties AwsVpcEndpointServiceName and Region) and runs Provision; the AWS owner accepts the connection request; the status reaches Ready.
A NamedCredential of type PrivateEndpoint references the connection, and every callout to the target uses it.
Integration traffic flows: Salesforce → AWS PrivateLink → customer AWS VPC → customer on-premises (via Direct Connect or VPN).

Decision Guidance

Situation	Recommended Approach	Reason
On-premises API accessible via public internet	Named Credential + mTLS or OAuth	No special network topology needed
On-premises API behind corporate firewall, no Private Connect	DMZ reverse proxy relay	Relay provides public-facing FQDN that Salesforce can call
Regulated data, no public internet path	Private Connect (if licensed and AWS-connected)	Eliminates public internet from data path
Hyperforce org needing on-premises access	Private Connect or mTLS relay — NOT IP allowlisting alone	Published Hyperforce ranges change between versions and are shared by all orgs in a region
On-premises system not on AWS	DMZ relay or MuleSoft Runtime Fabric on-premises	Private Connect requires AWS connectivity
Data residency encryption requirement	On-premises encryption gateway (DataPower/CipherCloud)	Keys stay on-premises; Salesforce stores tokenized values

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

Determine org type — Hyperforce or non-Hyperforce? On Hyperforce, any allowlist must be automated from the published ip-ranges.json feed and paired with mTLS or OAuth; plan for mTLS or Private Connect from the start.
Classify the connectivity requirement — Outbound from Salesforce to on-premises, inbound from on-premises to Salesforce, or bidirectional. Each direction may use a different pattern.
Assess Private Connect eligibility — Is the customer environment on AWS? Is Private Connect licensed? If both yes, Private Connect is the strongest option for regulated scenarios.
Design DMZ relay if Private Connect is not available — Identify the relay host location, TLS certificate requirements, and authentication mechanism at the relay layer.
Evaluate data residency requirements — If regulated data must never be visible in plaintext outside the customer network, design an encryption gateway layer at the DMZ boundary.
Document the network topology — Produce a diagram showing: Salesforce → relay/Private Connect endpoint → on-premises target. Include all network boundaries (DMZ, internal LAN, internet).
Validate against Hyperforce constraints — Confirm that no design depends on IP allowlisting alone, that every callout uses the intended named credential type, and that each org's private connection is Ready.

Review Checklist

Run through these before marking work in this area complete:

[ ] Hyperforce status confirmed; no IP allowlisting used on Hyperforce
[ ] Connectivity direction classified (outbound from SF / inbound to SF / bidirectional)
[ ] Private Connect eligibility assessed (AWS + license)
[ ] DMZ relay or Private Connect endpoint configured
[ ] Data residency requirements addressed with encryption gateway if required
[ ] Network topology diagram produced showing all boundaries
[ ] No assumption that Salesforce can terminate VPN tunnels

Salesforce-Specific Gotchas

Salesforce has no native VPN client — A common design error is planning a VPN tunnel from Salesforce to the corporate network. Salesforce cannot terminate IPSec or SSL VPN tunnels. All corporate-network connectivity requires an intermediary relay or Private Connect.
Private Connect requires support-assisted opt-in and separate licensing — Private Connect cannot be self-service enabled. Teams that design for Private Connect without confirming the license and support enablement process will be blocked at implementation.
Hyperforce IP ranges change and are shared — Salesforce publishes per-region prefixes in ip-ranges.json, versioned by syncToken (corrected 2026-10-03 from "ephemeral"). Allowlisting must be automated from the feed and cannot prove which org is calling. mTLS or OAuth carries the identity check.
DMZ relay security configuration is outside Salesforce's control — The relay is a customer-managed component. If the relay has weak TLS configuration or insufficient authentication, the Salesforce-side security is undermined regardless of Salesforce's own security posture.

Output Artifacts

Artifact	Description
Network topology diagram	Diagram showing Salesforce, relay/Private Connect, and on-premises system boundaries
Connectivity pattern decision	Documents which pattern was selected and why
Private Connect prerequisites checklist	License, AWS setup, and support request steps
Data residency architecture note	Documents encryption gateway placement and key management approach

architect/integration-security-architecture — Use for mTLS, OAuth, IP allowlisting alternatives, and Private Connect authentication details
architect/api-led-connectivity-architecture — Use for API layer design (System/Process/Experience) above the network connectivity layer
architect/mulesoft-anypoint-architecture — Use when MuleSoft Runtime Fabric is the on-premises relay component in the hybrid topology
integration/private-connect-setup: Use for the Setup steps that provision the Private Connect connection
standards/decision-trees/integration-pattern-selection.md: read before choosing the integration pattern that runs over this network path