Introduction to Passport.js

Philosophy: "Simple, Unobtrusive Authentication"

Passport.js is authentication middleware for Node.js created by Jared Hanson in 2011. It uses a strategy pattern to support 500+ authentication mechanisms — from local username/password to OAuth providers like Google, GitHub, Facebook, and more.

The Strategy Pattern

const LocalStrategy =
  require('passport-local').Strategy;

passport.use(new LocalStrategy(
  (username, password, done) => {
    User.findOne({ username }, (err, user) => {
      if (err) return done(err);
      if (!user) return done(null, false,
        { message: 'Unknown user' });
      if (!user.validPassword(password))
        return done(null, false,
          { message: 'Wrong password' });
      return done(null, user);
    });
  }
));

Each strategy provides a verify callback that receives credentials and calls done() with the result.

express-session Configuration

const session = require('express-session');
const MongoStore =
  require('connect-mongo');

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  store: MongoStore.create({
    mongoUrl: process.env.MONGO_URI
  }),
  cookie: {
    maxAge: 1000 * 60 * 60 * 24, // 1 day
    httpOnly: true,
    secure: process.env.NODE_ENV
      === 'production',
    sameSite: 'lax'
  }
}));

Install & Configure

npm install passport-local bcrypt

const LocalStrategy =
  require('passport-local').Strategy;

passport.use(new LocalStrategy(
  { usernameField: 'email' },
  async (email, password, done) => {
    try {
      const user =
        await User.findOne({ email });
      if (!user)
        return done(null, false,
          { message: 'No account found' });

      const match =
        await bcrypt.compare(
          password, user.password
        );
      if (!match)
        return done(null, false,
          { message: 'Wrong password' });

      return done(null, user);
    } catch (err) {
      return done(err);
    }
  }
));

Registration Route

app.post('/register', async (req, res) => {
  const { name, email, password } = req.body;

  // Check if user exists
  const existing =
    await User.findOne({ email });
  if (existing) {
    req.flash('error', 'Email in use');
    return res.redirect('/register');
  }

  // Hash password & create user
  const hash =
    await bcrypt.hash(password, 12);
  const user = await User.create({
    name, email, password: hash
  });

  // Auto-login after registration
  req.login(user, (err) => {
    if (err) return next(err);
    res.redirect('/dashboard');
  });
});

Authorization Code Flow

Install & Configure

npm install passport-google-oauth20

const GoogleStrategy =
  require('passport-google-oauth20').Strategy;

passport.use(new GoogleStrategy({
    clientID: process.env.GOOGLE_CLIENT_ID,
    clientSecret:
      process.env.GOOGLE_CLIENT_SECRET,
    callbackURL:
      '/auth/google/callback'
  },
  async (accessToken, refreshToken,
         profile, done) => {
    try {
      let user = await User.findOne({
        googleId: profile.id
      });
      if (!user) {
        user = await User.create({
          googleId: profile.id,
          name: profile.displayName,
          email: profile.emails[0].value,
          avatar: profile.photos[0].value
        });
      }
      return done(null, user);
    } catch (err) {
      return done(err);
    }
  }
));

Install & Configure

npm install passport-github2

const GitHubStrategy =
  require('passport-github2').Strategy;

passport.use(new GitHubStrategy({
    clientID:
      process.env.GITHUB_CLIENT_ID,
    clientSecret:
      process.env.GITHUB_CLIENT_SECRET,
    callbackURL:
      '/auth/github/callback'
  },
  async (accessToken, refreshToken,
         profile, done) => {
    try {
      let user = await User.findOne({
        githubId: profile.id
      });
      if (!user) {
        user = await User.create({
          githubId: profile.id,
          name: profile.displayName
            || profile.username,
          email: profile.emails?.[0]?.value,
          avatar:
            profile.photos?.[0]?.value
        });
      }
      return done(null, user);
    } catch (err) {
      return done(err);
    }
  }
));

Install & Configure

npm install passport-jwt jsonwebtoken

const JwtStrategy =
  require('passport-jwt').Strategy;
