如何通过 Admin SDK 为 Google Reseller Customer 创建管理员

2026-10-24数据小陈

结论

Directory API 不能为某个客户域“开启 API”。OAuth scope 只说明令牌申请了哪些权限，既不会自动启用 Admin SDK，也不会让调用者获得管理员身份。

这需要分两步处理：

在 OAuth 客户端所属的 Google Cloud 项目中启用 Admin SDK API，即 admin.googleapis.com。
使用有权管理该客户的 reseller 管理员身份调用 Directory API。先创建用户，再通过 users.makeAdmin 将其提升为管理员。

users.insert 请求中的 isAdmin 是只读字段，不能通过设置 "isAdmin": true 直接创建管理员。

先确认报错来自哪一层

查看 API 返回的完整 JSON，重点检查 error.errors[].reason 和 error.message。

如果原因是 accessNotConfigured、SERVICE_DISABLED，或者错误消息明确指出 Admin SDK API 尚未启用，问题出在 Google Cloud 项目。需要在签发 OAuth Access Token 的客户端所属项目中启用该 API：

gcloud services enable admin.googleapis.com \
  --project=PROJECT_ID

也可以调用 Service Usage API：

POST https://serviceusage.googleapis.com/v1/projects/PROJECT_NUMBER/services/admin.googleapis.com:enable
Authorization: Bearer CLOUD_IAM_ACCESS_TOKEN
Content-Type: application/json

{}

调用身份必须拥有 serviceusage.services.enable IAM 权限，例如 roles/serviceusage.serviceUsageAdmin 角色提供的权限。这里使用的是 Google Cloud IAM 授权，不是：

https://www.googleapis.com/auth/admin.directory.user

所以，普通的 reseller OAuth token 通常无法直接启用项目服务。

如果错误信息表明客户域不允许使用 API、调用者未获授权或权限不足，启用 Cloud API 并不能解决问题。此时需要检查：

Access Token 是否由 reseller 管理员或具备相应管理权限的账号签发。
reseller 是否仍在管理该 customer。
customer 和 subscription 是否已成功创建并处于可用状态。
客户域是否受到 API Controls、应用访问控制或管理员策略的限制。
新客户是否尚未完成服务条款接受、域验证或账号初始化流程。

Directory API 无法绕过域级安全策略。如果策略要求客户 Super Admin 在 Admin console 中批准应用或修改 API Controls，就必须由相应管理员完成操作。

创建第一个用户

Directory API 的 users.insert 没有 customerId 参数。系统会根据 primaryEmail 中的域名和当前 reseller 管理关系确定目标客户。

curl -X POST \
  'https://admin.googleapis.com/admin/directory/v1/users' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "primaryEmail": "admin@example.com",
    "name": {
      "givenName": "Domain",
      "familyName": "Admin"
    },
    "password": "INITIAL_PASSWORD",
    "changePasswordAtNextLogin": true
  }'

创建成功后，保存响应中的用户 id。生产系统在后续操作中最好使用这个不可变 ID，而不是继续依赖邮箱地址。

将用户提升为管理员

用户创建成功后，调用 users.makeAdmin：

curl -X POST \
  'https://admin.googleapis.com/admin/directory/v1/users/USER_ID/makeAdmin' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": true
  }'

如果使用邮箱作为 userKey，必须先进行 URL 编码：

admin%40example.com

现有 scope：

https://www.googleapis.com/auth/admin.directory.user

可以用于创建用户和执行 makeAdmin，但仅有 scope 并不能保证请求成功。令牌对应的管理员还必须有权创建用户并授予管理员权限。如果调用者只能管理用户，不能分配管理员身份，第二个请求会返回 403 Forbidden。

自动化时的建议流程

Billing software 可以按以下顺序执行：

提前在固定的 Google Cloud 项目中启用 admin.googleapis.com。这通常是一次性部署操作，无需为每个 customer 重复执行。
创建 reseller customer。
创建并激活 subscription。
等待客户资源可以通过 Directory API 访问。新建资源可能需要短暂时间完成传播。
调用 users.insert 创建第一个用户。
使用响应中的用户 ID 调用 users.makeAdmin。
通过安全渠道交付初始密码，并要求用户首次登录时修改密码。
根据账号的实际状态，完成服务条款接受、域验证或其他初始化步骤。

不要将初始密码、Access Token 或 Refresh Token 写入普通业务日志。遇到 403 错误时也不要直接反复重试，应先根据 reason 判断具体原因，包括 API 未启用、权限不足、域策略限制或账号尚未就绪。