RFC: TanStack Start Adapter for oidc-spa

[garronej]

Context

oidc-spa is a client-side implementation of the OpenID Connect Authorization Code Flow + PKCE.
All token exchanges with the authorization server happen entirely in the browser.

This approach offers major benefits:

• No database required: The auth server acts as session store! No need to spin up a postgress or mongodb like with NextAuth. Solution like Clerk or Auth0 let you bypass having a db as well... at the cost of vendor lock in.
• Portability, We can easily feature light weight adapter for differnet framwork and meta framwork since the solution is truely self contained.
• Security through simplicity, fewer moving parts, fewer risks.

We discuss why we deliberately avoid involving the backend in the token exchange process in this article:
“Why No Client Secret?”.

However, this approach introduces two core challenges:

1. Security perception, exchanging tokens in the frontend is often seen as weaker than doing it server-side.
   oidc-spa mitigates this through strict isolation of tokens and novel protection techniques
   against XSS and supply chain compromise.
   (See my Keycloak annual conference talk.)
2. SSR integration, in full-stack frameworks, the server initially renders HTML without
   knowing the user’s authentication state. This makes SSR and server data loading trickier.

This RFC describes how to solve both challenges cleanly in TanStack Start,
while keeping the developer experience (DX) consistent with idiomatic React/TanStack patterns.

---

The Challenge: SSR & Server Functions

Because tokens are exchanged on the client, the server doesn’t automatically know who the user is.
This makes it difficult to:

• Render templates conditionally based on authentication state.
• Fetch user-specific data on the server (e.g., querying todos from a DB).

This typically affects:

• React Server Components (Next.js)
• Isomorphic loaders (ReactRouter Framework Mode, TanStack Start)
• Server functions (TanStack Start)

We need a way to handle these cases without rewriting mental models or breaking SSR entirely.

---

Why Other SDKs Don’t Have This Problem

Libraries like Clerk or NextAuth manage authentication server-side.
The server owns token exchange, so it always knows the auth state.
But this comes at a cost, deeper coupling between the framwork and the auth requires a database to store session, or vendor lock in to a specic auth provider.

Our goal: Keep the simplicity of client-only OIDC, while retaining full-stack capabilities.

---

Solving SSR

There are three main reasons for using SSR:

1. First-page performance, render HTML quickly before JS loads.
2. SEO: Serve pre rendered search engine relevent content and metas tags.
3. Overfetching prevention, fetch only the data you need, not everything.

Since the auth state only exists client-side, full SSR isn’t possible for pages that render content contingent on the authentication state or user identity.
But partial SSR is, we can still server-render everything except the parts that depend on authentication.

Example

Using suspense to defer the rendering of the auth button to the client.

<header>
  My Company
  <a href="/home">Home</a>
  <a href="/dashboard">Dashboard</a>
  <a href="/contact">Contact</a>

  <Suspense fallback={<Spinner />}>
    <AuthButtons />
  </Suspense>
</header>

function AuthButtons() {
  const { isUserLoggedIn, login, logout } = useOidc();
  return isUserLoggedIn
    ? <button onClick={logout}>Logout</button>
    : <button onClick={login}>Login</button>;
}

This is what it'll look like in practice (the video is slowed down, it goes much faster):

Screen_Recording_2025-09-30_at_13.44.21.mov

💡 Key Insight:
Use React Suspense to defer the rendering of components using useOidc to the client
everything else can be SSR’d.

---

Now, how do we provide an experience that avoids overfetching in TanStack Start?

TanStack Start doesn’t yet support Server Components, so we can set those aside for now.
What it does have are loaders, functions that can run isomorphically on both the server and client, allowing you to prefetch the data required to render a route.

Here’s a typical example:

src/api.todos.ts

import { createFileRoute } from "@tanstack/react-router";
import { getOidcRequestMiddleware } from "src/oidc";

export const Route = createFileRoute("/api/todos")({
    server: {
        middleware: [getOidcRequestMiddleware({ assert: "user logged in" })],
        handlers: {
            GET: async ({ context: { oidcContext }}) => {

                const { accessTokenClaims } = oidcContext;

                const todos= await sqLite.getTodos({ userId: accessTokenClaim.sub });

                return todos;
            }
        }
    }
});

