Configurazione dell'API Groups

In questa pagina viene spiegato come configurare l'API Cloud Identity Groups.

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

Prima di iniziare

Attiva l'API Cloud Identity.

Abilita 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 autenticarti con l'API Groups come utente finale, come amministratore di gruppi di account di servizio senza delega a livello di dominio o come account di servizio con delega a livello di dominio. Le sezioni seguenti descrivono i singoli metodi.

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 Utilizzo di OAuth 2.0 per applicazioni server web e consulta la sezione Creazione di istanze di un client di seguito.

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 dei gruppi, completa i passaggi riportati di seguito. Questo metodo di autenticazione deve essere utilizzato quando vuoi che le azioni dell'account di servizio vengano registrate negli audit log come account di servizio.

Assegnazione di un ruolo di amministratore all'account di servizio

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

Innanzitutto, devi assegnare il ruolo Amministratore gruppi Google Workspace (Amministratore gruppo) all'account di servizio a cui vuoi delegare utilizzando i ruoli SDK Admin e l'API Role Attribution. Questo passaggio consente all'account di servizio di accedere ai gruppi del dominio, ma a nessun'altra risorsa.

Nota: per impostare l'account di servizio come amministratore con delega, 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 mediante l'API SDK Admin. Segui i passaggi riportati di seguito per assegnare il ruolo Amministratore di gruppi per il tuo account di servizio.

1. Nella console Google Cloud, vai alla pagina Account di servizio:

   Vai ad Account di servizio

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

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

4. Chiama l'API Admin SDK Roles per identificare il roleId per l'amministratore del gruppo. A questo scopo, puoi utilizzare Explorer API 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 dell'account di servizio

Ora disponi di un account di servizio con il ruolo Amministratore di gruppi. Il secondo passaggio consiste nel completare la procedura di autenticazione OAuth per l'account di servizio.

• Se stai sviluppando un'app su Google Cloud e l'account di servizio è un proprietario del progetto, puoi utilizzare le credenziali predefinite dell'applicazione, il che può semplificare il processo. Per ulteriori informazioni, consulta Autenticazione come account di servizio.

• Se l'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. Utilizzando la credenziale appena creata, genera un token di accesso.

   Nota: non impersonare un utente durante la generazione di credenziali. Salta 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();
   

   Conserva il token di accesso generato.

Codice completo per la generazione di un token di accesso per un account di servizio

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

Crea regola

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 dell'account di servizio

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

2. Controlla i log di controllo nella sezione Report della Console di amministrazione Google. Dovresti vedere l'account di servizio come attore delle modifiche relative al gruppo. Per ulteriori informazioni, consulta Eventi dei log.

   In alternativa, puoi utilizzare le API per accedere agli audit log. Per verificare se utilizzi lo strumento Explorer API Reports, assicurati di utilizzare le tue credenziali OAuth amministrative.

Autenticazione come account di servizio con delega a livello di dominio

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

Nota: poiché la delega a livello di dominio consente all'account di servizio di assumere l'identità di un utente amministratore, i log di controllo mostreranno tutte le azioni dell'account di servizio in qualità di utente. Se vuoi che le azioni vengano visualizzate come account di servizio, consulta la sezione Autenticazione come account di servizio senza delega a livello di dominio qui sopra.

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

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

Python

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

Creazione dell'istanza di un client

L'esempio seguente mostra come creare un'istanza di un client utilizzando le credenziali degli account di servizio. Per autenticarti come utente finale, sostituisci invece l'oggetto credential dell'account di servizio con il valore credential che hai ottenuto in precedenza in Utilizzo di OAuth 2.0 per applicazioni 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('[e-mail]')

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

  return service

Ora puoi iniziare a effettuare chiamate all'API Groups.