신원 및 액세스 관리

조직에서 Claude Code의 사용자 인증, 권한 부여 및 액세스 제어를 구성하는 방법을 알아보세요.

인증 방법

Claude Code를 설정하려면 Anthropic 모델에 대한 액세스가 필요합니다. 팀의 경우 다음 세 가지 방법 중 하나로 Claude Code 액세스를 설정할 수 있습니다:

• Anthropic Console을 통한 Anthropic API
• Amazon Bedrock
• Google Vertex AI

Anthropic API 인증

Anthropic API를 통해 팀의 Claude Code 액세스를 설정하려면:

1. 기존 Anthropic Console 계정을 사용하거나 새 Anthropic Console 계정을 생성합니다
2. 아래 방법 중 하나를 통해 사용자를 추가할 수 있습니다:
   • Console 내에서 사용자를 대량 초대 (Console -> Settings -> Members -> Invite)
   • SSO 설정
3. 사용자를 초대할 때 다음 역할 중 하나가 필요합니다:
   • “Claude Code” 역할은 사용자가 Claude Code API 키만 생성할 수 있음을 의미합니다
   • “Developer” 역할은 사용자가 모든 종류의 API 키를 생성할 수 있음을 의미합니다
4. 초대받은 각 사용자는 다음 단계를 완료해야 합니다:
   • Console 초대 수락
   • 시스템 요구사항 확인
   • Claude Code 설치
   • Console 계정 자격 증명으로 로그인

클라우드 공급자 인증

Bedrock 또는 Vertex를 통해 팀의 Claude Code 액세스를 설정하려면:

1. Bedrock 문서 또는 Vertex 문서를 따르세요
2. 환경 변수와 클라우드 자격 증명 생성 지침을 사용자에게 배포합니다. 여기서 구성 관리 방법에 대해 자세히 읽어보세요.
3. 사용자는 Claude Code를 설치할 수 있습니다

액세스 제어 및 권한

에이전트가 허용되는 작업(예: 테스트 실행, 린터 실행)과 허용되지 않는 작업(예: 클라우드 인프라 업데이트)을 정확히 지정할 수 있도록 세밀한 권한을 지원합니다. 이러한 권한 설정은 버전 제어에 체크인되어 조직의 모든 개발자에게 배포될 수 있으며, 개별 개발자가 사용자 정의할 수도 있습니다.

권한 시스템

Claude Code는 권력과 안전의 균형을 맞추기 위해 계층화된 권한 시스템을 사용합니다:

도구 유형	예시	승인 필요	”예, 다시 묻지 마세요” 동작
읽기 전용	파일 읽기, LS, Grep	아니오	해당 없음
Bash 명령	셸 실행	예	프로젝트 디렉토리 및 명령별로 영구적
파일 수정	파일 편집/쓰기	예	세션 종료까지

권한 구성

/permissions로 Claude Code의 도구 권한을 보고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 해당 규칙이 소스된 settings.json 파일을 나열합니다.

• Allow 규칙은 Claude Code가 추가 수동 승인 없이 지정된 도구를 사용할 수 있도록 허용합니다.
• Ask 규칙은 Claude Code가 지정된 도구를 사용하려고 할 때마다 사용자에게 확인을 요청합니다. Ask 규칙은 allow 규칙보다 우선합니다.
• Deny 규칙은 Claude Code가 지정된 도구를 사용하는 것을 방지합니다. Deny 규칙은 allow 및 ask 규칙보다 우선합니다.
• Additional directories는 Claude의 파일 액세스를 초기 작업 디렉토리를 넘어 다른 디렉토리로 확장합니다.
• Default mode는 새로운 요청을 만날 때 Claude의 권한 동작을 제어합니다.

권한 규칙은 다음 형식을 사용합니다: Tool 또는 Tool(optional-specifier)

