mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-10 07:58:15 -05:00
Merge branch 'main' of https://github.com/Infisical/infisical into feat/octopus-deploy-secret-sync
This commit is contained in:
Piyush Gupta
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Get Certificate Request"
|
||||
openapi: "GET /api/v1/cert-manager/certificates/certificate-requests/{requestId}"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Issue Certificate"
|
||||
openapi: "POST /api/v1/cert-manager/certificates"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Add Machine Identity to Group"
|
||||
openapi: "POST /api/v1/groups/{id}/machine-identities/{machineIdentityId}"
|
||||
---
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "List Group Machine Identities"
|
||||
openapi: "GET /api/v1/groups/{id}/machine-identities"
|
||||
---
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: "List Group Members"
|
||||
openapi: "GET /api/v1/groups/{id}/members"
|
||||
---
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
title: "List Group Projects"
|
||||
openapi: "GET /api/v1/groups/{id}/projects"
|
||||
---
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: "Remove Machine Identity from Group"
|
||||
openapi: "DELETE /api/v1/groups/{id}/machine-identities/{machineIdentityId}"
|
||||
---
|
||||
203
docs/docs.json
203
docs/docs.json
@@ -664,7 +664,16 @@
|
||||
"group": "Concepts",
|
||||
"pages": [
|
||||
"documentation/platform/pki/concepts/certificate-mgmt",
|
||||
"documentation/platform/pki/concepts/certificate-lifecycle"
|
||||
"documentation/platform/pki/concepts/certificate-lifecycle",
|
||||
"documentation/platform/pki/concepts/certificate-components"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Guides",
|
||||
"pages": [
|
||||
"documentation/platform/pki/guides/request-cert-agent",
|
||||
"documentation/platform/pki/guides/request-cert-api",
|
||||
"documentation/platform/pki/guides/request-cert-acme"
|
||||
]
|
||||
}
|
||||
]
|
||||
@@ -704,6 +713,7 @@
|
||||
{
|
||||
"group": "Infrastructure Integrations",
|
||||
"pages": [
|
||||
"integrations/platforms/certificate-agent",
|
||||
"documentation/platform/pki/k8s-cert-manager",
|
||||
"documentation/platform/pki/integration-guides/gloo-mesh",
|
||||
"documentation/platform/pki/integration-guides/windows-server-acme",
|
||||
@@ -878,7 +888,12 @@
|
||||
"api-reference/endpoints/groups/get-by-id",
|
||||
"api-reference/endpoints/groups/add-group-user",
|
||||
"api-reference/endpoints/groups/remove-group-user",
|
||||
"api-reference/endpoints/groups/list-group-users"
|
||||
"api-reference/endpoints/groups/list-group-users",
|
||||
"api-reference/endpoints/groups/add-group-machine-identity",
|
||||
"api-reference/endpoints/groups/remove-group-machine-identity",
|
||||
"api-reference/endpoints/groups/list-group-machine-identities",
|
||||
"api-reference/endpoints/groups/list-group-projects",
|
||||
"api-reference/endpoints/groups/list-group-members"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -2508,7 +2523,7 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Infisical PKI",
|
||||
"group": "Certificate Management",
|
||||
"pages": [
|
||||
{
|
||||
"group": "Certificate Authorities",
|
||||
@@ -2547,6 +2562,8 @@
|
||||
"pages": [
|
||||
"api-reference/endpoints/certificates/list",
|
||||
"api-reference/endpoints/certificates/read",
|
||||
"api-reference/endpoints/certificates/certificate-request",
|
||||
"api-reference/endpoints/certificates/create-certificate",
|
||||
"api-reference/endpoints/certificates/renew",
|
||||
"api-reference/endpoints/certificates/update-config",
|
||||
"api-reference/endpoints/certificates/revoke",
|
||||
@@ -3096,6 +3113,186 @@
|
||||
{
|
||||
"source": "/documentation/platform/pki/est",
|
||||
"destination": "/documentation/platform/pki/enrollment-methods/est"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/create-auth",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/create",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/delete-auth-by-id",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/delete-auth",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/delete",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/find-auth",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/list-auth",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/list-project-integrations",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/endpoints/integrations/update",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/api-reference/overview/examples/integration",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/documentation/platform/integrations",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cicd/circleci",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cicd/codefresh",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cicd/octopus-deploy",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cicd/rundeck",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cicd/travisci",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/aws-parameter-store",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/aws-secret-manager",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/azure-app-configuration",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/azure-devops",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/azure-key-vault",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/checkly",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/cloud-66",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/cloudflare-pages",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/cloudflare-workers",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/databricks",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/digital-ocean-app-platform",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/flyio",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/gcp-secret-manager",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/hashicorp-vault",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/hasura-cloud",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/heroku",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/laravel-forge",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/netlify",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/northflank",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/qovery",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/railway",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/render",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/supabase",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/terraform-cloud",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/vercel",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/windmill",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/overview",
|
||||
"destination": "/integrations/secret-syncs"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/aws-amplify",
|
||||
"destination": "/integrations/cicd/aws-amplify"
|
||||
},
|
||||
{
|
||||
"source": "/integrations/cloud/teamcity",
|
||||
"destination": "/integrations/secret-syncs/teamcity"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,29 +1,29 @@
|
||||
---
|
||||
title: "User Groups"
|
||||
description: "Manage user groups in Infisical."
|
||||
title: "Groups"
|
||||
description: "Manage groups containing users and machine identities in Infisical."
|
||||
---
|
||||
|
||||
<Info>
|
||||
User Groups 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.
|
||||
Groups 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.
|
||||
</Info>
|
||||
|
||||
## Concept
|
||||
|
||||
A (user) group is a collection of users that you can create in an Infisical organization to more efficiently manage permissions and access control for multiple users together. For example, you can have a group called `Developers` with the `Developer` role containing all the developers in your organization.
|
||||
A group is a collection of identities (users and/or machine identities) that you can create in an Infisical organization to more efficiently manage permissions and access control for multiple identities together. For example, you can have a group called `Developers` with the `Developer` role containing all the developers in your organization, or a group called `CI/CD Identities` containing all the machine identities used in your CI/CD pipelines.
|
||||
|
||||
User groups have the following properties:
|
||||
Groups have the following properties:
|
||||
|
||||
- If a group is added to a project under specific role(s), all users in the group will be provisioned access to the project with the role(s). Conversely, if a group is removed from a project, all users in the group will lose access to the project.
|
||||
- If a user is added to a group, they will inherit the access control properties of the group including access to project(s) under the role(s) assigned to the group. Conversely, if a user is removed from a group, they will lose access to project(s) that the group has access to.
|
||||
- If a user was previously added to a project under a role and is later added to a group that has access to the same project under a different role, then the user will now have access to the project under the composite permissions of the two roles. If the group is subsequently removed from the project, the user will not lose access to the project as they were previously added to the project separately.
|
||||
- A user can be part of multiple groups. If a user is part of multiple groups, they will inherit the composite permissions of all the groups that they are part of.
|
||||
- If a group is added to a project under specific role(s), all identities in the group will be provisioned access to the project with the role(s). Conversely, if a group is removed from a project, all identities in the group will lose access to the project.
|
||||
- If an identity is added to a group, they will inherit the access control properties of the group including access to project(s) under the role(s) assigned to the group. Conversely, if an identity is removed from a group, they will lose access to project(s) that the group has access to.
|
||||
- If an identity was previously added to a project under a role and is later added to a group that has access to the same project under a different role, then the identity will now have access to the project under the composite permissions of the two roles. If the group is subsequently removed from the project, the identity will not lose access to the project as they were previously added to the project separately.
|
||||
- An identity can be part of multiple groups. If an identity is part of multiple groups, they will inherit the composite permissions of all the groups that they are part of.
|
||||
|
||||
## Workflow
|
||||
|
||||
In the following steps, we explore how to create and use user groups to provision user access to projects in Infisical.
|
||||
In the following steps, we explore how to create and use groups to provision access to projects in Infisical. Groups can contain both users and machine identities, and the workflow is the same for both types of identities.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating a group">
|
||||
@@ -32,36 +32,38 @@ In the following steps, we explore how to create and use user groups to provisio
|
||||
|
||||
|
||||
When creating a group, you specify an organization level [role](/documentation/platform/access-controls/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 group. Here’s some guidance for each field:
|
||||
- Name (required): A friendly name for the group like `Engineering`.
|
||||
- Slug (required): A unique identifier for the group like `engineering`.
|
||||
- Role (required): A role from the Organization Roles tab for the group to assume. The organization role assigned will determine what organization level resources this group can have access to.
|
||||
|
||||
</Step>
|
||||
<Step title="Adding users to the group">
|
||||
Next, you'll want to assign users to the group. To do this, press on the users icon on the group and start assigning users to the group.
|
||||
<Step title="Adding identities to the group">
|
||||
Next, you'll want to assign identities (users and/or machine identities) to the group. To do this, click on the group row to open the group details page and click on the **+** button.
|
||||
|
||||
|
||||
|
||||
|
||||
In this example, we're assigning **Alan Turing** and **Ada Lovelace** to the group **Engineering**.
|
||||
In this example, we're assigning **Alan Turing** and **Ada Lovelace** (users) to the group **Engineering**. You can similarly add machine identities to the group by selecting them from the **Machine Identities** tab in the modal.
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Adding the group to a project">
|
||||
To enable the group 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 group to and go to Project Settings > Access Control > Groups and press **Add group**.
|
||||
|
||||
To do this, head over to the project you want to add the group to and go to Project Settings > Access Control > Groups and press **Add Group to Project**.
|
||||
|
||||
|
||||
|
||||
|
||||
Next, select the group 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 group can have access to.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
That's it!
|
||||
|
||||
The users of the group now have access to the project under the role you assigned to the group.
|
||||
|
||||
All identities of the group now have access to the project under the role you assigned to the group.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Steps>
|
||||
|
||||
258
docs/documentation/platform/pam/resources/aws-iam.mdx
Normal file
258
docs/documentation/platform/pam/resources/aws-iam.mdx
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
title: "AWS IAM"
|
||||
sidebarTitle: "AWS IAM"
|
||||
description: "Learn how to configure AWS Management Console access through Infisical PAM for secure, audited, and just-in-time access to AWS."
|
||||
---
|
||||
|
||||
Infisical PAM supports secure, just-in-time access to the **AWS Management Console** through federated sign-in. This allows your team to access AWS without sharing long-lived credentials, while maintaining a complete audit trail of who accessed what and when.
|
||||
|
||||
## How It Works
|
||||
|
||||
Unlike database or SSH resources that require a Gateway for network connectivity, AWS Console access works differently. Infisical uses AWS STS (Security Token Service) to assume roles on your behalf and generates temporary federated sign-in URLs.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant Infisical
|
||||
participant Resource Role as Resource Role<br/>(Your AWS Account)
|
||||
participant Target Role as Target Role<br/>(Your AWS Account)
|
||||
participant Console as AWS Console
|
||||
|
||||
User->>Infisical: Request AWS Console access
|
||||
Infisical->>Resource Role: AssumeRole (with ExternalId)
|
||||
Resource Role-->>Infisical: Temporary credentials
|
||||
Infisical->>Target Role: AssumeRole (role chaining)
|
||||
Target Role-->>Infisical: Session credentials
|
||||
Infisical->>Console: Generate federation URL
|
||||
Console-->>Infisical: Signed console URL
|
||||
Infisical-->>User: Return console URL
|
||||
User->>Console: Open AWS Console (federated)
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
1. **Resource Role**: An IAM role in your AWS account that trusts Infisical. This is the "bridge" role that Infisical assumes first.
|
||||
|
||||
2. **Target Role**: The IAM role that end users will actually use in the AWS Console. The Resource Role assumes this role on behalf of the user.
|
||||
|
||||
3. **Role Chaining**: Infisical uses AWS role chaining - it first assumes the Resource Role, then uses those credentials to assume the Target Role. This provides an additional layer of security and audit capability.
|
||||
|
||||
4. **External ID**: A unique identifier (your Infisical Project ID) used in the trust policy to prevent [confused deputy attacks](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).
|
||||
|
||||
## Session Behavior
|
||||
|
||||
### Session Duration
|
||||
|
||||
The session duration is set when creating the account and applies to all access requests. You can specify the duration using human-readable formats like `15m`, `30m`, or `1h`. Due to AWS role chaining limitations:
|
||||
|
||||
- **Minimum**: 15 minutes (`15m`)
|
||||
- **Maximum**: 1 hour (`1h`)
|
||||
|
||||
### Session Tracking
|
||||
|
||||
Infisical tracks:
|
||||
- When the session was created
|
||||
- Who accessed which role
|
||||
- When the session expires
|
||||
|
||||
<Info>
|
||||
**Important**: AWS Console sessions cannot be terminated early. Once a federated URL is generated, the session remains valid until the configured duration expires. However, you can [revoke active sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html) by modifying the role's trust policy.
|
||||
</Info>
|
||||
|
||||
### CloudTrail Integration
|
||||
|
||||
All actions performed in the AWS Console are logged in [AWS CloudTrail](https://console.aws.amazon.com/cloudtrail). The session is identified by the `RoleSessionName`, which includes the user's email address for attribution:
|
||||
|
||||
```
|
||||
arn:aws:sts::123456789012:assumed-role/pam-readonly/user@example.com
|
||||
```
|
||||
|
||||
This allows you to correlate Infisical PAM sessions with CloudTrail logs for complete audit visibility.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring AWS Console access in Infisical PAM, you need to set up two IAM roles in your AWS account:
|
||||
|
||||
1. **Resource Role** - Trusted by Infisical, can assume target roles
|
||||
2. **Target Role(s)** - The actual roles users will use in the console
|
||||
|
||||
<Info>
|
||||
**No Gateway Required**: Unlike database or SSH resources, AWS Console access does not require an Infisical Gateway. Infisical communicates directly with AWS APIs.
|
||||
</Info>
|
||||
|
||||
## Create the PAM Resource
|
||||
|
||||
The PAM Resource represents the connection between Infisical and your AWS account. It contains the Resource Role that Infisical will assume.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the Resource Role Permissions Policy">
|
||||
First, create an IAM policy that allows the Resource Role to assume your target roles. For simplicity, you can use a wildcard to allow assuming any role in your account:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [{
|
||||
"Effect": "Allow",
|
||||
"Action": "sts:AssumeRole",
|
||||
"Resource": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/*"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
**For more granular control**: If you want to restrict which roles the Resource Role can assume, replace the wildcard (`/*`) with a more specific pattern. For example:
|
||||
- `arn:aws:iam::<YOUR_ACCOUNT_ID>:role/pam-*` to only allow roles with the `pam-` prefix
|
||||
- `arn:aws:iam::<YOUR_ACCOUNT_ID>:role/infisical-*` to only allow roles with the `infisical-` prefix
|
||||
|
||||
This allows you to limit the blast radius of the Resource Role's permissions.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Create the Resource Role with Trust Policy">
|
||||
Create an IAM role (e.g., `InfisicalResourceRole`) with:
|
||||
- The permissions policy from the previous step attached
|
||||
- The following trust policy:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"AWS": "arn:aws:iam::<INFISICAL_AWS_ACCOUNT_ID>:root"
|
||||
},
|
||||
"Action": "sts:AssumeRole",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"sts:ExternalId": "<YOUR_INFISICAL_PROJECT_ID>"
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<Warning>
|
||||
**Security Best Practice**: Always use the External ID condition. This prevents confused deputy attacks where another Infisical customer could potentially trick Infisical into assuming your role.
|
||||
</Warning>
|
||||
|
||||
**Infisical AWS Account IDs:**
|
||||
| Region | Account ID |
|
||||
|--------|------------|
|
||||
| US | `381492033652` |
|
||||
| EU | `345594589636` |
|
||||
|
||||
<Note>
|
||||
**For Dedicated Instances**: Your AWS account ID differs from the ones listed above. Please contact Infisical support to obtain your dedicated AWS account ID.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**For Self-Hosted Instances**: Use the AWS account ID where your Infisical instance is deployed. This is the account that hosts your Infisical infrastructure and will be assuming the Resource Role.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Create the Resource in Infisical">
|
||||
1. Navigate to your PAM project and go to the **Resources** tab
|
||||
2. Click **Add Resource** and select **AWS IAM**
|
||||
3. Enter a name for the resource (e.g., `production-aws`)
|
||||
4. Enter the **Resource Role ARN** - the ARN of the role you created in the previous step
|
||||
|
||||
|
||||
|
||||
Clicking **Create Resource** will validate that Infisical can assume the Resource Role. If the connection fails, verify:
|
||||
- The trust policy has the correct Infisical AWS account ID
|
||||
- The External ID matches your project ID
|
||||
- The role ARN is correct
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Create PAM Accounts
|
||||
|
||||
A PAM Account represents a specific Target Role that users can request access to. You can create multiple accounts per resource, each pointing to a different target role with different permission levels.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the Target Role Trust Policy">
|
||||
Each target role needs a trust policy that allows your Resource Role to assume it:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"AWS": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/InfisicalResourceRole"
|
||||
},
|
||||
"Action": "sts:AssumeRole",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"sts:ExternalId": "<YOUR_INFISICAL_PROJECT_ID>"
|
||||
}
|
||||
}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Create the Account in Infisical">
|
||||
1. Navigate to the **Accounts** tab in your PAM project
|
||||
2. Click **Add Account** and select the AWS IAM resource you created
|
||||
3. Fill in the account details:
|
||||
|
||||
|
||||
|
||||
<ParamField path="Name" type="string" required>
|
||||
A friendly name for this account (e.g., `readonly`, `admin`, `developer`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Description" type="string">
|
||||
Optional description of what this account is used for
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Target Role ARN" type="string" required>
|
||||
The ARN of the IAM role users will assume (e.g., `arn:aws:iam::123456789012:role/pam-readonly`)
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="Default Session Duration" type="string" required>
|
||||
Session duration using human-readable format (e.g., `15m`, `30m`, `1h`). Minimum 15 minutes, maximum 1 hour.
|
||||
|
||||
<Warning>
|
||||
Due to AWS role chaining limitations, the maximum session duration is **1 hour**, regardless of the target role's configured maximum session duration.
|
||||
</Warning>
|
||||
</ParamField>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Access the AWS Console
|
||||
|
||||
Once your resource and accounts are configured, users can request access through Infisical:
|
||||
|
||||
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Accounts">
|
||||
Go to the **Accounts** tab in your PAM project.
|
||||
</Step>
|
||||
|
||||
<Step title="Find the Account">
|
||||
Find the AWS Console account you want to access.
|
||||
</Step>
|
||||
|
||||
<Step title="Request Access">
|
||||
Click the **Access** button.
|
||||
|
||||
Infisical will:
|
||||
1. Assume the Resource Role using your project's External ID
|
||||
2. Assume the Target Role using role chaining
|
||||
3. Generate a federated sign-in URL
|
||||
4. Open the AWS Console in a new browser tab
|
||||
|
||||
The user will be signed into the AWS Console with the permissions of the Target Role.
|
||||
</Step>
|
||||
</Steps>
|
||||
224
docs/documentation/platform/pam/resources/kubernetes.mdx
Normal file
224
docs/documentation/platform/pam/resources/kubernetes.mdx
Normal file
@@ -0,0 +1,224 @@
|
||||
---
|
||||
title: "Kubernetes"
|
||||
sidebarTitle: "Kubernetes"
|
||||
description: "Learn how to configure Kubernetes cluster access through Infisical PAM for secure, audited, and just-in-time access to your Kubernetes clusters."
|
||||
---
|
||||
|
||||
Infisical PAM supports secure, just-in-time access to Kubernetes clusters through service account token authentication. This allows your team to access Kubernetes clusters without sharing long-lived credentials, while maintaining a complete audit trail of who accessed what and when.
|
||||
|
||||
## How It Works
|
||||
|
||||
Kubernetes access in Infisical PAM uses an Infisical Gateway to securely proxy connections to your Kubernetes API server. When a user requests access, Infisical generates a temporary kubeconfig that routes traffic through the Gateway, enabling secure access without exposing your cluster directly.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant CLI as Infisical CLI
|
||||
participant Infisical
|
||||
participant Gateway as Infisical Gateway
|
||||
participant K8s as Kubernetes API Server
|
||||
|
||||
User->>CLI: Request Kubernetes access
|
||||
CLI->>Infisical: Authenticate & request session
|
||||
Infisical-->>CLI: Session credentials & Gateway info
|
||||
CLI->>CLI: Start local proxy
|
||||
CLI->>Gateway: Establish secure tunnel
|
||||
User->>CLI: kubectl commands
|
||||
CLI->>Gateway: Proxy kubectl requests
|
||||
Gateway->>K8s: Forward with SA token
|
||||
K8s-->>Gateway: Response
|
||||
Gateway-->>CLI: Return response
|
||||
CLI-->>User: kubectl output
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
1. **Gateway**: An Infisical Gateway deployed in your network that can reach the Kubernetes API server. The Gateway handles secure communication between users and your cluster.
|
||||
|
||||
2. **Service Account Token**: A Kubernetes service account token that grants access to the cluster. This token is stored securely in Infisical and used by the Gateway to authenticate with the Kubernetes API.
|
||||
|
||||
3. **Local Proxy**: The Infisical CLI starts a local proxy on your machine that intercepts kubectl commands and routes them securely through the Gateway to your cluster.
|
||||
|
||||
4. **Session Tracking**: All access sessions are logged, including when the session was created, who accessed the cluster, session duration, and when it ended.
|
||||
|
||||
### Session Tracking
|
||||
|
||||
Infisical tracks:
|
||||
- When the session was created
|
||||
- Who accessed which cluster
|
||||
- Session duration
|
||||
- All kubectl commands executed during the session
|
||||
- When the session ended
|
||||
|
||||
<Info>
|
||||
**Session Logs**: After ending a session (by stopping the proxy), you can view detailed session logs in the Sessions page, including all commands executed during the session.
|
||||
</Info>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring Kubernetes access in Infisical PAM, you need:
|
||||
|
||||
1. **Infisical Gateway** - A Gateway deployed in your network with access to the Kubernetes API server
|
||||
2. **Service Account** - A Kubernetes service account with appropriate RBAC permissions
|
||||
3. **Infisical CLI** - The Infisical CLI installed on user machines
|
||||
|
||||
<Warning>
|
||||
**Gateway Required**: Unlike AWS Console access, Kubernetes access requires an Infisical Gateway to be deployed and registered with your Infisical instance. The Gateway must have network connectivity to your Kubernetes API server.
|
||||
</Warning>
|
||||
|
||||
## Create the PAM Resource
|
||||
|
||||
The PAM Resource represents the connection between Infisical and your Kubernetes cluster.
|
||||
|
||||
<Steps>
|
||||
<Step title="Ensure Gateway is Running">
|
||||
Before creating the resource, ensure you have an Infisical Gateway running and registered with your Infisical instance. The Gateway must have network access to your Kubernetes API server.
|
||||
</Step>
|
||||
|
||||
<Step title="Create the Resource in Infisical">
|
||||
1. Navigate to your PAM project and go to the **Resources** tab
|
||||
2. Click **Add Resource** and select **Kubernetes**
|
||||
3. Enter a name for the resource (e.g., `production-k8s`, `staging-cluster`)
|
||||
4. Enter the **Kubernetes API Server URL** - the URL to your Kubernetes API endpoint (e.g.`https://kubernetes.example.com:6443`)
|
||||
5. Select the **Gateway** that has access to this cluster
|
||||
6. Configure SSL verification options if needed
|
||||
|
||||
<Note>
|
||||
**SSL Verification**: You may need to disable SSL verification if your Kubernetes API server uses a self-signed certificate or if the certificate's hostname doesn't match the URL you're using to access it.
|
||||
</Note>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Create a Service Account
|
||||
|
||||
Infisical PAM currently supports service account token authentication for Kubernetes. You'll need to create a service account with appropriate permissions in your cluster.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the Service Account YAML">
|
||||
Create a file named `sa.yaml` with the following content:
|
||||
|
||||
```yaml sa.yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: infisical-pam-sa
|
||||
namespace: kube-system
|
||||
---
|
||||
# Bind the ServiceAccount to the desired ClusterRole
|
||||
# This example uses cluster-admin - adjust based on your needs
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRoleBinding
|
||||
metadata:
|
||||
name: infisical-pam-binding
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: infisical-pam-sa
|
||||
namespace: kube-system
|
||||
roleRef:
|
||||
kind: ClusterRole
|
||||
name: cluster-admin # Change this to a more restrictive role as needed
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
---
|
||||
# Create a static, non-expiring token for the ServiceAccount
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: infisical-pam-sa-token
|
||||
namespace: kube-system
|
||||
annotations:
|
||||
kubernetes.io/service-account.name: infisical-pam-sa
|
||||
type: kubernetes.io/service-account-token
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Security Best Practice**: The example above uses `cluster-admin` for simplicity. In production environments, you should create custom ClusterRoles or Roles with the minimum permissions required for each use case.
|
||||
</Warning>
|
||||
</Step>
|
||||
|
||||
<Step title="Apply the Service Account">
|
||||
Apply the configuration to your cluster:
|
||||
|
||||
```bash
|
||||
kubectl apply -f sa.yaml
|
||||
```
|
||||
|
||||
This creates:
|
||||
- A ServiceAccount named `infisical-pam-sa` in the `kube-system` namespace
|
||||
- A ClusterRoleBinding that grants the service account its permissions
|
||||
- A Secret containing a static, non-expiring token for the service account
|
||||
</Step>
|
||||
|
||||
<Step title="Retrieve the Service Account Token">
|
||||
Get the service account token that you'll use when creating the PAM account:
|
||||
|
||||
```bash
|
||||
kubectl -n kube-system get secret infisical-pam-sa-token -o jsonpath='{.data.token}' | base64 -d
|
||||
```
|
||||
|
||||
Copy this token - you'll need it in the next step.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Create PAM Accounts
|
||||
|
||||
Once you have configured the PAM resource, you'll need to configure a PAM account for your Kubernetes resource.
|
||||
A PAM Account represents a specific service account that users can request access to. You can create multiple accounts per resource, each with different permission levels.
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Accounts">
|
||||
Go to the **Accounts** tab in your PAM project.
|
||||
</Step>
|
||||
|
||||
<Step title="Add New Account">
|
||||
Click **Add Account** and select the Kubernetes resource you created.
|
||||
</Step>
|
||||
|
||||
<Step title="Fill in Account Details">
|
||||
Fill in the account details and paste the service account token you retrieved earlier.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Access Kubernetes Cluster
|
||||
|
||||
Once your resource and accounts are configured, users can request access through the Infisical CLI:
|
||||
|
||||
<Steps>
|
||||
<Step title="Get the Access Command">
|
||||
1. Navigate to the **Accounts** tab in your PAM project
|
||||
2. Find the Kubernetes account you want to access
|
||||
3. Click the **Access** button
|
||||
4. Copy the provided CLI command
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Run the Access Command">
|
||||
Run the copied command in your terminal.
|
||||
|
||||
The CLI will:
|
||||
1. Authenticate with Infisical
|
||||
2. Establish a secure connection through the Gateway
|
||||
3. Start a local proxy on your machine
|
||||
4. Configure kubectl to use the proxy
|
||||
</Step>
|
||||
|
||||
<Step title="Use kubectl">
|
||||
Once the proxy is running, you can use `kubectl` commands as normal:
|
||||
|
||||
```bash
|
||||
kubectl get pods
|
||||
kubectl get namespaces
|
||||
kubectl describe deployment my-app
|
||||
```
|
||||
|
||||
All commands are routed securely through the Infisical Gateway to your cluster.
|
||||
</Step>
|
||||
|
||||
<Step title="End the Session">
|
||||
When you're done, stop the proxy by pressing `Ctrl+C` in the terminal where it's running. This will:
|
||||
- Close the secure tunnel
|
||||
- End the session
|
||||
- Log the session details to Infisical
|
||||
|
||||
You can view session logs in the **Sessions** page of your PAM project.
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -1,401 +0,0 @@
|
||||
---
|
||||
title: "Certificates"
|
||||
sidebarTitle: "Certificates"
|
||||
description: "Learn how to issue X.509 certificates with Infisical."
|
||||
---
|
||||
|
||||
## Concept
|
||||
|
||||
Assuming that you've created a Private CA hierarchy with a root CA and an intermediate CA, you can now issue/revoke X.509 certificates using the intermediate CA.
|
||||
|
||||
<div align="center">
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Root CA]
|
||||
A --> B[Intermediate CA]
|
||||
A --> C[Intermediate CA]
|
||||
B --> D[Leaf Certificate]
|
||||
C --> E[Leaf Certificate]
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
## Workflow
|
||||
|
||||
The typical workflow for managing certificates consists of the following steps:
|
||||
|
||||
1. Issuing a certificate under an intermediate CA with details like name and validity period. As part of certificate issuance, you can either issue a certificate directly from a CA or do it via a certificate template.
|
||||
2. Managing certificate lifecycle events such as certificate renewal and revocation. As part of the certificate revocation flow,
|
||||
you can also query for a Certificate Revocation List [CRL](https://en.wikipedia.org/wiki/Certificate_revocation_list), a time-stamped, signed
|
||||
data structure issued by a CA containing a list of revoked certificates to check if a certificate has been revoked.
|
||||
|
||||
<Note>
|
||||
Note that this workflow can be executed via the Infisical UI or manually such
|
||||
as via API.
|
||||
</Note>
|
||||
|
||||
## Guide to Issuing Certificates
|
||||
|
||||
In the following steps, we explore how to issue a X.509 certificate under a CA.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Infisical UI">
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating a certificate template">
|
||||
A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA and can also be bound to a certificate collection for alerting such that any certificate issued under the template is automatically added to the collection.
|
||||
|
||||
With certificate templates, you can specify, for example, that issued certificates must have a common name (CN) adhering to a specific format like `.*.acme.com` or perhaps that the max TTL cannot be more than 1 year.
|
||||
|
||||
Head to your Project > Certificate Authorities > Your Issuing CA and create a certificate template.
|
||||
|
||||
|
||||
|
||||
Here's some guidance on each field:
|
||||
|
||||
- Template Name: A name for the certificate template.
|
||||
- Issuing CA: The Certificate Authority (CA) that will issue certificates based on this template.
|
||||
- Certificate Collection (Optional): The certificate collection that certificates should be added to when issued under the template.
|
||||
- Common Name (CN): A regular expression used to validate the common name in certificate requests.
|
||||
- Alternative Names (SANs): A regular expression used to validate subject alternative names in certificate requests.
|
||||
- TTL: The maximum Time-to-Live (TTL) for certificates issued using this template.
|
||||
- Key Usage: The key usage constraint or default value for certificates issued using this template.
|
||||
- Extended Key Usage: The extended key usage constraint or default value for certificates issued using this template.
|
||||
</Step>
|
||||
<Step title="Creating a certificate">
|
||||
To create a certificate, head to your Project > Internal PKI > Certificates and press **Issue** under the Certificates section.
|
||||
|
||||
|
||||
|
||||
Here, set the **Certificate Template** to the template from step 1 and fill out the rest of the details for the certificate to be issued.
|
||||
|
||||
|
||||
|
||||
Here's some guidance on each field:
|
||||
|
||||
- Friendly Name: A friendly name for the certificate; this is only for display and defaults to the common name of the certificate if left empty.
|
||||
- Common Name (CN): The common name for the certificate like `service.acme.com`.
|
||||
- Alternative Names (SANs): A comma-delimited list of Subject Alternative Names (SANs) for the certificate; these can be hostnames or email addresses like `app1.acme.com, app2.acme.com`.
|
||||
- TTL: The lifetime of the certificate in seconds.
|
||||
- Key Usage: The key usage extension of the certificate.
|
||||
- Extended Key Usage: The extended key usage extension of the certificate.
|
||||
|
||||
<Note>
|
||||
Note that Infisical PKI supports issuing certificates without certificate templates as well. If this is desired, then you can set the **Certificate Template** field to **None**
|
||||
and specify the **Issuing CA** and optional **Certificate Collection** fields; the rest of the fields for the issued certificate remain the same.
|
||||
|
||||
That said, we recommend using certificate templates to enforce policies and attach expiration monitoring on issued certificates.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Copying the certificate details">
|
||||
Once you have created the certificate from step 1, you'll be presented with the certificate details including the **Certificate Body**, **Certificate Chain**, and **Private Key**.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Make sure to download and store the **Private Key** in a secure location as it will only be displayed once at the time of certificate issuance.
|
||||
The **Certificate Body** and **Certificate Chain** will remain accessible and can be copied at any time.
|
||||
</Note>
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="API">
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating a certificate template">
|
||||
A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA and can also be bound to a certificate collection for alerting such that any certificate issued under the template is automatically added to the collection.
|
||||
|
||||
With certificate templates, you can specify, for example, that issued certificates must have a common name (CN) adhering to a specific format like .*.acme.com or perhaps that the max TTL cannot be more than 1 year.
|
||||
|
||||
To create a certificate template, make an API request to the [Create Certificate Template](/api-reference/endpoints/certificate-templates-v2/create) API endpoint, specifying the issuing CA.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --request POST \
|
||||
--url https://us.infisical.com/api/v2/certificate-templates \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"projectId": "<string>",
|
||||
"name": "<string>",
|
||||
"description": "<string>",
|
||||
"subject": [
|
||||
{
|
||||
"type": "common_name",
|
||||
"allowed": [
|
||||
"*.infisical.com"
|
||||
]
|
||||
}
|
||||
],
|
||||
"sans": [
|
||||
{
|
||||
"type": "dns_name",
|
||||
"allowed": [
|
||||
"*.sample.com"
|
||||
]
|
||||
}
|
||||
],
|
||||
"keyUsages": {
|
||||
"allowed": [
|
||||
"digital_signature"
|
||||
]
|
||||
},
|
||||
"extendedKeyUsages": {
|
||||
"allowed": [
|
||||
"client_auth"
|
||||
]
|
||||
},
|
||||
"algorithms": {
|
||||
"signature": [
|
||||
"SHA256-RSA"
|
||||
],
|
||||
"keyAlgorithm": [
|
||||
"RSA-2048"
|
||||
]
|
||||
},
|
||||
"validity": {
|
||||
"max": "365d"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
"certificateTemplate": {
|
||||
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"projectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
|
||||
"name": "<string>",
|
||||
"description": "<string>",
|
||||
"subject": [
|
||||
{
|
||||
"type": "common_name",
|
||||
"allowed": [
|
||||
"*.infisical.com"
|
||||
]
|
||||
}
|
||||
],
|
||||
"sans": [
|
||||
{
|
||||
"type": "dns_name",
|
||||
"allowed": [
|
||||
"*.sample.com"
|
||||
]
|
||||
}
|
||||
],
|
||||
"keyUsages": {
|
||||
"allowed": [
|
||||
"digital_signature"
|
||||
]
|
||||
},
|
||||
"extendedKeyUsages": {
|
||||
"allowed": [
|
||||
"client_auth"
|
||||
]
|
||||
},
|
||||
"algorithms": {
|
||||
"signature": [
|
||||
"SHA256-RSA"
|
||||
],
|
||||
"keyAlgorithm": [
|
||||
"RSA-2048"
|
||||
]
|
||||
},
|
||||
"validity": {
|
||||
"max": "365d"
|
||||
},
|
||||
"createdAt": "2023-11-07T05:31:56Z",
|
||||
"updatedAt": "2023-11-07T05:31:56Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Creating a certificate">
|
||||
To create a certificate under the certificate template, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/issue-certificate) API endpoint,
|
||||
specifying the issuing CA.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates/issue-certificate' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"profileId": "<profile-id>",
|
||||
"commonName": "service.acme.com",
|
||||
"ttl": "1y",
|
||||
"signatureAlgorithm": "RSA-SHA256",
|
||||
"keyAlgorithm": "RSA_2048"
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
certificate: "...",
|
||||
certificateChain: "...",
|
||||
issuingCaCertificate: "...",
|
||||
privateKey: "...",
|
||||
serialNumber: "..."
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Note that Infisical PKI supports issuing certificates without certificate templates as well. If this is desired, then you can set the **Certificate Template** field to **None**
|
||||
and specify the **Issuing CA** and optional **Certificate Collection** fields; the rest of the fields for the issued certificate remain the same.
|
||||
|
||||
That said, we recommend using certificate templates to enforce policies and attach expiration monitoring on issued certificates.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Make sure to store the `privateKey` as it is only returned once here at the time of certificate issuance. The `certificate` and `certificateChain` will remain accessible and can be retrieved at any time.
|
||||
</Note>
|
||||
|
||||
If you have an external private key, you can also create a certificate by making an API request containing a pem-encoded CSR (Certificate Signing Request) to the [Sign Certificate](/api-reference/endpoints/certificates/sign-certificate) API endpoint, specifying the issuing CA.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates/sign-certificate' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"certificateTemplateId": "<certificate-template-id>",
|
||||
"csr": "...",
|
||||
"ttl": "1y",
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
certificate: "...",
|
||||
certificateChain: "...",
|
||||
issuingCaCertificate: "...",
|
||||
privateKey: "...",
|
||||
serialNumber: "..."
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Guide to Revoking Certificates
|
||||
|
||||
In the following steps, we explore how to revoke a X.509 certificate under a CA and obtain a Certificate Revocation List (CRL) for a CA.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Infisical UI">
|
||||
<Steps>
|
||||
<Step title="Revoking a Certificate">
|
||||
Assuming that you've issued a certificate under a CA, you can revoke it by
|
||||
selecting the **Revoke Certificate** option for it and specifying the reason
|
||||
for revocation.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Obtaining a CRL">
|
||||
In order to check the revocation status of a certificate, you can check it
|
||||
against the CRL of a CA by heading to its Issuing CA and downloading the CRL.
|
||||
|
||||
|
||||
|
||||
To verify a certificate against the
|
||||
downloaded CRL with OpenSSL, you can use the following command:
|
||||
|
||||
```bash
|
||||
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
||||
```
|
||||
|
||||
Note that you can also obtain the CRL from the certificate itself by
|
||||
referencing the CRL distribution point extension on the certificate.
|
||||
|
||||
To check a certificate against the CRL distribution point specified within it with OpenSSL, you can use the following command:
|
||||
|
||||
```bash
|
||||
openssl verify -verbose -crl_check -crl_download -CAfile chain.pem cert.pem
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
<Tab title="API">
|
||||
<Steps>
|
||||
<Step title="Revoking a certificate">
|
||||
Assuming that you've issued a certificate under a CA, you can revoke it by making an API request to the [Revoke Certificate](/api-reference/endpoints/certificates/revoke) API endpoint,
|
||||
specifying the serial number of the certificate and the reason for revocation.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates/<cert-id>/revoke' \
|
||||
--header 'Authorization: Bearer <access-token>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"revocationReason": "UNSPECIFIED"
|
||||
}'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
{
|
||||
message: "Successfully revoked certificate",
|
||||
serialNumber: "...",
|
||||
revokedAt: "..."
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Obtaining a CRL">
|
||||
In order to check the revocation status of a certificate, you can check it against the CRL of the issuing CA.
|
||||
To obtain the CRLs of the CA, make an API request to the [List CRLs](/api-reference/endpoints/certificate-authorities/crl) API endpoint.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request GET 'https://app.infisical.com/api/v1/cert-manager/ca/internal/<ca-id>/crls' \
|
||||
--header 'Authorization: Bearer <access-token>'
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```bash Response
|
||||
[
|
||||
{
|
||||
id: "...",
|
||||
crl: "..."
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
To verify a certificate against the CRL with OpenSSL, you can use the following command:
|
||||
|
||||
```bash
|
||||
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## FAQ
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="What is the workflow for renewing a certificate?">
|
||||
To renew a certificate, you have to issue a new certificate from the same CA
|
||||
with the same common name as the old certificate. The original certificate
|
||||
will continue to be valid through its original TTL unless explicitly
|
||||
revoked.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@@ -29,13 +29,13 @@ Refer to the documentation for each [enrollment method](/documentation/platform/
|
||||
## Guide to Renewing Certificates
|
||||
|
||||
To [renew a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#renewal), you can either request a new certificate from a certificate profile or have the platform
|
||||
automatically request a new one for you. Whether you pursue a client-driven or server-driven approach is totally dependent on the enrollment method configured on your certificate
|
||||
automatically request a new one for you to be delivered downstream to a target destination. Whether you pursue a client-driven or server-driven approach is totally dependent on the enrollment method configured on your certificate
|
||||
profile as well as your infrastructure use-case.
|
||||
|
||||
### Client-Driven Certificate Renewal
|
||||
|
||||
Client-driven certificate renewal is when renewal is initiated client-side by the end-entity consuming the certificate.
|
||||
This is the most common approach to certificate renewal and is suitable for most use-cases.
|
||||
More specifically, the client (e.g. [Infisical Agent](/integrations/platforms/certificate-agent), [ACME client](https://letsencrypt.org/docs/client-options/), etc.) monitors the certificate and makes a request for Infisical to issue a new certificate back to it when the existing certificate is nearing expiration. This is the most common approach to certificate renewal and is suitable for most use-cases.
|
||||
|
||||
### Server-Driven Certificate Renewal
|
||||
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: "Certificate Components"
|
||||
description: "Learn the main components for managing certificates with Infisical."
|
||||
---
|
||||
|
||||
## Core Components
|
||||
|
||||
The following resources define how certificates are issued, shaped, and governed in Infisical:
|
||||
|
||||
- [Certificate Authority (CA)](/documentation/platform/pki/ca/overview): The trusted entity that issues X.509 certificates. This can be an [Internal CA](/documentation/platform/pki/ca/private-ca) or an [External CA](/documentation/platform/pki/ca/external-ca) in Infisical.
|
||||
The former represents a fully managed CA hierarchy within Infisical, while the latter represents an external CA (e.g. [DigiCert](/documentation/platform/pki/ca/digicert), [Let's Encrypt](/documentation/platform/pki/ca/lets-encrypt), [Microsoft AD CS](/documentation/platform/pki/ca/azure-adcs), etc.) that can be integrated with Infisical.
|
||||
|
||||
- [Certificate Template](/documentation/platform/pki/certificates/templates): A policy structure specifying permitted attributes for requested certificates. This includes constraints around subject naming conventions, SAN fields, key usages, and extended key usages.
|
||||
|
||||
- [Certificate Profile](/documentation/platform/pki/certificates/profiles): A configuration set specifying how leaf certificates should be issued for a group of end-entities including the issuing CA, a certificate template, and the enrollment method (e.g. [ACME](/documentation/platform/pki/enrollment-methods/acme), [EST](/documentation/platform/pki/enrollment-methods/est), [API](/documentation/platform/pki/enrollment-methods/api), etc.) used to enroll certificates.
|
||||
|
||||
- [Certificate](/documentation/platform/pki/certificates/certificates): The actual X.509 certificate issued for a profile. Once created, it is tracked in Infisical’s certificate inventory for management, renewal, and lifecycle operations.
|
||||
|
||||
## Access Control
|
||||
|
||||
Access control defines who (or what) can manage certificate resources and who can issue certificates within a project. Without clear boundaries, [certificate authorities](/documentation/platform/pki/ca/overview) and issuance workflows can be misconfigured or misused.
|
||||
|
||||
To manage access to certificates, you assign role-based permissions at the project level. These permissions determine which certificate authorities, certificate templates, certificate profiles, and other related resources a user or machine identity can act on. For example,
|
||||
you may want to:
|
||||
|
||||
- Have specific teams(s) manage your internal CA hierarchy or external CA integration configuration and have separate team(s) configure certificate profiles for requested certificates.
|
||||
- Limit which teams can manage policies defined on certificate templates.
|
||||
- Have specific end-entities (e.g. servers, devices, users) request certificates from specific certificate profiles.
|
||||
|
||||
This model follows the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) so that each user or machine identity can manage or issue only the certificate resources it is responsible for and nothing more.
|
||||
@@ -9,7 +9,7 @@ A (digital) _certificate_ is a file that is tied to a cryptographic key pair and
|
||||
|
||||
For example, when you visit a website over HTTPS, your browser checks the TLS certificate deployed on the web server or load balancer to make sure it’s really the site it claims to be. If the certificate is valid, your browser establishes an encrypted connection with the server.
|
||||
|
||||
Certificates contain information about the subject (who it identifies), the public key, and a digital signature from the CA that issued the certificate. They also include additional fields such as key usages, validity periods, and extensions that define how and where the certificate can be used. When a certificate expires, the service presenting it is no longer trusted, and clients won't be able to establish a secure connection to the service.
|
||||
Certificates contain information about the subject (who it identifies), the public key, and a digital signature from the Certificate Authority (CA) that issued the certificate. They also include additional fields such as key usages, validity periods, and extensions that define how and where the certificate can be used. When a certificate expires, the service presenting it is no longer trusted, and clients won't be able to establish a secure connection to the service.
|
||||
|
||||
## What is Certificate Management?
|
||||
|
||||
|
||||
@@ -6,7 +6,9 @@ sidebarTitle: "ACME"
|
||||
## Concept
|
||||
|
||||
The ACME enrollment method allows Infisical to act as an ACME server. It lets you request and manage certificates against a specific [certificate profile](/documentation/platform/pki/certificates/profiles) using the [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment).
|
||||
This method is suitable for web servers, load balancers, and other general-purpose servers that can run an [ACME client](https://letsencrypt.org/docs/client-options/) for automated certificate management.
|
||||
|
||||
This method is suitable for web servers, load balancers, and other general-purpose servers that can run an [ACME client](https://letsencrypt.org/docs/client-options/) for automated certificate management;
|
||||
it can also be used with [cert-manager](https://cert-manager.io/) to issue and renew certificates for Kubernetes workloads through the [ACME issuer type](https://cert-manager.io/docs/configuration/acme/).
|
||||
|
||||
Infisical's ACME enrollment method is based on [RFC 8555](https://datatracker.ietf.org/doc/html/rfc8555/).
|
||||
|
||||
@@ -26,6 +28,17 @@ In the following steps, we explore how to issue a X.509 certificate using the AC
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
|
||||
By default, when the ACME client requests a certificate against the certificate profile for a particular domain, Infisical will verify domain ownership using the [HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) method prior to issuing a certificate back to the client.
|
||||
|
||||
If you want Infisical to skip domain ownership validation entirely, you can enable the **Skip DNS Ownership Validation** checkbox.
|
||||
|
||||
Note that skipping domain ownership validation for the ACME enrollment method is **not the same** as skipping validation for an [External ACME CA integration](/documentation/platform/pki/ca/acme-ca).
|
||||
|
||||
When using the ACME enrollment, the domain ownership check occurring between the ACME client and Infisical can be skipped. In contrast, External ACME CA integrations always require domain ownership validation, as Infisical must complete a DNS-01 challenge with the upstream ACME-compatible CA.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Obtain the ACME configuration">
|
||||
Once you've created the certificate profile, you can obtain its ACME configuration details by clicking the **Reveal ACME EAB** option on the profile.
|
||||
|
||||
@@ -100,32 +100,34 @@ Here, select the certificate profile from step 1 that will be used to issue the
|
||||
</Step>
|
||||
<Step title="Issue a certificate">
|
||||
|
||||
To issue a certificate against the certificate profile, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/issue-certificate) API endpoint.
|
||||
To issue a certificate against the certificate profile, make an API request to the [Issue Certificate](/api-reference/endpoints/certificates/create-certificate) API endpoint.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates/issue-certificate' \
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates' \
|
||||
--header 'Authorization: Bearer <access-token>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"profileId": "<certificate-profile-id>",
|
||||
"commonName": "service.acme.com",
|
||||
"ttl": "1y",
|
||||
"signatureAlgorithm": "RSA-SHA256",
|
||||
"keyAlgorithm": "RSA_2048",
|
||||
"keyUsages": ["digital_signature", "key_encipherment"],
|
||||
"extendedKeyUsages": ["server_auth"],
|
||||
"altNames": [
|
||||
{
|
||||
"type": "DNS",
|
||||
"value": "service.acme.com"
|
||||
},
|
||||
{
|
||||
"type": "DNS",
|
||||
"value": "www.service.acme.com"
|
||||
}
|
||||
]
|
||||
"attributes": {
|
||||
"commonName": "service.acme.com",
|
||||
"ttl": "1y",
|
||||
"signatureAlgorithm": "RSA-SHA256",
|
||||
"keyAlgorithm": "RSA_2048",
|
||||
"keyUsages": ["digital_signature", "key_encipherment"],
|
||||
"extendedKeyUsages": ["server_auth"],
|
||||
"altNames": [
|
||||
{
|
||||
"type": "DNS",
|
||||
"value": "service.acme.com"
|
||||
},
|
||||
{
|
||||
"type": "DNS",
|
||||
"value": "www.service.acme.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
@@ -133,31 +135,36 @@ Here, select the certificate profile from step 1 that will be used to issue the
|
||||
|
||||
```bash Response
|
||||
{
|
||||
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----",
|
||||
"serialNumber": "123456789012345678",
|
||||
"certificateId": "880h3456-e29b-41d4-a716-446655440003"
|
||||
"certificate": {
|
||||
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----",
|
||||
"serialNumber": "123456789012345678",
|
||||
"certificateId": "880h3456-e29b-41d4-a716-446655440003"
|
||||
},
|
||||
"certificateRequestId": "..."
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Make sure to store the `privateKey` as it is only returned once here at the time of certificate issuance. The `certificate` and `certificateChain` will remain accessible and can be retrieved at any time.
|
||||
Note: If the certificate is available to be issued immediately, the `certificate` field in the response will contain the certificate data. If issuance is delayed (for example, due to pending approval or additional processing), the `certificate` field will be `null` and you can use the `certificateRequestId` to poll for status or retrieve the certificate when it is ready using the [Get Certificate Request](/api-reference/endpoints/certificates/certificate-request) API endpoint.
|
||||
</Note>
|
||||
|
||||
If you have an external private key, you can also issue a certificate by making an API request containing a pem-encoded CSR (Certificate Signing Request) to the [Sign Certificate](/api-reference/endpoints/certificates/sign-certificate) API endpoint.
|
||||
If you have an external private key, you can also issue a certificate by making an API request containing a pem-encoded CSR (Certificate Signing Request) to the same [Issue Certificate](/api-reference/endpoints/certificates/create-certificate) API endpoint.
|
||||
|
||||
### Sample request
|
||||
|
||||
```bash Request
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates/sign-certificate' \
|
||||
curl --location --request POST 'https://app.infisical.com/api/v1/cert-manager/certificates' \
|
||||
--header 'Authorization: Bearer <access-token>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"profileId": "<certificate-profile-id>",
|
||||
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBE9oaW8...\n-----END CERTIFICATE REQUEST-----",
|
||||
"ttl": "1y"
|
||||
"attributes": {
|
||||
"ttl": "1y"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
@@ -165,11 +172,14 @@ Here, select the certificate profile from step 1 that will be used to issue the
|
||||
|
||||
```bash Response
|
||||
{
|
||||
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"serialNumber": "123456789012345679",
|
||||
"certificateId": "990i4567-e29b-41d4-a716-446655440004"
|
||||
"certificate": {
|
||||
"certificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"certificateChain": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"issuingCaCertificate": "-----BEGIN CERTIFICATE-----\nMIIEpDCCAowCCQD...\n-----END CERTIFICATE-----",
|
||||
"serialNumber": "123456789012345679",
|
||||
"certificateId": "990i4567-e29b-41d4-a716-446655440004"
|
||||
},
|
||||
"certificateRequestId": "..."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
108
docs/documentation/platform/pki/guides/request-cert-acme.mdx
Normal file
108
docs/documentation/platform/pki/guides/request-cert-acme.mdx
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: "Obtain a Certificate via ACME"
|
||||
---
|
||||
|
||||
import RequestCertSetup from "/snippets/documentation/platform/pki/guides/request-cert-setup.mdx";
|
||||
|
||||
The [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) lets any [ACME client](https://letsencrypt.org/docs/client-options/) obtain TLS certificates from Infisical using the [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment).
|
||||
This includes ACME clients like [Certbot](https://certbot.eff.org/), [cert-manager](https://cert-manager.io/) in Kubernetes using the [ACME issuer type](https://cert-manager.io/docs/configuration/acme/), and more.
|
||||
|
||||
Infisical currently supports the [HTTP-01 challenge type](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) for domain validation as part of the ACME enrollment method.
|
||||
|
||||
## Diagram
|
||||
|
||||
The following sequence diagram illustrates the certificate enrollment workflow for requesting a certificate via ACME from Infisical.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant ACME as ACME Client
|
||||
participant Infis as Infisical ACME Server
|
||||
participant Authz as HTTP-01 Challenge<br/>Validation Endpoint
|
||||
participant CA as CA<br/>(Internal or External)
|
||||
|
||||
Note over ACME: ACME Client discovers<br/>Infisical ACME Directory URL
|
||||
|
||||
ACME->>Infis: GET /directory
|
||||
Infis-->>ACME: Directory + nonce + endpoints
|
||||
|
||||
ACME->>Infis: HEAD /new-nonce
|
||||
Infis-->>ACME: Return nonce in Replay-Nonce header
|
||||
|
||||
ACME->>Infis: POST /new-account<br/>(contact, ToS agreed)
|
||||
Infis-->>ACME: Return account object
|
||||
|
||||
Note over ACME,Infis: Requesting a certificate
|
||||
|
||||
ACME->>Infis: POST /new-order<br/>(identifiers: DNS names)
|
||||
Infis-->>ACME: Return order<br/>with authorization URLs
|
||||
|
||||
loop For each authorization (one per DNS name)
|
||||
ACME->>Infis: POST /authorizations/:authzId
|
||||
Infis-->>ACME: Return HTTP-01 challenge<br/>(URL + token + keyAuth)
|
||||
|
||||
Note over ACME: Client must prove control<br/>over the domain via HTTP
|
||||
|
||||
ACME->>Authz: Provision challenge response<br/>at<br/>/.well-known/acme-challenge/<token>
|
||||
|
||||
ACME->>Infis: POST /authorizations/:authzId/challenges/:challengeId<br/>(trigger validation)
|
||||
|
||||
Infis->>Authz: HTTP GET /.well-known/acme-challenge/<token>
|
||||
Authz-->>Infis: Return keyAuth
|
||||
|
||||
Infis-->>ACME: Authorization = valid
|
||||
end
|
||||
|
||||
Note over Infis: All authorizations valid → ready to finalize
|
||||
|
||||
ACME->>ACME: Generate keypair locally<br/>and create CSR
|
||||
ACME->>Infis: POST /orders/:orderId/finalize<br/>(CSR)
|
||||
|
||||
Infis->>CA: Request certificate issuance<br/>(CSR)
|
||||
CA-->>Infis: Signed certificate (+ chain)
|
||||
|
||||
Infis-->>ACME: Return order with certificate URL<br/>(status: valid)
|
||||
|
||||
ACME->>Infis: POST /orders/:orderId/certificate
|
||||
Infis-->>ACME: Return certificate<br/>and certificate chain
|
||||
```
|
||||
|
||||
## Guide
|
||||
|
||||
In the following steps, we explore an end-to-end workflow for obtaining a certificate via ACME with Infisical.
|
||||
|
||||
<Steps>
|
||||
<RequestCertSetup />
|
||||
<Step title="Create a certificate profile">
|
||||
Next, follow the guide [here](/documentation/platform/pki/certificates/profiles#guide-to-creating-a-certificate-profile) to create a [certificate profile](/documentation/platform/pki/certificates/profiles)
|
||||
that will be referenced when requesting a certificate.
|
||||
|
||||
The certificate profile specifies which certificate template and issuing CA should be used to validate an incoming certificate request and issue a certificate;
|
||||
it also specifies the [enrollment method](/documentation/platform/pki/enrollment-methods/overview) for how certificates can be requested against this profile
|
||||
to begin with.
|
||||
|
||||
You should specify the certificate template from Step 2, the issuing CA from Step 1, and the **ACME** option in the **Enrollment Method** dropdown when creating the certificate profile.
|
||||
|
||||
</Step>
|
||||
<Step title="Request a certificate">
|
||||
Finally, follow the guide [here](/documentation/platform/pki/enrollment-methods/acme#guide-to-certificate-enrollment-via-acme) to request a certificate against the certificate profile
|
||||
using an [ACME client](https://letsencrypt.org/docs/client-options/).
|
||||
|
||||
The ACME client will connect to Infisical's ACME server at the **ACME Directory URL** and authenticate using the **EAB Key Identifier (KID)** and **EAB Secret** credentials as part of the ACME protocol.
|
||||
|
||||
The typical ACME workflow looks likes this:
|
||||
|
||||
- The ACME client creates (or reuses) an ACME account with Infisical using EAB credentials.
|
||||
- The ACME client creates an order for one or more DNS names.
|
||||
- For each DNS name, the ACME client receives an `HTTP-01` challenge and provisions the corresponding token response at `/.well-known/acme-challenge/<token>`.
|
||||
- Once all authorizations are valid, the ACME client finalizes the order by sending a CSR to Infisical.
|
||||
- Infisical issues the certificate from the issuing CA on the certificate profile and returns it (plus the chain) back to the ACME client.
|
||||
|
||||
ACME clients typically handle renewal by tracking certificate expiration and completing the lifecycle once again to request a new certificate.
|
||||
|
||||
<Note>
|
||||
We recommend reading more about the ACME protocol [here](https://letsencrypt.org/how-it-works/).
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: "Request a Certificate via the Infisical Agent"
|
||||
---
|
||||
|
||||
import RequestCertSetup from "/snippets/documentation/platform/pki/guides/request-cert-setup.mdx";
|
||||
|
||||
The [Infisical Agent](/integrations/platforms/certificate-agent) is an installable client daemon that can request TLS and other X.509 certificates from Infisical using the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles), persist it to a specified path on the filesystem, and automatically monitor and renew it before expiration.
|
||||
|
||||
Instead of [manually requesting](/documentation/platform/pki/guides/request-cert-api) and renewing a certificate via the [Issue Certificate](/api-reference/endpoints/certificates/create-certificate) API endpoint, you can install and launch the Infisical Agent to have it perform these steps for you automatically.
|
||||
|
||||
## Diagram
|
||||
|
||||
The following sequence diagram illustrates the certificate enrollment workflow for requesting a certificate using the Infisical Agent from Infisical.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Agent as Infisical Agent
|
||||
participant Infis as Infisical
|
||||
participant CA as CA<br/>(Internal or External)
|
||||
|
||||
Agent->>Infis: Request certificate<br/>(profileId, conditional subject/SANs, ttl,<br/>key usages, conditional CSR, etc.)
|
||||
|
||||
Infis->>Infis: Look up certificate profile<br/>(by profileId)
|
||||
Infis->>Infis: Validate request<br/>against profile constraints<br/>(CN/SAN rules, key usages, max TTL, etc.)
|
||||
|
||||
alt Issuer Type = Self-Signed
|
||||
Infis->>Infis: Generate keypair<br/>and self-sign certificate
|
||||
else Issuer Type = Internal CA
|
||||
Infis->>CA: Request certificate issuance
|
||||
CA-->>Infis: Signed certificate<br/>(+ chain)
|
||||
end
|
||||
|
||||
Infis-->>Agent: Return certificate, certificate chain,<br/>(and private key if server-generated)
|
||||
|
||||
Note over Agent: Persist certificate and begin lifecycle monitoring
|
||||
|
||||
loop Periodic certificate status check
|
||||
Agent->>Agent: Check certificate expiration<br/>against renew-before-expiry threshold
|
||||
|
||||
alt Renewal not required
|
||||
Agent-->>Agent: Continue monitoring
|
||||
else Renewal required
|
||||
Agent->>Infis: Request new certificate<br/>(same profile and constraints)
|
||||
|
||||
Infis->>Infis: Validate renewal request<br/>against profile constraints
|
||||
|
||||
alt Issuer Type = Self-Signed
|
||||
Infis->>Infis: Generate keypair<br/>and self-sign certificate
|
||||
else Issuer Type = Internal CA
|
||||
Infis->>CA: Request certificate issuance
|
||||
CA-->>Infis: Signed certificate<br/>(+ chain)
|
||||
end
|
||||
|
||||
Infis-->>Agent: Return renewed certificate, certificate chain, and private key
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Guide
|
||||
|
||||
In the following steps, we explore an end-to-end workflow for requesting and continuously renewing a certificate using the Infisical Agent.
|
||||
|
||||
<Steps>
|
||||
<RequestCertSetup />
|
||||
<Step title="Create a certificate profile">
|
||||
Next, follow the guide [here](/documentation/platform/pki/certificates/profiles#guide-to-creating-a-certificate-profile) to create a [certificate profile](/documentation/platform/pki/certificates/profiles)
|
||||
that will be referenced when requesting a certificate.
|
||||
|
||||
The certificate profile specifies which certificate template and issuing CA should be used to validate an incoming certificate request and issue a certificate;
|
||||
it also specifies the [enrollment method](/documentation/platform/pki/enrollment-methods/overview) for how certificates can be requested against this profile
|
||||
to begin with.
|
||||
|
||||
You should specify the certificate template from Step 2, the issuing CA from Step 1, and the **API** option in the **Enrollment Method** dropdown when creating the certificate profile.
|
||||
|
||||
<Note>
|
||||
Note that if you're looking to issue self-signed certificates, you should select the **Self-Signed** option in the **Issuer Type** dropdown when creating the certificate profile.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Request a certificate">
|
||||
Next, [install the Infisical CLI](/cli/overview) on the target machine you wish to request the certificate on and follow the documentation [here](/integrations/platforms/certificate-agent#operating-the-agent) to set up the Infisical Agent on it.
|
||||
|
||||
As part of the setup, you must create an [agent configuration file](/integrations/platforms/certificate-agent#agent-configuration) that specifies how the agent should authenticate with Infisical using a [machine identity](/documentation/platform/identities/machine-identities), the certificate profile it should request against (from Step 3), what kind of certificate to request, where to persist the certificate, and how it should be managed in terms of auto-renewal.
|
||||
|
||||
Finally, start the agent with that configuration file so it can start requesting and continuously renewing the certificate on your behalf using the command below:
|
||||
|
||||
```bash
|
||||
infisical cert-manager agent --config /path/to/your/agent-config.yaml
|
||||
```
|
||||
|
||||
The certificate, certificate chain, and private key will be persisted to the filesystem at the paths specified in the `file-output` section of the agent configuration file.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
79
docs/documentation/platform/pki/guides/request-cert-api.mdx
Normal file
79
docs/documentation/platform/pki/guides/request-cert-api.mdx
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Request a Certificate via API"
|
||||
---
|
||||
|
||||
import RequestCertSetup from "/snippets/documentation/platform/pki/guides/request-cert-setup.mdx";
|
||||
|
||||
The [API enrollment method](/documentation/platform/pki/enrollment-methods/api) lets you programmatically request TLS and other X.509 certificates from Infisical.
|
||||
|
||||
This is the most flexible way to request certificates from Infisical but requires you to implement certificate request and renewal logic on your own.
|
||||
For a more automated way to request certificates, we highly recommend you check out the guide for requesting certificates using the [Infisical Agent](/integrations/platforms/certificate-agent) [here](/documentation/platform/pki/guides/request-cert-agent).
|
||||
|
||||
## Diagram
|
||||
|
||||
The following sequence diagram illustrates the certificate issuance workflow for requesting a certificate via API from Infisical.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Client as Client
|
||||
participant Infis as Infisical
|
||||
participant CA as CA<br/>(Internal or External)
|
||||
|
||||
Client->>Infis: POST /certificate<br/>(profileId, conditional subject/SANs, ttl,<br/>key usages, conditional CSR, etc.)
|
||||
|
||||
Infis->>Infis: Look up certificate profile<br/>(by profileId)
|
||||
Infis->>Infis: Validate request or CSR<br/>against profile constraints<br/>(CN/SAN rules, key usages, max TTL, etc.)
|
||||
|
||||
alt Issuer Type = Self-Signed
|
||||
Infis->>Infis: Generate keypair<br/>and self-sign certificate
|
||||
else Issuer Type = CA
|
||||
Infis->>CA: Request certificate issuance<br/>(CSR)
|
||||
CA-->>Infis: Signed certificate<br/>(+ chain)
|
||||
end
|
||||
|
||||
Infis-->>Client: Return certificate, certificate chain,<br/>issuing CA certificate, serial number,<br/>certificate ID<br/>(and private key if server-generated)<br /> OR certificate request ID if async
|
||||
```
|
||||
|
||||
## Guide
|
||||
|
||||
In the following steps, we explore an end-to-end workflow for requesting a certificate via API from Infisical.
|
||||
|
||||
<Steps>
|
||||
<RequestCertSetup />
|
||||
<Step title="Create a certificate profile">
|
||||
Next, follow the guide [here](/documentation/platform/pki/certificates/profiles#guide-to-creating-a-certificate-profile) to create a [certificate profile](/documentation/platform/pki/certificates/profiles)
|
||||
that will be referenced when requesting a certificate.
|
||||
|
||||
The certificate profile specifies which certificate template and issuing CA should be used to validate an incoming certificate request and issue a certificate;
|
||||
it also specifies the [enrollment method](/documentation/platform/pki/enrollment-methods/overview) for how certificates can be requested against this profile
|
||||
to begin with.
|
||||
|
||||
You should specify the certificate template from Step 2, the issuing CA from Step 1, and the **API** option in the **Enrollment Method** dropdown when creating the certificate profile.
|
||||
|
||||
<Note>
|
||||
Note that if you're looking to issue self-signed certificates, you should select the **Self-Signed** option in the **Issuer Type** dropdown when creating the certificate profile.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Request a certificate">
|
||||
Finally, follow the guide [here](/documentation/platform/pki/enrollment-methods/api#guide-to-certificate-enrollment-via-api) to request a certificate against the certificate profile
|
||||
over the Web UI or by making an API request the [Issue Certificate](/api-reference/endpoints/certificates/create-certificate) API endpoint with or without a certificate signing request (CSR).
|
||||
|
||||
To renew a certificate on the client-side, you have two options:
|
||||
|
||||
- Make a request to issue a new certificate against the same [Issue Certificate](/api-reference/endpoints/certificates/create-certificate) API endpoint.
|
||||
- Make a request to the [Renew Certificate](/api-reference/endpoints/certificates/renew) API endpoint with the ID of the certificate you wish to renew. Note that this endpoint only works if the original certificate was issued through the [Issue Certificate](/api-reference/endpoints/certificates/issue-certificate) API endpoint without a CSR.
|
||||
|
||||
<Note>
|
||||
We recommend reading the guide [here](/documentation/platform/pki/certificates/certificates#guide-to-renewing-certificates) to learn more about all the ways to renew a certificate
|
||||
with Infisical including [server-driven certificate renewal](/documentation/platform/pki/certificates/certificates#server-driven-certificate-renewal).
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Note that depending on your environment and infrastructure use-case, you may wish to use a different [enrollment method](/documentation/platform/pki/enrollment-methods/overview) to request certificates.
|
||||
|
||||
For more automated certificate management, you may wish to request certificates using a client that can monitor expiring certificates and request renewals for you.
|
||||
For example, you can install the Infisical Agent on a VM and have it request and renew certificates for you or use an [ACME client](https://letsencrypt.org/docs/client-options/) paired with Infisical's [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme).
|
||||
@@ -139,7 +139,7 @@ The following steps show how to install cert-manager (using `kubectl`) and obtai
|
||||
```
|
||||
|
||||
<Note>
|
||||
- Currently, the Infisical ACME server only supports the HTTP-01 challenge and requires successful challenge completion before issuing certificates. Support for optional challenges and DNS-01 is planned for a future release.
|
||||
- Currently, the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) only supports the [HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) method. Support for the [DNS-01 challenge](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) method is planned for a future release. If domain ownership validation is not desired, you can disable it by enabling the **Skip DNS ownership validation** option in your ACME certificate profile configuration.
|
||||
- An `Issuer` is namespace-scoped. Certificates can only be issued using an `Issuer` that exists in the same namespace as the `Certificate` resource.
|
||||
- If you need to issue certificates across multiple namespaces with a single resource, create a `ClusterIssuer` instead. The configuration is identical except `kind: ClusterIssuer` and no `metadata.namespace`.
|
||||
- More details: https://cert-manager.io/docs/configuration/acme/
|
||||
|
||||
BIN
docs/images/pam/resources/aws-iam/access-account.png
Normal file
BIN
docs/images/pam/resources/aws-iam/access-account.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
BIN
docs/images/pam/resources/aws-iam/create-account.png
Normal file
BIN
docs/images/pam/resources/aws-iam/create-account.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 129 KiB |
BIN
docs/images/pam/resources/aws-iam/create-resource.png
Normal file
BIN
docs/images/pam/resources/aws-iam/create-resource.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 143 KiB |
BIN
docs/images/pam/resources/aws-iam/resource-role-policy.png
Normal file
BIN
docs/images/pam/resources/aws-iam/resource-role-policy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
BIN
docs/images/pam/resources/aws-iam/resource-role-trust-policy.png
Normal file
BIN
docs/images/pam/resources/aws-iam/resource-role-trust-policy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 214 KiB |
BIN
docs/images/pam/resources/aws-iam/target-role-trust-policy.png
Normal file
BIN
docs/images/pam/resources/aws-iam/target-role-trust-policy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 213 KiB |
BIN
docs/images/platform/groups/group-details.png
Normal file
BIN
docs/images/platform/groups/group-details.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 221 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 378 KiB After Width: | Height: | Size: 184 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 431 KiB After Width: | Height: | Size: 237 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 636 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 626 KiB After Width: | Height: | Size: 198 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 371 KiB After Width: | Height: | Size: 185 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 615 KiB After Width: | Height: | Size: 203 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 313 KiB After Width: | Height: | Size: 154 KiB |
@@ -1,8 +0,0 @@
|
||||
---
|
||||
title: "TeamCity"
|
||||
description: "How to sync secrets from Infisical to TeamCity"
|
||||
---
|
||||
|
||||
<Note>
|
||||
The TeamCity Native Integration will be deprecated in 2026. Please migrate to our new [TeamCity Sync](../secret-syncs/teamcity).
|
||||
</Note>
|
||||
552
docs/integrations/platforms/certificate-agent.mdx
Normal file
552
docs/integrations/platforms/certificate-agent.mdx
Normal file
@@ -0,0 +1,552 @@
|
||||
---
|
||||
title: "Infisical Agent"
|
||||
sidebarTitle: "Infisical Agent"
|
||||
description: "Learn how to use Infisical CLI Agent to manage certificates automatically."
|
||||
---
|
||||
|
||||
## Concept
|
||||
|
||||
The Infisical Agent is a client daemon that is packaged into the [Infisical CLI](/cli/overview).
|
||||
It can be used to request a certificate from Infisical using the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles), persist it to a specified path on the filesystem, and automatically monitor and renew it before expiration.
|
||||
|
||||
The Infisical Agent is notable:
|
||||
|
||||
- Automating certificate management: The agent can request, persist, monitor, and renew certificates from Infisical automatically without manual intervention. It also supports post-event hooks to execute custom commands after certificate issuance, renewal, or failure events.
|
||||
- Leveraging workload identity: The agent can authenticate with Infisical as a [machine identity](/documentation/platform/identities/machine-identities) using an infrastructure-native authentication method such as [AWS Auth](/docs/documentation/platform/identities/aws-auth), [Azure Auth](/docs/documentation/platform/identities/azure-auth), [GCP Auth](/docs/documentation/platform/identities/gcp-auth), [Kubernetes Auth](/docs/documentation/platform/identities/kubernetes-auth), etc.
|
||||
|
||||
The typical workflow for using the agent involves installing the Infisical CLI on the target machine, creating a configuration file defining the certificate to request and how it should be managed, and then starting the agent with that configuration so it can request, persist, monitor, and renew the certificate before it expires.
|
||||
This follows a [client-driven approach](/documentation/platform/pki/certificates/certificates#client-driven-certificate-renewal) to certificate renewal.
|
||||
|
||||
## Workflow
|
||||
|
||||
A typical workflow for using the Infisical Agent to request certificates from Infisical consists of the following steps:
|
||||
|
||||
1. Create a [certificate profile](/documentation/platform/pki/certificates/profiles) in Infisical with the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) configured on it.
|
||||
2. Install the [Infisical CLI](/cli/overview) on the target machine.
|
||||
3. Create an agent [configuration file](/integrations/platforms/certificate-agent#agent-configuration) containing details about the certificate to request and how it should be managed such as renewal thresholds, post-event hooks, etc.
|
||||
4. Start the agent with that configuration so it can request, persist, monitor, and going forward automatically renew the certificate before it expires on the target machine.
|
||||
|
||||
## Operating the Agent
|
||||
|
||||
This section describes how to use the Infisical Agent to request certificates from Infisical. It covers how the agent authenticates with Infisical,
|
||||
and how to configure it to start requesting certificates from Infisical.
|
||||
|
||||
### Authentication
|
||||
|
||||
The Infisical Agent can authenticate with Infisical as a [machine identity](/documentation/platform/identities/machine-identities) using one of its supported authentication methods.
|
||||
|
||||
Upon successful authentication, the agent receives a short-lived access token that it uses to make subsequent authenticated requests to obtain and renew certificates from Infisical;
|
||||
the agent automatically handles token renewal as documented [here](/integrations/platforms/infisical-agent#token-renewal).
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Universal Auth">
|
||||
The Universal Auth method uses a client ID and secret for authentication.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a universal auth machine identity">
|
||||
To create a universal auth machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/universal-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Update the agent configuration file with the auth method and credentials:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "universal-auth"
|
||||
config:
|
||||
client-id: "./client-id" # Path to file containing client ID
|
||||
client-secret: "./client-secret" # Path to file containing client secret
|
||||
remove-client-secret-on-read: false # Optional: remove secret file after reading
|
||||
```
|
||||
|
||||
You can also provide credentials directly:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "universal-auth"
|
||||
config:
|
||||
client-id: "your-client-id"
|
||||
client-secret: "your-client-secret"
|
||||
```
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Kubernetes Auth">
|
||||
The Kubernetes Auth method is used when running the agent in a Kubernetes environment.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Kubernetes machine identity">
|
||||
To create a Kubernetes machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/kubernetes-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Configure the agent to use Kubernetes service account authentication:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "kubernetes-auth"
|
||||
config:
|
||||
identity-id: "your-kubernetes-identity-id"
|
||||
service-account-token-path: "/var/run/secrets/kubernetes.io/serviceaccount/token"
|
||||
```
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
</Accordion>
|
||||
<Accordion title="Azure Auth">
|
||||
The Azure Auth method is used when running the agent in an Azure environment.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create an Azure machine identity">
|
||||
To create an Azure machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/azure-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Configure the agent to use Azure managed identity authentication:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "azure-auth"
|
||||
config:
|
||||
identity-id: "your-azure-identity-id"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native GCP ID Token">
|
||||
The Native GCP ID Token method is used to authenticate with Infisical when running in a GCP environment.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a GCP machine identity">
|
||||
To create a GCP machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/gcp-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Update the agent configuration file with the specified auth method and identity ID:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "gcp-id-token"
|
||||
config:
|
||||
identity-id: "your-gcp-identity-id"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="GCP IAM">
|
||||
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a GCP machine identity">
|
||||
To create a GCP machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/gcp-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Update the agent configuration file with the specified auth method, identity ID, and service account key:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "gcp-iam"
|
||||
config:
|
||||
identity-id: "your-gcp-identity-id"
|
||||
service-account-key: "/path/to/service-account-key.json"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Native AWS IAM">
|
||||
The AWS IAM method is used to authenticate with Infisical with an AWS IAM role while running in an AWS environment.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create an AWS machine identity">
|
||||
To create an AWS machine identity, follow the step by step guide outlined [here](/documentation/platform/identities/aws-auth).
|
||||
</Step>
|
||||
<Step title="Configure the agent">
|
||||
Update the agent configuration file with the specified auth method and identity ID:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
type: "aws-iam"
|
||||
config:
|
||||
identity-id: "your-aws-identity-id"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Agent Configuration
|
||||
|
||||
The Infisical Agent relies on a YAML configuration file to define its behavior, including how it should authenticate with Infisical, the certificate it should request, and how that certificate should be managed including auto-renewal.
|
||||
|
||||
The code snippet below shows an example configuration file that instructs the agent to request and continuously renew a certificate from Infisical.
|
||||
|
||||
Note that not all configuration options in this file are required but this example includes all of the available options.
|
||||
|
||||
```yaml example-cert-agent-config.yaml
|
||||
version: v1
|
||||
|
||||
# Infisical server configuration
|
||||
infisical:
|
||||
address: "https://app.infisical.com" # The URL of the Infisical instance (e.g. https://app.infisical.com, https://eu.infisical.com, https://your-self-hosted-instance.com)
|
||||
retry-strategy:
|
||||
max-retries: 3
|
||||
max-delay: "5s"
|
||||
base-delay: "200ms"
|
||||
|
||||
# Infisical authentication configuration
|
||||
auth:
|
||||
type: "universal-auth" # The authentication method to use (e.g. universal-auth, kubernetes-auth, azure-auth, gcp-id-token, gcp-iam, aws-iam)
|
||||
config:
|
||||
client-id: "your-client-id"
|
||||
client-secret: "your-client-secret"
|
||||
|
||||
# Certificate configuration
|
||||
certificates:
|
||||
- profile-name: "prof-web-server-12345"
|
||||
project-slug: "my-project-slug"
|
||||
attributes:
|
||||
common-name: "api.example.com"
|
||||
alt-names: ["api.example.com", "api-v2.example.com"]
|
||||
ttl: "90d"
|
||||
key-algorithm: "RSA_2048"
|
||||
signature-algorithm: "RSA-SHA256"
|
||||
key-usages:
|
||||
- "digital_signature"
|
||||
- "key_encipherment"
|
||||
extended-key-usages:
|
||||
- "server_auth"
|
||||
|
||||
# Enable automatic certificate renewal
|
||||
lifecycle:
|
||||
renew-before-expiry: "30d"
|
||||
status-check-interval: "6h"
|
||||
|
||||
# Configure where to store the issued certificate and its associated private key and certificate chain
|
||||
file-output:
|
||||
private-key:
|
||||
path: "/etc/ssl/private/web.key"
|
||||
permission: "0600" # Read/write for owner only
|
||||
certificate:
|
||||
path: "/etc/ssl/certs/web.crt"
|
||||
permission: "0644" # Read for all, write for owner
|
||||
chain:
|
||||
path: "/etc/ssl/certs/web-chain.crt"
|
||||
permission: "0644" # Read for all, write for owner
|
||||
omit-root: true # Exclude the root CA certificate in chain
|
||||
|
||||
# Configure custom commands to execute after certificate issuance, renewal, or failure events
|
||||
post-hooks:
|
||||
on-issuance:
|
||||
command: |
|
||||
echo "Certificate issued for ${CERT_COMMON_NAME}"
|
||||
systemctl reload nginx
|
||||
timeout: 30
|
||||
|
||||
on-renewal:
|
||||
command: |
|
||||
echo "Certificate renewed for ${CERT_COMMON_NAME}"
|
||||
systemctl reload nginx
|
||||
timeout: 30
|
||||
|
||||
on-failure:
|
||||
command: |
|
||||
echo "Certificate operation failed: ${ERROR_MESSAGE}"
|
||||
mail -s "Certificate Alert" admin@company.com < /dev/null
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
To be more specific, the configuration file instructs the agent to:
|
||||
|
||||
- Authenticate with Infisical using the [Universal Auth](/integrations/platforms/certificate-agent#universal-auth) authentication method.
|
||||
- Request a 90-day certificate against the [certificate profile](/documentation/platform/pki/certificates/profiles) named `prof-web-server-12345` with the common name `web.company.com` and the subject alternative names `web.company.com` and `www.company.com`.
|
||||
- Automatically renew the certificate 30 days before expiration by checking the certificate status every 6 hours and retrying up to 3 times with a base delay of 200ms and a maximum delay of 5s if the certificate status check fails.
|
||||
- Store the certificate and its associated private key and certificate chain (excluding the root CA certificate) in the filesystem at the specified paths with the specified permissions.
|
||||
- Execute custom commands after certificate issuance, renewal, or failure events such as reloading an `nginx` service or sending an email notification.
|
||||
|
||||
### Agent Execution
|
||||
|
||||
After creating the configuration file, you can run the command below with the `--config` flag pointing to the path where the agent configuration file is located.
|
||||
|
||||
```bash
|
||||
infisical cert-manager agent --config /path/to/your/agent-config.yaml
|
||||
```
|
||||
|
||||
This will start the agent as a daemon process, continuously monitoring and managing certificates according to your configuration. You can also run it in the foreground for debugging:
|
||||
|
||||
```bash
|
||||
infisical cert-manager agent --config /path/to/your/agent-config.yaml --verbose
|
||||
```
|
||||
|
||||
For production deployments, you may consider running the agent as a system service to ensure it starts automatically and runs continuously.
|
||||
|
||||
### Agent Certificate Configuration Parameters
|
||||
|
||||
The table below provides a complete list of parameters that can be configured in the **certificate configuration** section of the agent configuration file:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
| ------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `profile-name` | Yes | The name of the [certificate profile](/documentation/platform/pki/certificates/profiles) to request a certificate against (e.g., `web-server-12345`) |
|
||||
| `project-slug` | Yes | The slug of the project to request a certificate against (e.g., `my-project-slug`) |
|
||||
| `common-name` | Optional | The common name for the certificate (e.g. `www.example.com`) |
|
||||
| `alt-names` | Optional | The list of subject alternative names for the certificate (e.g., `["www.example.com", "api.example.com"]`) |
|
||||
| `ttl` | Optional (uses profile default if not specified) | The time-to-live duration for the certificate, specified as a duration string (e.g. `72h`, `90d`, `1y`, etc.) |
|
||||
| `key-algorithm` | Optional | The algorithm for the certificate key pair. One of: `RSA_2048`, `RSA_3072`, `RSA_4096`, `EC_prime256v1`, `EC_secp384r1`, `EC_secp521r1`. |
|
||||
| `signature-algorithm` | Optional | The algorithm used to sign the certificate. One of: `RSA-SHA256`, `RSA-SHA384`, `RSA-SHA512`, `ECDSA-SHA256`, `ECDSA-SHA384`, `ECDSA-SHA512`. |
|
||||
| `key-usages` | Optional | The list of key usage values for the certificate. One or more of: `digital_signature`, `key_encipherment`, `non_repudiation`, `data_encipherment`, `key_agreement`, `key_cert_sign`, `crl_sign`, `encipher_only`, `decipher_only`. |
|
||||
| `extended-key-usages` | Optional | The list of extended key usage values for the certificate. One or more of: `server_auth`, `client_auth`, `code_signing`, `email_protection`, `timestamping`, `ocsp_signing`. |
|
||||
| `csr-path` | Conditional | The path to a certificate signing request (CSR) file (e.g., `./csr/webserver.csr`, `/etc/ssl/csr.pem`). This is required if using a pre-generated CSR. |
|
||||
| `file-output.private-key.path` | Optional (required if the `csr-path` is not specified) | The path to store the private key (required if not using a CSR) |
|
||||
| `file-output.private-key.permission` | Optional (defaults to `0600`) | The octal file permissions for the private key file (e.g. `0600`) |
|
||||
| `file-output.certificate.path` | Yes | The path to store the issued certificate in the filesystem |
|
||||
| `file-output.certificate.permission` | Optional (defaults to `0600`) | The octal file permissions for the certificate file (e.g. `0644`) |
|
||||
| `file-output.chain.path` | Optional | The path to store the certificate chain in the filesystem. |
|
||||
| `file-output.chain.permission` | Optional (defaults to `0600`) | The octal permissions for the chain file (e.g. `0644`) |
|
||||
| `file-output.chain.omit-root` | Optional (defaults to `true`) | Whether to exclude the root CA certificate from the returned certificate chain |
|
||||
| `lifecycle.renew-before-expiry` | Optional (auto-renewal is disabled if not set) | Duration before certificate expiration when renewal checks should begin, specified as a duration string (e.g. `72h`, `90d`, `1y`, etc.) |
|
||||
| `lifecycle.status-check-interval` | Optional (defaults to `10s`) | How frequently the agent checks certificate status and renewal needs, specified as a duration string (e.g. `10s`, `30m`, `1d`, etc.) |
|
||||
| `post-hooks.on-issuance.command` | Optional | The shell command to execute after a certificate is successfully issued for the first time (e.g., `systemctl reload nginx`, `/usr/local/bin/reload-service.sh`) |
|
||||
| `post-hooks.on-issuance.timeout` | Optional (defaults to `30`) | Maximum execution time in seconds for the on-issuance post-hook command before it is terminated (e.g., `30`, `60`, `120`) |
|
||||
| `post-hooks.on-renewal.command` | Optional | The shell command to execute after a certificate is successfully renewed (e.g., `systemctl reload nginx`, `docker restart web-server`) |
|
||||
| `post-hooks.on-renewal.timeout` | Optional (defaults to `30`) | Maximum execution time in seconds for the on-renewal post-hook command before it is terminated (e.g., `30`, `60`, `120`) |
|
||||
| `post-hooks.on-failure.command` | Optional | The shell command to execute when certificate issuance or renewal fails (e.g., `logger 'Certificate renewal failed'`, `/usr/local/bin/alert.sh`) |
|
||||
| `post-hooks.on-failure.timeout` | Optional (defaults to `30`) | Maximum execution time in seconds for the on-failure post-hook command before it is terminated (e.g., `10`, `30`, `60`) |
|
||||
|
||||
### Post-Event Hooks
|
||||
|
||||
The Infisical Agent supports running custom commands in response to certificate lifecycle events such as issuance, renewal, and failure through the `post-hooks` configuration
|
||||
in the agent configuration file.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Issuance Hook">
|
||||
Runs when a new certificate is successfully issued:
|
||||
|
||||
```yaml
|
||||
post-hooks:
|
||||
on-issuance:
|
||||
command: |
|
||||
echo "New certificate issued for ${CERT_COMMON_NAME}"
|
||||
chown nginx:nginx ${CERT_FILE_PATH}
|
||||
chmod 644 ${CERT_FILE_PATH}
|
||||
systemctl reload nginx
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Renewal Hook">
|
||||
Runs when a certificate is successfully renewed:
|
||||
|
||||
```yaml
|
||||
post-hooks:
|
||||
on-renewal:
|
||||
command: |
|
||||
echo "Certificate renewed for ${CERT_COMMON_NAME}"
|
||||
# Reload services that use the certificate
|
||||
systemctl reload nginx
|
||||
systemctl reload haproxy
|
||||
|
||||
# Send notification
|
||||
curl -X POST https://hooks.slack.com/... \
|
||||
-d "{'text': 'Certificate for ${CERT_COMMON_NAME} renewed successfully'}"
|
||||
timeout: 60
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Failure Hook">
|
||||
Runs when certificate operations fail:
|
||||
|
||||
```yaml
|
||||
post-hooks:
|
||||
on-failure:
|
||||
command: |
|
||||
echo "Certificate operation failed for ${CERT_COMMON_NAME}: ${ERROR_MESSAGE}"
|
||||
# Send alert
|
||||
mail -s "Certificate Failure Alert" admin@company.com < /dev/null
|
||||
# Log to syslog
|
||||
logger -p daemon.error "Certificate agent failure: ${ERROR_MESSAGE}"
|
||||
timeout: 30
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Retrying mechanism
|
||||
|
||||
The Infisical Agent will automatically attempt to retry any failed API requests including authentication, certificate issuance, and renewal operations.
|
||||
By default, the agent will retry up to 3 times with a base delay of 200ms and a maximum delay of 5s.
|
||||
|
||||
You can configure the retrying mechanism through the agent configuration file:
|
||||
|
||||
```yaml
|
||||
infisical:
|
||||
address: "https://app.infisical.com"
|
||||
retry-strategy:
|
||||
max-retries: 3
|
||||
max-delay: "5s"
|
||||
base-delay: "200ms"
|
||||
# ... rest of the agent configuration file
|
||||
```
|
||||
|
||||
## Example Agent Configuration Files
|
||||
|
||||
Since there are several ways you might want to use the Infisical Agent to request certificates from Infisical,
|
||||
we provide a few example configuration files for common use cases below to help you get started.
|
||||
|
||||
### One-Time Certificate Issuance
|
||||
|
||||
The code snippet below shows a configuration file that instructs the agent to request a certificate from Infisical
|
||||
once without performing any subsequent auto-renewal.
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
|
||||
# Infisical server configuration
|
||||
infisical:
|
||||
address: "https://app.infisical.com" # The URL of the Infisical instance (e.g. https://app.infisical.com, https://eu.infisical.com, https://your-self-hosted-instance.com)
|
||||
retry-strategy:
|
||||
max-retries: 3
|
||||
max-delay: "5s"
|
||||
base-delay: "200ms"
|
||||
|
||||
# Infisical authentication configuration
|
||||
auth:
|
||||
type: "universal-auth" # The authentication method to use (e.g. universal-auth, kubernetes-auth, azure-auth, gcp-id-token, gcp-iam, aws-iam)
|
||||
config:
|
||||
client-id: "your-client-id"
|
||||
client-secret: "your-client-secret"
|
||||
|
||||
# Certificate configuration
|
||||
certificates:
|
||||
- profile-name: "prof-web-server-12345"
|
||||
project-slug: "my-project-slug"
|
||||
attributes:
|
||||
common-name: "api.example.com"
|
||||
alt-names:
|
||||
- "api.example.com"
|
||||
- "api-v2.example.com"
|
||||
key-algorithm: "RSA_2048"
|
||||
signature-algorithm: "RSA-SHA256"
|
||||
key-usages:
|
||||
- "digital_signature"
|
||||
- "key_encipherment"
|
||||
extended-key-usages:
|
||||
- "server_auth"
|
||||
ttl: "30d"
|
||||
file-output:
|
||||
private-key:
|
||||
path: "/etc/ssl/private/api.example.com.key"
|
||||
permission: "0600"
|
||||
certificate:
|
||||
path: "/etc/ssl/certs/api.example.com.crt"
|
||||
permission: "0644"
|
||||
chain:
|
||||
path: "/etc/ssl/certs/api.example.com.chain.crt"
|
||||
permission: "0644"
|
||||
omit-root: true
|
||||
```
|
||||
|
||||
### One-Time Certificate Issuance using a Pre-Generated CSR
|
||||
|
||||
The code snippet below shows a configuration file that instructs the agent to request a certificate from Infisical
|
||||
once using a pre-generated CSR.
|
||||
|
||||
Note that when `csr-path` is specified:
|
||||
|
||||
- The `private-key` is omitted from the configuration file because we assume that it is pre-generated and managed externally, with only the CSR being submitted to Infisical for signing.
|
||||
- The agent will not be able to perform any auto-renewal operations, as it is assumed to not have access to the private key required to generate a new CSR.
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
|
||||
# Infisical server configuration
|
||||
infisical:
|
||||
address: "https://app.infisical.com" # The URL of the Infisical instance (e.g. https://app.infisical.com, https://eu.infisical.com, https://your-self-hosted-instance.com)
|
||||
retry-strategy:
|
||||
max-retries: 3
|
||||
max-delay: "5s"
|
||||
base-delay: "200ms"
|
||||
|
||||
# Infisical authentication configuration
|
||||
auth:
|
||||
type: "universal-auth" # The authentication method to use (e.g. universal-auth, kubernetes-auth, azure-auth, gcp-id-token, gcp-iam, aws-iam)
|
||||
config:
|
||||
client-id: "your-client-id"
|
||||
client-secret: "your-client-secret"
|
||||
|
||||
# Certificate configuration
|
||||
certificates:
|
||||
- profile-name: "prof-web-server-12345"
|
||||
project-slug: "my-project-slug"
|
||||
csr-path: "/etc/ssl/requests/api.csr"
|
||||
file-output:
|
||||
certificate:
|
||||
path: "/etc/ssl/certs/api.example.com.crt"
|
||||
permission: "0644"
|
||||
chain:
|
||||
path: "/etc/ssl/certs/api.example.com.chain.crt"
|
||||
permission: "0644"
|
||||
omit-root: true
|
||||
```
|
||||
|
||||
### Certificate Issuance with Automatic Renewal
|
||||
|
||||
The code snippet below shows a configuration file that instructs the agent to request a certificate from Infisical and continuously renew it 14 days before expiration, checking the certificate status every 6 hours.
|
||||
|
||||
```yaml
|
||||
version: v1
|
||||
|
||||
# Infisical server configuration
|
||||
infisical:
|
||||
address: "https://app.infisical.com" # The URL of the Infisical instance (e.g. https://app.infisical.com, https://eu.infisical.com, https://your-self-hosted-instance.com)
|
||||
retry-strategy:
|
||||
max-retries: 3
|
||||
max-delay: "5s"
|
||||
base-delay: "200ms"
|
||||
|
||||
# Infisical authentication configuration
|
||||
auth:
|
||||
type: "universal-auth" # The authentication method to use (e.g. universal-auth, kubernetes-auth, azure-auth, gcp-id-token, gcp-iam, aws-iam)
|
||||
config:
|
||||
client-id: "your-client-id"
|
||||
client-secret: "your-client-secret"
|
||||
|
||||
# Certificate configuration
|
||||
certificates:
|
||||
- profile-name: "prof-web-server-12345"
|
||||
project-slug: "my-project-slug"
|
||||
attributes:
|
||||
common-name: "api.example.com"
|
||||
alt-names:
|
||||
- "api.example.com"
|
||||
- "api-v2.example.com"
|
||||
key-algorithm: "RSA_2048"
|
||||
signature-algorithm: "RSA-SHA256"
|
||||
key-usages:
|
||||
- "digital_signature"
|
||||
- "key_encipherment"
|
||||
extended-key-usages:
|
||||
- "server_auth"
|
||||
ttl: "30d"
|
||||
lifecycle:
|
||||
renew-before-expiry: "14d" # Renew 14 days before expiration
|
||||
status-check-interval: "6h" # Check certificate status every 6 hours
|
||||
file-output:
|
||||
private-key:
|
||||
path: "/etc/ssl/private/api.example.com.key"
|
||||
permission: "0600"
|
||||
certificate:
|
||||
path: "/etc/ssl/certs/api.example.com.crt"
|
||||
permission: "0644"
|
||||
chain:
|
||||
path: "/etc/ssl/certs/api.example.com.chain.crt"
|
||||
permission: "0644"
|
||||
post-hooks:
|
||||
on-issuance:
|
||||
command: "systemctl reload nginx"
|
||||
timeout: 30
|
||||
on-renewal:
|
||||
command: "systemctl reload nginx && logger 'Certificate renewed'"
|
||||
timeout: 30
|
||||
```
|
||||
@@ -247,9 +247,9 @@ curl -X POST \
|
||||
"projectDescription": "A project created via API",
|
||||
"slug": "new-project-slug",
|
||||
"template": "default",
|
||||
"type": "SECRET_MANAGER"
|
||||
"type": "secret-manager"
|
||||
}' \
|
||||
https://your-infisical-instance.com/api/v2/projects
|
||||
https://your-infisical-instance.com/api/v1/projects
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
<Step title="Configure a Certificate Authority">
|
||||
Before you can issue any certificate, you must first configure a [Certificate Authority (CA)](/documentation/platform/pki/ca/overview).
|
||||
|
||||
The CA you configure will be used to issue the certificate back to your client; it can be either Internal or External:
|
||||
|
||||
- [Internal CA](/documentation/platform/pki/ca/private-ca): If you're building your own PKI and wish to issue certificates for internal use, you should
|
||||
follow the guide [here](/documentation/platform/pki/ca/private-ca#guide-to-creating-a-ca-hierarchy) to create at minimum a root CA and an intermediate/issuing CA
|
||||
within Infisical.
|
||||
|
||||
- [External CA](/documentation/platform/pki/ca/external-ca): If you have existing PKI infrastructure or wish to connect to a public CA (e.g. [Let's Encrypt](/documentation/platform/pki/ca/lets-encrypt), [DigiCert](/documentation/platform/pki/ca/digicert), etc.) to issue TLS certificates,
|
||||
you should follow the documentation [here](/documentation/platform/pki/ca/external-ca) to configure an External CA.
|
||||
|
||||
<Note>
|
||||
Note that if you're looking to issue self-signed certificates, you can skip this step and proceed to Step 3.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
<Step title="Create a certificate template">
|
||||
Next, follow the guide [here](/documentation/platform/pki/certificates/templates#guide-to-creating-a-certificate-template) to create a [certificate template](/documentation/platform/pki/certificates/templates).
|
||||
|
||||
The certificate template will constrain what attributes may or may not be allowed in the request to issue a certificate.
|
||||
For example, you can specify that the requested common name must adhere to a specific format like `*.acme.com` and
|
||||
that the maximum TTL cannot exceed 1 year.
|
||||
|
||||
If you're looking to issue TLS server certificates, you should select the **TLS Server Certificate** option under the **Template Preset** dropdown.
|
||||
|
||||
</Step>
|
||||
Reference in New Issue
Block a user