OAuth Setup Guide

This document describes how to configure OAuth authentication providers for Foe Foundry.

Supported Providers

Foe Foundry supports the following OAuth 2.0 providers:

  1. Google - Sign in with Google
  2. Patreon - Sign in with Patreon
  3. Discord - Sign in with Discord
  4. Twitch - Sign in with Twitch

Environment Variables

All OAuth providers are configured via environment variables. These must be set in your deployment environment (e.g., Render, Heroku, etc.) or in your local .env file for development.

Google OAuth

GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com

Google OAuth uses the One Tap sign-in flow. You'll need to: 1. Create a project in Google Cloud Console 2. Navigate to "Credentials" in the APIs & Services section 3. Create OAuth 2.0 credentials (Web application type) 4. Configure the OAuth consent screen with your app information 5. Add your domain to authorized JavaScript origins (required for One Tap) 6. For server-side flows, add your redirect URIs to authorized redirect URIs

Note: Google One Tap is a client-side JavaScript library. The GOOGLE_CLIENT_ID is used in the frontend for One Tap authentication.

Patreon OAuth

PATREON_CLIENT_ID=your-patreon-client-id
PATREON_CLIENT_SECRET=your-patreon-client-secret
PATREON_REDIRECT_URI=https://yourdomain.com/auth/patreon/callback  # Optional

Patreon OAuth enables patron tier detection and benefits. You'll need to: 1. Create an application at Patreon Developers 2. Note your Client ID and Client Secret 3. Add your redirect URI (defaults to {SITE_URL}/auth/patreon/callback) 4. Request scopes: identity, identity[email], campaigns.members[email]

Discord OAuth

DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
DISCORD_REDIRECT_URI=https://yourdomain.com/auth/discord/callback  # Optional

Discord OAuth enables sign-in with Discord accounts. You'll need to: 1. Create an application at Discord Developer Portal 2. Navigate to OAuth2 settings 3. Note your Client ID and Client Secret 4. Add your redirect URI (defaults to {SITE_URL}/auth/discord/callback) 5. Request scopes: identify, email

Twitch OAuth

TWITCH_CLIENT_ID=your-twitch-client-id
TWITCH_CLIENT_SECRET=your-twitch-client-secret
TWITCH_REDIRECT_URI=https://yourdomain.com/auth/twitch/callback  # Optional

Twitch OAuth enables sign-in with Twitch accounts. You'll need to: 1. Create an application at Twitch Developer Console 2. Note your Client ID and Client Secret 3. Add your redirect URI (defaults to {SITE_URL}/auth/twitch/callback) 4. Request scopes: user:read:email

Site URL Configuration

The SITE_URL environment variable is used to construct redirect URIs automatically:

SITE_URL=https://yourdomain.com

If not set, it defaults to http://127.0.0.1:8080 for local development.

Redirect URI Logic

  • If a provider-specific redirect URI is set (e.g., PATREON_REDIRECT_URI), that value is used
  • Otherwise, the redirect URI is constructed as: {SITE_URL}/auth/{provider}/callback
  • Trailing slashes are automatically removed from SITE_URL

Security Considerations

JWT Secret

The application uses JWT tokens for session management. Set a secure random secret:

JWT_SECRET=your-very-long-random-secret-string-at-least-32-characters

Important: Never use the default development secret in production!

CSRF Protection

All OAuth flows use state tokens with: - Cryptographic nonces (32+ characters) - Time-based expiration (15 minutes) - Signature verification

SSL/TLS

OAuth providers require HTTPS in production. Ensure your deployment has: - Valid SSL certificate - HTTPS redirect enabled - Secure cookie settings

Testing OAuth Flows

Local Development

For local testing, you'll need to: 1. Use http://localhost:8080 or http://127.0.0.1:8080 as your redirect URI 2. Some providers (like Google) require exact origin matching 3. Add these URLs to your OAuth application's allowed redirect URIs

Development Mode Detection

The application automatically detects development mode when: - SITE_URL contains localhost or 127.0.0.1 - Redirect URIs contain 127.0.0.1 - DEV environment variable is set to true

User Account Linking

Users can link multiple OAuth providers to a single account: - Accounts are matched by email address - First login creates a new user account - Subsequent logins with the same email link the OAuth provider - Users can have Google, Patreon, Discord, and Twitch linked simultaneously

Troubleshooting

Common Issues

  1. "OAuth not configured" errors
  2. Check that CLIENT_ID and CLIENT_SECRET are set
  3. Verify environment variables are loaded

  4. Check application logs for specific missing variables

  5. "Invalid redirect URI" errors

  6. Verify redirect URI matches exactly in provider settings
  7. Check for trailing slashes

  8. Ensure HTTPS in production

  9. "Email not provided" errors

  10. Verify email scope is requested
  11. Check that user has verified email with provider

  12. Discord users must have verified emails

  13. State token verification failures

  14. Check JWT_SECRET is set and consistent
  15. Verify system time is synchronized
  16. State tokens expire after 15 minutes

Debug Logging

Enable debug logging to troubleshoot OAuth issues:

LOG_LEVEL=DEBUG

Check application logs for: - OAuth state token creation and verification - API calls to OAuth providers - User creation and linking operations - Email matching and patron tier detection

API Endpoints

OAuth Initiation

GET /auth/{provider}?ga_anonymous_id={ga_anonymous_id}&foe_foundry_redirect_url={redirect_url}

Redirects to provider's OAuth authorization page.

Parameters: - ga_anonymous_id (required): Google Analytics anonymous client ID for tracking - foe_foundry_redirect_url (optional): URL to redirect to after successful authentication

OAuth Callback

GET /auth/{provider}/callback?code={code}&state={state}

Handles OAuth callback, creates/updates user, and redirects to app.

Current User

GET /auth/me

Returns current user information and authentication status.

Logout

POST /auth/logout

Clears authentication cookie and logs out user.

Further Reading