Guide

Overview#

Integrating SuperTokens into a NestJS backend is a bit different than the quick setup guide shows. We will add a few things:

A module to house all authorization related code
A service to initialize the SDK
A middleware to add the authorization endpoints
A global error handler to pass SuperTokens related errors to the SDK
A guard to protect your API endpoints
A parameter decorator to access the session in your code

We will cover each of these in the following few sections. Then, you can do the rest of the customizations by following the "Common customizations" section.

Please look here to see how to get started with your NestJS backend.

1) Installing SuperTokens#

npm i -s supertokens-node

2) Adding a new module#

You can scaffold a module using the nest CLI by running this in the root folder of the application:

nest g module auth

The result should be a new auth folder with auth.module.ts in it. We should convert this into a dynamic module so we can set parts of the SuperTokens configuration in the App module. Centralizing settings like this can be helpful for things like using a separate connection URI for testing.

Add config type and injection token#

Add a config.interface.ts file next into the auth folder. We will put the type and injection token for the SuperTokens config here.

import { AppInfo } from "supertokens-node/types";

export const ConfigInjectionToken = "ConfigInjectionToken";

export type AuthModuleConfig = {
  appInfo: AppInfo;
  connectionURI: string;
  apiKey?: string;
}

Convert to a dynamic module#

We want to configure this module in the App module, so we add a static forRoot method and convert it into a dynamic module.

import {
  MiddlewareConsumer,
  Module,
  NestModule,
  DynamicModule,
} from '@nestjs/common';

import { AuthMiddleware } from './auth.middleware';
import { ConfigInjectionToken, AuthModuleConfig } from './config.interface';

@Module({
  providers: [],
  exports: [],
  controllers: [],
})
export class AuthModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(AuthMiddleware).forRoutes('*');
  }

  static forRoot({ connectionURI, apiKey, appInfo }: AuthModuleConfig): DynamicModule {
    return {
      providers: [
        {
          useValue: {
            appInfo,
            connectionURI,
            apiKey,
          },
          provide: ConfigInjectionToken,
        },
      ],
      exports: [],
      imports: [],
      module: AuthModule,
    };
  }
}

Adding the module to the application#

You need to update the App module to use the new dynamic module by importing the result of forRoot instead of the class itself.

// ...
import { Module} from '@nestjs/common';
import { AuthModule } from './auth/auth.module';

@Module({
  imports: [
    AuthModule.forRoot({
      connectionURI: "",
      apiKey: "",
      appInfo: {
        // Learn more about this on https://supertokens.com/docs/thirdpartypasswordless/appinfo
        appName: "<YOUR_APP_NAME>",
        apiDomain: "<YOUR_API_DOMAIN>",
        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
        apiBasePath: "/auth",
        websiteBasePath: "/auth",
      },
    }),
  ],
  controllers: [/* ... */],
  providers: [/* ... */],
})
export class AppModule {}

3) Adding a service#

You can scaffold this service using the nest CLI by running this in the root folder of the application:

nest g service supertokens auth

Move the new service into the dynamic module#

import {
  MiddlewareConsumer,
  Module,
  NestModule,
  DynamicModule,
} from '@nestjs/common';

import { AuthMiddleware } from './auth.middleware';
import { ConfigInjectionToken, AuthModuleConfig } from './config.interface';
import { SupertokensService } from './supertokens/supertokens.service';

@Module({
  providers: [],
  exports: [],
  controllers: [],
})
export class AuthModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(AuthMiddleware).forRoutes('*');
  }

  static forRoot({ connectionURI, apiKey, appInfo }: AuthModuleConfig): DynamicModule {
    return {
      providers: [
        {
          useValue: {
            appInfo,
            connectionURI,
            apiKey,
          },
          provide: ConfigInjectionToken,
        },
        SupertokensService,
      ],
      exports: [],
      imports: [],
      module: AuthModule,
    };
  }
}

Add service code#

We initialize the SDK in a service so that you can have access to injected services in event handlers. Edit the supertokens.service.ts to match:

How do you want to identify your users?

Only phone numberOnly emailEmail or phone number

Which authentication type will you use?

OTPMagic linksOTP and Magic link

4) Set up your email / sms delivery method#

How do you want to identify your users?

Only phone numberOnly emailEmail or phone number

5) Exposing SuperTokens APIs using its `middleware`#

The middleware file#

You can scaffold the middleware by running nest g middleware auth auth in the application's root folder. The result should be in the auth module, called auth.middleware.ts. Next, we need to edit this to use the middleware from supertokens.

