跳到主内容

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 中创建应用​

  1. 在你的用户组织中,添加一个应用(或打开现有应用)。

  2. 将 OAuth2 Proxy 的回调地址添加到 Redirect URLs:

    https://app.example.com/oauth2/callback
  3. 在 OIDC/OAuth 选项卡中,设置:

    • Token format:JWT-Standard
    • Token group format:Name (group),这样群组将以 devs 而不是 my-org/devs 的形式出现
  4. 保存,并记下 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 formatgroupsrolesUnverified email
JWT-Standardfrom userinfo, group namesfrom userinfo, role namessigns in
JWT-Customin the token if Groups is in Token fieldsin the token if you add a token attribute roles (see below)signs in
JWT (default)in the tokenrole objects, not usable for allowed_groupsrejected
JWT-Emptyin the tokenfrom userinfo, role namessigns 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 中添加一行:

NameCategoryValueType
rolesExisting FieldRolesArray

如果 Token fields 不为空,它还会限制 userinfo 端点返回的内容(参见 Token fields)。请包含 Groups(以及当你从 userinfo 读取角色时的 Roles),或者将其留空。

如果你必须保持默认的 JWT 格式,请添加 insecure_oidc_allow_unverified_email = true,以便电子邮件未验证的用户可以登录,并仅通过 groups 进行限制。

将用户传递给你的应用​

OAuth2 Proxy 会向其转发的请求添加以下标头(pass_user_headers,默认启用):

HeaderValue
X-Forwarded-UserCasdoor user ID (the sub claim)
X-Forwarded-Preferred-UsernameCasdoor 用户名,例如 alice
X-Forwarded-EmailEmail address
X-Forwarded-GroupsGroups (or roles), comma separated

确保你的应用只能通过 OAuth2 Proxy 访问,否则任何人都可以直接发送这些标头。

若要使用 OAuth2 Proxy 作为 Nginx (auth_request)、Caddy (forward_auth) 或 Traefik (forwardAuth) 的前向认证端点,而不是作为反向代理,请将代理指向其 /oauth2/auth 端点;请参阅 OAuth2 Proxy 文档中的 Integrations。

故障排除​

SymptomCause and fix
issuer did not match the issuer returned by provider at startupoidc_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 verifiedThe 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-inThe 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 listAdd https://app.example.com/oauth2/callback to the application's Redirect URLs.