Google Workspace (G Suite)

Google Workspace (formerly G Suite) is a collection of cloud computing, productivity, collaboration, device, user, and data management tools developed by Google.

Types of Assets Fetched

This adapter fetches the following types of assets:

• Devices
• Users
• SaaS data

Parameters

1. Email of an admin account to impersonate(required) - The email of your Google Workspace (G Suite) admin.
2. Account Profile Name - Google user name for retrieving SaaS data. https://admin.google.com/ac/accountsettings/profile
3. 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.
4. Get OAuth Apps- Select to fetch the OAuth applications used by each user.
   Note

   This data requires the following additional privilege to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.user.security
5. Fetch Cloud Identity Devices - Select whether to fetch Cloud Identity devices.
   • If enabled, the connection for this adapter will also fetch Cloud Identity devices.
   • If disabled, the connection for this adapter will not fetch Cloud Identity devices.
     Note

     Fetching Cloud Identity devices requires:

     • Cloud Identity API enabled.
     • Additional privilege to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/cloud-identity.devices.readonly
6. Fetch Chrome Browsers - Select whether to fetch Chrome browsers information.
   • If enabled, the connection for this adapter will fetch information about Chrome browsers.
   • If disabled, the connection for this adapter will not fetch information about Chrome browsers.
     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

7. Fetch Calendars - Select whether to fetch users' calendars.
8. 2FA Secret Key - The secret generated in Google Workspace for setting up 2-factor authentication for the Google user created for collecting SaaS Management data.
9. Username -  The value you enter in the User Name field in Google for the new user you created to allow Axonius to fetch SaaS Management data. 
10. Password - The password you set for the new user in Okta. 
11. Login URL -   The hostname or IP address of the Google server.  
12. 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.
13. To learn more about common adapter connection parameters and buttons, see Adding a New Adapter Connection.
    

Advanced Settings

1. Fetch MDM devices (required, default: true)   - Select this option to fetch Mobile devices and ChromeOS devices from Google Workspace.
2. Cloud Identity prefer device with recent last seen if duplicated asset name - Select whether in cases that more than one device with the same asset name is fetched from the Cloud Identify, the device with the most recent last seen will be saved under that asset name.

• If enabled, all connections for this adapter will not save all devices with the same asset name, only the device with the most recent last seen.
• If disabled, all connections for this adapter will save all devices with the same asset names.

1. Fetch user groups - Select whether to fetch user group memberships for each user from Google Workspace.

• If enabled, all connections for this adapter will fetch user group memberships for each user.
• If disabled, all connections for this adapter will not fetch user group memberships for each user.
  Note

  Fetching user group memberships requires an additional privilege to your Google Workspace (G Suite) admin account: https://www.googleapis.com/auth/admin.directory.group.readonly

1.  Fetch User Roles - Select whether to fetch user roles for each user from Google Workspace. 

• If enabled, all connections for this adapter will fetch user roles for each user.
• If disabled, all connections for this adapter will not fetch user roles for each user.

1. Ignore Cloud Identity devices without serial - Select whether to ignore devices coming from Cloud Identity without Serial Numbers.
2. Do not fetch disabled User Accounts(optional) - Select whether to exclude disabled user accounts from the fetch.
3. Fetch Disk Usage - 
4. Fetch extensions - Select to fetch instances of Google granting access permissions to other SaaS or native applications (only for accounts with SaaS Management capability). 
5. Fetch Licenses - Select to fetch Google licenses in your organization (only for accounts with SaaS Management capability). 
6. Fetch Settings (Policies) - Select to fetch settings configured for the Google accounts in your organization (only for accounts with SaaS Management capability). 
7. Fetch User Audit Logs (only for accounts with SaaS Management capability)
   • If enabled, all connections of this adapter will also fetch audit logs from Google.
   • If disabled, all connections of this adapter will not fetch audit logs from Google.

Adapter Integration Setup

To successfully connect this adapter, you need to complete the following steps:

1. Open the Google Workspace adapter
2. Create an SSO-excluded organizational unit
3. Create a user account
4. Enable or exclude 2-step verification
5. Enable Cloud API
6. Create a service account
7. Create a custom role and add it to the principal
8. Connect the adapter

