Google 로그인 추가

초보자 연습

전제 조건: 로컬에서 실행 중인 웹 앱(5분 만에 출시)과 실제 계정용 마이그레이션된 데이터베이스(데이터베이스 설정). 일반 Google 계정이 필요합니다. 여기의 모든 것은 무료이며 약 10분 걸립니다.

용어 정리: OAuth는 Google이 Google 페이지에서 사용자를 로그인시키고 앱에 증명을 넘겨주는 표준입니다. Google Cloud 프로젝트는 앱의 자격 증명을 보관하는 Google 콘솔의 컨테이너입니다. OAuth 동의 화면(OAuth consent screen)은 Google이 사용자를 돌려보내기 전에 보여주는 페이지입니다. 클라이언트 ID는 앱을 Google에 식별하고, 클라이언트 시크릿은 그 비밀번호로 서버에만 보관됩니다.

1. Google Cloud 프로젝트를 만듭니다. 2. 동의 화면을 구성합니다. 3. 웹 OAuth 클라이언트를 하나 만들고 ID와 시크릿을 복사합니다. 4. 세 값을 apps/web/.env.local에 붙여넣고 개발 서버를 재시작합니다.

프로젝트는 제품 전체에 하나면 충분합니다. 같은 Google Cloud 프로젝트가 나중에 Cloud Run 배포를 호스팅하고, 모바일 로그인도 같은 웹 백엔드를 통해 이루어집니다—플랫폼이나 기능별로 별도의 클라이언트를 만들 필요가 없습니다.

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

Google Cloud 프로젝트 만들기

1. console.cloud.google.com을 열고 Google 계정으로 로그인합니다.

2. 상단 바(Google Cloud 로고 옆)의 프로젝트 드롭다운을 클릭하고 New Project(새 프로젝트)를 선택합니다.

3. 이름을 지정하고—제품 이름이면 됩니다—Create(만들기)를 클릭합니다. 로그인 자격 증명에는 조직, 카드, 결제 계정이 필요하지 않습니다.

예상 결과: 콘솔이 새 프로젝트로 다시 로드되고 이름이 상단 바에 표시됩니다. 배포 가이드에 도달하면 다른 프로젝트를 만들지 말고 이 프로젝트를 재사용하세요.

OAuth 동의 화면 구성

1. 왼쪽 탐색에서 APIs & Services → OAuth consent screen(API 및 서비스 → OAuth 동의 화면)을 열고 Get started(시작하기)를 클릭합니다.

2. 사용자에게 표시될 App name(앱 이름)(제품 이름)을 입력하고, User support email(사용자 지원 이메일)을 선택하고, 대상으로 External(외부)을 선택하고, 개발자 연락처 이메일을 입력한 후 Create(만들기)까지 클릭하여 진행합니다.

3. 이 화면에서 필요한 것은 이것뿐입니다. 앱은 기본 openid, email, profile 범위만 요청하며 추가 범위나 인증이 필요하지 않습니다.

개발 중에는 게시 상태가 Testing(테스트 중)으로 유지됩니다. 이 모드에서는 나열된 계정만 로그인할 수 있으므로 Audience → Test users(대상 → 테스트 사용자)에서 본인의 Gmail 주소를 추가하세요—그렇지 않으면 Google이 본인까지 차단합니다. 제품이 공개되면 Publish app(앱 게시)을 클릭합니다. 민감한 범위를 요청하지 않으므로 게시해도 Google 인증 검토가 시작되지 않습니다.

OAuth 클라이언트 만들기

1. APIs & Services → Credentials → + Create Credentials → OAuth client ID(API 및 서비스 → 사용자 인증 정보 → + 사용자 인증 정보 만들기 → OAuth 클라이언트 ID)를 엽니다.

2. Application type(애플리케이션 유형)을 Web application(웹 애플리케이션)으로 설정하고 supastack local 같은 이름을 지정합니다.

3. Authorized JavaScript origins(승인된 JavaScript 원본)에 http://localhost:3000을 추가합니다. Authorized redirect URIs(승인된 리디렉션 URI)에 http://localhost:3000/api/auth/callback/google을 추가합니다—이 콜백 경로는 킷의 기본 인증 엔진인 Better Auth의 것입니다: {APP_URL}/api/auth/callback/google.

4. Create(만들기)를 클릭하고 대화 상자에서 Client ID(클라이언트 ID)와 Client Secret(클라이언트 시크릿)을 복사합니다. 나중에 클라이언트 페이지에서 다시 열 수 있지만 지금 복사하면 한 단계가 절약됩니다.

프로덕션용으로는 두 번째 웹 클라이언트를 만들거나(권장) 이 클라이언트에 추가합니다: JavaScript 원본 https://yourdomain.com, 리디렉션 URI https://yourdomain.com/api/auth/callback/google. 환경별로 클라이언트를 분리하면 로컬 시크릿이 유출되어도 프로덕션에 도달할 수 없습니다.

앱에 값 추가

apps/web/.env.local을 엽니다—Next.js는 루트 .env가 아니라 이 파일을 읽습니다—그리고 아래 세 줄을 설정합니다. AUTH_GOOGLE_ENABLED=true가 버튼을 켜고, 클라이언트 쌍이 Google Cloud 클라이언트를 식별합니다.

클라이언트 시크릿은 서버 전용입니다. NEXT_PUBLIC_ 또는 EXPO_PUBLIC_ 변수에 절대 나타나서는 안 되며 Git에 커밋해서도 안 됩니다. 프로덕션에서는 env 파일 대신 호스트의 시크릿 저장소에 같은 세 이름을 설정합니다.

편집 후 개발 서버를 재시작하세요—환경 변경 사항은 시작 시에만 읽힙니다.

# apps/web/.env.local
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

확인 및 문제 해결

http://localhost:3000/auth를 열고 Google 버튼을 클릭하고, Google 동의 화면을 완료하고, 앱이 로그인된 상태로 돌아오는지 확인합니다.

redirect_uri_mismatch는 Google에 등록된 리디렉션 URI가 정확히 일치하지 않음을 의미합니다—프로토콜(http 대 https), 포트, 경로를 확인하세요. 끝은 /api/auth/callback/google이어야 하며 /callback/google/이나 끝 슬래시 변형이 아니어야 합니다.

Access blocked / has not completed the Google verification process(액세스 차단됨 / Google 인증 프로세스가 완료되지 않음)는 동의 화면이 아직 Testing 상태이고 로그인하는 계정이 Test users에 등록되지 않았음을 의미합니다—Audience 섹션에서 추가하세요.

Google 버튼이 없거나 .env.local 편집 후에도 로그인이 실패하면 개발 서버를 재시작하세요. 시작 시 변수 이름을 지목하며 실패하면 완전한 클라이언트 쌍 없이 플래그만 활성화된 것입니다.

• 다음으로 GitHub 로그인 추가
• OAuth 공급자 개요