In this series I cover:

• Part 1: Background and Backend using NodeJS
• Part 2: React & JWT Authentication
• Part 3: Single Sign-On, JWT, and NodeJS
• Part 4: Single Sign-On, JWT, and React (This post)

In part 3, we enhanced our backend's authentication logic with SSO support. In this last part, we finish our journey by adding client-side support in SSO, using React.

If you haven't read the previous parts, I strongly encourage you to do so before proceeding with this part, as it contains an important background that will help you grasp the concepts we use here.

Our strategy

As you probably already know, when using SSO, some of the flow takes place on the provider's side. Obviously, we have little to no control there. Although we can't do much about it, we still have full control over our client-side. Therefore, we must do whatever we can to provide our users with a good experience on our end. Ideally, the users shouldn't feel like they've left our application in the process. All of that might sound a little bit tricky, but worry not! We have some tricks up our sleeve 😉

To clarify things up, let's start by describing the steps we follow in this part:

1. The user visits our login or signup page, and chooses to authenticate via SSO
2. We let our backend know which authentication strategy the user chose by calling the /auth/${providerName} endpoint
3. When the backend redirects the user to the provider's login page, we open a new popup-like window, for completing the authentication process on the provider's side
4. Upon successful login, the backend redirects the user back to the UI, with a refresh token cookie. We close the popup and let our app know that we have a new refresh token
5. We call the /refresh-token endpoint to get a new access token and redirects the user to the homepage of our application

Let's code

The login component

We start by creating a tiny component that renders a button for each provider we support. To make things simple, I hold the supportedSocialLoginTypes in an array on the client-side, but you can (and should!) move that to the backend and expose it by the API, so when adding a new SSO provider, the UI will react to it automatically.

import React from 'react';
import { Box, createStyles, makeStyles, Theme } from '@material-ui/core';
import Typography from '@material-ui/core/Typography';
import Button from '@material-ui/core/Button';
import LinkedInIcon from '@material-ui/icons/LinkedIn';
import GitHubIcon from '@material-ui/icons/GitHub';
import { openCenteredPopup } from '../../services/nativePopup';

const useStyles = makeStyles((theme: Theme) =>
  createStyles({
    loginWithText: {
      marginBottom: theme.spacing(4),
    },
    socialLoginButton: {
      textTransform: 'none',
      marginTop: 10,
    },
  }),
);

const supportedSocialLoginTypes = [
  { name: 'LinkedIn', icon: LinkedInIcon },
  { name: 'Github', icon: GitHubIcon },
];

export default function LoginWithSSO() {
  const { loginWithText, socialLoginButton } = useStyles();

  const handleSocialLoginSubmit = async (provider: string) => {
    openCenteredPopup(`${SERVER_URI}/api/auth/${provider.toLowerCase()}`, `login with ${provider}`, 500, 500);
  };

  return (
    <Box mt={2} width={'100%'}>
      <Typography className={loginWithText} variant="caption" color="textSecondary" align="center">
        Or login with
      </Typography>
      {supportedSocialLoginTypes.map(({ name, icon: Icon }) => (
        <Button
          key={name}
          startIcon={<Icon />}
          className={socialLoginButton}
          variant={'outlined'}
          color={'primary'}
          onClick={() => handleSocialLoginSubmit(name)}
          fullWidth
        >
          {`Login with ${name}`}
        </Button>
      ))}
    </Box>
  );
}

Open the provider's login page in a new window

We need to redirect our user to the provider's website, but we want to give the user the feeling they haven't left our application. Since we can't use a regular popup (e.g a floating, absolute div) for redirection, we mimic this experience by opening a new small and centered window that gives the experience we aim for.

// credit to: http://www.xtf.dk/2011/08/center-new-popup-window-even-on.html

export const openCenteredPopup = (url: string, title: string, w: number, h: number) => {
  // Fixes dual-screen position                             Most browsers      Firefox
  const dualScreenLeft = window.screenLeft !== undefined ? window.screenLeft : window.screenX;
  const dualScreenTop = window.screenTop !== undefined ? window.screenTop : window.screenY;

  const width = window.innerWidth
    ? window.innerWidth
    : document.documentElement.clientWidth
    ? document.documentElement.clientWidth
    : window.screen.width;
  const height = window.innerHeight
    ? window.innerHeight
    : document.documentElement.clientHeight
    ? document.documentElement.clientHeight
    : window.screen.height;

  const systemZoom = width / window.screen.availWidth;
  const left = (width - w) / 2 / systemZoom + dualScreenLeft;
  const top = (height - h) / 2 / systemZoom + dualScreenTop;
  const newWindow = window.open(
    url,
    title,
    `
      scrollbars=no,
      toolbar=no,
      location=no,
      directories=no,
      status=no,
      menubar=no,
      resizable=no,
      copyhistory=no,
      width=${w / systemZoom}, 
      height=${h / systemZoom}, 
      top=${top}, 
      left=${left}
      `,
  );

  newWindow?.focus();
};

Redirecting back to our app

Let's start by creating a function that we will use to communicate between the two windows. The authenticateCallback will be called by the popup window right after the authentication process is completed, and right before it disappears. We declare it in the useEffect of our AuthContainer from part 2:

