QueryParameter-to-Bearer Middleware

Traefik middleware to add a header with the value of a given URL query parameter

queryParameter key are configurable. It is assumed that there is only one query parameter with the given key. If there is no matching query parameter the cookie value is used for the Bearer token.

Tested with Traefik v2.11.29.

Example Traefik config:

[...]
experimental:
  plugins:
    queryParameterToBearer:
      moduleName: codeberg.org/iobear/queryparameter-to-bearer
      version: v0.1.6

http:
[...]
  routers:
    whoami:
      rule: "Host(`whoami.localhost`)"
      service: "whoami"
      entryPoints:
        - web
      middlewares:
        - add-header-from-query
  
  middlewares:
    add-header-from-query:
      plugin:
        queryParameterToBearer:
          queryParameter: "access_token"
          removeFromUpstreamQuery: true
          cookieName: "session_token"
          cookieSecure: false  # set true in production with HTTPS
          cookieHttpOnly: true
          cookieSameSite: "None"  # for iframe usage across domains
          cookieEncrypt: true
          # base64-encoded AES key (16/24/32 bytes when decoded). Set via env or file provider.
          cookieEncryptionKey: ""

Local testing with Traefik (no publishing)

You can test this plugin locally using Traefik's localPlugins with Docker Compose:

1. Start Traefik and whoami:

• Requires Docker and Docker Compose.
• Port 8081 maps to Traefik entryPoint web.

2. From the repo root, run:

docker compose up --build

3. In another terminal, call whoami with a token in the query string and inspect the headers echoed back by whoami:

curl -sS "http://localhost:8081/?access_token=abc123" | sed -n '1,200p'

You should see the Authorization header set to Bearer abc123 in the whoami response.

You can tweak parameters in traefik/dynamic.yml under the add-header-from-query middleware.

Config options

• queryParameter: name of the token query param (default: access_token)
• Header is always Authorization with Bearer scheme
• removeFromUpstreamQuery: remove the token param before proxying (default: true)
• cookieName: persist full header value in a cookie for session reuse (default: session_token_traefik)
• cookieSecure: set cookie Secure flag (default: true)
• cookieHttpOnly: set cookie HttpOnly flag (default: true)
• cookieSameSite: set cookie SameSite policy: "None", "Lax", or "Strict" (default: "Lax")
  • Use "None" when your site is embedded in iframes across domains (requires cookieSecure=true)
  • Use "Lax" for most scenarios (default, allows navigation from external links)
  • Use "Strict" for highest security (token only sent in first-party context)
• cookieEncrypt: encrypt cookie value with AES-GCM (default: true)
• cookieEncryptionKey: base64-encoded key for AES (required if cookieEncrypt=true)
• passthroughAuthErrors: pass through 401/403 status codes from upstream and clear the session cookie (default: true)
  • When enabled, if upstream returns 401 Unauthorized or 403 Forbidden, the plugin will clear the session cookie

Behavior

• If query contains the token, the header is set from it and a session cookie is written with the full header value.
• If query has no token but the cookie exists, the header is set from the cookie.
• If both exist, query takes precedence and refreshes the cookie.
• When encryption is enabled, the cookie stores an encrypted, base64url value including a random nonce; decryption happens transparently.

Generating a key Use a 32-byte key (AES-256) base64-encoded. Example to generate one:

head -c 32 /dev/urandom | base64

Attribution

I started with Corti's code from https://github.com/corticph/queryparameter-to-header and added a session cookie.