express-openid-connect vs oidc-provider: Client vs Server Architecture

Both express-openid-connect and oidc-provider are mature libraries for handling OpenID Connect (OIDC) in Node.js environments, but they solve fundamentally different problems. One is designed to consume authentication, while the other is designed to provide it. Understanding this distinction is critical for architecting secure systems.

🎯 Core Role: Consuming Auth vs Issuing Auth

express-openid-connect acts as a Relying Party (RP).

• It connects your app to an external Identity Provider (IdP).
• You use this when you want users to log in via Auth0, Google, or your own OIDC server.

// express-openid-connect: Configuring the client
const { auth } = require('express-openid-connect');

app.use(auth({
  auth0: {
    domain: 'your-tenant.auth0.com',
    clientId: 'your-client-id'
  },
  baseURL: 'http://localhost:3000',
  secret: 'long-secret-string'
}));

oidc-provider acts as an OpenID Provider (OP).

• It is the server that validates credentials and issues tokens.
• You use this when you are building the service that other apps log in to.

// oidc-provider: Configuring the server
const Provider = require('oidc-provider');

const provider = new Provider('http://localhost:3000', {
  findAccount: async (ctx, id) => {
    // Logic to find user in your database
    return { accountId: id };
  },
  scopes: ['openid', 'profile', 'email']
});

app.use(provider.callback);

⚙️ Configuration Complexity: Opinionated vs Flexible

express-openid-connect favors convention over configuration.

• It comes with sensible defaults for security settings like PKCE and token validation.
• Setup is fast, but you have less control over the underlying protocol flow.

// express-openid-connect: Minimal setup
app.use(auth({
  issuerBaseURL: 'https://your-idp.com',
  baseURL: 'https://your-app.com',
  clientID: 'client-id',
  secret: 'secret'
}));
// Routes are protected automatically with authRequired

oidc-provider requires explicit definition of almost every behavior.

• You must define how interactions (login screens) work.
• You must configure token lifetimes, CORS, and cookie settings manually.

// oidc-provider: Explicit interaction policy
const policy = Provider.interactionPolicy.base();
policy.add(new Provider.interactionPolicy.Prompt({
  name: 'login',
  requestable: true
}));

const provider = new Provider('http://localhost:3000', {
  interactions: { policy }
});

🔒 Protecting Routes vs Handling Requests

express-openid-connect provides middleware to guard your routes.

• You wrap specific routes to ensure a user is logged in.
• It automatically handles redirects to the IdP and back.

// express-openid-connect: Protecting a route
app.get('/dashboard', authRequired, (req, res) => {
  res.send(`Hello ${req.oidc.user.name}`);
});

app.get('/login', (req, res) => {
  res.oidc.login({ returnTo: '/dashboard' });
});

oidc-provider mounts to your app to handle incoming auth requests.

• It listens for authorization and token endpoint calls.
• You build the UI that captures the username and password.

// oidc-provider: Mounting the provider
// In your Express app
app.use('/oidc', provider.callback);

// You still need to build your own login form UI
app.get('/login', (req, res) => {
  res.send('<form>...</form>'); // Custom UI implementation
});

🍪 Session Management: Built-in vs Custom

express-openid-connect manages the user session for your app.

• It creates an encrypted cookie session after login.
• You access user data via req.oidc.user without extra code.

// express-openid-connect: Accessing session
app.get('/profile', authRequired, (req, res) => {
  // Session is automatically populated
  const user = req.oidc.user;
  res.json(user);
});

oidc-provider expects you to manage sessions for the Identity Server.

• It does not log users into your main app; it logs them into the IdP.
• You must implement findAccount and session persistence logic.

// oidc-provider: Implementing account lookup
const config = {
  findAccount: async (ctx, id, token) => {
    // You must fetch from your DB
    const user = await db.users.findById(id);
    return {
      accountId: user.id,
      claims: () => ({ sub: user.id, name: user.name })
    };
  }
};

🤝 Similarities: Shared Ground Between Client and Server

While their roles differ, both libraries share underlying standards and dependencies.

1. 🔐 Both Rely on OpenID Connect Standards

• Implement core OIDC flows (Authorization Code, Implicit, Hybrid).
• Support standard scopes like openid, profile, and email.

// Both support standard scopes
// express-openid-connect config
{ scopes: ['openid', 'profile'] }

// oidc-provider config
{ scopes: ['openid', 'profile'] }

2. 🚀 Both Run on Express/Node.js

• Designed as Express middleware or compatible modules.
• Fit into standard Node.js HTTP server architectures.

// Both integrate with Express
const express = require('express');
const app = express();

// Works with either package
app.use(express.json());

3. 🛡️ Both Prioritize Security Best Practices

• Enforce HTTPS in production modes.
• Support secure cookie flags and token encryption.

// express-openid-connect: Secure cookies
{ session: { cookie: { secure: true } } }

// oidc-provider: Secure cookies
{ cookies: { secure: true } }

4. 🔧 Both Allow Custom Claims

• You can add extra user data to tokens.
• Useful for roles, permissions, or tenant IDs.

// express-openid-connect: After login hook
{ afterCallback: (req, res, session, state) => {
    session.myCustomClaim = 'value';
}}

// oidc-provider: Extra claims
{ claims: { extra: ['myCustomClaim'] } }

5. 📦 Both Are Actively Maintained

• Regular updates for security patches.
• Strong documentation and community support.

// Both follow semantic versioning
// Check package.json for latest versions

📊 Summary: Key Similarities

🆚 Summary: Key Differences

💡 The Big Picture

express-openid-connect is like renting a secure apartment 🏢—everything is maintained for you, and you just move in. Ideal for startups, SaaS products, and teams that want to ship features without becoming security experts.

oidc-provider is like building your own house from the ground up 🏗️—you control every brick, but you are responsible for the roof not leaking. Best for enterprises with strict compliance needs, legacy user databases, or those building an identity platform as a product.

Final Thought: Do not build your own identity server unless you have to. Start with express-openid-connect and a managed provider. Only reach for oidc-provider when business requirements demand full ownership of the authentication flow.