mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Merge remote-tracking branch 'origin/main' into feat/dynamicSecretIdentityName
This commit is contained in:
carlosmonastyrski
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Machine identities"
|
||||
title: "Machine identities"
|
||||
description: "Learn how to set metadata and leverage authentication attributes for machine identities."
|
||||
---
|
||||
|
||||
@@ -25,7 +25,7 @@ Machine identities can have metadata set manually, just like users. In addition,
|
||||
|
||||
#### Accessing Attributes From Machine Identity Login
|
||||
|
||||
When machine identities authenticate, they may receive additional payloads/attributes from the service provider.
|
||||
When machine identities authenticate, they may receive additional payloads/attributes from the service provider.
|
||||
For methods like OIDC, these come as claims in the token and can be made available in your policies.
|
||||
|
||||
<Tabs>
|
||||
@@ -50,17 +50,29 @@ For methods like OIDC, these come as claims in the token and can be made availab
|
||||
```
|
||||
|
||||
You might map:
|
||||
|
||||
- **department:** to `user.department`
|
||||
|
||||
- **department:** to `user.department`
|
||||
- **role:** to `user.role`
|
||||
|
||||
Once configured, these attributes become available in your policies using the following format:
|
||||
|
||||
|
||||
```
|
||||
{{ identity.auth.oidc.claims.<permission claim name> }}
|
||||
```
|
||||
|
||||
<img src="/images/platform/access-controls/abac-policy-oidc-format.png" />
|
||||
|
||||
</Tab>
|
||||
<Tab title="Kubernetes Login Attributes">
|
||||
For identities authenticated using Kubernetes, the service account's namespace and name are available in their policy and can be accessed as follows:
|
||||
|
||||
```
|
||||
{{ identity.auth.kubernetes.namespace }}
|
||||
{{ identity.auth.kubernetes.name }}
|
||||
```
|
||||
|
||||
<img src="/images/platform/access-controls/abac-policy-k8s-format.png" />
|
||||
|
||||
</Tab>
|
||||
<Tab title="Other Authentication Method Attributes">
|
||||
At the moment we only support OIDC claims. Payloads on other authentication methods are not yet accessible.
|
||||
|
||||
@@ -50,126 +50,304 @@ Replace **\<account id\>** with your AWS account id and **\<aws-scope-path\>** w
|
||||
|
||||
## Set up Dynamic Secrets with AWS IAM
|
||||
|
||||
<Steps>
|
||||
<Step title="Secret Overview Dashboard">
|
||||
Navigate to the Secret Overview dashboard and select the environment in which you would like to add a dynamic secret to.
|
||||
</Step>
|
||||
<Step title="Click on the 'Add Dynamic Secret' button">
|
||||
|
||||
</Step>
|
||||
<Step title="Select AWS IAM">
|
||||
|
||||
</Step>
|
||||
<Step title="Provide the inputs for dynamic secret parameters">
|
||||
<ParamField path="Secret Name" type="string" required>
|
||||
Name by which you want the secret to be referenced
|
||||
</ParamField>
|
||||
<Tabs>
|
||||
<Tab title="Assume Role (Recommended)">
|
||||
Infisical will assume the provided role in your AWS account securely, without the need to share any credentials.
|
||||
<Accordion title="Self-Hosted Instance">
|
||||
To connect your self-hosted Infisical instance with AWS, you need to set up an AWS IAM User account that can assume the configured AWS IAM Role.
|
||||
|
||||
<ParamField path="Default TTL" type="string" required>
|
||||
Default time-to-live for a generated secret (it is possible to modify this value after a secret is generated)
|
||||
</ParamField>
|
||||
If your instance is deployed on AWS, the aws-sdk will automatically retrieve the credentials. Ensure that you assign the provided permission policy to your deployed instance, such as ECS or EC2.
|
||||
|
||||
<ParamField path="Max TTL" type="string" required>
|
||||
Maximum time-to-live for a generated secret
|
||||
</ParamField>
|
||||
The following steps are for instances not deployed on AWS:
|
||||
<Steps>
|
||||
<Step title="Create an IAM User">
|
||||
Navigate to [Create IAM User](https://console.aws.amazon.com/iamv2/home#/users/create) in your AWS Console.
|
||||
</Step>
|
||||
<Step title="Create an Inline Policy">
|
||||
Attach the following inline permission policy to the IAM User to allow it to assume any IAM Roles:
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "AllowAssumeAnyRole",
|
||||
"Effect": "Allow",
|
||||
"Action": "sts:AssumeRole",
|
||||
"Resource": "arn:aws:iam::*:role/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Obtain the IAM User Credentials">
|
||||
Obtain the AWS access key ID and secret access key for your IAM User by navigating to **IAM > Users > [Your User] > Security credentials > Access keys**.
|
||||
|
||||
<ParamField path="AWS Access Key" type="string" required>
|
||||
The managing AWS IAM User Access Key
|
||||
</ParamField>
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Set Up Connection Keys">
|
||||
1. Set the access key as **DYNAMIC_SECRET_AWS_ACCESS_KEY_ID**.
|
||||
2. Set the secret key as **DYNAMIC_SECRET_AWS_SECRET_ACCESS_KEY**.
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
|
||||
<ParamField path="AWS Secret Key" type="string" required>
|
||||
The managing AWS IAM User Secret Key
|
||||
</ParamField>
|
||||
<Steps>
|
||||
<Step title="Create the Managing User IAM Role for Infisical">
|
||||
1. Navigate to the [Create IAM Role](https://console.aws.amazon.com/iamv2/home#/roles/create?step=selectEntities) page in your AWS Console.
|
||||
|
||||
|
||||
<ParamField path="AWS IAM Path" type="string">
|
||||
[IAM AWS Path](https://aws.amazon.com/blogs/security/optimize-aws-administration-with-iam-paths/) to scope created IAM User resource access.
|
||||
</ParamField>
|
||||
2. Select **AWS Account** as the **Trusted Entity Type**.
|
||||
3. Select **Another AWS Account** and provide the appropriate Infisical AWS Account ID: use **381492033652** for the **US region**, and **345594589636** for the **EU region**. This restricts the role to be assumed only by Infisical. If self-hosting, provide your AWS account number instead.
|
||||
4. (Recommended) <strong>Enable "Require external ID"</strong> and input your **Project ID** to strengthen security and mitigate the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).
|
||||
5. Assign permission as shared in prerequisite.
|
||||
|
||||
<ParamField path="AWS Region" type="string" required>
|
||||
The AWS data center region.
|
||||
</ParamField>
|
||||
<Warning type="warning" title="Security Best Practice: Use External ID to Prevent Confused Deputy Attacks">
|
||||
When configuring an IAM Role that Infisical will assume, it’s highly recommended to enable the **"Require external ID"** option and specify your **Project ID**.
|
||||
|
||||
<ParamField path="IAM User Permission Boundary" type="string" required>
|
||||
The IAM Policy ARN of the [AWS Permissions Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to attach to IAM users created in the role.
|
||||
</ParamField>
|
||||
This precaution helps protect your AWS account against the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html), a potential security vulnerability where Infisical could be tricked into performing actions on your behalf by an unauthorized actor.
|
||||
|
||||
<ParamField path="AWS IAM Groups" type="string">
|
||||
The AWS IAM groups that should be assigned to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
<strong>Always enable "Require external ID" and use your Project ID when setting up the IAM Role.</strong>
|
||||
</Warning>
|
||||
</Step>
|
||||
<Step title="Copy the AWS IAM Role ARN">
|
||||
|
||||
</Step>
|
||||
<Step title="Secret Overview Dashboard">
|
||||
Navigate to the Secret Overview dashboard and select the environment in which you would like to add a dynamic secret to.
|
||||
</Step>
|
||||
<Step title="Click on the 'Add Dynamic Secret' button">
|
||||
|
||||
</Step>
|
||||
<Step title="Select AWS IAM">
|
||||
|
||||
</Step>
|
||||
<Step title="Provide the inputs for dynamic secret parameters">
|
||||
|
||||
<ParamField path="Secret Name" type="string" required>
|
||||
Name by which you want the secret to be referenced
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS Policy ARNs" type="string">
|
||||
The AWS IAM managed policies that should be attached to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
<ParamField path="Default TTL" type="string" required>
|
||||
Default time-to-live for a generated secret (it is possible to modify this value after a secret is generated)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS IAM Policy Document" type="string">
|
||||
The AWS IAM inline policy that should be attached to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
<ParamField path="Max TTL" type="string" required>
|
||||
Maximum time-to-live for a generated secret
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Username Template" type="string" default="{{randomUsername}}">
|
||||
Specifies a template for generating usernames. This field allows customization of how usernames are automatically created.
|
||||
<ParamField path="Username Template" type="string" default="{{randomUsername}}">
|
||||
Specifies a template for generating usernames. This field allows customization of how usernames are automatically created.
|
||||
|
||||
Allowed template variables are
|
||||
- `{{randomUsername}}`: Random username string
|
||||
- `{{unixTimestamp}}`: Current Unix timestamp
|
||||
- `{{identity.name}}`: Name of the identity that is generating the secret
|
||||
- `{{random N}}`: Random string of N characters
|
||||
Allowed template variables are
|
||||
- `{{randomUsername}}`: Random username string
|
||||
- `{{unixTimestamp}}`: Current Unix timestamp
|
||||
- `{{identity.name}}`: Name of the identity that is generating the secret
|
||||
- `{{random N}}`: Random string of N characters
|
||||
|
||||
Allowed template functions are
|
||||
- `truncate`: Truncates a string to a specified length
|
||||
- `replace`: Replaces a substring with another value
|
||||
Allowed template functions are
|
||||
- `truncate`: Truncates a string to a specified length
|
||||
- `replace`: Replaces a substring with another value
|
||||
|
||||
Examples:
|
||||
```
|
||||
{{randomUsername}} // 3POnzeFyK9gW2nioK0q2gMjr6CZqsRiX
|
||||
{{unixTimestamp}} // 17490641580
|
||||
{{identity.name}} // testuser
|
||||
{{random-5}} // x9k2m
|
||||
{{truncate identity.name 4}} // test
|
||||
{{replace identity.name 'user' 'replace'}} // testreplace
|
||||
```
|
||||
</ParamField>
|
||||
Examples:
|
||||
```
|
||||
{{randomUsername}} // 3POnzeFyK9gW2nioK0q2gMjr6CZqsRiX
|
||||
{{unixTimestamp}} // 17490641580
|
||||
{{identity.name}} // testuser
|
||||
{{random-5}} // x9k2m
|
||||
{{truncate identity.name 4}} // test
|
||||
{{replace identity.name 'user' 'replace'}} // testreplace
|
||||
```
|
||||
</ParamField>
|
||||
<ParamField path="Method" type="string" required>
|
||||
Select *Assume Role* method.
|
||||
</ParamField>
|
||||
|
||||
|
||||
<ParamField path="Aws Role ARN" type="string" required>
|
||||
The ARN of the AWS Role to assume.
|
||||
</ParamField>
|
||||
|
||||
</Step>
|
||||
<Step title="Click 'Submit'">
|
||||
After submitting the form, you will see a dynamic secret created in the dashboard.
|
||||
<ParamField path="AWS IAM Path" type="string">
|
||||
[IAM AWS Path](https://aws.amazon.com/blogs/security/optimize-aws-administration-with-iam-paths/) to scope created IAM User resource access.
|
||||
</ParamField>
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Generate dynamic secrets">
|
||||
Once you've successfully configured the dynamic secret, you're ready to generate on-demand credentials.
|
||||
To do this, simply click on the 'Generate' button which appears when hovering over the dynamic secret item.
|
||||
Alternatively, you can initiate the creation of a new lease by selecting 'New Lease' from the dynamic secret lease list section.
|
||||
<ParamField path="AWS Region" type="string" required>
|
||||
The AWS data center region.
|
||||
</ParamField>
|
||||
|
||||
|
||||
|
||||
<ParamField path="IAM User Permission Boundary" type="string" required>
|
||||
The IAM Policy ARN of the [AWS Permissions Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to attach to IAM users created in the role.
|
||||
</ParamField>
|
||||
|
||||
When generating these secrets, it's important to specify a Time-to-Live (TTL) duration. This will dictate how long the credentials are valid for.
|
||||
<ParamField path="AWS IAM Groups" type="string">
|
||||
The AWS IAM groups that should be assigned to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
|
||||
<ParamField path="AWS Policy ARNs" type="string">
|
||||
The AWS IAM managed policies that should be attached to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
<Tip>
|
||||
Ensure that the TTL for the lease fall within the maximum TTL defined when configuring the dynamic secret in step 4.
|
||||
</Tip>
|
||||
<ParamField path="AWS IAM Policy Document" type="string">
|
||||
The AWS IAM inline policy that should be attached to the created users.
|
||||
Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Username Template" type="string" default="{{randomUsername}}">
|
||||
Specifies a template for generating usernames. This field allows customization of how usernames are automatically created.
|
||||
|
||||
Once you click the `Submit` button, a new secret lease will be generated and the credentials for it will be shown to you.
|
||||
Allowed template variables are
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
- `{{randomUsername}}`: Random username string
|
||||
- `{{unixTimestamp}}`: Current Unix timestamp
|
||||
</ParamField>
|
||||
</Step>
|
||||
|
||||
<Step title="Click 'Submit'">
|
||||
After submitting the form, you will see a dynamic secret created in the dashboard.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Generate dynamic secrets">
|
||||
Once you've successfully configured the dynamic secret, you're ready to generate on-demand credentials.
|
||||
To do this, simply click on the 'Generate' button which appears when hovering over the dynamic secret item.
|
||||
Alternatively, you can initiate the creation of a new lease by selecting 'New Lease' from the dynamic secret lease list section.
|
||||
|
||||
|
||||
|
||||
|
||||
When generating these secrets, it's important to specify a Time-to-Live (TTL) duration. This will dictate how long the credentials are valid for.
|
||||
|
||||
|
||||
|
||||
<Tip>
|
||||
Ensure that the TTL for the lease falls within the maximum TTL defined when configuring the dynamic secret in step 4.
|
||||
</Tip>
|
||||
|
||||
Once you click the `Submit` button, a new secret lease will be generated and the credentials for it will be shown to you.
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Access Key">
|
||||
Infisical will use the provided **Access Key ID** and **Secret Key** to connect to your AWS instance.
|
||||
<Steps>
|
||||
<Step title="Secret Overview Dashboard">
|
||||
Navigate to the Secret Overview dashboard and select the environment in which you would like to add a dynamic secret to.
|
||||
</Step>
|
||||
<Step title="Click on the 'Add Dynamic Secret' button">
|
||||
|
||||
</Step>
|
||||
<Step title="Select AWS IAM">
|
||||
|
||||
</Step>
|
||||
<Step title="Provide the inputs for dynamic secret parameters">
|
||||
|
||||
<ParamField path="Secret Name" type="string" required>
|
||||
Name by which you want the secret to be referenced
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Default TTL" type="string" required>
|
||||
Default time-to-live for a generated secret (it is possible to modify this value after a secret is generated)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Max TTL" type="string" required>
|
||||
Maximum time-to-live for a generated secret
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Method" type="string" required>
|
||||
Select *Access Key* method.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS Access Key" type="string" required>
|
||||
The managing AWS IAM User Access Key
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS Secret Key" type="string" required>
|
||||
The managing AWS IAM User Secret Key
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS IAM Path" type="string">
|
||||
[IAM AWS Path](https://aws.amazon.com/blogs/security/optimize-aws-administration-with-iam-paths/) to scope created IAM User resource access.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS Region" type="string" required>
|
||||
The AWS data center region.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="IAM User Permission Boundary" type="string" required>
|
||||
The IAM Policy ARN of the [AWS Permissions Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to attach to IAM users created in the role.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS IAM Groups" type="string">
|
||||
The AWS IAM groups that should be assigned to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS Policy ARNs" type="string">
|
||||
The AWS IAM managed policies that should be attached to the created users. Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="AWS IAM Policy Document" type="string">
|
||||
The AWS IAM inline policy that should be attached to the created users.
|
||||
Multiple values can be provided by separating them with commas
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Username Template" type="string" default="{{randomUsername}}">
|
||||
Specifies a template for generating usernames. This field allows customization of how usernames are automatically created.
|
||||
|
||||
Allowed template variables are
|
||||
|
||||
- `{{randomUsername}}`: Random username string
|
||||
- `{{unixTimestamp}}`: Current Unix timestamp
|
||||
</ParamField>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Click 'Submit'">
|
||||
After submitting the form, you will see a dynamic secret created in the dashboard.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Generate dynamic secrets">
|
||||
Once you've successfully configured the dynamic secret, you're ready to generate on-demand credentials.
|
||||
To do this, simply click on the 'Generate' button which appears when hovering over the dynamic secret item.
|
||||
Alternatively, you can initiate the creation of a new lease by selecting 'New Lease' from the dynamic secret lease list section.
|
||||
|
||||
|
||||
|
||||
|
||||
When generating these secrets, it's important to specify a Time-to-Live (TTL) duration. This will dictate how long the credentials are valid for.
|
||||
|
||||
|
||||
|
||||
<Tip>
|
||||
Ensure that the TTL for the lease falls within the maximum TTL defined when configuring the dynamic secret in step 4.
|
||||
</Tip>
|
||||
|
||||
Once you click the `Submit` button, a new secret lease will be generated and the credentials for it will be shown to you.
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Audit or Revoke Leases
|
||||
|
||||
Once you have created one or more leases, you will be able to access them by clicking on the respective dynamic secret item on the dashboard.
|
||||
This will allow you to see the lease details and delete the lease ahead of its expiration time.
|
||||
|
||||
|
||||
|
||||
## Renew Leases
|
||||
|
||||
To extend the life of the generated dynamic secret lease past its initial time to live, simply click on the **Renew** button as illustrated below.
|
||||
|
||||
|
||||
<Warning>
|
||||
Lease renewals cannot exceed the maximum TTL set when configuring the dynamic secret
|
||||
Lease renewals cannot exceed the maximum TTL set when configuring the dynamic
|
||||
secret
|
||||
</Warning>
|
||||
|
||||
134
docs/documentation/platform/dynamic-secrets/vertica.mdx
Normal file
134
docs/documentation/platform/dynamic-secrets/vertica.mdx
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: "Vertica"
|
||||
description: "Learn how to dynamically generate Vertica database users."
|
||||
---
|
||||
|
||||
The Infisical Vertica dynamic secret allows you to generate Vertica database credentials on demand based on configured role.
|
||||
|
||||
## Prerequisite
|
||||
|
||||
Create a user with the required permission in your Vertica instance. This user will be used to create new accounts on-demand.
|
||||
|
||||
## Set up Dynamic Secrets with Vertica
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Secret Overview Dashboard">
|
||||
Open the Secret Overview dashboard and select the environment in which you would like to add a dynamic secret.
|
||||
</Step>
|
||||
<Step title="Click on the 'Add Dynamic Secret' button">
|
||||
|
||||
</Step>
|
||||
<Step title="Select `Vertica`">
|
||||
|
||||
</Step>
|
||||
<Step title="Provide the inputs for dynamic secret parameters">
|
||||
<ParamField path="Secret Name" type="string" required>
|
||||
Name by which you want the secret to be referenced
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Default TTL" type="string" required>
|
||||
Default time-to-live for a generated secret (it is possible to modify this value after a secret is generated)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Max TTL" type="string" required>
|
||||
Maximum time-to-live for a generated secret
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Gateway" type="string">
|
||||
Select a gateway for private cluster access. If not specified, the Internet Gateway will be used.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Host" type="string" required>
|
||||
Vertica database host
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Port" type="number" required>
|
||||
Vertica database port (default: 5433)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Database" type="string" required>
|
||||
Name of the Vertica database for which you want to create dynamic secrets
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="User" type="string" required>
|
||||
Username that will be used to create dynamic secrets
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Password" type="string" required>
|
||||
Password that will be used to create dynamic secrets
|
||||
</ParamField>
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="(Optional) Modify SQL Statements">
|
||||
|
||||
<ParamField path="Username Template" type="string" default="{{randomUsername}}">
|
||||
Specifies a template for generating usernames. This field allows customization of how usernames are automatically created.
|
||||
|
||||
Allowed template variables are
|
||||
- `{{randomUsername}}`: Random username string
|
||||
- `{{unixTimestamp}}`: Current Unix timestamp
|
||||
</ParamField>
|
||||
<ParamField path="Creation Statement" type="string">
|
||||
Customize the SQL statement used to create new users. Default creates a user with basic schema permissions.
|
||||
</ParamField>
|
||||
<ParamField path="Revocation Statement" type="string">
|
||||
Customize the SQL statement used to revoke users. Default revokes a user.
|
||||
</ParamField>
|
||||
</Step>
|
||||
<Step title="(Optional) Configure Password Requirements">
|
||||
<ParamField path="Password Length" type="number" default="48">
|
||||
Length of generated passwords (1-250 characters)
|
||||
</ParamField>
|
||||
<ParamField path="Character Requirements" type="object">
|
||||
Minimum required character counts:
|
||||
- **Lowercase Count**: Minimum lowercase letters (default: 1)
|
||||
- **Uppercase Count**: Minimum uppercase letters (default: 1)
|
||||
- **Digit Count**: Minimum digits (default: 1)
|
||||
- **Symbol Count**: Minimum symbols (default: 0)
|
||||
</ParamField>
|
||||
<ParamField path="Allowed Symbols" type="string" default="-_.~!*">
|
||||
Symbols allowed in generated passwords
|
||||
</ParamField>
|
||||
</Step>
|
||||
<Step title="Click 'Submit'">
|
||||
After submitting the form, you will see a dynamic secret created in the dashboard.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Generate dynamic secrets">
|
||||
Once you've successfully configured the dynamic secret, you're ready to generate on-demand credentials.
|
||||
To do this, simply click on the 'Generate' button which appears when hovering over the dynamic secret item.
|
||||
Alternatively, you can initiate the creation of a new lease by selecting 'New Lease' from the dynamic secret lease list section.
|
||||
|
||||
|
||||
|
||||
|
||||
When generating these secrets, it's important to specify a Time-to-Live (TTL) duration. This will dictate how long the credentials are valid for.
|
||||
|
||||
|
||||
|
||||
<Tip>
|
||||
Ensure that the TTL for the lease falls within the maximum TTL defined when configuring the dynamic secret.
|
||||
</Tip>
|
||||
|
||||
Once you click the `Submit` button, a new secret lease will be generated and the credentials for it will be shown to you.
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Audit or Revoke Leases
|
||||
Once you have created one or more leases, you will be able to access them by clicking on the respective dynamic secret item on the dashboard.
|
||||
This will allow you to see the expiration time of the lease or delete the lease before its set time to live.
|
||||
|
||||
|
||||
|
||||
## Renew Leases
|
||||
To extend the life of the generated dynamic secret leases past its initial time to live, simply click on the **Renew** button as illustrated below.
|
||||
|
||||
|
||||
<Warning>
|
||||
Lease renewals cannot exceed the maximum TTL set when configuring the dynamic secret
|
||||
</Warning>
|
||||
@@ -89,22 +89,3 @@ The relay system provides secure tunneling:
|
||||
- Gateways only accept connections to approved resources
|
||||
- Each connection requires explicit project authorization
|
||||
- Resources remain private to their assigned organization
|
||||
|
||||
## Security Measures
|
||||
|
||||
### Certificate Lifecycle
|
||||
- Certificates have limited validity periods
|
||||
- Automatic certificate rotation
|
||||
- Immediate certificate revocation capabilities
|
||||
|
||||
### Monitoring and Verification
|
||||
1. **Continuous Verification**:
|
||||
- Regular heartbeat checks
|
||||
- Certificate chain validation
|
||||
- Connection state monitoring
|
||||
|
||||
2. **Security Controls**:
|
||||
- Automatic connection termination on verification failure
|
||||
- Audit logging of all access attempts
|
||||
- Machine identity based authentication
|
||||
|
||||
|
||||
168
docs/documentation/platform/gateways/networking.mdx
Normal file
168
docs/documentation/platform/gateways/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>
|
||||
@@ -32,7 +32,7 @@ For detailed installation instructions, refer to the Infisical [CLI Installation
|
||||
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.
|
||||
|
||||
### Deployment process
|
||||
### Get started
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Gateway Identity">
|
||||
@@ -128,7 +128,7 @@ Once authenticated, the Gateway establishes a secure connection with Infisical t
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Development (direct)">
|
||||
<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)
|
||||
|
||||
@@ -52,10 +52,11 @@ Infisical is able to authenticate and interact with the TokenReview API by using
|
||||
|
||||
In the following steps, we explore how to create and use identities for your applications in Kubernetes to access the Infisical API using the Kubernetes Auth authentication method.
|
||||
|
||||
|
||||
|
||||
<Steps>
|
||||
<Step title="Obtaining the token reviewer JWT for Infisical">
|
||||
<Tabs>
|
||||
<Tab title="Option 1: Reviewer JWT Token">
|
||||
<Accordion title="Option 1: Reviewer JWT Token">
|
||||
|
||||
<Note>
|
||||
**When to use this option**: Choose this approach when you want centralized authentication management. Only one service account needs special permissions, and your application service accounts remain unchanged.
|
||||
@@ -126,41 +127,91 @@ In the following steps, we explore how to create and use identities for your app
|
||||
```
|
||||
|
||||
Keep this JWT token handy as you will need it for the **Token Reviewer JWT** field when configuring the Kubernetes Auth authentication method for the identity in step 2.
|
||||
</Accordion>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Option 2: Client JWT as Reviewer JWT Token">
|
||||
<Accordion title="Option 2: Client JWT as Reviewer JWT Token">
|
||||
<Note>
|
||||
**When to use this option**: Choose this approach to eliminate long-lived tokens. This option simplifies Infisical configuration but requires each application service account to have elevated permissions.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**When to use this option**: Choose this approach to eliminate long-lived tokens. This option simplifies Infisical configuration but requires each application service account to have elevated permissions.
|
||||
</Note>
|
||||
The self-validation method eliminates the need for a separate long-lived reviewer JWT by using the same token for both authentication and validation. Instead of creating a dedicated reviewer service account, you'll grant the necessary permissions to each application service account.
|
||||
|
||||
The self-validation method eliminates the need for a separate long-lived reviewer JWT by using the same token for both authentication and validation. Instead of creating a dedicated reviewer service account, you'll grant the necessary permissions to each application service account.
|
||||
For each service account that needs to authenticate with Infisical, add the `system:auth-delegator` role:
|
||||
|
||||
For each service account that needs to authenticate with Infisical, add the `system:auth-delegator` role:
|
||||
```yaml client-role-binding.yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: infisical-client-binding-[your-app-name]
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: system:auth-delegator
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: [your-app-service-account]
|
||||
namespace: [your-app-namespace]
|
||||
```
|
||||
|
||||
```yaml client-role-binding.yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: infisical-client-binding-[your-app-name]
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: system:auth-delegator
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: [your-app-service-account]
|
||||
namespace: [your-app-namespace]
|
||||
```
|
||||
```
|
||||
kubectl apply -f client-role-binding.yaml
|
||||
```
|
||||
|
||||
```
|
||||
kubectl apply -f client-role-binding.yaml
|
||||
```
|
||||
When configuring Kubernetes Auth in Infisical, leave the **Token Reviewer JWT** field empty. Infisical will use the client's own token for validation.
|
||||
</Accordion>
|
||||
<Accordion title="Option 3: Use Gateway as Reviewer">
|
||||
<Note>
|
||||
**When to use this option**: Choose this approach when you have a gateway deployed in your Kubernetes Cluster and wish to eliminate long-lived tokens. This approach simplifies Infisical Kubernetes Auth configuration, and only one service account will need to have the elevated `system:auth-delegator` ClusterRole binding.
|
||||
</Note>
|
||||
|
||||
When configuring Kubernetes Auth in Infisical, leave the **Token Reviewer JWT** field empty. Infisical will use the client's own token for validation.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Step>
|
||||
<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.
|
||||
</Info>
|
||||
|
||||
<Steps>
|
||||
<Step title="Deploying a gateway">
|
||||
To deploy a gateway in your Kubernetes cluster, follow our [Gateway deployment guide using helm](/documentation/platform/gateways/overview).
|
||||
</Step>
|
||||
|
||||
<Step title="Grant the gateway the system:auth-delegator ClusterRole binding">
|
||||
To grant the gateway the `system:auth-delegator` ClusterRole binding, you can use the following command:
|
||||
|
||||
```yaml gateway-role-binding.yaml
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: infisical-token-reviewer-role-binding
|
||||
namespace: default # Replace with your namespace if not default
|
||||
roleRef:
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
kind: ClusterRole
|
||||
name: system:auth-delegator
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: infisical-gateway # The name of the gateway service account
|
||||
namespace: default # Replace with your namespace if not default
|
||||
```
|
||||
|
||||
```bash
|
||||
kubectl apply -f gateway-role-binding.yaml
|
||||
```
|
||||
|
||||
<Tip>
|
||||
The gateway service account name is `infisical-gateway` by default if deployed using Helm.
|
||||
</Tip>
|
||||
</Step>
|
||||
|
||||
<Step title="Configure the Kubernetes Auth authentication method for the identity">
|
||||
To configure your Kubernetes Auth method to use the gateway as the token reviewer, set the `Review Method` to "Gateway as Reviewer", and select the gateway you want to use as the token reviewer.
|
||||
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Accordion>
|
||||
</Step>
|
||||
|
||||
<Step title="Creating an identity">
|
||||
To create an identity, head to your Organization Settings > Access Control > Identities and press **Create identity**.
|
||||
|
||||
157
docs/documentation/platform/identities/oidc-auth/azure.mdx
Normal file
157
docs/documentation/platform/identities/oidc-auth/azure.mdx
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Azure
|
||||
description: "Learn how to authenticate Azure pipelines with Infisical using OpenID Connect (OIDC)."
|
||||
---
|
||||
|
||||
**OIDC Auth** is a platform-agnostic JWT-based authentication method that can be used to authenticate from any platform or environment using an identity provider with OpenID Connect.
|
||||
|
||||
## Diagram
|
||||
|
||||
The following sequence diagram illustrates the OIDC Auth workflow for authenticating Azure pipelines with Infisical.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as Azure Pipeline
|
||||
participant Idp as Identity Provider
|
||||
participant Infis as Infisical
|
||||
|
||||
Client->>Idp: Step 1: Request identity token
|
||||
Idp-->>Client: Return JWT with verifiable claims
|
||||
|
||||
Note over Client,Infis: Step 2: Login Operation
|
||||
Client->>Infis: Send signed JWT to /api/v1/auth/oidc-auth/login
|
||||
|
||||
Note over Infis,Idp: Step 3: Query verification
|
||||
Infis->>Idp: Request JWT public key using OIDC Discovery
|
||||
Idp-->>Infis: Return public key
|
||||
|
||||
Note over Infis: Step 4: JWT validation
|
||||
Infis->>Client: Return short-lived access token
|
||||
|
||||
Note over Client,Infis: Step 5: Access Infisical API with Token
|
||||
Client->>Infis: Make authenticated requests using the short-lived access token
|
||||
```
|
||||
|
||||
## Concept
|
||||
|
||||
At a high-level, Infisical authenticates a client by verifying the JWT and checking that it meets specific requirements (e.g. it is issued by a trusted identity provider) at the `/api/v1/auth/oidc-auth/login` endpoint. If successful,
|
||||
then Infisical returns a short-lived access token that can be used to make authenticated requests to the Infisical API.
|
||||
|
||||
To be more specific:
|
||||
|
||||
1. The Azure pipeline requests an identity token from Azure's identity provider.
|
||||
2. The fetched identity token is sent to Infisical at the `/api/v1/auth/oidc-auth/login` endpoint.
|
||||
3. Infisical fetches the public key that was used to sign the identity token from Azure's identity provider using OIDC Discovery.
|
||||
4. Infisical validates the JWT using the public key provided by the identity provider and checks that the subject, audience, and claims of the token matches with the set criteria.
|
||||
5. If all is well, Infisical returns a short-lived access token that the Azure pipeline can use to make authenticated requests to the Infisical API.
|
||||
|
||||
<Note>
|
||||
Infisical needs network-level access to Azure's identity provider endpoints.
|
||||
</Note>
|
||||
|
||||
## Guide
|
||||
|
||||
In the following steps, we explore how to create and use identities to access the Infisical API using the OIDC Auth authentication method.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating an identity">
|
||||
To create an identity, head to your Organization Settings > Access Control > Identities and press **Create identity**.
|
||||
|
||||
|
||||
|
||||
When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
|
||||
|
||||
|
||||
|
||||
Now input a few details for your new identity. Here's some guidance for each field:
|
||||
|
||||
- Name (required): A friendly name for the identity.
|
||||
- Role (required): A role from the **Organization Roles** tab for the identity to assume. The organization role assigned will determine what organization level resources this identity can have access to.
|
||||
|
||||
Once you've created an identity, you'll be redirected to a page where you can manage the identity.
|
||||
|
||||
|
||||
|
||||
Since the identity has been configured with Universal Auth by default, you should re-configure it to use OIDC Auth instead. To do this, press to edit the **Authentication** section,
|
||||
remove the existing Universal Auth configuration, and add a new OIDC Auth configuration onto the identity.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<Warning>Restrict access by configuring the Subject, Audiences, and Claims fields</Warning>
|
||||
|
||||
Here's some more guidance on each field:
|
||||
- <div style={{ textAlign: 'justify' }}>**OIDC Discovery URL**: The URL used to retrieve the OpenID Connect configuration from the identity provider. This is used to fetch the public keys needed to verify the JWT. For Azure, set this to `https://login.microsoftonline.com/{tenant-id}/v2.0` (replace `{tenant-id}` with your Azure AD tenant ID).</div>
|
||||
- <div style={{ textAlign: 'justify' }}>**Issuer**: The value of the `iss` claim that the token must match. For Azure, this should be `https://login.microsoftonline.com/{tenant-id}/v2.0`.</div>
|
||||
- **Subject**: This must match the `sub` claim in the JWT.
|
||||
- **Audiences**: Values that must match the `aud` claim.
|
||||
- **Claims**: Additional claims that must be present. Refer to [Azure DevOps docs](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#workload-identity-federation) for available claims.
|
||||
- **Access Token TTL**: Lifetime of the issued token (in seconds), e.g., `2592000` (30 days)
|
||||
- **Access Token Max TTL**: Maximum allowed lifetime of the token
|
||||
- **Access Token Max Number of Uses**: Max times the token can be used (`0` = unlimited)
|
||||
- **Access Token Trusted IPs**: List of allowed IP ranges (defaults to `0.0.0.0/0`)
|
||||
|
||||
<Tip>If you are unsure about what to configure for the subject, audience, and claims fields, you can inspect the JWT token from your Azure DevOps pipeline by adding a debug step that outputs the token claims.</Tip>
|
||||
<Info>The `subject`, `audiences`, and `claims` fields support glob pattern matching; however, we highly recommend using hardcoded values whenever possible.</Info>
|
||||
</Step>
|
||||
<Step title="Adding an identity to a project">
|
||||
To enable the identity to access project-level resources such as secrets within a specific project, you should add it to that project.
|
||||
|
||||
To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**.
|
||||
|
||||
Next, select the identity you want to add to the project and the project level role you want to allow it to assume. The project role assigned will determine what project level resources this identity can have access to.
|
||||
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Accessing the Infisical API with the identity">
|
||||
In Azure DevOps, to authenticate with Infisical using OIDC, you must configure a service connection that enables workload identity federation.
|
||||
|
||||
Once set up, the OIDC token can be fetched automatically within the pipeline job context. Here's an example:
|
||||
|
||||
```yaml
|
||||
trigger:
|
||||
- main
|
||||
|
||||
pool:
|
||||
vmImage: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- task: AzureCLI@2
|
||||
displayName: 'Retrieve secrets from Infisical using OIDC'
|
||||
inputs:
|
||||
azureSubscription: 'your-azure-service-connection-name'
|
||||
scriptType: 'bash'
|
||||
scriptLocation: 'inlineScript'
|
||||
addSpnToEnvironment: true
|
||||
inlineScript: |
|
||||
# Get OIDC access token
|
||||
OIDC_TOKEN=$(az account get-access-token --resource "api://AzureADTokenExchange" --query accessToken -o tsv)
|
||||
|
||||
[ -z "$OIDC_TOKEN" ] && { echo "Failed to get access token"; exit 1; }
|
||||
|
||||
# Exchange for Infisical access token
|
||||
ACCESS_TOKEN=$(curl -s -X POST "<YOUR-INFISICAL-INSTANCE-URL>/api/v1/auth/oidc-auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"identityId\":\"{your-identity-id}\",\"jwt\":\"$OIDC_TOKEN\"}" \
|
||||
| jq -r '.accessToken')
|
||||
|
||||
# Fetch secrets
|
||||
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
|
||||
"<YOUR-INFISICAL-INSTANCE-URL>/api/v3/secrets/raw?environment={your-environment-slug}&workspaceSlug={your-workspace-slug}"
|
||||
```
|
||||
|
||||
Make sure the service connection is properly configured for workload identity federation and linked to your Azure AD app registration with appropriate claims.
|
||||
|
||||
<Note>
|
||||
Each identity access token has a time-to-live (TTL) which you can infer from the response of the login operation;
|
||||
the default TTL is `7200` seconds which can be adjusted.
|
||||
|
||||
If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
|
||||
a new access token should be obtained by performing another login operation.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
177
docs/documentation/platform/identities/oidc-auth/spire.mdx
Normal file
177
docs/documentation/platform/identities/oidc-auth/spire.mdx
Normal file
@@ -0,0 +1,177 @@
|
||||
---
|
||||
title: SPIFFE/SPIRE
|
||||
description: "Learn how to authenticate SPIRE workloads with Infisical using OpenID Connect (OIDC)."
|
||||
---
|
||||
|
||||
**OIDC Auth** is a platform-agnostic JWT-based authentication method that can be used to authenticate from any platform or environment using an identity provider with OpenID Connect.
|
||||
|
||||
## Diagram
|
||||
|
||||
The following sequence diagram illustrates the OIDC Auth workflow for authenticating SPIRE workloads with Infisical.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as SPIRE Workload
|
||||
participant Agent as SPIRE Agent
|
||||
participant Server as SPIRE Server
|
||||
participant Infis as Infisical
|
||||
|
||||
Client->>Agent: Step 1: Request JWT-SVID
|
||||
Agent->>Server: Validate workload and fetch signing key
|
||||
Server-->>Agent: Return signing material
|
||||
Agent-->>Client: Return JWT-SVID with verifiable claims
|
||||
|
||||
Note over Client,Infis: Step 2: Login Operation
|
||||
Client->>Infis: Send JWT-SVID to /api/v1/auth/oidc-auth/login
|
||||
|
||||
Note over Infis,Server: Step 3: Query verification
|
||||
Infis->>Server: Request JWT public key using OIDC Discovery
|
||||
Server-->>Infis: Return public key
|
||||
|
||||
Note over Infis: Step 4: JWT validation
|
||||
Infis->>Client: Return short-lived access token
|
||||
|
||||
Note over Client,Infis: Step 5: Access Infisical API with Token
|
||||
Client->>Infis: Make authenticated requests using the short-lived access token
|
||||
```
|
||||
|
||||
## Concept
|
||||
|
||||
At a high-level, Infisical authenticates a SPIRE workload by verifying the JWT-SVID and checking that it meets specific requirements (e.g. it is issued by a trusted SPIRE server) at the `/api/v1/auth/oidc-auth/login` endpoint. If successful,
|
||||
then Infisical returns a short-lived access token that can be used to make authenticated requests to the Infisical API.
|
||||
|
||||
To be more specific:
|
||||
|
||||
1. The SPIRE workload requests a JWT-SVID from the local SPIRE Agent.
|
||||
2. The SPIRE Agent validates the workload's identity and requests signing material from the SPIRE Server.
|
||||
3. The SPIRE Agent returns a JWT-SVID containing the workload's SPIFFE ID and other claims.
|
||||
4. The JWT-SVID is sent to Infisical at the `/api/v1/auth/oidc-auth/login` endpoint.
|
||||
5. Infisical fetches the public key that was used to sign the JWT-SVID from the SPIRE Server using OIDC Discovery.
|
||||
6. Infisical validates the JWT-SVID using the public key provided by the SPIRE Server and checks that the subject, audience, and claims of the token matches with the set criteria.
|
||||
7. If all is well, Infisical returns a short-lived access token that the workload can use to make authenticated requests to the Infisical API.
|
||||
|
||||
<Note>Infisical needs network-level access to the SPIRE Server's OIDC Discovery endpoint.</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before following this guide, ensure you have:
|
||||
|
||||
- A running SPIRE deployment with both SPIRE Server and SPIRE Agent configured
|
||||
- OIDC Discovery Provider deployed alongside your SPIRE Server
|
||||
- Workload registration entries created in SPIRE for the workloads that need to access Infisical
|
||||
- Network connectivity between Infisical and your OIDC Discovery Provider endpoint
|
||||
|
||||
For detailed SPIRE setup instructions, refer to the [SPIRE documentation](https://spiffe.io/docs/latest/spire-about/).
|
||||
|
||||
## OIDC Discovery Provider Setup
|
||||
|
||||
To enable JWT-SVID verification with Infisical, you need to deploy the OIDC Discovery Provider alongside your SPIRE Server. The OIDC Discovery Provider runs as a separate service that exposes the necessary OIDC endpoints.
|
||||
|
||||
In Kubernetes deployments, this is typically done by adding an `oidc-discovery-provider` container to your SPIRE Server StatefulSet:
|
||||
|
||||
```yaml
|
||||
- name: spire-oidc
|
||||
image: ghcr.io/spiffe/oidc-discovery-provider:1.12.2
|
||||
args:
|
||||
- -config
|
||||
- /run/spire/oidc/config/oidc-discovery-provider.conf
|
||||
ports:
|
||||
- containerPort: 443
|
||||
name: spire-oidc-port
|
||||
```
|
||||
|
||||
The OIDC Discovery Provider will expose the OIDC Discovery endpoint at `https://<spire-oidc-host>/.well-known/openid_configuration`, which Infisical will use to fetch the public keys for JWT-SVID verification.
|
||||
|
||||
<Note>For detailed setup instructions, refer to the [SPIRE OIDC Discovery Provider documentation](https://github.com/spiffe/spire/tree/main/support/oidc-discovery-provider).</Note>
|
||||
|
||||
## Guide
|
||||
|
||||
In the following steps, we explore how to create and use identities to access the Infisical API using the OIDC Auth authentication method with SPIFFE/SPIRE.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating an identity">
|
||||
To create an identity, head to your Organization Settings > Access Control > Identities and press **Create identity**.
|
||||
|
||||
|
||||
|
||||
When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
|
||||
|
||||
|
||||
|
||||
Now input a few details for your new identity. Here's some guidance for each field:
|
||||
|
||||
- Name (required): A friendly name for the identity.
|
||||
- Role (required): A role from the **Organization Roles** tab for the identity to assume. The organization role assigned will determine what organization level resources this identity can have access to.
|
||||
|
||||
Once you've created an identity, you'll be redirected to a page where you can manage the identity.
|
||||
|
||||
|
||||
|
||||
Since the identity has been configured with Universal Auth by default, you should re-configure it to use OIDC Auth instead. To do this, press to edit the **Authentication** section,
|
||||
remove the existing Universal Auth configuration, and add a new OIDC Auth configuration onto the identity.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<Warning>Restrict access by configuring the Subject, Audiences, and Claims fields</Warning>
|
||||
|
||||
Here's some more guidance on each field:
|
||||
- OIDC Discovery URL: The URL used to retrieve the OpenID Connect configuration from the SPIRE Server. This will be used to fetch the public key needed for verifying the provided JWT-SVID. This should be set to your SPIRE Server's OIDC Discovery endpoint, typically `https://<spire-server-host>:<port>/.well-known/openid_configuration`
|
||||
- Issuer: The unique identifier of the SPIRE Server issuing the JWT-SVID. This value is used to verify the iss (issuer) claim in the JWT-SVID to ensure the token is issued by a trusted SPIRE Server. This should match your SPIRE Server's configured issuer, typically `https://<spire-server-host>:<port>`
|
||||
- CA Certificate: The PEM-encoded CA certificate for establishing secure communication with the SPIRE Server endpoints. This should contain the CA certificate that signed your SPIRE Server's TLS certificate.
|
||||
- Subject: The expected SPIFFE ID that is the subject of the JWT-SVID. The format of the sub field for SPIRE JWT-SVIDs follows the SPIFFE ID format: `spiffe://<trust-domain>/<workload-path>`. For example: `spiffe://example.org/workload/api-server`
|
||||
- Audiences: A list of intended recipients for the JWT-SVID. This value is checked against the aud (audience) claim in the token. When workloads request JWT-SVIDs from SPIRE, they specify an audience (e.g., `infisical` or your service name). Configure this to match what your workloads use.
|
||||
- Claims: Additional information or attributes that should be present in the JWT-SVID for it to be valid. Standard SPIRE JWT-SVID claims include `sub` (SPIFFE ID), `aud` (audience), `exp` (expiration), and `iat` (issued at). You can also configure custom claims if your SPIRE Server includes additional metadata.
|
||||
- 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 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.
|
||||
<Tip>SPIRE JWT-SVIDs contain standard claims like `sub` (SPIFFE ID), `aud` (audience), `exp`, and `iat`. The audience is typically specified when requesting the JWT-SVID (e.g., `spire-agent api fetch jwt -audience infisical`).</Tip>
|
||||
<Info>The `subject`, `audiences`, and `claims` fields support glob pattern matching; however, we highly recommend using hardcoded SPIFFE IDs whenever possible for better security.</Info>
|
||||
</Step>
|
||||
<Step title="Adding an identity to a project">
|
||||
To enable the identity to access project-level resources such as secrets within a specific project, you should add it to that project.
|
||||
|
||||
To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**.
|
||||
|
||||
Next, select the identity you want to add to the project and the project level role you want to allow it to assume. The project role assigned will determine what project level resources this identity can have access to.
|
||||
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Using JWT-SVID to authenticate with Infisical">
|
||||
Here's an example of how a workload can use its JWT-SVID to authenticate with Infisical and retrieve secrets:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Obtain JWT-SVID from SPIRE Agent
|
||||
JWT_SVID=$(spire-agent api fetch jwt -audience infisical -socketPath /run/spire/sockets/agent.sock | grep -A1 "token(" | tail -1)
|
||||
|
||||
# Authenticate with Infisical using the JWT-SVID
|
||||
ACCESS_TOKEN=$(curl -s -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"identityId\":\"<your-identity-id>\",\"jwt\":\"$JWT_SVID\"}" \
|
||||
https://app.infisical.com/api/v1/auth/oidc-auth/login | jq -r '.accessToken')
|
||||
|
||||
# Use the access token to retrieve secrets
|
||||
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
|
||||
"https://app.infisical.com/api/v3/secrets/raw?workspaceSlug=<project-slug>&environment=<env-slug>&secretPath=/"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Each identity access token has a time-to-live (TTL) which you can infer from the response of the login operation;
|
||||
the default TTL is `7200` seconds which can be adjusted.
|
||||
|
||||
If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
|
||||
a new access token should be obtained by performing another login operation.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
JWT-SVIDs from SPIRE have their own expiration time (typically short-lived). Ensure your application handles both JWT-SVID renewal from SPIRE and access token renewal from Infisical appropriately.
|
||||
</Tip>
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
@@ -1,175 +0,0 @@
|
||||
---
|
||||
title: 'Secret Scanning'
|
||||
description: "Scan and prevent secret leaks in your code repositories"
|
||||
---
|
||||
|
||||
The Infisical Secret Scanner allows you to keep an overview and stay alert of exposed secrets across your entire GitHub organization and repositories.
|
||||
|
||||
To further enhance security, we recommend you also use our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to scan for exposed secrets prior to pushing your changes.
|
||||
|
||||
|
||||
<Accordion title="Self-hosting">
|
||||
|
||||
To setup secret scanning on your own instance of Infisical, you can follow the steps below.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a GitHub App">
|
||||
Create a new GitHub app in your GitHub organization or personal [Developer Settings](https://github.com/settings/apps).
|
||||
|
||||
|
||||
|
||||
### Configure the GitHub App
|
||||
To configure the GitHub app to work with Infisical, you'll need to modify the following settings:
|
||||
- **Homepage URL**: Required to be set. Set it to the URL of your Infisical instance. (e.g. `https://app.infisical.com`)
|
||||
- **Setup URL**: Set this to `https://<your-infisical-instance.com>/organization/secret-scanning`
|
||||
- **Webhook URL**: Set this to `https://<your-infisical-instance.com>/api/v1/secret-scanning/webhook`
|
||||
- **Webhook Secret**: Set this to a random string. This is used to verify the webhook request from Infisical. Use `openssl rand -base64 32` in your terminal to generate a random secret.
|
||||
|
||||
<Note>
|
||||
Remember to save the webhook secret as you will need it in the next step.
|
||||
</Note>
|
||||
|
||||
|
||||
|
||||
### Configure the GitHub App Permissions
|
||||
The GitHub app needs the following permissions:
|
||||
|
||||
Repository permissions:
|
||||
- `Checks`: Read and Write
|
||||
- `Contents`: Read-only
|
||||
- `Issues`: Read and Write
|
||||
- `Pull Requests`: Read and Write
|
||||
- `Metadata`: Read-only (enabled by default)
|
||||
|
||||
|
||||
|
||||
Subscribed events:
|
||||
- `Check run`
|
||||
- `Pull request`
|
||||
- `Push`
|
||||
|
||||
|
||||
|
||||
|
||||
### Create the GitHub App
|
||||
Now you can create the GitHub app by clicking on the "Create GitHub App" button.
|
||||
|
||||
<Note>
|
||||
If you want other Github users to be able to install the app, you need to tick the "Any account" option under "Where can this GitHub App be installed?"
|
||||
</Note>
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Retrieve the GitHub App ID">
|
||||
After clicking the "Create GitHub App" button, you will be redirected to the GitHub settings page. Here you can copy the "App ID" and save it for later when you need to configure your environment variables for your Infisical instance.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Retrieve your GitHub App slug">
|
||||
The GitHub App slug is the name of the app you created in a slug friendly format. You can find the slug in the URL of the app you created.
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Create a new GitHub App private key">
|
||||
Create a new app private key by clicking on the "Generate a private key" button under the "Private keys" section.
|
||||
|
||||
Once you click the "Generate a private key" button, the private key will be downloaded to your computer. Save this file for later as you will need the private key when configuring Infisical.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Remember to save the private key as you will need it in the next step.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
|
||||
<Step title="Configure your Infisical instance">
|
||||
Now you can configure your Infisical instance by setting the following environment variables:
|
||||
|
||||
- `SECRET_SCANNING_GIT_APP_ID`: The App ID of your GitHub App.
|
||||
- `SECRET_SCANNING_GIT_APP_SLUG`: The slug of your GitHub App.
|
||||
- `SECRET_SCANNING_PRIVATE_KEY`: The private key of your GitHub App that you created in a previous step.
|
||||
- `SECRET_SCANNING_WEBHOOK_SECRET`: The webhook secret of your GitHub App that you created in a previous step.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
After restarting your Infisical instance, you should be able to use the secret scanning feature within your organization. Follow the steps below to add the GitHub App to your Infisical organization.
|
||||
</Accordion>
|
||||
|
||||
## Install the Infisical Radar GitHub App
|
||||
|
||||
To install the GitHub App, press the "Integrate With GitHub" button in the top right corner of your Infisical Secret Scanning dashboard.
|
||||
|
||||
|
||||
|
||||
Next, you'll be prompted to select which organization you'd like to install the app into. Select the organization you'd like to install the app into by clicking the organization in the menu.
|
||||
|
||||
|
||||
|
||||
Select the repositories you'd like to scan for secrets and press the "Install" button.
|
||||
|
||||
|
||||
|
||||
## Code Scanning
|
||||
|
||||
|
||||
|
||||
Secret scans are built on event-driven architecture. This means that every time a push is made to one of your selected repositories, Infisical will scan the modified files for any exposed secrets.
|
||||
|
||||
If one or more exposed secrets are detected, it will be displayed in your Infisical dashboard. An exposed secret is known as a **"Risk"**. Each risk has the following data associated with it:
|
||||
- **Date**: When the risk was first detected.
|
||||
- **Secret Type**: Which type of secret was detected.
|
||||
- **Info**: Information about the secret, such as the repository, file name, and the committer who made the change.
|
||||
|
||||
Once an exposed secret is detected, all organization admins will be sent an e-mail notification containing details about the exposed secret.
|
||||
|
||||
<Tip>
|
||||
Each risk also contains a "View Exposed Secret" button, which will take you directly to the GitHub commit and to the line where the secret was exposed.
|
||||
</Tip>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Responding to Exposed Secrets
|
||||
|
||||
After an exposed secret is detected, it will be marked as `Needs Attention`. When there are risks marked as needs attention, it's important to address them as soon as possible.
|
||||
|
||||
You can mark the risk as `Resolved` by changing the status to one of the following states:
|
||||
- **This Is a False Positive**: The secret was not exposed, but was detected by the scanner.
|
||||
- **I Have Rotated The Secret**: The secret was exposed, but it has now been removed.
|
||||
- **No Rotation Needed**: You are choosing to ignore this risk. You may choose to do this if the risk is non-sensitive or otherwise not a security risk.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Ignoring Known Secrets
|
||||
If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
|
||||
|
||||
### infisical-scan:ignore
|
||||
|
||||
To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
|
||||
|
||||
```js example.js
|
||||
function helloWorld() {
|
||||
console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
|
||||
}
|
||||
```
|
||||
|
||||
### .infisicalignore
|
||||
An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
|
||||
You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
|
||||
By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
|
||||
|
||||
```.ignore .infisicalignore
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
|
||||
1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
|
||||
```
|
||||
96
docs/documentation/platform/secret-scanning/github.mdx
Normal file
96
docs/documentation/platform/secret-scanning/github.mdx
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: "GitHub Secret Scanning"
|
||||
sidebarTitle: "GitHub"
|
||||
description: "Learn how to configure secret scanning for GitHub."
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Create a [GitHub Radar Connection](/integrations/app-connections/github-radar)
|
||||
|
||||
## Create a GitHub Data Source in Infisical
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Infisical UI">
|
||||
1. Navigate to your Secret Scanning Project's Dashboard and click the **Add Data Source** button.
|
||||
|
||||
|
||||
2. Select the **GitHub** option.
|
||||
|
||||
|
||||
3. Select the **GitHub Radar Connection** to use and configure which repositories you would like to scan. Then click **Next**.
|
||||
|
||||
|
||||
- **GitHub Radar Connection** - the connection that has access to the repositories you want to scan.
|
||||
- **Scan Repositories** - select which repositories you would like to scan.
|
||||
- **All Repositories** - Infisical will scan all repositories associated with your connection.
|
||||
- **Select Repositories** - Infisical will scan the selected repositories.
|
||||
- **Auto-Scan Enabled** - whether Infisical should automatically perform a scan when a push is made to configured repositories.
|
||||
|
||||
4. Give your data source a name and description (optional). Then click **Next**.
|
||||
|
||||
|
||||
- **Name** - the name of the data source. Must be slug-friendly.
|
||||
- **Description** (optional) - a description of this data source.
|
||||
|
||||
5. Review your data source, then click **Create Data Source**.
|
||||
|
||||
|
||||
6. Your **GitHub Data Source** is now available and will begin a full scan if **Auto-Scan** is enabled.
|
||||
|
||||
|
||||
7. You can view repositories and scan results by clicking on your data source.
|
||||
|
||||
|
||||
8. In addition, you can review any findings from the **Findings Page**.
|
||||
|
||||
</Tab>
|
||||
<Tab title="API">
|
||||
To create a GitHub Data Source, make an API request to the [Create GitHub Data Source](/api-reference/endpoints/secret-scanning/data-sources/github/create) API endpoint.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --request POST \
|
||||
--url https://us.infisical.com/api/v2/secret-scanning/data-sources/github \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"name": "my-github-source",
|
||||
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"description": "my github data source",
|
||||
"connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"isAutoScanEnabled": true,
|
||||
"config": {
|
||||
"includeRepos": ["*"]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
"dataSource": {
|
||||
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"externalId": "1234567890",
|
||||
"name": "my-github-source",
|
||||
"description": "my github data source",
|
||||
"isAutoScanEnabled": true,
|
||||
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"createdAt": "2023-11-07T05:31:56Z",
|
||||
"updatedAt": "2023-11-07T05:31:56Z",
|
||||
"type": "github",
|
||||
"connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"connection": {
|
||||
"app": "github-radar",
|
||||
"name": "my-radar-app",
|
||||
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
|
||||
},
|
||||
"config": {
|
||||
"includeRepos": ["*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
230
docs/documentation/platform/secret-scanning/overview.mdx
Normal file
230
docs/documentation/platform/secret-scanning/overview.mdx
Normal file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
title: "Secret Scanning"
|
||||
sidebarTitle: "Overview"
|
||||
description: "Scan and prevent secret leaks in your code repositories"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Monitor and detect exposed secrets across your data sources, including code repositories, with Infisical Secret Scanning.
|
||||
|
||||
For additional security, we recommend using our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to check for exposed secrets before pushing your code changes.
|
||||
|
||||
<Note>
|
||||
Secret Scanning 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.
|
||||
</Note>
|
||||
|
||||
## How Secret Scanning Works
|
||||
|
||||
Secret Scanning consists of several components that enable you to quickly respond to secret leaks:
|
||||
|
||||
- **Scanner Engine**: The core component that analyzes your code and detects potential secrets using pattern matching and entropy analysis
|
||||
- **Real-time Monitoring**: Provides continuous surveillance of your repositories for immediate detection of exposed secrets
|
||||
- **Alert System**: Notifies organization admins via email when secrets are detected
|
||||
- **Risk Management**: Allows tracking and managing detected secrets with different status options
|
||||
- **Data Sources**: Integrates with various data sources and version control systems
|
||||
- **Customizable Rules**: Supports ignore patterns and custom configurations to reduce false positives
|
||||
|
||||
These components work together to provide comprehensive secret detection and incident response capabilities.
|
||||
|
||||
### Data Sources
|
||||
|
||||
Data sources are configured integrations with external platforms, such as a GitHub organization or a GitLab group, that establish secure connections for scanning purposes using [App Connections](/integrations/app-connections/overview).
|
||||
|
||||
A data source acts as a secure intermediary between the external system and the scanner engine. It manages a collection of scannable resources (such as repositories) and handles the authentication and communication required for scanning operations.
|
||||
|
||||
|
||||
|
||||
### Resources
|
||||
|
||||
Resources are the atomic, scannable units, such as a repository, that can be monitored for secret exposure. Resources are added automatically when a data source is scanned and updated when scanning events are triggered, such as when a user pushes changes to GitHub.
|
||||
|
||||
Each resource maintains its own scanning history and status, allowing for granular monitoring and management of secret scanning across your organization.
|
||||
|
||||
|
||||
|
||||
### Scans
|
||||
|
||||
Scans can be initiated in two ways:
|
||||
|
||||
1. **Full Scan** - Manually triggered scan that comprehensively checks either all resources associated with a data source or a single selected resource.
|
||||
|
||||
2. **Diff Scan** - Automatically executed when **Auto-Scan** is enabled on a data source. This scan type specifically focuses on updates to existing resources.
|
||||
|
||||
All scan activities can be monitored in real-time through the Infisical UI, which displays:
|
||||
- Current scan status
|
||||
- Timestamp of the scan
|
||||
- Resource(s) being scanned
|
||||
- Detection results (whether any secrets were found)
|
||||
|
||||
|
||||
|
||||
### Findings
|
||||
|
||||
Findings are automatically generated when secret leaks are detected during scanning operations. Each finding contains comprehensive information including:
|
||||
- The specific scanning rule that identified the leak
|
||||
- File location and line number where the secret was found
|
||||
- Resource-specific details (e.g., commit hash and author for Git repositories)
|
||||
|
||||
Findings are initially marked as **Unresolved** and can be updated to one of the following statuses with additional remarks:
|
||||
- **Resolved** - The issue has been addressed
|
||||
- **False Positive** - The detection was incorrect
|
||||
- **Ignore** - The finding can be safely disregarded
|
||||
|
||||
These status options help teams effectively track and manage the lifecycle of detected secret leaks.
|
||||
|
||||
|
||||
|
||||
### Configuration
|
||||
|
||||
You can configure custom scanning rules and exceptions by updating your project's scanning configuration via the UI or API.
|
||||
|
||||
The configuration options allow you to:
|
||||
- Define custom scanning patterns and rules
|
||||
- Set up ignore patterns to reduce false positives
|
||||
- Specify file path exclusions
|
||||
- Configure entropy thresholds for secret detection
|
||||
- Add allowlists for known safe patterns
|
||||
|
||||
For detailed configuration options, expand the example configuration below.
|
||||
|
||||
<Accordion title="Example Configuration">
|
||||
```toml
|
||||
# Title for the configuration file
|
||||
title = "Some title"
|
||||
|
||||
|
||||
# This configuration is the foundation that can be expanded. If there are any overlapping rules
|
||||
# between this base and the expanded configuration, the rules in this base will take priority.
|
||||
# Another aspect of extending configurations is the ability to link multiple files, up to a depth of 2.
|
||||
# "Allowlist" arrays get appended and may have repeated elements.
|
||||
# "useDefault" and "path" cannot be used simultaneously. Please choose one.
|
||||
[extend]
|
||||
# useDefault will extend the base configuration with the default config:
|
||||
# https://raw.githubusercontent.com/Infisical/infisical/main/cli/config/infisical-scan.toml
|
||||
useDefault = true
|
||||
# or you can supply a path to a configuration. Path is relative to where infisical cli
|
||||
# was invoked, not the location of the base config.
|
||||
path = "common_config.toml"
|
||||
|
||||
# An array of tables that contain information that define instructions
|
||||
# on how to detect secrets
|
||||
[[rules]]
|
||||
|
||||
# Unique identifier for this rule
|
||||
id = "some-identifier-for-rule"
|
||||
|
||||
# Short human readable description of the rule.
|
||||
description = "awesome rule 1"
|
||||
|
||||
# Golang regular expression used to detect secrets. Note Golang's regex engine
|
||||
# does not support lookaheads.
|
||||
regex = '''one-go-style-regex-for-this-rule'''
|
||||
|
||||
# Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
|
||||
# in conjunction with a valid `regex` entry.
|
||||
path = '''a-file-path-regex'''
|
||||
|
||||
# Array of strings used for metadata and reporting purposes.
|
||||
tags = ["tag","another tag"]
|
||||
|
||||
# A regex match may have many groups, this allows you to specify the group that should be used as (which group the secret is contained in)
|
||||
# its entropy checked if `entropy` is set.
|
||||
secretGroup = 3
|
||||
|
||||
# Float representing the minimum shannon entropy a regex group must have to be considered a secret.
|
||||
# Shannon entropy measures how random a data is. Since secrets are usually composed of many random characters, they typically have high entropy
|
||||
entropy = 3.5
|
||||
|
||||
# Keywords are used for pre-regex check filtering.
|
||||
# If rule has keywords but the text fragment being scanned doesn't have at least one of it's keywords, it will be skipped for processing further.
|
||||
# Ideally these values should either be part of the identifier or unique strings specific to the rule's regex
|
||||
# (introduced in v8.6.0)
|
||||
keywords = [
|
||||
"auth",
|
||||
"password",
|
||||
"token",
|
||||
]
|
||||
|
||||
# You can include an allowlist table for a single rule to reduce false positives or ignore commits
|
||||
# with known/rotated secrets
|
||||
[rules.allowlist]
|
||||
description = "ignore commit A"
|
||||
commits = [ "commit-A", "commit-B"]
|
||||
paths = [
|
||||
'''go\.mod''',
|
||||
'''go\.sum'''
|
||||
]
|
||||
# note: (rule) regexTarget defaults to check the _Secret_ in the finding.
|
||||
# if regexTarget is not specified then _Secret_ will be used.
|
||||
# Acceptable values for regexTarget are "match" and "line"
|
||||
regexTarget = "match"
|
||||
regexes = [
|
||||
'''process''',
|
||||
'''getenv''',
|
||||
]
|
||||
# note: stopwords targets the extracted secret, not the entire regex match
|
||||
# if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
|
||||
stopwords = [
|
||||
'''client''',
|
||||
'''endpoint''',
|
||||
]
|
||||
|
||||
|
||||
# This is a global allowlist which has a higher order of precedence than rule-specific allowlists.
|
||||
# If a commit listed in the `commits` field below is encountered then that commit will be skipped and no
|
||||
# secrets will be detected for said commit. The same logic applies for regexes and paths.
|
||||
[allowlist]
|
||||
description = "global allow list"
|
||||
commits = [ "commit-A", "commit-B", "commit-C"]
|
||||
paths = [
|
||||
'''gitleaks\.toml''',
|
||||
'''(.*?)(jpg|gif|doc)'''
|
||||
]
|
||||
|
||||
# note: (global) regexTarget defaults to check the _Secret_ in the finding.
|
||||
# if regexTarget is not specified then _Secret_ will be used.
|
||||
# Acceptable values for regexTarget are "match" and "line"
|
||||
regexTarget = "match"
|
||||
|
||||
regexes = [
|
||||
'''219-09-9999''',
|
||||
'''078-05-1120''',
|
||||
'''(9[0-9]{2}|666)-\d{2}-\d{4}''',
|
||||
]
|
||||
# note: stopwords targets the extracted secret, not the entire regex match
|
||||
# if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
|
||||
stopwords = [
|
||||
'''client''',
|
||||
'''endpoint''',
|
||||
]
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
|
||||
|
||||
## Ignoring Known Secrets
|
||||
If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
|
||||
|
||||
### infisical-scan:ignore
|
||||
|
||||
To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
|
||||
|
||||
```js example.js
|
||||
function helloWorld() {
|
||||
console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
|
||||
}
|
||||
```
|
||||
|
||||
### .infisicalignore
|
||||
An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
|
||||
You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
|
||||
By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
|
||||
|
||||
```.ignore .infisicalignore
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
|
||||
bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
|
||||
1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
|
||||
```
|
||||
Reference in New Issue
Block a user