# 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](https://www.tryrisotto.com/docs/integrations/tools/script-tools) access to Google APIs such as the Admin SDK. These built-in tools also use it:

- [Create Google Workspace User](https://www.tryrisotto.com/docs/integrations/tools/google/create_user)
- [Manage Google Workspace User Alias](https://www.tryrisotto.com/docs/integrations/tools/google/manage_user_alias)
- [Reset Google Workspace User Password](https://www.tryrisotto.com/docs/integrations/tools/google/reset_password)
- [Reset Google Workspace 2-Step Verification](https://www.tryrisotto.com/docs/integrations/tools/google/reset_two_step_verification)
- [Set Google Workspace User Suspension](https://www.tryrisotto.com/docs/integrations/tools/google/set_user_suspension)
- [Sign Out Google Workspace User](https://www.tryrisotto.com/docs/integrations/tools/google/sign_out_user)
- [Transfer Google Workspace User Data](https://www.tryrisotto.com/docs/integrations/tools/google/transfer_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.

> **Note:** This connector is the **Tools app** card on **Settings > Integrations >
> Google Workspace**. It is separate from the **Admin API** card on the same
> page, which is the Google Workspace identity connection. It is for script tools and the built-in tools
> in the list above. The other
> Google tools do not use it: [Create Google
> Group](https://www.tryrisotto.com/docs/integrations/tools/google/create_group) and [Move User to
> OU](https://www.tryrisotto.com/docs/integrations/tools/google/move_user_to_ou) use service account
> credentials, and [Manage Google Group
> Members](https://www.tryrisotto.com/docs/integrations/tools/google/manage_group_members) uses the **Admin
> API** card.

## 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](https://www.tryrisotto.com/docs/dashboard/settings/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.

   *Product example: Google Workspace's integration page, with the Admin API card connected and Set up on the Tools app card.*

   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](https://console.cloud.google.com/), 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.

   > **Warning:** The redirect URI must match exactly. If it does not match, Google refuses
   > the consent.

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. **Save and give consent**

   Click **Save and connect**. Risotto sends you to Google. Sign in with your Workspace admin account and approve the scopes.

   *Product example: The Connect Google dialog with the redirect URI to copy, both vault credentials picked, and Save and connect.*

   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:

```typescript
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.

> **Info:** Google auth only goes to `googleapis.com` and its subdomains. A script that
> sends Google auth to a different host does not save.

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

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.

   *Product example: The Google Tools app card warning that a scope is missing, with its status menu open on Reconnect....*

3. **Authorize**

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

   > **Warning:** If you clear a scope on the Google consent screen, Google does not grant
   > it. The card continues to show the scope as missing.

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

Source: https://www.tryrisotto.com/docs/integrations/google-workspace-tools