const ExtractJwt =
  require('passport-jwt').ExtractJwt;

const opts = {
  jwtFromRequest:
    ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: process.env.JWT_SECRET
};

passport.use(new JwtStrategy(opts,
  async (jwt_payload, done) => {
    try {
      const user = await User.findById(
        jwt_payload.sub
      );
      if (user) return done(null, user);
      return done(null, false);
    } catch (err) {
      return done(err, false);
    }
  }
));

ensureAuthenticated Middleware

function ensureAuth(req, res, next) {
  if (req.isAuthenticated()) {
    return next();
  }
  req.flash('error', 'Please log in');
  res.redirect('/login');
}

// Use on individual routes
app.get('/dashboard', ensureAuth,
  (req, res) => {
    res.render('dashboard', {
      user: req.user
    });
  }
);

// Use on route groups
app.use('/admin', ensureAuth, adminRouter);

Mongoose User Schema

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: {
    type: String, required: true,
    unique: true, lowercase: true
  },
  password: String,
  googleId: String,
  githubId: String,
  avatar: String,
  role: {
    type: String,
    enum: ['user', 'editor', 'admin'],
    default: 'user'
  },
  createdAt: {
    type: Date, default: Date.now
  }
});

module.exports =
  mongoose.model('User', userSchema);

Linking OAuth to Existing Accounts

// In Google strategy verify callback
async (accessToken, refreshToken,
       profile, done) => {
  // 1. Check if already linked
  let user = await User.findOne({
    googleId: profile.id
  });
  if (user) return done(null, user);

  // 2. Check if email matches existing user
  const email = profile.emails[0].value;
  user = await User.findOne({ email });
  if (user) {
    // Link Google to existing account
    user.googleId = profile.id;
    user.avatar = user.avatar
      || profile.photos[0].value;
    await user.save();
    return done(null, user);
  }

  // 3. Create new user
  user = await User.create({
    googleId: profile.id,
    name: profile.displayName,
    email, avatar: profile.photos[0].value
  });
  return done(null, user);
}

Rate Limiting Login Attempts

const rateLimit = require('express-rate-limit');

const loginLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 mins
  max: 5,
  message: 'Too many login attempts',
  standardHeaders: true,
  legacyHeaders: false
});

app.post('/login', loginLimiter,
  passport.authenticate('local', { ... })
);

Built-In Redirect Options

passport.authenticate('local', {
  successRedirect: '/dashboard',
  failureRedirect: '/login',
  failureFlash: true,
  // or custom message:
  failureFlash: 'Invalid credentials',
  successFlash: 'Welcome back!'
});

failureFlash: true uses the message from the strategy's done(null, false, { message }) call.

Supertest with Sessions

const request = require('supertest');
const app = require('../app');

describe('Auth Routes', () => {
  const agent = request.agent(app);

  it('should log in', async () => {
    await agent
      .post('/login')
      .send({
        email: 'test@test.com',
        password: 'password123'
      })
      .expect(302)
      .expect('Location', '/dashboard');
  });

  it('should access protected route',
    async () => {
      // Agent retains cookies/session
      const res = await agent
        .get('/dashboard')
        .expect(200);
      expect(res.text)
        .toContain('Dashboard');
    }
  );
});

app.js — Express + Passport + EJS

const express = require('express');
const session = require('express-session');
const passport = require('passport');
const flash = require('connect-flash');
const path = require('path');

require('./config/passport')(passport);

const app = express();
app.set('view engine', 'ejs');
app.set('views',
  path.join(__dirname, 'views'));
app.use(express.urlencoded(
  { extended: true }));
app.use(express.static('public'));

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false
}));
app.use(passport.initialize());
app.use(passport.session());
app.use(flash());

app.use((req, res, next) => {
  res.locals.currentUser = req.user;
  res.locals.success = req.flash('success');
  res.locals.error = req.flash('error');
  next();
});

app.use('/', require('./routes/index'));
app.use('/auth', require('./routes/auth'));

app.listen(3000);