도구 이름만 있는 규칙은 해당 도구의 모든 사용과 일치합니다. 예를 들어, allow 규칙 목록에 Bash를 추가하면 Claude Code가 사용자 승인 없이 Bash 도구를 사용할 수 있습니다.

권한 모드

Claude Code는 설정 파일에서 defaultMode로 설정할 수 있는 여러 권한 모드를 지원합니다:

모드	설명
default	표준 동작 - 각 도구의 첫 사용 시 권한을 요청
acceptEdits	세션 동안 파일 편집 권한을 자동으로 수락
plan	계획 모드 - Claude가 분석할 수 있지만 파일을 수정하거나 명령을 실행할 수 없음
bypassPermissions	모든 권한 프롬프트를 건너뜀 (안전한 환경 필요 - 아래 경고 참조)

작업 디렉토리

기본적으로 Claude는 실행된 디렉토리의 파일에 액세스할 수 있습니다. 이 액세스를 확장할 수 있습니다:

• 시작 시: --add-dir <path> CLI 인수 사용
• 세션 중: /add-dir 슬래시 명령 사용
• 영구 구성: 설정 파일의 additionalDirectories에 추가

추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다 - 프롬프트 없이 읽을 수 있게 되고, 파일 편집 권한은 현재 권한 모드를 따릅니다.

도구별 권한 규칙

일부 도구는 더 세밀한 권한 제어를 지원합니다:

Bash

