Google Workspace Tools Connector
Connect Google Workspace so script tools and built-in Google tools can call the Admin SDK, and reconnect when a tool needs a new OAuth scope
The Google Workspace tools connector gives script tools access to Google APIs such as the Admin SDK. These built-in tools also use it:
- Create Google Workspace User
- Manage Google Workspace User Alias
- Reset Google Workspace User Password
- Reset Google Workspace 2-Step Verification
- Set Google Workspace User Suspension
- Sign Out Google Workspace User
- Transfer Google Workspace User Data
The connector runs on an OAuth client that your organization owns in Google Cloud. A Workspace admin gives consent once, and every tool that calls Google through the connector uses that grant.
Prerequisites
- A Google Cloud project where you can create OAuth clients
- A Google Workspace account with an admin role. A delegated admin with directory access is enough.
- Access to the credential vault in Risotto
Set up the connector
Start the setup in Risotto
In the Risotto dashboard, go to Settings > Integrations and click the Google Workspace card. On the Tools app card ("Runs script tools on an OAuth client your organization owns."), click Set up. The button reads Connect when an OAuth client is already stored.
The Connect Google dialog opens. Its Instructions pane shows the redirect URI for your organization. Click the copy button beside it to copy it for the next step. On a narrow screen, click Instructions to show the steps.
Enable the Admin SDK API
In the Google Cloud console, open the project that will own the OAuth client. Go to APIs & Services > Library, find Admin SDK API, and click Enable.
Create an OAuth client
In the same project, create an OAuth client of type Web application. Under Authorized redirect URIs, paste the redirect URI from Risotto.
Authorized JavaScript origins are optional. If you add one, use the origin of your Risotto dashboard.
Store the client ID and secret in the vault
Back in the Connect Google dialog, use the Client ID and Client secret fields to pick a vault credential for each value, or choose Add a vault credential to create one. Both fields accept vault credentials only.
The client ID must end with
.apps.googleusercontent.com. Risotto refuses any other value.Save and give consent
Click Save and connect. Risotto sends you to Google. Sign in with your Workspace admin account and approve the scopes.
Risotto tests the connection before it saves the grant. When the test passes, the Tools app card shows the admin account and the connection date, with the Workspace domain and Approved scopes rows.
Default scopes
A new connection is read only. Every consent asks for these scopes:
openidhttps://www.googleapis.com/auth/userinfo.emailhttps://www.googleapis.com/auth/admin.directory.user.readonlyhttps://www.googleapis.com/auth/admin.directory.group.readonlyhttps://www.googleapis.com/auth/admin.directory.orgunit.readonlyhttps://www.googleapis.com/auth/admin.directory.device.chromeos.readonlyhttps://www.googleapis.com/auth/admin.directory.domain.readonly
Write scopes are not included by default. Risotto asks for a write scope only after a published script tool declares it, or after you add a built-in Google tool that needs it.
How script tools get scopes
A script tool declares the scopes it needs on each Google call. As with any http.* call, the Google host must be in the domains export:
export const domains = {
"admin.googleapis.com": "read"
};
const response = await http.get(
"https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer",
{
auth: {
type: "google",
scopes: ["https://www.googleapis.com/auth/admin.directory.user.readonly"]
}
}
);
Risotto asks Google for the default scopes plus every scope that your published script tools declare. Drafts do not count until you publish them. Disabled tools still count, so enabling or disabling a tool does not force a new consent.
Built-in Google tools
The consent also includes the scope of each built-in Google tool that your organization added on the Tools page. A disabled tool still counts. A deleted tool does not.
| Tool | Scope |
|---|---|
| Create Google Workspace User | https://www.googleapis.com/auth/admin.directory.user |
| Manage Google Workspace User Alias | https://www.googleapis.com/auth/admin.directory.user.alias |
| Reset Google Workspace User Password | https://www.googleapis.com/auth/admin.directory.user |
| Reset Google Workspace 2-Step Verification | https://www.googleapis.com/auth/admin.directory.user.security |
| Set Google Workspace User Suspension | https://www.googleapis.com/auth/admin.directory.user |
| Sign Out Google Workspace User | https://www.googleapis.com/auth/admin.directory.user.security |
| Transfer Google Workspace User Data | https://www.googleapis.com/auth/admin.datatransfer |
When you add one of these tools to a connection that does not have its scope, reconnect and approve the scope. Until then, the tool shows Needs reauth on the Tools page.
Re-authorize for a new scope
When you publish a script tool or add a built-in Google tool that needs a scope the current grant does not include, the grant does not update by itself. An admin must reconnect and approve the new scope. Until then, calls that need that scope fail.
You see the missing scope in two places:
- In the script editor: when you save the tool, a warning says the Google connection does not include the scope. The warning does not block the save or the publish. Publish the tool first, because the published tools decide what the next consent asks for.
- On the Google Workspace integration page: the Tools app card shows "Published script tools need permissions your Google grant does not include yet: ..." with the names of the missing scopes, and its status reads Error instead of Connected. The card shows the same text when the missing scope is for a built-in Google tool.
Publish the script tool
Publish the script tool that needs the new scope. Risotto adds its scopes to the next consent request. For a built-in Google tool, enable the tool on the Tools page instead.
Click Reconnect
Go to Settings > Integrations > Google Workspace. On the Tools app card, click Error, then Reconnect.... The Reconnect Google dialog opens and lists the scopes to approve.
Authorize
Click Authorize. Sign in to Google with the same Workspace admin account and approve all the listed scopes.
Confirm the new scopes
After you approve, Risotto opens the Google settings page and shows Tools app connected successfully. On the Tools app card, the missing-scopes warning is gone. The Approved scopes row shows the new count.
You do not need to republish the script tool after you reconnect. The next run uses the new grant.
The current connection continues to work while you reconnect. Risotto replaces the grant only after the new consent passes the connection test. If you cancel the consent or it fails, nothing changes.
Reconnect after a failed connection
On a connected Tools app card, Reconnect... is always in the status menu: Connected, or Error while the connection needs a reconnect. You can also use it when:
- Google revoked the grant or it expired
- Risotto shows a warning on the card that the connection needs to be reconnected
When the connection stops working, Risotto also sends an admin notification. Until you reconnect, script tools and built-in tools that call Google cannot run, and the requests that need them go to a human. If no scopes are missing, Reconnect sends you directly to Google.
Manage the OAuth client
- Rotate the client secret: update the value of the vault credential. You do not need a new consent. The next token request uses the new secret.
- Change the client: click Connected on the Tools app card, choose Edit client..., and in the Edit the Google OAuth client dialog select a different vault credential for the client ID, then click Save. A new client ID removes the old grant, so Risotto sends you to Google to give consent again.
- Change the client ID in the vault credential: do not edit the value of the client ID credential to a different OAuth client. A grant works only with the client that issued it, so Risotto marks the connection as needing reconnection. To fix it, put the original client ID back in the vault credential, or click Reconnect to give consent on the new client.
- Disconnect: click Connected on the Tools app card, then Disconnect.... Risotto revokes the Google refresh token and clears the stored OAuth client. The vault credentials stay in the vault. Script tools and built-in tools that call Google fail until you connect again.
Troubleshooting
The account that gave consent is not a Workspace admin
Give consent again with an account that has an admin role. A delegated admin with directory access is enough. Personal Google accounts do not work: the account must be in your Workspace domain.
The Admin SDK API is turned off
Enable the Admin SDK API on the Google Cloud project that owns the OAuth client, then connect again.
Google did not accept the OAuth client
Check that the two vault credentials hold the client ID and the secret of the same OAuth client.
Google did not complete the sign-in
Check that the redirect URI on the OAuth client matches the URI in the Connect Google dialog exactly, then connect again.
Google refused the credential
The grant was revoked or expired, or the client secret no longer matches the client in Google. Update the secret in the vault if necessary, then click Reconnect.
The Google OAuth client ID in the vault is not the one this connection was given to
Someone changed the value of the client ID credential in the vault. Put the original client ID back in the vault credential, or click Reconnect to give consent on the new client.
Google did not return a refresh token
Start the connection again from the Tools app card on the Google Workspace integration page.
Something wrong or missing? Report an issue · View as Markdown