[초급] Gemini CLI 로그인 403 에러, 30분 삽질하고 알아낸 인증의 본질

결론부터 말한다. `gcloud auth application-default login` 이 명령어 하나면 끝날 줄 알았다.

착각이었다. 지난 주말, 로컬 환경에서 Gemini API 연동 테스트를 하다가 아주 기본적인 인증 단계에서 막혔다. 터미널에 선명하게 찍히는 에러 메시지는 이거였다.

PermissionDenied: 403 The caller does not have permission

API는 분명히 켜져 있는데 권한이 없다는 말. 구글 클라우드(GCP) 좀 만져봤다는 사람들도 여기서 멘탈 나간다. 직장인 열에 아홉은 이 지점에서 의미 없는 재로그인만 반복하다 시간을 태운다. 이 간단한 걸 몰라서 30분을 헤맸다.

핵심은 ‘내 컴퓨터(로컬 터미널)가 GCP 프로젝트에 자신을 제대로 증명하지 못했다’는 점이다. 그냥 로그인 명령어 한 줄만 안다고 해결될 문제가 아니었음. 초심자들이 100% 확률로 겪는 인증 오류의 대표적인 원인 3가지를 정리한다.

❌ 실수 1: 활성화된 프로젝트와 CLI의 타겟 프로젝트 불일치

가장 흔한 시나리오다. GCP 웹 콘솔에서는 ‘my-gemini-project’라는 프로젝트에 들어가서 API를 활성화시켜 놓고, 정작 내 컴퓨터 터미널은 기본 설정인 ‘my-first-project’를 가리키고 있는 상황. 이건 마치 서울집 현관문은 열어놓고, 부산집에 가서 문을 열려고 시도하는 것과 같다. 당연히 문이 열릴 리가 없음.

💡 해결책:

터미널의 현재 타겟 프로젝트부터 확인해야 한다. 아래 명령어를 입력한다.

gcloud config get-value project

만약 여기서 나온 프로젝트 ID가 당신이 API를 활성화한 프로젝트와 다르다면, 다음 명령어로 즉시 변경해야 함.

gcloud config set project [YOUR_GEMINI_PROJECT_ID]

[YOUR_GEMINI_PROJECT_ID] 부분에 실제 당신의 프로젝트 ID를 넣으면 된다. 이 간단한 확인 절차 하나가 수십 분의 삽질을 막는다.

❌ 실수 2: 계정에 ‘Vertex AI 사용자’ 역할(Role) 누락

프로젝트 설정은 맞췄는데도 같은 403 에러가 나는 경우가 있다. 이건 프로젝트라는 ‘국가’는 맞게 찾아갔는데, 그 국가에 들어갈 수 있는 ‘비자’가 없는 상태다. 즉, 로그인한 구글 계정 자체에 Gemini API를 사용할 권한이 부여되지 않은 것.

💡 해결책:

GCP 콘솔의 ‘IAM 및 관리자’ 메뉴로 이동해야 한다. 거기서 당신의 계정(주 구성원)을 찾아서 ‘역할 추가’를 눌러야 함. 검색창에 ‘Vertex AI 사용자’를 검색해서 추가하고 저장한다. 이 역할에는 Gemini API를 호출하는 데 필요한 최소한의 권한이 포함되어 있다. 시스템 아키텍처 관점에서, 딱 필요한 최소 권한만 부여하는 것은 보안의 기본이다.

❌ 실수 3: API 키와 OAuth 인증 방식의 혼동

초심자들은 API 키만 발급받으면 모든 게 해결될 거라 믿는다. API 키는 단순한 식당 입장권과 같다. 이걸로는 특정 테이블(서비스)에 앉을 자격까지 증명하진 못한다. CLI나 SDK 환경에서는 ‘누가, 어떤 권한으로’ 사용하는지 증명하는 OAuth 2.0 기반의 인증(Application Default Credentials, ADC)이 필요함. 즉, 신분증이 필요한 상황에서 입장권만 내미는 꼴이다.

💡 해결책:

우리가 맨 처음에 실행했던 gcloud auth application-default login 명령어의 본질을 이해해야 한다. 이 명령어는 API 키를 사용하는 게 아니다. 실행하면 웹 브라우저가 열리고 구글 계정으로 로그인하게 되는데, 이 과정을 통해 내 컴퓨터 특정 경로에 ‘application_default_credentials.json’ 이라는 인증서 파일이 생성된다. Gemini SDK는 코드를 실행할 때 바로 이 파일을 자동으로 찾아서 ‘아, 이 사용자는 인증된 사용자구나’라고 인식하는 메커니즘이다. API 키는 코드에 직접 하드코딩해서 쓰는 다른 방식일 뿐, CLI 인증과는 별개다.

⚙️ 최종 요약

Gemini CLI 403 인증 에러는 결국 세 가지 확인으로 요약된다.

1. 어떤 프로젝트에서? (Where): 내 터미널이 올바른 GCP 프로젝트를 가리키고 있는가?
2. 누가, 무슨 권한으로? (Who/What): 내 구글 계정에 ‘Vertex AI 사용자’ 역할이 부여되었는가?
3. 어떻게 인증했나? (How): API 키가 아닌, gcloud login 명령어로 ADC 인증 파일을 생성했는가?

이 세 가지만 기억하면 된다. 앞으로 인증 에러가 발생하면, 코드를 뒤지기 전에 이 세 가지 항목부터 체크리스트처럼 확인하는 습관을 들이는 게 정신 건강에 이롭다.

PipeMaster-Lab 운영정책 및 제보 안내