快速入門：Next.js
為使用 App Router 的 Next.js App 加入登入功能。@usher/nextjs SDK 即將推出；在它推出之前，本指南使用標準 OpenID Connect 流程，而這正是 SDK 將替你完成的工作。
開始之前
- 一個使用 App Router 的 Next.js 15 或 16 App。
- 一個 Usher 環境。在 Usher Console 中打開你的專案，選擇一個環境，並記下它的簽發者。
註冊你的 App
在 Console 中前往應用程式，並建立一個網頁應用程式。完全照樣加入這個重新導向 URI：
http://localhost:3000/auth/callback拷貝用戶端 ID 和用戶端機密。機密只會顯示一次。
加入環境變數
.env.local
USHER_ISSUER=https://acme.usherid.com
USHER_CLIENT_ID=your_client_id
USHER_CLIENT_SECRET=your_client_secret
APP_URL=http://localhost:3000安裝 OpenID Connect 用戶端
任何經過認證的用戶端都可以。本指南使用 openid-client，它會處理探索、PKCE 和權杖驗證。
終端機
pnpm add openid-client探索你的簽發者
探索只會讀取一次簽發者的端點和金鑰，因此不需要寫死任何內容。
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`將使用者送往 Lobby
一個路由處理程式（Route Handler）會產生 PKCE 驗證器和 state 值，將它們保存在短效的 Cookie 中，然後重新導向到 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)
}處理回呼
Usher 會帶著授權碼將使用者送回來。用它換取權杖；openid-client 會替你檢查 state、PKCE 驗證器和 ID 權杖的簽章。
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('/')
}登出
在你的 App 中結束使用者的工作階段，然後將他們送往 Usher 的結束工作階段端點，讓 Lobby 也忘記他們。
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)
}使用 SDK
@usher/nextjs 發布後，同一個 App 看起來會像這樣。下方的預覽在正式發布前可能會有所變動。
app/layout.tsx · app/page.tsx（預覽）
// 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 />
}