Creating a database adapter for an external backend REST API

[basememara]

Description 📓

I would like my frontend to handle the authentication but use a backend for database access.

For context, I have a Next.js app on the frontend that communicates to a NestJS app for the backend. I would like all the authentication to happen on the Next.js frontend app which has the NextAuth installation, but the data access handled by the NestJS app. This is so I don't have to share the database between 2 servers but instead only the backend has database access. To achieve this, I need to create a custom database adapter that makes REST API requests to the NestJS backend app.

Also note that I do plan on using JWT which does not require a database, but I want to still leverage a database adapter with JWT so NextAuth can handle the create/update user, social account flows, and email verifications. I believe only the session functions will be unused in the adapter + JWT scenario.

I tried implementing an adapter that connects an external backend API and it was under-estimated based on other discussions. The most difficult part was the serialization and deserialization of the objects between frontend and backend servers.

I would like to share my implementation to help others and hopefully I can also get peer reviewed by the community, and eventually contribute it as a REST API adapter. Here's what I came up with:

Frontend / Next.js:

pages/api/auth/[next-auth].ts:

export const authOptions: AuthOptions = {
  adapter: AuthRestAdapter(),
  ...
}

export default NextAuth(authOptions);

utils/auth-reset-adapter.ts:

import axios from 'axios';
import { Adapter, AdapterAccount, AdapterSession, AdapterUser, VerificationToken } from 'next-auth/adapters';
import { backendAddress } from './backend-address';

export function AuthRestAdapter(): Adapter<true> {
  const client = axios.create({
    baseURL: `${backendAddress}/auth`,
    headers: {
      'Content-Type': 'application/json',
      'x-auth-secret': process.env.NEXTAUTH_SECRET || ''
    }
  });

  return {
    createUser: async (user: Omit<AdapterUser, 'id'>) => {
      const response = await client.post('/', user);
      return format<AdapterUser>(response.data);
    },
    getUserByEmail: async (email: string) => {
      const response = await client.get('/', { params: { email } });
      return response.data ? format<AdapterUser>(response.data) : response.data;
    },
    getUserByAccount: async ({
      providerAccountId,
      provider
    }: Pick<AdapterAccount, 'provider' | 'providerAccountId'>) => {
      const response = await client.get(`/account/${provider}/${providerAccountId}`);
      return response.data ? format<AdapterUser>(response.data) : response.data;
    },
    getUser: async (id: string) => {
      const response = await client.get(`/${id}`);
      return response.data ? format<AdapterUser>(response.data) : response.data;
    },
    updateUser: async (user: Partial<AdapterUser> & Pick<AdapterUser, 'id'>) => {
      const response = await client.patch('/', user);
      return format<AdapterUser>(response.data);
    },
    deleteUser: async (userId: string) => {
      const response = await client.delete(`/${userId}`);
      return response.data ? format<AdapterUser>(response.data) : response.data;
    },
    linkAccount: async (account: AdapterAccount) => {
      const response = await client.post('/account', account);
      return response.data ? format<AdapterAccount>(response.data) : response.data;
    },
    unlinkAccount: async ({ providerAccountId, provider }: Pick<AdapterAccount, 'provider' | 'providerAccountId'>) => {
      const response = await client.delete(`/account/${provider}/${providerAccountId}`);
      return response.data ? format<AdapterAccount>(response.data) : response.data;
    },
    createSession: async (session: { sessionToken: string; userId: string; expires: Date }) => {
      const response = await client.post('/session', session);
      return response.data ? format<AdapterSession>(response.data) : response.data;
    },
    getSessionAndUser: async (sessionToken: string) => {
      const response = await client.get(`/session/${sessionToken}`);

      if (!response.data) {
        return response.data;
      }

      const session = format<AdapterSession>(response.data.session);
      const user = format<AdapterUser>(response.data.user);
      return { session, user };
    },
    updateSession: async (session: Partial<AdapterSession> & Pick<AdapterSession, 'sessionToken'>) => {
      const response = await client.patch('/session', session);
      return response.data ? format<AdapterSession>(response.data) : response.data;
    },
    deleteSession: async (sessionToken: string) => {
      const response = await client.delete(`/session/${sessionToken}`);
      return response.data ? format<AdapterSession>(response.data) : response.data;
    },
    createVerificationToken: async (verificationToken: VerificationToken) => {
      const response = await client.post('/verification', verificationToken);
      return response.data ? format<VerificationToken>(response.data) : response.data;
    },
    useVerificationToken: async (params: { identifier: string; token: string }) => {
      const response = await client.patch(`/verification`, params);
      return response.data ? format<VerificationToken>(response.data) : response.data;
    }
  };
}

function format<T>(obj: Record<string, unknown>): T {
  return Object.entries(obj).reduce((result, [key, value]) => {
    const newResult = result;

    if (value === null) {
      return newResult;
    }

    if (isDate(value)) {
      newResult[key] = new Date(value);
    } else {
      newResult[key] = value;
    }

    return newResult;
  }, {} as Record<string, unknown>) as T;
}

