Google Workspace (G Suite)

Related Enforcement Actions:

These actions can help when you want users to be added to GSuite or to a group, or when you want to remove users or delete extensions.

• GSuite - Add Users

• GSuite - Add Users to Group

• GSuite - Change Users OU

• GSuite - Delete Extension

• GSuite - Remove Users

• GSuite - Remove Users From Group

• GSuite - Reset Users Logon Cookies

• GSuite - Role Assignments Actions

This adapter fetches the following types of assets:

• Devices

• Users

• SaaS data

Enable or Exclude 2-Step Verification

Depending on your organization's security policies, you can either enable 2-step verification for the user you just created, or exclude the user from the 2-step verification policy.

Enable 2-Step Verification

1. Log into Google Accounts with the user account you just created.

2. From the menu, select Security.

3. In the Signing in to Google section, click 2-Step verification.
   

4. Click Get Started.

5. If prompted, Enter the password.
   

6. Enter your phone number (you can remove it later) to receive a text message.

7. Click Next

8. Enter the code you received from Google and click Next.

9. Click Turn on.

10. Generate the secret key:

    1. In the 2-Step Verification age, in the Add More Second Steps to Verify It's You section, click Authenticator app.
       

    2. Install Google Authenticator on your phone or add a chrome extension.

    3. Click Set up authenticator.

    4. Click Can't scan it?.

    5. Copy the Secret key.
       

    6. Back in Axonius, paste the copied secret key in the 2FA Secret Key field.

11. Generate the verification code: 

    1. Back in the Google, click Scan QR Code to display the QR Code again. 

    2. Open the Google Authenticator on your device and click +.

    3. Scan the QR code. Google Authenticator displays a verification code.

    4. In Google, click Next and enter the verification code.

    5. Click Verify.

       Note

       This verification is a one-time process.

12. Enforce 2-step verification for the organizational unit:

    1. In the Google Workspace Admin Console, from the left navigation menu, navigate to Security > Authentication > 2-step verification.
       

    2. In the 2-Step Verification page, on the left pane, expand Organizational units.

    3. Locate and click the newly created organizational unit.

    4. Under the Authentication section, select the Allow users to turn on 2-Step Verification checkbox.

    5. Under Enforcement, select On.

    6. Under Methods, select Any.

Exclude the User Account from 2-Step Verification

If your organization's security policy allows it, you can simplify your setup by just excluding the user you created from 2-step verification, instead of enabling it.

1. From the Google Workspace Admin Console, navigate to Directory > Users.

2. Locate and click the newly created user account.

3. Click the Security section, ensure that 2-step verification is set to OFF.
   

Enable Cloud APIs

This process allows you to enable the APIs allow the adapter to access Google data relevant for your SaaS environment.

1. Log into the Google Cloud Console as an administrator. 

2. From the menu, navigate to APIs & Services.

3. Select any existing project. 

4. (Optional) Create a new project to include the API access: 

   1. Click Create Project.
      

   2. Enter a name for the project (for example, prj-axonius-sm).

   3. Click Create.
      

5. Click Enable APIs and Services.

6. Confirm that the following APIs are listed and enabled. If any of them are not enabled, click the API and click Enable:

   1. Admin SDK API

   2. Cloud Identity API

   3. Enterprise License Manager API

   4. Google Calendar

   5. Service Usage API

   6. Group Settings API
      

Create a Service Account

Creating a service account in the Google Cloud Console allows you to generate Principle value along with a JSON file containing other parameters, all of which are needed for connecting the Google adapter with Axonius.

1. Log into the Google Cloud Console as an administrator. From the menu, navigate to IAM & admin > Service Accounts.

2.  Create the service account:

   1. Click Create Service Account.
      

   2. Enter a Service Account name (for example, srv-axonius-sm).

   3. Click Create and Continue.

   4. Click Continue and then click Done.
      

3. Generate the Admin Account (principle) value:

   1. Locate and click the service account you just created.

   2. From the Permissions tab, copy the Principal value (email address).
      

   3. In Axonius, paste the copied value in the Admin account (Principle) field.

