RFC: forbidden and unauthorized

[ztanner]

Overview

If you’re familiar with the App Router, you’ve likely used notFound() to trigger 404 behavior alongside the customizable not-found.tsx file. In Next 15, we're actively exploring extending this approach to authorization errors:

• forbidden() triggers a 403 error with customizable UI via forbidden.tsx.
• unauthorized() triggers a 401 error with customizable UI via unauthorized.tsx.

Good to know: As with notFound() errors, the status code will be a 200 if the error is triggered after initial response headers have been sent. Learn more.

Enabling the feature

As this feature is still experimental, you’ll need to enable it in your next.config.js file:

const nextConfig = {
  experimental: {
    authInterrupts: true,
  },
};
export default nextConfig;

Using forbidden() and unauthorized()

You can use forbidden() and unauthorized() in Server Actions, Server Components, Client Components, or Route Handlers. Here’s an example:

import { verifySession } from '@/app/lib/dal';
import { forbidden } from 'next/navigation';
export default async function AdminPage() {
  const session = await verifySession();
  // Check if the user has the 'admin' role
  if (session.role !== 'admin') {
    forbidden();
  }
  // Render the admin page for authorized users
  return <h1>Admin Page</h1>;
}

Creating custom error pages

To customize the error pages, create the following files:

// app/forbidden.tsx

import Link from 'next/link';
export default function Forbidden() {
  return (
    <div>
      <h2>Forbidden</h2>
      <p>You are not authorized to access this resource.</p>
      <Link href="/">Return Home</Link>
    </div>
  );
}

// app/unauthorized.tsx

import Link from 'next/link';
export default function Unauthorized() {
  return (
    <div>
      <h2>Unauthorized</h2>
      <p>Please log in to access this page.</p>
      <Link href="/login">Go to Login</Link>
    </div>
  );
}

You can read more about the APIs in the forbidden and unauthorized documentation.

Note: before we stabilize this feature for 15.2, we're planning on adding more capabilities and improvements to the APIs to support a wider range of use cases.

---

We're actively iterating on this API and would love to hear your feedback about how it could be improved. Please feel free to leave any comments/suggestions/concerns in this thread. Thank you!

[jonathanhefner]

A common pattern for handling unauthenticated access is to redirect the user to the sign-in page, and then make a successful sign-in redirect back to the original starting point. Can that pattern be replicated with unauthorized()?

[Netail]

Sadly, the http 401 standard does not mention anything of supporting a new location. A client, of course, could implement it themself, but is not expected to - some clients may only redirect on 301, 302, 307 & 308. In such case you could use redirect() .

[darthmaim]

see the updated docs in this PR for an example of redirecting on error:

• support cause in Next.js error signals #73665

This does however not handle the case of redirecting back to the start point.

[simoncave]

Here's an example which does that: https://gfcw3s-3001.csb.app/examples/redirect

The way it works is that unauthorized.js renders a client component which redirects the user to `/sign-in?redirectUrl=${window.location.href}`. Once the user signs-in, they are redirected back to the original page.

Alternatively, we should be able to just render <SignInPage> inline inside unauthorized.js. As the URL doesn't change, once the user signs-in then the page should just reload and be authorized. But that doesn't seem to be working for me. Here's an example: https://gfcw3s-3001.csb.app/examples/inline

It seems that, after setting the session cookie, the page does a soft-reload but remains on unauthorized.js. It's not until I do a hard-reload that I see page.tsx. My expectation is that setting a cookie should reset the interrupt, and return to page.tsx. Any ideas, @ztanner?

https://codesandbox.io/p/devbox/gfcw3s

[jonathanhefner]

Thank you for the replies! 😃 Actually, I think what is important is that the user is shown the sign-in page (without any extra clicks) upon unauthenticated access, and is shown the original page (without any extra clicks) upon successful authentication.

