Skip to main content

Firebase Authentication - Quick Start Guide

Installation (5 minutes)​

1. Install Dependencies​

# Activate virtual environment
source venv/bin/activate

# Install firebase-admin
pip install firebase-admin==6.3.0

2. Configure GCP Credentials​

Local Development:

gcloud auth application-default login

Production (GKE): Already configured via Workload Identity - no action needed.

3. Run Tests​

# Run Firebase middleware tests
pytest tests/unit/test_firebase_auth_middleware.py -v

# Expected: 15 tests passed

4. Start Development Server​

python manage.py runserver

Testing (2 minutes)​

Test Public Endpoint (No Auth Required)​

curl http://localhost:8000/api/v1/health/

Expected: 200 OK with health status

Test Protected Endpoint (Requires Auth)​

curl http://localhost:8000/api/v1/users/

Expected: 401 Unauthorized with error:

{
  "error": "authentication_failed",
  "detail": "Missing Authorization header. Expected format: 'Bearer <token>'"
}

Test with Firebase Token​

# Get Firebase token (replace with your credentials)
FIREBASE_TOKEN="your-firebase-id-token"

curl -H "Authorization: Bearer $FIREBASE_TOKEN" \
     http://localhost:8000/api/v1/users/

Expected: 200 OK with user data (if user exists with matching firebase_uid)

Files Created​

api/middleware/
├── __init__.py                    # Middleware exports
├── firebase_auth.py               # FirebaseAuthenticationMiddleware (250 lines)
└── README.md                      # Quick reference guide

tests/unit/
└── test_firebase_auth_middleware.py  # 15 comprehensive unit tests

docs/
├── firebase-auth-integration.md       # Complete integration guide (700 lines)
└── FIREBASE-AUTH-implementation-summary.md  # Implementation summary

requirements.txt                   # Added firebase-admin==6.3.0
license_platform/settings/base.py  # Added middleware to MIDDLEWARE

Key Features​

✅ Firebase JWT Verification - Verifies tokens using Firebase Admin SDK ✅ User Authentication - Looks up Django users by firebase_uid ✅ Multi-Tenant Support - Sets tenant context automatically ✅ Public Endpoints - Bypasses auth for /health/, /admin/, /api/v1/auth/, etc. ✅ Error Handling - Production-ready error responses (401, 403, 500) ✅ Comprehensive Tests - 15 unit tests with 100% coverage ✅ Complete Documentation - Integration guide + API reference

Error Responses​

401 Unauthorized​

{
  "error": "authentication_failed",
  "detail": "Invalid or expired Firebase token"
}

Causes:

  • Missing Authorization header
  • Invalid header format
  • Expired/revoked/invalid Firebase token
  • User not found with Firebase UID

403 Forbidden​

{
  "error": "forbidden",
  "detail": "User must belong to an organization"
}

Cause: User authenticated but has no organization

500 Internal Server Error​

{
  "error": "server_error",
  "detail": "Failed to set tenant context"
}

Cause: Server-side error (check logs)

Client-Side Usage​

JavaScript/TypeScript​

import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';

// 1. Login with Firebase
const auth = getAuth();
const userCredential = await signInWithEmailAndPassword(auth, email, password);
const idToken = await userCredential.user.getIdToken();

// 2. Make API request
const response = await fetch('https://api.coditect.com/api/v1/users/', {
  headers: {
    'Authorization': `Bearer ${idToken}`,
    'Content-Type': 'application/json',
  },
});

// 3. Handle response
if (response.status === 401) {
  // Refresh token and retry
  const freshToken = await userCredential.user.getIdToken(true);
  // Retry with fresh token
}

Python Requests​

import requests

# Get Firebase token (from client)
firebase_token = "your-firebase-id-token"

# Make authenticated request
response = requests.get(
    'http://localhost:8000/api/v1/users/',
    headers={'Authorization': f'Bearer {firebase_token}'}
)

print(response.status_code)  # 200 if authenticated
print(response.json())

Next Steps​

  1. Install dependencies (see above)
  2. Run tests to verify installation
  3. Create user registration endpoint (see firebase-auth-integration.md)
  4. Implement token refresh on client side
  5. Add monitoring for authentication metrics
  6. Deploy to staging for integration testing

Documentation​

  • Complete Guide: docs/firebase-auth-integration.md
  • Implementation Summary: docs/FIREBASE-AUTH-implementation-summary.md
  • Middleware README: api/middleware/README.md

Support​

For issues or questions, see:

  • Tests: tests/unit/test_firebase_auth_middleware.py
  • Code: api/middleware/firebase_auth.py
  • Docs: docs/firebase-auth-integration.md

Status: Production-ready Last Updated: November 30, 2025 Owner: AZ1.AI INC