thomseddon/traefik-forward-auth

Traefik Forward Auth !Build Status https://goreportcard.com/badge/github.com/thomseddon/traefik-forward-auth](https://goreportcard.com/report/github.com/thomseddon/traefik-forward-auth) !Docker Pulls

一款轻量级转发认证服务，为https://github.com/containous/traefik%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86/%E8%B4%9F%E8%BD%BD%E5%9D%87%E8%A1%A1%E5%99%A8%E6%8F%90%E4%BE%9BOAuth/SSO%E7%99%BB%E5%BD%95%E5%92%8C%E8%AE%A4%E8%AF%81%E5%8A%9F%E8%83%BD%E3%80%82

核心优势

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

目录

• 版本发布
• 使用方法
  • 简单配置
  • 高级配置
  • 提供商设置
• 配置说明
  • 概述
  • 选项详情
• 核心概念
  • 转发头信息
  • 用户限制
  • 认证应用方式
    • 全局认证
    • Kubernetes中的选择性Ingress认证
    • Swarm中的选择性容器认证
    • 基于规则的认证
  • 运行模式
    • 覆盖模式
    • 认证主机模式
  • 登出功能
• 版权信息
• 许可协议

版本发布

推荐使用Docker Hub上的2标签（thomseddon/traefik-forward-auth:2）。

也可使用https://hub.docker.com/r/thomseddon/traefik-forward-auth/tags%E5%92%8Chttps://github.com/thomseddon/traefik-forward-auth/releases%E4%B8%8A%E7%9A%84%E6%9C%80%E6%96%B0%E5%A2%9E%E9%87%8F%E7%89%88%E6%9C%AC%E3%80%82

ARM版本同样在Docker Hub可用，只需在所需版本后添加-arm或-arm64（例如2-arm或2.1-arm64）。

从2.2.0版本开始，还提供无需Docker的二进制文件，可在特定GitHub发布的资产中找到。

升级指南

v2版本于2019年6月发布，虽然完全向后兼容，但部分配置选项已修改。请参阅https://github.com/thomseddon/traefik-forward-auth/wiki/v2-Upgrade-Guide%E4%BB%A5%E9%81%BF%E5%85%8D%E5%90%AF%E5%8A%A8%E8%AD%A6%E5%91%8A%E5%B9%B6%E7%A1%AE%E4%BF%9D%E4%BD%BF%E7%94%A8%E5%BD%93%E5%89%8D%E9%85%8D%E7%BD%AE%E3%80%82

使用方法

简单配置：

请先参阅提供商设置了解如何设置提供商。

docker-compose.yml：

yaml
version: '3'

services:
  traefik:
    image: traefik:v2.2
    command: --providers.docker
    ports:
      - "8085:80"
    volumes:
      - /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  # 替换为你的客户端ID
      - PROVIDERS_GOOGLE_CLIENT_SECRET=your-client-secret  # 替换为你的客户端密钥
      - SECRET=something-random  # 随机字符串，用于签名（例如使用openssl rand -hex 16生成）
      - INSECURE_COOKIE=true  # 示例假设没有使用HTTPS，请勿在生产环境中使用
    labels:
      - "traefik.http.middlewares.traefik-forward-auth.forwardauth.address=http://traefik-forward-auth:4181"
      - "traefik.http.middlewares.traefik-forward-auth.forwardauth.authResponseHeaders=X-Forwarded-User"
      - "traefik.http.services.traefik-forward-auth.loadbalancer.server.port=4181"

  whoami:
    image: containous/whoami
    labels:
      - "traefik.http.routers.whoami.rule=Host(`whoami.mycompany.com`)"  # 替换为你的域名
      - "traefik.http.routers.whoami.middlewares=traefik-forward-auth"

高级配置：

完整的https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/traefik-v2/swarm/docker-compose.yml%E6%88%96https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/traefik-v2/kubernetes/simple-separate-pod/%E7%A4%BA%E4%BE%8B%E5%8F%AF%E5%9C%A8examples%E7%9B%AE%E5%BD%95%E4%B8%AD%E6%89%BE%E5%88%B0%E3%80%82

examples目录中还包含https://github.com/thomseddon/traefik-forward-auth/blob/master/examples/traefik-v2/swarm/docker-compose-auth-host.yml%E5%92%8Chttps://github.com/thomseddon/traefik-forward-auth/blob/master/examples/traefik-v2/kubernetes/advanced-separate-pod/%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

提供商设置

以下是提供商设置的一般说明，更多提供商的具体说明和示例可在https://github.com/thomseddon/traefik-forward-auth/wiki/Provider-Setup wiki页面找到。

Google

