Configurazione dell'API Groups

Questa pagina spiega come configurare l'API Cloud Identity Groups.

Nota :per utilizzare l'API Groups, devi aver attivato Google Groups for Business per il tuo dominio e consentire agli utenti finali di creare gruppi. Per ulteriori informazioni, vedi Attivare o disattivare Groups for Business e Impostare le opzioni di condivisione di Groups for Business. Questi passaggi richiedono l'accesso amministratore di Google Workspace al tuo dominio.

Prima di iniziare

Abilita l'API Cloud Identity.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Installazione delle librerie client

Per installare le librerie client, esegui questo comando:

Python

Per ulteriori informazioni sulla configurazione dell'ambiente di sviluppo Python, consulta la Guida alla configurazione dell'ambiente di sviluppo Python.

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

Autenticazione con l'API Groups

Puoi eseguire l'autenticazione con l'API Groups come utente finale, come amministratore di un gruppo di service account senza delega a livello di dominio o come account di servizio con delega a livello di dominio. Le sezioni seguenti descrivono ciascun metodo.

Autenticazione come utente finale

Se non sei un amministratore o stai creando un'app che agisce per conto di utenti che non sono amministratori, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni server web e poi la sezione Creazione di un'istanza di un client di seguito.

Eseguire l'autenticazione come account di servizio senza delega a livello di dominio

Se utilizzi un account di servizio e vuoi utilizzarlo per gestire i gruppi come amministratore del gruppo, completa i passaggi riportati di seguito. Questo metodo di autenticazione deve essere utilizzato quando vuoi che le azioni delaccount di serviziot vengano registrate nei log di controllo comaccount di serviziont.

Assegnazione di un ruolo amministrativo al account di servizio

Suggerimento: se il account di servizio non ha bisogno dell'accesso a tutti i gruppi, valuta la possibilità di renderlo Proprietario dei gruppi di interesse. In questo caso non è necessario assegnare il ruolo di amministratore del gruppo.

Innanzitutto, devi assegnare il ruolo Amministratore di gruppi Google Workspace (Amministratore di gruppi) alaccount di serviziot a cui vuoi delegare l'accesso, utilizzando l'API Roles and Role Assignments dell'SDK Admin. Questo passaggio concede al account di servizio l'accesso ai gruppi del dominio, ma a nessun'altra risorsa.

Nota :per fare in modo che il account di servizio diventi un amministratore delegato, devi disporre dell'accesso come super amministratore di Google Workspace per il tuo dominio.

Consulta la guida alla gestione dei ruoli per informazioni generali sulla gestione dei ruoli utilizzando l'API SDK Admin. Segui i passaggi riportati di seguito per assegnare il ruolo di amministratore del gruppo al tuo account di servizio.

1. Nella console Google Cloud , vai alla pagina Service account:

   Vai a Service account

2. Fai clic sul nome del account di servizio che vuoi utilizzare con l'API Groups.

3. Copia l'ID univoco del account di servizio.

4. Chiama l'API Roles dell'SDK Admin per identificare roleId per l'amministratore del gruppo. Per farlo, puoi utilizzare API Explorer nella documentazione di SDK Admin.

5. Chiama l'API Role Attribution con il seguente corpo della richiesta:

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

Autenticazione e autorizzazione del account di servizio

Ora hai un account di servizio con il ruolo di amministratore del gruppo. Il secondo passaggio consiste nel completare la procedura di autenticazione OAuth per ilaccount di serviziot.

• Se stai sviluppando un'app su Google Cloud e il account di servizio è proprietario del progetto, puoi utilizzare le credenziali predefinite dell'applicazione per semplificare la procedura. Per saperne di più, consulta Autenticazione come service account.

• Se il account di servizio non è il proprietario del progetto, segui le istruzioni riportate di seguito.

In entrambi i casi, l'ambito applicabile per l'API Cloud Identity Groups è https://www.googleapis.com/auth/cloud-identity.groups.

1. Utilizza le credenziali appena create per generare un token di accesso.

   Nota: non impersonare un utente durante la generazione delle credenziali. Salta i campi come with_subject, createDelegated o 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();
   

   Python

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/cloud-identity.groups']
   SERVICE_ACCOUNT_FILE = '/path/to/service-account-file.json'
   
   credentials = service_account.Credentials.from_service_account_file(
       SERVICE_ACCOUNT_FILE, scopes=SCOPES)
   

   Go

   import (
           "context"
           "os"
   
           "golang.org/x/oauth2/google"
   )
   
   ctx := context.Background()
   jsonKey, err := os.ReadFile("/path/to/service-account-file.json")
   if err != nil {
           // Handle error.
   }
   conf, err := google.JWTConfigFromJSON(jsonKey, "https://www.googleapis.com/auth/cloud-identity.groups")
   if err != nil {
           // Handle error.
   }
   ts := conf.TokenSource(ctx)
   

   Conserva il token di accesso generato.

