Google Client ID란 무엇이며 어떻게 생성하나요?

어떤 Google OAuth 클라이언트 ID 은 Google이 표시하는 공개 앱 식별자로, 문자열로 끝나며 .apps.googleusercontent.com로 끝납니다. 이 값은 Google Cloud Console 하위 Google Auth 플랫폼 > 클라이언트 또는 API 및 서비스 > 사용자 인증 정보에서 생성 및 관리합니다. 이 값은 Google에 어떤 등록된 앱이 Google 로그인 또는 OAuth 토큰 요청을 시작하는지 알려줍니다.

Google Sign-In은 빠른 통합이 되어야 하는데, 실제로는 자격 증명 화면을 보며 왜 한 앱 유형은 클라이언트 시크릿을 제공하고 다른 유형은 제공하지 않는지 궁금해하고 계실 것입니다. 특히 Capacitor, Ionic, Electron 또는 웹과 네이티브가 혼합된 스택으로 개발 중이라면 이러한 혼란은 자연스럽습니다.

대부분의 가이드가 건너뛰는 부분은 실제 구현을 깨뜨리는 요소입니다: Google 클라이언트 ID는 플랫폼별로 다릅니다, 그리고 웹이 아닌 앱 유형은 보통 설계상 client secret을 제공하지 않습니다. secret을 강제로 주입하려고 잘못된 credential을 만들면, 디버깅이 더 어려운 깨진 OAuth 설정이 생기는 경우가 많습니다.

목차

• 사전 요구 사항: OAuth 동의 화면
• OAuth 2.0 client ID 생성 방법
  • 웹 애플리케이션 클라이언트
  • Android client (패키지 이름 및 SHA-1)
  • iOS 클라이언트 (번들 ID)
• 기존 client ID 찾기
• 클라이언트 ID와 클라이언트 시크릿
• Google Client ID란 무엇인가요?
• 플랫폼별 Client ID 설정
• Google API 자격 증명 보호하기
• 흔히 발생하는 Client ID 오류 해결하기
• 자주 묻는 질문

사전 요구 사항: OAuth 동의 화면

Google이 OAuth 클라이언트 생성을 허용하기 전에 프로젝트에서 Google Auth용 앱을 등록해야 합니다. Google은 다음 화면을 열 때 이 과정을 완료하도록 안내합니다. Google Auth 플랫폼 > 클라이언트 처음 사용하는 경우.

일반적인 단계:

1. 열기 Google Cloud Console 에서 로그인을 담당할 프로젝트를 선택하세요.
2. 다음으로 이동: Google 인증 플랫폼 (또는 API & 서비스 > OAuth 동의 화면 구버전 내비게이션의 경우).
3. 선택 외부 또는 내부 사용자 유형을 선택한 후 앱 이름, 지원 이메일, 개발자 연락처를 입력하세요.
4. 앱에서 요청할 스코프를 추가하세요(기본적인 로그인용, email 및 profile 이 경우가 흔합니다).
5. 저장 후 동의 화면 워크플로우를 진행하여 앱이 등록될 때까지 완료하세요.

이 화면의 애플리케이션 이름은 사용자가 Google 권한 프롬프트에서 보는 이름입니다. 내부 코드명이 아니라 사용자가 설치한 앱 이름과 일치해야 합니다.

OAuth 2.0 클라이언트 ID 생성 방법

Google은 이 플로우를 OAuth 클라이언트 관리 도움말 페이지에 문서화했습니다. 이 두 가지 진입점 모두 사용할 수 있습니다:

1. Google Auth 플랫폼 > 클라이언트 (그 다음 클라이언트 생성)
2. API 및 서비스 > 사용자 인증 정보 (그 다음 사용자 인증 정보 만들기 > OAuth 클라이언트 ID)

먼저 Cloud 프로젝트를 선택하거나 생성하세요. 인증 정보를 관련 없는 프로젝트에 분산하지 마세요.

