Skip to main content

Autocert Settings

This reference covers all of Pomerium's Autocert Settings:

Autocert​

Turning on Autocert allows Pomerium to automatically retrieve, manage, and renew public facing TLS Certificates from Let's Encrypt, which includes managed routes and the Authenticate Service.

You must use Autocert Directory with Autocert to store and share certificate data between services. (Note that Autocert also provides OCSP stapling.)

The Autocert setting can be useful in situations where you may not have Pomerium behind a TLS terminating ingress or proxy that is already handling your public certificates on your behalf.

Autocert will incorporate certificates available in the system trust store and certificates set manually in the Pomerium configuration, and they will take precedence over generated certificates when applicable to configured routes.

Autocert will attempt HTTP-01and TLS-ALPN-01 challenges. It does not support DNS-01 challenges, required to generate wildcard certificates.

Kubernetes users should not use Autocert. See the cert-manager's guide for more information.

warning

By using Autocert, you agree to the Let's Encrypt Subscriber Agreement. There are strict usage limits per domain you should be aware of. Consider testing with autocert_use_staging first.

Autocert requires that port 443 be accessible from the internet in order to complete a TLS-ALPN-01 challenge or port 80 in order to complete an HTTP-01 challenge (https://letsencrypt.org/docs/challenge-types/#tls-alpn-01).

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.

tip

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_DIRstringoptional

Note: string must point to the path of the directory, or a URL to an S3 or GCS bucket.

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 variablesTypeUsage
autocert_must_stapleAUTOCERT_MUST_STAPLEbooleanoptional

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​

Autocert Use Staging setting allows you to use Let's Encrypt's staging environment, which has more lenient usage limits than the production environment.

How to configure​

Config file keysEnvironment variablesTypeUsage
autocert_use_stagingAUTOCERT_USE_STAGINGbooleanoptional

Examples​

autocert_use_staging: true
AUTOCERT_USE_STAGING=true