Autocert Settings
This reference covers all of Pomerium's Autocert Settings:
- Autocert
- Autocert CA
- Autocert Directory
- Autocert EAB Key ID
- Autocert EAB Mac Key
- Autocert Email
- Autocert Must Staple
- Autocert Trusted Certificate Authority
- Autocert Use Staging
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.
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
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert | AUTOCERT | boolean | optional |
autocert is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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.
If set, Autocert CA will override the Autocert Use Staging setting.
How to configure
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_ca | AUTOCERT_CA | string | optional |
autocert_ca is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_dir | AUTOCERT_DIR | string | optional |
Note: string must point to the path of the directory, or a URL to an S3 or GCS bucket.
autocert_dir is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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 |
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
- Core
- Enterprise
- Kubernetes
| 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.
autocert_eab_key_id is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide 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
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_eab_mac_key | AUTOCERT_EAB_MAC_KEY | string | optional |
autocert_eab_mac_key is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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.
The CA may contact you at this address when, for example, a certificate expires.
How to configure
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_email | AUTOCERT_EMAIL | string | optional |
autocert_email is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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.
The Autocert Must Staple setting will only take effect when you request or renew your certificates.
How to configure
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_must_staple | AUTOCERT_MUST_STAPLE | boolean | optional |
See RFC7633 for more information.
autocert_must_staple is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide 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
- Core
- Enterprise
- Kubernetes
| 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 |
autocert_trusted_ca and autocert_trusted_ca_file are bootstrap configuration settings and are not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
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
- Core
- Enterprise
- Kubernetes
| Config file keys | Environment variables | Type | Usage |
|---|---|---|---|
autocert_use_staging | AUTOCERT_USE_STAGING | boolean | optional |
autocert_use_staging is a bootstrap configuration setting and is not configurable in the Console.
Kubernetes users should not use Autocert. See the cert-manager's guide for more information.
Examples
# config file key
autocert_use_staging: true
# environment variable
AUTOCERT_USE_STAGING=true