PHPackages                             firevel/firebase-authentication - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. firevel/firebase-authentication

ActiveLibrary[Authentication & Authorization](/categories/authentication)

firevel/firebase-authentication
===============================

Firebase authentication driver for Laravel

3.1.0(1mo ago)2225.0k↓47.9%10[1 PRs](https://github.com/firevel/firebase-authentication/pulls)1MITPHPPHP ^8.2CI passing

Since Jul 12Pushed 1mo agoCompare

[ Source](https://github.com/firevel/firebase-authentication)[ Packagist](https://packagist.org/packages/firevel/firebase-authentication)[ Docs](https://github.com/firevel/firebase-authentication)[ RSS](/packages/firevel-firebase-authentication/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (32)Versions (25)Used By (1)

Laravel Firebase Authentication
===============================

[](#laravel-firebase-authentication)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Latest Stable Version](https://camo.githubusercontent.com/496b5ab21bed93b9cee91bddca1a3ba3455417024fdaffbe2dfeb3cd7f3d8ec6/68747470733a2f2f706f7365722e707567782e6f72672f6669726576656c2f66697265626173652d61757468656e7469636174696f6e2f762f737461626c65)](https://packagist.org/packages/firevel/firebase-authentication)

A production-ready Firebase Authentication driver for Laravel that enables seamless JWT-based authentication using Firebase tokens.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
    - [Standard Setup (with Database)](#standard-setup-with-database)
    - [Microservice Setup (without Database)](#microservice-setup-without-database)
    - [Multiple Guards](#multiple-guards)
    - [Web Authentication](#web-authentication)
- [Configuration Reference](#configuration-reference)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Common Use Cases](#common-use-cases)
- [Security Considerations](#security-considerations)
- [Troubleshooting](#troubleshooting)
- [Upgrading from v2.x](UPGRADING.md)
- [Contributing](#contributing)
- [License](#license)

Features
--------

[](#features)

- **JWT Token Verification**: Securely verify Firebase Authentication JWT tokens
- **Automatic User Sync**: Create or update users from Firebase claims, with an opt-out for invite-only flows
- **Email Verification Sync**: Firebase's `email_verified` claim populates `email_verified_at` automatically
- **Claim Validation**: Type-enforce and sanitize incoming JWT claims (`string`, `integer`, `boolean`, `array`, `url`) — malformed token data is rejected before it ever reaches your database
- **Lifecycle Events**: `FirebaseUserCreated`, `FirebaseUserUpdated`, `FirebaseUserResolved` for plug-in hooks
- **Anonymous Authentication**: Built-in support for Firebase anonymous users
- **Microservice Ready**: Stateless authentication without database dependency
- **Web & API Guards**: Session-based exchange endpoint and bearer-token API auth
- **Configurable Caching**: Use Laravel's Redis/Memcached/database cache for the JWKS cache, not just the local filesystem
- **Clock-Skew Tolerance**: Optional leeway for token verification
- **Laravel Integration**: Native integration with Laravel's authentication system
- **Flexible User Models**: Works with Eloquent, or custom models

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 11.x, 12.x, 13.x
- Firebase project with Authentication enabled

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require firevel/firebase-authentication
```

The package will automatically register its service provider.

Upgrading from v2.x
-------------------

[](#upgrading-from-v2x)

See [UPGRADING.md](UPGRADING.md) for the v2 → v3 migration guide.

Quick Start
-----------

[](#quick-start)

For a quick setup with API authentication:

1. **Set your Firebase project ID** in `.env`:

```
GOOGLE_CLOUD_PROJECT=your-firebase-project-id
```

2. **Configure auth guard** in `config/auth.php`:

```
'guards' => [
    'api' => [
        'driver' => 'firebase',
        'provider' => 'users',
    ],
],
```

3. **Add trait to your User model**:

```
use Firevel\FirebaseAuthentication\FirebaseAuthenticatable;

class User extends Authenticatable
{
    use FirebaseAuthenticatable;

    protected $fillable = ['name', 'email', 'firebase_id', 'avatar_url'];

    // Optional: match users by email instead of Firebase UID (default: ['sub' => 'firebase_id'])
    // protected $firebaseResolveBy = 'email';

    // Optional: customize which Firebase claims map to which user attributes
    // (default: email→email, name→name, avatar_url→picture)
    // protected $firebaseClaimsMapping = [
    //     'email' => 'email',
    //     'name' => 'name',
    // ];
}
```

4. **Add the `firebase_id` and `avatar_url` columns** to your users table:

```
php artisan vendor:publish --tag=firebase-authentication-migrations
php artisan migrate
```

The published migration is additive: it adds `firebase_id` (unique, nullable) and `avatar_url` columns to your existing `users` table and makes `password` nullable. The existing `id` integer primary key is preserved.

5. **Protect your routes**:

```
Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});
```

That's it! Send requests with `Authorization: Bearer {firebase-jwt-token}` header.

Configuration
-------------

[](#configuration)

### Standard Setup (with Database)

[](#standard-setup-with-database)

This setup stores user data in your database and syncs it with Firebase claims.

#### 1. Environment Configuration

[](#1-environment-configuration)

Add your Firebase project ID to `.env`:

```
GOOGLE_CLOUD_PROJECT=your-firebase-project-id
```

Alternatively, publish the package config and set `project_id` there:

```
php artisan vendor:publish --tag=firebase-authentication-config
```

```
// config/firebase-authentication.php
return [
    'project_id' => env('FIREBASE_PROJECT_ID', 'your-project-id'),
    // ...
];
```

> For backwards compatibility, the package also still reads `config('firebase.project_id')` and `env('GOOGLE_CLOUD_PROJECT')` if the package-namespaced value is unset.

#### 2. Update Authentication Configuration

[](#2-update-authentication-configuration)

Modify `config/auth.php` to use the Firebase driver for API auth:

```
'guards' => [
    'api' => [
        'driver' => 'firebase',
        'provider' => 'users',
    ],
],
```

> For browser-based auth, see [Web Authentication](#web-authentication) below — the recommended path uses Laravel's `session` driver, not the `firebase` driver.

#### 3. Update Your User Model

[](#3-update-your-user-model)

Add the `FirebaseAuthenticatable` trait to your User model:

**Eloquent Example:**

```