r1cebank/traefik-forward-auth

Traefik Forward Auth  !Docker Pulls

一个轻量级的转发认证服务，为 https://github.com/containous/traefik 反向代理/负载均衡器提供 OAuth/SSO 登录和认证功能。

为什么选择它？

• 无缝覆盖任何HTTP服务，仅需一个端点（参见 配置 中的 url-path）
• 支持多种认证提供者，包括Google和OpenID Connect（Azure、Github、Salesforce等均支持）
• 通过动态生成redirect_uri支持多域名/子域名
• 允许基于请求参数选择性应用/绕过认证（参见 配置 中的 rules）
• 支持集中式认证主机/redirect_uri（参见 配置 中的 auth-host）
• 允许认证在多域名间持久化（参见 Cookie域名）
• 支持超出Google令牌生命周期的扩展认证（参见 配置 中的 lifetime）

目录

• 版本发布
• 使用方法
  • 简单配置
  • 高级配置
  • 提供者设置
• 配置
  • 概述
  • 选项详情
• 概念
  • 转发头信息
  • 用户限制
  • 操作模式
    • 覆盖模式
    • 认证主机模式
• 版权
• 许可协议

版本发布

我们推荐使用Docker Hub上的 2 标签。
您也可以使用Docker Hub https://hub.docker.com/r/thomseddon/traefik-forward-auth/tags 和GitHub https://github.com/thomseddon/traefik-forward-auth/releases 上的最新增量版本。

升级指南

v2于2019年6月发布，虽完全向后兼容，但部分配置选项已修改。请参阅 https://github.com/thomseddon/traefik-forward-auth/wiki/v2-Upgrade-Guide 以避免启动警告并确保使用当前配置。

使用方法

简单配置：

请先完成 提供者设置。

docker-compose.yml：

yaml
version: '3'

services:
  traefik:
    image: traefik:1.7
    ports:
      - "8085:80"
    volumes:
      - ./traefik.toml:/traefik.toml
      - /var/run/docker.sock:/var/run/docker.sock

  traefik-forward-auth:
    image: thomseddon/traefik-forward-auth:2
    environment:
      - PROVIDERS_GOOGLE_CLIENT_ID=your-client-id
      - PROVIDERS_GOOGLE_CLIENT_SECRET=your-client-secret
      - SECRET=something-random
      - INSECURE_COOKIE=true # 示例假设无HTTPS，生产环境请勿使用

  whoami:
    image: emilevauge/whoami:latest
    labels:
      - "traefik.frontend.rule=Host:whoami.mycompany.com"

traefik.toml：

toml
[entryPoints]
    [entryPoints.http]
    address = ":80"

    [entryPoints.http.auth.forward]
    address = "http://traefik-forward-auth:4181"
    authResponseHeaders = ["X-Forwarded-User"]

[docker]
endpoint = "unix:///var/run/docker.sock"
network = "traefik"

高级配置：

请查看examples目录中的完整 https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/docker-compose.yml 和 https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/traefik.toml%E3%80%82
examples目录中还有 https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/docker-compose-auth-host.yml%EF%BC%8C%E5%B1%95%E7%A4%BA%E5%A6%82%E4%BD%95%E9%85%8D%E7%BD%AE%E4%B8%AD%E5%A4%AE%E8%AE%A4%E8%AF%81%E4%B8%BB%E6%9C%BA%E5%8F%8A%E5%85%B6%E4%BB%96%E9%80%89%E9%A1%B9%E3%80%82

提供者设置

Google

1. 前往 [***] 并切换到正确账户。
2. 创建新项目，搜索并选择"Credentials"，填写"OAuth Consent Screen"标签页。
3. 点击"Create Credentials" > "OAuth client ID"，选择"Web Application"，填写名称，跳过"Authorized JavaScript origins"，在"Authorized redirect URIs"中添加所有允许认证的域名（后跟url-path，如https://app.test.com/_oauth）。
4. 必须设置 providers.google.client-id 和 providers.google.client-secret。

OpenID Connect

任何支持OpenID Connect 1.0的提供者均可通过OIDC配置选项设置，需指定 providers.oidc.issuer-url、providers.oidc.client-id 和 providers.oidc.client-secret。

