Google OAuth/OIDC Setup Tutorial

Google OAuth/OIDC Setup Tutorial

This tutorial walks you through setting up Google Single Sign-On (SSO) authentication for ContextForge, allowing users to log in with their Google accounts.

Prerequisites

• ContextForge installed and running
• Google account with access to Google Cloud Console
• Access to your gateway's environment configuration

Step 1: Create Google OAuth Application

1.1 Access Google Cloud Console

1. Go to Google Cloud Console
2. Select or create a project for your ContextForge
3. In the left sidebar, navigate to APIs & Services → Credentials

1.2 Enable Required APIs

Before creating credentials, enable the necessary APIs:

1. Go to APIs & Services → Library

2. Search for and enable:

   • Google Identity Service (for user authentication)
   • Google People API (for user profile information)
   • Google Identity and Access Management (IAM) API (optional, for advanced features)

1.3 Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (for general use) or Internal (for Google Workspace)
3. Fill out the required fields:

App name: ContextForge - [Your Organization]

User support email: Your support email

Application home page: Your gateway URL

• Example: https://gateway.yourcompany.com

Authorized domains: Add your domain

• Example: yourcompany.com

Developer contact information: Your email

4. Click Save and Continue

5. Add scopes (optional for basic auth):

   • userinfo.email
   • userinfo.profile
   • openid

1.4 Create OAuth Client ID

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Choose Web application
4. Configure the client:

Name: ContextForge OAuth Client

Authorized JavaScript origins: Your gateway domain

• Production: https://gateway.yourcompany.com
• Development: http://localhost:8000

Authorized redirect URIs: Critical - must be exact

• Production: https://gateway.yourcompany.com/auth/sso/callback/google
• Development: http://localhost:8000/auth/sso/callback/google

5. Click Create
6. Important: Copy the Client ID and Client Secret immediately

Step 2: Configure ContextForge Environment

2.1 Update Environment Variables

Add these variables to your .env file:

# Enable SSO System
SSO_ENABLED=true

# Google OAuth Configuration
SSO_GOOGLE_ENABLED=true
SSO_GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=GOCSPX-1234567890abcdefghijklmnop

# Optional: Auto-create users on first login
SSO_AUTO_CREATE_USERS=true

# Optional: Restrict to Google Workspace domain
SSO_TRUSTED_DOMAINS=["yourcompany.com"]

# Optional: Preserve local admin authentication
SSO_PRESERVE_ADMIN_AUTH=true

2.2 Example Production Configuration

# Production Google SSO Setup
SSO_ENABLED=true
SSO_GOOGLE_ENABLED=true
SSO_GOOGLE_CLIENT_ID=123456789012-realclientid.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=GOCSPX-realsecretfromgoogle

# Security settings for Google Workspace
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["yourcompany.com"]  # Only company emails
SSO_PRESERVE_ADMIN_AUTH=true

# Optional: Custom OAuth scopes
SSO_GOOGLE_SCOPE="openid profile email"

2.3 Development Configuration

# Development Google SSO Setup
SSO_ENABLED=true
SSO_GOOGLE_ENABLED=true
SSO_GOOGLE_CLIENT_ID=123456789012-devtest.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=GOCSPX-devtestsecret

# More permissive for testing
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true
# SSO_TRUSTED_DOMAINS=[]  # Allow any email for testing

2.4 Google Workspace Domain Restriction

For organizations using Google Workspace:

# Restrict to your organization's domain
SSO_TRUSTED_DOMAINS=["yourcompany.com"]

# Allow multiple domains
SSO_TRUSTED_DOMAINS=["yourcompany.com", "subsidiary.com", "contractor.org"]

Step 3: Restart and Verify Gateway

3.1 Restart the Gateway

# Development
make dev

# Or directly with uvicorn
uvicorn mcpgateway.main:app --reload --host 0.0.0.0 --port 8000

# Production
make serve

3.2 Verify Google SSO is Enabled

Test that Google appears in SSO providers:

# For development server (port 8000)
curl -X GET http://localhost:8000/auth/sso/providers

# For production server (port 4444, make serve)
curl -X GET http://localhost:4444/auth/sso/providers

# Should return Google in the list:
[
  {
    "id": "google",
    "name": "google",
    "display_name": "Google",
    "authorization_url": null
  }
]

Troubleshooting:

• 404 error: Check that SSO_ENABLED=true in your environment and restart gateway
• Empty array []: SSO is enabled but Google provider not created - restart gateway to auto-bootstrap

Step 4: Test Google SSO Login

4.1 Access Login Page

1. Navigate to your gateway's login page:

   • Development (port 8000): http://localhost:8000/admin/login
   • Development (make serve, port 4444): http://localhost:4444/admin/login
   • Production: https://gateway.yourcompany.com/admin/login

2. You should see a "Continue with Google" button

4.2 Test Authentication Flow

1. Click Continue with Google
2. You'll be redirected to Google's sign-in page
3. Enter your Google credentials
4. Grant permissions if prompted
5. You'll be redirected back to the gateway admin panel
6. You should be logged in successfully

4.3 Verify User Creation

Check that a user was created:

# Using the admin API (requires admin token)
curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  http://localhost:8000/auth/users

