/Traefik OIDC

Traefik OIDC

189

v1.0.10

Traefik OIDC Middleware

OpenID Connect authentication middleware for Traefik. Replaces forward-auth + oauth2-proxy. Auto-detects all major OIDC providers, validates ID tokens, manages sessions, and forwards user identity to downstream services.

Documentation

Configuration reference — every parameter
Provider guide — Google, Azure, Auth0, Okta, Keycloak, Cognito, GitLab, GitHub, generic
Auth0 audience guide — custom APIs, opaque tokens, token confusion
Redis cache — multi-replica deployments
Dynamic Client Registration — RFC 7591
Development · Testing

Provider support

Provider	OIDC	Refresh	Auto-detected by
Google	Full	Yes	`accounts.google.com`
Azure AD	Full	Yes	`login.microsoftonline.com`, `sts.windows.net`
Auth0	Full	Yes	`*.auth0.com`
Okta	Full	Yes	`.okta.com`, `.oktapreview.com`, `*.okta-emea.com`
Keycloak	Full	Yes	host containing `keycloak`, or `/realms/` in path (covers KC <17 `/auth/realms/` and 17+ `/realms/`)
AWS Cognito	Full	Yes	`cognito-idp.*.amazonaws.com`
GitLab	Full	Yes	`gitlab.com`
GitHub	OAuth 2.0 only — no ID token, no refresh	No	`github.com`
Generic	Full	Yes	any RFC-compliant `.well-known/openid-configuration`

Authentication and claim extraction use the ID token. Ensure your provider includes required claims (email, roles, groups) in the ID token, not just the access token or UserInfo endpoint.

Install

Enable the plugin in Traefik's static configuration:

# traefik.yml
experimental:
  plugins:
    traefikoidc:
      moduleName: github.com/lukaszraczylo/traefikoidc
      version: v0.7.10

Then attach the middleware in your dynamic configuration (see Quickstart below).

This middleware tracks the current Traefik helm chart release. If it fails to load, update Traefik first.

Verify release signatures

Release checksums are signed with cosign keyless signing:

cosign verify-blob \
  --certificate-identity-regexp "https://github.com/lukaszraczylo/traefikoidc/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle "traefikoidc_v<version>_checksums.txt.sigstore.json" \
  traefikoidc_v<version>_checksums.txt

Quickstart

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-auth
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: urn:k8s:secret:traefik-oidc:CLIENT_SECRET
      sessionEncryptionKey: urn:k8s:secret:traefik-oidc:SESSION_KEY
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      postLogoutRedirectURI: /
      # forceHTTPS defaults to true (secure-by-default). Only set false if you
      # serve OIDC over plaintext HTTP for local dev.
      allowedUserDomains: [company.com]
      allowedRolesAndGroups: [admin, developer]
      excludedURLs: [/health, /metrics]

More example configs in examples/.

Required parameters

Parameter	Description
`providerURL`	Issuer URL (used for OIDC discovery).
`clientID`	OAuth 2.0 client ID.
`clientSecret`	OAuth 2.0 client secret. Supports `urn:k8s:secret:ns:name:key`. Required when `clientAuthMethod` is unset, `client_secret_post`, or `client_secret_basic`; optional with `private_key_jwt`.
`sessionEncryptionKey`	Cookie encryption key, min 32 bytes.
`callbackURL`	Callback path, e.g. `/oauth2/callback`.

Common optional parameters

Full reference in docs/CONFIGURATION.md.

