1. Introduction

Cyber Guru offers the ability to automatically synchronize your organization's users directly from Google Workspace. This integration keeps the user list on the Cyber Guru platform up to date without manual intervention, reflecting in real time the changes made in your Google domain.

This guide describes, step by step, the operations to perform on your Google Workspace account and the data to provide to the Cyber Guru team to complete the configuration.

The services offered by the synchronization are Create, Update, Suspend (Delete).

The fields automatically synchronized are:

1.1 Process Overview

The integration is based on a Google Service Account authorized to read your domain's users in read-only mode. Below are the main phases:

2. Prerequisites

Before proceeding, make sure you meet the following requirements:

• Access as Super Admin (or delegated Admin with permissions on Service Accounts) to the Google Admin Console (admin.google.com)
• Access to the Google Cloud Console (console.cloud.google.com) with Owner or Editor role on the organization's Google Cloud project
• An existing Google Cloud project associated with the Google Workspace domain (or the ability to create one)
• Login credentials for the Cyber Guru platform with administrator role

3. Configuration on Google Cloud Console

3.1 Accessing the Google Cloud Console

1. Open your browser and navigate to https://console.cloud.google.com
2. Log in with the organization's administrator account
3. From the menu in the top left, verify that you are in the correct Google Cloud project (e.g. the project associated with the corporate domain)

3.2 Creating the Service Account

The Service Account is an application identity that Cyber Guru uses to authenticate to the Google Workspace APIs. Proceed as follows:

1. From the side menu, select IAM & Admin > Service Accounts
2. Click + CREATE SERVICE ACCOUNT
3. Fill in the form with the following values:
   • Service account name: cyberguru-sync (or a name of your choice)
   • Service account ID: will be generated automatically based on the name
   • Description: Service account for user synchronization with Cyber Guru
4. Click CREATE AND CONTINUE
5. In the Grant this service account access to project section, assign the Viewer role and click CONTINUE
6. In the Grant users access to this service account section, leave blank and click DONE

3.3 Enabling Domain-Wide Delegation

To allow the Service Account to read users across the entire Google Workspace domain, you need to enable Domain-Wide Delegation.

1. In the list of Service Accounts, click on the Service Account you just created
2. Select the Advanced settings tab
3. In the Domain-wide delegation section, click Edit and copy the Client ID

3.4 Generating the JSON Key (google_private_key)

The JSON key contains the cryptographic credentials that Cyber Guru uses to authenticate. It is the most sensitive element of the entire configuration.

1. Open the Service Account you created
2. Select the KEYS tab
3. Click ADD KEY > Create new key
4. Select the JSON format
5. Click CREATE: the JSON file will be automatically downloaded to your computer

4. Configuration on Google Admin Console

4.1 Authorizing the Service Account (OAuth Scopes)

In the Google Admin Console, you need to authorize the Service Account to access the Google Workspace APIs through the appropriate OAuth Scopes.

1. Navigate to https://admin.google.com and log in as Super Admin
2. From the menu, select Security > Access and data control > API controls
3. Click Manage Domain-Wide Delegation
4. Click Add new
5. In the Client ID field, enter the numeric Client ID of the Service Account noted earlier
6. In the OAuth Scopes field, enter the following scopes separated by commas:

1. Click AUTHORIZE

4.2 Retrieving the Customer ID (google_customer_id)

The Customer ID uniquely identifies your Google Workspace account.

1. From the Google Admin Console, navigate to Account > Account settings
2. In the Profile information section, find the Customer ID field
3. The value has the format Cxxxxxxxx (e.g. C03abc1de)
4. Note this value: it corresponds to the google_customer_id parameter

4.3 Retrieving the Domain (google_domain)

The primary domain of your Google Workspace is visible in the Google Admin Console:

1. From the Google Admin Console, navigate to Account > Domains > Manage domains
2. The primary domain (marked as Primary) is the value to be provided
3. E.g.: company.com. Corresponds to the google_domain parameter

4.4 Identifying the Admin Email (google_admin_email)

The Service Account must impersonate an administrator account to read the domain's users. Identify an account with the following requirements:

• Must be a real user of the Google Workspace domain (not an alias)
• Must have the Super Admin role or Admin role with read-only permissions on the directory
• Must be a stable account, not subject to deactivation or email change

This value corresponds to the google_admin_email parameter to be provided to Cyber Guru.

5. Advanced Parameters

The following three parameters are optional and concern advanced customization features. Configure them only if necessary, in agreement with the Cyber Guru team.

5.1 google_custom_schemas

Google Workspace allows administrators to add custom attributes to users via Custom Schemas. These attributes are not part of the standard user profile and are defined by the administrator to meet the organization's specific needs (e.g. department, location, risk level, etc.).

The google_custom_schemas parameter tells Cyber Guru which custom schemas to read for each user. If your organization uses custom schemas and you want Cyber Guru to import them, proceed as follows:

1. From the Google Admin Console, navigate to Directory > Custom settings
2. Check which custom schemas are defined (e.g. HR_Data, Security_Attributes)
3. For each schema of interest, note down the schema name and the field names to include

