팀에 에이전트까지 합류한 시대, 권한 관리는 어떻게 하고 계신가요?
Cloudflare Developer Platform 위에서 팀원뿐 아니라 AI 에이전트까지 애플리케이션을 배포하는 시대가 됐습니다. 그런데 여기서 가장 무서운 시나리오는 뭘까요? 바로 에이전트가 필요 이상의 권한을 부여받아 프로덕션을 건드리는 상황이에요.
기존에는 계정 단위 권한만 있어서 "이 Worker만 건드리게 하고 싶다"는 요구를 만족시키기 어려웠습니다. 이번 업데이트로 특정 Worker 단위로 권한을 스코프할 수 있게 됐고, 역할도 4가지로 세분화됐어요.
이 글에서는 새로 추가된 역할 4종과 실무에서 어떻게 조합해서 쓰면 좋을지 정리해볼게요.
새로 추가된 4가지 역할
| 역할 | 할 수 있는 것 | 언제 쓰나 |
|---|---|---|
| Metadata Read-Only | 리소스 목록, 설정, 메트릭/로그/트레이스 조회 (콘텐츠 접근 불가) | 디버깅용 관측 데이터만 주고 싶을 때 |
| Content Read-Only | Worker 코드, D1 데이터 등 콘텐츠 읽기 (수정 불가) | 코드 리뷰 에이전트나 팀원에게 소스만 공개할 때 |
| Editor | 콘텐츠 읽기/쓰기, 설정 변경 (생성·삭제 불가) | CI/CD나 배포 자동화에 권한을 줄 때 |
| Admin | 리소스 생성·이름변경·삭제·권한 부여까지 전권 | 해당 Worker의 완전한 관리가 필요할 때 |
스코프 3단계
역할은 다음 세 가지 스코프 중 하나에 적용됩니다.
- Developer Platform 레벨: 모든 리소스의 메타데이터
- Product 레벨: 특정 제품(예: 모든 Worker)의 메타데이터
- Resource 레벨: 특정 Worker 하나의 메타데이터
API 토큰으로 Worker 단위 권한 주기
# 특정 Worker에만 스코프된 API 토큰 생성 예시
curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/tokens" \
-H "Authorization: Bearer $CF_API_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"name": "deploy-my-worker-only",
"policies": [{
"effect": "allow",
"resources": {
"com.cloudflare.api.account.worker": {
"<WORKER_ID>": "*" # 이 Worker 하나에만 스코프
}
},
"permission_groups": [
{ "name": "Workers Scripts Edit" } # Editor 역할에 해당
]
}]
}'
이렇게 토큰을 만들면 에이전트가 탈취되더라도 피해 범위가 해당 Worker 하나로 제한됩니다. 이게 바로 최소 권한 원칙(Principle of Least Privilege)의 실전 적용이에요.
실무에서 자주 쓰는 3가지 시나리오
1. 소스 노출 없이 디버깅만
장애 대응용 에이전트에게 Metadata Read-Only를 주면 메트릭·로그·트레이스는 볼 수 있지만 Worker 코드는 못 봅니다. GraphQL Analytics API로 조회해도 본인 권한 범위 내 Worker 데이터만 반환돼요.
2. 코드 리뷰는 하되 배포는 못 하게
리뷰 봇에게 Content Read-Only를 주면 코드는 읽되 배포·설정 변경은 불가능합니다. D1·R2·KV에도 동일한 분리가 순차 적용될 예정이에요.
3. CI/CD에 딱 배포 권한만
워크플로우마다 Editor 역할의 토큰을 Worker 단위로 발급하면, 토큰이 유출돼도 다른 Worker를 건드리거나 삭제할 수 없습니다.
⚠️ 주의사항: Routes & Custom Domains는 별개
여기서 실수하기 쉬운 포인트가 있어요. Worker에 Editor 권한이 있어도 라우트나 커스텀 도메인을 바꾸려면 zone 레벨의 Workers Routes 권한이 추가로 필요합니다. 프로덕션 트래픽을 리다이렉트할 수 있는 민감한 작업이니까요.
// wrangler.jsonc - 라우트 설정 예시
{
"route": {
"pattern": "example.com/*",
"zone_name": "example.com"
}
}
반대로 라우트가 이미 설정된 상태라면 그 연결을 바꾸지 않는 배포는 zone 권한 없이도 가능합니다. 즉 CI/CD에 도메인 권한까지 줄 필요가 없어요.
Durable Objects는 Worker 권한을 따라갑니다
DO에는 별도 역할이 없고, 구현한 Worker의 권한을 그대로 상속합니다. 메트릭·로그는 Metadata Read-Only로 충분하지만, Data Studio로 저장 데이터를 조회·수정하려면 Editor가 필요해요.
403 에러가 친절해졌습니다
권한 부족 시 이제 어떤 권한이 필요한지 문서 링크와 함께 응답합니다. 에이전트가 스스로 필요한 권한을 파악할 수 있어서, 과도한 권한을 미리 부여할 필요가 없어졌어요.
한국 개발 생태계에서의 적용 맥락
국내 SI·스타트업 환경에서는 아직 "계정 하나에 Admin 토큰"을 공유하는 관행이 남아 있는 경우가 많아요. 특히 외주 인력이 섞이는 프로젝트에서는 리소스 단위 스코프가 보안 감사 대응에도 유리합니다. 다만 Terraform으로 관리한다면 provider 버전과 스키마 호환을 먼저 확인하세요.
이 기술의 한계
- 레거시 역할(Workers Platform Admin 등)은 deprecation 일정이 아직 없음. 기존 할당은 계속 동작하니 마이그레이션은 서두르지 않아도 됩니다.
- D1·R2·KV로의 확장은 로드맵이며, 현재는 Workers 중심입니다.
- 사용자 그룹(User Group)을 활용하면 개별 할당보다 관리 부담이 줄어요.
다음 단계 학습 방향
- 공식 문서에서 역할 매핑 테이블(레거시 → 신규)을 확인하고, 기존 토큰을 신규 역할로 교체
- 에이전트별로 최소 권한 토큰을 발급하는 템플릿 만들기
- Terraform으로 리소스 레벨 정책을 코드화