Firebase Tokens Laravel Package

Getting Started

Install or upgrade with composer require kreait/firebase-tokens:^5.6.2. The 5.6.2 patch is worth taking immediately because it fixes whitespace-only FIREBASE_AUTH_EMULATOR_HOST values incorrectly enabling emulator mode and skipping signature verification for ID tokens and session cookies. It also builds on 5.6.1, which stopped fetching public keys when verifying emulator tokens.

Start with the two core classes: CustomTokenGenerator to issue custom tokens for backend-initiated auth (for testing, provisioning, or integrating with an existing user store), and IdTokenVerifier/SessionCookieVerifier to validate tokens received from clients. The simplest path is CustomTokenGenerator::withClientEmailAndPrivateKey() and IdTokenVerifier::createWithProjectId() using your service account credentials and project ID. Verify your first token by calling verifyIdToken() in a try/catch block for IdTokenVerificationFailed.

Implementation Patterns

Register verifiers and generators as singletons in a service provider so public-key refresh and caching are reused across requests. Inject a PSR-6 or PSR-16 cache adapter, such as Laravel Cache or Symfony Cache, to avoid repeated HTTP calls to Google’s secure token keys during high traffic.

In Laravel, resolve IdTokenVerifier and CustomTokenGenerator from the container and inject them into authentication middleware, guards, or API endpoints. For multi-tenant apps, use withTenantId() on generators and withExpectedTenantId() on ID-token verifiers to scope tokens to a specific tenant. Inspect verified tokens with payload() and headers() to access claims such as user_id, email, firebase.sign_in_provider, and sub.

Since 5.6.1, verification of emulator-issued tokens short-circuits before any public-key fetch. That means local/test suites using the Auth Emulator need no cache adapter, no network access, and no service-account key material for verification—wire the cache adapter only for the production code path, and keep both paths behind separate service-provider bindings so the emulator shortcut never leaks into production configuration.

Keep emulator configuration explicit and environment-specific. Use the Firebase Auth Emulator only in local/test environments, and ensure FIREBASE_AUTH_EMULATOR_HOST is either unset/empty or set to a real emulator host—never a whitespace-only value. In Laravel .env files, prefer an empty value or omit the key entirely when not using the emulator.

Gotchas and Tips

Upgrade to at least 5.6.2. Before 5.6.2, a whitespace-only FIREBASE_AUTH_EMULATOR_HOST could be treated as enabled emulator mode, which caused ID-token and session-cookie signature verification to be skipped. Treat this environment variable as security-sensitive: unset it in production and validate it in deployment pipelines—e.g. fail the build if FIREBASE_AUTH_EMULATOR_HOST is set to an empty-but-present or whitespace value—and never leave values like FIREBASE_AUTH_EMULATOR_HOST= in .env files.

Because emulator verification no longer fetches public keys (5.6.1+), an accidentally enabled emulator fails silently and quickly: no network error, no key-fetch timeout, just a "successful" verification of an unsigned token. Don't rely on connectivity failures to surface misconfiguration—assert the emulator flag explicitly in a health check or config test.

When using the Firebase Auth Emulator, use emulator-issued tokens and do not mix production project IDs or production credentials. Emulator mode intentionally changes verification behavior, so accidental enablement is dangerous.

Avoid comparing raw JWT strings directly; use Token::toString() or (string) $token consistently. Be mindful of lcobucci/jwt compatibility and security advisories—use a supported version range such as ^3.4.6|^4.0.4|^4.1.5 or newer as appropriate for your package version. Session cookies do not support tenants as of the 2.2.0 release line, so don’t expect withTenantId() to work with SessionCookieVerifier. Use verifyIdTokenWithLeeway() only when necessary; overly large leeway windows can weaken replay protections. Keep an eye on package security releases, since this library is commonly used in authentication-critical paths.