웹 애플리케이션 클라이언트

브라우저 앱과 웹 클라이언트 ID 많은 모바일 SDK가 서버 오디언스로 기대하는 용도에 이 유형을 사용하세요.

1. 클릭 클라이언트 생성 (또는 OAuth 클라이언트 ID 를 사용자 인증 정보에서 생성하세요.)
2. 선택 웹 애플리케이션 응용 프로그램 유형으로 설정하세요.
3. 설정 승인된 JavaScript 원본 로그인 UI를 실행하는 각 오리진에 추가하세요 (스키마, 호스트, 포트가 정확히 일치해야 합니다). 로컬 개발에는 http://localhost:<port> 를 사용하세요. Google의 규칙에 따라 localhost를 제외한 프로덕션 오리진은 HTTPS를 사용해야 합니다.
4. 설정 승인된 리디렉션 URI Google이 다시 리디렉션한 후 서버나 SPA가 사용하는 각 콜백 URL에 추가하세요.
5. 클릭 생성. 복사 클라이언트 ID 을(를) 저장하고 클라이언트 시크릿 안전하게 보관하세요. Google은 시크릿을 한 번만 표시할 수 있습니다.

Capacitor 하이브리드 앱의 경우, 네이티브 SDK를 통해 로그인하더라도 Web 클라이언트 ID가 토큰 검증에 사용될 수 있습니다. 참고 Capacitor를 사용한 Google 로그인 방법 에서 모바일 설정 전체를 확인하세요.

Android 클라이언트 (패키지 이름 및 SHA-1)

Android OAuth 클라이언트는 Google Sign-In을 다음에 연결합니다: 패키지 이름 및 SHA-1 서명 인증서의

1. 클릭 클라이언트 생성 다음을 선택하세요: Android.

2. 다음을 입력하세요: 패키지 이름 앱에서 (예: com.example.app, 일치하는 applicationId Gradle에서).

3. 다음으로 가져오기 SHA-1 인증서 지문 테스트 중인 빌드에 서명하는 키스토어의 경우:

   keytool -list -v -keystore path-to-debug-or-production-keystore -alias your-key-alias

   기본 디버그 키스토어의 경우, Google에 따르면 비밀번호는 보통 android 이고, 경로는 일반적으로 ~/.android/debug.keystore.

4. SHA-1을 폼에 붙여넣고 클릭하세요 생성.

5. Android 복사 클라이언트 ID. Google은 일반적으로 하지 마세요 이 유형의 client secret을 발급하지 않습니다.

앱이 Google Play에 있다면, 다음도 등록하세요: Play App Signing을 Play Console의 SHA-1 앱 무결성. Play는 업로드 키스토어와 다른 키로 릴리스를 재서명합니다.

iOS 클라이언트 (Bundle ID)

1. 클릭 클라이언트 생성 다음을 선택하세요: iOS.
2. 다음을 입력하세요: Bundle ID Xcode에서 (다음 값과 동일) CFBundleIdentifier 에서 Info.plist, 예: com.example.app).
3. 선택적으로 추가 App Store ID 및 팀 ID Google이 요청할 때 입력하세요.
4. 클릭 생성 iOS 클라이언트 ID.

이 클라이언트를 네이티브 iOS Google Sign-In 또는 @capgo/capacitor-social-login Capacitor에 Apple 및 Google 제공자를 설정할 때.

직접 클릭하며 UI를 비교하고 싶다면 이 가이드가 괜찮은 시각적 참고 자료입니다:

기존 클라이언트 ID 찾기

생성 후 열기 Google Auth 플랫폼 > 클라이언트 또는 API 및 서비스 > 사용자 인증 정보. 각 행에는 이름과 유형별로 OAuth 2.0 클라이언트 ID가 나열됩니다. 클라이언트를 열면 해당 클라이언트 ID 문자열(xxxx.apps.googleusercontent.com). 웹 클라이언트에도 표시됩니다 클라이언트 시크릿 같은 상세 페이지에서 관리할 수 있습니다.

