# Google Gemini Enterprise Integration

Connect your Google Cloud Platform project and Google Workspace to Capsule Security for complete visibility into your organization's Gemini Enterprise AI agents, conversations, and usage.

![Google Gemini Enterprise](/assets/google-gemini-enterprise.24df4dcf40fc8bec27dca791ef4e6e4ae5c0efb5cb456965c780c6bc1b9176e9.9c1bb791.png)

## Overview

This integration connects to your Google Cloud Platform project and Google Workspace to provide complete visibility into your organization's Gemini Enterprise AI agents, user conversations, and usage patterns. The integration automatically discovers and syncs shared organizational agents, personal user agents, conversation sessions, and associated data sources.

## Prerequisites

Before you begin, ensure you have:

- **Google Cloud Platform project** with Gemini Enterprise (Discovery Engine) configured
- **Google Workspace** domain associated with the project
- **Editor** or **Owner** role on the GCP project
  - Required to enable APIs during installation
  - Required to grant IAM permissions to Capsule's service account
- **Google Workspace Admin** access
  - Required to configure domain-wide delegation
  - Must be Super Admin or have delegated admin permissions for API access


## Installation Overview

The installation process consists of two main steps:

1. **Configure Domain-Wide Delegation** (Google Workspace Admin Console) — This can be done in advance as a prerequisite
2. **Connect via Capsule Portal** (OAuth authorization) — Automated setup that enables APIs and grants permissions


## Step 1: Configure Domain-Wide Delegation

Domain-wide delegation allows Capsule's service account to access Google Workspace data on behalf of users in your organization. This step can be completed in advance before installing the integration in Capsule.

### Why is this required?

Capsule needs to:

- List users in your Google Workspace to discover who has Gemini Enterprise access
- Fetch session data for all users to provide complete visibility
- Access Discovery Engine resources across your organization


### Steps

