Traefik OIDC Middleware

This middleware replaces the need for forward-auth and oauth2-proxy when using Traefik as a reverse proxy to support OpenID Connect (OIDC) authentication.

Overview

The Traefik OIDC middleware provides a complete OIDC authentication solution with these key features:

Universal provider support: Works with 9+ OIDC providers including Google, Azure AD, Auth0, Okta, Keycloak, AWS Cognito, GitLab, and more
Automatic provider detection: Automatically detects and configures provider-specific settings
Dynamic Client Registration (RFC 7591): Automatic client registration with OIDC providers without manual pre-registration, with Redis storage support for multi-replica deployments
Automatic scope filtering: Intelligently filters OAuth scopes based on provider capabilities declared in OIDC discovery documents, preventing authentication failures with unsupported scopes
Security headers: Comprehensive security headers with CORS, CSP, HSTS, and custom profiles
Domain restrictions: Limit access to specific email domains or individual users
Role-based access control: Restrict access based on roles and groups from OIDC claims
Session management: Secure session handling with automatic token refresh
Rate limiting: Protection against brute force attacks
Excluded paths: Configure public URLs that bypass authentication
Custom headers: Template-based headers using OIDC claims and tokens
Comprehensive logging: Configurable log levels for debugging and monitoring

Supported OIDC Providers

Provider	Support Level	Refresh Tokens	Auto-Detection	Key Features
Google	✅ Full OIDC	✅ Yes	✅ `accounts.google.com`	Auto-config, Workspace support
Azure AD	✅ Full OIDC	✅ Yes	✅ `login.microsoftonline.com`	Multi-tenant, group claims
Auth0	✅ Full OIDC	✅ Yes	✅ `*.auth0.com`	Custom claims, flexible rules
Okta	✅ Full OIDC	✅ Yes	✅ `*.okta.com`	Enterprise SSO, MFA support
Keycloak	✅ Full OIDC	✅ Yes	✅ `/auth/realms/` path	Self-hosted, full customization
AWS Cognito	✅ Full OIDC	✅ Yes	✅ `cognito-idp.*.amazonaws.com`	Managed service, regional
GitLab	✅ Full OIDC	✅ Yes	✅ `gitlab.com`	Self-hosted support
GitHub	⚠️ OAuth 2.0 Only	❌ No	✅ `github.com`	API access only, no claims
Generic OIDC	✅ Full OIDC	✅ Yes	✅ Any endpoint	RFC-compliant providers

Provider Capabilities Matrix

Feature	Google	Azure AD	Auth0	Okta	Keycloak	Cognito	GitLab	GitHub	Generic
ID Tokens	✅	✅	✅	✅	✅	✅	✅	❌	✅
Refresh Tokens	✅	✅	✅	✅	✅	✅	✅	❌	✅
Auto-Configuration	✅	✅	✅	✅	✅	✅	✅	✅	✅
Custom Claims	Limited	✅	✅	✅	✅	✅	Limited	❌	Varies
Group/Role Claims	Limited	✅	✅	✅	✅	✅	Limited	❌	Varies
Domain Restriction	✅ (hd claim)	✅	✅	✅	✅	✅	✅	❌	Varies
Self-Hosted	❌	❌	❌	❌	✅	❌	✅	❌	✅
Enterprise Features	✅	✅	✅	✅	✅	✅	✅	❌	Varies

Important: GitHub uses OAuth 2.0 (not OpenID Connect) and only provides access tokens. Use it for API access only, not for user authentication with claims. All other providers support full OIDC with ID tokens and user claims.

Important Note on Token Validation: This middleware performs authentication and claim extraction based on the ID Token provided by the OIDC provider. It does not primarily use the Access Token for these purposes (though the Access Token is available for templated headers if needed). Therefore, ensure that all necessary claims (e.g., email, roles, custom attributes) are included in the ID Token by your OIDC provider's configuration.

The middleware has been tested with Google, Azure AD, Auth0, Okta, Keycloak, AWS Cognito, GitLab, GitHub (OAuth 2.0), and other standard OIDC providers. It includes automatic provider detection and special handling for provider-specific requirements.

Performance and Memory Management

This middleware includes advanced memory management features to ensure stable operation under high load:

Bounded caches: All internal caches (metadata, sessions, tokens) have configurable size limits with LRU eviction
Automatic cleanup: Background goroutines periodically clean up expired sessions and tokens
Memory monitoring: Built-in memory leak detection and prevention
Graceful degradation: Continues operating safely even under memory pressure
Zero goroutine leaks: All background tasks are properly managed and terminated on shutdown

Traefik Version Compatibility

This middleware follows closely the current Traefik helm chart versions. If the plugin fails to load, it's time to update to the latest version of the Traefik helm chart.

Installation

As a Traefik Plugin

Enable the plugin in your Traefik static configuration:

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

Configure the middleware in your dynamic configuration (see examples below).

Verifying Release Signatures

All release checksums are signed with cosign using keyless signing. To verify:

# Download the checksum file and its sigstore bundle from the release
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

Local Development with Docker Compose

For local development or testing, you can use the provided Docker Compose setup:

cd docker
docker-compose up -d

This will start Traefik with the OIDC middleware and two test services.

Configuration Options

The middleware supports the following configuration options:

Required Parameters

Parameter	Description	Example
`providerURL`	The base URL of the OIDC provider	`https://accounts.google.com`
`clientID`	The OAuth 2.0 client identifier	`1234567890.apps.googleusercontent.com`
`clientSecret`	The OAuth 2.0 client secret	`your-client-secret`
`sessionEncryptionKey`	Key used to encrypt session data (must be at least 32 bytes long)	`potato-secret-is-at-least-32-bytes-long`
`callbackURL`	The path where the OIDC provider will redirect after authentication	`/oauth2/callback`

Optional Parameters

Parameter	Description	Default	Example
`logoutURL`	The path for handling logout requests	`callbackURL + "/logout"`	`/oauth2/logout`
`postLogoutRedirectURI`	The URL to redirect to after logout	`/`	`/logged-out-page`
`scopes`	OAuth 2.0 scopes to use for authentication	`["openid", "profile", "email"]` (always included by default)	`["roles", "custom_scope"]` (appended to defaults)
`overrideScopes`	When true, replaces default scopes with provided scopes instead of appending	`false`	`true` (use only the scopes explicitly provided)
`logLevel`	Sets the logging verbosity	`info`	`debug`, `info`, `error`
`forceHTTPS`	Forces HTTPS scheme for redirect URIs (REQUIRED for TLS termination at load balancer like AWS ALB)	`false` (when not specified)	`true`, `false`
`rateLimit`	Sets the maximum number of requests per second	`100`	`500`
`excludedURLs`	Lists paths that bypass authentication	none	`["/health", "/metrics", "/public"]`
`allowedUserDomains`	Restricts access to specific email domains	none	`["company.com", "subsidiary.com"]`
`allowedUsers`	A list of specific email addresses that are allowed access	none	`["user1@example.com", "user2@another.org"]`
`allowedRolesAndGroups`	Restricts access to users with specific roles or groups	none	`["admin", "developer"]`
`roleClaimName`	JWT claim name for extracting user roles (supports namespaced claims for Auth0)	`"roles"`	`"https://myapp.com/roles"`, `"user_roles"`
`groupClaimName`	JWT claim name for extracting user groups (supports namespaced claims for Auth0)	`"groups"`	`"https://myapp.com/groups"`, `"user_groups"`
`userIdentifierClaim`	JWT claim to use as user identifier (for users without email, e.g., Azure AD service accounts)	`"email"`	`"sub"`, `"oid"`, `"upn"`, `"preferred_username"`
`revocationURL`	The endpoint for revoking tokens	auto-discovered	`https://accounts.google.com/revoke`
`oidcEndSessionURL`	The provider's end session endpoint	auto-discovered	`https://accounts.google.com/logout`
`enablePKCE`	Enables PKCE (Proof Key for Code Exchange) for authorization code flow	`false`	`true`, `false`
`refreshGracePeriodSeconds`	Seconds before token expiry to attempt proactive refresh	`60`	`120`
`cookieDomain`	Explicit domain for session cookies (important for multi-subdomain setups)	auto-detected	`.example.com`, `app.example.com`
`cookiePrefix`	Custom prefix for session cookie names (for isolating multiple middleware instances)	`_oidc_raczylo_`	`_oidc_userauth_`, `_oidc_admin_`
`sessionMaxAge`	Maximum session age in seconds before requiring re-authentication	`86400` (24 hours)	`3600` (1 hour), `604800` (7 days)
`audience`	Custom audience for access token validation (for Auth0 custom APIs, etc.)	`clientID`	`https://my-api.example.com`
`strictAudienceValidation`	Reject sessions with access token audience mismatch (prevents token confusion attacks)	`false`	`true`
`allowOpaqueTokens`	Enable opaque (non-JWT) access token support via RFC 7662 introspection	`false`	`true`
`requireTokenIntrospection`	Require introspection for opaque tokens (force validation, no fallback)	`false`	`true`
`headers`	Custom HTTP headers with templates that can access OIDC claims and tokens	none	See "Templated Headers" section
`securityHeaders`	Configure security headers including CSP, HSTS, CORS, and custom headers	enabled with default profile	See "Security Headers Configuration" section
`disableReplayDetection`	Disable JTI-based replay attack detection for multi-replica deployments	`false`	`true`
`allowPrivateIPAddresses`	Allow private IP addresses in provider URLs (for internal networks with Keycloak, etc.)	`false`	`true`
`minimalHeaders`	Reduce forwarded headers to prevent "431 Request Header Fields Too Large" errors	`false`	`true`
`enableBackchannelLogout`	Enable OIDC Back-Channel Logout (IdP-initiated logout via server-to-server POST)	`false`	`true`
`backchannelLogoutURL`	The path for receiving backchannel logout tokens from the IdP	none	`/backchannel-logout`
`enableFrontchannelLogout`	Enable OIDC Front-Channel Logout (IdP-initiated logout via iframe)	`false`	`true`
`frontchannelLogoutURL`	The path for receiving front-channel logout requests from the IdP	none	`/frontchannel-logout`
`redis`	Redis cache configuration for distributed deployments	disabled	See "Redis Cache" section

