TLS Options

The TLS options allow one to configure some parameters of the TLS connection.

'default' TLS Option

The default option is special. When no tls options are specified in a tls router, the default option is used.
When specifying the default option explicitly, make sure not to specify provider namespace as the default option does not have one.
Conversely, for cross-provider references, for example, when referencing the file provider from a docker label, you must specify the provider namespace, for example:
traefik.http.routers.myrouter.tls.options=myoptions@file

Providers

TLS options are not supported by label or tag-based providers. However, you can define them when using a KV provider.

TLSOption in Kubernetes

With the TLSOption resource, the option named default applies to every router that does not reference a TLSOption explicitly, whatever the namespace it is defined in. The defaultTLSResourcesNamespace provider option restricts the namespace this cluster-wide default can be defined in.

Server Name Association

The TLS options are configured on a router, but they are applied during the TLS handshake, that is to say before the routing occurs, when the server name (SNI) is the only information available. A TLS options reference is therefore always mapped to the host names found in the Host part of the router rule, and neither to the router nor to its rule. There could also be several Host parts in a rule, in which case the TLS options reference is mapped to as many host names.

In the case of domain fronting, if the TLS options associated with the Host header and the SNI are different, Traefik responds with a 421 Misdirected Request status code.

Conflicting TLS Options

Since a TLS options reference is mapped to a host name, a conflict occurs when a configuration introduces a situation where the same host name, on the same entry point, is matched with two different TLS options references, such as in the example below:

Structured (YAML)

# Dynamic configuration

http:
  routers:
    routerfoo:
      rule: "Host(`example.com`) && Path(`/foo`)"
      tls:
        options: foo

    routerbar:
      rule: "Host(`example.com`) && Path(`/bar`)"
      tls:
        options: bar

Structured (TOML)

# Dynamic configuration

[http.routers]
  [http.routers.routerfoo]
    rule = "Host(`example.com`) && Path(`/foo`)"
    [http.routers.routerfoo.tls]
      options = "foo"

  [http.routers.routerbar]
    rule = "Host(`example.com`) && Path(`/bar`)"
    [http.routers.routerbar.tls]
      options = "bar"

If that happens, both mappings are discarded, and the host name (example.com in this example) gets associated with the default TLS options instead.

The conflict detection is not limited to a single provider: routers coming from different providers, for example a router defined with a container label and another one defined with the file provider, conflict with each other as soon as they serve the same host name on the same entry point.

Default TLS Options

The default TLS options are the fallback of the conflict resolution, and should therefore not be less secure than the options they can replace. A router relying on a mutual TLS authentication (clientAuth), for example, no longer enforces it if a conflict on its host name falls back to default TLS options that do not require it.

The surest way to avoid this is to have all the routers serving the same host name, on the same entry point, reference the same TLS options.

Strict TLS Options

The core.strictTLSOptions install configuration option disables the fallback to the default TLS options. When it is enabled, the routers involved in the conflict are marked in error and are not built at all, and the host name is no longer mapped to any TLS options.

Disabled routers

Enabling strictTLSOptions fails closed: a conflict disables all the routers serving the conflicting host name on the concerned entry point, until the conflict is resolved.

File (YAML)

## Install configuration
core:
  strictTLSOptions: true

File (TOML)

## Install configuration
[core]
  strictTLSOptions = true

CLI

## Install configuration
--core.strictTLSOptions=true

Minimum TLS Version

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      minVersion: VersionTLS12

    mintls13:
      minVersion: VersionTLS13

Structured (TOML)

# Dynamic configuration

[tls.options]

  [tls.options.default]
    minVersion = "VersionTLS12"

  [tls.options.mintls13]
    minVersion = "VersionTLS13"

Maximum TLS Version

We discourage the use of this setting to disable TLS1.3.

The recommended approach is to update the clients to support TLS1.3.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      maxVersion: VersionTLS13

    maxtls12:
      maxVersion: VersionTLS12

