mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
doc: added platform dcs
This commit is contained in:
Sheen Capadngan
@@ -18,7 +18,7 @@ description: "Network-related commands for Infisical including gateway and proxy
|
||||
|
||||
## Description
|
||||
|
||||
Network-related commands for Infisical that provide secure access to private resources through a three-tier proxy system:
|
||||
Network-related commands for Infisical that provide secure access to private resources:
|
||||
|
||||
- **Gateway**: Lightweight agent deployed within your VPCs to provide access to private resources
|
||||
- **Proxy**: Identity-aware relay infrastructure that routes encrypted traffic (can be instance-wide or organization-specific)
|
||||
|
||||
@@ -174,7 +174,15 @@
|
||||
"pages": [
|
||||
"documentation/platform/gateways/overview",
|
||||
"documentation/platform/gateways/gateway-security",
|
||||
"documentation/platform/gateways/networking"
|
||||
"documentation/platform/gateways/networking",
|
||||
{
|
||||
"group": "Gateway (Deprecated)",
|
||||
"pages": [
|
||||
"documentation/platform/gateways-deprecated/overview",
|
||||
"documentation/platform/gateways-deprecated/gateway-security",
|
||||
"documentation/platform/gateways-deprecated/networking"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: "Gateway Security Architecture"
|
||||
sidebarTitle: "Architecture"
|
||||
description: "Understand the security model and tenant isolation of Infisical's Gateway"
|
||||
---
|
||||
|
||||
# Gateway Security Architecture
|
||||
|
||||
The Infisical Gateway enables Infisical Cloud to securely interact with private resources using mutual TLS authentication and private PKI (Public Key Infrastructure) system to ensure secure, isolated communication between multiple tenants.
|
||||
This document explains the internal security architecture and how tenant isolation is maintained.
|
||||
|
||||
## Security Model Overview
|
||||
|
||||
### Private PKI System
|
||||
Each organization (tenant) in Infisical has its own private PKI system consisting of:
|
||||
|
||||
1. **Root CA**: The ultimate trust anchor for the organization
|
||||
2. **Intermediate CAs**:
|
||||
- Client CA: Issues certificates for cloud components
|
||||
- Gateway CA: Issues certificates for gateway instances
|
||||
|
||||
This hierarchical structure ensures complete isolation between organizations as each has its own independent certificate chain.
|
||||
|
||||
### Certificate Hierarchy
|
||||
```
|
||||
Root CA (Organization Specific)
|
||||
├── Client CA
|
||||
│ └── Client Certificates (Cloud Components)
|
||||
└── Gateway CA
|
||||
└── Gateway Certificates (Gateway Instances)
|
||||
```
|
||||
|
||||
## Communication Security
|
||||
|
||||
### 1. Gateway Registration
|
||||
When a gateway is first deployed:
|
||||
|
||||
1. Establishes initial connection using machine identity token
|
||||
2. Allocates a relay address for communication
|
||||
3. Exchanges certificates through a secure handshake:
|
||||
- Gateway receives a unique certificate signed by organization's Gateway CA along with certificate chain for verification
|
||||
|
||||
### 2. Mutual TLS Authentication
|
||||
All communication between gateway and cloud uses mutual TLS (mTLS):
|
||||
|
||||
- **Gateway Authentication**:
|
||||
- Presents certificate signed by organization's Gateway CA
|
||||
- Certificate contains unique identifiers (Organization ID, Gateway ID)
|
||||
- Cloud validates complete certificate chain
|
||||
|
||||
- **Cloud Authentication**:
|
||||
- Presents certificate signed by organization's Client CA
|
||||
- Certificate includes required organizational unit ("gateway-client")
|
||||
- Gateway validates certificate chain back to organization's root CA
|
||||
|
||||
### 3. Relay Communication
|
||||
The relay system provides secure tunneling:
|
||||
|
||||
1. **Connection Establishment**:
|
||||
- Uses QUIC protocol over UDP for efficient, secure communication
|
||||
- Provides built-in encryption, congestion control, and multiplexing
|
||||
- Enables faster connection establishment and reduced latency
|
||||
- Each organization's traffic is isolated using separate relay sessions
|
||||
|
||||
2. **Traffic Isolation**:
|
||||
- Each gateway gets unique relay credentials
|
||||
- Traffic is end-to-end encrypted using QUIC's TLS 1.3
|
||||
- Organization's private keys never leave their environment
|
||||
|
||||
## Tenant Isolation
|
||||
|
||||
### Certificate-Based Isolation
|
||||
- Each organization has unique root CA and intermediate CAs
|
||||
- Certificates contain organization-specific identifiers
|
||||
- Cross-tenant communication is cryptographically impossible
|
||||
|
||||
### Gateway-Project Mapping
|
||||
- Gateways are explicitly mapped to specific projects
|
||||
- Access controls enforce organization boundaries
|
||||
- Project-level permissions determine resource accessibility
|
||||
|
||||
### Resource Access Control
|
||||
1. **Project Verification**:
|
||||
- Gateway verifies project membership
|
||||
- Validates organization ownership
|
||||
- Enforces project-level permissions
|
||||
|
||||
2. **Resource Restrictions**:
|
||||
- Gateways only accept connections to approved resources
|
||||
- Each connection requires explicit project authorization
|
||||
- Resources remain private to their assigned organization
|
||||
|
Before Width: | Height: | Size: 324 KiB After Width: | Height: | Size: 324 KiB |
168
docs/documentation/platform/gateways-deprecated/networking.mdx
Normal file
168
docs/documentation/platform/gateways-deprecated/networking.mdx
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
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.
|
||||
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:
|
||||
|
||||
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
|
||||
|
||||
## Required Network Connectivity
|
||||
|
||||
### Outbound Connections (Required)
|
||||
|
||||
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 |
|
||||
|
||||
### Relay Server IP Addresses
|
||||
|
||||
Your firewall must allow outbound connectivity to the following Infisical relay servers on dynamically allocated ports.
|
||||
|
||||
<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>
|
||||
<Tab title="Infisical cloud (EU)">
|
||||
```
|
||||
3.125.237.40:49152-65535
|
||||
52.28.157.98:49152-65535
|
||||
3.125.176.90:49152-65535
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Infisical dedicated">
|
||||
Please contact your Infisical account manager for dedicated relay server IP addresses.
|
||||
</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
|
||||
|
||||
The gateway uses QUIC (Quick UDP Internet Connections) 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
|
||||
|
||||
## Understanding Firewall Behavior with UDP
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### Connection Tracking
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## Common Network Scenarios
|
||||
|
||||
### Corporate Firewalls
|
||||
|
||||
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
|
||||
|
||||
### Cloud Environments (AWS/GCP/Azure)
|
||||
|
||||
Configure security groups to allow:
|
||||
- **Outbound UDP** to relay IPs on port 5349
|
||||
- **Outbound HTTPS** to app.infisical.com/eu.infisical.com on port 443
|
||||
- **Inbound UDP** on ephemeral ports (if not using stateful rules)
|
||||
|
||||
## 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
|
||||
- **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
|
||||
- **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:
|
||||
|
||||
- **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
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
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
|
||||
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**:
|
||||
|
||||
- **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
|
||||
|
||||
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:
|
||||
|
||||
- **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
|
||||
|
||||
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>
|
||||
352
docs/documentation/platform/gateways-deprecated/overview.mdx
Normal file
352
docs/documentation/platform/gateways-deprecated/overview.mdx
Normal file
@@ -0,0 +1,352 @@
|
||||
---
|
||||
title: "Gateway"
|
||||
sidebarTitle: "Overview"
|
||||
description: "How to access private network resources from Infisical"
|
||||
---
|
||||
|
||||
|
||||
|
||||
The Infisical Gateway provides secure access to private resources within your network without needing direct inbound connections to your environment.
|
||||
This method keeps your resources fully protected from external access while enabling Infisical to securely interact with resources like databases.
|
||||
Common use cases include generating dynamic credentials or rotating credentials for private databases.
|
||||
|
||||
<Info>
|
||||
Gateway is a paid feature available under the Enterprise Tier for Infisical
|
||||
Cloud users. Self-hosted Infisical users can contact
|
||||
[sales@infisical.com](mailto:sales@infisical.com) to purchase an enterprise
|
||||
license.
|
||||
</Info>
|
||||
|
||||
## How It Works
|
||||
|
||||
The Gateway serves as a secure intermediary that facilitates direct communication between the Infisical server and your private network.
|
||||
It’s a lightweight daemon packaged within the Infisical CLI, making it easy to deploy and manage. Once set up, the Gateway establishes a connection with a relay server, ensuring that all communication between Infisical and your Gateway is fully end-to-end encrypted.
|
||||
This setup guarantees that only the platform and your Gateway can decrypt the transmitted information, keeping communication with your resources secure, private and isolated.
|
||||
|
||||
## Deployment
|
||||
|
||||
The Infisical Gateway is seamlessly integrated into the Infisical CLI under the `gateway` command, making it simple to deploy and manage.
|
||||
You can install the Gateway in all the same ways you install the Infisical CLI—whether via npm, Docker, or a binary.
|
||||
For detailed installation instructions, refer to the Infisical [CLI Installation instructions](/cli/overview).
|
||||
|
||||
To function, the Gateway must authenticate with Infisical. This requires a machine identity configured with the appropriate permissions to create and manage a Gateway.
|
||||
Once authenticated, the Gateway establishes a secure connection with Infisical to allow your private resources to be reachable.
|
||||
|
||||
### Get started
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Gateway Identity">
|
||||
1. Navigate to **Organization Access Control** in your Infisical dashboard.
|
||||
2. Create a dedicated machine identity for your Gateway.
|
||||
3. **Best Practice:** Assign a unique identity to each Gateway for better security and management.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Authentication Method">
|
||||
You'll need to choose an authentication method to initiate communication with Infisical. View the available machine identity authentication methods [here](/documentation/platform/identities/machine-identities).
|
||||
</Step>
|
||||
|
||||
<Step title="Deploy the Gateway">
|
||||
Use the Infisical CLI to deploy the Gateway. You can run it directly or install it as a systemd service for production:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Production (systemd)">
|
||||
For production deployments on Linux, install the Gateway as a systemd service:
|
||||
```bash
|
||||
sudo infisical gateway install --token <your-machine-identity-token> --domain <your-infisical-domain>
|
||||
sudo systemctl start infisical-gateway
|
||||
```
|
||||
This will install and start the Gateway as a secure systemd service that:
|
||||
- Runs with restricted privileges:
|
||||
- Runs as root user (required for secure token management)
|
||||
- Restricted access to home directories
|
||||
- Private temporary directory
|
||||
- Automatically restarts on failure
|
||||
- Starts on system boot
|
||||
- Manages token and domain configuration securely in `/etc/infisical/gateway.conf`
|
||||
|
||||
<Warning>
|
||||
The install command requires:
|
||||
- Linux operating system
|
||||
- Root/sudo privileges
|
||||
- Systemd
|
||||
</Warning>
|
||||
</Tab>
|
||||
|
||||
<Tab title="Production (Helm)">
|
||||
|
||||
The Gateway can be installed via [Helm](https://helm.sh/). Helm is a package manager for Kubernetes that allows you to define, install, and upgrade Kubernetes applications.
|
||||
|
||||
For production deployments on Kubernetes, install the Gateway using the Infisical Helm chart:
|
||||
|
||||
### Install the latest Helm Chart repository
|
||||
```bash
|
||||
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
|
||||
```
|
||||
|
||||
### Update the Helm Chart repository
|
||||
```bash
|
||||
helm repo update
|
||||
```
|
||||
|
||||
### Create a Kubernetes Secret containing gateway environment variables
|
||||
|
||||
The gateway supports all identity authentication methods through the use of environment variables.
|
||||
The environment variables must be set in the `infisical-gateway-environment` Kubernetes secret.
|
||||
|
||||
|
||||
#### Supported authentication methods
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Universal Auth">
|
||||
The Universal Auth method is a simple and secure way to authenticate with Infisical. It requires a client ID and a client secret to authenticate with Infisical.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_UNIVERSAL_AUTH_CLIENT_ID" type="string" required>
|
||||
Your machine identity client ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET" type="string" required>
|
||||
Your machine identity client secret.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `universal-auth` when using Universal Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=universal-auth --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native Kubernetes">
|
||||
The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH" type="string" optional>
|
||||
Path to the Kubernetes service account token to use. Default: `/var/run/secrets/kubernetes.io/serviceaccount/token`.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `kubernetes` when using Native Kubernetes.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=kubernetes --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native Azure">
|
||||
The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `azure` when using Native Azure.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=azure --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Native GCP ID Token">
|
||||
The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `gcp-id-token` when using Native GCP ID Token.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=gcp-id-token --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="GCP IAM">
|
||||
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH" type="string" required>
|
||||
Path to your GCP service account key file _(Must be in JSON format!)_
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `gcp-iam` when using GCP IAM.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=gcp-iam --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id> --from-literal=INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH=<service-account-key-file-path>
|
||||
```
|
||||
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native AWS IAM">
|
||||
The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `aws-iam` when using Native AWS IAM.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=aws-iam --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OIDC Auth">
|
||||
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_JWT" type="string" required>
|
||||
The OIDC JWT from the identity provider.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `oidc-auth` when using OIDC Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=oidc-auth --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id> --from-literal=INFISICAL_JWT=<oidc-jwt>
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="JWT Auth">
|
||||
The JWT Auth method is used to authenticate with Infisical via a JWT token.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_JWT" type="string" required>
|
||||
The JWT token to use for authentication.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_MACHINE_IDENTITY_ID" type="string" required>
|
||||
Your machine identity ID.
|
||||
</ParamField>
|
||||
<ParamField query="INFISICAL_AUTH_METHOD" type="string" required>
|
||||
The authentication method to use. Must be `jwt-auth` when using JWT Auth.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=jwt-auth --from-literal=INFISICAL_JWT=<jwt> --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Token Auth">
|
||||
You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.
|
||||
|
||||
<ParamField query="Environment Variables">
|
||||
<Expandable title="properties">
|
||||
<ParamField query="INFISICAL_TOKEN" type="string" required>
|
||||
The machine identity access token to use for authentication.
|
||||
</ParamField>
|
||||
</Expandable>
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_TOKEN=<token>
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
#### Other environment variables
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="INFISICAL_API_URL">
|
||||
The API URL to use for the gateway. By default, `INFISICAL_API_URL` is set to `https://app.infisical.com`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
### Install the Infisical Gateway Helm Chart
|
||||
```bash
|
||||
helm install infisical-gateway infisical-helm-charts/infisical-gateway
|
||||
```
|
||||
|
||||
### Check the gateway logs
|
||||
After installing the gateway, you can check the logs to ensure it's running as expected.
|
||||
|
||||
```bash
|
||||
kubectl logs deployment/infisical-gateway
|
||||
```
|
||||
|
||||
You should see the following output which indicates the gateway is running as expected.
|
||||
```bash
|
||||
$ kubectl logs deployment/infisical-gateway
|
||||
INF Provided relay port 5349. Using TLS
|
||||
INF Connected with relay
|
||||
INF 10.0.101.112:56735
|
||||
INF Starting relay connection health check
|
||||
INF Gateway started successfully
|
||||
INF New connection from: 10.0.1.8:34051
|
||||
INF Gateway is reachable by Infisical
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local Installation (testing)">
|
||||
For development or testing, you can run the Gateway directly. Log in with your machine identity and start the Gateway in one command:
|
||||
```bash
|
||||
infisical gateway --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain)
|
||||
```
|
||||
|
||||
Alternatively, if you already have the token, use it directly with the `--token` flag:
|
||||
```bash
|
||||
infisical gateway --token <your-machine-identity-token>
|
||||
```
|
||||
|
||||
Or set it as an environment variable:
|
||||
```bash
|
||||
export INFISICAL_TOKEN=<your-machine-identity-token>
|
||||
infisical gateway
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
For detailed information about the gateway command and its options, see the [gateway command documentation](/cli/commands/gateway).
|
||||
|
||||
<Note>
|
||||
Ensure the deployed Gateway has network access to the private resources you intend to connect with Infisical.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify Gateway Deployment">
|
||||
To confirm your Gateway is working, check the deployment status by looking for the message **"Gateway started successfully"** in the Gateway logs. This indicates the Gateway is running properly. Next, verify its registration by opening your Infisical dashboard, navigating to **Organization Access Control**, and selecting the **Gateways** tab. Your newly deployed Gateway should appear in the list.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -6,86 +6,124 @@ description: "Understand the security model and tenant isolation of Infisical's
|
||||
|
||||
# Gateway Security Architecture
|
||||
|
||||
The Infisical Gateway enables Infisical Cloud to securely interact with private resources using mutual TLS authentication and private PKI (Public Key Infrastructure) system to ensure secure, isolated communication between multiple tenants.
|
||||
The Infisical Gateway enables secure access to private resources using SSH reverse tunnels, certificate-based authentication, and a comprehensive PKI (Public Key Infrastructure) system. The architecture provides end-to-end encryption and complete tenant isolation through multiple certificate authorities.
|
||||
This document explains the internal security architecture and how tenant isolation is maintained.
|
||||
|
||||
## Security Model Overview
|
||||
|
||||
### Private PKI System
|
||||
Each organization (tenant) in Infisical has its own private PKI system consisting of:
|
||||
### Certificate Architecture
|
||||
|
||||
1. **Root CA**: The ultimate trust anchor for the organization
|
||||
2. **Intermediate CAs**:
|
||||
- Client CA: Issues certificates for cloud components
|
||||
- Gateway CA: Issues certificates for gateway instances
|
||||
The gateway system uses multiple certificate authorities depending on deployment configuration:
|
||||
|
||||
This hierarchical structure ensures complete isolation between organizations as each has its own independent certificate chain.
|
||||
**For Organizations Using Infisical-Managed Proxies:**
|
||||
|
||||
- **Instance proxy SSH Client CA & Server CA** - Gateway ↔ Infisical Proxy Server authentication
|
||||
- **Instance proxy PKI Client CA & Server CA** - Platform ↔ Infisical Proxy Server authentication
|
||||
- **Organization Gateway Client CA & Server CA** - Platform ↔ Gateway authentication
|
||||
|
||||
**For Organizations Using Customer-Deployed Proxies:**
|
||||
|
||||
- **Organization proxy SSH Client CA & Server CA** - Gateway ↔ Customer Proxy Server authentication
|
||||
- **Organization proxy PKI Client CA & Server CA** - Platform ↔ Customer Proxy Server authentication
|
||||
- **Organization Gateway Client CA & Server CA** - Platform ↔ Gateway authentication
|
||||
|
||||
### Certificate Hierarchy
|
||||
|
||||
```
|
||||
Root CA (Organization Specific)
|
||||
├── Client CA
|
||||
│ └── Client Certificates (Cloud Components)
|
||||
└── Gateway CA
|
||||
└── Gateway Certificates (Gateway Instances)
|
||||
Instance Level (Shared Proxies):
|
||||
├── Instance Proxy SSH CA (Gateway ↔ Proxy)
|
||||
├── Instance Proxy PKI CA (Platform ↔ Proxy)
|
||||
|
||||
Organization Level:
|
||||
├── Organization Proxy SSH CA (Gateway ↔ Org Proxy)
|
||||
├── Organization Proxy PKI CA (Platform ↔ Org Proxy)
|
||||
└── Organization Gateway CA (Platform ↔ Gateway)
|
||||
```
|
||||
|
||||
## Communication Security
|
||||
|
||||
### 1. Gateway Registration
|
||||
|
||||
When a gateway is first deployed:
|
||||
|
||||
1. Establishes initial connection using machine identity token
|
||||
2. Allocates a relay address for communication
|
||||
3. Exchanges certificates through a secure handshake:
|
||||
- Gateway receives a unique certificate signed by organization's Gateway CA along with certificate chain for verification
|
||||
1. Authenticates with Infisical using machine identity token
|
||||
2. Receives SSH certificates for proxy server authentication
|
||||
3. Establishes SSH reverse tunnel to assigned proxy server
|
||||
4. Certificate issuance varies by proxy configuration:
|
||||
- **Infisical-managed proxy**: Receives Instance proxy SSH client certificate + Instance proxy SSH Server CA
|
||||
- **Customer-deployed proxy**: Receives Organization proxy SSH client certificate + Organization proxy SSH Server CA
|
||||
|
||||
### 2. Mutual TLS Authentication
|
||||
All communication between gateway and cloud uses mutual TLS (mTLS):
|
||||
### 2. SSH Tunnel Authentication
|
||||
|
||||
Gateway ↔ Proxy Server communication uses SSH certificate authentication:
|
||||
|
||||
- **Gateway Authentication**:
|
||||
- Presents certificate signed by organization's Gateway CA
|
||||
- Certificate contains unique identifiers (Organization ID, Gateway ID)
|
||||
- Cloud validates complete certificate chain
|
||||
|
||||
- **Cloud Authentication**:
|
||||
- Presents certificate signed by organization's Client CA
|
||||
- Certificate includes required organizational unit ("gateway-client")
|
||||
- Gateway validates certificate chain back to organization's root CA
|
||||
- Presents SSH client certificate (Instance or Organization proxy SSH Client CA)
|
||||
- Certificate contains gateway identification and permissions
|
||||
- Proxy server validates certificate against appropriate SSH Client CA
|
||||
|
||||
### 3. Relay Communication
|
||||
The relay system provides secure tunneling:
|
||||
- **Proxy Server Authentication**:
|
||||
- Presents SSH server certificate (Instance or Organization proxy SSH Server CA)
|
||||
- Gateway validates certificate against appropriate SSH Server CA
|
||||
- Ensures gateway connects to legitimate proxy infrastructure
|
||||
|
||||
1. **Connection Establishment**:
|
||||
- Uses QUIC protocol over UDP for efficient, secure communication
|
||||
- Provides built-in encryption, congestion control, and multiplexing
|
||||
- Enables faster connection establishment and reduced latency
|
||||
- Each organization's traffic is isolated using separate relay sessions
|
||||
### 3. Application Traffic Security
|
||||
|
||||
2. **Traffic Isolation**:
|
||||
- Each gateway gets unique relay credentials
|
||||
- Traffic is end-to-end encrypted using QUIC's TLS 1.3
|
||||
End-to-end encryption for application data:
|
||||
|
||||
1. **mTLS Layer**:
|
||||
|
||||
- Infisical platform establishes mTLS connections directly with gateways
|
||||
- Uses Organization Gateway certificates for authentication
|
||||
- Application traffic is encrypted end-to-end between platform and gateway
|
||||
|
||||
2. **SSH Tunnel Layer**:
|
||||
|
||||
- mTLS-encrypted application traffic travels through SSH reverse tunnels
|
||||
- Creates double encryption: mTLS payload within SSH tunnel
|
||||
- Proxy servers cannot decrypt either encryption layer
|
||||
|
||||
3. **Traffic Isolation**:
|
||||
- Each gateway maintains separate SSH tunnels
|
||||
- Organization's private keys never leave their environment
|
||||
- Complete cryptographic isolation between organizations
|
||||
|
||||
## Tenant Isolation
|
||||
|
||||
### Certificate-Based Isolation
|
||||
- Each organization has unique root CA and intermediate CAs
|
||||
- Certificates contain organization-specific identifiers
|
||||
- Cross-tenant communication is cryptographically impossible
|
||||
### Multi-Layer Certificate Isolation
|
||||
|
||||
### Gateway-Project Mapping
|
||||
- Gateways are explicitly mapped to specific projects
|
||||
- Access controls enforce organization boundaries
|
||||
- Project-level permissions determine resource accessibility
|
||||
The architecture provides tenant isolation through multiple certificate authority layers:
|
||||
|
||||
- **Instance-level CAs**: Shared proxy infrastructure uses instance-level certificates
|
||||
- **Organization-level CAs**: Each organization has unique certificate authorities
|
||||
- **Proxy deployment flexibility**: Organizations can choose shared or dedicated proxy infrastructure
|
||||
- **Cryptographic separation**: Cross-tenant communication is cryptographically impossible
|
||||
|
||||
### Authentication Flows by Deployment Type
|
||||
|
||||
**Infisical-Managed Proxy Deployments:**
|
||||
|
||||
- Gateway authenticates with proxy using Instance proxy SSH certificates
|
||||
- Platform authenticates with proxy using Instance proxy PKI certificates
|
||||
- Platform authenticates with gateway using Organization Gateway certificates
|
||||
|
||||
**Customer-Deployed Proxy Deployments:**
|
||||
|
||||
- Gateway authenticates with proxy using Organization proxy SSH certificates
|
||||
- Platform authenticates with proxy using Organization proxy PKI certificates
|
||||
- Platform authenticates with gateway using Organization Gateway certificates
|
||||
|
||||
### Resource Access Control
|
||||
1. **Project Verification**:
|
||||
- Gateway verifies project membership
|
||||
- Validates organization ownership
|
||||
- Enforces project-level permissions
|
||||
|
||||
2. **Resource Restrictions**:
|
||||
- Gateways only accept connections to approved resources
|
||||
- Each connection requires explicit project authorization
|
||||
- Resources remain private to their assigned organization
|
||||
1. **Certificate Validation**:
|
||||
|
||||
- All connections require valid certificates from appropriate CAs
|
||||
- Embedded certificate details control access permissions
|
||||
- Ephemeral certificate validation ensures time-bound access
|
||||
|
||||
2. **Network Isolation**:
|
||||
|
||||
- Each organization's traffic flows through isolated certificate-authenticated channels
|
||||
- Proxy servers route traffic based on certificate validation without content access
|
||||
- Gateway validates all incoming connections against Organization Gateway Client CA
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -4,33 +4,53 @@ sidebarTitle: "Overview"
|
||||
description: "How to access private network resources from Infisical"
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
The Infisical Gateway provides secure access to private resources within your network without needing direct inbound connections to your environment. This method keeps your resources fully protected from external access while enabling Infisical to securely interact with resources like databases.
|
||||
|
||||
**Architecture Components:**
|
||||
|
||||
- **Gateway**: Lightweight agent deployed within your VPCs that provides access to private resources
|
||||
- **Proxy**: Identity-aware relay infrastructure that routes encrypted traffic (instance-wide or organization-specific)
|
||||
|
||||
The Infisical Gateway provides secure access to private resources within your network without needing direct inbound connections to your environment.
|
||||
This method keeps your resources fully protected from external access while enabling Infisical to securely interact with resources like databases.
|
||||
Common use cases include generating dynamic credentials or rotating credentials for private databases.
|
||||
|
||||
<Info>
|
||||
**Note:** Gateway is a paid feature. - **Infisical Cloud users:** Gateway is
|
||||
available under the **Enterprise Tier**. - **Self-Hosted Infisical:** Please
|
||||
contact [sales@infisical.com](mailto:sales@infisical.com) to purchase an
|
||||
enterprise license.
|
||||
Gateway is a paid feature available under the Enterprise Tier for Infisical
|
||||
Cloud users. Self-hosted Infisical users can contact
|
||||
[sales@infisical.com](mailto:sales@infisical.com) to purchase an enterprise
|
||||
license.
|
||||
</Info>
|
||||
|
||||
## How It Works
|
||||
|
||||
The Gateway serves as a secure intermediary that facilitates direct communication between the Infisical server and your private network.
|
||||
It’s a lightweight daemon packaged within the Infisical CLI, making it easy to deploy and manage. Once set up, the Gateway establishes a connection with a relay server, ensuring that all communication between Infisical and your Gateway is fully end-to-end encrypted.
|
||||
This setup guarantees that only the platform and your Gateway can decrypt the transmitted information, keeping communication with your resources secure, private and isolated.
|
||||
The Gateway system uses SSH reverse tunnels for secure, firewall-friendly connectivity:
|
||||
|
||||
1. **Gateway Registration**: The gateway establishes an outbound SSH reverse tunnel to a proxy server using SSH certificates issued by Infisical
|
||||
2. **Proxy Routing**: The proxy server acts as an identity-aware relay that routes encrypted traffic between the Infisical platform and gateways
|
||||
3. **Resource Access**: The Infisical platform connects to your private resources through the established gateway connections
|
||||
|
||||
**Key Benefits:**
|
||||
|
||||
- **No inbound firewall rules needed** - all connections are outbound from your network
|
||||
- **Firewall-friendly** - uses standard SSH over TCP
|
||||
- **Certificate-based authentication** provides enhanced security
|
||||
- **Automatic reconnection** if connections are lost
|
||||
|
||||
## Deployment
|
||||
|
||||
The Infisical Gateway is seamlessly integrated into the Infisical CLI under the `gateway` command, making it simple to deploy and manage.
|
||||
The Infisical Gateway is integrated into the Infisical CLI under the `network gateway` command, making it simple to deploy and manage.
|
||||
You can install the Gateway in all the same ways you install the Infisical CLI—whether via npm, Docker, or a binary.
|
||||
For detailed installation instructions, refer to the Infisical [CLI Installation instructions](/cli/overview).
|
||||
|
||||
To function, the Gateway must authenticate with Infisical. This requires a machine identity configured with the appropriate permissions to create and manage a Gateway.
|
||||
Once authenticated, the Gateway establishes a secure connection with Infisical to allow your private resources to be reachable.
|
||||
**Prerequisites:**
|
||||
|
||||
1. **Proxy Server**: Before deploying gateways, you need a running proxy server:
|
||||
- **Infisical Cloud**: Instance proxies are already available - no setup needed
|
||||
- **Self-hosted**: Instance admin must set up shared instance proxies, or organizations can deploy their own
|
||||
2. **Machine Identity**: Configure a machine identity with appropriate permissions to create and manage gateways
|
||||
|
||||
Once authenticated, the Gateway establishes an SSH reverse tunnel to the specified proxy server, allowing secure access to your private resources.
|
||||
|
||||
### Get started
|
||||
|
||||
@@ -46,6 +66,36 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
You'll need to choose an authentication method to initiate communication with Infisical. View the available machine identity authentication methods [here](/documentation/platform/identities/machine-identities).
|
||||
</Step>
|
||||
|
||||
<Step title="Choose Your Proxy Setup">
|
||||
You have two options for proxy infrastructure:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Use Instance Proxies (Easiest)">
|
||||
**Infisical Cloud:** Instance proxies are already running and available - **no setup required**. You can immediately proceed to deploy gateways using these shared proxies.
|
||||
|
||||
**Self-hosted:** If your instance admin has set up shared instance proxies, you can use them directly. If not, the instance admin can set them up:
|
||||
```bash
|
||||
# Instance admin sets up shared proxy (one-time setup)
|
||||
export INFISICAL_PROXY_AUTH_SECRET=<instance-proxy-secret>
|
||||
infisical network proxy --type=instance --ip=<public-ip> --name=<proxy-name>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Deploy Your Own Organization Proxy">
|
||||
**Available for all users:** Deploy your own dedicated proxy infrastructure for enhanced control:
|
||||
```bash
|
||||
# Deploy organization-specific proxy
|
||||
infisical network proxy --type=org --ip=<public-ip> --name=<proxy-name> --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>
|
||||
```
|
||||
|
||||
**When to choose this:**
|
||||
- You need lower latency (deploy closer to your resources)
|
||||
- Enhanced security requirements
|
||||
- Compliance needs (data sovereignty, air-gapped environments)
|
||||
- Custom network policies
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
|
||||
<Step title="Deploy the Gateway">
|
||||
Use the Infisical CLI to deploy the Gateway. You can run it directly or install it as a systemd service for production:
|
||||
|
||||
@@ -53,7 +103,7 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
<Tab title="Production (systemd)">
|
||||
For production deployments on Linux, install the Gateway as a systemd service:
|
||||
```bash
|
||||
sudo infisical gateway install --token <your-machine-identity-token> --domain <your-infisical-domain>
|
||||
sudo infisical network gateway install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --proxy-name <proxy-name>
|
||||
sudo systemctl start infisical-gateway
|
||||
```
|
||||
This will install and start the Gateway as a secure systemd service that:
|
||||
@@ -81,7 +131,7 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
|
||||
### Install the latest Helm Chart repository
|
||||
```bash
|
||||
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
|
||||
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
|
||||
```
|
||||
|
||||
### Update the Helm Chart repository
|
||||
@@ -116,7 +166,12 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
</ParamField>
|
||||
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=universal-auth --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> --from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret>
|
||||
kubectl create secret generic infisical-gateway-environment \
|
||||
--from-literal=INFISICAL_AUTH_METHOD=universal-auth \
|
||||
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> \
|
||||
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret> \
|
||||
--from-literal=INFISICAL_PROXY_NAME=<proxy-name> \
|
||||
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
@@ -283,6 +338,29 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
#### Required environment variables
|
||||
|
||||
In addition to the authentication method above, you **must** include these required variables:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="INFISICAL_PROXY_NAME">
|
||||
The name of the proxy server that this gateway should connect to.
|
||||
</Accordion>
|
||||
<Accordion title="INFISICAL_GATEWAY_NAME">
|
||||
The name of this gateway instance.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
**Complete example with required variables:**
|
||||
```bash
|
||||
kubectl create secret generic infisical-gateway-environment \
|
||||
--from-literal=INFISICAL_AUTH_METHOD=universal-auth \
|
||||
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=<client-id> \
|
||||
--from-literal=INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=<client-secret> \
|
||||
--from-literal=INFISICAL_PROXY_NAME=<proxy-name> \
|
||||
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
|
||||
```
|
||||
|
||||
#### Other environment variables
|
||||
|
||||
<AccordionGroup>
|
||||
@@ -306,14 +384,12 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
|
||||
You should see the following output which indicates the gateway is running as expected.
|
||||
```bash
|
||||
$ kubectl logs deployment/infisical-gateway
|
||||
INF Provided relay port 5349. Using TLS
|
||||
INF Connected with relay
|
||||
INF 10.0.101.112:56735
|
||||
INF Starting relay connection health check
|
||||
INF Gateway started successfully
|
||||
INF New connection from: 10.0.1.8:34051
|
||||
INF Gateway is reachable by Infisical
|
||||
$ kubectl logs deployment/infisical-gateway
|
||||
INF Starting gateway
|
||||
INF Starting gateway certificate renewal goroutine
|
||||
INF Successfully registered gateway and received certificates
|
||||
INF Connecting to proxy server infisical-start on 152.42.218.156:2222...
|
||||
INF Proxy connection established for gateway
|
||||
```
|
||||
|
||||
</Tab>
|
||||
@@ -321,27 +397,31 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
<Tab title="Local Installation (testing)">
|
||||
For development or testing, you can run the Gateway directly. Log in with your machine identity and start the Gateway in one command:
|
||||
```bash
|
||||
infisical gateway --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain)
|
||||
infisical network gateway --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --proxy-name=<proxy-name> --name=<gateway-name>
|
||||
```
|
||||
|
||||
Alternatively, if you already have the token, use it directly with the `--token` flag:
|
||||
```bash
|
||||
infisical gateway --token <your-machine-identity-token>
|
||||
infisical network gateway --token <your-machine-identity-token> --proxy-name=<proxy-name> --name=<gateway-name>
|
||||
```
|
||||
|
||||
Or set it as an environment variable:
|
||||
```bash
|
||||
export INFISICAL_TOKEN=<your-machine-identity-token>
|
||||
infisical gateway
|
||||
infisical network gateway --proxy-name=<proxy-name> --name=<gateway-name>
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
For detailed information about the gateway command and its options, see the [gateway command documentation](/cli/commands/gateway).
|
||||
For detailed information about the network commands and their options, see the [network command documentation](/cli/commands/network).
|
||||
|
||||
<Note>
|
||||
Ensure the deployed Gateway has network access to the private resources you intend to connect with Infisical.
|
||||
**Requirements:**
|
||||
- Ensure the deployed Gateway has network access to the private resources you intend to connect with Infisical
|
||||
- The gateway must be able to reach the proxy server (outbound connection only)
|
||||
- Replace `<proxy-name>` with the name of your proxy server and `<gateway-name>` with a unique name for this gateway
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify Gateway Deployment">
|
||||
|
||||
BIN
docs/images/platform/gateways/gateway-highlevel-diagram.png
Normal file
BIN
docs/images/platform/gateways/gateway-highlevel-diagram.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 111 KiB |
Reference in New Issue
Block a user