• Bash(npm run build) 정확한 Bash 명령 npm run build와 일치
• Bash(npm run test:*) npm run test로 시작하는 Bash 명령과 일치
• Bash(curl http://site.com/:*) 정확히 curl http://site.com/로 시작하는 curl 명령과 일치

Claude Code는 셸 연산자(예: &&)를 인식하므로 Bash(safe-cmd:*)와 같은 접두사 일치 규칙은 safe-cmd && other-cmd 명령을 실행할 권한을 주지 않습니다

Bash 권한 패턴의 중요한 제한사항:

1. 이 도구는 접두사 일치를 사용하며, 정규식이나 glob 패턴이 아닙니다
2. 와일드카드 :*는 패턴 끝에서만 작동하여 모든 연속을 일치시킵니다
3. Bash(curl http://github.com/:*)와 같은 패턴은 여러 방법으로 우회될 수 있습니다:
   • URL 앞의 옵션: curl -X GET http://github.com/...는 일치하지 않음
   • 다른 프로토콜: curl https://github.com/...는 일치하지 않음
   • 리디렉션: curl -L http://bit.ly/xyz (github로 리디렉션)
   • 변수: URL=http://github.com && curl $URL는 일치하지 않음
   • 추가 공백: curl http://github.com는 일치하지 않음

더 신뢰할 수 있는 URL 필터링을 위해 다음을 고려하세요:

• WebFetch(domain:github.com) 권한으로 WebFetch 도구 사용
• CLAUDE.md를 통해 허용된 curl 패턴에 대해 Claude Code에 지시
• 사용자 정의 권한 검증을 위한 훅 사용

Read & Edit

Edit 규칙은 파일을 편집하는 모든 내장 도구에 적용됩니다. Claude는 Grep, Glob, LS와 같이 파일을 읽는 모든 내장 도구에 Read 규칙을 적용하기 위해 최선의 노력을 기울입니다.

Read & Edit 규칙은 모두 네 가지 고유한 패턴 유형을 가진 gitignore 사양을 따릅니다:

패턴	의미	예시	일치
//path	파일시스템 루트에서 절대 경로	Read(//Users/alice/secrets/**)	/Users/alice/secrets/**
~/path	홈 디렉토리에서 경로	Read(~/Documents/*.pdf)	/Users/alice/Documents/*.pdf
/path	설정 파일에 상대적인 경로	Edit(/src/**/*.ts)	<설정 파일 경로>/src/**/*.ts
path 또는 ./path	현재 디렉토리에 상대적인 경로	Read(*.env)	<cwd>/*.env

/Users/alice/file과 같은 패턴은 절대 경로가 아닙니다 - 설정 파일에 상대적입니다! 절대 경로에는 //Users/alice/file을 사용하세요.

• Edit(/docs/**) - <project>/docs/에서 편집 (/docs/가 아님!)
• Read(~/.zshrc) - 홈 디렉토리의 .zshrc 읽기
• Edit(//tmp/scratch.txt) - 절대 경로 /tmp/scratch.txt 편집
• Read(src/**) - <현재-디렉토리>/src/에서 읽기

WebFetch

• WebFetch(domain:example.com) example.com에 대한 fetch 요청과 일치

MCP

• mcp__puppeteer puppeteer 서버에서 제공하는 모든 도구와 일치 (Claude Code에서 구성된 이름)
• mcp__puppeteer__puppeteer_navigate puppeteer 서버에서 제공하는 puppeteer_navigate 도구와 일치

다른 권한 유형과 달리 MCP 권한은 와일드카드(*)를 지원하지 않습니다.

MCP 서버의 모든 도구를 승인하려면:

• ✅ 사용: mcp__github (모든 GitHub 도구 승인)
• ❌ 사용하지 마세요: mcp__github__* (와일드카드는 지원되지 않음)

특정 도구만 승인하려면 각각을 나열하세요:

• ✅ 사용: mcp__github__get_issue
• ✅ 사용: mcp__github__list_issues

훅을 통한 추가 권한 제어

Claude Code 훅은 런타임에 권한 평가를 수행하기 위해 사용자 정의 셸 명령을 등록하는 방법을 제공합니다. Claude Code가 도구 호출을 할 때, PreToolUse 훅이 권한 시스템이 실행되기 전에 실행되고, 훅 출력이 권한 시스템 대신 도구 호출을 승인하거나 거부할지 결정할 수 있습니다.

엔터프라이즈 관리 정책 설정

Claude Code의 엔터프라이즈 배포를 위해 사용자 및 프로젝트 설정보다 우선하는 엔터프라이즈 관리 정책 설정을 지원합니다. 이를 통해 시스템 관리자가 사용자가 재정의할 수 없는 보안 정책을 시행할 수 있습니다.

시스템 관리자는 다음 위치에 정책을 배포할 수 있습니다:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux 및 WSL: /etc/claude-code/managed-settings.json
• Windows: C:\ProgramData\ClaudeCode\managed-settings.json

이러한 정책 파일은 일반 설정 파일과 동일한 형식을 따르지만 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다. 이는 조직 전체에서 일관된 보안 정책을 보장합니다.

설정 우선순위

여러 설정 소스가 존재할 때 다음 순서로 적용됩니다 (높은 우선순위에서 낮은 우선순위 순):

1. 엔터프라이즈 정책
2. 명령줄 인수
3. 로컬 프로젝트 설정 (.claude/settings.local.json)
4. 공유 프로젝트 설정 (.claude/settings.json)
5. 사용자 설정 (~/.claude/settings.json)

이 계층 구조는 조직 정책이 항상 시행되도록 보장하면서도 적절한 경우 프로젝트 및 사용자 수준에서 유연성을 허용합니다.

자격 증명 관리

Claude Code는 인증 자격 증명을 안전하게 관리합니다:

• 저장 위치: macOS에서 API 키, OAuth 토큰 및 기타 자격 증명은 암호화된 macOS Keychain에 저장됩니다.
• 지원되는 인증 유형: Claude.ai 자격 증명, Anthropic API 자격 증명, Bedrock Auth 및 Vertex Auth.
• 사용자 정의 자격 증명 스크립트: apiKeyHelper 설정을 구성하여 API 키를 반환하는 셸 스크립트를 실행할 수 있습니다.
• 새로 고침 간격: 기본적으로 apiKeyHelper는 5분 후 또는 HTTP 401 응답 시 호출됩니다. 사용자 정의 새로 고침 간격을 위해 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 환경 변수를 설정하세요.