Google OAuth Setup

Configure Google OAuth to authenticate Stategraph users with their Google Workspace accounts.

Prerequisites

Google Cloud account
Google Cloud project
Admin access to configure OAuth consent screen

Step 1: Create OAuth Client

Open Google Cloud Console

Go to Google Cloud Console
Select your project (or create a new one)

Navigate to APIs & Services > OAuth consent screen
Select user type:
Internal: Only users in your Google Workspace organization
External: Any Google user (requires app verification for production)
Fill in the required fields:
App name: Stategraph
User support email: Your email
Developer contact: Your email
Click Save and Continue
Add scopes (optional, email and profile are included by default)
Complete the setup

Create OAuth Client ID

Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
Select Web application
Configure:
Name: Stategraph
Authorized redirect URIs: Add your callback URL

https://stategraph.example.com/oauth2/google/callback

For local development:

http://localhost:8080/oauth2/google/callback

Click Create
Copy the Client ID and Client Secret

Step 2: Configure Stategraph

Required Environment Variables

# Enable Google OAuth
STATEGRAPH_OAUTH_TYPE=google

# From Google Cloud Console
STATEGRAPH_OAUTH_CLIENT_ID=123456789-abc123.apps.googleusercontent.com
STATEGRAPH_OAUTH_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxx

# Your public URL
STATEGRAPH_UI_BASE=https://stategraph.example.com

Optional Environment Variables

# Restrict to specific domain
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com

# Custom login button text
STATEGRAPH_OAUTH_DISPLAY_NAME="Sign in with Google"

# Callback URL base (if different from UI base)
STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

Docker Compose Example

services:
  server:
    image: ghcr.io/stategraph/stategraph-server:<version>
    environment:
      DB_HOST: "db"
      DB_PORT: "5432"
      DB_USER: "stategraph"
      DB_PASS: "stategraph"
      DB_NAME: "stategraph"

      STATEGRAPH_UI_BASE: "https://stategraph.example.com"

      STATEGRAPH_OAUTH_TYPE: "google"
      STATEGRAPH_OAUTH_CLIENT_ID: "123456789-abc123.apps.googleusercontent.com"
      STATEGRAPH_OAUTH_CLIENT_SECRET: "${GOOGLE_CLIENT_SECRET}"
      STATEGRAPH_OAUTH_EMAIL_DOMAIN: "yourcompany.com"

Step 3: Verify Configuration

Test Authentication

Open Stategraph in your browser
You should see a login button
Click to authenticate with Google
After authentication, you should see the Stategraph UI

Check Logs

If authentication fails, check the server logs:

docker compose logs server

Look for oauth2-proxy messages indicating the issue.

Advanced Configuration

Google Groups Restriction

Restrict access to members of specific Google Groups:

# Google Group email
STATEGRAPH_OAUTH_GOOGLE_GROUP=stategraph-users@yourcompany.com

# Admin email for group lookup
STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL=admin@yourcompany.com

# Service account JSON for Google Admin API
STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON='{...}'

Setup Service Account

Create a service account in Google Cloud Console
Enable domain-wide delegation
Grant the service account these Admin SDK scopes:
https://www.googleapis.com/auth/admin.directory.group.readonly
Download the JSON key file
Set the JSON content as STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON

Configure Domain-Wide Delegation

Go to Google Admin Console
Navigate to Security > API Controls > Domain-wide Delegation
Add the service account client ID
Add scope: https://www.googleapis.com/auth/admin.directory.group.readonly

Multiple Domains

To allow multiple domains, use a comma-separated list or allow all:

# Allow all domains
STATEGRAPH_OAUTH_EMAIL_DOMAIN=*

# Note: Multiple specific domains require additional configuration

Troubleshooting

"redirect_uri_mismatch"

The redirect URI in your Google OAuth configuration doesn't match.

Solution: 1. Go to Google Cloud Console > APIs & Services > Credentials 2. Edit your OAuth client 3. Add the exact redirect URI: https://stategraph.example.com/oauth2/google/callback

"access_denied"

Google denied access to the application.

Causes: - User's email domain not in allowed list - User not in required Google Group - OAuth consent screen not approved for external users

Solutions: - Check STATEGRAPH_OAUTH_EMAIL_DOMAIN setting - Verify Google Group membership - For external users, complete app verification

"invalid_client"

The client ID or secret is incorrect.

Solution: - Verify the client ID and secret from Google Cloud Console - Check for extra whitespace or newlines

The session cookie may not be set correctly.

Causes: - STATEGRAPH_UI_BASE doesn't match the URL you're accessing - HTTPS/HTTP mismatch - Proxy stripping cookies

Solutions: - Verify STATEGRAPH_UI_BASE matches your URL exactly - Ensure consistent protocol (https) - Check proxy configuration

Google Groups not working

Service account configuration issues.

Checklist: - [ ] Service account created - [ ] Domain-wide delegation enabled - [ ] Admin email is a super admin - [ ] JSON key is valid - [ ] Scopes are delegated in Admin Console

Complete Example

Environment File (.env)

# Database
DB_HOST=db
DB_PORT=5432
DB_USER=stategraph
DB_PASS=your-secure-password
DB_NAME=stategraph

# Stategraph
STATEGRAPH_UI_BASE=https://stategraph.example.com

# Google OAuth
STATEGRAPH_OAUTH_TYPE=google
STATEGRAPH_OAUTH_CLIENT_ID=123456789-abc123.apps.googleusercontent.com
STATEGRAPH_OAUTH_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxx
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com
STATEGRAPH_OAUTH_DISPLAY_NAME=Sign in with Google

# Optional: Google Groups
# STATEGRAPH_OAUTH_GOOGLE_GROUP=stategraph-users@yourcompany.com
# STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL=admin@yourcompany.com
# STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON='{...}'

Docker Compose

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: "your-secure-password"
      POSTGRES_USER: "stategraph"
      POSTGRES_DB: "stategraph"
    volumes:
      - db:/var/lib/postgresql/data/
    networks:
      - stategraph

  server:
    image: ghcr.io/stategraph/stategraph-server:<version>
    env_file:
      - .env
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
    networks:
      - stategraph

networks:
  stategraph:

volumes:
  db: