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.

danger

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

# config file key
autocert: true

# environment variable
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

# config file key
autocert_ca: https://acme.zerossl.com/v2/DV90

# environment variable
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.

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

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.

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

# config file key
autocert_eab_key_id: EAB_KID

# environment variable
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

# config file key
autocert_eab_key_id: base64-URL-encoded_secret_key

# environment variable
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

# config file key
autocert_email: example@domain.com

# environment variable
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

# config file key
autocert_must_staple: true

# environment variable
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

# config file key
autocert_trusted_ca: base64-encoded-string
autocert_trusted_ca_file: /relative/file/location

# environment variable
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

# config file key
autocert_use_staging: true

# environment variable
AUTOCERT_USE_STAGING=true