next-firebase-auth-edge
Next.js 13 Firebase Authentication for Edge and Node.js runtimes. Dedicated for Next 13 server components. Compatible with Next.js middleware.
Example
The demo is available at next-firebase-auth-edge-static-demo.vercel.app
You can find source code for the demo in examples/next13-typescript-static-pages
Why
Official firebase-admin
library relies heavily on Node.js internal crypto
library and primitives that are unavailable inside Next.js Edge Runtime.
This library aims to solve the problem of creating and verifying custom JWT tokens provided by Firebase Authentication using Web Crypto API available inside Edge runtimes
What's new in version 0.7
Compatibility with Next.js 13.4. In the latest release of Next.js, the app router has reached a stable state and is no longer considered experimental.
With the introduction of version 0.7, several deprecated APIs have been removed, including the isTokenValid
option.
To successfully migrate to version 0.7, make sure to eliminate all deprecated options from your codebase. If you had any validation logic previously implemented in the isTokenValid
option, you should now transition it to the handleValidToken
option. Here's an example:
// Before
isTokenValid: (token) => token.email_verified ?? false,
handleValidToken: async ({ token, decodedToken }) => {
return NextResponse.next();
}
// After
handleValidToken: async ({ token, decodedToken }) => {
if (!token.email_verified) {
// Handle this in handleError
throw new Error("User email not verified");
}
return NextResponse.next();
},
handleError: async (error) => {
// Avoid redirect loop
if (request.nextUrl.pathname === "/login") {
return NextResponse.next();
}
const url = request.nextUrl.clone();
url.pathname = "/login";
url.search = `redirect=${request.nextUrl.pathname}${url.search}`;
return NextResponse.redirect(url);
},
Built on top of Web Crypto API
next-firebase-auth-edge
is built entirely upon Web Crypto API. Although it seems fine at first, please remember that it is still in an experimental stage. Any feedback or contribution is welcome.
Node.js Edge runtime polyfill is provided by Vercel's edge-runtime library
Installation
With npm
npm install next-firebase-auth-edge
With yarn
yarn add next-firebase-auth-edge
With pnpm
pnpm add next-firebase-auth-edge
Authentication middleware
In order to set encrypted authentication cookies, we need to define server endpoints to handle logging in and logging out of users.
This can be achieved quite easily using the authentication middleware function:
All examples below are based on working Next.js 13 app examples found in /examples directory
// middleware.ts
import type { NextRequest } from "next/server";
import { authentication } from "next-firebase-auth-edge/lib/next/middleware";
export async function middleware(request: NextRequest) {
return authentication(request, {
loginPath: "/api/login",
logoutPath: "/api/logout",
apiKey: "firebase-api-key",
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
cookieSerializeOptions: {
path: "/",
httpOnly: true,
secure: false, // Set this to true on HTTPS environments
sameSite: "strict" as const,
maxAge: 12 * 60 * 60 * 24 * 1000, // twelve days
},
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
// Optional
checkRevoked: false,
handleValidToken: async ({ token, decodedToken }) => {
console.log("Successfully authenticated", { token, decodedToken });
return NextResponse.next();
},
handleInvalidToken: async () => {
// Avoid redirect loop
if (request.nextUrl.pathname === "/login") {
return NextResponse.next();
}
// Redirect to /login?redirect=/prev-path when request is unauthenticated
const url = request.nextUrl.clone();
url.pathname = "/login";
url.search = `redirect=${request.nextUrl.pathname}${url.search}`;
return NextResponse.redirect(url);
},
handleError: async (error) => {
console.error("Unhandled authentication error", { error });
// Avoid redirect loop
if (request.nextUrl.pathname === "/login") {
return NextResponse.next();
}
// Redirect to /login?redirect=/prev-path on unhandled authentication error
const url = request.nextUrl.clone();
url.pathname = "/login";
url.search = `redirect=${request.nextUrl.pathname}${url.search}`;
return NextResponse.redirect(url);
},
});
}
export const config = {
matcher: ["/", "/((?!_next/static|favicon.ico|logo.svg).*)"],
};
Options
Required
Name | Description |
---|---|
loginPath | Defines API login endpoint. When called with auth firebase token from the client (see examples below), responds with Set-Cookie headers containing signed id and refresh tokens. |
logoutPath | Defines API logout endpoint. When called from the client (see examples below), returns empty Set-Cookie headers that remove previously set credentials |
apiKey | Firebase project API key used to fetch firebase id and refresh tokens |
cookieName | The name for cookie set by loginPath api route. |
cookieSignatureKeys | Rotating keys the cookie is validated against |
cookieSerializeOptions | Defines additional cookie options sent along Set-Cookie headers |
serviceAccount | Firebase project service account |
Optional
Name | Type | Description |
---|---|---|
checkRevoked |
boolean By default false
|
If true, validates the token against firebase server on each request. Unless you have a good reason, it's better not to use it. |
handleValidToken |
(tokens: { token: string, decodedToken: DecodedIdToken }) => Promise<NextResponse> By default returns NextResponse.next()
|
Receives id and decoded tokens and should return a promise that resolves with NextResponse. |
handleInvalidToken |
() => Promise<NextResponse> By default returns NextResponse.next()
|
If passed, is called and returned if request has not been authenticated (either does not have credentials attached or credentials have expired). Can be used to redirect unauthenticated users to specific page or pages. |
handleError |
(error: unknown) => Promise<NextResponse> By default returns NextResponse.next()
|
Receives an unhandled error that happened during authentication and should resolve with NextResponse. By default, in case of unhandled error during authentication, we just allow application to render. This allows you to customize error handling |
Troubleshooting
error - Too big integer
One of the common issues during setup is error - Too big integer
thrown by crypto-signer
. If you stumble on it, please make sure to follow resolution mentioned in https://github.com/awinogrodzki/next-firebase-auth-edge/issues/17#issuecomment-1376298292
The error is caused by malformed firebase private key. We are working on providing correct private key validation and more user friendly error message. Until then, please follow the quick fix in aforementioned issue comment.
Example AuthProvider
Below is example implementation of custom AuthProvider component that handles the calling of authentication endpoints.
GET /api/login
endpoint should be called with firebase token (see examples below). It responds with Set-Cookie
header containing encrypted cookies.
GET /api/logout
removes authentication cookies. Make sure to sign out the user from firebase before calling the endpoint.
You can see a working demo at next-firebase-auth-edge-static-demo.vercel.app
The source code for the demo can be found here examples/next13-typescript-static-pages
export const AuthProvider: React.FunctionComponent<AuthProviderProps> = ({
defaultTenant,
children,
}) => {
const { getFirebaseAuth } = useFirebaseAuth(clientConfig);
const firstLoadRef = React.useRef(true);
const [tenant, setTenant] = React.useState(defaultTenant);
// Call logout any time
const handleLogout = async () => {
const auth = await getFirebaseAuth();
const { signOut } = await import("firebase/auth");
await signOut(auth);
// Removes authentication cookies
await fetch("/api/logout", {
method: "GET",
});
};
const handleIdTokenChanged = async (firebaseUser: FirebaseUser | null) => {
if (firebaseUser && tenant && firebaseUser.uid === tenant.id) {
firstLoadRef.current = false;
return;
}
const auth = await getFirebaseAuth();
if (!firebaseUser && firstLoadRef.current) {
const { signInAnonymously } = await import("firebase/auth");
firstLoadRef.current = false;
await signInAnonymously(auth);
return;
}
if (!firebaseUser) {
firstLoadRef.current = false;
startTransition(() => {
setTenant(null);
});
return;
}
firstLoadRef.current = false;
const tokenResult = await firebaseUser.getIdTokenResult();
// Sets authentication cookies
await fetch("/api/login", {
method: "GET",
headers: {
Authorization: `Bearer ${tokenResult.token}`,
},
});
startTransition(() => {
setTenant(mapFirebaseResponseToTenant(tokenResult, firebaseUser));
});
};
const registerChangeListener = async () => {
const auth = await getFirebaseAuth();
const { onIdTokenChanged } = await import("firebase/auth");
return onIdTokenChanged(auth, handleIdTokenChanged);
};
React.useEffect(() => {
const unsubscribePromise = registerChangeListener();
return () => {
unsubscribePromise.then((unsubscribe) => unsubscribe());
};
}, []);
return (
<AuthContext.Provider
value={{
tenant,
}}
>
{children}
</AuthContext.Provider>
);
};
Server Components
next-firebase-auth-edge
is designed to work with React Server Components and Next.js 13.
Below is an example of root app/layout.tsx
server component using getTokens
function to extract user tokens from request cookies
import "./globals.css";
import { getTokens } from "next-firebase-auth-edge/lib/next/tokens";
import { cookies } from "next/headers";
import { AuthProvider } from "./auth-provider";
import { serverConfig } from "./server-config";
import { Tokens } from "next-firebase-auth-edge/lib/auth";
import { Tenant } from "../auth/types";
//...
export default async function AuthenticatedLayout({
children,
}: {
children: React.ReactNode;
}) {
const tokens = await getTokens(cookies(), {
apiKey: "firebase-api-key",
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
});
const tenant = tokens ? mapTokensToTenant(tokens) : null;
return (
<html lang="en">
<head />
<body>
<AuthProvider defaultTenant={tenant}>{children}</AuthProvider>
</body>
</html>
);
}
API Routes or getServerSideProps
Library provides getTokensFromObject
function that allows us to authenticate users inside API routes or getServerSideProps.
API Route example
import { NextApiRequest, NextApiResponse } from "next";
import { getTokensFromObject } from "next-firebase-auth-edge/lib/next/tokens";
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const tokens = await getTokensFromObject(req.cookies, {
apiKey: "firebase-api-key",
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
});
return res.status(200).json({ tokens });
}
GetServerSideProps example
import { GetServerSidePropsContext } from 'next';
import { getTokensFromObject } from 'next-firebase-auth-edge/lib/next/tokens';
export async function getServerSideProps(context: GetServerSidePropsContext) {
const tokens = await getTokensFromObject(context.req.cookies, {
apiKey: "firebase-api-key",
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
});
return { props: {} };
}
Advanced usage
Authentication middleware might not fully support every use-case. To help you with more complex authentication flows, next-firebase-auth-edge
provides a set of low-level building blocks.
getFirebaseAuth
const {
getCustomIdAndRefreshTokens,
verifyIdToken,
createCustomToken,
handleTokenRefresh,
getUser,
deleteUser,
verifyAndRefreshExpiredIdToken,
setCustomUserClaims,
} = getFirebaseAuth(
{
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
"firebase-api-key"
);
Methods
Name | Type | Description |
---|---|---|
getCustomIdAndRefreshTokens | (idToken: string, firebaseApiKey: string) => Promise<IdAndRefreshTokens> |
Generates a new set of id and refresh tokens for user identified by provided idToken
|
verifyIdToken | (idToken: string, checkRevoked?: boolean) => Promise<DecodedIdToken> |
Verifies provided idToken . Throws FirebaseAuthError . See source code for possible error types. |
createCustomToken | (uid: string, developerClaims?: object) => Promise<string> |
Creates a custom token for given firebase user. Optionally, it's possible to attach additional developerClaims
|
handleTokenRefresh | (refreshToken: string, firebaseApiKey: string) => Promise<Tokens> |
Returns id token and decodedToken for given refreshToken
|
getUser | (uid: string) => Promise<UserRecord> |
Returns Firebase UserRecord by uid |
deleteUser | (uid: string) => Promise<void> |
Deletes user |
setCustomUserClaims | (uid: string, customClaims: object ∣ null) => Promise<void> |
Sets custom claims for given user. Overwrites existing values. Use getUser to fetch current claims |
verifyAndRefreshExpiredIdToken | (token: string, refreshToken: string) => Promise<Tokens ∣ null> |
Verifies provided idToken . If token is expired, uses refreshToken to validate it. Returns null if token is not valid. |
refreshAuthCookies in middleware
Can be used inside Next.js Edge runtime to refresh user's authentication cookies. Useful when we want to refresh credentials after updating custom claims with setCustomUserClaims
function
Usage in static pages example
Using refreshAuthCookies automatically sets Set-Cookie headers with updated cookies in response. Additionally, it returns a set of updated idToken and refreshToken, in case you want to do something with it
// middleware.ts
import type { NextRequest } from "next/server";
import {
authentication,
refreshAuthCookies,
} from "next-firebase-auth-edge/lib/next/middleware";
import { getFirebaseAuth } from "next-firebase-auth-edge/lib/auth";
const commonOptions = {
apiKey: "firebase-api-key",
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
cookieSerializeOptions: {
path: "/",
httpOnly: true,
secure: false, // Set this to true on HTTPS environments
sameSite: "strict" as const,
maxAge: 12 * 60 * 60 * 24 * 1000, // twelve days
},
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
};
const { setCustomUserClaims, getUser } = getFirebaseAuth(
commonOptions.serviceAccount,
commonOptions.apiKey
);
export async function middleware(request: NextRequest) {
return authentication(request, {
loginPath: "/api/login",
logoutPath: "/api/logout",
handleValidToken: async ({ token, decodedToken }) => {
if (request.nextUrl.pathname === "/api/custom-claims") {
await setCustomUserClaims(decodedToken.uid, {
someClaims: ["someValue"],
});
const user = await getUser(decodedToken.uid);
const response = new NextResponse(JSON.stringify(user.customClaims), {
status: 200,
headers: { "content-type": "application/json" },
});
await refreshAuthCookies(token, response, commonOptions);
return response;
}
return NextResponse.next();
},
...commonOptions,
});
}
export const config = {
matcher: ["/", "/((?!_next/static|favicon.ico|logo.svg).*)"],
};
refreshAuthCookies in API handler
Can be used inside Next.js API routes to refresh user's authentication cookies. Useful when we want to refresh credentials after updating custom claims or user profile data
Usage in static pages example
Using refreshAuthCookies automatically sets Set-Cookie headers with updated cookies in api response. Additionally, it returns a set of updated idToken and refreshToken, in case you want to do something with it
// pages/api/refresh-tokens.ts
// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
import type { NextApiRequest, NextApiResponse } from "next";
import { serverConfig } from "../../config/server-config";
import { refreshAuthCookies } from "next-firebase-auth-edge/lib/next/cookies";
import { getFirebaseAuth } from "next-firebase-auth-edge/lib/auth";
export default async function handler(
req: NextApiRequest,
res: NextApiResponse
) {
const bearerToken = req.headers["authorization"]?.split(" ")[1] ?? "";
// ...use bearer token to update custom claims using "firebase-admin" library and then:
const { idToken, refreshToken } = await refreshAuthCookies(bearerToken, res, {
serviceAccount: {
projectId: "firebase-project-id",
privateKey: "firebase service account private key",
clientEmail: "firebase service account client email",
},
apiKey: "firebase-api-key",
cookieName: "AuthToken",
cookieSignatureKeys: ["secret1", "secret2"],
cookieSerializeOptions: {
path: "/",
httpOnly: true,
secure: false, // Set this to true on HTTPS environments
sameSite: "strict" as const,
maxAge: 12 * 60 * 60 * 24 * 1000, // twelve days
},
});
// Optionally do something with new `idToken` and `refreshToken`
res.status(200).json({ example: true });
}
Make sure to call the endpoint with correct Authorization
headers:
await fetch("/api/refresh-tokens", {
method: "GET",
headers: {
Authorization: `Bearer ${idToken}`,
},
});
Emulator support
Library provides Firebase Authentication Emulator support. An example can be found in examples/next13-typescript-firebase-emulator
Please remember to copy .env.dist
file into .env
and fill all needed credentials, especially:
NEXT_PUBLIC_EMULATOR_HOST=http://localhost:9099
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIREBASE_AUTH_EMULATOR_HOST
is used internally by the library
NEXT_PUBLIC_EMULATOR_HOST
is used only by provided example
Please note that even in emulator mode, library needs actual service account credentials to sign tokens with x509 certificate fetched from Google, a step that does not currently support emulation. Make sure to provide valid service account credentials even if using emulator.
Also, don't forget to put correct Firebase Project ID in .firebaserc
file.