빠른 시작: Next.js
App Router를 사용하는 Next.js 앱에 로그인을 추가합니다. @usher/nextjs SDK는 곧 제공될 예정입니다. 그때까지 이 가이드는 표준 OpenID Connect 흐름을 사용하며, 이는 SDK가 대신 처리해 줄 내용과 정확히 같습니다.
시작하기 전에
- App Router를 사용하는 Next.js 15 또는 16 앱.
- Usher 환경. Usher Console에서 프로젝트를 열고 환경을 선택한 다음, 해당 환경의 발급자를 확인해 두세요.
앱 등록하기
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:3000OpenID Connect 클라이언트 설치하기
인증받은 클라이언트라면 무엇이든 작동합니다. 이 가이드에서는 디스커버리, PKCE, 토큰 검증을 처리하는 openid-client를 사용합니다.
터미널
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로 보내기
라우트 핸들러가 PKCE 검증자(verifier)와 state 값을 만들어 유효 기간이 짧은 쿠키에 보관한 뒤, 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는 코드와 함께 사용자를 돌려보냅니다. 이 코드를 토큰으로 교환하세요. state, PKCE 검증자, ID 토큰의 서명은 openid-client가 대신 확인합니다.
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('/')
}로그아웃
앱에서 사용자의 세션을 끝낸 다음, 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/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 />
}