Two-Factor Auth

This module provides 2FA functionality for enhanced security. It allows users to enable or disable 2FA, generate a QR code for setup in authentication apps, and validate a 2FA code during login.

Setup:

• Step 1: User installs an authentication app on his prefered device.

• Step 2: OTP link is generated on a server side.

• Step 3: User scans generated on UI QR Code (via app) or follows a link to an authenticator app.

• Step 4: User enters code generated by authenticator app and submits its 2FA setup request.

2FA Setup Component

Usage:

• Step 1: User logs in with their credentials (username/password).

• Step 2: After successful login, the user is prompted to enter a time-based one-time password (TOTP) generated by an authentication app (e.g., Google Authenticator, Authy).

• Step 3: The TOTP is verified on the server, and access is granted if both the password and the 2FA code are correct.

2FA Verification component

Implementation

Intercode Common uses separate UI components and a NestJS module in 2FA implementation

Libraries and enviroment setup

First of all we need to install libraries needed to implement 2FA functionality

yarn add otplib
yarn add qrcode

Then we need to set up our 2FA App name on a API side

Add this variables to the following files

.env

TWO_FACTOR_AUTH_APP_NAME=YourAppName

constants.ts

TWO_FACTOR_AUTH_APP_NAME: process.env.TWO_FACTOR_AUTH_APP_NAME

API

TwoFactorAuthController

The TwoFactorAuthController handles 2FA-related HTTP requests. This controller is secured with JWT-based authentication and uses the following endpoints:

• GET /2fa/generate-qr Generates a QR code and provides an OTP URI link for the user to set up 2FA in an authentication app. Requires DemoGuard.

• POST /2fa/enable-two-factor-auth Enables 2FA for the user by verifying the provided OTP code. If the code is valid, 2FA is enabled. Requires DemoGuard.

• POST /2fa/disable-two-factor-auth Disables 2FA for the user.

• POST /2fa/authenticate Authenticates the user using their OTP code from an authentication app. If successful, it returns a signed-in token.

Guards Used:

• JwtAuthenticationGuard: Ensures that requests come from authenticated users.

• DemoGuard: Additional security check applied to 2FA endpoints.

two-factor-auth.controller.ts

import { Body, Controller, Post, UseGuards, ValidationPipe, HttpException, HttpStatus, Get } from '@nestjs/common';
import { TwoFactorAuthService } from '../service/two-factor-auth.service';
import { TwoFactorAuthCodeDto } from '../dto/two-factor-auth-code.dto';
import { JwtUserPayload } from 'src/common/interfaces/jwt-user-payload.interface';
import { GetUser } from '../decorator/get-user.decorator';
import { JwtAuthenticationGuard } from 'src/common/guards/jwt-authentication.guard';
import { AdminGuard } from 'src/common/guards/admin.guard';
import { TwoFactorImpersonationDto } from '../dto/two-factor-impersonation.dto';
import { JwtTwoFactorGuard } from 'src/common/guards/jwt-two-factor.guard';
import { DemoGuard } from '../../common/guards/demo.guard';

@Controller('2fa')
@UseGuards(JwtAuthenticationGuard)
export class TwoFactorAuthController {
    constructor(private readonly twoFactorAuthService: TwoFactorAuthService) {}

    @UseGuards(DemoGuard)
    @Get('generate-qr')
    async generateQrCode(@GetUser() user: JwtUserPayload) {
        const { otpAuthUrl } = await this.twoFactorAuthService.generateTwoFactorAuthSecret(user);
        return { qrCode: await this.twoFactorAuthService.generateQrCode(otpAuthUrl), link: otpAuthUrl };
    }

    @UseGuards(DemoGuard)
    @Post('enable-two-factor-auth')
    async enableOfTwoFactorAuth(
        @GetUser() user: JwtUserPayload,
        @Body(ValidationPipe) twoFactorAuthCodeDto: TwoFactorAuthCodeDto
    ) {
        const isCodeValid = await this.twoFactorAuthService.verifyTwoFactorAuthCode(twoFactorAuthCodeDto.code, user);
        if (!isCodeValid) {
            throw new HttpException(
                {
                    message: 'Code is not valid!',
                    description: 'An incorrect code or code time has expired. Please try again.',
                },
                HttpStatus.BAD_REQUEST
            );
        }
        await this.twoFactorAuthService.activationOfTwoFactorAuth(user, true);
    }

