> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace

> Google Workspace (formerly G Suite) is a cloud-based productivity and collaboration suite developed by Google. It includes a set of business applications designed to help teams work efficiently, communicate, and manage workflows.

### Pre-requisites

<Check>
  Users with an existing GCP environment, it is recommended to have a new project that links to your Google Workspace via the registered domain
</Check>

<Check>
  Admin Access to the Domain DNS Settings
</Check>

### **Setup Google Workspace**

Setting up **Google Workspace** involves several steps, depending on whether you create a new account or manage an existing domain.

<Steps>
  <Step title="Configure a New Project in GCP">
    GCP is hierarchical, so we must first create a project. If you already have a GCP environment set up, we recommend following similar steps below to create a new project that links to your Google Workspace via the registered domain.

    1. Go to [Google Cloud Console](https://console.cloud.google.com/welcome).

           <Note>
             Sign in with your Google account used to set up Google Workspace.
           </Note>
    2. Click on the **project selector** (top-left dropdown near “Google Cloud”).
    3. Click **"New Project"** to configure the project with all the necessary details:
       * **Project Name**: Enter a unique name for your project (For example: **AirMDR**).
       * **Organization & Location**: Enter [airmdr.com](http://airmdr.com) as organization and location or your organization and your location.
    4. Click **Create**.

           <Info>
             <Icon icon="rocket-launch" /> Now you have Successfully created a New Organization and Project in GCP\
             \
             Only the creator of the project has the right to manage the project.
           </Info>
  </Step>

  <Step title="Enable Admin SDK API and Google Workspace Alert center API">
    <Tip>
      Our virtual agent will eventually use a GCP service account, which uses the Workspace Admin SDK to interact with the GW admin console REST API, therefore it needs to be enabled in GCP. AirMDR will only enable read access to the Reports API for this admin SDK.
    </Tip>

    1. Go to [Google Cloud Console](https://console.cloud.google.com/welcome) → APIs & Services.
    2. Click **Enable APIs and services** in the top menu.
    3. Search for Each API:
       * Search **"Admin SDK API"**, click it, and click **“Enable”**.
       * Search **"Google Workspace Alert Center API"**, click it, and click **“Enable”**.
       * Search **"Gmail API"**, click it, and click **“Enable”**.

    <Note>
      When finished, you will have enabled the Admin SDK API within your project, where your service account will have access to pull data from Google Workspace.
    </Note>
  </Step>

  <Step title="Configure OAuth Consent Screen in Google Cloud Platform (GCP)">
    1. Go to the [Google Cloud Console](https://console.cloud.google.com/welcome).
    2. Select your project.
    3. Navigate to **"APIs & Services" → "OAuth consent screen"** in the left-navigation pane.
    4. Click **Get started**.
    5. Configure App Information with the required details:
       * **App Name**: airmdr-agent
       * **User Support Email**: Provide an email for users to contact (For Example: your email address), and Click **Next**.
    6. Choose **Audience** as **Internal**.
    7. Provide the **Developer Contact Information**: (For Example: your email address), and click **Next**.
    8. In **Finish**, mark the checkbox to acknowledge and accept the terms of Google User Data Policy.
    9. Click **"Create"**.

           <Check>
             After successful configuration, we will now have a registered application using OAuth 2.0 for authorization and the consent screen information set
           </Check>

           <Note>
             The default token request limit for this app daily is 10,000 and can be increased on request.
           </Note>
  </Step>

  <Step title="Create a Service Account in Google Cloud">
    <Check>
      A service account is required for the AirMDR agent to ingest data from Google Workspace

      This account is meant for non-human applications, allowing it to access resources in GW via the Admin SDK API we enabled earlier.
    </Check>

    <Info>
      This is required to access Google Workspace APIs like **Admin SDK API** and **Google Workspace Alert Center API**.
    </Info>

    1. Go to [Google Cloud Console](https://console.cloud.google.com/welcome) → APIs & Services → Credentials → + Create credentials → Service account.

           <img src="https://mintcdn.com/airmdr/6WXLh1uC-UzYOlBG/images/GoogleWorkspace1.png?fit=max&auto=format&n=6WXLh1uC-UzYOlBG&q=85&s=9a0caefd23454acdf291e31ac8b36d7a" alt="Google Workspace1 Pn" width="1355" height="423" data-path="images/GoogleWorkspace1.png" />
    2. On the **"Create Service Account"** page provide the required details:
       * **Service account name**: `airmdr-agent`
       * **Service account ID**: `airmdr-agent`
       * **Service account Description**: Describe what this service account will do
    3. Click **"Create and Continue"**.
    4. Assign necessary roles to grant permissions:
       * **"Service Account Token Creator"**
       * **"Viewer"** or **"Editor"** *(if needed for managing resources)*
    5. Click **"Done"**.

           <img src="https://mintcdn.com/airmdr/-s0d-0E2yQ2m2OqO/images/GoogleWorkspace2.png?fit=max&auto=format&n=-s0d-0E2yQ2m2OqO&q=85&s=1db93b510f0d05c10eaa5dab06bdcf51" alt="Google Workspace2 Pn" width="657" height="711" data-path="images/GoogleWorkspace2.png" />
    6. Click on the newly created service account.
    7. Go to the **"Keys"** tab.
    8. Click **"Add Key" → "Create New Key"**.

    Choose **JSON** format and click **"Create"**.

    <Info>
      **After successful configuration, we will now have a service account named airmdr-agent, a Service Account JSON file with the necessary credentials for this service account saved to your host.**
    </Info>

    <Check>
      <Icon icon="mail" /> **Securely save and share the downloaded Service Account JSON file to AirMDR.**
    </Check>

    <Accordion title="Sample Service Account JSON" icon="sparkles">
      ```

      {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "your-private-key-id",
        "private_key": "-----BEGIN PRIVATE KEY-----YOUR-PRIVATE-KEY\n-----END PRIVATE KEY-----\n",
        "client_email": "your-client-email",
        "client_id": "your-client-id",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "your-client-x509-cert-url",
        "universe_domain": "googleapis.com"
      }
      ```
    </Accordion>

    <Note>
      **By default, the Owner role will be applied to this service account based on inheritance from the project**
    </Note>
  </Step>

  <Step title="Enable Domain-Wide Delegation">
    <Info>
      **Only admins can perform this action.**
    </Info>

    Our service account will need domain-wide delegation of permissions to access APIs that reach outside of GCP and into Google Workspace. The important data necessary for this has already been established in earlier steps where we need an API key, service account, and OAuth client ID.

    1. Go to [Google Workspace Admin Console](https://admin.google.com/).
    2. Navigate to Security → Access and data control → API controls.
    3. Select Manage Domain Wide Delegation → Add a new client ID and enter the required credentials:

       * Client ID

             <Tip>
               To retrieve Client ID:\
               Navigate to Service Account in [GCP](https://console.cloud.google.com/welcome) and copy OAuthID\
               or\
               Copy from the JSON file generated while configuring the Service Account.
             </Tip>
       * OAuth Scopes

             <Tip>
               To retrieve OAuth Scopes:\
               Navigate to [Google Cloud Console](https://console.cloud.google.com/welcome) → IAM & Admin → Service accounts OAuth2 Client ID (Visible in the header section of the service account)\
               \
               OAuth Scopes: \
               [<u>https://www.googleapis.com/auth/admin.reports.audit.readonly</u>](https://www.googleapis.com/auth/admin.reports.audit.readonly), [<u>https://www.googleapis.com/auth/apps.alerts</u>](https://www.googleapis.com/auth/apps.alerts)

               > **You can now authorize AirMDR to fetch emails too of your organization’s users by specifying the required scope.**\
               > [https://www.googleapis.com/auth/gmail.readonly](https://www.googleapis.com/auth/gmail.readonly)
             </Tip>

           <img src="https://mintcdn.com/airmdr/-s0d-0E2yQ2m2OqO/images/GoogleWorkspace.png?fit=max&auto=format&n=-s0d-0E2yQ2m2OqO&q=85&s=0713e1799a7c0eb3d8508e8c79f02cb5" alt="Google Workspace Pn" width="972" height="850" data-path="images/GoogleWorkspace.png" />
    4. Click **"AUTHORIZE"**.

           <Check>
             <Icon icon="rocket-launch" /> Now you have Successfully enabled Domain-wide Delegation in Google Workspace
           </Check>

           <Note>
             AirMDR requires the JSON file generated while configuring the Service Account or an email ID that has admin access to read alerts in the Alert Center UI\
             \
             AirMDR Service account in GCP only needs access to:

             * [admin.reports.audit.readonly](https://www.googleapis.com/auth/admin.reports.audit.readonly): To access Google Workspace Audit Reports
             * [apps.alerts](https://www.googleapis.com/auth/apps.alerts): To read alerts
           </Note>
  </Step>

  <Step title="Admin Email ID Requirement">
    To successfully integrate Google Workspace with AirMDR, the `admin_email_id` parameter is required during the configuration process. This email address must correspond to a **valid Google Workspace administrator account** within your organization.

    #### Purpose

    The `admin_email_id` is used by AirMDR to:

    * Authenticate access to your Google Workspace environment.
    * Ensure authorization for retrieving security-related data and configuration settings.
    * Maintain a consistent point of contact for system alerts or integration-related events.

    #### Guidelines

    * Use your **primary business email ID** that has **Google Workspace Admin privileges**.
    * Ensure the account has sufficient permissions to grant scopes requested by AirMDR for monitoring and automation.
    * The email ID must be actively monitored, as integration health notifications and audit-related communications may be routed to this address.

      Example: `admin_email_id: "security-admin@yourcompany.com"`

          <Note>
            If your organization uses service accounts for automation, the `admin_email_id` is still required to validate permissions and maintain traceability within audit logs.
          </Note>

      ### ✅ Summary of Retrieved Credentials

      | Credential                    | Description                                                                                                                                                                                                                                                                                   |
      | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | **admin\_email\_id**          | Your **primary business email ID** that has **Google Workspace Admin privileges**                                                                                                                                                                                                             |
      | **Service Account JSON file** | **Service Account JSON file** generated in [step. 4](https://docs.airmdr.com/Integrations/Google-Workspace#after-successful-configuration%2C-we-will-now-have-a-service-account-named-airmdr-agent%2C-a-json-file-with-the-necessary-credentials-for-this-service-account-saved-to-your-host) |

          <Check>
            <Icon icon="mail" /> Securely save and share the `admin_email_id`, and **Service Account JSON file** with the AirMDR [**support**](mailto:support@airmdr.com) team to configure\
            or \
            Self [configure](https://docs.airmdr.com/Integrations/Google-Workspace#configure-google-workspace-in-airmdr-integrations-dashboard) Google Workspace in the AirMDR Integrations Dashboard.
          </Check>
  </Step>
</Steps>

### Configure Google Workspace in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials, and click **Login.**

   <img src="https://mintcdn.com/airmdr/wnBXbVlE7mmN9W6R/images/Datadog11.png?fit=max&auto=format&n=wnBXbVlE7mmN9W6R&q=85&s=94afec6835b90abcec516831e584184f" alt="" width="443" height="568" data-path="images/Datadog11.png" />
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **Integrations.**

   <img src="https://mintcdn.com/airmdr/-Uv__fqsZox2OjNr/images/Slack24.png?fit=max&auto=format&n=-Uv__fqsZox2OjNr&q=85&s=a9491b36c15fdaecb13d250b89843ad9" alt="Slack24 Pn" width="548" height="1456" data-path="images/Slack24.png" />
3. Use the search option, enter the keyword "**Google Workspace**", select the **Connections** tab, and click the **Add New Connection** icon.

   <img src="https://mintcdn.com/airmdr/1PfsRg3hGpCR-bzO/images/GoogleWorkspace7.png?fit=max&auto=format&n=1PfsRg3hGpCR-bzO&q=85&s=31643575a66d84f53a94d33d8fa1e913" alt="Google Workspace7 Pn" width="2102" height="1192" data-path="images/GoogleWorkspace7.png" />
4. Enter the generated **admin\_email\_id,** provide the contents of the generated [**JSON file with Service Account credentials**](https://docs.airmdr.com/Integrations/Google-Workspace#after-successful-configuration%2C-we-will-now-have-a-service-account-named-airmdr-agent%2C-a-json-file-with-the-necessary-credentials-for-this-service-account-saved-to-your-host) in the Authentication Details field params, and click **Create.**

   <img src="https://mintcdn.com/airmdr/1PfsRg3hGpCR-bzO/images/GoogleWorkspace8.png?fit=max&auto=format&n=1PfsRg3hGpCR-bzO&q=85&s=8403bb41ea056db34cd5ccc5e47cd28e" alt="Google Workspace8 Pn" width="1508" height="1450" data-path="images/GoogleWorkspace8.png" />