​
Concept

The Infisical ACME integration allows you to connect with ACME (Automatic Certificate Management Environment) Certificate Authorities to automatically issue and manage publicly trusted TLS certificates for your subscribers. This integration enables you to leverage established public CA infrastructure like Let’s Encrypt while centralizing your certificate management within Infisical.

ACME is a protocol that automates the process of certificate issuance and renewal through domain validation challenges. The integration is perfect for obtaining trusted X.509 certificates for public-facing services and is capable of automatically renewing certificates as needed.

As part of the workflow, you configure DNS provider credentials, register an ACME CA provider with Infisical, and create subscribers to represent the certificates you wish to issue. Each issued certificate is automatically managed through its lifecycle, including renewal before expiration.

We recommend reading about ACME protocol and DNS-01 challenges for a fuller understanding of the underlying technology.

​
Workflow

A typical workflow for using Infisical with ACME Certificate Authorities consists of the following steps:

  1. Setting up AWS Route53 credentials with appropriate DNS permissions.
  2. Creating an AWS connection in Infisical to store the Route53 credentials.
  3. Registering an ACME Certificate Authority (like Let’s Encrypt) with Infisical.
  4. Creating subscribers that use the ACME CA as their issuing authority.
  5. Managing certificate lifecycle events such as issuance, renewal, and revocation through Infisical.

​
Understanding ACME DNS-01 Challenge

The DNS-01 challenge is the method used by ACME CA providers to verify that you control a domain before issuing a certificate. Here’s how Infisical handles this process:

  1. Challenge Request: When you request a certificate, the ACME provider (like Let’s Encrypt) issues a challenge token.

  2. DNS Record Creation: Infisical creates a TXT record at _acme-challenge.<YOUR_DOMAIN> with a value derived from the challenge token.

  3. DNS Propagation: The TXT record must propagate through the DNS system (usually takes a few minutes, depending on TTL settings).

  4. Validation: The ACME provider checks for the existence of this TXT record to verify domain control.

  5. Cleanup: After validation completes successfully, Infisical automatically removes the TXT record from your DNS.

This automated process eliminates the need for manual intervention in domain validation, streamlining certificate issuance.

​
Guide

In the following steps, we explore how to set up ACME Certificate Authority integration with Infisical using Let’s Encrypt as an example.

1

Set Up AWS Connection with Required Permissions

Before proceeding with the ACME CA registration, you need to set up an AWS connection with the appropriate permissions for DNS validation:

  1. Navigate to your Organization Settings > App Connections and create a new AWS connection.

  2. Ensure your AWS connection has the following minimum permissions for Route53 DNS validation:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "route53:GetChange",
      "Resource": "arn:aws:route53:::change/*"
    },
    {
      "Effect": "Allow",
      "Action": "route53:ListHostedZonesByName",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ListResourceRecordSets"
      ],
      "Resource": [
        "arn:aws:route53:::hostedzone/YOUR_HOSTED_ZONE_ID"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": [
        "arn:aws:route53:::hostedzone/YOUR_HOSTED_ZONE_ID"
      ],
      "Condition": {
        "ForAllValues:StringEquals": {
          "route53:ChangeResourceRecordSetsRecordTypes": [
            "TXT"
          ]
        }
      }
    }
  ]
}

Replace YOUR_HOSTED_ZONE_ID with your actual Route53 hosted zone ID.

For detailed instructions on setting up an AWS connection, see the AWS Connection documentation.

2

Register ACME Certificate Authority

1

Create ACME CA

To register an ACME CA, head to your Project > Internal PKI > Certificate Authorities and press the + button in the External Certificate Authorities section.

Fill out the details for the ACME CA registration:

Here’s guidance on each field:

  • Type: Select “ACME” as the External CA type.
  • Name: Enter a name for the ACME CA (e.g., “lets-encrypt-production”).
  • DNS App Connection: Select from available DNS app connections or configure a new one. This connection provides Infisical with the credentials needed to create and remove DNS records for ACME validation.
  • Hosted Zone ID: Enter your Route53 hosted zone ID (e.g., Z04044I124N1GOOMCOYX1) for the domain(s) you’ll be requesting certificates for.
  • Directory URL: Enter the ACME v2 directory URL for your chosen CA provider (e.g., https://acme-v02.api.letsencrypt.org/directory for Let’s Encrypt).
  • Account Email: Email address to associate with your ACME account. This email will receive important notifications about your certificates.
  • Enable Direct Issuance: Toggle on to allow direct certificate issuance without requiring subscribers.

Finally, press Create to register the ACME CA with Infisical.

2

Verify ACME CA Registration

Once registered, your ACME CA will appear in the External Certificate Authorities section.

From here, you can:

  • View the status of the ACME CA registration
  • Edit the configuration settings
  • Disable or re-enable the ACME CA
  • Delete the ACME CA registration if no longer needed

You can now use this ACME CA to issue certificates for your subscribers.

3

Create Subscriber for ACME CA

Next, create a subscriber that uses your ACME CA for certificate issuance. Navigate to your Project > Subscribers and create a new subscriber.

Configure the subscriber with:

  • Issuing CA: Select your registered ACME CA
  • Common Name: The domain for which you want to issue certificates (e.g., example.com)
  • Alternative Names: Additional domains to include in the certificate

Check out the Subscribers page for detailed instructions on creating and managing subscribers.

4

Issue Certificate

Once your subscriber is configured, you can issue certificates either through the Infisical UI or programmatically via the API.

When you request a certificate:

  1. Infisical generates a key pair for the certificate
  2. Sends a Certificate Signing Request (CSR) to the ACME CA
  3. Receives a DNS-01 challenge from the ACME provider
  4. Creates a TXT record in Route53 to satisfy the challenge
  5. Notifies the ACME provider that the challenge is ready for validation
  6. Once validated, the ACME provider issues the certificate
  7. Infisical stores and manages the certificate for your subscriber

The certificate will be automatically renewed before expiration according to your subscriber configuration.

5

Use Certificate in Your Applications

The issued certificate and private key are now available through Infisical and can be:

​
Example: Let’s Encrypt Integration

Let’s Encrypt is a free, automated, and open Certificate Authority that provides domain-validated SSL/TLS certificates. Here’s how the integration works with Infisical:

​
Production Environment

  • Directory URL: https://acme-v02.api.letsencrypt.org/directory
  • Rate Limits: 50 certificates per registered domain per week
  • Certificate Validity: 90 days with automatic renewal
  • Trusted By: All major browsers and operating systems

​
Staging Environment (for testing)

  • Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory
  • Rate Limits: Much higher limits for testing
  • Certificate Validity: 90 days (not trusted by browsers)
  • Use Case: Testing your ACME integration without hitting production rate limits

Always test your ACME integration using Let’s Encrypt’s staging environment first. This allows you to verify your DNS configuration and certificate issuance process without consuming your production rate limits.

​
FAQ