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.
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.
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 keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert | AUTOCERT | boolean | optional |
Examples
autocert: true
AUTOCERT=TRUE
Autocert CA
Autocert CA is the directory URL of the ACME CA to use when requesting certificates.
If set, Autocert CA will override the Autocert Use Staging setting.
How to configure
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_ca | AUTOCERT_CA | string | optional |
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 keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_dir | AUTOCERT_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 paths | Value |
|---|---|
| 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 keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_eab_key_id | AUTOCERT_EAB_KEY_ID | string | optional |
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 keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_eab_mac_key | AUTOCERT_EAB_MAC_KEY | string | optional |
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.
The CA may contact you at this address when, for example, a certificate expires.
How to configure
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_email | AUTOCERT_EMAIL | string | optional |
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.
The Autocert Must Staple setting will only take effect when you request or renew your certificates.
How to configure
| Config file keys | Environment variables | Type | Usage | Default |
|---|---|---|---|---|
autocert_must_staple | AUTOCERT_MUST_STAPLE | boolean | optional | false |
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 keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_trusted_ca | AUTOCERT_TRUSTED_CA | string | optional |
autocert_trusted_ca_file | AUTOCERT_TRUSTED_CA_FILE | string | optional |
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 keys | Environment variables | Type | Usage | Default |
|---|---|---|---|---|
autocert_use_staging | AUTOCERT_USE_STAGING | boolean | optional | false |
Examples
autocert_use_staging: true
AUTOCERT_USE_STAGING=true