Skip to content

OAuth2 Setup Guide - Phase 1 Implementation

Status: Ready for Configuration
Date: December 28, 2025
Version: 1.0

📋 Overview

This guide walks through enabling multiple OAuth2 providers in Firebase Console and testing them with the updated Gavekort multi-tenant app.

Supported Providers: - ✅ Google Sign-In (Recommended - already configured) - ✅ GitHub OAuth - ✅ Apple Sign In (requires Apple Developer account) - ✅ Email/Password (fallback option)

🔧 Step 1: Enable OAuth Providers in Firebase Console

A. Google Sign-In (Already Enabled)

  1. Go to: https://console.firebase.google.com/project/gavekort-multitenant/authentication/providers
  2. Verify "Google" is enabled (should be ✅)
  3. Configure if needed:
  4. Web Client ID: (shown in Firebase Console)
  5. Support email: Provide your contact email

B. Enable GitHub OAuth

  1. Firebase Console Setup:
  2. Navigate to: Authentication → Sign-in method → GitHub

  3. Click "Enable"

  4. GitHub App Setup (OAuth App):

  5. Go to: https://github.com/settings/developers
  6. Click "OAuth Apps" → "New OAuth App"
  7. Fill in:
    • Application name: Gavekort Multi-Tenant
    • Homepage URL: https://gavekort-multitenant.web.app
    • Authorization callback URL: https://gavekort-multitenant.firebaseapp.com/__/auth/handler

  8. Copy the generated:

    • Client ID
    • Client Secret

  9. Back to Firebase Console:

  10. Paste Client ID and Client Secret in the GitHub provider settings
  11. Click "Save"

C. Enable Apple Sign In (Optional)

  1. Firebase Console Setup:
  2. Navigate to: Authentication → Sign-in method → Apple

  3. Click "Enable"

  4. Apple Developer Setup (requires Apple Developer account):

  5. Go to: https://developer.apple.com/account/resources/identifiers/list
  6. Create a new "Service ID" for Sign in with Apple
  7. Configure with your domain

  8. Generate a private key and download it

  9. Back to Firebase Console:

  10. Configure Apple provider with:
    • Team ID: (from Apple Developer)
    • Key ID: (from private key)
    • Private Key: (from downloaded .p8 file)
  11. Click "Save"

🌐 Step 2: Update Your App Configuration

Environment Variables (.env.local)

The following are already configured in webapp/.env.local:

REACT_APP_FIREBASE_API_KEY=AIzaSyCG2CaNMx6Z7P8jC28mu_ZwuPXEvImeBjM
REACT_APP_FIREBASE_AUTH_DOMAIN=gavekort-multitenant.firebaseapp.com
REACT_APP_FIREBASE_PROJECT_ID=gavekort-multitenant
REACT_APP_FIREBASE_STORAGE_BUCKET=gavekort-multitenant.firebasestorage.app
REACT_APP_FIREBASE_MESSAGING_SENDER_ID=380848678496
REACT_APP_FIREBASE_APP_ID=1:380848678496:web:2d09563be3465b0b208505
REACT_APP_API_BASE_URL=https://europe-west1-gavekort-multitenant.cloudfunctions.net

No additional configuration needed - the app automatically detects enabled providers.

📦 Step 3: Deploy Cloud Functions

The OAuth2 Cloud Functions are now ready to deploy:

cd functions
npm run build
firebase deploy --only functions

New Functions Deployed: - onAuthCreate - Triggered automatically on user creation (triggers custom claims) - log_signin_event - Log sign-in events for security audit - link_oauth_provider - Allow users to link multiple providers - get_oauth_providers - Get user's linked providers

🧪 Step 4: Test OAuth2 Authentication

Test in Development

# Terminal 1: Start Firebase Emulator
firebase emulators:start

# Terminal 2: Start React app
cd webapp
npm start

Visit: http://localhost:3000/

Test flows: 1. Click "Google" → Should open Google login popup 2. Click "GitHub" → Should open GitHub login popup 3. Click "Apple" → Should open Apple login popup (if enabled) 4. Fill email/password → Traditional sign-up/login

