AWS EC2中使用Workload Identity Federation调用Gmail API报错排查

• EC2实例IAM角色权限与信任策略问题
  确保EC2关联的AWS IAM角色具备sts:GetCallerIdentity权限，且信任策略允许EC2服务（ec2.amazonaws.com）扮演该角色。可补充如下权限策略：

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": "sts:GetCallerIdentity",
        "Resource": "*"
      }
    ]
  }
  

• Workload Identity Pool属性映射不匹配
  检查Google Cloud中Workload Identity Pool的属性映射规则，必须将AWS的${aws:PrincipalArn}映射到attribute.aws_role。同时确认gcloud命令中member参数里的attribute.aws_role值，与EC2实例使用的AWS角色ARN完全一致（包括大小写、账号ID、角色名）。

• 服务账号域级委派配置验证
  确认Google Workspace管理控制台中，服务账号的域级委派已添加所有所需Scopes：

  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/admin.directory.user.readonly
    确保委派权限未被限制，且服务账号已被授权代表目标用户操作。

• GoogleAuth配置补充
  本地JWT认证与Workload Identity Federation逻辑不同，需调整代码配置：

  1. 确保client_library_config.json是Workload Identity Federation的外部账号配置文件（类型为external_account），而非普通服务账号密钥文件。
  2. 在GoogleAuth初始化时显式禁用JWT模式：

     const auth = new GoogleAuth({
       scopes,
       subject: "XXXX@XXXX.com",
       projectId: "XXXXX",
       useJWTAccessWithScope: false
     });
     

• EC2元数据服务访问验证
  在EC2实例上执行命令，确认能正常获取AWS临时凭证：

  curl http://169.254.169.254/latest/meta-data/iam/security-credentials/<your-ec2-role-name>
  

  若无法获取，检查实例的IMDS是否被禁用，或网络策略是否阻止访问。

• 权限绑定的成员参数正确性
  重新核对gcloud命令中的member参数，确保principalSet路径完全正确：

  gcloud iam service-accounts add-iam-policy-binding <service_account_email>  \    
  --role=roles/iam.workloadIdentityUser  \ 
  --member="principalSet://iam.googleapis.com/projects/<project_id>/locations/global/workloadIdentityPools/<pool_id>/attribute.aws_role/arn:aws:sts::<aws_account_id>:assumed-role/<aws_role_name>" \ 
  --project <google_cloud_project_name>
  

  重点检查project_id、pool_id、AWS账号ID、角色名的拼写，任何错误都会导致权限验证失败。

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