Welcome to this online guide which will show you how to, in a few quick steps, configure your Google Workspace with Hector. This will allow you to benefit from Google sign in functionalities, as well as importing your users and groups into Hector.
Connection
1. Connect to your Google Admin account.
You must have administrator privileges in order to add Hector as an authorized App.
2. Domain
Once connected, click on the “Manage Domains” link on your home page and then copy your primary domain, as you will need it later in the guide.
3. Domain-Wide Delegation
Next step is the domain-wide delegation. This allows certain users or applications from outside your group to read or manipulate parts of the group. In our case, you will want to add the Hector application with the privileges to read-only your groups, group members and users. Here are a couple of lines your are going to need to configure your domain-wide delegation:
Client ID (HECTOR): 112195502243245937406
Scopes (privileges):
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.group.member.readonly
- https://www.googleapis.com/auth/admin.directory.user.readonly
Click on the “Security” and “API Controls” button on the menu and then click the “Manage Domain Wide Delegation” link.
Click on the “Add new” button. Fill out the form with all the information above, then click “Authorize”.
You have completed the Google Workspace portion of the setup. Next step is to access your Hector instance as an administrator
4. Hector Setup for Google Authentication
Connect to your Hector instance as an administrator and navigate to the “Settings” menu, and then click on “Security”. Once inside, choose the “Google Workspace” option from the list in order to display the necessary fields to configure authentication using Google.
If you save your configuration like this, your users can now begin to sign on to Hector using their Google accounts. If you want to import your Google Workspace (which is probably the reason you are reading this guide) and have a daily synchronization, follow the next steps!
Synchronization
To activate the Google Workspace integration, log in to your Hector administrator account. Only administrators can configure integrations.
In the Google Workspace integration settings, you must complete the fields Domain and Administrator Email displayed in the image. If you have completed those fields in Settings > Security > Google Workspace, they should appear with the correct informations inside them, you can either save to keep the same settings or change them if you want to use another Google Workspace instance to synchronize your users.
- The domain is the field that we retrieved in the second step of the guide.
- The administrator email is an email with admin privileges inside your Google Workspace.
- What you are going to enter in “Administrator Group”, “Staff Group” and “Users Group” is the left part of the “@” of your group’s email address. You can find those in your Google Workspace by clicking on “Directory” and “Groups“. You can add more than one per role if you separate their names by a comma.
Once you decide on all your groups, complete the form. It should look similar to this:
Don’t forget to save your configurations! Users not synchronized for more than 2 days are automatically deactivated in Hector.
6. How the Integration Works
🔄 What to Expect When Syncing
Once synchronization is enabled, Hector will start syncing with Google Workspace based on your integration settings based on the sync frequency.
⚠️ Note: This is a one-way sync from Google Workspace → Hector. Hector does not send updates back to Google.
🕒 Sync Frequency
Hector syncs with Google Workspace every night. Any new, updated, or deactivated members in Google Workspace will be reflected in Hector based on your integration rules.
🔁 Initial Sync Behavior
- All Google Workspace members belonging to one of the groups retrieved according to the filters defined in the group import — as configured in the integration settings — are synchronized.
- Existing Hector users with a matching email address will be updated.
- Only active Google workspace members not already in Hector will be created as new users.
🧱 Field Mapping on User Creation
When a Google Workspace member is created in Hector, the following fields are populated:
| Google Field | Hector Field | Notes |
|---|---|---|
| First Name | First Name | |
| Last Name | Last Name | |
| Used for matching existing users | ||
| Unique Identifier | ||
| Role | Title | |
| Language | Default language defined in Settings → Global → General → General → Language | |
| City | Default City defined in Settings → Global → General → Address → Default City | |
| Enabled | By default, set to “Enabled” | |
| Groups | Role | Role associated with the group configured in the integration settings. If a user belongs to multiple groups linked to different roles, the role placed highest in the integration settings will take priority |
| Groups | Groups | All groups associated with the user in Google Workspace that match the filter defined in the group import — as configured in the integration settings — are associated with the user in Hector. |
| Department | Default department defined in Settings → Entities → Resources → User → Options → Default department |
🔄 Field Mapping on User Update
When a Google Workspace member is updated, the changes are reflected in Hector by mapping the following fields:
| Google Field | Hector Field | Notes |
|---|---|---|
| First Name | First Name | Updated if changed |
| Last Name | Last Name | Updated if changed |
| Role | Title | Updated if changed |
| Groups | Role | Role associated with the group configured in the integration settings. If a user belongs to multiple groups linked to different roles, the role placed highest in the integration settings will take priority |
| Groups | Groups | All groups associated with the user in Google Workspace that match the filter defined in the group import — as configured in the integration settings — are associated with the user in Hector. |
⛔ Handling Inactive or Deleted Members
- If a Google Workspace member previously synchronized with Hector can no longer be retrieved (for example, if they have been deleted or deactivated), they will be automatically deactivated in Hector after more than 2 days without retrieval.
💡 Tip: Use Hector’s user retention settings to automatically delete users who have been inactive for X time.