Menyiapkan Groups API

Halaman ini menjelaskan cara menyiapkan Cloud Identity Groups API.

Catatan: Untuk menggunakan Groups API, Anda harus mengaktifkan Google Grup untuk Bisnis untuk domain Anda dan mengizinkan pengguna akhir membuat grup. Lihat MENGAKTIFKAN atau MENONAKTIFKAN Grup untuk Bisnis dan Menetapkan opsi berbagi Grup untuk Bisnis untuk mengetahui informasi selengkapnya. Langkah ini memerlukan akses administrator Google Workspace ke domain Anda.

Sebelum memulai

Aktifkan API Cloud Identity.

Mengaktifkan API

Menginstal library klien

Untuk menginstal library klien, jalankan perintah berikut:

Python

Untuk mengetahui informasi selengkapnya tentang cara menyiapkan lingkungan pengembangan Python, lihat Panduan Penyiapan Lingkungan Pengembangan Python.

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

Mengautentikasi dengan Groups API

Anda dapat melakukan autentikasi dengan Groups API sebagai pengguna akhir, sebagai admin grup akun layanan tanpa delegasi tingkat domain, atau sebagai akun layanan dengan delegasi seluruh domain. Bagian berikut menjelaskan setiap metode.

Mengautentikasi sebagai pengguna akhir

Jika Anda bukan administrator, atau sedang membuat aplikasi yang bertindak atas nama pengguna yang bukan administrator, lihat Menggunakan OAuth 2.0 untuk aplikasi server web, lalu lihat bagian Membuat instance klien di bawah.

Mengautentikasi sebagai akun layanan tanpa delegasi tingkat domain

Jika Anda menggunakan akun layanan dan ingin menggunakannya untuk mengelola grup sebagai admin grup, selesaikan langkah-langkah di bawah ini. Metode autentikasi ini harus digunakan jika Anda ingin tindakan akun layanan didaftarkan di log audit sebagai akun layanan.

Menetapkan peran admin untuk akun layanan

Tips: Jika akun layanan tidak memerlukan akses ke semua grup, pertimbangkan untuk menjadikannya sebagai pemilik grup yang diinginkan. Dalam kasus ini, Anda tidak perlu menetapkan peran admin grup.

Pertama, Anda harus menetapkan Peran Administrator Grup Google Workspace (Group Administrator) ke akun layanan yang ingin Anda delegasikan, menggunakan Admin SDK Roles and Role Assignments API. Langkah ini memberi akun layanan akses ke grup domain, tetapi tidak memberi resource lainnya.

Catatan: Anda harus memiliki akses Admin Super Google Workspace untuk domain Anda agar akun layanan menjadi admin yang didelegasikan.

Lihat panduan Mengelola Peran untuk mengetahui informasi umum tentang cara mengelola Peran menggunakan Admin SDK API. Ikuti langkah-langkah di bawah ini untuk menetapkan peran Group Adminstrator untuk akun layanan Anda.

1. Di konsol Google Cloud, buka halaman Service Accounts:

   Buka Akun Layanan

2. Klik nama akun layanan yang ingin Anda gunakan dengan Groups API.

3. Salin ID Unik akun layanan.

4. Panggil Admin SDK Roles API guna mengidentifikasi roleId untuk Group Administrator. Anda dapat menggunakan API Explorer dalam dokumentasi Admin SDK untuk melakukannya.

5. Panggil Role Assignments API dengan isi permintaan berikut:

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

Mengautentikasi dan memberi otorisasi pada akun layanan

Anda sekarang memiliki akun layanan dengan peran Administrator Grup. Langkah kedua adalah menyelesaikan proses autentikasi OAuth untuk akun layanan.

• Jika Anda mengembangkan aplikasi di Google Cloud dan akun layanan adalah pemilik project, Anda dapat menggunakan kredensial default aplikasi, yang dapat menyederhanakan prosesnya. Baca bagian Mengautentikasi sebagai Akun Layanan untuk mengetahui informasi selengkapnya.

• Jika akun layanan bukan pemilik project, ikuti petunjuk di bawah ini.

Dalam kedua kasus tersebut, cakupan yang berlaku untuk Cloud Identity Groups API adalah https://www.googleapis.com/auth/cloud-identity.groups.

1. Buat token akses menggunakan kredensial yang baru saja Anda buat.

   Catatan: Jangan meniru identitas pengguna saat membuat kredensial. Lewati kolom seperti with_subject, createDelegated, atau setServiceAccountUser.

   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();
   

   Simpan token akses yang dibuat.

Kode lengkap untuk membuat token akses untuk akun layanan

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();
  }
}

Buat aturan

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",
  ],
)

Menguji akun layanan

1. Coba panggilan Groups API dengan kredensial akun layanan: membuat grup, menambahkan pengguna, memperbarui setelan grup, dll.

2. Periksa Log Audit di bagian Laporan Konsol Google Admin. Anda akan melihat akun layanan sebagai pelaku untuk perubahan terkait grup. Lihat Mencatat peristiwa ke dalam log untuk mengetahui informasi selengkapnya.

   Atau, Anda dapat menggunakan API untuk mengakses log audit. Untuk memeriksanya menggunakan Penjelajah Reports API, pastikan Anda menggunakan kredensial OAuth admin.

Mengautentikasi sebagai akun layanan dengan delegasi tingkat domain

Jika Anda adalah administrator yang mengelola grup identitas, atau jika ingin memberikan hak istimewa di seluruh domain kepada akun agar dapat mengelola Google Grup atas nama admin, Anda harus melakukan autentikasi sebagai akun layanan.

Catatan: Karena delegasi seluruh domain bekerja dengan mengizinkan akun layanan untuk meniru identitas pengguna admin, log audit akan menampilkan tindakan akun layanan apa pun sebagai pengguna. Jika Anda ingin tindakan ditampilkan sebagai akun layanan, lihat bagian Mengautentikasi sebagai akun layanan tanpa delegasi seluruh domain di atas.

Untuk mengetahui detail tentang menyiapkan delegasi tingkat domain, lihat Mengontrol akses API dengan delegasi seluruh domain.

Untuk mengautentikasi sebagai akun layanan, lihat Menggunakan OAuth 2.0 untuk aplikasi server ke server. Saat menginisialisasi kredensial dalam kode Anda, tentukan alamat email tempat akun layanan bertindak dengan memanggil with_subject() pada kredensial tersebut. Contoh:

Python

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

Membuat instance klien

Contoh berikut menunjukkan cara membuat instance klien menggunakan kredensial akun layanan. Untuk mengautentikasi sebagai pengguna akhir, ganti objek credential dari akun layanan dengan credential yang Anda peroleh sebelumnya di Menggunakan OAuth 2.0 untuk aplikasi server web.

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('[e-mail]')

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

  return service

Sekarang Anda dapat mulai melakukan panggilan ke Groups API.