Jay is a member of the NestJS core team, primarily helping out the community on Discord and Github and contributing to various parts of the framework.

If you're here, you're either one of the avid readers of my, just stumbling about dev.to looking for something interesting to read, or you're searching for how to implement sessions withPassport andNestJS.Nest's own docs do a pretty good job of showing how to set up the use ofJWTs with Passport, but are lacking when it comes to how to use sessions. Maybe you want to use a session store because of supporting some legacy software. Maybe it's because JWTs bring too much complexity with scope. Maybe it's because you're looking for an easier way to set up refresh tokens. Whatever the case, this article is going to be for you.

Pre-requisites

I'm going to be using NestJS (it's in the title, so I hope that's obvious) and I'm going to be making use ofGuards so if you don't know what those are, I highly suggest reading up on them first. Don't worry, I'll wait.

I'm also going to be not using an HTTP client likePostman orInsomnia, but usingcURL instead. I lke living in the terminal as much as I can, as it gives me immediate feedback between my terminals. Feel free to use whichever you prefer, but the code snippets will be curls.

And speaking of immediate feedback, I'm also going to be usingtmux, which is a terminal multiplexer, to allow me to run multiple terminals at a time within the same window and logical grouping. This allows me to keep a single terminal window up and view my server logs, docker-compose instance and/or logs, and make curls without having to alt-tab to change views. Very handy, and very customizable.

Lastly, I'll be usingdocker and adocker-compose file to run aRedis instance for the session storage and to allow for running a redis-cli to be able to query the redis instance ran by Docker.

All of the code will be availableto follow along with and run here. Just note that to run it after you clone and run the install for the repo, you'll need tocd blog-posts/nestjs-passport-sessions and then runnest start --watch yourself. Just a side effect of how the repo is set up for my dev.to blogs.

Following along from scratch

If you're following along with the code that's pre-built, feel free to skip over this.

To set up a similar project from scratch, you'll need to first set up a Nest project, which is easiest through the Nest CLI

nest new session-authentication

Choose your package manager of choice, and then install the follow dependencies

pnpm i @nestjs/passport passport passport-local express-session redis connect-redis bcrypt

And the following peer dependencies

pnpm i-D @types/passport-local @types/express-session @types/connect-redis @types/bcrypt @types/redis

npm and yarn work fine as well, I just like pnpm as a package manager

Now you should be okay to follow along with the rest of the code, building as we go.

NestJS and Passport

The AuthGuard()

Like most@nestjs/ packages, the@nestjs/passport package ismostly a thin wrapper around passport, but Nest does do some cool things with the passport package that I think are worth mentioning. First, theAuthGuard mixin. At first glance, this mixin may look a little intimidating, but let's take it chunk by chunk.

exportconstAuthGuard:(type?:string|string[])=>Type<IAuthGuard>=memoize(createAuthGuard);

Ignoring thememoize call, thiscreateAuthGuard is where the magic of class creation happens. We end up passing thetype, if applicable, to thecreateAuthGuard method and will eventually pass that back to the@UseGuards(). Everything from here on, unless mentioned otherwise, will be a part of thecreateAuthGuard method.

