How should authentication be handled in an app that uses only external APIs?

[hamez0r]

Our app is using our micro-services suite. One of them is responsible for authentication (using Oauth2). Requests to protected endpoints must include Bearer Token. I'm trying to figure out a way to handle 401 responses and redirect to the login flow (which is started by /oauth2/login-required route in the app).

I created an authenticatedRequest that does this

const request = async (
  method: Method,
  url: RequestInfo | URL,
  options?: RequestInit,
) => {
  const response = await fetch(url, {
    method,
    redirect: "follow",
    ...options,
    headers: {
      Authorization: `Bearer ${bearerToken()}`,
      ...options?.headers,
    },
  });

  if (response.status === 401) {
    throw new UnauthorizedError();
    // I also tried this, with no success, and I don't like the coupling
    // throw redirect({ to: "/oauth2/login-required" });
  }

  return response;
};

This way, if the user is not authenticated (first visit), or the token was revoked, or for whatever other reason the endpoint returned 401, I know it's time to redirect to /oauth2/login-required (using refresh tokens is out of scope here).

My initial tought was to have the error handled by queryCahe

export async function getRouter() {
  const context = await getContext();

  const router = createTanStackRouter({
    routeTree,
    context,
    scrollRestoration: true,
    defaultPreload: "intent",
    defaultPreloadStaleTime: 0,
  });

  // Why does this look fishy?
  context.queryClient.getQueryCache().config.onError = (error) => {
    if (error instanceof UnauthorizedError) {
      router.navigate({ to: "/oauth2/login-required" });
    }
  };

  setupRouterSsrQueryIntegration({ router, queryClient: context.queryClient });

  return router;
}

Then I'm trying to defer data loading in my component

export const Route = createFileRoute("/_layout")({
  loader: async ({ context }) => {
    context.queryClient.query(userDetailsOptions);
  },
  component: RouteComponent,
});

function RouteComponent() {
  const { data: user } = useSuspenseQuery(userDetailsOptions);
  console.log(user);
  return (
    <div>
      <p>Hello "/_layout" route!</p>
      <Outlet />
    </div>
  );
}

This results in the following error

A query that was dehydrated as pending ended up rejecting. [["user-details"]]: [object Response]; The error will be redacted in production builds
node:internal/process/promises:392
      new UnhandledPromiseRejection(reason);
      ^

UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "#<_Response>".

I'm starting to realize that since I intend to stream the queried data, the server has already replied with 200. And then I'm changing my mind and replying with 307, so that's one possible source for the disconnect.

Is there a way to achieve what I want using start + router + query?
My next try was going to be adding error boundaries, but I'm not sure this would solve the issue, since it looks like my issue is rather related to the server, and not React-land.

[XXMOHAMED012]

do not redirect or navigate on a isomorphic function, this creates hydration errors all the time, try to navigate from inside the compoenent.

i hope this can help you:

i am using Tanstack Start and Tanstack query with axios,
we have 2 services: auth service and api service,
inside my frontend app i need to call the auth service using the auth service session cookie to ask for a jwt, then use this jwt to get an access token from the api so i can use the app.

in my case the full app is protected, (there is no public routes) but you can use the same way to make some routes public and others protected, just create a pathless route and make it the gate, then put all protected routes inside it.
this is a custom setup, and i created it like that so i can enable the router preloading while making sure side effects does not fire when a route is preloaded (like a 401 redirect or loader error), this problem was hard to solve.

this is the gate, any thing under this layout will be protected, beforeLoad will run with every navigation.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { exchange } from "@/shared/api/api";

export const Route = createFileRoute("/_layout")({
  beforeLoad: async ({ location }) => {
    await exchange().catch(() => {
      throw redirect({
        href: `${import.meta.env.VITE_AUTH_URL}/?from=${encodeURIComponent(location.href)}`,
      });
    });
  },
});

this is a part of my api client, where i exchange and handle 401 errors and refresh, any other errors should not be handled at this layer.

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  withCredentials: true,
});

api.interceptors.response.use(null, async (error: AxiosError) => {
  if (!isAxiosError(error) || error.response?.status !== 401) {
    return Promise.reject(error);
  }

  const orignalRequest: RetriedConfig | undefined = error.config;
  if (!orignalRequest || orignalRequest.retried) {
    return Promise.reject(error);
  }
  orignalRequest.retried = true;

  try {
    await exchange(true);
  } catch (err) {
    error.cause = err instanceof Error ? err : undefined;
    return Promise.reject(error);
  }
  return api(orignalRequest);
});

// exchange
const chain = async (): Promise<boolean> => {
  const { data } = await axios.get<{ token: string }>(
    `${import.meta.env.VITE_AUTH_URL}/api/auth/token`,
    { withCredentials: true }
  );

  const { data: session } = await axios.post<{ data: { status: string } }>(
    `${import.meta.env.VITE_API_URL}/auth/exchange`,
    null,
    {
      headers: { Authorization: `Bearer ${data.token}` },
      withCredentials: true,
    }
  );
};