    @UseGuards(DemoGuard)
    @Post('disable-two-factor-auth')
    async disableOfTwoFactorAuth(@GetUser() user: JwtUserPayload) {
        await this.twoFactorAuthService.activationOfTwoFactorAuth(user, false);
    }

    @Post('authenticate')
    async authenticate(
        @GetUser() user: JwtUserPayload,
        @Body(ValidationPipe) twoFactorAuthCodeDto: TwoFactorAuthCodeDto
    ) {
        const isCodeValid = await this.twoFactorAuthService.verifyTwoFactorAuthCode(twoFactorAuthCodeDto.code, user);
        if (!isCodeValid) {
            throw new HttpException(
                {
                    message: 'Code is not valid!',
                    description: 'An incorrect code or code time has expired. Please try again.',
                    code: 'INVALID_TWO_FACTOR_AUTH_CODE',
                },
                HttpStatus.BAD_REQUEST
            );
        }
        return await this.twoFactorAuthService.signIn(user, true);
    }
}

TwoFactorAuthService

The TwoFactorAuthService is responsible for 2FA logic, including generating secrets, creating QR codes, verifying OTP codes, and handling token generation. Key methods include:

• generateTwoFactorAuthSecret(user: JwtUserPayload) Creates a 2FA secret for the user and stores it in the database. Returns the secret and an OTP URI link if the QR code hasn’t already been generated.

• generateQrCode(otpPathUrl: string) Converts the OTP URI to a QR code (as a data URL) that the user can scan in their authentication app.

• activationOfTwoFactorAuth(user: JwtUserPayload, status: boolean) Activates or deactivates 2FA for the user, based on the status parameter.

• verifyTwoFactorAuthCode(code: string, user: JwtUserPayload) Verifies the provided OTP code against the user’s saved 2FA secret.

• signIn(user: JwtUserPayload, isTwoFactorAuthenticated: boolean): Promise<UserTokens> Generates an access token and refresh token, including the 2FA status, for an authenticated user.

two-factor-auth.service.ts

