traefik_mtls_check_plugin

README

Traefik mTLS Check middleware Plugin

The traefik_mtls_check_plugin package is a middleware plugin for Traefik that performs mutual TLS (mTLS) certificate validation. It allows Traefik to verify the client certificates presented during TLS handshake against a given CA certificate. The main difference between this middleware plugin and TLSOptions, that the plugin allows you to specify the response code and message that should be returned to the client in case of a failed validation. On other hand, TLSOptions with clientAuthType: RequireAndVerifyClientCert will return ssl error to the client. The combination of:

• TLSOptions with clientAuthType: RequestClientCert
• mTlsCheck middleware
• Errors middleware with custom errorPage

will allow you to return custom errorPage to the client in case of failed validation and the unwanted visitors will not be able to recognize that you are using mTLS.

Installation

To use the traefik_mtls_check_plugin, you need to have Traefik installed and configured. Follow the instructions below to install the plugin:

1. Install Traefik: Traefik Installation Guide
2. Configure Traefik to use the plugin: Add the following lines to your Traefik configuration file (traefik.toml or traefik.yaml):

[experimental.plugins.traefik-mtls-check-plugin]
  moduleName = "github.com/WalterP/traefik-mtls-check-plugin"
  version = "v0.1.0"

experimental:
  plugins:
    traefik-mtls-check-plugin:
      moduleName: "github.com/WalterP/traefik-mtls-check-plugin"
      version: "v0.1.0"

--experimental.plugins.traefik-mtls-check-plugin.modulename=github.com/WalterP/traefik-mtls-check-plugin
--experimental.plugins.traefik-mtls-check-plugin.version=v0.1.0

1. Restart Traefik: traefik restart

Configuration

The traefik_mtls_check_plugin supports the following configuration options in the Traefik middleware configuration file:

• responseCode: The HTTP response code to return when the certificate validation fails.
• caCert: The CA certificate content as a string. (Optional if caCertPath is provided). Mostly for kubernetes usage. See example below.
• caCertPath: The path to the CA certificate file. (Optional if caCert is provided). Mostly for docker usage.
• message: The message to return in the response body when the certificate validation fails.

Usage

Once the traefik_mtls_check_plugin is installed and configured, you can use it by adding it as a middleware to your Traefik routes. Here's an example of how to configure the plugin in your Traefik routing:

Docker:

- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.message=Not - Found"
- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.ResponseCode=404"
- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.caCertPath=/certs/mtls/ca.crt"
- "traefik.http.routers.whoami.middlewares=test-redirect"

Kubernetes:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: mtls-check
spec:
  plugin:
    traefik-mtls-check-plugin:
      message: "Not-found"
      responseCode: 404
      caCert: "urn:k8s:secret:client-mtls:ca.crt"

Example with combination of custom errorPage:

- "traefik.http.routers.whoami.tls.options=mtls@file"
- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.message=Not - Found"
- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.ResponseCode=404"
- "traefik.http.middlewares.test-redirect.plugin.traefik-mtls-check-plugin.caCertPath=/certs/mtls/ca.crt"
- "traefik.http.middlewares.test-errors.errors.status=400-499"
- "traefik.http.middlewares.test-errors.errors.service=errorServer@docker"
- "traefik.http.routers.whoami.middlewares=test-errors,test-redirect"
- "traefik.http.services.whoami.loadbalancer.server.port=8082"

mtlsOptions used to request client certificate:

    mtls:
      sniStrict: false
      clientAuth:
        clientAuthType: RequestClientCert
        caFiles:
          - /etc/traefik/ca.crt

Documentation

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Config
  • func CreateConfig() *Config

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

Types

type Config

type Config struct {
	ResponseCode int    `yaml:"responseCode" json:"responseCode"`
	CaCert       string `yaml:"caCert" json:"caCert"`
	CACertPath   string `yaml:"caCertPath" json:"caCertPath"`
	Message      string `yaml:"message" json:"message"`
}

Config This is the configuration struct. Here we are defining the configuration options that the user can set in the traefik.toml file.

func CreateConfig

func CreateConfig() *Config

CreateConfig This function is used to create the default configuration for the plugin. It is called when the user does not. provide a configuration for the plugin in the traefik.toml file.