1. Go to [Google Workspace Admin Console](https://admin.google.com/ac/owl/domainwidedelegation)
2. You must be signed in as a **Super Admin** or have **delegated admin privileges** for API access
3. Click **Add new** in the Domain-wide delegation section
4. Complete the configuration form:
**Client ID**: Copy this from the Capsule portal installation card (Step 1 shows the Client ID with a copy button)
**OAuth Scopes** (copy and paste exactly):

```
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/cloud-platform
```
**Scope descriptions:**
  - `admin.directory.user.readonly` — Read-only access to list Google Workspace users
  - `cloud-platform` — Access to Google Cloud Platform resources (Discovery Engine sessions)
5. Click **Authorize**
6. **Wait 10-15 minutes** for the changes to propagate across Google's systems


### Verify Configuration

After waiting for propagation, verify the configuration:

1. In Google Workspace Admin Console, go back to [Domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation)
2. Find the entry for Capsule's service account (search for the Client ID)
3. Verify the OAuth scopes are exactly:

```
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/cloud-platform
```
4. Ensure the status shows as **Authorized**


## Step 2: Connect Integration via Capsule Portal

After configuring domain-wide delegation, connect the integration through the Capsule portal.

### What Gets Configured Automatically

During the OAuth connection flow, Capsule will automatically:

✅ **Enable required Google Cloud APIs** in your project:

- Discovery Engine API (`discoveryengine.googleapis.com`)
- Admin SDK API (`admin.googleapis.com`)
- Compute Engine API (`compute.googleapis.com`)


✅ **Grant IAM permissions** to Capsule's service account:

- `Discovery Engine Viewer` role (`roles/discoveryengine.viewer`)
- `Compute Viewer` role (`roles/compute.viewer`)


✅ **Validate configuration**:

- Verify project access
- Confirm Google Workspace domain matches your account


### Steps

1. Go to **Integrations** in the Capsule portal
2. Find **Google Gemini Enterprise** and click **Install**
3. Complete the installation form:
  - **Google Workspace Domain**: Enter your organization's workspace domain (e.g., `example.com`)
    - This should match the domain of Google Workspace accounts that use Gemini Enterprise
  - **Project ID**: Enter your Google Cloud project ID where Gemini Enterprise is configured
    - Find this in [Google Cloud Console](https://console.cloud.google.com) under Project Info
4. Click **Connect** to begin OAuth authorization
5. **Sign in with Google** using an account that has:
  - Email address from the workspace domain you entered
  - Editor or Owner role on the GCP project
6. **Review and authorize** the requested permissions:
  - View and manage data across Google Cloud services
  - See your primary Google Account email address
  - See your personal info, including any personal info you've made publicly available
7. After authorization, Capsule will automatically:
  - Enable Discovery Engine, Admin SDK, and Compute Engine APIs
  - Grant `Discovery Engine Viewer` and `Compute Viewer` permissions to Capsule's service account
  - Validate your project and workspace configuration
8. If you haven't completed Step 1 yet, use the Client ID shown in the installation card above to configure domain-wide delegation in Google Workspace Admin Console
9. The integration status should now show as **Connected**


## Step 3: Verify Data Sync

After completing the integration setup, verify that data is syncing correctly.

### Steps

1. Capsule will automatically begin the first data sync
2. **Initial sync will take some time** depending on:
  - Number of regions where engines are deployed
  - Number of users in your workspace
  - Volume of historical session data
3. Once complete, you'll see:
  - Agents listed in the **Inventory** section
  - Sessions visible in the **Observability** section
  - User activity in the **Users** view


## Troubleshooting

### Installation Fails with "invalid_grant"

**Cause**: OAuth authorization code was used multiple times or expired

**Solution**:

1. Click **Try Again** in the error message
2. Complete the OAuth flow again without delays
3. Don't refresh or navigate away during authorization


### Installation Fails with "Access denied to project"

**Cause**: Your Google account doesn't have sufficient permissions on the GCP project

**Solution**:

1. Verify you have **Editor** or **Owner** role on the project
2. Check in [Google Cloud Console](https://console.cloud.google.com) → IAM & Admin → IAM
3. Ask a project admin to grant you the necessary role


### Installation Fails with "Domain mismatch"

**Cause**: Your Google account's email domain doesn't match the workspace domain you entered

**Solution**:

1. Verify you're using a Google account from the correct workspace domain
2. The account email (e.g., `user@example.com`) must match the workspace domain (e.g., `example.com`)
3. Don't use personal Gmail accounts or accounts from other organizations


### No Data Appears After Installation

**Possible causes**:

1. **Domain-wide delegation not configured** (most common)
  - Verify Step 1 was completed correctly
  - Check the Client ID matches exactly
  - Ensure OAuth scopes are correct
  - Wait 10-15 minutes for propagation
2. **No Gemini Enterprise usage in the project**
  - Verify engines exist in your GCP project
  - Check [Discovery Engine Console](https://console.cloud.google.com/gen-app-builder)
  - Ensure users have created sessions
3. **Service account permission issue**
  - Verify `Discovery Engine Viewer` and `Compute Viewer` roles were granted during installation
  - Check [IAM page](https://console.cloud.google.com/iam-admin/iam) for the Capsule service account
  - Re-run installation if permissions are missing


### Sessions Not Syncing

**Cause**: Domain-wide delegation configuration issue

**Solution**:

1. Go to [Domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation)
2. Find Capsule's service account entry
3. Verify OAuth scopes are **exactly**:

```
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/cloud-platform
```
4. If scopes are incorrect, click **Edit** and update them
5. Click **Authorize** again
6. Wait 10-15 minutes for propagation
7. Manually trigger a sync from Capsule integration settings


## Security & Privacy

### Data Access

Capsule accesses only the data necessary for compliance monitoring:

- **Read-only access**: Cannot modify or delete agents, sessions, or configurations
- **Scoped to project**: Only accesses the specific GCP project you configured
- **Workspace users only**: Only lists users from your Google Workspace domain
- **Session data**: Conversation logs for audit and compliance purposes


### Authentication

- **OAuth 2.0**: Industry-standard authorization protocol
- **Service account**: Dedicated account for Capsule's integration (no shared credentials)
- **Domain-wide delegation**: Explicit authorization by Workspace admins
- **No stored passwords**: Uses token-based authentication


## Support

Need help with the integration?

- **Documentation**: [docs.capsule.security](https://docs.capsule.security)
- **Email Support**: support@capsule.security


When contacting support, please include:

- Your Google Cloud Project ID
- Screenshots of any error messages
- Timestamp when the issue occurred