設定 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 Roles and Role Assignments API，將 Google Workspace 群組管理員角色 (Group Administrator) 指派給要委派的服務帳戶。這個步驟可讓服務帳戶存取網域的群組，但無法存取其他資源。

如需透過 Admin SDK API 管理角色的相關一般資訊，請參閱管理角色指南。請按照下列步驟，為服務帳戶指派群組管理員角色。

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

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

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

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

  4. 呼叫 Admin SDK Roles API，找出群組管理員的 roleId。您可以使用 Admin SDK 說明文件中的 API 探索工具執行這項操作。

  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 存取稽核記錄。如要使用報表 API 探索工具進行檢查，請務必使用管理員 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。