Claude Code 인증(Authentication)

Claude Code 인증(Authentication)

Claude Code는 설정 방식에 따라 여러 인증 방법을 지원해요. 개인은 Claude.ai 계정으로, 팀은 Claude for Teams·Enterprise, Claude Console, 또는 Amazon Bedrock·Google Cloud's Agent Platform·Microsoft Foundry 같은 클라우드 제공자로 로그인할 수 있어요. 어떤 계정 형태든 claude를 처음 실행하면 브라우저 로그인 절차를 거쳐요.

출처: 공식문서

본문

Claude Code에 로그인

설치 후 터미널에서 claude를 실행하면 첫 실행 때 브라우저 창이 열려 로그인하게 해요. ANTHROPIC_API_KEY 환경변수가 설정돼 있으면 로그인 프롬프트를 건너뛰고 키 승인을 요청해요.

브라우저가 자동으로 안 열리면 c를 눌러 로그인 URL을 클립보드에 복사한 뒤 브라우저에 붙여 넣으세요. 로그인 후 브라우저가 리다이렉트 대신 로그인 코드를 보여주면, 터미널의 Paste code here if prompted 프롬프트에 붙여 넣어요. 이건 WSL2·SSH 세션·컨테이너처럼 브라우저가 로컬 콜백 서버에 닿지 못할 때 흔해요. 로그인이 완료되면 터미널에 Login successful이 뜨고 Enter를 누르면 계속돼요.

인증할 수 있는 계정 유형:

  • Claude Pro 또는 Max 구독: Claude.ai 계정으로 로그인
  • Claude for Teams 또는 Enterprise: 팀 관리자가 초대한 Claude.ai 계정
  • Claude Console: Console 자격 증명으로 로그인(관리자의 초대 필요, API 키 없이도 로그인 가능)
  • 클라우드 제공자: Amazon Bedrock·Google Cloud's Agent Platform·Microsoft Foundry를 쓰는 조직이면 claude 실행 전 필수 환경변수를 설정하거나 로그인 프롬프트에서 3rd-party platform을 선택(브라우저 로그인 불필요)
  • 클라우드 게이트웨이: 자체 호스팅 Claude apps gateway를 쓰면 /login으로 회사 SSO 로그인

로그아웃·재인증은 /logout을 입력해요. 로그아웃은 첫 실행 설정 상태도 리셋해서 다음에 claude를 실행하면 로그인·설정이 다시 진행돼요.

팀 인증 설정하기

팀·조직용으로는 다음 중 하나로 Claude Code 접근을 구성할 수 있어요.

  • Claude for Teams 또는 Enterprise(대부분 팀에 권장)
  • Claude Console
  • Claude apps gateway(자체 호스팅 게이트웨이)
  • Amazon Bedrock / Google Cloud's Agent Platform / Microsoft Foundry

Claude for Teams/Enterprise: Claude for Teams는 셀프서비스 플랜으로 협업 기능·관리자 도구·청구 관리를 제공해요(소규모 팀에 적합). Claude for Enterprise는 SSO·도메인 캡처·역할 기반 권한·컴플라이언스 API·관리형 정책 설정을 추가해요(보안/컴플라이언스가 중요한 대규모 조직에 적합). 팀원 초대는 관리자 대시보드에서, 그다음 팀원이 Claude Code를 설치하고 Claude.ai 계정으로 로그인해요.

Claude Console 인증: API 기반 청구를 선호하는 조직용이에요. 사용자 추가는 Console 내부(Settings → Members → Invite) 벌크 초대 또는 SSO 설정으로 가능해요. 초대 시 역할을 지정하는데, Claude Code 역할은 Claude Code API 키만, Developer 역할은 모든 종류의 API 키를 만들 수 있어요. 초대된 사용자는 초대 수락 → 시스템 요구사항 확인 → Claude Code 설치 → Console 계정으로 로그인을 완료해야 해요.

API 키 없이 로그인: 조직이 개발자의 키 생성을 막아도 Console 계정으로 키 없이 로그인할 수 있어요(Claude Code v2.1.242+). /login 프롬프트에서 Anthropic Console 계정을 선택하면 두 가지를 제안해요.

  • Console 계정으로 로그인 (recommended): OAuth 토큰을 Anthropic 프로필로 저장하고 API 키를 만들지 않음
  • API 키 생성 (legacy): Console API 키를 만들어 자격 증명으로 저장

프로필은 OAuth 로그인이라 자동 갱신되고, 갱신 실패 시 Anthropic profile login expired로 요청이 실패해요. 키 없는 로그인 전에는 ANTHROPIC_API_KEY를 해제해야 해요.

다음 경우는 물어보지 않고 Claude Code가 API 키를 만들어요: 클라우드 제공자/Claude Platform on AWS로 실행할 때, 어떤 설정 파일이 forceLoginOrgUUID 또는 forceLoginMethod("claudeai"/"console")를 설정했을 때.

클라우드 제공자 인증: Amazon Bedrock·Google Cloud's Agent Platform·Microsoft Foundry 팀은 각 제공자 문서를 따라 설정한 뒤 환경변수와 클라우드 자격 증명 생성 지침을 사용자에게 배포하고, 사용자가 Claude Code를 설치하면 돼요.

로그인을 조직으로 제한하기

개발자의 claude.ai 로그인이 특정 Anthropic 조직에 속하도록 하려면 관리형 설정에서 forceLoginMethod와 forceLoginOrgUUID를 설정해요. forceLoginOrgUUID를 조직 ID로 설정하면 다른 조직의 claude.ai 로그인이면 오류를 보고하고 시작 시 종료돼요. Claude Console 로그인의 경우 forceLoginOrgUUID는 Console 로그인 페이지에서 조직을 미리 선택하는 데 쓰이고, 결과 자격 증명이 어느 조직에 속하는지는 검사하지 않아요.

