Configurar la API Groups

En esta página se explica cómo configurar la API Groups de Cloud Identity.

Nota: Para usar la API Groups, debes habilitar Grupos de Google para Empresas en tu dominio y permitir que los usuarios finales creen grupos. Consulta los artículos Activar o desactivar Grupos para empresas y Configurar las opciones de uso compartido de Grupos para empresas para obtener más información. Para seguir estos pasos, debes tener acceso de administrador de Google Workspace a tu dominio.

Antes de empezar

Enable the Cloud Identity API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Instalar las bibliotecas de cliente

Para instalar las bibliotecas de cliente, ejecuta el siguiente comando:

Python

Para obtener más información sobre cómo configurar tu entorno de desarrollo de Python, consulta la guía de configuración del entorno de desarrollo de Python.

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

Autenticarse con la API Groups

Puedes autenticarte con la API Groups como usuario final, como administrador de un grupo de cuentas de servicio sin delegación en todo el dominio o como cuenta de servicio con delegación en todo el dominio. En las siguientes secciones se describe cada método.

Autenticarse como usuario final

Si no eres administrador o estás creando una aplicación que actúa en nombre de usuarios que no son administradores, consulta el artículo Usar OAuth 2.0 en aplicaciones de servidor web y, a continuación, la sección Crear una instancia de un cliente que se muestra más abajo.

Autenticarse como cuenta de servicio sin delegación de todo el dominio

Si utilizas una cuenta de servicio y quieres usarla para gestionar grupos como administrador de grupos, sigue los pasos que se indican a continuación. Este método de autenticación se debe usar cuando quieras que las acciones de la cuenta de servicio se registren en los registros de auditoría como la cuenta de servicio.

Asignar un rol de administrador a la cuenta de servicio

Nota: Si la cuenta de servicio no necesita acceder a todos los grupos, puedes hacerla propietaria de los grupos que le interesen. En este caso, no es necesario que asignes el rol de administrador del grupo.

En primer lugar, debes asignar el rol de administrador de grupos de Google Workspace (GroupAdministrator) a la cuenta de servicio que quieras delegar mediante la API Roles and Role Assignments del SDK de administrador. Con este paso, la cuenta de servicio obtiene acceso a los grupos del dominio, pero no a otros recursos.

Nota: Para convertir la cuenta de servicio en administrador delegado, debes tener acceso de superadministrador de Google Workspace en tu dominio.

Consulta la guía sobre cómo gestionar roles para obtener información general sobre cómo gestionar roles con la API Admin SDK. Sigue los pasos que se indican a continuación para asignar el rol de administrador de grupo a tu cuenta de servicio.

1. En la Google Cloud consola, ve a la página Cuentas de servicio:

   Ir a Cuentas de servicio

2. Haz clic en el nombre de la cuenta de servicio que quieras usar con la API Groups.

3. Copia el ID único de la cuenta de servicio.

4. Llama a la API Roles del SDK de administrador para identificar el roleId de administrador de grupo. Para ello, puedes usar el Explorador de APIs de la documentación del SDK de administrador.

5. Llama a la API Role Assignments con el siguiente cuerpo de solicitud:

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

Autenticar y autorizar la cuenta de servicio

Ahora tienes una cuenta de servicio con el rol de administrador de grupos. El segundo paso es completar el proceso de autenticación OAuth de la cuenta de servicio.

• Si estás desarrollando una aplicación en Google Cloud y la cuenta de servicio es propietaria del proyecto, puedes usar las credenciales predeterminadas de la aplicación, lo que puede simplificar el proceso. Consulta más información en el artículo Autenticarse como cuenta de servicio.

• Si la cuenta de servicio no es la propietaria del proyecto, sigue las instrucciones que se indican a continuación.

En ambos casos, el ámbito aplicable de la API Groups de Cloud Identity es https://www.googleapis.com/auth/cloud-identity.groups.

1. Con la credencial que acabas de crear, genera un token de acceso.

   Nota: No suplantes la identidad de un usuario al generar credenciales. Omite los campos como 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();
   

   Guarda el token de acceso que se ha generado.

Código completo para generar un token de acceso para una cuenta de servicio

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

Compilar regla

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

Probar la cuenta de servicio

1. Prueba cualquier llamada a la API Groups con las credenciales de la cuenta de servicio: crea un grupo, añade usuarios, actualiza la configuración del grupo, etc.

2. Consulta los registros de auditoría en la sección Informes de la consola de administración de Google. Deberías ver la cuenta de servicio como el actor de los cambios relacionados con tu grupo. Consulta más información en el artículo Registrar eventos.

   También puedes usar APIs para acceder a los registros de auditoría. Para comprobarlo con el Explorador de APIs Reports, asegúrate de usar tus credenciales de OAuth de administrador.

Autenticarse como cuenta de servicio con delegación de todo el dominio

Si eres administrador y gestionas grupos de identidades, o si quieres proporcionar a una cuenta privilegios en todo el dominio para que pueda gestionar Grupos de Google en nombre de los administradores, debes autenticarte como cuenta de servicio.

Nota: La delegación de todo el dominio permite que la cuenta de servicio suplante la identidad de un usuario administrador, por lo que los registros de auditoría mostrarán las acciones de la cuenta de servicio como si las hubiera realizado el usuario. Si quieres que las acciones se muestren como la cuenta de servicio, consulta la sección Autenticación como cuenta de servicio sin delegación en todo el dominio

más arriba.

Para obtener más información sobre cómo configurar la delegación de todo el dominio, consulta el artículo Controlar el acceso a las APIs con la delegación de todo el dominio.

Para autenticarte como cuenta de servicio, consulta el artículo Usar OAuth 2.0 en aplicaciones de servidor a servidor. Al inicializar la credencial en tu código, especifica la dirección de correo en la que actúa la cuenta de servicio llamando a with_subject() en la credencial. Por ejemplo:

Python

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

Crear una instancia de un cliente

En el siguiente ejemplo se muestra cómo crear una instancia de un cliente mediante credenciales de cuenta de servicio. Para autenticarte como usuario final, sustituye el objeto credential de la cuenta de servicio por el credential que has obtenido anteriormente en Uso de OAuth 2.0 para aplicaciones de servidor 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

Ahora puedes empezar a hacer llamadas a la API Groups.