GCP问题：服务账户模拟带GA权限域用户账户失败排查

问题背景 #

• 服务账户：ga@googleanalytics.iam.gserviceaccount.com
• 拟模拟的用户账户：ga@domain.tld
• 使用的GA权限域：

  target_scopes = ['https://www.googleapis.com/auth/analytics',
  'https://www.googleapis.com/auth/analytics.edit',
  'https://www.googleapis.com/auth/analytics.manage.users',
  'https://www.googleapis.com/auth/analytics.provision',
  'https://www.googleapis.com/auth/analytics.user.deletion'] 
  

• 错误现象：
  • 含模拟逻辑时抛出404错误：Gaia id not found for email ga@domain.tld
  • 去掉模拟逻辑时返回未授权错误
• 已完成配置：
  • 服务账户已分配Service Account Token Creator和Service Account User角色
  • Google Workspace Admin中已设置全域委派，并添加了上述GA权限域

排查与解决方案 #

1. 确认拟模拟用户的有效性 #

• 检查ga@domain.tld是已激活的Google Workspace正式用户，别是别名、组邮箱或已删除账户。Gaia ID找不到的核心原因就是邮箱无法映射到有效用户实体，可直接在Google Workspace Admin控制台搜索该用户，确认账户状态正常、未被禁用/删除。

2. 核对全域委派的配置细节 #

• 确保在Google Workspace Admin配置全域委派时，客户端ID填写正确：要使用服务账户对应的OAuth 2.0客户端ID（在Google Cloud控制台「API和服务」→「凭据」里找这个服务账户的对应ID）。
• 检查权限域列表和代码里的target_scopes完全一致，不能有拼写错误（比如末尾斜杠、大小写问题，GA权限域都是小写）。

3. 确认服务账户的模拟权限层级 #

• Service Account User角色要分配在正确层级：要么是服务账户所在的项目层级，要么是用户所在的组织层级，别只在某个资源层级分配，否则模拟权限不生效。
• 同时检查Google Workspace Admin的「安全性」→「API控制」→「域范围委派」，确认该服务账户的委派没有被限制到特定OU或用户组，确保能模拟目标用户。

4. 检查代码模拟逻辑的正确性 #

• 模拟时必须用完整的用户邮箱地址，不能有空格或特殊字符。
• 若用Google官方客户端库（比如Python的google-auth），要正确设置subject参数为目标用户邮箱，示例代码片段：

  from google.oauth2 import service_account
  
  credentials = service_account.Credentials.from_service_account_file(
      'service-account-key.json',
      scopes=target_scopes,
      subject='ga@domain.tld'  # 这里必须是拟模拟的用户邮箱
  )
  

• 别同时混用服务账户默认凭据（不指定subject），会导致权限冲突。

5. 验证目标用户的GA权限 #

• 就算模拟成功，如果ga@domain.tld本身没有目标GA账户的管理权限（比如Edit或Manage Users级别），还是会返回未授权错误。要确认该用户已经被添加到目标GA账户的权限列表里，且权限级别足够完成添加属性的操作。

6. 检查Google Cloud项目的API启用状态 #

• 确保项目已启用对应API：操作GA4就开Google Analytics Admin API，操作UA就开Google Analytics API。没启用对应API会直接导致请求被拒绝或返回错误。

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