启用全域委派后访问Google Directory API仍提示服务账户未授权

云原生阿岚

2026-6-19

问题描述

我尝试通过Airflow连接Google Directory API（REST Resource: users），获取Google Workspace组织内的用户列表并更新部分属性。操作使用的服务账户已配置对应权限范围：https://www.googleapis.com/auth/admin.directory.user，且已启用全域委派、开启Admin SDK API，同时拥有项目的完整权限。

但运行基于Google API Client和Google OAuth2的Python测试脚本，尝试通过用户邮箱获取单个用户信息时，出现以下错误：

Error fetching user: 
<HttpError 403 when requesting https://admin.googleapis.com/admin/directory/v1/users/<username>%40<domain>?alt=json 
returned "Not Authorized to access this resource/api". 
Details: 
  "[
    {
       'message': 'Not Authorized to access this resource/api', 
        'domain': 'global', 'reason': 'forbidden'
    }
   ]
">

不过，当我在凭证中添加超级管理员邮箱作为 impersonation 的subject时，服务账户可正常访问Directory API获取用户信息：

credentials = service_account.Credentials.from_service_account_file("/path/to/file.json", 
scopes=SCOPES, 
subject="super_admin@yourdomain.com")

我查阅官方文档后未找到需添加管理员邮箱的说明，请问我是否遗漏了配置步骤？若必须让服务账户 impersonate 管理员，那启用全域委派的意义是什么？

问题分析与解答

为什么必须指定impersonation的subject？
Google Workspace的Directory API属于域私有资源API，服务账户本身是Google Cloud项目级别的凭证，无法直接访问域内的用户数据。必须通过模拟（impersonate）域内拥有对应权限的管理员账号，才能获得访问Directory API的权限——这是Workspace域内API的固有访问规则。
全域委派的作用是什么？
全域委派是服务账户能够模拟域内用户的前提条件：没有开启全域委派的服务账户，哪怕你指定了subject，也无法完成模拟操作。它的作用是授权服务账户拥有“模拟域内任意已配置权限范围的用户”的资格，而非直接赋予API访问权。简单说，全域委派是开门的钥匙，而指定subject是选择用哪个身份进门操作。
是否遗漏了配置步骤？
没有遗漏。这一规则属于Directory API的访问逻辑细节，部分文档可能未单独强调，但所有涉及Workspace域内私有数据的API（比如Directory、Drive的域内数据等），基本都要求服务账户通过模拟域内用户来访问。

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