# 로컬부터 운영까지 인증 선택하기

사용자 ADC, 서비스 계정 가장, 애플리케이션 OAuth, Workload Identity Federation, 서비스 계정 키 파일을 비교하고 로컬과 운영 환경에 맞는 인증 방식을 선택합니다.

- 카테고리: BigQuery
- 소요 시간: 약 13분
- 난이도: 중간
- 업데이트: 2026.09.02
- 원문: /wiki/playbook/bigquery-checklist/how-to-set-up-bigquery-authentication

## 목차

- [ADC가 무엇인가](#adc)
- [인증 방식 선택표](#environment)
- [1단계 · API 확인](#step-1)
- [2단계 · 로컬 인증 적용](#step-2)
- [3단계 · 코드 연결](#step-3)
- [4단계 · 운영 인증](#step-4)
- [문제 해결](#troubleshooting)
- [코드로 인증 확인](#code-examples)
- [자주 묻는 질문](#faq)

BigQuery 클라이언트 라이브러리는 비밀번호를 직접 받지 않습니다. 대신 Google Cloud가 표준으로 제공하는 **Application Default Credentials(ADC)**를 우선 사용하지만, 로컬 인증 방식이 gcloud 하나로 제한되는 것은 아닙니다. 개인 Google 계정, 서비스 계정, 외부 ID 공급업체, 애플리케이션 OAuth 중 현재 상황에 맞는 방식을 선택할 수 있습니다.

> **이 문서 핵심**
>
> - **대상.** Node.js·Python·Java 등으로 BigQuery API를 호출하는 사용자와 애플리케이션 운영 담당자.
>
> - **준비.** 프로젝트 ID, 데이터셋 region, 필요한 IAM 역할.
>
> - **완료 후.** 환경과 권한 모델에 맞는 인증 방식을 선택하고 동일한 BigQuery 호출 코드를 실행합니다.

## ADC는 인증 종류가 아니라 자격 증명 탐색 규칙입니다

ADC는 애플리케이션이 자격 증명을 찾는 순서를 뜻합니다. 일반적으로 환경 변수 `GOOGLE_APPLICATION_CREDENTIALS`, 로컬 ADC 파일, Google Cloud 실행 환경에 연결된 서비스 계정 순으로 확인합니다. 환경 변수는 서비스 계정 키뿐 아니라 Workload Identity Federation의 외부 계정 구성 파일을 가리킬 수도 있습니다. 어떤 자격 증명이 선택되든 실제 데이터 접근 범위는 IAM 역할이 결정합니다.

> **정보**
>
> **gcloud는 ADC를 준비하는 방법 중 하나입니다.** `gcloud auth login`은 gcloud 명령 자체의 계정을, `gcloud auth application-default login`은 애플리케이션 라이브러리가 사용할 로컬 ADC를 준비합니다. gcloud를 사용하지 않는 경우에도 외부 계정 구성, 서비스 계정 키, OAuth 사용자 자격 증명을 클라이언트 라이브러리에 제공할 수 있습니다.

자세한 탐색 순서와 파일 위치는 Google Cloud의 [ADC 작동 방식](https://cloud.google.com/docs/authentication/application-default-credentials)을 기준으로 합니다.

## 상황에 맞는 로컬 인증 방식 고르기

![로컬 애플리케이션에서 다섯 가지 Google Cloud 인증 방식으로 분기되는 선택 지도](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/00-authentication-options.png)

> **한눈에 보기.** 같은 BigQuery 코드라도 신원을 가져오는 경로는 상황에 따라 달라집니다.

1. **A. 사용자 ADC** — 개인 PC에서 본인 Google 계정 권한으로 확인. gcloud 필요, 가장 간단.
2. **B. 서비스 계정 가장** — 운영 서비스 계정과 같은 권한으로 로컬 검증. gcloud 필요, 권장.
3. **C. 애플리케이션 OAuth** — 제품 사용자가 자신의 Google 계정을 연결. gcloud 불필요.
4. **D. Workload Identity Federation** — 회사 IdP·AWS·Azure·CI의 기존 신원을 사용. 런타임 gcloud 불필요, 외부 환경 권장.
5. **E. 서비스 계정 키** — 다른 방식을 사용할 수 없는 제한 환경. gcloud 불필요, 최후 수단.

> **팁**
>
> **빠르게 고르기.** 혼자 로컬에서 확인하면 A, 운영 계정과 권한을 맞춰야 하면 B, 고객이 Google 로그인을 통해 자신의 BigQuery를 연결하는 제품이면 C, 회사 외부 실행 환경이면 D를 선택합니다. E는 다른 선택지가 막힌 경우에만 사용합니다.

> **주의**
>
> **API 키는 이 목록의 대체 인증 수단이 아닙니다.** API 키만으로는 비공개 BigQuery 데이터에 접근할 사용자나 서비스 계정의 신원을 증명할 수 없습니다.

## 1단계. BigQuery API 사용 설정 확인

**API 및 서비스 → API 라이브러리 → BigQuery API**로 이동합니다. 화면에 **API 사용 설정됨**이 보이면 준비된 상태입니다.

![BigQuery API가 사용 설정된 제품 상세 화면](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/01-bigquery-api-enabled.png)

> **화면 1.** 선택한 프로젝트에서 BigQuery API 활성화 상태 확인.

**CLI로 API 활성화**
```bash
gcloud services enable bigquery.googleapis.com \
  --project=hurdlers-bq-dev-guide-260902
```

API가 켜져 있어도 IAM이 없으면 쿼리나 테이블 조회는 허용되지 않습니다.

## 2단계. 선택한 로컬 인증 방식 적용

아래 A~E 중 현재 상황에 해당하는 하나를 선택합니다. 여러 방식을 동시에 설정하면 ADC 탐색 순서 때문에 예상과 다른 계정이 선택될 수 있으므로, 한 프로젝트에서는 주 인증 방식을 명확히 정합니다.

### A. 본인 Google 계정으로 사용자 ADC 만들기

개인 PC에서 본인에게 부여된 IAM 권한으로 빠르게 확인할 때 사용합니다. Google Cloud CLI 설치가 가능하고, 로컬 작업과 개인 감사 이력을 연결하려는 경우에 가장 단순합니다.

**사용자 ADC**
```bash
gcloud auth login
gcloud config set project hurdlers-bq-dev-guide-260902
gcloud auth application-default login
gcloud auth application-default set-quota-project hurdlers-bq-dev-guide-260902
```

여러 Google 계정을 쓰는 경우 명령 실행 후 활성 계정과 프로젝트를 반드시 확인합니다. 아래 캡처처럼 두 값이 모두 의도한 계정과 프로젝트여야 합니다.

![Cloud Shell에서 활성 Google 계정과 프로젝트를 확인한 결과](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/05-cloud-shell-account-project.png)

> **화면 2.** `gcloud auth list`와 `gcloud config list project` 결과.

### B. 서비스 계정을 가장한 로컬 ADC 만들기

개인 계정에 데이터 권한을 직접 주지 않고 운영 애플리케이션과 같은 서비스 계정 권한으로 확인할 때 사용합니다. 사용자에게 대상 서비스 계정의 `roles/iam.serviceAccountTokenCreator` 역할이 필요합니다.

**서비스 계정 가장**
```bash
gcloud auth application-default login \
  --impersonate-service-account=bq-app-runtime@hurdlers-bq-dev-guide-260902.iam.gserviceaccount.com
```

가장으로 만든 로컬 ADC는 C#·C++·Go·Java·Node.js·PHP·Python·Ruby·Rust 인증 라이브러리에서 지원됩니다. 사용하는 언어와 라이브러리 버전은 [로컬 ADC 공식 문서](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment)에서 다시 확인합니다.

### C. 애플리케이션의 OAuth 2.0 사용자 동의 흐름

사용자가 제품 화면에서 **Google 계정 연결**을 누르고 자신의 BigQuery 접근을 허용해야 하는 경우에 사용합니다. 이 방식은 로컬 도구 설정이 아니라 애플리케이션 기능입니다.

1. Google Cloud에서 OAuth 동의 화면과 OAuth 클라이언트를 구성합니다.
2. Authorization Code 흐름으로 사용자 동의를 받고 access token과 refresh token을 발급받습니다.
3. Google Auth 라이브러리로 사용자 credentials 객체를 만든 뒤 BigQuery 클라이언트에 전달합니다.
4. refresh token은 서버 측 보안 저장소에 암호화하고 철회·재동의 흐름을 함께 구현합니다.

> **정보**
>
> 개인 PC에서 내부 업무를 확인하는 용도로 OAuth 앱을 새로 만드는 것은 과합니다. 여러 최종 사용자가 각자의 Google 계정을 연결해야 하는 제품 기능일 때 선택합니다.

데스크톱·설치형 앱의 세부 흐름은 Google의 [OAuth 2.0 설치형 앱 가이드](https://developers.google.com/identity/protocols/oauth2/native-app)를 따릅니다.

### D. Workload Identity Federation 구성 파일 사용

회사 IdP, AWS, Azure, GitHub Actions 같은 외부 환경의 신원을 Google Cloud 단기 자격 증명으로 교환합니다. 관리자가 공급업체별 external account 구성 파일을 만든 뒤 그 경로를 ADC에 제공합니다.

**외부 계정 구성 파일을 ADC에 연결**
```bash
export GOOGLE_APPLICATION_CREDENTIALS="/secure/path/external-account.json"
npm run start
```

외부 계정 구성 파일 자체는 서비스 계정 비공개 키를 포함하지 않지만, 파일이 호출하는 subject token 공급 경로와 실행 권한까지 함께 보호해야 합니다. 공급업체별 설정은 [Workload Identity Federation 문서](https://cloud.google.com/iam/docs/workload-identity-federation)를 따릅니다.

### E. 서비스 계정 JSON 키 파일 사용

사용자 계정, 가장, 외부 ID 연동을 사용할 수 없는 제한된 환경의 예외 선택지입니다. 키를 발급받았다면 소스 코드에 값을 복사하지 않고 파일 경로를 ADC에 제공합니다.

**macOS·Linux**
```bash
export GOOGLE_APPLICATION_CREDENTIALS="/secure/path/bq-app-runtime.json"
```

**Windows PowerShell**
```powershell
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\secure\bq-app-runtime.json"
```

ADC 대신 클라이언트에 파일을 명시적으로 전달할 수도 있지만, 같은 장기 키를 사용하는 방식입니다.

**Node.js에서 키 파일 경로 명시**
```typescript
const bigquery = new BigQuery({
  projectId: "hurdlers-bq-dev-guide-260902",
  keyFilename: "/secure/path/bq-app-runtime.json",
});
```

**Python에서 credentials 객체 전달**
```python
from google.cloud import bigquery
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(
    "/secure/path/bq-app-runtime.json"
)
client = bigquery.Client(
    project="hurdlers-bq-dev-guide-260902",
    credentials=credentials,
)
```

> **주의**
>
> 서비스 계정 키는 기본적으로 장기 자격 증명이며 파일을 가진 누구나 서비스 계정 권한을 사용할 수 있습니다. 저장소·컨테이너 이미지에 포함하지 않고, 사용 목적·소유자·만료·교체·폐기 절차를 함께 관리합니다. 가능해지는 즉시 가장이나 Workload Identity Federation으로 전환합니다.

키를 사용해야 한다면 Google Cloud의 [서비스 계정 보안 권장사항](https://cloud.google.com/iam/docs/best-practices-service-accounts)을 운영 기준에 포함합니다.

## 3단계. 클라이언트 코드에서 프로젝트와 region 명시

A·B·D 방식과 E의 환경 변수 방식은 공식 BigQuery 클라이언트가 ADC를 통해 자동으로 인식합니다. C의 OAuth credentials나 E의 키 파일을 코드에서 명시적으로 전달하는 경우만 클라이언트 생성부가 달라집니다. 인증 방식과 별개로 프로젝트 ID와 location은 항상 명시합니다.

**Node.js 조회 예시**
```typescript
import { BigQuery } from "@google-cloud/bigquery";

const bigquery = new BigQuery({ projectId: "hurdlers-bq-dev-guide-260902" });

const [rows] = await bigquery.query({
  query: "SELECT order_id, order_status FROM `hurdlers-bq-dev-guide-260902.developer_guide.orders` WHERE order_date = @orderDate",
  params: { orderDate: "2026-09-02" },
  location: "asia-northeast3",
  maximumBytesBilled: "1073741824",
  labels: { app: "orders-api", env: "dev" },
});

console.log(rows);
```

**Python 조회 예시**
```python
from google.cloud import bigquery

client = bigquery.Client(project="hurdlers-bq-dev-guide-260902")
job_config = bigquery.QueryJobConfig(
    query_parameters=[bigquery.ScalarQueryParameter("order_date", "DATE", "2026-09-02")],
    maximum_bytes_billed=1_073_741_824,
    labels={"app": "orders-api", "env": "dev"},
)

rows = client.query_and_wait(
    "SELECT order_id, order_status FROM `hurdlers-bq-dev-guide-260902.developer_guide.orders` WHERE order_date = @order_date",
    location="asia-northeast3",
    job_config=job_config,
)
```

> **팁**
>
> 문자열 연결로 사용자 값을 SQL에 삽입하지 말고 **named parameter**를 사용하세요. 파라미터 값은 쿼리 로그에서 가려지고, 타입 검증과 SQL 인젝션 방어에도 도움이 됩니다.

## 4단계. 운영 환경에 서비스 신원 연결

운영 애플리케이션마다 전용 서비스 계정을 만들고, 필요한 프로젝트·데이터셋에 최소 역할만 부여합니다. 사람 계정을 운영 런타임에 사용하지 않습니다.

![Google Cloud 서비스 계정 목록의 만들기 버튼](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/02-service-account-create.png)

> **화면 3.** IAM 및 관리자에서 **서비스 계정 만들기** 선택.

![BigQuery 애플리케이션 런타임 서비스 계정 입력 예시](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/03-service-account-form.png)

> **화면 4.** 표시 이름·ID·용도를 알아볼 수 있게 작성.

- 쿼리 작업 프로젝트: `roles/bigquery.jobUser`
- 조회 대상 데이터셋: `roles/bigquery.dataViewer`
- 결과를 쓰는 데이터셋: 필요한 경우에만 `roles/bigquery.dataEditor`

Cloud Run에서는 서비스 설정에 전용 서비스 계정을 연결합니다. ADC가 메타데이터 서버에서 단기 자격 증명을 자동으로 받아 코드 변경 없이 동작합니다.

![워크로드 아이덴티티 풀 시작 화면](/wiki-assets/playbook/how-to-set-up-bigquery-authentication/04-workload-identity-pool.png)

> **화면 5.** Google Cloud 외부 환경은 Workload Identity Federation으로 연결.

외부 워크로드 인증은 Google Cloud의 [Workload Identity Federation 문서](https://cloud.google.com/iam/docs/workload-identity-federation)를 기준으로 구성합니다.

## 문제 해결 순서

| 증상 | 확인 순서 |
| --- | --- |
| `DefaultCredentialsError` | 환경 변수 경로 → 로컬 ADC 파일 → 연결된 서비스 계정 순으로 확인 |
| 서비스 계정 가장 403 | 대상 계정의 Service Account Token Creator 역할과 IAM Credentials API |
| OAuth `invalid_grant` | refresh token 철회·만료, OAuth 클라이언트, redirect URI |
| WIF 토큰 교환 실패 | issuer·audience·subject token·attribute mapping과 시스템 시간 |
| 키 파일을 찾지 못함 | 절대 경로·파일 권한·컨테이너 마운트와 환경 변수 적용 범위 |
| `403 bigquery.jobs.create` | 쿼리 작업 프로젝트의 Job User 역할 |
| `403 getData` | 대상 데이터셋의 Data Viewer 역할 |
| `403 serviceusage.services.use` | quota project 설정과 Service Usage Consumer 권한 |
| 잘못된 프로젝트에 작업 생성 | 클라이언트 projectId, gcloud config, ADC quota project를 각각 확인 |

인증 전체 흐름은 Google Cloud [인증 방법 개요](https://cloud.google.com/docs/authentication)를 함께 참고합니다.

인증 방식을 적용한 뒤 동일한 터미널에서 연결 확인 파일을 실행해 실제로 선택된 신원과 권한을 검증합니다.

## 자주 묻는 질문

### 서비스 계정 JSON 키를 다운로드하면 더 간단하지 않나요?

초기 설정은 쉬워 보이지만 장기 키가 유출·복제·방치될 위험이 큽니다. Google Cloud 내부에서는 연결된 서비스 계정, 외부 환경에서는 Workload Identity Federation을 우선합니다.

### gcloud를 설치할 수 없으면 무엇을 선택하나요?

제품 사용자의 계정을 연결해야 하면 OAuth 2.0, 회사 IdP나 외부 실행 신원이 있으면 Workload Identity Federation을 선택합니다. 둘 다 불가능한 제한 환경에서는 관리 승인 후 서비스 계정 키 파일을 사용할 수 있습니다.

### Cloud Shell에서 되는 코드가 로컬에서는 왜 실패하나요?

Cloud Shell은 계정과 프로젝트 컨텍스트가 미리 준비되지만 로컬은 ADC가 별도입니다. gcloud CLI 로그인만 하지 않았는지, application-default login까지 실행했는지 확인합니다.

### 프로젝트 ID를 환경 변수로 관리해도 되나요?

네. 환경별 프로젝트 ID와 데이터셋 이름은 설정으로 분리하는 것이 좋습니다. 다만 자격 증명 자체를 일반 설정에 섞지 않습니다.

## Navigation

- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)

### BigQuery

- [BigQuery](/wiki/playbook/bigquery-checklist)
- [BigQuery 온보딩](/wiki/playbook/bigquery-checklist/bigquery-onboarding-guide)
- [BigQuery 인증 설정](/wiki/playbook/bigquery-checklist/how-to-set-up-bigquery-authentication) (현재 문서)
- [BigQuery 데이터셋·테이블 설계](/wiki/playbook/bigquery-checklist/bigquery-dataset-and-table-design-guide)
- [BigQuery 쿼리·비용 제어](/wiki/playbook/bigquery-checklist/bigquery-query-and-cost-control-guide)
- [BigQuery 쓰기·MERGE·CDC](/wiki/playbook/bigquery-checklist/bigquery-data-write-and-cdc-guide)
- [BigQuery 코드 예제 모음](/wiki/playbook/bigquery-checklist/bigquery-code-examples)
- [BigQuery로 들어오는 GA4 데이터](/wiki/playbook/bigquery-checklist/what-is-ga4-data-in-bigquery)
- [BigQuery Studio 인터페이스 이해하기](/wiki/playbook/bigquery-checklist/what-is-bigquery-studio-interface)
- [BigQuery 예상 비용](/wiki/playbook/bigquery-checklist/how-to-estimate-bigquery-costs)
- [무료 버전(샌드박스) 해제해야 하는 이유](/wiki/playbook/bigquery-checklist/why-upgrade-from-bigquery-sandbox)
- [GA4 BigQuery 데이터를 왜 평탄화해야 하나](/wiki/playbook/bigquery-checklist/why-flatten-ga4-bigquery-data)
- [Log Router란?](/wiki/playbook/bigquery-checklist/what-is-log-router)
- [Pub/Sub이란?](/wiki/playbook/bigquery-checklist/what-is-pubsub)
- [Cloud Functions이란?](/wiki/playbook/bigquery-checklist/what-is-cloud-function-and-run)
- [GA4 export 시점에 예약 쿼리 자동 실행하기](/wiki/playbook/bigquery-checklist/how-to-trigger-scheduled-query-on-ga4-export)
- [테이블 정의서는 왜 필요한가](/wiki/playbook/bigquery-checklist/why-table-definition-doc)
- [Event_Flat 테이블 이해하기](/wiki/playbook/bigquery-checklist/what-is-event-flat-table)
- [Item_Performance 테이블 이해하기](/wiki/playbook/bigquery-checklist/what-is-item-performance-table)