authMiddleware()

The authMiddleware() helper integrates Clerk authentication into your Next.js application through middleware. authMiddleware() is compatible with both the App and Pages routers.

Usage

Create a middleware.ts file. If your application uses the src/ directory, your middleware.ts file should be placed inside the src/ folder. If you are not using a src/ directory, place the middleware.ts file in your root directory.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware();
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

With the recommended matcher, all routes are protected by Clerk's authentication middleware, with the exception of internal /_next/ routes and static files. Static files are detected by matching on paths that end in .+\..+. If your middleware needs to run on all routes but you don't want Clerk to protect every route, use the ignoredRoutes option.

Default behaviour

If there is no afterAuth present in the middleware, then authMiddleware() will fall back to its default behavior:

• If the .env based settings for the sign-in and sign-up routes are present, add the sign-in and sign-up routes to any routes listed in publicRoutes.
• If the .env based settings are not present, add /sign-in and /sign-up to any routes listed in publicRoutes.
• Make all routes from publicRoutes public.
• Configure all routes from ignoredRoutes to be ignored and return no auth related information.
• Make all remaining routes protected.

Example

Assuming that the .env based settings for sign-in and sign-up are set to /sign-in and /sign-up respectively, the following authMiddleware() would make the routes /, /contact, /sign-in and /sign-up public, no routes ignored, and all remaining routes protected.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware({
  publicRoutes: ["/", "/contact"],
});
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

.env.local
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

Use afterAuth() for fine-grained control

Some developers will need to handle specific cases such as handling redirects differently or detecting if a user is inside an organization. These cases can be handled with afterAuth().

middleware.ts
import { NextResponse } from "next/server";
import { authMiddleware, redirectToSignIn } from "@clerk/nextjs";
 
export default authMiddleware({
  afterAuth(auth, req, evt) {
    // Handle users who aren't authenticated
    if (!auth.userId && !auth.isPublicRoute) {
      return redirectToSignIn({ returnBackUrl: req.url });
    }
    // Redirect signed in users to organization selection page if they are not active in an organization
    if (
      auth.userId &&
      !auth.orgId &&
      req.nextUrl.pathname !== "/org-selection"
    ) {
      const orgSelection = new URL("/org-selection", req.url);
      return NextResponse.redirect(orgSelection);
    }
    // If the user is signed in and trying to access a protected route, allow them to access route
    if (auth.userId && !auth.isPublicRoute) {
      return NextResponse.next();
    }
    // Allow users visiting public routes to access them
    return NextResponse.next();
  },
});

Understanding afterAuth configuration

When using afterAuth, the checks must handle all cases — a custom afterAuth completely overrides the default behavior covered earlier, aside from adding sign-in and sign-up to publicRoutes. afterAuth does not allow you to add just one check and rely on the default behavior otherwise.

Looking at the example immediately above, the following is happening:

1. Redirect all users who are not signed in but who are visiting a protected page to the sign-in route.

if (!auth.userId && !auth.isPublicRoute) {
  return redirectToSignIn({ returnBackUrl: req.url });
}

2. If the user is signed in but is not currently active in an organization and is not visiting the route for selecting an organization, then redirect them to the organization selector. This will force users to select and be active in an organization to visit other parts of the site.

if (auth.userId && !auth.orgId && req.nextUrl.pathname !== "/org-selection") {
  const orgSelection = new URL("/org-selection", req.url);
  return NextResponse.redirect(orgSelection);
}

3. If the user is signed in and accessing a protected route, allow them to access it.

if (auth.userId && !auth.isPublicRoute) {
  return NextResponse.next();
}

4. If none of the above match, then the user is visiting a public route. Allow them to. Don't check if they are signed in -- it doesn't matter.

return NextResponse.next();

Use beforeAuth() to execute middleware before authentication

If you need additional middleware handlers to execute before Clerk's authentication middleware, use beforeAuth(). An example where the middleware handler from next-intl is executed can be seen below.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
import createMiddleware from "next-intl/middleware";
 
const intlMiddleware = createMiddleware({
  locales: ["en", "el"],
 
  defaultLocale: "en",
});
 
export default authMiddleware({
  beforeAuth: (req) => {
    // Execute next-intl middleware before Clerk's auth middleware
    return intlMiddleware(req);
  },
 
  // Ensure that locale specific sign-in pages are public
  publicRoutes: ["/", "/:locale/sign-in"],
});
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

Make routes public by using publicRoutes

By default, Clerk's authMiddleware() treats all routes as private if the middleware runs. If you need to make specific routes public, use the publicRoutes option.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
export default authMiddleware({
  // "/" will be accessible to all users
  publicRoutes: ["/"],
});
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

Use the req object to match against urls. The following example makes all routes but /dashboard public.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware({
  publicRoutes: (req) => !req.url.includes("/dashboard"),
});
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

You can also use regex to match routes. The following is an example of a negative assertion that makes only the /admin route protected.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
 
export default authMiddleware({
  publicRoutes: ["((?!^/admin).*)"],
});
 
export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

If you are building your own sign in pages, you don't need to add these pages to your publicRoutes. They will be inferred from your .env file:

.env
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

Execution order of beforeAuth, publicRoutes, and afterAuth

If you define an afterAuth function, it will run even if the request corresponds to a private route and no user is signed in. If you don’t define an afterAuth function, a redirect response to the signInUrl will be returned automatically. This diagram explains how and when the two handlers are invoked in the runtime.

Debug your middleware

If you are having issues getting your Middleware dialed in, or are trying to narrow down auth-related issues, you can use the debugging feature in authMiddlware. Add debug: true to authMiddlware and you will get debug logs in your terminal.

middleware.ts
import { authMiddleware } from "@clerk/nextjs";
export default authMiddleware({
  publicRoutes: ["/"],
  debug: true
});
 
export const config = {
  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
};

Options

The authMiddleware() method accepts an optional object. The following options are available:

Last updated on March 8, 2024