# 인증

> Anthropic API, AWS Bedrock, GCP Vertex AI로 Claude Code 인증 설정 방법.

Claude Code는 여러 인증 방식을 지원합니다. 방식은 API에 직접 접근하는지, 클라우드 제공업체를 통하는지, API 키 헬퍼 스크립트를 통하는지에 따라 다릅니다.

## Claude.ai OAuth (기본)

API 키가 설정되지 않은 상태에서 `claude`를 처음 실행하면, Claude Code가 claude.ai 계정으로 OAuth 흐름을 시작합니다.

1. 터미널에서 실행: `claude`
2. URL이 표시되면 브라우저에서 열어 claude.ai 계정으로 로그인하고 권한 부여
3. 브라우저에서 인증 후 Claude Code가 자동으로 OAuth 토큰을 받아 저장합니다(macOS는 Keychain, 다른 플랫폼은 자격 증명 파일)

OAuth 토큰은 만료 전에 자동으로 갱신됩니다. 명시적으로 로그아웃하거나 접근을 취소하지 않는 한 재인증이 필요하지 않습니다.

## API 키

OAuth 대신 Anthropic API 키로 인증할 수 있습니다.

**환경 변수:**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
```
이 변수가 설정되면 Claude Code가 직접 사용하고 OAuth를 요청하지 않습니다.

**설정 파일 apiKeyHelper:**
```json
{
  "apiKeyHelper": "cat ~/.anthropic/api-key"
}
```
Claude Code가 이 커맨드를 실행해 자격 증명을 동적으로 가져옵니다. 결과는 5분 동안 캐시됩니다(`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`로 설정 가능). 커맨드는 API 키만 stdout에 출력하고 코드 0으로 종료해야 합니다.

> ⚠️ `ANTHROPIC_API_KEY`가 설정되거나 `apiKeyHelper`가 구성되면 OAuth 흐름이 비활성화됩니다.

## AWS Bedrock

AWS Bedrock을 통해 Claude를 사용하려면:

```bash
# 1. Bedrock 모드 활성화
export CLAUDE_CODE_USE_BEDROCK=1

# 2. AWS 자격 증명 설정 (표준 AWS 자격 증명 체인)
# - AWS 자격 증명 파일 (~/.aws/credentials)
# - 환경 변수: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
# - IAM 역할(EC2 인스턴스 프로파일, ECS 태스크 역할 등)
# - AWS SSO (aws sso login)

# 3. 리전 설정 (선택사항)
export AWS_REGION=us-east-1
```

**자동 AWS 자격 증명 갱신:**
세션이 만료될 경우(예: 단기 SSO 토큰) `awsAuthRefresh`를 설정해 자동으로 자격 증명을 갱신합니다:

```json
{
  "awsAuthRefresh": "aws sso login --profile my-profile"
}
```

커맨드에서 자격 증명을 내보내려면 `awsCredentialExport`를 사용합니다:

```json
{
  "awsCredentialExport": "aws sts assume-role --role-arn arn:aws:iam::123456789012:role/MyRole --role-session-name claude-code --query Credentials --output json"
}
```

## GCP Vertex AI

Google Cloud Vertex AI를 통해 Claude를 사용하려면:

```bash
# 1. Vertex 모드 활성화
export CLAUDE_CODE_USE_VERTEX=1

# 2. GCP 자격 증명 설정
# - gcloud auth application-default login (대화형)
# - GOOGLE_APPLICATION_CREDENTIALS를 통한 서비스 계정 키 파일
# - 워크로드 아이덴티티(GKE용)

# 3. 프로젝트 및 리전 설정 (선택사항)
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export CLOUD_ML_REGION=us-central1
```

**자동 GCP 자격 증명 갱신:**
```json
{
  "gcpAuthRefresh": "gcloud auth application-default login"
}
```

## 계정 전환

**다른 계정으로 로그인:**
```
/login
```
새 OAuth 흐름을 시작합니다. 저장된 토큰이 새 계정의 토큰으로 교체됩니다.

**로그아웃:**
```
/logout
```
저장된 자격 증명을 제거합니다. 다음 실행 시 인증을 요청합니다.

## 토큰 만료 및 갱신

Claude Code가 조용히 토큰 갱신을 처리합니다:
- 각 API 요청 전에 액세스 토큰 만료 여부 확인
- 만료된 경우 저장된 갱신 토큰으로 잠금을 획득하고 갱신
- 여러 동시 Claude Code 인스턴스는 잠금 파일을 통해 중복 갱신 방지
- API에서 `401` 응답이 오면 즉시 강제 갱신

## 인증 우선순위

여러 인증 소스가 설정된 경우 이 순서로 해석됩니다:

1. `ANTHROPIC_AUTH_TOKEN` 환경 변수
2. `CLAUDE_CODE_OAUTH_TOKEN` 환경 변수
3. 파일 디스크립터의 OAuth 토큰(관리형 배포용)
4. 설정의 `apiKeyHelper`
5. 저장된 claude.ai OAuth 토큰(Keychain 또는 자격 증명 파일)
6. `ANTHROPIC_API_KEY` 환경 변수

> 💡 CI 및 비대화형 환경에서는 `ANTHROPIC_API_KEY` 또는 `CLAUDE_CODE_OAUTH_TOKEN`을 사용하세요. 이것들은 대화형 흐름보다 먼저 확인됩니다.