⚠️ IMPORTANT - TLS Termination at Load Balancer:

If you're running Traefik behind a load balancer (AWS ALB, Google Cloud Load Balancer, Azure Application Gateway, etc.) that terminates TLS:

You MUST set forceHTTPS: true in your configuration

Without this setting, redirect URIs will use http:// instead of https://, causing OAuth callback failures

This is especially critical for AWS ALB which may overwrite the X-Forwarded-Proto header

Default behavior:

When forceHTTPS is not specified in your config → defaults to false (Go zero value)

When forceHTTPS: true is explicitly set → always uses https:// for redirect URIs

When forceHTTPS: false is explicitly set → scheme detection based on headers/TLS

See GitHub Issue #82 for details.

Scope Configuration

Scope Behavior

The middleware supports two modes for handling OAuth 2.0 scopes, controlled by the overrideScopes parameter:

Default Append Mode (`overrideScopes: false`)

By default, the middleware uses an append behavior for OAuth 2.0 scopes:

Default scopes are always included: ["openid", "profile", "email"]
User-provided scopes are appended to the defaults with automatic deduplication
The final scope list maintains the order: defaults first, then user scopes

Override Mode (`overrideScopes: true`)

When overrideScopes is set to true, the middleware uses replacement behavior:

Default scopes are not automatically included
Only the scopes explicitly provided in the scopes field are used
You must include all required scopes explicitly, including openid if needed

Examples:

Default behavior (no custom scopes):

# No scopes field specified
# Result: ["openid", "profile", "email"]

Default append behavior:

scopes:
  - roles
  - custom_scope
# Result: ["openid", "profile", "email", "roles", "custom_scope"]

Overlapping scopes with append (automatic deduplication):

scopes:
  - openid      # Duplicate - will be deduplicated
  - roles
  - profile     # Duplicate - will be deduplicated
  - permissions
# Result: ["openid", "profile", "email", "roles", "permissions"]

Using override mode:

overrideScopes: true
scopes:
  - openid
  - profile
  - custom_scope
# Result: ["openid", "profile", "custom_scope"]

Empty scopes list with default behavior:

scopes: []
# Result: ["openid", "profile", "email"]

Empty scopes list with override mode:

overrideScopes: true
scopes: []
# Result: [] (Warning: empty scopes may cause authentication to fail)

The default append behavior ensures essential OIDC scopes are always present, while the override mode gives you complete control over the exact scopes requested from the provider.

Auth0 Audience Validation & Security

The middleware provides comprehensive support for Auth0 audience validation to prevent token confusion attacks. Auth0 can issue tokens in three different scenarios, each requiring specific configuration.

Understanding Token Audiences

Per OAuth 2.0 and OIDC specifications:

ID Tokens: MUST have aud = client_id (OIDC Core 1.0 spec)
Access Tokens: Can have custom audiences (e.g., API identifiers)

Proper audience validation prevents token confusion attacks where a token intended for one API is used to access another API.

Auth0 Scenarios

Scenario 1: Custom API Audience ✅ (RECOMMENDED)

Configuration:

audience: "https://my-api.example.com"  # Your API identifier from Auth0
strictAudienceValidation: true          # Enforce strict validation

Result: Fully secure, OIDC compliant with proper access token audience validation.

Scenario 2: Default Audience ⚠️ (USE WITH CAUTION)

Configuration:

# audience not specified (defaults to client_id)
strictAudienceValidation: true  # Recommended: reject mismatched tokens

Behavior: Access tokens may not contain client_id in audience, triggering security warnings. Set strictAudienceValidation: true to reject such sessions.

Scenario 3: Opaque Access Tokens ✅ (SUPPORTED)

Configuration:

allowOpaqueTokens: true              # Enable opaque token support
requireTokenIntrospection: true      # Require introspection (recommended)

Result: Secure with OAuth 2.0 Token Introspection (RFC 7662).

Security Configuration Options

Option	Purpose	Recommended Value
`audience`	Expected audience for access tokens	Your API identifier or leave empty
`strictAudienceValidation`	Reject sessions with audience mismatch	`true` for production
`allowOpaqueTokens`	Accept non-JWT access tokens	`true` if provider issues opaque tokens
`requireTokenIntrospection`	Force introspection for opaque tokens	`true` when `allowOpaqueTokens=true`

Complete Auth0 Configuration Examples

Production Configuration (Scenario 1):

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-auth0-secure
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-auth0-domain.auth0.com
      clientID: your-auth0-client-id
      clientSecret: your-auth0-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      audience: "https://my-api.example.com"
      strictAudienceValidation: true
      allowedRolesAndGroups:
        - "https://your-app.com/roles:admin"
        - editor

Opaque Token Configuration (Scenario 3):

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-auth0-opaque
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-auth0-domain.auth0.com
      clientID: your-auth0-client-id
      clientSecret: your-auth0-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      allowOpaqueTokens: true
      requireTokenIntrospection: true
      strictAudienceValidation: true

For detailed Auth0 configuration including all three scenarios, troubleshooting, and security best practices, see AUTH0_AUDIENCE_GUIDE.md.

Security Headers Configuration

The middleware includes comprehensive security headers support to protect your applications against common web vulnerabilities. Security headers are applied to all authenticated responses.

Security Features

Content Security Policy (CSP) - Prevents XSS and code injection
HTTP Strict Transport Security (HSTS) - Forces HTTPS connections
Frame Options - Protects against clickjacking attacks
XSS Protection - Browser-level XSS filtering
Content Type Options - Prevents MIME type sniffing
Referrer Policy - Controls referrer information sharing
CORS Headers - Complete Cross-Origin Resource Sharing support
Custom Headers - Add any additional security headers

Security Profiles

Choose from predefined security profiles or create custom configurations:

Profile	Use Case	Security Level	CORS Enabled
`default`	Standard web applications	High	Disabled
`strict`	Maximum security applications	Very High	Disabled
`development`	Local development	Medium	Enabled (localhost)
`api`	API endpoints	High	Configurable
`custom`	Custom requirements	Configurable	Configurable

Configuration Examples

Default Security (Recommended)

securityHeaders:
  enabled: true
  profile: "default"

Strict Security

securityHeaders:
  enabled: true
  profile: "strict"

API with CORS

securityHeaders:
  enabled: true
  profile: "api"
  corsEnabled: true
  corsAllowedOrigins: 
    - "https://your-frontend.com"
    - "https://*.example.com"
  corsAllowCredentials: true

Custom Configuration

securityHeaders:
  enabled: true
  profile: "custom"
  
  # Content Security Policy
  contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'"
  
  # HSTS Settings
  strictTransportSecurity: true
  strictTransportSecurityMaxAge: 31536000  # 1 year
  strictTransportSecuritySubdomains: true
  strictTransportSecurityPreload: true
  
  # Frame and Content Protection
  frameOptions: "DENY"
  contentTypeOptions: "nosniff"
  xssProtection: "1; mode=block"
  referrerPolicy: "strict-origin-when-cross-origin"
  
  # CORS Configuration
  corsEnabled: true
  corsAllowedOrigins: ["https://app.example.com"]
  corsAllowedMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
  corsAllowedHeaders: ["Authorization", "Content-Type", "X-Requested-With"]
  corsAllowCredentials: true
  corsMaxAge: 86400
  
  # Custom Headers
  customHeaders:
    X-Custom-Header: "custom-value"
    X-API-Version: "v1"
  
  # Server Identification
  disableServerHeader: true
  disablePoweredByHeader: true

