Groups API einrichten

Auf dieser Seite wird erläutert, wie Sie die Cloud Identity Groups API einrichten.

Hinweis

Aktivieren Sie die Cloud Identity API.

Aktivieren Sie die API

Clientbibliotheken installieren

Führen Sie den folgenden Befehl aus, um die Clientbibliotheken zu installieren:

Python

Weitere Informationen zum Einrichten der Python-Entwicklungsumgebung finden Sie im Einrichtungsleitfaden für die Python-Entwicklungsumgebung.

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

Bei der Groups API authentifizieren

Sie können sich mit der Groups API als Endnutzer, als Dienstkontoadministrator für Dienstkonten ohne domainweite Delegierung oder als Dienstkonto mit domainweiter Delegierung authentifizieren. In den folgenden Abschnitten werden die einzelnen Methoden beschrieben.

Als Endnutzer authentifizieren

Wenn Sie kein Administrator sind oder eine Anwendung erstellen, die im Namen von Nutzern agiert, die keine Administratoren sind, finden Sie weitere Informationen unter OAuth 2.0 für Webserveranwendungen verwenden. Lesen Sie dann unten den Abschnitt Client instanziieren.

Als Dienstkonto ohne domainweite Delegierung authentifizieren

Wenn Sie ein Dienstkonto verwenden und es als Gruppenadministrator verwalten möchten, führen Sie die folgenden Schritte aus. Sie sollten diese Authentifizierungsmethode verwenden, wenn die Aktionen des Dienstkontos in den Audit-Logs als Dienstkonto registriert werden sollen.

Dem Dienstkonto eine Administratorrolle zuweisen

Tipp: Wenn das Dienstkonto nicht auf alle Gruppen zugreifen muss, können Sie es als Inhaber der entsprechenden Gruppen festlegen. In diesem Fall müssen Sie die Gruppenadministratorrolle nicht zuweisen.

Zuerst sollten Sie dem Dienstkonto, das Sie delegieren möchten, die Rolle "Google Workspace Group Administrator" zuweisen. Verwenden Sie dazu die Admin SDK-Rollen und die Role Assignments API. Mit diesem Schritt erhält das Dienstkonto Zugriff auf die Gruppen der Domain, aber keine andere Ressource.

Allgemeine Informationen zum Verwalten von Rollen mit der Admin SDK API finden Sie im Leitfaden zum verwalten von Rollen. Führen Sie die folgenden Schritte aus, um die Rolle "Gruppenadministrator" für Ihr Dienstkonto zuzuweisen.

  1. Wählen Sie in der Developer Console die Option IAM & Admin > Dienstkonten aus und klicken Sie auf das Dienstkonto, das Sie mit der Groups API verwenden möchten.

  2. Kopieren Sie die eindeutige ID des Dienstkontos.

  3. Rufen Sie die Admin SDK Roles API auf, um den roleId für Gruppenadministrator anzugeben. Dazu können Sie den API Explorer in der Admin-SDK-Dokumentation verwenden.

  4. Rufen Sie die Role Assignments API mit dem folgenden Anfragetext auf:

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

Dienstkonto authentifizieren und autorisieren

Sie haben jetzt ein Dienstkonto mit der Rolle "Gruppenadministrator". Der zweite Schritt besteht darin, den OAuth-Authentifizierungsvorgang für das Dienstkonto abzuschließen.

  • Wenn Sie eine Anwendung in Google Cloud entwickeln und das Dienstkonto Inhaber des Projekts ist, können Sie stattdessen die Standardanmeldedaten für Anwendungen verwenden. Dies vereinfacht den Vorgang. Weitere Informationen finden Sie unter Als Dienstkonto authentifizieren.

  • Wenn das Dienstkonto nicht der Inhaber des Projekts ist, folgen Sie der nachstehenden Anleitung.

In beiden Fällen ist der anwendbare Bereich für die Cloud Identity Groups API https://www.googleapis.com/auth/cloud-identity.groups.

  1. Generieren Sie mit den soeben erstellten Anmeldedaten ein Zugriffstoken.

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

    Behalten Sie das generierte Zugriffstoken.

Vollständiger Code zum Generieren eines Zugriffstokens für ein Dienstkonto

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

Build-Regel

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

Dienstkonto testen

  1. Führen Sie jeden Groups API-Aufruf mit den Anmeldedaten des Dienstkontos aus: Gruppe erstellen, Nutzer hinzufügen, Gruppeneinstellungen aktualisieren usw.

  2. Prüfen Sie die Audit-Logs im Bereich "Berichte" der Google Admin-Konsole. Das Dienstkonto sollte dem Nutzer für die gruppenbezogenen Änderungen angezeigt werden. Weitere Informationen finden Sie unter Logereignisse.

    Alternativ können Sie APIs verwenden, um auf Audit-Logs zuzugreifen. Für die Prüfung mit dem Explorer-API für Reports verwenden Sie Ihre OAuth-Anmeldedaten.

Als Dienstkonto mit domainweiter Delegierung authentifizieren

Wenn Sie ein Administrator sind, der Identitätsgruppen verwaltet, oder ein Konto mit domainweiten Berechtigungen zur Verwaltung von Google Groups im Namen von Administratoren bereitstellen möchten, sollten Sie sich als Dienstkonto authentifizieren und diesem dann die domainweiten Berechtigungen gewähren.

Führen Sie die folgenden Schritte aus, um das Dienstkonto zu authentifizieren und die domainweite Delegierung einzurichten.

  1. Als Dienstkonto authentifizieren; Weitere Informationen finden Sie unter OAuth 2.0 für Server-zu-Server-Anwendungen verwenden. Führen Sie dann die folgenden Schritte aus:

  2. Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

    Zur Seite „Dienstkonten“

  3. Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen.

  4. Wählen Sie Ihr Dienstkonto aus und klicken Sie auf Bearbeiten.

  5. Klicken Sie auf Domainweite Delegation einblenden.

  6. Wählen Sie Domainweite Google Workspace-Delegation aktivieren.

  7. Klicken Sie auf Speichern.

Geben Sie als Nächstes beim Initialisieren der Anmeldedaten in Ihrem Code die E-Mail-Adresse an, unter der das Dienstkonto agiert. Rufen Sie dazu with_subject() für die Anmeldedaten auf. Beispiel:

Python

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

Client instanziieren

Das folgende Beispiel zeigt, wie ein Client mithilfe von Dienstkonto-Anmeldedaten instanziiert wird. Wenn Sie sich stattdessen als Endnutzer authentifizieren möchten, ersetzen Sie das credential-Objekt aus dem Dienstkonto durch den credential-Wert, den Sie zuvor in OAuth 2.0 für Webserveranwendungen verwenden erhalten haben.

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=credentials)

  return service

Sie können jetzt Aufrufe an die Groups API senden.