TLS Certificates

Info

When a router has to handle HTTPS traffic, it should be specified with a tls field of the router definition.

Certificates Definition¶

Automated¶

User defined¶

To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the dynamic configuration, in the [[tls.certificates]] section:

Structured (YAML)

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

Structured (TOML)

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"

[[tls.certificates]]
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

Restriction

In the above example, we've used the file provider to handle these definitions. It is the only available method to configure the certificates (as well as the options and the stores). However, in Kubernetes, the certificates can and must be provided by secrets.

Certificate selection (SNI)¶

Traefik selects the certificate to present during the TLS handshake, based on the Server Name Indication (SNI) sent by the client.

However, HTTP router rules (e.g., Host()) are evaluated after TLS has been established, so they do not influence certificate selection.

Strict SNI Checking¶

By default, if the client does not send SNI, or if no certificate matches the requested server name, Traefik falls back to the default certificate from the TLS store (if configured).

To reject connections without SNI (or with an unknown server name) instead of falling back to the default certificate, enable sniStrict in TLS Options.

Certificates Stores¶

In Traefik, certificates are grouped together in certificates stores.

Restriction

Any store definition other than the default one (named default) will be ignored, and there is therefore only one globally available TLS store.

In the tls.certificates section, a list of stores can then be specified to indicate where the certificates should be stored:

Structured (YAML)

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
      stores:
        - default
    # Note that since no store is defined,
    # the certificate below will be stored in the `default` store.
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

Structured (TOML)

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"
  stores = ["default"]

[[tls.certificates]]
  # Note that since no store is defined,
  # the certificate below will be stored in the `default` store.
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

Restriction

The stores list will actually be ignored and automatically set to ["default"].

Per provider examples

Default Certificate¶

Traefik can use a default certificate for connections without a SNI, or without a matching domain. This default certificate should be defined in a TLS store:

Structured (YAML)

tls:
  stores:
    default:
      defaultCertificate:
        certFile: path/to/cert.crt
        keyFile: path/to/cert.key

Structured (TOML)

[tls.stores]
  [tls.stores.default]
    [tls.stores.default.defaultCertificate]
      certFile = "path/to/cert.crt"
      keyFile  = "path/to/cert.key"

If no defaultCertificate is provided, Traefik will use the generated one.

ACME Default Certificate¶

You can configure Traefik to use an ACME provider (like Let's Encrypt) to generate the default certificate. The configuration to resolve the default certificate should be defined in a TLS store:

Precedence with the defaultGeneratedCert option

The defaultGeneratedCert definition takes precedence over the ACME default certificate configuration.

Structured (YAML)

tls:
  stores:
    default:
      defaultGeneratedCert:
        resolver: myresolver
        domain:
          main: example.org
          sans:
            - foo.example.org
            - bar.example.org

Structured (TOML)

[tls.stores]
  [tls.stores.default.defaultGeneratedCert]
    resolver = "myresolver"
    [tls.stores.default.defaultGeneratedCert.domain]
      main = "example.org"
      sans = ["foo.example.org", "bar.example.org"]

Labels

labels:
  - "traefik.tls.stores.default.defaultgeneratedcert.resolver=myresolver"
  - "traefik.tls.stores.default.defaultgeneratedcert.domain.main=example.org"
  - "traefik.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"