TLS Configuration

Configure TLS options, certificates, cipher suites, and client authentication in Traefik.

TLS Configuration

Traefik provides comprehensive TLS configuration options for securing your services, including custom certificates, TLS versions, cipher suites, and mutual TLS authentication.

Certificate Definition

Manual Certificates

Define certificates manually in the dynamic configuration:

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

Certificates can be defined using the file provider only. In Kubernetes, use Secrets instead.

Certificate Content vs. File Path

Certificates can be provided as file paths or inline content:

File Path

tls:
  certificates:
    - certFile: /etc/traefik/certs/domain.crt
      keyFile: /etc/traefik/certs/domain.key

Inline Content

tls:
  certificates:
    - certFile: |
        -----BEGIN CERTIFICATE-----
        MIIDXTCCAkWgAwIBAgIJAKZ...
        -----END CERTIFICATE-----
      keyFile: |
        -----BEGIN PRIVATE KEY-----
        MIIEvQIBADANBgkqhkiG9w...
        -----END PRIVATE KEY-----

Kubernetes Secrets

In Kubernetes, certificates are provided through Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: my-tls-cert
  namespace: default
type: kubernetes.io/tls
data:
  tls.crt: LS0tLS1CRUdJTi...
  tls.key: LS0tLS1CRUdJTi...
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-ingress
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`example.com`)
      kind: Rule
      services:
        - name: my-service
          port: 80
  tls:
    secretName: my-tls-cert

Certificate Stores

Certificates are organized in stores. Only the default store is available:

YAML

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

Default Certificate

The default certificate is used for connections without SNI or without a matching domain:

YAML

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

If no default certificate is configured, Traefik generates a self-signed certificate automatically.

TLS Options

TLS options control the TLS connection parameters.

Minimum TLS Version

Set the minimum TLS version to enforce:

YAML

tls:
  options:
    default:
      minVersion: VersionTLS12
    
    strict:
      minVersion: VersionTLS13

Available versions:

• VersionTLS10 (not recommended)
• VersionTLS11 (not recommended)
• VersionTLS12 (recommended minimum)
• VersionTLS13 (recommended)

TLS 1.0 and 1.1 are deprecated and vulnerable. Always use TLS 1.2 or higher in production.

Maximum TLS Version

Limit the maximum TLS version (not recommended):

YAML

tls:
  options:
    legacy:
      maxVersion: VersionTLS12

Disabling TLS 1.3 is discouraged. Update clients to support TLS 1.3 instead.

Cipher Suites

Configure allowed cipher suites for TLS 1.2 and below:

YAML

tls:
  options:
    default:
      minVersion: VersionTLS12
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

Recommended cipher suites:

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
• TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

TLS 1.3 cipher suites are not configurable. All TLS 1.3 cipher suites are considered secure.

Curve Preferences

Specify elliptic curves for key exchange:

YAML

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

Available curves:

• CurveP256 / secp256r1
• CurveP384 / secp384r1
• CurveP521 / secp521r1
• X25519 / x25519
• X25519MLKEM768 / x25519mlkem768 (post-quantum)

ALPN Protocols

Configure Application-Layer Protocol Negotiation:

YAML

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

Default: ["h2", "http/1.1", "acme-tls/1"]

Strict SNI Checking

Reject connections without valid SNI:

YAML

tls:
  options:
    strict:
      sniStrict: true
      minVersion: VersionTLS12

With sniStrict: true, Traefik rejects connections from clients that don’t specify a server_name extension or don’t match any configured certificates.

Client Authentication (mTLS)

Enable mutual TLS authentication to verify client certificates:

YAML

tls:
  options:
    mtls:
      minVersion: VersionTLS12
      clientAuth:
        caFiles:
          - /path/to/client-ca.crt
        clientAuthType: RequireAndVerifyClientCert

Client Auth Types

