Claude 应用网关新增 oidc.user_id_claim：用 Entra ID 的 oid 识别用户
企业里用 Claude 应用网关（Claude apps gateway）统一接入 Claude Code 的团队，登录一般走 OIDC 单点登录。CLI 2.1.312 给网关加了一个很实用的配置项：oidc.user_id_claim。
变化内容
更新说明的意思是：网关现在可以通过 oidc.user_id_claim 指定 id_token 中 sub 以外的某个声明来识别用户，例如 Microsoft Entra ID 的 oid。
以前网关默认拿 id_token 里的 sub 当用户的唯一标识。在大多数身份提供商那里这没问题，但 Entra ID（原 Azure AD）是个典型的例外。
为什么 Entra ID 需要它
在 Entra ID 里，sub 是「成对标识」：同一个人，对不同的应用注册会得到不同的 sub。这会带来几个麻烦：
- 跨应用对不上号：网关看到的
sub，和你在其他内部系统、审计平台里看到的用户 ID 不一样，做用量统计或权限对账时很难关联； - 换应用注册就「换了个人」：如果哪天重建了应用注册，所有人的
sub都会变，网关会把老用户当成新用户； - 和目录数据脱节：管理员在 Entra 后台、Microsoft Graph 里查用户，用的都是对象 ID，也就是
oid。
oid 是用户在整个租户内不变的对象 ID，不随应用变化。用它当用户标识，网关侧的数据就能和公司目录直接对上。
怎么配置
按配置名的字面意思，在网关的 OIDC 设置里把 user_id_claim 指向你想用的声明即可。下面只是示意写法，具体放在哪个文件、用什么格式，请以你部署的网关文档为准：
oidc:
# 其他 OIDC 配置保持不变
user_id_claim: oid不配置时仍然沿用 sub，所以这次升级本身不会改变现有行为。
选哪个声明
- Entra ID：优先用
oid。它在租户内稳定，而且是 Graph API 里的标准用户 ID； - 其他身份提供商：如果
sub本身就是稳定的全局 ID（大多数 IdP 都是），没必要改； - 不建议用邮箱当 ID：
email、preferred_username会随改名、换域名而变化，适合展示，不适合当主键。
另外要确认 id_token 里确实带了你指定的声明。有些 IdP 需要在应用注册里额外勾选，才会把对应声明放进 token。
迁移时注意
如果网关已经用 sub 跑了一段时间，切到 oid 后，用户标识会整体变化。可以想到的影响包括：按用户统计的用量历史断档、按用户 ID 配置的权限或额度需要重新对应。建议先在测试环境确认新 ID 的格式，再挑一个低峰时间切换，并提前通知负责用量报表的同事。
小结
oidc.user_id_claim 是一个面向企业管理员的小改动，但对 Entra ID 用户很关键：用户 ID 从此可以跟公司目录保持一致，不再因为应用注册不同而「一人多号」。没用 Entra ID、或者 sub 已经够用的团队，不需要做任何调整。