> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# OAuth 로그인 설정

Google, Apple, GitHub, Microsoft, Twitter — 각각 플래그 하나와 클라이언트 쌍.

## 실제 계정 생성 및 확인

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

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

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

[계정을 만들기 전에 Postgres를 시작하세요](https://supastack.dev/ko/docs/web/database.md)

[이메일 로그인 코드 사용 및 문제 해결](https://supastack.dev/ko/docs/web/setup-ai.md)

[Google 로그인 구성](https://supastack.dev/ko/docs/web/setup-oauth.md)

[Google 로그인 추가](https://supastack.dev/ko/docs/web/google-sign-in.md)

[GitHub 로그인 추가](https://supastack.dev/ko/docs/web/github-sign-in.md)

[Apple 로그인 추가](https://supastack.dev/ko/docs/web/apple-sign-in.md)


## 활성화할 로그인 방법 선택

기반에는 이메일/비밀번호, 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 변경 후에는 앱 재시작이 필요합니다.


설정을 계속하려면 [AI 설정](https://supastack.dev/ko/docs/web/setup-ai.md) 가이드를 읽어보세요.


## 다음

[인증](https://supastack.dev/ko/docs/modules/auth.md)