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

  1. Go to Google Cloud Console
  2. Select your project (or create a new one)
  1. Navigate to APIs & Services > OAuth consent screen
  2. Select user type:
    - Internal: Only users in your Google Workspace organization
    - External: Any Google user (requires app verification for production)
  3. Fill in the required fields:
    - App name: Stategraph
    - User support email: Your email
    - Developer contact: Your email
  4. Click Save and Continue
  5. Add scopes (optional, email and profile are included by default)
  6. Complete the setup

Create OAuth Client ID

  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials > OAuth client ID
  3. Select Web application
  4. 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
  1. Click Create
  2. 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

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

Callback URL: The callback URL your Google OAuth client needs is {STATEGRAPH_OAUTH_REDIRECT_BASE}/oauth2/google/callback (or {STATEGRAPH_UI_BASE}/oauth2/google/callback if redirect base is not set separately). This URL is logged at startup for easy copy-paste.

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"
      STATEGRAPH_OAUTH_REDIRECT_BASE: "https://stategraph.example.com"

Step 3: Verify Configuration

Test Authentication

  1. Open Stategraph in your browser
  2. You should see a login button
  3. Click to authenticate with Google
  4. 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

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

Configure Domain-Wide Delegation

  1. Go to Google Admin Console
  2. Navigate to Security > API Controls > Domain-wide Delegation
  3. Add the service account client ID
  4. 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

Login redirects but nothing happens

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_REDIRECT_BASE=https://stategraph.example.com

# 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:

Next Steps