使用OAuth2.0调用Document AI API遇权限拒绝错误的排查求助

问题描述 #

生成access token调用Document AI API时触发PERMISSION_DENIED错误，仅IAM中设为所有者的用户能正常通过OAuth2.0调用。未在API调用中指定服务账号，需明确当前调用关联的身份，以及排查权限问题的步骤。已尝试为所有服务账号分配所有者角色，但问题未解决。

错误信息：

{
    "error": {
        "code": 403,
        "message": "Permission 'documentai.processors.processOnline' denied on resource '//documentai.googleapis.com/projects/205806916918/locations/us/processors/1c3f33f7cb3a533e' (or it may not exist).",
        "status": "PERMISSION_DENIED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "IAM_PERMISSION_DENIED",
                "domain": "documentai.googleapis.com",
                "metadata": {
                    "resource": "projects/205806916918/locations/us/processors/1c3f33f7cb3a533e",
                    "permission": "documentai.processors.processOnline"
                }
            }
        ]
    }
}

当前IAM权限截图：

一、当前API调用关联的身份说明 #

未指定服务账号时，API调用使用的是当前运行环境的默认身份，分场景：

• 本地开发环境（如用gcloud auth login登录后）：身份为你登录的用户账号（非服务账号）
• GCP托管服务（GCE/GKE/Cloud Functions等）：身份为资源绑定的默认服务账号（例如Compute Engine默认服务账号格式为[项目编号]-compute@developer.gserviceaccount.com）
• OAuth2.0授权码流程：身份为授权的用户账号

你可以通过解码access token确认具体身份：

• 本地环境执行命令：gcloud auth print-access-token | base64 -d | jq '.email'
• 直接解码token的payload部分，查看email字段值，即为当前调用身份

二、权限问题排查步骤 #

1. 确认调用身份的IAM权限配置 #

• 不要直接分配所有者角色，遵循最小权限原则，给目标身份添加Document AI Processor User（roles/documentai.processorUser）角色，该角色包含所需的documentai.processors.processOnline权限
• 检查权限是直接绑定到该身份，还是通过组/组织单元继承。如果是继承，确认没有对应的Deny规则阻断权限
• 验证错误信息中的processor资源路径是否正确：确认项目ID、区域、processor ID与实际存在的资源一致，避免路径拼写错误

2. 检查access token有效性 #

• 确认token的aud（受众）字段值为https://documentai.googleapis.com/，避免因受众不匹配导致权限验证失败
• 检查token是否过期，重新生成access token后再次测试调用

3. 排除IAM缓存延迟 #

IAM权限变更通常需要5-10分钟生效，若刚修改完权限，等待一段时间后再测试

4. 检查组织政策限制 #

查看项目的组织政策设置，确认没有禁止Document AI API调用、或限制特定身份访问资源的政策

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