import { createFileRoute } from "@tanstack/react-router";
import { enforceLogin, getOidcAccessToken } from "src/oidc";

export const Route = createFileRoute("/todos")({
  beforeLoad: enforceLogin,
  loader: async () => {
    // 🛑 This will fail when the loader in run on the server!
    const { accessToken } = await getOidcAccessToken({ assert: "user logged in" });
    const resp = await fetch("/api/todos", { Authorization: `Bearer ${accessToken}`});
    const todos = (await resp.json()) as { id: number; isDone: boolean; text: string }[];
    return todos;
  },
  component: RouteComponent,
});

function RouteComponent() {

  const todos = Route.useLoaderData();

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>
          {todo.isDone && "✅"} {todo.text}
        </li>
      ))}
    </ul>
  );
}

In this configuration, the /api/todos endpoint requires an access token.
The issue arises when the loader runs on the server, since the server doesn’t know the authentication state, meaning we can’t use getOidcAccessToken() there.

The only option is to disable SSR (ssr: false) for this route so it runs entirely on the client:

import { createFileRoute } from "@tanstack/react-router";
import { enforceLogin, getOidcAccessToken } from "src/oidc";

export const Route = createFileRoute("/todos")({
  beforeLoad: enforceLogin,
  loader: async () => {
    const { accessToken } = await getOidcAccessToken({ assert: "user logged in" });
    const resp = await fetch("/api/todos", { Authorization: `Bearer ${accessToken}`});
    const todos = (await resp.json()) as { id: number; isDone: boolean; text: string }[];
    return todos;
  },
  component: RouteComponent,
  ssr: false,
  pendingComponent: ()=> <p>Nice SSR fallaback</p>
});

function RouteComponent() {

  const todos = Route.useLoaderData();

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>
          {todo.isDone && "✅"} {todo.text}
        </li>
      ))}
    </ul>
  );
}

This works, but it doesn’t solve the second issue: overfetching.
It’s fine if the page isn’t fully SSR’d (we still benefit from SSR for the static layout and metadata, which is the more important).
The real concern is that the client might fetch far more data than needed.

For instance, if the /api/todos endpoint returns detailed metadata about each todo, but the page only renders text and isDone, we’re transferring unnecessary data.
That’s one of the main reasons SPA architectures have a reputation for being inefficient: they often overfetch.
To achieve optimal performance without forcing overly fine-grained APIs, we need a way to ensure that only the required data is sent to the client.

The solution: Server Functions.

import { createFileRoute } from "@tanstack/react-router";
import { enforceLogin, getOidcFnMiddleware } from "src/oidc";

const getTodos = createServerFn()
    .middleware([ getOidcFnMiddleware({ assert: "user logged in"}) ])
    .handler(async ({ oidcContext }) => {
        const { accessToken } = oidcContext;

        const resp = await fetch("/api/todos", { Authorization: `Bearer ${accessToken}`});
        const todos = (await resp.json()) as { id: number; isDone: boolean; text: string }[];

        return todos.map(({id, isDone, text })=> ({id, isDone, text }));
    });

export const Route = createFileRoute("/todos")({
  beforeLoad: enforceLogin,
  loader: async () => {
    const todos = await getTodos();
    return todos;
  },
  component: RouteComponent,
  ssr: false,
  pendingComponent: ()=> <p>Nice SSR fallaback</p>
});

function RouteComponent() {

  const todos = Route.useLoaderData();

  return (
      <ul>
        {todos.map((todo) => (
          <li key={todo.id}>
            {todo.isDone && "✅"} {todo.text}
          </li>
        ))}
      </ul>
  );
}

In this model, the /api/todos endpoint is requested on the server and only the data actually needed for rendering is sent to the client.

This works because ssr: false ensures the loader is executed exclusively on the client, while the getTodos function itself runs on the server.
Since it’s client-initiated, we can safely forward the authentication context, including the accessToken.

---

To sum up, the rules for using oidc-spa in TanStack Start are:

1. SSR is possible! Just wrap any component that uses useOidc within a narrowly scoped Suspense boundary.
2. You can use server functions with access to the authentication context, as long as they are always triggered by the client:
   • either via a route loader (marked ssr: false), or
   • within a useEffect() callback (which always runs client-side).