동의 화면은 단순한 장식이 아닙니다. 신뢰 경계(trust boundary)의 일부입니다. 사용자는 내부 프로젝트 별칭이 아니라 애플리케이션 이름을 보게 됩니다.

클라이언트 ID와 클라이언트 시크릿

Google은 웹 애플리케이션 서버에서 실행되는 클라이언트를 비공개 시크릿을 사용할 수 있는 클라이언트로 분류합니다. Android, iOS 및 기타 설치되어 있는지 클라이언트는 공개 clients. Google은 APK나 IPA에 포함된 내용은 사용자가 추출할 수 있으므로 의도적으로 시크릿을 생략합니다.

시크릿을 얻기 위해 모바일 앱에 Web 클라이언트를 만들지 마세요. 이러한 불일치는 invalid_client, DEVELOPER_ERROR, 그리고 이후 혼란스러운 토큰 오디언스 오류를 유발합니다.

Google Client ID란 무엇인가요?

어떤 Google OAuth 2.0 클라이언트 ID 는 Google 인증 시스템에서 애플리케이션의 공개 식별자입니다. Google은 인증 엔드포인트에서 액세스 토큰을 요청할 때 애플리케이션의 고유한 사용자 이름으로 설명하며, 토큰 교환 시 앱의 신원을 검증하는 OAuth 플로우에서 사용되므로 API 키와 구별된다고 언급합니다. 자세한 내용은 Google Cloud의 OAuth 클라이언트 문서.

다음과 같이 생각하세요. Google client id 앱의 공개 사용자 이름.

이 값은 Google에 “이 요청은 해당 등록된 애플리케이션에서 온 것입니다”라고 알립니다. 로그인, 동의, 토큰 교환, 그리고 앱이 사용자를 대신해 동작을 요청하는 모든 플로우에서 중요합니다. 클라이언트 ID는 앱과 Google 인증 서버 양쪽에서 참조되도록 설계되었습니다.

사람들이 헷갈리는 이유는 이 자격 증명이 서로 다른 두 개념과 나란히 놓여 있는데, 이 세 가지는 서로 대체할 수 없기 때문입니다.

클라이언트 ID OAuth에서 앱을 식별합니다.
API 키 위임된 사용자 인증이 포함되지 않는 특정 API 호출에서 프로젝트를 식별합니다.
클라이언트 시크릿 비밀을 안전하게 유지할 수 있는 플로우와 앱 유형에서만 사용되는 기밀 대응 값입니다.

이 세 가지를 같은 것의 변형으로 취급하는 순간, 많은 깨진 통합이 시작됩니다. 이 세 가지는 다릅니다.

필요하다면 Google로 로그인 또는 원탭(One Tap), 클라이언트 ID는 프론트엔드에서 인증 핸드셰이크를 시작할 때 사용하는 값입니다. Google 문서에 따르면 자격 증명을 생성하려면 먼저 앱을 전용 Cloud Console 프로젝트에 등록해야 하며, 웹 앱은 전체 스킴과 호스트 이름이 포함된 승인된 JavaScript 원본 또는 리디렉션 URI를 설정해야 합니다.

하이브리드 앱을 개발하는 팀에게 가장 안전한 멘탈 모델은 다음과 같습니다:

• 클라이언트 ID로 앱을 식별합니다
• 동의 화면으로 사용자에게 앱을 보여줍니다
• 올바른 앱 유형으로 흐름에 시크릿이 포함되어야 하는지 판단합니다

앱 ID와 위임된 액세스가 어떻게 맞물리는지 더 자세히 알고 싶다면, 이 앱 권한 부여 가이드를 좋은 복습 자료입니다. Capacitor의 OAuth2를 끝에서 끝까지 다루는 내용은 Capacitor 앱에서 OAuth2.

플랫폼별 Client ID 설정

