awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: added platform dcs

Browse Source
This commit is contained in:
Sheen Capadngan
2025-09-04 03:37:31 +08:00
parent 0a9f51f62f
commit 4d22030bb8
10 changed files with 916 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

183
docs/documentation/platform/gateways/networking.mdx
View File

@@ -3,16 +3,17 @@ title: "Networking"
description: "Network configuration and firewall requirements for Infisical Gateway"
---
The Infisical Gateway requires outbound network connectivity to establish secure communication with Infisical's relay infrastructure.
The Infisical Gateway requires outbound network connectivity to establish secure SSH reverse tunnels with proxy servers.
This page outlines the required ports, protocols, and firewall configurations needed for optimal gateway usage.
## Network Architecture
The gateway uses a relay-based architecture to establish secure connections:
The gateway uses SSH reverse tunnels to establish secure connections with end-to-end encryption:
1. **Gateway** connects outbound to **Relay Servers** using UDP/QUIC protocol
2. **Relay Servers** facilitate secure communication between Gateway and Infisical Cloud
3. All traffic is end-to-end encrypted using mutual TLS over QUIC
1. **Gateway** connects outbound to **Proxy Servers** using SSH over TCP
2. **Infisical platform** establishes mTLS connections with gateways for application traffic
3. **Proxy Servers** route the doubly-encrypted traffic (mTLS payload within SSH tunnels) between the platform and gateways
4. **Double encryption** ensures proxy servers cannot access application data - only the platform and gateway can decrypt traffic
## Required Network Connectivity
@@ -20,65 +21,69 @@ The gateway uses a relay-based architecture to establish secure connections:
The gateway requires the following outbound connectivity:
| Protocol | Destination | Ports | Purpose |
|----------|-------------|-------|---------|
| UDP | Relay Servers | 49152-65535 | Allocated relay communication (TLS) |
| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and relay allocation |
| Protocol | Destination | Ports | Purpose |
| -------- | ------------------------------------ | ----- | ------------------------------------------ |
| TCP | Proxy Servers | 2222 | SSH reverse tunnel establishment |
| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests |
### Relay Server IP Addresses
### Proxy Server Connectivity
Your firewall must allow outbound connectivity to the following Infisical relay servers on dynamically allocated ports.
**For Instance Proxies (Infisical Cloud):** Your firewall must allow outbound connectivity to Infisical-managed proxy servers.
**For Organization Proxies:** Your firewall must allow outbound connectivity to your own proxy server IP addresses.
**For Self-hosted Instance Proxies:** Your firewall must allow outbound connectivity to proxy servers configured by your instance administrator.
<Tabs>
<Tab title="Infisical cloud (US)">
```
54.235.197.91:49152-65535
18.215.196.229:49152-65535
3.222.120.233:49152-65535
34.196.115.157:49152-65535
```
<Tab title="Instance Proxies (Infisical Cloud)">
Infisical provides multiple managed proxy servers with static IP addresses.
You can whitelist these IPs ahead of time based on which proxy server you
choose to connect to. **Firewall requirements:** Allow outbound TCP
connections to the desired proxy server IP on port 2222.
</Tab>
<Tab title="Infisical cloud (EU)">
```
3.125.237.40:49152-65535
52.28.157.98:49152-65535
3.125.176.90:49152-65535
```
<Tab title="Organization Proxies">
You control the proxy server IP addresses when deploying your own
organization proxies. **Firewall requirements:** Allow outbound TCP
connections to your proxy server IP on port 2222. For example, if your proxy
is at `203.0.113.100`, allow TCP to `203.0.113.100:2222`.
</Tab>
<Tab title="Infisical dedicated">
Please contact your Infisical account manager for dedicated relay server IP addresses.
<Tab title="Self-hosted Instance Proxies">
Contact your instance administrator for the proxy server IP addresses
configured for your deployment. **Firewall requirements:** Allow outbound
TCP connections to instance proxy servers on port 2222.
</Tab>
</Tabs>
<Warning>
These IP addresses are static and managed by Infisical. Any changes will be communicated with 60-day advance notice.
</Warning>
## Protocol Details
### QUIC over UDP
### SSH over TCP
The gateway uses QUIC (Quick UDP Internet Connections) for primary communication:
The gateway uses SSH reverse tunnels for primary communication:
- **Port 5349**: STUN/TURN over TLS (secure relay communication)
- **Built-in features**: Connection migration, multiplexing, reduced latency
- **Encryption**: TLS 1.3 with certificate pinning
- **Port 2222**: SSH connection to proxy servers
- **Built-in features**: Automatic reconnection, certificate-based authentication, encrypted tunneling
- **Encryption**: SSH with certificate-based authentication and key exchange
## Understanding Firewall Behavior with UDP
## Firewall Configuration for SSH
Unlike TCP connections, UDP is a stateless protocol, and depending on your organization's firewall configuration, you may need to adjust network rules accordingly.
When the gateway sends UDP packets to a relay server, the return responses need to be allowed back through the firewall.
Modern firewalls handle this through "connection tracking" (also called "stateful inspection"), but the behavior can vary depending on your firewall configuration.
The gateway uses standard SSH over TCP, making firewall configuration straightforward.
### TCP Connection Handling
### Connection Tracking
SSH connections over TCP are stateful and handled seamlessly by all modern firewalls:
Modern firewalls automatically track UDP connections and allow return responses. This is the preferred configuration as it:
- Automatically handles return responses
- Reduces firewall rule complexity
- Avoids the need for manual IP whitelisting
- **Established connections** are automatically tracked
- **Return traffic** is allowed for established outbound connections
- **No special configuration** needed for connection tracking
- **Standard SSH protocol** that enterprise firewalls handle well
In the event that your firewall does not support connection tracking, you will need to whitelist the relay IPs to explicitly define return traffic manually.
### Simplified Firewall Rules
Since SSH uses TCP, you only need simple outbound rules:
1. **Allow outbound TCP** to proxy servers on port 2222
2. **Allow outbound HTTPS** to Infisical API endpoints on port 443
3. **No inbound rules required** - all connections are outbound only
## Common Network Scenarios
@@ -86,83 +91,87 @@ In the event that your firewall does not support connection tracking, you will n
For corporate environments with strict egress filtering:
1. **Whitelist relay IP addresses** (listed above)
2. **Allow UDP port 5349** outbound
3. **Configure connection tracking** for UDP return traffic
4. **Allow ephemeral port range** 49152-65535 for return traffic if connection tracking is disabled
1. **Allow outbound TCP** to proxy servers on port 2222
2. **Allow outbound HTTPS** to the Infisical API server on port 443
3. **No inbound rules required** - all connections are outbound only
4. **Standard TCP rules** - simple and straightforward configuration
### Cloud Environments (AWS/GCP/Azure)
Configure security groups to allow:
- **Outbound UDP** to relay IPs on port 5349
- **Outbound TCP** to proxy servers on port 2222
- **Outbound HTTPS** to app.infisical.com/eu.infisical.com on port 443
- **Inbound UDP** on ephemeral ports (if not using stateful rules)
- **No inbound rules required** - SSH reverse tunnels are outbound only
## Frequently Asked Questions
<Accordion title="What happens if there is a network interruption?">
The gateway is designed to handle network interruptions gracefully:
- **Automatic reconnection**: The gateway will automatically attempt to reconnect to relay servers every 5 seconds if the connection is lost
- **Automatic reconnection**: The gateway will automatically attempt to reconnect to proxy servers if the SSH connection is lost
- **Connection retry logic**: Built-in retry mechanisms handle temporary network outages without manual intervention
- **Multiple relay servers**: If one relay server is unavailable, the gateway can connect to alternative relay servers
- **Persistent sessions**: Existing connections are maintained where possible during brief network interruptions
- **Persistent SSH tunnels**: SSH connections are automatically re-established when connectivity is restored
- **Certificate rotation**: The gateway handles certificate renewal automatically during reconnection
- **Graceful degradation**: The gateway logs connection issues and continues attempting to restore connectivity
No manual intervention is typically required during network interruptions.
</Accordion>
<Accordion title="Why does the gateway use QUIC instead of TCP?">
QUIC (Quick UDP Internet Connections) provides several advantages over traditional TCP for gateway communication:
<Accordion title="Why does the gateway use SSH over TCP?">
SSH over TCP provides several advantages for enterprise gateway communication:
- **Faster connection establishment**: QUIC combines transport and security handshakes, reducing connection setup time
- **Built-in encryption**: TLS 1.3 is integrated into the protocol, ensuring all traffic is encrypted by default
- **Connection migration**: QUIC connections can survive IP address changes (useful for NAT rebinding)
- **Reduced head-of-line blocking**: Multiple data streams can be multiplexed without blocking each other
- **Better performance over unreliable networks**: Advanced congestion control and packet loss recovery
- **Lower latency**: Optimized for real-time communication between gateway and cloud services
- **Firewall-friendly**: TCP is stateful and handled seamlessly by all enterprise firewalls
- **Standard protocol**: SSH is a well-established protocol that network teams are familiar with
- **Certificate-based security**: Uses SSH certificates for strong authentication without shared secrets
- **Automatic tunneling**: SSH reverse tunnels handle all the complexity of secure communication
- **Enterprise compatibility**: Works reliably across all enterprise network configurations
TCP's reliability and firewall compatibility make it ideal for enterprise environments where network policies are strictly managed.
While TCP is stateful and easier for firewalls to track, QUIC's performance benefits outweigh the additional firewall configuration requirements.
</Accordion>
<Accordion title="Do I need to open any inbound ports on my firewall?">
No inbound ports need to be opened. The gateway only makes outbound connections:
- **Outbound UDP** to relay servers on ports 49152-65535
- **Outbound HTTPS** to Infisical API endpoints
- **Return responses** are handled by connection tracking or explicit IP whitelisting
- **Outbound SSH** to proxy servers on port 2222
- **Outbound HTTPS** to Infisical API endpoints on port 443
- **SSH reverse tunnels** handle all communication - no return traffic configuration needed
This design maintains security by avoiding the need for inbound firewall rules that could expose your network to external threats.
</Accordion>
<Accordion title="What if my firewall blocks the required UDP ports?">
If your firewall has strict UDP restrictions:
<Accordion title="What if my firewall blocks SSH connections?">
If your firewall has strict outbound restrictions:
1. **Work with your network team** to allow outbound UDP to the specific relay IP addresses
2. **Use explicit IP whitelisting** if connection tracking is disabled
3. **Consider network policy exceptions** for the gateway host
1. **Work with your network team** to allow outbound TCP connections on port 2222 to proxy servers
2. **Allow standard SSH traffic** - most enterprises already have SSH policies in place
3. **Consider network policy exceptions** for the gateway host if needed
4. **Monitor firewall logs** to identify which specific rules are blocking traffic
The gateway requires UDP connectivity to function - TCP-only configurations are not supported.
</Accordion>
<Accordion title="How many relay servers does the gateway connect to?">
The gateway connects to **one relay server at a time**:
<Accordion title="How many proxy servers does the gateway connect to?">
The gateway connects to **one proxy server**:
- **Single active connection**: Only one relay connection is established per gateway instance
- **Automatic failover**: If the current relay becomes unavailable, the gateway will connect to an alternative relay
- **Load distribution**: Different gateway instances may connect to different relay servers for load balancing
- **No manual selection**: The Infisical API automatically assigns the optimal relay server based on availability and proximity
- **Single SSH connection**: Each gateway establishes one SSH reverse tunnel to its assigned proxy server
- **Named proxy assignment**: Gateways connect to the specific proxy server specified by `--proxy-name`
- **Automatic reconnection**: If the proxy connection is lost, the gateway automatically reconnects to the same proxy
- **Certificate-based authentication**: Each connection uses SSH certificates issued by Infisical for secure authentication
You should whitelist all relay IP addresses to ensure proper failover functionality.
</Accordion>
<Accordion title="Can the relay servers decrypt traffic going through them?">
No, relay servers cannot decrypt any traffic passing through them:
<Accordion title="Can the proxy servers decrypt traffic going through them?">
No, proxy servers cannot decrypt any traffic passing through them due to end-to-end encryption:
- **End-to-end encryption**: All traffic between the gateway and Infisical Cloud is encrypted using mutual TLS with certificate pinning
- **Relay acts as a tunnel**: The relay server only forwards encrypted packets - it has no access to encryption keys
- **No data storage**: Relay servers do not store any traffic or network-identifiable information
- **Certificate isolation**: Each organization has its own private PKI system, ensuring complete tenant isolation
- **Client-to-Gateway mTLS**: Clients establish mTLS connections directly with gateways, encrypting all application traffic
- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to proxy servers
- **Double encryption**: Traffic is encrypted twice - once by client mTLS and again by SSH tunnels
- **Proxy acts as a relay**: The proxy server only routes the doubly-encrypted traffic without access to either encryption layer
- **No data storage**: Proxy servers do not store any traffic or sensitive information
- **Certificate isolation**: Each connection uses unique certificates, ensuring complete tenant isolation
The relay infrastructure is designed as a secure forwarding mechanism, similar to a VPN tunnel, where the relay provider cannot see the contents of the traffic flowing through it.
</Accordion>
The proxy infrastructure is designed as a secure routing mechanism where only the client and gateway can decrypt the actual application traffic.
</Accordion>