OAuth 2.0 인증

Claude Code는 OAuth 2.0 + PKCE(Proof Key for Code Exchange) 흐름을 사용하여 사용자를 인증합니다. API 키 대신 OAuth를 채택한 이유는 키 유출 위험 제거, 범위 기반 권한 관리, 그리고 구독 상태와의 자동 연동입니다.

인증 시스템의 핵심 구성 요소:

• PKCE 흐름: 17단계 시퀀스로 인가 코드 교환을 안전하게 수행
• 이중 인증 경로: 자동(브라우저 리다이렉트)과 수동(복사-붙여넣기) 모드의 경쟁
• 토큰 저장: macOS keychain 또는 plaintext 파일에 안전하게 보관
• 토큰 갱신: 만료 5분 전 선제적 갱신으로 세션 중단 방지

전체 OAuth PKCE 인증 흐름은 17개 단계로 구성됩니다.

// auth/oauth.ts — PKCE 챌린지 생성
function generatePKCE(): { verifier: string, challenge: string } {
  const verifier = base64url(randomBytes(32))
  const challenge = base64url(
    createHash('sha256').update(verifier).digest()
  )
  return { verifier, challenge }
}

두 인증 경로는 동시에 시작되어 먼저 완료된 쪽이 사용됩니다.

자동 인증 (브라우저 리다이렉트)

시스템 기본 브라우저를 열어 인증 URL로 리다이렉트합니다. 로컬에 AuthCodeListener 서버가 실행되어 콜백을 수신합니다. 사용자가 브라우저에서 로그인하면 자동으로 인가 코드가 CLI에 전달됩니다.

수동 인증 (복사-붙여넣기)

브라우저를 열 수 없는 환경(SSH, 컨테이너, 헤드리스 서버)에서는 인증 URL을 터미널에 출력합니다. 사용자가 URL을 복사하여 다른 기기의 브라우저에 붙여넣고, 인증 후 표시되는 코드를 CLI에 입력합니다.

// auth/oauth.ts — 자동/수동 인증 경쟁
async function authenticate(): Promise<TokenSet> {
  const { verifier, challenge } = generatePKCE()
  const state = randomUUID()

  // 두 경로를 동시에 시작
  const autoAuth = startAutoAuth(challenge, state)    // 브라우저 오픈
  const manualAuth = startManualAuth(challenge, state) // URL 표시

  // 먼저 완료된 쪽의 코드 사용
  const code = await Promise.race([autoAuth, manualAuth])

  // 토큰 교환
  return exchangeCodeForTokens(code, verifier)
}

AuthCodeListener는 자동 인증 흐름에서 콜백을 수신하는 로컬 HTTP 서버입니다.

// auth/listener.ts — 로컬 콜백 서버
class AuthCodeListener {
  private server: Server
  private port: number

  async start(): Promise<void> {
    this.server = createServer(this.handleCallback)
    // 포트 0으로 바인딩 → OS가 사용 가능한 포트 할당
    await listen(this.server, 0, '127.0.0.1')
    this.port = (this.server.address() as AddressInfo).port
  }

  private handleCallback(req, res): void {
    const url = new URL(req.url, `http://localhost:${this.port}`)
    const code = url.searchParams.get('code')
    const state = url.searchParams.get('state')

    // state 검증 후 코드 반환
    if (state === this.expectedState) {
      this.resolve(code)
      res.end('인증 완료! 터미널로 돌아가세요.')
    }
  }
}

포트 0 바인딩은 OS가 사용 가능한 임시 포트를 자동 할당합니다. 이를 통해 포트 충돌을 피하고, 할당된 포트 번호는 리다이렉트 URI에 동적으로 포함됩니다.

Claude Code는 6개의 OAuth 범위를 요청합니다. 각 범위는 특정 기능에 매핑됩니다.

1. openid — OIDC 표준 식별자 토큰
2. profile — 사용자 이름, 아바타 등 프로필 정보
3. email — 이메일 주소 접근
4. offline_access — refresh_token 발급 (오프라인 갱신)
5. claude:read — Claude API 읽기 권한 (대화, 모델 정보)
6. claude:write — Claude API 쓰기 권한 (메시지 전송, 도구 실행)