import { Injectable, NestMiddleware } from "@nestjs/common";
import { middleware } from 'supertokens-node/framework/express';

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  supertokensMiddleware: any;

  constructor() {
    this.supertokensMiddleware = middleware();
  }

  use(req: Request, res: any, next: () => void) {
    return this.supertokensMiddleware(req, res, next);
  }
}

Registering the middleware#

We need to edit the module file to register the middleware. You can achieve this by implementing a configure method in the AuthModule class.

import { DynamicModule, MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AuthMiddleware } from "./auth.middleware";
// ...

export class AuthModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(AuthMiddleware).forRoutes('*');
  }
  // ...
}

6) Update CORS settings#

You should enable and update your CORS settings in main.ts:

import { NestFactory } from '@nestjs/core';
// ...
import supertokens from 'supertokens-node';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors({
    origin: ['<YOUR_WEBSITE_DOMAIN>'],
    allowedHeaders: ['content-type', ...supertokens.getAllCORSHeaders()],
    credentials: true,
  });

  await app.listen(3000);
}

bootstrap()

7) Add the SuperTokens error handler#

We add the SuperTokens error handler through a NestJS exception filter.

Exception filter#

You can scaffold the exception filter using the CLI by: nest g filter auth auth. This will result in a new auth.filter.ts file next to the auth module. We need to edit this to add our error handler.

import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
import { Request, Response, NextFunction, ErrorRequestHandler } from 'express';

import { errorHandler } from 'supertokens-node/framework/express';
import { Error as STError } from 'supertokens-node';

@Catch(STError)
export class SupertokensExceptionFilter implements ExceptionFilter {
  handler: ErrorRequestHandler;

  constructor() {
    this.handler = errorHandler();
  }

  catch(exception: Error, host: ArgumentsHost) {
    const ctx = host.switchToHttp();

    const resp = ctx.getResponse<Response>();
    if (resp.headersSent) {
      return;
    }

    this.handler(
      exception,
      ctx.getRequest<Request>(),
      resp,
      ctx.getNext<NextFunction>(),
    );
  }
}

Registering the filter#

We need to add this filter as a global exception filter. You can do this in main.ts, right after the updated cors settings.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

import supertokens from 'supertokens-node';
import { SupertokensExceptionFilter } from './auth/auth.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors({
    origin: ['http://localhost:3001'], // TODO: URL of the website domain
    allowedHeaders: ['content-type', ...supertokens.getAllCORSHeaders()],
    credentials: true,
  });

  app.useGlobalFilters(new SupertokensExceptionFilter());

  await app.listen(3000);
}

bootstrap();

8) Add session verification guard#

Now that the library is set up, you can add a guard to protect your API. You can scaffold this nest g guard auth auth. This results in auth.guard.ts that we can edit to implement session verification.

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Error as STError } from "supertokens-node";

import { verifySession } from 'supertokens-node/recipe/session/framework/express';
import { VerifySessionOptions } from 'supertokens-node/recipe/session';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly verifyOptions?: VerifySessionOptions) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const ctx = context.switchToHttp();

    let err = undefined;
    const resp = ctx.getResponse();
    // You can create an optional version of this by passing {sessionRequired: false} to verifySession
    await verifySession(this.verifyOptions)(
      ctx.getRequest(),
      resp,
      (res) => {
        err = res;
      },
    );

    if (resp.headersSent) {
      throw new STError({
        message: "RESPONSE_SENT",
        type: "RESPONSE_SENT",
      });
    }

    if (err) {
      throw err;
    }

    return true;
  }
}

9) Add a parameter decorator#

Now you can add a parameter decorator to access the already verified session in your APIs. You can generate an empty decorator by running nest g decorator session auth. Edit session.decorator.ts to return the session attached to the request:

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const Session = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.session;
  },
);

10) Combine the decorator and the guard to authenticate users#

You can add a protected method into a controller (e.g.: App.controller.ts) that receives the verified session as a parameter by:

import { Controller, Get, UseGuards } from '@nestjs/common';
// ...
import { SessionContainer } from "supertokens-node/recipe/session";
import { AuthGuard } from './auth/auth.guard';
import { Session } from './auth/session.decorator';
// ...

@Controller()
export class AppController {
  // ...
  @Get('test')
  @UseGuards(new AuthGuard())
  async getTest(@Session() session: SessionContainer): Promise<string> {
    // TODO: magic
    return "magic";
  }
}

You should look at the Sessions section under Common Customizations to see how you can use the session object.

11) Setup the SuperTokens core#

Are you using https://try.supertokens.com as the connection URI in the init function?

YesNo