Groups API einrichten

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

Hinweis: Um die Groups API zu verwenden, muss Google Groups for Business für Ihre Domain aktiviert sein und Endnutzer müssen Gruppen erstellen dürfen. Weitere Informationen finden Sie unter Google Groups for Business aktivieren/deaktivieren und Freigabeoptionen für Google Groups for Business festlegen. Für diese Schritte ist der Google Workspace-Administratorzugriff auf Ihre Domain erforderlich.

Hinweise

Cloud Identity API aktivieren.

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, sollten Sie es zum Inhaber aller relevanten Gruppen machen. In diesem Fall müssen Sie die Rolle „Gruppenadministrator“ 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.

Hinweis: Sie benötigen Super Admin-Zugriff für Ihre Domain, um das Dienstkonto zu einem delegierten Administrator zu machen.

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. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf:

   Zur Seite „Dienstkonten“

2. Klicken Sie auf den Namen des Dienstkontos, das Sie mit der Groups API verwenden möchten.

3. Kopieren Sie die eindeutige ID des Dienstkontos.

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

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

   Hinweis: Geben Sie sich nicht als ein Nutzer aus, wenn Sie Anmeldedaten generieren. Überspringen Sie Felder wie with_subject, createDelegated oder 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();
   

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

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/common/base",
      "//java/com/google/common/collect",
      "//third_party/java/google_http_java_client:gson",
      "//third_party/java/google_http_java_client:json",
  ],
)

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.

Hinweis: Da die domainweite Delegierung dadurch funktioniert, dass sich das Dienstkonto als Admin-Nutzer ausgeben darf, zeigen Audit-Protokolle alle Dienstkonto-Aktionen als Nutzer an. Wenn die Aktionen als Dienstkonto angezeigt werden sollen, lesen Sie die Informationen unter Als Dienstkonto ohne domainweite Delegierung authentifizieren.

Informationen zum Einrichten der domainweiten Delegierung finden Sie unter API-Zugriff mit domainweiter Delegierung steuern.

Informationen zur Authentifizierung von Dienstkonten finden Sie unter OAuth 2.0 für Server-zu-Server-Anwendungen verwenden. Geben Sie 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('[e-mail]')

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

  return service

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