OAuth2 Proxy
OAuth2 Proxy 是一个反向代理,它在用户到达你的应用之前通过 OIDC 提供商对用户进行签名认证。它还可以充当 Nginx、Caddy 或 Traefik 的前向认证端点。使用 Casdoor 作为提供商时,你可以仅允许属于某个 Casdoor 群组的成员或持有某个 Casdoor 角色的用户访问。
本页的配置已通过端到端测试,适用于 OAuth2 Proxy v7.15 和 Casdoor v4.17。
如果你只需要在应用前实现 Casdoor 登录而不需要 OAuth2 Proxy 本身,casdoor-forward-auth 可为 Traefik、Caddy 和 Nginx 完成同样的工作,并在请求头中传递用户的群组和角色。
步骤 1:在 Casdoor 中创建应用
-
在你的用户组织中,添加一个应用(或打开现有应用)。
-
将 OAuth2 Proxy 的回调地址添加到 Redirect URLs:
https://app.example.com/oauth2/callback -
在 OIDC/OAuth 选项卡中,设置:
- Token format:
JWT-Standard - Token group format:
Name (group),这样群组将以devs而不是my-org/devs的形式出现
- Token format:
-
保存,并记下 Client ID 和 Client secret。
为什么使用 JWT-Standard:如果使用默认的 JWT 格式,邮箱未验证的用户将无法登录(OAuth2 Proxy 会拒绝 email_verified: false,而管理员创建的用户通常邮箱未验证),并且 roles 声明包含的是完整的角色对象而不是角色名称。参见 Casdoor 返回的内容。
步骤 2:配置 OAuth2 Proxy
创建 oauth2-proxy.cfg:
provider = "oidc"
oidc_issuer_url = "https://door.example.com"
client_id = "<client ID>"
client_secret = "<client secret>"
redirect_url = "https://app.example.com/oauth2/callback"
scope = "openid email profile"
email_domains = ["*"]
cookie_secret = "<random secret>"
http_address = "0.0.0.0:4180"
upstreams = ["http://127.0.0.1:8080"]
# Let in only members of the Casdoor group "devs"
oidc_groups_claim = "groups"
allowed_groups = ["devs"]
oidc_issuer_url是 Casdoor 的 URL,末尾不带斜杠。它必须与https://door.example.com/.well-known/openid-configuration中显示的issuer完全一致。Casdoor 根据conf/app.conf中的origin构建 issuer,如果origin为空,则根据请求的主机构建;如果两者不一致,OAuth2 Proxy 将因issuer did not match错误而失败。cookie_secret必须是 16、24 或 32 字节,例如openssl rand -base64 32 | tr -- '+/' '-_'的输出。- 保留
profile范围:只有当授予了profile范围时,Casdoor 才会在其 userinfo 端点返回群组和角色。 upstreams是你的应用。
启动它:
oauth2-proxy --config oauth2-proxy.cfg
打开 https://app.example.com。登录 Casdoor 后,devs 群组的成员可以访问该应用,其他人则会收到 403 Forbidden。
改为按角色限制访问
要检查 Casdoor 角色而不是群组,请读取 roles 声明:
oidc_groups_claim = "roles"
allowed_groups = ["admin"]
此时 allowed_groups 中存放的是角色名称,不包含组织信息。
检查 OAuth2 Proxy 接收到的内容
登录后,打开 https://app.example.com/oauth2/userinfo。它会显示 OAuth2 Proxy 提取的群组:
{"user":"d1a5f427-...","email":"alice@example.com","groups":["devs"],"preferredUsername":"alice"}
如果 groups 为空,说明该用户在 Casdoor 中没有群组或角色,或者声明名称错误。如果其中包含类似 {"owner":"my-org","name":"admin",...} 的长 JSON 字符串,说明应用仍使用默认的 JWT 格式且配置了 oidc_groups_claim = "roles";请将格式切换为 JWT-Standard。
Casdoor 发送的内容
用户的群组和角色如何传递给 OAuth2 Proxy 取决于应用的 Token format:
| Token format | groups | roles | Unverified email |
|---|---|---|---|
JWT-Standard | from userinfo, group names | from userinfo, role names | signs in |
JWT-Custom | in the token if Groups is in Token fields | in the token if you add a token attribute roles (see below) | signs in |
JWT (default) | in the token | role objects, not usable for allowed_groups | rejected |
JWT-Empty | in the token | from userinfo, role names | signs in |
使用 JWT-Standard 时,令牌本身仅携带标准的 OIDC 声明。OAuth2 Proxy 会在 Casdoor 的 userinfo 端点查找令牌中缺失的任何声明,因此 groups 和 roles 仍然能够获取,每次登录仅一次。
Token group format 控制所有格式中的群组值:ID(默认)生成 my-org/devs,Name 生成 devs,对于嵌套群组,Path 生成 my-org/parent/devs。
若要将角色名称放入令牌本身,请使用 JWT-Custom 并在 Token attributes 中添加一行:
| Name | Category | Value | Type |
|---|---|---|---|
roles | Existing Field | Roles | Array |
如果 Token fields 不为空,它还会限制 userinfo 端点返回的内容(参见 Token fields)。请包含 Groups(以及当你从 userinfo 读取角色时的 Roles),或者将其留空。
如果你必须保持默认的 JWT 格式,请添加 insecure_oidc_allow_unverified_email = true,以便电子邮件未验证的用户可以登录,并仅通过 groups 进行限制。
将用户传递给你的应用
OAuth2 Proxy 会向其转发的请求添加以下标头(pass_user_headers,默认启用):
| Header | Value |
|---|---|
X-Forwarded-User | Casdoor user ID (the sub claim) |
X-Forwarded-Preferred-Username | Casdoor 用户名,例如 alice |
X-Forwarded-Email | Email address |
X-Forwarded-Groups | Groups (or roles), comma separated |
确保你的应用只能通过 OAuth2 Proxy 访问,否则任何人都可以直接发送这些标头。
若要使用 OAuth2 Proxy 作为 Nginx (auth_request)、Caddy (forward_auth) 或 Traefik (forwardAuth) 的前向认证端点,而不是作为反向代理,请将代理指向其 /oauth2/auth 端点;请参阅 OAuth2 Proxy 文档中的 Integrations。
故障排除
| Symptom | Cause and fix |
|---|---|
issuer did not match the issuer returned by provider at startup | oidc_issuer_url differs from the issuer in Casdoor's discovery document. Set origin in Casdoor's conf/app.conf to its public URL and use the same value here. |
500 after sign-in, log says email in id_token ... isn't verified | The application uses the default JWT format and the user's email is not verified. Switch to JWT-Standard, or set insecure_oidc_allow_unverified_email = true. |
403 Forbidden after sign-in | The user is not in allowed_groups. Open /oauth2/userinfo to see what OAuth2 Proxy received and compare it with Token group format. |
Casdoor shows Redirect URI: ... doesn't exist in the allowed Redirect URI list | Add https://app.example.com/oauth2/callback to the application's Redirect URLs. |