访问[***]

创建新项目，然后在搜索栏中搜索并选择"Credentials"。填写"OAuth Consent Screen"选项卡。

点击"Create Credentials" > "OAuth client ID"。选择"Web Application"，填写应用名称，跳过"Authorized JavaScript origins"，在"Authorized redirect URIs"中填写所有允许认证的域名，并附加url-path（例如[***]

必须设置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配置选项。

示例请参阅https://github.com/thomseddon/traefik-forward-auth/wiki/Provider-Setup wiki页面。

通用OAuth2

对于不支持OpenID Connect的提供商，可使用通用OAuth2提供商，静态配置OAuth2和"user"端点。

必须设置：

• providers.generic-oauth.auth-url - 客户端应重定向到的认证URL
• providers.generic-oauth.token-url - 服务用于交换授权码获取访问令牌的URL
• providers.generic-oauth.user-url - 用于获取用户信息的URL（服务发送GET请求）
• providers.generic-oauth.client-id - 客户端ID
• providers.generic-oauth.client-secret - 客户端密钥

还可设置：

• providers.generic-oauth.scope - 请求中应包含的作用域（默认：profile, email）
• providers.generic-oauth.token-style - 查询用户URL时令牌的呈现方式，可选header或query（默认：header）。header模式下令牌在Authorization头中，query模式下令牌在access_token查询参数中。

示例请参阅https://github.com/thomseddon/traefik-forward-auth/wiki/Provider-Setup wiki页面。

配置说明

概述

支持以下配置选项：

用法:
  traefik-forward-auth [选项]

应用选项:
  --log-level=[trace|debug|info|warn|error|fatal|panic] 日志级别（默认：warn） [$LOG_LEVEL]
  --log-format=[text|json|pretty]                       日志格式（默认：text） [$LOG_FORMAT]
  --auth-host=                                          第三方认证返回时使用的单个主机 [$AUTH_HOST]
  --config=                                             配置文件路径 [$CONFIG]
  --cookie-domain=                                      认证Cookie的域名，可多次设置 [$COOKIE_DOMAIN]
  --insecure-cookie                                     使用不安全Cookie [$INSECURE_COOKIE]
  --cookie-name=                                        Cookie名称（默认：_forward_auth） [$COOKIE_NAME]
  --csrf-cookie-name=                                   CSRF Cookie名称（默认：_forward_auth_csrf） [$CSRF_COOKIE_NAME]
  --default-action=[auth|allow]                         默认操作（默认：auth） [$DEFAULT_ACTION]
  --default-provider=[google|oidc|generic-oauth]        默认提供商（默认：google） [$DEFAULT_PROVIDER]
  --domain=                                             仅允许指定邮箱域名，可多次设置 [$DOMAIN]
  --lifetime=                                           会话生命周期（秒）（默认：43200） [$LIFETIME]
  --logout-redirect=                                    登出后重定向URL [$LOGOUT_REDIRECT]
  --url-path=                                           回调URL路径（默认：/_oauth） [$URL_PATH]
  --secret=                                             签名密钥（必填） [$SECRET]
  --whitelist=                                          仅允许指定邮箱地址，可多次设置 [$WHITELIST]
  --port=                                               监听端口（默认：4181） [$PORT]
  --rule.<name>.<param>=                                规则定义，param可取值："action"、"rule"或"provider"

Google提供商:
  --providers.google.client-id=                         客户端ID [$PROVIDERS_GOOGLE_CLIENT_ID]
  --providers.google.client-secret=                     客户端密钥 [$PROVIDERS_GOOGLE_CLIENT_SECRET]
  --providers.google.prompt=                            OpenID提示选项的空格分隔列表 [$PROVIDERS_GOOGLE_PROMPT]

OIDC提供商:
  --providers.oidc.issuer-url=                          发行者URL [$PROVIDERS_OIDC_ISSUER_URL]
  --providers.oidc.client-id=                           客户端ID [$PROVIDERS_OIDC_CLIENT_ID]
  --providers.oidc.client-secret=                       客户端密钥 [$PROVIDERS_OIDC_CLIENT_SECRET]
  --providers.oidc.resource=                            可选资源指示器 [$PROVIDERS_OIDC_RESOURCE]