// AuthContainer.ts

  useEffect(() => {
    // add listener for login or logout from other tabs
    window.addEventListener('storage', async (event: WindowEventMap['storage']) => {
      if (event.key === AuthEvents.LOGOUT && isAuthenticated()) {
        await clearToken(false);
        setUser(null);
      } else if (event.key === AuthEvents.LOGIN) {
        refreshToken();
      }
    });

    // add listener for cross-window communication (SSO popup)
    window.authenticateCallback = async function () {
      await refreshToken();
      history.push('/');
    };
  }, [clearToken, history, isAuthenticated, refreshToken]);

When the user completes the authentication on the provider's UI, the provider will redirect it back to our backend. In part 3, we configured the backend to send the authenticated user (+ a refresh token) to the specific route on our frontend: /authentication/redirect. Recall that at this stage, the user is still in the popup window, therefore, the redirection occurs there!

Let's create a small component that will render when this route is accessed; its role is to pass the control back to the caller window, by closing the popup, and notifying that a new refresh token is available by calling the authenticateCallback function we attached to the window object earlier. Notice that we reference the main window using window.opener.

Remember: cookies are available on a domain basis, rather than a particular window. We can be sure that the new refresh token is sent with each new call we make, across all open windows that share the same domain, including our caller window.

// SocialAuthCallback.tsx

import React, { useEffect } from 'react';

export const SocialAuthCallback = () => {
  useEffect(() => {
    setTimeout(() => {
      window.opener.authenticateCallback();
      window.close();
    }, 1000);
  });

  return <div>Authenticated successfully! you are being redirected...</div>;
};

     <Route path="/authentication/redirect" exact component={SocialAuthCallback} />
      // .... rest of applications routes here

Yes! we are done! At this point, the main window fetches a new access token for the user and redirects them back to the homepage. Easy right?

Closing words

That's all for this series. We have covered a lot! If you follow the steps in the series, you should have a working JWT-based authentication in no time! That was a long and exciting journey for me. I hope you enjoyed reading it at least as much I enjoyed writing it. Please let me know what you think by leaving a comment down below.

In this series I cover:

• Part 1: Background and Backend using NodeJS
• Part 2: React & JWT Authentication
• Part 3: Single Sign-On, JWT, and NodeJS (This post)
• Part 4: Single Sign-On, JWT, and React

In this part, we will use what we've accomplished so far and turn it into a complete solution by adding support in multiple SSO strategies using NodeJS, Express, PassportJS. If you haven't read the previous parts, I strongly encourage you to do so before proceeding with this part, as it contains an important background that will help you grasp the concepts we use here.

What is a Single Sign-On Authentication?

We all use Single Sign-On authentication every day. When we subscribe to a new website for the first time, there are usually several ways to choose how to complete the registration process:

• Username & password - we provide our credentials and a new user that is associated with our email address is created for us
• ”Sign up with ...” - we use an existing account we own (Google, Facebook, Twitter, Github, Apple, etc)

Whenever we chose the second option, we are redirected to the selected provider, which asks our permission to share our data with the service we came from. This is called Single Sign-On (SSO). Using SSO, we can log into a website without entering a username and password.

I'm not going to dig into the protocol itself in this post, as there's plenty of information available online, but I do encourage you to learn it yourself. Here's a nice post explaining SSO in more depth.

Wait a minute...

"But... how can it work given that we have to rely on a third party to manage our user's authentication, and the JWT is being generated by our backend?"

Great question! This is exactly what this entire post is all about! Our strategy will be as follows:

1. Configure PassportJS strategies for each SSO provider we support
2. Let the user authenticate using their provider of choice
3. Upon successful login, update the user in the DB, generate a refresh token, attach it to a cookie and redirect the user back to the application
4. Use the refresh token to generate an access token for the user

Prerequisites

Each provider we support requires registration using a dedicated developer account. When you complete the registration process, you will get a Client ID and a Secret ID. Make sure to save them and keep them safe, we will need them later.

Follow the links below to create and configure your SSO access with the two providers we use in this post:

• Github
• LinkedIn

And now, without further ado...

Let's Code

The app configuration

Let's start by adding our providers to the backend's config. I'm using convict to manage the configuration, but you can replace it with whatever you are comfortable with. convict pulls the sensitive data (e.g Client ID, Secret ID) from the application's .env file.

// src/config/config.ts

import convict from 'convict';

export default convict({
  env: {
    default: 'dev',
    env: 'NODE_ENV',
  },
  http: {
    port: {
      doc: 'The port to listen on',
      default: 3001,
      env: 'PORT',
    },
    host: {
      default: 'http://localhost',
      env: 'HOST',
    },
  },
  authentication: {
    linkedin: {
      clientID: {
        doc: 'The Client ID from Google to use for authentication',
        default: '',
        env: 'LINKEDIN_CLIENT_ID',
      },
      clientSecret: {
        doc: 'The Client Secret from Google to use for authentication',
        default: '',
        env: 'LINKEDIN_SECRET',
      },
      scope: {
        default: ['r_emailaddress', 'r_liteprofile'],
      },
    },
    github: {
      clientID: {
        doc: 'The Client ID from Github to use for authentication',
        default: '',
        env: 'GITHUB_CLIENT_ID',
      },
      clientSecret: {
        doc: 'The Client Secret from Github to use for authentication',
        default: '',
        env: 'GITHUB_SECRET',
      },
      scope: {
        default: [],
      },
    },
    token: {
      secret: {
        doc: 'The signing key for the JWT',
        default: 'mySuperSecretKey',
        env: 'JWT_SECRET',
      },
      issuer: {
        doc: 'The issuer for the JWT',
        default: '',
      },
      audience: {
        doc: 'The audience for the JWT',
        default: '',
      },
      expiresIn: {
        doc: 'expressed in seconds or a string describing a time span zeit/ms.',
        default: '24h',
        env: 'JWT_EXPIRES_IN',
      },
    },
    refreshToken: {
      expiresIn: {
        doc: 'expressed in seconds or a string describing a time span zeit/ms.',
        default: '24h',
        env: 'REFRESH_JWT_EXPIRES_IN',
      },
    },
  },
}).validate();

