设置 Groups API

本页面介绍如何设置 Cloud Identity Groups API。

准备工作

启用 Cloud Identity API。

启用 API

安装客户端库

如需安装客户端库，请运行以下命令：

Python

如需详细了解如何设置 Python 开发环境，请参阅 Python 开发环境设置指南。

pip install --upgrade google-api-python-client google-auth \
  google-auth-oauthlib google-auth-httplib2

使用 Groups API 进行身份验证

您可以以最终用户、不进行全网域授权的服务账号群组管理员或进行全网域授权的服务账号的身份向 Groups API 进行身份验证。以下部分介绍每一种方法。

作为最终用户进行身份验证

如果您不是管理员，或者要构建一个代表非管理员用户的应用，请参阅针对网络服务器应用使用 OAuth 2.0，然后参阅下面的实例化客户端部分。

以服务账号身份进行身份验证并且不进行全网域授权

如果您使用的是服务账号，并且想要使用它以群组管理员身份管理群组，请完成以下步骤。如果您希望服务账号的操作在审核日志注册为服务账号，则应使用此身份验证方法。

为服务账号分配管理员角色

首先，您应使用 Admin SDK Roles API 和 Role Assignments API 将 Google Workspace Group Administrator 角色（群组管理员）分配给您要委托的服务账号。此步骤会授予服务账号访问网域内群组的权限，但无法访问其他资源。

如需了解使用 Admin SDK API 管理角色的一般信息，请参阅管理角色指南。请按照以下步骤为服务账号分配 Group Adminator 角色。

  1. 在 Google Cloud 控制台中，前往服务帐号页面：

    转到“服务账号”

  2. 点击要与 Groups API 搭配使用的服务帐号的名称。

  3. 复制服务账号的唯一 ID。

  4. 调用 Admin SDK Roles API 以识别 Group Administrator 的 roleId。您可以使用 Admin SDK 文档中的 API Explorer 来执行此操作。

  5. 使用以下请求正文调用 Role Assignment API：

    {
  "assignedTo": "SERVICE_ACCOUNT_UNIQUE_ID"
  "roleId": "ROLE_ID"
  "scopeType": "CUSTOMER"
  "kind": "admin#directory#roleAssignment"
}

对服务账号进行身份验证和授权

您现在已经拥有一个具有 Group Administrator 角色的服务账号。第二步是完成服务账号的 OAuth 身份验证流程。

  • 如果您是在 Google Cloud 上开发应用并且服务账号是项目的所有者，则可以改用应用默认凭据，从而简化该流程。如需了解详情，请参阅以服务账号身份进行身份验证。

  • 如果服务账号不是项目的所有者，请按照以下说明操作。

无论是哪种情况，Cloud Identity Groups API 适用的范围均为 https://www.googleapis.com/auth/cloud-identity.groups。

  1. 使用您刚创建的凭据生成访问令牌。

    Java

    GoogleCredential credential = new GoogleCredential.Builder()
    .setTransport(httpTransport)
    .setJsonFactory(JSON_FACTORY)
    .setServiceAccountId(emailAddress)
    .setServiceAccountPrivateKeyFromP12File(new File("MyProject.p12"))
    .setServiceAccountScopes(ImmutableList.of("https://www.googleapis.com/auth/cloud-identity.groups"))
    .build();

    保留生成的访问令牌。

为服务账号生成访问令牌的完整代码

Java

GenerateServiceAccountOauth2Token.java

package com.google.tools;

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.common.collect.ImmutableList;
import java.io.FileInputStream;

/** Command line tool to generate Oauth2 token for a given service account
/** without domain wide delegation. */
public final class GenerateServiceAccountOauth2Token {

  private static final ImmutableList<String> API_SCOPES =
      ImmutableList.of(
          "https://www.googleapis.com/auth/cloud-identity.groups",
          "https://www.googleapis.com/auth/admin.directory.group",
          "https://www.googleapis.com/auth/admin.directory.group.member",
          "https://www.googleapis.com/auth/apps.groups.settings");

  public static void main(final String[] args) throws Exception {
    String accessToken = getTokenFromJsonKey();
    System.out.println("Token: " + accessToken);
  }

  private static String getTokenFromJsonKey() throws Exception {
    GoogleCredential credential =
        GoogleCredential.fromStream(
            new FileInputStream(
                "<path for json file>"),
            new NetHttpTransport(),
            GsonFactory.getDefaultInstance());
    System.out.println("ServiceAccountId=" + credential.getServiceAccountId());

    HttpTransport httpTransport = new NetHttpTransport();
    JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    GoogleCredential.Builder builder =
        new GoogleCredential.Builder()
            .setServiceAccountPrivateKey(credential.getServiceAccountPrivateKey())
            .setServiceAccountPrivateKeyId(credential.getServiceAccountPrivateKeyId())
            .setServiceAccountId(credential.getServiceAccountId())
            .setTransport(httpTransport)
            .setJsonFactory(jsonFactory)
            .setServiceAccountScopes(API_SCOPES)
            .setClock(credential.getClock());
    credential = builder.build();
    if (!credential.refreshToken()) {
      throw new Exception("Failed to fetch access token.");
    }
    return credential.getAccessToken();
  }
}

编译规则

java_binary(
  name = "generate_oauth2_token",
  srcs = ["GenerateServiceAccountOauth2Token.java"],
  main_class = "com.google.tools.GenerateServiceAccountOauth2Token",
  deps = [
      "//java/com/google/api/client/googleapis/auth/oauth2",
      "//java/com/google/api/client/googleapis/javanet",
      "//java/com/google/api/client/http",
      "//java/com/google/api/client/http/javanet",
      "//java/com/google/common/base",
      "//java/com/google/common/collect",
      "//third_party/java/google_http_java_client:gson",
      "//third_party/java/google_http_java_client:json",
  ],
)

测试服务账号

  1. 尝试使用服务账号凭据运行 Groups API 调用：创建群组、添加用户、更新群组设置等。

  2. 在 Google 管理控制台的“报告”部分查看审核日志。您应该会看到服务账号是与群组相关的更改的执行者。如需了解详情，请参阅日志事件。

    此外，您也可以使用 API 来访问审核日志。要使用 Reports API Explorer 查看，请务必使用管理员 OAuth 凭据。

以服务账号身份进行身份验证并进行全网域授权

如果您是管理身份群组的管理员，或者您希望向账号提供全网域权限以使其可以代表管理员管理 Google 群组，则应以服务账号身份进行身份验证。

如需详细了解如何设置全网域授权，请参阅使用全网域授权功能控制 API 访问权限。

如需以服务账号身份进行身份验证，请参阅为“服务器到服务器”应用使用 OAuth 2.0。在代码中初始化凭据时，通过对凭据调用 with_subject() 来指定服务账号要操作的电子邮件地址。例如：

Python

credentials = service_account.Credentials.from_service_account_file(
  SERVICE_ACCOUNT_FILE, scopes=SCOPES).with_subject(delegated_email)

实例化客户端

以下示例展示了如何使用服务账号凭据对客户端进行实例化。要改为以最终用户身份进行身份验证，请将服务账号中的 credential 对象替换为您之前在为网络服务器应用使用 OAuth 2.0 中获得的 credential。

Python

from google.oauth2 import service_account
import googleapiclient.discovery

SCOPES = ['https://www.googleapis.com/auth/cloud-identity.groups']
SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'

def create_service():
  credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
  delegated_credentials = credentials.with_subject('user@example.org')

  service_name = 'cloudidentity'
  api_version = 'v1'
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    credentials=delegated_credentials)

  return service

现在，您可以开始调用 Groups API。