Forem: Tapan Rai

Learn by building: What is TOTP? Building a Simple TOTP Authentication Server with Node.js

Tapan Rai — Mon, 26 Feb 2024 18:54:26 +0000

TOTP stands for time-based one-time passcode. This code is meant to grant users one-time access to an application. TOTPs have become a staple in enhancing security through two-factor authentication (2FA).

Implementing a TOTP authentication server can significantly increase the security of your application by requiring users to provide not only something they know (their password) but also something they have (a one-time code generated by their device).

How does TOTP Work?

TOTP consists of two key components to generate the OTP codes.

A seed. This is a static secret key that is shared between the client and server.
A moving factor. This is a component that changes every time a new OTP is requested or at set periods of time. The moving factor for TOTP is Unix time.

The algorithm uses a form of symmetric key cryptography since the same key is used by both the client and the server to independently generate the OTP.

Here are the stages of TOTP authentication:

Stage 1 - Initialization

When setting up TOTP for the first time, the server generates a shared seed for each user. This key is securely transferred to the user's TOTP generator, usually by encoding it into a QR code that the user scans with a TOTP app.

Stage 2 - TOTP Generation

The TOTP generator (the user's app) takes the current time and divides it by the time step to calculate the number of time steps since a reference time (usually Unix epoch time, January 1, 1970).
It then uses an algorithm, typically HMAC-SHA-1, combining the seed and the time step count as inputs to generate a hash value.
A portion of this hash value is then extracted and converted into a 6 to 8 digit code, which is the TOTP.

Stage 3 - Authentication

The user enters the TOTP displayed by their generator app into the online service within its validity period.
Simultaneously, the server, which knows the shared secret and the current time, generates the expected TOTP using the same process.
The server then compares the TOTP entered by the user with the expected TOTP it has generated.

Stage 4 - Verification

If the TOTPs match, the authentication is successful, and the user is granted access.
If they do not match, access is denied, which could be due to entering an expired TOTP or a synchronization issue between the server and the user's device.

Now, let's build our own TOTP server

Building a simple TOTP server

Prerequisites

Basic knowledge of JavaScript and Node.js
Node.js installed on your development machine
An understanding of REST APIs and how to interact with them

Step 1: Setting Up Your Project

First, create a new directory for your project and initialize a new Node.js application by running:



mkdir totp-auth-server
cd totp-auth-server
npm init -y

Install the necessary dependencies. You'll need express for creating the server and otplib for generating and verifying TOTP tokens.



npm install express otplib qrcode

Step 2: Creating the Server

Create an index.js file in your project root. This file will be the entry point of your application. Start by setting up an Express server:



const express = require('express');
const app = express();

app.use(express.json()); // Enables express to parse JSON bodies

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server is listening on port ${PORT}`));

Step 3: Generate a TOTP Secret and QR Code

Incorporate otplib and qrcode to generate a TOTP secret for each user and a QR code for easy setup in a TOTP application like Google Authenticator or Authy.



const { authenticator } = require('otplib');
const QRCode = require('qrcode');

// Temporary in-memory storage for demonstration
let userSecrets = {};

app.post('/user/register', async (req, res) => {
  const { email } = req.body;
  if (!email) {
    return res.status(400).json({ message: 'Email is required' });
  }

  const secret = authenticator.generateSecret();
  // Store the secret using the email as a key
  userSecrets[email] = secret;

  const otpauth = authenticator.keyuri(email, 'YourServiceName', secret);

  try {
    const qrCodeUrl = await QRCode.toDataURL(otpauth);
    res.json({ email, qrCodeUrl, secret: process.env.NODE_ENV === 'development' ? secret : undefined });
  } catch (error) {
    res.status(500).json({ message: 'Error generating QR code', error });
  }
});

This endpoint generates a unique TOTP secret for a user and returns it along with a QR code image URL. The secret is what otplib uses to generate and verify tokens, while the QR code facilitates easy addition of the account to a TOTP application.

Step 4: Verifying TOTP Tokens

Create an endpoint to verify the token provided by the user. This step is crucial for logging in or performing sensitive operations within your application.



app.post('/user/verify', (req, res) => {
  const { email, token } = req.body;

  if (!email || !token) {
    return res.status(400).json({ message: 'Email and token are required' });
  }

  // Retrieve the secret using the email as a key
  const secret = userSecrets[email];

  if (!secret) {
    return res.status(404).json({ message: 'User not found' });
  }

  try {
    const isValid = authenticator.verify({ token, secret });

    if (isValid) {
      res.json({ verified: true });
    } else {
      res.status(400).json({ verified: false, message: 'Invalid token' });
    }
  } catch (error) {
    res.status(500).json({ message: 'Verification failed', error });
  }
});

You now have a basic TOTP authentication server that can generate secrets, produce QR codes for easy setup, and verify tokens.

Word of caution ⚠️

While building your own TOTP server can be an educational experience, for most businesses and applications, leveraging existing, proven solutions is advisable. These solutions offer a balance of security, reliability, and cost-effectiveness, allowing you to focus on your core product or service. If you need customization, many existing solutions offer extensive APIs and configuration options that can meet your needs without the risks and overhead of a homegrown system.

AWS CDK: Deploy a web-server to AWS Fargate with CI/CD using AWS CodePipeline and Github

Tapan Rai — Wed, 26 Jul 2023 09:45:20 +0000

We all know infrastructure as code (IAC) is important and with AWS CDK, amazon is bringing infrastructure creation and deployment in the hands of the engineers building the software.

AWS CDK is extremely accessible since it's code can be written is Typescript, Javascript, C#, Java, Go and Python.

In this article we're going to deploy a Nest.js node server on AWS Fargate with CI/CD setup on AWS CodePipeline and we'll be using AWS CDK with Typescript to do this.

If you don't want to go through the whole article, here's a link to the Github repo

Pre-requisites:

Understanding of docker
Basics of Networking
- VPC
- Subnets
Knowledge of AWS Services, namely:
- AWS CodeBuild
- AWS CodePipeline
- AWS Elastic Load Balancer
- AWS Certificate Manager
- Elastic Container Service
- CloudFormation
AWS CLI and cdk toolkit configured on your system
Your Github token with repo and webhook access; stored in AWS secrets manager
Your domain certificate added on AWS Certificate Manager

Let's Begin.

Step 1:
Containerize your app

For the demo we'll use this repo

Since Fargate is a container deployment service, we'll containize our app using docker. Here's the Dockerfile we'll be adding to the root of our project.

FROM node:18.17.0-slim

RUN npm i -g @nestjs/cli

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm run build

CMD npm run start:prod

Adding the .dockerignore here for good measure

.env*
.git
node_modules/
infra/
cdk.out/

Step 2:
Add dev dependencies, create the folder structure for your infra code and setup env.ts

Run this command in the root of your project

npm i -D aws-cdk-lib constructs

Your infra code will be part of the directory structure itself so create the following directory structure in the root of your project.

app-root
    ├── infra
          ├── stacks
                ├── cluster.ts
                ├── pipeline.ts
                ├── server.ts
          ├── env.ts
          ├── index.ts

Don't worry we'll go through each file one by one.

Lastly, setup your env.ts file

export default {
  stack: {
    id: 'aws-cdk-demo-1',
  },
  cluster: {
    vpc: {
      id: 'vpc-1',
      name: 'starter-vpc',
    },
    ecsCluster: {
      id: 'ecs-cluster-1',
    },
  },
  server: {
    securityGroup: {
      id: 'server-sg',
    },
    port: 3000,
    environmentVariables: {},
    iamRole: {
      id: 'server-role',
    },
    loadBalancer: {
      id: 'server-lb',
      certificateArn: '<CERT_ARN>',
    },
    ecr: {
      repoId: 'ecr-repo-1',
    },
  },
  pipeline: {
    id: 'pipeline-1',
    source: {
      github: {
        owner: 'AceTheNinja',
        repo: 'aws-cdk-nestjs-starter',
        tokenSecretName: '<GITHUB_TOKEN_SECRET_NAME>',
        branch: 'master',
      },
    },
    build: {
      id: 'build-1',
    },
  },
};

You can replace <GITHUB_TOKEN_SECRET_NAME> with the secret name stored in AWS Secrets Manager and <CERT_ARN> with the ARN from AWS Certificate Manager of your domain.

The server.environmentVariables can be set if your app requires any env variables to be loaded.

Step 3:
Create an ECS Cluster

Starting with stacks/cluster.ts
We'll create a new VPC for your application and deploy an ECS cluster within it.

import { Construct } from 'constructs';

import { aws_ecs as ecs, aws_ec2 as ec2, CfnOutput } from 'aws-cdk-lib';
import env from '../env';

class Cluster extends Construct {
  readonly ecsCluster: ecs.Cluster;
  readonly vpc: ec2.Vpc;

  constructor(scope: Construct, id: string) {
    super(scope, id);
    // Create a new VPC
    this.vpc = new ec2.Vpc(this, env.cluster.vpc.id, {
      vpcName: env.cluster.vpc.name,
    });

    // Creates a new ECS cluster in the VPC created above.
    this.ecsCluster = new ecs.Cluster(this, env.cluster.ecsCluster.id, {
      vpc: this.vpc,
    });

    this.output();
  }

  output() {
    // create a cloudformation output for the ARN of the ECS cluster
    new CfnOutput(this, 'ECSCluster_ARN', {
      value: this.ecsCluster.clusterArn,
    });
  }
}

export { Cluster };

Step 4:
Create the Fargate task and service

Now we'll setup our task definition and service on Fargate in the file stacks/server.ts

import { Construct } from 'constructs';
import {
  aws_ec2 as ec2,
  aws_ecs as ecs,
  aws_ecr as ecr,
  aws_certificatemanager as acm,
  aws_iam as iam,
  CfnOutput,
  Duration,
  aws_ecs_patterns as ecsPatterns,
} from 'aws-cdk-lib';

import { Cluster } from './cluster';
import { Protocol } from 'aws-cdk-lib/aws-elasticloadbalancingv2';

import env from '../env';

interface WebAppProps {
  readonly cluster: Cluster;
}

class WebApp extends Construct {
  private fargateService: ecsPatterns.ApplicationLoadBalancedFargateService;

  public readonly service: ecs.IBaseService;
  public readonly containerName: string;
  public readonly ecrRepo: ecr.Repository;
  public readonly securityGroup: ec2.SecurityGroup;

  constructor(scope: Construct, id: string, props: WebAppProps) {
    super(scope, id);

    // Creates a new security group for your fargate service
    this.securityGroup = new ec2.SecurityGroup(
      this,
      env.server.securityGroup.id,
      {
        vpc: props.cluster.vpc,
        allowAllOutbound: true,
        description: `security group for server`,
      },
    );

    // Adding inbound port to the security group 
    this.securityGroup.addIngressRule(
      ec2.Peer.anyIpv4(),
      ec2.Port.tcp(env.server.port),
      'Ingress rule for webserver',
    );

    this.fargateService = this.createService(props.cluster.ecsCluster);

    this.ecrRepo = new ecr.Repository(this, env.server.ecr.repoId);
    this.ecrRepo.grantPull(this.fargateService.taskDefinition.executionRole);
    this.service = this.fargateService.service;
    this.containerName =
      this.fargateService.taskDefinition.defaultContainer.containerName;

    this.addAutoScaling();
    this.output();
  }

  private createService(cluster: ecs.Cluster) {
    // Creates a new ECS service
    const server = new ecsPatterns.ApplicationLoadBalancedFargateService(
      this,
      'Service',
      {
        // The cluster in which to create this service
        cluster: cluster,
        // The number of tasks to run
        desiredCount: 1,
        // The image to use when running the tasks
        taskImageOptions: {
          image: ecs.ContainerImage.fromAsset('.'),
          containerPort: env.server.port,
          environment: env.server.environmentVariables,
          enableLogging: true,
          taskRole: new iam.Role(this, env.server.iamRole.id, {
            assumedBy: new iam.ServicePrincipal('ecs-tasks.amazonaws.com'),
            managedPolicies: [
              iam.ManagedPolicy.fromAwsManagedPolicyName(
                'CloudWatchFullAccess',
              ),
            ],
          }),
        },
        // The load balancer to use
        publicLoadBalancer: true,
        // The certificate to use for HTTPS
        certificate: acm.Certificate.fromCertificateArn(
          this,
          env.server.loadBalancer.id,
          env.server.loadBalancer.certificateArn,
        ),
        // The type of DNS record to use
        recordType: ecsPatterns.ApplicationLoadBalancedServiceRecordType.CNAME,
        // The security group to use
        securityGroups: [this.securityGroup],
      },
    );

    // Enable cookie stickiness on the target group for websockets
    server.targetGroup.enableCookieStickiness(Duration.days(1));

    // Configure the health check
    server.targetGroup.configureHealthCheck({
      path: '/',
      unhealthyThresholdCount: 5,
      protocol: Protocol.HTTP,
      port: env.server.port,
    });

    return server;
  }

  // Add autoscaling to the Fargate service
  private addAutoScaling() {
    const autoScalingGroup = this.fargateService.service.autoScaleTaskCount({
      minCapacity: 1,
      maxCapacity: 3,
    });
    autoScalingGroup.scaleOnCpuUtilization('CpuScaling', {
      targetUtilizationPercent: 50,
      scaleInCooldown: Duration.seconds(60),
      scaleOutCooldown: Duration.seconds(60),
    });
  }

  // Create an AWS CloudFormation output for the Amazon ECR repository name and ARN
  private output() {
    new CfnOutput(this, 'ECRRepo_ARN', { value: this.ecrRepo.repositoryArn });
    new CfnOutput(this, 'ContainerName', { value: this.containerName });
  }
}

export { WebApp, WebAppProps };

Step 5:
Setup CI/CD pipeline with Github and CodePipeline

Finally we'll setup the CI/CD pipeline. For this you'll have to add a buildspec.yml to the root of your folder so it can be utilised by CodeBuild to build an image of your server which can be deployed to Fargate.

buildspec.yml

version: '0.2'
phases:
  install:
    runtime-versions:
      nodejs: '18.x'
  pre_build:
    commands:
      - aws --version
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7)
      - IMAGE_TAG=${COMMIT_HASH:=latest}
  build:
    commands:
      - docker build -t $REPOSITORY_URI:latest .
      - docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
  post_build:
    commands:
      - aws ecr get-login-password --region ap-south-1 | docker login --username AWS --password-stdin $REPOSITORY_URI
      - docker push $REPOSITORY_URI:latest
      - docker push $REPOSITORY_URI:$IMAGE_TAG
      - printf '[{"name":"%s","imageUri":"%s"}]' $CONTAINER_NAME $REPOSITORY_URI:$IMAGE_TAG > imagedefinitions.json
artifacts:
  files:
    - imagedefinitions.json

and now onto the CI/CD pipeline code in stacks/pipeline.ts

import {
  CfnOutput,
  SecretValue,
  aws_codebuild as codebuild,
  aws_codepipeline as codepipeline,
  aws_codepipeline_actions as codepipeline_actions,
  aws_ecr as ecr,
  aws_ecs as ecs,
} from 'aws-cdk-lib';

import { WebApp } from './server';
import { Construct } from 'constructs';
import env from '../env';

interface PipelineProps {
  readonly webapp: WebApp;
}

class Pipeline extends Construct {
  private readonly webapp: WebApp;

  readonly service: ecs.IBaseService;
  readonly containerName: string;
  readonly ecrRepo: ecr.Repository;

  public readonly pipeline: codepipeline.Pipeline;

  constructor(scope: Construct, id: string, props: PipelineProps) {
    super(scope, id);
    this.webapp = props.webapp;
    this.service = this.webapp.service;
    this.ecrRepo = this.webapp.ecrRepo;
    this.containerName = this.webapp.containerName;

    this.pipeline = this.createPipeline();
    this.output();
  }

  // Creates the pipeline structure
  private createPipeline(): codepipeline.Pipeline {
    const sourceOutput = new codepipeline.Artifact();
    const buildOutput = new codepipeline.Artifact();
    return new codepipeline.Pipeline(this, env.pipeline.id, {
      stages: [
        this.createSourceStage('Source', sourceOutput),
        this.createImageBuildStage('Build', sourceOutput, buildOutput),
        this.createDeployStage('Deploy', buildOutput),
      ],
    });
  }

  // Create a stage that retrieves source code from GitHub
  private createSourceStage(
    stageName: string,
    output: codepipeline.Artifact,
  ): codepipeline.StageProps {
    const githubAction = new codepipeline_actions.GitHubSourceAction({
      actionName: 'Github_Source',
      owner: env.pipeline.source.github.owner,
      repo: env.pipeline.source.github.repo,
      oauthToken: SecretValue.secretsManager(env.pipeline.source.github.tokenSecretName),
      branch: env.pipeline.source.github.branch,
      output: output,
    });
    return {
      stageName: stageName,
      actions: [githubAction],
    };
  }

  // Create the pipeline build stage
  private createImageBuildStage(
    stageName: string,
    input: codepipeline.Artifact,
    output: codepipeline.Artifact,
  ): codepipeline.StageProps {
    const project = new codebuild.PipelineProject(this, env.pipeline.build.id, {
      environment: {
        buildImage: codebuild.LinuxBuildImage.STANDARD_5_0,
        privileged: true,
      },
      environmentVariables: {
        REPOSITORY_URI: { value: this.ecrRepo.repositoryUri },
        CONTAINER_NAME: { value: this.containerName },
      },
      cache: codebuild.Cache.local(codebuild.LocalCacheMode.DOCKER_LAYER),
    });

    this.ecrRepo.grantPullPush(project.grantPrincipal);

    const codebuildAction = new codepipeline_actions.CodeBuildAction({
      actionName: 'CodeBuild_Action',
      input: input,
      outputs: [output],
      project: project,
    });

    return {
      stageName: stageName,
      actions: [codebuildAction],
    };
  }

  // Create the pipeline deploy stage
  createDeployStage(
    stageName: string,
    input: codepipeline.Artifact,
  ): codepipeline.StageProps {
    const ecsDeployAction = new codepipeline_actions.EcsDeployAction({
      actionName: 'ECSDeploy_Action',
      input: input,
      service: this.service,
    });
    return {
      stageName: stageName,
      actions: [ecsDeployAction],
    };
  }

  output() {
    // create a cloudformation output for the ARN of the pipeline
    new CfnOutput(this, 'Pipeline ARN', {
      value: this.pipeline.pipelineArn,
    });
  }
}

export { Pipeline, PipelineProps };

Step 6:
Instantiate all constructs into your CloudFormation Stack

Here we'll bring all our constructs together for instantiation in the infra/index.ts file.

import { WebApp } from './stacks/server';
import { Pipeline } from './stacks/pipeline';
import { Cluster } from './stacks/cluster';
import { App, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import env from './env';

class WebStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const cluster = new Cluster(this, 'Cluster');
    const webapp = new WebApp(this, 'WebApp', {
      cluster: cluster,
    });
    const pipeline = new Pipeline(this, 'Pipeline', {
      webapp: webapp,
    });
  }
}

const app = new App();
new WebStack(app, env.stack.id);
app.synth();

Step 7:
Running CDK

To link and run cdk with our app we'll have to do some housekeeping work, viz. updating package.json to add cdk synth and deploy commands and add cdk.json file to tell cdk how to run the infra code.

package.json

{
  ...
  "scripts": {
     ...
     "cdk:synth": "cdk synth",
     "cdk:deploy": "cdk deploy"
  }
}

cdk.json

{
  "app": "npx ts-node infra/index.ts"
}

Since our infra code is written in typescript we'll be using ts-node package to run it.

Finally, to test out the implementation we can run npm run cdk:synth and to deploy the code use npm run cdk:deploy.

Note:
Deploying this on M1 & M2 Mac is causing the docker container to crash. Please use this code with either Intel Macs or Linux.