配置

配置概述

支持以下配置选项：

Usage:
  traefik-forward-auth [OPTIONS]

Application Options:
  --log-level=[trace|debug|info|warn|error|fatal|panic] Log level (default: warn) [$LOG_LEVEL]
  --log-format=[text|json|pretty]                       Log format (default: text) [$LOG_FORMAT]
  --auth-host=                                          Single host to use when returning from 3rd party auth [$AUTH_HOST]
  --config=                                             Path to config file [$CONFIG]
  --cookie-domain=                                      Domain to set auth cookie on, can be set multiple times [$COOKIE_DOMAIN]
  --insecure-cookie                                     Use insecure cookies [$INSECURE_COOKIE]
  --cookie-name=                                        Cookie Name (default: _forward_auth) [$COOKIE_NAME]
  --csrf-cookie-name=                                   CSRF Cookie Name (default: _forward_auth_csrf) [$CSRF_COOKIE_NAME]
  --default-action=[auth|allow]                         Default action (default: auth) [$DEFAULT_ACTION]
  --default-provider=[google|oidc]                      Default provider (default: google) [$DEFAULT_PROVIDER]
  --domain=                                             Only allow given email domains, can be set multiple times [$DOMAIN]
  --lifetime=                                           Lifetime in seconds (default: 43200) [$LIFETIME]
  --url-path=                                           Callback URL Path (default: /_oauth) [$URL_PATH]
  --secret=                                             Secret used for signing (required) [$SECRET]
  --whitelist=                                          Only allow given email addresses, can be set multiple times [$WHITELIST]
  --rule.<name>.<param>=                                Rule definitions, param can be: "action", "rule" or "provider"

Google Provider:
  --providers.google.client-id=                         Client ID [$PROVIDERS_GOOGLE_CLIENT_ID]
  --providers.google.client-secret=                     Client Secret [$PROVIDERS_GOOGLE_CLIENT_SECRET]
  --providers.google.prompt=                            Space separated list of OpenID prompt options [$PROVIDERS_GOOGLE_PROMPT]

OIDC Provider:
  --providers.oidc.issuer-url=                          Issuer URL [$PROVIDERS_OIDC_ISSUER_URL]
  --providers.oidc.client-id=                           Client ID [$PROVIDERS_OIDC_CLIENT_ID]
  --providers.oidc.client-secret=                       Client Secret [$PROVIDERS_OIDC_CLIENT_SECRET]

Help Options:
  -h, --help                                            Show this help message

配置优先级（从高到低）：

1. 命令行参数/标志
2. 环境变量
3. 配置文件（INI格式，可多次指定）

选项详情

• auth-host: 第三方认证返回时使用的统一主机，仅需在提供者控制台添加此主机作为redirect_uri（如auth.example.com）。
• cookie-domain: 设置认证Cookie的域名，支持多域名，可实现跨子域认证（如test.com允许app1.test.com和app2.test.com共享Cookie）。
• insecure-cookie: 非HTTPS环境下需启用，不设置Cookie的Secure属性。
• default-action: 未匹配规则时的默认行为（auth需认证，allow直接允许）。
• domain/whitelist: 限制登录用户的域名或具体***（whitelist优先级更高）。
• lifetime: 认证会话有效期（默认12小时）。
• rules: 选择性认证规则，支持按路径、主机、方法等条件设置不同的认证策略。

概念

用户限制

通过domain（限制域名）或whitelist（限制具体用户）控制登录权限，whitelist优先级更高。

转发头信息

认证用户会通过X-Forwarded-User头传递给后端服务，需在Traefik中配置authResponseHeaders。

操作模式

覆盖模式（默认）

授权端点（如/_oauth）覆盖所有域名，每个域名需在提供者控制台添加redirect_uri。用户流程：请求→重定向登录→返回原域名的回调地址→验证→重定向原请求。

认证主机模式

通过auth-host和cookie-domain实现集中认证，仅需在提供者控制台添加认证主机的redirect_uri。用户流程：请求→重定向登录→返回认证主机的回调地址→设置跨域Cookie→重定向原请求。

版权

2018 Thom Seddon

许可协议

https://github.com/thomseddon/traefik-forward-auth/blob/master/LICENSE.md