Firebase Auth for Cloudflare Workers

2.0.6 · active · verified Wed Apr 22

firebase-auth-cloudflare-workers is a specialized, zero-dependency library designed to facilitate Firebase ID token (JWT) verification directly within Cloudflare Workers environments. Currently stable at version 2.0.6, it provides a robust solution for authenticating users by leveraging Web Standard APIs, ensuring minimal bundle size and optimized performance at the edge. Key differentiators include its complete independence from external npm dependencies, full support for UTF-8 character encoding, and dedicated integration with the Firebase Auth Emulator for local development and testing. The library enables developers to offload authentication logic to the Cloudflare edge, reducing latency and reliance on origin servers for token validation. While a specific release cadence isn't published, updates typically align with evolving Firebase authentication standards or Cloudflare Workers platform features.

Common errors

```
Error: Firebase ID token has incorrect 'aud' (audience) claim.
```
cause The Firebase project ID extracted from the ID token does not match the `projectId` configured for the `Auth` instance in your Cloudflare Worker.

fix Verify that `env.PROJECT_ID` in your Worker's `Bindings` and `wrangler.toml` exactly matches your Firebase project ID (e.g., `example-project12345`). This ID is part of the token's claims.
```
Error: Firebase ID token has expired. Get a fresh token from your client app and try again.
```
cause The JWT presented in the Authorization header has passed its expiration time.

fix Ensure the client application is refreshing Firebase ID tokens regularly before they expire. The client-side Firebase SDK handles this automatically, but custom implementations might need explicit refresh logic.
```
ReferenceError: KVNamespace is not defined
```
cause The `PUBLIC_JWK_CACHE_KV` binding, which is an instance of `KVNamespace`, was not properly declared and bound in your `wrangler.toml` file or passed correctly in the Worker's `Bindings`.

fix Add the `[[kv_namespaces]]` entry to your `wrangler.toml` and ensure `binding = "PUBLIC_JWK_CACHE_KV"` matches the name used in your code, along with a valid `id` for your KV namespace.
```
Error: Firebase ID token has invalid signature.
```
cause The ID token's signature cannot be verified using the public keys obtained from Firebase, possibly due to a malformed token, incorrect public key caching, or an issue with the signing keys.

fix Check the `PUBLIC_JWK_CACHE_KEY` and `PUBLIC_JWK_CACHE_KV` configurations. Ensure the KV store is accessible and correctly storing / retrieving the public JSON Web Keys (JWKs). Clear the KV cache if keys might be stale.

Warnings

gotcha The `Auth.getOrInitialize` method is designed as a singleton. Repeated calls with the same `projectId` and `keyStore` will return the same `Auth` instance. This behavior is crucial for managing resources efficiently in a Cloudflare Worker's stateless execution model.
Fix: Always use `Auth.getOrInitialize` to retrieve the Auth instance, passing the necessary environment variables for consistent behavior across requests.
gotcha By default, `authObj.verifyIdToken` does NOT check if the Firebase session cookie (or ID token) has been revoked. This could allow access with a revoked token. To enable revocation checks, you must explicitly pass `true` as the second argument.
Fix: For enhanced security, call `authObj.verifyIdToken(idToken, true, env)` to ensure revocation status is checked. Be aware this incurs an additional network request to Firebase Auth backend.
gotcha When using the Firebase Auth Emulator, the `env` parameter in `verifyIdToken` is critical for detecting the emulator host. Forgetting to pass `env` (or not configuring `FIREBASE_AUTH_EMULATOR_HOST` in `Bindings` and `wrangler.toml`) will cause token verification to attempt to reach production Firebase services, even if you intend to use the emulator.
Fix: Ensure `FIREBASE_AUTH_EMULATOR_HOST` is correctly configured in your Worker's `Bindings` interface and `wrangler.toml`, and always pass the `env` object to `authObj.verifyIdToken` when developing with the emulator.
breaking Versions prior to 2.x might have differing initialization patterns or require slightly different type definitions. Upgrading from 1.x to 2.x may require minor adjustments to import paths or method signatures.
Fix: Refer to the official documentation for specific migration guides if upgrading from major version 1.x. Ensure `import { Auth } from 'firebase-auth-cloudflare-workers';` and associated types are correct.

Install

npm install firebase-auth-cloudflare-workers npm
yarn add firebase-auth-cloudflare-workers yarn
pnpm add firebase-auth-cloudflare-workers pnpm

Imports

Auth

wrong:

const Auth = require('firebase-auth-cloudflare-workers').Auth

correct:

import { Auth } from 'firebase-auth-cloudflare-workers'

The library is designed for ESM in Cloudflare Workers environments. Use named import.

WorkersKVStoreSingle
wrong:
```
import { KVStore } from 'firebase-auth-cloudflare-workers'
```
correct:
```
import { WorkersKVStoreSingle } from 'firebase-auth-cloudflare-workers'
```
This specific implementation uses Cloudflare KV for caching public JWKs. Ensure it's correctly imported.

EmulatorEnv

wrong:

import { EmulatorEnv } from 'firebase-auth-cloudflare-workers'

correct:

import type { EmulatorEnv } from 'firebase-auth-cloudflare-workers'

EmulatorEnv is a type definition. Import it using 'import type' to avoid bundling issues.

Quickstart

Demonstrates how to set up a Cloudflare Worker using the module syntax to verify a Firebase ID token, including KV store initialization for caching public JWKs and basic error handling. This is a complete, runnable example for a worker.

import type { EmulatorEnv } from "firebase-auth-cloudflare-workers";
import { Auth, WorkersKVStoreSingle } from "firebase-auth-cloudflare-workers";

interface Bindings extends EmulatorEnv {
  PROJECT_ID: string;
  PUBLIC_JWK_CACHE_KEY: string;
  PUBLIC_JWK_CACHE_KV: KVNamespace;
  FIREBASE_AUTH_EMULATOR_HOST?: string; // Made optional as it's for emulator
}

const verifyJWT = async (req: Request, env: Bindings): Promise<Response> => {
  const authorization = req.headers.get('Authorization');
  if (authorization === null) {
    return new Response(JSON.stringify({ error: 'Authorization header missing' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    });
  }
  const jwt = authorization.replace(/Bearer\s+/i, "");

  // Auth is designed as a singleton for Workers
  const auth = Auth.getOrInitialize(
    env.PROJECT_ID,
    WorkersKVStoreSingle.getOrInitialize(env.PUBLIC_JWK_CACHE_KEY, env.PUBLIC_JWK_CACHE_KV)
  );

  try {
    const firebaseToken = await auth.verifyIdToken(jwt, false, env);
    return new Response(JSON.stringify(firebaseToken), {
      headers: {
        "Content-Type": "application/json"
      }
    });
  } catch (error: any) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext): Promise<Response> {
    return await verifyJWT(request, env);
  }
};

// To run, ensure wrangler.toml is configured:
// name = "firebase-auth-example"
// compatibility_date = "2022-07-05"
// 
// [vars]
// PROJECT_ID = "your-firebase-project-id"
// PUBLIC_JWK_CACHE_KEY = "public-jwk-cache-key"
// FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099" # Only if using emulator
// 
// [[kv_namespaces]]
// binding = "PUBLIC_JWK_CACHE_KV"
// id = "<YOUR_KV_NAMESPACE_ID>"
// preview_id = "<YOUR_KV_NAMESPACE_PREVIEW_ID>"
// 
// You can install with: `npm i firebase-auth-cloudflare-workers`

view raw JSON →