Skip to main content

ITDR for Google Workspace Common Troubleshooting Steps

Melissa
  • Updated

Team: Huntress Managed Identity Threat Detection and Response (ITDR) for Google Workspace (GWS)
Product: ITDR for GWS
Environment: Google Workspace
Summary: Follow these steps to resolve common integration and sync issues when connecting Huntress to your Google Workspace environment.

 

Overview

Configuring ITDR for Google Workspace is generally straightforward. However, errors or issues may occasionally arise during the initial data synchronization, or unexpected behavior may occur following setup completion. 

 

In this Article

Onboarding Troubleshooting
Post-Onboarding Troubleshooting
 

Onboarding Troubleshooting

Verify the following configuration requirements for your initial setup:

  • Verify Super Administrator permissions. Only a Super Administrator account can add the integration.
  • Confirm API scope accuracy. Copy the following comma-separated scopes directly from the Huntress Platform into the Google Admin console to avoid hidden, extra, or missing characters. Do not copy the scope into any other program before pasting it into Google, like Docs or Word, as this can change the formatting. 
    • If you are unsure whether the scope was properly copied, it's best to unmap the integration and start over, ensuring the scope is copied correctly. 
  • Invalid Client ID during Google Consent Step
    • Manually type the Client ID instead of copy/paste
  • Access Blocked: admin needs to review Huntress Managed ITDR
    • In GWS, confirm Huntress ITDR under Security -> Access and data control -> API controls -> App access control with the correct client ID, set to Trusted and scoped to all users in the tenant.
    • Rerun the Google consent flow in an incognito window.
    • Rerun the Huntress auth in a normal browser session.
      • The GWS ITDR integration should appear and show Healthy in Huntress.

Post-Onboarding Troubleshooting

If issues occur after a successful initial setup, check the status of your administrator account and location settings:

  • Maintain an active Super Administrator account. This account must remain active and retain its permission level to prevent the sync from breaking.  
  • Configure Expected Locations. If you receive Unwanted Access escalations for legitimate logins, add those locations to the Unwanted Access section in the Huntress Platform. Because Google Workspace does not provide "normal" sign-in locations, this rule reduces false-positive alerts.

Tenant still Unhealthy after 48 hours

If a Google Workspace tenant still shows Unhealthy more than 48 hours after you complete onboarding and re-authorization, use these steps to confirm the Google configuration:

  1. In the Google Admin console, verify the domain-wide delegation entry:
    • Go to Security > Access and data control > API controls > Domain-wide delegation.
    • Locate the entry for Huntress and confirm the Client ID matches the Client ID in the Huntress Google Workspace integration (Integrations > Google Workspace > Edit Integration > View Setup Guide > Step 1E.

    • Copy and paste the full comma-separated scopes string into the OAuth scopes field of the Huntress Google Workspace integration in step 1G. 

      Always overwrite the scopes with the full list instead of adding only the missing scopes. This prevents subtle formatting errors and ensures future scope changes apply correctly. Do not copy the text to a third party tool such as a Word or TXT doc. Copy it directly to your Google Workspace instance.

  2. Confirm the Google app access control configuration for the Huntress ITDR app:
    • In Google Admin, go to Security > Access and data control > API controls.
    • Under App access control, select Manage Third-Party App Access.
    • Find the app entry for Huntress Managed ITDR with the Client ID from the Huntress Google Workspace integration in step 2E. 
    • Confirm the app is configured as:
      • Scope: All in {organization name} (all users)
      • Access to Google data: Trusted
  3. Re-authorize the integration in Huntress:
    • In the Huntress Platform, go to Account > Integrations and open the Google Workspace integration.
    • Use the Reauthorize action for the affected tenant (or unmap and remap if Reauthorize is not available), then complete the Google consent flow with a dedicated Super Administrator, granting all requested scopes.
  4. Wait for the next health check run:
    • Allow time for at least one full health check cycle to run (up to 48 hours).
    • Return to the Google Workspace integration in Huntress and confirm that the tenant health status updates to Healthy.
  5. If the tenant still shows Unhealthy, contact Huntress Support.

Related articles