Step 1: Opening the Google Workspace Adapter

To begin connecting the Google Workspace adapter, you need to open the adapter.

1. On the left navigation panel, click Adapters.
2. Use the Search bar to locate the Google Workspace adapter.
3. Click the Google Workspace  adapter to open it.
4. Click Add Connection.

Step 2: Create an SSO-Excluded Organizational Unit

Before you create a Google user to connect Axonius with Google Workspace, you'll need to create an OU that's excluded from the SSO as a container for the user. 

1. In the Google Workspace Admin Console, from the navigation menu, navigate to Directory > Organizational Unit.
2. Click Create new organizational unit.
   
   
3. Enter a Name for the Organization unit (for example, Axonius SaaS Management).
4. Click Create.
   
5. From the left navigation menu, navigate to Security > Authentication > SSO with third party IdP.
6. In the Manage SSO profile assignments section, click Get Started or Manage.
   
7. In the Manage SSO profile assignments page, on the left pane, expand the Organizational units section and select the organizational unit you just created.
   
8. Under SSO profile assignment, select None.
9. Click Override to save changes.
   

Step 3: Create a User Account

1. Set the user name:

   1. In the Google Workspace Admin Console, from the navigation menu, navigate to Directory > Users.

   2. Click Add new user.

   3. Enter a first name, last name, and primary email address in their corresponding fields.

   4. Copy the primary email that you entered.
      

   6. Back in Axonius, in the Username field, enter the user name and domain name using the format 'username@domainname'.
      For example: maria@axoniusgoogle.com
      
      
      
      

2. Set the user's password:

   1. Click Manage user's password, organizational unit, and profile photo.
      
      

   2. In the Organizational unit field click .

   3. Select the newly created organizational unit and click Done.

   4. Select Create password.

   5. Enter a strong password.

      NOTE

      It's best practice for the password to contain 32 characters.
3. Clear the Ask user to change their password when they sign in checkbox.
4. Click Add New User.
   
5. Click Copy Password.
6. Click Done.
   
7. In Axonius, paste the value into the Password field.
   
8. Back in Google Workspace, refresh the page.
9. Set the permission level:

   • Locate and click the user you just created to open their user record.Under the Admin roles and privileges section, click Assign Roles.
     Click the Super Admin toggle to set it to Assigned.
     
     
     NOTE
     If your organization's security policy does not allow for providing Axonius Super Admin access to your Google environment, you can follow the instructions at the end of this guide to set up a Least-Privileged role instead.
     
     
     
     
     
     

     1. Click Save.
        

Step 4: 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.
   

Step 5: Enable Cloud API

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. Group Settings API
      

Step 6: 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.

4. 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. 

5. Configure the OAuth scopes:

   1. From the Details tab, click Advanced settings.

   2. Click to copy the the Client ID, and then click View Google Workspace Admin Console.
      

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

   4. Click Manage Domain Wide Delegation.

   5. Click Add New.
      

   6. 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):
      • Required scopes:
        
        
        MarkupMarkup

        https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly

        
        
      • Required scopes for SaaS Management:
        MarkupMarkup

        https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/apps.licensing,https://www.googleapis.com/auth/apps.groups.settings
        https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/apps.licensing,https://www.googleapis.com/auth/apps.groups.settings

      • Additional scope to fetch OAuth applications (Included in the SaaS Management scopes):
        MarkupMarkup

        https://www.googleapis.com/auth/admin.directory.user.security
        

        
        
      • Additional scope to fetch Cloud Identity devices:
        
        
        MarkupMarkup

        https://www.googleapis.com/auth/cloud-identity.devices.readonly

      • Additional scope to fetch Chrome browsers information (Included in the SaaS Management scopes):
        
        
        MarkupMarkup

        https://www.googleapis.com/auth/admin.directory.device.chromebrowsers.readonly

      • Additional scope to fetch user group memberships (Included in the SaaS Management scopes):
        
        
        MarkupMarkup

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

      • Additional scope to fetch Google Calendar:
        
        
        MarkupMarkup

        https://www.googleapis.com/auth/calendar

        
        
   8. Click Authorize.
      

Step 7: 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.

Step 8: 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 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 Step 5: 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
   • Google Data 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 and classic Hangouts > 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.