跳到主内容

Caddy

casdoor-forward-auth 为位于 Caddy 后面的任何服务提供 Casdoor 单点登录,而无需修改该服务。Caddy 通过其内置的 forward_auth 指令向 casdoor-forward-auth 询问每个请求:已登录的用户带着身份标识的请求头访问服务,其他所有人首先被重定向到 Casdoor 登录页面。

同样的服务也适用于 Traefik 和 Nginx。本页面的设置在 Caddy v2.11 和 casdoor-forward-auth v2.0 下进行了端到端测试。

工作原理​

  1. Caddy 将受保护网站的每个请求发送到 casdoor-forward-auth 的 /auth。
  2. 如果存在有效的会话 cookie,/auth 会返回 200 以及类似 X-Forwarded-User 的头信息,Caddy 会将这些信息复制到发往你的服务的请求中。
  3. 如果没有会话,页面加载(GET、HEAD)会被重定向到 Casdoor。其他请求(POST、PUT 等)会收到 401,因为它们无法跟随登录重定向。Caddy 将这些响应原样返回给浏览器。
  4. 登录后,Casdoor 跳转到 /callback。 casdoor-forward-auth 检查 state、交换授权码、校验访问令牌,把用户保存在签名的 HttpOnly 会话 Cookie 中,然后把用户送回原来请求的页面。

先决条件​

  • Caddy v2
  • 一个 Casdoor 实例(见 服务器安装)
  • 两个指向 Caddy 的主机名,例如 auth.example.com 用于 casdoor-forward-auth,app.example.com 用于受保护的服务

第 1 步:配置 Casdoor 应用​

  1. 在 Casdoor 中创建或编辑一个应用。

  2. 把 casdoor-forward-auth 的回调地址加到 Redirect URLs:

    https://auth.example.com/callback
  3. 记下 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 步:测试集成​

  1. 打开受保护的服务,例如 https://app.example.com。
  2. 你会被跳转到 Casdoor 登录页。
  3. 登录后回到你打开的页面,服务会收到身份请求头。 traefik/whoami 会把它们打印出来,可以在那里检查。

身份请求头​

HeaderValue
X-Forwarded-UserUser name, e.g., alice
X-Forwarded-User-IdUser ID
X-Forwarded-OrganizationOrganization of the user
X-Forwarded-EmailEmail address
X-Forwarded-GroupsComma-separated groups, e.g., built-in/dev,built-in/ops
X-Forwarded-RolesComma-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 的状态。