Authentication logic using PassportJS

As you already know, we use PassportJS to declare the authentication strategies of our application. In part 1, we created our first passport strategy - the JWT strategy.

PassportJS supports multiple authentication strategies out of the box. Let's add two new strategies for Github and Linkedin using passport-github2and passport-linkedin-oauth2 respectively.

// src/auth/providers/github.ts

import { Strategy as GithubStrategy } from 'passport-github2';
import { getConfigByProviderName, processUserFromSSO } from '../index';
import passport from 'passport';
import { VerifiedCallback } from 'passport-jwt';
import { Request } from 'express';

const providerName = 'github';
const passportConfig = getConfigByProviderName(providerName);

if (passportConfig.clientID) {
  passport.use(
    new GithubStrategy(
      { ...passportConfig, passReqToCallback: true },
      (req: Request, accessToken: string, refreshToken: string, profile: any, verified: VerifiedCallback) => {
        processUserFromSSO(req, profile, providerName, verified);
      },
    ),
  );
}

// src/auth/providers/linkedin.ts

import { Strategy as LinkedInStrategy } from 'passport-linkedin-oauth2';
import { getConfigByProviderName, processUserFromSSO } from '../index';
import passport from 'passport';
import { VerifiedCallback } from 'passport-jwt';
import { Request } from 'express';

const providerName = 'linkedin';
const passportConfig = getConfigByProviderName(providerName);

if (passportConfig.clientID) {
  passport.use(
    new LinkedInStrategy(
      { ...passportConfig, passReqToCallback: true },
      (req: Request, accessToken: string, refreshToken: string, profile: any, verified: VerifiedCallback) => {
        processUserFromSSO(req, profile, providerName, verified);
      },
    ),
  );
}

You probably noticed that we use the processUserFromSSO function in both providers. After a successful login, the SSO provider exposes an accessToken, a refreshToken, and a limited profile of the logged-in user. We are not interested in the first two, as we manage the access and refresh tokens ourselves. However, we still need the information from the profile, to identify the user in our system. Once we have that, we can pull the corresponding user object from our database and attach it to the request. If we don't have a match in our DB, it means that this is the user's first time logging in to our system, so we create one for them.

Note: To simplify things, I chose to create a new user object in the DB for each provider, by searching for the user by the origin and the originId. Ideally, to provide a better user experience, we would create one user object to identify an individual across all providers (if the email matches).

Let's rearrange our code from the previous parts, and create the processUserFromSSO function along with more useful utils.

// src/auth/index.ts

import { User, UserModel } from '../models/user';
import fs from 'fs';
import { removeExtensionFromFile } from '../middleware/utils';
import { VerifiedCallback } from 'passport-jwt';
import config from '../config/config';
import passport from 'passport';
import { Request } from 'express';
import { join } from 'path';

export const init = () => {
  const providersPath = join(__dirname, 'providers');
  fs.readdirSync(providersPath).forEach((file) => {
    const authFile = removeExtensionFromFile(file);
    import(join(providersPath, authFile));
  });
};

export const requireAuth = passport.authenticate('jwt', {
  userProperty: 'currentUser',
  session: false,
});

export const getConfigByProviderName = (providerName: string) => {
  return {
    clientID: config.get(`authentication.${providerName}.clientID`),
    clientSecret: config.get(`authentication.${providerName}.clientSecret`),
    scope: config.get(`authentication.${providerName}.scope`),
    callbackURL: getAuthCallbackUrl(providerName),
  };
};

export const processUserFromSSO = (req: Request, profile: any, origin: string, done: VerifiedCallback) => {
  const {
    emails,
    name: { givenName, familyName },
    id,
  } = profile;

  UserModel.findOneAndUpdate(
    { origin, originId: id },
    {
      email: emails?.[0]?.value,
      firstName: givenName,
      lastName: familyName,
      origin,
      originId: id,
    },
    { upsert: true },
    (err, user) => {
      if (err) {
        return done(err);
      }
      req.currentUser = user as User;
      return done(null, user);
    },
  );
};

const getAuthCallbackUrl = (providerName: string) => {
  return `${config.get('http.host')}:${config.get('http.port')}/api/auth/${providerName}/callback`;
};

Express routes for SSO authentication

To wrap things up, we loop through the providers we configured and add two routes for each one of them:

• /auth/${providerName} - initiates the authentication process. The UI calls this API to let the backend know that the user chose to authenticate using SSO. The backend will reach the relevant provider to initiate the process and will redirect the user to the provider's login page
• /auth/${providerName}/callback - the provider uses this route to redirect the user back to the application once the authentication process is completed. At this point, the user is authenticated, and we need to attach the access token. Since we can't redirect the user with a token in a secured way, we attach the refresh token to a cookie that will be used by the UI to fetch the access token

// src/routes/auth.ts

import express, { Request, Response } from 'express';
const router = express.Router();
import passport from 'passport';
import config from '../config/config';
import { generateRefreshToken } from '../utils/token-util';