Expected Behavior

After successful OAuth login: 1. ✅ User is created in Firebase Auth 2. ✅ Custom claims set automatically (role: "END_USER") 3. ✅ User document created in Firestore 4. ✅ Auth history recorded 5. ✅ User redirected to /wallet

🔒 Step 5: Security & Best Practices

Firestore Security Rules (Already Configured)

The following rules are in firestore.rules:

match /users/{userId} {
  allow read: if request.auth.uid == userId;
  allow write: if request.auth.uid == userId;
  allow read, write: if request.auth.token.role == 'ADMIN';
}
  • ✅ Users can only read/write their own documents
  • ✅ Admin users can access all user documents

Custom Claims (Set Automatically)

When a user signs up via OAuth:

{
  "role": "END_USER",
  "createdAt": "2025-12-28T...",
  "provider": "google.com",
  "providerEmail": "user@example.com"
}

Roles Available: - END_USER - Normal club member (default) - ADMIN - Club manager/staff (set manually) - CLUB - System administrator (set manually)

📱 Step 6: Mobile/Cross-Tab Handling

Redirect-Based Flow (for mobile)

The app now handles redirect-based OAuth for: - Mobile browsers that block popups - Cross-tab sign-in flows

Implementation: LoginPage.tsx calls handleRedirectResult() on mount.

🐛 Troubleshooting

Issue: "Popup blocked" error

Solution: - Ensure popups are allowed in browser settings - Test in incognito/private mode

Issue: "Account exists with different credential"

Solution: - User already has account with different provider - Can link providers from user settings (not yet implemented)

Issue: Custom claims not set

Solution: 1. Check Cloud Functions deployed: firebase deploy --only functions 2. Check function logs: firebase functions:log 3. Wait 60 seconds after user creation (async operation)

Issue: Users not appearing in Firestore

Solution: 1. Check users collection exists in Firestore 2. Check function permissions: gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:ACCOUNT --role=roles/datastore.user

📊 Monitoring & Logging

View OAuth Sign-Ins

# View all authentication history
firebase functions:log --only onAuthCreate,log_signin_event

Monitor in Firebase Console

  1. Go to: https://console.firebase.google.com/project/gavekort-multitenant/functions
  2. Click function → "Logs"
  3. Filter by date/provider

View User Documents

  1. Firebase Console → Firestore Database
  2. Collection: users
  3. Each user document contains:
  4. email
  5. authProvider (google.com, github.com, apple.com)
  6. authProvidersLinked (array of linked providers)
  7. role (END_USER, ADMIN, CLUB)
  8. createdAt timestamp
  9. lastSignIn timestamp

🔗 Linking Multiple Providers (Future)

Users can link multiple OAuth providers once "Account Settings" is implemented:

// Future implementation in AccountSettings component
const linkGitHub = async () => {
  const result = await linkOAuthProvider({ provider: "github.com" });
  // Success: User can now sign in with GitHub
};

✅ Deployment Checklist

Before deploying to production:

  • [ ] All OAuth providers enabled in Firebase Console
  • [ ] GitHub OAuth App created and credentials added
  • [ ] Apple Sign In configured (if required)
  • [ ] Cloud Functions deployed: firebase deploy --only functions
  • [ ] Firestore security rules updated: firebase deploy --only firestore:rules
  • [ ] Environment variables configured
  • [ ] Test all auth flows in staging
  • [ ] Monitor logs for errors
  • [ ] Create user documentation for sign-in methods

🚀 Next Steps (Phase 2)

After OAuth2 is stable:

  1. Wallet Items List - Show all claimed giftcards
  2. Transaction Filters - Filter by date/type
  3. CSV Export - Download transaction history
  4. Account Settings - Link/unlink providers

See FEATURES_ROADMAP.md for Phase 2+ details.

Questions? Check Firebase docs: - Firebase Auth Providers - GitHub OAuth Integration - Apple Sign In