GitHub 로그인 추가

초보자 연습

전제 조건: 로컬에서 실행 중인 웹 앱과 실제 계정용 마이그레이션된 데이터베이스. GitHub 계정이 필요합니다—리포지토리를 소유한 것과 같은 계정이면 됩니다. 무료이며 환경당 약 5분입니다.

용어 정리: GitHub OAuth 앱은 GitHub이 대신 사용자를 로그인시켜 주는 등록입니다. 대부분의 공급자와 달리 하나의 OAuth 앱은 정확히 하나의 Authorization callback URL(인증 콜백 URL)만 허용합니다—따라서 로컬(http://localhost:3000/…)과 프로덕션(https://yourdomain.com/…)은 각각 자체 앱이 필요합니다. 하나의 앱을 재사용하며 콜백을 왔다 갔다 수정하면 매번 한쪽이 깨집니다.

1. 계정의 Developer settings(개발자 설정)에서 로컬 OAuth 앱을 만듭니다. 2. Client ID(클라이언트 ID)를 복사하고 Client Secret(클라이언트 시크릿)을 생성합니다. 3. 세 개의 환경 값을 설정하고 재시작합니다. 4. 공개 전에 실제 도메인으로 한 번 더 반복합니다.

• 웹 앱을 5분 만에 출시
• 데이터베이스 설정

로컬 OAuth 앱 만들기

1. github.com을 열고 로그인합니다. 오른쪽 상단의 프로필 사진을 클릭 → Settings(설정).

2. 왼쪽 사이드바 맨 아래로 스크롤하여 Developer settings → OAuth Apps → New OAuth App(개발자 설정 → OAuth 앱 → 새 OAuth 앱)을 엽니다.

3. Application name(애플리케이션 이름): supastack local 같은 것—사용자는 GitHub 인증 페이지에서 이 이름을 봅니다. Homepage URL(홈페이지 URL): http://localhost:3000. Authorization callback URL(인증 콜백 URL): http://localhost:3000/api/auth/callback/github. Register application(애플리케이션 등록)을 클릭합니다.

4. 앱 페이지에서 Client ID(클라이언트 ID)를 복사하고, Generate a new client secret(새 클라이언트 시크릿 생성)을 클릭하고, 시크릿을 즉시 복사합니다—GitHub는 한 번만 표시하지만 언제든 새로 생성할 수 있습니다.

프로덕션 OAuth 앱 만들기

제품 이름, Homepage URL https://yourdomain.com, Authorization callback URL https://yourdomain.com/api/auth/callback/github으로 같은 New OAuth App 단계를 반복합니다.

각 앱의 자격 증명은 자체 환경에 보관하세요. 로컬 앱의 쌍은 apps/web/.env.local에, 프로덕션 앱의 쌍은 호스트의 시크릿 저장소에 둡니다. 로컬 시크릿이 프로덕션 구성에 도달해서는 안 되며 그 반대도 마찬가지입니다.

앱에 값 추가

로컬 앱의 자격 증명을 사용하여 apps/web/.env.local에 아래 세 줄을 설정합니다. AUTH_GITHUB_ENABLED=true가 버튼을 켜고, 이 쌍이 OAuth 앱을 식별합니다.

클라이언트 시크릿은 서버 전용으로 유지됩니다—NEXT_PUBLIC_/EXPO_PUBLIC_ 변수에는 절대 넣지 않고 커밋도 하지 않습니다. 편집 후 개발 서버를 재시작하세요.

다른 곳에서 보게 될 수 있는 GITHUB_APP_* 값은 재사용하지 마세요—그것들은 사용자 로그인이 아니라 관련 없는 GitHub App 통합의 것입니다. 킷의 docs/github-auth-setup.md는 이 전체 흐름을 처음부터 끝까지 안내하는 두 번째 참고 자료입니다.

# apps/web/.env.local — from the LOCAL OAuth App
AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-oauth-app-secret

확인 및 문제 해결

http://localhost:3000/auth를 열고 GitHub 버튼을 클릭합니다. github.com에서 앱을 인증하고 로그인된 상태로 돌아오는지 확인합니다.

AUTH_GITHUB_ENABLED=true가 설정될 때까지 /auth의 GitHub 옵션은 보이지만 비활성화 상태로 남습니다—env 파일 이름을 확인한 후 재시작하세요. GITHUB_CLIENT_ID와 GITHUB_CLIENT_SECRET 없이 플래그만 설정하면 시작이 실패하고 누락된 변수가 지목됩니다.

콜백 불일치가 흔한 실패입니다. 앱의 Authorization callback URL은 {APP_URL}/api/auth/callback/github과 정확히 일치해야 합니다—프로토콜, 호스트, 포트, 경로 모두. 배포 후 redirect_uri 오류는 보통 APP_URL이 프로덕션인데 요청이 로컬 앱의 자격 증명에 닿았거나 그 반대를 의미합니다.

env를 편집할 때마다 개발 서버를 재시작하세요. 값은 시작 시에만 읽힙니다.

• 다음으로 데이터베이스 설정
• OAuth 공급자 개요