// local-jwt login
// .. rest of the routes from part 1 are here

// social-jwt login
export const generateUserTokenAndRedirect = async (req: Request, res: Response) => {
  const successRedirect = `${process.env.FRONTEND_URL}/authentication/redirect`;
  const { token } = generateRefreshToken(req.currentUser?._id.toString());
  res.cookie('refresh_token', token, { httpOnly: true });
  res.redirect(successRedirect);
};

// loop over the available authentication providers and add a route for them
Object.keys(config.get('authentication') || {}).forEach((providerName) => {
  const failureRedirect = `${process.env.FRONTEND_URL}"`;
  const providerAuthMiddleware = passport.authenticate(providerName, {
    session: false,
    userProperty: 'currentUser',
    failureRedirect,
  });
  router.get(`/auth/${providerName}`, providerAuthMiddleware);
  router.get(`/auth/${providerName}/callback`, providerAuthMiddleware, generateUserTokenAndRedirect);
});

export default router;

That's all for this part. In the next part, we'll complete our journey by adding client-side support in SSO using the infrastructure we created so far. I hope you find this post helpful, let me know what you think!

In this series I cover:

• Part 1: Background and Backend using NodeJS
• Part 2: React & JWT Authentication (This post)
• Part 3: Single Sign-On, JWT, and NodeJS
• Part 4: Single Sign-On, JWT, and React

In this part, we focus on the client-side. If you haven't read Part 1, I strongly encourage you to do so before proceeding with this part, as it contains an important background that will help you grasp the concepts we use here.

What we want to achieve

• A secured mechanism - we follow the rules described in the first part: access token is not stored in the local storage; utilize refresh tokens instead
• User (and developer) friendly - automatic login & logout, multi-tabs support, automatic token refresh
• State management - our app should know whether a user is authenticated

Let's start!

State Management: unstated-next

I really like Context API. It's a simple, integral part of React, and it works great for my use-cases. unstated-next is a tiny wrapper on top, that makes the use of Context API and hooks even better. You can, of course, use whatever state management solution you like (Redux 🙄, Mobx, etc). The concept remains the same.

HTTP Client: axios, axios-hooks

Axios is a really popular, open-source HTTP client for node and the browser. Axios has built-in support for request interceptors, which come handy when passing authorization headers. Since we use React hooks, we will add hooks support by integrating axios-hooks. If you don't like Axios, there are other great options out there (e.g SWR).

The useTokenExpiration hook

Let's start at the end. Since we use refresh tokens, we benefit from an increase in the level of the app's security by generating short-living access tokens. If access tokens expire often, we should refresh them to keep the users logged in. To achieve that, we set a timeout for each new access token we receive, and call the /refresh-token endpoint to receive a new one when it expires.

The useTokenExpiration gets the current token's expiration time, counts down until it expires, and lets the app know that a refresh is required, by calling the onTokenRefreshRequired callback.

// useTokenExpiration.ts

import { useEffect, useRef, useState } from 'react';

export function useTokenExpiration(onTokenRefreshRequired: Function) {
  const clearAutomaticRefresh = useRef<number>();
  const [tokenExpiration, setTokenExpiration] = useState<Date>();

  useEffect(() => {
    // get a new access token with the refresh token when it expires
    if (tokenExpiration instanceof Date && !isNaN(tokenExpiration.valueOf())) {
      const now = new Date();
      const triggerAfterMs = tokenExpiration.getTime() - now.getTime();

      clearAutomaticRefresh.current = window.setTimeout(async () => {
        onTokenRefreshRequired();
      }, triggerAfterMs);
    }

    return () => {
      window.clearTimeout(clearAutomaticRefresh.current);
    };
  }, [onTokenRefreshRequired, tokenExpiration]);

  const clearAutomaticTokenRefresh = () => {
    window.clearTimeout(clearAutomaticRefresh.current);
    setTokenExpiration(undefined);
  };

  return {
    clearAutomaticTokenRefresh,
    setTokenExpiration,
  };
}

The useToken hook

This is the heart of the authentication mechanism. It is responsible for the entire token management and lifecycle.

The token lifecycle