import { ForbiddenException, HttpException, HttpStatus, Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { authenticator } from 'otplib';
import { Repository } from 'typeorm';
import { toDataURL } from 'qrcode';
import { AuthService } from './auth.service';
import { JwtUserPayload } from 'src/common/interfaces/jwt-user-payload.interface';
import UserEntity from '../entities/user.entity';
import UserTokens from '../dto/user-tokens';
import constants from '../../constants';
import dayjs from 'dayjs';
import { Role } from 'src/common/constants/role.enum';
import { sign } from 'jsonwebtoken';
import { TokensExpiredTime } from 'src/common/constants/tokens-expired-time';

@Injectable()
export class TwoFactorAuthService {
    tokenSecret: string = constants.TOKEN_SECRET;

    constructor(
        @InjectRepository(UserEntity)
        private readonly userRepository: Repository<UserEntity>,
        private readonly authService: AuthService
    ) {}

    public async generateTwoFactorAuthSecret(user: JwtUserPayload) {
        const auth = await this.userRepository.findOne({
            where: { id: user.id },
            withDeleted: true,
        });

        if (auth) {
            if (auth.isTwoFactorEnable) {
                throw new HttpException(
                    {
                        message: 'QR code was already generated.',
                        description: 'You already have code in your Authenticator app.',
                    },
                    HttpStatus.BAD_REQUEST
                );
            }
        }

        const secret = authenticator.generateSecret();
        const appName = constants.TWO_FACTOR_AUTH_APP_NAME;
        const otpAuthUrl = authenticator.keyuri(auth.email, appName, secret);

        await this.userRepository.update({ id: auth.id }, { twoFactorAuthSecret: secret });
        return {
            secret,
            otpAuthUrl,
        };
    }

    public async generateQrCode(otpPathUrl: string) {
        return toDataURL(otpPathUrl);
    }

    public async activationOfTwoFactorAuth(user: JwtUserPayload, status: boolean) {
        try {
            return await this.userRepository.update(
                { id: user.id },
                {
                    isTwoFactorEnable: status,
                }
            );
        } catch (error) {
            throw new HttpException(
                {
                    message: 'Error occurred while updating 2FA.',
                    description: 'Please try again later.',
                },
                HttpStatus.BAD_REQUEST
            );
        }
    }

    public async verifyTwoFactorAuthCode(code: string, user: JwtUserPayload) {
        const authUser = await this.userRepository.findOne({
            where: { id: user.id },
            withDeleted: true,
        });

        if (!authUser.twoFactorAuthSecret) {
            throw new HttpException(
                {
                    message: 'Error',
                    description: 'Two factor auth is disabled on your profile',
                    code: "TWO_FACTOR_AUTH_DISABLED"
                },
                HttpStatus.BAD_REQUEST
            );
        }

        return authenticator.verify({
            token: code,
            secret: authUser.twoFactorAuthSecret,
        });
    }

    public async signIn(user: JwtUserPayload, isTwoFactorAuthenticated: boolean): Promise<UserTokens> {
        const accessToken = await this.authService.generateAccessToken({ userId: user.id, isTwoFactorAuthenticated });
        const refreshToken = await this.authService.setRefreshTokenWithExpDate(user.id);

        return {
            accessToken,
            refreshToken,
            isTwoFactorEnable: user.isTwoFactorEnable,
        };
    }
}

UI

TwoFactorAuth

TwoFactorAuth manages 2FA activation and deactivation, integrating with the backend service to display and validate OTP codes and QR codes. It also includes error handling via notifications.

• States:

  • loading: Indicates whether a request is in progress.

  • qrCode & otpLink: Store the generated QR code data and OTP URI link.

• Handlers:

  • getQrCode: Fetches a QR code for 2FA setup, which the user scans with their authentication app.

  • handleDisable: Prompts the user to confirm 2FA deactivation, using a modal for confirmation.

  • turnOffTwoFactorAuth: Deactivates 2FA for the user by calling disableTwoFactorAuth and updating the UI.

  • onFormSubmit: Submits the OTP code from the TwoFactorAuthForm to enable 2FA.

  • errorNotification: Shows error messages if any request fails, using Ant Design’s notification system.

• Display Logic:

  • 2FA Setup (when currentUser.isTwoFactorEnable is false): Presents three steps:

    1. Step 1: General instructions.

    2. Step 2: QR code generation.

       • Includes a button to generate the QR code and display it.

       • The QR code can be scanned to configure the 2FA app.

    3. Step 3: Form for OTP input.

  • 2FA Deactivation (when currentUser.isTwoFactorEnable is true): Shows a button to turn off 2FA with a power icon and loading state, triggering handleDisable.

import { useState } from 'react';
import { Divider, Button, Modal, notification, Flex } from 'antd';
import { QrcodeOutlined, PoweroffOutlined } from '@ant-design/icons';
import TwoFactorAuthForm from '../auth/TwoFactorAuthForm';
import { useAuthService } from '../../services/authService';
import { useAuth } from '../../context/AuthContext';
import { notificationType } from '../../common/constants/notificationType';
import { buttonStyle, colors, spacing } from '../../theming';
import { useTranslation } from 'react-i18next';

export default function TwoFactorAuth() {
    const [api, contextHolder] = notification.useNotification();
    const { currentUser, fetchUser } = useAuth();
    const { t } = useTranslation(['settings', 'confirmModal', 'apiResponses']);

    const { getGeneratedQr, enableTwoFactorAuth, disableTwoFactorAuth } = useAuthService();
    const [loading, setLoading] = useState(false);
    const [qrCode, setQrCode] = useState(null);
    const [otpLink, setOtpLink] = useState(null);

    // #region handlers
    function errorNotification(error) {
        api[notificationType.ERROR]({
            message: error.response?.data?.message ?? 'Error occurred while working with 2FA.',
            description: error.response?.data?.description ?? '',
            placement: 'bottomRight',
        });
    }

    async function getQrCode() {
        try {
            const { data } = await getGeneratedQr();

            if (data) {
                setQrCode(data.qrCode);
                setOtpLink(data.link);
            }
        } catch (error) {
            errorNotification(error);
        }
    }

    async function handleDisable() {
        Modal.confirm({
            title: t('confirmModal:title.disable-2fa'),
            styles: { body: { padding: spacing[4] } },
            width: 'fit-content',
            content: t('confirmModal:actions.disable-2fa'),
            centered: true,
            maskClosable: true,
            onOk: turnOffTwoFactorAuth,
            okText: t('confirmModal:buttons.yes'),
            cancelText: t('confirmModal:buttons.cancel'),
        });
    }

    async function turnOffTwoFactorAuth() {
        try {
            setLoading(true);
            const response = await disableTwoFactorAuth();

            if (response) {
                fetchUser();
            }

            setLoading(false);
        } catch (error) {
            errorNotification(error);
        } finally {
            setLoading(false);
        }
    }

    async function onFormSubmit(form) {
        try {
            setLoading(true);
            const response = await enableTwoFactorAuth(form.code);
            if (response) {
                fetchUser();
            }

            setLoading(false);
        } catch (error) {
            errorNotification(error);
        } finally {
            setLoading(false);
        }
    }
    // #endregion

    if (!currentUser.isTwoFactorEnable) {
        return (
            <Flex vertical justify="center">
                {contextHolder}
                <Divider orientation="left">{t('settings:2FA.step-1.title')}</Divider>
                <div style={{ margin: '0 50px' }}>
                    <p>{t('settings:2FA.step-1.subtitle')}</p>
                </div>
                <Divider orientation="left">{t('settings:2FA.step-2.title')}</Divider>
                <div style={{ margin: '0 50px' }}>
                    <p>{t('settings:2FA.step-2.subtitle')}</p>
                    <Button
                        type="primary"
                        icon={<QrcodeOutlined />}
                        onClick={getQrCode}
                        disabled={qrCode ? true : false}
                        style={{ ...buttonStyle.medium }}
                    >
                        {t('settings:2FA.step-2.button')}
                    </Button>
                    {qrCode && <p style={{ color: colors.colorError }}>{t('settings:2FA.step-2.help')}</p>}
                    <div style={{ margin: '10px 0' }} onClick={() => window.open(otpLink, '_blank')}>
                        {qrCode && <img src={qrCode} alt="Two-Factor Authentication QR Code" />}
                    </div>
                </div>

                <Divider orientation="left">{t('settings:2FA.step-3.title')}</Divider>
                <div style={{ margin: '0 50px' }}>
                    <p>{t('settings:2FA.step-3.subtitle')}</p>
                    <div style={{ maxWidth: 350 }}>
                        <TwoFactorAuthForm
                            loading={loading}
                            showCancel={false}
                            submitDisabled={qrCode ? false : true}
                            onFormSubmit={onFormSubmit}
                            t={t}
                        />
                    </div>
                </div>
            </Flex>
        );
    }

    if (currentUser.isTwoFactorEnable) {
        return (
            <div>
                {contextHolder}
                <Divider orientation="left">{t('settings:2FA.turn-off.title')}</Divider>
                <Button
                    type="primary"
                    icon={<PoweroffOutlined />}
                    onClick={handleDisable}
                    loading={loading}
                    danger
                    style={{ ...buttonStyle.medium }}
                >
                    {t('settings:2FA.turn-off.button')}
                </Button>
            </div>
        );
    }
}

TwoFactorAuthForm

TwoFactorAuthForm is a form component that accepts a 6-digit OTP code from the user, validating it against predefined rules before submission. It includes:

• Code Input Field: Accepts a 6-digit OTP code.

  • Validation Rules: The code must be exactly 6 digits and is required.

  • Debounced Validation: Provides feedback 1 second after the user stops typing.

• Buttons:

  • Cancel Button: Allows the user to go back or cancel the 2FA setup, visible based on showCancel prop.

  • Submit Button: Submits the form to verify and enable 2FA, with a loading indicator when loading is true.

import { Button, Form, Input, Flex } from 'antd';
import { buttonStyle } from '../../theming';

export default function TwoFactorAuthForm({ loading, showCancel, submitDisabled, onBackClick, onFormSubmit, t }) {
    return (
        <Form onFinish={onFormSubmit} layout="vertical" requiredMark={false}>
            <Form.Item
                label={t('settings:2FA.form.label')}
                name="code"
                hasFeedback
                validateDebounce={1000}
                rules={[
                    {
                        min: 6,
                        max: 6,
                        message: t('settings:2FA.form.minmax'),
                    },
                    {
                        required: true,
                        message: t('settings:2FA.form.required'),
                    },
                ]}
            >
                <Input
                    size="large"
                    placeholder={t('settings:2FA.form.placeholder')}
                    disabled={submitDisabled}
                    autoComplete="off"
                />
            </Form.Item>
            <Flex justify={showCancel ? 'space-around' : 'start'} align="center" style={{ marginTop: 30 }}>
                {showCancel && (
                    <Button
                        htmlType="button"
                        type="default"
                        size={'middle'}
                        onClick={onBackClick}
                        style={{ ...buttonStyle.medium }}
                    >
                        {t('settings:2FA.form.cancel')}
                    </Button>
                )}
                <Button
                    htmlType="submit"
                    type="primary"
                    size={'middle'}
                    loading={loading}
                    disabled={submitDisabled}
                    style={{ ...buttonStyle.medium }}
                >
                    {t('settings:2FA.form.submit')}
                </Button>
            </Flex>
        </Form>
    );
}