Authentication and session management

Why authentication is different in headless

In a traditional WordPress architecture, authentication relies on PHP session cookies. The browser sends the cookie with every request to the same domain, and WordPress verifies the session on the server. This mechanism works because the frontend and backend share the same domain.

In a headless architecture, the frontend (Next.js) and the backend (WordPress) are deployed on different domains (for example www.mysite.com and admin.mysite.com). WordPress session cookies are not sent to requests targeting the frontend. An authentication mechanism that works across domains is therefore required.

Available authentication methods

Three main methods allow authenticating a user between a Next.js frontend and a WordPress backend.

JWT authentication: full implementation

JWT (JSON Web Token) is the most suitable mechanism for user authentication in a headless architecture. The principle is as follows: the user submits their credentials, the server returns a signed token, and the client attaches that token to every authenticated request.

Installing the JWT plugin on WordPress

wp plugin install jwt-authentication-for-wp-rest-api --activate

// wp-config.php
define('JWT_AUTH_SECRET_KEY', 'your-random-secret-key-of-64-characters-minimum');
define('JWT_AUTH_CORS_ENABLE', true);

# .htaccess
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

curl -X POST https://admin.mysite.com/wp-json/jwt-auth/v1/token \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "password"}'

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_email": "user@mysite.com",
  "user_nicename": "user",
  "user_display_name": "John Doe"
}

Implementation on the Next.js side

Login API route

The Next.js API route serves as an intermediary between the login form and the WordPress API. It stores the token in an httpOnly cookie, which is inaccessible to client-side JavaScript.

// app/api/auth/login/route.ts
import { cookies } from 'next/headers';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const { username, password } = await request.json();

  const wpRes = await fetch(
    `${process.env.NEXT_PUBLIC_WORDPRESS_URL}/wp-json/jwt-auth/v1/token`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username, password }),
    }
  );

  if (!wpRes.ok) {
    return Response.json(
      { error: 'Invalid credentials' },
      { status: 401 }
    );
  }

  const data = await wpRes.json();

  // Store the token in a secure httpOnly cookie
  cookies().set('auth_token', data.token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 7, // 7 days
    path: '/',
  });

  return Response.json({
    user_email: data.user_email,
    user_display_name: data.user_display_name,
  });
}

Logout API route

// app/api/auth/logout/route.ts
import { cookies } from 'next/headers';

export async function POST() {
  cookies().delete('auth_token');
  return Response.json({ success: true });
}

Route protection middleware

The Next.js middleware intercepts requests before pages are rendered. It checks for the authentication cookie and redirects to the login page if necessary.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const protectedRoutes = ['/account', '/favorites', '/cart'];

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth_token')?.value;
  const isProtected = protectedRoutes.some((route) =>
    request.nextUrl.pathname.startsWith(route)
  );

  if (isProtected && !token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('redirect', request.nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/account/:path*', '/favorites/:path*', '/cart/:path*'],
};

Token storage: httpOnly cookie or localStorage?

CORS configuration

The WordPress backend must allow requests from the frontend domain. This is configured in a plugin or in functions.php:

// functions.php — CORS configuration for headless
function headless_cors_headers() {
    $allowed_origins = [
        'https://www.mysite.com',
        'https://staging.mysite.com',
    ];

    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';

    if (in_array($origin, $allowed_origins)) {
        header("Access-Control-Allow-Origin: $origin");
        header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
        header('Access-Control-Allow-Headers: Content-Type, Authorization');
        header('Access-Control-Allow-Credentials: true');
    }
}
add_action('rest_api_init', function () {
    remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');
    add_filter('rest_pre_serve_request', function ($value) {
        headless_cors_headers();
        return $value;
    });
});

Role-based content access

In WordPress headless, some content can be restricted to logged-in users or specific roles. The check is performed on the server inside Next.js Server Components:

// app/account/page.tsx
import { cookies } from 'next/headers';

async function getCurrentUser(token: string) {
  const res = await fetch(
    `${process.env.NEXT_PUBLIC_WORDPRESS_URL}/wp-json/wp/v2/users/me`,
    {
      headers: { Authorization: `Bearer ${token}` },
      cache: 'no-store',
    }
  );
  if (!res.ok) return null;
  return res.json();
}

export default async function AccountPage() {
  const token = cookies().get('auth_token')?.value;
  if (!token) return <p>Access denied</p>;

  const user = await getCurrentUser(token);
  if (!user) return <p>Session expired</p>;

  return (
    <main>
      <h1>Hello {user.name}</h1>
      <p>Role: {user.roles[0]}</p>
    </main>
  );
}

Security considerations

Key takeaways