Valstorm Logo
ValstormDocs
Google•9 min read

Google Cloud Platform (GCP) Workspace Integration Setup Guide

title: Google Cloud Platform (GCP) Workspace Integration Setup Guide name: Google Cloud Platform (GCP) Workspace Integration Setup Guide slug: google-cloud-platform-gcp-workspace-integration-setup-guide category: Documentation sort_order: 1 is_public: false is_published: true seo_title: GCP Workspace Integration Setup Guide | Valstorm Docs seo_description: Complete guide to setting up Google Cloud Platform (GCP) project for Valstorm integrations, including OAuth 2.0, Gmail, Calendar, and Pub/Sub sync. tags:

  • gcp
  • google-workspace
  • oauth2
  • pubsub
  • integrations

This guide documents the complete end-to-end blueprint to initialize a Google Cloud Platform (GCP) project from scratch for Valstorm Google Workspace integrations (OAuth 2.0 User Authentication, Gmail Sync, Calendar Sync, Drive Events, and Cloud Pub/Sub push webhooks).

It details:

  1. Automated CLI Setup (gcloud / vsagent) — Creating project, linking billing, enabling all APIs, creating Pub/Sub topics, setting IAM publisher policies, and provisioning the Service Account.
  2. Manual Security Steps (Google Cloud Console) — Configuring the OAuth 2.0 Consent Screen, Scopes, and Web Client credentials (restricted by Google from automated API creation for security and domain verification reasons).
  3. Valstorm Platform Provisioning — Embedding the resulting OAuth and Service Account credentials into the tenant's environment_configuration.
  4. Automated Bash Script (setup_gcp_project.sh) — A single script to execute all automated steps.

Architecture Overview

┌───────────────────────────┐ │ Google Cloud Console │ │ (OAuth Consent Screen) │ └─────────────┬─────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ GCP Project: `valstorm-workspace-oauth` (or tenant project) │ │ │ │ ├── Enabled APIs: │ │ │ ├── Gmail API (`gmail.googleapis.com`) │ │ │ ├── Google Calendar API (`calendar-json.googleapis.com`) │ │ │ ├── Google Drive API (`drive.googleapis.com`) │ │ │ ├── Cloud Pub/Sub API (`pubsub.googleapis.com`) │ │ │ ├── Google Workspace Events API (`workspaceevents.googleapis.com`) │ │ │ └── People API / User Info (`people.googleapis.com`) │ │ │ │ │ ├── OAuth 2.0 Web Client (`client_secret_*.json`): │ │ │ ├── Auth Redirect: `https://api.valstorm.com/v1/google-workspace/oauth2callback` │ │ │ └── JavaScript Origins: `https://app.valstorm.com` │ │ │ │ │ ├── Cloud Pub/Sub Architecture: │ │ │ ├── Topic: `valstorm-gmail-push` │ │ │ ├── Topic IAM Policy: `serviceAccount:[email protected]` │ │ │ │ -> Role: `roles/pubsub.publisher` │ │ │ └── Push Subscription: `org_{org_id}_gmail_watcher` │ │ │ └── Target Endpoint: `https://api.valstorm.com/v1/google-workspace/pub-sub/{org}`│ │ │ │ │ └── Service Account (`valstorm-integration@{project}.iam.gserviceaccount.com`): │ │ ├── Roles: `roles/pubsub.admin`, `roles/workspaceevents.admin` │ │ └── Private Key: Stored in Valstorm `environment_configuration` │ └────────────────────────────────────────────────────────────────────────────────────────┘

1. Automated Setup Steps (gcloud CLI)

These steps are executed via the command line or wrapped in vsagent.

Step 1.1: Authentication & Project Initialization

BASH
# 1. Login with Admin credentials gcloud auth login # 2. Set environment variables export PROJECT_ID="valstorm-workspace-oauth" export PROJECT_NAME="Valstorm Workspace Integration" export BILLING_ACCOUNT_ID="YOUR-BILLING-ACCOUNT-ID" # e.g. 012345-6789AB-CDEF01 # 3. Create the project (omit --organization if using standalone account) gcloud projects create "${PROJECT_ID}" --name="${PROJECT_NAME}" # 4. Link billing account gcloud billing projects link "${PROJECT_ID}" --billing-account="${BILLING_ACCOUNT_ID}" # 5. Set active project gcloud config set project "${PROJECT_ID}"

Step 1.2: Enable Required APIs

Valstorm requires these 7 core APIs for full communication, calendar sync, storage, and push webhooks:

BASH
gcloud services enable \ gmail.googleapis.com \ calendar-json.googleapis.com \ drive.googleapis.com \ pubsub.googleapis.com \ workspaceevents.googleapis.com \ people.googleapis.com \ iam.googleapis.com \ cloudresourcemanager.googleapis.com \ --project="${PROJECT_ID}"

Step 1.3: Configure Cloud Pub/Sub Topics & IAM Bindings

For Gmail push notifications to work, Google's internal mail service account ([email protected]) must be explicitly granted publisher rights on the topic:

