oidc-spa

We're here to help!

oidc-spa is an OpenID Connect client built for browser-first apps.
It wraps the full Authorization Code + PKCE flow in a high-level API so you can ship secure app auth without stitching together multiple SDKs and ad-hoc glue.

- 🔒 Security-first defaults: in-memory tokens, strict redirect handling, and opt-in defenses like DPoP
and token substitution to reduce token exposure risk.
- 🧭 Battle-tested auth UX: token renewal, idle timeout, auto login/logout, multi-tab session sync, and reliable session restore on reload.
- 🧩 Full-stack ready: backend token validation utilities and first-class TanStack Start integration in the same library.
- 🧰 Provider-aware: handles real-world quirks across Keycloak, Entra ID, Auth0, Google, and more.
- ✨ Developer experience: types flow from config into the API, minimal knobs, and easy-to-mock auth for tests.

Get Started

At a glance

The Framework-Agnostic Adapter:

``ts import { createOidc, oidcEarlyInit } from "oidc-spa/core"; // ~33 KB min+gzip (See: https://docs.oidc-spa.dev/resources/bundle-size) import { z } from "zod"; // 59 KB min+gzip, but it's optional.

// Call this only if you don't use oidc-spa's Vite plugin. oidcEarlyInit({ BASE_URL: "/" });

// In oidc-spa the user is either logged in or they aren't. // The state will never mutate without a full app reload. // This makes reasoning about auth much, much easier. if (!oidc.isUserLoggedIn) { await oidc.login(); // Never here return; }

const { name, realm_access } = oidc.getDecodedIdToken();

console.log(Hello ${name});

const { accessToken } = await oidc.getTokens();

await fetch("https://my-domain.net/api/todos", { headers: { Authorization:Bearer ${accessToken}} });

if (realm_access.roles.includes("realm-admin")) { // User is an admin }`

Higher-level adapters, example with React but we also feature a similar Angular adapter:

Full-stack auth solution with TanStack Start:

`tsx import { createServerFn } from "@tanstack/react-start"; import { enforceLogin, oidcFnMiddleware } from "@/oidc"; import fs from "node:fs/promises";

const getTodos = createServerFn({ method: "GET" }) .middleware([oidcFnMiddleware({ assert: "user logged in" })]) .handler(async ({ context: { oidc } }) => { const userId = oidc.accessTokenClaims.sub;

const json = await fs.readFile(todos_${userId}.json, "utf8");

return JSON.parse(json); });

export const Route = createFileRoute("/todos")({ beforeLoad: enforceLogin, loader: () => getTodos(), component: RouteComponent });

function RouteComponent() { const todos = Route.useLoaderData();

return (


            {todos.map(todo => (
                
                    {todo.isDone && "✅"} {todo.text}
                

            ))}


    );
}

At a glance

The Framework-Agnostic Adapter:

// Call this only if you don't use oidc-spa's Vite plugin. oidcEarlyInit({ BASE_URL: "/" });

const { name, realm_access } = oidc.getDecodedIdToken();

console.log(Hello ${name});

const { accessToken } = await oidc.getTokens();

await fetch("https://my-domain.net/api/todos", { headers: { Authorization:Bearer ${accessToken}} });

if (realm_access.roles.includes("realm-admin")) { // User is an admin }`

Higher-level adapters, example with React but we also feature a similar Angular adapter:

Full-stack auth solution with TanStack Start:

`tsx import { createServerFn } from "@tanstack/react-start"; import { enforceLogin, oidcFnMiddleware } from "@/oidc"; import fs from "node:fs/promises";

const json = await fs.readFile(todos_${userId}.json, "utf8");

return JSON.parse(json); });

export const Route = createFileRoute("/todos")({ beforeLoad: enforceLogin, loader: () => getTodos(), component: RouteComponent });

function RouteComponent() { const todos = Route.useLoaderData();

return (


            {todos.map(todo => (
                
                    {todo.isDone && "✅"} {todo.text}
                

            ))}


    );
}

At a glance

Sponsors

oidc-spa

At a glance

Sponsors

Dist Tags