Codice completo per generare un token di accesso per un service account

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

Regola di build

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

Test del account di servizio

1. Prova una chiamata API Groups con le credenziali dell'account di servizio: crea un gruppo, aggiungi utenti, aggiorna le impostazioni del gruppo e così via.

2. Controlla i log di controllo nella sezione Report della Console di amministrazione Google. Dovresti visualizzare ilaccount di serviziot come attore delle modifiche relative al gruppo. Per saperne di più, consulta Eventi di log.

   In alternativa, puoi utilizzare le API per accedere agli audit log. Per eseguire il controllo utilizzando Explorer API per i report, assicurati di utilizzare le credenziali OAuth dell'amministratore.

Eseguire l'autenticazione come account di servizio con delega a livello di dominio

Se sei un amministratore che gestisce i gruppi di identità o se vuoi fornire a un account privilegi a livello di dominio in modo che possa gestire Google Gruppi per conto degli amministratori, devi autenticarti come service account.

Nota :poiché la delega sull'intero dominio funziona consentendo al account di servizio di impersonare un utente amministratore, i log di controllo mostreranno le azioni del account di servizio come se fossero state eseguite dall'utente. Se vuoi che le azioni vengano visualizzate come account di servizio, consulta la sezione Eseguire l'autenticazione come account di servizio senza delega a livello di dominio sopra.

Per informazioni dettagliate sulla configurazione della delega a livello di dominio, vedi Controllare l'accesso all'API con la delega a livello di dominio.

Per eseguire l'autenticazione come account di servizio, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni server-to-server. Quando inizializzi la credenziale nel codice, specifica l'indirizzo email su cui agisce il account di servizio chiamando with_subject() sulla credenziale. Ad esempio:

Java

import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials
    .fromStream(new FileInputStream(SERVICE_ACCOUNT_FILE))
    .createScoped(SCOPES)
    .createDelegated(delegated_email);

Python

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

Go

import (
        "context"
        "os"

        "golang.org/x/oauth2/google"
)

ctx := context.Background()
jsonKey, err := os.ReadFile(SERVICE_ACCOUNT_FILE)
if err != nil {
        // Handle error.
}
config, err := google.JWTConfigFromJSON(jsonKey, SCOPES...)
if err != nil {
        // Handle error.
}
config.Subject = delegated_email
ts := config.TokenSource(ctx)

Creazione di un'istanza di un client

L'esempio seguente mostra come creare un'istanza di un client utilizzando le credenziali del account di servizio. Per eseguire l'autenticazione come utente finale, sostituisci l'oggetto credential dell'account di servizio con l'oggetto credential che hai ottenuto in precedenza in Utilizzo di OAuth 2.0 per applicazioni server web.

Java

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.cloudidentity.v1.CloudIdentity;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

import java.io.FileInputStream;
import java.util.Collections;
import java.util.List;

// ...

List<String> SCOPES = Collections.singletonList("https://www.googleapis.com/auth/cloud-identity.groups");
String SERVICE_ACCOUNT_FILE = "/path/to/service-account-file.json";

public CloudIdentity createService() throws Exception {
  GoogleCredentials credentials = GoogleCredentials
      .fromStream(new FileInputStream(SERVICE_ACCOUNT_FILE))
      .createScoped(SCOPES)
      .createDelegated("[e-mail]"); // Omit for no domain-wide delegation

  CloudIdentity service = new CloudIdentity.Builder(
      GoogleNetHttpTransport.newTrustedTransport(),
      GsonFactory.getDefaultInstance(),
      new HttpCredentialsAdapter(credentials))
      .setApplicationName("your-app-name")
      .build();

  return service;
}

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]') # Omit for no domain-wide delegation

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

  return service

Go

import (
        "context"
        "os"

        "golang.org/x/oauth2/google"
        "google.golang.org/api/cloudidentity/v1"
        "google.golang.org/api/option"
)

// ...

scopes := []string{"https://www.googleapis.com/auth/cloud-identity.groups"}
serviceAccountFile := "/path/to/service-account-file.json"

func createService(ctx context.Context) (*cloudidentity.Service, error) {
        jsonKey, err := os.ReadFile(serviceAccountFile)
        if err != nil {
                return nil, err
        }
        config, err := google.JWTConfigFromJSON(jsonKey, scopes...)
        if err != nil {
                return nil, err
        }
        config.Subject = "[e-mail]" // Omit for no domain-wide delegation
        ts := config.TokenSource(ctx)

        service, err := cloudidentity.NewService(ctx, option.WithTokenSource(ts))
        return service, err
}

Ora puoi iniziare a effettuare chiamate all'API Groups.