const isDate = (value: unknown): value is string =>
  typeof value === 'string' ? new Date(value).toString() !== 'Invalid Date' && !Number.isNaN(Date.parse(value)) : false;

Note the following with the adapter:

• Created REST client with the NEXTAUTH_SECRET to be passed to the backend to verify the requests
• Every function is calling an endpoint to the backend to be fulfilled there
• The response must be formatted or deserialized properly otherwise the object cannot be hydrated; I stole this formatter from the Supabase database adapter but first tried to use class-transformer which unfortunately only works with classes not interfaces or types.

Backend / NestJS:

src/api/auth/auth.controller.ts:

import { Body, Controller, Delete, Get, Param, Patch, Post, Query } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import { AdapterAccount, AdapterSession, AdapterUser, VerificationToken } from 'next-auth/adapters';
import { AuthService } from './auth.service';

@Controller('auth')
@ApiTags('Auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post()
  async createUser(@Body() user: Omit<AdapterUser, 'id'>) {
    return await this.authService.createUser(user);
  }

  @Get()
  async getUserByEmail(@Query('email') email: string) {
    return await this.authService.getUserByEmail(email);
  }

  @Get('account/:provider/:id')
  async getUserByAccount(@Param('id') id: string, @Param('provider') provider: string) {
    return await this.authService.getUserByAccount(id, provider);
  }

  @Get(':id')
  async getUser(@Param('id') id: string) {
    return await this.authService.getUser(id);
  }

  @Patch()
  async updateUser(@Body() user: Partial<AdapterUser> & Pick<AdapterUser, 'id'>) {
    return await this.authService.updateUser(user);
  }

  @Delete(':id')
  async deleteUser(@Param('id') id: string) {
    return await this.authService.deleteUser(id);
  }

  @Post('account')
  async linkAccount(@Body() account: AdapterAccount) {
    return await this.authService.linkAccount(account);
  }

  @Delete('account/:provider/:id')
  async unlinkAccount(@Param('id') id: string, @Param('provider') provider: string) {
    return await this.authService.unlinkAccount(id, provider);
  }

  @Post('session')
  async createSession(@Body() session: { sessionToken: string; userId: string; expires: Date }) {
    return await this.authService.createSession(session);
  }

  @Get('session/:sessionToken')
  async getSessionAndUser(@Param('sessionToken') sessionToken: string) {
    return await this.authService.getSessionAndUser(sessionToken);
  }

  @Patch('session')
  async updateSession(@Body() session: Partial<AdapterSession> & Pick<AdapterSession, 'sessionToken'>) {
    return await this.authService.updateSession(session);
  }

  @Delete('session/:sessionToken')
  async deleteSession(@Param('sessionToken') sessionToken: string) {
    return await this.authService.deleteSession(sessionToken);
  }

  @Post('verification')
  async createVerificationToken(@Body() verificationToken: VerificationToken) {
    return await this.authService.createVerificationToken(verificationToken);
  }

  @Patch('verification')
  async useVerificationToken(@Body() params: { identifier: string; token: string }) {
    return await this.authService.useVerificationToken(params);
  }
}

src/api/auth/auth.controller.ts:

import { Injectable } from '@nestjs/common';
import { PrismaAdapter } from '@next-auth/prisma-adapter';
import { Adapter, AdapterAccount, AdapterSession, AdapterUser, VerificationToken } from 'next-auth/adapters';
import { PrismaService } from 'src/prisma/prisma.service';

@Injectable()
export class AuthService {
  adapter: Adapter;

  constructor(prisma: PrismaService) {
    this.adapter = PrismaAdapter(prisma);
  }

  async createUser(user: Omit<AdapterUser, 'id'>) {
    return await this.adapter.createUser(user);
  }

  async getUserByEmail(email: string) {
    return await this.adapter.getUserByEmail(email);
  }

  async getUserByAccount(id: string, provider: string) {
    return await this.adapter.getUserByAccount({ providerAccountId: id, provider });
  }

  async getUser(id: string) {
    return await this.adapter.getUser(id);
  }

  async updateUser(user: Partial<AdapterUser> & Pick<AdapterUser, 'id'>) {
    return await this.adapter.updateUser(user);
  }

  async deleteUser(userId: string) {
    return await this.adapter.deleteUser?.(userId);
  }

  async linkAccount(account: AdapterAccount) {
    return await this.adapter.linkAccount(account);
  }

  async unlinkAccount(id: string, provider: string) {
    return await this.adapter.unlinkAccount?.({ providerAccountId: id, provider });
  }

  async createSession(session: { sessionToken: string; userId: string; expires: Date }) {
    return await this.adapter.createSession(session);
  }

  async getSessionAndUser(sessionToken: string) {
    return await this.adapter.getSessionAndUser(sessionToken);
  }

  async updateSession(session: Partial<AdapterSession> & Pick<AdapterSession, 'sessionToken'>) {
    return await this.adapter.updateSession(session);
  }

  async deleteSession(sessionToken: string) {
    return await this.adapter.deleteSession(sessionToken);
  }