通用OAuth2提供商:
  --providers.generic-oauth.auth-url=                   认证/登录URL [$PROVIDERS_GENERIC_OAUTH_AUTH_URL]
  --providers.generic-oauth.token-url=                  令牌URL [$PROVIDERS_GENERIC_OAUTH_TOKEN_URL]
  --providers.generic-oauth.user-url=                   获取用户信息的URL [$PROVIDERS_GENERIC_OAUTH_USER_URL]
  --providers.generic-oauth.client-id=                  客户端ID [$PROVIDERS_GENERIC_OAUTH_CLIENT_ID]
  --providers.generic-oauth.client-secret=              客户端密钥 [$PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET]
  --providers.generic-oauth.scope=                      作用域（默认：profile, email） [$PROVIDERS_GENERIC_OAUTH_SCOPE]
  --providers.generic-oauth.token-style=[header|query]  查询用户URL时令牌的呈现方式（默认：header）
                                                        [$PROVIDERS_GENERIC_OAUTH_TOKEN_STYLE]
  --providers.generic-oauth.resource=                   可选资源指示器 [$PROVIDERS_GENERIC_OAUTH_RESOURCE]

帮助选项:
  -h, --help                                            显示帮助信息

所有选项可通过以下方式提供，优先级从高到低：

1. 命令行参数/标志 - 如上所示
2. 环境变量 - 如上中括号所示
3. 配置文件
   1. 使用INI格式（例如url-path = _oauthpath）
   2. 通过--config标志或$CONFIG环境变量指定文件位置
   3. 可多次指定，按传递顺序读取每个文件

选项详情

• auth-host

  设置后，用户从第三方提供商认证返回时将始终转发到此主机。通过使用中央主机，只需将此auth-host添加为第三方提供商的有效重定向URI。

  主机应不带协议或路径，例如：

  --auth-host="auth.example.com"
  

  更多详情，请参阅概念部分的认证主机模式。

  注意 - 这应视为高级用法，如遇问题请尝试禁用此选项并重新阅读认证主机模式部分。

• config

  用于指定配置文件路径；可多次设置，按传递顺序读取每个文件。选项应使用INI格式，例如：

  url-path = _oauthpath
  

• cookie-domain

  设置后，用户成功完成认证后，若原始请求的主机是给定Cookie域名的子域名，则认证Cookie将为高级Cookie域名设置。这意味着一个Cookie可允许访问多个子域名而无需重新认证。可多次指定。

  例如：

  --cookie-domain="example.com"  --cookie-domain="test.org"
  

  例如，若设置Cookie域为test.com，请求来自app1.test.com，认证后auth cookie将为整个test.com域设置。因此，当app2.test.com的请求需要认证时，将发送原始cookie，无需进一步认证即可允许访问。

  注意，若同一域运行多个traefik/traefik-forward-auth实例，使用Cookie域可能导致Cookie冲突。可通过在每个主机/集群使用不同的cookie-name或在两个实例中使用相同的cookie-secret解决。

• insecure-cookie

  若客户端与traefik之间未使用HTTPS，需传递insecure-cookie选项，此时Cookie的Secure属性将不被设置。

• cookie-name

  设置认证成功后Cookie的名称。

  默认：_forward_auth

• csrf-cookie-name

  设置认证期间临时CSRF Cookie的名称。

  默认：_forward_auth_csrf

• default-action

  指定请求不匹配任何规则时的行为。有效值为auth或allow。

  默认：auth（即所有请求需要认证）

• default-provider

  设置默认认证提供商，可在规则中覆盖。当前有效值为google或oidc。

  默认：google

• domain

  设置后，仅允许匹配给定域名的用户访问。

  例如，设置--domain=example.com --domain=test.org将仅允许example.com或test.org的用户访问。因此允许，而不允许。

  更多详情，请参阅概念部分的用户限制。

• lifetime

  成功认证会话的持续时间（秒）。

  默认：43200（12小时）

• logout-redirect

  设置后，用户登出后将重定向到此URL。

• match-whitelist-or-domain

  启用后，用户若匹配whitelist或domain参数之一即可被允许。

  v3版本将默认启用，v2版本为保持向后兼容默认禁用。

  默认：false

  更多详情，请参阅概念部分的用户限制。

• url-path

  自定义服务处理认证后回调的路径。

  默认：/_oauth

  注意，使用默认覆盖模式时，对此精确路径的请求将被此服务拦截，不会转发到应用。若默认/_oauth路径与应用现有路由冲突，可使用此选项或认证主机模式。

• secret

  用于签名Cookie认证，应为随机字符串（例如openssl rand -hex 16生成）

• whitelist

  设置后，仅允许指定用户访问。

  例如，设置--whitelist=thom@example.com --whitelist=alice@example.com将仅允许这两个用户访问。因此允许，而不允许。

  更多详情，请参阅概念部分的用户限制。

• rule

  指定选择性认证规则。规则格式：rule.<name>.<param>=<value>

  • <name>可为任意字符串，仅用于分组规则
  • <param>可取值：
    • action - 同