Hugging Face's logo

Spaces:
Seth0330
/
EZOFISOCR
Running

App Files Community
EZOFISOCR / FIREBASE_OTP_SETUP.md
Seth
Merge remote changes, keeping API key implementation
272f36f
preview code
|
raw
history blame contribute delete
15.6 kB

<<<<<<< HEAD

Firebase Authentication + OTP Setup Guide

This application uses Firebase Authentication for Google sign-in and Brevo for OTP email delivery. Only business email addresses are allowed.

Prerequisites

  1. Firebase project
  2. Brevo account (for sending OTP emails)
  3. Business email domain verification

Step 1: Firebase Setup

1.1 Create Firebase Project

  1. Go to Firebase Console
  2. Click "Add project" or select an existing project
  3. Follow the setup wizard

1.2 Enable Google Authentication

  1. In Firebase Console, go to Authentication → Sign-in method
  2. Click on Google provider
  3. Enable it and set your project support email
  4. Save the changes

1.3 Get Firebase Web App Configuration

  1. In Firebase Console, go to Project Settings (gear icon)
  2. Scroll down to "Your apps" section
  3. Click the Web icon (</>) to add a web app
  4. Register your app (you can skip Firebase Hosting for now)
  5. Copy the Firebase configuration object

1.4 Get Firebase Service Account Key

  1. In Firebase Console, go to Project Settings → Service accounts
  2. Click Generate new private key
  3. Download the JSON file (keep it secure!)

1.5 Set Frontend Environment Variables

Create or update frontend/.env:

VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id

1.6 Set Backend Environment Variables

You have two options for Firebase Admin SDK:

Option A: Service Account JSON File

FIREBASE_SERVICE_ACCOUNT_KEY=/path/to/service-account-key.json

Option B: Service Account JSON String (Recommended for Docker/Cloud/Hugging Face Spaces)

FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"...","private_key_id":"...","private_key":"...","client_email":"...","client_id":"...","auth_uri":"...","token_uri":"...","auth_provider_x509_cert_url":"...","client_x509_cert_url":"..."}'

For Hugging Face Spaces:

  • Use Option B (JSON String) as a Secret (Private)
  • Copy the entire contents of your service account JSON file
  • Paste it as the value for FIREBASE_SERVICE_ACCOUNT_JSON
  • Make sure to keep the single quotes around the JSON if setting via command line, or just paste the raw JSON in the Spaces UI

Step 2: Brevo Setup

2.1 Create Brevo Account

  1. Go to Brevo (formerly Sendinblue)
  2. Sign up for a free account (300 emails/day free tier)
  3. Verify your email address

2.2 Get API Key

  1. Log in to Brevo
  2. Go to Settings → API Keys
  3. Click Generate a new API key
  4. Copy the API key (starts with xkeysib-...)

2.3 Verify Sender Email

  1. Go to Senders & IP → Senders
  2. Click Add a sender
  3. Enter your sender email (e.g., noreply@yourdomain.com)
  4. Verify the email address (check your inbox for verification email)
  5. Once verified, you can use it to send emails

2.4 Set Backend Environment Variables 

BREVO_API_KEY=xkeysib-your-api-key-here
BREVO_SENDER_EMAIL=noreply@yourdomain.com
BREVO_SENDER_NAME=EZOFIS AI

Step 3: JWT Secret Key

Generate a strong random string for JWT token signing:

# Generate a random secret (Linux/Mac)
openssl rand -hex 32

# Or use Python
python -c "import secrets; print(secrets.token_hex(32))"

Set the environment variable:

JWT_SECRET_KEY=your-generated-secret-key-here

Step 4: Frontend URL

Set the frontend URL for OAuth redirects:

FRONTEND_URL=http://localhost:5173  # Development
# OR
FRONTEND_URL=https://your-domain.com  # Production

Step 5: Install Dependencies

Backend 

cd backend
pip install -r requirements.txt

Frontend 

cd frontend
npm install

Step 6: Database Migration

The database will automatically create the new schema when you start the application. However, if you have existing data:

Option 1: Fresh Start (Recommended for Development)

  • Delete the existing database file: data/app.db
  • Restart the application (tables will be recreated)

Option 2: Manual Migration (For Production)

  • The new users table will be created automatically
  • Existing extractions table needs user_id column added
  • You'll need to assign existing records to a default user or migrate them

Step 7: Test the Setup

7.1 Test Firebase Authentication

  1. Start the backend server
  2. Start the frontend development server
  3. Navigate to the application
  4. Click "Google Sign In"
  5. Sign in with a business Google account
  6. Verify you're redirected to the dashboard

7.2 Test OTP Authentication

  1. Click on "Email / OTP" tab
  2. Enter a business email address
  3. Click "Send OTP"
  4. Check your email for the OTP code
  5. Enter the OTP and verify
  6. Verify you're redirected to the dashboard

