0
# Passport Local
1

2
Passport Local provides a local username and password authentication strategy for the Passport authentication middleware. It enables traditional credential-based authentication in Node.js applications using Connect-style middleware frameworks like Express.
3

4
## Package Information
5

6
- **Package Name**: passport-local
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install passport-local`
10

11
## Core Imports
12

13
```javascript
14
const LocalStrategy = require('passport-local').Strategy;
15
```
16

17
Or using the default export:
18

19
```javascript
20
const LocalStrategy = require('passport-local');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const passport = require('passport');
27
const LocalStrategy = require('passport-local').Strategy;
28

29
passport.use(new LocalStrategy(
30
  function(username, password, done) {
31
    User.findOne({ username: username }, function (err, user) {
32
      if (err) { return done(err); }
33
      if (!user) { return done(null, false); }
34
      if (!user.verifyPassword(password)) { return done(null, false); }
35
      return done(null, user);
36
    });
37
  }
38
));
39

40
// Authenticate requests
41
app.post('/login', 
42
  passport.authenticate('local', { failureRedirect: '/login' }),
43
  function(req, res) {
44
    res.redirect('/');
45
  });
46
```
47

48
## Capabilities
49

50
### Strategy Constructor
51

52
Creates a new local authentication strategy instance.
53

54
```javascript { .api }
55
/**
56
 * Local authentication strategy constructor
57
 * @param {Object} options - Configuration options (optional)
58
 * @param {Function} verify - Callback function that verifies username/password
59
 */
60
function Strategy(options, verify);
61

62
// Constructor overload - when options is omitted
63
function Strategy(verify);
64
```
65

66
#### Options
67

68
```javascript { .api }
69
interface StrategyOptions {
70
  /** Field name where the username is found, defaults to 'username' */
71
  usernameField?: string;
72
  /** Field name where the password is found, defaults to 'password' */
73
  passwordField?: string;
74
  /** When true, req is the first argument to the verify callback (default: false) */
75
  passReqToCallback?: boolean;
76
}
77
```
78

79
#### Verify Callback
80

81
```javascript { .api }
82
/**
83
 * Verify callback function for authenticating credentials
84
 * @param {string} username - Username from request
85
 * @param {string} password - Password from request
86
 * @param {Function} done - Callback to complete authentication
87
 */
88
function verifyCallback(username, password, done);
89

90
/**
91
 * Verify callback function with request object (when passReqToCallback is true)
92
 * @param {Object} req - HTTP request object
93
 * @param {string} username - Username from request
94
 * @param {string} password - Password from request
95
 * @param {Function} done - Callback to complete authentication
96
 */
97
function verifyCallbackWithReq(req, username, password, done);
98
```
99

100
#### Done Callback
101

102
```javascript { .api }
103
/**
104
 * Authentication completion callback
105
 * @param {Error|null} err - Error if authentication failed due to error
106
 * @param {Object|false} user - User object if authentication succeeded, false if failed
107
 * @param {Object} info - Additional info object (optional)
108
 */
109
function doneCallback(err, user, info);
110
```
111

112
### Strategy Properties
113

114
```javascript { .api }
115
class Strategy {
116
  /** Strategy name, always 'local' */
117
  name: string;
118
}
119
```
120

121
### Authentication Method
122

123
The authenticate method is called internally by Passport and should not be called directly.
124

125
```javascript { .api }
126
/**
127
 * Authenticate request based on form submission contents
128
 * @param {Object} req - HTTP request object
129
 * @param {Object} options - Authentication options
130
 */
131
Strategy.prototype.authenticate(req, options);
132
```
133

134
#### Authentication Options
135

136
```javascript { .api }
137
interface AuthenticateOptions {
138
  /** Custom message for missing credentials (default: 'Missing credentials') */
139
  badRequestMessage?: string;
140
}
141
```
142

143
## Error Handling
144

145
The strategy handles the following error scenarios:
146

147
- **Missing verify callback**: Throws `TypeError` if verify callback is not provided to constructor
148
- **Missing credentials**: Returns 400 Bad Request with configurable message when username or password is missing
149
- **Authentication failure**: Calls `this.fail()` when verify callback returns false for user
150
- **Runtime errors**: Calls `this.error()` when verify callback throws an exception
151

152
## Integration with Passport
153

154
```javascript
155
// Register the strategy
156
passport.use(new LocalStrategy(verifyCallback));
157

158
// Use in routes
159
app.post('/login', passport.authenticate('local', options));
160
```
161

162
The strategy integrates with Passport's standard authentication flow:
163
1. Extracts username/password from request body or query parameters
164
2. Calls the provided verify callback with credentials
165
3. Handles the authentication result via Passport's success/fail/error methods
166

167
## Field Extraction
168

169
Credentials are extracted from the request in the following order:
170
1. From `req.body` using the configured field names
171
2. From `req.query` using the configured field names (fallback)
172

173
The field extraction supports nested field paths using bracket notation (e.g., `user[name]`).