Google Workspace

Connect a client's Google Workspace with a service account, so the agent can look into users, sign-ins, groups, licences and devices.

In the appPlatformSettingsMicrosoft 365 and GoogleGoogle Workspace

Connect a client's Google Workspace so the agent can see what really happened to a user: whether their account is suspended, their recent sign-ins, their groups, licences and devices.

You connect it with a service account in Google Cloud, allowed in the client's Admin console to act as one of their admins (domain-wide delegation). What the agent can read depends on the scopes you allow for it there, and on what that admin could do.

The agent reads what the scopes allow. If the fix is a change in Google Workspace, such as unsuspending a user or creating a new one, it proposes it, and nothing happens until a person approves it. See Changes below.

Set it up step by step

On Settings › Microsoft 365 and Google, in the Service account row, Set it up step by step walks through every click, lets you choose what the agent may see and change, and writes the scopes line for you.

Make the service account#

1
In the Google Cloud console (console.cloud.google.com), sign in as a super admin of the Workspace: the account on its own domain, not a personal Gmail. Pick or create a project. Under APIs & Services › Library, enable the Admin SDK API. Enable any others you want the agent to use, such as the Enterprise License Manager API or the Cloud Identity API.
2
Go to IAM & Admin › Service accounts and click Create service account. Give it a name, such as Cerberius Agents. It needs no roles in the project.
3
Open it, go to Keys › Add key › Create new key, and choose JSON. A key file downloads. Keep it safe: it is a password. If Google says Service account key creation is disabled, see the box below.
4
On the service account's Details tab, copy its Unique ID (its client ID, a long number).
5
In the Google Admin console, open the domain-wide delegation page straight from its address, admin.google.com/ac/owl/domainwidedelegation (its place in the menus differs between accounts), and click Add new. Paste the client ID. Then paste the scopes you want, one per box: a new empty box appears after each. See Which scopes below.
6
Choose the admin the service account will act as. The agent sees what that admin could, within the scopes.
7
Here, go to Settings › Microsoft 365 and Google. Click Connect an account (or Connect another, if Microsoft 365 is already there), and choose Google Workspace.
8
Under Service account, click Add service account key… and paste the whole key file. Under What it may do, enter the admin's email in Acts as and the same scopes in Scopes. Click Save, then Check connection.

Letting it do more later

Do it in this order. On the domain-wide delegation page, click the service account's row, then Edit. Keep the scopes there, paste each new one into the empty box at the bottom, and click Authorise. Then add the same scopes here under Scopes, click Save and Check connection. Google first: if this page asks for a scope Google hasn't allowed, Google refuses them all and the agent can't reach Google Workspace.

Service account key creation is disabled

New Google accounts block service account keys. Lift it for this project only:

In the project picker, open the All tab and click your organisation (the domain, with a building icon). Go to IAM & Admin › IAM › Grant access: your email, role Organisation Policy Administrator, Save.
Choose the project again. Go to IAM & Admin › Organisation policies, search disableServiceAccountKeyCreation, and open the one marked Active.
Manage policy › Override parent's policy › Add a rule, enforcement Off, Set policy.
Wait about 5 minutes, then make the key.

If Check connection says an API "has not been used in project … or it is disabled", open the link it gives, click Enable, wait a few minutes and check again.

Which scopes#

Your choice: any Google scope works, and the agent can use any Google API the scopes allow. The tables are the common ones. The scopes here must be exactly the ones you allowed in the Admin console. Google refuses the connection otherwise, and Check connection says so. The short form works here too, such as admin.directory.user.

To read:

Scope	What the agent can then see
`https://www.googleapis.com/auth/admin.directory.user.readonly`	Users: whether the account is suspended, its details, its last sign-in.
`https://www.googleapis.com/auth/admin.directory.group.readonly`	Groups and their members.
`https://www.googleapis.com/auth/admin.reports.audit.readonly`	Sign-in and admin activity, such as failed or suspicious sign-ins.
`https://www.googleapis.com/auth/admin.directory.device.mobile.readonly`	Phones and tablets.
`https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly`	Chromebooks.
`https://www.googleapis.com/auth/apps.licensing`	Licences (Google has no read-only scope for these).

To let the agent propose changes, add the matching scopes without .readonly, for example:

Scope	Changes it allows
`https://www.googleapis.com/auth/admin.directory.user`	Create a user, unsuspend one, sign them out everywhere, change their details.
`https://www.googleapis.com/auth/admin.directory.group`	Make groups and change them.
`https://www.googleapis.com/auth/apps.licensing`	Assign or remove licences.
`https://www.googleapis.com/auth/admin.directory.group.member`	Add someone to a group, or remove them.

Give only what your team is happy for the agent to read and propose.

The settings#

Setting	What it is
Service account (the key)	The service account's JSON key file. Once saved, it is never shown again: the row shows the service account's email and client ID instead. Replace or Remove it there.
Acts as	The email of the admin the service account acts as.
Scopes	One per line. The short form works too, such as `admin.directory.user.readonly`.
Save	Saves Acts as and Scopes. The key is saved on its own, when you add it.
Check connection	Shows once the key, the admin and the scopes are saved. It signs in and lists who it acts as and its scopes, and whether it can read users.

How the agent uses it#

At the start of each investigation, Cerberius Agents signs in as the service account, acting as the admin, and gives the agent a pass that lasts about an hour. The agent never sees the key.
The agent can only read. It can't send anything that changes Google Workspace.
It acts as the admin, so it can't open another user's Gmail settings, such as their forwarding or filters.
What it reads can appear in its findings as evidence. Secrets and tokens are removed first.

Changes#

To let the agent propose Google Workspace changes, switch on Google Workspace changes under Settings › Approved changes. See Allowing changes.

The agent then puts the exact requests in a change for an approver. When it's approved:

Cerberius Agents reads everything the change edits or removes. If one can't be read, for example because of a wrong user, nothing runs.
It sends the requests in order, and stops at the first one Google refuses. The ticket says what was done.
The agent checks the result and drafts the reply to the requester.

Some changes are never made, even if the scopes allow them: admin roles and privileges, making someone an admin, and anything that hands out credentials or changes who manages the Google Cloud project. Domains can change, such as adding a domain or an alias, if the scopes allow it.

New accounts: the agent never writes a password. Cerberius Agents gives the new account a long random first password, which must be changed at the first sign-in, and nobody sees it. Reset it in the Admin console to give the person their first password.

With your own runner#

When the agent runs on your own runner, the service account's key is kept by you, like your other keys. Acts as and Scopes stay in these settings.

Save Acts as and Scopes first. Then choose how the JSON key is kept: Scrambled for your runner (type it: your browser checks it, then scrambles it so only your runner can unscramble it; we store only the scrambled copy, so the row no longer shows the service account's email) or In your store (named google-workspace-key). See Two ways to keep your keys.
Your runner signs in for each investigation and gives the agent the same hour-long pass. The key never leaves your runner: it signs the request for the pass, which goes only to Google's sign-in service, and the pass goes only to Google's APIs.
Check connection is made by your runner.
Approved changes are made by your runner, with the same checks as above, once its own rules allow them: add a google_workspace section (see Microsoft 365, Google and domains).
It needs version 0.8.0 or later.