In particular, I am concerned about obtaining a reference to the original page in generic way. Accessing the current URL is a known issue (see also #43704, #46618, #58212, #65282, #73800).

It seems that, after setting the session cookie, the page does a soft-reload but remains on unauthorized.js. It's not until I do a hard-reload that I see page.tsx. My expectation is that setting a cookie should reset the interrupt, and return to page.tsx.

I think that might be expected behavior. I think it might be the same as revalidatePath ("only invalidates the cache when the included path is next visited"), so a reload or redirect is needed.

I put together a similar demo with inline sign-in, but using a redirect: https://next-sign-in-in-place.vercel.app/ (source code).

For the redirect URL, I used the HTTP referer header. However, that header generally isn't reliable, so it would be good to have an alternative mechanism.

Another issue is the flash of white between redirects. That's to be expected, but it would be nice to eliminate it.

I think if Next.js provided a server-side refresh() function to trigger a client-side refresh, it could potentially address both problems.

[darthmaim]

One thing that is still missing for me with not-found.tsx is the ability to set metadata (see #45620).

Now that there are more pages with forbidden.tsx and unauthorized.tsx it would be a good time add the ability to export metadata from these error pages.

[KraKeN-47]

Probably a good idea to also document on how streaming (loading.tsx) will affect this flow. Because to my understanding you will get status 200 instead of 401/403.

[switz]

So this is very nice and long awaited (no pun intended), but I'm wondering why we're sugaring over status codes instead of just letting us return status(401); or something to that effect. Chaining it with redirect would be nice too return status(401).redirect('/');

I get the advantage of custom error pages (unauthorized.tsx), but we're adding cruft to web standards by not just leaning on them and creating our own language. If we can put in any status code, we can do 401.tsx or _401.tsx?

Can you explain the reasoning behind not just opening up any status code to be sent?

[Netail]

Regarding the redirect, see #73753 (reply in thread)

For webpages I think they now covered all possible return status codes that could render complete pages differently, other status codes are more meant for API endpoints? Instead of using the HTTP code as file name, it's easier to know what the file is for, instead of mapping the HTTP code to the correct meaning in your head or having to search what the HTTP code meant again.

[switz]

What about a 500 or 503 if my database is down? Return a 201 from a server action? Creating a new set of web standards that are not portable and only specific to next.js is weird, and one of the common criticisms of this framework. Just let us lean on the standards and re-use our existing knowledge.

[Netail]

You can throw a 500 by throwing an error (throw new Error()), which will then render the error.tsx. Gotta agree on the server-actions part, that is weird

[Netail]

Maybe the possibility of passing down a payload to the unauthorized / forbidden page? e.g. for info on which scope a user is missing.

Also a retry/reset function similar to error pages could be nice for forbidden, in case a colleague added the scope a few seconds later?

[darthmaim]

Passing down a cause will be possible once this is merged:

• support cause in Next.js error signals #73665

Edit: after reading your question and the PR again, the payload might not be available on the error page, but only when catching the error 🤔

[Netail]

You could technically stringify some data into the error message then parse it out. The error passed into the function will be passed down as the cause prop to the error page

[simoncave]

I wrote a feature request proposing this.

I like the approach in the PR: the payload gets attached as the cause.

@ztanner, is the intention to allow cause to be read from unauthorized.js and forbidden.js, presumably with a reset function as well?

[aravind-eng]

Is it possible to globally check whether a user is authenticated and invoke unauthorized() without having to implement the check on every individual route or page? Based on the current documentation, it seems necessary to perform this authentication check separately for each route.

Is there a more efficient method or best practice for handling authentication across the entire application?

Thank you for your assistance!

[darthmaim]

This could be a possible solution:

• Introduce experimental Request Interceptors #70961

[aravind-eng]

Thats great!. This is exactly what i am looking for. Is this feature already available in the current canary build?
Thanks for sharing these details.

[matthiasfeist]

I'd like to suggest also exposing the Errors that are thrown by these methods or some function that can "identify" them.

The reason is that these control flows are realised via JS errors that are thrown and sometimes in a catch block, you need to differentiate if it's a not found/unauthorized/forbidden error and then re-throw it while handling other application errors.
So some method to identify these re-throwable errors would be nice.

It seems like library authors like for next-safe-action are reaching very deep into undocumented files to make this happen right now: https://github.com/TheEdoRan/next-safe-action/blob/86f00f422c6799e81c57d402dfc40354cf78db17/packages/next-safe-action/src/utils.ts#L5

[darthmaim]

See this PR:

• support cause in Next.js error signals #73665

[matthiasfeist]

Yes that might help but is not quite solving the problem yet.

[sawa-ko]

I wonder... why instead of making specific functions for “popular” http response types, better a generic function that allows us to respond with any type of http response?

[aralroca]

Because the response has already been sent (is being sent, as part of the streaming). These methods cause the rendering to be interrupted and a soft-redirect is made from the client, but the status is always 200.

[aralroca]

Although they are useful, I wonder if it is appropriate to use them in server components. For me it makes more sense from an earlier stage, the middleware, to check this and return the Response if necessary with the appropriate status. In the end if you are already rendering the page in streaming the headers have already been sent and using these methods cause a soft-redirect from the client, where the status is always 200, which is fine to give feedback to the users, but I have my doubts if it is good practice.

[aralroca]

ok, can make sense to use it inside server actions

[colinclerk]

Could you share the suggested approach for implementing reverification? (e.g. user is allowed to perform, but needs to reverify their credentials before the sensitive action is allowed). We are unsure how to solve it with this API, primarily because we think we'd need "cause" on the client.

We're particularly interested in how we can do it as a library, but happy to try and derive from the individual developer example.

The specific examples we'd like to understand are:

• A client component is using useActionState to call a server action. In the server action we want to call forbidden({cause: "needs_reverification"}) and somehow get the cause from the state
• A client component is calling fetch() to a route handler. In the route handler, we want to call forbidden({cause: "needs_reverification"}) and determine the cause from the response

Alternatively - is the advice not to use these APIs and return early instead? If so, can you provide a mental model for when a throw-based flow is suggested (redirect/forbidden/notFound) vs when a early return flow is suggested?