如何通过服务账号获取People API与Directory API的域用户数据
核心问题说明
服务账号默认不具备Google Workspace域内的用户数据访问权限,必须通过域宽委派机制完成权限打通,且在调用时显式模拟具备权限的域内管理员身份,否则无论怎么调整代码都会返回403权限错误。
服务账号侧前置配置
- 创建/编辑服务账号时,务必勾选启用Google Workspace域宽委派开关,记录下该服务账号对应的唯一客户端ID,后续管理员配置需要用到
- 提前梳理好需要的API权限范围(OAuth Scope),两类API不要漏配:
- Directory API 读取域用户基础信息:
https://www.googleapis.com/auth/admin.directory.user.readonly,如果业务需要对用户数据做校验类写操作,再追加对应写权限的scope - People API 拉取域内目录关联的用户信息:
https://www.googleapis.com/auth/directory.readonly,如果需要获取用户公开资料维度的字段,再追加https://www.googleapis.com/auth/userinfo.profile
- Directory API 读取域用户基础信息:
Workspace 管理控制台授权配置
- 使用Workspace超级管理员账号登录管理后台,进入API控制板块的域宽委派配置页
- 触发“添加新委派”流程,将之前记录的服务账号客户端ID填入对应输入框,把提前梳理的所有scope完整、无拼写错误地粘贴到授权范围栏,保存配置
- 注意:这一步的授权逻辑是允许服务账号模拟指定的具备对应操作权限的域内管理员执行操作,而非直接把域内权限开放给服务账号本身
代码调用侧的必须修正
很多人完成控制台配置后依然调用失败,核心问题是没有在凭据初始化阶段指定模拟身份:
- 基于服务账号私钥初始化API客户端时,必须显式传入
subject参数,参数值为你要模拟的、具备对应OU数据访问权限的域内管理员邮箱(例如admin@yourdomain.com) - People API、Directory API均不支持服务账号无模拟的直接访问,哪怕已开启域宽委派,省略subject参数的调用会直接被接口拒绝
正确的凭据初始化参考(Python客户端示例):
from google.oauth2 import service_account REQUIRED_SCOPES = [ "https://www.googleapis.com/auth/admin.directory.user.readonly", "https://www.googleapis.com/auth/directory.readonly" ] # 必须通过subject指定模拟的管理员身份,不可省略 credentials = service_account.Credentials.from_service_account_file( "sa-key.json", scopes=REQUIRED_SCOPES, subject="admin@your-workspace-domain.com" )
常见踩坑排查
- 不要尝试给服务账号本身分配Workspace域内用户角色,这类权限对服务账号的域宽委派链路不生效
- 检查scope拼写一致性,Directory API和People API的权限是独立的,仅配置Directory的scope会导致People API调用直接报权限错误
- 如果模拟的管理员没有目标用户所在组织单元(OU)的读取权限,即使委派配置正确,也无法拉取对应OU下的用户数据
- 确保服务账号是在绑定了对应Workspace组织的云项目下创建的,个人版Google账号关联的项目不支持域宽委派配置,根本不会出现在控制台的可委派客户端列表里
内容的提问来源于stack exchange,提问作者Maksim Bezmen
相关产品推荐
相关产品推荐

