firebase-auth-cloudflare-workers

firebase-auth-cloudflare-workers

Zero-dependencies firebase auth library for Cloudflare Workers.

• Implemented by only Web Standard API.
• Supported UTF-8.
• Supported Firebase Auth Emulator.

Synopsis

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
}

const verifyJWT = async (req: Request, env: Bindings): Promise<Response> => {
  const authorization = req.headers.get('Authorization')
  if (authorization === null) {
    return new Response(null, {
      status: 400,
    })
  }
  const jwt = authorization.replace(/Bearer\s+/i, "")
  const auth = Auth.getOrInitialize(
    env.PROJECT_ID,
    WorkersKVStoreSingle.getOrInitialize(env.PUBLIC_JWK_CACHE_KEY, env.PUBLIC_JWK_CACHE_KV)
  )
  const firebaseToken = await auth.verifyIdToken(jwt, env)

  return new Response(JSON.stringify(firebaseToken), {
    headers: {
      "Content-Type": "application/json"
    }
  })
}

wrangler.toml

name = "firebase-auth-example"
compatibility_date = "2022-07-05"
workers_dev = true

[vars]
FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099"
PROJECT_ID = "example-project12345"

# Specify cache key to store and get public jwk.
PUBLIC_JWK_CACHE_KEY = "public-jwk-cache-key"

[[kv_namespaces]]
binding = "PUBLIC_JWK_CACHE_KV"
id = ""
preview_id = "testingId"

Module Worker syntax

export async function fetch(req: Request, env: Bindings) {
  return await verifyJWT(req, env)
}

export default { fetch };

Service Worker syntax

declare global {
  const PROJECT_ID: string
  const PUBLIC_JWK_CACHE_KEY: string
  const PUBLIC_JWK_CACHE_KV: KVNamespace
  const FIREBASE_AUTH_EMULATOR_HOST: string
}

addEventListener('fetch', (event: FetchEvent) => {
  // Create env object for verifyIdToken API.
  const bindings: EmulatorEnv = {
    PROJECT_ID,
    PUBLIC_JWK_CACHE_KEY,
    PUBLIC_JWK_CACHE_KV,
    FIREBASE_AUTH_EMULATOR_HOST,
  }
  event.respondWith(verifyJWT(event.request, bindings))
})

Install

You can install from npm registry.

$ npm i firebase-auth-cloudflare-workers

Docs

• API
• Type
• Run example code
• Todo

API

Auth.getOrInitialize(projectId: string, keyStore: KeyStorer, credential?: Credential): Auth

Auth is created as a singleton object. This is because the Module Worker syntax only use environment variables at the time of request.

• projectId specifies the ID of the project for which firebase auth is used.
• keyStore is used to cache the public key used to validate the Firebase ID token (JWT).
• credential is an optional. This is used to utilize Admin APIs such as createSessionCookie. Currently, you can specify ServiceAccountCredential class, which allows you to use a service account.

See official document for project ID: https://firebase.google.com/docs/projects/learn-more#project-identifiers

authObj.verifyIdToken(idToken: string, env?: EmulatorEnv): Promise<FirebaseIdToken>

Verifies a Firebase ID token (JWT). If the token is valid, the promise is fulfilled with the token's decoded claims; otherwise, the promise is rejected.

See the ID Token section of the OpenID Connect spec for more information about the specific properties below.

• idToken The ID token to verify.
• env is an optional parameter. but this is using to detect should use emulator or not.

authObj.verifySessionCookie(sessionCookie: string, env?: EmulatorEnv): Promise<FirebaseIdToken>

Verifies a Firebase session cookie. Returns a Promise with the cookie claims. Rejects the promise if the cookie could not be verified.

See Verify Session Cookies for code samples and detailed documentation.

• sessionCookie The session cookie to verify.
• env is an optional parameter. but this is using to detect should use emulator or not.

authObj.createSessionCookie(idToken: string, sessionCookieOptions: SessionCookieOptions, env?: EmulatorEnv): Promise<string>

Creates a new Firebase session cookie with the specified options. The created JWT string can be set as a server-side session cookie with a custom cookie policy, and be used for session management. The session cookie JWT will have the same payload claims as the provided ID token. See Manage Session Cookies for code samples and detailed documentation.

• idToken The Firebase ID token to exchange for a session cookie.
• sessionCookieOptions The session cookie options which includes custom session duration.
• env is an optional parameter. but this is using to detect should use emulator or not.

Required service acccount credential to use this API. You need to set the credentials with Auth.getOrInitialize.

WorkersKVStoreSingle.getOrInitialize(cacheKey: string, cfKVNamespace: KVNamespace): WorkersKVStoreSingle

WorkersKVStoreSingle is created as a singleton object. This is because the Module Worker syntax only use environment variables at the time of request.

This caches the public key used to verify the Firebase ID token in the Workers KV.

This is implemented KeyStorer interface.

• cacheKey specifies the key of the public key cache.
• cfKVNamespace specifies the KV namespace which is bound your workers.

AdminAuthApiClient.getOrInitialize(projectId: string, credential: Credential, retryConfig?: RetryConfig): AdminAuthApiClient

AdminAuthApiClient is created as a singleton object. This is because the Module Worker syntax only use environment variables at the time of request.

You can send request with the Admin Auth API. To generate an access token, you will use the Credential class. For instance, if you want to generate an access token from a Service Account JSON, you need to specify ServiceAccountCredential as a parameter during initialization.

By specifying the roles/firebaseauth.admin role to the Service Account, it becomes available for use. If you want finer control over permissions, create a Custom Role based on the Access Control guide and assign it to the Service Account.

emulatorHost(env?: EmulatorEnv): string | undefined

Returns the host of your Firebase Auth Emulator. For example, this case returns "127.0.0.1:9099" if you configured like below.

wrangler.toml

[vars]
FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099"

useEmulator(env?: EmulatorEnv): boolean

This is a wrapper emulatorHost function.

When true the SDK should communicate with the Auth Emulator for all API calls and also produce unsigned tokens.

Type

KeyStorer

This is an interface to cache the public key used to verify the Firebase ID token. By creating a class that implemented this interface, you can cache it in any storage of your choice.

interface KeyStorer {
  get<ExpectedValue = unknown>(): Promise<ExpectedValue | null>;
  put(value: string, expirationTtl: number): Promise<void>;
}

EmulatorEnv

interface EmulatorEnv {
  FIREBASE_AUTH_EMULATOR_HOST: string | undefined
}

FirebaseIdToken

Interface representing a decoded Firebase ID token, returned from the authObj.verifyIdToken method.

Run example code

I put an example directory as Module Worker Syntax. this is explanation how to run the code.

1. Clone this repository and change your directory to it.
2. Install dev dependencies as pnpm command.
3. Run firebase auth emulator by $ pnpm start-firebase-emulator
4. Access to Emulator UI in your favorite browser.
5. Create a new user on Emulator UI. (email: [e-mail] password: test1234)
6. Run example code on local (may serve as localhost:8787) by $ pnpm start-example
7. Get jwt for created user by $ curl -s http://localhost:8787/get-jwt | jq .idToken -r
8. Try authorization with user jwt $ curl http://localhost:8787/ -H 'Authorization: Bearer PASTE-JWT-HERE'

for Session Cookie

You can try session cookie with your browser.

Access to /admin/login after started up Emulator and created an account (email: [e-mail] password: test1234).

Todo

Non-required service account key.

• IDToken verification

Required service account key.

• Check authorized user is deleted (revoked)