There are dozens of authentication solutions to choose from today, many of which come with a price tag. Which one should you choose?

In this tutorial, we're going to take a look at how you can add authentication to your React apps for free using the industry-standard library Passport.js.

By the end, you will understand how Passport works within a real project, plus you will have all the starter code to be able to set up authentication in your future React projects.

Why Use Passport.js?

Passport.js is a battle-tested library. It has been the go-to solution for authentication in Node.js apps for many years with over 1.7 million weekly downloads.

The Passport.js Node Library

It allows your users to sign up easily with email and password at no cost. Additionally, Passport also gives us the ability to use different strategies for authentication such as social login through Google or Twitter, among hundreds of other options.

You can view authentication as an essential gateway for your users. You'll need authentication in many cases to not only separate the casual from the serious users of your applications. Authentication is used to provide the necessary experience for different categories of users.

Why Not Use a Dedicated (Paid) Auth Service?

The need to authenticate your users is a very common problem, but it doesn't mean it's an easy problem to solve.

In fact, this is why so many companies such as Auth0, Clerk.dev, Okta and many others have emerged to provide authentication as a service. In many developers' eyes, getting authentication right comes at a price.

Fortunately for us JavaScript and Node developers, we have a great library in Passport.js, which allows us to wire up authentication in Node environments quite easily.

We are going to take a look at a complete integration of Passport.js within a React application and break down how it works line-by-line.

Download the Project Code

To get the complete code which is available from the official Next.js GitHub, you can go to the following repo with NPM or Yarn.

This is going to give you all the project files that we will be looking through, plus it will give you an ideal template to use Passport.js in your next React project.

I would recommend that you download the entire examples folder from https://github.com/vercel/next.js and grab the with-passport folder. The template script included in the README includes broken code.

Passport App Demo

How the Passport Local Strategy Works

To start using Passport in your projects, you'll need to install the main passport library as well as a specific strategy.

Strategies are different methods with which your users can authenticate themselves. Passport Local is the strategy that Passport provides to enable users to sign up and login in the most traditional way–with email and password.

Both of these are included in the package.json file.

If you look in the lib folder, you can see how passport-local is set up.

// /lib/password-local.js

import Local from 'passport-local'
import { findUser, validatePassword } from './user'

export const localStrategy = new Local.Strategy(function (
  username,
  password,
  done
) {
  findUser({ username })
    .then((user) => {
      if (user && validatePassword(user, password)) {
        done(null, user)
      } else {
        done(new Error('Invalid username and password combination'))
      }
    })
    .catch((error) => {
      done(error)
    })
})

In the password-local.js file, the strategy is created and takes care of finding a user based off of their username and validating their password. If a user is found it will be returned via the done callback. If not, an error will be thrown.

If you look in /pages/api, you will see all of the server-related code which uses passport. The names of the files correspond to the actions you will need: login logout and sign up.

How to Sign Up Users with Passport

If you look at the signup file, it is simply creating a user based off of the data that's provided on the request body and is passed along with the request.

// /pages/api/signup.js

import { createUser } from '../../lib/user'

export default async function signup(req, res) {
  try {
    await createUser(req.body)
    res.status(200).send({ done: true })
  } catch (error) {
    console.error(error)
    res.status(500).end(error.message)
  }
}

When that's done, the server responds with a 200 success code, meaning your user has been created with the email and password they provided.

If you go back to the lib folder, into user.js, you can see how this createUser function works:

// /lib/user.js

const users = []

export async function createUser({ username, password }) {
  // Here you should create the user and save the salt and hashed password (some dbs may have
  // authentication methods that will do it for you so you don't have to worry about it):
  const salt = crypto.randomBytes(16).toString('hex')
  const hash = crypto
    .pbkdf2Sync(password, salt, 1000, 64, 'sha512')
    .toString('hex')
  const user = {
    id: uuidv4(),
    createdAt: Date.now(),
    username,
    hash,
    salt,
  }

  // This is an in memory store for users, there is no data persistence without a proper DB
  users.push(user)

  return { username, createdAt: Date.now() }
}

