Google Workspace + Steampipe

Google Workspace is a collection of cloud computing, productivity and collaboration tools, software and products developed and marketed by Google.

Steampipe is an open-source zero-ETL engine to instantly query cloud APIs using SQL.

For example:

select
  summary,
  hangout_link,
  start_time,
  end_time
from
  googleworkspace_calendar_my_event
where
  start_time > now() :: timestamp
  and end_time < ('now' :: timestamp + interval '1 day');

+----------------+--------------------------------------+---------------------+---------------------+
| summary        | hangout_link                         | start_time          | end_time            |
+----------------+--------------------------------------+---------------------+---------------------+
| Product Review | https://meet.google.com/ris-zooa-rxo | 2021-08-18 12:30:00 | 2021-08-18 13:00:00 |
+----------------+--------------------------------------+---------------------+---------------------+

Documentation

Table definitions & examples →

Get started

Install

Download and install the latest Google Workspace plugin:

steampipe plugin install googleworkspace

Credentials

Item	Description
APIs	1. Go to the Google API Console. 2. Select the project that contains your credentials. 3. Click `Enable APIs and Services`. 4. Enable: `Google Calendar API`, `Google Drive API`, `Gmail API`, `Google People API`.
Credentials	1. To use domain-wide delegation, generate your service account and credentials and delegate domain-wide authority to your service account. Enter the following OAuth 2.0 scopes for the services that the service account can access: `https://www.googleapis.com/auth/calendar.readonly`, `https://www.googleapis.com/auth/contacts.readonly`, `https://www.googleapis.com/auth/contacts.other.readonly`, `https://www.googleapis.com/auth/directory.readonly`, `https://www.googleapis.com/auth/drive.readonly`, `https://www.googleapis.com/auth/gmail.readonly` 2. To use OAuth client, configure your credentials.
Radius	Each connection represents a single Google Workspace account.
Resolution	1. Credentials from the JSON file specified by the `credentials` parameter in your Steampipe config. 2. Credentials from the JSON file specified by the `token_path` parameter in your Steampipe config. 3. Credentials from the default json file location (`~/.config/gcloud/application_default_credentials.json`).

Configuration

Installing the latest googleworkspace plugin will create a config file (~/.steampipe/config/googleworkspace.spc) with a single connection named googleworkspace:

connection "googleworkspace" {
  plugin = "googleworkspace"

  # You may connect to Google Workspace using more than one option:
  # 1. To authenticate using domain-wide delegation, specify a service account credential file and the user email for impersonation
  # `credentials` - Either the path to a JSON credential file that contains Google application credentials,
  # or the contents of a service account key file in JSON format. If `credentials` is not specified in a connection,
  # credentials will be loaded from:
  #   - The path specified in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, if set; otherwise
  #   - The standard location (`~/.config/gcloud/application_default_credentials.json`)
  #   - The path specified for the credentials.json file ("/path/to/my/creds.json")
  # credentials = "~/.config/gcloud/application_default_credentials.json"
  # `impersonated_user_email` - The email (string) of the user which should be impersonated. Needs permissions to access the Admin APIs.
  # `impersonated_user_email` must be set, since the service account needs to impersonate a user with Admin API permissions to access the workspace services.
  # impersonated_user_email = "username@domain.com"

  # 2. To authenticate using OAuth 2.0, specify a client secret file
  # `token_path` - The path to a JSON credential file that contains Google application credentials.
  # If `token_path` is not specified in a connection, credentials will be loaded from:
  #   - The path specified in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, if set; otherwise
  #   - The standard location (`~/.config/gcloud/application_default_credentials.json`)
  # token_path = "~/.config/gcloud/application_default_credentials.json"
}

Advanced configuration options

Authenticate using OAuth client

You can use client secret credentials to protect the user's data by only granting tokens to authorized requestors. Use following steps to configure credentials:

Configure the OAuth consent screen.
Create an OAuth client ID credential with the application type Desktop app, and download the client secret JSON file.

Wherever you have the Google Cloud SDK installed, run the following command with the correct client secret JSON file parameters:

gcloud auth application-default login \
  --client-id-file=client_secret.json \
  --scopes="\
https://www.googleapis.com/auth/calendar.readonly,\
https://www.googleapis.com/auth/contacts.other.readonly,\
https://www.googleapis.com/auth/contacts.readonly,\
https://www.googleapis.com/auth/directory.readonly,\
https://www.googleapis.com/auth/drive.readonly,\
https://www.googleapis.com/auth/gmail.readonly"

In the browser window that just opened, authenticate as the user you would like to make the API calls through.
Review the output for the location of the Application Default Credentials file, which usually appears following the text Credentials saved to file:.
Set the Application Default Credentials filepath in the Steampipe config token_path or in the GOOGLE_APPLICATION_CREDENTIALS environment variable.

Postgres FDW

This plugin is available as a native Postgres FDW. Unlike Steampipe CLI, which ships with an embedded Postgres server instance, the Postgres FDW can be installed in any supported Postgres database version.

You can download the tarball for your platform from the Releases page, but it is simplest to install them with the steampipe_postgres_installer.sh script:

/bin/sh -c "$(curl -fsSL https://steampipe.io/install/postgres.sh)" -- googleworkspace

The installer will prompt you for the plugin name and version, download and install the appropriate files for your OS, system architecture, and Postgres version.

To configure the Postgres FDW, you will create an extension, foreign server, and schema and import the foreign schema.

CREATE EXTENSION IF NOT EXISTS steampipe_postgres_googleworkspace;
CREATE SERVER steampipe_googleworkspace FOREIGN DATA WRAPPER steampipe_postgres_googleworkspace OPTIONS (config '<your_config>');
CREATE SCHEMA googleworkspace;
IMPORT FOREIGN SCHEMA googleworkspace FROM SERVER steampipe_googleworkspace INTO googleworkspace;

SQLite Extension

This plugin is available as a SQLite Extension, making the tables available as SQLite virtual tables.

You can download the tarball for your platform from the Releases page, but it is simplest to install them with the steampipe_sqlite_installer.sh script:

/bin/sh -c "$(curl -fsSL https://steampipe.io/install/sqlite.sh)" -- googleworkspace

The installer will prompt you for the plugin name, version, and destination directory. It will then determine the OS and system architecture, and it will download and install the appropriate package.

To configure the SQLite extension, load the extension module and then run the steampipe_configure_googleworkspace function to configure it with plugin-specific options.

$ sqlite3
sqlite> .load ./steampipe_sqlite_extension_googleworkspace.so
sqlite> select steampipe_configure_googleworkspace('<your_config>');

Export

This plugin is available as a standalone Export CLI. Steampipe exporters are stand-alone binaries that allow you to extract data using Steampipe plugins without a database.

You can download the tarball for your platform from the Releases page, but it is simplest to install them with the steampipe_export_installer.sh script:

/bin/sh -c "$(curl -fsSL https://steampipe.io/install/export.sh)" -- googleworkspace

You can pass the configuration to the command with the --config argument:

steampipe_export_googleworkspace --config '<your_config>' <table_name>