Quickstart: Next.js

Add sign-in to a Next.js app with the App Router. The @usher/nextjs SDK is coming; until it arrives, this guide uses the standard OpenID Connect flow, which is exactly what the SDK will do for you.

Before you start

A Next.js 15 or 16 app using the App Router.
An Usher environment. In Usher Console, open your project, choose an environment, and note its issuer.

Register your app

In Console, go to Applications and create a web application. Add this redirect URI exactly:

http://localhost:3000/auth/callback

Copy the client ID and client secret. The secret is shown once.

Add your environment variables

.env.local

USHER_ISSUER=https://acme.id.hallelo.net
USHER_CLIENT_ID=your_client_id
USHER_CLIENT_SECRET=your_client_secret
APP_URL=http://localhost:3000

Install an OpenID Connect client

Any certified client works. This guide uses openid-client, which handles discovery, PKCE and token validation.

Terminal

pnpm add openid-client

Discover your issuer

Discovery reads the issuer’s endpoints and keys once, so nothing is hard-coded.

lib/usher.ts

import * as client from 'openid-client'

let config: Promise<client.Configuration> | undefined

export function usher() {
  config ??= client.discovery(
    new URL(process.env.USHER_ISSUER!),
    process.env.USHER_CLIENT_ID!,
    process.env.USHER_CLIENT_SECRET!,
  )
  return config
}

export const redirectUri = `${process.env.APP_URL}/auth/callback`

Send people to the Lobby

A route handler makes a PKCE verifier and a state value, keeps them in a short-lived cookie, and redirects to the Lobby.

app/auth/sign-in/route.ts

import * as client from 'openid-client'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
import { redirectUri, usher } from '@/lib/usher'

export async function GET() {
  const config = await usher()
  const codeVerifier = client.randomPKCECodeVerifier()
  const state = client.randomState()

  const jar = await cookies()
  jar.set('usher_flow', JSON.stringify({ codeVerifier, state }), {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    path: '/auth',
    maxAge: 600,
  })

  const url = client.buildAuthorizationUrl(config, {
    redirect_uri: redirectUri,
    scope: 'openid profile email offline_access',
    code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),
    code_challenge_method: 'S256',
    state,
  })
  redirect(url.href)
}

Handle the callback

Usher sends the person back with a code. Swap it for tokens; openid-client checks the state, the PKCE verifier and the ID token’s signature for you.

app/auth/callback/route.ts

import * as client from 'openid-client'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
import { usher } from '@/lib/usher'

export async function GET(request: Request) {
  const config = await usher()
  const jar = await cookies()
  const flow = JSON.parse(jar.get('usher_flow')?.value ?? '{}')
  jar.delete('usher_flow')

  const tokens = await client.authorizationCodeGrant(config, new URL(request.url), {
    pkceCodeVerifier: flow.codeVerifier,
    expectedState: flow.state,
  })
  const claims = tokens.claims()! // sub, email, name, …

  // start your own session here: store claims.sub, and keep the refresh token server-side
  redirect('/')
}

Sign out

End the person’s session in your app, then send them to Usher’s end-session endpoint so the Lobby forgets them too.

app/auth/sign-out/route.ts

import * as client from 'openid-client'
import { redirect } from 'next/navigation'
import { usher } from '@/lib/usher'

export async function GET() {
  const config = await usher()
  // clear your own session first
  const url = client.buildEndSessionUrl(config, {
    post_logout_redirect_uri: process.env.APP_URL!,
  })
  redirect(url.href)
}

With the SDK

When @usher/nextjs is published, the same app looks like this. The preview below may change before release.

app/layout.tsx · app/page.tsx (preview)

// app/layout.tsx
import { UsherProvider } from '@usher/nextjs'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UsherProvider>{children}</UsherProvider>
      </body>
    </html>
  )
}

// app/page.tsx
import { SignIn, UserButton, currentUser } from '@usher/nextjs'

export default async function Page() {
  const user = await currentUser()
  return user ? <UserButton /> : <SignIn />
}

Next steps

Any OIDC libraryThe settings, if you’re using another language or framework. ConceptsIssuers, the Lobby, and how long each token lasts.