Skip to main content

Autocert Settings

The Autocert settings configure Pomerium to manage public-facing TLS certificates automatically, by integrating with a certificate authority (CA) that supports the ACME protocol, such as Let's Encrypt.

Autocert can be useful in situations where Pomerium may not be behind a TLS-terminating ingress controller, proxy, or load balancer that manages TLS certificates on behalf of your upstream services. Certificates provisioned by Autocert provide also OCSP stapling.

You must use the Autocert Directory setting with Autocert to store and share certificate data between Pomerium services.

Autocert can incorporate also certificates set manually in the Pomerium configuration. These certificates will take precedence over generated certificates when applicable to configured routes.

Autocert support

The suite of Autocert settings listed below are supported only in Pomerium Core configurations. Here's what you should know about ACME support in other Pomerium products:

  • Pomerium Enterprise users should note that Autocert cannot be configured in the Enterprise Console or the Pomerium Enterprise configuration file. Autocert is a bootstrap setting, meaning it must be configured in Pomerium Core (either in a configuration file or as an environment variable) before running Pomerium Enterprise.

  • Kubernetes users should refer to the Cert-Manager integration section for more information on configuring automated certificate management in the Pomerium Ingress Controller.

  • Pomerium Zero users should note that Pomerium automatically manages certificates for starter domains and custom domains.

Autocert

The Autocert setting enables Pomerium to automatically retrieve, manage, and renew public-facing TLS certificates from the Autocert CA. Pomerium uses these certificates to secure Pomerium-managed route domains and the authenticate service. If you don't configure Autocert CA, Pomerium will use Let's Encrypt by default.

When requesting or renewing a certificate, Pomerium performs either the HTTP-01 or TLS-ALPN-01 challenge (the DNS-01 challenge is not supported):

  • The HTTP-01 challenge requires that you set up an HTTP redirect listener on port 80 (see HTTP Redirect Address).
  • The TLS-ALPN-01 challenge requires that the Address setting specifies port 443.
Let's Encrypt usage limits

If you use Let's Encrypt as your CA, you agree to the Let's Encrypt Subscriber Agreement. Let's Encrypt enforces strict usage limits per domain you should be aware of. Consider testing Autocert with autocert_use_staging first.

How to configure

Config file keysEnvironment variablesTypeUsage
autocertAUTOCERTbooleanoptional

Examples

autocert: true
AUTOCERT=TRUE

Autocert CA

Autocert CA is the directory URL of the ACME CA to use when requesting certificates.

note

If set, Autocert CA will override the Autocert Use Staging setting.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_caAUTOCERT_CAstringoptional

Examples

autocert_ca: https://acme.zerossl.com/v2/DV90
AUTOCERT_CA=https://acme.zerossl.com/v2/DV90

Autocert Directory

Autocert Directory is the path where Autocert stores X.509 certificate data.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_dirAUTOCERT_DIR*string** optional

* string must point to the directory path or URL of an S3 or GCS bucket.

** If you don't specify an Autocert directory, Pomerium will generate a directory by default based on your runtime environment. See Defaults for more information.

Examples

S3 bucket

An S3 bucket can be used as storage by using a URL like:

autocert_dir: s3://your-bucket.s3.us-east-1.amazonaws.com/some/prefix

Credentials are sourced from the environment.

GCS bucket

A Google Cloud Storage bucket can be used as storage by using a URL like:

autocert_dir: gs://your-bucket/some/prefix

Credentials are sourced from Google Application Default Credentials.

Defaults

Default pathsValue
Docker images/data/autocert
OS packages/etc/pomerium/ (Must be manually set with environmental variables.)
XDG base directories$XDG_DATA_HOME
Home directories$HOME/.local/share/pomerium

Autocert EAB Key ID

Autocert EAB Key ID is the key identifier when requesting a certificate from a CA with External Account Binding (EAB) enabled.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_eab_key_idAUTOCERT_EAB_KEY_IDstringoptional

See RFC8555-#7.3.4 for more information.

Examples

autocert_eab_key_id: EAB_KID
AUTOCERT_EAB_KEY_ID=EAB_KID

Autocert EAB MAC Key

Autocert EAB MAC Key is the base64-URL-encoded secret key corresponding to the Autocert EAB Key ID.

The Autocert EAB MAC Key setting is required when Autocert EAB Key ID is set.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_eab_mac_keyAUTOCERT_EAB_MAC_KEYstringoptional

Examples

autocert_eab_key_id: base64-URL-encoded_secret_key
AUTOCERT_EAB_KEY_ID=base64-URL-encoded_secret_key

Autocert Email

Autocert Email is the email address to use when requesting certificates from an ACME CA or registering an ACME account.

tip

The CA may contact you at this address when, for example, a certificate expires.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_emailAUTOCERT_EMAILstringoptional

Examples

autocert_email: example@domain.com
AUTOCERT_EMAIL=example@domain.com

Autocert Must Staple

If true, Autocert Must Staple forces Autocert to request a certificate with the status_request extension (commonly called Must-Staple).

This allows the TLS client (your browser) to fail immediately if the TLS handshake doesn't include OCSP stapling information.

This setting is only used when Autocert is set to true.

tip

The Autocert Must Staple setting will only take effect when you request or renew your certificates.

How to configure

Config file keysEnvironment variablesTypeUsageDefault
autocert_must_stapleAUTOCERT_MUST_STAPLEbooleanoptionalfalse

See RFC7633 for more information.

Examples

autocert_must_staple: true
AUTOCERT_MUST_STAPLE=true

Autocert Trusted Certificate Authority

Autocert Trusted Certificate Authority is the X.509 CA (bundle) used when communicating with a CA supporting the ACME protocol.

If not set, the system trusted roots will be used to verify TLS connections to the ACME CA.

How to configure

Config file keysEnvironment variablesTypeUsage
autocert_trusted_caAUTOCERT_TRUSTED_CAstringoptional
autocert_trusted_ca_fileAUTOCERT_TRUSTED_CA_FILEstringoptional

Examples

autocert_trusted_ca: base64-encoded-string
autocert_trusted_ca_file: /relative/file/location
AUTOCERT_TRUSTED_CA=base64-encoded-string
AUTOCERT_TRUSTED_CA_FILE=/relative/file/location

Autocert Use Staging

The Autocert Use Staging setting allows you to use Let's Encrypt's staging environment, which has more generous usage limits than the production environment. If you're testing or using Autocert in development, you should use the staging environment so that you don't exceed Let's Encrypt's rate limits.

How to configure

Config file keysEnvironment variablesTypeUsageDefault
autocert_use_stagingAUTOCERT_USE_STAGINGbooleanoptionalfalse

Examples

autocert_use_staging: true
AUTOCERT_USE_STAGING=true