如何通过GCP Identity Platform为服务账户添加自定义声明？

核心限制说明 #

首先明确：通过IAM直接生成服务账户的ID Connect Token时，无法直接注入自定义声明——这和用户身份的自定义声明机制不同，服务账户的ID Token由Google IAM直接签发，默认仅包含标准IAM声明，不支持直接添加自定义字段。

可行替代方案 #

方案1：服务账户模拟用户身份（推荐） #

既然你的API已经适配了用户自定义声明的逻辑，最直接的方式是让后端服务通过服务账户模拟特定用户（或专门创建的服务用户），获取带自定义声明的用户ID Token：

• 为服务账户授予roles/iam.serviceAccountTokenCreator权限，允许其模拟目标用户
• 调用IAM的generateIdToken接口时，指定目标用户邮箱作为subject参数
• 生成的ID Token会包含该用户已配置的所有自定义声明，完全复用现有API的认证逻辑

方案2：自定义令牌代理服务 #

如果必须使用服务账户自身身份，可搭建轻量令牌代理服务：

• 后端服务先向代理请求服务账户的ID Token（或自行调用IAM生成）
• 代理验证原Token合法性后，添加自定义声明并重新签名令牌
• 将重新签名后的Token返回给后端服务，用于API调用
• 注意：重新签名的密钥需与API认证逻辑兼容，确保后端能验证新Token有效性

方案3：IAM角色映射自定义权限 #

如果自定义声明仅用于权限控制，可绕过Token修改，直接在API后端做逻辑映射：

• API认证时提取服务账户的邮箱或唯一ID
• 通过内部权限服务（或IAM角色绑定）查询该服务账户对应的权限
• 动态生成权限逻辑，无需修改ID Token本身

操作示例（方案1） #

使用gcloud CLI模拟用户生成带自定义声明的ID Token：

gcloud auth print-identity-token --impersonate-service-account=目标用户邮箱@your-domain.com --audiences=你的API受众

生成的Token包含该用户已配置的所有自定义声明，可直接用于API的Bearer认证。

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