Skip to main content

Certificates Settings

This reference covers all of Pomerium's Certificates Settings:

Note

All certificates supplied to Pomerium must be in PEM format.

Certificates

Certificates are the X.509 public-key and private-key pair used to establish secure HTTP and gRPC connections. Any combination of these settings can be used together and are additive. You can also use any of these settings in conjunction with Autocert to get OCSP stapling.

Certificates loaded into Pomerium from these config values are used to attempt secure connections between end-users and services, between Pomerium services, and to upstream endpoints.

Note

Pomerium will check your system's trust/key store for valid certificates first. If your certificate solution imports into the system store, you don't need to also specify them with these configuration keys.

How to configure

Config file keysEnvironment variablesTypeUsage
certificatesNot settable as environment variablestring (Array of relative file locations for multiple certificates)required (if insecure not set)
certificate and certificate_keyCERTIFICATE and CERTIFICATE_KEYstring (base64-encoded string)required (if insecure not set)
certificate_file and certificate_key_fileCERTIFICATE_FILE and CERTIFICATE_KEY_FILEstring (Relative file location for a single certificate)required (if insecure not set)

Examples

Specify multiple certificates at once:

# Array of relative file locations for multiple certs
certificates:
- cert: '$HOME/.acme.sh/authenticate.example.com_ecc/fullchain.cer'
key: '$HOME/.acme.sh/authenticate.example.com_ecc/authenticate.example.com.key'
- cert: '$HOME/.acme.sh/verify.example.com_ecc/fullchain.cer'
key: '$HOME/.acme.sh/verify.example.com_ecc/verify.example.com.key'
- cert: '$HOME/.acme.sh/prometheus.example.com_ecc/fullchain.cer'
key: '$HOME/.acme.sh/prometheus.example.com_ecc/prometheus.example.com.key'

Set a single certificate and key covering multiple domains and/or a wildcard subdomain:

# Relative file location for a single cert
certificate_file: '$HOME/.acme.sh/*.example.com/fullchain.crt'
certificate_key_file: '$HOME/.acme.sh/*.example.com/*.example.com.key'
Note:

All certificates supplied to Pomerium must be in PEM format.

Certificate Authority

Certificate Authority defines a set of root certificate authorities (CAs) that Pomerium uses when communicating with other TLS-protected services.

Note:

Unlike route-specific CA settings, this setting augments (rather than replaces) the system's trust store. Routes that specify a CA will ignore those provided here.

danger

Be sure to include the intermediary certificate.

How to configure

Config file keysEnvironment variablesTypeUsage
certificate_authorityCERTIFICATE_AUTHORITYstringoptional
certificate_authority_fileCERTIFICATE_AUTHORITY_FILEstringoptional

Examples

# config file key
certificate_authority: base64-encoded-string

# environment variable
CERTIFICATE_AUTHORITY_FILE=/relative/file/location

Client Certificate Authority

caution

This setting is deprecated; it has been moved to a new Downstream mTLS Settings group (see the Certificate Authority setting there).

This setting will be treated as an alias for the new setting, but will be removed in a future Pomerium release.

Client Certificate Authority is the X.509 public-key used to validate mTLS client certificates.

If not set, no client certificate will be required.

How to configure

Config file keysEnvironment variablesTypeUsage
client_caCLIENT_CAstringoptional
client_ca_fileCLIENT_CA_FILEstringoptional

Examples

client_ca: base64-encoded-string
client_ca_file: base64-encoded-string

CLIENT_CA=/relative/file/location
CLIENT_CA_FILE=/relative/file/location