That’s it.
These are very reasonable tradeoffs for what you gain: a full-stack, provider-agnostic authentication solution.
Learning oidc-spa isn’t just learning a bespoke SDK, it’s learning core concept of OpenID Connect standard through a portable solution.

---

Now that we’ve covered the theoretical foundation, let’s move on to the actual API that oidc-spa exposes.

---

Example usage

src/oidc.ts

import { oidcSpa } from "oidc-spa/tanstack-start/react";
import { z } from "zod";

export const { 
    bootstrapOidc, 
    OidcSuspense,
    useOidc, 
    getOidcAccessToken, 
    getOidcFnMiddleware, 
    getOidcRequestMiddleware 
} = oidcSpa
    .withExpectedDecodedIdTokenShape({
        decodedIdTokenSchema: z.object({
            preferred_username: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
        })
    })
    // NOTE: Optional. If omitted, `getOidcFnMiddleware` and `getOidcRequestMiddleware`
    // will not be available (see the note on multi-instance setups below).
    .withAccessTokenValidation({
        // Suitable for any provider that issues JWT access tokens.
        // Keycloak does this by default.
        type: "RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens",
        decodedAccessTokenSchema: z.object({
            audience: z.string();
            sub: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
        }),
        additionalValidation: ({ paramsOfBootstrap, accessTokenClaims }) =>
            accessTokenClaims.audience === "account"
    })
    .finalize();
    /*

    OR, for providers issuing opaque access tokens that require
    introspection endpoints for validation:

    .withAccessTokenValidation({ type: "clerk", ... })
    .withAccessTokenValidation({ type: "Auth0", ... })
    .withAccessTokenValidation({ type: "EntraID", ... })
    .withAccessTokenValidation({ type: "Google OAuth2" })

    // You can also define custom validation logic for arbitrary providers:
    .withAccessTokenValidation<{ sub: string; }>({
        type: "custom",
        createValidateAndGetAccessTokenClaims: ...
    })
    */

// bootstrapOidc Can be called here or anywhere else, even inside a component body (just like a hook).
// Any subsequent invocation will be ignored.
if (import.meta.env.USE_MOCK) {

    bootstrapOidc({
        isMock: true,
        mockDecodedIdToken: {
            preferred_username: "jhond",
            realm_access: { roles: ["admin"] }
        },
        mockAccessTokenClaims: {
            audience: "profile",
            sub: "123",
            realm_access: { roles: ["admin"] }
        }
    });

} else {

    bootstrapOidc({
        issuerUri: "https://auth.my-company.com/realms/myrealm",
        clientId: "myclient",
        startCountdownSecondsBeforeAutoLogout: 45,
        // ...
    });

}

---

About OidcSuspense

As mentioned earlier when discussing SSR boundaries, I initially hoped to let users rely solely on React’s built-in <Suspense />.
Unfortunately, there’s currently no way (while rendering on the server) to signal “this can’t be rendered here, defer to the nearest Suspense boundary and let the client continue.”
Throwing a never-resolving suspense works, but it leaves the server waiting for a stream that never completes — causing the loading tab to spin indefinitely.

Until React offers more granular control over suspense semantics, you need to use the provided wrapper:

<OidcSuspense fallback={<Spinner />}>
    <AuthButtons />
</OidcSuspense>

I’m considering naming this utility simply <Suspense />, since it behaves identically for everything else, meaning you could use it everywhere you’d normally use a Suspense boundary, and it would just work.

---

About getOidcFnMiddleware

const fn = createServerFn()
    .middleware([
        getOidcFnMiddleware({ 
            // assert: "user logged in"
            hasRequiredClaims: ({ accessTokenClaims }) =>
                accessTokenClaims.realm_access.roles.contain("admin")
        })
    ])
    .handler(async ({ oidcContext }) => {
        // NOTE: `isUserLoggedIn`, `accessTokenClaims`, and `accessToken`
        // are type-coupled for strong typing.
        const { isUserLoggedIn, accessTokenClaims, accessToken } = oidcContext;

        if (isUserLoggedIn) {
            // Here, `accessTokenClaims` and `accessToken` are defined.
        } else {
            // Here, they are undefined.
        }

        // If you specify `assert: "user logged in"`,
        // `isUserLoggedIn` will be statically typed as `true`.
        // If it’s not true, a 401 is returned automatically.
        // Both `accessToken` and `accessTokenClaims` are guaranteed to be defined.
        // oidc-spa validate, the signature and expiration internally.  
    });

