A lightweight, type-safe authentication library for Next.js applications deployed on Cloudflare Workers, using Auth0 as the authentication provider.
- Easy integration with Next.js and Cloudflare Workers
- Type-safe authentication middleware
- Built-in handlers for login, logout, and callback
- Server-side session management
- Client-side React hooks and components
- Automatic token refresh
- Secure cookie handling
- Customizable authentication flow
npm install auth0-cloudflare-nextjs- An Auth0 account and application
- A Next.js project set up for deployment on Cloudflare Workers
- Node.js 14 or later
Add the following to your wrangler.toml:
[vars]
AUTH0_DOMAIN = "your-auth0-domain"
AUTH0_CLIENT_ID = "your-client-id"
AUTH0_CLIENT_SECRET = "your-client-secret"
AUTH0_CALLBACK_URL = "https://your-worker-domain.workers.dev/api/auth/callback"
AUTH0_AUDIENCE = "your-api-audience" # optional
AUTH0_BASE_URL = "https://your-base-url" # optional
DISABLE_SECURE_COOKIES = "false" # optional, defaults to falseCreate a catch-all API route for Auth0:
// app/api/auth/[auth0]/route.ts
import { handleAuth } from "auth0-cloudflare-nextjs";
export const GET = handleAuth();Create a middleware to protect routes:
// middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { withAuth } from "auth0-cloudflare-nextjs";
import { getCloudflareContext } from "@opennextjs/cloudflare";
export async function middleware(request: NextRequest) {
const context = await getCloudflareContext();
const handler = withAuth(async (req, ctx) => {
return NextResponse.next();
});
return handler(request, context);
}
export const config = {
matcher: ["/protected/:path*"],
};Access user sessions in server components:
// Server Component
import { getServerSession } from "auth0-cloudflare-nextjs";
export default async function Page() {
const session = await getServerSession();
if (!session) {
return <div>Not authenticated</div>;
}
return <div>Welcome {session.user.name}</div>;
}For custom handlers:
import { getSessionFromRequest } from "auth0-cloudflare-nextjs";
export async function GET(req: NextRequest) {
const session = await getSessionFromRequest(req);
if (!session) {
return new Response("Unauthorized", { status: 401 });
}
return Response.json(session.user);
}Set up the provider in your root layout:
// app/layout.tsx
import { UserProvider } from "auth0-cloudflare-nextjs/client";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html>
<body>
<UserProvider>{children}</UserProvider>
</body>
</html>
);
}Use the authentication hook in client components:
"use client";
import { useUser } from "auth0-cloudflare-nextjs/client";
export default function Profile() {
const { user, error, isLoading, login, logout } = useUser();
if (isLoading) return <div>Loading...</div>;
if (error) return <div>{error.message}</div>;
if (!user) return <button onClick={login}>Login</button>;
return (
<div>
<h2>{user.name}</h2>
<button onClick={logout}>Logout</button>
</div>
);
}Customize the authentication flow:
import { setAuthUtilOptions } from 'auth0-cloudflare-nextjs';
setAuthUtilOptions({
onLogin: async (req, context, auth0Client) => {
// Custom login logic
return NextResponse.redirect('...');
},
onCallback: async (req, context, auth0Client) => {
// Custom callback handling
return NextResponse.redirect('...');
},
onLogout: async (req, context, auth0Client) => {
// Custom logout logic
return NextResponse.redirect('...');
},
onGetUser: async (req, context, auth0Client) => {
// Custom user info retrieval
return NextResponse.json({...});
}
});- Secure Cookie Storage: Tokens are stored in HttpOnly, secure cookies
- Automatic Token Refresh: Handles token expiration automatically
- CSRF Protection: Implements state parameter validation
- Token Validation: Verifies token signature, issuer, and audience
- Configurable Security: Adjustable secure cookie settings
The library handles various authentication scenarios:
- Expired tokens (with automatic refresh)
- Invalid signatures
- Incorrect issuers
- Invalid audiences
- Missing or invalid cookies
- Invalid callback state
- Failed token refresh attempts
- Auth0 API connectivity problems
- Callback URL mismatches
The library is written in TypeScript and provides full type definitions:
import type {
Auth0User,
Auth0Config,
AuthenticatedNextRequest,
JWTPayload,
} from "auth0-cloudflare-nextjs";Contributions are welcome! Please feel free to submit issues and pull requests.
This project is licensed under the MIT License.
If you encounter any issues or have questions:
- Check the GitHub Issues
- Create a new issue if none exists
- Join our community discussions
- Auth0 for their authentication platform
- Next.js for the React framework
- Cloudflare Workers for the serverless platform