  async createVerificationToken(verificationToken: VerificationToken) {
    return await this.adapter.createVerificationToken?.(verificationToken);
  }

  async useVerificationToken({ identifier, token }) {
    return await this.adapter.useVerificationToken?.({ identifier, token });
  }
}

Note the following with the service:

• I am using the Prisma adapter underneath, but anyone can use any database adapter without the outer layers having any knowledge. This is great because I don't have to recreate any logic but just proxy it through to an existing database adapter. What's also nice is the frontend doesn't need access to the database, only the backend does.

To secure the communication between the frontend and backend, I'm using a middleware in the backend app:

src/middlewares/auth.middleware.ts:

import { Injectable, NestMiddleware, UnauthorizedException } from '@nestjs/common';
import { NextFunction, Request, Response } from 'express';

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  async use(req: Request, _res: Response, next: NextFunction) {
    if (req.headers['x-auth-secret'] !== process.env.NEXTAUTH_SECRET) {
      throw new UnauthorizedException('Auth secret not provided or incorrect');
    }

    next();
  }
}

app.module.ts:

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(AuthMiddleware).forRoutes('auth');
  }
}

The only drawback I've encountered so far is a little bit of latency. Are there any other thoughts or concerns about this approach and implementation? Any experience or insights would be greatly appreciated!

Related discussion:

• Using an adapter for external backend API? #1150
• Generating JWT on backend server and passing that to next-auth #4834

How to reproduce ☕️

Add AuthRestAdapter() to your NextAuth options and implement the controller/service on the NestJS backend.

Contributing 🙌🏽

Yes, I am willing to help implement this feature in a PR

[geekyayush]

I have done the same exact thing for my app. It was the only solution

[SaadiSidali]

I couldn't reach you on any other platform so I'll ask my questions here, I like your approach and would want to implement the same thing in my app, but still want to use Nestjs guards or maybe a brief example of how to authorize on Nestjs side or any further config that is required.

Great work Basem

[kingroho]

Hi @basememara this is perfect solution so we only have one api to communicate with. I'm thinking of also building a mobile app and a sveltekit for the web.

I was thinking the same solution but, my nest.js protected routes are only accessible via JWT. But we are encoding the JWT on the next.js side because we're just returning the user from nest.js? Is this correct?

I have a dedicated login/registration mechanism on nest js but they only spit out accessToken and refreshToken instead of user.

Can't wrap my head around on how can next.js talk to the nest.js protected routes api if the JWT was not from the nest app.

[basememara]

@SaadiSidali the only additional things I can think of that may help further is the following...

I added a new middleware called user.middleware.ts that looks something like this:

@Injectable()
export class UserMiddleware implements NestMiddleware {
  async use(req: Request, _res: Response, next: NextFunction) {
    // Validate token if provided
    const token = await getToken({ req });

    if (token?.sub) {
      req.user = {
        id: token.sub,
        name: token.name || null,
        email: token.email || null,
        custom1: token.custom1
      };

      return next();
    }

    throw new UnauthorizedException('Credentials not provided or incorrect');
  }
}

After attaching the user details to all request objects, I can start building decorators and guards around it. For example, a @User decorator:

// User.decorator.ts
export const User = createParamDecorator((data: keyof AuthUser, ctx: ExecutionContext) => {
  const request = ctx.switchToHttp().getRequest();
  return data ? request.user?.[data] : request.user;
});

// AuthUser.ts
export interface AuthUser {
  id: string;
  name: string | null;
  email: string | null;
  custom1: string | null;
}

// types.d.ts
declare module 'express-serve-static-core' {
  interface Request {
    user?: AuthUser;
  }
}

declare module 'next-auth/jwt' {
  interface JWT extends AuthUser {}
}

[basememara]

@kingroho the reason the NestJS can read tokens generated from the Next.js app is because they share the same env variable NEXTAUTH_SECRET. This is the key to understanding that the JWT token can be decrypted by any app or script that uses this secret value. You can even take the cookie value and decrypt it with a Python script offline using that secret value. It's why in my user.middleware above can use getToken to read the JWT token sent by the Next.js app.. that function from NextAuth implicitly uses the NEXTAUTH_SECRET value or you can override it with another secret value but nice that it implicitly uses that env variable so no need to pass it in explicitly.

[kingroho]

Wow, I did not know you can use the same secret to decode/encode JWTs. I'll use your code as a reference then. Thank you.

[sangdth]

@basememara Thanks for sharing, this is the missing documentation that I'm looking for. I hope we can bring this into official documentation of how to make a customised Adapter for an existing backend.

My question, does this implementation also work with for example login with social media account like Facebook/GitHub? I guess yes because looks like the adapter passes all the requests to the backend.

[basememara]

Hey @sangdth, yes I have this fully functioning in production with Google login as one of my providers. Right that's the beauty is everything else falls in place because of the NextAuth adapter architecture.

[malbaugh]

Hey @basememara, thanks for sharing your approach - super helpful.

Should we not include session tokens in the request URL to avoid man-in-the-middle attacks or leaking of session ids elsewhere? Is this a valid concern?