Merge remote-tracking branch 'origin/main' into feat/resource-metadata

This commit is contained in:
Sheen Capadngan
2024-12-20 14:23:14 +08:00
231 changed files with 11454 additions and 167 deletions
@@ -0,0 +1,9 @@
---
title: "Create"
openapi: "POST /api/v1/app-connections/aws"
---
<Note>
Check out the configuration docs for [AWS Connections](/integrations/app-connections/aws) to learn how to obtain
the required credentials.
</Note>
@@ -0,0 +1,4 @@
---
title: "Delete"
openapi: "DELETE /api/v1/app-connections/aws/{connectionId}"
---
@@ -0,0 +1,4 @@
---
title: "Get by ID"
openapi: "GET /api/v1/app-connections/aws/{connectionId}"
---
@@ -0,0 +1,4 @@
---
title: "Get by Name"
openapi: "GET /api/v1/app-connections/aws/name/{connectionName}"
---
@@ -0,0 +1,4 @@
---
title: "List"
openapi: "GET /api/v1/app-connections/aws"
---
@@ -0,0 +1,9 @@
---
title: "Update"
openapi: "PATCH /api/v1/app-connections/aws/{connectionId}"
---
<Note>
Check out the configuration docs for [AWS Connections](/integrations/app-connections/aws) to learn how to obtain
the required credentials.
</Note>
@@ -0,0 +1,10 @@
---
title: "Create"
openapi: "POST /api/v1/app-connections/github"
---
<Note>
GitHub Connections must be created through the Infisical UI.
Check out the configuration docs for [GitHub Connections](/integrations/app-connections/github) for a step-by-step
guide.
</Note>
@@ -0,0 +1,4 @@
---
title: "Delete"
openapi: "DELETE /api/v1/app-connections/github/{connectionId}"
---
@@ -0,0 +1,4 @@
---
title: "Get by ID"
openapi: "GET /api/v1/app-connections/github/{connectionId}"
---
@@ -0,0 +1,4 @@
---
title: "Get by Name"
openapi: "GET /api/v1/app-connections/github/name/{connectionName}"
---
@@ -0,0 +1,4 @@
---
title: "List"
openapi: "GET /api/v1/app-connections/github"
---
@@ -0,0 +1,10 @@
---
title: "Update"
openapi: "PATCH /api/v1/app-connections/github/{connectionId}"
---
<Note>
GitHub Connections must be updated through the Infisical UI.
Check out the configuration docs for [GitHub Connections](/integrations/app-connections/github) for a step-by-step
guide.
</Note>
@@ -0,0 +1,4 @@
---
title: "List"
openapi: "GET /api/v1/app-connections"
---
@@ -0,0 +1,4 @@
---
title: "Options"
openapi: "GET /api/v1/app-connections/options"
---
@@ -0,0 +1,4 @@
---
title: "Create"
openapi: "POST /api/v1/ssh/ca"
---
@@ -0,0 +1,4 @@
---
title: "Delete"
openapi: "DELETE /api/v1/ssh/ca/{sshCaId}"
---
@@ -0,0 +1,4 @@
---
title: "List templates"
openapi: "GET /api/v1/ssh/ca/{sshCaId}/certificate-templates"
---
@@ -0,0 +1,4 @@
---
title: "List"
openapi: "GET /api/v2/workspace/{projectId}/ssh-cas"
---
@@ -0,0 +1,4 @@
---
title: "Retrieve public key"
openapi: "GET /api/v1/ssh/ca/{sshCaId}/public-key"
---
@@ -0,0 +1,4 @@
---
title: "Retrieve"
openapi: "GET /api/v1/ssh/ca/{sshCaId}"
---
@@ -0,0 +1,4 @@
---
title: "Update"
openapi: "PATCH /api/v1/ssh/ca/{sshCaId}"
---
@@ -0,0 +1,4 @@
---
title: "Create"
openapi: "POST /api/v1/ssh/certificate-templates"
---
@@ -0,0 +1,4 @@
---
title: "Delete"
openapi: "DELETE /api/v1/ssh/certificate-templates/{certificateTemplateId}"
---
@@ -0,0 +1,4 @@
---
title: "List"
openapi: "GET /api/v2/workspace/{projectId}/ssh-certificate-templates"
---
@@ -0,0 +1,4 @@
---
title: "Retrieve"
openapi: "GET /api/v1/ssh/certificate-templates/{certificateTemplateId}"
---
@@ -0,0 +1,4 @@
---
title: "Update"
openapi: "PATCH /api/v1/ssh/certificate-templates/{certificateTemplateId}"
---
@@ -0,0 +1,4 @@
---
title: "Issue SSH Credentials"
openapi: "POST /api/v1/ssh/certificates/issue"
---
@@ -0,0 +1,4 @@
---
title: "Sign SSH Public Key"
openapi: "POST /api/v1/ssh/certificates/sign"
---
+209
View File
@@ -0,0 +1,209 @@
---
title: "Infisical SSH"
sidebarTitle: "Infisical SSH"
description: "Learn how to generate SSH credentials to provide secure and centralized SSH access control for your infrastructure."
---
## Concept
Infisical can be used to issue SSH certificates to clients to provide short-lived, secure SSH access to infrastructure;
this improves on many limitations of traditional SSH key-based authentication via mitigation of private key compromise, static key management,
unauthorized access, and SSH key sprawl.
The following concepts are useful to know when working with Infisical SSH:
- SSH Certificate Authority (CA): A trusted authority that issues SSH certificates.
- Certificate Template: A set of policies bound to a SSH CA for certificates issued under that template; a CA can possess multiple templates, each with different policies for a different purpose (e.g. for admin versus developer access).
- SSH Certificate: A short-lived, credential issued by the SSH CA granting time-bound access to infrastructure.
<div align="center">
```mermaid
graph TD
A[SSH CA]
A --> B[Certificate Template A]
A --> C[Certificate Template N]
B --> D[SSH Certificate A]
C --> E[SSH Certificate N]
```
</div>
When using Infisical SSH to provision client access to a remote host, an operator must create a SSH CA in Infisical; a certificate template under it,
specifying policies such as allowed users that can be requested under that template by a client; and configure the host to trust certificates issued by the Infisical SSH CA.
When a client needs access to a host, they authenticate with Infisical and request a SSH certificate (and optionally key pair)
to be used to access the host for a time-bound session as part of the SSH operation.
## Client Workflow
The following sequence diagram illustrates the client workflow for accessing a remote host using an SSH certificate (and optionally key pair)
supplied by Infisical.
```mermaid
sequenceDiagram
participant Client as Client
participant Infisical as Infisical (SSH CA)
participant Host as Remote Host
Note over Client,Client: Step 1: Client Authentication with Infisical
Client->>Infisical: Send credential(s) to authenticate with Infisical
Infisical-->>Client: Return access token
Note over Client,Infisical: Step 2: SSH Certificate Request
Client->>Infisical: Make authenticated request for SSH certificate via either /api/v1/ssh/issue or /api/v1/ssh/sign
Infisical-->>Client: Return signed SSH certificate (and optionally key pair)
Note over Client,Client: Step 3: SSH Operation
Client->>Host: SSH into Host using the SSH certificate
Host-->>Client: Grant access to the host
```
At a high-level, Infisical issues a signed SSH certificate to a client that can be used to access a remote host.
To be more specific:
1. The client authenticates with Infisical; this can be done using a machine identity [authentication method](/documentation/platform/identities/machine-identities) or a user [authentication method](/documentation/platform/identities/user-identities).
2. The client makes an authenticated request for an SSH certificate via either the `/api/v1/ssh/issue` or `/api/v1/ssh/sign` endpoints. Note that if the client wishes to use an existing SSH key pair, it can use the `/api/v1/ssh/sign` endpoint; otherwise, it can use the `/api/v1/ssh/issue` endpoint to have Infisical issue a new SSH key pair in conjunction with the certificate.
3. The client uses the issued SSH certificate (and potentially SSH key pair) to temporarily access the host.
<Note>
Note that the workflow above requires an operator to perform additional
configuration on the remote host to trust SSH certificates issued by
Infisical.
</Note>
## Guide to Configuring Infisical SSH
In the following steps, we explore how to configure Infisical SSH to start issuing SSH certificates to clients as well as a remote host to trust these certificates
as part of the SSH operation.
<Steps>
<Step title="Configuring Infisical SSH">
1.1. Start by creating a SSH project in the SSH tab of your organization.
![ssh project create](/images/platform/ssh/ssh-project.png)
1.2. Next, create a CA in the **Certificate Authorities** tab of the
project.
![ssh create ca](/images/platform/ssh/ssh-create-ca-1.png)
![ssh create ca popup](/images/platform/ssh/ssh-create-ca-2.png)
Here's some guidance on each field:
- Friendly Name: A friendly name for the CA; this is only for display.
- Key Algorithm: The type of public key algorithm and size, in bits, of the key pair for the CA. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.
1.3. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.
A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA.
With certificate templates, you can specify, for example, that certificates issued under a template are only allowed for users with a specific username like `ec2-user` or perhaps that the max TTL requested cannot exceed 1 year.
![ssh create template](/images/platform/ssh/ssh-create-template-1.png)
![ssh create template popup](/images/platform/ssh/ssh-create-template-2.png)
Here's some guidance on each field:
- SSH Template Name: A name for the certificate template; this must be a valid slug.
- Allowed Users: A comma-separated list of valid usernames (e.g. `ec2-user`) on the remote host for which a client can request a certificate for. If you wish to allow a client to request a certificate for any username, set this to `*`; alternatively, if left blank, the template will not allow issuance of certificates under any username.
- Allowed Hosts: A comma-separated list of valid hostnames/domains on the remote host for which a client can request a certificate for. Each item in the list can be either a wildcard hostname (e.g. `*.acme.com`), a specific hostname (e.g. `example.com`), an IPv4 address (e.g. `192.168.1.1`), or an IPv6 address. If left empty, the template will not allow any hostnames; if set to `*`, the template will allow any hostname.
- Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request.
- Max TTL: The maximum TTL for certificates issued under this template.
- Allow User Certificates: Whether or not to allow issuance of user certificates.
- Allow Host Certificates: Whether or not to allow issuance of host certificates.
- Allow Custom Key IDs: Whether or not to allow clients to specify a custom key ID to be included on the certificate as part of the certificate request.
1.4. Finally, add the user(s) you wish to be able to request a SSH certificate to the SSH project through the **Access Control** tab.
</Step>
<Step title="Configuring the remote host">
2.1. Begin by downloading the CA's public key from the CA's details section.
![ssh ca public key](/images/platform/ssh/ssh-ca-public-key.png)
<Note>
The CA's public key can also be retrieved programmatically via API by making a `GET` request to the `/ssh/ca/<ca-id>/public-key` endpoint.
</Note>
2.2. Next, create a file containing this public key in the SSH folder of the remote host; we'll call the file `ca.pub`.
This would result in the file at the path `/etc/ssh/ca.pub`.
2.3. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.
```bash
TrustedUserCAKeys /etc/ssh/ca.pub
PubkeyAcceptedKeyTypes=+ssh-rsa,[email protected]
```
2.4. Finally, reload the SSH daemon on the remote host to apply the changes.
```bash
sudo systemctl reload sshd
```
At this point, the remote host is configured to trust SSH certificates issued by the Infisical SSH CA.
</Step>
</Steps>
## Guide to Using Infisical SSH to Access a Host
We show how to obtain a SSH certificate and use it for a client to access a host via CLI:
<Note>
The subsequent guide assumes the following prerequisites:
- SSH Agent is running: The `ssh-agent` must be actively running on the host machine.
- OpenSSH is installed: The system should have OpenSSH installed; this includes
both the `ssh` client and `ssh-agent`.
- `SSH_AUTH_SOCK` environment variable
is set; the `SSH_AUTH_SOCK` variable should point to the UNIX socket that
`ssh-agent` uses for communication.
</Note>
<Steps>
<Step title="Authenticate with Infisical">
```bash
infisical login
```
</Step>
<Step title="Obtain a SSH certificate and load it into the SSH agent">
Run the `infisical ssh issue-credentials` command, specifying the `--addToAgent` flag to automatically load the SSH certificate into the SSH agent.
```bash
infisical ssh issue-credentials --certificateTemplateId=<certificate-template-id> --principals=<username> --addToAgent
```
Here's some guidance on each flag:
- `certificateTemplateId`: The ID of the certificate template to use for issuing the SSH certificate.
- `principals`: The comma-delimited username(s) or hostname(s) to include in the SSH certificate.
</Step>
<Step title="SSH into the host">
Finally, SSH into the desired host; the SSH operation will be performed using the SSH certificate loaded into the SSH agent.
```bash
ssh username@hostname
```
</Step>
</Steps>
<Note>
Note that the above workflow can be executed via API or other client methods
such as SDK.
</Note>
Binary file not shown.

