middleware for Node.js implementing client SSL certificate authentication/authorization
Switch branches/tags
Nothing to show
Latest commit 63e6184 Mar 17, 2014 @tgies tgies 0.3.0: Support async auth, cleanup
This is version 0.3.0.

- Support asynchronous authentication function (thanks mmalecki).
  This closes #6.
- Remove some cruft from the tree.
- Call the returned function "middleware" per convention.

Squashed commit of the following:

commit 9fca8aa
Author: Tony Gies <tgies@tgies.net>
Date:   Mon Mar 17 10:23:41 2014 -0500


commit 068bd7c
Author: Tony Gies <tgies@tgies.net>
Date:   Mon Mar 17 10:21:25 2014 -0500

    Don't track .gitignore

commit 15a72e4
Merge: 4759317 cb6be60
Author: Tony Gies <tgies@tgies.net>
Date:   Mon Mar 17 10:18:47 2014 -0500

    Merge remote-tracking branch 'mmalecki/async-authorization' into develop

commit cb6be60
Author: Maciej Małecki <me@mmalecki.com>
Date:   Mon Mar 17 15:20:13 2014 +0100

    Allow asynchronous authorization

commit 4759317
Author: Tony Gies <tgies@tgies.net>
Date:   Wed May 8 08:27:54 2013 -0500

    Name the returned function "middleware"



middleware for Node.js implementing client SSL certificate authentication/authorization

Copyright © 2013 Tony Gies

April 30, 2013

Build Status


client-certificate-auth is available from npm.

$ npm install client-certificate-auth


client-certificate-auth is tested against Node.js versions 0.6, 0.8, and 0.10. It has no external dependencies (other than any middleware framework with which you may wish to use it); however, to run the tests, you will need mocha and should.


client-certificate-auth provides HTTP middleware for Node.js (in particular Connect/Express) to require that a valid, verifiable client SSL certificate is provided, and passes information about that certificate to a callback which must return true for the request to proceed; otherwise, the client is considered unauthorized and the request is aborted.


The https server must be set up to request a client certificate and validate it against an issuer/CA certificate. What follows is a typical example using Express:

var express = require('express');
var fs = require('fs');
var https = require('https');
var clientCertificateAuth = require('client-certificate-auth');

var opts = {
  // Server SSL private key and certificate
  key: fs.readFileSync('server.key'),
  cert: fs.readFileSync('server.pem'),
  // issuer/CA certificate against which the client certificate will be
  // validated. A certificate that is not signed by a provided CA will be
  // rejected at the protocol layer.
  ca: fs.readFileSync('cacert.pem'),
  // request a certificate, but don't necessarily reject connections from
  // clients providing an untrusted or no certificate. This lets us protect only
  // certain routes, or send a helpful error message to unauthenticated clients.
  requestCert: true,
  rejectUnauthorized: false

var app = express();

// add clientCertificateAuth to the middleware stack, passing it a callback
// which will do further examination of the provided certificate.
app.use(function(err, req, res, next) { console.log(err); next(); });

app.get('/', function(req, res) {

var checkAuth = function(cert) {
  * allow access if certificate subject Common Name is 'Doug Prishpreed'.
  * this is one of many ways you can authorize only certain authenticated
  * certificate-holders; you might instead choose to check the certificate
  * fingerprint, or apply some sort of role-based security based on e.g. the OU
  * field of the certificate. You can also link into another layer of
  * auth or session middleware here; for instance, you might pass the subject CN
  * as a username to log the user in to your underlying authentication/session
  * management layer.
  return cert.subject.CN === 'Doug Prishpreed';

https.createServer(opts, app).listen(4000);

Or secure only certain routes:

app.get('/unsecure', function(req, res) {
  res.send('Hello world');

app.get('/secure', clientCertificateAuth(checkAuth), function(req, res) {
  res.send('Hello authorized user');

checkAuth can also be asynchronous:

function checkAuth(cert, callback) {