Google Workspace

This module allows Anjana Data to synchronize users directly from your organization's Google Workspace directory.

The integration uses the Google Directory API via a Service Account with Domain-Wide Delegation. This allows the application to "impersonate" (act on behalf of) an administrator to read the directory without human interaction.

There are two synchronization modes depending on whether group-names is configured or not:

• Group-filtered mode (with group-names): Anjana retrieves the members of the specified groups (including subgroups transitively) and synchronizes only those users. Recommended when only a subset of the domain should have access.

• Full domain mode (without group-names): Anjana calls GET /admin/directory/v1/users with the value of customer (default my_customer, an alias of the authenticated domain) and synchronizes all domain users, including those from secondary domains. You can specify an explicit Customer ID (e.g. C02xxxxxx) for multi-tenant environments.

Part 1: Configuration in Google Cloud (Service Account)

First we need to create the machine identity (Service Account) that Anjana will use.

1. Go to the Google Cloud Console (console.cloud.google.com).

2. Go to IAM & Admin > Service Accounts.

3. Click + CREATE SERVICE ACCOUNT.

   • Assign it a name (e.g. anjana-provisioning).

   • Click Done (you don't need to assign project IAM roles).

4. In the list, click on the newly created account.

5. Go to the Keys tab > Add key > Create new key.

   • Select the JSON format and download it.

   • Important: Save this file, you will need it to configure Anjana.

6. Go to the Details tab and copy the "Unique ID" (Client ID). It is a long numeric number (e.g. 1029384756...). You will need it in the next step.

Part 2: Domain-Wide Delegation (Google Admin)

Now we need to authorize that Service Account to read the corporate directory.

1. Go to the Google Admin Console (admin.google.com) with a Super Administrator account.

2. Go to Security > Access and data control > API controls.

3. At the bottom, click Manage Domain Wide Delegation.

4. Click Add new:

   • Client ID: Paste the numeric "Unique ID" you copied in Part 1.

   • OAuth Scopes: Copy and paste exactly the following list (comma-separated):

     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. Click Authorize.

Part 3: Configuration in application.yml

You will need to decide how to provide the downloaded JSON file:

• Option A (Recommended): Upload the file to the server and use json-path.

• Option B: Paste the JSON content directly into the YAML using json-content.

Group-filtered mode (with group-names)

Only the members of the specified groups are synchronized (including subgroups transitively).

security:
  provisioning:
    providers:
      google:
        google-workspace:
          delegated-user: "admin@empresa.com"
          application-name: "Anjana Data Sync"
          # Only users from these groups (and their subgroups)
          group-names:
            - "todos-los-empleados@empresa.com"
            - "usuarios-anjana@empresa.com"

          # OPTION A: Path to the JSON file
          json-path: "/opt/anjana/config/keys/google-service-account.json"

          # OPTION B: Direct JSON content
          # json-content: |
          #   { "type": "service_account", ... }

Full domain mode (without group-names)

All users of the Google Workspace domain are synchronized (including secondary domains).

security:
  provisioning:
    providers:
      google:
        google-workspace:
          delegated-user: "admin@empresa.com"
          application-name: "Anjana Data Sync"
          # group-names not configured → full domain synchronization

          # Google Workspace Customer ID (e.g. C02xxxxxx).
          # Default "my_customer" (alias of the authenticated domain).
          # Only needed in multi-tenant environments or with an explicit Customer ID.
          # customer: "C02xxxxxx"

          # OPTION A: Path to the JSON file
          json-path: "/opt/anjana/config/keys/google-service-account.json"

Property Explanation

Custom field mapping (field-mapping)

Anjana includes a default mapping that covers common cases. You can override any field by specifying the key from which to read the value. Keys are listed in priority order: the first non-empty value is used.

Default mapping

Available fields

Configuration example

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:
            # Use recoveryEmail as contact email if primaryEmail is corporate
            email: ["recoveryEmail", "primaryEmail"]
            # Read job title and if empty use the department
            title: ["title", "department"]