BASH
export TOPIC_NAME="valstorm-gmail-push" # 1. Create the central topic gcloud pubsub topics create "${TOPIC_NAME}" --project="${PROJECT_ID}" # 2. Grant Google Gmail Push Service Account publishing rights gcloud pubsub topics add-iam-policy-binding "${TOPIC_NAME}" \ --member="serviceAccount:[email protected]" \ --role="roles/pubsub.publisher" \ --project="${PROJECT_ID}"

Step 1.4: Provision the Platform Service Account

Create a service account with permissions to manage topics, create push subscriptions, and manage Workspace events:

BASH
export SA_NAME="valstorm-integration" export SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" # 1. Create Service Account gcloud iam service-accounts create "${SA_NAME}" \ --description="Valstorm Platform Service Account for PubSub and Workspace Automation" \ --display-name="Valstorm Integration" \ --project="${PROJECT_ID}" # 2. Grant Pub/Sub Admin gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/pubsub.admin" # 3. Grant Workspace Events Admin gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/workspaceevents.admin" # 4. Generate Service Account JSON Key file gcloud iam service-accounts keys create ./valstorm_service_account.json \ --iam-account="${SA_EMAIL}" \ --project="${PROJECT_ID}"

2. Manual Configuration (Google Cloud Console)

Google deliberately restricts the creation of OAuth 2.0 Consent Screens and Credentials via API to ensure explicit administrative verification, brand safety, and domain authorization.

  1. Navigate to: https://console.cloud.google.com/apis/credentials/consent?project={PROJECT_ID}
  2. Choose User Type:
  • Internal: Recommended if this GCP project is tied to your Google Workspace Organization (allows any internal employee to sign in immediately without Google verification).
  • External: Required if users from external email domains will sign in (requires submitting for Google verification for production use; add test users during development).
  1. Fill in App Information:
  1. Add Authorized Domains:
  • valstorm.com
  • Any custom domain your organization uses.
  1. Click Save and Continue.

Step 2.2: Add Required Scopes

On the Scopes step, click Add or Remove Scopes and select:

  • .../auth/userinfo.email
  • .../auth/userinfo.profile
  • openid
  • https://www.googleapis.com/auth/gmail.modify (Read, compose, send, and modify emails)
  • https://www.googleapis.com/auth/gmail.compose (Compose and draft emails)
  • https://www.googleapis.com/auth/gmail.labels (List and manage labels)
  • https://www.googleapis.com/auth/calendar.events (Manage calendar events)
  • https://www.googleapis.com/auth/drive (Access and sync Drive files)
  • https://www.googleapis.com/auth/pubsub (Manage Pub/Sub push notification subscriptions)

Click Update > Save and Continue.

Step 2.3: Create OAuth 2.0 Web Client Credentials

  1. Navigate to: https://console.cloud.google.com/apis/credentials?project={PROJECT_ID}
  2. Click + Create Credentials > OAuth client ID.
  3. Set Application type: Web application.
  4. Set Name: Valstorm Web Client.
  5. Add Authorized JavaScript origins:
https://app.valstorm.com
  1. Add Authorized redirect URIs:
https://api.valstorm.com/v1/google-workspace/oauth2callback
  1. Click Create.
  2. Click Download JSON and save as client_secret.json.

3. Registering Credentials in Valstorm

Once you have client_secret.json (OAuth) and valstorm_service_account.json (Service Account), insert or update them in the tenant's environment_configuration table.

3.1 OAuth Configuration Record (enco_...)

Insert into environment_configuration with name: Google Workspace:

JSON
{ "name": "Google Workspace", "category": "Integration", "config": { "web": { "client_id": "xxxxxx-xxxxxxxxxxxxxxxx.apps.googleusercontent.com", "project_id": "valstorm-workspace-oauth", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_secret": "GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx", "redirect_uris": [ "https://api.valstorm.com/v1/google-workspace/oauth2callback", ], "javascript_origins": [ "https://app.valstorm.com", ] } } }

3.2 Service Account Record (enco_...)

Insert into environment_configuration with name: Google Workspace Service Account - valstorm.com:

JSON
{ "name": "Google Workspace Service Account - valstorm.com", "category": "Integration", "config": { "type": "service_account", "project_id": "valstorm-workspace-oauth", "private_key_id": "xxxxxxxxxxxxxxxxxxxx", "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", "client_email": "valstorm-integration@valstorm-workspace-oauth.iam.gserviceaccount.com", "client_id": "xxxxxxxxxxxxxxxxxxxx", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/valstorm-integration%40valstorm-workspace-oauth.iam.gserviceaccount.com" } }

4. Complete Automation Script (setup_gcp_project.sh)

Save and run this script to automate all CLI steps in under 60 seconds:

BASH
#!/usr/bin/env bash set -euo pipefail # ============================================================================== # Valstorm GCP Workspace Initialization Script # ============================================================================== # Configurations (Modify as needed) PROJECT_ID="${1:-valstorm-workspace-oauth}" PROJECT_NAME="${2:-Valstorm Workspace Integration}" BILLING_ACCOUNT_ID="${3:-}" # Optional: provide as 3rd arg or link manually TOPIC_NAME="valstorm-gmail-push" SA_NAME="valstorm-integration" OUTPUT_DIR="./gcp_credentials" echo "==========================================================" echo "Initializing GCP Project: ${PROJECT_ID}" echo "==========================================================" # 1. Create or Verify Project if gcloud projects describe "${PROJECT_ID}" &>/dev/null; then echo "✅ Project '${PROJECT_ID}' already exists." else echo "🚀 Creating project '${PROJECT_ID}'..." gcloud projects create "${PROJECT_ID}" --name="${PROJECT_NAME}" echo "✅ Project created." fi # 2. Link Billing Account if provided if [-n "${BILLING_ACCOUNT_ID}"](-n "${BILLING_ACCOUNT_ID}"); then echo "💳 Linking billing account '${BILLING_ACCOUNT_ID}'..." gcloud billing projects link "${PROJECT_ID}" --billing-account="${BILLING_ACCOUNT_ID}" echo "✅ Billing linked." fi gcloud config set project "${PROJECT_ID}" # 3. Enable Required Google APIs echo "📦 Enabling required APIs..." gcloud services enable \ gmail.googleapis.com \ calendar-json.googleapis.com \ drive.googleapis.com \ pubsub.googleapis.com \ workspaceevents.googleapis.com \ people.googleapis.com \ iam.googleapis.com \ cloudresourcemanager.googleapis.com \ --project="${PROJECT_ID}" echo "✅ APIs enabled." # 4. Create Cloud Pub/Sub Topic echo "🔔 Provisioning Cloud Pub/Sub topic '${TOPIC_NAME}'..." if gcloud pubsub topics describe "${TOPIC_NAME}" --project="${PROJECT_ID}" &>/dev/null; then echo "✅ Topic '${TOPIC_NAME}' already exists." else gcloud pubsub topics create "${TOPIC_NAME}" --project="${PROJECT_ID}" echo "✅ Topic '${TOPIC_NAME}' created." fi # 5. Grant Gmail Push Service Account Publisher Rights echo "🔐 Granting IAM publish permission to Gmail push service..." gcloud pubsub topics add-iam-policy-binding "${TOPIC_NAME}" \ --member="serviceAccount:[email protected]" \ --role="roles/pubsub.publisher" \ --project="${PROJECT_ID}" echo "✅ Gmail publish permission granted." # 6. Create Service Account SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" echo "👤 Creating Service Account '${SA_EMAIL}'..." if gcloud iam service-accounts describe "${SA_EMAIL}" --project="${PROJECT_ID}" &>/dev/null; then echo "✅ Service account '${SA_EMAIL}' already exists." else gcloud iam service-accounts create "${SA_NAME}" \ --description="Valstorm Platform Service Account for Pub/Sub and Workspace Operations" \ --display-name="Valstorm Integration" \ --project="${PROJECT_ID}" echo "✅ Service account created." fi # 7. Grant Service Account Roles echo "🛡️ Assigning roles (pubsub.admin, workspaceevents.admin)..." gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/pubsub.admin" \ --quiet gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/workspaceevents.admin" \ --quiet echo "✅ Roles assigned." # 8. Export Service Account Key mkdir -p "${OUTPUT_DIR}" KEY_PATH="${OUTPUT_DIR}/${PROJECT_ID}_service_account.json" echo "🔑 Exporting Service Account Key to: ${KEY_PATH}..." gcloud iam service-accounts keys create "${KEY_PATH}" \ --iam-account="${SA_EMAIL}" \ --project="${PROJECT_ID}" echo "✅ Key generated." echo "" echo "==========================================================" echo "🎉 CLI Setup Complete!" echo "==========================================================" echo "Next Steps:" echo "1. Configure OAuth Consent Screen in Google Cloud Console:" echo " 👉 https://console.cloud.google.com/apis/credentials/consent?project=${PROJECT_ID}" echo "2. Create Web Application OAuth Client ID:" echo " 👉 https://console.cloud.google.com/apis/credentials?project=${PROJECT_ID}" echo "3. Save the Service Account key (${KEY_PATH}) and OAuth credentials into Valstorm environment_configuration." echo "=========================================================="

5. Verification Checklist

Before releasing to company users, run this 5-point verification:

  • APIs Enabled: gcloud services list --enabled --project={PROJECT_ID} includes gmail, calendar-json, drive, pubsub, workspaceevents.
  • Pub/Sub Topic Permissions: gcloud pubsub topics get-iam-policy valstorm-gmail-push --project={PROJECT_ID} contains serviceAccount:[email protected] as roles/pubsub.publisher.
  • Service Account Roles: valstorm-integration@{PROJECT_ID}.iam.gserviceaccount.com has roles/pubsub.admin.
  • OAuth Client Authorized URIs: https://api.valstorm.com/v1/google-workspace/oauth2callback is saved in Authorized Redirect URIs.
  • Valstorm Pub/Sub Manager: Clicking "Create Subscription" in Valstorm UI successfully returns: Successfully created Pub/Sub subscription on projects/{PROJECT_ID}/topics/valstorm-gmail-push pointing to https://api.valstorm.com/v1/google-workspace/pub-sub/{org_id}.