7.3 Test Business Email Validation

  1. Try to sign in with a personal Gmail account
  2. Verify you get an error message
  3. Try OTP with a personal email
  4. Verify it's blocked

Environment Variables Summary

Backend (.env or environment) 

# Firebase
FIREBASE_SERVICE_ACCOUNT_JSON='{...}'  # OR
FIREBASE_SERVICE_ACCOUNT_KEY=/path/to/key.json

# Brevo
BREVO_API_KEY=xkeysib-...
BREVO_SENDER_EMAIL=noreply@yourdomain.com
BREVO_SENDER_NAME=EZOFIS AI

# JWT
JWT_SECRET_KEY=your-secret-key

# Frontend URL
FRONTEND_URL=http://localhost:5173  # For local development
# For Hugging Face Spaces: https://your-username-ezofisocr.hf.space

For Hugging Face Spaces:

  • Set FIREBASE_SERVICE_ACCOUNT_JSON, BREVO_API_KEY, and JWT_SECRET_KEY as Secrets (Private)
  • Set BREVO_SENDER_EMAIL, BREVO_SENDER_NAME, and FRONTEND_URL as Variables (Public)
  • See HUGGINGFACE_SPACES_SETUP.md for detailed instructions

Frontend (.env) 

VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
VITE_FIREBASE_PROJECT_ID=...
VITE_FIREBASE_STORAGE_BUCKET=...
VITE_FIREBASE_MESSAGING_SENDER_ID=...
VITE_FIREBASE_APP_ID=...
VITE_API_BASE_URL=http://localhost:7860

Troubleshooting

Firebase Issues

  • "Firebase not configured": Check that FIREBASE_SERVICE_ACCOUNT_JSON or FIREBASE_SERVICE_ACCOUNT_KEY is set correctly
  • "Invalid Firebase token": Ensure Firebase Web SDK is properly configured in frontend
  • "Email not found": Make sure Google sign-in is enabled in Firebase Console

Brevo Issues

  • "Failed to send email":
    • Verify your API key is correct
    • Check that sender email is verified in Brevo
    • Ensure you haven't exceeded the free tier limit (300 emails/day)
  • "API key not set": Check that BREVO_API_KEY environment variable is set

Business Email Validation

  • Personal emails (Gmail, Yahoo, etc.) are automatically blocked
  • Only business/corporate email domains are allowed
  • The validation happens on both frontend and backend

Security Notes

  1. Never commit Firebase service account keys or API keys to version control
  2. Use environment variables or secure secret management
  3. JWT tokens expire after 7 days
  4. OTP codes expire after 10 minutes
  5. Maximum 5 OTP verification attempts per email
  6. All extraction records are filtered by user_id for data isolation

Production Deployment

  1. Set all environment variables in your hosting platform
  2. Use HTTPS for both frontend and backend
  3. Update FRONTEND_URL to your production domain
  4. Verify sender email in Brevo with your production domain
  5. Consider using Redis for OTP storage instead of in-memory (for scalability)
  6. Set up proper error monitoring and logging

Support

For issues:

=======

Firebase Authentication + OTP Setup Guide

This application uses Firebase Authentication for Google sign-in and Brevo for OTP email delivery. Only business email addresses are allowed.

Prerequisites

  1. Firebase project
  2. Brevo account (for sending OTP emails)
  3. Business email domain verification

Step 1: Firebase Setup

1.1 Create Firebase Project

  1. Go to Firebase Console
  2. Click "Add project" or select an existing project
  3. Follow the setup wizard

1.2 Enable Google Authentication

  1. In Firebase Console, go to Authentication → Sign-in method
  2. Click on Google provider
  3. Enable it and set your project support email
  4. Save the changes

1.3 Get Firebase Web App Configuration

  1. In Firebase Console, go to Project Settings (gear icon)
  2. Scroll down to "Your apps" section
  3. Click the Web icon (</>) to add a web app
  4. Register your app (you can skip Firebase Hosting for now)
  5. Copy the Firebase configuration object

1.4 Get Firebase Service Account Key

  1. In Firebase Console, go to Project Settings → Service accounts
  2. Click Generate new private key
  3. Download the JSON file (keep it secure!)

1.5 Set Frontend Environment Variables

Create or update frontend/.env:

VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id

1.6 Set Backend Environment Variables

You have two options for Firebase Admin SDK:

Option A: Service Account JSON File

FIREBASE_SERVICE_ACCOUNT_KEY=/path/to/service-account-key.json

Option B: Service Account JSON String (Recommended for Docker/Cloud)

FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"...","private_key_id":"...","private_key":"...","client_email":"...","client_id":"...","auth_uri":"...","token_uri":"...","auth_provider_x509_cert_url":"...","client_x509_cert_url":"..."}'

Step 2: Brevo Setup

2.1 Create Brevo Account

  1. Go to Brevo (formerly Sendinblue)
  2. Sign up for a free account (300 emails/day free tier)
  3. Verify your email address

