NextAuth.js

When you want an authentication system in your Next.js application, NextAuth.js is an excellent solution to bring in the complexity of security without the hassle of having to build it yourself. It comes with an extensive list of providers to quickly add OAuth authentication and provides adapters for many databases and ORMs.

Context Provider

In your app’s entrypoint, you’ll see that your application is wrapped in a SessionProvider↗:

<SessionProvider session={session}>
  <Component {...pageProps} />
</SessionProvider>

This context provider allows your application to access the session data from anywhere in your application, without having to pass it down as props:

import { useSession } from "next-auth/react";

const User = () => {
  const { data: session } = useSession();

  if (!session) {
    // Handle unauthenticated state, e.g. render a SignIn component
    return <SignIn />;
  }

  return <p>Welcome {session.user.name}!</p>;
};

Retrieving session server-side

Sometimes you might want to request the session on the server. To do so, prefetch the session using the

import { getServerAuthSession } from "../server/auth";
import { type GetServerSideProps } from "next";

export const getServerSideProps: GetServerSideProps = async (ctx) => {
  const session = await getServerAuthSession(ctx);
  return {
    props: { session },
  };
};

const User = () => {
  const { data: session } = useSession();
  // NOTE: `session` wont have a loading state since it's already prefetched on the server

  ...
}

Inclusion of

user.id

on the Session

Create T3 App is configured to utilise the session callback↗ in the NextAuth.js config to include the user’s ID within the

callbacks: {
    session({ session, user }) {
      if (session.user) {
        session.user.id = user.id;
      }
      return session;
    },
  },

This is coupled with a type declaration file to make sure the

import { DefaultSession } from "next-auth";

declare module "next-auth" {
  interface Session {
    user?: {
      id: string;
    } & DefaultSession["user"];
  }
}

The same pattern can be used to add any other data to the

Usage with tRPC

When using NextAuth.js with tRPC, you can create reusable, protected procedures using middleware↗. This allows you to create procedures that can only be accessed by authenticated users.

This is done in a two step process:

1. Grab the session from the request headers using the
   getServerSession
   ↗ function. The advantage of using
   getServerSession
   instead of the regular
   getSession
   is that it’s a server-side only function and doesn’t trigger unnecessary fetch calls.
   create-t3-app
   creates a helper function that abstracts this peculiar API away so that you don’t need to import both your NextAuth.js options as well as the
   getServerSession
   function every time you need to access the session.

export const getServerAuthSession = (ctx: {
  req: GetServerSidePropsContext["req"];
  res: GetServerSidePropsContext["res"];
}) => {
  return getServerSession(ctx.req, ctx.res, authOptions);
};

Using this helper function, we can grab the session and pass it through to the tRPC context:

import { getServerAuthSession } from "../auth";

export const createContext = async (opts: CreateNextContextOptions) => {
  const { req, res } = opts;
  const session = await getServerAuthSession({ req, res });
  return await createContextInner({
    session,
  });
};

2. Create a tRPC middleware that checks if the user is authenticated. We then use the middleware in a
   protectedProcedure
   . Any caller to these procedures must be authenticated, or else an error will be thrown which can be appropriately handled by the client.

const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.session || !ctx.session.user) {
    throw new TRPCError({ code: "UNAUTHORIZED" });
  }
  return next({
    ctx: {
      // infers the `session` as non-nullable
      session: { ...ctx.session, user: ctx.session.user },
    },
  });
});

export const protectedProcedure = t.procedure.use(isAuthed);

The session object is a light, minimal representation of the user and only contains a few fields. When using the

const userRouter = router({
  me: protectedProcedure.query(async ({ ctx }) => {
    const user = await prisma.user.findUnique({
      where: {
        id: ctx.session.user.id,
      },
    });
    return user;
  }),
});

Usage with Prisma

Getting NextAuth.js to work with Prisma requires a lot of initial setup↗.

Adding new fields to your models

When adding new fields to any of the

If for example, you’d like to add a

+ enum Role {
+   USER
+   ADMIN
+ }

  model User {
    ...
+   role Role @default(USER)
  }

Usage with Next.js middleware

Usage of NextAuth.js with Next.js middleware requires the use of the JWT session strategy↗ for authentication. This is because the middleware is only able to access the session cookie if it is a JWT. By default, Create T3 App is configured to use the default database strategy, in combination with Prisma as the database adapter.

Setting up the default DiscordProvider

1. Head to the Applications section in the Discord Developer Portal↗, and click on “New Application”
2. In the settings menu, go to “OAuth2 => General”

• Copy the Client ID and paste it in
  DISCORD_CLIENT_ID
  in
  .env
  .
• Under Client Secret, click “Reset Secret” and copy that string to
  DISCORD_CLIENT_SECRET
  in
  .env
  . Be careful as you won’t be able to see this secret again, and resetting it will cause the existing one to expire.
• Click “Add Redirect” and paste in
  <app url>/api/auth/callback/discord
  (example for local development:
  http://localhost:3000/api/auth/callback/discord↗
  )
• Save your changes
• It is possible, but not recommended, to use the same Discord Application for both development and production. You could also consider Mocking the Provider↗ during development.

Useful Resources