Configure the service account key

1. Open the Keys tab.

2. Click Add Key.

3. Select Create new key.
   

4. Select JSON and then click Create. The JSON key will automatically be downloaded to your machine.
   

5. Back in Axonius, click Upload File to upload the downloaded JSON file. 

Configure the OAuth Scopes

1. From the Details tab, click Advanced settings.

2. Click to copy the the Client ID.

3. Click View Google Workspace Admin Console.
   

4. Navigate to Security > Access and data control > API Controls. 

5. Click Manage Domain Wide Delegation.
   

6. Access the Scopes field:

   1. If you have previously set up this adapter, paste the copied client ID into the ‘Add a Filter’ area, and select the Client ID filter.

      

      Then hover over the API Client in the list, and click Edit.

      

   2. If this is the first time connecting the adapter, or there are no results for the Client ID filter, Click Add New. In the Client ID field, paste the copied Client ID.

      

7. In the OAuth scopes (comma-delimited) field, paste the following OAuth scopes (comma-separated):

   NOTE

   Ensure that the corresponding options are selected in Parameters and Advanced Settings. If you are adding to existing scopes, ensure that you add the scopes AFTER the scopes that are already there and do not replace them.

   • Required scopes for this adapter: https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly

   • For fetching Chrome browsers: https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly

   • For fetching tokens for applications and for deleting extensions via the Enforcement Center: https://www.googleapis.com/auth/admin.directory.user.security

   • For fetching Cloud Identity devices: https://www.googleapis.com/auth/cloud-identity.devices.readonly

   • For fetching user groups:

     https://www.googleapis.com/auth/admin.directory.group.readonly

   • For fetching Disk Usage - displays values in the Disk Quota field https://www.googleapis.com/auth/admin.reports.usage.readonly

   • For fetching data from Google Calendar: https://www.googleapis.com/auth/calendar The following scopes are only for Axonius accounts with the SaaS Management module:

     While to access SaaS data you need to grant roles and/or scopes that include write capabilities, the adapter only actually reads data from the application.

   • For fetching Audit Logs: https://www.googleapis.com/auth/admin.reports.audit.readonly

   • For fetching User Roles Scope (required) https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

   • For fetching Settings (Policies): https://www.googleapis.com/auth/apps.groups.settings

   • For fetching Accounts : https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.customer.readonly

   • For fetching User License Associations: https://www.googleapis.com/auth/apps.licensing 

8. Click Authorize.
   

Create a Custom Role and Add to Principal 

1. Log into the Google Cloud Console as an administrator. 

2. Create a custom role:

   1. From the menu, navigate to IAM & admin > Roles.

   2. Click Create Role.
      

   3. Enter a Title (for example, "srv-axonius-sm-role").

   4. Click Add Permissions.
      

   5. Next to the filter search row, search for 'resourcemanager.projects.get'.
      

   6. Select the permission and click Add.

   7. Click Create.
      

3. Add the role to the principle:

   1. Navigate to IAM & admin > IAM.

   2. From the Principals list, select the principal you associated with the service account.

   3. Click corresponding to the selected principal.
      

   4. In the Edit Permissions window, click Add Another Role.

      

   5. Locate and add the custom role you created.
      

   6. Click Save.
      

   7. If prompted, click Continue.

4. Go to the following URL (add the project ID located in the JSON file that you generated earlier): https://console.developers.google.com/apis/api/admin.googleapis.com/overview?project=<project_id>

5. Click to enable the Admin SDK API.

Connect Adapter

1. We recommend logging into Google with the user you created to ensure that the user was properly configured.

2. Back in Axonius, in the Google Workspace adapter setup window, click Save and Fetch.

Optional: Create a Least-Privileged Role (For SaaS Management)

If your Axonius account includes the SaaS Management module, and you organization's security policy does not allow for providing Axonius Super Admin access to your Google environment when you set up the user account, you can follow these instructions at the end of this guide to set up a Least-Privileged role instead.

Once this process is complete, continue setting up the adapter connection with Enable or exclude 2-step verification.