Type	Description
NoClientCert	No client certificate required or verified
RequestClientCert	Request certificate but don’t require it
RequireAnyClientCert	Require certificate but don’t verify it
VerifyClientCertIfGiven	Verify certificate only if provided
RequireAndVerifyClientCert	Require and verify client certificate

1. NoClientCert

   No client certificate verification. Default behavior.

2. RequestClientCert

   Request a client certificate during handshake but continue without it.

3. RequireAnyClientCert

   Client must send a certificate but it’s not validated against CA.

4. VerifyClientCertIfGiven

   If client sends a certificate, it must be valid. Otherwise, connection proceeds.

5. RequireAndVerifyClientCert

   Client must send a valid certificate signed by a trusted CA.

Using TLS Options in Routers

Apply TLS options to routers:

YAML

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      tls:
        options: mtls@file

The default TLS option is applied automatically if no option is specified. When referencing options from other providers, include the provider namespace (e.g., myoptions@file).

Disable Session Tickets

Force full TLS handshake on every connection:

YAML

tls:
  options:
    default:
      disableSessionTickets: true

Disabling session tickets increases CPU usage and connection latency. Only use when required for security compliance.

Complete Configuration Examples

Production TLS Configuration

YAML

tls:
  options:
    production:
      minVersion: VersionTLS12
      maxVersion: VersionTLS13
      cipherSuites:
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      curvePreferences:
        - CurveP521
        - CurveP384
      sniStrict: true
      alpnProtocols:
        - h2
        - http/1.1
  
  certificates:
    - certFile: /etc/traefik/certs/example.com.crt
      keyFile: /etc/traefik/certs/example.com.key
  
  stores:
    default:
      defaultCertificate:
        certFile: /etc/traefik/certs/default.crt
        keyFile: /etc/traefik/certs/default.key

mTLS Configuration

YAML

tls:
  options:
    mtls:
      minVersion: VersionTLS13
      clientAuth:
        caFiles:
          - /etc/traefik/ca/client-ca.crt
        clientAuthType: RequireAndVerifyClientCert
      sniStrict: true

Development Configuration

YAML

tls:
  options:
    dev:
      minVersion: VersionTLS12
      sniStrict: false
  
  certificates:
    - certFile: /etc/traefik/certs/localhost.crt
      keyFile: /etc/traefik/certs/localhost.key

Security Best Practices

1. Use TLS 1.2 or Higher

   Set minVersion: VersionTLS12 or VersionTLS13 to disable vulnerable protocols.

2. Enable Strong Cipher Suites

   Only allow modern, secure cipher suites with forward secrecy (ECDHE).

3. Use Modern Curves

   Prefer X25519, P-384, and P-521 curves for key exchange.

4. Enable HTTP/2

   Include h2 in alpnProtocols for better performance and security.

5. Implement Certificate Rotation

   Regularly rotate certificates and maintain proper certificate lifecycle management.

6. Monitor Certificate Expiry

   Set up alerts for certificate expiration (30 days before).

Troubleshooting

Certificate Not Found

Check File Paths

Verify certificate and key file paths are correct and accessible:

ls -la /path/to/cert.crt
ls -la /path/to/cert.key

Verify Permissions

Ensure Traefik has read permissions:

chmod 644 /path/to/cert.crt
chmod 600 /path/to/cert.key

Validate Certificate

Check certificate validity:

openssl x509 -in /path/to/cert.crt -text -noout

TLS Handshake Failures

• Cipher suite mismatch: Client doesn’t support any configured cipher suites
• Protocol version mismatch: Client TLS version below minVersion
• SNI issues: Enable debug logging to see SNI values
• Certificate chain issues: Ensure intermediate certificates are included

Client Certificate Errors

• CA not trusted: Verify CA file path in caFiles
• Certificate expired: Check client certificate validity
• Wrong clientAuthType: Adjust based on requirements

Enable debug logging for detailed TLS connection information:

--log.level=DEBUG