Passport.js: The Local Strategy for Username/Password Auth

Why it exists

Passport.js provides a modular way to handle authentication in Node.js. The Local Strategy is the specific plugin for the most common case: authenticating a user with a username and password that you store and manage yourself, as opposed to delegating to a social login provider.

The mental model

Think of Passport as an authentication framework, not a turnkey solution. It uses 'strategies' for different auth methods. The Local Strategy is for credentials stored 'locally' in your app's database. Your job is to write one piece of logic—a 'verify' function—and Passport handles plugging it into the Express request/response cycle, managing sessions, and protecting routes.

How it works

First, you instantiate LocalStrategy and give it a custom verify function. When a user submits a login form, Passport passes the username and password to this function. Your code is then responsible for finding the user in your database. If the user is found, you must hash the submitted password (using the user's stored salt) and compare it to the hashed password stored in your database. This comparison must be done with a timing-safe function to prevent attackers from guessing passwords based on response times. Finally, you call a callback with the user object on success, or with false on failure. This entire flow is triggered by adding passport.authenticate('local') as middleware to your login route.

When to use it

Use the Local Strategy whenever your application is the source of truth for user accounts. It's the standard for any Express app with its own user registration and login forms, giving you full control over the database schema and password security practices like hashing and salting.

When not to use it

Do not use the Local Strategy for third-party authentication. For social logins (Google, Facebook), enterprise SSO (SAML), or other federated identity protocols (OpenID Connect), you must use a different, purpose-built Passport strategy, such as passport-google-oauth20.

One canonical example

The core of the strategy is the verify function you provide. It receives credentials, looks up the user, and securely checks the password. For example: function verify(username, password, cb) { findUserByUsername(username, (err, user) => { if (err || !user) { return cb(null, false, { message: 'Incorrect username.' }); } checkPassword(password, user.hashed_password, user.salt, (err, isMatch) => { if (err || !isMatch) { return cb(null, false, { message: 'Incorrect password.' }); } return cb(null, user); }); }); } This function is then registered with Passport: passport.use(new LocalStrategy(verify));