The hasRequiredClaims option is mandatory, without it, it’s too easy for developers to write code like this:

const { decodedIdToken } = useOidc({ assert: "user logged in" });

useEffect(() => {
  if (decodedIdToken.realm_access.roles.contain("admin")) {
    // Server function
    deleteDatabase("prod");
  }
}, []);

In this example, the user checks permissions on the client before making an RPC call, but their server function might neglects to enforce them server-side.
That’s dangerous, the server must always verify claims again.
Hence, hasRequiredClaims ensures the boundary is enforced properly at the cost
of making user write hasRequiredClaims: ()=> true a lot.

---

About getOidcRequestMiddleware

Works the same way as getOidcFnMiddleware, but for API endpoints instead of server functions.

---

Talking to multiple OAuth2-enabled resource servers

In most cases, when we talk about a “web app,” we’re referring to the pair (client, dedicated API).
This boundary becomes less clear with full-stack frameworks like Next.js or TanStack Start, but the conceptual model remains valid.

By default, when you call .withAccessTokenValidation(), oidc-spa assumes that the resource server for which the access token is valid is everything that runs on the
backend in your TanStack Start app: Server Function and API handlers.

However, this isn’t always the case, your app might also need to talk directly to other resource servers, such as an S3-compatible storage (MinIO), a Vault server, or the Kubernetes API.

Often, your backend acts as a proxy to these services.
For example, when interacting with Kubernetes, you might call a backend endpoint that forwards requests and injects credentials.
But this isn’t required, your app can just as well talk directly to multiple resource servers, especially in SPA or Electron-like environments where the frontend is the primary application and the backend remains stateless.

---

RFC 8707, Resource Indicators for OAuth 2.0

The OIDC specification includes RFC 8707, which allows a client to request access tokens for a specific resource server.
Providers like Auth0 or Entra ID support this pattern:
you register a client and separately register APIs (resource servers), then define which APIs each client can access.

oidc-spa’s core supports this concept, but the higher-level framework adapters (like this one) intentionally do not, for a simple reason:
Keycloak, the de facto open-source standard for OIDC, doesn’t implement the resource parameter.

Keycloak conflates OIDC clients and resource servers.
When you create a client in Keycloak, you’re effectively defining both the application and the resource server it talks to.
So, if you want your app to talk to multiple resource servers, you’ll end up creating multiple clients, e.g.:

myapp
myapp-vault
myapp-minio
myapp-kube

There are two possible approaches:

1. Token Exchange, a standardized mechanism defined in RFC 8693, which allows
   exchanging a token issued for one client or audience for another.
   In practice, however, it’s implemented by very few IdPs,
   Keycloak being one of the only relevant ones.
   While it works, the model feels conceptually off: you still end up defining multiple clients for what is effectively a single application.
   We don’t plan to support this because, despite being a standard, it’s not widely adopted and doesn’t align with our goal of remaining provider-agnostic.

2. Multiple OIDC instances, create one oidc-spa instance per client.
   This is more standard-compliant and fully supported by oidc-spa.
   It’s technically non-trivial, but already solved internally, multiple client instances can coexist in one app seamlessly, allowing communication with multiple backends.

---

In summary, oidc-spa’s design is influenced by Keycloak’s interpretation of the standard, but it aims to balance practicality and correctness:

• We optimize for a first-class Keycloak experience.
• We avoid non-standard extensions like token exchange.
• We fully support multi-client setups for apps that need to talk to multiple resource servers.

It’s not the most elegant design, but it stays faithful to the standards and provides a consistent, developer-friendly experience.
If Keycloak ever supports true multi-resource semantics, oidc-spa will evolve accordingly.
Until then, multiple instances remain the recommended approach.

---

Example: Connecting to Vault

If your app also needs to talk to Vault (for example), you can define another OIDC instance like this:

src/getVaultToken.ts

import { oidcSpa } from "oidc-spa/tanstack-start/react";
import { z } from "zod";

const { bootstrapOidc, getOidcAccessToken } = oidcSpa.withAutoLogin().finalize();

