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

$3

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

$3

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

`bash


.env


FIREBASE_JSON_ENCRYPTION_KEY=your-secure-32-character-key-here
`

$3

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 ✓

$3

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

---

Installation

$3

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

$3

`bash
yarn add strapi-plugin-firebase-authentication


or


npm install strapi-plugin-firebase-authentication
`

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

---

$3

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

`bash


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.

---

$3

Create or edit config/plugins.js:

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

Add to .env file:

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

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

---

$3

`bash
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.

---

$3

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.

---

$3

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.

---

$3

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.

---

$3

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": "test@example.com", "password": "password123" }
4. Expected: 200 OK with { user, jwt } response

If tests fail: Check Troubleshooting for common issues.

---

$3

❌ 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

---

$3

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):

`javascript
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

$3

| 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 |

$3

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": "user@example.com" }
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.

$3

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):

`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

$3

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

---

$3

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

---

$3

Solution:

Install and configure Strapi Email Plugin:

`bash
yarn add @strapi/provider-email-sendgrid
`

`javascript
// config/plugins.js
email: {
config: {
provider: 'sendgrid',
providerOptions: { apiKey: env('SENDGRID_API_KEY') },
settings: {
defaultFrom: 'noreply@yourapp.com'
}
}
}
`

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

$3

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

$3

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

$3

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)

$3

- 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! 🚀