Middlewares

Middleware names are case / snake insensitive, redirectHTTP, redirect_http, RedirectHttp are all equivalent

Use case example

Docker compose

Authentik (untested, experimental)

# docker compose
services:
  ...
  server:
    ...
    container_name: authentik
    labels:
      proxy.authentik.middlewares.redirect_http:
      proxy.authentik.middlewares.set_x_forwarded:
      proxy.authentik.middlewares.modify_request.add_headers: |
        Strict-Transport-Security: "max-age=63072000" always

  whoami:
    image: containous/whoami
    container_name: whoami
    ports:
      - 80
    labels:
      proxy.#1.middlewares.forward_auth.address: https://your_authentik_forward_address
      proxy.#1.middlewares.forward_auth.trustForwardHeader: true
      proxy.#1.middlewares.forward_auth.authResponseHeaders: |
        X-authentik-username
        X-authentik-groups
        X-authentik-email
        X-authentik-name
        X-authentik-uid
        X-authentik-jwt
        X-authentik-meta-jwks
        X-authentik-meta-outpost
        X-authentik-meta-provider
        X-authentik-meta-app
        X-authentik-meta-version
    restart: unless-stopped

Include file

openai:
    host: https://api.openai.com/
    middlewares:
        cidr_whitelist:
            allow:
                - 127.0.0.1
                - 10.0.0.0/16
        modify_request:
            set_headers:
                Host: api.openai.com
    homepage:
        show: false

🔼Back to top

Available middlewares

Redirect http

Redirect http requests to https

# docker labels
proxy.app1.middlewares.redirect_http:

# include file
app1:
    middlewares:
        redirect_http:

nginx equivalent:

server {
    listen 80;
    server_name domain.tld;
    return 301 https://$host$request_uri;
}

🔼Back to top

Custom error pages

Please check Custom Error Pages

# docker labels
proxy.app1.middlewares.custom_error_page:

# include file
app1:
    middlewares:
        custom_error_page:

nginx equivalent:

location / {
    try_files $uri $uri/ /error_pages/404.html =404;
}

🔼Back to top

Real IP

Check https://nginx.org/en/docs/http/ngx_http_realip_module.html for explaination of options

Behaviors

This middleware is used for setting $remote_addr, $remote_host from real_ip.header (i.e.) X-Real-IP. Doing so will also change the IP address in access log.

Custom

# docker labels
proxy.app1.middlewares.real_ip.header: X-Real-IP
proxy.app1.middlewares.real_ip.from: |
    - 127.0.0.1
    - 192.168.0.0/16
    - 10.0.0.0/8
proxy.app1.middlewares.real_ip.recursive: true
# include file
app1:
    middlewares:
        real_ip:
            header: X-Real-IP
            from:
                - 127.0.0.1
                - 192.168.0.0/16
                - 10.0.0.0/8
            recursive: true

nginx equivalent:

location / {
    set_real_ip_from 127.0.0.1;
    set_real_ip_from 192.168.0.0/16;
    set_real_ip_from 10.0.0.0/8;

    real_ip_header    X-Real-IP;
    real_ip_recursive on;
}

🔼Back to top

Cloudflare

This is a preset for Cloudflare

header: CF-Connecting-IP
from: CIDR List of Cloudflare IPs from (updated every hour)
- https://www.cloudflare.com/ips-v4
- https://www.cloudflare.com/ips-v6
recursive: true

# docker labels
proxy.app1.middlewares.cloudflare_real_ip:

# include file
app1:
    middlewares:
        cloudflare_real_ip:

🔼Back to top

CIDR Whitelist

# docker labels
proxy.app1.middlewares.cidr_whitelist: |
    allow:
      - 10.0.0.0/8
      - 192.168.0.0/16
    status_code: 403
    message: "IP not allowed"

# include file
app1:
    middlewares:
        cidr_whitelist:
            allow:
                - 10.0.0.0/8
                - 192.168.0.0/16
            status_code: 403 # default
            message: "IP not allowed" # default

Rate Limiter

average: average number of requests per period burst: maximum number of requests allowed in a period periods: time period in format number[unit]

# docker labels
proxy.app1.middlewares.ratelimit: |
    average: 100
    burst: 100
    periods: 1s

# include file
app1:
    middlewares:
        ratelimit:
            average: 100
            burst: 100
            periods: 1s

🔼Back to top

Modify request or response

Supported variables

