DOCSEARCHbyAlgolia
Submit Docs

traefik-forward-auth

repository·master·Indexed 25 days ago

https://github.com/thomseddon/traefik-forward-auth

A minimal forward authentication service providing OAuth/SSO login and authentication for the Traefik reverse proxy and load balancer. It supports Google, OpenID Connect (OIDC), and generic OAuth2 providers. The service can be deployed via Docker or Kubernetes using either a single-pod or separate-pod pattern, and supports both global and selective authentication via Traefik middlewares and Ingress annotations.

Tokens
7.9K
Snippets
16
Records
32
Agent score
81%

What's inside traefik-forward-auth

  1. Restrict access via domains and whitelists

    master

    You can restrict which users are allowed to authenticate using two methods:

    1. Domain Restriction: Use --domain=<domain> to only allow users with specific email domains (e.g., --domain=example.com). This can be set multiple times.
    2. Whitelist Restriction: Use --whitelist=<email> to only allow specific email addresses. This can be set multiple times.

    In v3, users are permitted if they match either the whitelist or domain parameters by default. In v2, this behavior is controlled by the --match-whitelist-or-domain flag (defaults to false).

  2. Manage authentication cookies and domains

    master

    Cookie Domain

    Use --cookie-domain to set the domain for the authentication cookie. If the original request's host is a subdomain of this domain, the cookie will be set at the higher level. This allows a single authentication to grant access to multiple subdomains (e.g., setting example.com allows access to app1.example.com and app2.example.com).

    Note: If running multiple instances of traefik-forward-auth for the same domain, ensure they use the same secret or different cookie-name to avoid clashes.

    Insecure Cookies

    If you are not using HTTPS between the client and Traefik, use the --insecure-cookie flag to prevent the Secure attribute from being set on cookies.

    Cookie Names

    • cookie-name: The name of the auth cookie (default: _forward_auth).
    • csrf-cookie-name: The name of the temporary CSRF cookie (default: _forward_auth_csrf).

  3. Pass the authenticated user to applications via X-Forwarded-User

    master
    Traefik Forward Auth sets the authenticated user in the X-Forwarded-User header. To ensure this header is passed through to your backend application, you must add it to the authResponseHeaders configuration option in Traefik.

  4. Restrict user access via domain and whitelist

    master

    You can limit which users are allowed to log in using the following parameters:

    • domain: Limits logins to a specific domain (e.g., test.com).
    • whitelist: Limits logins to specific user identifiers (e.g., thom@test.com).

    Behavioral Notes:

    • If both whitelist and domain are provided, whitelist takes precedence and domain is ignored by default.
    • To allow users matching either whitelist or domain, use the match-whitelist-or-domain parameter (this becomes the default behavior in v3).
    • If you define domains or whitelist on a specific rule, the global configuration is ignored for that rule.

  5. Understand Overlay Mode vs Auth Host Mode

    master

    Traefik Forward Auth operates in two primary modes:

    Overlay Mode (Default)

    In this mode, the authorization endpoint is overlaid onto any domain. By default, the path is /_oauth (customizable via url-path).

    Flow:

    1. User requests www.myapp.com/home.
    2. User is redirected to the OAuth provider (e.g., Google).
    3. After login, user is redirected back to www.myapp.com/_oauth.
    4. Token and CSRF cookie are validated.
    5. User is redirected back to the original destination.

    Note: Every hostname used must be permitted in your OAuth provider's redirect URI whitelist.

    Auth Host Mode

    Useful for managing many subdomains without adding every single one to your OAuth provider's console. This is activated via the auth-host option.

    Requirements:

    1. The request must match the configured cookie-domain.
    2. The auth-host must be a subdomain of the same cookie-domain.
    3. Requests to the auth-host must be routed to the traefik-forward-auth container.

    Flow Example: If cookie-domain is test.com and auth-host is auth.test.com:

    1. User requests app10.test.com/home.
    2. User is redirected to the OAuth provider.
    3. User is redirected back to auth.test.com/_oauth.
    4. Auth cookie is set for .test.com.
    5. User is redirected back to app10.test.com/home and allowed access.

  7. Deploy traefik-forward-auth on Kubernetes with Traefik v1.7

    master

    You can deploy traefik-forward-auth on Kubernetes alongside Traefik v1.7 using two different architectural patterns:

    1. Separate Pod Pattern: Deploy traefik-forward-auth in its own dedicated pod. This is recommended if you are managing Traefik deployment separately (for example, via Helm) and want to decouple the authentication service from the edge router.
    2. Single Pod Pattern: Deploy both Traefik and traefik-forward-auth within a single pod. This pattern co-locates the services, which can simplify networking between them but couples their lifecycles.

    Refer to the specific README files within the examples/traefik-v1.7/kubernetes/ directory for the exact manifest configurations for each pattern.

  8. Install Traefik Forward Auth via Docker

    master
    To install Traefik Forward Auth, use the thomseddon/traefik-forward-auth:2 Docker image. For ARM architectures, append -arm or -arm64 to the tag (e.g., 2-arm or 2.1-arm64). Binary files for non-Docker usage are available as assets in the GitHub releases starting from version 2.2.0.

  9. Apply authentication globally via Traefik Entrypoints

    master

    You can enable forward authentication for an entire entrypoint (e.g., all HTTP or all HTTPS traffic) using Traefik static configuration.

    HTTP Example:

    --entryPoints.http.address=:80
