Claude Code 조직 권한 설정: bypassPermissions를 막고 비밀 파일 접근을 차단하는 법

TL;DR

핵심 3줄 요약

이 글에서 다룰 내용

server-managed settings는 무엇이고 언제 쓰면 좋은가

Claude Code가 저장소를 읽고 셸 명령을 실행할 때 구성원의 주의만으로 공통 보안 기준을 지키기는 어렵습니다. 사용자나 프로젝트마다 설정이 다르면 같은 조직에서도 비밀 파일 deny 규칙과 권한 모드가 달라집니다.

한 문장 정의: server-managed settings는 claude.ai 관리 콘솔에서 Claude Code 설정을 조직 사용자에게 중앙 배포하는 기능입니다.

공식 문서에 따르면 이 기능은 Claude Team·Enterprise 고객에게 제공됩니다. 설정을 보거나 바꾸려면 해당 조직의 Owner 또는 Primary Owner 역할이 필요하며 api.anthropic.com 에 연결할 수 있어야 합니다. Admin 등 다른 역할이 메뉴를 열었을 때 다른 페이지로 이동한다면 Owner 또는 Primary Owner에게 변경을 요청해야 합니다.

이 방식은 기기 관리 인프라가 없거나 관리되지 않는 기기에도 공통 설정을 보낼 때 유용합니다. 다만 정책은 조직 사용자에게 동일하게 적용되며 현재 per-group 구성은 지원되지 않습니다. 팀별로 다른 규칙을 배포할 수 있다고 가정하지 말고 전사 영향 범위를 먼저 검토해야 합니다.

배포 전에 권한 범위와 승인자를 확인하기

1. 적용 조건을 기록합니다

조직 플랜이 Team 또는 Enterprise인지, 변경자가 Owner 또는 Primary Owner인지, 테스트 사용자가 조직 OAuth 로그인이나 지원되는 직접 API 키 방식으로 인증하는지 확인합니다. 네트워크에서 api.anthropic.com 접근도 점검합니다.

2. 기존 규칙과 정상 작업을 수집합니다

현재 사용자·프로젝트 설정에 어떤 allow·ask·deny 규칙이 있는지 살핍니다. 빌드, 테스트, 코드 읽기처럼 계속 허용해야 할 작업과 .env , .env.* , secrets/** 처럼 차단할 경로를 나눕니다. 실제 비밀값은 테스트 자료에 넣지 않습니다.

3. 조직 전체 변경 승인을 받습니다

변경 목적, JSON 초안, 적용 시각, 테스트 담당자, 롤백 담당자를 기록합니다. server-managed settings는 모든 사용자에게 동일하게 적용되므로 한 팀의 요구만 보고 바로 저장해서는 안 됩니다.

권한 우회와 비밀 파일 접근을 차단하는 순서

1. 관리 콘솔에서 설정 화면을 엽니다

claude.ai에서 Admin Settings > Claude Code > Managed settings 로 이동합니다. 공식 메뉴 이름과 현재 화면이 다르다면 추정 경로를 따라가지 말고 계정 역할과 공식 문서를 다시 확인합니다.

2. 공식 예시를 검토용 초안으로 넣습니다

아래 JSON은 Anthropic의 server-managed settings 문서에 나온 예시입니다. Bash(curl *) , .env , .env.* , secrets/** 를 deny 목록에 넣고 bypassPermissions 모드를 막으며 관리형 규칙만 적용합니다.

{
"permissions": {
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true
}

deny 규칙은 ask , allow 보다 먼저 평가됩니다. Bash(curl *) 는 curl과 일치하는 Bash 호출을 막는 예시일 뿐 모든 외부 전송 경로를 차단하지는 않습니다. .env 와 secrets/** 규칙도 지정된 Read 경로를 막는 예시이며 운영체제 권한이나 비밀 관리 서비스를 대신하지 않습니다.

3. 세 설정의 역할을 따로 확인합니다

disableBypassPermissionsMode: "disable" 은 bypassPermissions 모드와 --dangerously-skip-permissions 사용을 막습니다. allowManagedPermissionRulesOnly: true 는 사용자·프로젝트 설정이 allow·ask·deny 권한 규칙을 정의하지 못하게 하고 관리형 규칙만 적용합니다. permissions.deny 는 일치하는 도구 호출과 경로를 차단합니다.

4. 저장 전 JSON과 영향 범위를 승인받습니다

오탈자, 경로 패턴, 정상 업무 영향, 적용 대상이 조직 전체라는 점을 다시 봅니다. 승인 전에는 Save를 누르지 않습니다. 변경 후 문제가 생기면 되돌릴 수 있도록 이전 JSON도 따로 보관합니다.

5. 저장한 뒤 새 세션에서 적용을 확인합니다

공식 문서에 따르면 Claude Code 클라이언트는 다음 시작 시점 또는 매시간 폴링에서 변경된 설정을 받습니다. 즉시 검증하려면 일반 사용자가 Claude Code를 재시작합니다. 보안 승인 대화상자가 나타나는 설정이라면 내용을 읽고 승인 여부를 판단합니다.

일반 사용자 세션에서 차단과 정상 작업을 검증하기

1. /permissions 에서 유효 규칙을 확인합니다

일반 사용자 계정으로 Claude Code를 시작하고 /permissions 를 실행합니다. 관리형 deny 규칙이 유효 권한 규칙에 보이는지 확인합니다. 관리자 화면의 저장 메시지만으로 적용 완료를 판단하지 않습니다.

2. 비민감 테스트 저장소에서 차단을 재현합니다

가짜 값만 든 .env 와 secrets/sample.txt 를 만든 테스트 저장소를 사용합니다. Claude Code에 두 파일을 읽으라고 요청하고 deny 결과를 기록합니다. 실제 자격증명이나 운영 저장소로 차단 시험을 하지 않습니다.

3. 정상 작업이 유지되는지 확인합니다

일반 소스 파일 읽기, 승인된 테스트 실행, 안전한 코드 수정처럼 유지해야 할 작업도 함께 확인합니다. 차단만 통과하고 정상 업무가 멈췄다면 배포 성공이 아닙니다.

4. 우회 모드와 로컬 규칙 추가를 점검합니다

격리된 테스트 환경에서 bypassPermissions 모드가 활성화되지 않는지 확인합니다. 사용자나 프로젝트 설정에 임의 권한 규칙을 넣어도 관리형 정책이 그대로 적용되는지 /permissions 에서 다시 봅니다. 실제 운영 명령이나 외부 전송은 실행하지 않습니다.

그대로 복사해 쓸 프롬프트

이 프롬프트의 결과도 공식 문서와 현재 관리자 화면에 대조합니다. Claude가 만든 경로 패턴을 그대로 저장하지 않습니다.

실전 활용 팁

주의할 점

자주 묻는 질문

출처

마무리

Claude Code 조직 권한 설정은 JSON을 저장했다고 끝나지 않습니다. 조직 전체 영향과 승인자를 먼저 확인하고, 권한 우회 차단·관리형 규칙 강제·비밀 파일 deny를 각각 검토합니다. 그다음 일반 사용자 세션에서 차단과 정상 작업을 함께 재현해야 합니다.

server-managed settings는 클라이언트 측 통제입니다. 비밀값을 저장소에서 분리하고 기기·운영체제·비밀 관리 정책과 결합할 때 실무 안전성이 높아집니다.