본문으로 건너뛰기

시작하기

아래 예시 코드는 넥스트 앱에 인증을 추가하는 방법을 설명합니다.

새로운 프로젝트​

가장 쉬운 방법은 예시 앱을 복제하고 README.md의 지침을 따르는 것입니다. https://next-auth-example.vercel.app/에서 실시간 데모를 확인할 수 있습니다.

기존 프로젝트​

넥스트인증 설치하기​

bash
npm install next-auth
bash
npm install next-auth
정보

타입스크립트를 사용하는 경우 넥스트인증는 패키지 내에서 타입 정의와 함께 제공됩니다. next-auth의 타입스크립트에 대해 자세히 알아보려면 타입스크립트 문서를 확인하세요.

API 경로 추가하기​

프로젝트에 넥스트인증을 추가하려면 pages/api/auth에 [...nextauth].js라는 파일을 만듭니다. 이 파일에는 모든 전역 넥스트인증 설정과 동적 경로 처리기가 포함됩니다.

pages/api/auth/[...nextauth].js
js
import NextAuth from "next-auth"
import GithubProvider from "next-auth/providers/github"
export default NextAuth({
  // 하나 이상의 인증 제공자를 설정합니다.
  providers: [
    GithubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
    // ...여기에 제공자를 추가합니다.
  ],
})
pages/api/auth/[...nextauth].js
js
import NextAuth from "next-auth"
import GithubProvider from "next-auth/providers/github"
export default NextAuth({
  // 하나 이상의 인증 제공자를 설정합니다.
  providers: [
    GithubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
    // ...여기에 제공자를 추가합니다.
  ],
})

/api/auth/*(signIn, callback, signOut 등)에 대한 모든 요청은 넥스트인증에서 자동으로 처리됩니다.

공유 세션 상태 설정하기​

useSession을 사용하려면 먼저 앱의 최상위 수준에 세션 컨텍스트 SessionProvider를 노출해야 합니다.

pages/_app.jsx
tsx
import { SessionProvider } from "next-auth/react"
export default function App({
  Component,
  pageProps: { session, ...pageProps },
}) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  )
}
pages/_app.jsx
tsx
import { SessionProvider } from "next-auth/react"
export default function App({
  Component,
  pageProps: { session, ...pageProps },
}) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  )
}

그러면 useSession의 인스턴스가 세션 데이터와 상태에 접근할 수 있습니다. 또한 <SessionProvider />는 브라우저 탭과 창 간에 세션을 갱신하고 동기화합니다.

프런트엔드 - 리액트 훅 추가하기​

넥스트인증 클라이언트의 useSession() 리액트 훅은 누군가 로그인했는지 확인하는 가장 쉬운 방법입니다.

components/login-btn.jsx
jsx
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
  const { data: session } = useSession()
  if (session) {
    return (
      <>
        Signed in as {session.user.email} <br />
        <button onClick={() => signOut()}>Sign out</button>
      </>
    )
  }
  return (
    <>
      Not signed in <br />
      <button onClick={() => signIn()}>Sign in</button>
    </>
  )
}
components/login-btn.jsx
jsx
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
  const { data: session } = useSession()
  if (session) {
    return (
      <>
        Signed in as {session.user.email} <br />
        <button onClick={() => signOut()}>Sign out</button>
      </>
    )
  }
  return (
    <>
      Not signed in <br />
      <button onClick={() => signIn()}>Sign in</button>
    </>
  )
}

앱의 모든 위치(예: 헤더 컴포넌트)에서 useSession 훅을 사용할 수 있습니다.

백엔드 - API 경로​

경로 API를 보호하기 위해 unstable_getServerSession() 메서드를 사용할 수 있습니다.

pages/api/restricted.js
jsx
import { unstable_getServerSession } from "next-auth/next"
import { authOptions } from "./auth/[...nextauth]"
export default async (req, res) => {
  const session = await unstable_getServerSession(req, res, authOptions)
  if (session) {
    res.send({
      content:
        "This is protected content. You can access this content because you are signed in.",
    })
  } else {
    res.send({
      error: "You must be sign in to view the protected content on this page.",
    })
  }
}
pages/api/restricted.js
jsx
import { unstable_getServerSession } from "next-auth/next"
import { authOptions } from "./auth/[...nextauth]"
export default async (req, res) => {
  const session = await unstable_getServerSession(req, res, authOptions)
  if (session) {
    res.send({
      content:
        "This is protected content. You can access this content because you are signed in.",
    })
  } else {
    res.send({
      error: "You must be sign in to view the protected content on this page.",
    })
  }
}

확장성​

넥스트인증 콜백 사용하기​

넥스트인증을 사용하면 내장 콜백을 통해 인증 흐름의 다양한 부분에 연결할 수 있습니다.

예를 들어 로그인에서 클라이언트 측 프런트엔드로 값을 전달하려면 다음과 같이 session과 jwt 콜백 조합을 사용할 수 있습니다.

pages/api/auth/[...nextauth].js
js
...
callbacks: {
  async jwt({ token, account }) {
    // 로그인 후 바로 토큰에 대한 OAuth access_token을 유지합니다.
    if (account) {
      token.accessToken = account.access_token
    }
    return token
  },
  async session({ session, token, user }) {
    // 제공자의 access_token과 같은 프로퍼티를 클라이언트에게 보냅니다.
    session.accessToken = token.accessToken
    return session
  }
}
...
pages/api/auth/[...nextauth].js
js
...
callbacks: {
  async jwt({ token, account }) {
    // 로그인 후 바로 토큰에 대한 OAuth access_token을 유지합니다.
    if (account) {
      token.accessToken = account.access_token
    }
    return token
  },
  async session({ session, token, user }) {
    // 제공자의 access_token과 같은 프로퍼티를 클라이언트에게 보냅니다.
    session.accessToken = token.accessToken
    return session
  }
}
...

이제 getSession이나 useSession를 호출할 때마다 반환되는 데이터 개체에 accessToken 값이 포함됩니다.

components/accessToken.jsx
jsx
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
  const { data } = useSession()
  const { accessToken } = data
  return <div>Access Token: {accessToken}</div>
}
components/accessToken.jsx
jsx
import { useSession, signIn, signOut } from "next-auth/react"
export default function Component() {
  const { data } = useSession()
  const { accessToken } = data
  return <div>Access Token: {accessToken}</div>
}

콜백 URL 설정하기 (OAuth만 해당)​

OAuth 제공자를 기본 제공자 중 하나 또는 커스텀 제공자를 통해 사용하는 경우, 제공자의 설정에서 콜백 URL을 지정해야 합니다. 각 제공자에는 수행 방법에 대한 포인터를 제공하는 '설정' 부분이 있습니다.

이 단계에 따라 OAuth 제공자와 통합하는 방법을 배울 수 있습니다.

프로덕션에 배포하기​

사이트를 배포할 때 NEXTAUTH_URL 환경 변수를 웹사이트의 표준 URL로 설정합니다.

text
NEXTAUTH_URL=https://example.com
text
NEXTAUTH_URL=https://example.com
팁

프로덕션에서는 이 값을 앱을 배포하는 데 사용하는 서비스에서 환경 변수로 설정해야 합니다.

베르셀에서 환경 변수를 설정하려면 대시보드나 vercel env pull 명령을 사용합니다.