ZITADEL项目中JWT令牌角色缺失问题的分析与解决

问题背景

在使用ZITADEL身份管理系统进行用户模拟(impersonation)操作时，开发人员遇到了一个权限相关的问题：通过JWT Profile进行用户模拟后，返回的访问令牌(access token)中缺少应有的用户角色信息。这个问题在v2.70.0版本的自托管环境中被发现，使用PostgreSQL 15.3作为数据库。

问题现象

当按照官方文档进行用户模拟操作时，虽然应用程序配置中已经启用了"将用户角色添加到访问令牌"选项，并且设置了"JWT"作为认证令牌类型，但生成的访问令牌中仍然缺少以下关键字段：

urn:zitadel:iam:org:project:roles
urn:zitadel:iam:org:project:234618608091660860:roles

有趣的是，通过常规登录流程获取的令牌包含这些角色信息，但通过模拟流程获取的令牌则没有。

技术分析

经过深入调查，发现这个问题与OAuth 2.0令牌交换流程中的scope处理机制有关。在ZITADEL中，用户角色信息是通过特定的scope请求来获取的：

1. urn:zitadel:iam:org:projects:roles - 请求所有项目的角色
2. urn:zitadel:iam:org:project:{projectid}:roles - 请求特定项目的角色

然而，仅添加这两个scope并不足以在模拟场景下获取角色信息。关键在于还需要请求第三个关键scope：

3. urn:zitadel:iam:org:project:id:{projectId}:aud - 指定项目的受众范围

解决方案

要解决这个问题，需要在令牌交换请求中包含所有必要的scope：

1. 确保原始令牌(actor_token)已经包含了角色相关的scope
2. 在模拟请求中，除了角色scope外，还必须包含受众scope
3. 完整的scope列表应该包括：
   • urn:zitadel:iam:org:projects:roles
   • urn:zitadel:iam:org:project:{projectid}:roles
   • urn:zitadel:iam:org:project:id:{projectId}:aud

最佳实践

对于需要在ZITADEL中实现用户模拟功能的开发者，建议遵循以下实践：

1. 仔细检查所有相关scope是否已正确配置
2. 在测试阶段解码并验证令牌内容，确保包含所有预期的声明
3. 注意模拟操作可能涉及的跨组织场景，这可能会引发其他问题
4. 保持ZITADEL系统更新到最新版本，以获取所有安全补丁和功能改进

总结

ZITADEL中的用户模拟功能是一个强大的特性，但在使用时需要注意scope的完整配置。通过理解OAuth 2.0令牌交换机制和ZITADEL特定的scope处理逻辑，开发者可以确保获取到包含完整权限信息的访问令牌，从而构建安全可靠的应用程序。