Google Workspace + JupiterOne Integration Benefits
Visualize Google Workspace domain user groups, users, and their authorized
tokens in the JupiterOne graph.
Map Google Workspace users to employees in your JupiterOne account.
Use queries to help perform access reviews, group assignments, OAuth
application authorizations, and other permission settings
Workspace users identified as employees are mapped to their managers to
provide an organization chart in JupiterOne.
Monitor changes to Google Workspace users using JupiterOne alerts.
How it Works
JupiterOne periodically fetches details from Google Workspace to maintain an
updated graph.
Additional details stored in Google Workspace users is used to map your
organization management structure.
Write JupiterOne queries to review and monitor updates to the graph.
- Configure alerts to take action when JupiterOne graph changes occur.
Requirements
A Google Workspace super administrator must grant the JupiterOne Google
Service Account domain-wide delegation authority.
A Google Workspace user granted Admin API permissions; this user will be
impersonated by the Service Account.
You must have permission in JupiterOne to install new integrations.
Support
If you need help with this integration, please contact
JupiterOne Support.
Integration Walkthrough
In Google Workspace
The integration connects to Google Workspace Admin APIs with the following
details:
- The Google Workspace Customer ID for the domain to ingest into JupiterOne
The email address of a Google Workspace user created for JupiterOne with
permissions to read the information ingested into JupiterOne
The credentials of the JupiterOne Service Account authorized to impersonate
the user and access necessary API scopes
Log into the Google Workspace Admin Console as a super administrator to
perform the following actions.
Click 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.
Return to the Admin Console home page. Click Security > API
controls.
In the Domain wide delegation pane, select Manage Domain Wide
Delegation.
Click Add new and enter the JupiterOne Service Account client ID
102174985137827290632 into the Client ID field.
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
Click Authorize.
Continuing in the Admin console, create a user the JupiterOne Service
Account will impersonate:
Click Users > Add new user.
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.
Click Add new user.
Retain the temporary generated password for the next step.
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 if necessary.
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.
Click Users, then click on the "JupiterOne SystemUser".
Click Admin roles and privileges, then click the icon to edit the
user's roles.
Click Create custom role > Create a new role.
Name "JupiterOne System", Description "Role for JupiterOne user to
enable read-only access to Google Workspaces Admin APIs." Note: If you have
email controls that filter for employee impersonation attacks, you may want
to change the name to something such as "j1-system”.
In the Privileges, Admin console privileges section check these
permissions:
- Manage Devices and Settings
- Manage Chrome OS Devices (read only)
- In the Privileges, Admin API Privileges section, check these
permissions:
- Users -> Read
- Groups -> Read
- Domain Management
- User Security Management
NOTE: In order to ingest role and role assignment data you will need to 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 Admin API Privileges granted to the
custom Admin Role.
To authorize additional scopes, log into the Google Workspace Admin Console
as a super administrator to perform the following actions.
Click Security > API controls.
In the Domain wide delegation pane, select Manage Domain Wide
Delegation.
Identify the JupiterOne Service Account having the client ID
102174985137827290632. Click Edit to add scopes.
Click Authorize.
To grant additional Admin API Privileges, return to the Admin console.
Click Admin roles, then click on the "JupiterOne System" role.
Click Privileges to add additional privileges to enable JupiterOne to
fetch new data.
Click Save.
In JupiterOne
- From the top navigation of the J1 Search homepage, select Integrations.
- Scroll to the Google integration tile and click it.
- Click the Add Configuration button.
- Enter the Account Name by which you'd like to identify this Google
Workspace account in JupiterOne. Ingested entities will have this value
stored in tag.AccountName when Tag with Account Name is checked.
- Enter a Description that will further 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 setup of Google Workspace.
- Enter the email address of the user created during setup of Google
Workspace.
- Click Create Configuration once all values are provided.
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.
How to Uninstall
- From the top navigation of the J1 Search homepage, select Integrations.
- Scroll to the Google integration tile and click it.
- Identify and click the integration to delete.
- Click the trash can icon.
- Click the Remove button to delete the integration.
- Revoke JupiterOne from Domain wide delegation in Google Workspace.
- Delete the "JupiterOne SystemUser" user in Google Workspace.
- Delete the "JupiterOne System" role in Google Workspace.
Data Model
Entities
The following entities are created:
| Resources |
Entity _type |
Entity _class |
|---|
| Account |
google_account |
Account |
| Chrome OS Device |
google_chrome_os_device |
Device |
| Domain |
google_domain |
Domain |
| Group |
google_group |
UserGroup |
| Group Settings |
google_group_settings |
Configuration |
| Mobile Device |
google_mobile_device |
Device |
| Role |
google_role |
AccessRole |
| Site |
google_site |
Site |
| Token |
google_token |
AccessKey |
| User |
google_user |
User |
Relationships
The following relationships are created:
Source Entity _type |
Relationship _class |
Target Entity _type |
|---|
google_account |
HAS |
google_group |
google_account |
HAS |
google_role |
google_account |
HAS |
google_user |
google_account |
MANAGES |
google_chrome_os_device |
google_account |
MANAGES |
google_mobile_device |
google_group |
HAS |
google_group |
google_group |
HAS |
google_group_settings |
google_group |
HAS |
google_user |
google_site |
HAS |
google_user |
google_token |
ALLOWS |
mapped_entity (class Vendor) |
google_user |
ASSIGNED |
google_role |
google_user |
ASSIGNED |
google_token |
.png)