Skip to main content

Migrating authentication to v43

Historical migration guide

This guide describes the changes introduced in Blueprint Auth v43. Its examples target that version, not the current API. If you are upgrading to v44, also follow Migrating authentication to v44.

Overview​

Version 43 adds request validation to cookie-authenticated API routes. It checks the request method, JSON content type, and trusted Origin or Referer headers before handling login, logout, or GraphQL requests.

The v43.0.0 breaking change affects applications that use any of these factories, in either Pages Router API routes or App Router Route Handlers:

  • createLoginHandler
  • createLogoutHandler
  • createGraphQLHandler

If you do not use these factories, no changes are required for this breaking change. createSessionHandler, createKrakenOAuthHandler, and createUpdateOrgTokenHandler skip the origin and JSON content-type checks. Their existing HTTP method requirements still apply.

Migration steps​

Step 1: Update Blueprint Auth​

pnpm update @krakentech/blueprint-auth@^43

Step 2: Configure trusted application origins​

Add validation.allowedRequestOrigins to your existing auth configuration. Include the origins that serve your application, not the Kraken API origin.

lib/auth/config.ts
import { createAuthConfig } from "@krakentech/blueprint-auth";

export const authConfig = createAuthConfig({
  // Keep your existing routes, Kraken configuration, and customizations.
  validation: {
    allowedRequestOrigins: [
      "https://www.example.com",
      "http://localhost:3000",
    ],
    // Keep your other validation settings.
  },
});

Each entry should be an origin: scheme, hostname, and port when applicable, with no path, query, or fragment. Use the actual protocol and port of your local server. Configure production, staging, and preview origins for their respective deployments. Do not derive this allowlist from an incoming request header.

The three affected handler factories throw AuthMissingPropertiesError during creation if the resolved allowlist is missing or empty. Pass the shared auth configuration to each factory.

Starting with v43.0.3, you can use an environment variable instead:

.env.local
ALLOWED_REQUEST_ORIGINS="https://www.example.com,http://localhost:3000"

The environment variable is a comma-separated list. An explicitly configured validation.allowedRequestOrigins takes precedence, including an empty array. For v43.0.0 through v43.0.2, configure the origins in code.