Structured (TOML)

# Dynamic configuration

[tls.options]

  [tls.options.default]
    maxVersion = "VersionTLS13"

  [tls.options.maxtls12]
    maxVersion = "VersionTLS12"

Cipher Suites

See cipherSuites for more information.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Structured (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    cipherSuites = [
      "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
    ]

TLS 1.3

Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa. (https://tools.ietf.org/html/rfc8446)
With TLS 1.3, the cipher suites are not configurable (all supported cipher suites are safe in this case). https://golang.org/doc/go1.12#tls_1_3

Curve Preferences

This option allows setting the preferred elliptic curves.

The names of the curves defined by crypto (e.g. CurveP521) and the RFC defined names (e. g. secp521r1) can be used.

See CurveID for more information.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      curvePreferences:
        - CurveP521
        - CurveP384

Structured (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    curvePreferences = ["CurveP521", "CurveP384"]

Strict SNI Checking

With strict SNI checking enabled, Traefik won't allow connections from clients that do not specify a server_name extension or don't match any of the configured certificates. The default certificate is irrelevant on that matter.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      sniStrict: true

Structured (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    sniStrict = true

ALPN Protocols

Optional, Default="h2, http/1.1, acme-tls/1"

This option allows specifying the list of supported application level protocols for the TLS handshake, in order of preference. If the client supports ALPN, the selected protocol will be one from this list, and the connection will fail if there is no mutually supported protocol.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      alpnProtocols:
        - http/1.1
        - h2

Structured (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    alpnProtocols = ["http/1.1", "h2"]

Client Authentication (mTLS)

Traefik supports mutual authentication, through the clientAuth section.

For authentication policies that require verification of the client certificate, the certificate authority for the certificates should be set in clientAuth.caFiles.

In Kubernetes environment, CA certificate can be set in clientAuth.secretNames. See TLSOption resource for more details.

The clientAuth.clientAuthType option governs the behaviour as follows:

Option	Operation
NoClientCert	Disregards any client certificate.
RequestClientCert	Asks for a certificate but proceeds anyway if none is provided.
RequireAnyClientCert	Requires a certificate but does not verify if it is signed by a CA listed in clientAuth.caFiles or in clientAuth.secretNames.
VerifyClientCertIfGiven	If a certificate is provided, verifies if it is signed by a CA listed in clientAuth.caFiles or in clientAuth.secretNames. Otherwise proceeds without any certificate.
RequireAndVerifyClientCert	requires a certificate, which must be signed by a CA listed in clientAuth.caFiles or in clientAuth.secretNames.

Structured (YAML)

# Dynamic configuration

tls:
  options:
    default:
      clientAuth:
        # in PEM format. each file can contain multiple CAs.
        caFiles:
          - tests/clientca1.crt
          - tests/clientca2.crt
        clientAuthType: RequireAndVerifyClientCert

Structured (TOML)

# Dynamic configuration

[tls.options]
  [tls.options.default]
    [tls.options.default.clientAuth]
      # in PEM format. each file can contain multiple CAs.
      caFiles = ["tests/clientca1.crt", "tests/clientca2.crt"]
      clientAuthType = "RequireAndVerifyClientCert"

Disable Session Tickets

Optional, Default="false"

When set to true, Traefik disables the use of session tickets, forcing every client to perform a full TLS handshake instead of resuming sessions.

Structured (YAML)

# routing configuration

tls:
  options:
    default:
      disableSessionTickets: true

Structured (TOML)

# routing configuration

[tls.options]
  [tls.options.default]
    disableSessionTickets = true

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
  name: default
  namespace: default

spec:
  disableSessionTickets: true

---

Using Traefik OSS in Production?

If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.

• Watch our API Gateway Demo Video
• Request 24/7/365 OSS Support

Adding API Gateway capabilities to Traefik OSS is fast and seamless. There's no rip and replace and all configurations remain intact. See it in action via this short video.