Wiki.js 2.5.296集成Azure AD B2C（OpenID Connect）认证故障排查

一、获取Wiki.js的额外日志 #

• 修改Wiki.js配置文件（默认是config.yml），启用调试级日志：

  log:
    level: debug
    format: json
  

  保存后重启Wiki.js服务，日志会输出到logs/app.log（本地部署）；如果是Docker部署，用docker logs <容器名称>查看实时日志。调试日志会详细记录OIDC流程的每一步，包括请求参数、响应内容、声明映射结果等。
• 用抓包工具（如Charles、Wireshark）捕获Wiki.js与Azure AD B2C之间的HTTP请求，重点查看：
  • 授权码交换请求（/token端点）的响应是否包含有效access_token和id_token
  • UserInfo端点请求的完整响应内容，确认声明的结构和键名

二、核心排查点 #

• 检查声明映射配置：在Wiki.js的「通用OpenID Connect/OAuth2」设置中，确认「用户ID字段」「邮箱字段」的配置与Azure AD B2C返回的声明键名完全匹配。比如Azure AD B2C可能返回emails[0]而非email，需将Wiki.js的邮箱字段映射改为emails[0]，或者在Azure AD B2C自定义策略中把声明重命名为email。
• 验证ID Token内容：用jwt.io解析返回的id_token，确认其中包含email声明。部分情况下Wiki.js会优先从ID Token读取用户信息，而非调用UserInfo端点，若ID Token中缺失该声明，会导致认证失败。
• 核对Azure AD B2C应用配置：
  • 重定向URI必须与Wiki.js配置的完全一致（包括协议、域名、端口、结尾斜杠）
  • 应用注册已添加openid、profile、email权限
  • 自定义策略的<OutputClaims>和<RelyingParty>节点已正确配置，确保email、sub等声明输出到ID Token或UserInfo响应
• 手动验证OIDC流程：
  1. 手动构造授权请求获取授权码
  2. 用授权码调用/token端点换取access_token
  3. 携带access_token调用UserInfo端点，确认返回的用户数据结构符合Wiki.js的期望（比如顶级字段而非嵌套结构）

三、源码调试（若上述方法未定位问题） #

• 下载Wiki.js 2.5.296版本的源码，找到OIDC认证逻辑文件：server/modules/auth/providers/oidc.js
• 在本地搭建Node.js调试环境，在关键步骤添加console.log输出，比如：
  • 换取token后的响应数据
  • 调用UserInfo端点后的返回结果
  • 声明映射后的用户信息对象
• 重点关注认证成功后，Wiki.js如何校验用户信息，是否因字段缺失、格式错误导致判定为无效用户，进而返回「无效的邮箱/用户名或密码」提示。

四、通用OIDC集成经验 #

• 优先让ID Token包含所有必要声明，减少对UserInfo端点的依赖，避免额外的网络请求和潜在的兼容性问题
• 严格匹配重定向URI，任何细微差异（如http/https、斜杠）都会导致认证失败
• 注意声明键名的大小写和格式，不同OIDC提供商的返回格式可能不同，必须与Wiki.js的映射配置完全一致
• 针对Azure AD B2C，自定义策略需确保将所需声明明确输出到ID Token或UserInfo响应中，避免默认策略遗漏关键字段

内容的提问来源于stack exchange，提问作者Røye