let inFlight: Promise<void> | null = null;
let live = false;

export const exchange = (force = false): Promise<void> => {
  if (live && !force) {
    return Promise.resolve();
  }
  inFlight ??= chain()
    .then(
      () => {
        live = true;
      },
      (error: unknown) => {
        live = false;
        throw error;
      }
    )
    .finally(() => {
      inFlight = null;
    });
  return inFlight;
};

then to make the setup preloading safe, i handle errors in 2 places, 1- route error component, 2- component query (i made a custom hook for it), with this setup, i can make sure side effects fires only when the user makes a real navigation.

this is the custom hook:

import {
  type DefaultError,
  type QueryKey,
  type UseSuspenseQueryOptions,
  type UseSuspenseQueryResult,
  useSuspenseQuery,
} from "@tanstack/react-query";
import { useEffect } from "react";
import { toast } from "sonner";
import { errorMessage } from "./api";

export function useApiQuery<
  TQueryFnData = unknown,
  TError = DefaultError,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
>(
  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>
): UseSuspenseQueryResult<TData, TError> {
  const query = useSuspenseQuery(options);
  const message = query.error ? errorMessage(query.error) : null;

  useEffect(() => {
    if (message) {
      toast.error(message, { id: message });
    }
  }, [message]);

  return query;
}

and this is the error component (this is a global one that handles all route errors) you can make a error component for each route if you need, i used to do that, but i made this to solve the preloading issue.

export function RouteError({ error }: ErrorComponentProps) {
  const message = errorMessage(error);

  useEffect(() => {
    toast.error(message, { id: message });
  }, [message]);

  return <p>{message}</p>;
}

in this setup:

user opens the app, beforeLoad will run and check if he is authorized:
A- user is authorized => render the route.
B- user is not authorized => redirect to the auth server.
(some times you need to handle exchange or refresh errors in different ways, like 429 errors, in this case redirecting the user to the auth server is not a good solution, and may not solve the problem)

now the user is authorized and can use the app, when a route has a loader,
the loader will run the query (in this example the errors will be ignored).
there is a lot of details here and you can use preloading or not use it, but i will explain my current setup as i said.
an example:

import { noop } from "@tanstack/react-query";
import { createFileRoute } from "@tanstack/react-router";
import { sessionQuery } from "@/features/student/api/student";
import Student from "@/features/student/pages/Student";

export const Route = createFileRoute("/_layout/_sidebar/student")({
  loader: ({ context }) => {
    context.queryClient.query(sessionQuery).catch(noop);
  },
  component: Student,
});

the component:

import { useApiQuery } from "@/shared/api/useApiQuery";
import { sessionQuery } from "../api/student";

const Student = () => {
  const { data } = useApiQuery(sessionQuery);

  return (
    <>
      <div>{data.user_id}</div>
      <div>{data.scope}</div>
      <div>this is just for testing the data access layer</div>
    </>
  );
};

export default Student;

now:
A- the loader qury fails and returns an error => the router will render the error component (the global one) and it will handle the error.
B- the route component is rendered before and there is data in the query cache, when the background refetch fails => the custom hook will handle the error.

they can not conflict with each other, because you only have one component rendred at a time, the route component, pending component, error component.

i hope this examples help you or give an idea how to handle the 401 and other errors, i still make changes to this setup and will be happy to discuss more if it does not help you or you still have cases that needs to be handled.

also you can give this to AI and ask it to create a prototype for your app, then if the prototype solves your problems, you can build on it and create your custom setup.

[XXMOHAMED012]

note: this setup has ssr: false on the root route
because the first request will run on the server, and browser cookies are not avilable there, so every request will return a 401.

i think i can solve it by creating an isomorphic function, so if the request runs on the server i will read the cookies from the client and call the auth and the api using them, then return the response and set the cookies for the client if the auth or api sets them, (the exchange also can run on the server)

but i deferred it now

[hamez0r]

Thanks for the explanation, I ended up doing pretty much the same thing.

As for the isomorphic function for the token, here's what I have

export const bearerToken = createIsomorphicFn()
  .server(() => {
    const request = getRequest();
    const cookie = request.headers.get("cookie") ?? "";
    return readTokenFromCookie(cookie);
  })
  .client(() => {
    return readTokenFromCookie(document.cookie);
  });

function readTokenFromCookie(cookie: string) {
  const token = cookie
    .split(";")
    .map((c) => c.trim())
    .find((c) => c.startsWith(BEARER_TOKEN_KEY + "="))
    ?.replace(BEARER_TOKEN_KEY + "=", "");
  return token ?? "";
}

We're using oauth, my server gets the token and then sets the cookie on the client.