Strapi Plugin Firebase Authentication

A production-ready Strapi v5 plugin that seamlessly integrates Firebase Authentication with your Strapi Headless CMS. Authenticate users via Firebase (Google, Apple, Email/Password, Phone, Magic Link) and automatically sync them with Strapi's user system.

Features at a Glance

• Multiple Authentication Methods: Google Sign-In, Apple Sign-In, Email/Password, Phone-only, Magic Link (passwordless)
• Automatic User Sync: Creates and updates Strapi users from Firebase authentication
• Password Reset Flow: Complete password reset with email verification
• Phone-Only Support: Configurable email handling for phone-based authentication
• Admin Panel: Manage Firebase users directly from Strapi admin
• Secure Configuration: AES-256 encrypted Firebase credentials
• Email Service: Three-tier fallback (Strapi Email Plugin → Firebase Extension → Console)
• Flexible User Lookup: Multiple strategies (Firebase UID, email, phone, Apple relay email)

Table of Contents

1. Quick Reference
2. Installation
3. Configuration
4. Features & Authentication Flows
5. API Reference
6. Admin Panel
7. Client Integration
8. Email Templates
9. Architecture & Database
10. Security
11. Troubleshooting
12. Best Practices
13. Support

Quick Reference

Essential Endpoints

Authentication:

• POST /api/firebase-authentication - Exchange Firebase token for Strapi JWT
• POST /api/firebase-authentication/emailLogin - Direct email/password login
• POST /api/firebase-authentication/forgotPassword - Request password reset
• POST /api/firebase-authentication/resetPassword - Authenticated password change (requires JWT)
• POST /api/firebase-authentication/requestMagicLink - Passwordless login
• GET /api/firebase-authentication/config - Get public configuration

Minimal Configuration

// config/plugins.js
module.exports = () => ({
  "firebase-authentication": {
    enabled: true,
    config: {
      FIREBASE_JSON_ENCRYPTION_KEY: process.env.FIREBASE_JSON_ENCRYPTION_KEY,
    },
  },
});

# .env
FIREBASE_JSON_ENCRYPTION_KEY=your-secure-32-character-key-here

Required Setup Steps

1. Install: yarn add strapi-plugin-firebase-authentication
2. Configure: Add plugin config to config/plugins.js
3. Build: yarn build && yarn develop
4. Upload: Settings → Firebase Authentication → Upload service account JSON
5. Permissions: Settings → Users & Permissions → Public → firebase-authentication.authenticate ✓

Admin Access

• Settings: Settings → Firebase Authentication
• User Management: Plugins → Firebase Authentication

Installation

Prerequisites

Before installing, ensure you have:

• Strapi v5 project (this plugin is for v5 only)
• Firebase project with Authentication enabled (Create one)
• Node.js 18+ and npm/yarn installed

Step 1: Install Plugin

yarn add strapi-plugin-firebase-authentication
# or
npm install strapi-plugin-firebase-authentication

Verify: Check that the plugin appears in your package.json dependencies.

Step 2: Create Encryption Key

Generate a secure 32+ character encryption key for storing Firebase credentials:

# Generate a random key (save this!)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Common Mistake: Using a weak or short key. The key MUST be at least 32 characters.

Step 3: Configure Plugin

Create or edit config/plugins.js:

module.exports = () => ({
  "firebase-authentication": {
    enabled: true,
    config: {
      FIREBASE_JSON_ENCRYPTION_KEY: process.env.FIREBASE_JSON_ENCRYPTION_KEY,
    },
  },
});

Add to .env file:

FIREBASE_JSON_ENCRYPTION_KEY=your-generated-key-from-step-2

Verify: Run echo $FIREBASE_JSON_ENCRYPTION_KEY to confirm it's set.

Step 4: Build and Start

yarn build
yarn develop

What happens:

• Plugin compiles (admin + server)
• Strapi restarts with plugin enabled
• "Firebase Authentication" appears in Plugins sidebar

Verify: Check console output for:

✔ Building admin panel (XX.Xs)
Firebase Authentication plugin initialized

If build fails: Run yarn build --clean to clear cache.

Step 5: Download Firebase Service Account

