Copy page

Google Workspace

OAuth Activity

Collect OAuth token activity from the Google Workspace Admin SDK Reports API (the token application, shown as "OAuth Token" audit log in the Admin console).

Sync Type: Incremental

How syncing works

Each sync fetches activity from the Reports API token application in time windows and checkpoints after every window. Each window ends 3 hours before the current time, so a new event reaches Monad at least 3 hours after it happens. Activity that Google publishes more than 3 hours after its event time is not fetched. On the first run the input starts from the current time and fetches no history unless Backfill Start Time is set. A Backfill Start Time more than 180 days in the past is clamped to 180 days ago. Each record is one activity object as returned by the Reports API.

Requirements

Before configuring this input, you need to set up a Google Cloud service account and grant it the necessary permissions in your Google Workspace environment. Follow these steps:

1. Create a Google Cloud Project:

   • Go to the Google Cloud Console.
   • Create a new project or select an existing one.

2. Enable the Admin SDK API:

   • In your project, go to "APIs & Services" > "Library".
   • Search for "Admin SDK API" and enable it.

3. Create a Service Account:

   • Go to "IAM & Admin" > "Service Accounts".
   • Click "Create Service Account".
   • Give it a name and description.
   • For role, you don't need to grant any roles in Google Cloud.
   • Click "Create and Continue", then "Done".

4. Generate a Key for the Service Account:

   • In the service account list, click on your new service account.
   • Go to the "Keys" tab.
   • Click "Add Key" > "Create new key".
   • Choose JSON as the key type and click "Create".
   • Save the downloaded JSON file securely.

5. Set up Domain-Wide Delegation:

   • Go to your Google Workspace Admin Console.
   • Navigate to Security -> Access and Data Control -> API Controls.
   • In the "Domain-wide Delegation" section, click "Add new".
   • For "Client ID", enter the service account's Client ID (found in the JSON key file).
   • For scopes, enter: https://www.googleapis.com/auth/admin.reports.audit.readonly
   • Click "Authorize".

6. Create and Configure an Admin Account:

   • In the Google Workspace Admin Console, go to Users.
   • Click on "Add new user" to create a new account, or select an existing user.
   • Fill in the required information for the new user.
   • After creating the user, click on the user's name to access their details.
   • In the user details page, find the "Admin roles and privileges" section.
   • Click on "Assign roles".
   • Navigate to "Admin roles" under the Account section.
   • Click "Create new role".
   • Name the role (e.g., "OAuth Activity Report Reader").
   • Under privileges, expand the "Reports" section.
   • Check the box for "Read" under "Admin Audit Reports".
   • Save the new role.
   • Return to the user's details and assign this new custom role.

Configuration

The Google Workspace OAuth Activity Input is configured using the following settings:

Settings

Setting	Type	Required	Default	Description
email	string	No	-	Email address to use for authenticating with Google Cloud.
auth_type	string	Yes	service_account	Type of authentication to use (service_account or oauth). Allowed values: service_account.
use_synthetic_data	bool	No	false	Generate synthetic data for testing, instead of connecting to a real data source. Defaults to an hourly cron schedule for cron-based inputs.
backfill_start_time	date	No	-	Date to start fetching data from, in ISO 8601 format. Dates more than 180 days in the past are clamped to 180 days ago. If not specified, only activity generated after the input is first enabled is fetched. All syncs thereafter are incremental.

Secrets

Secret	Type	Required	Description
credentials_json	secret	No	JSON credentials to authenticate with Google Cloud (required for service account auth).

Remember to keep your service account key confidential and never commit it to version control systems.

Functionality

This input component performs the following actions:

1. Authenticates with Google Workspace using a service account and admin impersonation.
2. Periodically fetches OAuth activity logs.
3. Processes and publishes OAuth activity data to the pipeline for further handling.

Best Practices

1. Service Account: Use a dedicated service account for this input.
2. Least Privilege: Grant only the necessary permissions to the service account.
3. Admin Impersonation: Use a dedicated admin account for impersonation, preferably one with limited permissions.
4. Credential Security: Keep the service account JSON key secure and never commit it to version control.
5. Regular Audits: Periodically review the service account's access and the impersonated admin's permissions.

Limitations

• The input fetches a maximum of 1000 results per API call.
• Historical data availability depends on Google Workspace's retention policies.
• API quotas and limits apply as per Google Workspace Admin SDK guidelines.

Troubleshooting

• For authentication errors, verify the service account credentials and Domain-Wide Delegation setup.
• If encountering "permission denied" errors, check the impersonated admin's privileges.
• No data being fetched could indicate a lack of OAuth activities or logging issues in your Google Workspace.

Sample Record

Code
{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2025-08-11T23:46:26.909848Z",
    "uniqueQualifier": "b0715ec1-82c9-b0f3-2509-debec016f0cc",
    "applicationName": "oauth",
    "customerId": "C03az79cb"
  },
  "etag": "\"etag_example\"",
  "actor": {
    "email": "user@example.com",
    "profileId": "42b29ca3-492a-59a8-72ae-1a44b3d5bfff",
    "callerType": "USER",
    "key": "key_example"
  },
  "ownerDomain": "example.com",
  "ipAddress": "209.38.231.104",
  "events": [
    {
      "type": "authorization",
      "name": "grant",
      "parameters": [
        {
          "name": "client_id",
          "value": "2d1e335b-c6f3-4843-8ad6-565bab6eb35b"
        },
        {
          "name": "scope",
          "value": "https://www.googleapis.com/auth/drive"
        }
      ]
    }
  ]
}

Sync frequency

This input polls on a connector-specific interval of 5 minutes, with each sync beginning after the previous one completes. A cron schedule configured on the pipeline overrides this cadence. See Input Sync Frequency for details.