mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Merge branch 'heads/main' into ENG-3630
This commit is contained in:
Daniel Hougaard
@@ -6,84 +6,285 @@ description: "Learn how to stream Infisical Audit Logs to external logging provi
|
||||
<Info>
|
||||
Audit log streams is a paid feature.
|
||||
|
||||
If you're using Infisical Cloud, then it is available under the **Enterprise Tier**. If you're self-hosting Infisical,
|
||||
then you should contact team@infisical.com to purchase an enterprise license to use it.
|
||||
If you're using Infisical Cloud, then it is available under the **Enterprise Tier**. If you're self-hosting Infisical, then you should contact team@infisical.com to purchase an enterprise license to use it.
|
||||
</Info>
|
||||
|
||||
Infisical Audit Log Streaming enables you to transmit your organization's Audit Logs to external logging providers for monitoring and analysis.
|
||||
|
||||
The logs are formatted in JSON, requiring your logging provider to support JSON-based log parsing.
|
||||
|
||||
Infisical Audit Log Streaming enables you to transmit your organization's audit logs to external logging providers for monitoring and analysis.
|
||||
|
||||
## Overview
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Organization Settings in your sidebar." />
|
||||
<Step title="Select Audit Log Streams Tab.">
|
||||
|
||||
</Step>
|
||||
<Step title="Click on Create">
|
||||
|
||||
<Step title="Create Stream">
|
||||
1. Navigate to **Organization Settings**
|
||||
2. Select the **Audit Log Streams** tab
|
||||
3. Click **Add Log Stream**
|
||||
|
||||
Provide the following values
|
||||
<ParamField path="Endpoint URL" type="string" required>
|
||||
The HTTPS endpoint URL of the logging provider that collects the JSON stream.
|
||||
</ParamField>
|
||||
<ParamField path="Headers" type="string" >
|
||||
The HTTP headers for the logging provider for identification and authentication.
|
||||
</ParamField>
|
||||
|
||||
</Step>
|
||||
<Step title="Select Provider">
|
||||
If your log provider is included in this list, select it. Otherwise click on **Custom** to input your own Endpoint URL and headers.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Input Credentials">
|
||||
Depending on your chosen provider, you'll be asked to input different credentials.
|
||||
|
||||
For **Custom**, you need to input an endpoint URL and headers.
|
||||
|
||||
|
||||
|
||||
Once you're finished, click **Create Log Stream**.
|
||||
</Step>
|
||||
<Step title="Log Stream Created">
|
||||
Your audit logs are now ready to be streamed.
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
|
||||
Your Audit Logs are now ready to be streamed.
|
||||
|
||||
## Example Providers
|
||||
|
||||
### Better Stack
|
||||
<AccordionGroup>
|
||||
<Accordion title="Azure">
|
||||
Infisical offers a dedicated **Azure** provider to stream your audit logs, enabling seamless integration with services like Microsoft Sentinel.
|
||||
|
||||
<Steps>
|
||||
<Step title="Select Connect Source">
|
||||
|
||||
</Step>
|
||||
<Step title="Provide a name and select platform"/>
|
||||
<Step title="Provide Audit Log Stream inputs">
|
||||
|
||||
<Warning>
|
||||
After setting up all Azure resources, it may take 10-20 minutes for logs to begin streaming.
|
||||
</Warning>
|
||||
|
||||
1. Copy the **endpoint** from Better Stack to the **Endpoint URL** field.
|
||||
3. Create a new header with key **Authorization** and set the value as **Bearer \<source token from betterstack\>**.
|
||||
</Step>
|
||||
</Steps>
|
||||
<Steps>
|
||||
<Step title="Create a Data Collection Endpoint">
|
||||
Navigate to [Data Collection Endpoints](https://portal.azure.com/#view/HubsExtension/BrowseResource.ReactView/resourceType/microsoft.insights%2Fdatacollectionendpoints) and click **Create**.
|
||||
|
||||
### Datadog
|
||||
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to API Keys section">
|
||||
|
||||
</Step>
|
||||
<Step title="Select New Key and provide a key name">
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Find your Datadog region specific logging endpoint.">
|
||||
|
||||
Configure your Data Collection Endpoint by providing an **Endpoint Name**, **Subscription**, and a **Resource group**. Then click **Review + Create**.
|
||||
|
||||
1. Navigate to the [Datadog Send Logs API documentation](https://docs.datadoghq.com/api/latest/logs/?code-lang=curl&site=us5#send-logs).
|
||||
2. Pick your Datadog account region.
|
||||
3. Obtain your Datadog logging endpoint URL.
|
||||
</Step>
|
||||
<Step title="Provide audit log stream inputs">
|
||||
|
||||
|
||||
|
||||
1. Copy the **logging endpoint** from Datadog to the **Endpoint URL** field.
|
||||
2. Copy the **API Key** from previous step
|
||||
3. Create a new header with key **DD-API-KEY** and set the value as **API Key**.
|
||||
</Step>
|
||||
</Steps>
|
||||
After creation, it may take a few minutes for the Data Collection Endpoint to appear. Once visible, click on it and copy the **Logs Ingestion** URL. You will need this URL in later steps.
|
||||
|
||||
## Audit Log Stream Data
|
||||
|
||||
</Step>
|
||||
<Step title="Create a Log Analytics Workspace">
|
||||
<Info>
|
||||
If you already have a Log Analytics Workspace, you may skip this step.
|
||||
</Info>
|
||||
|
||||
Each log entry sent to the external logging provider will follow the same structure.
|
||||
Navigate to [Log Analytics Workspaces](https://portal.azure.com/#browse/Microsoft.OperationalInsights%2Fworkspaces) and click **Create**.
|
||||
|
||||
|
||||
|
||||
Configure your Log Analytics Workspace by providing a **Subscription**, **Resource group**, and a **Name**. Then click **Review + Create**.
|
||||
|
||||
|
||||
|
||||
Once the workspace is deployed, click **Go to resource** to access it.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create a Custom Log Table">
|
||||
Within your Log Analytics Workspace, navigate to **Tables** and click **Create**. Select **New custom log (DCR-based)** from the dropdown.
|
||||
|
||||
|
||||
|
||||
Configure the Custom Log Table: Provide a **Table name** (e.g., `InfisicalLogs`), select the **Data collection endpoint** created in Step 1, and create a new **Data collection rule** as illustrated in the image below. Then, click **Next**.
|
||||
|
||||
|
||||
|
||||
On the **Schema and transformation** page, you'll be prompted to upload a **Log Sample**. Create a `.json` file with the following content and upload it:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "00000000-0000-0000-0000-000000000000",
|
||||
"actor": "user",
|
||||
"actorMetadata": {
|
||||
"email": "user@example.com",
|
||||
"userId": "00000000-0000-0000-0000-000000000000",
|
||||
"username": "user@example.com"
|
||||
},
|
||||
"ipAddress": "0.0.0.0",
|
||||
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36",
|
||||
"userAgentType": "web",
|
||||
"eventType": "get-secrets",
|
||||
"eventMetadata": {},
|
||||
"projectName": "MyProject",
|
||||
"orgId": "00000000-0000-0000-0000-000000000000",
|
||||
"projectId": "00000000-0000-0000-0000-000000000000",
|
||||
"TimeGenerated": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
Optionally, you can add **Transformations** to further destructure the data. For example, to extract actor email and userId:
|
||||
|
||||
```
|
||||
source
|
||||
| extend
|
||||
ActorEmail = tostring(actorMetadata.email),
|
||||
ActorUserId = tostring(actorMetadata.userId)
|
||||
```
|
||||
|
||||
On the final step, click **Create**.
|
||||
|
||||
<Warning>
|
||||
It may take a few minutes for your Custom Log Table to be created and appear under Tables.
|
||||
</Warning>
|
||||
</Step>
|
||||
<Step title="Obtain Data Collection Rule Immutable ID">
|
||||
After creating your Data Collection Rule, you'll need its **Immutable ID**.
|
||||
|
||||
Navigate to [Data collection rules](https://portal.azure.com/#view/HubsExtension/BrowseResource.ReactView/resourceType/microsoft.insights%2Fdatacollectionrules). Click on your newly created DCR and copy its **Immutable ID** for the next step.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create Audit Log Stream on Infisical">
|
||||
In Infisical, create a new audit log stream and select the **Azure** provider. Input the following details:
|
||||
|
||||
- **Tenant ID**: Your Tenant ID
|
||||
- **Client ID**: The Client ID of an App Registration
|
||||
- **Client Secret**: The Client Secret of an App Registration
|
||||
- **Data Collection Endpoint URL**: Obtained from Step 1
|
||||
- **Data Collection Rule Immutable ID**: Obtained from Step 4
|
||||
- **Custom Log Table Name**: Defined in Step 3
|
||||
|
||||
|
||||
|
||||
<Warning>
|
||||
The App Registration used for authentication must have the **Monitoring Metrics Publisher** role assigned on the **Data Collection Rule** created in Step 3. [See Microsoft Guide](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/tutorial-logs-ingestion-portal#assign-permissions-to-the-dcr).
|
||||
</Warning>
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Better Stack">
|
||||
You can stream to Better Stack using a **Custom** log stream.
|
||||
|
||||
<Steps>
|
||||
<Step title="Connect Source">
|
||||
On Better Stack, select **Connect Source** and click **Create source** after providing a name.
|
||||
|
||||
|
||||
|
||||
Once your source is created, take note of the **endpoint** and **Source token** for the next step.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create Audit Log Stream on Infisical">
|
||||
On Infisical, create a new audit log stream and select the **Custom** option.
|
||||
|
||||
|
||||
|
||||
1. Fill in the endpoint URL with your Better Stack source endpoint
|
||||
2. Create a new header with key `Authorization` and set the value as `Bearer <betterstack-src-token>`
|
||||
|
||||
|
||||
|
||||
Once you're finished, click **Create Log Stream**.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Cribl">
|
||||
Stream Infisical audit logs to Cribl Stream for centralized processing and routing. Infisical supports Cribl as a provider for seamless integration.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create Infisical Data Source">
|
||||
In Cribl Stream, navigate to **Worker Groups** and select your Worker Group. Take note of the **Ingress Address** for later steps.
|
||||
|
||||
|
||||
|
||||
Within your Worker Group, navigate to **Data > Sources > HTTP** and click **Add Source**.
|
||||
|
||||
|
||||
|
||||
Configure the **Input ID**, **Port**, and **Cribl HTTP event API** path (e.g., `/infisical`). Then, generate an **Auth Token**.
|
||||
|
||||
You can optionally configure TLS in the **TLS Settings** tab and add a pipeline in the **Pre-Processing** tab.
|
||||
|
||||
<Warning>
|
||||
Ensure that you're using a port that's open on your instance.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
Once you've configured the Data Source, click **Save** and deploy your changes.
|
||||
</Step>
|
||||
<Step title="Create Audit Log Stream on Infisical">
|
||||
On Infisical, create a new audit log stream and select the **Cribl** provider option.
|
||||
|
||||
Input the following credentials:
|
||||
- **Cribl Stream URL**: Your HTTP source endpoint composed of `http://<ingress-address>:<port>/<http-event-api-path>/_bulk`
|
||||
- **Cribl Stream Token**: The authentication token from Step 1
|
||||
|
||||
<Info>
|
||||
If you configured TLS for your Data Source, use the `https://` protocol.
|
||||
</Info>
|
||||
|
||||
|
||||
|
||||
Once you're finished, click **Create Log Stream**.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Datadog">
|
||||
You can stream to Datadog using the **Datadog** provider log stream.
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to API Keys section">
|
||||
|
||||
</Step>
|
||||
<Step title="Select New Key and provide a key name">
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create Audit Log Stream on Infisical">
|
||||
On Infisical, create a new audit log stream and select the **Datadog** provider option.
|
||||
|
||||
Input your **Datadog Region** and the **Token** obtained from step 2.
|
||||
|
||||
|
||||
|
||||
Once you're finished, click **Create Log Stream**.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Splunk">
|
||||
You can stream to Splunk using the **Splunk** provider log stream.
|
||||
|
||||
<Steps>
|
||||
<Step title="Obtain Splunk Token">
|
||||
Navigate to **Settings** > **Data Inputs**.
|
||||
|
||||
|
||||
|
||||
Click on **HTTP Event Collector**.
|
||||
|
||||
|
||||
|
||||
Click on **New Token** in the top left.
|
||||
|
||||
|
||||
|
||||
Provide a name and click **Next**.
|
||||
|
||||
|
||||
|
||||
On the next page, click **Review** and then **Submit** at the top. On the final page you'll see your token.
|
||||
|
||||
Copy the **Token Value** and your Splunk hostname from the URL to be used for later.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Create Audit Log Stream on Infisical">
|
||||
On Infisical, create a new audit log stream and select the **Splunk** provider option.
|
||||
|
||||
Input your **Splunk Hostname** and the **Token** obtained from step 1.
|
||||
|
||||
|
||||
|
||||
Once you're finished, click **Create Log Stream**.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Example Log Entry
|
||||
|
||||
@@ -117,106 +318,109 @@ Each log entry sent to the external logging provider will follow the same struct
|
||||
```
|
||||
|
||||
### Audit Logs Structure
|
||||
|
||||
<Warning>
|
||||
Streamed audit log structure **varies based on provider**, but they all share the audit log fields shown below.
|
||||
</Warning>
|
||||
|
||||
<ParamField path="id" type="string" required>
|
||||
The unique identifier for the log entry.
|
||||
The unique identifier for the log entry.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="actor" type="platform | user | service | identity | scimClient | unknownUser" required>
|
||||
The entity responsible for performing or causing the event; this can be a user or service.
|
||||
The entity responsible for performing or causing the event; this can be a user or service.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="actorMetadata" type="object" required>
|
||||
The metadata associated with the actor. This varies based on the actor type.
|
||||
The metadata associated with the actor. This varies based on the actor type.
|
||||
|
||||
<Accordion title="User Metadata">
|
||||
This metadata is present when the `actor` field is set to `user`.
|
||||
<AccordionGroup>
|
||||
<Accordion title="User Metadata">
|
||||
This metadata is present when the `actor` field is set to `user`.
|
||||
|
||||
<ParamField path="userId" type="string" required>
|
||||
The unique identifier for the actor.
|
||||
</ParamField>
|
||||
<ParamField path="email" type="string" required>
|
||||
The email address of the actor.
|
||||
</ParamField>
|
||||
<ParamField path="username" type="string" required>
|
||||
The username of the actor.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
<ParamField path="userId" type="string" required>
|
||||
The unique identifier for the actor.
|
||||
</ParamField>
|
||||
<ParamField path="email" type="string" required>
|
||||
The email address of the actor.
|
||||
</ParamField>
|
||||
<ParamField path="username" type="string" required>
|
||||
The username of the actor.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
<Accordion title="Identity Metadata">
|
||||
This metadata is present when the `actor` field is set to `identity`.
|
||||
|
||||
<Accordion title="Identity Metadata">
|
||||
This metadata is present when the `actor` field is set to `identity`.
|
||||
<ParamField path="identityId" type="string" required>
|
||||
The unique identifier for the identity.
|
||||
</ParamField>
|
||||
<ParamField path="name" type="string" required>
|
||||
The name of the identity.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
<Accordion title="Service Token Metadata">
|
||||
This metadata is present when the `actor` field is set to `service`.
|
||||
|
||||
<ParamField path="identityId" type="string" required>
|
||||
The unique identifier for the identity.
|
||||
</ParamField>
|
||||
<ParamField path="name" type="string" required>
|
||||
The name of the identity.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Service Token Metadata">
|
||||
This metadata is present when the `actor` field is set to `service`.
|
||||
|
||||
<ParamField path="serviceId" type="string" required>
|
||||
The unique identifier for the service.
|
||||
</ParamField>
|
||||
<ParamField path="name" type="string" required>
|
||||
The name of the service.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
|
||||
|
||||
<Note>
|
||||
If the `actor` field is set to `platform`, `scimClient`, or `unknownUser`, the `actorMetadata` field will be an empty object.
|
||||
</Note>
|
||||
<ParamField path="serviceId" type="string" required>
|
||||
The unique identifier for the service.
|
||||
</ParamField>
|
||||
<ParamField path="name" type="string" required>
|
||||
The name of the service.
|
||||
</ParamField>
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
If the `actor` field is set to `platform`, `scimClient`, or `unknownUser`, the `actorMetadata` field will be an empty object.
|
||||
</Note>
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="ipAddress" type="string" required>
|
||||
The IP address of the actor.
|
||||
The IP address of the actor.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="eventType" type="string" required>
|
||||
The type of event that occurred. Below you can see a list of possible event types. More event types will be added in the future as we expand our audit logs further.
|
||||
The type of event that occurred. Below you can see a list of possible event types. More event types will be added in the future as we expand our audit logs further.
|
||||
|
||||
`get-secrets`, `delete-secrets`, `get-secret`, `create-secret`, `update-secret`, `delete-secret`, `get-workspace-key`, `authorize-integration`, `update-integration-auth`, `unauthorize-integration`, `create-integration`, `delete-integration`, `add-trusted-ip`, `update-trusted-ip`, `delete-trusted-ip`, `create-service-token`, `delete-service-token`, `create-identity`, `update-identity`, `delete-identity`, `login-identity-universal-auth`, `add-identity-universal-auth`, `update-identity-universal-auth`, `get-identity-universal-auth`, `create-identity-universal-auth-client-secret`, `revoke-identity-universal-auth-client-secret`, `get-identity-universal-auth-client-secret`, `create-environment`, `update-environment`, `delete-environment`, `add-workspace-member`, `remove-workspace-member`, `create-folder`, `update-folder`, `delete-folder`, `create-webhook`, `update-webhook-status`, `delete-webhook`, `webhook-triggered`, `get-secret-imports`, `create-secret-import`, `update-secret-import`, `delete-secret-import`, `update-user-workspace-role`, `update-user-workspace-denied-permissions`, `create-certificate-authority`, `get-certificate-authority`, `update-certificate-authority`, `delete-certificate-authority`, `get-certificate-authority-csr`, `get-certificate-authority-cert`, `sign-intermediate`, `import-certificate-authority-cert`, `get-certificate-authority-crl`, `issue-cert`, `get-cert`, `delete-cert`, `revoke-cert`, `get-cert-body`, `create-pki-alert`, `get-pki-alert`, `update-pki-alert`, `delete-pki-alert`, `create-pki-collection`, `get-pki-collection`, `update-pki-collection`, `delete-pki-collection`, `get-pki-collection-items`, `add-pki-collection-item`, `delete-pki-collection-item`, `org-admin-accessed-project`, `create-certificate-template`, `update-certificate-template`, `delete-certificate-template`, `get-certificate-template`, `create-certificate-template-est-config`, `update-certificate-template-est-config`, `get-certificate-template-est-config`, `update-project-slack-config`, `get-project-slack-config`, `integration-synced`, `create-shared-secret`, `delete-shared-secret`, `read-shared-secret`.
|
||||
`get-secrets`, `delete-secrets`, `get-secret`, `create-secret`, `update-secret`, `delete-secret`, `get-workspace-key`, `authorize-integration`, `update-integration-auth`, `unauthorize-integration`, `create-integration`, `delete-integration`, `add-trusted-ip`, `update-trusted-ip`, `delete-trusted-ip`, `create-service-token`, `delete-service-token`, `create-identity`, `update-identity`, `delete-identity`, `login-identity-universal-auth`, `add-identity-universal-auth`, `update-identity-universal-auth`, `get-identity-universal-auth`, `create-identity-universal-auth-client-secret`, `revoke-identity-universal-auth-client-secret`, `get-identity-universal-auth-client-secret`, `create-environment`, `update-environment`, `delete-environment`, `add-workspace-member`, `remove-workspace-member`, `create-folder`, `update-folder`, `delete-folder`, `create-webhook`, `update-webhook-status`, `delete-webhook`, `webhook-triggered`, `get-secret-imports`, `create-secret-import`, `update-secret-import`, `delete-secret-import`, `update-user-workspace-role`, `update-user-workspace-denied-permissions`, `create-certificate-authority`, `get-certificate-authority`, `update-certificate-authority`, `delete-certificate-authority`, `get-certificate-authority-csr`, `get-certificate-authority-cert`, `sign-intermediate`, `import-certificate-authority-cert`, `get-certificate-authority-crl`, `issue-cert`, `get-cert`, `delete-cert`, `revoke-cert`, `get-cert-body`, `create-pki-alert`, `get-pki-alert`, `update-pki-alert`, `delete-pki-alert`, `create-pki-collection`, `get-pki-collection`, `update-pki-collection`, `delete-pki-collection`, `get-pki-collection-items`, `add-pki-collection-item`, `delete-pki-collection-item`, `org-admin-accessed-project`, `create-certificate-template`, `update-certificate-template`, `delete-certificate-template`, `get-certificate-template`, `create-certificate-template-est-config`, `update-certificate-template-est-config`, `get-certificate-template-est-config`, `update-project-slack-config`, `get-project-slack-config`, `integration-synced`, `create-shared-secret`, `delete-shared-secret`, `read-shared-secret`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="eventMetadata" type="object" required>
|
||||
The metadata associated with the event. This varies based on the event type.
|
||||
The metadata associated with the event. This varies based on the event type.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="userAgent" type="string">
|
||||
The user agent of the actor, if applicable.
|
||||
The user agent of the actor, if applicable.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="userAgentType" type="web | cli | k8-operator | terraform | other | InfisicalPythonSDK | InfisicalNodeSDK">
|
||||
The type of user agent.
|
||||
The type of user agent.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="expiresAt" type="string" required>
|
||||
The expiration date of the log entry. When this date is reached, the log entry will be deleted from Infisical.
|
||||
The expiration date of the log entry. When this date is reached, the log entry will be deleted from Infisical.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="createdAt" type="string" required>
|
||||
The creation date of the log entry.
|
||||
The creation date of the log entry.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="updatedAt" type="string" required>
|
||||
The last update date of the log entry. This is unlikely to be out of sync with the `createdAt` field, as we do not update log entries after they've been created.
|
||||
The last update date of the log entry. This is unlikely to be out of sync with the `createdAt` field, as we do not update log entries after they've been created.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="orgId" type="string" required>
|
||||
The unique identifier for the organization where the event occurred.
|
||||
The unique identifier for the organization where the event occurred.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="projectId" type="string">
|
||||
The unique identifier for the project where the event occurred.
|
||||
The unique identifier for the project where the event occurred.
|
||||
|
||||
The `projectId` field will only be present if the event occurred at the project level, not the organization level.
|
||||
The `projectId` field will only be present if the event occurred at the project level, not the organization level.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="projectName" type="string">
|
||||
The name of the project where the event occurred.
|
||||
The name of the project where the event occurred.
|
||||
|
||||
The `projectName` field will only be present if the event occurred at the project level, not the organization level.
|
||||
The `projectName` field will only be present if the event occurred at the project level, not the organization level.
|
||||
</ParamField>
|
||||
|
||||
@@ -7,8 +7,39 @@ description: "Learn how to authenticate into Infisical with email and password."
|
||||
|
||||
It is currently possible to use the **Email and Password** auth method to authenticate into the Web Dashboard and Infisical CLI.
|
||||
|
||||
### Emergency Kit
|
||||
Every **Email and Password** is accompanied by an emergency kit given to users during signup. If the password is lost or forgotten, emergency kit is only way to retrieve the access to your account. It is possible to generate a new emergency kit with the following steps:
|
||||
1. Open the `Personal Settings` menu.
|
||||
|
||||
2. Scroll down to the `Emergency Kit` section.
|
||||
3. Enter your current password and click `Save`.
|
||||
|
||||
### Change Password
|
||||
You can update your account password at any time:
|
||||
1. Open the `Personal Settings` menu.
|
||||
|
||||
2. Navigate to the `Authentication` tab.
|
||||
|
||||
3. In the `Change Password` section, enter your current password and new password.
|
||||
|
||||
4. Click `Save` to save your new password.
|
||||
|
||||
### Change Email
|
||||
You can update your account email address:
|
||||
1. Open the `Personal Settings` menu.
|
||||
2. Navigate to the `Authentication` tab.
|
||||
3. In the `Change Email` section, enter your new email address.
|
||||
|
||||
4. Click `Send Verification Code` to receive an 6-digit verification code at your new email address.
|
||||
5. Check your new email inbox and enter the verification code.
|
||||
|
||||
6. Click `Confirm Email Change` to complete the process.
|
||||
7. You will be logged out and need to sign in again with your new email address.
|
||||
|
||||
<Tip>
|
||||
Changing your email will remove all connected external authentication methods and terminate all active sessions for security.
|
||||
</Tip>
|
||||
|
||||
<Warning>
|
||||
Email changes are disabled if SCIM is enabled for any of your organizations. Contact your organization administrator if you need to change your email address in a SCIM-enabled environment.
|
||||
</Warning>
|
||||
@@ -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,133 @@ 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 Relays:**
|
||||
|
||||
- **Instance relay SSH Client CA & Server CA** - Gateway ↔ Infisical Relay Server authentication
|
||||
- **Instance relay PKI Client CA & Server CA** - Platform ↔ Infisical Relay Server authentication
|
||||
- **Organization Gateway Client CA & Server CA** - Platform ↔ Gateway authentication
|
||||
|
||||
**For Organizations Using Customer-Deployed Relays:**
|
||||
|
||||
- **Organization relay SSH Client CA & Server CA** - Gateway ↔ Customer Relay Server authentication
|
||||
- **Organization relay PKI Client CA & Server CA** - Platform ↔ Customer Relay 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 Relays):
|
||||
├── Instance Relay SSH CA (Gateway ↔ Relay)
|
||||
├── Instance Relay PKI CA (Platform ↔ Relay)
|
||||
|
||||
Organization Level:
|
||||
├── Organization Relay SSH CA (Gateway ↔ Org Relay)
|
||||
├── Organization Relay PKI CA (Platform ↔ Org Relay)
|
||||
└── 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 relay server authentication
|
||||
3. Establishes SSH reverse tunnel to assigned relay server
|
||||
4. Certificate issuance varies by relay configuration:
|
||||
- **Infisical-managed relay**: Receives Instance relay SSH client certificate + Instance relay SSH Server CA
|
||||
- **Customer-deployed relay**: Receives Organization relay SSH client certificate + Organization relay SSH Server CA
|
||||
|
||||
### 2. Mutual TLS Authentication
|
||||
All communication between gateway and cloud uses mutual TLS (mTLS):
|
||||
### 2. SSH Tunnel Authentication
|
||||
|
||||
Gateway ↔ Relay 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 relay SSH Client CA)
|
||||
- Certificate contains gateway identification and permissions
|
||||
- Relay server validates certificate against appropriate SSH Client CA
|
||||
|
||||
### 3. Relay Communication
|
||||
The relay system provides secure tunneling:
|
||||
- **Relay Server Authentication**:
|
||||
- Presents SSH server certificate (Instance or Organization relay SSH Server CA)
|
||||
- Gateway validates certificate against appropriate SSH Server CA
|
||||
- Ensures gateway connects to legitimate relay 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. Platform-to-Gateway Direct Connection
|
||||
|
||||
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
|
||||
The platform establishes secure direct connections with gateways through a **TLS-pinned tunnel** mechanism:
|
||||
|
||||
1. **TLS-Pinned Tunnel Establishment**:
|
||||
|
||||
- Gateway initiates outbound connection to platform through SSH reverse tunnel
|
||||
- Platform establishes direct mTLS connection with gateway using Organization Gateway certificates
|
||||
- TLS certificate pinning ensures the connection is bound to the specific gateway identity
|
||||
- No inbound connections required - all communication flows through the outbound tunnel
|
||||
|
||||
2. **Connection Flow**:
|
||||
|
||||
```
|
||||
Platform ←→ [SSH Reverse Tunnel] ←→ Gateway
|
||||
```
|
||||
|
||||
- Gateway maintains persistent outbound SSH tunnel to relay server
|
||||
- Platform connects directly to gateway through this tunnel
|
||||
- TLS handshake occurs over the SSH tunnel, establishing mTLS connection
|
||||
- Application traffic flows through the TLS-pinned tunnel
|
||||
|
||||
3. **Security Benefits**:
|
||||
|
||||
- **No inbound connections**: Gateway never needs to accept incoming connections
|
||||
- **Certificate-based authentication**: Uses Organization Gateway certificates for mutual TLS
|
||||
- **Double encryption**: TLS traffic within SSH tunnel provides layered security
|
||||
- **Relay server isolation**: Relay cannot decrypt either TLS or application data
|
||||
- **Tenant isolation**: Each organization's traffic flows through separate authenticated channels
|
||||
|
||||
## 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 relay infrastructure uses instance-level certificates
|
||||
- **Organization-level CAs**: Each organization has unique certificate authorities
|
||||
- **Relay deployment flexibility**: Organizations can choose shared or dedicated relay infrastructure
|
||||
- **Cryptographic separation**: Cross-tenant communication is cryptographically impossible
|
||||
|
||||
### Authentication Flows by Deployment Type
|
||||
|
||||
**Infisical-Managed Relay Deployments:**
|
||||
|
||||
- Gateway authenticates with relay using Instance relay SSH certificates
|
||||
- Platform authenticates with relay using Instance relay PKI certificates
|
||||
- Platform authenticates with gateway using Organization Gateway certificates
|
||||
|
||||
**Customer-Deployed Relay Deployments:**
|
||||
|
||||
- Gateway authenticates with relay using Organization relay SSH certificates
|
||||
- Platform authenticates with relay using Organization relay 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
|
||||
- Relay 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 relay 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 **Relay Servers** using SSH over TCP
|
||||
2. **Infisical platform** establishes mTLS connections with gateways for application traffic
|
||||
3. **Relay Servers** route the doubly-encrypted traffic (mTLS payload within SSH tunnels) between the platform and gateways
|
||||
4. **Double encryption** ensures relay servers cannot access application data - only the platform and gateway can decrypt traffic
|
||||
|
||||
## Required Network Connectivity
|
||||
|
||||
@@ -20,65 +21,70 @@ 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 | Relay Servers | 2222 | SSH reverse tunnel establishment |
|
||||
| TCP | app.infisical.com / eu.infisical.com | 443 | API communication and certificate requests |
|
||||
|
||||
### Relay Server IP Addresses
|
||||
### Relay Server Connectivity
|
||||
|
||||
Your firewall must allow outbound connectivity to the following Infisical relay servers on dynamically allocated ports.
|
||||
**For Instance Relays (Infisical Cloud):** Your firewall must allow outbound connectivity to Infisical-managed relay servers.
|
||||
|
||||
**For Organization Relays:** Your firewall must allow outbound connectivity to your own relay server IP addresses or hostnames.
|
||||
|
||||
**For Self-hosted Instance Relays:** Your firewall must allow outbound connectivity to relay 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 Relays (Infisical Cloud)">
|
||||
Infisical provides multiple managed relay servers with static IP addresses.
|
||||
You can whitelist these IPs ahead of time based on which relay server you
|
||||
choose to connect to. **Firewall requirements:** Allow outbound TCP
|
||||
connections to the desired relay 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 Relays">
|
||||
You control the relay server IP addresses or hostnames when deploying your
|
||||
own organization relays. **Firewall requirements:** Allow outbound TCP
|
||||
connections to your relay server IP or hostname on port 2222. For example,
|
||||
if your relay is at `203.0.113.100` or `relay.example.com`, allow TCP to
|
||||
`203.0.113.100:2222` or `relay.example.com:2222`.
|
||||
</Tab>
|
||||
<Tab title="Infisical dedicated">
|
||||
Please contact your Infisical account manager for dedicated relay server IP addresses.
|
||||
<Tab title="Self-hosted Instance Relays">
|
||||
Contact your instance administrator for the relay server IP addresses or
|
||||
hostnames configured for your deployment. **Firewall requirements:** Allow
|
||||
outbound TCP connections to instance relay 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 relay 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 relay servers (IP addresses or hostnames) 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 +92,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 relay servers (IP addresses or hostnames) 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 relay servers (IP addresses or hostnames) 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 relay 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 relay 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 relay servers (IP addresses or hostnames)
|
||||
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**:
|
||||
The gateway connects to **one relay 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 relay server
|
||||
- **Named relay assignment**: Gateways connect to the specific relay server specified by `--relay`
|
||||
- **Automatic reconnection**: If the relay connection is lost, the gateway automatically reconnects to the same relay
|
||||
- **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:
|
||||
No, relay 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 (via TLS-pinned tunnel)**: Clients connect via a proxy that establishes a TLS-pinned tunnel to the gateway; mTLS between the client and gateway is negotiated inside this tunnel, encrypting all application traffic
|
||||
- **SSH tunnel encryption**: The mTLS-encrypted traffic is then transmitted through SSH reverse tunnels to relay servers
|
||||
- **Double encryption**: Traffic is encrypted twice - once by client mTLS and again by SSH tunnels
|
||||
- **Relay only routes traffic**: The relay server only routes the doubly-encrypted traffic without access to either encryption layer
|
||||
- **No data storage**: Relay 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 relay 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
|
||||
- **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 relay server using SSH certificates issued by Infisical
|
||||
2. **Relay Routing**: The relay server 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 `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. **Relay Server**: Before deploying gateways, you need a running relay server:
|
||||
- **Infisical Cloud**: Instance relays are already available - no setup needed
|
||||
- **Self-hosted**: Instance admin must set up shared instance relays, 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 relay server, allowing secure access to your private resources.
|
||||
|
||||
### Get started
|
||||
|
||||
@@ -46,14 +66,51 @@ 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 Relay Setup">
|
||||
You have two options for relay infrastructure:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Use Instance Relays (Easiest)">
|
||||
**Infisical Cloud:** Instance relays are already running and available - **no setup required**. You can immediately proceed to deploy gateways using these shared relays.
|
||||
|
||||
**Self-hosted:** If your instance admin has set up shared instance relays, you can use them directly. If not, the instance admin can set them up:
|
||||
```bash
|
||||
# Instance admin sets up shared relay (one-time setup)
|
||||
export INFISICAL_RELAY_AUTH_SECRET=<instance-relay-secret>
|
||||
infisical relay start --type=instance --ip=<public-ip> --name=<relay-name>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Deploy Your Own Organization Relay">
|
||||
**Available for all users:** Deploy your own dedicated relay infrastructure for enhanced control:
|
||||
```bash
|
||||
# Deploy organization-specific relay
|
||||
infisical relay start --type=org --ip=<public-ip> --name=<relay-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:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Production (systemd)">
|
||||
For production deployments on Linux, install the Gateway as a systemd service:
|
||||
|
||||
<Warning>
|
||||
**Gateway v2:** The `infisical gateway systemd install` command deploys the new Gateway v2 component.
|
||||
|
||||
If you are migrating from Gateway v1 (legacy `infisical gateway install` command), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
sudo infisical gateway install --token <your-machine-identity-token> --domain <your-infisical-domain>
|
||||
sudo infisical gateway systemd install --token <your-machine-identity-token> --domain <your-infisical-domain> --name <gateway-name> --relay <relay-name>
|
||||
sudo systemctl start infisical-gateway
|
||||
```
|
||||
This will install and start the Gateway as a secure systemd service that:
|
||||
@@ -81,7 +138,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 +173,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_RELAY_NAME=<relay-name> \
|
||||
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
@@ -283,6 +345,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_RELAY_NAME">
|
||||
The name of the relay 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_RELAY_NAME=<relay-name> \
|
||||
--from-literal=INFISICAL_GATEWAY_NAME=<gateway-name>
|
||||
```
|
||||
|
||||
#### Other environment variables
|
||||
|
||||
<AccordionGroup>
|
||||
@@ -291,8 +376,13 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
### Install the Infisical Gateway Helm Chart
|
||||
<Warning>
|
||||
**Version mapping:** Helm chart versions `>= 1.0.0` contain the new Gateway v2 component. Helm chart versions `<= 0.0.5` contain the legacy Gateway v1 component.
|
||||
|
||||
If you are moving from Gateway v1 (chart `<= 0.0.5`) to Gateway v2 (chart `>= 1.0.0`), this is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
helm install infisical-gateway infisical-helm-charts/infisical-gateway
|
||||
```
|
||||
@@ -306,14 +396,18 @@ 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
|
||||
12:43AM INF Starting gateway
|
||||
12:43AM INF Starting gateway certificate renewal goroutine
|
||||
12:43AM INF Successfully registered gateway and received certificates
|
||||
12:43AM INF Connecting to relay server infisical-start on 152.42.218.156:2222...
|
||||
12:43AM INF Relay connection established for gateway
|
||||
12:43AM INF Received incoming connection, starting TLS handshake
|
||||
12:43AM INF TLS handshake completed successfully
|
||||
12:43AM INF Negotiated ALPN protocol: infisical-ping
|
||||
12:43AM INF Starting ping handler
|
||||
12:43AM INF Ping handler completed
|
||||
12:43AM INF Gateway is reachable by Infisical
|
||||
```
|
||||
|
||||
</Tab>
|
||||
@@ -321,27 +415,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 gateway start --token $(infisical login --method=universal-auth --client-id=<> --client-secret=<> --plain) --relay=<relay-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 gateway start --token <your-machine-identity-token> --relay=<relay-name> --name=<gateway-name>
|
||||
```
|
||||
|
||||
Or set it as an environment variable:
|
||||
```bash
|
||||
export INFISICAL_TOKEN=<your-machine-identity-token>
|
||||
infisical gateway
|
||||
infisical gateway start --relay=<relay-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 gateway commands and their 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.
|
||||
**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 relay server (outbound connection only)
|
||||
- Replace `<relay-name>` with the name of your relay server and `<gateway-name>` with a unique name for this gateway
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verify Gateway Deployment">
|
||||
|
||||
@@ -34,24 +34,33 @@ To create and manage LDAP auth templates, see our [Machine Identity Auth Templat
|
||||
To configure LDAP auth for your identity, press the **Add Auth Method** button on the identity's page.
|
||||
|
||||
|
||||
|
||||
|
||||
Now select **LDAP Auth** from the list of available auth methods for the identity.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
After selecting **LDAP Auth**, you'll see the form you need to fill out to configure LDAP auth for your identity. The following fields are available:
|
||||
|
||||
**Configuration Tab**
|
||||
- `URL`: The LDAP server to connect to such as `ldap://ldap.your-org.com`, `ldaps://ldap.myorg.com:636` _(for connection over SSL/TLS)_, etc.
|
||||
- `Bind DN`: The DN to bind to the LDAP server with.
|
||||
- `Bind Pass`: The password to bind to the LDAP server with.
|
||||
- `Search Base / DN`: Base DN under which to perform user search such as `ou=Users,dc=acme,dc=com`.
|
||||
- `User Search Filter`: Template used to construct the LDAP user search filter such as `(uid={{username}})`; use literal `{{username}}` to have the given username used in the search. The default is `(uid={{username}})` which is compatible with several common directory schemas.
|
||||
- `Required Attributes`: A key/value pair of attributes that must be present in the LDAP user entry for them to be authenticated. As an example, if you set key `uid` to value `user1,user2,user3`, then only users with `uid` of `user1`, `user2`, or `user3` will be able to login with this identity. Each value is a comma separated list of attributes.
|
||||
- `CA Certificate`: The CA certificate to use when verifying the LDAP server certificate. This field is optional but recommended.
|
||||
- `Access Token TTL` _(default is 2592000 equivalent to 30 days)_: The lifetime for an access token in seconds. This value will be referenced at renewal time.
|
||||
- `Access Token Max TTL` _(default is 2592000 equivalent to 30 days)_: The maximum lifetime for an access token in seconds. This value will be referenced at renewal time.
|
||||
- `Access Token Max Number of Uses` _(default is 0)_: The maximum number of times that an access token can be used; a value of 0 implies infinite number of uses.
|
||||
|
||||
**Lockout Tab**
|
||||
- `Lockout` _(enabled by default)_: The lockout feature will temporarily block login attempts after X consecutive login failures.
|
||||
- `Lockout Threshold` _(default is 3)_: The amount of times login must fail before locking the identity auth method.
|
||||
- `Lockout Duration` _(default is 5 minutes)_: How long an identity auth method lockout lasts.
|
||||
- `Lockout Counter Reset` _(default is 30 seconds)_: How long to wait from the most recent failed login until resetting the lockout counter.
|
||||
|
||||
**Advanced Tab**
|
||||
- `CA Certificate`: The CA certificate to use when verifying the LDAP server certificate. This field is optional but recommended.
|
||||
- `Access Token Trusted IPs`: The IPs or CIDR ranges that access tokens can be used from. By default, each token is given the 0.0.0.0/0, allowing usage from any network address.
|
||||
|
||||
Once you've filled out the form, press **Add** to save your changes.
|
||||
@@ -91,3 +100,13 @@ To create and manage LDAP auth templates, see our [Machine Identity Auth Templat
|
||||
</Step>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
**FAQ**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="How do I reset a lockout?">
|
||||
You can reset (remove) all lockouts for an identity auth method by clicking into the auth method and pressing **Reset All Lockouts**.
|
||||
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -38,6 +38,16 @@ To interact with various resources in Infisical, Machine Identities can authenti
|
||||
- [GCP Auth](/documentation/platform/identities/gcp-auth): A GCP-native authentication method for GCP resources (e.g. Compute Engine, App Engine, Cloud Run, Google Kubernetes Engine, IAM service accounts, etc.).
|
||||
- [OIDC Auth](/documentation/platform/identities/oidc-auth): A platform-agnostic, JWT-based authentication method for workloads using an OpenID Connect identity provider.
|
||||
|
||||
## Identity Lockout
|
||||
|
||||
Lockout is a feature that prevents brute-force attacks on identity login endpoints. Auth methods that support lockout include: [Universal Auth](/documentation/platform/identities/universal-auth).
|
||||
|
||||
Supported auth methods have lockout enabled by default. If triggered, lockout temporarily disables the login endpoint for 5 minutes after 3 consecutive failed login attempts within a 30-second window. Lockout can be configured and disabled in the identity auth method settings.
|
||||
|
||||
<Warning>
|
||||
When Lockout is enabled, a rate limit of approximately 10 requests per second is enforced on relevant authentication endpoints. This security measure employs a protective lock to mitigate parallel login attacks. If this rate limitation interferes with your operational requirements, you may consider disabling Lockout.
|
||||
</Warning>
|
||||
|
||||
## FAQ
|
||||
|
||||
<AccordionGroup>
|
||||
@@ -51,15 +61,15 @@ You can learn more about how to do this in the CLI quickstart [here](/cli/usage)
|
||||
|
||||
<Accordion title="What is the difference between an identity and service token?">
|
||||
A service token is a project-level authentication method that is being deprecated in favor of identities. The service token method will be removed in the future in accordance with the deprecation notice and timeline stated [here](https://infisical.com/blog/deprecating-api-keys).
|
||||
|
||||
|
||||
Amongst many differences, identities provide broader access over the Infisical API, utilizes the same
|
||||
permission system as user identities, and come with a significantly larger number of configurable authentication and security features.
|
||||
|
||||
|
||||
If you're looking for a simple authentication method, similar to service tokens, that can be bound onto an identity, we recommend checking out [Token Auth](/documentation/platform/identities/token-auth).
|
||||
</Accordion>
|
||||
<Accordion title="Why can I not create, read, update, or delete an identity?">
|
||||
There are a few reasons for why this might happen:
|
||||
|
||||
|
||||
- You have insufficient organization permissions to create, read, update, delete identities.
|
||||
- The identity you are trying to read, update, or delete is more privileged than yourself.
|
||||
- The role you are trying to create an identity for or update an identity to is more privileged than yours.
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "Learn how to authenticate to Infisical from any platform or enviro
|
||||
---
|
||||
|
||||
**Universal Auth** is a platform-agnostic authentication method that can be configured for a [machine identity](/documentation/platform/identities/machine-identities) to authenticate from any platform/environment using a Client ID and Client Secret.
|
||||
This authentication method supports setting token periods, which can help [overcome secret zero](#solving-secret-zero-with-periodic-tokens).
|
||||
This authentication method supports setting token periods, which can help [overcome secret zero](#solving-secret-zero-with-periodic-tokens).
|
||||
|
||||
## Diagram
|
||||
|
||||
@@ -65,17 +65,32 @@ using the Universal Auth authentication method.
|
||||
By default, the identity has been configured with Universal Auth. If you wish, you can edit the Universal Auth configuration
|
||||
details by pressing to edit the **Authentication** section.
|
||||
|
||||
Here's some guidance on each field:
|
||||
|
||||
**Configuration Tab**
|
||||
|
||||
|
||||
|
||||
- Access Token TTL (default is `2592000` equivalent to 30 days): The lifetime for an access token in seconds. This value will be referenced at renewal time.
|
||||
- Access Token Max TTL (default is `2592000` equivalent to 30 days): The maximum lifetime for an access token in seconds. This value will be referenced at renewal time.
|
||||
- Access Token Max Number of Uses (default is `0`): The maximum number of times that an access token can be used; a value of `0` implies infinite number of uses.
|
||||
- Access Token Period (optional, default is `0`): If set, the access token becomes a renewable, non-expiring token for the specified period (in seconds). TTL and Max TTL are ignored when this is set. This is ideal for "secret zero" scenarios, where a workload needs to bootstrap itself securely without hard-coded static secrets.
|
||||
|
||||
**Lockout Tab**
|
||||
|
||||
|
||||
|
||||
Here's some more guidance on each field:
|
||||
- Lockout (enabled by default): The lockout feature will temporarily block login attempts after X consecutive login failures.
|
||||
- Lockout Threshold (default is `3`): The amount of times login must fail before locking the identity auth method.
|
||||
- Lockout Duration (default is `5 minutes`): How long an identity auth method lockout lasts.
|
||||
- Lockout Counter Reset (default is `30 seconds`): How long to wait from the most recent failed login until resetting the lockout counter.
|
||||
|
||||
**Advanced Tab**
|
||||
|
||||
|
||||
|
||||
- Access Token TTL (default is `2592000` equivalent to 30 days): The lifetime for an acccess token in seconds. This value will be referenced at renewal time.
|
||||
- Access Token Max TTL (default is `2592000` equivalent to 30 days): The maximum lifetime for an acccess token in seconds. This value will be referenced at renewal time.
|
||||
- Access Token Max Number of Uses (default is `0`): The maximum number of times that an access token can be used; a value of `0` implies infinite number of uses.
|
||||
- Client Secret Trusted IPs: The IPs or CIDR ranges that the **Client Secret** can be used from together with the **Client ID** to get back an access token. By default, **Client Secrets** are given the `0.0.0.0/0`, allowing usage from any network address.
|
||||
- Access Token Trusted IPs: The IPs or CIDR ranges that access tokens can be used from. By default, each token is given the `0.0.0.0/0`, allowing usage from any network address.
|
||||
- Access Token Period (optional, default is `0`): If set, the access token becomes a renewable, non-expiring token for the specified period (in seconds). TTL and Max TTL are ignored when this is set. This is ideal for "secret zero" scenarios, where a workload needs to bootstrap itself securely without hard-coded static secrets.
|
||||
|
||||
<Warning>
|
||||
Restricting **Client Secret** and access token usage to specific trusted IPs is a paid feature.
|
||||
@@ -202,6 +217,10 @@ This approach allows your workload to securely bootstrap and maintain access to
|
||||
|
||||
A token can be renewed any number of times where each call to renew it can extend the token's lifetime by increments of the access token's TTL.
|
||||
Regardless of how frequently an access token is renewed, its lifespan remains bound to the maximum TTL determined at its creation.
|
||||
</Accordion>
|
||||
<Accordion title="How do I reset a lockout?">
|
||||
You can reset (remove) all lockouts for an identity auth method by clicking into the auth method and pressing **Reset All Lockouts**.
|
||||
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -8,6 +8,7 @@ Every time a secret change is performed, a new version of the same secret is cre
|
||||
Such versions can be accessed visually by opening up the [secret sidebar](/documentation/platform/project#drawer) (as seen below) or [retrieved via API](/api-reference/endpoints/secrets/read)
|
||||
by specifying the `version` query parameter.
|
||||
|
||||
|
||||
|
||||
|
||||
The secret versioning functionality is heavily connected to [Point-in-time Recovery](/documentation/platform/pit-recovery) of secrets in Infisical.
|
||||
|
||||
Reference in New Issue
Block a user