Firebase Tokens Laravel Package

Getting Started

Install the package with composer require kreait/firebase-tokens. Start by using the two core classes: CustomTokenGenerator to issue custom tokens for backend-initiated auth (e.g., for testing or provisioning), and IdTokenVerifier/SessionCookieVerifier to validate tokens received from client applications. The simplest path is using CustomTokenGenerator::withClientEmailAndPrivateKey() and IdTokenVerifier::createWithProjectId()—pass your service account credentials and project ID to get started. Verify your first token by calling verifyIdToken() in a try/catch block to handle IdTokenVerificationFailed exceptions.

Implementation Patterns

Use a singleton or service provider to reuse verifiers/generators across requests—refreshing public keys happens automatically and efficiently when a cache implementation is injected. Cache the Google Secure Token Store keys using a PSR-6/PSR-16 adapter (e.g., Symfony Cache or Laravel Cache) to avoid excessive HTTP calls during high-traffic periods. For multi-tenant apps, chain withTenantId() on generators and withExpectedTenantId() on verifiers to scope tokens to a specific tenant ID. In Laravel, resolve IdTokenVerifier and CustomTokenGenerator via a service provider and inject them into authentication middlewares or API endpoints. Leverage the Token object’s payload() and headers() methods to inspect claims like user_id, email, firebase.sign_in_provider, and sub.

Gotchas and Tips

Avoid using the token string directly for comparison—always use Token::toString() or (string)$token consistently, and never compare raw JWT strings from different verifiers due to signature variance. When using the Firebase Auth Emulator in local development, ensure you set the correct issuer audience—emulator tokens use localhost-based issuers and may fail verification against production project IDs. The lcobucci/jwt library version can cause compatibility issues; ensure it’s ^3.4.6|^4.0.4|^4.1.5 or newer to avoid security vulnerabilities like GHSA-7322-jrq4-x5hf. Watch for PHP 8.1+ strictness regressions—versions 5.0.1 and 5.1.0 specifically fixed emulated environment signature checks. Session cookies do not support tenants as of now (verified in 2.2.0), so don’t expect withTenantId() to work on SessionCookieVerifier. Use verifyIdTokenWithLeeway() only when absolutely necessary—overly large leeways can reintroduce replay attack risk. Finally, monitor GitHub Stars or sponsorships—this is a community-maintained, high-impact library that’s critical for PHP Firebase integrations.