Google Workspace

Este módulo permite a Anjana Data sincronizar usuarios directamente desde el directorio de Google Workspace de su organización.

La integración utiliza la Google Directory API mediante una Cuenta de Servicio con Delegación de Dominio (Domain-Wide Delegation). Esto permite a la aplicación "impersonar" (actuar en nombre de) un administrador para leer el directorio sin interacción humana.

Existen dos modos de sincronización según si se configuran o no group-names:

• Modo filtrado por Grupos (con group-names): Anjana obtiene los miembros de los grupos indicados (incluyendo subgrupos de forma transitiva) y sincroniza solo esos usuarios. Recomendado cuando solo un subconjunto del dominio debe tener acceso.

• Modo dominio completo (sin group-names): Anjana llama a GET /admin/directory/v1/users con el valor de customer (por defecto my_customer, alias del dominio autenticado) y sincroniza todos los usuarios del dominio, incluyendo los de dominios secundarios. Puede especificar un Customer ID explícito (ej. C02xxxxxx) para entornos multi-tenant.

Parte 1: Configuración en Google Cloud (Service Account)

Primero debemos crear la identidad de máquina (Cuenta de Servicio) que Anjana utilizará.

1. Acceda a la Consola de Google Cloud (console.cloud.google.com).

2. Vaya a IAM y administración > Cuentas de servicio.

3. Haga clic en + CREAR CUENTA DE SERVICIO.

   • Asígnele un nombre (ej. anjana-provisioning).

   • Haga clic en Listo (no necesita asignar roles de IAM de proyecto).

4. En la lista, haga clic en la cuenta recién creada.

5. Vaya a la pestaña Claves > Agregar clave > Crear clave nueva.

   • Seleccione el formato JSON y descárguela.

   • Importante: Guarde este archivo, lo necesitará para configurar Anjana.

6. Vaya a la pestaña Detalles y copie el "ID único" (Client ID). Es un número largo numérico (ej. 1029384756...). Lo necesitará en el siguiente paso.

Parte 2: Delegación de Dominio (Google Admin)

Ahora debemos autorizar a esa Cuenta de Servicio para leer el directorio corporativo.

1. Acceda a la Consola de Administración de Google (admin.google.com) con una cuenta de Super Administrador.

2. Vaya a Seguridad > Control de acceso y datos > Controles de API.

3. En la parte inferior, haga clic en Gestionar la delegación de todo el dominio.

4. Haga clic en Añadir nueva:

   • ID de cliente: Pegue el "ID único" numérico que copió en la Parte 1.

   • Ámbitos de OAuth (Scopes): Copie y pegue exactamente la siguiente lista (separada por comas):

     https://www.googleapis.com/auth/admin.directory.user.readonly,
     https://www.googleapis.com/auth/admin.directory.group.readonly,
     https://www.googleapis.com/auth/admin.directory.group.member.readonly
     

5. Haga clic en Autorizar.

Parte 3: Configuración en application.yml

Necesitará decidir cómo proporcionar el fichero JSON descargado:

• Opción A (Recomendada): Subir el fichero al servidor y usar json-path.

• Opción B: Pegar el contenido del JSON directamente en el YAML usando json-content.

Modo filtrado por Grupos (con group-names)

Solo se sincronizan los miembros de los grupos indicados (incluyendo subgrupos de forma transitiva).

security:
  provisioning:
    providers:
      google:
        google-workspace:
          delegated-user: "admin@empresa.com"
          application-name: "Anjana Data Sync"
          # Solo usuarios de estos grupos (y sus subgrupos)
          group-names:
            - "todos-los-empleados@empresa.com"
            - "usuarios-anjana@empresa.com"

          # OPCIÓN A: Ruta al fichero JSON
          json-path: "/opt/anjana/config/keys/google-service-account.json"

          # OPCIÓN B: Contenido directo del JSON
          # json-content: |
          #   { "type": "service_account", ... }

Modo dominio completo (sin group-names)

Se sincronizan todos los usuarios del dominio Google Workspace (incluyendo dominios secundarios).

security:
  provisioning:
    providers:
      google:
        google-workspace:
          delegated-user: "admin@empresa.com"
          application-name: "Anjana Data Sync"
          # group-names no configurado → sincronización de todo el dominio

          # ID del Customer de Google Workspace (ej. C02xxxxxx).
          # Por defecto "my_customer" (alias del dominio autenticado).
          # Solo necesario en entornos multi-tenant o con Customer ID explícito.
          # customer: "C02xxxxxx"

          # OPCIÓN A: Ruta al fichero JSON
          json-path: "/opt/anjana/config/keys/google-service-account.json"

Explicación de Propiedades

Mapeo de campos personalizado (field-mapping)

Anjana incluye un mapeo por defecto que cubre los casos habituales. Puede sobreescribir cualquier campo indicando la clave de la que debe leer el valor. Las claves son listas en orden de prioridad: se usa el primer valor no vacío.

Mapeo por defecto

Campos disponibles

Ejemplo de configuración

security:
  provisioning:
    providers:
      google:
        google-workspace:
          delegated-user: "admin@empresa.com"
          application-name: "Anjana Data Sync"
          json-path: "/opt/anjana/keys/google-sa.json"
          field-mapping:
            # Usar recoveryEmail como email de contacto si primaryEmail es corporativo
            email: ["recoveryEmail", "primaryEmail"]
            # Leer cargo y si está vacío usar el departamento
            title: ["title", "department"]