# Google Workspace Radiant connects to Google Workspace to ingest email activity, authentication activity, and user and group IAM information. The connector uses a Google Cloud service account with domain-wide delegation, and reads Workspace activity logs from BigQuery. Configuration is a one-time setup performed in Google Cloud, Google Admin, and Radiant Security. If you do not have Google BigQuery, use [Google Workspace IAM only](/radiant-connectors/data-connectors/google-workspace-iam-only.md) to enable just the IAM and email data feeds. At the end of this configuration, you provide Radiant Security with the following values: * **BigQuery Project ID** * **BigQuery Dataset Name** * **Delegate User Email** * **Service account JSON key file** ### Prerequisites The Google Workspace account must have one of the following plans for email activity log collection: * [ ] Enterprise * [ ] Education Standard * [ ] Education Plus {% hint style="info" %} To verify your current license plan, sign in to an account with admin access and visit [`https://admin.google.com/ac/billing/subscriptions`](https://admin.google.com/ac/billing/subscriptions). {% endhint %} The user performing this configuration must hold the following permissions and roles: * [ ] Role: `Super Administrator` (Google Workspace) * [ ] Role: `roles/resourcemanager.projectIamAdmin` (Google Cloud) * [ ] Permission: `resourcemanager.projects.create` (Google Cloud) * [ ] Administrator role in Radiant Security ### Create a project in Google Cloud 1. Sign in to the [Google Cloud console](https://console.cloud.google.com/). 2. From the **Select organization** drop-down at the top of the page, click **New project**. 3. In the **Project name** field, enter a descriptive name. Radiant recommends `{your organization's name}-workspace-logs`. For details on project naming and identifiers, see Google's [Creating and managing projects](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects). 4. The Google Cloud console generates a **Project ID** from the project name. To customize it, click **Edit** next to the Project ID. The Project ID is permanent after the project is created. 5. Copy the **Project ID** for later use. 6. Click **Create**. 7. Select the newly created project from the drop-down at the top of the page. 8. From the navigation menu, select **APIs & Services** > **Library.**
9. In the API Library, search for and enable the following APIs, one at a time: * Admin SDK API * Cloud Identity * Gmail API * Google Calendar API * Google Workspace Alert Center API
10. Open the OAuth consent screen for your project. From the navigation menu, select **APIs & Services** > **OAuth consent screen**. With the project selected, Google routes you to the **Google Auth Platform**. 11. Configure the consent screen. The path depends on whether the Google Auth Platform is already configured for this project: **If you see the message "Google Auth platform not configured yet":** click **Get Started** and complete the wizard: 1. Under **App Information**, enter the following: * **App name**: `radiant-security-workspace-logs` * **User support email**: select the appropriate user. 2. Click **Next**. 3. Under **Audience**, select **Internal** as the user type. 4. Click **Next**. 5. Under **Contact Information**, enter an email address where Google can notify you about changes to your project. 6. Click **Next**. 7. Under **Finish**, review the Google API Services User Data Policy, select **I agree to the Google API Services: User Data Policy**, and click **Continue**. 8. Click **Create**. **If the Google Auth Platform is already configured:** verify the existing configuration in the left navigation: * **Branding**: confirm **App name** is `radiant-security-workspace-logs` and that **User support email** and **Developer contact information** are populated. * **Audience**: confirm **User type** is **Internal**. If it shows **External**, contact your Google Workspace administrator before continuing. ### Create a service account A dedicated service account in Google Cloud ingests the data. The service account holds the permissions required to read the data fed into Radiant Security. 1. In the Google Cloud console, navigate to **IAM & Admin** > **Service Accounts**.
2. Click **+ Create service account** and enter the **Service account name**: `radiant-security-connector`. 3. Optional: Enter a description of the service account. 4. Click **Create and Continue**. 5. Under **Grant this service account access to project**, assign the following roles. Click **+ Add another role** to add the second role: * **BigQuery Data Viewer** * **BigQuery Read Session User** 6. Click **Done**. 7. Click the `radiant-security-connector` service account to open it. 8. On the **Service Accounts** page, click the email address of the `radiant-security-connector` service account. 9. Click the **Keys** tab. 10. Click **Add key** and select **Create new key**. 11. Select **JSON** as the **Key type** and click **Create**. The JSON key file downloads automatically. {% hint style="warning" %} The downloaded JSON key file is the only copy. Store it securely. You upload this file to Radiant Security at the end of this guide. For guidance, see Google's [Best practices for managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys). {% endhint %} ### Grant access to the service account To call APIs in Google Workspace, the service account must be granted domain-wide delegation of authority in the Google Workspace Admin console by a super administrator. For background, see Google's [Delegating domain-wide authority to a service account](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority). 1. On the **Service Accounts** page in Google Cloud, click the `radiant-security-connector` service account. 2. On the **Details** tab, expand **Advanced settings** and copy the **Client ID**. 3. Click **View Google Workspace Admin Console**. 4. Navigate to **Security** > **Access and data control** > **API controls**. 5. Click **Manage Domain Wide Controls**. 6. Click **Add new** and paste the Client ID you copied in step 2. 7. In the **OAuth Scopes** field, copy and paste the following permissions: ```bash https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.reports.usage.readonly, https://www.googleapis.com/auth/gmail.settings.basic, https://www.googleapis.com/auth/apps.alerts, https://www.googleapis.com/auth/bigquery, https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.modify, https://mail.google.com, https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/calendar.events.readonly ``` 8. The specific permissions for each Google OAuth scope are listed in the following table: | OAuth Scope | Functionality | | ---------------------------------------------- | --------------------------------------------------------------------------- | | admin.directory.domain.readonly | Get users on the domain | | admin.directory.group.readonly | Get user group memberships | | admin.directory.rolemanagement.readonly | Get user roles | | admin.directory.user.readonly | Get user profile information | | admin.reports.usage.readonly | Get usage status (Account status, MFA enablement, etc) | | admin.reports.audit.readonly | Get user audit activity (Google services accessed, login times, etc) | | gmail.settings.basic | Mailbox settings - Get and Set email forwarding rules - Block sender action | | apps.alerts | Get phishing alert reports from google | | bigquery | Read BigQuery tables (Workspace activity) | | gmail.readonly | Get Email raw body (Mail reports Based on Google alerts) | | gmail.modify | Soft Delete email action | | mail.google.com | Hard Delete email action | | calendar.readonly and calendar.events.readonly | Get user calendar events - Out Of Office events | 9. Click **Authorize**. {% hint style="info" %} Two of the scopes grant write access and support automated response actions in Radiant Security: * `https://www.googleapis.com/auth/gmail.modify` — soft-delete an email from a user's mailbox. * `https://mail.google.com` — hard-delete an email from a user's mailbox. To configure the Google Workspace action connector that uses these scopes, see [Execute response actions with Google Workspace](/radiant-connectors/data-connectors/google-workspace/execute-response-actions-with-google-workspace.md). {% endhint %} ### Enable BigQuery export 1. Sign in to the [Google Workspace Admin console](https://admin.google.com/). 2. Navigate to **Reporting** > **Data Integrations** > **BigQuery Export**. 3. Click on the export box and fill the required fields: * Project ID: the Project ID you copied when creating the Google Cloud project. * In the **New dataset within project field**, enter a name for the dataset: `google_workspace_log` 4. Click **Save**. ### Create a Google Workspace read-only admin role and delegated user {% hint style="warning" %} The Google Workspace APIs require a delegate Google Workspace account that holds all privileges needed by the APIs. This is an account inside the Google Workspace environment and is distinct from the Google Cloud service account created earlier. For background, see Google's [Delegating domain-wide authority to the service account](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority). {% endhint %} Radiant recommends creating a dedicated, named user account in Google Workspace for this purpose (for example, `radiant-delegate@yourdomain.com`) rather than reusing a personal admin account. 1. Sign in to the [Google Workspace Admin console](https://admin.google.com/). 2. Navigate to **Account > Admin Roles**. 3. Click on **Create new role**. 4. Name the role **`Radiant Security Read Only`** and click **Continue**. 5. Select the following privileges: * `Organizational Units` > `Read` * `Users` > `Read` * `Alert Center` > `View Access` * `Reports` * `Groups` > `Read` * `DLP` > `View DLP rule` * `Security Center` > `Activity Rules` > `View` 6. On the review screen, click **Create Role**. **Assign the role to a delegate user** 1. In the Google Workspace Admin console, create a dedicated user account if one does not already exist. For guidance, see Google's [Add an account for a new user](https://support.google.com/a/answer/33310). 2. On the **Admin Roles** page, open the `Radiant Security Read Only` role. 3. Click **Assign members** and assign the role to the delegate user account created in step 1. 4. Record the delegate user's email address. You enter this value as the **Delegate User Email** in the final section of this guide. ### Add the data connector in Radiant Security 1. Log in to [Radiant Security](https://app.radiantsecurity.ai/). 2. From the navigation menu, select **Settings > Data Connectors** and click **+ Add Connector**. 3. Search for and select the **Google Workspace** option and then click **Data Feeds**. 4. Add the following values from the previous steps: * **BigQuery Project ID**: the Project ID of the Google Cloud project you created. * **BigQuery Dataset Name**: `google_workspace_log` * **Delegate User Email**: the email address of the dedicated Workspace user account assigned the **Radiant Security Read Only** role. * **JSON File**: upload the service account JSON key file 5. Click **Add Connector** to save the connector configuration. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.radiantsecurity.ai/radiant-connectors/data-connectors/google-workspace.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.