0
# Passport
1

2
Passport is a comprehensive Express-compatible authentication middleware for Node.js that provides a complete authentication framework through an ecosystem of 480+ strategies. It serves as a lightweight, unobtrusive authentication layer that handles request authentication without imposing database schema constraints or mounting routes, giving developers maximum flexibility in application architecture.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const passport = require("passport");
15
```
16

17
For ES modules:
18

19
```javascript
20
import passport from "passport";
21
```
22

23
Access to constructors and strategies:
24

25
```javascript
26
const { Passport, Strategy } = require("passport");
27
// or
28
import { Passport, Strategy } from "passport";
29
```
30

31
## Basic Usage
32

33
```javascript
34
const express = require("express");
35
const session = require("express-session");
36
const passport = require("passport");
37
const LocalStrategy = require("passport-local").Strategy;
38

39
const app = express();
40

41
// Configure express-session middleware
42
app.use(session({
43
  secret: "keyboard cat",
44
  resave: false,
45
  saveUninitialized: false
46
}));
47

48
// Initialize Passport
49
app.use(passport.initialize());
50
app.use(passport.session());
51

52
// Configure user serialization
53
passport.serializeUser((user, done) => {
54
  done(null, user.id);
55
});
56

57
passport.deserializeUser((id, done) => {
58
  // Load user from database
59
  User.findById(id, (err, user) => {
60
    done(err, user);
61
  });
62
});
63

64
// Register authentication strategy
65
passport.use(new LocalStrategy(
66
  (username, password, done) => {
67
    // Verify credentials
68
    User.findOne({ username }, (err, user) => {
69
      if (err) return done(err);
70
      if (!user || !user.validatePassword(password)) {
71
        return done(null, false, { message: "Invalid credentials" });
72
      }
73
      return done(null, user);
74
    });
75
  }
76
));
77

78
// Protected route
79
app.post("/login",
80
  passport.authenticate("local", {
81
    successRedirect: "/dashboard",
82
    failureRedirect: "/login"
83
  })
84
);
85
```
86

87
## Architecture
88

89
Passport is built around several key components:
90

91
- **Authenticator**: Core class managing strategies, serialization, and middleware generation
92
- **Strategies**: Pluggable authentication mechanisms (local, OAuth, etc.)
93
- **Session Management**: User serialization/deserialization for persistent login sessions
94
- **Middleware System**: Express/Connect compatible middleware for authentication flow
95
- **Request Extensions**: Helper methods added to HTTP request objects
96

97
## Capabilities
98

99
### Core Authentication
100

101
Main authentication functionality including strategy management, middleware creation, and request processing. This is the primary interface for integrating Passport into applications.
102

103
```javascript { .api }
104
// Default singleton instance
105
const passport = require("passport");
106

107
// Strategy management
108
passport.use(name, strategy);
109
passport.use(strategy);
110
passport.unuse(name);
111

112
// Middleware generation
113
passport.initialize(options);
114
passport.authenticate(strategy, options, callback);
115
passport.authorize(strategy, options, callback);
116
passport.session(options);
117
```
118

119
[Core Authentication](./core-authentication.md)
120

121
### Session Management
122

123
User session handling including login/logout operations and user serialization/deserialization for persistent authentication state across requests.
124

125
```javascript { .api }
126
// User serialization/deserialization
127
passport.serializeUser(fn);
128
passport.deserializeUser(fn);
129

130
// Request methods (added by Passport)
131
req.logIn(user, options, callback);
132
req.logOut(options, callback);
133
req.isAuthenticated();
134
req.isUnauthenticated();
135
```
136

137
[Session Management](./session-management.md)
138

139
### Strategy Development
140

141
Framework for creating custom authentication strategies and understanding the strategy interface for advanced authentication scenarios.
142

143
```javascript { .api }
144
const Strategy = require("passport-strategy");
145

146
class CustomStrategy extends Strategy {
147
  constructor(options, verify) {
148
    super();
149
    this.name = "custom";
150
    // Strategy implementation
151
  }
152
  
153
  authenticate(req, options) {
154
    // Authentication logic
155
    this.success(user, info);
156
    this.fail(challenge, status);
157
    this.redirect(url, status);
158
    this.pass();
159
    this.error(err);
160
  }
161
}
162
```
163

164
[Strategy Development](./strategy-development.md)
165

166
## Types
167

168
```javascript { .api }
169
interface AuthenticateOptions {
170
  session?: boolean;
171
  keepSessionInfo?: boolean;
172
  successRedirect?: string;
173
  failureRedirect?: string;
174
  successFlash?: boolean | string | { type: string; message: string };
175
  failureFlash?: boolean | string | { type: string; message: string };
176
  successMessage?: boolean | string;
177
  failureMessage?: boolean | string;
178
  failWithError?: boolean;
179
  assignProperty?: string;
180
  authInfo?: boolean;
181
  successReturnToOrRedirect?: string;
182
}
183

184
interface InitializeOptions {
185
  userProperty?: string;
186
  compat?: boolean;
187
}
188

189
interface SerializationCallback {
190
  (err: Error | null, user?: any): void;
191
}
192

193
interface DeserializationCallback {
194
  (err: Error | null, user?: any): void;
195
}
196

197
interface VerifyCallback {
198
  (err: Error | null, user?: any, info?: any): void;
199
}
200

201
class AuthenticationError extends Error {
202
  constructor(message: string, status?: number);
203
  name: "AuthenticationError";
204
  message: string;
205
  status: number;
206
}
207

208
interface SessionManagerOptions {
209
  key?: string;
210
  keepSessionInfo?: boolean;
211
}
212

213
interface LogInOptions {
214
  session?: boolean;
215
  keepSessionInfo?: boolean;
216
}
217

218
interface LogOutOptions {
219
  keepSessionInfo?: boolean;
220
}
221

222
interface TransformAuthInfoCallback {
223
  // Synchronous (arity 1)
224
  (info: any): any;
225
  // Asynchronous (arity 2)  
226
  (info: any, done: (err: Error | null, transformedInfo?: any) => void): void;
227
  // With request access (arity 3)
228
  (req: any, info: any, done: (err: Error | null, transformedInfo?: any) => void): void;
229
}
230

231
interface FrameworkAdapter {
232
  initialize(passport: any, options?: any): Function;
233
  authenticate(passport: any, name?: string | string[], options?: any, callback?: Function): Function;
234
}
235

236
// External dependencies (not part of Passport core)
237
interface UtilsMerge {
238
  (dest: any, src: any): any;
239
}
240

241
interface PauseStream {
242
  (stream: any): any;
243
}
244

245
interface PassportStrategy {
246
  name: string;
247
  authenticate(req: any, options?: any): void;
248
}
249
```