Docs

Integrations / Identity / Google Workspace

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:

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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:

  • openid
  • https://www.googleapis.com/auth/userinfo.email
  • 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.orgunit.readonly
  • https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly
  • https://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.

ToolScope
Create Google Workspace Userhttps://www.googleapis.com/auth/admin.directory.user
Manage Google Workspace User Aliashttps://www.googleapis.com/auth/admin.directory.user.alias
Reset Google Workspace User Passwordhttps://www.googleapis.com/auth/admin.directory.user
Reset Google Workspace 2-Step Verificationhttps://www.googleapis.com/auth/admin.directory.user.security
Set Google Workspace User Suspensionhttps://www.googleapis.com/auth/admin.directory.user
Sign Out Google Workspace Userhttps://www.googleapis.com/auth/admin.directory.user.security
Transfer Google Workspace User Datahttps://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.
  1. 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.

  2. 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.

  3. Authorize

    Click Authorize. Sign in to Google with the same Workspace admin account and approve all the listed scopes.

  4. 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 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