passport-openidconnect

passport-openidconnect is a Passport.js strategy that implements the OpenID Connect Basic Client Profile, letting a Node.js application authenticate users against any standards-compliant OpenID Provider (OP) — Okta, Auth0, Google, or a self-hosted provider — without hand-rolling the authorization-code exchange and ID-token validation logic.

The strategy handles the full redirect flow: sending the authorization request, exchanging the returned code for tokens via the oauth package, and validating the ID token’s issuer, audience, expiration, and nonce claims per the OpenID Connect Basic Client Profile spec before invoking the application’s verify callback. That callback’s signature is inspected by argument count (arity) at runtime, so an app can opt into receiving the raw ID token, access token, refresh token, and OAuth2 params, or just a normalized profile, without any configuration flag.

What You Get

• A drop-in Passport Strategy class configured with an issuer, authorization/token endpoints, and client credentials
• Automatic ID token validation (issuer, audience, expiration, nonce, authorized-party) per the OpenID Connect Basic Client Profile
• A pluggable state store (session-based by default) that protects the authorization request against CSRF and replay
• Normalized profile and context objects parsed from ID token claims, plus optional UserInfo endpoint fetching
• Arity-based verify callback dispatch, so apps can request as much or as little token/profile detail as they need

Common Use Cases

• Adding “Sign in with <OIDC provider>” to an Express app already using Passport for other strategies
• Integrating with Auth0, Okta, or another hosted identity provider that exposes standard OIDC endpoints
• Building a relying party against an in-house or self-hosted OpenID Provider for SSO
• Federated login where a database maps OP issuer + subject pairs to local user accounts

Under The Hood

Architecture The module is a single Passport Strategy constructor (lib/strategy.js) implementing the authenticate(req, options) contract, delegating to focused collaborator modules: lib/profile.js (claims to normalized profile), lib/context.js (claims to auth context), lib/utils.js (URL reconstruction, object merge, ID generation), lib/state/session.js (pluggable CSRF state store), and lib/errors/* (typed OAuth/OIDC error classes). Data flows linearly — incoming request, state store verification, OAuth2 code exchange via the oauth package, ID token claim validation, profile/context parsing, optional UserInfo fetch, then arity-dispatched verify callback and success/fail/error — with the bulk of that logic concentrated in one long authenticate function whose nested callbacks are the main point that would need care if token validation or profile merging changed.

Tech Stack Dependencies are minimal: the community oauth package (0.10.x) drives the authorization-code exchange, and passport-strategy (1.x) supplies the base class contract. Dev dependencies — mocha 2.x, chai 2.x with chai-passport-strategy, sinon, proxyquire, and jws — support a BDD-style test suite for Passport strategies. There is no build step, bundler, or TypeScript; it’s plain CommonJS targeting node >= 0.6.0, and .travis.yml still tests against Node 0.6 through 5 plus early io.js releases, reflecting the module’s 2013 origin and long API stability rather than active modernization.

Code Quality The test suite is unusually extensive for a package this size — five spec files totaling roughly 4,200 lines, with strategy.test.js and verify.test.js alone covering redirect paths and every verify-callback arity (3 through 10 arguments, with and without passReqToCallback) plus error branches, run through chai-passport-strategy’s DSL with sinon fake timers for determinism. Error handling is explicit via dedicated AuthorizationError, TokenError, and InternalOAuthError constructors mapped to RFC 6749 status codes rather than passing raw errors through. There is no TypeScript, no modern linter config beyond a bare .jshintrc, and no active CI beyond a legacy Travis config that hasn’t been updated for current Node versions.

API Design The defining design choice is arity-based verify-callback dispatch: authenticate inspects the app-supplied verify function’s declared argument count and calls it with anywhere from a bare profile up to the raw ID token, access token, refresh token, and OAuth2 params, letting integrators opt into more detail without any options flag — a pattern consistent with the author’s other Passport strategies, though the contract lives in function-signature length rather than named options, which a newcomer has to discover by reading the source. Getting started needs only five required options and two routes, and the README carries one fully worked example plus links to two external example apps — adequate, not extensive, documentation for a conservative, faithful implementation of the OpenID Connect Basic Client Profile rather than a novel one.