// auth/oauth.ts — 요청 범위
const OAUTH_SCOPES = [
  'openid',
  'profile',
  'email',
  'offline_access',
  'claude:read',
  'claude:write',
]

토큰 교환 직후 프로필 API를 호출하여 사용자 정보와 구독 상태를 가져옵니다. 구독 플랜에 따라 사용 가능한 기능이 결정됩니다.

// auth/profile.ts — 프로필 및 구독 가져오기
async function fetchProfile(accessToken: string): Promise<UserProfile> {
  const response = await fetch('https://api.anthropic.com/v1/me', {
    headers: { Authorization: `Bearer ${accessToken}` },
  })
  const data = await response.json()

  return {
    userId: data.id,
    email: data.email,
    name: data.name,
    plan: mapSubscription(data.subscription),  // 플랜 → 기능 매핑
  }
}

// 구독 플랜별 기능 매핑
function mapSubscription(sub: Subscription): PlanFeatures {
  switch (sub.tier) {
    case 'free':       return { maxTokens: 8192,  remoteControl: false }
    case 'pro':        return { maxTokens: 32768, remoteControl: false }
    case 'max':        return { maxTokens: 65536, remoteControl: true }
    case 'enterprise': return { maxTokens: 65536, remoteControl: true }
  }
}

토큰은 플랫폼에 따라 두 가지 저장 방식 중 하나를 사용합니다.

macOS Keychain

macOS에서는 시스템 키체인에 토큰을 저장합니다. security CLI 도구를 통해 키체인에 접근하며, 이는 OS 수준의 암호화와 잠금 화면 보호를 제공합니다.

Plaintext 파일

Linux/Windows 또는 키체인 접근 실패 시 ~/.claude/auth.json에 plaintext로 저장됩니다. 파일 권한은 0600(소유자만 읽기/쓰기)으로 설정됩니다.

// auth/tokenStore.ts — 플랫폼별 토큰 저장
async function storeTokens(tokens: TokenSet): Promise<void> {
  if (process.platform === 'darwin') {
    try {
      await keychainStore('claude-code', JSON.stringify(tokens))
      return
    } catch {
      // 키체인 실패 시 plaintext 폴백
    }
  }

  // plaintext 저장 (0600 권한)
  await writeFile(AUTH_PATH, JSON.stringify(tokens), { mode: 0o600 })
}

access_token 만료 5분 전에 선제적으로 갱신을 시도합니다. 이 버퍼는 네트워크 지연이나 일시적 서버 오류를 흡수하여 사용자 세션이 중단되지 않도록 합니다.

// auth/refresh.ts — 선제적 토큰 갱신
const REFRESH_BUFFER_MS = 5 * 60 * 1000  // 5분

async function ensureValidToken(): Promise<string> {
  const tokens = await loadTokens()
  const expiresAt = tokens.issued_at + tokens.expires_in * 1000
  const now = Date.now()

  if (now + REFRESH_BUFFER_MS >= expiresAt) {
    // 만료 5분 전: 갱신 실행
    const refreshed = await refreshTokens(tokens.refresh_token)
    await storeTokens(refreshed)
    return refreshed.access_token
  }

  return tokens.access_token
}

로그아웃 흐름

claude logout 명령은 세 단계로 처리됩니다: (1) 서버에 토큰 폐기 요청, (2) 로컬 토큰 저장소 삭제, (3) 키체인에서 항목 제거. 서버 측 폐기가 실패하더라도 로컬 토큰은 반드시 삭제됩니다.

엔터프라이즈 구성

엔터프라이즈 환경에서는 MDM 정책으로 OAuth 서버 URL을 커스터마이징할 수 있습니다. com.anthropic.claude-code 도메인의 AuthServerURL 키가 인증 서버 엔드포인트를 결정합니다.

// auth/oauth.ts — 엔터프라이즈 인증 서버 해석
function getAuthServerURL(): string {
  // 1. 환경 변수 우선
  if (process.env.CLAUDE_AUTH_SERVER_URL) {
    return process.env.CLAUDE_AUTH_SERVER_URL
  }
  // 2. MDM 정책 확인
  const mdm = getMdmSetting('AuthServerURL')
  if (mdm) return mdm
  // 3. 기본값
  return 'https://auth.anthropic.com'
}