If an organisation uses Google Workspace, you no longer need to import its staff with a csv file. You link the platform to that organisation's Google environment and pick one group whose members take part. From that moment on, new staff are created automatically, changed details are copied over, and staff who disappear from the group are set to inactive.
It works the same way as the existing connection with Microsoft Entra. You'll find both under User synchronisation for the organisation.
What you need
The customer has to arrange two things for you in their own Google environment. Without those two the connection won't work, and you'll only notice at the first synchronisation.
- A service account with a key file. The customer creates it in Google Cloud, in the project their Workspace belongs to. The key file is a file in json form that can only be downloaded once.
- Domain-wide delegation for that service account, with exactly these two scopes:
https://www.googleapis.com/auth/admin.directory.user.readonlyhttps://www.googleapis.com/auth/admin.directory.group.readonly
Both are read-only. The platform therefore cannot change or delete anything in the customer's Google environment; it only reads the group and the details of its members.
You also need the email address of an administrator of that Google domain. Google does not allow a service account to request data on its own. It always does so on behalf of an existing user, and that user must have the rights to see the user list.
Watch out with new Google environments. Google nowadays switches on an organisation policy by default that forbids creating keys for service accounts. If the customer runs into that, their Google administrator has to switch that policy off for this one project. That is a deliberate choice by the customer and not something we can do from our side.
Step 1: set up the connection
Go to User synchronisation for the organisation and click Add Google Workspace connection under Google Workspace. You fill in four things:
- Under title you enter a name you'll recognise the connection by, for example the customer's name.
- Under administrator you enter the email address of the administrator on whose behalf the platform requests the data.
- Under domain you enter the customer's domain.
- Under service account key you paste the full contents of the json file.
The screen shows the two scopes once more, so you can copy them into the customer's Google admin console.
The key is stored encrypted and never shown again after saving. If you want to replace it later, you paste a new one into the field. If you leave the field empty, the existing key stays in place. If the platform does not recognise the pasted text as a Google key, you're told straight away rather than at the first synchronisation.
Step 2: set up the schedule
Go to Synchronisation schedules and create one. Under source you choose Google Workspace, and the screen adapts accordingly: you pick the connection you just created and under Google group you enter the email address of the group whose members take part, for example staff@customer.com.
The rest is the same as an Entra schedule. You choose the role new users get, how often the synchronisation runs, and whether new users receive a welcome email and a password link.
If there is no Google connection for this organisation yet, the screen says so and points you to the place where you create one.
What happens in each run
The platform fetches the members of the specified group and goes through them one by one.
- Staff who don't exist yet are created, with the role from the schedule.
- Existing staff are updated.
- If a staff member has a department, that department is created in the platform if it doesn't exist yet, and the staff member is linked to it.
- Staff who previously came in through this group but are no longer in it are set to inactive.
- If there is a group inside the group, its members are included as well.
These fields come across from Google:
| In Google | In the platform |
|---|---|
| First and last name | First and last name |
| Primary email address | Email address |
| Department from the organisation details | Department |
| Country code from the address | Country |
| Language | Language |
| Secondary email address | Alternative email address |
| Suspended | Active or inactive |
A suspended account in Google therefore arrives in the platform as inactive.
Good to know
Licence seats. If the organisation is at its maximum, the creation of new users stops. Setting someone to inactive does not free up a seat, because inactive users still count. If you want to free up a seat, a user has to be detached from the organisation.
Manager and profile photo are not yet copied over from Google. With Entra they are. Nothing is broken if the customer has filled in those details; they just don't come across.
Fetching manually is not possible yet. The Import from Azure screen only works with Entra schedules. With Google you therefore wait for the next scheduled run, or you temporarily set it to run more often.
The clean-up can switch itself off. If a great many groups are nested inside each other, the platform fetches a limited number and considers the member list incomplete. It then skips setting people to inactive, because otherwise staff who are simply still employed would be switched off. The schedule's log says why.
If something goes wrong
Each run adds a line to the schedule's log, also when it goes wrong. It contains Google's own message. These are the most common:
“unauthorized_client”
Domain-wide delegation is not set up, or the two scopes are not listed exactly. Have the customer's Google administrator check whether the right service account has been added and whether both addresses match to the letter.
“Not a valid email or user ID”
The administrator address you entered does not exist in the customer's Google domain, or is misspelled. Check the administrator field in the connection.
“Google returned no member list for group …”
The group address you entered does not exist, or the administrator on whose behalf we work is not allowed to see that group. Check the address in the schedule. It is the group's email address, not its name.
“No Google group set for this schedule”
The group field was left empty. Fill it in in the schedule.
“This connection is missing a key or an administrator”
The connection is incomplete. Complete it, or create it again with the key file at hand.