Next.js OIDC Client Quickstart

This guide walks you through how to integrate Descope into your Next.js app as an OIDC client, using redirect-based login with Federated Apps.

Install the SDK

Install the Descope SDK for Next.js using your preferred package manager:

npm install @descope/nextjs-sdk

yarn add @descope/nextjs-sdk

pnpm add @descope/nextjs-sdk

bun install @descope/nextjs-sdk

Wrap Your App with `AuthProvider`

In your layout.tsx, wrap your app in AuthProvider and configure OIDC by enabling oidcConfig.

app/layout.tsx

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      projectId="__ProjectID__" // Replace with your Project ID
      oidcConfig={true}         // Enables OIDC redirect behavior
    >
      <html lang="en">
        <body>{children}</body>
      </html>
    </AuthProvider>
  );
}

You may also pass a full oidcConfig object to customize settings such as redirectUri, scope, and applicationId. Read more in our Client SDK docs section.

Use the useDescope() hook and call sdk.oidc.loginWithRedirect() to start the login process.

app/page.tsx

'use client';

import { useDescope } from '@descope/nextjs-sdk/client';

export default function Page() {
  const sdk = useDescope();

  return (
    <button
      onClick={() => {
        sdk.oidc.loginWithRedirect({
          redirect_uri: window.location.origin, // Optional: defaults to current URL
          login_hint: 'user@example.com', // Optional: pre-fill the form.externalId context key
        });
      }}
    >
      Login with OIDC
    </button>
  );
}

`loginWithRedirect` Parameters

You can pass any of the following parameters into the loginWithRedirect function to provide additional info to the OIDC provider:

redirect_uri: A custom URI that overrides the default redirect after login. This will default to being the current URL.
login_hint: A hint to Descope of the user identifier (e.g., email address). This will pre-fill the form.externalId context key in the flow you're redirected to.

Redirect Back and Automatic Session Handling

After a successful login, the OIDC provider will redirect the user to your app. The AuthProvider will automatically process the returned tokens and establish a session.

No additional code is needed on the redirect page — just ensure the page is wrapped with AuthProvider.

Access User and Session Info

You can use useSession() and useUser() to access authentication state and user info.

app/dashboard.tsx

'use client';

import { useDescope, useSession, useUser } from '@descope/nextjs-sdk/client';

export default function Dashboard() {
  const { isAuthenticated, isSessionLoading } = useSession();
  const { user, isUserLoading } = useUser();

  if (isSessionLoading || isUserLoading) return <p>Loading...</p>;

  if (isAuthenticated) {
    return <p>Welcome, {user.name}</p>;
  }

  return <p>You are not logged in</p>;
}

Logout the User

To log out, you can call sdk.logout() for local session clearing, or sdk.oidc.logout() for a full OIDC-compliant logout with redirect:

app/page.tsx

'use client';

import { useDescope } from '@descope/nextjs-sdk/client';

export default function LogoutButton() {
  const sdk = useDescope();

  return (
    <>
      <button onClick={() => sdk.logout()}>Logout</button>
      <button
        onClick={() =>
          sdk.oidc.logout({
            post_logout_redirect_uri: window.location.origin + '/after-logout',
          })
        }
      >
        Logout and Redirect
      </button>
    </>
  );
}

(Optional) Use Middleware to Protect Routes

Use the Descope middleware to guard specific routes:

middleware.ts

import { authMiddleware } from '@descope/nextjs-sdk/server';

export default authMiddleware({
  projectId: '__ProjectID__',
  redirectUrl: '/sign-in',
  publicRoutes: ['/sign-in', '/about'],
});

export const config = {
  matcher: ['/((?!_next|.*\\..*).*)'],
};

You're All Set!

Your Next.js app now uses Descope as an OIDC provider with redirect-based login, logout, and session management.

Was this helpful?

On this page