When to Move Authentication to Netlify Edge Functions

The Problem: Authentication Latency at Scale

Your React app loads fast from Netlify's CDN, but every authenticated request still round-trips to your origin server for JWT validation. At 200ms per request, that adds up. Users on mobile networks feel it. The origin server handles validation logic that could run closer to the client.

Netlify Edge Functions let you validate JWTs at the CDN edge, before the request reaches your origin. This isn't a universal win — edge functions have constraints. Here's how to decide if moving auth to the edge makes sense for your stack.

What Edge Functions Actually Run On

Edge Functions execute in V8 isolates distributed across Netlify's edge network. Unlike Node.js Lambda functions, they don't have access to the full Node standard library — no fs, no crypto module, no native addons. You get the Web Platform APIs: fetch, Request, Response, Headers, and standard globals like crypto.subtle for cryptographic operations.

Cold starts are typically under 50ms because isolates are kept warm. The deployment bundle must stay under 50MB uncompressed, and initialization must complete within 100ms. These limits shape what you can realistically do.

Worked Example: JWT Validation at the Edge

Suppose you're using RS256-signed JWTs from Auth0. The public key is available at a JWKS endpoint. Here's a minimal edge function that validates the token and forwards the request with user claims attached:

// netlify/edge-functions/auth.ts
import type { Config, Context } from "@netlify/edge-functions";

export default async function auth(request: Request, context: Context) {
  const authHeader = request.headers.get("authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return new Response("Unauthorized", { status: 401 });
  }
  const token = authHeader.slice(7);
  
  // Fetch JWKS (cache in memory across invocations)
  const jwksUrl = "https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json";
  const jwks = await fetch(jwksUrl).then(r => r.json());
  
  // Parse token header to find matching key
  const [headerB64] = token.split(".");
  const header = JSON.parse(atob(headerB64));
  const key = jwks.keys.find((k: any) => k.kid === header.kid);
  if (!key) return new Response("Invalid token", { status: 401 });
  
  // Verify signature using Web Crypto API
  const publicKey = await crypto.subtle.importKey(
    "jwk",
    key,
    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
    false,
    ["verify"]
  );
  
  const [signingInput, signatureB64] = [token.slice(0, token.lastIndexOf(".")), token.slice(token.lastIndexOf(".") + 1)];
  const signature = new Uint8Array(atob(signatureB64.replace(/-/g, "+").replace(/_/g, "/")).split("").map(c => c.charCodeAt(0)));
  
  const valid = await crypto.subtle.verify(
    "RSASSA-PKCS1-v1_5",
    publicKey,
    signature,
    new TextEncoder().encode(signingInput)
  );
  
  if (!valid) return new Response("Invalid signature", { status: 401 });
  
  // Token is valid — forward with claims in headers
  const payload = JSON.parse(atob(token.split(".")[1]));
  const newHeaders = new Headers(request.headers);
  newHeaders.set("x-user-id", payload.sub);
  newHeaders.set("x-user-email", payload.email || "");
  newHeaders.set("x-user-roles", (payload["https://your-app/roles"] || []).join(","));
  
  return context.next({ headers: newHeaders });
}

export const config: Config = {
  path: "/api/*"
};

Deploy with netlify deploy after adding @netlify/edge-functions as a dev dependency. The function intercepts all /api/* requests, validates the JWT, and forwards user claims via headers your origin can trust (since only the edge function sets them).

Trade-offs You'll Hit

• No persistent storage: You can't write to disk. The JWKS fetch above runs on every cold start. In-memory caching works across warm invocations but resets on scale events.
• Bundle size pressure: The Web Crypto API is built-in, but adding a JWT library like jose pushes bundle size. The example above avoids dependencies by using platform APIs directly.
• Debugging is log-only: No breakpoints. Use console.log and check the Netlify dashboard function logs. Local development via netlify dev approximates behavior but doesn't replicate edge network latency or cold-start timing.
• Vendor-specific APIs: context.next() and Config type are Netlify-specific. Moving to Cloudflare Workers or Vercel Edge Functions requires rewriting the routing and response-handling layer.

When It's Worth It

Move auth to the edge when:

• Your origin is a legacy service you can't modify easily
• You have high-volume API traffic where 100-200ms saved per request compounds
• You need A/B testing or feature flags that vary by user segment before hitting origin

Keep auth at the origin when:

• You need complex session logic (refresh tokens, revocation checks against a database)
• Your team lacks bandwidth for edge-specific debugging workflows
• Token validation requires libraries that exceed the 50MB bundle limit

Verify It Works

1. Deploy the function to a preview branch: netlify deploy --build
2. Trigger a request with a valid JWT: curl -H "Authorization: Bearer $TOKEN" https://your-preview.netlify.app/api/data
3. Check the Netlify dashboard → Functions → Edge Functions → Logs for execution time and any errors
4. In browser dev tools, confirm the response headers include x-user-id and latency is under 100ms for warm requests

If cold starts exceed 100ms or bundle size warnings appear, strip dependencies or move validation back to origin.