AI/Claude Code Doc(공식문서) 번역본

Claude Code 공식문서 리뷰-Administration[2] : Claude Code 설정 - 신원 및 접근 관리(Identity and Access Management)

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> [관리] 섹션의 내용 중 [Claude Code 설정 - 신원 및 접근 관리(Identity and Access Management)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/ko/iam

신원 및 접근 관리 - Claude Code Docs

Claude Code에 대한 사용자 인증, 권한 부여 및 접근 제어를 조직에서 구성하는 방법을 알아봅니다.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

Claude Code ID 및 접근 관리 (IAM)

인증, 권한 부여, 접근 제어 설정 가이드

인증 방법

Claude Code는 Anthropic 모델에 대한 접근이 필요합니다. 팀은 네 가지 방법으로 Claude Code 접근을 설정할 수 있습니다:

Claude Console을 통한 Claude API
Amazon Bedrock
Microsoft Foundry
Google Vertex AI

Claude API 인증

설정 단계:

기존 Claude Console 계정을 사용하거나 새로 생성
사용자 추가: Console에서 일괄 초대 (설정 > 멤버 > 초대) 또는 SSO 설정
초대 시 사용자 역할 지정:
- "Claude Code" 역할: Claude Code API 키만 생성 가능
- "Developer" 역할: 모든 종류의 API 키 생성 가능
각 사용자가 해야 할 일: Console 초대 수락, 시스템 요구 사항 확인, Claude Code 설치, Console 자격 증명으로 로그인

클라우드 제공자 인증

Bedrock, Vertex, Azure의 경우:

해당 클라우드 제공자 문서 참조
환경 변수 및 자격 증명 생성 지침 배포
사용자가 Claude Code를 설치하고 자격 증명 구성

접근 제어 및 권한

세분화된 권한 (Fine-grained Permissions): 도구나 명령 단위로 허용/거부를 설정할 수 있는 권한 시스템입니다. 예를 들어 파일 읽기는 허용하고 쓰기는 거부하는 식의 세밀한 제어가 가능합니다.

권한 시스템

세 단계 시스템으로 성능과 안전성의 균형을 맞춥니다:

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

권한 구성

/permissions 명령으로 권한을 보고 관리합니다. 이 UI는 모든 규칙과 해당 소스 파일을 나열합니다.

규칙 유형:

Allow: 수동 승인 없이 도구 사용
Ask: 도구 사용 전 확인 (Allow보다 우선)
Deny: 도구 사용 방지 (최우선 적용)
추가 디렉토리: 작업 디렉토리 외부로 파일 접근 확장
기본 모드: 새 요청에 대한 동작 제어

고급 기능 - Hooks를 통한 권한 제어:

PreToolUse hook을 사용하면 도구 호출을 프로그래밍 방식으로 승인하거나 거부할 수 있다. 이 기능은 기본 Allow/Ask/Deny 규칙과 독립적으로 동작하며, 사용자 정의 로직에 따라 세밀한 권한 제어가 가능하다. 상세 내용은 Hooks 문서를 참조한다.

ex)

권한 모드

설정 파일의 defaultMode로 구성:

모드	설명
`default`	표준 동작 - 첫 사용 시 권한 요청
`acceptEdits`	세션 동안 파일 편집 권한 자동 수락
`plan`	계획 모드 - 파일 수정이나 명령 실행 없이 분석만
`bypassPermissions`	모든 권한 프롬프트 건너뛰기 (안전한 환경 필요)

주의: bypassPermissions는 샌드박스 환경이나 완전히 신뢰할 수 있는 환경에서만 사용하세요.

ex) 좌측 하단에 모드가 노출 되고 shift + tab으로 전환 가능하다.

작업 디렉토리

기본적으로 Claude는 실행 디렉토리의 파일에 접근합니다.

접근 확장 방법:

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

도구별 권한 규칙

Bash

