# AQUILA - Google Workspace Gmail Logs (For revision)

**Google Workspace Gmail Logs**

The integration collects and parses Gmail audit logs data available for reporting in Google Workspace. You must first export Google Workspace logs to Google BigQuery. This involves exporting all activity log events and usage reports to Google BigQuery. Only certain Google Workspace editions support this feature. For more details see [About reporting logs and BigQuery(external, opens in a new tab or window)](https://support.google.com/a/answer/9079364?hl=en "https://support.google.com/a/answer/9079364?hl=en"). The integration uses the [BigQuery API(external, opens in a new tab or window)](https://cloud.google.com/bigquery/docs/reference/rest "https://cloud.google.com/bigquery/docs/reference/rest") to query logs from BigQuery.

**Requirements**

In order to ingest data from the Google BigQuery API, you must:

1. Enable BigQuery API if not already

- In the [Google Cloud console(external, opens in a new tab or window)](https://console.cloud.google.com/ "https://console.cloud.google.com/"), navigate to **APIs & Services > Library**.
- Search for **BigQuery API** and select it.
- Click **Enable**.

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/uYPwXM9dOQHfPk29-embedded-image-brnb4xle.png)</span>

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/kg9834EzQwNzLiCk-embedded-image-fmyjnfif.png)</span>

2. Create a service account:

- In the [Google Cloud console(external, opens in a new tab or window)](https://console.cloud.google.com/ "https://console.cloud.google.com/"), navigate to **APIs &amp; Services &gt; Credentials**.
- Click Create **Credentials &gt; Service account**.
- In the setup:
- Enter a name for the service account.
- Click **Create and Continue**.
- (Optional) Grant project access.
- Click **Continue**.
- (Optional) Grant user access.
- Click **Done**.


<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/l7zteQ6pvanPGyAJ-embedded-image-gnrccc9r.png)</span>

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/7tZ82CrZysTPMw3t-embedded-image-bemswslo.png)</span>

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/rfx9sZOvxcyMNi9N-embedded-image-wjcl13go.png)</span>

3. Generate a JSON Key:

- From the **Credentials** page, click on the name of your new service account.
- Go to the **Keys** tab.
- Click **Add Key &gt; Create new key**.
- Choose **JSON** format and click **Create**.
- Save the downloaded JSON key securely.

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/2u0YbNjJG8LJejfp-embedded-image-rdoeryjn.png)</span>

4. Grant IAM Role to service account:

- Go to **IAM &amp; Admin &gt; IAM** in the Cloud Console.
- Click **Grant access**.
- Paste the service account email in the **New principals** field.
- Click **Select a role**, search for and select **BigQuery Job User**.
- Click **Save**.

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/bQftkt86iXedqvR9-embedded-image-o9637aou.png)</span>

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/7o8jujmDnxWTPTyL-embedded-image-xnud2oad.png)</span>

5. Set up a BigQuery project for reporting logs

- Go to **IAM &amp; Admin page** for your project.
- Add a project editor for your project.
- Click **Grant access**.
- Enter gapps-reports@system.gserviceaccount.com in the **New principals** field.
- In **Select a role**, select **Project**, then **Editor**.
- Click **Save**.

- Add a Google Workspace administrator account as a project editor by following the same steps above.
- For more details see [Set up a BigQuery project for reporting logs(external, opens in a new tab or window)](https://support.google.com/a/answer/9082756?hl=en "https://support.google.com/a/answer/9082756?hl=en")

<span style="mso-no-proof: yes;">![](https://cytechint-docs-bookstack.s3.amazonaws.com/uploads/images/gallery/2026-01/yVqcG3QtVxKNCnK4-embedded-image-nmhimzvb.png)</span>

5. Set up a BigQuery Export configuration:

- Sign in to your [Google Admin console(external, opens in a new tab or window)](https://admin.google.com/ "https://admin.google.com/") with a super administrator account.
- Navigate to **Reporting &gt; Data Integrations** (Requires having the **Reports** administrator privilege).  
    Education administrators go to Menu **Reporting &gt; BigQuery export**, which opens the **Data integrations** page.
- Point to the **BigQuery Export** card and click Edit.
- To activate BigQuery logs, check the **Enable Google Workspace data export to Google BigQuery** box.
- (Optional) To export sensitive parameters of DLP rules, check the **Allow export of sensitive content from DLP rule logs** box.
- Under **BigQuery project ID**, select the project where you want to store the logs.  
    Choose a project for which gapps-reports@system.gserviceaccount.com has an editor role.
- Under **New dataset within project**, enter the name of the dataset to use for storing the logs in the project.  
    A new dataset will be created with this name in your BigQuery project.
- (Optional) Check the **Restrict the dataset to a specific geographic location** box &gt; select the location from the menu.
- Click **Save**.
- For more details see [Set up a BigQuery Export configuration(external, opens in a new tab or window)](https://support.google.com/a/answer/9079365?hl=en "https://support.google.com/a/answer/9079365?hl=en").

6. Grant Dataset Permissions: (**If this step is available to your end kindly follow the instructions but if not just skip**.)

- Go to [Google Cloud console(external, opens in a new tab or window)](https://console.cloud.google.com/ "https://console.cloud.google.com/") and search for **BigQuery**.
- Click your Google Cloud project on the left pane.
- Locate the dataset, click the **three-dot menu &gt; Share &gt; Manage Permissions**.
- Click **Add principal**.
- Paste the service account email in **New principals**.
- Select **BigQuery Data Viewer** as the role.
- Click **Save**.

This integration will make use of the following *oauth2 scope*:

- [https://www.googleapis.com/auth/bigquery](https://www.googleapis.com/auth/bigquery "https://www.googleapis.com/auth/bigquery")

Once you have downloaded your service account credentials as a JSON file, you are ready to set up your integration for collecting Gmail logs.

NOTE: For Gmail data stream, the default value of "BigQuery API Host" is [https://bigquery.googleapis.com](https://bigquery.googleapis.com "https://bigquery.googleapis.com/"). The BigQuery API Host will be used for collecting gmail logs only.

<div class="x_elementToProof" data-ogsc="rgb(0, 0, 0)" id="bkmrk-please-provide-the-f">**Please provide the following information to CyTech Support:** </div>- <div class="x_elementToProof" data-ogsc="" role="presentation"><span data-ogsc="">**GCP Project ID** (</span>GCP Project ID of project that has enabled export Gmail Logs)<span data-ogsc=""> - The unique identifier of the Google Cloud project where your BigQuery dataset is hosted and where Google Workspace Gmail logs are exported.</span></div>
- <div class="x_elementToProof" data-ogsc="" role="presentation"><span data-ogsc="">**Dataset Name** (</span>BigQuery dataset name<span data-ogsc="">) - The name of the BigQuery dataset inside the GCP project that stores the exported Gmail logs in daily tables for querying and analysis.</span></div>