NestJS course ยท Module 4: Authentication
Passport.js - the access control system
In this lesson6
You already know how to issue a JWT pass and check a password. But in a real Empire all sorts of visitors approach the gates: one has a password, another a sealed pass, a third a letter of recommendation from an ally in Gaul, a fourth a key to the trade gate. Handling each of them separately means duplicating the same logic four times - and every way in is a fresh chance to get it wrong.
The Romans put a guardhouse at the gate with one set of regulations and many sentries: each sentry knows one kind of document, but they all report in the same way. In NestJS that guardhouse is Passport.js - a library where every login method is a separate strategy, and the ecosystem offers over 500 ready-made ones.
The guardhouse's three layers
Before we write a line of code, let's establish what this guardhouse is made of - it is the skeleton of the whole lesson and it returns with every strategy:
- Passport Module - registration: tells NestJS which sentries we employ at all.
- Strategy - the verification logic: one sentry checking one kind of document.
- Guard - activation: names which sentry we call at this particular gate.
- The
@UseGuards()decorator - posting the guard at an endpoint's entrance.
Remember the order from the bottom up: the strategy knows how to check, the guard knows whom to call, the decorator knows where to post them.
The local strategy - the password sentry
Let's start with the simplest sentry: he checks a login and a password.
@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
constructor(private authService: AuthService) {
super({
usernameField: 'username',
passwordField: 'password',
});
}
async validate(username: string, password: string): Promise<any> {
const user = await this.authService.validateUser(username, password);
if (!user) {
throw new UnauthorizedException();
}
return user;
}
}Let's walk through this class, because each of its elements will repeat in the strategies that follow. PassportStrategy(Strategy) is a base class built from the imported Strategy - here from the passport-local package. Change the package and you change the kind of sentry, while the rest of the skeleton stays.
The super() call in the constructor configures the strategy. usernameField and passwordField say which request fields to take the data from - and this is a common snagging point, because if your form sends email instead of username, this is exactly where you declare it.
The heart is validate(). Passport calls it itself, handing over the extracted fields, and your job is to answer: who is this. Note this method's contract - it is the most important sentence in this lesson. The returned object lands in request.user and becomes available in the controller. When the document is false, you do not return null or false - you throw UnauthorizedException, and NestJS turns it into a 401 response.
The guard - calling a sentry by name
A strategy will not act on its own. It has to be activated, and that is what a guard does:
@Injectable()
export class LocalAuthGuard extends AuthGuard('local') {}Yes, that is the whole class body - empty. AuthGuard('local') builds a ready-made guard which finds the registered strategy by name and runs its validate(). The name 'local' is not arbitrary: it is the default identifier of the strategy from the passport-local package, just as 'jwt' belongs to passport-jwt and 'google' to the Google strategy.
The guard for the JWT passes you met in the previous lesson looks the same:
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}Why write a class at all, when you could put @UseGuards(AuthGuard('local')) directly? For two reasons: the name LocalAuthGuard reads better in a controller, and when you want to add your own behaviour, you have somewhere to put it. That is exactly what the handleRequest method is for, and you can override it:
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
handleRequest(err: any, user: any) {
if (err) {
throw err;
}
if (!user) {
throw new UnauthorizedException('Pass invalid or expired');
}
return user;
}
}The order here is logical and worth remembering: first you check the error, then the presence of a user, and only at the end you return the object - and what you return lands in request.user. We override this method mainly to give a readable message instead of a bare 401.
An external strategy - the letter from Gaul
Since the skeleton does not change, adding Google login comes down to swapping the package and the configuration. The sentry is new, the regulations are the same.
@Injectable()
export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
constructor(private configService: ConfigService) {
super({
clientID: configService.get('GOOGLE_CLIENT_ID'),
clientSecret: configService.get('GOOGLE_CLIENT_SECRET'),
callbackURL: '/auth/google/callback',
scope: ['email', 'profile'],
});
}
}Here Strategy comes from the passport-google-oauth20 package. clientID and clientSecret are your application's credentials issued by Google - which is why we read them through ConfigService from environment variables instead of writing them into the code. A secret in a repository is somebody else's secret; I recommend treating that as a rule without exceptions.
callbackURL is the address Google will send the user back to after login - your application must have an endpoint there. scope declares which data you are asking for.
Note the second argument in PassportStrategy(Strategy, 'google'): it is an explicitly given name, by which the AuthGuard('google') guard will find this strategy. With the local strategy we could omit it, because the default name was enough.
Posting the guard at the gate
The last step is naming which endpoints the guard watches over:
@Controller('auth')
export class AuthController {
@UseGuards(LocalAuthGuard)
@Post('login')
async login(@Request() req) {
return this.authService.generateToken(req.user);
}
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
return req.user;
}
}Here the whole chain closes. The guard ran the strategy, the strategy executed validate(), the returned object landed in request.user - and only now can the controller method reach for it. If verification failed, the method does not run at all: the guard stops the request before it reaches the controller.
Summary
The guardhouse stands, and you can employ any sentry in it:
- Passport.js is an authentication framework in which every login method is a separate strategy - the ecosystem provides over 500 ready-made ones,
- the layers stack from the bottom: strategy (how to check), guard (whom to call),
@UseGuards()(where to post them), - a strategy extends
PassportStrategy(Strategy), is configured throughsuper({...})and implementsvalidate(), validate()returns the user, who lands inrequest.user, and on rejection it throwsUnauthorizedException,- a guard is usually an empty class:
extends AuthGuard('local'),AuthGuard('jwt'),AuthGuard('google'), - you override
handleRequestwhen you want your own handling: check the error, check the user, return the object, - external strategies differ only in package and configuration; read
clientIDandclientSecretfromConfigService, never from code, - the second argument of
PassportStrategy(Strategy, 'name')gives the strategy the name its guard will look it up by.
In the next lesson we will go one level deeper - to roles and permissions, the question of what a visitor we have already admitted is allowed to do. For now remember: the strategy knows how to check a document, the guard knows which sentry to call, and request.user is the report left behind by a successful check.
Code for this lesson: src/auth/passport-strategies.ts
// Passport.js - Universal Access Control System
// Passport strategies for various login methods
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy as LocalStrategy } from 'passport-local';
import { Strategy as JwtStrategy, ExtractJwt } from 'passport-jwt';
// ===========================================
// 1. Local Strategy - login with a password
// ===========================================
@Injectable()
export class RomanLocalStrategy extends PassportStrategy(LocalStrategy) {
constructor() {
super({
usernameField: 'username', // Field with username
passwordField: 'password', // Field with the password
});
}
// Method called at login
async validate(username: string, password: string) {
// Here call AuthService.validateUser()
console.log('Local Strategy: checking', username);
// Validation simulation
if (username === 'caesar' && password === 'spqr') {
return { id: '1', username: 'caesar', rank: 'consul' };
}
throw new UnauthorizedException('Incorrect login data!');
}
}
// ===========================================
// 2. JWT Strategy - token verification
// ===========================================
@Injectable()
export class RomanJwtStrategy extends PassportStrategy(JwtStrategy) {
constructor() {
super({
// Where to extract the token from
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
// Whether to ignore expiration
ignoreExpiration: false,
// Secret for verifying the signature
secretOrKey: 'spqr-secret-key',
});
}
// Method called after token decoding
async validate(payload: any) {
console.log('JWT Strategy: token decoded', payload);
// The payload from the token goes into req.user
return {
id: payload.sub,
username: payload.username,
rank: payload.rank,
};
}
}
// ===========================================
// 3. Using the strategy in a controller
// ===========================================
import { Controller, Post, Get, UseGuards, Request } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Controller('auth')
export class AuthController {
// Login - uses LocalStrategy
@Post('login')
@UseGuards(AuthGuard('local'))
async login(@Request() req) {
console.log('Logged in:', req.user);
return { message: 'Welcome to the Empire!', user: req.user };
}
// Protected endpoint - uses JwtStrategy
@Get('profile')
@UseGuards(AuthGuard('jwt'))
getProfile(@Request() req) {
console.log('Legionary profile:', req.user);
return { user: req.user };
}
}
console.log('=== Passport Strategies ===');
console.log('LocalStrategy: username + password -> validate()');
console.log('JwtStrategy: Bearer token -> validate(payload)');
console.log('AuthGuard("local") -> uses LocalStrategy');
console.log('AuthGuard("jwt") -> uses JwtStrategy');
Docs entries used in this lesson
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What is Passport.js in the context of NestJS?
2. What does the validate() method in LocalStrategy do?
These are 2 of 12 questions for this lesson. Solve the rest in the game.
Hands-on tasks in the game
- Code editor
Complete the LocalStrategy class that extends PassportStrategy(Strategy) from passport-local and implements validate(username, password) throwing UnauthorizedException when the user does not exist
- Vertical ordering
Arrange the super() configuration options in LocalStrategy from left to right
- Click in order
Arrange the elements of the LocalAuthGuard definition in the correct order
- Code editor
Create a JwtAuthGuard class with the @Injectable() decorator that extends AuthGuard('jwt')
- Vertical ordering
Order the authentication layers in NestJS from lowest to highest
- Code editor
Complete the GoogleStrategy with clientID and clientSecret options fetched from ConfigService and callbackURL set to '/auth/google/callback'
- Click in order
Arrange the logic of the handleRequest method in AuthGuard from first to last step
- Vertical ordering
Order the steps of the OAuth 2.0 process (e.g., logging in via Google)
- Code editor
Complete the AuthController with a @Post('login') endpoint protected by @UseGuards(LocalAuthGuard) that returns a JWT token
- Horizontal ordering
Arrange the syntax for using multiple guards on an endpoint
- Code editor
Complete the generateRefreshToken method in AuthService that creates a JWT with expiresIn: '7d' and contains a payload with userId and tokenType: 'refresh'
- Click in order
Arrange the steps of the JWT token refresh process
- Code editor
Complete the controller with a @Get('profile') endpoint protected by @UseGuards(JwtAuthGuard) that returns the logged-in user's data from @Req() req
- Vertical ordering
Arrange the syntax for retrieving the user from the request in a protected endpoint
- Click in order
Arrange the elements of the jwtService.sign() call in the correct order
- Code editor
Complete the login(user) method in AuthService that creates a payload with sub: user.id and username: user.username, then returns { access_token: this.jwtService.sign(payload) }
- Vertical ordering
Order the AuthModule configuration elements from imports to exports
- Code editor
Complete the validate method in AuthService that checks email and password, and throws throw new UnauthorizedException('Invalid login credentials') when the user is not found
- Horizontal ordering
Arrange the syntax for importing AuthGuard from @nestjs/passport
- Click in order
Arrange the order of execution of layers in an HTTP request with authentication
- Code editor
Complete the AuthModule importing PassportModule, JwtModule.registerAsync(jwtConfig), with providers: [AuthService, JwtStrategy, LocalStrategy] and exports: [AuthService]
- Horizontal ordering
Arrange the syntax of the validate method in JwtStrategy from async to returning the object
- Vertical ordering
Order the JWT token lifecycle from creation to expiration
Tasks after this lesson
- QuestionWhat is Passport.js?
- QuestionLocal Strategy in Passport
- Coding taskLocalStrategy implementation
- Put in orderLocalStrategy configuration
- QuestionAuthGuard in NestJS
- Click in orderLocalAuthGuard definition
- Coding taskJwtAuthGuard implementation
- QuestionGoogle OAuth strategy
- Put in orderAuthentication layers order
- Coding taskGoogleStrategy configuration
- Click in orderhandleRequest method in Guard
- QuestionNumber of strategies in Passport.js
- Put in orderOAuth 2.0 flow
- Coding taskLogin endpoint implementation
- QuestionusernameField property in LocalStrategy
- Put in order@UseGuards decorator with multiple guards
- Coding taskRefresh Token
- Click in orderToken handling strategy
- Questionbcrypt.compare method
- QuestionJWT_SECRET key requirements
- Coding taskProtecting an endpoint with JWT
- Question@ApiBearerAuth decorator
- Put in order@Req() decorator syntax
- Click in orderjwtService.sign() method
- Coding taskToken generation service
- Put in orderAuthModule registration
- Question'sub' field in JWT payload
- Coding taskHandling 401 Unauthorized error
- QuestionPassport strategy types
- Put in orderAuthGuard import syntax
- Click in orderMiddleware vs Guard in Authentication
- Questionreq.user object after JWT authentication
- Coding taskComplete AuthModule with JWT and Passport
- Put in ordervalidate() syntax in JwtStrategy
- Put in orderJWT token lifecycle