# Manage Google Group Members

Add or remove users from Google Groups with automatic role assignment

Add or remove users from Google Groups with support for multiple roles. The tool uses your organization's Google Workspace OAuth credentials for simple, secure authentication.

## Setup Requirements

This tool uses OAuth authentication (not service accounts), making setup significantly simpler than traditional Google Workspace tools. Your organization just needs to connect Google Workspace once in the Risotto dashboard.

### Quick Reference

**Authentication Method**: OAuth (no service account required)

**Required OAuth Scopes**:

```
https://www.googleapis.com/auth/admin.directory.group
```

**Supported Roles**:

- MEMBER (standard group member)
- OWNER (full management permissions)
- MANAGER (elevated permissions)

## Step-by-Step Setup

### Step 1: Connect Google Workspace (If Not Already Connected)

If your organization hasn't already connected Google Workspace to Risotto:

1. **Navigate to Identity**

   Log into the [Risotto Dashboard](https://dashboard.tryrisotto.com) and navigate to **Settings > Integrations > Google Workspace**

2. **Connect Google Workspace**

   Find the **Google Workspace** card and click **Connect**

3. **Authorize Risotto**

   Follow the OAuth flow to authorize Risotto. Make sure to grant the requested permissions:

   - `https://www.googleapis.com/auth/admin.directory.user.readonly`
   - `https://www.googleapis.com/auth/admin.directory.group`

> **Note:** The Google Workspace user who authorizes Risotto must have **Super Admin** or
> **Groups Admin** privileges to manage group membership.

### Step 2: Enable the Tool

1. **Navigate to Tools**

   In the Risotto Dashboard, select **Tools** in the sidebar

2. **Open the Google group**

   In the **Tool groups** list, select **Google**

3. **Enable the Tool**

   Find **Manage Google Group Members** and click **Enable**

4. **Configure the Tool**

   Optionally, open the tool and click **Edit**. Change the **Name** or
   **Description**, or set **Requires Approval**.

5. **Save the Tool**

   Click **Save**

The tool will automatically use your organization's Google Workspace OAuth credentials and be available for selection when creating or editing a Runbook.

## Features

### Idempotent Operations

The tool is designed to be idempotent, meaning you can safely run the same operation multiple times:

- **Adding an existing user**: Returns success without error
- **Removing a non-existent user**: Returns success without error

This makes the tool safe to use in automated workflows and runbooks.

### Supported Roles

When adding users to groups, the agent can specify one of three roles:

- **MEMBER**: Standard group member with basic access
- **OWNER**: Full group management permissions
- **MANAGER**: Elevated permissions between member and owner

### Automatic Token Refresh

Risotto automatically manages OAuth token refresh:

- When the access token expires, Risotto uses the refresh token to get a new access token
- This happens transparently in the background
- You don't need to manually reconnect unless the refresh token itself expires (typically after 200 days of inactivity)

## Limitations

- The tool acts with the permissions of the Google Workspace admin who connected the **Admin API**. It can change any group that this admin can manage.
- The tool does not check whether a group is locked in Google Admin.
- The tool does not check who owns a group, so it does not limit changes to groups that the requestor owns or manages.

To limit which groups the tool can change, attach an [approval policy](https://www.tryrisotto.com/docs/dashboard/settings/approval-policies#attaching-a-policy-to-a-tool) to the tool, or use a [script tool](https://www.tryrisotto.com/docs/integrations/tools/script-tools) that checks the group before it changes it.

## Troubleshooting

### Common Issues

#### No Google Workspace OAuth credentials found

**Cause**: Your organization hasn't connected Google Workspace to Risotto

**Solution**:

1. Navigate to **Settings > Integrations > Google Workspace** in the dashboard
2. On the **Admin API** card, click **Connect**
3. Grant all requested permissions

#### 403 Forbidden Error

**Cause**: The Google Workspace user who authorized Risotto doesn't have sufficient permissions

**Solution**:

- The authorizing user must have one of these roles:
- **Super Admin** (recommended)
- **Groups Admin** (minimum required)
- Re-authorize with an admin account that has the necessary permissions

#### Token Expired

**Cause**: OAuth token has expired

**Solution**:

- Risotto automatically refreshes OAuth tokens
- Try the operation again (it should work after auto-refresh)
- If it persists, reconnect Google Workspace in **Settings > Integrations > Google Workspace**

#### User Already in Group / User Not in Group

**Note**: These are not errors! The tool is designed to be idempotent: -
Adding a user already in the group will return success - Removing a user not
in the group will return success

### Permission Requirements

The Google Workspace user who authorizes Risotto must have one of these admin roles:

- **Super Admin** (recommended) - Full access to all Google Workspace features
- **Groups Admin** (minimum required) - Can manage groups and group membership

## OAuth vs. Service Account Authentication

This tool uses OAuth instead of service account authentication, which provides several advantages:

| Feature          | OAuth (This Tool)           | Service Account                                 |
| ---------------- | --------------------------- | ----------------------------------------------- |
| Setup Complexity | Simple one-click            | Complex multi-step setup                        |
| User Experience  | Authorize once in dashboard | Download JSON, configure domain-wide delegation |
| Token Management | Automatic refresh           | Manual key rotation required                    |
| Security         | User-scoped permissions     | Broad service account permissions               |
| Maintenance      | Zero maintenance            | Requires periodic key rotation                  |

> **Tip:** If you have other Google Workspace tools that use service accounts, you can
> migrate them to OAuth for simpler management. Contact <support@tryrisotto.com>
> for migration assistance.

## Security & Privacy

- **OAuth Tokens**: Stored encrypted in the Risotto database
- **Automatic Refresh**: Tokens are automatically refreshed before expiration
- **Scope Limitation**: Risotto only requests the minimum required permissions
- **Audit Logs**: All group membership changes are logged in Google Workspace audit logs

## Additional Resources

- [Google Workspace Admin Help Center](https://support.google.com/a/)
- [Google Groups API Documentation](https://developers.google.com/admin-sdk/directory/reference/rest/v1/members)
- [Risotto Documentation](https://www.tryrisotto.com/docs)

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