131 lines
4.4 KiB
Markdown
131 lines
4.4 KiB
Markdown
# 인증
|
|
|
|
> 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`을 사용하세요. 이것들은 대화형 흐름보다 먼저 확인됩니다.
|