traefik-oidc-auth

If you are protecting multiple subdomains that share a parent domain (e.g., app1.example.com and app2.example.com), you can optimize performance and user experience by storing the session cookie at the common parent level using SessionCookie.Domain.

Warning: Sharing a session cookie via SessionCookie.Domain can affect authorization. Since authorization is only checked when the session is created, a user logged into one application via a middleware will also be considered logged in for any other application sharing that same session cookie, even if they have different authorization rules.

middlewares:
  oidc-auth:
    plugin:
      traefik-oidc-auth:
        CallbackUri: "https://login.example.com/oidc/callback"
        SessionCookie:
          Domain: ".example.com"
        Provider:
          Url: "https://ident.example.com/"
          ClientId: "<YourClientId>"
          ClientSecret: "<YourClientSecret>"
        Scopes: ["openid", "profile", "email"]

The Traefik OIDC Authentication plugin acts as a middleware for the Traefik reverse proxy to secure upstream services using OAuth 2.0. It intercepts incoming requests and manages the authentication lifecycle so that individual microservices do not need to implement OAuth flows themselves.

Authentication Flow

1. Authentication Verification: The plugin checks for a valid OAuth token stored in a Cookie.
2. Token Validation: It verifies the token against the configured OAuth provider to ensure it is valid and not expired.
3. User Authorization: It confirms the user has required permissions (via claim validation or role matching).
4. Request Handling:
   • Valid Token: The request is forwarded to the upstream service.
   • Missing/Invalid Token: The plugin redirects the user to the OAuth provider's authorization endpoint or returns an HTTP error (e.g., 401 Unauthorized).

Request Scenarios

• When no Cookie is present: The plugin redirects the user to the OAuth provider. After successful login and consent, the provider redirects the user to the plugin's callback (/oidc/callback). The plugin then exchanges the code for tokens, validates authorization, creates a session/cookie, and redirects the user back to the original requested page.
• When a Cookie is present: The plugin fetches the JWKS (JSON Web Key Set) from the OAuth provider to validate the token locally. If valid, the request is forwarded; if invalid or expired, the user is redirected to the OAuth provider for login.

Authorization rules are evaluated based on the following lifecycle:

1. Default Behavior: AssertClaims is evaluated once when the user logs in and the session is created. The result is cached in the session and reused for subsequent requests. Even if claims change (e.g., via a silent token refresh), the cached result is used.
2. Per-Request Evaluation: If you need to enforce rules that might change during a session (like acr claims for step-up authentication), set CheckOnEveryRequest to true. This prevents caching and re-evaluates the assertion on every request.
3. Stateless Authorization: When using AuthorizationHeader or AuthorizationCookie, CheckOnEveryRequest is effectively always true because there is no persistent session to cache the result.

Note on Unauthorized Results: If an initial check fails, the 'unauthorized' result is cached in the session. Depending on your UnauthorizedBehavior configuration, users may see a 403 or be bounced through the IDP once before seeing the 403 page.

When running on Kubernetes, you can use a Middleware CRD and reference sensitive values (like the encryption secret and the clientSecret) from a Kubernetes Secret using the urn:k8s:secret:<secret-name>:<key> syntax.

1. Create a Kubernetes Secret containing your pluginSecret and providerClientSecret.
2. Define a Middleware resource where the plugin.traefik-oidc-auth.secret and plugin.traefik-oidc-auth.provider.clientSecret point to the keys in your Secret.
3. Attach the Middleware to an IngressRoute.

apiVersion: v1
kind: Secret
metadata:
  name: oidc-secret
  namespace: traefik
type: Opaque
stringData:
  pluginSecret: "MLFs4TT99kOOq8h3UAVRtYoCTDYXiRcZ"
  providerClientSecret: "<YourClientSecret>"
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: oidc
  namespace: traefik
spec:
  plugin:
    traefik-oidc-auth:
      secret: "urn:k8s:secret:oidc-secret:pluginSecret"
      provider:
        clientId: "abcd-12345"
        clientSecret: "urn:k8s:secret:oidc-secret:providerClientSecret"
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami
  namespace: traefik
spec:
  routes:
    - kind: Rule
      match: Host(`whoami.mycluster.com`)
      middlewares:
        - name: oidc
      services:
        - kind: Service
          name: whoami
          port: 80