After

Width:  |  Height:  |  Size: 957 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 957 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 598 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 584 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 306 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 311 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 584 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 974 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 586 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 580 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 974 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 352 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 974 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 562 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 665 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 597 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 277 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 665 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 430 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 698 KiB

+354
View File
@@ -0,0 +1,354 @@
---
title: "AWS Connection"
description: "Learn how to configure an AWS Connection for Infisical."
---
Infisical supports two methods for connecting to AWS.
<Tabs>
<Tab title="Assume Role (Recommended)">
Infisical will assume the provided role in your AWS account securely, without the need to share any credentials.
**Prerequisites:**
- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
<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.
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.
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**.
![Access Key Step 1](/images/integrations/aws/integrations-aws-access-key-1.png)
![Access Key Step 2](/images/integrations/aws/integrations-aws-access-key-2.png)
![Access Key Step 3](/images/integrations/aws/integrations-aws-access-key-3.png)
</Step>
<Step title="Set Up Connection Keys">
1. Set the access key as **INF_APP_CONNECTION_AWS_CLIENT_ID**.
2. Set the secret key as **INF_APP_CONNECTION_AWS_CLIENT_SECRET**.
</Step>
</Steps>
</Accordion>
<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.
![IAM Role Creation](/images/integrations/aws/integration-aws-iam-assume-role.png)
2. Select **AWS Account** as the **Trusted Entity Type**.
3. Choose **Another AWS Account** and enter **381492033652** (Infisical AWS Account ID). This restricts the role to be assumed only by Infisical. If self-hosting, provide your AWS account number instead.
4. Optionally, enable **Require external ID** and enter your **Organization ID** to further enhance security.
</Step>
<Step title="Add Required Permissions for the IAM Role">
Depending on your use case, add one or more of the following policies to your IAM Role:
<Tabs>
<Tab title="Secrets Sync">
<AccordionGroup>
<Accordion title="AWS Secrets Manager">
Use the following custom policy to grant the minimum permissions required by Infisical to sync secrets to AWS Secrets Manager:
![IAM Role Secrets Manager Permissions](/images/app-connections/aws/secrets-manager-permissions.png)
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSecretsManagerAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:CreateSecret",
"secretsmanager:UpdateSecret",
"secretsmanager:DescribeSecret",
"secretsmanager:TagResource",
"secretsmanager:UntagResource",
"kms:ListKeys",
"kms:ListAliases",
"kms:Encrypt",
"kms:Decrypt"
],
"Resource": "*"
}
]
}
```
</Accordion>
<Accordion title="AWS Parameter Store">
Use the following custom policy to grant the minimum permissions required by Infisical to sync secrets to AWS Parameter Store:
![IAM Role Secrets Manager Permissions](/images/app-connections/aws/parameter-store-permissions.png)
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSSMAccess",
"Effect": "Allow",
"Action": [
"ssm:PutParameter",
"ssm:DeleteParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath",
"ssm:DescribeParameters",
"ssm:DeleteParameters",
"ssm:AddTagsToResource", // if you need to add tags to secrets
"kms:ListKeys", // if you need to specify the KMS key
"kms:ListAliases", // if you need to specify the KMS key
"kms:Encrypt", // if you need to specify the KMS key
"kms:Decrypt" // if you need to specify the KMS key
],
"Resource": "*"
}
]
}
```
</Accordion>
</AccordionGroup>
</Tab>
</Tabs>
</Step>
<Step title="Copy the AWS IAM Role ARN">
![Copy IAM Role ARN](/images/integrations/aws/integration-aws-iam-assume-arn.png)
</Step>
<Step title="Setup AWS Connection in Infisical">
<Tabs>
<Tab title="Infisical UI">
1. Navigate to the App Connections tab on the Organization Settings page.
![App Connections Tab](/images/app-connections/general/add-connection.png)
2. Select the **AWS Connection** option.
![Select AWS Connection](/images/app-connections/aws/select-aws-connection.png)
3. Select the **Assume Role** method option and provide the **AWS IAM Role ARN** obtained from the previous step and press **Connect to AWS**.
![Create AWS Connection](/images/app-connections/aws/create-assume-role-method.png)
4. Your **AWS Connection** is now available for use.
![Assume Role AWS Connection](/images/app-connections/aws/assume-role-connection.png)
</Tab>
<Tab title="API">
To create an AWS Connection, make an API request to the [Create AWS
Connection](/api-reference/endpoints/app-connections/aws/create) API endpoint.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/app-connections/aws \
--header 'Content-Type: application/json' \
--data '{
"name": "my-aws-connection",
"method": "assume-role",
"credentials": {
"roleArn": "...",
}
}'
```
### Sample response
```bash Response
{
"appConnection": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "my-aws-connection",
"version": 123,
"orgId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"app": "aws",
"method": "assume-role",
"credentials": {}
}
}
```
</Tab>
</Tabs>
</Step>
</Steps>
</Tab>
<Tab title="Access Key">
Infisical will use the provided **Access Key ID** and **Secret Key** to connect to your AWS instance.
**Prerequisites:**
- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
<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.
![IAM Role Creation](/images/integrations/aws/integration-aws-iam-assume-role.png)
2. Select **AWS Account** as the **Trusted Entity Type**.
3. Choose **Another AWS Account** and enter **381492033652** (Infisical AWS Account ID). This restricts the role to be assumed only by Infisical. If self-hosting, provide your AWS account number instead.
4. Optionally, enable **Require external ID** and enter your **Organization ID** to further enhance security.
</Step>
<Step title="Add Required Permissions for the IAM Role">
Depending on your use case, add one or more of the following policies to your IAM Role:
<Tabs>
<Tab title="Secrets Sync">
<AccordionGroup>
<Accordion title="AWS Secrets Manager">
Use the following custom policy to grant the minimum permissions required by Infisical to sync secrets to AWS Secrets Manager:
![IAM Role Secrets Manager Permissions](/images/app-connections/aws/secrets-manager-permissions.png)
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSecretsManagerAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:CreateSecret",
"secretsmanager:UpdateSecret",
"secretsmanager:DescribeSecret",
"secretsmanager:TagResource",
"secretsmanager:UntagResource",
"kms:ListKeys",
"kms:ListAliases",
"kms:Encrypt",
"kms:Decrypt"
],
"Resource": "*"
}
]
}
```
</Accordion>
<Accordion title="AWS Parameter Store">
Use the following custom policy to grant the minimum permissions required by Infisical to sync secrets to AWS Parameter Store:
![IAM Role Secrets Manager Permissions](/images/app-connections/aws/parameter-store-permissions.png)
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowSSMAccess",
"Effect": "Allow",
"Action": [
"ssm:PutParameter",
"ssm:DeleteParameter",
"ssm:GetParameters",
"ssm:GetParametersByPath",
"ssm:DescribeParameters",
"ssm:DeleteParameters",
"ssm:AddTagsToResource", // if you need to add tags to secrets
"kms:ListKeys", // if you need to specify the KMS key
"kms:ListAliases", // if you need to specify the KMS key
"kms:Encrypt", // if you need to specify the KMS key
"kms:Decrypt" // if you need to specify the KMS key
],
"Resource": "*"
}
]
}
```
</Accordion>
</AccordionGroup>
</Tab>
</Tabs>
</Step>
<Step title="Obtain Access Key ID and Secret Access Key">
Retrieve an AWS **Access Key ID** and a **Secret Key** for your IAM user in **IAM > Users > User > Security credentials > Access keys**.
![access key 1](/images/integrations/aws/integrations-aws-access-key-1.png)
![access key 2](/images/integrations/aws/integrations-aws-access-key-2.png)
![access key 3](/images/integrations/aws/integrations-aws-access-key-3.png)
</Step>
<Step title="Setup AWS Connection in Infisical">
<Tabs>
<Tab title="Infisical UI">
1. Navigate to the App Connections tab on the Organization Settings page.
![App Connections Tab](/images/app-connections/general/add-connection.png)
2. Select the **AWS Connection** option.
![Select AWS Connection](/images/app-connections/aws/select-aws-connection.png)
3. Select the **Access Key** method option and provide the **Access Key ID** and **Secret Key** obtained from the previous step and press **Connect to AWS**.
![Create AWS Connection](/images/app-connections/aws/create-access-key-method.png)
4. Your **AWS Connection** is now available for use.
![Assume Role AWS Connection](/images/app-connections/aws/access-key-connection.png)
</Tab>
<Tab title="API">
To create an AWS Connection, make an API request to the [Create AWS
Connection](/api-reference/endpoints/app-connections/aws/create) API endpoint.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/app-connections/aws \
--header 'Content-Type: application/json' \
--data '{
"name": "my-aws-connection",
"method": "access-key",
"credentials": {
"accessKeyId": "...",
"secretKey": "..."
}
}'
```
### Sample response
```bash Response
{
"appConnection": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "my-aws-connection",
"version": 123,
"orgId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"app": "aws",
"method": "access-key",
"credentials": {
"accessKeyId": "..."
}
}
}
```
</Tab>
</Tabs>
</Step>
</Steps>
</Tab>
</Tabs>
@@ -0,0 +1,169 @@
---
title: "GitHub Connection"
description: "Learn how to configure a GitHub Connection for Infisical."
---
Infisical supports two methods for connecting to GitHub.
<Tabs>
<Tab title="GitHub App (Recommended)">
Infisical will use a GitHub App with finely grained permissions to connect to GitHub.
**Prerequisites:**
- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
<Accordion title="Self-Hosted Instance">
Using the GitHub integration with app authentication on a self-hosted instance of Infisical requires configuring an application on GitHub
and registering your instance with it.
<Steps>
<Step title="Create an application on GitHub">
Navigate to the GitHub app settings [here](https://github.com/settings/apps). Click **New GitHub App**.
![integrations github app create](/images/integrations/github/app/self-hosted-github-app-create.png)
Give the application a name, a homepage URL (your self-hosted domain i.e. `https://your-domain.com`), and a callback URL (i.e. `https://your-domain.com/app-connections/github/oauth/callback`).
![integrations github app basic details](/images/integrations/github/app/self-hosted-github-app-basic-details.png)
Enable request user authorization during app installation.
![integrations github app enable auth](/images/integrations/github/app/self-hosted-github-app-enable-oauth.png)
Disable webhook by unchecking the Active checkbox.
![integrations github app webhook](/images/integrations/github/app/self-hosted-github-app-webhook.png)
Set the repository permissions as follows: Metadata: Read-only, Secrets: Read and write, Environments: Read and write, Actions: Read.
![integrations github app repository](/images/integrations/github/app/self-hosted-github-app-repository.png)
Similarly, set the organization permissions as follows: Secrets: Read and write.
![integrations github app organization](/images/integrations/github/app/self-hosted-github-app-organization.png)
Create the Github application.
![integrations github app create confirm](/images/integrations/github/app/self-hosted-github-app-create-confirm.png)
<Note>
If you have a GitHub organization, you can create an application under it
in your organization Settings > Developer settings > GitHub Apps > New GitHub App.
</Note>
</Step>
<Step title="Add your application credentials to Infisical">
Generate a new **Client Secret** for your GitHub application.
![integrations github app create secret](/images/integrations/github/app/self-hosted-github-app-secret.png)
Generate a new **Private Key** for your Github application.
![integrations github app create private key](/images/integrations/github/app/self-hosted-github-app-private-key.png)
Obtain the necessary Github application credentials. This would be the application slug, client ID, app ID, client secret, and private key.
![integrations github app credentials](/images/integrations/github/app/self-hosted-github-app-credentials.png)
Back in your Infisical instance, add the five new environment variables for the credentials of your GitHub application:
- `INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID`: The **Client ID** of your GitHub application.
- `INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET`: The **Client Secret** of your GitHub application.
- `INF_APP_CONNECTION_GITHUB_APP_CLIENT_SLUG`: The **Slug** of your GitHub application. This is the one found in the URL.
- `INF_APP_CONNECTION_GITHUB_APP_CLIENT_APP_ID`: The **App ID** of your GitHub application.
- `INF_APP_CONNECTION_GITHUB_APP_CLIENT_PRIVATE_KEY`: The **Private Key** of your GitHub application.
Once added, restart your Infisical instance and use the GitHub integration via app authentication.
</Step>
</Steps>
</Accordion>
## Setup GitHub Connection in Infisical
<Steps>
<Step title="Navigate to the App Connections">
Navigate to the **App Connections** tab on the **Organization Settings** page.
![App Connections Tab](/images/app-connections/general/add-connection.png)
</Step>
<Step title="Add Connection">
Select the **GitHub Connection** option from the connection options modal.
![Select GitHub Connection](/images/app-connections/github/select-github-connection.png)
</Step>
<Step title="Authorize Connection">
Select the **GitHub App** method and click **Connect to GitHub**.
![Connect via GitHub App](/images/app-connections/github/create-github-app-method.png)
</Step>
<Step title="Install GitHub App">
You will then be redirected to the GitHub app installation page.
Install and authorize the GitHub application. This will redirect you back to Infisical's App Connections page.
![Install GitHub App](/images/app-connections/github/install-github-app.png)
</Step>
<Step title="Connection Created">
Your **GitHub Connection** is now available for use.
![Assume Role AWS Connection](/images/app-connections/github/github-app-connection.png)
</Step>
</Steps>
</Tab>
<Tab title="OAuth">
Infisical will use an OAuth App to connect to GitHub.
**Prerequisites:**
- Set up and add envars to [Infisical Cloud](https://app.infisical.com)
<Accordion title="Self-Hosted Instance">
Using the GitHub integration on a self-hosted instance of Infisical requires configuring an OAuth application in GitHub
and registering your instance with it.
<Steps>
<Step title="Create an OAuth application in GitHub">
Navigate to your user Settings > Developer settings > OAuth Apps to create a new GitHub OAuth application.
![integrations github config](../../images/integrations/github/integrations-github-config-settings.png)
![integrations github config](../../images/integrations/github/integrations-github-config-dev-settings.png)
![integrations github config](../../images/integrations/github/integrations-github-config-new-app.png)
Create the OAuth application. As part of the form, set the **Homepage URL** to your self-hosted domain `https://your-domain.com`
and the **Authorization callback URL** to `https://your-domain.com/app-connections/github/oauth/callback`.
![integrations github config](../../images/integrations/github/integrations-github-config-new-app-form.png)
<Note>
If you have a GitHub organization, you can create an OAuth application under it
in your organization Settings > Developer settings > OAuth Apps > New Org OAuth App.
</Note>
</Step>
<Step title="Add your OAuth application credentials to Infisical">
Obtain the **Client ID** and generate a new **Client Secret** for your GitHub OAuth application.
![integrations github config](../../images/integrations/github/integrations-github-config-credentials.png)
Back in your Infisical instance, add two new environment variables for the credentials of your GitHub OAuth application:
- `INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID`: The **Client ID** of your GitHub OAuth application.
- `INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET`: The **Client Secret** of your GitHub OAuth application.
Once added, restart your Infisical instance and use the GitHub integration.
</Step>
</Steps>
</Accordion>
## Setup GitHub Connection in Infisical
<Steps>
<Step title="Navigate to the App Connections">
Navigate to the **App Connections** tab on the **Organization Settings** page.
![App Connections Tab](/images/app-connections/general/add-connection.png)
</Step>
<Step title="Add Connection">
Select the **GitHub Connection** option from the connection options modal.
![Select GitHub Connection](/images/app-connections/github/select-github-connection.png)
</Step>
<Step title="Authorize Connection">
Select the **OAuth** method and click **Connect to GitHub**.
![Connect via GitHub App](/images/app-connections/github/create-oauth-method.png)
</Step>
<Step title="Grant Access">
You will then be redirected to the GitHub to grant Infisical access to your GitHub account (organization and repo privileges).
Once granted, you will redirect you back to Infisical's App Connections page.
![GitHub Authorization](/images/integrations/github/integrations-github-auth.png)
</Step>
<Step title="Connection Created">
Your **GitHub Connection** is now available for use.
![Assume Role AWS Connection](/images/app-connections/github/oauth-connection.png)
</Step>
</Steps>
</Tab>
</Tabs>
@@ -0,0 +1,77 @@
---
sidebarTitle: "Overview"
description: "Learn how to manage and configure third-party app connections with Infisical."
---
App Connections enable your organization to integrate Infisical with third-party services in a secure and versatile way.
## Concept
App Connections are an organization-level resource used to establish connections with third-party applications
that can be used across Infisical projects. Example use cases include syncing secrets, generating dynamic secrets, and more.
<br />
<div align="center">
```mermaid
%%{init: {'flowchart': {'curve': 'linear'} } }%%
graph TD
A[AWS]
B[AWS Connection]
C[Project 1 Secret Sync]
D[Project 2 Secret Sync]
E[Project 3 Generate Dynamic Secret]
B --> A
C --> B
D --> B
E --> B
classDef default fill:#ffffff,stroke:#666,stroke-width:2px,rx:10px,color:black
classDef aws fill:#FFF2B2,stroke:#E6C34A,stroke-width:2px,color:black,rx:15px
classDef project fill:#E6F4FF,stroke:#0096D6,stroke-width:2px,color:black,rx:15px
classDef connection fill:#F4FFE6,stroke:#96D600,stroke-width:2px,color:black,rx:15px
class A aws
class B connection
class C,D,E project
```
</div>
## Workflow
App Connections require initial setup in both your third-party application and Infisical. Follow these steps to establish a secure connection:
<Note>
For step-by-step guides specific to each application, refer to the App Connections section in the Navigation Bar.
</Note>
1. <strong>Create Access Entity:</strong> If necessary, create an entity such as a service account or role within the third-party application you want to connect to. Be sure
to limit the access of this entity to the minimal permission set required to perform the operations you need. For example:
- For secret syncing: Read/write permissions to specific secret stores
- For dynamic secrets: Permissions to create temporary credentials
<Tip>
Whenever possible, Infisical encourages creating a designated service account for your App Connection to limit the scope of permissions based on your use-case.
</Tip>
2. <strong>Generate Authentication Credentials:</strong> Obtain the required credentials from your third-party application. These can vary between applications and might be:
- an API key or access token
- A client ID and secret pair
- other credentials, etc.
3. <strong>Create App Connection:</strong> Configure the connection in Infisical using your generated credentials through either the UI or API.
<Info>
Some App Connections can only be created via the UI such as connections using OAuth.
</Info>
4. <strong>Utilize the Connection:</strong> Use your App Connection for various features across Infisical such as our Secrets Sync by selecting it via the dropdown menu
in the UI or by passing the associated `connectionId` when generating resources via the API.
<Note>
Infisical is continuously expanding its third-party application support. If your desired application isn't listed,
you can still use previous methods of connecting to it such as our Native Integrations.
</Note>
+70
View File
@@ -114,6 +114,7 @@
"documentation/platform/pki/alerting"
]
},
"documentation/platform/ssh",
{
"group": "Key Management (KMS)",
"pages": [
@@ -340,6 +341,14 @@
"cli/faq"
]
},
{
"group": "App Connections",
"pages": [
"integrations/app-connections/overview",
"integrations/app-connections/aws",
"integrations/app-connections/github"
]
},
{
"group": "Infrastructure Integrations",
"pages": [
@@ -756,6 +765,33 @@
"api-reference/endpoints/identity-specific-privilege/list"
]
},
{
"group": "App Connections",
"pages": [
"api-reference/endpoints/app-connections/list",
"api-reference/endpoints/app-connections/options",
{ "group": "AWS",
"pages": [
"api-reference/endpoints/app-connections/aws/list",
"api-reference/endpoints/app-connections/aws/get-by-id",
"api-reference/endpoints/app-connections/aws/get-by-name",
"api-reference/endpoints/app-connections/aws/create",
"api-reference/endpoints/app-connections/aws/update",
"api-reference/endpoints/app-connections/aws/delete"
]
},
{ "group": "GitHub",
"pages": [
"api-reference/endpoints/app-connections/github/list",
"api-reference/endpoints/app-connections/github/get-by-id",
"api-reference/endpoints/app-connections/github/get-by-name",
"api-reference/endpoints/app-connections/github/create",
"api-reference/endpoints/app-connections/github/update",
"api-reference/endpoints/app-connections/github/delete"
]
}
]
},
{
"group": "Integrations",
"pages": [
@@ -846,6 +882,40 @@
}
]
},
{
"group": "Infisical SSH",
"pages": [
{
"group": "Certificates",
"pages": [
"api-reference/endpoints/ssh/certificates/issue-credentials",
"api-reference/endpoints/ssh/certificates/sign-key"
]
},
{
"group": "Certificate Authorities",
"pages": [
"api-reference/endpoints/ssh/ca/list",
"api-reference/endpoints/ssh/ca/create",
"api-reference/endpoints/ssh/ca/read",
"api-reference/endpoints/ssh/ca/update",
"api-reference/endpoints/ssh/ca/delete",
"api-reference/endpoints/ssh/ca/public-key",
"api-reference/endpoints/ssh/ca/list-certificate-templates"
]
},
{
"group": "Certificate Templates",
"pages": [
"api-reference/endpoints/ssh/certificate-templates/list",
"api-reference/endpoints/ssh/certificate-templates/create",
"api-reference/endpoints/ssh/certificate-templates/read",
"api-reference/endpoints/ssh/certificate-templates/update",
"api-reference/endpoints/ssh/certificate-templates/delete"
]
}
]
},
{
"group": "Infisical KMS",
"pages": [
+48 -2
View File
@@ -418,7 +418,53 @@ When set, all visits to the Infisical login page will automatically redirect use
information.
</Accordion>
## Native secret integrations
## App Connections
You can configure third-party app connections for re-use across Infisical Projects.
<Accordion title="AWS Assume Role Connection">
<ParamField query="INF_APP_CONNECTION_AWS_ACCESS_KEY_ID" type="string" default="none" optional>
The AWS IAM User access key ID for assuming roles
</ParamField>
<ParamField query="INF_APP_CONNECTION_AWS_SECRET_ACCESS_KEY" type="string" default="none" optional>
The AWS IAM User secret key for assuming roles
</ParamField>
</Accordion>
<Accordion title="GitHub App Connection">
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_ID" type="string" default="none" optional>
The ID of the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_SLUG" type="string" default="none" optional>
The slug of the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_CLIENT_ID" type="string" default="none" optional>
The client ID for the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_CLIENT_SECRET" type="string" default="none" optional>
The client secret for the GitHub App
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_APP_PRIVATE_KEY" type="string" default="none" optional>
The private key for the GitHub App
</ParamField>
</Accordion>
<Accordion title="GitHub OAuth Connection">
<ParamField query="INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_ID" type="string" default="none" optional>
The OAuth2 client ID for GitHub OAuth Connection
</ParamField>
<ParamField query="INF_APP_CONNECTION_GITHUB_OAUTH_CLIENT_SECRET" type="string" default="none" optional>
The OAuth2 client secret for GitHub OAuth Connection
</ParamField>
</Accordion>
## Native Secret Integrations
To help you sync secrets from Infisical to services such as Github and Gitlab, Infisical provides native integrations out of the box.
@@ -492,7 +538,7 @@ To help you sync secrets from Infisical to services such as Github and Gitlab, I
</ParamField>
</Accordion>
<Accordion title="AWS">
<Accordion title="AWS Integration">
<ParamField query="CLIENT_ID_AWS_INTEGRATION" type="string" default="none" optional>
The AWS IAM User access key for assuming roles.
</ParamField>