API with NestJS #3. Authenticating users with bcrypt, Passport, JWT, and cookies

JavaScript NestJS TypeScript

Authentication is a crucial part of almost every web application. There are many ways to approach it, and we’ve handled it manually in our TypeScript Express series. This time we look into the passport, which is the most popular Node.js authentication library. We also register users and make their passwords secure by hashing.

You can find all of the code from this series in this repository. Feel free to give it a star.

Defining the User entity

The first thing to do when considering authentication is to register our users. To do so, we need to define an entity for our users.


The only new thing above is the unique flag. It indicates that there should not be two users with the same email. This functionality is built into PostgreSQL and helps us to keep the consistency of our data. Later, we depend on emails being unique when authenticating.

We need to perform a few operations on our users. To do so, let’s create a service.



All of the above is wrapped using a module.


Handling passwords

An essential thing about registration is that we don’t want to save passwords in plain text. If at any time our database gets breached, our passwords would have been directly exposed.

To make passwords more secure, we hash them. In this process, the hashing algorithm transforms one string into another string. If we change just one character of a string, the outcome is entirely different.

The above operation can only be performed one way and can’t be reversed easily. This means that we don’t know the passwords of our users. When the user attempts to log in, we need to perform this operation once again. Then, we compare the outcome with the one saved in the database.

Since hashing the same string twice gives the same result, we use salt. It prevents users that have the same password from having the same hash. Salt is a random string added to the original password to achieve a different result every time.

Using bcrypt

We use the bcrypt hashing algorithm implemented by the bcrypt npm package. It takes care of hashing the strings, comparing plain strings with hashes, and appending salt.

Using bcrypt might be an intensive task for the CPU. Fortunately, our bcrypt implementation uses a thread pool that allows it to run in an additional thread. Thanks to that, our application can perform other tasks while generating the hash.

When we use bcrypt, we define salt rounds. It boils down to being a cost factor and controls the time needed to receive a result. Increasing it by one doubles the time. The bigger the cost factor, the more difficult it is to reverse the hash with brute-forcing. Generally speaking, 10 salt rounds should be fine.

The salt used for hashing is a part of the result, so no need to keep it separately.

Creating the authentication service

With all of the above knowledge, we can start implementing basic registering and logging in functionalities. To do so, we need to define an authentication service first.

Authentication means checking the identity of user. It provides an answer to a question: who is the user?

Authorization is about access to resources. It answers the question: is user authorized to perform this operation?


 is not the cleanest way to not send the password in a response. In the upcoming parts of this series we explore mechanisms that help us with that.

A few notable things are happening above. We create a hash and pass it to the   method along with the rest of the data. We use a  statement here because there is an important case when it might fail. If a user with that email already exists, the   method throws an error. Since our unique column cases it the error comes from Postgres.

To understand the error, we need to look into the PostgreSQL Error Codes documentation page. Since the code for uniqe_violation is 23505, we can create an enum to handle it cleanly.


Since in the above service we state explicitly that a user with this email already exists, it might a good idea to implement a mechanism preventing attackers from brute-forcing our API in order to get a list of registered emails

The thing left for us to do is to implement the logging in.


An important thing above is that we return the same error, whether the email or password is wrong. Doing so prevents some attacks that would aim to get a list of emails registered in our database.

There is one small thing about the above code that we might want to improve. Within our   method, we throw an exception that we then catch locally. It might be considered confusing. Let’s create a separate method to verify the password:

Integrating our authentication with Passport

In the TypeScript Express series, we’ve handled the whole authentication process manually. NestJS documentation suggests using the Passport library and provides us with the means to do so. Passport gives us an abstraction over the authentication, thus relieving us from some heavy lifting. Also, it is heavily tested in production by many developers.

Diving into how to implement the authentication manually without Passport is still a good idea. By doing so, we can get an even better understanding of this process

Applications have different approaches to authentication. Passport calls those mechanisms strategies. The first strategy that we want to implement is the passport-local strategy. It is a strategy for authenticating with a username and password.

