Gateway

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)

Common use cases include generating dynamic credentials or rotating credentials for private databases.

Gateway is a paid feature available under the Enterprise Tier for Infisical Cloud users. Self-hosted Infisical users can contact [e-mail] to purchase an enterprise license.

How It Works

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 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.

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

1. 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.
2. Configure Authentication Method

   You’ll need to choose an authentication method to initiate communication with Infisical. View the available machine identity authentication methods here.

3. Choose Your Proxy Setup

   You have two options for proxy infrastructure:

   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:

   # 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>
   

   Deploy Your Own Organization Proxy

   Available for all users: Deploy your own dedicated proxy infrastructure for enhanced control:

   # 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
4. 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:

   Production (systemd)

   For production deployments on Linux, install the Gateway as a systemd service:

   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:

   • 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

   The install command requires:

   • Linux operating system
   • Root/sudo privileges
   • Systemd

   Production (Helm)

   The Gateway can be installed via Helm. 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

   helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
   

   Update the Helm Chart repository

   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

   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.

   Environment Variables

   Show properties

   INFISICAL_UNIVERSAL_AUTH_CLIENT_ID · string · required

   Your machine identity client ID.

   INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET · string · required

   Your machine identity client secret.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be universal-auth when using Universal Auth.

     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>
   

   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.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH · string

   Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be kubernetes when using Native Kubernetes.

     kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=kubernetes --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
   

   Native Azure

   The Native Azure method is used to authenticate with Infisical when running in an Azure environment.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be azure when using Native Azure.

     kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=azure --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
   

   Native GCP ID Token

   The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

     kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=gcp-id-token --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
   

   GCP IAM

   The GCP IAM method is used to authenticate with Infisical with a GCP service account key.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_GCP_SERVICE_ACCOUNT_KEY_FILE_PATH · string · required

   Path to your GCP service account key file (Must be in JSON format!)

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be gcp-iam when using GCP IAM.

     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>
   

   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.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be aws-iam when using Native AWS IAM.

     kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_AUTH_METHOD=aws-iam --from-literal=INFISICAL_MACHINE_IDENTITY_ID=<machine-identity-id>
   

   OIDC Auth

   The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.

   Environment Variables

   Show properties

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_JWT · string · required

   The OIDC JWT from the identity provider.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be oidc-auth when using OIDC Auth.

     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>
   

   JWT Auth

   The JWT Auth method is used to authenticate with Infisical via a JWT token.

   Environment Variables

   Show properties

   INFISICAL_JWT · string · required

   The JWT token to use for authentication.

   INFISICAL_MACHINE_IDENTITY_ID · string · required

   Your machine identity ID.

   INFISICAL_AUTH_METHOD · string · required

   The authentication method to use. Must be jwt-auth when using JWT Auth.

     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>
   

   Token Auth

   You can use the INFISICAL_TOKEN environment variable to authenticate with Infisical with a raw machine identity access token.

   Environment Variables

   Show properties

   INFISICAL_TOKEN · string · required

   The machine identity access token to use for authentication.

     kubectl create secret generic infisical-gateway-environment --from-literal=INFISICAL_TOKEN=<token>
   

   Required environment variables

   In addition to the authentication method above, you must include these required variables:

   INFISICAL_PROXY_NAME

   The name of the proxy server that this gateway should connect to.

   INFISICAL_GATEWAY_NAME

   The name of this gateway instance.

   Complete example with required variables:

   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

   INFISICAL_API_URL

   The API URL to use for the gateway. By default, INFISICAL_API_URL is set to https://app.infisical.com.

   Install the Infisical Gateway Helm Chart

   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.

   kubectl logs deployment/infisical-gateway
   

   You should see the following output which indicates the gateway is running as expected.

   $ 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
   

   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:

   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:

   infisical network gateway --token <your-machine-identity-token> --proxy-name=<proxy-name> --name=<gateway-name>
   

   Or set it as an environment variable:

   export INFISICAL_TOKEN=<your-machine-identity-token>
   infisical network gateway --proxy-name=<proxy-name> --name=<gateway-name>
   

   For detailed information about the network commands and their options, see the network command documentation.

   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
5. 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.