如何向Azure AD OAuth2客户端凭据令牌添加自定义数据？

客户端凭据流（Client Credentials Flow）本质是服务到服务的无用户认证，默认令牌仅包含应用相关声明（如appid、tenantid）。要添加自定义字段，主要有以下可行方式：

1. Azure门户配置自定义声明（推荐） #

这是官方支持的最简方案，无需修改代码逻辑：

• 登录Azure门户，找到目标应用注册
• 进入令牌配置页面，点击添加可选声明
  • 选择令牌类型为Access（适配你访问API的场景）
  • 若需内置用户类声明（如email），直接勾选对应选项；若要自定义字段（如customUsername），点击添加自定义声明
• 填写自定义声明信息：
  • 声明名称：比如customUsername
  • 源类型选应用，源值设为固定字符串（如你的服务账号名称）
  • 保存配置后，等待5-10分钟让Azure AD同步生效

重新获取令牌后，解析即可看到新增的自定义声明字段。

2. 动态自定义字段的替代方案 #

如果需要每次请求传递不同的自定义值，客户端凭据流本身不支持（无用户上下文），可考虑两种思路：

• 改用授权码流（带用户上下文），该流的令牌包含用户信息，也可通过上述方式添加自定义声明，适合有前端交互的场景
• 自行封装JWT：获取Azure AD令牌后，生成包含自定义字段的新JWT，将Azure AD令牌作为可信字段（如azp）嵌入其中。后端先验证你生成的JWT，再验证内嵌的Azure AD令牌。这种方式需自行维护签名密钥，适合复杂场景。

验证自定义声明 #

可用jwt-decode快速解析令牌确认：

const jwtDecode = require('jwt-decode');
const accessToken = '你的Azure AD访问令牌';
const decodedToken = jwtDecode(accessToken);
console.log(decodedToken.customUsername); // 输出配置的自定义值

注意事项 #

• 客户端凭据流的自定义声明只能是固定值，无法动态传递用户信息，需动态值必须切换到带用户上下文的认证流
• 确保API验证逻辑（passport-azure-ad）不会过滤自定义声明，默认配置下只要令牌签名有效，所有声明都会被解析

内容的提问来源于stack exchange，提问作者Farid Hajnal