OAuth 로그인 설정

실제 계정 생성 및 확인

인증은 누가 앱을 사용하고 있는지 증명하는 것을 의미합니다. Postgres를 시작하고 먼저 데이터베이스 가이드를 사용하여 마이그레이션을 실행한 다음 웹 서버를 실행 상태로 둡니다. http://localhost:3000/auth,를 열고 이메일/비밀번호 가입을 선택하고 이름, 이메일, 비밀번호를 입력하고 제출하세요. 첫 번째 테스트를 위해 EMAIL_PROVIDER=local를 유지하세요.

흐름이 이메일 코드를 요청하면 다른 브라우저 탭에서 http://localhost:3000/mail-preview를 열고 해당 주소에 대한 가장 최근 메시지를 찾아 해당 코드를 로그인 양식에 다시 복사합니다. 만료된 경우 새 코드를 요청하세요. 이러한 메시지는 로컬 보낼 편지함에 남아 있습니다. 외부 받은편지함을 반복해서 확인해도 찾을 수 없습니다. 로그아웃한 다음 다시 로그인하여 데이터베이스 지원 계정이 작동하는지 확인하세요.

가입 시 데이터베이스 연결 또는 테이블 누락 오류가 보고되면 소셜 로그인을 활성화하는 대신 데이터베이스 설정을 완료하세요. Google, GitHub, Apple, X 및 Microsoft 버튼에는 자체 공급자 애플리케이션 및 콜백 설정이 필요합니다. 공급자 가이드가 완료된 후에만 활성화하십시오. Better Auth는 기본 엔진으로 제공되며 로컬 이메일 로그인을 위해 유료 인증 계정이 필요하지 않습니다.

• 계정을 만들기 전에 Postgres를 시작하세요
• 이메일 로그인 코드 사용 및 문제 해결
• Google 로그인 구성
• Google 로그인 추가
• GitHub 로그인 추가
• Apple 로그인 추가

활성화할 로그인 방법 선택

기반에는 이메일/비밀번호, OTP, 구성 가능한 소셜 인증이 포함됩니다. Better Auth가 신원과 세션을 소유하고, 애플리케이션이 프로바이더 구성과 OTP 트랜잭션 전송을 구성합니다.

구성한 소셜 프로바이더만 활성화하세요. 프로바이더 클라이언트 시크릿과 인증 시크릿은 서버에 둡니다.

신원을 워크스페이스에 연결

인증된 핸들러는 워크스페이스 레코드에 닿기 전에 세션 상태를 해석합니다. 워크스페이스 프로비저닝은 멱등해야 하며 라이프사이클 후크를 반복해도 소유권 레코드가 중복 생성되지 않아야 합니다.

세션 동작 검증

로그인, 유효하지 않거나 만료된 OTP, 일회용 소비, 로그아웃, 거부된 익명 액세스를 테스트하세요. 메모리 어댑터 테스트는 핸들러 의미를 커버합니다. 프로덕션 데이터베이스 영속화와 실제 프로바이더 콜백은 별도의 수용이 필요합니다.

설치 및 설정

1. AUTH_SECRET을 최소 32자의 무작위 문자로 설정하세요 — openssl rand -hex 32가 됩니다.

2. 각 프로바이더의 개발자 콘솔에서 OAuth 앱을 만들고 콜백 URL을 등록하세요: Better Auth(기본 AUTH_PROVIDER)에서는 {APP_URL}/api/auth/callback/<provider>. 프로바이더가 콜백을 하나만 허용하면 로컬과 프로덕션에 별도 앱을 사용하세요 — docs/github-auth-setup.md가 GitHub 플로를 끝까지 안내합니다.

3. 프로바이더 플래그를 켜고 클라이언트 쌍을 설정하세요 — AUTH_GOOGLE_ENABLED와 GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, 그리고 Apple, GitHub, Microsoft, Twitter의 대응 세트. 자격 증명 없이 플래그를 켜면 누락된 변수를 지목하며 시작이 실패합니다.

4. Microsoft는 엔진에 따라 다른 유일한 콜백입니다: Better Auth는 /api/auth/callback/microsoft, Auth.js는 /api/auth/callback/microsoft-entra-id.

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

구현 워크플로

워크스페이스 외부 계정은 다른 표면입니다: CONNECTED_X_*, CONNECTED_GOOGLE_*, CONNECTED_MICROSOFT_* 쌍이 Settings → Connections를 채우고, 그 콜백은 {APP_URL}/api/accounts/{x|google|microsoft}/callback 아래에 있습니다. 빈 client id는 그 프로바이더의 연결 플로를 비활성화로 둡니다 — 로그인 앱 자격 증명을 거기에 재사용하지 마세요.

프로바이더 클라이언트 시크릿은 AUTH_SECRET과 마찬가지로 서버 전용입니다 — NEXT_PUBLIC_이나 EXPO_PUBLIC_ 변수에 절대 넣지 마세요.

로그인이 작동하나요? AI 설정으로 계속하세요.

검증 및 문제 해결

첫 로그인, 돌아오는 세션, 취소된 동의 화면, 비활성화된 프로바이더를 테스트하세요. 콜백 불일치가 흔한 실패입니다 — 등록된 URL은 APP_URL과 엔진의 콜백 id와 정확히 일치해야 하며, env 변경 후에는 앱 재시작이 필요합니다.