1. Log into the Google Workspace Admin Console as an administrator. 

2. From the home page, scroll down and navigate to Account>Admin roles.

3. Click Create new role.

4. Enter the name and description for the new role (for example, "svc_axonius_sm_role"), and click Continue.

5. In the Admin Console Privileges section, select the following permissions:

   • Organizational Units > Read

   • Users > Read

   • Security

     • User Security Management

     • Security Settings

   • Domain Settings

   • Reports

6. Expand the Services section and select the following permissions:

   • Directory settings > Settings

   • Looker Studio > Manage Data Studio Settings

   • Sites > Manage Google Sites

   • Google Vault > View All Matters

   • Calendar > All Settings > Settings

   • Data Security > Access Level Management

   • Data Security > Rule Management

   • Classroom > Settings

   • Google Chat > Settings (Read and Modify)

   • Directory Sync > Manage Directory Sync Settings > Read Directory Sync Settings

   • Google Hangouts > Settings

   • YouTube > Manage YouTube Settings

   • Google Meet > Manage Meet Settings

   • Pinpoint > Admin settings for Pinpoint

   • Contacts > Contacts Settings Message > Delegates Read

   • Currents > Settings

   • Gmail > Settings

   • Groups for Business > Settings

   • Cloud Search > Settings

   • Shared device settings > Parent privilege for Managing all common device configurations > Manage all common device configurations

   • Mobile Device Management > Manage Devices and Settings

   • Drive and Docs > Settings

   • Google Workspace Marketplace > Manage access to allowlisted apps

   • Alert Center > Full access > View access

   • Jamboard > Manage Jamboard Settings

   • Chrome Management > Settings > Manage User Settings

   • Chrome Management > Settings > Managed Browsers > Read

   • Chrome Management > Settings > Manage Printers

   • Chrome Management > Settings > Manage Chrome OS Devices > Manage Chrome OS Devices (read only)

   • Chrome Management > Settings > Manage Chrome OS Device Settings

   • App Maker > Settings

   • Google Cloud Print > Cloud Print Manager

7. Expand the Services > Security Center section:

   1. Ensure that the user has full administrative rights for VirusTotal > View Report.

   2. Ensure that the user has full administrative rights for the following Investigation Tool related permissions:

      • Gmail > View Metadata and Attributes

      • Drive > View Metadata and Attributes

      • Device > View Metadata and Attributes

      • User > View Metadata and Attributes

      • OAuth > View Metadata and Attributes

      • Rule > View Metadata and Attributes

      • Chrome > View Metadata and Attributes

      • Meet > View Metadata and Attributes

      • Groups > View Metadata and Attributes

      • Voice > View Metadata and Attributes

      • Calendar > View Metadata and Attributes

      • Admin > View Metadata and Attributes

      • Activity Rules > View

8. In the Admin API Privileges section, select the following permissions:

   • Organization Units > Read

   • Users > Read

   • Groups > Read

   • User Security Management

   • Schema Management > Schema Read

   • License Management > License Read

   • Billing Management > Billing Read

   • Domain Management

   • Domain Allowlist Management > Domain Allowlist Read

9. Click Continue. 

10. Click Create Role.

11. Click the corresponding toggle to enable the custom role you created.

12. Click Save.

The parameters that you need to fill out will differ based on the capabilities in your Axonius platform. 'General' pertains to users with ‘Cybersecurity Asset Management’ and/or ‘SaaS Management’ capabilities.

To learn more about common adapter connection parameters and buttons, see Adding a New Adapter Connection.

General

• Email of an admin account to impersonate (required) - The email of your Google Workspace (G Suite) admin.

• JSON Key pair for the service account (required) - Upload the JSON file you have created for your service account. For more details, see the sections below.

• Get OAuth Apps - Select to fetch the OAuth applications used by each user.

  Note

  This data requires an additional scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.user.security  For more information, see Configure the OAuth Scopes.

