如何为Docker Swarm服务配置Traefik ForwardAuth与Keycloak认证

一、Keycloak客户端配置 #

1. 登录Keycloak控制台进入目标Realm，创建新客户端：
   • 客户端ID：自定义名称（比如ttyd-auth，后续配置会用到）
   • 客户端协议：选择openid-connect
   • 访问类型：选择confidential（需要生成客户端密钥用于认证）
2. 客户端详情配置：
   • Valid Redirect URIs：填写ttyd服务的完整访问URL/_oauth2/callback（例如https://ttyd.yourdomain.com/_oauth2/callback），测试阶段可临时填https://ttyd.yourdomain.com/*
   • Web Origins：填写ttyd服务的域名（例如https://ttyd.yourdomain.com），或填*（仅测试环境使用）
3. 切换到「Credentials」标签，复制生成的Client Secret，保存备用

二、部署oauth2-proxy作为认证中间层 #

Traefik的ForwardAuth本身不处理OAuth2流程，需要借助oauth2-proxy桥接Keycloak与Traefik。将以下服务定义部署到Docker Swarm：

version: '3.8'
services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.5.1
    command:
      - --provider=keycloak
      - --client-id=ttyd-auth  # 对应Keycloak的客户端ID
      - --client-secret=你的Keycloak客户端密钥  # 替换为刚才复制的密钥
      - --redirect-url=https://ttyd.yourdomain.com/_oauth2/callback  # 和Keycloak配置的一致
      - --oidc-issuer-url=https://keycloak.yourdomain.com/realms/你的Realm名称  # Keycloak Realm的根地址
      - --cookie-secret=$(openssl rand -hex 16)  # 生成随机Cookie密钥，也可手动指定32位字符串
      - --http-address=0.0.0.0:4180
      - --upstream=file:///dev/null
      - --skip-provider-button  # 直接跳转Keycloak登录页，跳过选择界面
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.role == manager
    networks:
      - traefik-public  # 确保和Traefik在同一Overlay网络
    labels:
      - traefik.enable=true
      - traefik.http.services.oauth2-proxy.loadbalancer.server.port=4180
      - traefik.http.routers.oauth2-proxy.rule=Host(`ttyd.yourdomain.com`) && Path(`/_oauth2/*`)
      - traefik.http.routers.oauth2-proxy.entrypoints=websecure
      - traefik.http.routers.oauth2-proxy.tls.certresolver=letsencrypt  # 适配你的证书 resolver

三、配置Traefik ForwardAuth中间件 #

在Traefik的动态配置文件（如dynamic.yml）中添加以下内容：

http:
  middlewares:
    keycloak-auth:
      forwardAuth:
        address: http://oauth2-proxy:4180  # 同一网络下直接用服务名访问oauth2-proxy
        authResponseHeaders:
          - X-Forwarded-User  # 传递认证后的用户信息到ttyd服务
        trustForwardHeader: true

四、关联中间件到ttyd服务 #

修改ttyd服务的Docker Swarm部署配置，添加Traefik标签关联认证中间件：

services:
  ttyd:
    image: tsl0922/ttyd:latest
    command: ttyd bash
    deploy:
      replicas: 1
    networks:
      - traefik-public
    labels:
      - traefik.enable=true
      - traefik.http.services.ttyd.loadbalancer.server.port=7681  # ttyd默认端口
      - traefik.http.routers.ttyd.rule=Host(`ttyd.yourdomain.com`)
      - traefik.http.routers.ttyd.entrypoints=websecure
      - traefik.http.routers.ttyd.tls.certresolver=letsencrypt
      - traefik.http.routers.ttyd.middlewares=keycloak-auth  # 关联Keycloak认证中间件

关键说明 #

• 关于Keycloak OpenID端点：无需手动指定单个端点，oauth2-proxy会通过oidc-issuer-url自动拉取OpenID配置中的所有端点（包括授权、令牌、用户信息端点等）
• Cookie密钥：必须使用随机生成的32位字符串，避免安全风险
• 网络配置：确保Traefik、oauth2-proxy、ttyd服务都在同一Overlay网络中，保证服务间通信

验证 #

部署所有服务后，访问ttyd.yourdomain.com，会自动跳转到Keycloak登录页面。登录成功后，将自动重定向到ttyd服务界面，未认证用户无法直接访问。

内容的提问来源于stack exchange，提问作者Jakob Guldberg Aaes