Parameter	Default	Purpose
`forceHTTPS`	`true`	Forces `https://` in redirect URIs. Leave at default behind any TLS-terminating LB (AWS ALB, GCP LB, Azure App Gateway). Set `false` only for plaintext HTTP local dev.
`logoutURL`	`callbackURL + "/logout"`	RP-initiated logout path.
`postLogoutRedirectURI`	`/`	Where to send users after logout.
`scopes`	appended to `openid profile email`	Extra OAuth scopes. Set `overrideScopes: true` to replace defaults.
`excludedURLs`	none	Prefix-matched paths that bypass auth.
`allowedUserDomains`	none	Restrict to email domains.
`allowedUsers`	none	Restrict to specific addresses (or claim values when `userIdentifierClaim != email`).
`allowedRolesAndGroups`	none	Require any of these roles/groups from ID-token claims.
`roleClaimName` / `groupClaimName`	`roles` / `groups`	For namespaced claims (Auth0).
`userIdentifierClaim`	`email`	Use `sub`, `oid`, `upn`, or `preferred_username` for users without email.
`enablePKCE`	`false`	PKCE on the auth code flow.
`cookieDomain`	auto	Set explicitly for multi-subdomain setups (`.example.com`).
`cookiePrefix`	`_oidc_raczylo_`	Unique prefix per middleware instance to isolate sessions.
`sessionMaxAge`	`86400`	Session lifetime in seconds.
`refreshGracePeriodSeconds`	`60`	Proactively refresh tokens this many seconds before expiry.
`maxRefreshTokenAgeSeconds`	`21600`	Heuristic max stored refresh-token lifetime (6h). Past this, the plugin treats the RT as expired without contacting the IdP — returns 401 to AJAX, full re-auth on navigations. Set `0` to disable. Tune to match your IdP's RT TTL.
`rateLimit`	`100`	Requests/sec. Min `10`.
`logLevel`	`info`	`debug`, `info`, `error`.
`audience`	`clientID`	Custom access-token audience (Auth0 custom APIs).
`strictAudienceValidation`	`false`	Reject mismatched audiences. Set `true` in production.
`allowOpaqueTokens` / `requireTokenIntrospection`	`false`	Accept opaque access tokens via RFC 7662.
`disableReplayDetection`	`false`	Disable JTI cache. Use Redis instead for multi-replica.
`allowPrivateIPAddresses`	`false`	Permit private-IP `providerURL` (internal Keycloak, etc.).
`minimalHeaders`	`false`	Reduce forwarded headers (mitigates HTTP 431).
`stripAuthCookies`	`false`	Strip OIDC cookies from backend hop (mitigates HTTP 431).
`caCertPath` / `caCertPEM`	none	Trust an internal CA for the provider's TLS.
`insecureSkipVerify`	`false`	Local dev only. Disables TLS verification, logs a security warning.
`clientAuthMethod`	`client_secret_post`	Client auth method. Set `private_key_jwt` for RFC 7523 JWT assertions (Entra ID, Okta, Auth0, Keycloak). See Client authentication via private key JWT.
`clientAssertionPrivateKey`	none	Inline PEM private key for `private_key_jwt`. Mutually exclusive with `clientAssertionKeyPath`.
`clientAssertionKeyPath`	none	File path to PEM private key for `private_key_jwt`.
`clientAssertionKeyID`	none	JWS `kid` header. Required when `clientAuthMethod=private_key_jwt`; must match the public key registered with the IdP.
`clientAssertionAlg`	`RS256`	JWS alg for `private_key_jwt`. Supported: `RS256/384/512`, `PS256/384/512`, `ES256/384/512`.
`enableBackchannelLogout` / `backchannelLogoutURL`	`false` / none	OIDC Back-Channel Logout (server-to-server).
`enableFrontchannelLogout` / `frontchannelLogoutURL`	`false` / none	OIDC Front-Channel Logout (iframe).
`redis`	disabled	See docs/REDIS.md.
`dynamicClientRegistration`	disabled	See docs/DCR.md.

Production gotchas

TLS termination at a load balancer

forceHTTPS defaults to true, so redirect URIs always use https://. This is the right default behind AWS ALB, GCP LB, Azure App Gateway, or any LB that terminates TLS — X-Forwarded-Proto is unreliable (ALB may overwrite it).

Only set forceHTTPS: false when you actually serve OIDC over plaintext HTTP (local dev). See issue #82.

Multi-replica deployments

Each replica keeps its own in-memory JTI cache → false positive "token replay detected" when the same token hits different replicas. Two options:

Set disableReplayDetection: true (loses replay protection).
Enable Redis for shared state (recommended) — see docs/REDIS.md.

For IdP-initiated logout (back/front-channel) in multi-replica setups, Redis is required so a logout on one instance invalidates sessions on the others.

Multiple middleware instances on the same host

Each instance must use a unique cookiePrefix and sessionEncryptionKey, otherwise a session minted by one instance can grant access through another. See issue #87.

SSE and WebSocket endpoints

Browser clients cannot follow an OIDC 302 redirect on an SSE stream or a WebSocket upgrade. The middleware handles this automatically:

SSE (Accept: text/event-stream) and WebSocket (Upgrade: websocket) requests skip the OIDC redirect.
They are not unauthenticated — a valid encrypted session cookie is required, otherwise the request is rejected. The session must already exist (i.e. the user logged in via a normal HTTP page first).
X-Forwarded-User is forwarded from the session.
Validation is cookie-only (no JWK fetch), so streaming keeps working during brief IdP outages.

No configuration needed — this is implicit behavior.

HTTP 431 from backends

Either the ID token or the chunked OIDC cookies overflow your backend's header buffer. Combine these as needed:

minimalHeaders: true     # drop X-Auth-Request-Token et al.
stripAuthCookies: true   # strip _oidc_raczylo_* cookies on the backend hop