To configure a strategy, we need to provide a set of options specific to a particular strategy. In NestJS, we do it by extending the   class.


For every strategy, Passport calls the  function using a set of parameters specific for a particular strategy. For the local strategy, Passport needs a method with a username and a password. In our case, the email acts as a username.

We also need to configure our  to use Passport.


Using built-in Passport Guards

The above module uses the  . Let’s create the basics of it now.

Below, we use Guards. Guard is responsible for determining whether the route handler handles the request or not. In its nature, it is similar to Express.js middleware but is more powerful.

We focus on guards quite a bit in the upcoming parts of this series and create custom guards. Today we only use the existing guards though.


Above we use   because NestJS responds with 201 Created for POST requests by default


Passing the strategy name directly into   in the controller might not be considered a clean approach. Instead, we create our own class.


Thanks to doing all of the above, our  route is handled by Passport. The data of the user is attached to the  object, and this is why we extend the  interface.

If the user authenticates successfully, we return his data. Otherwise, we throw an error.

Using JSON Web Tokens

We aim to restrict some parts of the application. By doing so, only authenticated users can access them. We don’t want them to need to authenticate for every request. Instead, we need a way to let the users indicate that they have already logged in successfully.

A simple way to do so is to use JSON Web Tokens. JWT is a string that is created on our server using a secret key, and only we can decode it. We want to give it to the user upon logging in so that it can be sent back on every request. If the token is valid, we can trust the identity of the user.

The first thing to do is to add two new environment variables:   and  .

We can use any string as a JWT secret key. It is important to keep it secret and not to share it. We use it to encode and decode tokens in our application.

We describe our expiration time in seconds to increase security. If someone’s token is stolen, the attacker has access to the application in a similar way to having a password. Due to the expiry time, the issue is partially dealt with because the token will expire.


Generating tokens

In this article, we want the users to store the JWT in cookies. It has a certain advantage over storing tokens in the web storage thanks to the HttpOnly directive. It can’t be accessed directly through JavaScript in the browser, making it more secure and resistant to attacks like cross-site scripting.

If you want to know more about cookies, check oout Cookies: explaining document.cookie and the Set-Cookie header

Now, let’s configure the  .


Thanks to that, we can now use  in our .



We need to send the token created by the   method when the user logs in successfully. We do it by sending the Set-Cookie header. To do so, we need to directly use the   object.

When the browser receives this response, it sets the cookie so that it can use it later.

Receiving tokens

To be able to read cookies easily we need the  .


Now, we need to read the token from the Cookie header when the user requests data. To do so, we need a second passport strategy.


There are a few notable things above. We extend the default JWT strategy by reading the token from the cookie.

When we successfully access the token, we use the id of the user that is encoded inside. With it, we can get the whole user data through the   method. We also need to add it to our  .


Thanks to the   method running under the hood when the token is encoded, we have access to all of the user data.

We now need to add our new  to the  .


Requiring authentication from our users

Now, we can require our users to authenticate when sending requests to our API. To do so, we first need to create our  .


Now, we can use it every time we want our users to authenticate before making a request. For example, we might want to do so, when creating posts through our API.


Logging out

JSON Web Tokens are stateless. We can’t change a token to be invalid in a straightforward way. The easiest way to implement logging out is just to remove the token from the browser. Since the cookies that we designed are  , we need to create an endpoint that clears it.



Verifying tokens

One important additional functionality that we need is verifying JSON Web Tokens and returning user data. By doing so, the browser can check if the current token is valid and get the data of the currently logged in user.

Postman authentication endpoint


In this article, we’ve covered registering and logging in users in NestJS. To implement it, we’ve used bcrypt to hash passwords to secure them. To authenticate users, we’ve used JSON Web Tokens. There are still ways to improve the above features. For example, we should exclude passwords more cleanly. Also, we might want to implement the token refreshing functionality. Stay tuned for more articles about NestJS!

Series Navigation<< API with NestJS #2. Setting up a PostgreSQL database with TypeORMAPI with NestJS #4. Error handling and data validation >>
Notify of