Mondoo
Docs
CnquerySaas

Query Google Workspace

Query Google Workspace configuration with cnquery

Mondoo's google-workspace provider lets you use cnquery to query and inventory your Google Workspace environment. You can explore users, groups, domains, organizational units, roles, connected apps, calendars, and usage reports.

Requirements

To analyze your Google Workspace environment with cnquery, you must have:

Create a Google Cloud service account

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

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 the Google Workspace Admin Console to give your new service account the access it needs to 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 you recorded in Step D above.

  5. For OAuth Scopes, paste this comma-delimited list to add all required 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

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

Example queries

Users

List all users with key security fields:

cnquery> googleworkspace.users { primaryEmail fullName isAdmin suspended isEnrolledIn2Sv }
googleworkspace.users: [
  0: {
    primaryEmail: "alice@smith.family"
    fullName: "Alice Smith"
    isAdmin: true
    suspended: false
    isEnrolledIn2Sv: true
  }
  1: {
    primaryEmail: "betty@smith.family"
    fullName: "Betty Smith"
    isAdmin: false
    suspended: false
    isEnrolledIn2Sv: false
  }
  ...
]

Display all details for a specific user:

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
}

Groups

List all groups:

cnquery> googleworkspace.groups { name email directMembersCount adminCreated }
googleworkspace.groups: [
  0: {
    name: "Engineering"
    email: "engineering@smith.family"
    directMembersCount: 12
    adminCreated: true
  }
  1: {
    name: "All Staff"
    email: "all@smith.family"
    directMembersCount: 45
    adminCreated: true
  }
  ...
]

List members of a specific group:

cnquery> googleworkspace.groups[0].members { email type status }
googleworkspace.groups[0].members: [
  0: {
    email: "alice@smith.family"
    type: "USER"
    status: "ACTIVE"
  }
  1: {
    email: "betty@smith.family"
    type: "USER"
    status: "ACTIVE"
  }
  ...
]

Domains

List all domains and their verification status:

cnquery> googleworkspace.domains { domainName isPrimary verified }
googleworkspace.domains: [
  0: {
    domainName: "smith.family"
    isPrimary: true
    verified: true
  }
  ...
]

Roles

List all admin roles:

cnquery> googleworkspace.roles { name isSuperAdminRole isSystemRole }
googleworkspace.roles: [
  0: {
    name: "Super Admin"
    isSuperAdminRole: true
    isSystemRole: true
  }
  1: {
    name: "Groups Admin"
    isSuperAdminRole: false
    isSystemRole: true
  }
  ...
]

Organizational units

List organizational units:

cnquery> googleworkspace.orgUnits { name description }
googleworkspace.orgUnits: [
  0: {
    name: "Engineering"
    description: "Engineering department"
  }
  1: {
    name: "Marketing"
    description: "Marketing department"
  }
  ...
]

Connected apps

List third-party apps connected to the workspace:

cnquery> googleworkspace.connectedApps { name scopes }
googleworkspace.connectedApps: [
  0: {
    name: "Slack"
    scopes: [
      0: "https://www.googleapis.com/auth/calendar.readonly"
    ]
  }
  1: {
    name: "Zoom"
    scopes: [
      0: "https://www.googleapis.com/auth/calendar"
    ]
  }
  ...
]

Usage reports

Retrieve account usage data for a user, including storage quotas and security settings:

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

On this page

RequirementsCreate a Google Cloud service accountStep A: Create a Google Cloud ProjectStep B: Enable the required APIs to scan Google WorkspaceStep C: Set up the OAuth consent screenStep D: Create the service accountConfigure domain-wide delegation in Google Workspace Admin ConsoleSuper admin role emailRecord your Google Workspace customer IDUse cnquery shell to test your configurationExample queriesUsersGroupsDomainsRolesOrganizational unitsConnected appsUsage reportsLearn more