Google 로그인 설정을 망치는 가장 빠른 방법은 하나의 client ID로 모든 플랫폼을 커버할 수 있다고 가정하는 것입니다. 불가능합니다. 멀티플랫폼 앱의 경우 각 플랫폼마다 고유한 OAuth 2.0 client ID를 등록해야 하며, 특히 Android 설정에서는 소유권 확인을 위해 SHA1 fingerprint가 필요합니다. 자세한 내용은 Google의 Android 클라이언트 설정 안내.

사용자에게는 하나의 앱일 수 있지만, Google 입장에서는 여러 개의 OAuth client입니다.

어떤 웹 앱, Android 빌드, iOS 빌드, 데스크톱 앱 동일한 보안 특성을 제공하지 않습니다. Google은 각 플랫폼에 고유한 앱 등록 모델을 제공하여 이를 처리합니다.

실무에서 따라야 할 구분은 다음과 같습니다:

• 웹 웹 클라이언트 ID를 사용하고, Origin과 Redirect URI를 엄격하게 매칭합니다.
• Android 패키지 ID와 SHA1 지문에 연결된 Android 클라이언트 ID를 사용합니다.
• iOS 앱의 bundle identity에 연결된 iOS client ID를 사용합니다.
• Desktop 또는 Electron 비밀 기반 브라우저 플로우 대신 설치형 또는 데스크톱 스타일 OAuth 패턴을 사용하는 경우가 많습니다.

Google Client ID 유형 비교

모바일과 데스크톱의 클라이언트 시크릿 역설

모바일 및 데스크톱 개발자는 모든 OAuth 클라이언트에 client ID 및 클라이언트 시크릿. 그런 다음 웹 애플리케이션 credential을 생성합니다. 콘솔에서 secret을 볼 수 있는 유일한 방법이니까요.

Google의 OAuth 클라이언트 가이드에 따르면, Android, iOS, 설치형 앱과 같은 비웹 애플리케이션 유형은 사용자가 추출할 수 있는 클라이언트 측 소프트웨어에 기밀 secret이 내장되는 것을 원치 않기 때문에 의도적으로 client ID만 제공하고 client secret은 제공하지 않는 경우가 많습니다.

Capacitor 팀의 경우, 이는 보통 두 가지 나쁜 패턴 중 하나로 나타납니다:

1. 앱이 웹 클라이언트 를 사용하여 브라우저 기반 플로우를 시작하고, 그 후 기밀 서버처럼 동작하려고 합니다.
2. 앱이 클라이언트 시크릿 번들된 code에서 가져오므로, 시크릿을 사용하는 의미가 사라집니다.

더 나은 접근 방식은 모바일 및 데스크톱 앱을 공개 클라이언트. 백엔드가 관여하는 경우, 기밀 작업은 백엔드에서 처리하고 네이티브 앱은 공개 클라이언트가 수행해야 할 작업으로 제한하세요.

Firebase 기반 Android 로그인에서 또 다른 미묘한 점이 중요합니다. 해당 설정에서 웹 애플리케이션 유형 클라이언트 ID 는 백엔드 서버의 OAuth 클라이언트 ID로 사용되며, Android 앱은 자체 플랫폼별 ID를 유지합니다. 역할이 다릅니다.

하나의 규칙만 기억한다면, 이 규칙을 사용하세요: 원하는 자격 증명 형태가 아니라 code가 실행되는 위치에 맞는 클라이언트 유형을 선택하세요.

Google API 자격 증명 보호하기

대부분의 OAuth 사고는 복잡한 공격 때문이 아닙니다. 팀이 자격 증명을 누출하거나 리다이렉트 설정을 과도하게 넓히거나, 처음부터 안전하지 않은 곳에 시크릿을 저장하기 때문입니다.