1. Go to Firebase Console
2. Select your project
3. Navigate to: Project Settings (⚙️ icon) → Service Accounts tab
4. Click "Generate New Private Key"
5. Download and save the JSON file securely (you'll upload this next)

Important: This JSON contains sensitive credentials. Never commit it to Git.

Step 6: Upload to Strapi

1. Navigate to: Settings → Firebase Authentication (left sidebar)
2. Click "Upload Configuration" button
3. Select the downloaded service account JSON file
4. Wait for "Configuration uploaded successfully" message
5. Restart Strapi: yarn develop (important!)

Verify: You should see in console:

Firebase Admin SDK initialized successfully

If initialization fails: Check Troubleshooting section.

Step 7: Configure Permissions

Navigate to: Settings → Users & Permissions → Roles → Public

Enable these permissions:

• firebase-authentication → authenticate ✓

Why: This allows unauthenticated users to exchange Firebase tokens for Strapi JWTs.

Verify: The permission checkbox should be checked and saved.

Step 8: Test Your Setup

Create a simple test to verify everything works:

Option 1: Test with Firebase Token

1. Get a Firebase ID token from your client app (or Firebase Console)
2. Send POST request to: http://localhost:1337/api/firebase-authentication
3. Body: { "idToken": "your-firebase-token-here" }
4. Expected: 200 OK with { user, jwt } response

Option 2: Test with Email/Password (if configured)

1. Create a user in Firebase Console
2. Send POST to: http://localhost:1337/api/firebase-authentication/emailLogin
3. Body: { "email": "[email protected]", "password": "password123" }
4. Expected: 200 OK with { user, jwt } response

If tests fail: Check Troubleshooting for common issues.

Common Setup Mistakes

❌ Encryption key too short → Must be 32+ characters ❌ Forgot to restart after uploading config → Always restart Strapi ❌ Wrong Firebase project → Ensure service account matches your client app ❌ Forgot to enable permissions → Public role needs authenticate permission ❌ Committed service account JSON to Git → Use .gitignore

Next Steps

After successful installation:

1. Configure additional settings (optional):

   • Password requirements: Settings → Firebase Authentication
   • Magic link settings (passwordless auth)
   • Email templates for password reset

2. Integrate with your client app (see Client Integration)

3. Set up email service for password reset (see Email Templates)

4. Review security best practices (see Best Practices)

Configuration

The plugin is configured in two places: config/plugins.js and the Strapi admin panel.

Minimal Configuration (config/plugins.js):

module.exports = () => ({
  "firebase-authentication": {
    enabled: true,
    config: {
      FIREBASE_JSON_ENCRYPTION_KEY: process.env.FIREBASE_JSON_ENCRYPTION_KEY,
    },
  },
});

Admin Panel Settings (Settings → Firebase Authentication):

• Firebase Web API Key (for email/password login)
• Password requirements (regex + message)
• Password reset URL & email subject
• Magic link settings (enable, URL, subject, expiry)
• Phone-only user handling (emailRequired: false for phone-only apps)

API Reference

Public Endpoints

| Method | Endpoint | Purpose | | ------ | ----------------------------------------------- | -------------------------------------------- | | POST | /api/firebase-authentication | Exchange Firebase token for Strapi JWT | | POST | /api/firebase-authentication/emailLogin | Email/password login (no SDK required) | | POST | /api/firebase-authentication/forgotPassword | Request password reset email | | POST | /api/firebase-authentication/resetPassword | Authenticated password change (requires JWT) | | POST | /api/firebase-authentication/requestMagicLink | Request passwordless login email | | GET | /api/firebase-authentication/config | Get public configuration |

Password Reset Flow

There are two distinct password reset approaches in this plugin:

1. Forgot Password Flow (Email-Based)

For users who forgot their password:

1. User requests reset: POST /api/firebase-authentication/forgotPassword with { "email": "[email protected]" }
2. Firebase sends email with link to Firebase's hosted password reset page
3. User clicks link → Opens Firebase's secure hosted UI
4. User enters new password on Firebase's page
5. After success → Redirects to configured continue URL
6. User logs in normally with new password

Configuration: Set passwordResetUrl in Firebase Authentication settings (this is where users land AFTER resetting their password on Firebase's page).

2. Authenticated Password Change

For admin-initiated resets or users changing their own password:

• Endpoint: POST /api/firebase-authentication/resetPassword
• Requires: Valid JWT in Authorization header + { "password": "newpassword" } in body
• Use cases:
  • Admin resetting a user's password via admin panel
  • Authenticated user changing their own password
• Returns: Updated user object + fresh JWT for auto-login

Note: This endpoint is NOT part of the forgot password email flow. Use forgotPassword for email-based password reset.

Admin Endpoints

Admin endpoints use the admin API type (no /api prefix) and require admin authentication.

User Management: | Method | Endpoint | Purpose | |--------|----------|---------| | GET | /firebase-authentication/users | List/search users | | POST | /firebase-authentication/users | Create user | | GET | /firebase-authentication/users/:id | Get user | | PUT | /firebase-authentication/users/:id | Update user | | DELETE | /firebase-authentication/users/:id | Delete user | | PUT | /firebase-authentication/users/resetPassword/:id | Reset password |

Settings Management: | Method | Endpoint | Purpose | |--------|----------|---------| | GET | /firebase-authentication/settings/firebase-config | Get Firebase config | | POST | /firebase-authentication/settings/firebase-config | Upload Firebase config | | DELETE | /firebase-authentication/settings/firebase-config | Delete Firebase config | | POST | /firebase-authentication/settings/password-config | Update password/magic link settings |

Usage

Basic Flow:

1. User authenticates with Firebase Client SDK
2. Client gets Firebase ID token
3. Client sends token to Strapi: POST /api/firebase-authentication
4. Plugin returns Strapi JWT for API access

Example (JavaScript):

// After Firebase authentication
const idToken = await firebaseUser.getIdToken();

// Exchange with Strapi
const response = await fetch("https://your-api.com/api/firebase-authentication", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ idToken }),
});