Security Headers Parameters

Parameter	Description	Default	Example
`enabled`	Enable/disable security headers	`true`	`true`, `false`
`profile`	Security profile to use	`default`	`default`, `strict`, `development`, `api`, `custom`
`contentSecurityPolicy`	CSP header value	Profile-based	`"default-src 'self'"`
`strictTransportSecurity`	Enable HSTS	`true`	`true`, `false`
`strictTransportSecurityMaxAge`	HSTS max age in seconds	`31536000`	`86400`
`strictTransportSecuritySubdomains`	Include subdomains in HSTS	`true`	`true`, `false`
`strictTransportSecurityPreload`	Enable HSTS preload	`true`	`true`, `false`
`frameOptions`	X-Frame-Options header	`DENY`	`DENY`, `SAMEORIGIN`, `ALLOW-FROM uri`
`contentTypeOptions`	X-Content-Type-Options header	`nosniff`	`nosniff`
`xssProtection`	X-XSS-Protection header	`1; mode=block`	`1; mode=block`
`referrerPolicy`	Referrer-Policy header	`strict-origin-when-cross-origin`	`no-referrer`
`corsEnabled`	Enable CORS headers	`false`	`true`, `false`
`corsAllowedOrigins`	Allowed CORS origins	`[]`	`["https://app.com", "https://*.example.com"]`
`corsAllowedMethods`	Allowed CORS methods	`["GET", "POST", "OPTIONS"]`	`["GET", "POST", "PUT", "DELETE"]`
`corsAllowedHeaders`	Allowed CORS headers	`["Authorization", "Content-Type"]`	`["X-Custom-Header"]`
`corsAllowCredentials`	Allow credentials in CORS	`false`	`true`, `false`
`corsMaxAge`	CORS preflight cache time	`86400`	`3600`
`customHeaders`	Additional custom headers	`{}`	`{"X-Custom": "value"}`
`disableServerHeader`	Remove Server header	`true`	`true`, `false`
`disablePoweredByHeader`	Remove X-Powered-By header	`true`	`true`, `false`
`permissionsPolicy`	Permissions-Policy header	``	`"geolocation=(), camera=(), microphone=()"`
`crossOriginEmbedderPolicy`	Cross-Origin-Embedder-Policy header	``	`"require-corp"`, `"credentialless"`, `"unsafe-none"`
`crossOriginOpenerPolicy`	Cross-Origin-Opener-Policy header	``	`"same-origin"`, `"same-origin-allow-popups"`, `"unsafe-none"`
`crossOriginResourcePolicy`	Cross-Origin-Resource-Policy header	``	`"same-origin"`, `"same-site"`, `"cross-origin"`

CORS Wildcard Support

The middleware supports flexible CORS origin patterns:

corsAllowedOrigins:
  - "https://example.com"              # Exact match
  - "https://*.example.com"            # Subdomain wildcard
  - "http://localhost:*"               # Port wildcard (development)
  - "*"                                # Allow all (not recommended)

Advanced Configuration

The middleware provides several advanced configuration options for production environments.

Provider-Specific Optimizations

The middleware automatically optimizes for each OIDC provider:

Google: Automatically configures access_type=offline and prompt=consent for refresh tokens
Azure AD: Optimized multi-tenant support and group claim handling
Auth0: Enhanced custom claim processing and namespace support
Keycloak: Self-hosted deployment optimizations
AWS Cognito: Regional endpoint handling and user pool integration

Token Management

Automatic token refresh: Proactively refreshes tokens before expiration
Token validation: Comprehensive JWT validation with security checks
Grace period: Configurable time window for token refresh
Session handling: Secure session management with encrypted storage

Configuration Examples

High-Throughput Configuration

# Optimized for high-traffic environments
rateLimit: 1000
refreshGracePeriodSeconds: 300
securityHeaders:
  enabled: true
  profile: "api"
  corsEnabled: true
  corsMaxAge: 86400

High-Security Configuration

# Maximum security for sensitive environments
rateLimit: 50
allowedUserDomains: ["company.com"]
allowedRolesAndGroups: ["admin", "developer"]
securityHeaders:
  enabled: true
  profile: "strict"
  corsEnabled: false

Development Configuration

# Development-friendly settings
logLevel: "debug"
forceHTTPS: false
securityHeaders:
  enabled: true
  profile: "development"
  corsEnabled: true
  corsAllowedOrigins: ["http://localhost:*"]

Multi-Replica Deployment Configuration

When running multiple Traefik replicas with the OIDC plugin, you may encounter false positive replay detection errors. Each replica maintains its own in-memory JTI (JWT Token ID) cache, causing legitimate token reuse to be flagged as replay attacks.

Problem: When the same valid token hits different replicas:

Request → Replica A → JTI added to Replica A's cache ✓
Request → Replica B → JTI NOT in Replica B's cache ✓
Request → Replica A → ❌ FALSE POSITIVE: "token replay detected"

Solution 1 (Simple): Disable replay detection for distributed deployments:

disableReplayDetection: true  # Disable JTI replay detection for multi-replica setups

Solution 2 (Recommended): Use Redis cache backend for shared state (see Redis Cache section)

Security Note: When disableReplayDetection: true:

✅ Token signatures still validated
✅ Expiration still checked
✅ All other claims still verified
❌ JTI replay check skipped

Example Configuration:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-multi-replica
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      disableReplayDetection: true  # Required for multi-replica deployments without Redis

Recommendation: For single-instance deployments, leave this setting at false (default) to maintain replay attack protection. For multi-replica deployments, use the Redis cache backend for proper replay detection across all instances.

Redis Cache (Optional)

The plugin supports optional Redis caching for multi-replica deployments. This solves issues with JTI replay detection and session management when running multiple Traefik instances behind a load balancer.

✨ Yaegi Compatible: Redis support is implemented using a pure-Go RESP protocol client that works seamlessly with Traefik's Yaegi interpreter (no unsafe package). Full Redis functionality is available for both dynamic plugin loading and pre-compiled deployments.

Why Use Redis Cache?

When running multiple Traefik replicas, each instance maintains its own in-memory cache for:

JTI (JWT Token ID) replay detection
Session data
Token metadata

Without a shared cache, you may experience:

False positive replay detection errors
Session inconsistencies between replicas
Users needing to re-authenticate when hitting different instances

Basic Configuration

Redis is configured through Traefik's dynamic configuration (YAML, labels, etc.):

# Enable Redis cache in your middleware configuration
redis:
  enabled: true
  address: "localhost:6379"
  password: "your-password"  # Optional
  db: 0
  keyPrefix: "traefikoidc:"

Configuration Priority

The plugin uses the following priority for Redis configuration:

Traefik Dynamic Configuration (PRIMARY) - Configure via YAML files or Docker/Kubernetes labels
Environment Variables (FALLBACK) - Used only when not set in Traefik config

This approach allows you to manage all settings through Traefik's configuration system while maintaining backward compatibility with environment variables.

Configuration Options

Parameter	Description	Default	Example
`enabled`	Enable Redis caching	`false`	`true`
`address`	Redis server address	-	`redis:6379`
`password`	Redis password	-	`YOUR_PASSWORD`
`db`	Database number	`0`	`1`
`keyPrefix`	Key prefix for namespacing	`traefikoidc:`	`myapp:`
`cacheMode`	Cache mode: `redis`, `hybrid`, `memory`	`redis`	`hybrid`
`poolSize`	Connection pool size	`10`	`20`
`connectTimeout`	Connection timeout (seconds)	`5`	`10`
`readTimeout`	Read timeout (seconds)	`3`	`5`
`writeTimeout`	Write timeout (seconds)	`3`	`5`
`enableTLS`	Enable TLS	`false`	`true`
`tlsSkipVerify`	Skip TLS verification	`false`	`true`
`enableCircuitBreaker`	Circuit breaker for failures	`true`	`true`
`circuitBreakerThreshold`	Failures before circuit opens	`5`	`10`
`circuitBreakerTimeout`	Circuit reset timeout (seconds)	`60`	`30`
`enableHealthCheck`	Periodic health checks	`true`	`true`
`healthCheckInterval`	Health check interval (seconds)	`30`	`60`

Environment Variables (Fallback)

If not configured through Traefik, these environment variables can be used as fallback:

REDIS_ENABLED - Enable Redis cache
REDIS_ADDRESS - Redis server address
REDIS_PASSWORD - Redis password
REDIS_DB - Database number
REDIS_KEY_PREFIX - Key prefix
REDIS_CACHE_MODE - Cache mode
REDIS_POOL_SIZE - Connection pool size
REDIS_CONNECT_TIMEOUT - Connection timeout
REDIS_READ_TIMEOUT - Read timeout
REDIS_WRITE_TIMEOUT - Write timeout
REDIS_ENABLE_TLS - Enable TLS
REDIS_TLS_SKIP_VERIFY - Skip TLS verification

