Menyiapkan Groups API

Halaman ini menjelaskan cara menyiapkan Cloud Identity Groups API.

Sebelum memulai

Enable the Cloud Identity API.

Enable the 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 mengautentikasi dengan Groups API sebagai pengguna akhir, sebagai admin grup akun layanan tanpa delegasi tingkat domain, atau sebagai akun layanan dengan delegasi tingkat domain. Bagian berikut menjelaskan setiap metode.

Mengautentikasi sebagai pengguna akhir

Jika Anda bukan administrator, atau 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.

Melakukan autentikasi 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. Metode autentikasi ini harus digunakan jika Anda ingin tindakan akun layanan didaftarkan dalam log audit sebagai akun layanan.

Menetapkan peran admin ke akun layanan

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

Lihat Panduan Mengelola Peran untuk mengetahui informasi umum tentang cara mengelola Peran menggunakan Admin SDK API. Ikuti langkah-langkah di bawah untuk menetapkan peran Group Administrator 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 untuk 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 memberikan otorisasi ke akun layanan

Sekarang Anda memiliki akun layanan dengan peran Group Administrator. 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 sebagai gantinya, yang dapat menyederhanakan proses. Lihat Melakukan Autentikasi sebagai Akun Layanan untuk mengetahui informasi selengkapnya.

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

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

  1. Dengan kredensial yang baru saja Anda buat, buat token akses.

    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 dihasilkan.

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

Membuat 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 apa pun 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 Anda. Lihat artikel Mencatat peristiwa ke dalam log untuk mengetahui informasi selengkapnya.

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

Melakukan autentikasi sebagai akun layanan dengan delegasi tingkat domain

Jika Anda adalah administrator yang mengelola grup identitas, atau jika Anda ingin memberikan akun dengan hak istimewa tingkat domain agar dapat mengelola Google Grup atas nama admin, Anda harus mengautentikasi sebagai akun layanan.

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

Untuk mengautentikasi sebagai akun layanan, lihat Menggunakan OAuth 2.0 untuk aplikasi server ke server. Saat melakukan inisialisasi kredensial dalam kode Anda, tentukan alamat email tempat akun layanan bertindak dengan memanggil with_subject() pada kredensial. 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('user@example.org')

  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.