Certificates Settings

This reference covers all of Pomerium's Certificates Settings:

• Certificates
• Certificate Authority

Note

All certificates supplied to Pomerium must be in PEM format.

Pomerium supports certificates with RSA or ECDSA keys. For server or client certificates with ECDSA keys, Pomerium supports only the P-256 curve. For certificate authorities with ECDSA keys, Pomerium supports the P-384 and P-521 curves as well.

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

Core

Config file keys	Environment variables	Type	Usage
certificates	Not settable as environment variable	string (Array of relative file locations for multiple certificates)	required (if insecure not set)
certificate and certificate_key	CERTIFICATE and CERTIFICATE_KEY	string (base64-encoded string)	required (if insecure not set)
certificate_file and certificate_key_file	CERTIFICATE_FILE and CERTIFICATE_KEY_FILE	string (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'

Enterprise

Add Certificates in the Enterprise Console:

View Certificates:

Kubernetes

certificates: pomerium/wildcard-localhost

See Kubernetes TLS Certificates for more information.

note

All certificates supplied to Pomerium must be in PEM format.

Certificate Authority (CA)

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.

warning

Be sure to include the intermediary certificate.

How to configure

Core

Config file keys	Environment variables	Type	Usage
certificate_authority	CERTIFICATE_AUTHORITY	string	optional
certificate_authority_file	CERTIFICATE_AUTHORITY_FILE	string	optional

Examples

certificate_authority: 'base64-encoded-string'

CERTIFICATE_AUTHORITY_FILE=/relative/file/location

Enterprise

Configure Certificate Authority in the Enterprise Console:

Kubernetes

Kubernetes does not support certificate_authority