Skip to main content

Query Google Workspace

Use cnquery to inventory and query your Google Workspace environment.

Before you begin​

Be sure you have the required access:

Create a Google Cloud service account​

note

These steps for configuring Admin SDK API access to your Google Workspace environment rely on Google Cloud (GCP) even if you aren't otherwise using GCP.

Step A: Create a Google Cloud Project​

  1. Go to Google Cloud and sign in as a super administrator. If it's your first time signing into the console, agree to the terms of service.

  2. From the Google Cloud menu, select IAM & Admin > Manage Resources.

  3. At the top, select Create Project and enter a project name (such as Mondoo Security Scan).

    If you want, you can add the project to a folder: For Location, select Browse, navigate to the folder, and choose Select.

  4. Select Create.

Step B: Enable the required APIs to scan Google Workspace​

  1. From the Google Cloud menu, select APIs & Services > Library.

  2. For each of these APIs, select the API name and then select Enable:

    • Admin SDK
    • Google Calendar API
    • Contacts API
    • Gmail API
    • Groups Migration API
    • Cloud Identity API
    • Google Drive API
tip

If you don't see the API you need, type its name in the search box.

  1. From the Google Cloud menu, select APIs & Services > OAuth consent screen.

  2. For User Type, select Internal.

  3. Select Create.

  4. For App name, enter "Mondoo Security Scanner" or another name that makes sense for your organization.

  5. For Authorized Domains, select + ADD DOMAIN and enter your domain configured in Google Workspace.

  6. Select a User support email for users to contact with questions.

  7. For Developer contact information, enter email addresses so Google can contact you about changes to your project.

  8. Select Save and Continue > Save and then select Continue > Back to Dashboard.

Step D: Create the service account​

  1. From the Google Cloud menu, select APIs & Services > Credentials.

  2. Select Create Credentials > Service account.

  3. For Service account name, enter "mondoo-security-scanner" or another name that makes sense for your organization.

    If you want, you can also add a Service account description.

  4. Select Create and select Continue.

  5. Select Done > Save.

  6. At the top, select Key > Add Key > Create new key.

  7. Make sure the key type is set to JSON, then select Create. You see a message that the service account's private key JSON file was downloaded to your computer. Note the file name and where your browser saves it. You need it for later steps.

  8. Select Close.

    Google Service Account Client ID

  9. Record the OAuth 2 / Client ID from the list of service accounts. You need that for the next step.

Configure domain-wide delegation in Google Workspace Admin Console​

In this next section you configure domain-wide delegation in Google Workspace Admin console to give your new service account the access it needs the Google Workspace APIs.

  1. Log into the Google Workspace Admin Console.

  2. In the left-side navigation, select Security > Access and data control > API controls.

  3. Select Domain-wide Delegation and then select Add new.

  4. For the Client ID, enter the client ID your recorded in Step D above.

  5. For OAuth Scopes, paste this comma-delimited list to add all 16 read-only OAuth scopes:

    https://www.googleapis.com/auth/admin.chrome.printers.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.orgunit.readonly,https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly,https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly,https://www.googleapis.com/auth/admin.directory.user.alias.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.userschema.readonly,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/cloud-identity.groups.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events,https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/calendar.settings.readonly

  6. Select Authorize.

Super admin role email​

To use your Google Cloud service account with domain-wide delegation, you must specify a super admin role email to impersonate when authenticating to the API.

In the Google Workspace Admin Console, navigate to Account > Admin Roles and select Super Admins. Record the email address for the Super Admin you want to use when authenticating.

To learn more about super admin roles, read Prebuilt administrator roles in the Google Workspace documentation.

Record your Google Workspace customer ID​

Navigate to Account > Account Settings and record the Customer ID. You need the customer ID to configure hosted scanning in Mondoo Platform, or to use locally with cnspec or cnquery.

Google Workspace Customer ID

Use cnquery shell to test your configuration​

To test proper configuration, use the cnquery shell to run a sample query:

cnquery shell google-workspace --customer-id 5amp13iD --impersonated-user-email admin@domain.com --credentials-path /home/user/my-project-6646123456789.json
For...Substitute...
--impersonated-user-emailThe email address of a user that has super admin privileges
--credentials-pathThe path to the downloaded JSON credentials file

cnquery returns results similar to these:

cnquery> googleworkspace.users
googleworkspace.users: [
  0: {
    primaryEmail: "alice@smith.family"
  }
  1: {
    primaryEmail: "betty@smith.family"
  }
  ....

If you prefer, you can use any of these environment variables to provide the credentials file. They're listed in order of precedence:

  • GOOGLE_APPLICATION_CREDENTIALS
  • GOOGLEWORKSPACE_CREDENTIALS
  • GOOGLEWORKSPACE_CLOUD_KEYFILE_JSON
  • GOOGLE_CREDENTIALS
note

If any of the variables above and the --credentials-path parameter are both present, the environment variable takes precedence.

Example queries​

Display details for the first user in the workspace:

cnquery> googleworkspace.users[0]{ * }
googleworkspace.users[0]: {
  isMailboxSetup: true
  familyName: "Smith"
  suspensionReason: ""
  recoveryEmail: ""
  archived: false
  aliases: []
  isAdmin: false
  lastLoginTime: 2023-01-03 20:45:12 +0000 UTC
  agreedToTerms: true
  suspended: false
  isEnrolledIn2Sv: false
  fullName: "Alice Smith"
  recoveryPhone: ""
  primaryEmail: "alice@smith.family"
  givenName: "Alice"
  id: "1182761XXXXXXXXX"
  tokens: [
  0: googleworkspace.token displayText="iOS Account Manager"
  1: googleworkspace.token displayText="Facetune2"
  2: googleworkspace.token displayText="YouTube on TV"
  3: googleworkspace.token displayText="Discord"
  4: googleworkspace.token displayText="Google Chrome"
  5: googleworkspace.token displayText="Epic Games, Inc."
  6: googleworkspace.token displayText="the-game-awards"
  ]
  creationTime: 2021-11-30 04:31:25 +0000 UTC
  isEnforcedIn2Sv: false
  usageReport: googleworkspace.report.usage id = googleworkspace.report.usage/C013XXXXXX/118276124783XXXXXXXXX/2023-01-03
}

Notice that usageReport is listed in this example output. This provides access to several reports with more useful user data that you can also check.

For example, this retrieves the first user in the workspace's account usage data:

cnquery> googleworkspace.users[0].usageReport.account
googleworkspace.users[0].usageReport.account: {
  adminSetName: "Alice Smith"
  driveUsedQuotaInMb: 231.000000
  gmailUsedQuotaInMb: 39.000000
  is2SvEnforced: false
  isDisabled: false
  isLessSecureAppsAccessAllowed: false
  isS2SvEnrolled: false
  isSuperAdmin: false
  passwordLengthCompliance: "COMPLIANT"
  passwordStrength: "STRONG"
  usedQuotaInMb: 270.000000
}

Learn more​