The useToken hook holds the access token in-memory (we explained why it's important, remember?). Therefore we store the access token in a useRef hook - more on that soon. The hook is also responsible for managing the entire token lifecycle: initialization, removal, expiration, and refresh. The token expiration is handled by using the useTokenExpiration hook we created.

A word about clearing the token - since the refresh token is saved in an httpOnly cookie, we can't access it or modify it from the browser using Javascript. This raises a problem: we can't really complete the action on the client-side alone as the browser will keep sending the refresh token cookie and a new access token will be received on every refresh. To solve that, we call the /logout endpoint, which returns a new empty cookie, and in practice, deletes the refresh token from the browser.

Let's create the lifecycle methods:

// useToken.ts

// .... 

export function useToken(onTokenInvalid: Function, onRefreshRequired: Function) {
 const accessToken = useRef<string>();
  const { clearAutomaticTokenRefresh, setTokenExpiration } = useTokenExpiration(onRefreshRequired);

  const setToken = useCallback(
    ({ token_expiration, access_token }: TokenResponse) => {
      accessToken.current = access_token;
      const expirationDate = new Date(token_expiration);
      setTokenExpiration(expirationDate);
    },
    [setTokenExpiration],
  );

  const isAuthenticated = useCallback(() => {
    return !!accessToken.current;
  }, []);

  const clearToken = useCallback(
    (shouldClearCookie = true) => {
      // if we came from a different tab, we should not clear the cookie again
      const clearRefreshTokenCookie = shouldClearCookie ? axios.get('logout') : Promise.resolve();

      // clear refresh token
      return clearRefreshTokenCookie.finally(() => {
        // clear token
        accessToken.current = '';

        // clear auto refresh interval
        clearAutomaticTokenRefresh();
      });
    },
    [clearAutomaticTokenRefresh],
  );

  return {
    clearToken,
    setToken,
    isAuthenticated,
  };
}

Initiating Axios and setting interceptors

Once we have the token, we want to pass it to all of the requests automatically. For that we use interceptors. Interceptors are pieces of code that run before and after we fire a request and allow us to intervene in the process. Since we should do the initiating process just once on the application startup, we store the access token in a useRef hook. By doing that, the useEffect containing the definitions of our interceptors will not redefine them over and over again when the access token changes.

The first interceptor attaches the access token to the authorization header before we send it to the backend. The second interceptor handles the 401 response from the backend by clearing the token's data and notifying the app that the current user isn't logged in anymore.

// useToken.ts

export const axios = Axios.create({
  baseURL: BASE_URL,
});

export function useToken(onTokenInvalid: Function, onRefreshRequired: Function) {
// .....

    useEffect(() => {
    // add authorization token to each request
    axios.interceptors.request.use(
      (config: AxiosRequestConfig): AxiosRequestConfig => {
        config.headers.authorization = `Bearer ${accessToken.current}`;
        return config;
      },
    );

    // if the current token is expired or invalid, logout the user
    axios.interceptors.response.use(
      (response) => response,
      (error) => {
        if (error.response.status === 401 && accessToken.current) {
          clearToken();

          // let the app know that the current token was cleared
          onTokenInvalid();
        }
        return Promise.reject(error);
      },
    );

    // configure axios-hooks to use this instance of axios
    configure({ axios });
  }, [clearToken, onTokenInvalid]);

And finally, the entire hook:

// useToken.ts

import Axios, { AxiosRequestConfig } from 'axios';
import { useCallback, useEffect, useRef } from 'react';
import { configure } from 'axios-hooks';
import { BASE_URL } from '../config/config';
import { User } from '../Containers/AuthContainer';
import { useTokenExpiration } from './useTokenExpiration';

interface TokenResponse {
  access_token: string;
  token_expiration: string;
}

export interface UserAndTokenResponse extends TokenResponse {
  user: User;
}

export const axios = Axios.create({
  baseURL: BASE_URL,
});

export function useToken(onTokenInvalid: Function, onRefreshRequired: Function) {
  const accessToken = useRef<string>();
  const { clearAutomaticTokenRefresh, setTokenExpiration } = useTokenExpiration(onRefreshRequired);

  const setToken = useCallback(
    ({ token_expiration, access_token }: TokenResponse) => {
      accessToken.current = access_token;
      const expirationDate = new Date(token_expiration);
      setTokenExpiration(expirationDate);
    },
    [setTokenExpiration],
  );

  const isAuthenticated = useCallback(() => {
    return !!accessToken.current;
  }, []);

  const clearToken = useCallback(
    (shouldClearCookie = true) => {
      // if we came from a different tab, we should not clear the cookie again
      const clearRefreshTokenCookie = shouldClearCookie ? axios.get('logout') : Promise.resolve();

      // clear refresh token
      return clearRefreshTokenCookie.finally(() => {
        // clear token
        accessToken.current = '';

        // clear auto refresh interval
        clearAutomaticTokenRefresh();
      });
    },
    [clearAutomaticTokenRefresh],
  );

  useEffect(() => {
    // add authorization token to each request
    axios.interceptors.request.use(
      (config: AxiosRequestConfig): AxiosRequestConfig => {
        config.headers.authorization = `Bearer ${accessToken.current}`;
        return config;
      },
    );

    // if the current token is expired or invalid, logout the user
    axios.interceptors.response.use(
      (response) => response,
      (error) => {
        if (error.response.status === 401 && accessToken.current) {
          clearToken();

          // let the app know that the current token was cleared
          onTokenInvalid();
        }
        return Promise.reject(error);
      },
    );

    // configure axios-hooks to use this instance of axios
    configure({ axios });
  }, [clearToken, onTokenInvalid]);

  return {
    clearToken,
    setToken,
    isAuthenticated,
  };
}

The Authentication Container

The Authentication Container holds the logged-in user state, and exposes the user authentication lifecycle methods: register, login, logout, and refresh token. The container is also responsible for cross-tabs login and logout support.

Initialization

The access token is saved in memory and therefore isn't available in the initialization phase of the app, however, the refresh token that is saved in an httpOnly cookie is available. When our app starts up, we try to fetch a new access token using the /refresh-token endpoint and we attempt to initialize our app with it. If the request is successful, we update the state with the received access token and the user object. In case the refresh token is not available or expired, the user will have to login again. Let's create the container, and the useEffect hook that is responsible for the initialization.

// AuthContainer.ts

//...

function useAuth() {
  const history = useHistory();
  const [user, setUser] = useState<User | null>(null);
  const refreshToken = useCallback(refresh, []);

  const onTokenInvalid = useCallback(() => setUser(null), []);
  const { setToken, clearToken, isAuthenticated } = useToken(onTokenInvalid, refreshToken);

  useEffect(() => {
    // try to get new token on first render using refresh token
    refreshToken();
  }, [refreshToken]);

  async function refresh() {
    const {
      data: { user, ...rest },
    } = await axios.get<UserAndTokenResponse>('refresh-token');

    setUser(user);
    setToken(rest);
  }

//.....

The user lifecycle methods

The lifecycle methods have several roles:

• Update the user state on different lifecycle events: login, logout, register, refresh token
• Set a new token data when user registers or logs in
• Clear token data when the user logs out
• Notify the other open applications tabs on login and logout events

// AuthContainer.ts

//...


const logout = useCallback(() => {
    clearToken().finally(() => {
      setUser(null);
      history.push('/');

      // fire an event to logout from all tabs
      window.localStorage.setItem(AuthEvents.LOGOUT, new Date().toISOString());
    });
  }, [history, clearToken]);

  const register = useCallback(
    async (userToRegister: UserBase) => {
      const {
        data: { user, ...rest },
      } = await axios.post<UserAndTokenResponse>('register', userToRegister);
      setUser(user);
      setToken(rest);
    },
    [setToken],
  );

  const login = useCallback(
    async (email: string, password: string) => {
      const {
        data: { user, ...rest },
      } = await axios.post<UserAndTokenResponse>('login', {
        email,
        password,
      });
      setUser(user);
      setToken(rest);

      // fire an event to let all tabs know they should login
      window.localStorage.setItem(AuthEvents.LOGIN, new Date().toISOString());
    },
    [setToken],
  );

  async function refresh() {
    const {
      data: { user, ...rest },
    } = await axios.get<UserAndTokenResponse>('refresh-token');

    setUser(user);
    setToken(rest);
  }
//...

Multiple tabs support for login and logout

If the user has multiple tabs open, when they log in or out, we should notify the other tabs that the status has changed. For that, we use storage events. When we set a new variable on the local storage, an event is fired across all tabs, not including the tab that initiated the change. This is exactly what we are looking for!

Let's first add the listener that listens to storage events fired by other tabs:

  useEffect(() => {
    // add listener for login or logout from other tabs
    window.addEventListener('storage', async (event: WindowEventMap['storage']) => {
      if (event.key === AuthEvents.LOGOUT && isAuthenticated()) {
        await clearToken(false);
        setUser(null);
      } else if (event.key === AuthEvents.LOGIN) {
        refreshToken();
      }
    });
  }, [clearToken, isAuthenticated, refreshToken]);

Let's combine everything together:

// AuthContainer.ts

import { useCallback, useEffect, useState } from 'react';
import { createContainer } from 'unstated-next';
import { useHistory } from 'react-router';
import { axios, UserAndTokenResponse, useToken } from '../Hooks/useToken';
import { AuthEvents } from '../services/AuthEvents';

export interface UserBase {
  name: string;
  email: string;
  password: string;
}

export interface User extends UserBase {
  _id: string;
  role: 'user' | 'admin';
}

function useAuth() {
  const history = useHistory();
  const [user, setUser] = useState<User | null>(null);
  const refreshToken = useCallback(refresh, []);

  const onTokenInvalid = () => setUser(null);
  const { setToken, clearToken, isAuthenticated } = useToken(onTokenInvalid, refreshToken);

  useEffect(() => {
    // try to get new token on first render using refresh token
    refreshToken();
  }, [refreshToken]);

  useEffect(() => {
    // add listener for login or logout from other tabs
    window.addEventListener('storage', async (event: WindowEventMap['storage']) => {
      if (event.key === AuthEvents.LOGOUT && isAuthenticated()) {
        await clearToken(false);
        setUser(null);
      } else if (event.key === AuthEvents.LOGIN) {
        refreshToken();
      }
    });
  }, [clearToken, isAuthenticated, refreshToken]);

  const logout = useCallback(() => {
    clearToken().finally(() => {
      setUser(null);
      history.push('/');

      // fire an event to logout from all tabs
      window.localStorage.setItem(AuthEvents.LOGOUT, new Date().toISOString());
    });
  }, [history, clearToken]);

  const register = useCallback(
    async (userToRegister: UserBase) => {
      const {
        data: { user, ...rest },
      } = await axios.post<UserAndTokenResponse>('register', userToRegister);
      setUser(user);
      setToken(rest);
    },
    [setToken],
  );

  const login = useCallback(
    async (email: string, password: string) => {
      const {
        data: { user, ...rest },
      } = await axios.post<UserAndTokenResponse>('login', {
        email,
        password,
      });
      setUser(user);
      setToken(rest);

      // fire an event to let all tabs know they should login
      window.localStorage.setItem(AuthEvents.LOGIN, new Date().toISOString());
    },
    [setToken],
  );

  async function refresh() {
    const {
      data: { user, ...rest },
    } = await axios.get<UserAndTokenResponse>('refresh-token');

    setUser(user);
    setToken(rest);
  }

  return {
    user,
    setUser,
    register,
    login,
    logout,
    refreshToken,
  };
}

export const AuthContainer = createContainer(useAuth);

That's it! Now we just need to wrap everything with the AuthContainer to make the authentication state available in the entire app.

// App.tsx

export default () => {
  return (
    <ThemeProvider theme={theme}>
        <Router>
          <AuthContainer.Provider>
            <App />
          </AuthContainer.Provider>
        </Router>
    </ThemeProvider>
  );
};

And now we can use our new and shiny AuthContainer to protect the application routes

import React, { ComponentType } from 'react';
import { BrowserRouter as Router, Redirect, Route } from 'react-router-dom';

interface ProtectedRouteProps { 
  component: ComponentType<any>;
  path: string
}

const ProtectedRoute: FC<ProtectedRouteProps> = ({ component: Component, path = '' }) => {
  const { user } = AuthContainer.useContainer();

  return (
    <Route
      path={path}
      render={(props) =>
        user ? (
          <Component {...props} />
        ) : (
          <Redirect
            to={{
              pathname: '/login',
              state: { from: props.location },
            }}
          />
        )
      }
    />
  );
};

That's all for this part. In the next part, we'll integrate multiple social logins that work seamlessly using the infrastructure we created so far. I hope you find this post helpful, let me know what you think!

In this series I will cover:

• Part 1: Background and Backend using NodeJS (This post)
• Part 2: React & JWT Authentication
• Part 3: Single Sign-On, JWT, and NodeJS
• Part 4: Single Sign-On, JWT, and React

What and Why

JWT, or in its full name JSON Web Token, is an open standard defined by RFC7519 for safe and compact communication between parties. The authentication (and sometimes authorization) data is transmitted in a form of a JSON object. The payload inside JWT is digitally signed using a secret or a public/private key pair and therefore can be verified and trusted.

The JWT standard became so popular mainly due to its simplicity. JWTs are compact, stateless (and therefore are a perfect match for microservice architecture), easy to generate, and process. JWT also works great with all programming languages and can be used across different environments and systems. If this is your first time reading about JWT, I strongly encourage you to learn the basics before proceeding with this post. Here is a great starting point.

Stateless or Stateful?

There are two approaches for users' authentication with tokens, Stateless, or Stateful. Both approaches make use of tokens that are being sent to the client to identify the user in future interactions. However, the main difference is how and where the users' authentication data is stored after a successful login.

Stateful Authentication

The backend generates a random token that represents a session of a user in the system and stores that information in the DB or the memory. When a user accesses one of the protected resources, the session is pulled out of the storage, and the verification process occurs.

Stateless Authentication

The backend generates a token that represents a user and contains the user's data as a payload. When a user accesses one of the protected resources, the token itself is verified, the users' information is extracted from the token itself, and a decision is made.

There are pros and cons to each approach. Most of the advantages of JWT we have mentioned earlier exist thanks to the stateless nature of it. However, those come with a cost that can make our system vulnerable to attacks if a token is stolen from the client.

Access Token vs Refresh Token

To solve most of the security problems that might arise from the use of JWTs, we use refresh tokens. There are many implementations and guides that explain how to create a JWT-based authentication. However, most of them don't use refresh tokens. Refresh tokens are crucial when working with JWTs, so don't skip them!

In general, access tokens are used to authenticate a user, while refresh tokens are used to generate a new access token. Users can't authenticate with a refresh token, and this is an important detail, therefore, our system needs to know how to differentiate the tokens by their types.

How do refresh tokens help us protecting our system?

After a successful login, our backend sends the access token to the client. From that point, the client will pass the token with every request. Allow me to emphasize two things we should NOT DO:

• We DO NOT store the JWT token in the local storage as it is vulnerable to XSS attacks.
• We DO NOT store our access token in a cookie (even if it is httpOnly cookie), as it is vulnerable to CSRF attacks. There's another way to handle CSRF attacks, by using SAME SITE but it depends on browser support, so I wouldn't count on it completely just yet.

So what do we do? We use refresh tokens. When a user logs in for the first time, they'll get two tokens:

• Access token in the payload of the response of the authentication request.
• A refresh token in an HTTP only cookie.

The access token won't be saved in the local storage of our client application, and here goes the XSS risk. The refresh token will be stored in a cookie and can be used to retrieve a new access token from a dedicated endpoint in future visits to our app. The new access token will be passed to the client in the payload of the request, here goes the CSRF risk. It might sound a little bit confusing at the start, so it's about time to see some code examples to clear things out!

Backend implementation

Generate and encrypt the token

Before we start to work our way towards secured API endpoints, we need to create some Utils to help us achieve our goals. Obviously, we want to be able to generate a JWT. Since a JWT is not encrypted by default, we also want to encrypt it to prevent sensitive information that is stored on the token to leak.

Let's first create our encryption-util, as we'll need to use it in our token-util as well.

import config from '../config/config';
import { createCipheriv, createDecipheriv, scryptSync } from 'crypto';
const secret = config.get('authentication.token.secret');
const algorithm = 'aes-192-cbc';

const key = scryptSync(secret, 'salt', 24);
const iv = Buffer.alloc(16, 0); // Initialization crypto vector

export function encrypt(text: string) {
  const cipher = createCipheriv(algorithm, key, iv);
  let encrypted = cipher.update(text, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

export function decrypt(text: string) {
  const decipher = createDecipheriv(algorithm, key, iv);
  let decrypted = decipher.update(text, 'hex', 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}

Now, we use our encryption-util to generate an encrypted JWT. For the JWT itself, we'll utilize the jsonwebtoken package. Let's create it.

import { decode, sign, verify } from 'jsonwebtoken';
import config from '../config/config';
import { decrypt, encrypt } from './encryption-util';

export enum TokenType {
  ACCESS_TOKEN = 'access_token',
  REFRESH_TOKEN = 'refresh_token',
}

type JWT = { exp: number; type: TokenType; sub: string };

export const generateAccessToken = (userId: string) => {
  return generateToken(userId, TokenType.ACCESS_TOKEN);
};

export const generateRefreshToken = (userId: string) => {
  return generateToken(userId, TokenType.REFRESH_TOKEN);
};

const generateToken = (userId: string, type: TokenType) => {
  const audience = config.get('authentication.token.audience');
  const issuer = config.get('authentication.token.issuer');
  const secret = config.get('authentication.token.secret');
  const expiresIn =
    type === TokenType.ACCESS_TOKEN
      ? config.get('authentication.token.expiresIn')
      : config.get('authentication.refreshToken.expiresIn');

  const token = sign({ type }, secret, {
    expiresIn,
    audience: audience,
    issuer: issuer,
    subject: userId,
  });

  return {
    token: encrypt(token),
    expiration: (decode(token) as JWT).exp * 1000,
  };
};

export const getTokenType = (token: string): TokenType => {
  return (verify(token, config.get('authentication.token.secret')) as JWT).type;
};

export const parseTokenAndGetUserId = (token: string): string => {
  const decryptedToken = decrypt(token);
  const decoded = verify(decryptedToken, config.get('authentication.token.secret')) as JWT;
  return decoded.sub || '';
};

User Authentication with PassportJS

PassportJS is modular authentication middleware for NodeJS, allowing us to use different authentication strategies. Here we create a new passport strategy using the passport-jwt package.

Our frontend uses the authorization HTTP header to provide the access token while making a new request to the backend. When a new request comes in, we need to authenticate the user by the provided token, read the user from the DB, and attach it to the request. The passport strategy contains 2 main parts, the jwtFromRequest and the verifyCallback function. The jwtFromRequest function is responsible for getting the token from the request, and then decrypting, verifying, and checking the type of the token. The verifyCallback function is responsible for getting the user from the database based on the token, and attaching it to the request for future use.

Here's the passport JWT strategy.

import { UserModel } from '../models/user';
import { Strategy as JwtStrategy, VerifiedCallback } from 'passport-jwt';
import config from '../config/config';
import passport from 'passport';
import { Request } from 'express';
import { decrypt } from '../utils/encryption-util';
import { getTokenType, TokenType } from '../utils/token-util';

passport.use(
  new JwtStrategy(
    {
      jwtFromRequest: (req: Request) => {
        try {
          if (!req.headers.authorization) {
            throw new Error('token was not provided, authorization header is empty');
          }

          const tokenFromHeader = req.headers.authorization.replace('Bearer ', '').trim();
          const decryptedToken = decrypt(tokenFromHeader);
          const tokenType = getTokenType(decryptedToken);

          if (tokenType !== TokenType.ACCESS_TOKEN) {
            throw new Error('wrong token type provided');
          }

          return decryptedToken;
        } catch (e) {
          console.error('Token is not valid', e.message);
          return null;
        }
      },
      secretOrKey: config.get('authentication.token.secret'),
      issuer: config.get('authentication.token.issuer'),
      audience: config.get('authentication.token.audience'),
      passReqToCallback: true,
    },
    (req: Request, payload: any, done: VerifiedCallback) => {
      UserModel.findById(payload.sub, (err, user) => {
        if (err) {
          return done(err, false);
        }
        req.currentUser = user?.toObject();
        return !user ? done(null, false) : done(null, user);
      });
    },
  ),
);

Once we have the strategy configured, we need to have a way to restrict our API endpoints. For that, we create a middleware. As discussed before, we work in a stateless way and therefore we set the session value as false.

export const requireAuth = passport.authenticate('jwt', {
  userProperty: 'currentUser',
  session: false,
});

We're almost done with our backend. We need to create the API endpoints, protect them, as send the access_token and the refresh_token to the user. Routes that require authentication will be protected using the requireAuth middleware we created earlier.

import express from 'express';
const router = express.Router();
import { requireAuth } from '../auth';
import config from '../config/config';
import { generateAccessToken, generateRefreshToken } from '../utils/token-util';

const generateTokensAndAuthenticateUser = async (res, userId) => {
  const user = await findUserById(userId);
  const { token: access_token, expiration: token_expiration } = await generateAccessToken(userId);
  const { token: refreshToken } = generateRefreshToken(userId);
  res.cookie('refresh_token', refreshToken, { httpOnly: true });
  res.status(200).json({ access_token, token_expiration, user });
};

router.post('/register', () => {
  try {
    const { email } = req.body;
    const doesEmailExist = await fieldExists('email', email);

    if (!doesEmailExist) {
      const user = await registerUser(req.body);
      generateTokensAndAuthenticateUser(res, user._id);
    }
  } catch (error) {
    handleError(res, error);
  }
});

router.get('/refresh-token', () => {
  try {
    const tokenEncrypted = req.cookies.refresh_token;
    const userId = await parseTokenAndGetUserId(tokenEncrypted);
    generateTokensAndAuthenticateUser(res, userId);
  } catch (error) {
    handleError(res, error);
  }
});

router.get('/logout', requireAuth, () => {
  res.cookie('refresh_token', '', { httpOnly: true });
  res.status(200).end();
});

router.post('/login', async () => {
  try {
    const { email, passport } = req.body;
    const user = await findUser(data.email);
    await checkPassword(password, user);
    generateTokensAndAuthenticateUser(res, user._id);
  } catch (error) {
    handleError(res, error);
  }
});

That's all for now. The full code will be published soon! In the next part, we'll create a React-based web app and use the backend we just created. I hope you find this post helpful, let me know what you think!