OpenID Connect Libraries: Architecture, Security, and Framework Integration

Implementing authentication in modern web applications requires careful selection of tools that match your runtime environment and framework. The oidc-client ecosystem has evolved significantly, shifting from legacy JavaScript to modern TypeScript, while distinct libraries serve backend versus frontend needs. Let's compare how these four packages handle authentication flows, environment constraints, and framework integration.

🏗️ Core Architecture and Runtime Environment

oidc-client was the original standard for browser-based OIDC.

• Written in vanilla JavaScript.
• Runs exclusively in the browser (SPA).
• Status: Deprecated and archived.

// oidc-client: Legacy setup (Do Not Use)
const userManager = new Oidc.UserManager({
  authority: "https://accounts.google.com",
  client_id: "your-client-id",
  redirect_uri: "http://localhost:3000/callback"
});

oidc-client-ts is the direct successor and rewrite.

• Written in TypeScript for type safety.
• Runs exclusively in the browser (SPA).
• Status: Active maintenance and recommended standard.

// oidc-client-ts: Modern setup
import { UserManager } from "oidc-client-ts";

const userManager = new UserManager({
  authority: "https://accounts.google.com",
  client_id: "your-client-id",
  redirect_uri: "http://localhost:3000/callback"
});

openid-client targets server-side environments.

• Designed for Node.js backends.
• Supports confidential clients (client secrets).
• Status: Active maintenance for backend use.

// openid-client: Backend setup
import { customFetch, Issuer } from "openid-client";

const issuer = await Issuer.discover("https://accounts.google.com");
const client = new issuer.Client({
  client_id: "your-client-id",
  client_secret: "your-client-secret" // Secure on server
});

react-oidc-context wraps the browser client for React.

• Built on top of oidc-client-ts.
• Provides React hooks and Context API.
• Status: Active maintenance for React projects.

// react-oidc-context: React setup
import { AuthProvider } from "react-oidc-context";

const config = {
  authority: "https://accounts.google.com",
  client_id: "your-client-id",
  redirect_uri: "http://localhost:3000/callback"
};

// Wrap your app
<AuthProvider {...config}>...</AuthProvider>

🔐 Security Model: Public vs Confidential Clients

Security boundaries define which library you can safely use. Browser-based apps are "public clients" and cannot store secrets. Server apps are "confidential clients" and should.

oidc-client-ts enforces public client security.

• Uses PKCE (Proof Key for Code Exchange) by default.
• No client secret is passed in the code.
• Tokens stored in browser memory or storage.

// oidc-client-ts: PKCE handled automatically
await userManager.signinRedirect();
// No client_secret in config

openid-client supports confidential client flows.

• Allows client_secret_basic or client_secret_post.
• Suitable for backend-for-frontend (BFF) patterns.
• Keeps tokens on the server, away from the browser.

// openid-client: Using client secret
const tokenSet = await client.callback(redirectUri, params, {
  code_verifier: "verifier",
  state: "state"
});
// Secret used internally during token exchange

react-oidc-context inherits oidc-client-ts security.

• Same PKCE requirements.
• Adds React-specific security like automatic session monitoring.
• Keeps implementation consistent with the underlying library.

// react-oidc-context: Secure hook usage
const { isAuthenticated, signoutRedirect } = useAuth();
// PKCE and token handling abstracted away

oidc-client had legacy security models.

• Lacked modern TypeScript safety checks.
• No longer updated for new security threats.
• Risk of vulnerabilities in token handling.

// oidc-client: Legacy security (Risky)
// No type safety to prevent misconfiguration
userManager.signinRedirect(); 

🔄 Handling Authentication State and Tokens

Managing the user session lifecycle is a core task. Each library exposes this differently.

oidc-client-ts gives manual control over the user manager.

• You explicitly call methods to get the user.
• You must wire up event listeners for token expiration.
• Best for non-framework or custom framework setups.

// oidc-client-ts: Manual user retrieval
const user = await userManager.getUser();
if (user?.access_token) {
  // Attach token to API calls
}

react-oidc-context automates state via hooks.

• useAuth hook provides reactive user state.
• Automatically triggers re-renders on login/logout.
• Reduces boilerplate for React components.

// react-oidc-context: Reactive state
const { user, isLoading } = useAuth();

if (isLoading) return <div>Loading...</div>;
return <div>Hello {user?.profile.name}</div>;

openid-client manages sessions on the server.

• You handle sessions via cookies or server memory.
• No browser-based user object to manage directly.
• Focuses on validating tokens received from the frontend.

// openid-client: Token validation
const claims = await client.userinfo(tokenSet.access_token);
// Validate claims on server side

oidc-client used older event patterns.

• Relied on global callbacks.
• Harder to integrate with modern component lifecycles.
• Deprecated event handling mechanisms.

// oidc-client: Legacy events
userManager.events.addUserLoaded((user) => {
  console.log("User loaded", user);
});

🧩 Framework Integration and Boilerplate

The amount of code you write depends on how much the library abstracts for your specific framework.

react-oidc-context is purpose-built for React.

• Minimal setup code for standard flows.
• Integrated loading and error states.
• Ideal for teams wanting speed in React ecosystems.

// react-oidc-context: Protected Route
function ProtectedRoute() {
  const { isAuthenticated } = useAuth();
  return isAuthenticated ? <Dashboard /> : <Login />;
}

oidc-client-ts requires manual React integration.

• You must create your own Context or Hooks.
• More flexible for Vue, Angular, or Svelte.
• Better if you need full control over the lifecycle.

// oidc-client-ts: Custom React Hook
function useUserManager() {
  const [user, setUser] = useState(null);
  // Manual wiring of userManager events required
  return user;
}

openid-client integrates with Express or NestJS.

• Used in route handlers or middleware.
• No frontend component integration.
• Essential for BFF (Backend for Frontend) architectures.

// openid-client: Express Middleware
app.get("/profile", async (req, res) => {
  const tokens = req.session.tokens;
  const userinfo = await client.userinfo(tokens.access_token);
  res.json(userinfo);
});

oidc-client requires legacy integration patterns.

• Callback-based patterns instead of Promises.
• More verbose error handling.
• Not compatible with modern TypeScript projects.

// oidc-client: Callback pattern
userManager.signinRedirectCallback().then(function (user) {
  // Handle success
}).catch(function (err) {
  // Handle error
});

📊 Summary: Key Differences

💡 The Big Picture

oidc-client-ts is the foundation 🏗️ for any browser-based authentication. Use it directly if you are not using React or need maximum control over the authentication lifecycle.

react-oidc-context is the accelerator 🚀 for React teams. It removes the boilerplate of wiring up oidc-client-ts manually, letting you focus on building UI components rather than auth logic.

openid-client is the secure vault 🔒 for your backend. Use it when you need to keep tokens off the client entirely (BFF pattern) or when your backend needs to call other APIs on behalf of the user.

oidc-client is the legacy system 🕸️. Do not start new projects with it. If you are still using it, treat migration to oidc-client-ts as a security priority.

Final Thought: Security and environment are your primary decision factors. If you are in the browser, use oidc-client-ts (or its React wrapper). If you are on the server, use openid-client. Never mix confidential client secrets into browser-based libraries.