Cache Modes

The plugin supports three cache modes:

memory (default): In-memory cache only, suitable for single-instance deployments
redis: Redis-only cache, all data stored in Redis
hybrid: Two-tier caching with local memory cache + Redis backend for optimal performance

Example Configurations

Docker Compose with Redis

services:
  redis:
    image: redis:alpine
    command: redis-server --requirepass yourpassword

  traefik:
    image: traefik:v3.2
    # ... rest of your Traefik configuration
    labels:
      # Configure the OIDC middleware with Redis
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.clientID=your-client-id"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.clientSecret=your-secret"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.providerURL=https://auth.example.com"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.callbackURL=/oauth2/callback"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.sessionEncryptionKey=your-64-char-key"
      # Redis configuration via labels
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.redis.enabled=true"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.redis.address=redis:6379"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.redis.password=yourpassword"
      - "traefik.http.middlewares.oidc.plugin.traefikoidc.redis.cacheMode=hybrid"

Kubernetes with Redis

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-redis
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: your-encryption-key
      callbackURL: /oauth2/callback
      redis:
        enabled: true
        address: "redis-service.redis-namespace:6379"
        password: "urn:k8s:secret:redis-secret:password"
        db: 0
        keyPrefix: "traefikoidc"
        cacheMode: "hybrid"

Advanced Redis Configuration

See Redis Cache Documentation for:

Detailed architecture overview
High availability setup with Redis Sentinel
Redis Cluster configuration
Performance tuning guidelines
Monitoring and observability
Troubleshooting guide
Migration from memory-only cache

Dynamic Client Registration (RFC 7591)

The middleware supports OIDC Dynamic Client Registration (RFC 7591), allowing automatic client registration with OIDC providers without manual pre-registration. This is useful for:

Multi-tenant deployments: Automatically register clients per tenant
Development environments: Quick setup without manual OAuth app creation
Self-service integrations: Allow applications to self-register

How It Works

When enabled, the middleware discovers the registration_endpoint from the provider's .well-known/openid-configuration
If no clientID is configured, it automatically registers a new client with the provider
The registered client_id and client_secret are cached and optionally persisted to a file
Subsequent requests use the registered credentials

Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-dynamic-registration
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-oidc-provider.com
      # clientID and clientSecret are NOT required when using DCR
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback

      dynamicClientRegistration:
        enabled: true

        # Optional: Initial access token for protected registration endpoints
        initialAccessToken: "your-initial-access-token"

        # Optional: Override the registration endpoint (auto-discovered by default)
        registrationEndpoint: "https://your-provider.com/register"

        # Optional: Persist credentials to file for reuse across restarts
        persistCredentials: true
        credentialsFile: "/tmp/oidc-client-credentials.json"

        # Client metadata for registration
        clientMetadata:
          redirect_uris:
            - "https://your-app.com/oauth2/callback"
          client_name: "My Application"
          application_type: "web"
          grant_types:
            - "authorization_code"
            - "refresh_token"
          response_types:
            - "code"
          token_endpoint_auth_method: "client_secret_basic"
          contacts:
            - "admin@your-app.com"

DCR Configuration Parameters

Parameter	Description	Required	Default
`enabled`	Enable dynamic client registration	Yes	`false`
`initialAccessToken`	Bearer token for protected registration endpoints	No	-
`registrationEndpoint`	Override auto-discovered registration endpoint	No	From discovery
`persistCredentials`	Save registered credentials to file	No	`false`
`credentialsFile`	Path to store/load credentials	No	`/tmp/oidc-client-credentials.json`
`clientMetadata.redirect_uris`	REQUIRED - Redirect URIs for OAuth flow	Yes	-
`clientMetadata.client_name`	Human-readable client name	No	-
`clientMetadata.application_type`	`web` or `native`	No	`web`
`clientMetadata.grant_types`	OAuth grant types	No	`["authorization_code", "refresh_token"]`
`clientMetadata.response_types`	OAuth response types	No	`["code"]`
`clientMetadata.token_endpoint_auth_method`	Authentication method	No	`client_secret_basic`
`clientMetadata.contacts`	Contact email addresses	No	-
`clientMetadata.logo_uri`	URL to client logo	No	-
`clientMetadata.client_uri`	URL to client homepage	No	-
`clientMetadata.policy_uri`	URL to privacy policy	No	-
`clientMetadata.tos_uri`	URL to terms of service	No	-
`clientMetadata.scope`	Space-separated scopes	No	-

Provider Support

DCR support varies by provider:

Provider	DCR Support	Notes
Keycloak	✅ Full	Enable in realm settings
Auth0	✅ Full	Requires Management API token
Okta	✅ Full	Enable Dynamic Client Registration
Azure AD	⚠️ Limited	App Registration API instead
Google	❌ No	Manual registration required
AWS Cognito	❌ No	Manual registration required

Security Considerations

HTTPS Required: Registration endpoints must use HTTPS (except localhost for development)
Initial Access Token: Recommended for production to prevent unauthorized registrations
Credential Persistence: If enabled, ensure the credentials file has appropriate permissions (0600)
Secret Expiration: Monitor client_secret_expires_at and handle rotation if needed

Example: Keycloak with DCR

dynamicClientRegistration:
  enabled: true
  clientMetadata:
    redirect_uris:
      - "https://myapp.example.com/oauth2/callback"
    client_name: "My App - Production"
    application_type: "web"
    grant_types:
      - "authorization_code"
      - "refresh_token"

Usage Examples

Basic Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-basic
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

With Excluded URLs (Public Access Paths)

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-open-urls
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      excludedURLs:
        - /login        # covers /login, /login/me, /login/reminder etc.
        - /public-data
        - /health
        - /metrics

With Email Domain Restrictions

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-domain-restricted
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      allowedUserDomains:
        - company.com
        - subsidiary.com

With Specific User Access

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-specific-users
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      allowedUsers:
        - user1@example.com
        - user2@another.org

With Both Domain and Specific User Access

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-domain-and-users
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      allowedUserDomains:
        - company.com
      allowedUsers:
        - special-user@gmail.com
        - contractor@external.org

When configuring access control:

If only allowedUsers is set, only the specified email addresses will be granted access
If only allowedUserDomains is set, only users with email addresses from those domains will be granted access
If both are set, access is granted if the user's email is in allowedUsers OR their email's domain is in allowedUserDomains
If neither is set, any authenticated user will be granted access
Email matching is case-insensitive

With Role-Based Access Control

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-rbac
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      allowedRolesAndGroups:
        - admin
        - developer

With Cookie Domain Configuration (Multi-Subdomain Setup)

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-multi-subdomain
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      cookieDomain: .example.com  # Allows cookies to be shared across all subdomains
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

Important: The cookieDomain parameter is crucial when running behind a reverse proxy or when your application serves multiple subdomains. Without it, cookies may be created with inconsistent domains, leading to authentication issues like "CSRF token missing in session" errors.

With Multiple Middleware Instances (Session Isolation)

When running multiple middleware instances with different authorization requirements (e.g., one for general users and one for admins), you must use different cookiePrefix values to prevent session sharing between instances:

# Middleware for general user authentication
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-userauth
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://auth.example.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: user-key-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      cookiePrefix: "_oidc_userauth_"  # Unique prefix for this instance
---
# Middleware for admin authentication with stricter requirements
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-adminauth
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://auth.example.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: admin-key-at-least-32-bytes-long  # Different encryption key
      callbackURL: /oauth2/admin/callback  # Different callback URL
      cookiePrefix: "_oidc_adminauth_"  # Different prefix for isolation
      allowedUsers:  # Restricted to specific admin users
        - admin@example.com
        - superadmin@example.com

Security Note: When running multiple instances, ensure you use:

Different cookiePrefix values to prevent cookie name collisions
Different sessionEncryptionKey values for complete session isolation
Different callbackURL paths to avoid routing conflicts

This configuration prevents authorization bypass issues where a user authenticated via the general middleware could access admin-protected routes. See issue #87 for more details.

With Extended Session Duration

For applications that users access infrequently (weekly or monthly), you can extend the session duration beyond the default 24 hours to reduce authentication friction:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-long-session
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://auth.example.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: your-key-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      sessionMaxAge: 604800  # 7 days (in seconds)
      # Other common values:
      # 259200   - 3 days
      # 604800   - 7 days
      # 1209600  - 14 days
      # 2592000  - 30 days

Security Note: Longer session durations improve user experience but increase security risk. Consider your application's security requirements:

High-security apps: Use shorter sessions (3600 = 1 hour)
Standard apps: Default 24 hours balances security and UX
Low-frequency access apps: Extend to 7-30 days for better UX

See issue #91 for more details.

With Custom Logging and Rate Limiting

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-custom-settings
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      logLevel: debug    # Options: debug, info, error (default: info)
      rateLimit: 500     # Requests per second (default: 100)
      forceHTTPS: false  # Default is true for security
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

With Custom Post-Logout Redirect

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-custom-logout
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      postLogoutRedirectURI: /logged-out-page  # Where to redirect after logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

With IdP-Initiated Logout (Backchannel & Front-Channel)

This plugin supports OIDC Back-Channel Logout and OIDC Front-Channel Logout for IdP-initiated single logout.

Backchannel Logout (recommended): The IdP sends a server-to-server POST request with a signed logout_token JWT when a user logs out.

Front-Channel Logout: The IdP loads an iframe with the logout URL to invalidate the session in the browser.

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-idp-logout
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://auth.example.com
      clientID: your-client-id
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout  # RP-initiated logout
      
      # Backchannel Logout (server-to-server)
      enableBackchannelLogout: true
      backchannelLogoutURL: /backchannel-logout
      
      # Front-Channel Logout (iframe-based)
      enableFrontchannelLogout: true
      frontchannelLogoutURL: /frontchannel-logout
      
      # For multi-replica deployments, use Redis to share session invalidations
      redis:
        enabled: true
        address: redis:6379

Note: For multi-replica deployments, you must enable Redis to share session invalidation state across all instances. Otherwise, a logout on one instance won't invalidate sessions on other instances.

IdP Configuration: Configure your IdP to send logout requests to:

Backchannel: https://your-app.example.com/backchannel-logout (POST with logout_token)
Front-Channel: https://your-app.example.com/frontchannel-logout?sid=SESSION_ID&iss=ISSUER (GET in iframe)

With Templated Headers

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-headers
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
      headers:
        # Using double curly braces to escape template expressions
        - name: "X-User-Email"
          value: "{{{{.Claims.email}}}}"
        - name: "X-User-ID"
          value: "{{{{.Claims.sub}}}}"
        - name: "Authorization"
          value: "Bearer {{{{.AccessToken}}}}"
        - name: "X-User-Roles"
          value: "{{{{range $i, $e := .Claims.roles}}}}{{{{if $i}}}},{{{{end}}}}{{{{$e}}}}{{{{end}}}}"
        - name: "X-Is-Admin"
          value: "{{{{if eq .Claims.role \"admin\"}}}}true{{{{else}}}}false{{{{end}}}}"

With PKCE Enabled

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-pkce
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: 1234567890.apps.googleusercontent.com
      clientSecret: your-client-secret
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      enablePKCE: true  # Enables PKCE for added security
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

Provider-Specific Configuration Examples

Google OIDC Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-google
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://accounts.google.com
      clientID: your-google-client-id.apps.googleusercontent.com
      clientSecret: your-google-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
        # Note: DO NOT manually add offline_access scope for Google
        # The middleware automatically handles Google-specific requirements
      refreshGracePeriodSeconds: 300  # Optional: Start refresh 5 min before expiry
      allowedUserDomains:
        - your-gsuite-domain.com  # Optional: Restrict to workspace users

Azure AD Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-azure
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://login.microsoftonline.com/your-tenant-id/v2.0
      clientID: your-azure-ad-client-id
      clientSecret: your-azure-ad-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # For group/role claims, configure in Azure AD Token Configuration
      allowedUserDomains:
        - yourcompany.com
      allowedRolesAndGroups:
        - "group-object-id-1"  # Azure AD group Object IDs
        - "AppRoleName"        # Application role names

Azure AD Configuration (Users Without Email)

For Azure AD users without email addresses (service accounts, organizational accounts without mail attributes):

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-azure-no-email
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://login.microsoftonline.com/your-tenant-id/v2.0
      clientID: your-azure-ad-client-id
      clientSecret: your-azure-ad-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout

      # Use 'sub' instead of 'email' for user identification
      userIdentifierClaim: sub  # Can also use: "oid", "upn", "preferred_username"

      overrideScopes: true  # Optional: Don't request email scope if not needed
      scopes:
        - openid
        - profile
        - groups

      # When using non-email identifiers, allowedUsers matches against the claim value
      allowedUsers:
        - "abc12345-6789-0abc-def0-123456789abc"  # Azure AD user object ID
        - "def67890-1234-5678-90ab-cdef12345678"

      # NOTE: allowedUserDomains is ignored when userIdentifierClaim is not "email"

Note: When userIdentifierClaim is set to a non-email claim (like sub, oid, or upn), the allowedUserDomains configuration is ignored since domain-based validation only applies to email addresses. Use allowedUsers with the actual claim values instead.

Auth0 Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-auth0
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-auth0-domain.auth0.com
      clientID: your-auth0-client-id
      clientSecret: your-auth0-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout

      # Audience configuration for custom APIs
      audience: "https://my-api.example.com"  # Your API identifier from Auth0
      strictAudienceValidation: true          # Enforce proper audience validation

      scopes:
        - read:custom_data  # Custom scopes as needed

      # Custom claim names for Auth0 namespaced claims
      roleClaimName: "https://your-app.com/roles"   # Auth0 requires namespaced custom claims
      groupClaimName: "https://your-app.com/groups" # Must match claims added in Auth0 Actions

      allowedRolesAndGroups:
        - admin    # Will match "admin" in https://your-app.com/roles claim
        - editor
      postLogoutRedirectURI: /logged-out-page  # Must be in Auth0 Allowed Logout URLs

Note: For detailed Auth0 audience configuration including opaque tokens and all security scenarios, see AUTH0_AUDIENCE_GUIDE.md.

Okta Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-okta
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-tenant.okta.com/oauth2/default
      clientID: your-okta-client-id
      clientSecret: your-okta-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - groups  # Include groups in token claims
      allowedRolesAndGroups:
        - admin
        - developer
        - "Everyone"  # Default Okta group

Keycloak Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-keycloak
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://your-keycloak-domain/auth/realms/your-realm
      clientID: your-keycloak-client-id
      clientSecret: your-keycloak-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles
        - groups
      allowedRolesAndGroups:
        - admin
        - editor
      # Ensure Keycloak client mappers add necessary claims to ID Token
      # For internal Keycloak deployments with private IPs (e.g., Docker network):
      # allowPrivateIPAddresses: true

Internal Network Deployment: If your Keycloak runs on an internal network with private IP addresses (e.g., 192.168.x.x, 10.x.x.x, 172.16-31.x.x) and you don't have DNS resolution available, set allowPrivateIPAddresses: true to allow the plugin to connect to your Keycloak instance. See Issue #97 for details.

AWS Cognito Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-cognito
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_YourUserPool
      clientID: your-cognito-client-id
      clientSecret: your-cognito-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - aws.cognito.signin.user.admin  # Cognito-specific scope
      allowedRolesAndGroups:
        - admin
        - user

GitLab Configuration

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-gitlab
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://gitlab.com
      clientID: your-gitlab-client-id
      clientSecret: your-gitlab-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - read_user
        - read_api
      allowedUserDomains:
        - yourcompany.com

GitHub OAuth Configuration ⚠️

Warning: GitHub uses OAuth 2.0, not OpenID Connect. Use only for API access, not user authentication.

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oauth-github
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: https://github.com/login/oauth
      clientID: your-github-client-id
      clientSecret: your-github-client-secret
      sessionEncryptionKey: your-secure-encryption-key-min-32-chars
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - user:email
        - read:user
      # Note: No ID tokens available, only access tokens for GitHub API
      # No refresh tokens - users must re-authenticate when tokens expire

The middleware automatically detects each provider and applies the necessary adjustments to ensure proper authentication and token refresh.

Keeping Secrets Secret in Kubernetes

For Kubernetes environments, you can reference secrets instead of hardcoding sensitive values:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc-with-secrets
  namespace: traefik
spec:
  plugin:
    traefikoidc:
      providerURL: urn:k8s:secret:traefik-middleware-oidc:ISSUER
      clientID: urn:k8s:secret:traefik-middleware-oidc:CLIENT_ID
      clientSecret: urn:k8s:secret:traefik-middleware-oidc:SECRET
      sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
      callbackURL: /oauth2/callback
      logoutURL: /oauth2/logout
      scopes:
        - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]

Don't forget to create the secret:

kubectl create secret generic traefik-middleware-oidc \
  --from-literal=ISSUER=https://accounts.google.com \
  --from-literal=CLIENT_ID=1234567890.apps.googleusercontent.com \
  --from-literal=SECRET=your-client-secret \
  -n traefik

Complete Docker Compose Example

Here's a complete example of using the middleware with Docker Compose:

version: "3.7"

services:
  traefik:
    image: traefik:v3.2.1
    command:
      - "--experimental.plugins.traefikoidc.modulename=github.com/lukaszraczylo/traefikoidc"
      - "--experimental.plugins.traefikoidc.version=v0.7.10"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./traefik-config/traefik.yml:/etc/traefik/traefik.yml
      - ./traefik-config/dynamic-configuration.yml:/etc/traefik/dynamic-configuration.yml
    labels:
      - "traefik.http.routers.dash.rule=Host(`dash.localhost`)"
      - "traefik.http.routers.dash.service=api@internal"
    ports:
      - "80:80"

  hello:
    image: containous/whoami
    labels:
      - traefik.enable=true
      - traefik.http.routers.hello.entrypoints=http
      - traefik.http.routers.hello.rule=Host(`hello.localhost`)
      - traefik.http.services.hello.loadbalancer.server.port=80
      - traefik.http.routers.hello.middlewares=my-plugin@file

  whoami:
    image: jwilder/whoami
    labels:
      - traefik.enable=true
      - traefik.http.routers.whoami.entrypoints=http
      - traefik.http.routers.whoami.rule=Host(`whoami.localhost`)
      - traefik.http.services.whoami.loadbalancer.server.port=8000
      - traefik.http.routers.whoami.middlewares=my-plugin@file

traefik-config/traefik.yml:

log:
  level: INFO

experimental:
  localPlugins:
    traefikoidc:
      moduleName: github.com/lukaszraczylo/traefikoidc

# API and dashboard configuration
api:
  dashboard: true
  insecure: true

entryPoints:
  http:
    address: ":80"
    forwardedHeaders:
      insecure: true

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
  file:
    filename: /etc/traefik/dynamic-configuration.yml

traefik-config/dynamic-configuration.yml:

http:
  middlewares:
    my-plugin:
      plugin:
        traefikoidc:
          providerURL: https://accounts.google.com
          clientID: 1234567890.apps.googleusercontent.com
          clientSecret: your-client-secret
          callbackURL: /oauth2/callback
          logoutURL: /oauth2/logout
          postLogoutRedirectURI: /logged-out-page
          sessionEncryptionKey: potato-secret-is-at-least-32-bytes-long
          scopes:
            - roles  # Appended to defaults: ["openid", "profile", "email", "roles"]
          allowedUserDomains:
            - company.com
          allowedUsers:
            - special-user@gmail.com
            - contractor@external.org
          allowedRolesAndGroups:
            - admin
            - developer
          forceHTTPS: false
          logLevel: debug
          rateLimit: 100
          excludedURLs:
            - /login
            - /public
            - /health
            - /metrics
          headers:
            # Using YAML literal style to prevent Traefik from pre-evaluating templates
            - name: "X-User-Email"
              value: |
                {{.Claims.email}}
            - name: "X-User-ID"
              value: |
                {{.Claims.sub}}
            - name: "Authorization"
              value: |
                Bearer {{.AccessToken}}
            - name: "X-User-Roles"
              value: |
                {{range $i, $e := .Claims.roles}}{{if $i}},{{end}}{{$e}}{{end}}

Templated Headers

The middleware supports setting custom HTTP headers with values templated from OIDC claims and tokens. This allows you to pass authentication information to downstream services in a flexible, customized format.

Templates can access the following variables:

{{.Claims.field}} - Access individual claims from the ID token (e.g., {{.Claims.email}}, {{.Claims.sub}})
{{.AccessToken}} - The raw access token string
{{.IdToken}} - The raw ID token string (same as AccessToken in most configurations)
{{.RefreshToken}} - The raw refresh token string

⚠️ Important: Template Escaping

If you encounter the error can't evaluate field AccessToken in type bool when starting Traefik, this indicates that Traefik is attempting to evaluate the template expressions before passing them to the plugin. This is a known issue when using template syntax in Traefik plugin configurations.

Solution: You must escape the template expressions using double curly braces:

headers:
  - name: "Authorization"
    value: "Bearer {{{{.AccessToken}}}}"

This is the only reliable method that works consistently. Here's why:

Double curly braces ({{{{.AccessToken}}}}) ✅
- The YAML parser converts {{{{ → {{ and }}}} → }}
- Result: Bearer {{.AccessToken}} reaches the Go template engine correctly
Other methods (YAML literal style, single quotes) do NOT work ❌
- These methods don't prevent Traefik's YAML parser from interpreting the curly braces
- The template syntax gets processed incorrectly before reaching the plugin

Working example configuration:

headers:
  - name: "X-User-Email"
    value: "{{{{.Claims.email}}}}"
  - name: "X-User-ID"
    value: "{{{{.Claims.sub}}}}"
  - name: "Authorization"
    value: "Bearer {{{{.AccessToken}}}}"
  - name: "X-User-Name"
    value: "{{{{.Claims.given_name}}}} {{{{.Claims.family_name}}}}"

Advanced template examples:

Conditional logic:

headers:
  - name: "X-Is-Admin"
    value: "{{{{if eq .Claims.role \"admin\"}}}}true{{{{else}}}}false{{{{end}}}}"

Array handling:

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

Notes:

Variable names are case-sensitive (use .Claims, not .claims)
Missing claims will result in <no value> in the header value
The middleware validates templates during startup and logs errors for invalid templates
Always use double curly braces ({{{{ and }}}}) to escape template expressions in YAML configuration files

Default Headers Set for Downstream Services

When a user is authenticated, the middleware sets the following headers for downstream services:

X-Forwarded-User: The user's email address (always set)
X-User-Groups: Comma-separated list of user groups (if available)
X-User-Roles: Comma-separated list of user roles (if available)
X-Auth-Request-Redirect: The original request URI
X-Auth-Request-User: The user's email address
X-Auth-Request-Token: The user's ID token (can be large)

Minimal Headers Mode

If your downstream services return "431 Request Header Fields Too Large" errors, you can enable minimal headers mode to reduce header overhead:

http:
  middlewares:
    my-auth:
      plugin:
        traefikoidc:
          minimalHeaders: true
          # ... other config

When minimalHeaders: true is set:

Only forwards: X-Forwarded-User
Skips: X-Auth-Request-Token (the full ID token - often the largest header), X-Auth-Request-User, X-Auth-Request-Redirect
Still forwards: X-User-Groups and X-User-Roles (if configured)
Still processes: Custom templated headers

This is particularly useful when:

Your ID tokens are large (many claims, long group lists)
Downstream services have limited header buffer sizes (default 8KB in many servers)
You don't need the full token forwarded to backend services

See GitHub Issue #64 for details.

Security Headers

The middleware also sets the following security headers:

X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

Provider Configuration Recommendations

Important: ID Token Validation

This Traefik OIDC plugin performs authentication and extracts user claims (like email, roles, groups) exclusively from the ID Token provided by your OIDC provider. It does not primarily use the Access Token for these critical functions. Therefore, it is crucial to ensure that all necessary claims are included in the ID Token itself. A common issue is that some OIDC providers might, by default, place certain claims only in the Access Token or UserInfo endpoint.

This section provides guidance on configuring popular OIDC providers to work optimally with this plugin.

Google Workspace / Google Cloud Identity

Google's OIDC implementation is well-supported with automatic configuration.

Automatic Configuration: The middleware automatically detects Google and applies required settings:
- Uses access_type=offline and prompt=consent for refresh tokens
- Filters out unsupported offline_access scope
- Handles Google-specific token refresh
Setup Requirements:
- Create OAuth 2.0 credentials in Google Cloud Console
- Configure OAuth consent screen (must be "Published" for production)
- Add authorized redirect URIs
ID Token Claims: Google includes standard claims like email, sub, name, given_name, family_name, picture
Hosted Domain: For Google Workspace, the hd claim contains the organization domain
Best Practices: Use providerURL: https://accounts.google.com

Azure AD (Microsoft Entra ID)

Azure AD provides comprehensive enterprise OIDC support.

Tenant Configuration: Use tenant-specific endpoint: https://login.microsoftonline.com/{tenant-id}/v2.0
Group Claims: Configure in App Registration → Token Configuration → Add groups claim
ID Token Claims: Includes email, name, preferred_username, oid by default
Group Handling: Be aware of group "overage" - too many groups results in a groups claim link instead of embedded groups
Optional Claims: Add custom claims via Token Configuration section
Multi-tenant: Supports both single-tenant and multi-tenant applications

Auth0

Auth0 provides flexible OIDC with custom claims support.

Custom Claims: Use Auth0 Actions (recommended) or Rules to add claims to ID Token:

// Auth0 Action example
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://your-app.com/';
  if (event.authorization) {
    api.idToken.setCustomClaim(namespace + 'roles', event.authorization.roles);
    api.idToken.setCustomClaim('email', event.user.email);
  }
};

Logout Configuration: Ensure postLogoutRedirectURI is in "Allowed Logout URLs"
Application Type: Set to "Regular Web Application" for server-side flows
Refresh Tokens: Automatically handled with offline_access scope

Okta

Okta provides enterprise-grade OIDC with extensive customization.

Application Setup: Create OIDC Web Application in Okta Admin Console
Authorization Server: Use default (/oauth2/default) or custom authorization server
Group Claims: Configure Groups claim in authorization server to include user groups
Scopes: Default scopes sufficient; add groups scope for group information
Sign-On Policy: Configure authentication policies and MFA requirements
Custom Claims: Add custom attributes via user profiles and authorization server claims

Keycloak

Keycloak is highly configurable, requiring proper client mapper setup.

Client Mappers: Essential for including claims in ID Token:
- Email: User Property mapper for email with "Add to ID token" enabled
- Roles: User Client Role or User Realm Role mappers with "Add to ID token" enabled
- Groups: Group Membership mapper with "Add to ID token" enabled
Token Claim Names: Use mapper "Token Claim Name" in allowedRolesAndGroups configuration
Realm Configuration: Ensure proper realm settings and client configuration
Issuer URL Format: https://your-keycloak/auth/realms/your-realm
Troubleshooting: Verify mappers in Clients → Your Client → Mappers tab

AWS Cognito

AWS Cognito provides managed OIDC with regional deployment.

User Pool Setup: Create User Pool with proper app client configuration
App Client: Enable "Authorization code grant" and configure callback URLs
Regional Endpoints: Auto-detected from issuer URL format
Custom Attributes: Configure custom attributes and map to claims
Groups: Use Cognito Groups for role-based access control
Federation: Supports federated identity providers (SAML, social providers)

GitLab

GitLab supports OIDC for both GitLab.com and self-hosted instances.

Application Registration: Create in GitLab Admin Area → Applications
Scopes: Use openid, profile, email for basic claims
Self-hosted: Use your GitLab instance URL as providerURL
GitLab.com: Use https://gitlab.com as providerURL
Group Claims: May require custom configuration for group information
API Access: Include read_api scope for GitLab API access via access token

GitHub (OAuth 2.0 Only) ⚠️

Important: GitHub uses OAuth 2.0, not OpenID Connect.

OAuth App Setup: Register OAuth App in GitHub Settings → Developer settings
Limitations:
- No ID tokens (access tokens only)
- No refresh tokens (tokens expire, requiring re-authentication)
- No standard OIDC claims
Use Cases: API access only, not suitable for user authentication with claims
Scopes: Use user:email, read:user for basic profile access
Detection: Auto-detected from github.com in issuer URL

Auth0

Auth0 is generally OIDC compliant and works well.

ID Token Claims:

To add custom claims or standard claims not included by default (like roles or permissions) to the ID Token, you'll need to use Auth0 Rules or Actions.

Using Actions (Recommended): Create a custom Action that runs after login to add claims to the ID Token. Example:

// Auth0 Action to add email and roles to ID Token
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://your-app.com/'; // Or your custom namespace
  if (event.authorization) {
    api.idToken.setCustomClaim(namespace + 'roles', event.authorization.roles);
    api.idToken.setCustomClaim('email', event.user.email); // Standard claim, ensure it's there
    // Add other claims as needed
  }
};

