Docs · Integrate

Next.js with Auth.js

Add Gatekeep to a Next.js app as an Auth.js (NextAuth v5) OIDC provider, with PKCE and no client secret.

Auth.js handles the redirect, PKCE, the code exchange and ID token checks. Gatekeep is just another OIDC provider.

1. Install

npm install next-auth@beta
npx auth secret   # writes AUTH_SECRET to .env.local

2. Configure the provider

Add your issuer and client ID to .env.local:

GATEKEEP_ISSUER=https://acme.gatekeepauth.com
GATEKEEP_CLIENT_ID=acme-notes

Create auth.ts in the root of your project:

import NextAuth from "next-auth"

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    {
      id: "gatekeep",
      name: "Gatekeep",
      type: "oidc",
      issuer: process.env.GATEKEEP_ISSUER,
      clientId: process.env.GATEKEEP_CLIENT_ID,
      // Public client: PKCE instead of a secret.
      client: { token_endpoint_auth_method: "none" },
      checks: ["pkce", "state", "nonce"],
      authorization: { params: { scope: "openid email" } },
    },
  ],
  callbacks: {
    // Keep Gatekeep's permanent user ID on the session.
    session({ session, token }) {
      if (token.sub) session.user.id = token.sub
      return session
    },
  },
})

Expose the route handlers in app/api/auth/[...nextauth]/route.ts:

import { handlers } from "@/auth"
export const { GET, POST } = handlers

3. Register the callback URL

Auth.js uses /api/auth/callback/<provider id>. Send us these redirect URIs for your app:

https://app.yourapp.com/api/auth/callback/gatekeep
http://localhost:3000/api/auth/callback/gatekeep

4. Add a sign-in button

import { signIn } from "@/auth"

export function SignIn() {
  return (
    <form action={async () => { "use server"; await signIn("gatekeep") }}>
      <button type="submit">Sign in</button>
    </form>
  )
}

Read the user in any server component with const session = await auth(). session.user.id is the Gatekeep sub.