设置 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. Developers Console 中,选择 IAM 和管理 > 服务帐号,然后点击要与 Groups API 搭配使用的服务帐号。

  2. 复制服务帐号的唯一 ID

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

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

    {
      "assignedTo": "SERVICE_ACCOUNT_UNIQUE_ID"
      "roleID": "ROLE_ID"
      "scopeType": "CUSTOMER"
    }
    

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

您现在已经拥有一个具有 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.jackson2.JacksonFactory;
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(),
            new JacksonFactory());
    System.out.println("ServiceAccountId=" + credential.getServiceAccountId());

    HttpTransport httpTransport = new NetHttpTransport();
    JacksonFactory jsonFactory = new JacksonFactory();
    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/api/client/json",
      "//java/com/google/api/client/json/jackson2",
      "//java/com/google/common/base",
      "//java/com/google/common/collect",
  ],
)

测试服务帐号

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

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

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

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

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

按照以下步骤对服务帐号进行身份验证并设置全网域授权。

  1. 以服务帐号身份进行身份验证;请参阅为“服务器到服务器”应用使用 OAuth 2.0。然后按以下步骤操作

  2. 在 Cloud Console 中,转到服务帐号页面。

    转到“服务帐号”页面

  3. 点击选择项目,然后选择一个项目并点击打开

  4. 选择您的服务帐号,然后点击修改

  5. 点击显示全网域授权

  6. 选择启用 Google Workspace 全网域授权

  7. 点击保存

接下来,在代码中初始化凭据时,通过对凭据调用 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.googleapis.com'
  api_version = 'v1'
  discovery_url = (
    'https://%s/$discovery/rest?version=%s' % (service_name, api_version))
  service = googleapiclient.discovery.build(
    service_name,
    api_version,
    discoveryServiceUrl=discovery_url,
    credentials=credentials)

  return service

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