Google Sign-In은 금방 끝날 줄 알았는데, 막상 인증 화면을 마주하니 앱 유형에 따라 어떤 건 client secret이 나오고 어떤 건 안 나와서 당황스러우실 겁니다. Capacitor, Ionic, Electron 또는 웹과 네이티브가 혼합된 스택으로 개발 중이라면 이런 혼란은 매우 당연합니다.
대부분의 가이드가 놓치고 있지만, 실제 구현 시 문제를 일으키는 핵심은 바로 이것입니다: Google Client ID는 플랫폼별로 다릅니다, 그리고 웹이 아닌 앱 유형은 보통 설계상 client secret을 제공하지 않습니다. 억지로 secret을 만들기 위해 잘못된 인증 정보를 생성하면, 결국 디버깅하기 훨씬 까다로운 OAuth 설정 오류를 겪게 됩니다.
목차
- 앱을 Google 생태계에 연결하기
- Google Client ID란 무엇인가요?
- Client ID 생성 및 확인 방법
- 플랫폼별 Client ID 설정
- Google API 자격 증명 보안하기
- 흔히 발생하는 Client ID 오류 해결하기
앱을 Google 생태계에 연결하기
많은 팀이 동시에 이 문제에 직면합니다. 필요한 것은 Google로 로그인, 또는 Drive나 Calendar 같은 서비스에 대한 사용자 승인 권한이 필요해지면서 API 키만으로는 부족해지는 상황입니다.
이는 사용자 로그인과 위임된 액세스가 OAuth를 통해 이루어지기 때문입니다. Google은 다음을 식별할 방법이 필요합니다. 사용자의 앱단순히 호출되는 API뿐만이 아닙니다. 이를 수행하는 자격 증명은 바로 Google Client ID입니다.
크로스 플랫폼 코드베이스에서 작업하면 혼란이 더 빠르게 가중됩니다. 웹 프론트엔드, Android 셸, iOS 앱, 그리고 데스크톱용 Electron 빌드까지 있을 수 있죠. 이들은 제품 브랜딩과 백엔드 로직을 공유할 수 있지만, 하나의 OAuth identity를 모두 공유해서는 안 됩니다.
실제적인 OAuth 설정은 보통 몇 가지 구현 문제로 귀결됩니다:
- 어떤 애플리케이션 유형을 생성해야 하는가
- client secret이 필요한가
- 어떤 redirect URI 또는 origin이 정확히 일치해야 하는가
- 자격 증명을 섞지 않고 모바일과 웹 플로우를 어떻게 연결할 것인가
- 브라우저에서 작동하는 플로우가 왜 native wrapper 내부에서는 실패하는가
실무 원칙: 앱에서 사용자 권한이나 로그인을 요청한다면, API 키가 아닌 OAuth client type 관점에서 먼저 생각하세요.
이 차이를 인지하는 것이 초기에 시간을 아껴줍니다. 또한 콘솔에 필드가 더 많이 표시된다는 이유만으로 웹 자격 증명을 기반으로 모바일 로그인 플로우를 구축하는 흔한 실수를 방지해 줍니다. 만약 Capacitor 앱에 이를 구현 중이라면, 다음 가이드를 참고하세요. Capacitor 앱의 OAuth2 앱 측 워크플로우를 돕는 유용한 도구입니다.
Google Client ID란 무엇인가요?
일치하는 Google OAuth 2.0 client ID는 Google 인증 시스템에서 사용자의 앱을 식별하는 공개 식별자입니다. Google은 이를 Google 인증 엔드포인트에서 액세스 토큰을 요청할 때 사용하는 앱 전용 사용자 이름으로 정의합니다. 또한, API 키와는 다르다고 명시하는데, 이는 API 문서에서 설명하듯 토큰 교환 과정에서 앱의 신원을 확인하는 OAuth 플로우에 사용되기 때문입니다. Google Cloud의 OAuth client 문서.
간단한 개념 이해
다음과 같이 생각해보세요. Google client id 문제를 앱의 공개 사용자 이름.
이는 Google에 “이 요청은 등록된 특정 애플리케이션에서 보낸 것입니다”라고 알려주는 역할을 합니다. 로그인, 동의, 토큰 교환, 그리고 앱이 사용자를 대신해 동작해야 하는 모든 흐름에서 매우 중요합니다. Client ID는 앱과 Google 인증 서버 모두에서 참조하도록 설계되었습니다.
사람들이 흔히 혼동하는 이유는 이 인증 정보가 서로 대체할 수 없는 다른 두 가지 개념과 함께 나열되어 있기 때문입니다.
클라이언트 ID OAuth에서 앱을 식별합니다.
API 키 사용자 권한 위임이 필요 없는 특정 API 호출 시 프로젝트를 식별합니다.
클라이언트 보안 비밀번호 비밀 정보를 안전하게 보관할 수 있는 앱 유형 및 흐름에서만 사용되는 보안 인증 정보입니다.
많은 통합 오류가 이들을 동일한 개념의 변형으로 취급할 때 발생합니다. 이들은 엄연히 다릅니다.
실무에서의 Google Client ID 활용
필요한 경우 Google로 로그인 또는 원탭(One Tap), 클라이언트 ID는 프론트엔드에서 인증 핸드셰이크를 시작할 때 사용하는 값입니다. Google 문서에 따르면, 인증 정보를 생성하기 전에 반드시 전용 Cloud Console 프로젝트에 앱을 등록해야 하며, 웹 앱의 경우 전체 스킴과 호스트네임이 포함된 승인된 JavaScript 원본 또는 리다이렉트 URI를 설정해야 합니다.
단순한 키를 생성하는 것보다 설정이 까다롭게 느껴지는 이유가 바로 이것입니다. Google은 단순히 액세스를 허용하는 것이 아니라, 인증 요청을 확인된 앱 ID에 결합하기 때문입니다.
하이브리드 앱을 개발하는 팀을 위한 가장 안전한 개념 모델은 다음과 같습니다:
- 클라이언트 ID로 앱을 식별합니다
- 동의 화면(consent screen)으로 사용자에게 앱을 나타냅니다
- 올바른 앱 유형을 사용하여 인증 흐름에 secret이 필요한지 결정합니다
앱 ID와 위임된 액세스(delegated access)가 어떻게 연계되는지 더 자세히 알고 싶다면, 이 앱 인증 가이드를 참고해 보세요.
Client ID 생성 및 확인 방법
콘솔 경로가 많이 바뀌어서 개발자들이 길을 헤매는 경우가 많습니다. 하지만 대부분은 제대로 찾아온 것이 맞습니다. 현재 Google은 인증 정보를 위해 두 가지 경로를 제공합니다. 최신 경로는 Google Auth Platform > Clients 이며, 기존 경로는 APIs & Services > Credentials 입니다. 자세한 내용은 Google 설정 문서에서.
올바른 콘솔 영역에서 시작하기
Google Cloud Console을 열고 인증 설정을 관리할 프로젝트를 선택하거나 생성하세요. 인증 설정을 여러 프로젝트에 분산시키지 마세요. 나중에 감사(auditing)나 기술 지원 시 매우 번거로워집니다.
그다음, 다음 중 한 곳으로 이동하세요:
- Google Auth Platform > Clients
- API 및 서비스 > 사용자 인증 정보
팀마다 탐색 레이블이 다르게 보일 수 있지만, 이는 정상적인 현상입니다. Google은 API 자격 증명 화면에서 인증 설정 부분을 별도로 분리해 왔습니다.
제약 없이 자격 증명 생성하기
새 OAuth 클라이언트를 생성할 때 가장 중요한 결정 사항은 애플리케이션 유형입니다. Google은 다음과 같은 특정 유형을 선택하도록 요청합니다. 웹, Android, iOS, 또는 Desktop 이 선택은 단순한 외관 설정이 아닙니다. 앱을 식별하는 방식과 필요한 지원 구성을 정의합니다.
웹 앱의 경우, 다음 항목을 입력해야 합니다:
- 승인된 JavaScript 원본
- 승인된 리디렉션 URI
이 값들은 정확히 일치해야 합니다. 웹 자격 증명의 경우, Google은 단순한 도메인 개념이 아닌 https://www.example.com다음과 같이 전체 scheme과 hostname을 요구합니다.
모바일 플랫폼은 형식이 다릅니다. Android 등록에는 패키지 수준의 ID와 소유권 확인이 필요하며, iOS는 자체 플랫폼 식별자를 사용합니다. 만약 Google 인증을 다른 인증 레이어와 결합한다면, Supabase를 활용한 이 Capacitor 소셜 로그인 설정은 이러한 요소들이 어떻게 유기적으로 연결되는지 보여주는 유용한 예시입니다.
직접 클릭하며 UI를 비교해보고 싶다면, 다음 가이드를 시각적 레퍼런스로 활용하세요:
나중에 확인하는 방법
생성 후 client ID는 프로젝트의 자격 증명 목록에 표시됩니다. 동일한 프로젝트 공간에서 팀은 API를 활성화하고 OAuth identity가 동의 화면에 어떻게 연결되는지 확인할 수 있습니다. 등록된 애플리케이션 이름은 사용자가 권한 prompt를 볼 때 나타나므로, 앱 이름을 정확하게 지정하는 것이 중요합니다.
Google은 이러한 자격 증명을 지속적으로 관리할 수 있게 해줍니다. dashboard로 돌아가 client ID를 복사하거나 설정을 검토할 수 있으며, 필요한 경우 해당 자격 증명과 연결된 client secret도 관리할 수 있습니다.
동의 화면은 단순한 장식이 아닙니다. 이는 신뢰 경계의 일부입니다. 사용자는 내부 프로젝트 별명이 아닌 실제 애플리케이션 이름을 보게 됩니다.
플랫폼별 Client ID 설정
Google 로그인 설정을 망치는 가장 빠른 방법은 하나의 Client ID로 모든 플랫폼을 커버할 수 있다고 가정하는 것입니다. 불가능합니다. 멀티 플랫폼 앱의 경우 각 플랫폼마다 고유한 OAuth 2.0 Client ID를 등록해야 하며, 특히 Android 설정에서는 소유권 확인을 위해 SHA1 지문이 필요합니다. 자세한 내용은 이 플랫폼 설정 가이드에서 확인하세요..
하나의 앱에 여러 Client ID가 필요한 이유
사용자에게는 하나의 앱일지라도, Google 입장에서는 여러 개의 OAuth 클라이언트입니다.
일치하는 웹 앱, Android 빌드, iOS 빌드, 그리고 데스크톱 앱은 보안 특성이 서로 다릅니다. 신원을 증명하는 방식이 다를 뿐만 아니라, 모든 플랫폼이 신뢰할 수 있는 환경에 자격 증명을 저장하는 것도 아닙니다. Google은 각 플랫폼에 고유한 앱 등록 모델을 제공하여 이 문제를 해결합니다.
이러한 분리는 보안 관행 측면에서 매우 바람직합니다. 특정 플랫폼의 자격 증명 설정이 침해되거나 잘못 구성되더라도 다른 플랫폼이 자동으로 노출되지 않기 때문입니다.
실무에서 따라야 할 구분 방식은 다음과 같습니다:
- 웹 웹 클라이언트 ID를 사용하며, 엄격한 Origin 및 Redirect URI 매칭을 적용합니다.
- Android 패키지 ID 및 SHA1 지문과 연결된 Android 클라이언트 ID를 사용합니다.
- iOS 앱의 bundle ID와 연결된 iOS 클라이언트 ID를 사용합니다.
- 데스크톱 또는 Electron secret 기반의 브라우저 플로우 대신, 설치형 또는 데스크톱 스타일의 OAuth 패턴을 주로 사용합니다.
Google Client ID 유형 비교
| 애플리케이션 유형 | 기본 식별자 | Client Secret 제공 여부 | 주요 사용 사례 |
|---|---|---|---|
| 웹 | 승인된 JavaScript origin 및 redirect URI | 일반적으로 제공됨 | 브라우저 앱 및 백엔드 지원 웹 OAuth |
| Android | 패키지 ID 및 SHA1 지문 | 대부분의 경우 없음 | Android 네이티브 로그인 |
| iOS | 앱 번들 식별자 | 대부분의 경우 없음 | iPhone 및 iPad 네이티브 로그인 |
| 데스크톱 | 설치된 앱 identity | 대부분의 경우 없음 | Electron 방식의 네이티브 플로우를 포함한 데스크톱 앱 |
모바일 및 데스크톱의 client secret 역설
많은 튜토리얼이 이 부분을 놓치곤 합니다.
모바일 및 데스크톱 개발자들은 보통 모든 OAuth 클라이언트가 다음 두 가지를 모두 제공할 것이라고 기대합니다. 클라이언트 ID 와 클라이언트 보안 비밀번호. 그래서 개발자들은 콘솔에서 secret을 확인할 수 있는 유일한 방법인 웹 애플리케이션 자격 증명을 생성하곤 합니다. 흐름이 더 완벽해 보이기 때문이죠. 하지만 나중에 인증 과정에서 예상치 못한 오류가 발생하게 됩니다.
다음 모바일 자격 증명 불일치에 대한 설명에 따르면, Android, iOS 및 설치형 앱과 같은 비 웹 애플리케이션 유형은 의도적으로 client ID만 받고 client secret은 받지 않는 경우가 많습니다. Google은 사용자가 추출할 수 있는 클라이언트 측 소프트웨어에 보안이 중요한 secret이 포함되는 것을 원치 않기 때문입니다.
이러한 설계 방식은 옳습니다. 모바일 앱이나 Electron bundle은 안전한 secret 저장소가 될 수 없습니다.
올바른 방법: 퍼블릭 클라이언트를 위해 설계된 Native 또는 클라이언트 사이드 OAuth 플로우입니다.
반면, 다음은 권장하지 않습니다: 구현 과정에서 억지로 secret을 사용하려고 모바일 앱용 웹 자격 증명을 만드는 경우입니다.
Capacitor 팀의 경우, 보통 다음 두 가지 잘못된 패턴이 나타납니다:
- 앱이 다음을 사용하여 브라우저 기반 플로우를 실행하고, web client를 사용하면서 마치 보안이 유지되는 서버처럼 동작하려 할 때입니다.
- 앱에서 다음을 전송합니다: client secret을 번들링된 code에서 추출될 수 있으므로, 이는 시크릿을 사용하는 의미가 없습니다.
더 나은 접근 방식은 모바일 및 데스크톱 앱을 public clients로 취급하는 것입니다.. 최신 OAuth에서는 일반적으로 클라이언트 내부에 secret을 숨기지 않는 플로우를 사용합니다. 백엔드가 관여한다면 보안이 필요한 작업은 백엔드에서 처리하고, 네이티브 앱은 public client의 역할만 수행하도록 제한해야 합니다.
Firebase 기반 Android 로그인 시 주의해야 할 미묘한 차이점이 하나 더 있습니다. 이 설정에서는, web application 타입의 client ID를 백엔드 서버의 OAuth client ID로 사용하며, Android 앱은 자체적인 플랫폼 전용 identity를 유지합니다. 개발팀은 동일한 프로젝트 내에서 web 자격 증명과 mobile 자격 증명을 모두 보게 되므로, 하나가 다른 하나를 대체한다고 오해하여 혼란을 겪곤 합니다. 하지만 그렇지 않습니다. 두 자격 증명은 서로 다른 역할을 수행합니다.
딱 한 가지만 기억해야 한다면, 이 규칙을 따르세요: code가 실행되는 환경에 맞는 client type을 선택하세요. 원하는 자격 증명의 형태를 기준으로 선택해서는 안 됩니다..
Google API 자격 증명 보안하기
대부분의 OAuth 사고는 복잡한 공격 때문에 발생하지 않습니다. 팀에서 자격 증명을 유출하거나, 리다이렉트 설정을 너무 넓게 잡거나, 처음부터 안전하지 않은 곳에 secret을 저장하기 때문에 발생합니다.
Google의 OAuth 가이드는 client ID와 secret을 개인 데이터로 취급해야 한다고 강조하며, 웹 앱의 경우 client ID를 사전에 등록된 redirect URI와 대조하여 검증합니다. 리다이렉트 URI가 엄격하게 일치하지 않으면 Google은 요청을 거부합니다. 이러한 origin binding은 다음 가이드에서 설명하는 토큰 탈취 방지책의 일부입니다. OAuth.com의 client registration 가이드.
즉시 보안 조치를 취해야 할 항목들
딱 몇 가지만 제대로 관리한다면, 다음 사항을 지키세요:
- 앱 code에 client secret을 절대 포함하지 마세요. Web bundle, 모바일 바이너리, Electron 패키지는 사용자가 내부를 조사할 수 있습니다.
- 정확한 redirect URI를 등록하세요. 대충 설정해서는 안 됩니다. Google은 웹 플로우에서 엄격한 일치 여부를 검증합니다.
- Origin 범위를 좁게 유지하세요. 설정의 번거로움을 피하려고 광범위한 도메인에 권한을 부여하지 마세요.
- 플랫폼별로 자격 증명을 분리하세요. 편의성 때문에 Android, iOS, web을 하나의 자격 증명으로 통합하지 마세요.
놓치기 쉬운 운영 디테일이 하나 있습니다. Google은 기존 client ID에 대해 새 secret을 생성하고 이전 것을 비활성화할 수 있게 해줍니다. 이는 secret이 노출되었을 때나 배포 프로세스를 강화할 때 매우 중요합니다.
보안 팀이 실제로 하는 일
문제를 겪지 않는 팀은 OAuth 자격 증명을 다른 프로덕션 secret과 동일하게 취급합니다.
이들은 web client secret을 백엔드에 보관하고, 환경 관리 시스템을 통해 주입하며, 콘솔 접근 권한을 감사합니다. 만약 release pipeline을 정리 중이라면, CI/CD 파이프라인의 secret 관리 가이드를 인증 설정에도 적용해 보세요.
또한 이들은 키뿐만 아니라 메타데이터도 검토합니다. OAuth 동의 화면은 사용자가 보는 클라이언트 identity와 연결되어 있습니다. 앱 이름이 모호하거나 오해의 소지가 있다면, 사용자는 prompt를 불신하거나 잘못된 앱을 승인할 가능성이 높습니다.
보안은 단순히 secret을 숨기는 것만이 아닙니다. 올바른 앱 identity, redirect target, 승인 화면이 항상 일치하도록 보장하는 것도 포함됩니다.
자주 발생하는 Client ID 오류 해결하기
대부분의 Google OAuth 실패는 몇 가지 설정 실수에서 비롯됩니다. 에러 메시지가 친절하지 않을 때도 있지만, 원인을 알면 문제는 대개 명확합니다.
대부분의 실패를 해결하는 방법
redirect_uri_mismatch
앱이 전송하는 redirect URI가 해당 web client에 등록된 것과 정확히 일치하지 않습니다. scheme, host, path 및 끝부분의 차이점을 확인하세요. web OAuth에서 정확한 일치는 보안 모델의 일부입니다.
invalid_client
이는 보통 앱이 잘못된 client ID를 보내거나, 해당 클라이언트에 맞지 않는 secret을 사용하거나, 플랫폼 간에 자격 증명을 혼용하고 있음을 의미합니다. 흔한 예로 Android 또는 iOS flow에서 실수로 web 자격 증명을 잘못된 곳에 사용하는 경우가 있습니다.
invalid_request
범위가 넓은 오류지만, 크로스 플랫폼 앱에서는 잘못된 인증 파라미터나 클라이언트 유형에 맞지 않는 인증 흐름이 원인인 경우가 많습니다. 앱이 포함해서는 안 될 곳에 secret을 넣으려 하지는 않는지, 혹은 선택한 OAuth 흐름이 다른 종류의 클라이언트를 요구하는지 확인하세요.
Google Sign-In이 웹에서는 작동하지만 모바일에서 실패하는 경우
The first thing to inspect is the client type. The most common source of error for mobile developers is creating a web application client ID just to get a client secret, when they should be using Android or iOS types that often omit the secret intentionally, as explained in 이 client secret 불일치 분석 내용을참고하세요. 만약 로그인 후 토큰 생명주기(lifecycle) 관리가 포함되어 있다면, 해당 권한 취소(revocation) 가이드도 도움이 됩니다.
자격 증명(credential) 생성 후 Android 로그인 실패
Android 클라이언트에 연결된 SHA1 지문(fingerprint)을 다시 확인하세요. 서명 ID(signing identity)가 Google이 예상하는 값과 일치하지 않으면 앱의 소유권을 올바르게 증명할 수 없습니다.
동의 화면(Consent screen)이 잘못된 경우
콘솔의 OAuth 설정에 연결된 애플리케이션 이름과 브랜딩을 확인하세요. 사용자는 화면에 보이는 내용을 보고 권한을 부여하므로, 잘못된 메타데이터는 신뢰도 문제와 고객 지원 문의를 야기합니다.
실무적인 디버깅 순서는 다음과 같습니다: 클라이언트 유형 확인, 리다이렉트 설정, 플랫폼 식별자, 그리고 해당 흐름에 secret이 포함되어야 하는지 여부 순으로 확인하세요.
Capacitor 또는 Electron 앱을 배포하는 팀이라면 인증 버그가 단독으로 발생하는 경우는 드뭅니다. 보통 릴리스 압박, 롤백 필요성, 환경별 수정 사항과 함께 나타나곤 합니다. Capgo 스토어 심사를 기다리지 않고도 앱 code 및 에셋에 타겟 업데이트를 배포할 수 있도록 도와주므로, 프로덕션 환경에서 로그인 흐름, 콜백 처리, 클라이언트 측 인증 문제가 발생했을 때 훨씬 쉽게 수정할 수 있습니다.
