We're here to help!
A full-featured OpenID Connect / OAuth2 client for single-page applications (SPAs).
With oidc-spa, you can seamlessly integrate authentication providers like Keycloak, Auth0, or Microsoft Entra ID into your application, purely on the client side—
without involving your backend in the token exchange.
In simple terms, oidc-spa is a library that makes it easy to add authentication to your Vite or Create-React-App project.
There are many authentication and user management platforms out there: Okta, Auth0, Entra ID...
There are also plenty of self-hosted options like Keycloak, Ory Hydra, and Dex.
What all of these have in common is that they implement the OpenID Connect/OAuth2 standard.
This library provides a unified way to connect with these different providers instead of having to use their specific SDKs.
oidc-spa implement the Authorization Code Flow with PKCE, this means that you do not need a backend and a database to handle the authentication process.
The authentication process is handled entirely in the browser. And no need for /login or /logout routes.
Most OIDC providers push their own client libraries:
- Auth0 →
auth0-spa-js - Microsoft Entra ID →
MSAL.js - Keycloak →
keycloak-js(no longer actively promoted, planned for deprecation) - ... and so on.
These libraries are tied to a specific provider. But what if you need to:
✅ Switch OIDC providers without modifying your authentication logic?
✅ Build a self-hostable solution that works with any provider (e.g., you're developing a dashboard app that you sell to enterprises and need to integrate with their existing IAM system)?
✅ Stop re-learning authentication implementation every time you change providers?
And besides, not all SDKs are equal in terms of setup simplicity, performance, and API quality.
We wanted a universal solution—one that is as good or better than all existing SDKs in every aspect.
- 🎓 No OIDC/OAuth2 expertise required: Easy to setup and use. We're here to help on Discord!
- 🛠️ Simple setup: No need to define
/loginor/logoutroutes—token refreshing is automatic, it just works. - ✨ React integration: Expose a framework agnostic API but also a React adapter
oidc-spa/react. - 🔥 No limitation- For example, everything you could do with
keycloak-js, you can do withoidc-spa. - 💬 Detailed debug messages: If your OIDC server is not properly configured, it tells you precisely what’s wrong and what you need to do to fix it.
- 🕣 Auto logout with countdown: "You will be logged out in 10... 9... 8...", users see exactly when their session expires.
- 🚪 Logout propagation: Logging out in one tab logs out all others.
- 📖 Comprehensive documentation: Guides and examples for common scenarios.
- ✅ Type safety: Strong TypeScript support with optional Zod integration validating the expected shape of the ID token.
- 🔒 Security-first: Uses Authorization Code Flow + PKCE—No token persistence in
localStorageorsessionStorage. - 🖥️ Optional backend utilities: Provides tools for token validation in JavaScript backends (Node.js, Deno, Web Workers).
- 🔗 Multi-instance support: Run multiple
oidc-spainstances—for example, to offer Login with Google OR Microsoft in the same app. - 🍪 No third-party cookie issues: Third-party cookies blocked? No problem—
oidc-spaworks around it automatically with no special measures needed on your side.
While oidc-client-ts is a comprehensive toolkit designed for various applications, oidc-spa is specifically built for SPAs with an easy-to-set-up API.
But ease of use isn't the only difference—oidc-spa also provides out-of-the-box solutions for features that oidc-client-ts leaves up to you to implement, such as:
- Login/logout propagation across tabs
- Graceful fallback when third-party cookies are blocked
- Seamless browser back/forward cache (bfcache) management
- Auto logout countdown so users can be automatically logged out after a set period of inactivity.
- Ensuring you never get an expired access token error—even after the computer wakes up from sleep.
- Gracefully handles scenarios where the provider does not issue a refresh token or lacks a logout endpoint (e.g., Google OAuth)
react-oidc-context is a React wrapper around oidc-client-ts.
oidc-spa also feature a carefully crafted React API that comes with working examples that you can test locally.
The official OIDC Client for Keycloak. It only works with Keycloak and will eventually be deprecated.
Beyond that, achieving the same seamless user experience as oidc-spa with keycloak-js requires writing a lot of custom code—code that really shouldn’t be handled at the application level.
Since oidc-spa is built for true SPAs, Next.js applications should use NextAuth.js instead.
NOTE: We might create in the future a
oidc-mpalibrary for Multi Page Applications that would aim at supporting Next.js 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.
This library powers the authentication of the following platforms:
