Skip to main content

Google Cloud Integration

Google Cloud logo

This page provides a comprehensive guide for integrating Google Cloud services with Timbr’s ontology-based semantic layer.

Timbr operates as a virtual knowledge graph over existing data sources, enabling the semantic layer to securely expose business entities, relationships, and logic across Google Cloud services, BI tools, and AI systems.

This includes configuring Google Cloud Single Sign-On (SSO) using OAuth 2.0 and OpenID Connect, enabling BigQuery token-based authentication for user-specific data access, and integrating with Google Analytics.

Table of Contents​

  1. Google Cloud Single Sign-On (SSO)
  2. BigQuery Token Authentication
  3. Google Analytics Integration

Google Cloud Single Sign-On (SSO)​

Configure Google Cloud as a Single Sign-On (SSO) provider for the Timbr platform using OAuth 2.0 and OpenID Connect.

Prerequisites​

Before you begin, ensure you have:

  • Administrative access to your Google Cloud Console
  • Administrative access to the Timbr platform server to configure environment variables
  • Your Timbr domain URL (e.g., https://timbr.example.com)
  • An HTTPS endpoint (Google Cloud SSO doesn't allow configuring HTTP servers)
  • An existing SSL certificate configured for the Timbr Platform service

Step 1: Create a Google Cloud Project (if needed)​

If you don't already have a Google Cloud project:

  1. Navigate to Google Cloud Console
  2. Click the project dropdown at the top of the page
  3. Click New Project
  4. Enter a project name (e.g., "Timbr Platform")
  5. Click Create

Step 2: Enable Required APIs​

  1. In the Google Cloud Console, navigate to APIs & Services > Library
  2. Search for and enable the following APIs:
    • Google+ API (for user profile information)
    • People API (for user information access)
  1. Navigate to APIs & Services > OAuth consent screen
  2. Select the User Type:
    • Internal: For Google Workspace organizations (users within your domain only)
    • External: For allowing any Google account
  3. Click Create
  4. Configure the consent screen:
    • App name: Timbr Platform (or your preferred name)
    • User support email: Select your email address
    • App logo: (Optional) Upload your organization's logo
    • Application home page: https://<your-timbr-domain>
    • Authorized domains: Add your Timbr domain (e.g., timbr.example.com)
    • Developer contact information: Enter your email address
  5. Click Save and Continue

Configure Scopes​

  1. On the Scopes page, click Add or Remove Scopes
  2. Add the following scopes:
    • .../auth/userinfo.email - View your email address
    • .../auth/userinfo.profile - See your personal info
    • openid - Authenticate using OpenID Connect
  3. Click Update and then Save and Continue

Test Users (External Apps Only)​

If you selected External user type and your app is in testing mode:

  1. Click Add Users

  2. Enter the email addresses of users who should have access during testing

  3. Click Save and Continue

  4. Review the summary and click Back to Dashboard

Step 4: Create OAuth 2.0 Credentials​

  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Application type: Web application
  4. Configure the following settings:
    • Name: Timbr Platform OAuth Client (or your preferred name)
    • Authorized JavaScript origins: (Optional) Add https://<your-timbr-domain>
    • Authorized redirect URIs: https://<your-timbr-domain>/oauth-authorized/google
      • Replace <your-timbr-domain> with your actual Timbr domain
  5. Click Create

Step 5: Collect OAuth Client Credentials​

After creating the OAuth client:

  1. A dialog will appear with your credentials
  2. Copy the Client ID - this will be your OAUTH_CLIENT_ID
  3. Copy the Client Secret - this will be your OAUTH_SECRET
  4. Click OK
Keep Credentials Secure

Store your client secret securely. Never commit it to version control or share it publicly.

Retrieving Credentials Later

You can always view your OAuth credentials by clicking on the client name in the Credentials page.

Step 6: Configure Timbr Environment Variables​

Add the Google OAuth environment variables to your timbr-platform service configuration.

Required Environment Variables​

# Provider identifier
OAUTH_PROVIDER=google

# Client ID from Google Cloud Console
OAUTH_CLIENT_ID=<GOOGLE_CLOUD_CLIENT_ID>

# Client Secret from Google Cloud Console
OAUTH_SECRET=<GOOGLE_CLOUD_CLIENT_SECRET>

# BigQuery token authentication (set to false unless using BigQuery with user tokens)
USE_BIGQUERY_TOKEN=false
BigQuery Token Authentication

Set USE_BIGQUERY_TOKEN=true only if you're using BigQuery as a datasource and want to authenticate per user. See the BigQuery Token Authentication section for more details.

Deployment Options​

Docker Compose​

Add the OAuth environment variables to your timbr-platform service in docker-compose.yml:

services:
  timbr-platform:
    # ...
    environment:
      - OAUTH_PROVIDER=google
      - OAUTH_CLIENT_ID=<GOOGLE_CLOUD_CLIENT_ID>
      - OAUTH_SECRET=<GOOGLE_CLOUD_CLIENT_SECRET>
      - USE_BIGQUERY_TOKEN=false

After updating your docker-compose.yml, restart the timbr-platform service:

sudo docker-compose up -d timbr-platform
Kubernetes​

Add the OAuth environment variables to your timbr-platform Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: timbr-platform
  namespace: default
spec:
  template:
    spec:
      containers:
        - name: timbr-platform
          # ...
          env:
            # ...
            - name: OAUTH_PROVIDER
              value: google
            - name: OAUTH_CLIENT_ID
              value: <GOOGLE_CLOUD_CLIENT_ID>
            - name: OAUTH_SECRET
              value: <GOOGLE_CLOUD_CLIENT_SECRET>
            - name: USE_BIGQUERY_TOKEN
              value: "false"

Apply the updated manifest:

kubectl apply -f timbr-platform.yaml
Using Kubernetes Secrets

For better security in Kubernetes, store sensitive values like OAUTH_CLIENT_ID and OAUTH_SECRET in Kubernetes Secrets instead of plain text in the manifest:

- name: OAUTH_SECRET
  valueFrom:
    secretKeyRef:
      name: google-oauth-secret
      key: client-secret

Optional Environment Variables​

# Enable user self-registration on first OAuth login (default: false)
AUTH_USER_REGISTRATION=true

# Default role for self-registered users (default: viewer)
AUTH_USER_REGISTRATION_ROLE=viewer

# Allow or disable username/password login alongside OAuth (default: true)
AUTH_WITH_USERPASS=true

# Default scheme for OAuth redirects (default: https)
OAUTH_DEFAULT_SCHEME=https

Step 7: Test the Integration​

  1. Navigate to your Timbr platform URL (e.g., https://timbr.example.com)
  2. You should see an option to Sign in with Google (or similar)
  3. Click the sign-in button
  4. Select your Google account and authorize the application
  5. Grant the requested permissions
  6. After successful authentication, you should be redirected back to the Timbr platform
First-Time Login

If AUTH_USER_REGISTRATION=true, new users will be automatically created on their first login with the role specified in AUTH_USER_REGISTRATION_ROLE.

Troubleshooting​

"Redirect URI mismatch" error:

  • Verify the redirect URI in Google Cloud Console exactly matches: https://<your-timbr-domain>/oauth-authorized/google
  • Ensure there are no trailing slashes or typos
  • The domain must match exactly, including protocol (https)

"Access blocked: This app's request is invalid" error:

  • Ensure the OAuth consent screen is properly configured
  • Verify required scopes are added
  • If using External user type in testing mode, ensure the user is added to test users

Users can't sign in:

  • Check that the SSL certificate is valid and not expired
  • Verify OAUTH_PROVIDER=google is set correctly
  • Ensure the client ID and secret are correct
  • Check Timbr platform logs for specific error messages

BigQuery Token Authentication​

Enable per-user authentication for Google BigQuery datasources, allowing users to query BigQuery with their own credentials and permissions.

Overview​

When enabled, BigQuery token authentication allows:

  • User-specific access: Each user queries BigQuery with their own Google Cloud credentials
  • Fine-grained permissions: Users see only the data they have access to in BigQuery
  • Audit trail: Track which users execute which queries
  • No shared credentials: Eliminates the need for a shared service account

Prerequisites​

  • Google Cloud SSO must be configured (see section above)
  • BigQuery API enabled in your Google Cloud project
  • Users must have appropriate BigQuery permissions in Google Cloud
  • Administrative access to Timbr platform configuration

Step 1: Enable BigQuery API​

  1. In the Google Cloud Console, navigate to APIs & Services > Library
  2. Search for BigQuery API
  3. Click Enable (if not already enabled)

Step 2: Configure OAuth Scopes​

When creating or editing your OAuth client (from the SSO setup):

  1. Navigate to APIs & Services > OAuth consent screen

  2. Click Edit App

  3. On the Scopes page, add the following BigQuery-specific scope:

    • .../auth/bigquery - View and manage your data in Google BigQuery

    Or for read-only access:

    • .../auth/bigquery.readonly - View data in Google BigQuery

  4. Click Update and Save and Continue

Scope Permissions

Choose the appropriate scope based on your requirements:

  • Use .../auth/bigquery if users need to create or modify BigQuery resources
  • Use .../auth/bigquery.readonly if users only need to read data

Step 3: Update Timbr Platform Configuration​

Enable BigQuery token authentication by setting the environment variable:

USE_BIGQUERY_TOKEN=true

Deployment Options​

Docker Compose​

Update your timbr-platform service in docker-compose.yml:

services:
  timbr-platform:
    # ...
    environment:
      - OAUTH_PROVIDER=google
      - OAUTH_CLIENT_ID=<GOOGLE_CLOUD_CLIENT_ID>
      - OAUTH_SECRET=<GOOGLE_CLOUD_CLIENT_SECRET>
      - USE_BIGQUERY_TOKEN=true  # Changed from false to true

Restart the service:

sudo docker-compose up -d timbr-platform
Kubernetes​

Update your timbr-platform Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: timbr-platform
spec:
  template:
    spec:
      containers:
        - name: timbr-platform
          # ...
          env:
            # ...
            - name: USE_BIGQUERY_TOKEN
              value: "true"  # Changed from "false" to "true"

Apply the manifest:

kubectl apply -f timbr-platform.yaml

Step 4: Configure BigQuery Datasource in Timbr​

Add or configure a BigQuery datasource in the Timbr platform:

  1. Navigate to Datasources in the Timbr Platform

  2. Click Add New Datasource (or edit an existing BigQuery datasource)

  3. Configure with the following settings:

    • Datasource Type: BigQuery
    • Datasource Name: bigquery (or your preferred name)
    • Project ID: Your Google Cloud project ID
    • Dataset: (Optional) Default dataset name
    • Authentication: The user's OAuth token will be used automatically

  4. Click Test Connection to verify the configuration

  5. Click Save

How It Works​

  1. User authenticates to Timbr using Google Cloud SSO
  2. Timbr obtains an OAuth token with BigQuery access scope
  3. When querying BigQuery, Timbr uses the user's token to authenticate
  4. BigQuery executes the query with the user's permissions
  5. Results are returned based on what the user has access to

Grant BigQuery Permissions to Users​

To allow users to access specific BigQuery datasets and tables:

  1. In Google Cloud Console, navigate to BigQuery
  2. Select the dataset you want to grant access to
  3. Click Share > Permissions
  4. Click Add Principal
  5. Enter the user's email address
  6. Select an appropriate role:
    • BigQuery Data Viewer: Read-only access to data
    • BigQuery Data Editor: Read and write access to data
    • BigQuery User: Can run queries and jobs
  7. Click Save
IAM Roles

You can also grant permissions at the project level via IAM & Admin > IAM if you want users to have broader access.

Benefits​

  • Enhanced security: No shared credentials or service accounts
  • Access control: Leverage existing Google Cloud IAM permissions
  • Compliance: User actions are auditable through Google Cloud logs
  • Simplified management: Manage access in one place (Google Cloud IAM)

Troubleshooting​

"Permission denied" errors:

  • Verify the user has appropriate BigQuery permissions in Google Cloud
  • Check that the BigQuery API is enabled
  • Ensure the OAuth scope includes BigQuery access

Token expiration:

  • OAuth tokens expire after a certain period
  • Users may need to re-authenticate by logging out and back in
  • Consider implementing token refresh mechanisms if needed

Missing datasets or tables:

  • Verify the user has been granted access to the specific datasets
  • Check that the project ID is correct in the datasource configuration

Google Analytics Integration​

Connect the Timbr Platform to Google Analytics to track user behavior and platform usage.

Prerequisites​

  • Google Analytics account
  • Google Analytics tracking ID (e.g., G-XXXXXXXXXX or UA-XXXXXXXXX-X)
  • Administrative access to Timbr platform configuration

Step 1: Create Google Analytics Property (if needed)​

If you don't already have a Google Analytics property:

  1. Sign in to Google Analytics
  2. Click Admin (gear icon in the lower left)
  3. In the Property column, click Create Property
  4. Enter property details:
    • Property name: Timbr Platform
    • Reporting time zone: Select your timezone
    • Currency: Select your currency
  5. Click Next and complete the setup
  6. For web-based properties, create a Data Stream:
    • Select Web
    • Website URL: Your Timbr domain (e.g., https://timbr.example.com)
    • Stream name: Timbr Platform
  7. Click Create stream
  8. Copy the Measurement ID (e.g., G-XXXXXXXXXX)

Step 2: Configure Timbr Platform​

Add the Google Analytics tracking ID to your timbr-platform service:

GOOGLE_ANALYTICS_TAG=<YOUR_GOOGLE_ANALYTICS_TAG>

Deployment Options​

Docker Compose​

Add to your timbr-platform service in docker-compose.yml:

services:
  timbr-platform:
    # ...
    environment:
      # ... (existing configuration)
      - GOOGLE_ANALYTICS_TAG=G-XXXXXXXXXX

Restart the service:

sudo docker-compose up -d timbr-platform
Kubernetes​

Add to your timbr-platform Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: timbr-platform
spec:
  template:
    spec:
      containers:
        - name: timbr-platform
          # ...
          env:
            # ...
            - name: GOOGLE_ANALYTICS_TAG
              value: G-XXXXXXXXXX

Apply the manifest:

kubectl apply -f timbr-platform.yaml

Step 3: Verify Integration​

  1. Navigate to your Timbr platform
  2. Perform some actions (page views, clicks, etc.)
  3. In Google Analytics, go to Reports > Realtime
  4. Verify that your activity is being tracked
Data Collection

It may take a few minutes for data to appear in Google Analytics. For detailed reports, wait 24-48 hours for data processing.

What Gets Tracked​

By default, Google Analytics will track:

  • Page views
  • User sessions
  • Geographic location
  • Browser and device information
  • User interactions (depending on your Timbr platform's analytics implementation)

Privacy Considerations​

When implementing Google Analytics:

  • Review your organization's privacy policy
  • Inform users about data collection
  • Consider implementing cookie consent mechanisms
  • Review Google Analytics data retention settings
  • Comply with GDPR, CCPA, and other privacy regulations
Privacy Compliance

Ensure your use of Google Analytics complies with relevant data protection regulations in your jurisdiction.

Additional Resources​

Support​

For additional assistance with Google Cloud integration, please contact Timbr support or refer to the main Timbr documentation.