We're here to help!
oidc-spa is a framework-agnostic OpenID Connect client for browser-centric web applications implementing the Authorization Code Flow with PKCE.
It work with any spec compliant OIDC provider like Keycloak, Auth0 or Microsoft EntraID and replace provider-specific SDKs like keycloak-js, auth0-spa-js, or @azure/msal-browser with one unified API, freeing your app from vendor lock-in and making it deployable in any IT system.
Concretely this mean that it let you build an app and sell it to different companies ensuring they will be able to deploy it in their environment regardless of what auth platform they use internally.
oidc-spa provides strong guarantees regarding the protection of your tokens even in case of successful XSS or supply chain attacks. No other implementation can currently claim that.
It is uncompromising in terms of performance, security, DX, and UX. You get a state-of-the-art authentication and authorization system out of the box with zero glue code to write and no knobs to adjust.
Unlike server-centric solutions such as Auth.js, oidc-spa makes the frontend the OIDC client in your IdP model's representation.
Your backend becomes a simple OAuth2 resource server that you frontend query with the access token attached as Authorization header. oidc-spa also provides the tools for token validation on the server side:
- As an unified solution for TanStack Start
- Or, as a separate adapter for creating authed APIs with tRCP, Express, Hono, Nest.js, ect.
That means no database, no session store, and enterprise-grade UX out of the box, while scaling naturally to edge runtimes.
oidc-spa exposes real OIDC primitives, decoded ID tokens, access tokens, and claims, instead of hiding them behind a “user” object, helping you understand and control your security posture.
It’s infra-light, open-standard, transparent, and ready to work in minutes.
But in details? I want to understand the tradeoffs.
In the modern tech ecosystem, no one “rolls their own auth” anymore, not even OpenAI or Vercel.
Authentication has become a platform concern. Whether you host your own identity provider like Keycloak, or use a service such as Auth0 or Microsoft Entra ID, authentication today means redirecting users to your auth provider.
Why not BetterAuth or Auth.js
These are great for what they are, but they’re “roll your own auth” solutions.
With oidc-spa, you delegate authentication to a specialized identity provider such as Keycloak, Auth0, Okta, or Clerk.
With BetterAuth, your backend is the authorization server, even if you can integrate third party identity providers id doesn't change that fact.
That’s very battery-included, but also far heavier infrastructure-wise.
Today, very few companies still roll their own auth, not even OpenAI or Vercel.
Another big difference: oidc-spa is browser-centric. The token exchange happens on the client,
and the backend server is merely an OAuth2 resource server in the OIDC model.
If you use BetterAuth to provide login via Keycloak, your backend becomes the OIDC client application,
which has some security benefits over browser token exchange, but at the cost of centralization and requiring backend infrastructure.
One clear advantage BetterAuth has over oidc-spa is more natural SSR support. In the oidc-spa model, the server doesn’t know the authentication state of the user at all time, which makes it difficult to integrate with traditional full-stack frameworks that rely on server-side rendering.
Server Side Rendering
The only SSR-capable framework we currently support is TanStack Start, because it provides the low-level primitives needed to render as much as possible on the server while deferring rendering of auth aware components to the client.
This approach achieves a similar UX and performance to server-centric frameworks, but it’s inherently less transparent than streaming fully authenticated components to the client.
Try the TansStack Start example deployment with JavaScript disabled to get a feel of what can and can't be SSR'd: https://example-tanstack-start.oidc-spa.dev/
Security and XSS resilience
Yes; client-side authentication raises valid security concerns.
But this isn’t a fatal flaw; it’s an engineering challenge, and oidc-spa addresses it head-on.
It treats the browser as a hostile environment, going to great lengths to protect tokens even under XSS or supply-chain attacks.
These mitigations are documented here.
Limitations regarding backend delegation
The main limitation is with long-running background operations.
If your backend must call third-party APIs on behalf of the user while they’re offline, you’ll need service accounts for those APIs or take charge of rotating tokens yourself which can be tricky.
Beyond that, everything else scalability, DX, performance, works in your favor.
If that all sounds good to you…
Let’s get started.
- Full Stack - all in one auth solution:
- Single Page Apps (SPAs):
- Framework Agnostic
- React Router
- Tanstack Router
- Angular
- ...More to come...
- Backend: Express, Hono, tRPC, Nest.js ...
It is a great low-level implementation of the OIDC primitives.
But it is only that, a low-level implementation. If you want to use it in your application,
you’ll have to write a ton of glue code to achieve a state-of-the-art UX,
code that has no business living in application-level logic.
Example of what you get out of the box with oidc-spa:
- Login/logout propagation across tabs
- Automatic silent sign-in when possible, with full-page redirect fallback
- Seamless browser back/forward cache (bfcache) management
- Auto logout countdown so users are warned before inactivity logout
- Never getting an expired access token error, even after waking from sleep
- Graceful handling when the provider lacks refresh tokens or a logout endpoint (e.g. Google OAuth)
- Mock support, run with a mock identity without contacting a server
oidc-spa just works. You provide the few parameters required to talk to your IdP, and that’s it.
On top of that, oidc-spa provides much stronger security guarantees than oidc-client-ts does out of the box,
and yields a level of performance that isn’t realistically achievable with the tools oidc-client-ts alone provides.
react-oidc-context is a thin React wrapper around oidc-client-ts.
oidc-client-ts compares to oidc-spa/core,
and react-oidc-context compares to oidc-spa/react-spa.
oidc-spa provides much better security, DX, and UX out of the box.
NOTE: You can use
oidc-spa/keycloak-jsas a literal drop-in replacement forkeycloak-js
your app will instantly perform better, be much more secure, and implement session expiration correctly.
The official OIDC client for Keycloak has several issues:
- Does not respect the OIDC spec, hence only works with Keycloak, requiring a wildcard in valid redirect URIs, which is problematic.
- Its API encourages incorrect usage, e.g., by directly exposing the access token via a synchronous API..
- Does not expose high-level adapters for React or Angular, requiring you to write your own wrappers.
- Does not handle redirects correctly: once on the login page, you can’t go back.
- Makes no attempt to protect tokens against XSS attacks.
- You can't talk to more than one resource server.
- Does not handle session expiration; users aren’t automatically logged out or warned before expiration.
- Lacks mock implementations for testing against mock identities.
oidc-spa exports oidc-spa/keycloak providing all the keycloak specific feature that keycloak-js offers.
oidc-spa even comes with a polyfill implementation of the keycloak-js API.
It’s an Angular wrapper for keycloak-js, with the same limitations as above.
oidc-spa exposes an Angular adapter: oidc-spa/angular.
This is a solid generic OIDC adapter.
However, oidc-spa/angular still has several advantages:
- Better security guarantees (angular-oauth2-oidc does not protect tokens from XSS or supply-chain attacks)
- Better performance due to early initialization
- Auto logout overlay (“Are you still there?” countdown)
- Stronger type safety with propagated user profile types
- Ability to start rendering before session restoration settles
- Support for multiple resource servers
- Clearer and more actionable error messages for misconfiguration
These are great for what they are, but they’re “roll your own auth” solutions.
With oidc-spa, you delegate authentication to a specialized identity provider such as Keycloak, Auth0, Okta, or Clerk.
With BetterAuth, your backend is the authorization server. (even if you can integrate third party provider).
That’s very battery-included, but also far heavier infrastructure-wise.
Today, very few companies still roll their own auth—including OpenAI and Vercel.
Another big difference: oidc-spa is browser-centric. The token exchange happens on the client,
and the backend server is merely an OAuth2 resource server in the OIDC model.
If you use BetterAuth to provide login via Keycloak, your backend becomes the OIDC client application,
which has some security benefits over browser token exchange, but at the cost of centralization and requiring backend infrastructure.
One clear advantage BetterAuth has over oidc-spa is SSR support. In the oidc-spa model, the server doesn’t handle authentication directly, which makes it difficult to integrate with traditional full-stack frameworks that rely on server-side rendering.
The only SSR-capable framework we currently support is TanStack Start, because it provides the low-level primitives needed to render as much as possible on the server while deferring authentication logic to the client.
This approach achieves a similar UX and performance to server-centric frameworks, but it’s inherently less flexible than streaming fully authenticated server components to the client.
oidc-spa is extremely lightweight, it’s just a library, with no infrastructure or backend requirements. It scales beautifully, delivers great performance at the edge, and keeps your deployment simple. The tradeoff is that SSR becomes harder, though not impossible, as demonstrated with TanStack Start.
oidc-spa vendors oidc-client-ts for its frontend logic and jose for token validation on the backend.
The idea was to build on top of battle-tested primitives.
We appreciate what we owe to those projects.
Head over to the documentation website 📘!
Project backers — we trust and recommend their services.
Keycloak as a Service — Keycloak community contributors of popular extensions providing free and dedicated Keycloak hosting and enterprise Keycloak support to businesses of all sizes.