createUser takes a username and password and hashes the password so it can be saved securely and not as plain text. Then the created user is added to an array of users.

If and when you connect a database to this project, this is where you would actually create a new user in your database and swap that out with users.push

How to Log In Users with Passport

If you look at how your app works, after signing up and creating your user, the user then has to log in. When a user logs in, they make requests to /api/login.

This is where Passport actually steps in and does authentication for you. In this example, we're using the next-connect library to initialize passport before the POST request is made (upon login form submission).

// /api/login.js

passport.use(localStrategy)

export default nextConnect()
  .use(passport.initialize())
  .post(async (req, res) => {
    try {
      const user = await authenticate('local', req, res)
      // session is the payload to save in the token, it may contain basic info about the user
      const session = { ...user }

      await setLoginSession(res, session)

      res.status(200).send({ done: true })
    } catch (error) {
      console.error(error)
      res.status(401).send(error.message)
    }
  })

The login endpoint receives the data from your front end. When the POST request is made with the user's credentials, namely the email and password, it uses this authenticate function from passport to take care of authenticating your request.

Then another function, setLoginSession, takes care of creating a session for the logged-in user with the package @hapi/iron.

// /lib/auth.js

import Iron from '@hapi/iron'
import { MAX_AGE, setTokenCookie, getTokenCookie } from './auth-cookies'

const TOKEN_SECRET = process.env.TOKEN_SECRET

export async function setLoginSession(res, session) {
  const createdAt = Date.now()
  // Create a session object with a max age that we can validate later
  const obj = { ...session, createdAt, maxAge: MAX_AGE }
  const token = await Iron.seal(obj, TOKEN_SECRET, Iron.defaults)

  setTokenCookie(res, token)
}

This takes care of creating a cookie for your user which can now be used to identify and therefore authenticate them on future requests until the cookie expires or the user logs out.

If a user goes through the process of logging in they'll be redirected to the homepage. This is due to a special hook called useUser within your login page.

// /pages/login.js

const Login = () => {
  useUser({ redirectTo: '/', redirectIfFound: true })

  // ...
}

useUser makes a request to the /api/user endpoint. In this endpoint, it takes care of getting the session from the request that was made and finding a user based off of it and finally returning that user.

// /api/user.js

import { getLoginSession } from '../../lib/auth'
import { findUser } from '../../lib/user'

export default async function user(req, res) {
  try {
    const session = await getLoginSession(req)
    const user = (session && (await findUser(session))) ?? null

    res.status(200).json({ user })
  } catch (error) {
    console.error(error)
    res.status(500).end('Authentication token is invalid, please log in')
  }
}

For this request, we use the package swr which allows us to make GET requests using a convenient hook called useSWR.

When the user data is sent back to the useUser hook, it redirects the user to a given route based off of the provided redirectTo property. Since this was set to forward slash, it will redirect your user to the homepage. You can change this property's value to be whatever page you want the user to visit immediately after logging in instead of staying on the login page.

How to Log Out Users with Passport

Finally, the last action Passport takes care of in this app is logging out the user. Fortunately logging them out is as simple as removing the cookie you created on login.

You log out your user and remove the cookie on the server side. You do this by making a GET request to /api/logout.

// /api/logout

import { removeTokenCookie } from '../../lib/auth-cookies'

export default async function logout(req, res) {
  removeTokenCookie(res)
  res.writeHead(302, { Location: '/' })
  res.end()
}

In it, you use a function removeTokenCookie to delete the cookie that you created when the session was made. After doing so, the user is redirected back to the homepage using a server-side redirect.

How to Get Better at Authenticating Users

The best way to get a good understanding of Passport and authentication in general is to work with it. As long as you are a developer, it will be an essential component to understand and implement.

Beyond my explanations here, be sure to run this application on your own. Play around with signing up logging in and logging out users so you can get a good understanding of what's actually going on when you authenticate them.

