Caddy
casdoor-forward-auth 为位于 Caddy 后面的任何服务提供 Casdoor 单点登录,而无需修改该服务。Caddy 通过其内置的 forward_auth 指令向 casdoor-forward-auth 询问每个请求:已登录的用户带着身份标识的请求头访问服务,其他所有人首先被重定向到 Casdoor 登录页面。
同样的服务也适用于 Traefik 和 Nginx。本页面的设置在 Caddy v2.11 和 casdoor-forward-auth v2.0 下进行了端到端测试。
工作原理
- Caddy 将受保护网站的每个请求发送到 casdoor-forward-auth 的
/auth。 - 如果存在有效的会话 cookie,
/auth会返回200以及类似X-Forwarded-User的头信息,Caddy 会将这些信息复制到发往你的服务的请求中。 - 如果没有会话,页面加载(
GET、HEAD)会被重定向到 Casdoor。其他请求(POST、PUT等)会收到401,因为它们无法跟随登录重定向。Caddy 将这些响应原样返回给浏览器。 - 登录后,Casdoor 跳转到
/callback。 casdoor-forward-auth 检查state、交换授权码、校验访问令牌,把用户保存在签名的HttpOnly会话 Cookie 中,然后把用户送回原来请求的页面。
先决条件
- Caddy v2
- 一个 Casdoor 实例(见 服务器安装)
- 两个指向 Caddy 的主机名,例如
auth.example.com用于 casdoor-forward-auth,app.example.com用于受保护的服务
第 1 步:配置 Casdoor 应用
-
在 Casdoor 中创建或编辑一个应用。
-
把 casdoor-forward-auth 的回调地址加到 Redirect URLs:
https://auth.example.com/callback -
记下 Client ID 和 Client secret。
步骤 2:部署 casdoor-forward-auth 和 Caddy
创建一个 Caddyfile:
auth.example.com {
reverse_proxy casdoor-forward-auth:9999
}
app.example.com {
forward_auth casdoor-forward-auth:9999 {
uri /auth
copy_headers X-Forwarded-User X-Forwarded-User-Id X-Forwarded-Organization X-Forwarded-Email X-Forwarded-Groups X-Forwarded-Roles
}
reverse_proxy app:8080
}
app:8080 是你想要保护的服务。要保护更多服务,请为每个站点提供相同的 forward_auth 块。不要在 casdoor-forward-auth 自身的站点上放置 forward_auth。
创建 docker-compose.yml:
services:
caddy:
image: caddy:2
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
casdoor-forward-auth:
image: ghcr.io/casdoor/casdoor-forward-auth:latest
environment:
CASDOOR_ENDPOINT: https://door.casdoor.com
CLIENT_ID: <client ID>
CLIENT_SECRET: <client secret>
EXTERNAL_URL: https://auth.example.com
COOKIE_DOMAIN: example.com
COOKIE_SECRET: <random string of at least 32 characters>
app:
image: traefik/whoami
command: --port 8080
volumes:
caddy_data:
替换占位值:
CASDOOR_ENDPOINT:你的 Casdoor 服务器地址CLIENT_ID和CLIENT_SECRET:第 1 步中得到的值EXTERNAL_URL:casdoor-forward-auth 的公网地址。<EXTERNAL_URL>/callback必须是应用的 Redirect URL 之一COOKIE_DOMAIN:受保护主机的父域名,这样会话 Cookie 会发送到所有这些主机COOKIE_SECRET:一个随机密钥,例如用openssl rand -hex 32生成。保持不变:修改它会让所有人登出
Caddy 会自动为这两个主机获取 HTTPS 证书。启动服务:
docker compose up -d
第 3 步:测试集成
- 打开受保护的服务,例如
https://app.example.com。 - 你会被跳转到 Casdoor 登录页。
- 登录后回到你打开的页面,服务会收到身份请求头。
traefik/whoami会把它们打印出来,可以在那里检查。
身份请求头
| Header | Value |
|---|---|
X-Forwarded-User | User name, e.g., alice |
X-Forwarded-User-Id | User ID |
X-Forwarded-Organization | Organization of the user |
X-Forwarded-Email | Email address |
X-Forwarded-Groups | Comma-separated groups, e.g., built-in/dev,built-in/ops |
X-Forwarded-Roles | Comma-separated role names |
casdoor-forward-auth 始终返回所有这些头信息(可能为空),因此 Caddy 的 copy_headers 会替换客户端在相同头信息中发送的任何内容。确保受保护的服务只能通过 Caddy 访问,否则任何人都可以直接发送这些头信息。
限制访问
默认情况下,任何能够登录 Casdoor 应用的用户都会被允许访问。若要仅允许具有特定 Casdoor 角色或群组的用户访问,请在该站点的 uri 中添加 roles 和/或 groups(以逗号分隔):
app.example.com {
forward_auth casdoor-forward-auth:9999 {
uri /auth?roles=admin,ops
copy_headers X-Forwarded-User X-Forwarded-User-Id X-Forwarded-Organization X-Forwarded-Email X-Forwarded-Groups X-Forwarded-Roles
}
reverse_proxy app:8080
}
用户需至少拥有列出的一个角色才能通过;如果同时指定了 groups(例如 groups=built-in/dev),则还需至少拥有列出的一个群组。其他已登录的用户将收到 403 错误。每个站点可以有自己的规则;ALLOWED_ROLES 和 ALLOWED_GROUPS 环境变量为所有站点设置统一规则。
这也涵盖了“先注册,后获权”的场景:新用户(例如通过 Google 注册的用户)没有角色,因此会收到 403 错误,直到管理员在 Casdoor 的 Roles 页面为其分配角色。角色和群组在登录时读取,因此变更后,用户需要打开 https://auth.example.com/logout 并重新登录,或者等待会话结束(SESSION_TTL)。
配置与登出
casdoor-forward-auth 使用相同的环境变量进行配置,适用于各种反向代理;请参阅 Traefik 页面上的 Configuration。/logout 会清除 casdoor-forward-auth 的会话(若附加 ?rd=<url> 则在之后重定向);用户仍保持登录 Casdoor 的状态。