Cookies remain in the browser; only the Traefik→backend hop is affected. See #64, #122.

Internal CA for the provider

If the provider's TLS cert is signed by a private CA (self-hosted GitLab, internal Keycloak, ADFS):

caCertPath: /etc/ssl/certs/internal-ca.pem
# or, inline:
caCertPEM: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

Both can be combined. An unparseable bundle fails the plugin at startup. See #125.

Client authentication via private key JWT

Use when your IdP enforces short-lived secrets or pushes secretless client auth — Microsoft Entra ID / Azure AD, Okta, Auth0, Keycloak. Instead of sending a static clientSecret, the plugin signs a short-lived JWT and submits it as client_assertion per RFC 7523.

Minimal config:

clientAuthMethod: private_key_jwt
clientAssertionKeyPath: /etc/traefik/oidc/client-key.pem
clientAssertionKeyID: my-key-2026
# clientAssertionAlg: RS256   # default; or PS256/384/512, ES256/384/512

Or inline:

clientAuthMethod: private_key_jwt
clientAssertionPrivateKey: |
  -----BEGIN PRIVATE KEY-----
  ...
  -----END PRIVATE KEY-----
clientAssertionKeyID: my-key-2026

Accepted PEM forms: PKCS#8 (PRIVATE KEY), PKCS#1 (RSA PRIVATE KEY), SEC1 (EC PRIVATE KEY). The assertion uses iss=sub=clientID, aud=tokenURL, 60s lifetime, random hex jti per request. Sent on /token (auth-code + refresh) and /revoke. The kid must match the public key registered with the IdP.

clientSecret becomes optional with private_key_jwt. Existing client_secret_post setups are unaffected. Keys are parsed once at startup — rotation requires a Traefik reload.

See issue #135.

Environment variable names containing `API`

Traefik reserves TRAEFIK_API_*. User vars whose name contains API (e.g. OIDC_ENCRYPTION_SECRET_API) make the plugin fail with invalid handler type: <nil>. Rename to anything without the literal API substring. See #98.

Templated headers

Forward identity to backends via Go templates over ID-token claims and tokens:

headers:
  - name: X-User-Email
    value: "{{{{.Claims.email}}}}"
  - name: Authorization
    value: "Bearer {{{{.AccessToken}}}}"
  - name: X-User-Roles
    value: "{{{{range $i, $e := .Claims.roles}}}}{{{{if $i}}}},{{{{end}}}}{{{{$e}}}}{{{{end}}}}"

Available bindings: .Claims.<field>, .AccessToken, .IdToken, .RefreshToken. Names are case-sensitive (.Claims, not .claims).

Escape with quadruple braces. If you see can't evaluate field AccessToken in type bool, Traefik's YAML parser ate your {{ }}. The fix that actually works is {{{{ }}}} — the YAML pass turns it into {{ }} for the Go template engine. Other escaping tricks (literal blocks, single quotes) do not work reliably.

Default downstream headers

When a request is authenticated, the middleware sets:

Header	Notes
`X-Forwarded-User`	User's email (always).
`X-User-Groups`	Comma-separated.
`X-User-Roles`	Comma-separated.
`X-Auth-Request-User`	User's email.
`X-Auth-Request-Redirect`	Original request URI.
`X-Auth-Request-Token`	Full ID token — the largest header; suppressed by `minimalHeaders`.

Plus security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy) controlled by the securityHeaders section — see docs/CONFIGURATION.md.

Common errors

Symptom	Cause
`Token verification failed`	Wrong/unreachable `providerURL`, or clock skew.
`Session encryption key too short`	`sessionEncryptionKey` is < 32 bytes.
`No matching public key found`	JWKS endpoint down, or `kid` mismatch.
`Access denied: Your email domain is not allowed`	User's domain not in `allowedUserDomains`.
`Access denied: You do not have any of the allowed roles or groups`	Claims missing or not in `allowedRolesAndGroups`.
`can't evaluate field AccessToken in type bool`	Template not escaped — use `{{{{ }}}}`.
`tls: failed to verify certificate: x509: certificate signed by unknown authority`	Internal CA — set `caCertPath` / `caCertPEM`.
`invalid handler type: <nil>`	Env var name contains `API` — rename it.
`false positive replay detected`	Multi-replica without Redis — see Multi-replica deployments.
Google sessions expire after ~1h	Consent screen still in "Testing" mode. Do not add `offline_access` — Google rejects it; the middleware sets `access_type=offline` automatically.

Provider-specific issues (Keycloak mappers, Azure AD group overage, Auth0 namespaced claims, Cognito regions, GitLab self-hosted) live in docs/PROVIDERS.md.

Set logLevel: debug to surface detail.

License

See LICENSE.