integration-docs
Loading

Google Workspace Integration

Version 2.45.0 (View all)
Compatible Kibana version(s) 8.18.0 or higher
9.0.0 or higher
Supported Serverless project types
What's this?
Security
Observability
Subscription level
What's this?
Basic
Level of support
What's this?
Elastic

The Google Workspace integration collects and parses data from the different Google Workspace audit reports APIs.

These blogs from our Security Labs will help you know more about the Google Workspace and how to it setup:

  1. To understand what Google Workspace is in Part One - Surveying the Land
  2. To set it up, step by step, in Part Two - Setup Threat Detection with Elastic

It is compatible with a subset of applications under the Google Reports API v1. As of today it supports:

Google Workspace Service Description
SAML help View users’ successful and failed sign-ins to SAML applications.
User Accounts help Audit actions carried out by users on their own accounts including password changes, account recovery details and 2-Step Verification enrollment.
Login help Track user sign-in activity to your domain.
Rules help View a record of actions to review your user’s attempts to share sensitive data.
Admin help View administrator activity performed within the Google Admin console.
Drive help Record user activity within Google Drive including content creation in such as Google Docs, as well as content created elsewhere that your users upload to Drive such as PDFs and Microsoft Word files.
Groups help Track changes to groups, group memberships and group messages.
Group Enterprise help The Group Enterprise activity report returns information about various types of Enterprise Groups Audit activity events.
Device help The Mobile activity report returns information about various types of Device Audit activity events.
Token help The Token activity report returns information about various types of OAuth Token Audit activity events.
Access Transparency help The Access Transparency activity report returns information about various types of Access Transparency activity events.
Context Aware Access help The Context Aware Access activity report returns information about various types of Context-Aware Access Audit activity events.
GCP The GCP activity report returns information about various types of Google Cloud Platform activity events.
Chrome The Chrome activity reports return information about Chrome browser and Chrome OS events.
Data Studio Track and audit user interactions and changes made to Looker Studio assets.
Calendar The Calendar activity report returns information about how your account's users manage and modify their Google Calendar events.
Chat The Chat activity report returns information about how your account's users use and manage Spaces.
Vault The Vault activity report returns information about various types of Vault Audit activity events.
Meet The Meet activity report returns information about various aspects of call events.
Keep The Keep activity report returns information about how your account's users manage and modify their notes.

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

This integration will make use of the following oauth2 scope:

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

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

Click the Advanced option of Google Workspace Audit Reports. The default value of "API Host" is https://www.googleapis.com. The API Host will be used for collecting access_transparency, admin, calendar, chat, chrome, context_aware_access, data_studio, device, drive, gcp, groups, group_enterprise, keep, login, meet, rules, saml, token, user accounts and vault logs.

Note

The Delegated Account value in the configuration, is expected to be the email of the administrator account, and not the email of the ServiceAccount.

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. The integration uses the BigQuery API to query logs from BigQuery.

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

  1. Enable BigQuery API if not already
  • In the Google Cloud console, navigate to APIs & Services > Library.
  • Search for BigQuery API and select it.
  • Click Enable.
  1. Create a service account:
  • In the Google Cloud console, navigate to APIs & Services > Credentials.
  • Click Create Credentials > 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.
  1. 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 > Create new key.
  • Choose JSON format and click Create.
  • Save the downloaded JSON key securely.
  1. Grant IAM Role to service account:
  • Go to IAM & Admin > 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.
  1. Set up a BigQuery project for reporting logs
  • Go to IAM & Admin page for your project.
  • Add a project editor for your project.
    • Click Grant access.
    • Enter [email protected] 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
  1. Set up a BigQuery Export configuration:
  • Sign in to your Google Admin console with a super administrator account.
  • Navigate to Reporting > Data Integrations (Requires having the Reports administrator privilege).
    Education administrators go to Menu Reporting > 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 [email protected] 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 > select the location from the menu.
  • Click Save.
  • For more details see Set up a BigQuery Export configuration.
  1. Grant Dataset Permissions:
  • Go to Google Cloud console and search for BigQuery.
  • Click your Google Cloud project on the left pane.
  • Locate the dataset, click the three-dot menu > Share > 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

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. The BigQuery API Host will be used for collecting gmail logs only.

