Wekan 对接 AD FS 4.0 单点登录OAUTH2_ADFS_ENABLED 开关与 OAuth2/OIDC 全参数实战【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本篇围绕 Wekan 的docs/Features/Login/ADFS.md展开讲清楚如何让 Wekan 通过 OAuth 2 OpenID 协议接入微软 AD FS 4.0 实现 SSO 登录给出 Snap、Docker、启动脚本三种部署形态下的最小配置写法并结合仓库源码packages/wekan-oidc/oidc_server.js剖析该开关在登录流程中到底改变了哪一步行为最后补齐让 ADFS 登录真正跑通所需的完整参数、账号合并策略与排错方法。读完后可直接在自建的 AD FS 4.0 环境上完成 Wekan 的 SSO 配置与验证。一、背景Wekan 为 AD FS 4.0 增加了什么AD FS 4.0Windows Server 2012 R2 自带的 Active Directory Federation Services是微软第一代支持 OAuth 2 / OpenID Connect 协议的版本企业常用它给内部 Web 应用提供 SSO。Wekan 的通用 OIDC 客户端原生走token 端点换取令牌 → 调 UserInfo 端点取用户信息的标准流程而 AD FS 4.0 的部署场景中用户声明claims往往是直接放在访问令牌JWT里下发的并没有可依赖的 UserInfo 端点。为此 Wekan 在 v4.302020-09-13版本中新增了OAUTH2_ADFS_ENABLED设置专门用于AD FS 4.0 using OAuth 2 and OpenID的 SSO 集成见 old-CHANGELOG/2020.md 中 v4.30 条目对应社区 issue #3184 与 PR #3269。该开关的语义可以概括为一句话告诉 Wekan 的 OIDC 客户端用户声明在令牌内部请就地解码 JWT不要再请求 UserInfo 端点。仓库中 docs/Features/Login/Apple.md 对同名机制给出了明确解释Sign in with Apple 因没有公开的 userinfo 端点也复用这一开关OAUTH2_ADFS_ENABLEDtrue尽管名字叫 ADFS这个开关只是告诉 Wekan 的 OIDC 客户端从 access/id token 里读声明而不是调用 userinfo 端点——与 ADFS 和 Azure AD B2C 用的是同一套机制二、最小配置两个开关按部署形态选择关联文档给出的最小配置就是两个布尔开关启用 OAuth2 连接、启用 ADFS 模式。下面完整保留原文档的两种形态。Snap 形态启用sudo snap set oauth2-enabledtrue sudo snap set oauth2-adfs-enabledtrue关闭unsetsudo snap unset oauth2-enabled sudo snap unset oauth2-adfs-enabled两点补充依据Snap 配置键oauth2-adfs-enabled在 snap-src/bin/config 中定义默认值false描述为 Enable OAuth2 ADFS. Default: false其snap help输出snap-src/bin/wekan-help也明确标注 OAuth2 ADFS Enabled.Also requires oauth2-enabledtrue即 ADFS 开关必须与oauth2-enabled同时打开才生效。snap help中展示的标准写法带实例名snap set wekan oauth2-adfs-enabledtrue与原文档省略实例名的写法在默认单实例场景下等价。Docker 与 .sh/.bat 启动脚本形态OAUTH2_ENABLEDtrue OAUTH2_ADFS_ENABLEDtrue关闭方式是把对应行删除或注释掉。各形态中的默认状态如下可逐一对照docker-compose.yml 中OAUTH2_ENABLEDtrue与OAUTH2_ADFS_ENABLEDfalse默认均处于注释状态#- ...需要取消注释并改为true各 FerretDB/ToroDB 变体 compose 文件如 docker-compose-ferretdb-v2-postgresql.yml保持同样的注释模板Dockerfile 通过 ENV 把OAUTH2_ADFS_ENABLEDfalse设为镜像内默认值start-wekan.sh 与 start-wekan.bat 中同样是注释掉的#export OAUTH2_ADFS_ENABLEDfalse/REM SET OAUTH2_ADFS_ENABLEDfalse示例行取消注释并改为true即可。三、源码级剖析开关在登录流程中改变了哪一步ADFS 开关的消费点在通用 OIDC 登录回调查询函数中核心逻辑在 packages/wekan-oidc/oidc_server.jsvar claimsInAccessToken (process.env.OAUTH2_ADFS_ENABLED true || process.env.OAUTH2_ADFS_ENABLED true || process.env.OAUTH2_B2C_ENABLED true || process.env.OAUTH2_B2C_ENABLED true) || false; if(claimsInAccessToken) { // hack when using custom claims in the accessToken. On premise ADFS. And Azure AD B2C. userinfo getTokenContent(accessToken); } else { // normal behaviour, getting the claims from UserInfo endpoint. userinfo await getUserInfo(accessToken); }从源码结构看有三点值得注意同时接受字符串true与布尔true两种形式。这与 v4.30 提交说明Add testing for both string and boolean version of true一致——Snap 与 Docker 注入环境变量的类型不同双兼容保证两种部署形态行为一致。开启后 userinfo 数据源切换为本地解码 JWT。getTokenContent()oidc_server.js把令牌按.切成三段将第二段payloadbase64 解码为 JSON 得到声明整个流程不再发起任何针对 UserInfo 端点的 HTTP 请求。因此对 ADFS 部署而言OAUTH2_USERINFO_ENDPOINT是否配置都不影响登录令牌本身必须携带完整声明。与OAUTH2_B2C_ENABLEDAzure AD B2C共用同一条 token-claims 分支B2C 分支额外要求令牌中必须存在emails声明数组否则直接抛出带提示的异常oidc_server.js。拿到 userinfo 后字段到 Wekan 用户属性的映射由四个OAUTH2_*_MAP环境变量决定oidc_server.js环境变量Snap 键映射到的用户属性OAUTH2_ID_MAPoauth2-id-map唯一 IDservices.oidc.idOAUTH2_USERNAME_MAPoauth2-username-map用户名OAUTH2_FULLNAME_MAPoauth2-fullname-map全名OAUTH2_EMAIL_MAPoauth2-email-map邮箱此外源码还会捕获令牌中的email_verified声明布尔true或字符串true均可见 oidc_server.js供后续账号合并策略判断使用。四、让 ADFS 登录真正跑通完整参数清单两个开关只是启用分支完整的 ADFS SSO 仍需要一套通用 OIDC 连接参数。参数命名与默认值以 docker-compose.yml 的 OAUTH2 AZURE 注释块ADFS/B2C 开关正位于此块内和 snap-src/bin/config 的键定义为准逐项说明如下环境变量Snap 键必填说明OAUTH2_ENABLEDoauth2-enabled是总开关默认falseOAUTH2_ADFS_ENABLEDoauth2-adfs-enabled是启用 token-claims 模式默认falseOAUTH2_CLIENT_IDoauth2-client-id是AD FS 中注册的 Relying Party信任的 relying party应用标识符OAUTH2_SECREToauth2-secret是注册应用时生成的密钥Docker 中也可改用OAUTH2_SECRET_FILE从 secrets 文件读取OAUTH2_SERVER_URLoauth2-server-url是AD FS 服务器地址如https://adfs.example.com/OAUTH2_AUTH_ENDPOINToauth2-auth-endpoint是授权端点路径AD FS 4.0 的 OAuth/OIDC 授权端点通常为/adfs/oauth2/authorize一类路径具体以 AD FS 服务器输出的端点为准OAUTH2_TOKEN_ENDPOINToauth2-token-endpoint是令牌端点路径通常为/adfs/oauth2/token一类路径OAUTH2_USERINFO_ENDPOINToauth2-userinfo-endpoint否ADFS 模式下源码不再调用该端点可留空OAUTH2_REQUEST_PERMISSIONSoauth2-request-permissions否请求的 scopes空格分隔且不要加引号默认openid profile email键定义见 snap-src/bin/configOAUTH2_ID_MAP/OAUTH2_USERNAME_MAP/OAUTH2_FULLNAME_MAP/OAUTH2_EMAIL_MAP是声明名映射取值须与 AD FS 令牌中实际携带的 claim 名一致端点配置允许两种写法相对OAUTH2_SERVER_URL的路径或完整的http(s)://URL见 docs/Features/Login/OAuth2.md 中 Spring Authorization Server 一节的说明。AD FS 侧必须同步完成的三件事属于 AD FS 管理域不在 Wekan 仓库范围内在 AD FS 中为 Wekan 创建 Relying Party Trust拿到 Application Identifier对应OAUTH2_CLIENT_ID与密钥回调地址登记为https://wekan域名/_oauth/oidcWekan 通用 OIDC 的固定回调路径见 docs/Features/Login/OAuth2.md 各提供商小节在 Claim Rules声明规则中确保访问令牌携带 Wekan 映射所需的字段唯一 ID、邮箱、姓名等。若 AD FS 默认声明与你的OAUTH2_*_MAP取值不一致登录虽能完成令牌交换但映射出的用户属性会缺失——这正是开关已开却登录异常最常见的根因。五、账号注册、合并与管理员权限ADFS 登录成功后Wekan 侧还有三个策略开关值得在部署文档中一并固定下来它们在 docker-compose.yml 的注释块与 docs/Features/Login/OAuth2.md 中有权威定义OAUTH2_AUTO_REGISTRATION默认true设为false时尚无 Wekan 账号按已验证邮箱匹配的用户被拒绝登录适用于账号必须在 Wekan 侧先行预置的管控场景OAUTH2_MERGE_EXISTING_USERS默认false为true时OIDC 登录可挂接到同邮箱的既有密码/LDAP 账号上。源码注释GHSA-mp7g-hj5q-gxhq明确警告仅在完全信任 AD FS 邮件声明的前提下才应开启且提供商必须下发email_verifiedtrue否则合并不会发生——这也是 oidc_server.js 专门捕获该声明的原因OAUTH2_ADMIN_GROUPS默认空逗号/空白分隔的 OIDC 组名列表组成员登录即获得 Wekan 全局管理员权限机制与 LDAP 的LDAP_SYNC_ADMIN_GROUPS对应实现见 oidc_server.js 的groupRoutineOnLogin。另外若希望登录后持续同步邮箱/姓名/用户名以及 AD FS 组信息组到 Wekan 团队/组织的映射可设置PROPAGATE_OIDC_DATAtrue配合提供商下发的groups/wekanGroups声明使用详细用法见 packages/wekan-oidc/README.md该文档以 authentik 为例wekanGroups的 JSON 结构与 ADFS 自定义声明完全同构。六、验证与排错Wekan 的 OIDC 流程自带调试输出与防御性报错排错时优先利用这两点打开调试开关设置DEBUGtrue后oidc_server.js 会在控制台打印 token 响应与 userinfo 解码结果XXX: getToken response/XXX: userinfo可直接核对 AD FS 令牌中到底携带了哪些 claimSnap 形态下用sudo snap logs wekan.wekan查看日志。读懂三类内置报错均为 oidc_server.js 中针对 #5174 问题专门补充的提示the token endpoint returned no usable response—— 授权码交换失败检查 client ID/secret 与回调地址是否一致the token endpoint returned neither access_token nor id_token—— AD FS 返回了 200 但没有令牌输出中会附带返回字段名与error_description直接对照 AD FS 日志定位claims were expected inside the access token, which could not be parsed—— ADFS 模式开启但令牌不是可解析的 JWT通常是 scope/声明规则配置导致令牌类型不符。排错检查顺序建议oauth2-enabled是否为true→ AD FS 回调地址是否精确等于https://域名/_oauth/oidc→ 令牌 payload 中的 claim 名与四个OAUTH2_*_MAP是否逐一对应 → 登录用户邮箱是否已验证影响OAUTH2_MERGE_EXISTING_USERS路径。小结Wekan 对接 AD FS 4.0 的核心就是OAUTH2_ENABLEDtrueOAUTH2_ADFS_ENABLEDtrue两个开关Snap 下为oauth2-enabled/oauth2-adfs-enabled其本质是把 OIDC 客户端的 userinfo 数据源从UserInfo 端点切换为令牌内 JWT 声明。配合OAUTH2_CLIENT_ID、OAUTH2_SERVER_URL、授权/令牌端点路径与四个 claim 映射变量再根据安全策略固定OAUTH2_AUTO_REGISTRATION、OAUTH2_MERGE_EXISTING_USERS、OAUTH2_ADMIN_GROUPS三个策略项即可完成一次可验证、可运维的 AD FS SSO 集成同一套机制同样适用于 Azure AD B2COAUTH2_B2C_ENABLED与 Sign in with Apple 等声明在令牌内的提供商。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考