Skip to main content

Google Workspace

Visualize Google Workspace domain user groups, users, and their authorized tokens, map Google Workspace users to employees and managers, and monitor changes through queries and alerts.

Installation​

For this integration, you will need to add necessary API scopes to your Google Workspace as well as create a dedicated user and role with scopes and privileges for JupiterOne within the Admin console. Every step below is required whether or not your organization signs in through SSO; if it does, read the note under Create a JupiterOne user in Google Workspace for how to complete the dedicated user's one-time sign-in.

Add the JupiterOne API scopes​

Log in to the Google Workspace Admin Console as a super administrator to perform the following actions:

  1. Click Account > Account Settings > Profile and retrieve your Customer ID. It will have a format similar to C1111abcd. Alternatively, click Security and expand Setup single sign-on (SSO) for SAML applications and copy the idpid property value from the SSO URL. For example, https://accounts.google.com/o/saml2/idp?idpid=C1111abcd provides the ID C1111abcd. Retain this value for the Account ID field in the JupiterOne integration configuration.

  2. Return to the Admin Console home page. Click Security > Access and data control > API controls.

  3. In the Domain wide delegation pane, select Manage Domain Wide Delegation.

  4. Click Add new and enter the JupiterOne Service Account client ID 102174985137827290632 (US region) or 114158755753045408365 (EU region) into the Client ID field. If the JupiterOne integration configuration UI shows you a different client ID, use the one it shows — that value is authoritative for your account.

  5. Add the following API scopes (comma separated):

    https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/apps.groups.settings, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly, https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly, https://www.googleapis.com/auth/cloud-identity.devices.readonly, https://www.googleapis.com/auth/chrome.management.reports.readonly

  6. Click Authorize.

  7. Point to the client ID in the list and click View details to confirm all of the scopes above were saved. Google's console occasionally does not persist every scope on the first save; if any are missing, click Edit, re-add them, and Authorize again.

note

If your organization has enabled multi-party approval for sensitive admin actions, authorizing domain-wide delegation requires a second super administrator to approve the change before it takes effect. Scope changes can also take up to 24 hours to propagate.

Create a JupiterOne user in Google Workspace​

Continuing in the Admin console, create a user the JupiterOne Service Account will impersonate.

  1. Click Users > Add new user.

  2. Enter First name "JupiterOne", Last name "SystemUser", Primary email "jupiterone-admin". Retain the email address for the Admin Email field in the JupiterOne integration configuration.

  3. Click Add new user, and retain the temporary generated password for the next step.

  4. In another browser (or using Chrome's Incognito feature), log in as the new user to set a complex password and accept the Google Workspaces Terms of Service. You may dispose of the password as it will not be used and may be reset by a super administrator in the future as needed.

caution

Do not skip step 4, including when your organization signs in through SSO. Domain-wide delegation cannot impersonate a user who has never signed in: Google only sets the account's agreedToTerms flag after that first interactive login, it is an output-only field that no administrator or API call can set on the user's behalf, and until it is set the integration's authorization attempt fails. If your domain routes sign-in to an external identity provider, complete this one-time login through your IdP (provisioning jupiterone-admin there), or grant the account a temporary SSO exemption so it can sign in with the Google password, then remove the exemption afterward.

After that one-time login, the password is no longer used. JupiterOne authenticates as the Service Account and impersonates the address through domain-wide delegation, so the account needs no ongoing password, no IdP app assignment, and no interactive access.

Create a JupiterOne role in Google Workspace​

Continuing in the Admin console, create a new role that will have only the permissions required by JupiterOne, and which will include only the jupiterone-admin system user.

  1. Click Users, then click on the "JupiterOne SystemUser".

  2. Click Admin roles and privileges, then click the icon to edit the user's roles

  3. Click Create custom role > Create a new role.

  4. Enter Name "JupiterOne System", a Description "Role for JupiterOne user to enable read-only access to Google Workspaces Admin APIs." If you have email controls that filter for employee impersonation attacks, you may want to change the name to something such as "j1-system”.

  5. In the Admin privileges section, select these permissions:

    • Users -> Read
    • Groups -> Read
    • Domains -> Domain Management
    • Security -> User Security Management
    • Services -> Mobile Device Management -> Manage Devices and Settings
    • Services -> Chrome Management -> Manage ChromeOS Devices (read only)
    • Services -> Chrome Management -> View Extensions List Report
note

Google has consolidated the privilege tree: the permissions above were previously split across separate Admin console privileges and Admin API privileges sections, and are now all found under Admin privileges. The fastest way to select them is the privileges search box in the role editor rather than expanding each branch.

Grant Manage ChromeOS Devices (read only), not Manage ChromeOS Devices. The integration only reads ChromeOS device data, so the read-only privilege is sufficient and avoids granting write access to your devices.

To ingest role and role assignment data you must grant this account Super Admin permissions in addition to the custom role listed above. Permissions will still be restricted by the readonly API scopes if Super Admin permissions are granted, however access to group setting updates and token deletions will be an incidental side effect due to the limitations in the Google domain wide API settings.

These permissions will not be used by the JupiterOne integration, but if granting those permissions is unacceptable, please do not provide Super Admin permissions. The only ingestion items that will not be ingested due to missing Super Admin permissions are roles, role assignments, and token information.

Adding Scopes and Privileges​

Changes to the integration may include additional data ingestion requiring authorization of new scopes and additional privileges granted to the custom Admin Role.

To authorize additional scopes, log in to the Google Workspace Admin Console as a super administrator to perform the following actions.

  1. Click Security > Access and data control > API controls.

  2. In the Domain wide delegation pane, select Manage Domain Wide Delegation.

  3. Identify the JupiterOne Service Account client ID shown in the JupiterOne integration configuration UI.

  4. Click Edit to add scopes.

  5. Click Authorize, then point to the client ID and click View details to confirm the new scopes were saved.

To grant additional privileges, return to the Admin console:

  1. Click Admin roles, then click the "JupiterOne System" role.

  2. Click Privileges to add additional privileges under Admin privileges to enable JupiterOne to fetch new data.

  3. Click Save.

Configuration in JupiterOne​

To add the Google Workspace integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Google Workspace. Click New Instance to begin configuring your integration. Enter the following:

  • Account Name by which you want to identify this Google Workspace account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.
  • Description that assist your team when identifying the integration instance.
  • Select a Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.
  • Enter the Customer ID collected during the setup of Google Workspace.
  • Enter the Email Address of the user created during setup of Google Workspace.

Click Create once all values are provided to finalize the integration.

Integration Jobs Events​

A common log when running the integration job is Permission denied reading tokens for N users. This happens when the credentials provided to JupiterOne are insufficient for reading tokens of users with greater permissions, such as those with the Super Admin role assignment. This is not an error, but is only listed as informational.

As noted, this is due to the "JupiterOne SystemUser" that is configured for integration purposes not having sufficient permissions to list the tokens for users with higher privileges, such as the "Super Admin" Role. These tokens are not necessary for the job to complete and all other data will still be retrieved.

The "Tokens" step involves extensive API usage, often resulting in a long-running integration job. If you find this data less valuable, you may want to consider disabling this step using ingest sources.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.