forceLoginOrgUUID를 어떤 설정 파일에든 설정하면 해당 파일이 적용되는 세션에서 키 없는 Console 로그인을 제공하지 않고 API 키를 만들게 돼요. 개발자를 claude.ai 로그인으로 안내하려면 forceLoginMethod를 "claudeai"로 설정하세요. v2.1.212부터 모든 로그인 경로(터미널 /login, VS Code 확장, Agent SDK, claude setup-token, /install-github-app, 게이트웨이)에 forceLoginMethod가 적용돼요.

자격 증명 관리

Claude Code는 인증 자격 증명을 안전하게 관리해요.

  • 저장 위치: macOS는 암호화된 Keychain(SSH 세션처럼 Keychain 쓰기가 거부되면 ~/.claude/.credentials.json 파일 모드 0600에 저장, Linux와 동일). Linux는 ~/.claude/.credentials.json(모드 0600). Windows는 %USERPROFILE%\.claude\.credentials.json(사용자 프로필 디렉터리의 접근 제어를 상속). CLAUDE_CONFIG_DIR을 설정하면 그 디렉터리 아래에 보관하고 macOS Keychain 항목도 그 디렉터리에 키잉해요.
  • 지원 인증 유형: Claude.ai 자격 증명, Claude API 자격 증명, Microsoft Foundry Auth, Bedrock Auth, Vertex Auth, Anthropic 프로필 및 Workload Identity Federation 자격 증명, Claude apps gateway 세션 토큰.
  • 커스텀 자격 증명 스크립트: apiKeyHelper 설정으로 API 키를 반환하는 셸 스크립트를 실행시킬 수 있어요. 기본 5분마다 재실행, CLAUDE_CODE_API_KEY_HELPER_TTL_MS로 간격 조절. 10초가 넘으면 경고 노티스를 띄워요.

apiKeyHelper, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN은 CLI와 VS Code 확장·Agent SDK·GitHub Actions에 적용돼요. Claude Desktop과 클라우드 세션은 이들을 호출하지 않고 OAuth를 사용해요.

만료 임박 로그인 갱신

/login으로 만든 로그인이 만료 3일 전이면 시작 시 Your login expires in 3 days · run /login to renew 경고가 떠요(v2.1.203+, v2.1.217부터는 5일 전 표시). /login으로 갱신하면 돼요. 경고는 정보성이라 요청을 막지 않아요. 만료되면 Login expired · Please run /login 오류로 요청이 실패할 때까지 계속돼요. /status의 Login 행이 Expired — log in again으로 보이면 갱신이 필요한 상태예요(v2.1.210+). 무인 실행 세션(agent view 백그라운드, Remote Control)은 자격 증명 만료 후 스스로 회복할 수 없으니 일찍 갱신하는 게 중요해요.

인증 우선순위

여러 자격 증명이 있을 때 Claude Code는 이 순서로 고릅니다.

  1. 클라우드 제공자 자격 증명 — CLAUDE_CODE_USE_BEDROCK/CLAUDE_CODE_USE_VERTEX/CLAUDE_CODE_USE_FOUNDRY가 설정됐을 때
  2. ANTHROPIC_AUTH_TOKEN — Authorization 헤더로 전송. bearer 토큰으로 인증하는 LLM 게이트웨이/프록시용
  3. ANTHROPIC_API_KEY — X-Api-Key 헤더로 전송. 직접 Anthropic API 접근용. 대화형 모드에선 키 승인을 한 번 물어봄
  4. apiKeyHelper 스크립트 출력 — vault에서 가져온 단기 토큰 같은 회전 자격 증명용
  5. CLAUDE_CODE_OAUTH_TOKEN — claude setup-token으로 만든 장기 OAuth 토큰. 브라우저 로그인 불가능한 CI 파이프라인용
  6. Anthropic 프로필 및 페더레이션 자격 증명 — ant CLI와 WIF가 쓰는 자격 증명
  7. /login 구독 OAuth 자격 증명 — Claude Pro·Max·Team·Enterprise 기본값

로그인한 Claude apps gateway 세션은 이 목록 밖에 있는데, 제공자 선택이라 위 항목들을 모두 오버라이드해요. 활성 Claude 구독이 있어도 ANTHROPIC_API_KEY가 환경에 설정돼 있으면 승인 후 API 키를 우선 사용해요. unset ANTHROPIC_API_KEY로 구독으로 돌아갈 수 있고 /status로 활성 인증 방식을 확인할 수 있어요.

장기 토큰 생성

CI 파이프라인·스크립트처럼 대화형 브라우저 로그인이 없는 환경에선 claude setup-token으로 1년짜리 OAuth 토큰을 생성해요.

claude setup-token

브라우저 승인 후 토큰이 터미널에 출력돼요(어디에도 저장하지 않음). 복사해서 CLAUDE_CODE_OAUTH_TOKEN으로 설정하세요.

export CLAUDE_CODE_OAUTH_TOKEN=your-token

이 토큰은 Pro·Max·Team·Enterprise 플랜을 요구하고 모델 요청만 가능해요. Remote Control 세션을 세우거나 claude.ai 커넥터를 가져올 수는 없고, 로컬로 구성한 MCP 서버는 동작해요. bare mode는 CLAUDE_CODE_OAUTH_TOKEN을 읽지 않으니 그 경우 ANTHROPIC_API_KEY나 apiKeyHelper를 쓰세요.

더 알아보기