Integrate Google Workspace with Red Canary

Create a Google Cloud Console project to start sending google workspace telemetry for ingestion. 

1. From your Google Cloud Console dashboard, click Create Project.
   

2. Fill in the mandatory fields:

   1. Project Name—The name associated with your project

   2. Organization—The name of your organization

   3. Location—Location of your organization

3. Click Create.

Enable the Admin SDK to create and manage admin-controlled resources owned by a Google Workspace account.

1. From your Google Cloud Console dashboard, type Admin SDK API into the search bar.

2. From the Marketplace section, click Admin SDK API. Check the drop down in the top left, next to Google Cloud and verify that the current project matches the project created in Step 1.

   

3. Click Enable.

Enable the Alert Center API to create and manage alerts and issues owned by a Google Workspace account.

1. From your Google Cloud Console dashboard, type Alert Center API into the search bar.

2. From the Marketplace section, click Alert Center API.

   

3. Check the drop down in the top left, next to Google Cloud and verify that  the current project matches the project created in Step 1.

4. Click Enable.

Create a service account to enable Red Canary to ingest your data.

1. From your Google Cloud Console dashboard, select the project you created in Step 1.

2. Click the Navigation menu icon.

   

3. Click IAM & Admin, and then click Service Accounts.

   

4. Click Create Service Account.

5. Fill in the mandatory fields:

   1. Service account name

   2. Service account ID 

6. Click CREATE AND CONTINUE.

7. Click Done.

Create a private key so that sanctioned users can use the service account.

1. From the service account you just created, click the Actions icon, and then click Manage Keys.

   

2. Click the Add Key dropdown.

   

3. Click Create new key.

   

4. Select JSON, and then click Create.

5. Save this .JSON file in a secure location.

Enable domain wide delegation to allow applications to access user data across your organization's Google Workspace environment.

1. From your Google Cloud Console dashboard, select the project you created in Step 1.

2. Click the Navigation menu icon.

   

3. Click IAM & Admin, and then click Service Accounts.  

4. From the service account you just created, click the Actions icon, and then click Manage Details.

   

5. Copy and save the Client ID (Same as Unique ID).
   

6. Click View Google Workspace Admin Console.

Granting the service account proper permissions enables Red Canary to ingest all the necessary telemetry.

1. From your Google Workspace Admin Console, click the Security dropdown.

   

2. Click the Access and data control dropdown.

3. Click API Controls.

   

4. Scroll down, and then click Manage Domain-Wide Delegation.

   

5. Click Add New.

   

6. For the Client Name field, enter the Client ID from Step 6.5.

7. For the OAuth scopes field, enter:

   1. https://www.googleapis.com/auth/admin.reports.audit.readonly

   2. https://www.googleapis.com/auth/apps.alerts

   3. https://www.googleapis.com/auth/admin.reports.usage.readonly

8. Click Authorize.

The Google service account created in Step 4 requires a google workspace account to start sending telemetry to Red Canary.

Note: You can re-use an existing Google Workspace user account with Admin Console Reports permissions.

1. From your Google Workspace Admin Console, click the Directory dropdown.

2. From the Directory dropdown, click Users.

3. Click Add new user.

   

4. Fill in the fields to identify the Red Canary service account.

5. Click Add new user.

   Note: You do not need to copy or use the automatically generated password. To set your own password, click Preview and send.

6. Click Done.

7. To see your new user account, refresh the Users page.

8. Select the user account you just created.

9. Scroll down to the Admin roles and Privileges section, and then click the Expand Roles and Privileges dropdown.

   

10. Click Create Custom Role.

    

11. Click Create new role. 

12. Enter a name for your new role.

13. Enter a description for your new role.

14. Click Continue.

15. From the Privilege Name section, scroll down and then click the Services dropdown.

16. Click the Alert Center Dropdown, and then select View Access.

    

17. From the Privilege Name section, scroll down and select Reports.

    

18. Click Continue.

19. Click Create Role. 

20. Click Assign users.

21.  Enter the name of the new service account you created in Step 8.4.

22. Click Assign Role.

Connect your Google service account key to Red Canary in order to start receiving Google Workspace alerts in Red Canary.

1. From your Red Canary homepage, click Integrations.

   

2. Click Google Workspace.

   

3. Click Configure.

4. Enter the service account key from the .JSON file you downloaded from Google Workspace in Step 5.5.

5. Enter the email account created in Step 8. Note: The email address entered must mach the Google Workspace user created in Step 8. This email is not expected to match the email found in the JSON key.

   

6. Click Save.

Environments covered

• Google Workspace

Ingest details

Red Canary polls two APIs to collect data from Google Workspace:

• Reports API (Red Canary processes these audit activity sources as telemetry)

  • User accounts activity

  • Login activity

  • Admin activity

• Alert Center API (Red Canary processes all retrieved data as external alerts)

• Customer Usage Reports API (Red Canary polls the Customer Usage Reports API once daily to retrieve the total number of users for licensing purposes)

The Google Workspace ingestor currently polls the above-mentioned APIs every five minutes. There is a lag between event creation in Google and the time that Red Canary's ingestor processes the event creations when polling the Reports API. For more information, see Data retention and lag times. Google takes a long time to make event kinds available via the API. However, this lag should not apply to the Google Workspace Alert Center API.

APIs and Permissions

This integration article specifies enabling only the necessary APIs, including Admin SDK and Alert Center, and assigning specific read-only permissions. Only the required APIs and scopes are enabled and granted.

Create a Service Account

The creation and configuration of service accounts are focused on providing specific roles and permissions needed for data ingestion without granting excessive access. The steps include creating a custom role with view access and specific privileges for reports and alerts and ensuring the service account has only the necessary permissions.

Google Workspace Service Admin Account email

The Google Workspace Service Admin Account email, created in the Google Workspace Admin console, is used for viewing reports and viewing the alert center. This account does not give Red Canary admin access to your Google Workspace environment. It is tied to the private key that was created for the service account that was created in the Google Cloud Console.

Domain-Wide Delegation

The domain-wide delegation is explicitly scoped to specific API permissions necessary for the telemetry data, including audit read-only, app alerts, and usage read-only.

Create a Private Key

The purpose of creating the private key in the Google Cloud Console setup process is to enable secure authentication and authorization for the service account.

• Authentication: The private key is used to authenticate the service account to Google Cloud services. A service account must prove its identity when it attempts to access Google APIs. The private key is part of a pair (public/private) that securely identifies the service account.

• Authorization: The private key and the service account grant permission to access specific Google Cloud and Google Workspace APIs. It ensures that only authorized entities (in this case, the service account with the correct private key) can access the resources and perform actions.

• Secure Communication: The private key facilitates secure communication between the service account and Google APIs. It ensures that the data sent between the client (service account) and server (Google APIs) are encrypted and cannot be tampered with.

The private key is crucial for allowing the service account created in the Google Workspace console to access the necessary APIs for telemetry ingestion. Here’s how it works in the context of the setup process described in the integration document:

• Service Account Creation: A service account is created with specific roles and permissions for telemetry ingestion.

• Private Key Generation: A private key is generated for this service account, which will be used to authenticate and authorize the service account when accessing Google Workspace APIs.

• Integration with Red Canary: The private key (in JSON format) is saved and used to configure the Managed Service Provider (Red Canary) to ensure secure and authorized access to the telemetry data.

• API Access: The service account uses the private key to access the Admin SDK API and Alert Center API to retrieve and send telemetry data from Google Workspace to the Red Canary.

In summary, the private key is an essential component that allows the service account to securely and effectively access the necessary APIs for telemetry ingestion, ensuring that the data is handled securely.