The Google Workspace Integration collects and parses data received from the Google Workspace Alert Center API using HTTP JSON Input.

  • Alert Data Stream has been tested against Google Workspace Alert Center API (v1).

  • Following Alert types have been supported in the current integration version:

    1. Customer takeout initiated
    2. Malware reclassification
    3. Misconfigured whitelist
    4. Phishing reclassification
    5. Suspicious message reported
    6. User reported phishing
    7. User reported spam spike
    8. Leaked password
    9. Suspicious login
    10. Suspicious login (less secure app)
    11. Suspicious programmatic login
    12. User suspended
    13. User suspended (spam)
    14. User suspended (spam through relay)
    15. User suspended (suspicious activity)
    16. Google Operations
    17. Configuration problem
    18. Government attack warning
    19. Device compromised
    20. Suspicious activity
    21. AppMaker Default Cloud SQL setup
    22. Activity Rule
    23. Data Loss Prevention
    24. Apps outage
    25. Primary admin changed
    26. SSO profile added
    27. SSO profile updated
    28. SSO profile deleted
    29. Super admin password reset
    30. Account suspension warning
    31. Calendar settings changed
    32. Chrome devices auto-update expiration warning
    33. Customer takeout initiated
    34. Drive settings changed
    35. Email settings changed
    36. Gmail potential employee spoofing
    37. Mobile settings changed
    38. New user added
    39. Reporting Rule
    40. Suspended user made active
    41. User deleted
    42. User granted Admin privilege
    43. User suspended (spam)
    44. User's Admin privileges revoked
    45. Users password changed
    46. Google Voice configuration problem detected

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

This integration will make use of the following oauth2 scope:

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

Once Service Account credentials are downloaded as a JSON file, then the integration can be setup to collect data.

Note

The Delegated Account value in the configuration, is expected to be the email of the administrator account, and not the email of the ServiceAccount.

Note

The default value of the "Page Size" is set to 1000. This option is available under 'Alert' Advance options. Set the parameter "Page Size" according to the requirement. For Alert Data Stream, The default value of "Alert Center API Host" is https://alertcenter.googleapis.com. The Alert Center API Host will be used for collecting alert logs only.

Agentless integrations allow you to collect data without having to manage Elastic Agent in your cloud. They make manual agent deployment unnecessary, so you can focus on your data instead of the agent that collects it. For more information, refer to Agentless integrations and the Agentless integrations FAQ.

Agentless deployments are only supported in Elastic Serverless and Elastic Cloud environments. This functionality is in beta and is subject to change. Beta features are not subject to the support SLA of official GA features.

This is a list of Google Workspace Reports fields that are mapped to ECS that are common to all data sets.

Google Workspace Reports ECS Fields
items[].id.time @timestamp
items[].id.uniqueQualifier event.id
items[].id.applicationName event.provider
items[].events[].name event.action
items[].customerId organization.id
items[].ipAddress source.ip, related.ip, source.as.*, source.geo.*
items[].actor.email source.user.email, source.user.name, source.user.domain
items[].actor.profileId source.user.id

This is the saml dataset.

This is the user_accounts dataset.

This is the login dataset.

This is the rules dataset.

This is the admin dataset.

This is the drive dataset.

This is the groups dataset.

This is the alert dataset.

This is the device dataset.

This is the group_enterprise dataset.

This is the token dataset.

This is the access_transparency dataset.

This is the context_aware_access dataset.

This is the gcp dataset.

This is the chrome dataset.

This is the data_studio dataset.

This is the calendar dataset.

This is the chat dataset.

This is the vault dataset.

This is the meet dataset.

This is the keep dataset.

This is the gmail dataset.

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration. The screenshots below illustrate how the ingested data is displayed.