• Fetch Cloud Identity Devices - Select whether to fetch Cloud Identity devices.

  Note

  Fetching Cloud Identity devices requires:

  Adding the following scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/cloud-identity.devices.readonly

  It also requires enabling the Cloud Identity API. For more information, see Enable Cloud API and Configure the OAuth Scopes.

• Fetch Chrome Browsers - Select this option to fetch Chrome browsers information.

  Note

  Fetching Chrome browsers information requires an additional privilege to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly For more information, see Configure the OAuth Scopes.

• Fetch Calendars - Select this option to fetch users' calendars.

  Note

  Fetching calendar information requires an additional privilege to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/calendar It also requires enabling the Cloud Identity API.

  For more information, see Enable Cloud API and Configure the OAuth Scopes.

• Login URL -  The hostname or IP address of the Google server.  

• Proxy address - Connect the adapter to a proxy instead of directly connecting it to the domain.

• Proxy port - The port for the proxy server.

• Proxy username - The user name to use when connecting to the value supplied in Host Name or IP Address via the value supplied in Proxy address.

• Proxy password - The password to use when connecting to the server using the Proxy.

SaaS Management

• Account Profile Name - Google user name (https://admin.google.com/ac/accountsettings/profile).

• 2FA Secret Key - The secret generated in Google Workspace for setting up 2-factor authentication for the Google user created.

• Username - The value you enter in the User Name field in Google for the new user you created. 

• Password - The password you set for the new user in Google. 

• SSO provider - If your organization uses Google for SSO, you can set this select this check box (selected by default). For more information, see Connecting your SSO Solution Provider Adapter.

General

• Fetch MDM devices (required, default: true) - Select this option to fetch Mobile devices and Chrome OS devices from Google Workspace.

  Note

  Fetching MDM devices requires adding the following scopes to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.device.mobile.readonly https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly For more information, see Configure the OAuth Scopes.

• Cloud Identity prefer device with recent last seen if duplicated asset name - Select this option to save the device with the most recent Last Seen date under that asset name, when multiple instances of the same asset name are fetched from Cloud Identify.

• Fetch user groups - Select this option to fetch user group memberships for each user from Google Workspace.

  Note

  Fetching user groups requires adding the following scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.group.readonly. It also requires enabling the Group Settings API. For more information, see Enable Cloud API and Configure the OAuth Scopes.

•  Fetch User Roles - Select this option to fetch user roles for each user from Google Workspace. 

  Note

  Fetching user roles requires adding the following scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly For more information, see Configure the OAuth Scopes.

• Ignore Cloud Identity devices without serial - Select this option to ignore devices coming from Cloud Identity without Serial Numbers.

• Do not fetch disabled User Accounts (optional) - Select this option to exclude disabled user accounts from the fetch.

• Fetch Disk Usage - Select to fetch the amount of disk storage space used by each Google account.

  Note

  Fetching disk usage requires adding the following scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.reports.usage.readonly It also requires enabling the Service Usage API. For more information, see Enable Cloud API and Configure the OAuth Scopes.

• Use Hostname as Asset Name for Cloud Identity Devices - Select this option to use the host name as the asset name, when the host name exists.

Cyber-Security Asset Management

• When Possible - Use Annotation ID as Asset Name - Populate the asset name with the value of the Annotation ID (when the value exists) instead of using the value in the Name field.

SaaS Management

• Fetch Applications -  Select this option to fetch application information from Android devices as "Installed Software"

• Fetch extensions - Select to fetch instances of Google granting access permissions to other SaaS or native applications.

  Note

  Fetching extensions requires adding the following scope to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.user.security For more information, see Configure the OAuth Scopes.

• Fetch Licenses - Select to fetch Google licenses in your organization.

• Fetch Settings (Policies) - Select to fetch settings configured for the Google accounts in your organization.

  Note

  Fetching settings requires adding the following scopes to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/apps.groups.settings For more information, see Configure the OAuth Scopes.

• Fetch User Audit Logs - Select to fetch audit logs from Google.

Note:

Fetching user audit logs requires adding the following scopes to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.reports.audit.readonly For more information, see Configure the OAuth Scopes.