Google의 OAuth 가이드라인은 클라이언트 시크릿 을 자신이 제어하는 서버에 있어야 하는 기밀 자격 증명으로 취급합니다. Client ID 공개 식별자이지만, 여전히 신중하게 등록해야 합니다. 웹 앱의 경우 Google은 사전에 등록된 리다이렉트 URI와 Client ID를 대조합니다. 리다이렉트 URI가 정확히 일치하지 않으면 Google이 요청을 거부합니다.

몇 가지만 제대로 하려면, 이렇게 하세요:

• 앱 code에 client secret을 포함해 배포하지 마세요. Web bundle, 모바일 바이너리, Electron 패키지는 사용자가 내부를 확인할 수 있습니다.
• 정확한 redirect URI를 등록하세요. 대충 맞추는 것으로는 부족합니다. Google은 web flow에서 엄격한 일치를 검증합니다.
• Origin 범위를 좁게 유지하세요. 설정이 번거롭다고 해서 광범위한 도메인을 승인하지 마세요.
• 플랫폼별로 자격 증명을 분리하세요. 편의성 때문에 Android, iOS, web을 하나의 자격 증명으로 묶지 마세요.

문제를 피하는 팀들은 OAuth 자격 증명을 다른 프로덕션 시크릿과 동일하게 취급합니다. 웹 클라이언트 시크릿은 백엔드에 보관하고, 환경 변수 관리로 주입하며, 콘솔 접근 권한을 감사합니다. 릴리스 파이프라인을 정리 중이라면, 이 가이드에서 CI/CD 파이프라인에서 시크릿 관리하는 방법 을 인증 설정에도 적용해 볼 가치가 있습니다.

흔히 발생하는 Client ID 오류 해결하기

대부분의 Google OAuth 실패는 소수의 설정 실수에서 비롯됩니다. 에러 메시지는 항상 친절하지 않지만, 어디를 봐야 하는지 알면 근본 원인은 보통 단순합니다.

redirect_uri_mismatch

앱에서 전송한 redirect URI가 해당 web client에 등록된 값과 정확히 일치하지 않습니다. scheme, host, path, 끝부분의 차이까지 확인하세요.

invalid_client

보통 앱이 잘못된 client ID를 보내거나, 해당 client의 secret이 틀렸거나, 플랫폼 간 자격 증명을 섞고 있다는 뜻입니다.

origin_mismatch (JavaScript 플로우)

페이지 origin이 다음 항목에 등록되어 있지 않습니다: 승인된 JavaScript 원본 Web client의 경우.

Google sign-in을 활성화한 경우 client id가 최소 하나 필요합니다 (Supabase, Firebase 등 유사 대시보드)

provider 토글은 켜져 있지만 웹 클라이언트 ID 필드가 비어 있거나 잘못된 프로젝트에서 붙여넣은 값입니다. Google Cloud Console에서 OAuth 클라이언트를 생성하세요. Supabase의 경우 해당 플랫폼을 출시할 때 Web, Android, iOS 클라이언트 ID를 쉼표로 구분해 입력하고, Web 클라이언트 ID를 맨 앞에 두세요. 네이티브 클라이언트를 구성한 뒤 저장하세요. Supabase와 Capacitor를 함께 사용하는 경우 다음을 따르세요: Supabase와 함께하는 Capacitor 소셜 로그인 설정.

DEVELOPER_ERROR, error 10, 또는 Android에서 디버그에서는 sign-in이 되지만 프로덕션에서는 실패하는 경우

Android OAuth 클라이언트가 누락되었거나 패키지 이름 / SHA-1 쌍이 사용자가 실행하는 APK를 서명한 keystore와 일치하지 않습니다. 스토어 빌드에는 Play App Signing 인증서 지문을 추가하세요. 플러그인이 다음을 사용하는지 확인하세요: 웹 클라이언트 ID SDK가 서버 클라이언트 ID를 요구하는 위치로, 다음 문서에 설명된 대로 Capgo Social Login 문서.

Google Sign-In이 웹에서는 작동하지만 모바일에서는 실패하는 경우

