Registry / security / passport-client-cert

passport-client-cert

library2.1.0jsnpmunverified

Passport.js strategy for TLS client certificate authentication. Version 2.1.0 is the latest stable release (as of 2023). The package enables mutual TLS authentication directly in Node.js applications without requiring a reverse proxy. It provides a verify callback that receives the parsed client certificate object from Node's TLS socket. Key differentiators: first-class support for the standard Passport.js pattern (serialization/deserialization, req.logIn, etc.), ability to pass request object to verify callback, and TypeScript type definitions shipped. Alternative to handling client certificates manually via tls.getPeerCertificate. Release cadence is low; updates are infrequent. Works only with Node.js HTTP/HTTPS servers (not Express middleware alone). Requires a TLS-enabled server with requestCert and rejectUnauthorized options set.

security

npm install passport-client-cert

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PASSPORT-CLIENT-CE

passport-client-cert

securityjavascriptv2.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Strategy

✓ import { Strategy } from 'passport-client-cert'

✗ const Strategy = require('passport-client-cert')

ESM import available; named export 'Strategy' is the recommended approach.

default

✓ import ClientCertStrategy from 'passport-client-cert'

✗ const ClientCertStrategy = require('passport-client-cert').default || require('passport-client-cert')

Default export is Strategy; mixing CommonJS with ESM requires careful destructuring.

Strategy as ClientCertStrategy

✓ import { Strategy as ClientCertStrategy } from 'passport-client-cert'

✗ import ClientCertStrategy from 'passport-client-cert' // works but loses type info

Renaming the import for clarity is common; type definitions support both.

Establishes HTTPS server with mutual TLS, uses passport-client-cert strategy to authenticate users based on client certificate common name.

import express from 'express'; import https from 'https'; import fs from 'fs'; import passport from 'passport'; import { Strategy as ClientCertStrategy } from 'passport-client-cert'; const app = express(); passport.use(new ClientCertStrategy((clientCert, done) => { const cn = clientCert.subject?.CN ?? ''; const user = cn === 'allowed-cn' ? { name: 'Allowed User' } : null; done(null, user); })); app.get('/protected', passport.authenticate('client-cert', { session: false }), (req, res) => { res.json({ user: req.user }); }); const server = https.createServer({ key: fs.readFileSync('/path/to/server-key.pem'), cert: fs.readFileSync('/path/to/server-cert.pem'), ca: fs.readFileSync('/path/to/ca.pem'), requestCert: true, rejectUnauthorized: true }, app); server.listen(3443, () => console.log('Listening on https://localhost:3443'));

Debug

Known issues

gotchaThe verify callback expects the plain certificate object, not the TLS socket. The object structure follows Node's tls.TLSSocket.getPeerCertificate() output which may differ between Node versions (e.g., 'subject' may have different key casing).

fix

Check the clientCert object structure: ensure you access properties like clientCert.subject.CN (note: uppercase CN, not cn). Use optional chaining for safety.

affects: >=1.0.0

gotchaPassport session support is not enabled by default. Calling authenticate with session: false is typical; if sessions are desired, you must call req.login() manually or configure passport serialize/deserialize.

fix

Either use session: false in authenticate or implement passport.serializeUser/deserializeUser and call req.login(user) in verify callback.

affects: >=1.0.0

breakingIn v2.0.0, the package switched to ES module syntax. CommonJS require() may need to use .default or dynamic import.

fix

Use import { Strategy } from 'passport-client-cert' or const { Strategy } = await import('passport-client-cert'). For CommonJS, use require('passport-client-cert').default if default export, but named export works with older Node.

affects: >=2.0.0

deprecatedThe option 'clientCertStrategy' misspelled? No, but be aware that the strategy constructor differs from the original v1.x where require('passport-client-cert') returned the Strategy directly.

fix

Update import pattern: const Strategy = require('passport-client-cert').Strategy;

affects: <2.0.0

Errors

Common errors & fixes

Error: Unknown authentication strategy "client-cert"

Strategy name not registered or misspelled; passport.use() must be called with the strategy instance, and the name defaults to 'client-cert'.

fix

Make sure passport.use(new ClientCertStrategy(...)) is executed before authenticate. Verify the strategy name is correct (default is 'client-cert').

TypeError: Cannot read properties of undefined (reading 'subject')

The client certificate object is undefined when requestCert is not set or when no certificate is sent.

fix

Ensure the server has requestCert: true, and optionally handle cases where clientCert is null/falsy in the verify callback.

Error: failed to parse certificate

The client certificate provided is not a valid PEM or DER-encoded X.509 certificate.

fix

Check that the client certificate file is correctly formatted and the key matches. Use openssl to validate: openssl x509 -in cert.pem -text -noout.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

passportrequiredCore Passport.js library required for strategy integration

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ripjar/passport-client-cert ↗

packagepassport-client-cert ↗

homepagehttps://github.com/ripjar/passport-client-cert ↗