Ensure the claims you add (e.g., https://your-app.com/roles) are then used in the plugin's allowedRolesAndGroups or headers configuration.

Scopes: Request appropriate scopes. You might need custom scopes if your Actions/Rules depend on them to add specific claims.
Endpoints: Your providerURL will be https://your-auth0-domain.auth0.com.
Logout: Ensure postLogoutRedirectURI is registered in your Auth0 application settings under "Allowed Logout URLs".

Generic OIDC Providers

For other OIDC providers (e.g., Okta, Zitadel, self-hosted solutions):

ID Token is Key: The primary requirement is that all claims needed for authentication decisions (email, roles, groups, custom attributes for headers) must be included in the ID Token.
Check Provider Documentation: Consult your OIDC provider's documentation on how to:
- Configure client applications.
- Map user attributes, roles, or group memberships to claims in the ID Token.
- Define custom scopes if they are necessary to include certain claims.
Standard Endpoints: Ensure your provider exposes a standard OIDC discovery document (.well-known/openid-configuration) at the providerURL. The plugin uses this to find authorization, token, JWKS, and end_session endpoints.
Scopes: Always include openid in your scopes. profile and email are generally recommended. Add other scopes as required by your provider to release specific claims to the ID Token.
Troubleshooting: If the plugin isn't working as expected (e.g., access denied, claims missing), the first step is to decode the ID Token received from your provider (e.g., using jwt.io) to verify its contents. This will show you exactly what claims the plugin is seeing.

For common issues and general troubleshooting, please refer to the Troubleshooting section.

Troubleshooting

Logging

Set the logLevel to debug to get more detailed logs:

logLevel: debug

Common Issues

Token verification failed: Check that your providerURL is correct and accessible.
Session encryption key too short: Ensure your sessionEncryptionKey is at least 32 bytes long.
No matching public key found: The JWKS endpoint might be unavailable or the token's key ID (kid) doesn't match any key in the JWKS.
Access denied: Your email domain is not allowed: The user's email domain is not in the allowedUserDomains list.
Access denied: You do not have any of the allowed roles or groups: The user doesn't have any of the roles or groups specified in allowedRolesAndGroups.
"can't evaluate field AccessToken in type bool" error: This error occurs when Traefik attempts to evaluate template expressions in the headers configuration before passing them to the plugin. To fix this:
- Use double curly braces to escape template expressions: value: "Bearer {{{{.AccessToken}}}}"
- This is the only reliable method that works with Traefik's YAML parsing
- See the Templated Headers section for complete examples

Provider-Specific Issues

Google sessions expire after ~1 hour: If using Google as the OIDC provider and sessions expire prematurely:
- Do NOT manually add the offline_access scope. Google rejects this scope as invalid.
- The middleware automatically applies Google parameters (access_type=offline and prompt=consent).
- Ensure your Google Cloud OAuth consent screen is "Published" for production.
- "Testing" mode limits refresh token validity.
Keycloak: Claims Missing from ID Token:
- Configure client mappers to add email, roles, groups to ID Token
- Check "Add to ID token" is enabled for all required mappers
- Verify "Token Claim Name" matches your configuration
Azure AD: Group overage issues:
- Users with many groups may receive a groups link instead of embedded groups
- Consider using app roles instead of groups for many-group scenarios
- Configure group claims in App Registration → Token Configuration
Auth0: Custom claims not appearing:
- Use Auth0 Actions (not Rules) to add custom claims to ID Token
- Ensure namespaced claims follow format: https://your-app.com/claim
- Add claims to ID token specifically, not just access token
Okta: Authorization server issues:
- Verify using correct authorization server endpoint (/oauth2/default or custom)
- Ensure Groups claim is configured in authorization server
- Check application assignment and user group membership
AWS Cognito: Regional endpoint errors:
- Use correct regional endpoint format: cognito-idp.{region}.amazonaws.com
- Verify User Pool ID is correct in issuer URL
- Check app client has authorization code grant enabled
GitLab: Self-hosted instance issues:
- Ensure issuer URL points to your GitLab instance root
- Verify application is created in Admin Area → Applications
- Check redirect URI configuration matches exactly
GitHub: Limited functionality warnings:
- Remember GitHub is OAuth 2.0 only, not OIDC
- No ID tokens available (access tokens only)
- No refresh tokens (re-authentication required on expiry)
- Use only for GitHub API access, not user authentication
Environment variable names containing "API" cause plugin failure (Issue #98):
- When using environment variable syntax like ${OIDC_ENCRYPTION_SECRET_API} in Traefik configuration, the plugin fails with "invalid handler type: <nil>" error
- This is a Traefik-side issue, not a plugin bug. Traefik uses reserved environment variables starting with TRAEFIK_API_* for its internal API configuration, and the "API" substring in user-defined variable names may interfere with Traefik's environment variable processing
- Workaround: Avoid using "API" as a substring in environment variable names. Use alternatives like:
  - ${OIDC_ENCRYPTION_SECRET_SVC} instead of ${OIDC_ENCRYPTION_SECRET_API}
  - ${OIDC_ENCRYPTION_SECRET_SERVICE}
  - ${OIDC_ENCRYPTION_SECRET_BACKEND}
  - Any name that doesn't contain the literal substring "API"

Provider Warnings and Recommendations

The middleware includes built-in warnings for provider-specific limitations. Check your logs for important notices about:

GitHub OAuth 2.0 limitations (no OIDC support)
Auth0 offline_access scope requirements
Keycloak URL pattern requirements
AWS Cognito regional endpoint requirements
Provider-specific setup recommendations

For detailed provider-specific guidance, see the Provider-Specific Configuration Examples section.

Recent Improvements

Security Features (v0.4.0+)

Security Headers: Complete security headers system with CSP, HSTS, CORS, and XSS protection
Multiple Security Profiles: Choose from default, strict, development, API, or custom security configurations
Enhanced Token Validation: Improved JWT validation with comprehensive security checks
Advanced Rate Limiting: Configurable rate limiting to prevent abuse

User Experience (v0.4.0+)

Automatic Provider Detection: Seamless configuration for major OIDC providers
Improved Error Handling: Better error messages and graceful degradation
Enhanced Session Management: More reliable session handling with automatic cleanup
Flexible Configuration: Expanded configuration options for different deployment scenarios

Reliability (v0.4.0+)

Automatic Token Refresh: Proactive token refresh to prevent authentication interruptions
Memory Management: Improved memory efficiency and automatic resource cleanup
Better Provider Support: Enhanced compatibility with provider-specific features
Comprehensive Testing: Extensive test coverage ensures reliability in production

Architecture Overview

Design Principles

The middleware is designed with the following principles:

Reliability: Automatic error recovery and graceful degradation
Security: Comprehensive security measures and validation
Performance: Efficient resource usage and caching
Flexibility: Extensive configuration options for different use cases
Compatibility: Support for all major OIDC providers with automatic detection

Key Features

Automatic Session Management: Handles session lifecycle, cleanup, and security
Provider Integration: Seamless integration with OIDC providers including auto-discovery
Security Integration: Built-in security headers and protection mechanisms
Resource Management: Efficient memory usage and automatic cleanup
Error Handling: Comprehensive error recovery and user-friendly error messages

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

Memory Management: Ensure all goroutines can be cancelled and resources are bounded
Testing: Add tests for new features, including memory leak tests where appropriate
Race Conditions: Run tests with -race flag to detect race conditions
Documentation: Update README and .traefik.yml for any new configuration options

Name		Name	Last commit message	Last commit date
Latest commit History 173 Commits
.github		.github
docs		docs
examples		examples
integration		integration
internal		internal
regression		regression
session/chunking		session/chunking
vendor		vendor
.gitguardian.yaml		.gitguardian.yaml
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
.traefik.yml		.traefik.yml
LICENSE		LICENSE
README.md		README.md
SECURITY_FIX.md		SECURITY_FIX.md
audience_test.go		audience_test.go
auth_flow.go		auth_flow.go
auth_flow_behaviour_test.go		auth_flow_behaviour_test.go
auth_flow_pkce_test.go		auth_flow_pkce_test.go
autocleanup.go		autocleanup.go
autocleanup_additional_test.go		autocleanup_additional_test.go
azure_oidc_test.go		azure_oidc_test.go
background_tasks_ultra_test.go		background_tasks_ultra_test.go
cache_bench_test.go		cache_bench_test.go
cache_compat.go		cache_compat.go
cache_manager.go		cache_manager.go
cache_test.go		cache_test.go
config_marshalling.go		config_marshalling.go
coverage_boost_final_test.go		coverage_boost_final_test.go
csrf_session_test.go		csrf_session_test.go
custom_claims_test.go		custom_claims_test.go
dcr_storage_compat.go		dcr_storage_compat.go
dcr_storage_test.go		dcr_storage_test.go
dynamic_client_registration.go		dynamic_client_registration.go
dynamic_client_registration_test.go		dynamic_client_registration_test.go
edge_cases_suite_test.go		edge_cases_suite_test.go
enhanced_mocks_suite_test.go		enhanced_mocks_suite_test.go
enhanced_mocks_test.go		enhanced_mocks_test.go
error_recovery.go		error_recovery.go
error_recovery_bench_test.go		error_recovery_bench_test.go
error_recovery_test.go		error_recovery_test.go
go.mod		go.mod
go.sum		go.sum
goroutine_manager.go		goroutine_manager.go
goroutine_manager_test.go		goroutine_manager_test.go
helpers.go		helpers.go
http_client_factory.go		http_client_factory.go
http_client_factory_unit_test.go		http_client_factory_unit_test.go
http_client_pool.go		http_client_pool.go
http_client_pool_test.go		http_client_pool_test.go
input_validation.go		input_validation.go
input_validation_test.go		input_validation_test.go
issue67_regression_test.go		issue67_regression_test.go
jwk.go		jwk.go
jwk_caching_test.go		jwk_caching_test.go
jwt.go		jwt.go
logger_singleton.go		logger_singleton.go
logout.go		logout.go
logout_test.go		logout_test.go
main.go		main.go
main_bench_test.go		main_bench_test.go
main_coverage_boost2_test.go		main_coverage_boost2_test.go
main_coverage_boost_test.go		main_coverage_boost_test.go
main_exchange_test.go		main_exchange_test.go
main_goroutine_leak_test.go		main_goroutine_leak_test.go
main_initialization_test.go		main_initialization_test.go
main_refresh_test.go		main_refresh_test.go
main_servehttp_test.go		main_servehttp_test.go
main_simple_test.go		main_simple_test.go
main_test.go		main_test.go
memory_leak_bench_test.go		memory_leak_bench_test.go
memory_leak_fixes.go		memory_leak_fixes.go
memory_leak_test.go		memory_leak_test.go
memory_monitor.go		memory_monitor.go
memory_optimizations.go		memory_optimizations.go
metadata_cache.go		metadata_cache.go
middleware.go		middleware.go
middleware_edge_cases_test.go		middleware_edge_cases_test.go
mocks_test.go		mocks_test.go
pkce_flow_test.go		pkce_flow_test.go
profiling.go		profiling.go
profiling_test.go		profiling_test.go
redis_integration_test.go		redis_integration_test.go
refresh_coordinator.go		refresh_coordinator.go
refresh_coordinator_test.go		refresh_coordinator_test.go
refresh_race_test.go		refresh_race_test.go
scope_filter.go		scope_filter.go
scope_filter_test.go		scope_filter_test.go
security_edge_cases_test.go		security_edge_cases_test.go
security_monitoring.go		security_monitoring.go
security_monitoring_test.go		security_monitoring_test.go
semver.yaml		semver.yaml
session.go		session.go
session_behaviour_test.go		session_behaviour_test.go
session_bench_test.go		session_bench_test.go
session_chunk_cleanup.go		session_chunk_cleanup.go
session_chunk_manager.go		session_chunk_manager.go
session_test.go		session_test.go
settings.go		settings.go

License

lukaszraczylo/traefikoidc

Folders and files

Latest commit

History

Repository files navigation

Traefik OIDC Middleware

Overview

Supported OIDC Providers

Provider Capabilities Matrix

Performance and Memory Management

Traefik Version Compatibility

Installation

As a Traefik Plugin

Verifying Release Signatures

Local Development with Docker Compose

Configuration Options

Required Parameters

Optional Parameters

Scope Configuration

Scope Behavior

Default Append Mode (overrideScopes: false)

Override Mode (overrideScopes: true)

Examples:

Auth0 Audience Validation & Security

Understanding Token Audiences

Auth0 Scenarios

Scenario 1: Custom API Audience ✅ (RECOMMENDED)

Scenario 2: Default Audience ⚠️ (USE WITH CAUTION)

Scenario 3: Opaque Access Tokens ✅ (SUPPORTED)

Security Configuration Options

Complete Auth0 Configuration Examples

Security Headers Configuration

Security Features

Security Profiles

Configuration Examples

Default Security (Recommended)

Strict Security

API with CORS

Custom Configuration

Security Headers Parameters

CORS Wildcard Support

Advanced Configuration

Provider-Specific Optimizations

Token Management

Configuration Examples

High-Throughput Configuration

High-Security Configuration

Development Configuration

Multi-Replica Deployment Configuration

Redis Cache (Optional)

Why Use Redis Cache?

Basic Configuration

Configuration Priority

Configuration Options

Environment Variables (Fallback)

Cache Modes

Example Configurations

Docker Compose with Redis

Kubernetes with Redis

Advanced Redis Configuration

Dynamic Client Registration (RFC 7591)

How It Works

Configuration

DCR Configuration Parameters

Provider Support

Security Considerations

Example: Keycloak with DCR

Usage Examples

Basic Configuration

With Excluded URLs (Public Access Paths)

With Email Domain Restrictions

With Specific User Access

With Both Domain and Specific User Access

With Role-Based Access Control

With Cookie Domain Configuration (Multi-Subdomain Setup)

With Multiple Middleware Instances (Session Isolation)

With Extended Session Duration

With Custom Logging and Rate Limiting

With Custom Post-Logout Redirect

Default Append Mode (`overrideScopes: false`)

Override Mode (`overrideScopes: true`)

Packages