I hope this project serves as a good starting point for any React application you have where you want to feature authentication. If you want to extend this example beyond email and password auth, be sure to check out Passport's website for all 500+ available strategies that your users can use to sign in.

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

Getting started

This is a simple authentication tutorial for building a Twitter Authentication web application using Passport API. It’s a side project that I worked on for education purposes.

I broke down this tutorial into two parts. The first part focuses on building authentication routes in the backend. The second part focuses on building UI components in the front-end using React.

Tech Stack

• Server Side: Node.js, Express.js, Passport Twitter API, MongoDB,
• Client: ReactJS

What are we going to build?

• User clicks on login button which redirects to Twitter OAuth authentication page.
• Once the OAuth has been successfully authenticated to Twitter, the user will be redirected back to the web application home page.

Authenticate via passport-twitter

Passport.js. offers authentication APIs to other OAuth service providers such as Google and Facebook. As an example, I chose to use Twitter as an OAuth service provider.

What is OAuth?

Open Authorization is a standard for granting your web application access to a third-party sign-in service like Twitter, Facebook, or Google, which returns an OAuth token. An OAuth Token is a credential that can be used by an application to access an external service API.

In this project, I'm using passport-twitter middleware to handle Twitter authentication using the OAuth 1.0 API, because it saves time and handles all the complex authentication process behind the scene.

What are the server endpoints?

/auth/twitter — authenticate via passport twitter

/auth/login/success — returns login success response with user information

/auth/login/failed — returns login failed message

/auth/logout — log-out and redirects to client home page

/auth/twitter/redirect — redirect to home page if login succeeded or redirect to /auth/login/failed if failed

Architecture Diagram

Here is an overview of the architecture diagram which we will be going over in more detail.

Architecture Diagram

Project Structure

I separated server and client logic in different folders to be clear and clean. My server is running on localhost:4000, whereas the client is running on localhost:3000. (Feel free to define your own port.)

|-- twitter-auth-project|   |-- server|   |   |-- index.js|   |   |-- package.json|   |-- client|   |   |-- src|   |   |   |-- index.jsx|   |   |   |-- package.json

Implementation

Part 1: Register your app as an OAuth provider at Twitter Application Site

First things first, register your application at Twitter Application Management. You will be issued with a consumer key (API Key) and consumer secret (API Secret) that you can use in passport strategy later on.

You will also need to configure a callback URL. This is the callback URL after the OAuth has been authenticated successfully.

For local development purpose, I customized my callback URLs to be the client URL which is localhost:3000.