# Look for your Google email in the user list

Step 5: Google Workspace Integration (Advanced)

5.1 Google Workspace Domain Verification

For Google Workspace organizations:

1. In Google Cloud Console, go to Domain verification
2. Verify ownership of your domain
3. This allows stricter domain controls

5.2 Google Groups Integration

Map Google Groups to gateway teams:

# Custom configuration (requires additional API setup)
GOOGLE_GROUPS_MAPPING={"group1@yourcompany.com": "team-uuid-1", "admins@yourcompany.com": "admin-team-uuid"}

Note: This requires additional Google Groups API setup and custom development.

5.3 Advanced OAuth Scopes

Request additional Google permissions:

# Extended scopes for Google Workspace
SSO_GOOGLE_SCOPE="openid profile email https://www.googleapis.com/auth/admin.directory.group.readonly"

Common useful scopes:

• openid profile email - Basic user info (default)
• https://www.googleapis.com/auth/admin.directory.user.readonly - Read user directory
• https://www.googleapis.com/auth/admin.directory.group.readonly - Read group memberships

Step 6: Production Deployment Checklist

6.1 Security Requirements

• Use HTTPS for all redirect URIs
• Store client secrets securely (vault/secret management)
• Set restrictive SSO_TRUSTED_DOMAINS for Google Workspace
• Configure OAuth consent screen properly
• Regular secret rotation

6.2 Google Cloud Configuration

• OAuth consent screen configured
• Authorized domains added
• Required APIs enabled
• Redirect URIs match exactly
• Client ID and secret copied securely

6.3 DNS and Certificates

• Gateway accessible from internet
• HTTPS certificates valid
• Domain verification completed (for Workspace)

Troubleshooting

Error: "SSO authentication is disabled"

Problem: SSO endpoints return 404 Solution: Set SSO_ENABLED=true and restart gateway

Error: "redirect_uri_mismatch"

Problem: Google OAuth redirect URI doesn't match Solution: Verify exact URL match in Google Cloud Console

# Google Cloud Console authorized redirect URIs must exactly match:
https://your-domain.com/auth/sso/callback/google

# Common mistakes:
https://your-domain.com/auth/sso/callback/google/  # Extra slash
http://your-domain.com/auth/sso/callback/google   # HTTP instead of HTTPS
https://www.your-domain.com/auth/sso/callback/google  # Wrong subdomain

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

Problem: OAuth consent screen not configured properly Solution: Complete OAuth consent screen configuration

1. Go to Google Cloud Console → OAuth consent screen
2. Fill in all required fields
3. Add your domain to authorized domains
4. Publish the app (for external users)

Error: "User creation failed"

Problem: User's email domain not in trusted domains Solution: Add domain to trusted domains or remove restriction

# For Google Workspace - add your domain
SSO_TRUSTED_DOMAINS=["yourcompany.com"]

# For consumer Google accounts - remove restriction
SSO_TRUSTED_DOMAINS=[]

Google Sign-in Shows "This app isn't verified"

Problem: App verification required for production use Solution: For internal use, users can click "Advanced" → "Go to [App Name] (unsafe)"

For production apps with external users:

1. Go through Google's app verification process
2. Or limit to internal users only (Google Workspace)

Error: "invalid_client"

Problem: Wrong client ID or secret Solution: Verify credentials from Google Cloud Console

# Double-check these values match Google Cloud Console
SSO_GOOGLE_CLIENT_ID=your-actual-client-id.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=GOCSPX-your-actual-client-secret

Testing Checklist

• Google Cloud project created
• OAuth consent screen configured
• OAuth client ID created with correct redirect URI
• Client ID and secret added to environment
• Gateway restarted with new config
• /auth/sso/providers returns Google provider
• Login page shows "Continue with Google" button
• Clicking Google button redirects to Google sign-in
• Google sign-in redirects back successfully
• User is logged into gateway admin panel
• User appears in gateway user list

Google Workspace Specific Setup

Admin Console Configuration

If using Google Workspace:

1. Go to Google Admin Console
2. Navigate to Security → API controls
3. Click MANAGE THIRD-PARTY APP ACCESS
4. Configure app access for your ContextForge OAuth app

Domain-Wide Delegation (Advanced)

For service account access (advanced use cases):

1. Create a service account in Google Cloud Console
2. Enable domain-wide delegation
3. In Google Admin Console, configure API scopes
4. Use service account for server-to-server authentication

Next Steps

After Google SSO is working:

1. Test with different user types (admin, regular users)
2. Set up team mappings for automatic role assignment
3. Configure additional SSO providers for redundancy
4. Monitor authentication logs for issues
5. Document user onboarding process

Related Documentation

• Complete SSO Guide - Full SSO documentation
• GitHub SSO Tutorial - GitHub setup guide
• Team Management - Managing teams and roles
• RBAC Configuration - Role-based access control

Support

If you encounter issues:

1. Check Google Cloud Console for error messages
2. Enable debug logging: LOG_LEVEL=DEBUG
3. Review gateway logs for Google OAuth errors
4. Verify all Google Cloud Console settings match tutorial
5. Test with a simple curl command to isolate issues