/**
 * Exchanges the OIDC access token for a Vault token.
 * 
 * This assumes that the Vault OIDC auth method is enabled and configured under the path:
 * `auth/oidc/`
 * 
 * See: https://developer.hashicorp.com/vault/docs/auth/jwt/oidc-login
 */
export async function getVaultToken() {

  // Only first call matters, subsequent calls are  NoOp
  bootstrapOidc({
    issuerUri: "https://auth.my-company.com/realms/myrealm",
    clientId: "myclient-vault",
  });

  // No need to assert user logged in here, we enabled autoLogin.
  const { accessToken } = await getOidcAccessToken();

  const response = await fetch("https://vault.my-company.com/v1/auth/oidc/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jwt: accessToken }),
  });

  if (!response.ok) {
    throw new Error(`Vault OIDC login failed: ${response.statusText}`);
  }

  const { auth } = await response.json();
  return { vaultToken: auth.client_token };
}

Here, we don’t specify .withAccessTokenValidation() because it’s out of scope for our application,
the Vault server itself will handle token validation (the app exchanges the access token for a Vault token).

There’s no risk of a double login here: both myclient and myclient-vault belong to the same realm (myrealm) on the same authentication server.
SSO ensures that if you’re authenticated with one, you’re automatically authenticated with the other, you might just be prompted to consent to extra claims.

[mwolf1989]

I’m considering naming this utility simply , since it behaves identically for everything else, meaning you could use it everywhere you’d normally use a Suspense boundary, and it would just work.

I would not use the Same Name for This. Ide autocomplete will mess this up and you will get the wrong Import. In auth case i think it's a Security concern to have the wrong I think.

[garronej]

Agreed, let's keep the <OidcSuspense /> name until we find a way to make it work with actual <Suspense />.
I just don't want pepole to think of this as something new they need to wrap their head about. It will behave just as Suspense.

[mwolf1989]

Whats about a Second required fallback like unauthed fallback? To Keep it sperated from the normal suspense?

[garronej]

It's not entirely clear.
Perhaps this would feel more natural to users.
I wouldn’t call it unauthed, but something like oidcInitializationPendingFallback (or a shorter variant). That name clarifies that this fallback isn’t rendered when the user is not authenticated, but when the system hasn’t yet determined the authentication state.

That said, I’m not sure this is the best approach, the elegance of React Suspense is precisely that it avoids every library implementing its own gating mechanism for showing a fallback.

With Suspense, you can simply write:

<Suspense fallback={<Spinner />}>
    <MySubTree />
</Suspense>

While anything required to render MySubTree is still loading, React automatically shows the spinner.

This approach prevents patterns like:

<I18nGate fallback={<Spinner />}>
    <StoreGate fallback={<Spinner />}>
        <OidcGate fallback={<Spinner />}>
            <MySubTree />
        </OidcGate>
    </StoreGate>
</I18nGate>

Suspense removes the need for every library to expose its own loading gate.
It also prevents spinner stuttering, where animations reset each time another part of the app finishes loading.

[garronej]

I've thought about it again.
Let's forget about Suspense, it's too hard of a sell compared to Clerk, where SSR “just works.”
I didn’t want to make concessions at first because, from a pedagogical standpoint, it’s very important to me to communicate that the auth state is not a variable.
A user is either logged in or not, that status never changes during the lifetime of the app instance.
To transition from logged out to logged in, the user must be redirected to the identity provider’s login page.

That’s why I originally introduced a third state, “we don’t yet know if the user is logged in”, and planned to handle it through Suspense.
But based on the feedback I received, people don’t like having to think about wrapping components in Suspense, especially not in a custom one.

So here’s the plan:
const { isUserLoggedIn } = useOidc() will now return either a boolean or undefined.
This way, things will just work.
While rendering on the server, or before OIDC initialization completes, the app will behave as if the user is logged out (undefined being falsy).
However, developers who want finer control can explicitly check for isUserLoggedIn === undefined.

This is especially useful in cases like:

Welcome to the new world of X (for guests)
Hello, John (for logged-in users)

Without this distinction, you’d briefly see Welcome… flash before being replaced by Hello, John once the client initializes, which feels glitchy.
By checking for undefined, developers can choose to render nothing (or a placeholder) until the state is resolved, avoiding any layout shift.