Product

Gmail API OAuth Credentials는 어디서 가져오나

Google Cloud Console에서 Gmail API를 활성화하고, OAuth 2.0 Client ID와 Secret을 발급받는 전 과정을 정리합니다.

Gmail을 자동화하려면 결국 Google OAuth credentials가 필요합니다.

IMAP용 앱 비밀번호도 있지만, 현재는 Gmail API + OAuth 2.0이 더 안전하고 확장성이 좋습니다. 이 글은 Google Cloud Console에서 필요한 값을 뽑는 방법을 단계별로 정리합니다.

필요한 값

Gmail API를 OAuth로 호출하려면 다음이 필요합니다.

  • Client ID
  • Client Secret
  • Redirect URI

이 셋으로 access token과 refresh token을 받아옵니다.

프로젝트 만들고 Gmail API 켜기

  1. Google Cloud Console에 로그인합니다.
  2. 상단 프로젝트 선택기에서 New Project를 누릅니다.
  3. 프로젝트 이름을 입력하고 Create합니다.
  4. 왼쪽 메뉴 APIs & Services → Enabled APIs & services로 갑니다.
  5. + ENABLE APIS AND SERVICES를 누르고 Gmail API를 검색합니다.
  6. Enable을 눌러 API를 켭니다.

OAuth 동의 화면 설정하기

  1. APIs & Services → OAuth consent screen으로 갑니다.
  2. User Type를 External 또는 Internal로 선택합니다. 조직 외부 사용자용이라면 External, 내용 테스트라면 Internal이 가능하면 Internal이 더 간단합니다.
  3. App name, User support email, Developer contact information을 입력합니다.
  4. 필요한 scope를 추가합니다. Gmail 관련 scope는 보통 다음 중 하나입니다.
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
  5. Test users에 자신의 이메일을 추가합니다. 앱이 아직 검증되지 않은 상태에서는 여기 등록된 사용자만 로그인할 수 있습니다.

OAuth Client ID 발급하기

  1. APIs & Services → Credentials로 갑니다.
  2. Create Credentials → OAuth client ID를 선택합니다.
  3. Application type을 선택합니다.
    • 웹 앱: Web application
    • 데스크톱/CLI: Desktop app
    • 모바일: Android 또는 iOS
  4. 이름을 입력하고, Authorized redirect URIs에 실제 redirect 주소를 추가합니다. 예를 들어 http://localhost:8080/oauth2callback 같은 주소입니다.
  5. Create를 누륩니다.
  6. 팝업에 뜨는 Client ID와 Client Secret을 복사합니다.

Client Secret은 이 창을 닫으면 다시 볼 수 없으므로 반드시 지금 복사해야 합니다.

정리하면

단계메뉴산출물
프로젝트 생성Cloud Console 상단프로젝트 ID
API 활성화APIs & Services → Enabled APIsGmail API 사용 가능
동의 화면OAuth consent screen앱 정보, scope, test user
CredentialsCredentials → OAuth client IDClient ID, Client Secret

주의할 점

External 앱은 Google의 검증 절차를 거쳐야 production에서 일반 사용자가 사용할 수 있습니다. 테스트 단계라면 Test users에 계정을 추가해야 합니다.

scope가 민감할수록 검증이 까다로워집니다. 예를 들어 gmail.readonly와 gmail.send는 검증이 비교적 쉽지만, gmail.modify나 https://mail.google.com/은 더 엄격합니다.

또한 redirect URI는 정확히 일치해야 합니다. 끝에 / 하나가 달라도 OAuth 인증이 실패합니다.

마지막으로 Client Secret은 .env에 넣고 커밋하지 마세요. GitHub에 노출되면 Google이 알림을 전송할 수 있습니다.