Bash(npm run build)          # 정확한 명령 일치
Bash(npm run test:*)         # 접두사 일치 (npm run test:*)
Bash(curl http://site.com/:*) # 와일드카드를 사용한 접두사 일치

중요한 제한 사항:

접두사 일치를 사용하며, 정규식/glob이 아님
와일드카드 :*는 패턴 끝에서만 작동
URL 앞의 옵션, 다른 프로토콜, 리다이렉트, 변수 등으로 우회 가능

Bash 규칙 우회 사례:

Allow: Bash(curl https://example.com/:*) 규칙이 있을 때, 다음 명령들은 차단되지 않는다:

curl -X POST https://example.com/ - URL 앞에 옵션
curl http://example.com/ - 다른 프로토콜
curl https://evil.com --next https://example.com/ - 리다이렉트
curl https://$URL/ - 변수 사용

권장: 민감한 URL 접근에는 Bash 규칙 대신 WebFetch(domain:example.com)를 사용한다.

Read & Edit

gitignore 명세를 따릅니다:

패턴	의미	예시
`//path`	파일시스템 루트의 절대 경로	`Read(//Users/alice/secrets/**)`
`~/path`	홈 디렉토리 경로	`Read(~/Documents/*.pdf)`
`/path`	설정 파일 기준 상대 경로	`Edit(/src/*/.ts)`
`path`	현재 디렉토리 기준 상대 경로	`Read(*.env)`

경고 - 흔한 실수:

/Users/alice/file은 절대 경로가 아니다. 이것은 설정 파일 위치 기준 상대 경로로 해석된다.

파일시스템 루트부터의 절대 경로를 지정하려면 //Users/alice/file처럼 슬래시 두 개를 사용해야 한다.

`/Users/alice/secrets`	설정 파일 기준 상대 경로 (의도와 다를 수 있음)
`//Users/alice/secrets`	파일시스템 루트 기준 절대 경로 (올바른 사용)

WebFetch

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

MCP

mcp__puppeteer                    # puppeteer 서버의 모든 도구
mcp__puppeteer__*                 # 와일드카드 - puppeteer의 모든 도구
mcp__puppeteer__puppeteer_navigate # puppeteer의 특정 도구

엔터프라이즈 관리형 설정

Claude for Enterprise 고객은 Claude.ai 관리 콘솔을 통해 사용 가능:

사용자 인증 시 설정이 자동으로 가져와짐
로컬에서 재정의 불가
활성화하려면 Anthropic 계정 팀에 연락

설정 우선순위

적용 순서 (높음에서 낮음):

관리형 설정 (Claude.ai 관리 콘솔)
파일 기반 관리형 설정 (managed-settings.json)
- macOS: /Library/Application Support/ClaudeCode/managed-settings.json
- Linux: /etc/claude-code/managed-settings.json
- Windows: C:\Program Files\ClaudeCode\managed-settings.json
명령줄 인자
로컬 프로젝트 설정 (.claude/settings.local.json)
공유 프로젝트 설정 (.claude/settings.json)
사용자 설정 (~/.claude/settings.json)

자격 증명 관리

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

항목	설명
저장 위치	macOS Keychain (암호화), 다른 플랫폼은 플랫폼별 보안 저장소 사용
지원 유형	Claude.ai, Claude API, Azure Auth, Bedrock Auth, Vertex Auth
커스텀 자격 증명 스크립트	`apiKeyHelper` 설정으로 API 키를 반환하는 셸 스크립트 구성
갱신 간격	기본 5분 또는 HTTP 401 시; `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 환경 변수로 커스터마이즈

실전 팁: 엔터프라이즈 환경에서 보안 볼트나 시크릿 매니저와 통합할 때 커스텀 자격 증명 스크립트가 유용합니다.

흔한 에러와 해결법

Permission denied

Error: Permission denied for tool: Edit

원인: 해당 도구에 대한 권한이 없음

해결법:

/permissions 명령으로 현재 권한 확인
필요한 권한 규칙 추가
또는 프롬프트에서 승인

API key invalid

Error: Invalid API key or authentication failed

원인: API 키가 만료되었거나 잘못됨