NextAuth with Pages Router

This guide will help you integrate Descope with your NextAuth application using the Pages Router. Follow the steps below to get started.

If you're interested in using our native SDK instead of NextAuth, you can read about the pros and cons of each in our guide.

Install NextAuth.js

To use Descope with Next.js, the simplest method is to use NextAuth.js. You can install it with this command:

Terminal

npm i --save next-auth

Import NextAuth Packages

Import all necessary NextAuth packages in a [...nextauth].ts file. The location of [...nextauth].ts will exist in pages/api/auth.

pages/api/auth/[...nextauth].ts

import NextAuth from "next-auth/next";
import type { NextAuthOptions } from "next-auth"
 
export const authOptions: NextAuthOptions = {
  providers: [],
}
 
export default NextAuth(authOptions)

Initialize Descope as a Provider

Once you've imported the necessary packages, you'll need to initialize NextAuth and add Descope as a provider.

pages/api/auth/[...nextauth].ts

import NextAuth from "next-auth/next";
import type { NextAuthOptions } from "next-auth"
 
export const authOptions: NextAuthOptions = {
	providers: [
		{
			id: "descope",
			name: "Descope",
			type: "oauth",
			wellKnown: `https://api.descope.com/__ProjectID__/.well-known/openid-configuration`,
			authorization: { params: { scope: "openid email profile" } },
			idToken: true,
			clientId: "__ProjectID__",
			clientSecret: "<Descope Access Key>",
			checks: ["pkce", "state"],
			profile(profile) {
				return {
					id: profile.sub,
					name: profile.name,
					email: profile.email,
					image: profile.picture,
				}
			},
		}
	],
	callbacks: {
        async jwt({token, account, profile}) {
            if (account) {
                return {
                    ...token,
                    access_token: account.access_token,
                    expires_at: Math.floor(Date.now() / 1000 + account.expires_in),
                    refresh_token: account.refresh_token,
                    profile: {
                      name: profile?.name,
                      email: profile?.email,
                      image: profile?.picture,
                  },
                }
            } else if (Date.now() < token.expires_at * 1000) {
                return token
            } else {
                try {
                    const response = await fetch("https://api.descope.com/oauth2/v1/token", {
                        headers: {"Content-Type": "application/x-www-form-urlencoded"},
                        body: new URLSearchParams({
                            client_id: "__ProjectID__",
                            client_secret: "<Descope Access Key>",
                            grant_type: "refresh_token",
                            refresh_token: token.refresh_token,
                        }),
                        method: "POST",
                    })
    
                    const tokens = await response.json()
    
                    if (!response.ok) throw tokens
    
                    return {
                        ...token,
                        access_token: tokens.access_token,
                        expires_at: Math.floor(Date.now() / 1000 + tokens.expires_in),
                        refresh_token: tokens.refresh_token ?? token.refresh_token,
                    }
                } catch (error) {
                    console.error("Error refreshing access token", error)
                    return {...token, error: "RefreshAccessTokenError"}
                }
            }
        },
    
        async session({session, token}) {
            if (token.profile) {
              session.user = token.profile;
            }
    
            session.error = token.error
            session.accessToken = token.access_token
            return session
        },
	}
};
 
export default NextAuth(authOptions)

Setup NextAuth's `SessionProvider`

In your _app.tsx file, wrap the components in SessionProvider to allow for session management and authentication throughout your Next application.

_app.tsx

import type { AppProps } from "next/app";
import { Session } from "next-auth";
import { SessionProvider } from "next-auth/react"
 
 
export default function App(
  { Component, pageProps }: 
  AppProps<{ session: Session }>
) {
  return (
    <SessionProvider session={pageProps.session}>
        <Component {...pageProps} />
    </SessionProvider>
  )
}

Accessing the Authentication Flow

Add a sign-in button in the client to access your sign-in authentication flow. The signIn method has 'descope' as the provider id, and the callback URL set to /dashboard as an example to redirect back to.

components/Navbar.tsx

import { signIn } from "next-auth/react"
 
export default function Navbar() {
    return (
        <button 
            onClick={() => signIn(
                "descope", 
                { callbackUrl: "/dashboard" }
            )}
        >
			Apply
        </button>
    )
}

Session Management

To learn more about session management with NextAuth & Descope, check out the Web Client Session Validation docs.

Congratulations

Now that you've got the authentication down, go focus on building out the rest of your app!

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Using NextAuth and Customization

Once you've configured NextAuth to work with Descope as an OIDC provider, the next step is to utilize all of the various NextAuth functions in your application.

You can visit our guide with detailed docs on how all of the Sign In, Logout, etc. functions work with NextAuth, in your Next.js application.

Built-in Functions

Otherwise, you can visit our Flow Customization section to configure and personalize many different areas of Descope, including your brand, style, custom user authentication journeys, etc.

We recommend starting with customizing your user-facing screens, such as signup and login.

Customize

Was this helpful?

Checkpoint

On this page