Allow sending of arbitrary data via unauthorized.

[simoncave]

Goals

Allow context to be sent from unauthorized() to unauthorized.js.

Non-Goals

No response

Background

Next.js 15.1 introduces the unauthorized and forbidden functions, available behind the authInterrupts configuration option.

The documentation for unauthorized includes an example titled "Displaying login UI to unauthenticated users". In this example, a server component checks to see if the user is authenticated and, if not, calls unauthorized(). This interrupts rendering of the component by throwing an error, which is captured in unauthorized.js, which renders log-in UI as a fallback.

This works for simple authorization schemes, where you're either authorized (200) or not (401). But in some authorization schemes, authorization comes with variable levels of assurance based on how you authenticated. This means that there can be more than two outcomes:

1. 200 OK — You're authorized.
2. 401 Unauthorized — You're not authorized, so you need to log-in.
3. 401 Unauthorized — You're not authorized enough, so you need to step-up by using a stronger form of authentication (e.g. a passkey on a physical security key) ¹.

If Next.js is in full control of the authorization scheme, then it should be possible to distinguish between scenarios 2 and 3 from unauthorized.js. But if the authorization violation occurred in an upstream service which is returning a 401 response to Next.js, then we need to be able to provide an argument to unauthorized that we can read from unauthorized.js.

Proposal

The unauthorized function should accept a single argument which is either:

• Ideally: Any arbitrary value which can be serialized by React.
• At a minimum: Any string.

server-actions.ts

"use server";

import { unauthorized } from "next/navigation";

export async function sendPayment(options: { recipient: string, amount: number }) {
  const authnToken = (await cookies()).get("AuthnToken");

  const response = await fetch("https://payments-service.example", {
    body: JSON.stringify(
    headers: {
      authorization: `Bearer ${authnToken)`,
    },
  });

  if (response.status === 401) {
    const stepUpToken = response.headers.get("x-authz-step-up-token");
    unauthorized(stepUpToken);
  }

  if (!response.ok) {
    throw new Error("Payment failed.");
  }
  
  return { ok: true };
}

The unauthorized.js file should receive the argument as a prop.

unauthorized.ts

import Login from "@/app/components/Login";
import StepUp from "@/app/components/StepUp";
 
export default function UnauthorizedPage(props: { detail: unknown }) {
 const stepUpToken = props.detail;

  return (
    <main>
      <h1>401 - Unauthorized</h1>
      {stepUpToken ? <StepUp token={stepUpToken} /> : <Login />}
    </main>
  )
}

Note

This feature request focusses on unauthorized, but what makes sense for unauthorized may also make sense for forbidden and even notFound.

Footnotes

1. It might seem like scenario 3 should be a 403, but the devil is in the details. A 403 error is about a subject's relationship to a resource. It means "you're not allowed to do that". Scenario 3 means "you are allowed to do that, but before I let you do it, I need more assurance that you are who you say you are". ↩

[colinclerk]

Clerk would also like the ability to pass reasons through error responses, with the same immediate goal of improving DX for "Step Up" auth (which we call "reverification" of signed in users).

We would also like the ability to handle server action errors from the client, instead of just from unauthorized.ts, but falling back to unauthorized.ts is a reasonable start.

[simoncave]

Any thoughts on the API? Would you change anything about what I proposed?

[feedthejim]

Hey @simoncave, thanks for writing this up. Could you move close this and move this over to the RFC discussion here #73753 ? I will coalesce all feedback there and bring it back to the team.

[simoncave]

👍🏻 → #73753 (reply in thread)

[simoncave]

See #73753 (reply in thread)