_[https://developer.twitter.com/en/apps/create](https://developer.twitter.com/en/apps/create" rel="noopener" target="blank" title=")

Part 2: Setup Express Server for Twitter Authentication

I chose Express.js to set up the server on the backend. Express.js is a web application framework for Node.js which designed to build APIs.

|-- server|   |-- config|   |   |-- keys.js|   |   |-- passport-setup.js|-- |-- models|   |   |-- user-model.js|   |-- routes|   |   |-- auth-routes.js|   |-- index.js|   |-- package.json

npm install express to install an express server. The server runs on http://localhost:4000.

index.js is the entry point for all the server endpoints.

/routes/auth-routes.js contains all the authentication endpoints.

/config/keys.js contains all the Twitter API consumer keys, and database configs. You can copy them and put your own keys.

Part 3: Setup authentication routes

Previously in the “What are the server endpoints?” section, we have identified the authentication endpoints to Twitter API.

/auth/twitter — authenticate via passport twitter

/auth/login/success — returns login success response with user information

/auth/login/failed — returns login failed message

/auth/logout — logout and redirects to client home page

/auth/twitter/redirect — redirect to home page if login succeeded or to /auth/login/failed if failed

Let’s put them into practice.

/routes/auth-routes.js

In index.js, import routes/auth-routes,

npm install cors — support cross-origin browser

Part 4: Setup Twitter strategy using Passport API

Passport API is a middleware we use to authenticate via Twitter OAuth. Passport API does the login authentication behind the scene so you do not need to handle the complex logic. It has also different authentication strategies (i.e GoogleStrategy, FacebookStrategy). In my example, I chose to use TwitterStrategy to login via a Twitter account.

Part 5: Setup and connect a database

When the system successfully authenticates the user through PassportAPI, it will need to store the user in a database so it can retrieve this user information to the client.

architecture diagram

I’m using MongoDB to store the user login information.

Part 5.1 — Sign up mlab and follow the instructions here: https://mlab.com/

Part 5.2 — Add MongoDB credentials in keys.js

Part 5.3 — Establish a MongoDB connection using mongoose

npm install mongoose to connect to MongoDB.

“Mongoose provides a straight-forward, schema-based solution to model your application data. It includes built-in typecasting, validation, and query building.” (https://mongoosejs.com/)

Part 5.4 — Create a user object model that represents the user profile in the database record

/models/user-model.js

Part 6: Save and fetch user from a database

Once the Passport API successfully authenticated via Twitter OAuth, our server saves the user information to the MongoDB. If this user already exists, the system simply finds the current user from the database and returns the user to the client. This is all done using mongoose APIs.

/config/passport-setup.js

Part 7: Use client session to store cookie session

Every time the user logins a website, the browser remembers this user information so that the user does not need to log in again. How this user gets remembered is through an HTTP cookie. An HTTP cookie contains encrypted data about the user and how long the session lasts.

If you login to any webpage, and open the DevTools, you can see the cookies have been set in the browser.

After a successful login, cookies are set in the browser. Open DevTools, go to Application | Cookies.

Serialization and deserialization are important concepts to know. Serialization is when the user gets encrypted from the database and sends it back to the browser as a cookie. Deserialization is when the user cookie gets decrypted from the browser to the database.

In order to support login sessions, Passport will serialize and deserialize user instance to and from the session.

/config/passport-setup.js

Here is the final index.js using cookie-session.

I chose to use cookie-session as a middle to store session data on the client.

$ npm install cookie-session

Also, use cookieSession in index.js

app.use(cookieSession({  name: 'session',  keys: [/* secret keys */],  maxAge: 24 * 60 * 60 * 1000 // session will expire after 24 hours}))

passport.session() acts as a middleware to alter the req object and change the encrypted user value that is currently the session sig (from the client cookie) into a user object.

Optional step:

I customized the localhost:4000/ root URL to show success message if login correctly otherwise shows a failed message.

Next Step: Client — Setup Login Page and Logout Page using React

I built the front end components using React, and React Router to set up links.

Login Page and Logout Page

Functionality

The page contains a header with home and login/logout button. Initially, the page will display the “welcome” message and “login” button. Once the user has authenticated via twitter authentication, it will display the username and “logout” button.

Client setup

client|-- src|   |-- components|   |   |-- Header.jsx|   |   |-- Homepage.jsx|   |-- App.js|   |-- AppRouter.js|   |-- index.js|   |-- index.css|   |-- serviceWorker.js|-- package.json

Identify UI components

UI components

• HomePage: a container that displays welcome and user information. Calls /auth/login/success endpoint. If the endpoint succeeded, the user information will be stored in the user object and the state of authenticated will be set true. The page shows a message that “You have login successfully”. If the endpoint failed, the user is not authenticated, and the page displays “Welcome”.
• Header: It handles navigation. When the user is authenticated, “login” will be changed to “logout”. The authenticated state is passed down from HomePage as a prop.

Implementation

HomePage.jsx: a container that displays welcome and user information

Header.jsx — navigation component

Lastly, set up Route that navigates to HomePage in the AppRouter.jsx and App.jsx

Thank you so much for reading this blog post. I hope you found it helpful.

The entire project is available on my Github: https://github.com/leannezhang/twitter-authentication

If you have any comments or feedback, please feel free to comment below or reach me.

Twitter: @ liyangz

Reading Materials

• Passport Twitter Example
• Passport Twitter
• Passport Google API Tutorial