$req_method: request http method
$req_scheme: request URL scheme (http/https)
$req_host: request host without port
$req_port: request port
$req_addr: request host with port (if present)
$req_path: request URL path
$req_query: raw query string
$req_url: full request URL
$req_uri: request URI (encoded path?query)
$req_content_type: request Content-Type header
$req_content_length: length of request body (if present)
$remote_addr: client's remote address (may changed by middlewares like RealIP and CloudflareRealIP)
$remote_host: client's remote ip parse from $remote_addr
$remote_port: client's remote port parse from $remote_addr (may be empty)
$resp_content_type: response Content-Type header
$resp_content_length: length response body
$status_code: response status code
$upstream_name: upstream server name (alias)
$upstream_scheme: upstream server scheme
$upstream_host: upstream server host
$upstream_port: upstream server port
$upstream_addr: upstream server address with port (if present)
$upstream_url: full upstream server URL
$header(name): get request header by name
$resp_header(name): get response header by name
$arg(name): get URL query parameter by name

Set headers

# docker labels
proxy.app1.middlewares.request.set_headers: |
    X-Custom-Header1: value1, value2
    X-Custom-Header2: value3

# include file
app1:
    middlewares:
        request:
            set_headers:
                X-Custom-Header1: value1, value2
                X-Custom-Header2: value3

nginx equivalent:

location / {
    add_header X-Custom-Header1 value1, value2;
    add_header X-Custom-Header2 value3;
}

🔼Back to top

Add headers

# docker labels
proxy.app1.middlewares.request.add_headers: |
    X-Custom-Header1: value1, value2
    X-Custom-Header2: value3

# include file
app1:
    middlewares:
        request:
            add_headers:
                X-Custom-Header1: value1, value2
                X-Custom-Header2: value3

nginx equivalent:

location / {
    more_set_headers "X-Custom-Header1: value1, value2";
    more_set_headers "X-Custom-Header2: value3";
}

🔼Back to top

Hide headers

# docker labels
proxy.app1.middlewares.modify_request.hide_headers: |
    X-Custom-Header1
    X-Custom-Header2

# include file
app1:
    middlewares:
        modify_request:
            hide_headers:
                - X-Custom-Header1
                - X-Custom-Header2

nginx equivalent:

location / {
    more_clear_headers "X-Custom-Header1";
    more_clear_headers "X-Custom-Header2";
}

🔼Back to top

X-Forwarded-* Headers

Hide X-Forwarded-*

Remove Forwarded and X-Forwarded-* headers before request

# docker labels
proxy.app1.middlewares.hide_x_forwarded:

# include file
app1:
    middlewares:
        hide_x_forwarded:

Set X-Forwarded-*

Replace existing X-Forwarded-* headers with GoDoxy provided headers

# docker labels
proxy.app1.middlewares.set_x_forwarded:

# include file
app1:
    middlewares:
        set_x_forwarded:

🔼Back to top

Forward Authorization header (experimental)

Fields:

address: authentication provider URL (required)
trust_forward_header: whether to trust X-Forwarded-* headers from upstream proxies (default: false)
auth_response_headers: list of headers to copy from auth response (default: empty)
add_auth_cookies_to_response: list of cookies to add to response (default: empty)

# docker labels
proxy.app1.middlewares.forward_auth.address: https://auth.example.com
proxy.app1.middlewares.forward_auth.trust_forward_header: true
proxy.app1.middlewares.forward_auth.auth_response_headers: |
    - X-Auth-Token
    - X-Auth-User
proxy.app1.middlewares.forward_auth.add_auth_cookies_to_response: |
    - uid
    - session_id

# include file
app1:
    middlewares:
        forward_authorization:
            address: https://auth.example.com
            trust_forward_header: true
            auth_response_headers:
                - X-Auth-Token
                - X-Auth-User
            add_auth_cookies_to_response:
                - uid
                - session_id

Traefik equivalent:

# docker labels
traefik.http.middlewares.authentik.forwardauth.address: https://auth.example.com
traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: true
traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-Auth-Token, X-Auth-User
traefik.http.middlewares.authentik.forwardauth.addAuthCookiesToResponse: uid, session_id

# standalone
http:
    middlewares:
        forwardAuth:
            address: https://auth.example.com
            trustForwardHeader: true
            authResponseHeaders:
                - X-Auth-Token
                - X-Auth-User
            addAuthCookiesToResponse:
                - uid
                - session_id

🔼Back to top

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Middlewares

Middlewares

Use case example

Docker compose

Include file

Available middlewares

Redirect http

Custom error pages

Real IP

Behaviors

Custom

Cloudflare

CIDR Whitelist

Rate Limiter

Modify request or response

Supported variables

Set headers

Add headers

Hide headers

X-Forwarded-* Headers

Hide X-Forwarded-*

Set X-Forwarded-*

Forward Authorization header (experimental)

Clone this wiki locally