設定 Groups API

本頁面說明如何設定 Cloud Identity Groups API。

事前準備

Enable the Cloud Identity API.

Enable the 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 角色和角色指派 API，將 Google Workspace 群組管理員角色 (群組管理員) 指派給要委派的服務帳戶。這個步驟會讓服務帳戶存取網域的群組，但不會存取其他資源。

如要進一步瞭解如何使用 Admin SDK API 管理角色，請參閱管理角色指南。請按照下列步驟為服務帳戶指派群組管理員角色。

  1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面：

    前往「Service Accounts」(服務帳戶)

  2. 按一下要與 Groups API 搭配使用的服務帳戶名稱。

  3. 複製服務帳戶的專屬 ID。

  4. 呼叫 Admin SDK Roles API，即可識別群組管理員的 roleId。您可以使用 Admin SDK 說明文件中的 API Explorer 執行這項操作。

  5. 使用以下要求主體呼叫 Role Assignments API：

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

驗證及授權服務帳戶

您現在已擁有具備群組管理員角色的服務帳戶。第二步是完成服務帳戶的 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。