GitHub로 OAuth 설정하기

이 튜토리얼에서는 Next.js 애플리케이션에서 Auth.js를 설정하여 GitHub로 로그인할 수 있도록 해보겠습니다.

Setting up Auth.js

Auth.js와 Next.js 설치하기

이 튜토리얼에서는 기본 Auth.js & Next.js 예제 앱을 사용할 예정입니다. 이미 Next.js 앱이 있다면 그대로 사용해도 괜찮습니다. 없다면 저장소를 클론하세요:

git clone https://github.com/nextauthjs/next-auth-example.git && cd next-auth-example

예제 앱을 사용한다면 Auth.js가 이미 설치되어 있습니다. 그렇지 않다면 설치 가이드를 따라 진행하세요.

서버 설정 만들기

이제 Auth.js의 주요 설정 파일을 만들어 보겠습니다. 이 파일에는 Auth.js에 필요한 설정과 동적 라우트 핸들러가 포함됩니다.

import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"
 
export const { handlers, auth } = NextAuth({
  providers: [GitHub],
})

import { handlers } from "@/auth" // 방금 만든 auth.ts 파일을 참조
export const { GET, POST } = handlers
export const runtime = "edge" // 선택 사항

이 파일은 캐치-올 동적 라우트이기 때문에, 모든 관련된 Auth.js API 라우트에 응답합니다. 이를 통해 여러분의 애플리케이션은 OAuth 2 프로토콜을 사용해 선택한 OAuth 프로바이더와 상호작용할 수 있습니다.

환경 변수 추가하기

아직 하지 않았다면, 설치 섹션에서 설명한 대로 .env.local 파일을 생성하고 다음 두 개의 GitHub 변수를 추가하세요.

AUTH_SECRET="changeMe"
 
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=

GitHub에 애플리케이션을 등록한 후, GitHub 개발자 포털에서 적절한 값을 가져와 AUTH_GITHUB_ID와 AUTH_GITHUB_SECRET을 채울 예정입니다.

Registering your App

GitHub에서 OAuth 앱 만들기

GitHub에서 필요한 자격 증명을 얻으려면 개발자 설정에서 애플리케이션을 생성해야 합니다.

GitHub 개발자 설정으로 이동하거나, Settings → Developers → OAuth Apps에서 “New OAuth App”을 클릭하세요.

다음으로 애플리케이션을 등록하는 화면이 나타납니다. 모든 필수 필드를 입력하세요.

기본 콜백 URL은 일반적으로 [origin]/api/auth/callback/[provider] 형식을 따르지만, 사용하는 프레임워크에 따라 약간 다를 수 있습니다.

// 로컬
http://localhost:3000/api/auth/callback/github
 
// 프로덕션
https://app.company.com/api/auth/callback/github

// 로컬
http://localhost:3000/auth/callback/github
 
// 프로덕션
https://app.company.com/auth/callback/github

// 로컬
http://localhost:3000/auth/callback/github
 
// 프로덕션
https://app.company.com/auth/callback/github

// 로컬
http://localhost:3000/auth/callback/github
 
// 프로덕션
https://app.company.com/auth/callback/github

모든 필수 필드를 입력한 후 **“Register application”**을 누르세요.

Secrets

애플리케이션을 성공적으로 등록한 후, GitHub는 필요한 정보를 제공합니다.

이 화면에서 필요한 두 가지는 Client ID와 Client Secret입니다.

Client ID는 항상 볼 수 있으며, GitHub 내에서 OAuth 애플리케이션의 공개 식별자입니다.

Client Secret을 얻으려면 **“Generate a new client secret”**을 클릭해야 합니다. 이렇게 하면 첫 번째 Client Secret이 생성됩니다. 첫 번째 Client Secret이 유출되거나 분실된 경우 여기서 쉽게 새로운 Client Secret을 생성할 수 있습니다.

모든 것을 연결하기

이제 필요한 Client ID와 Client Secret을 얻었으니, 앞서 만든 .env.local 파일에 붙여넣으세요.

AUTH_SECRET="changeMe"
 
AUTH_GITHUB_ID={clientId}
AUTH_GITHUB_SECRET={clientSecret}

모든 준비가 끝났다면, 이제 로컬 개발 서버를 시작하고 로그인 과정을 테스트할 수 있습니다.

npm run dev

pnpm run dev

yarn dev

bun run dev

http://localhost:3000로 이동하세요. 다음과 같은 페이지가 보일 것입니다:

**“Sign in”**을 클릭하면, 기본 Auth.js 로그인 페이지로 리디렉션될 것입니다. 이 페이지는 커스터마이징하여 필요에 맞게 수정할 수 있습니다. 다음으로 **“Sign in with GitHub”**을 클릭하세요. Auth.js가 GitHub로 리디렉션하고, GitHub는 여러분의 애플리케이션을 인식한 후 사용자에게 새로운 애플리케이션에 인증할지 확인하고 자격 증명을 입력하도록 요청할 것입니다.

인증이 완료되면, GitHub는 사용자를 여러분의 앱으로 다시 리디렉션하고 Auth.js가 나머지 과정을 처리할 것입니다:

여기까지 왔다면 모든 것이 잘 작동한 것입니다! 이제 사용자가 GitHub를 통해 여러분의 애플리케이션에 로그인할 수 있는 OAuth 인증 흐름을 완료했습니다!

배포

앱을 프로덕션 환경에 배포하기 전에 몇 가지 변경이 필요합니다.

안타깝게도 GitHub은 하나의 애플리케이션에 여러 콜백 URL을 등록할 수 없습니다. 따라서 GitHub 대시보드에서 이전에 했던 것처럼 별도의 애플리케이션을 등록해야 합니다. 이때 콜백 URL을 프로덕션 도메인으로 설정합니다(예: https://example.com/api/auth/callback/github). 그러면 새로운 Client ID와 Client Secret이 생성되며, 이를 호스팅 제공업체의 대시보드(Vercel, Netlify, Cloudflare 등)를 통해 프로덕션 환경에 추가하거나, 프로덕션 환경 변수를 관리하는 방식에 따라 설정해야 합니다.

자세한 내용은 배포 페이지를 참고하세요.