Configurer l'API Groups

Cette page explique comment configurer l'API Cloud Identity Groups.

Avant de commencer

Activez l'API Cloud Identity

Activer l'API

Installer les bibliothèques clientes

Pour installer les bibliothèques clientes, exécutez la commande suivante :

Python

Pour savoir comment configurer votre environnement de développement Python, consultez le guide de configuration d'un environnement de développement Python.

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

S'authentifier avec l'API Groups

Vous pouvez vous authentifier auprès de l'API Groups en tant qu'utilisateur final, en tant qu'administrateur de groupe de comptes de service sans délégation au niveau du domaine, ou en tant que compte de service avec une délégation au niveau du domaine. Les sections suivantes décrivent chacune des méthodes.

Authentification en tant qu'utilisateur final

Si vous n'êtes pas administrateur, ou si vous créez une application qui agit pour le compte d'utilisateurs qui ne sont pas administrateurs, consultez la page Utiliser OAuth 2.0 pour les applications de serveur Web, puis la section Instancier un client ci-dessous.

Authentification en tant que compte de service sans délégation au niveau du domaine

Si vous utilisez un compte de service et que vous souhaitez vous en servir pour gérer des groupes en tant qu'administrateur de groupe, procédez comme suit : Cette méthode d'authentification doit être utilisée lorsque vous souhaitez que les actions du compte de service soient enregistrées dans les journaux d'audit en tant que compte de service.

Attribuer un rôle d'administrateur au compte de service

Tout d'abord, vous devez utiliser des rôles SDK Admin et l'API Role Assignments pour attribuer le rôle d'administrateur de groupe Google Workspace (Administrateur de groupe) au compte de service auquel vous souhaitez déléguer des tâches. Cette étape permet au compte de service d'accéder aux groupes du domaine, mais à aucune autre ressource.

Consultez le guide Gérer les rôles pour obtenir des informations générales sur la gestion des rôles à l'aide de l'API Admin SDK. Pour attribuer le rôle d'administrateur de groupe pour votre compte de service, suivez les étapes ci-dessous.

  1. Dans la console Google Cloud, accédez à la page Comptes de service:

    Accéder à la page "Comptes de service"

  2. Cliquez sur le nom du compte de service que vous souhaitez utiliser avec l'API Groups.

  3. Copiez l'identifiant unique du compte de service.

  4. Appelez l'API Admin SDK Roles pour identifier l'élément roleId pour l'administrateur de groupe. Pour ce faire, vous pouvez utiliser les API Explorer dans la documentation du SDK Admin.

  5. Appelez l'API Role Assignments avec le corps de requête suivant :

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

S'authentifier et autoriser le compte de service

Vous disposez maintenant d'un compte de service avec le rôle Administrateur de groupe. La deuxième étape consiste à suivre le processus d'authentification OAuth pour le compte de service.

  • Si vous développez une application sur Google Cloud et que le compte de service est propriétaire du projet, vous pouvez utiliser les identifiants par défaut de l'application, ce qui peut simplifier le processus. Consultez la section Authentification en tant que compte de service pour plus d'informations.

  • Si le compte de service n'est pas le propriétaire du projet, suivez les instructions ci-dessous.

Dans les deux cas, le champ d'application applicable à l'API Cloud Identity Groups est https://www.googleapis.com/auth/cloud-identity.groups.

  1. À l'aide des identifiants que vous venez de créer, générez un jeton d'accès.

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

    Conservez le jeton d'accès généré.

Code complet permettant de générer un jeton d'accès pour un compte de service

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

Règle de compilation

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

Tester le compte de service

  1. Essayez tous les appels d'API Groups avec les identifiants du compte de service : créer un groupe, ajouter des utilisateurs, mettre à jour les paramètres du groupe, etc.

  2. Consultez les journaux d'audit dans la section Rapports de la console d'administration Google. Vous devez voir le compte de service en tant qu'acteur pour vos modifications liées au groupe. Pour en savoir plus, consultez la page Événements de journaux.

    Vous pouvez également utiliser des API pour accéder aux journaux d'audit. Pour vérifier à l'aide de l'explorateur d'API Reports, veillez à utiliser vos identifiants OAuth d'administrateur.

Authentification en tant que compte de service avec délégation au niveau du domaine

Si vous êtes administrateur en charge de la gestion des groupes d'identités ou si vous souhaitez fournir à un compte des droits relatifs à l'ensemble du domaine lui permettant de gérer les Google Groupes pour le compte des administrateurs, vous devez vous authentifier en tant que compte de service.

Pour en savoir plus sur la configuration de la délégation au niveau du domaine, consultez la page Contrôler l'accès à l'API à l'aide de la délégation au niveau du domaine.

Pour en savoir plus sur l'authentification en tant que compte de service, consultez l'article Utiliser OAuth 2.0 pour les applications de serveur à serveur. Lors de l'initialisation de l'identifiant dans votre code, spécifiez l'adresse e-mail avec laquelle le compte de service agit en appelant with_subject() sur l'identifiant. Exemple :

Python 

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

Instancier un client

L'exemple suivant montre comment instancier un client à l'aide des identifiants d'un compte de service. Pour vous authentifier en tant qu'utilisateur final, remplacez l'objet credential du compte de service par l'objet credential que vous avez obtenu précédemment dans Utiliser OAuth 2.0 pour les applications de serveur 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

Vous pouvez maintenant commencer à appeler l'API Groups.