👉구글 로그인(OAuth 2.0) 연동 및 로컬 환경 설정 가이드

구글 로그인 연동 과정과 로컬 환경에서의 트러블슈팅 내역을 정리!

 

1. 구글 클라우드 콘솔 설정 (Google Cloud Console)

구글 로그인을 사용하려면 먼저 [Google Cloud Console](https://console.cloud.google.com/)에서 

프로젝트를 생성하고 OAuth 2.0 클라이언트를 발급받아야 한다.

1️⃣Step 1: OAuth 동의 화면
1. API 및 서비스 > OAuth 동의 화면으로 이동합니다.
2. User Type을 선택합니다 (테스트용은 `외부` 선택).
3. 앱 이름, 사용자 지원 이메일 등 필수 정보를 입력합니다.
4. 테스트 사용자: 앱이 '테스트' 상태인 경우, 로그인을 허용할 구글 계정 이메일을 반드시 등록해야 합니다.

2️⃣Step 2: 사용자 인증 정보 생성 (Client ID & Secret)
1. `사용자 인증 정보` > `사용자 인증 정보 만들기` > `OAuth 클라이언트 ID`를 선택합니다.
2. 애플리케이션 유형을 `웹 애플리케이션`으로 선택합니다.
3. 승인된 리디렉션 URI (Redirect URIs):
   - 로컬 환경용: http://localhost:/api/auth/google/callback
   - 배포 환경용: https://your-domain.com/api/auth/google/callback`
   - 중요: 이 URI가 실제 서버 코드의 설정과 일치하지 않으면 redirect_uri_mismatch 에러가 발생합니다.
4. 생성을 완료하면 Client ID와 Client Secret이 발급됩니다.

---

2. 환경 변수 설정

발급받은 인증 정보는 코드에 직접 적지 않고 환경 변수로 관리합니다.

1️⃣로컬 서버용 (dev.vars : 최상위 경로에 생성):

GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:/api/auth/google/callback

 -> 발급 받은 Client ID와 Client Secret을 각각 입력하면 됩니다.

2️⃣배포 환경 (Cloudflare Pages): 
Cloudflare 관리 대시보드 > Settings > Variables에서 동일한 키값을 설정합니다.

 

---

3. 핵심 디버깅 기록: 로컬 환경 쿠키 문제

로컬(localhost)에서 로그인이 "무반응"이거나 "Internal Server Error"가 발생하는 경우 가장 먼저 확인해야 할 부분입니다.

 

문제: `Secure` 쿠키 플래그
- 증상: 구글 로그인은 완료되어 콜백 주소로 돌아왔으나, 세션(또는 OAuth State) 쿠키가 브라우저에 저장되지 않아 검증에 실패함.
- 원인: 최신 브라우저는 Secure 속성이 있는 쿠키를 HTTPS 연결에서만 허용합니다. 로컬 서버는 보통 http://이기 때문에 쿠키가 무시됩니다.
- 해결 :

  ```typescript
  // src/lib/auth.ts
  const isSecure = c.req.url.startsWith('https://');
  
  setCookie(c, "session_id", sessionId, {
      path: "/",
      secure: isSecure, // HTTPS일 때만 true, 로컬(HTTP)에서는 false로 가변 처리
      httpOnly: true,
      sameSite: "Lax",
  });
  ```

 

---

4. DB 일치성 확인 (D1 Migration)

로컬 서버와 운영 서버의 DB 구조가 다를 경우(예: 신규 아이디 로그인 시 가입 처리 중 에러), 마이그레이션을 로컬에도 적용해줘야 합니다.

- 명령어: `npm run db:migrate:local`
- 내용: `tier`, `plan` 등 새로운 기능 개발을 위해 추가된 컬럼들을 로컬 DB(`SQLite`)에도 생성해줍니다.

 

---

Checklist
1. [ ] 승인된 리디렉션 URI에 `localhost` 포트까지 정확히 적었는가?
2. [ ] OAuth 동의 화면의 '테스트 사용자'에 내 계정을 등록했는가?
3. [ ] 로컬 서버 구동 시 `isLocal` 또는 `isSecure` 조건문으로 쿠키의 `Secure` 플래그를 꺼주었는가?
4. [ ] 로컬 DB 구조가 최신 상태인가?