oidc-spa v6.9.11

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.

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.
When a user clicks the "Login" button in your app, just call the login() method—it's that simple.

Why oidc-spa?

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.

Features

• 🎓 No OIDC/OAuth2 expertise required: Easy to setup and use. We're here to help on Discord!
• 🛠️ Simple setup: No need to define /login or /logout routes—token refreshing is automatic, it just works.
• ✨ React integration: Expose a framework agnostic API (oidc-spa) but also a React adapter oidc-spa/react.
• 🔥 No limitation- For example, everything you could do with keycloak-js, you can do with oidc-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 localStorage or sessionStorage.
• 🖥️ Optional backend utilities: Provides tools for token validation in JavaScript backends (Node.js, Deno, Web Workers).
• 🔗 Multi-instance support: Run multiple oidc-spa instances—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-spa works around it automatically with no special measures needed on your side.

Comparison with Existing Libraries

oidc-client-ts

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

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.

keycloak-js

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.

NextAuth.js

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-mpa library for Multi Page Applications that would aim at supporting Next.js projects.

🚀 Quick start

Head over to the documentation website 📘!

Sponsors

Project backers, we trust and recommend their services.

Showcases

This library powers the authentication of the following platforms:

Onyxia

• Source code
• Public instance

The French Interministerial Base of Free Software

• Source code
• Deployment of the website