Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
Google Workspace - AskJ1 Community
<main> <article class="userContent"> <h2 data-id="google-workspace-jupiterone-integration-benefits">Google Workspace + JupiterOne Integration Benefits</h2> <ul><li><p>Visualize Google Workspace domain user groups, users, and their authorized<br> tokens in the JupiterOne graph.</p></li> <li><p>Map Google Workspace users to employees in your JupiterOne account.</p></li> <li><p>Use queries to help perform access reviews, group assignments, OAuth<br> application authorizations, and other permission settings</p></li> <li><p>Workspace users identified as employees are mapped to their managers to<br> provide an organization chart in JupiterOne.</p></li> <li><p>Monitor changes to Google Workspace users using JupiterOne alerts.</p></li> </ul><h2 data-id="how-it-works">How it Works</h2> <ul><li><p>JupiterOne periodically fetches details from Google Workspace to maintain an<br> updated graph.</p></li> <li><p>Additional details stored in Google Workspace users is used to map your<br> organization management structure.</p></li> <li><p>Write JupiterOne queries to review and monitor updates to the graph.</p></li> <li>Configure alerts to take action when JupiterOne graph changes occur.</li> </ul><h2 data-id="requirements">Requirements</h2> <ul><li><p>A Google Workspace super administrator must grant the JupiterOne Google<br> Service Account domain-wide delegation authority.</p></li> <li><p>A Google Workspace user granted Admin API permissions; this user will be<br> impersonated by the Service Account.</p></li> <li><p>You must have permission in JupiterOne to install new integrations.</p></li> </ul><h2 data-id="support">Support</h2> <p>If you need help with this integration, please contact<br><a rel="nofollow" href="https://support.jupiterone.io">JupiterOne Support</a>.</p> <h2 data-id="integration-walkthrough">Integration Walkthrough</h2> <h3 data-id="in-google-workspace">In Google Workspace</h3> <p>The integration connects to Google Workspace Admin APIs with the following<br> details:</p> <ul><li>The Google Workspace <strong>Customer ID</strong> for the domain to ingest into JupiterOne</li> <li><p>The <strong>email address</strong> of a Google Workspace user created for JupiterOne with<br> permissions to read the information ingested into JupiterOne</p></li> <li><p>The credentials of the JupiterOne Service Account authorized to impersonate<br> the user and access necessary <strong>API scopes</strong></p></li> </ul><p>Log into the Google Workspace <strong>Admin Console</strong> as a super administrator to<br> perform the following actions.</p> <ol><li><p>Click <strong>Account Settings</strong> > <strong>Profile</strong> and retrieve your <strong>Customer ID</strong>.<br> It will have a format similar to <code class="code codeInline" spellcheck="false" tabindex="0">C1111abcd</code>.</p> <p>Alternatively, click <strong>Security</strong> and expand <strong>Setup single sign-on (SSO) for<br> SAML applications</strong> and copy the <strong><code class="code codeInline" spellcheck="false" tabindex="0">idpid</code></strong> property value from the <strong>SSO<br> URL</strong>. For example, <code class="code codeInline" spellcheck="false" tabindex="0">https://accounts.google.com/o/saml2/idp?idpid=C1111abcd</code><br> provides the ID <code class="code codeInline" spellcheck="false" tabindex="0">C1111abcd</code></p> <p>Retain this value for the Account ID field in the JupiterOne integration<br> configuration.</p></li> <li><p>Return to the <strong>Admin Console</strong> home page. Click <strong>Security</strong> > <strong>API<br> controls</strong>.</p></li> <li><p>In the <strong>Domain wide delegation</strong> pane, select <strong>Manage Domain Wide<br> Delegation</strong>.</p></li> <li><p>Click <strong>Add new</strong> and enter the JupiterOne Service Account client ID<br><code class="code codeInline" spellcheck="false" tabindex="0">102174985137827290632</code> into the <strong>Client ID</strong> field.</p></li> <li><p>Add the following <strong>API scopes</strong> (comma separated):</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">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 </pre></li> <li><p>Click <strong>Authorize</strong>.</p></li> </ol><p>Continuing in the <strong>Admin console</strong>, create a user the JupiterOne Service<br> Account will impersonate:</p> <ol><li><p>Click <strong>Users</strong> > <strong>Add new user</strong>.</p></li> <li><p>Enter <strong>First name</strong> "JupiterOne", <strong>Last name</strong> "SystemUser", <strong>Primary<br> email</strong> "jupiterone-admin".</p> <p>Retain the email address for the Admin Email field in the JupiterOne<br> integration configuration.</p></li> <li><p>Click <strong>Add new user</strong>.</p> <p>Retain the temporary generated password for the next step.</p></li> <li><p>In another browser (or using Chrome's Incognito feature), <strong>Log in</strong> as the<br> new user to set a complex password and <strong>accept the Google Workspaces Terms<br> of Service</strong>.</p> <p>You may dispose of the password as it will not be used and may be reset by a<br> super administrator in the future if necessary.</p></li> </ol><p>Continuing in the <strong>Admin console</strong>, create a new role that will have only the<br> permissions required by JupiterOne, and which will include only the<br><code class="code codeInline" spellcheck="false" tabindex="0">jupiterone-admin</code> system user.</p> <ol><li><p>Click <strong>Users</strong>, then click on the <strong>"JupiterOne SystemUser"</strong>.</p></li> <li><p>Click <strong>Admin roles and privileges</strong>, then click the icon to <strong>edit the<br> user's roles</strong>.</p></li> <li><p>Click <strong>Create custom role</strong> > <strong>Create a new role</strong>.</p></li> <li><p><strong>Name</strong> "JupiterOne System", <strong>Description</strong> "Role for JupiterOne user to<br> enable read-only access to Google Workspaces Admin APIs." Note: If you have<br> email controls that filter for employee impersonation attacks, you may want<br> to change the name to something such as "j1-system”.</p></li> <li><p>In the <strong>Privileges</strong>, <strong>Admin console privileges</strong> section check these<br> permissions:</p></li> </ol><ul><li>Manage Devices and Settings</li> <li>Manage Chrome OS Devices (read only)</li> </ul><ol start="6"><li>In the <strong>Privileges</strong>, <strong>Admin API Privileges</strong> section, check these<br> permissions:</li> </ol><ul><li>Users -> Read</li> <li>Groups -> Read</li> <li>Domain Management</li> <li>User Security Management</li> </ul><p>NOTE: In order to ingest role and role assignment data you will need to grant<br> this account Super Admin permissions in addition to the custom role listed<br> above. Permissions will still be restricted by the readonly API scopes if Super<br> Admin permissions are granted, however access to group setting updates and token<br> deletions will be an incidental side effect due to the limitations in the Google<br> domain wide API settings. These permissions will not be used by the JupiterOne<br> integration, but if granting those permissions is unacceptable, please do not<br> provide Super Admin permissions. The only ingestion items that will not be<br> ingested due to missing Super Admin permissions are roles, role assignments, and<br> token information.</p> <h4 data-id="adding-scopes-and-privileges">Adding Scopes and Privileges</h4> <p>Changes to the integration may include additional data ingestion requiring<br> authorization of new scopes and additional Admin API Privileges granted to the<br> custom Admin Role.</p> <p>To authorize additional scopes, log into the Google Workspace <strong>Admin Console</strong><br> as a super administrator to perform the following actions.</p> <ol><li><p>Click <strong>Security</strong> > <strong>API controls</strong>.</p></li> <li><p>In the <strong>Domain wide delegation</strong> pane, select <strong>Manage Domain Wide<br> Delegation</strong>.</p></li> <li><p>Identify the JupiterOne Service Account having the client ID<br><code class="code codeInline" spellcheck="false" tabindex="0">102174985137827290632</code>. Click <strong>Edit</strong> to add scopes.</p></li> <li><p>Click <strong>Authorize</strong>.</p></li> </ol><p>To grant additional Admin API Privileges, return to the <strong>Admin console</strong>.</p> <ol><li><p>Click <strong>Admin roles</strong>, then click on the <strong>"JupiterOne System"</strong> role.</p></li> <li><p>Click <strong>Privileges</strong> to add additional privileges to enable JupiterOne to<br> fetch new data.</p></li> <li><p>Click <strong>Save</strong>.</p></li> </ol><h3 data-id="in-jupiterone">In JupiterOne</h3> <ol><li>From the top navigation of the J1 Search homepage, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>Google</strong> integration tile and click it.</li> <li>Click the <strong>Add Configuration</strong> button.</li> <li>Enter the <strong>Account Name</strong> by which you'd like to identify this Google<br> Workspace account in JupiterOne. Ingested entities will have this value<br> stored in <code class="code codeInline" spellcheck="false" tabindex="0">tag.AccountName</code> when <strong>Tag with Account Name</strong> is checked.</li> <li>Enter a <strong>Description</strong> that will further assist your team when identifying<br> the integration instance.</li> <li>Select a <strong>Polling Interval</strong> that you feel is sufficient for your monitoring<br> needs. You may leave this as <code class="code codeInline" spellcheck="false" tabindex="0">DISABLED</code> and manually execute the integration.</li> <li>Enter the <strong>Customer ID</strong> collected during setup of Google Workspace.</li> <li>Enter the <strong>email address</strong> of the user created during setup of Google<br> Workspace.</li> <li>Click <strong>Create Configuration</strong> once all values are provided.</li> </ol><h3 data-id="integration-jobs-events">Integration Jobs Events</h3> <p>A common log when running the integration job is<br><code class="code codeInline" spellcheck="false" tabindex="0">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.</code><br> This is not an error, but is only listed as informational. As noted, this is due<br> to the <strong>"JupiterOne SystemUser"</strong> that is configured for integration purposes<br> not having sufficient permissions to list the tokens for users with higher<br> privileges, such as the "Super Admin" Role. These tokens are not necessary for<br> the job to complete and all other data will still be retrieved.</p> <h1 data-id="how-to-uninstall">How to Uninstall</h1> <ol><li>From the top navigation of the J1 Search homepage, select <strong>Integrations</strong>.</li> <li>Scroll to the <strong>Google</strong> integration tile and click it.</li> <li>Identify and click the <strong>integration to delete</strong>.</li> <li>Click the <strong>trash can</strong> icon.</li> <li>Click the <strong>Remove</strong> button to delete the integration.</li> <li>Revoke JupiterOne from <strong>Domain wide delegation</strong> in Google Workspace.</li> <li>Delete the "JupiterOne SystemUser" user in Google Workspace.</li> <li>Delete the "JupiterOne System" role in Google Workspace.</li> </ol><p><br></p> <h2 data-id="data-model">Data Model</h2> <h3 data-id="entities">Entities</h3> <p>The following entities are created:</p> <table><thead><tr><th>Resources</th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Entity <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> </tr></thead><tbody><tr><td>Account</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Account</code></td> </tr><tr><td>Chrome OS Device</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_chrome_os_device</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Device</code></td> </tr><tr><td>Domain</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_domain</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Domain</code></td> </tr><tr><td>Group</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">UserGroup</code></td> </tr><tr><td>Group Settings</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_group_settings</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Configuration</code></td> </tr><tr><td>Mobile Device</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_mobile_device</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Device</code></td> </tr><tr><td>Role</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_role</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">AccessRole</code></td> </tr><tr><td>Site</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_site</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">Site</code></td> </tr><tr><td>Token</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_token</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">AccessKey</code></td> </tr><tr><td>User</td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">User</code></td> </tr></tbody></table><h3 data-id="relationships">Relationships</h3> <p>The following relationships are created:</p> <table><thead><tr><th>Source Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> <th>Relationship <code class="code codeInline" spellcheck="false" tabindex="0">_class</code></th> <th>Target Entity <code class="code codeInline" spellcheck="false" tabindex="0">_type</code></th> </tr></thead><tbody><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_role</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><strong>MANAGES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_chrome_os_device</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_account</code></td> <td><strong>MANAGES</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_mobile_device</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_group_settings</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_group</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_site</code></td> <td><strong>HAS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_token</code></td> <td><strong>ALLOWS</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">mapped_entity (class Vendor)</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> <td><strong>ASSIGNED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_role</code></td> </tr><tr><td><code class="code codeInline" spellcheck="false" tabindex="0">google_user</code></td> <td><strong>ASSIGNED</strong></td> <td><code class="code codeInline" spellcheck="false" tabindex="0">google_token</code></td> </tr></tbody></table><p><br></p> </article> </main>
.png)