2.2 Get API Key

  1. Log in to Brevo
  2. Go to Settings → API Keys
  3. Click Generate a new API key
  4. Copy the API key (starts with xkeysib-...)

2.3 Verify Sender Email

  1. Go to Senders & IP → Senders
  2. Click Add a sender
  3. Enter your sender email (e.g., noreply@yourdomain.com)
  4. Verify the email address (check your inbox for verification email)
  5. Once verified, you can use it to send emails

2.4 Set Backend Environment Variables 

BREVO_API_KEY=xkeysib-your-api-key-here
BREVO_SENDER_EMAIL=noreply@yourdomain.com
BREVO_SENDER_NAME=EZOFIS AI

Step 3: JWT Secret Key

Generate a strong random string for JWT token signing:

# Generate a random secret (Linux/Mac)
openssl rand -hex 32

# Or use Python
python -c "import secrets; print(secrets.token_hex(32))"

Set the environment variable:

JWT_SECRET_KEY=your-generated-secret-key-here

Step 4: Frontend URL

Set the frontend URL for OAuth redirects:

FRONTEND_URL=http://localhost:5173  # Development
# OR
FRONTEND_URL=https://your-domain.com  # Production

Step 5: Install Dependencies

Backend 

cd backend
pip install -r requirements.txt

Frontend 

cd frontend
npm install

Step 6: Database Migration

The database will automatically create the new schema when you start the application. However, if you have existing data:

Option 1: Fresh Start (Recommended for Development)

  • Delete the existing database file: data/app.db
  • Restart the application (tables will be recreated)

Option 2: Manual Migration (For Production)

  • The new users table will be created automatically
  • Existing extractions table needs user_id column added
  • You'll need to assign existing records to a default user or migrate them

Step 7: Test the Setup

7.1 Test Firebase Authentication

  1. Start the backend server
  2. Start the frontend development server
  3. Navigate to the application
  4. Click "Google Sign In"
  5. Sign in with a business Google account
  6. Verify you're redirected to the dashboard

7.2 Test OTP Authentication

  1. Click on "Email / OTP" tab
  2. Enter a business email address
  3. Click "Send OTP"
  4. Check your email for the OTP code
  5. Enter the OTP and verify
  6. Verify you're redirected to the dashboard

7.3 Test Business Email Validation

  1. Try to sign in with a personal Gmail account
  2. Verify you get an error message
  3. Try OTP with a personal email
  4. Verify it's blocked

Environment Variables Summary

Backend (.env or environment) 

# Firebase
FIREBASE_SERVICE_ACCOUNT_JSON='{...}'  # OR
FIREBASE_SERVICE_ACCOUNT_KEY=/path/to/key.json

# Brevo
BREVO_API_KEY=xkeysib-...
BREVO_SENDER_EMAIL=noreply@yourdomain.com
BREVO_SENDER_NAME=EZOFIS AI

# JWT
JWT_SECRET_KEY=your-secret-key

# Frontend URL
FRONTEND_URL=http://localhost:5173

Frontend (.env) 

VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
VITE_FIREBASE_PROJECT_ID=...
VITE_FIREBASE_STORAGE_BUCKET=...
VITE_FIREBASE_MESSAGING_SENDER_ID=...
VITE_FIREBASE_APP_ID=...
VITE_API_BASE_URL=http://localhost:7860

Troubleshooting

Firebase Issues

  • "Firebase not configured": Check that FIREBASE_SERVICE_ACCOUNT_JSON or FIREBASE_SERVICE_ACCOUNT_KEY is set correctly
  • "Invalid Firebase token": Ensure Firebase Web SDK is properly configured in frontend
  • "Email not found": Make sure Google sign-in is enabled in Firebase Console

Brevo Issues

  • "Failed to send email":
    • Verify your API key is correct
    • Check that sender email is verified in Brevo
    • Ensure you haven't exceeded the free tier limit (300 emails/day)
  • "API key not set": Check that BREVO_API_KEY environment variable is set

Business Email Validation

  • Personal emails (Gmail, Yahoo, etc.) are automatically blocked
  • Only business/corporate email domains are allowed
  • The validation happens on both frontend and backend

Security Notes

  1. Never commit Firebase service account keys or API keys to version control
  2. Use environment variables or secure secret management
  3. JWT tokens expire after 7 days
  4. OTP codes expire after 10 minutes
  5. Maximum 5 OTP verification attempts per email
  6. All extraction records are filtered by user_id for data isolation

Production Deployment

  1. Set all environment variables in your hosting platform
  2. Use HTTPS for both frontend and backend
  3. Update FRONTEND_URL to your production domain
  4. Verify sender email in Brevo with your production domain
  5. Consider using Redis for OTP storage instead of in-memory (for scalability)
  6. Set up proper error monitoring and logging

Support

For issues:

daae7a900bd14d0802e4f04b99edb85493053f1d