classMixinAuthGuard<TUser=any>implementsCanActivate{constructor(@Optional()protectedreadonlyoptions?:AuthModuleOptions){this.options=this.options||{};if(!type&&!this.options.defaultStrategy){newLogger('AuthGuard').error(NO_STRATEGY_ERROR);}}...

The constructor allows for an optional injection ofAuthModuleOptions. This is what is passed toPassportModule.register(). This just allows Nest to figure out if thedefaultStrategy is used or the named one passed toAuthGuard.

asynccanActivate(context:ExecutionContext):Promise<boolean>{constoptions={...defaultOptions,...this.options,...awaitthis.getAuthenticateOptions(context)};const[request,response]=[this.getRequest(context),this.getResponse(context)];constpassportFn=createPassportContext(request,response);constuser=awaitpassportFn(type||this.options.defaultStrategy,options,(err,user,info,status)=>this.handleRequest(err,user,info,context,status));request[options.property||defaultOptions.property]=user;returntrue;}

This here reads through decently well, we have custom methods for getting the authentication options (defaults to returningundefined), getting therequest andresponse objects (defaults tocontext.switchToHttp().getRequest()/getResponse()), and then thiscreatePassportContext method that is called and then it's return is immediately called with the strategy name and options. Then, we setreq.user to the return ofpassportFn and returntrue to let the request continue. The next code block is not a part of the mixin orMixinAuthGuard class.

constcreatePassportContext=(request,response)=>(type,options,callback:Function)=>newPromise<void>((resolve,reject)=>passport.authenticate(type,options,(err,user,info,status)=>{try{request.authInfo=info;returnresolve(callback(err,user,info,status));}catch(err){reject(err);}})(request,response,err=>(err?reject(err):resolve())),);

Here's where some magic may be seen to happen: Nest ends up callingpassport.authenticate for us, so that we don't have to call it ourselves. In doing so, it wraps passport in a promise, so that we can manage the callback properly, and provides it's own handler to theauthenticate function. This entire method is actually creating a different callback function so that we can end up callingthis.handleRequest with theerr,user,info, andstatus returned by passport. This can take a bit of time to understand, and isn't necessarily needed, but it's usually good to know whatsome of the code under the hood is doing.

handleRequest(err,user,info,context,status):TUser{if(err||!user){throwerr||newUnauthorizedException();}returnuser;}

This is pretty straightforward, but it's useful to know this method is here.As mentioned in Nest's docs if you need to do any debugging about why the request is failing, here is a good place to do it. Generally just adding the lineconsole.log({ err, user, info, context, status }) is enough, and will help you figure out pretty much anything going wrong within the passport part of the request.

There's two other classes I want to talk about before getting to the implementation, but I promise it'll be worth it!

The PassportStrategy()

So the next mixin we have to look at is thePassportStrategy mixin. This is how we end up actually registering our strategy class'svalidate method to passport'sverify callback. This mixin does a little bit more in terms of some advance JS techniques, so again, lets take this chunk by chunk.

exportfunctionPassportStrategy<TextendsType<any>=any>(Strategy:T,name?:string|undefined):{new(...args):InstanceType<T>;}{abstractclassMixinStrategyextendsStrategy{

This part is pretty straightforward, we're just passing the passport strategy class and an optional renaming of the strategy to the mixin.

constructor(...args:any[]){constcallback=async(...params:any[])=>{constdone=params[params.length-1];try{constvalidateResult=awaitthis.validate(...params);if(Array.isArray(validateResult)){done(null,...validateResult);}else{done(null,validateResult);}}catch(err){done(err,null);}};

This is the first half of the constructor. You'll probably notice right of the bat that we don;'t callsuper, at least not yet. This is because we're setting up the callback to be passed to passport later. So what's happening here is we're setting up a function that's going to be callingthis.validate and getting the result from it. If that result happens to be an array, we spread the array (passport will use the first value), otherwise we'll end up calling thedone callback with just the result. If there happens to be an error, in good ole callback style, it'll be passed as the first value to thedone method.

super(...args,callback);constpassportInstance=this.getPassportInstance();if(name){passportInstance.use(name,thisasany);}else{passportInstance.use(thisasany);}}

Now we end up callingsuper, and in doing so, we overwrite the originalverify with the new callback we just created. This sets up the entire passport Strategy class that we're going to use for the strategy's name. Now all that's left to do is tell passport about it, by callingpassportInstance.use(this) (or passing the custom name as the first argument).

If any of that went a little too deep, don't worry. It's something you can come back to if you really want, but isn't necessary for the rest of ths article.

PassportSerializer

Finally, an actual class! This is the most straightforward and the last bit of passport I'll talk about before getting into the implementation of sessions. This classusually won't be used in Nest applications _unless you are using sessions, and we're about to see why.

So passport has the notion of serializing and deserializing a user. Serializing a user is just taking the user's information and compressing it/ making it as minimal as possible. In many cases, this is just using theID of the user. Deserializing a user is the opposite, taking an ID and hydrating an entire user out of it. This usually means a call to a database, but it's not necessary if you don't want to worry about it. Now, Nest has aPassportSerializer class like so:

exportabstractclassPassportSerializer{abstractserializeUser(user:any,done:Function);abstractdeserializeUser(payload:any,done:Function);constructor(){constpassportInstance=this.getPassportInstance();passportInstance.serializeUser((user,done)=>this.serializeUser(user,done));passportInstance.deserializeUser((payload,done)=>this.deserializeUser(payload,done));}getPassportInstance(){returnpassport;}}

You should only ever have one class extending thePassportSerializer, and what it should do is set up the general serialization and deserialization of the user for the session storage. Theuser passed toserializeUser is usually the same value asreq.user, and thepayload passed todeserializeUser is the value passed as the second parameter to thedone ofserializeUser. This will make a bit more sens when it is seen in code.

Break Time

Okay, that was a lot of information about NestJS and Passport all at once, and some pretty complex code to go through. Take a break here if you need to. Get some coffee, stretch your legs, go play that mobile game you've been wanting to. Whatever you want to do, or continue on with the article if you want.

Running Redis Locally

You can either install and run redis locally on your machine, or you can use adocker-compose.yml file to run redis inside a container. The following compose fle is what I used while working on this article

# docker-compose.ymlversion:'3'services:redis:image:redis:latestports:-'6379:6379'rcli:image:redis:latestlinks:-rediscommand:redis-cli -h redis

And then to run redis, I just useddocker compose up redis -d. When I needed to run the redis CLI, I useddocker compose run rcli to connect to the redis instance via the docker network.

Setting Up the Middleware

Now on to the middleware we're going to be using: for setting up sessions and a way to store them, I'm going to be usingexpress-session, andconnect-redis for the session and session store, andredis as the redis client for connect-redis. I'm also going to be setting up our middleware via aNest middleware instead of usingapp.use in thebootstrap so that when we do e2e testing, the middleware is already set up (that's out of the scope of this article). I've also got redis set up as acustom provider using the following code

// src/redis/redis.module.tsimport{Module}from'@nestjs/common';import*asRedisfrom'redis';import{REDIS}from'./redis.constants';@Module({providers:[{provide:REDIS,useValue:Redis.createClient({port:6379,host:'localhost'}),},],exports:[REDIS],})exportclassRedisModule{}

// src/redis/redis.constants.tsexportconstREDIS=Symbol('AUTH:REDIS');

which allows for us to use@Inject(REDIS) to inject the redis client. Now we can configure our middleware like so:

// src/app.module.tsimport{Inject,Logger,MiddlewareConsumer,Module,NestModule}from'@nestjs/common';import*asRedisStorefrom'connect-redis';import*assessionfrom'express-session';import*aspassportfrom'passport';import{RedisClient}from'redis';import{AppController}from'./app.controller';import{AppService}from'./app.service';import{AuthModule}from'./auth';import{REDIS,RedisModule}from'./redis';@Module({imports:[AuthModule,RedisModule],providers:[AppService,Logger],controllers:[AppController],})exportclassAppModuleimplementsNestModule{constructor(@Inject(REDIS)privatereadonlyredis:RedisClient){}configure(consumer:MiddlewareConsumer){consumer.apply(session({store:new(RedisStore(session))({client:this.redis,logErrors:true}),saveUninitialized:false,secret:'sup3rs3cr3t',resave:false,cookie:{sameSite:true,httpOnly:false,maxAge:60000,},}),passport.initialize(),passport.session(),).forRoutes('*');}}

and have passport ready to use sessions. There's two important things to note here:

1. passport.initialize() must be called beforepassport.session().
2. session() must be called beforepassport.initialize()

With this now out of the way, let's move on to our auth module.

The AuthModule

To start off, let's define ourUser as the following

// src/auth/models/user.interface.tsexportinterfaceUser{id:number;firstName:string;lastName:string;email:string;password:string;role:string;}

And then haveRegisterUserDto andLoginUserDto as

// src/auth/models/register-user.dto.tsexportclassRegisterUserDto{firstName:string;lastName:string;email:string;password:string;confirmationPassword:string;role='user';}

and

// src/auth/models/login-user.dto.tsexportclassLoginUserDto{email:string;password:string;}

Now we'll set up ourLocalStrategy as

// src/auth/local.strategy.tsimport{Injectable}from'@nestjs/common';import{PassportStrategy}from'@nestjs/passport';import{Strategy}from'passport-local';import{AuthService}from'./auth.service';@Injectable()exportclassLocalStrategyextendsPassportStrategy(Strategy){constructor(privatereadonlyauthService:AuthService){super({usernameField:'email',});}asyncvalidate(email:string,password:string){returnthis.authService.validateUser({email,password});}}

Notice here we're passingusernameField: 'email' tosuper. This is because in ourRegisterUserDto andLoginUserDto we're using theemail field and notusername which is passport's default. You can change thepasswordField too, but I had no reason to do that for this article. Now we'll make ourAuthService,

// src/auth/auth.service.tsimport{BadRequestException,Injectable,UnauthorizedException}from'@nestjs/common';import{compare,hash}from'bcrypt';import{LoginUserDto,RegisterUserDto}from'./models';import{User}from'./models/user.interface';@Injectable()exportclassAuthService{privateusers:User[]=[{id:1,firstName:'Joe',lastName:'Foo',email:'joefoo@test.com',// Passw0rd!password:'$2b$12$s50omJrK/N3yCM6ynZYmNeen9WERDIVTncywePc75.Ul8.9PUk0LK',role:'admin',},{id:2,firstName:'Jen',lastName:'Bar',email:'jenbar@test.com',// P4ssword!password:'$2b$12$FHUV7sHexgNoBbP8HsD4Su/CeiWbuX/JCo8l2nlY1yCo2LcR3SjmC',role:'user',},];asyncvalidateUser(user:LoginUserDto){constfoundUser=this.users.find(u=>u.email===user.email);if(!user||!(awaitcompare(user.password,foundUser.password))){thrownewUnauthorizedException('Incorrect username or password');}const{password:_password,...retUser}=foundUser;returnretUser;}asyncregisterUser(user:RegisterUserDto):Promise<Omit<User,'password'>>{constexistingUser=this.users.find(u=>u.email===user.email);if(existingUser){thrownewBadRequestException('User remail must be unique');}if(user.password!==user.confirmationPassword){thrownewBadRequestException('Password and Confirmation Password must match');}const{confirmationPassword:_,...newUser}=user;this.users.push({...newUser,password:awaithash(user.password,12),id:this.users.length+1,});return{id:this.users.length,firstName:user.firstName,lastName:user.lastName,email:user.email,role:user.role,};}findById(id:number):Omit<User,'password'>{const{password:_,...user}=this.users.find(u=>u.id===id);if(!user){thrownewBadRequestException(`No user found with id${id}`);}returnuser;}}

our controller

// src/auth/auth.controller.tsimport{Body,Controller,Post,Req,UseGuards}from'@nestjs/common';import{LocalGuard}from'../local.guard';import{AuthService}from'./auth.service';import{LoginUserDto,RegisterUserDto}from'./models';@Controller('auth')exportclassAuthController{constructor(privatereadonlyauthService:AuthService){}@Post('register')registerUser(@Body()user:RegisterUserDto){returnthis.authService.registerUser(user);}@UseGuards(LocalGuard)@Post('login')loginUser(@Req()req,@Body()user:LoginUserDto){returnreq.session;}}

and our serializer

// src/auth/serialization.provider.tsimport{Injectable}from'@nestjs/common';import{PassportSerializer}from'@nestjs/passport';import{AuthService}from'./auth.service';import{User}from'./models/user.interface';@Injectable()exportclassAuthSerializerextendsPassportSerializer{constructor(privatereadonlyauthService:AuthService){super();}serializeUser(user:User,done:(err:Error,user:{id:number;role:string})=>void){done(null,{id:user.id,role:user.role});}deserializeUser(payload:{id:number;role:string},done:(err:Error,user:Omit<User,'password'>)=>void){constuser=this.authService.findById(payload.id);done(null,user);}}

along with our module

// src/auth/auth.module.tsimport{Module}from'@nestjs/common';import{PassportModule}from'@nestjs/passport';import{AuthController}from'./auth.controller';import{AuthService}from'./auth.service';import{LocalStrategy}from'./local.strategy';import{AuthSerializer}from'./serialization.provider';@Module({imports:[PassportModule.register({session:true,}),],providers:[AuthService,LocalStrategy,AuthSerializer],controllers:[AuthController],})exportclassAuthModule{}

All we need to do for theAuthSerializer is to add it to theproviders array. Nest will instantiate it, which will end up callingpassport.serializeUser andpassport.deserializeUser for us (told you going over that would be useful).

The Guards

So now let's get to our guards, as you'll notice up in theAuthController we're not usingAuthGuard('local'), butLocalGuard. The reason for this is because we need to end up callingsuper.logIn(request), which theAuthGuardhas, but doesn't make use of by default. This just ends up callingrequest.login(user, (err) => done(err ? err : null, null)) for us, which is how the user serialization happens. This is what kicks off the session. I'll repeat that because it'ssuper important.super.logIn(request)is how the user gets a session. To make use of this method, we can set up theLocalGuard as below

// src/local.guard.tsimport{ExecutionContext,Injectable}from'@nestjs/common';import{AuthGuard}from'@nestjs/passport';@Injectable()exportclassLocalGuardextendsAuthGuard('local'){asynccanActivate(context:ExecutionContext):Promise<boolean>{constresult=(awaitsuper.canActivate(context))asboolean;awaitsuper.logIn(context.switchToHttp().getRequest());returnresult;}}

We have another guard as well, theLoggedInGuard. This guards ends up just callingrequest.isAuthenticated() which is a method that passport ends up adding to the request object when sessions are in use. We can use this instead of having to have the user pass us the username and password every request, because there will be a cookie with the user's session id on it.

// src/logged-in.guard.tsimport{CanActivate,ExecutionContext,Injectable}from'@nestjs/common';@Injectable()exportclassLoggedInGuardimplementsCanActivate{canActivate(context:ExecutionContext){returncontext.switchToHttp().getRequest().isAuthenticated();}}

And now we have one other guard for checking if a user is an admin or not.

// src/admin.guard.tsimport{ExecutionContext,Injectable}from'@nestjs/common';import{LoggedInGuard}from'./logged-in.guard';@Injectable()exportclassAdminGuardextendsLoggedInGuard{canActivate(context:ExecutionContext):boolean{constreq=context.switchToHttp().getRequest();returnsuper.canActivate(context)&&req.session.passport.user.role==='admin';}}

This guard extends our usualLoggedInGuard and checks for the user's role, which is saved in the redis session, via theAuthSerializer we created earlier.

A couple of extra classes

There's a few other classes that I'm making use of. It'll be easiest to view them in the GitHub repo, but I'll add them here if you just want to copy paste:

// src/app.controller.tsimport{Controller,Get,UseGuards}from'@nestjs/common';import{AdminGuard}from'./admin.guard';import{AppService}from'./app.service';import{LoggedInGuard}from'./logged-in.guard';@Controller()exportclassAppController{constructor(privatereadonlyappService:AppService){}@Get()publicRoute(){returnthis.appService.getPublicMessage();}@UseGuards(LoggedInGuard)@Get('protected')guardedRoute(){returnthis.appService.getPrivateMessage();}@UseGuards(AdminGuard)@Get('admin')getAdminMessage(){returnthis.appService.getAdminMessage();}}

// src/app.service.tsimport{Injectable}from'@nestjs/common';@Injectable()exportclassAppService{getPublicMessage():string{return'This message is public to all!';}getPrivateMessage():string{return'You can only see this if you are authenticated';}getAdminMessage():string{return'You can only see this if you are an admin';}}

// src/main.tsimport{Logger}from'@nestjs/common';import{NestFactory}from'@nestjs/core';import{AppModule}from'./app.module';constbootstrap=async()=>{constapp=awaitNestFactory.create(AppModule);constlogger=app.get(Logger);awaitapp.listen(3000);logger.log(`Application listening at${awaitapp.getUrl()}`);};bootstrap();

Testing out the flow

So now, we can run everything all together and test out the flow. First things first, make sure the Redis instance is running. Without that, the server won't start. Once it's running, runnest start --watch to start the server in dev mode which will recompile and restart on file change. Now it's time to send somecurls.

Testing Existing Users

So let's start off with some existing user test. We'll try to log in as Joe Foo.

curl http://localhost:3000/auth/login-d'email=joefoo@test.com&password=Passw0rd!'-c cookie.joe.txt

If you aren't familiar with curl, the-d make the request a POST, and sends the data asapplication/x-www-form-urlencoded which Nest accepts by default. The-c tells curl that it should start the cookie engine and save the cookies to a file. If all goes well, you should get a response like

{"cookie":{"originalMaxAge":60000,"expires":"2021-08-16T05:30:51.621Z","httpOnly":false,"path":"/","sameSite":true},"passport":{"user":1}}

Now we can send a request to/protected and get our protected response back

curl http://localhost:3000/protected-b cookie.joe.txt

With-b we are telling curl to use the cookies found in this file.

Now let's check the registration:

curl http://localhost:3000/auth/register-c cookie.new.txt-d'email=new.email@test.com&password=password&confirmationPassword=password&firstName=New&lastName=Test'

You'll notice that no session was created for the new user, which means they still need to log in. Now let's send that login request

curl http://localhost:3000/auth/login-c cookie.new.txt-d'email=new.email@test.com&password=password'

And check that we did indeed create a session

curl http://localhost:3000/protected-b cookie.new.txt`

And just like that, we've implemented a session login with NestJS, Redis, and Passport.

To view the session IDs in redis, you can connect the redis-cli to the running instance and runKEYS * to get all of the set keys. By defaultconnect-redis usessess: as a session key prefix.

Conclusion

Phew, okay, that was definitely a longer article than I had anticipated with a much deeper focus on Nest's integration with Passport, but hopefully it helps paint a picture of how everything ties together. With the above, it should be possible to integrate sessions with any kind of login, basic, local, OAuth2.0, so long as the user object remains the same.

One last thing to note, when using sessions, cookies are a must. The client must be able to work with cookies, otherwise the session will essentially be lost on each request.

If you have any questions, feel free to leave a comment or find me on theNestJS Discord Server