먼저 클라이언트 유형을 확인하세요. 네이티브 플로우에서는 웹 자격 증명이 Android 또는 iOS 클라이언트를 대체할 수 없습니다.

동의 화면이 이상하게 보입니다

Google Cloud Console의 OAuth 동의 화면에서 애플리케이션 이름과 브랜딩을 확인하세요.

실용적인 디버깅 순서는 간단합니다: 먼저 클라이언트 타입, 그다음 리다이렉트 설정, 플랫폼 식별자, 마지막으로 시크릿이 플로우에 아예 포함되어야 하는지 확인하세요..

자주 묻는 질문

Web 클라이언트 ID와 Android 클라이언트 ID는 같은 Google Cloud 프로젝트에 있어야 하나요?

네. Android에서 Google Sign-In을 사용하려면 Android 클라이언트(패키지 이름 및 SHA-1)와 Web 애플리케이션 클라이언트를 같은 Google Cloud 프로젝트에 생성해야 합니다. 앱은 Web 클라이언트 ID를 서버 클라이언트 ID로 전달하며, Google은 Android 클라이언트가 같은 프로젝트에 속하는지 확인합니다. 불일치는 DEVELOPER_ERROR의 흔한 원인입니다. Capgo 소셜 로그인 플러그인 문서에 설정 방법이 나와 있습니다.

Google 클라이언트 ID란 무엇인가요?

앱 자격 증명을 생성할 때 Google이 할당하는 공개 OAuth 2.0 식별자입니다. 보통 다음과 같은 형태입니다. 123456789012-abcdefg.apps.googleusercontent.com. Google은 앱이 시작될 때 Sign in with Google을 사용하거나 authorization code를 token으로 교환할 때마다 이 값을 사용합니다.

Google client ID는 어디서 찾을 수 있나요?

Google Cloud Console에서 Google Auth 플랫폼 > 클라이언트 또는 API 및 서비스 > 사용자 인증 정보을(를) 열고, OAuth 2.0 client를 선택하세요. 클라이언트 ID 필드에 복사할 전체 문자열이 포함되어 있습니다.

Android와 iOS client에는 client secret이 포함되나요?

보통 아닙니다. 설치형 앱은 public OAuth client입니다. client secret은 서버 측에서만, 보통 웹 애플리케이션 OAuth 클라이언트.

왜 백엔드가 '최소 하나의 client id가 필요합니다'라고 말하는가요?

dashboard에서 Google sign-in이 활성화되어 있지만 client ID가 저장되지 않았습니다. Google Cloud Console에서 OAuth 클라이언트를 생성하고, 기능을 사용자에게 활성화하기 전에 Web client ID를 provider 설정에 붙여넣으세요.

Android에서 DEVELOPER_ERROR를 수정하는 방법은 무엇인가요?

기기의 서명 키에 해당하는 올바른 package name과 SHA-1로 Android OAuth 클라이언트를 등록하세요. Google Play를 통해 배포하는 경우 Play App Signing SHA-1도 포함해야 합니다. Web client ID가 인증 SDK이 기대하는 값과 일치하도록 하세요.

모든 플랫폼에서 하나의 Client ID를 재사용할 수 있나요?

아니요. Web, Android, iOS 각각에 대해 별도의 OAuth 클라이언트를 생성하세요. Capacitor 앱은 사용자가 단일 제품을 보더라도 세 가지를 모두 구성하는 경우가 많습니다.

Capacitor 또는 Electron 앱을 배포하는 팀이라면 인증 버그가 단독으로 발생하는 경우는 드뭅니다. 보통 릴리스 압박, 롤백 필요성, 환경별 수정 사항과 함께 나타나곤 합니다. Capgo 스토어 심사를 기다리지 않고 앱의 code 및 에셋에 타겟 업데이트를 배포할 수 있도록 지원합니다. 덕분에 프로덕션에 유입된 로그인 플로우, 콜백 처리, 클라이언트 측 인증 문제를 훨씬 쉽게 수정할 수 있습니다.