const { user, jwt } = await response.json();
localStorage.setItem("jwt", jwt); // Use this JWT for Strapi API calls

Resources:

• Firebase Web SDK
• Firebase iOS SDK
• Firebase Android SDK

Architecture

The plugin validates Firebase ID tokens and syncs users between Firebase and Strapi. Users authenticate via Firebase on the client, then exchange their Firebase token for a Strapi JWT to access your API.

Security:

• Firebase service account JSON encrypted with AES-256
• All tokens validated server-side via Firebase Admin SDK
• Passwords managed by Firebase (not Strapi)
• User responses automatically sanitized

Troubleshooting

🔴 "Firebase is not initialized"

Solution:

1. Verify FIREBASE_JSON_ENCRYPTION_KEY in config/plugins.js (min 32 characters)
2. Upload Firebase service account JSON: Settings → Firebase Authentication
3. Restart Strapi: yarn develop
4. Check startup logs for initialization errors

🔴 "Token validation failed"

Solution:

1. Ensure token hasn't expired (1 hour TTL) - client should obtain fresh token
2. Verify client and server use the same Firebase project
3. Confirm service account JSON matches your Firebase project ID
4. Check Firebase Console for service status

🔴 Email Not Sending

Solution:

Install and configure Strapi Email Plugin:

yarn add @strapi/provider-email-sendgrid

// config/plugins.js
email: {
  config: {
    provider: 'sendgrid',
    providerOptions: { apiKey: env('SENDGRID_API_KEY') },
    settings: {
      defaultFrom: '[email protected]'
    }
  }
}

Alternative: Install Firebase Email Extension

Need more help? Check Firebase Console logs or GitHub Issues

Best Practices

• Use Firebase SDK for authentication (not emailLogin for production)
• Store JWTs in httpOnly cookies (production) or secure storage (mobile)
• Configure Strapi Email Plugin (SendGrid, Mailgun, SES) for production
• Implement rate limiting on public endpoints
• Enforce HTTPS for password reset URLs
• Monitor Firebase quotas regularly
• Keep dependencies updated

Support

Questions and Issues

If you encounter problems or have questions:

1. Check Troubleshooting Section: Review common errors above
2. Firebase Documentation: firebase.google.com/docs/auth
3. Strapi Documentation: docs.strapi.io
4. GitHub Issues: github.com/meta-cto/strapi-plugin-firebase-auth/issues
   • Search existing issues first
   • Provide detailed information when creating new issues

Creating a Bug Report

When reporting issues, please include:

1. Plugin version: Check package.json
2. Strapi version: Run yarn strapi version
3. Node version: Run node --version
4. Error message: Full error text and stack trace
5. Steps to reproduce: Detailed steps to trigger the issue
6. Configuration: Relevant plugin configuration (redact sensitive data)
7. Expected behavior: What should happen
8. Actual behavior: What actually happens

Feature Requests

To request new features:

1. Search existing feature requests
2. Create detailed proposal with use case
3. Explain why feature would be beneficial
4. Suggest implementation approach (if applicable)

Community

• GitHub Discussions: Ask questions and share experiences
• Discord: Join Strapi community Discord server
• Stack Overflow: Tag questions with strapi and firebase

License

This plugin is licensed under the MIT License. See LICENSE.md for full details.

Changelog

See CHANGELOG.md for version history and release notes.

Credits

Developed and maintained by Meta CTO team.

Contributors:

• Firebase Admin SDK: Google
• Strapi Framework: Strapi Solutions SAS
• AES Encryption: crypto-js library

Additional Resources

Firebase Documentation:

• Firebase Authentication
• Firebase Admin SDK
• Platform Guides: Web | iOS | Android

Strapi Documentation:

• Strapi v5
• Email Providers (SendGrid, Mailgun, Amazon SES)

Firebase Extensions:

• Trigger Email Extension

Thank you for using Strapi Plugin Firebase Authentication! 🎉

If you find this plugin helpful, please consider:

• Starring the GitHub repository
• Sharing with your community
• Contributing improvements
• Reporting issues to help us improve

Happy coding! 🚀