--entrypoints.http.http.middlewares=traefik-forward-auth # "default-traefik-forward-auth" on kubernetes

    HTTPS Example:

    --entryPoints.http.address=:80
--entryPoints.http.http.redirections.entryPoint.to=https
--entryPoints.http.http.redirections.entryPoint.scheme=https
--entryPoints.https.address=:443
--entrypoints.https.http.middlewares=traefik-forward-auth # "default-traefik-forward-auth" on kubernetes

    Kubernetes Note: When referencing middleware from static configuration (command arguments or config files) in Kubernetes, you must prepend the namespace to the middleware name (e.g., default-traefik-forward-auth if the middleware is named traefik-forward-auth in the default namespace).

  10. Protect Kubernetes Ingresses using annotations

    master

    To apply authentication to specific Ingresses in a Kubernetes cluster using Traefik, add the following annotations to your Ingress metadata. This approach ensures that only selected Ingresses are protected by default.

    Required annotations:

    • kubernetes.io/ingress.class: traefik
    • ingress.kubernetes.io/auth-type: forward
    • ingress.kubernetes.io/auth-url: The internal URL of your traefik-forward-auth service (e.g., http://traefik-forward-auth:4181).
    • ingress.kubernetes.io/auth-response-headers: The header(s) to be passed from the auth service to the backend (e.g., X-Forwarded-User).
    apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: whoami
  labels:
    app: whoami
  annotations:
    kubernetes.io/ingress.class: traefik
    ingress.kubernetes.io/auth-type: forward
    ingress.kubernetes.io/auth-url: http://traefik-forward-auth:4181
    ingress.kubernetes.io/auth-response-headers: X-Forwarded-User
spec:
  rules:
  - host: whoami.example.com
    http:
      paths:
      - backend:
          serviceName: whoami
          servicePort: http

  11. Configure Generic OAuth2 Provider

    master

    For providers that do not support OIDC, use the Generic OAuth2 provider.

    Required settings:

    • providers.generic-oauth.auth-url: URL to send the client to for authentication.
    • providers.generic-oauth.token-url: URL to exchange an auth code for an access token.
    • providers.generic-oauth.user-url: URL used to retrieve user info via a GET request.
    • providers.generic-oauth.client-id: Client ID.
    • providers.generic-oauth.client-secret: Client Secret.

    Optional settings:

    • providers.generic-oauth.scope: Scopes included in the request (defaults to profile, email).
    • providers.generic-oauth.token-style: How the token is presented when querying the User URL. Options are header (default) or query (uses access_token query string).

  12. Configure Google Provider

    master

    To use Google as an authentication provider:

    1. Create a project in the Google Cloud Console.
    2. Configure the 'OAuth Consent Screen'.
    3. Create an 'OAuth client ID' of type 'Web Application'.
    4. In 'Authorized redirect URIs', add your domains appended with the configured url-path (e.g., https://app.test.com/_oauth).
    5. Set the following environment variables:
      • PROVIDERS_GOOGLE_CLIENT_ID
      • PROVIDERS_GOOGLE_CLIENT_SECRET