The value to be provided is a list of schema names, for example:

5.2 google_org_mapping

The google_org_mapping parameter defines how to rename the Google Workspace Custom Schema fields when they are synchronized as org fields in Cyber Guru.

This mapping allows you to standardize the names of custom attributes coming from Google, making them consistent with the naming used in Cyber Guru (e.g. department, location, manager).

Format

Example

Each line contains the pair SchemaFieldName; target_name:

Fields not included in the mapping are still synchronized, keeping their original structure.

5.3 google_groups

The google_groups parameter allows you to limit synchronization to only users belonging to one or more specific Google Workspace groups. If not configured, all domain users are synchronized.

If your organization wants to synchronize only a subset of users based on group membership, proceed as follows:

1. From the Google Admin Console, navigate to Directory > Groups
2. Identify the groups of interest and note down the ID of each group

How it works: only users who are direct members of at least one of the specified groups will be synchronized. If a configured group is not found in Google Workspace, synchronization for the company is stopped (fail-safe behavior).

ℹ️ When to configure this parameter This parameter is optional. If you want to synchronize all domain users, leave it blank. It can be combined with google_domain: in that case, only users from the specified groups who belong to the specified domain will be synchronized.

6. Summary of Parameters to Provide

Once you have completed the operations described in the previous sections, collect all the values in the table below and send them to the Cyber Guru team via ticket or encrypted email (see Section 7).

7. How to Send Data to Cyber Guru

Once you have collected all the parameters, provide them to the Cyber Guru team following the instructions below.

7.1 Accepted Channels

• Support ticket on the Cyber Guru platform (preferred method): attach the data in an encrypted text file
• Email to your Cyber Guru contact: use only verified corporate email addresses

7.2 Recommended Format for the Ticket / Email

Include the following information in the body of the message or as an attachment:

7.3 What to Expect After Submission

1. The Cyber Guru team will receive the data and load it into your instance's configuration within 1-2 business days
2. A connectivity test and an initial user import will be performed
3. You will receive confirmation via ticket with the number of synchronized users and the outcome of the operation
4. In case of errors, the Cyber Guru team will contact you to request the missing or correct information

8. Frequently Asked Questions (FAQ)

Q: Does the Service Account have access to sensitive user data?

A: No. The Service Account is configured with read-only scopes limited to the user directory. It does not have access to email, documents, calendar, or other personal user data.

Q: What happens if a user is deactivated in Google Workspace?

A: At each synchronization, Cyber Guru updates the users' status. Users deactivated or deleted from Google Workspace are automatically deactivated on the Cyber Guru platform as well.

Q: How often does synchronization occur?

A: The synchronization frequency is configurable by the Cyber Guru team based on your needs. By default, it runs every 24 hours. For specific needs, contact support.

Q: What happens if I change the password of the admin email specified in google_admin_email?

A: The admin email password does not affect the integration: the Service Account uses the JSON private key to authenticate, not the user's password. However, if the account is deactivated or the admin role is removed, synchronization will stop working. In that case, provide the new admin account to Cyber Guru.

Q: Do I need to renew the JSON key periodically?

A: Google JSON keys do not expire automatically, but it is good security practice to rotate them every 12 months. If you do so, generate a new key (section 3.4), delete the old one from the Google Cloud project, and provide the new key to the Cyber Guru team.

Q: Can I use a Service Account that already exists in my organization?

A: Yes, you can use an existing Service Account as long as it does not have excessive permissions. Verify that it has Domain-Wide Delegation enabled and the correct OAuth Scopes as indicated in section 4.1.

Q: Are google_custom_schemas and google_org_mapping mandatory?

A: No, both parameters are optional. If you do not use custom schemas or an organizational mapping is not required, let the Cyber Guru team know and they will configure the integration with the default values.

Q: Does synchronization include users from all of the organization's domains?

A: By default, only the domain specified in google_domain is synchronized. If your organization has multiple Google Workspace domains (alias domains or additional domains), contact the Cyber Guru team.

Q: Can I synchronize only some Custom Schemas?

A: Yes, use the google_custom_schemas field to specify which schemas to synchronize.

Q: Can I rename the Custom Schema fields?

A: Yes, use the google_org_mapping field to map SchemaName.FieldName → tags.custom_name.

Q: Why isn't the country synchronized?

A: The countryCode field is only available if the address is entered via API with structured fields. In the Google Admin Console, the address field is free text and does not provide a countryCode.

Q: Can I modify users from CyberGuru to Google?

A: No, synchronization is one-way. Google Workspace is always the source of truth.

Q: Are users deleted?

A: No, if a user no longer exists in Google, they are only suspended in CyberGuru, not deleted.

Q: Can I synchronize only users from specific Google groups?

A: Yes, provide the Cyber Guru team with the IDs of the Google groups to include. Only users who are members of at least one of the specified groups will be synchronized.

Q: What happens if a configured group no longer exists?

A: Synchronization for the company is stopped for security reasons. Contact the Cyber Guru team to update the configuration.

9. Support and Contacts

If you have any questions during configuration, the Cyber Guru team is available through the following channels: