인증

​

Claude Code에 로그인

• Claude Pro 또는 Max 구독: Claude.ai 계정으로 로그인합니다. claude.com/pricing에서 구독합니다.
• Claude for Teams 또는 Enterprise: 팀 관리자가 초대한 Claude.ai 계정으로 로그인합니다.
• Claude Console: Console 자격증명으로 로그인합니다. 관리자가 먼저 초대해야 합니다. API 키를 생성하거나 생성하지 않고 로그인할 수 있습니다.
• 클라우드 제공자: 조직에서 Amazon Bedrock, Google Cloud의 Agent Platform, 또는 Microsoft Foundry를 사용하는 경우 claude를 실행하기 전에 필요한 환경 변수를 설정하거나 로그인 프롬프트에서 3rd-party platform을 선택합니다. 이는 Bedrock 및 Vertex AI에 대한 대화형 설정 마법사를 시작합니다. 브라우저 로그인이 필요하지 않습니다.
• 클라우드 게이트웨이: 조직에서 자체 호스팅 Claude 앱 게이트웨이를 실행하는 경우 /login을 통해 회사 SSO로 로그인합니다. 게이트웨이에서 발급한 토큰이 세션의 유일한 자격증명입니다.

​

팀 인증 설정

• Claude for Teams 또는 Enterprise, 대부분의 팀에 권장됨
• Claude Console
• Claude apps gateway, 개발자가 IdP로 로그인하고 구성한 클라우드 제공자로 추론을 라우팅하는 자체 호스팅 게이트웨이
• Amazon Bedrock
• Google Cloud’s Agent Platform
• Microsoft Foundry

​

Claude for Teams 또는 Enterprise

• Claude for Teams: 협업 기능, 관리 도구, 청구 관리가 포함된 셀프 서비스 플랜입니다. 소규모 팀에 최적입니다.
• Claude for Enterprise: SSO, 도메인 캡처, 역할 기반 권한, 규정 준수 API, 조직 전체 Claude Code 구성을 위한 관리형 정책 설정을 추가합니다. 보안 및 규정 준수 요구 사항이 있는 대규모 조직에 최적입니다.

​

Claude Console 인증

​

API 키 없이 로그인

• Console 계정으로 로그인, (권장) 레이블: Claude Code는 해당 로그인의 OAuth 토큰을 유지하고 Anthropic 프로필로 저장합니다. API 키를 생성하지 않습니다
• API 키 생성, (레거시) 레이블: Claude Code가 Console API 키를 생성하고 다른 자격증명과 함께 저장합니다

• Amazon Bedrock, Google Cloud’s Agent Platform 또는 Microsoft Foundry 또는 AWS의 Claude Platform과 같은 클라우드 제공자에 대해 실행합니다
• 모든 설정 파일이 forceLoginOrgUUID를 설정하거나 forceLoginMethod를 "claudeai" 또는 "console"로 설정합니다
• 관리형 설정 파일, MDM 프로필 또는 캐시된 서버 관리 설정과 같은 머신의 관리형 설정 소스가 존재하지만 Claude Code가 읽을 수 없으며 다른 관리형 소스가 정책을 제공하지 않습니다

• 작성하는 프로필: Claude Code는 ANTHROPIC_PROFILE로 명명된 프로필, 활성 프로필 또는 default를 작성합니다. 해당 프로필이 페더레이션 프로필인 경우 Claude Code는 이를 덮어쓰는 대신 로그인을 거부합니다
• 로그아웃되는 대상: Claude Code는 머신에 저장된 모든 claude.ai 로그인을 로그아웃합니다
• 실행 취소 방법: /logout을 실행하면 이 로그인이 작성한 자격증명이 제거되고 취소됩니다

​

클라우드 제공자 인증

​

조직에 대한 로그인 제한

• 터미널, VS Code 확장 및 Agent SDK 로그인: claude.ai 계정 로그인에 대해 forceLoginOrgUUID 확인
• claude setup-token 및 /install-github-app: forceLoginMethod만 강제하므로 다른 조직에서 토큰을 발급할 수 있습니다
• 게이트웨이 로그인: forceLoginMethod: "gateway"로 선택되며 제한되지 않으며 Anthropic 조직에 대해 인증하지 않으므로 forceLoginOrgUUID가 적용되지 않습니다. 게이트웨이 ID 제공자를 사용하여 액세스를 제한합니다

• env 블록: Claude Code v2.1.223 이상에서 키별로 병합
• 교차 소스 잠금 키: 모든 관리 소스에서 인정됨

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN 또는 apiKeyHelper: 환경 자격증명에 대해 조직 멤버십을 확인할 수 없으므로 시작 시 차단됨
• Amazon Bedrock과 같은 클라우드 제공자 세션: 클라우드 제공자에 대해 인증하므로 차단되지 않습니다. 클라우드 IAM 정책을 통해 이를 제한합니다
• Anthropic 프로필 또는 페더레이션 자격증명: 차단되지 않으며 키는 프로필이 속한 조직을 확인하지 않습니다

​

자격증명 관리

• 저장 위치:
  • macOS에서 자격증명은 암호화된 macOS Keychain에 저장됩니다. Keychain이 SSH 세션에서 잠긴 경우와 같이 Keychain이 쓰기를 거부하면 Claude Code는 대신 로그인을 파일 모드 0600으로 ~/.claude/.credentials.json에 저장합니다. 이는 Linux에서 사용하는 것과 동일한 저장소입니다. Keychain이 쓰기 가능할 때까지 Console 로그인이 API 키를 생성하지 못합니다. 로그인을 Keychain으로 다시 이동하려면 복구 단계를 따릅니다.
  • Linux에서 자격증명은 ~/.claude/.credentials.json에 파일 모드 0600으로 저장됩니다.
  • Windows에서 자격증명은 %USERPROFILE%\.claude\.credentials.json에 저장되며 사용자 프로필 디렉터리의 액세스 제어를 상속하므로 기본적으로 파일이 사용자 계정으로 제한됩니다.
  • CLAUDE_CONFIG_DIR 환경 변수를 설정한 경우 Claude Code는 macOS 폴백이 쓰는 파일을 포함하여 .credentials.json 파일을 해당 디렉터리 아래에 유지하고, macOS Keychain 항목도 해당 디렉터리로 키를 지정하므로 다른 CLAUDE_CONFIG_DIR을 가진 세션은 다른 항목을 읽습니다.
  • Claude Code는 /login 및 /logout을 통해 .credentials.json을 관리합니다. 요청을 사용자 정의 API 엔드포인트를 통해 라우팅하려면 대신 ANTHROPIC_BASE_URL 환경 변수를 설정합니다.
• 지원되는 인증 유형: Claude.ai 자격증명, Claude API 자격증명, Microsoft Foundry Auth, Bedrock Auth, Vertex Auth, Anthropic 프로필 및 Workload Identity Federation 자격증명, 그리고 Claude apps gateway 세션 토큰.
• 사용자 정의 자격증명 스크립트: apiKeyHelper 설정을 구성하여 API 키를 반환하는 셸 스크립트를 실행합니다.
• 새로고침 간격: Claude Code는 기본적으로 5분 후에 apiKeyHelper를 다시 실행합니다. 사용자 정의 새로고침 간격을 위해 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 환경 변수를 설정합니다. Claude Code가 도우미를 다시 실행하는 다른 경우는 apiKeyHelper를 참조합니다.
• 느린 도우미 알림: apiKeyHelper가 키를 반환하는 데 10초 이상 걸리면 Claude Code는 경과 시간을 표시하는 프롬프트 표시줄에 경고 알림을 표시합니다. 이 알림이 정기적으로 표시되면 자격증명 스크립트를 최적화할 수 있는지 확인합니다.
• 도우미 실패: 스크립트가 오류로 종료되거나 시간 초과되거나 아무것도 인쇄하지 않으면 요청은 3회 시도 내에 Your apiKeyHelper script is failing으로 실패합니다. v2.1.208 이전에는 도우미 실패가 약 10번의 자동 재시도 후 일반 401로 표시되었습니다.

​

만료되는 로그인 갱신

​

인증 우선순위

1. CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, 또는 CLAUDE_CODE_USE_FOUNDRY가 설정된 경우 클라우드 제공자 자격증명. 설정은 타사 통합을 참조합니다.
2. ANTHROPIC_AUTH_TOKEN 환경 변수. Authorization: Bearer 헤더로 전송됩니다. Anthropic API 키 대신 베어러 토큰으로 인증하는 LLM 게이트웨이 또는 프록시를 통해 라우팅할 때 사용합니다.
3. ANTHROPIC_API_KEY 환경 변수. X-Api-Key 헤더로 전송됩니다. Claude Console의 키를 사용하여 Anthropic API에 직접 액세스할 때 사용합니다. 대화형 모드에서는 키를 승인하거나 거부하도록 한 번 프롬프트되며 선택이 기억됩니다. 나중에 변경하려면 /config의 “사용자 정의 API 키 사용” 토글을 사용합니다. 토글은 ANTHROPIC_API_KEY가 환경에 설정되어 있는 동안에만 나타납니다. 비대화형 모드(-p)에서는 키가 있을 때 항상 사용됩니다.
4. apiKeyHelper 스크립트 출력. 자격증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전 자격증명에 사용합니다.
5. CLAUDE_CODE_OAUTH_TOKEN 환경 변수. claude setup-token으로 생성된 장기 OAuth 토큰입니다. 브라우저 로그인을 사용할 수 없는 CI 파이프라인 및 스크립트에 사용합니다. /login을 실행하는 동안 변수가 설정되어 있으면 Claude Code는 현재 세션을 새 로그인으로 전환하지만 변수를 셸 프로필에서 제거하거나 설정 파일의 env 블록에서 제거할 때까지 모든 새 세션에서 변수를 다시 읽습니다.
6. Anthropic 프로필 및 페더레이션 자격증명, ant CLI 및 Workload Identity Federation이 사용하는 자격증명입니다. ant auth login이 작성한 프로필은 ANTHROPIC_PROFILE에서 이름을 지정할 때만 여기에 순위가 지정되며, 그렇지 않으면 /login 아래에 순위가 지정됩니다. Anthropic 프로필 및 페더레이션 자격증명을 참조합니다.
7. /login의 구독 OAuth 자격증명. Claude Pro, Max, Team, Enterprise 사용자의 기본값입니다.

​

Anthropic 프로필 및 페더레이션 자격증명

• 명명된 프로필 또는 페더레이션 변수: ANTHROPIC_PROFILE을 설정 해제하거나 페더레이션 변수 중 하나를 설정 해제합니다
• 활성 프로필: API 키 없이 Console 계정에 로그인하여 작성한 현재 자격증명이 있는 user_oauth 프로필의 경우 /logout을 실행하고, ant auth login이 작성한 현재 자격증명이 있는 경우 ant auth logout을 실행하거나, 구성 디렉터리의 configs/에서 프로필의 파일을 삭제합니다.

​

장기 토큰 생성

claude setup-token

export CLAUDE_CODE_OAUTH_TOKEN=your-token