Implementing OpenID Connect Authentication in JavaScript Applications
These libraries handle OpenID Connect (OIDC) flows but serve different architectural roles. oidc-client-ts, oidc-client, openid-client, and react-oidc-context are client libraries used to authenticate users against an identity provider. oidc-provider is a server library used to build your own identity provider. Choosing the wrong one can lead to security vulnerabilities or broken authentication flows.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
OpenID Connect Libraries: Client, Server, and Framework Roles
Choosing the right OpenID Connect (OIDC) library depends on where your code runs and what role it plays. Some libraries help your app log in users (Client), while others help your app act as the login server itself (Provider). Mixing these up leads to security risks or broken builds. Let's look at how each package fits into your architecture.
🏗️ Core Role: Client vs. Server
The most important split is between libraries that log users in (Clients) and libraries that create the login system (Providers).
oidc-client-ts, oidc-client, openid-client, and react-oidc-context are all Clients.
They help your application talk to an identity server (like Auth0, Azure AD, or Google).
oidc-provider is a Server.
It helps you build your own identity server. You do not use this to log into another service.
// oidc-provider: Setting up your own Identity Server
import Provider from 'oidc-provider';
const provider = new Provider('http://localhost:3000', { /* config */ });
app.use(provider.callback);
// oidc-client-ts: Connecting to an existing Identity Server
import { UserManager } from 'oidc-client-ts';
const userManager = new UserManager({ authority: 'https://accounts.google.com', /* ... */ });
// openid-client: Connecting from a Node.js backend
import { custom } from 'openid-client';
const client = await custom({ /* ... */ });
// react-oidc-context: Connecting from React
import { AuthProvider } from 'react-oidc-context';
<AuthProvider {...config}>/* app */</AuthProvider>
// oidc-client: Legacy Client (Deprecated)
import { UserManager } from 'oidc-client';
const userManager = new UserManager({ /* ... */ });
🖥️ Runtime Environment: Browser vs. Node.js
Security rules change based on where your code runs. Browsers cannot keep secrets safely, but Node.js servers can.
oidc-client-ts and oidc-client are built for Browsers.
They use PKCE (Proof Key for Code Exchange) to secure the login flow without a client secret. They store tokens in browser storage.
// oidc-client-ts: Browser-safe PKCE flow
await userManager.signinRedirect();
// Handles redirect and token exchange securely in the browser
openid-client is built for Node.js.
It supports confidential clients that can store a client secret safely on the server. It is ideal for Backend-for-Frontend (BFF) patterns.
// openid-client: Server-side token exchange with secret
const params = client.callbackParams(ctx.req);
const tokenSet = await client.callback(redirectUri, params, { code_verifier });
react-oidc-context runs in the Browser (inside React).
It wraps oidc-client-ts to manage state within React components.
// react-oidc-context: React hook usage
const { isAuthenticated, signinRedirect } = useAuth();
oidc-provider runs on Node.js.
It listens for incoming login requests from other clients.
// oidc-provider: Listening for auth requests
provider.listen(3000);
⚛️ Framework Integration: React vs. Vanilla
If you use React, wrapping the auth logic saves time. If you use vanilla JS or another framework, you need the core library.
react-oidc-context provides hooks and context.
It handles loading states and user data automatically within the React tree.
// react-oidc-context: Accessing user data
const { user } = useAuth();
return <div>Hello {user?.profile.name}</div>;
oidc-client-ts is framework independent.
You must manually manage user state and subscription events.
// oidc-client-ts: Manual event subscription
userManager.events.addUserLoaded((user) => {
console.log('User loaded', user);
});
oidc-client is also framework independent (Legacy).
It works similarly to oidc-client-ts but lacks TypeScript support.
// oidc-client: Manual event subscription (Legacy)
userManager.events.addUserLoaded((user) => {
console.log('User loaded', user);
});
openid-client is for backend frameworks (Express, Next.js API).
You integrate it into your server routes.
// openid-client: Express route example
app.get('/callback', async (req, res) => {
// handle callback
});
oidc-provider is for backend servers.
It mounts directly to an HTTP server instance.
// oidc-provider: Mounting to HTTP server
provider.listen(3000);
⚠️ Maintenance Status: Legacy vs. Active
One of these packages is no longer recommended for new work.
oidc-client is Deprecated.
The maintainers have stopped updates in favor of the TypeScript rewrite. Do not use this for new projects.
// oidc-client: DO NOT USE IN NEW PROJECTS
import { UserManager } from 'oidc-client'; // Deprecated package
oidc-client-ts is Active.
This is the modern standard for browser-based SPAs.
// oidc-client-ts: Recommended for SPAs
import { UserManager } from 'oidc-client-ts';
react-oidc-context is Active.
It is the recommended way to use OIDC in React apps today.
// react-oidc-context: Recommended for React
import { AuthProvider } from 'react-oidc-context';
openid-client is Active.
It is the standard for Node.js OIDC clients.
// openid-client: Recommended for Node.js
import { Issuer } from 'openid-client';
oidc-provider is Active.
It is the standard for building custom Identity Providers in Node.js.
// oidc-provider: Recommended for Custom IdP
import Provider from 'oidc-provider';
📊 Summary Table
| Package | Role | Environment | Status | Best For |
|---|---|---|---|---|
oidc-client-ts | Client | Browser | ✅ Active | Vanilla JS/TS SPAs |
react-oidc-context | Client | Browser (React) | ✅ Active | React SPAs |
openid-client | Client | Node.js | ✅ Active | Backend/BFF Auth |
oidc-provider | Server | Node.js | ✅ Active | Building Identity Servers |
oidc-client | Client | Browser | ❌ Deprecated | Legacy Maintenance Only |
💡 Final Recommendation
For most frontend teams building a Single Page Application:
- Use
react-oidc-contextif you are using React. - Use
oidc-client-tsif you are using Vue, Angular, or vanilla JavaScript. - Avoid
oidc-clientcompletely for new work.
For backend teams:
- Use
openid-clientto log your server into another service. - Use
oidc-provideronly if you need to build your own login server from scratch.
Choosing the right tool ensures your tokens stay safe and your code remains maintainable.
How to Choose: oidc-client vs oidc-client-ts vs oidc-provider vs openid-client vs react-oidc-context
- oidc-client:
Avoid this package for new projects as it is officially deprecated. Only choose this if you are maintaining a legacy application that cannot be migrated yet. For any new work, switch to
oidc-client-tswhich offers the same features with TypeScript support and active maintenance. - oidc-client-ts:
Choose
oidc-client-tsif you are building a Single Page Application (SPA) in vanilla JavaScript or TypeScript without a specific framework wrapper. It is the modern standard for browser-based authentication using PKCE. It gives you full control over the user manager and event handling. - oidc-provider:
Choose
oidc-provideronly if you need to build your own Identity Server from scratch. This is not for logging into Google or Auth0 — it is for making your Node.js server act like Google or Auth0. It is complex and should only be used when third-party identity services do not meet your needs. - openid-client:
Choose
openid-clientif you are implementing authentication on a Node.js backend. It is designed for server-side environments where you can safely store client secrets. It is ideal for Backend-for-Frontend (BFF) patterns or server-side rendered applications. - react-oidc-context:
Choose
react-oidc-contextif you are building a React application. It wrapsoidc-client-tsto provide hooks and context providers that simplify state management. This saves you from writing boilerplate code to handle user sessions and loading states within React components.
Popular Comparisons
README for oidc-client
oidc-client
Library to provide OpenID Connect (OIDC) and OAuth2 protocol support for client-side, browser-based JavaScript client applications. Also included is support for user session and access token management.
Install
Node.js
Node.js v4.4 or later required.
NPM
npm install oidc-client --save
NOTE: if you're not already using babel-polyfill make sure you run
npm install --save babel-polyfill as well. Then include it in your build.
CommonJS
If you don't use a package manager or a module loader, then you can get the library from the dist folder on github here.
Including in the browser
If you intend to use this library directly in a browser and are not using UMD/AMD then there is a compiled version in the ~/dist folder. It is already bundled/minified and contains the necessary dependencies and polyfills (mainly for ES6 features such as Promises).
If you are using UMD/AMD and/or you already have included an ES6 polyfill (such as babel-polyfill.js) then you can include the UMD packaged version of the file from the ~/lib folder.
Building the Source
git clone https://github.com/IdentityModel/oidc-client-js.git
cd oidc-client-js
npm install
npm run build
Running the Sample
npm start
and then browse to http://localhost:15000.
Running the Tests
npm test
Docs
Some initial docs are here.
Feedback, Feature requests, and Bugs
All are welcome on the issue tracker.