Protecting Routes with Middleware

The Descope Next.js SDK provides authentication middleware to enforce secure access control across application routes. Middleware allows authentication checks before requests reach a page or API, ensuring only authorized users can proceed.

Although the middleware isn't strictly required, it is recommended for consistent and secure route protection.

This guide covers:

• Configuring authentication middleware
• Defining public and private routes
• Using wildcard paths for flexible route protection
• Redirecting unauthenticated users
• Handling session expiration and forced re-authentication

Setting Up Authentication Middleware

In Next.js, middleware intercepts requests before they reach a route. The Descope SDK provides authMiddleware() to enforce authentication for protected pages.

Creating Middleware

Create a middleware.ts file in the root of your Next.js project.

import { authMiddleware } from '@descope/nextjs-sdk/server';
 
export default authMiddleware({
  projectId: process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID,
  redirectUrl: '/sign-in',
  publicRoutes: ['/home', '/about'],
  privateRoutes: ['/dashboard', '/profile'],
});
 
export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

How Middleware and the SDK Works

• All routes are private by default.
• Public routes are explicitly defined using publicRoutes.
• Private routes can be defined using privateRoutes, but if both publicRoutes and privateRoutes are used, privateRoutes is ignored.
• Middleware redirects unauthenticated users to redirectUrl.

The Session Header

When a request is processed, the middleware:

1. Extracts the session JWT from the request (Authorization header or DS cookie).
2. Validates the JWT using Descope's backend.
3. Encodes session data as a Base64 JSON string.
4. Attaches the session data to the request headers under the X-Descope-Session header.

const addSessionToHeadersIfExists = (
  headers: Headers,
  session: AuthenticationInfo | undefined
): Headers => {
  if (session) {
    const requestHeaders = new Headers(headers);
    requestHeaders.set(
      DESCOPE_SESSION_HEADER,
      Buffer.from(JSON.stringify(session)).toString('base64')
    );
    return requestHeaders;
  }
  return headers;
};

After validation, the middleware modifies the request headers to include the session data before forwarding the request.

return NextResponse.next({
  request: { headers: addSessionToHeadersIfExists(req.headers, session) }
});

This allows server-side components and API routes to access authentication details without manually validating the session again.

Session Storage Differences Between Next.js and React/JS

By default, the Descope Next.js SDK stores the DS (Descope Session) in a cookie, whereas the Web JS SDK and React SDK store it in localStorage. This means:

• Next.js SDK (cookies):

  • Accessible via JavaScript.
  • Stored securely in a secure, samesite=lax cookie.
  • Automatically included in server-side requests.
  • Persistent across browser sessions.

• React SDK (local storage):

  • Accessible via JavaScript.
  • Requires manual handling for secure transmission to the backend.

This allows client-side applications to use the token for making authenticated API requests.

Multi-Project SDK Support

Descope's Next.js SDK supports multi-project setups, where each tenant in a multi-tenant application is mapped to a separate Descope project. This approach is ideal when tenants need isolated configurations or dedicated user stores.

A typical setup looks like this:

• Each request includes a header (e.g., x-tenant-id) that identifies the tenant.
• The application dynamically initializes the Descope SDK using the project ID associated with the tenant.
• Middleware handles authentication using the appropriate project.

SDK Instance Caching

To support multi-tenant applications efficiently, the SDK automatically caches instances based on project ID:

• On the first request for a given project ID, a new SDK instance is created.
• On subsequent requests with the same project ID, the existing instance is reused.

This per-project caching ensures optimal performance by avoiding redundant SDK initializations while allowing different tenants to use separate Descope configurations.

Example: Tenant-Based Authentication

Here's a complete example showing how to implement tenant-based authentication in your middleware:

import { authMiddleware } from '@descope/nextjs-sdk/server';
import { NextRequest } from 'next/server';
 
type TenantConfig = { projectId: string; baseUrl?: string };
 
// Tenant configuration mapping
const tenantConfigs: Record<string, TenantConfig> = {
  'tenant-a': {
    projectId: 'tenant-a-project',
    baseUrl: 'https://api.descope.com',
  },
  'tenant-b': {
    projectId: 'tenant-b-project', 
    baseUrl: 'https://api.descope.com',
  },
};
 
export const middleware = async (request: NextRequest) => {
  const tenantId = request.headers.get('x-tenant-id');
  
  if (!tenantId || !tenantConfigs[tenantId]) {
    return new Response('Invalid tenant', { status: 400 });
  }
 
  const config = tenantConfigs[tenantId];
  
  const auth = authMiddleware({
    projectId: config.projectId,
    baseUrl: config.baseUrl,
    redirectUrl: '/sign-in',
    privateRoutes: ['/dashboard', '/profile'],
    publicRoutes: ['/home', '/about'],
  });
 
  return await auth(request);
};
 
export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

Using Wildcard Paths for Route Protection

Wildcard paths (*) simplify route protection by applying authentication requirements to entire sections of an application.

Protecting API Endpoints

export default authMiddleware({
  privateRoutes: ['/api/*'],
});

Protecting an Admin Section

export default authMiddleware({
  privateRoutes: ['/admin/*'],
});

Redirecting Unauthenticated Users

By default, unauthenticated users are redirected to /sign-in. To customize this behavior, update redirectUrl.

Redirecting to a Custom Login Page

export default authMiddleware({
  redirectUrl: '/auth/login',
});

Controlling Log Levels in the Descope Next.js SDK

The Descope Next.js SDK allows you to control logging levels for debugging and monitoring authentication-related events. This is useful for diagnosing issues during development and ensuring secure authentication flows in production.

Supported Log Levels

The logLevel option in authMiddleware() can be set to one of the following values:

Configuring Log Levels

You can set the log level when defining your middleware:

import { authMiddleware } from '@descope/nextjs-sdk/server';
 
export default authMiddleware({
  projectId: process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID,
  logLevel: 'debug', // Change to 'info', 'warn', or 'error' as needed
  redirectUrl: '/sign-in',
});

Example: Debugging Authentication

Setting the log level to debug provides detailed output in the console, helping to trace authentication issues.

import { authMiddleware } from '@descope/nextjs-sdk/server';
 
export default authMiddleware({
  projectId: process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID,
  logLevel: 'debug', // Enables verbose debugging logs
  redirectUrl: '/sign-in',
});

Sample Debug Logs

When logLevel: 'debug' is set, you might see logs like:

Auth middleware starts
Auth middleware finishes

If an error occurs:

Auth middleware starts
Failed to validate JWT: Failed to validate JWT  [JWSInvalid: Compact JWS must be a string or Uint8Array] {
    code: 'ERR_JWS_INVALID',
    name: 'JWSInvalid'
}
Redirecting to /sign-in

Recommended Log Levels

• Development: Use debug or info to get detailed logs while debugging authentication.
• Production: Use warn or error to log only critical authentication failures.

For full implementation details, check the sample projects:

• App Router Sample
• Pages Router Sample