You can synchronize users and groups from Google Workspace. To enable the sync, you need to complete steps both in the Google and Haiilo Administration.

When syncing a user directory, users and groups are considered separately in the sync. Groups are synced first, followed by users. Users can only be added to groups synced in the first step. However, all users matching the user filters are synced, regardless of whether they belong to the groups synced in the group sync.

Please complete the app registration in Google Workspace as detailed in the Setting up Google Workspace authentication article before proceeding with this tutorial.

Create a service account in Google

You need super admin rights in your Google Workspace account to complete the service account configuration.

Activate Admin SDK API access

1. Log in to the Google Cloud Platform.
2. Select the project that you created when setting up Google authentication for Haiilo
3. Go to Menu > APIs and Services > Library
4. Search the API library for and select the Admin SDK API
5. Enable the API for your project

Create a service account

1. In Google Cloud, go to Menu > APIs and Services > Credentials
2. Select Create credentials and select Service account.
3. Define the service account details:
   • Enter a name
   • Use the automatically generated Service account ID or generate a new one
   • Choose the role Owner
4. Select the newly created service account > Keys
5. Add and then create a new JSON key. The key downloads to your computer. You may rename the key for easier identification, e.g., service-account.json.
6. From the Details tab, copy the Unique ID

Enable domain delegation

1. Open admin.google.com
2. Go to Menu > Security > Access and data control > API Controls.
3. Select Manage Domain Wide Delegation.
4. Select Add new and paste the Unique ID that you copied earlier in the Client ID field
5. In the OAuth Scopes fields, enter and authorize the below scopes:

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

Set up a new user directory in Haiilo

You need to have "Manage user directories" permission to set up a Google user directory in Haiilo.

1. In Haiilo, go to Administration > User directories
2. Select Create user directory
3. Enter a name
4. Choose the type: Google Workspace
5. Check Active, if this new user directory should be activated directly

Fill out the fields on each tab as detailed below.

Connection

The information to fill in the Connection tab can be found in the service account JSON file that you downloaded from Google Cloud Console.

1. Service account user email: Enter the email address of the Google Admin account you used for the configuration
2. Client ID: Enter the "client_id" from the JSON file
3. Client email: Enter the "client_email" from the JSON file
4. Private key: Enter the "private_key" from the JSON file
5. Private key ID: Enter the "private_key_id" from the JSON file
6. Project ID: Enter the "project_id" from the JSON file
7. Token URI: Enter the "token_uri" from the JSON file

User

1. User filter: Define filters to synchronize only certain users. You can use the standard Google filters, e.g., name='Jane Smith',givenName:{B}*. For custom fields, the field name should be specified with the category, e.g., categoryName.customField='value'.
   • You can find more information on user filters in Google's Developer guides.
2. Remove local groups: Check if you want to remove the synced users from any local groups they've been manually added to.
3. Remove other directory groups: Check if you want to remove the synced users from any other user directory groups they've been manually added to.
4. Username: Enter the attribute for username. We recommend using primaryEmail.
5. You can synchronize users' profile fields. Only professional fields that consist of a string and not an array can be synced.

Groups

1. To synchronize groups from Google Workspace, check Synchronize groups.
2. Group filters: Define filters to synchronize only certain groups. You can use the standard Google filters, e.g., name='Test group'.
   • You can find more information on group filters in Google's Developer guides.
3. Users from groups only: Check if you only want to sync users that are part of a synchronized group. Enabling this means that only the users matching the User filter that also belong to a group synced in the group sync will be synced.
4. Preserve groups: If Synchronize groups is disabled, you can check this field to preserve any previously synced groups for this specific user directory. This way, you can freeze the previously synced groups. If left unchecked, any previously synced groups and their memberships will be removed in the next sync.

Synchronization

1. Page size: Defines how many items are synchronized per query. The LDAP protocol limit is 1000, so don't choose a higher value.
2. Activation: If checked, new and restored users are activated during synchronization. Otherwise, you have to manually set the status of the users to Active in the user management.
3. Orphaned users: Choose what happens to users that currently exist as active users on Haiilo, but no longer exist in the user directory. If you choose Ignore, they will remain unchanged.
4. Restore users: If checked, a user who has been deactivated or deleted from Haiilo but is present again in the user directory during the sync will be reactivated. It's not possible to restore anonymized users. A previously anonymized user can only be created as a new user.

Scheduling

1. Choose the synchronization frequency. If you choose Disabled, you run the sync manually.