Kiro 핸드북

테마

거버넌스 ​

적용 대상 (개인 구독 vs 엔터프라이즈 구독)

Kiro 구독은 개인 구독(GitHub·Google 소셜 로그인 또는 AWS Builder ID)과 엔터프라이즈 구독(AWS IAM Identity Center 또는 외부 IdP, 관리자가 Kiro 프로필로 관리)으로 나뉩니다.

  • 콘솔에서 하는 통제(모델, MCP, API 키, 웹 도구, Cloud Sessions, device flow)는 엔터프라이즈 구독 관리자가 Kiro 프로필에 설정합니다. MCP 통제는 원문에 "Builder ID and social auth users are not subject to organization-level MCP controls"라고 명시돼 있어, 개인 구독 사용자에게는 조직 수준 MCP 통제가 적용되지 않습니다.
  • managed-settings.json(권한 정책, 로그인 제어)은 파일을 배포한 기기의 Kiro에 적용됩니다. 구독 종류와 무관하게 그 기기에서 동작하지만, 파일을 OS 보호 경로에 두어야 하므로 기기 관리 권한(MDM, 그룹 정책 등)이 필요합니다.

목표 ​

조직 사용자가 쓰는 모델, MCP 서버, 도구, 로그인 방식을 관리자가 제한하는 방법을 파악합니다.

구독 체계에 따른 차이 ​

통제개인 구독 (소셜·Builder ID)엔터프라이즈 구독 (IAM Identity Center·외부 IdP)
관리자 콘솔 (Kiro 콘솔·Kiro 프로필)없음있음
모델 거버넌스 (승인 목록·기본 모델)안 됨됨
조직 수준 MCP 통제 (끄기·레지스트리)적용 안 됨 (원문 명시)됨
웹 도구·Cloud Sessions 조직 설정안 됨됨
API 키 생성본인이 Pro 이상이면 가능관리자가 먼저 허용해야 가능
device flow 로그인 통제안 됨프로필별로 됨
사용량 모니터링·프롬프트 로깅없음있음 (사용량 모니터링)
managed-settings.json (권한 정책·로그인 제어)기기에 파일을 배포하면 적용기기에 파일을 배포하면 적용

정리하면, 콘솔에서 하는 거의 모든 거버넌스는 엔터프라이즈 구독 전용입니다. 개인 구독에서 관리자가 강제할 수 있는 것은 기기에 직접 배포하는 managed-settings.json(권한 정책·로그인 제어)뿐입니다. API 키는 개인 구독도 본인이 Pro 이상이면 만들 수 있지만, 엔터프라이즈 구독은 관리자가 먼저 허용해야 합니다.

두 가지 설정 경로 ​

경로위치다루는 것
Kiro 콘솔Settings > Shared settings / Kiro Settings모델, MCP, API 키, 웹 도구, Cloud Sessions
Kiro 콘솔 (프로필별)Settings > Device flow authenticationCLI device flow 로그인
managed-settings.json각 기기의 OS 보호 경로 (MDM·그룹 정책으로 배포)에이전트 권한 정책, 로그인 방식 제한
항목기본값
모델Kiro가 지원하는 모든 모델 (일부 예외, 아래 참고)
MCP모든 MCP 서버 사용 가능
API 키 생성꺼짐
웹 도구 (web_search, web_fetch)켜짐
로그인 방식Kiro가 지원하는 모든 방식
Cloud Sessions (IAM Identity Center 조직)꺼짐

⚠️ 클라이언트에서 강제되는 설정

MCP 토글·레지스트리, 웹 도구, 권한 정책, 로그인 제어는 클라이언트가 강제합니다. 로컬 기기 관리자 권한이 있는 사용자는 우회할 수 있습니다. 누가 Kiro를 쓸 수 있는지는 IdP와 Kiro 콘솔의 구독 관리로 통제하세요.

콘솔에서 하는 통제 ​

모델 ​

Settings → Shared settings → Model availability에서 Control which models are available to users를 켭니다.

  • 꺼져 있으면: 일부 예외 모델(현재 Claude Fable 5.1, Kimi K3)을 뺀 모든 모델을 쓸 수 있습니다. Claude Fable 5.1은 Kiro Enterprise 조직에 제공되며 추론은 us-east-1에서만 이뤄집니다. Fable 5.1 트래픽은 자동 오남용 탐지를 위해 최대 30일 보관되고(법적 요구가 없는 한), 분류기가 표시한 트래픽은 AWS가 사람이 검토할 수 있습니다.
  • 켜져 있으면: Manage approved list에서 고른 모델만 쓸 수 있습니다. "Auto"도 목록에 있습니다. 승인 목록에서 기본 모델을 지정하면 조직의 모든 클라이언트에 적용됩니다.
  • Kiro가 새 모델을 추가하면 승인 목록에 자동으로 선택됩니다. 막으려면 체크를 풀고 저장합니다. 예외 모델은 선택되지 않은 채로 나타나며, 관리자가 선택하고 저장해야 사용자에게 보입니다. 새 모델이 나오면 콘솔에 알림이 옵니다.
  • 모델마다 추론 범위와 엔드포인트 위치를 조직의 데이터 상주·컴플라이언스 요건과 대조하세요.
  • 목록을 바꿔도 바로 반영되지 않습니다. 사용자가 세션을 다시 시작하거나 로그아웃 후 다시 로그인해야 합니다.
  • Kimi K3와 experimental·pre-release·preview·beta 모델은 Kiro Excluded Models입니다. 추가하기 전에 해당 설명을 읽으세요.

Available models 설명대로 Auto는 거버넌스에서 별도 선택지로 허용·차단할 수 있으며, 허용하면 승인 목록 밖의 Active 모델로도 라우팅될 수 있습니다. 승인 목록의 모델만 쓰게 하려면 Auto를 차단합니다(Models 참고).

Kiro 클라이언트를 최신 버전으로 유지해야 모델 제한이 제대로 적용됩니다.

MCP ​

MCP 설정은 Kiro 프로필에 속하며 조직 수준과 계정 수준에서 정할 수 있습니다. 계정 수준이 조직 수준보다 우선하므로, 조직 전체는 끄고 특정 팀 계정만 허용 목록으로 켤 수 있습니다. IAM Identity Center나 API 키로 인증한 사용자에게 적용되며, Builder ID·소셜 로그인 사용자는 대상이 아닙니다.

끄기: Shared settings에서 Model Context Protocol (MCP) 토글을 Off로 둡니다. 사용자 설정·레거시·레지스트리·세션 주입 서버가 모두 막히고, /mcp에 MCP has been disabled by your administrator가 표시됩니다. 클라이언트가 거버넌스 API에 닿지 못해도 MCP가 꺼진 상태로 동작합니다(fail closed). 보통 일시적이고 다시 연결되면 풀립니다.

허용 목록 (MCP 레지스트리): MCP를 On으로 두고 MCP Registry URL에 레지스트리 JSON 파일의 URL을 넣습니다.

  • 파일 형식은 MCP registry 표준 v0.1 서버 스키마의 부분집합입니다. 원격 서버는 remotes(항목 정확히 1개, streamable-http 또는 sse), 로컬 서버는 packages(항목 정확히 1개)(npm→npx, pypi→uvx, oci→docker, stdio 전송)로 정의합니다. 사용자 기기에 해당 실행기가 미리 설치돼 있어야 합니다.
  • 파일은 HTTPS로 제공하며 신뢰할 수 있는 CA가 서명한 인증서가 필요합니다(자체 서명 불가). 사내망 전용 URL이어도 사용자 기기에서 닿기만 하면 됩니다.
  • Kiro는 시작할 때와 24시간마다 레지스트리를 가져옵니다. 레지스트리에서 빠진 로컬 서버는 종료하고 다시 추가하지 못하게 하며, 버전이 다르면 레지스트리 버전으로 다시 실행합니다.
  • 레지스트리의 서버 정의는 읽기 전용입니다. 사용자는 환경 변수·HTTP 헤더 추가(레지스트리 값을 덮어씀), 요청 타임아웃, 서버 범위(Global·Workspace·Agent), 도구 신뢰 권한만 바꿀 수 있습니다.
json
{
  "servers": [
    {
      "server": {
        "name": "my-remote-server",
        "description": "My server description",
        "version": "1.0.0",
        "remotes": [{ "type": "streamable-http", "url": "https://acme.com/my-server" }]
      }
    }
  ]
}

전체 JSON 스키마는 MCP 거버넌스 원문에 있습니다.

API 키 ​

Kiro CLI를 로컬이나 CI/CD에서 자동화 스크립트로 돌릴 때 API 키를 씁니다. API 키는 Pro·Pro+·Pro Max·Power 구독자만 만들 수 있습니다. 개인 구독은 본인이 Pro 이상이면 Kiro 포털에서 바로 키를 만들 수 있습니다. 엔터프라이즈 구독은 기본값이 꺼짐이라, 관리자가 Settings → Kiro settings에서 Enable users to generate API keys를 먼저 켜야 사용자가 키를 만들 수 있습니다. 헤드리스 실행과 함께 보세요.

웹 도구 ​

Shared settings에서 Web search and web fetch tools를 Off로 두면 web_search와 web_fetch가 사용자에게 숨겨지고, /tools에 관리자가 웹 접근을 껐다는 안내가 표시됩니다.

Cloud Sessions ​

IAM Identity Center 조직은 기본적으로 꺼져 있습니다. Kiro 프로필이 설정된 계정에서 Settings > Kiro Settings의 Cloud Sessions를 켭니다. 예전 이름은 Kiro Web (Preview) 였으며, 이미 켰던 조직은 그대로 켜져 있습니다.

  • 모든 Kiro Web 세션이 클라우드 세션이므로, 꺼져 있으면 Kiro Web에서 세션을 시작할 수 없습니다.
  • 같은 토글이 IDE Agent Focus Mode의 클라우드 세션과 kiro-cli --cloud도 제어합니다.
  • API 키 생성과는 별개 토글입니다.
  • MCP 설정, 모델 가용성, Customer Managed Keys 같은 일부 공유 설정은 Kiro Web 세션에 적용되지 않습니다. 전체 목록은 Kiro Web with AWS Identity Center를 보세요.

Cloud Sessions 페이지도 참고하세요.

managed-settings.json으로 하는 통제 ​

파일 위치 ​

OS경로
macOS/Library/Application Support/Kiro/managed-settings.json
WindowsC:\ProgramData\Kiro\managed-settings.json
Linux/etc/kiro/managed-settings.json

이 경로는 관리자·root 권한이 있어야 바꿀 수 있습니다. IDE와 CLI가 같은 파일을 읽으므로 기기의 모든 Kiro에 적용됩니다. Jamf·Kandji 같은 MDM이나 그룹 정책·SCCM으로 배포할 수 있습니다. Windows에서는 BOM 없는 UTF-8로 저장해야 합니다. Windows PowerShell Out-File의 기본값인 UTF-16 파일과 BOM으로 시작하는 파일은 거부됩니다. 권한 정책 하나와 로그인 제어를 같은 파일의 rules 배열과 settings 객체에 함께 둡니다.

권한 정책 ​

사용자의 Permissions 위에 관리자 규칙을 겹칩니다. 같은 capability에 관리자 규칙과 사용자 규칙이 있으면 더 엄격한 쪽이 이깁니다 (deny > ask > allow).

  • 관리자 규칙은 deny와 ask만 쓸 수 있습니다. 제한만 할 수 있고 허용은 줄 수 없습니다. 클라이언트가 요청한 policy preset의 allow도 관리자 deny·ask를 넘지 못합니다.
  • 규칙 필드는 사용자 권한과 같습니다: capability(shell, fs_read, fs_write, web_fetch, mcp 등), match, exclude, effect.
  • 적용하려면 Kiro를 다시 시작합니다.
json
{
  "rules": [
    { "capability": "shell", "match": ["rm *", "sudo *", "chmod *", "chown *", "mkfs *"], "effect": "deny" },
    { "capability": "web_fetch", "exclude": ["docs.aws.amazon.com", "*.amazonaws.com", "*.github.com"], "effect": "deny" },
    { "capability": "mcp", "effect": "ask" }
  ]
}

두 번째 규칙은 exclude에 없는 모든 도메인의 웹 가져오기를 막습니다. exclude에 해당하는 도메인에는 관리자 규칙이 없으므로 사용자 자신의 권한이 적용됩니다.

검증과 오류: 시작할 때 파일을 검증하며, 잘못되면 fail closed입니다.

경우결과
JSON 문법 오류파일 전체 거부, 모든 도구 호출 거부
effect: "allow"파일 전체 거부 (fail closed)
스키마에 없는 필드 (effct 같은 오타)파일 전체 거부
(참고) signin_method 규칙의 잘못된 effect로그인 제한만 무시 (아래 로그인 제어 참고)
모르는 capability그 규칙만 경고와 함께 건너뜀 (새 정책을 옛 버전에서 쓸 수 있게)

사용자가 "모든 도구가 거부된다"고 하면 이 파일부터 확인하세요. 관리자 정책에 막힌 호출에는 조직이 관리하는 제한이라 사용자 설정으로 덮을 수 없다는 메시지가 표시됩니다. 테스트 기기에서 막아야 할 동작을 시켜, 규칙 출처가 "administration"으로 나오는지 확인합니다.

패턴 매칭이나 허용 목록이 필요하면 권한 정책을, 기능 전체를 켜고 끄려면 콘솔 설정을 씁니다.

로그인 제어 ​

관리 기기에서 로그인 화면에 보일 방식을 제한하고, IAM Identity Center 시작 URL과 리전을 미리 채우고, 도움말 링크를 붙입니다. Kiro IDE 1.2 이상, Kiro CLI 2.25.0 이상에 적용됩니다. Kiro Web이나 파일이 없는 기기, 그 이전 버전 클라이언트에는 적용되지 않습니다.

json
{
  "rules": [
    { "capability": "signin_method", "match": ["*"], "exclude": ["idc"], "effect": "deny" }
  ],
  "settings": {
    "idc_start_url": "https://my-org.awsapps.com/start",
    "idc_region": "us-east-1",
    "signin_help_url": "https://it.example.com/kiro-help"
  }
}
  • signin_method 규칙의 effect는 항상 deny입니다. match는 뺄 방식, exclude는 남길 방식입니다. 일부만 허용하려면 "match": ["*"]로 모두 막고 exclude에 허용할 방식을 적습니다.
  • 방식 이름(대소문자 구분): idc(화면 표시 Your organization), external_idp, builder_id, google, github, social(Google+GitHub). 화면 표시 이름은 받지 않습니다. 한 규칙에 match와 exclude를 합쳐 최대 16개까지 적습니다.
  • settings 키: idc_start_url, idc_region, external_idp_domain, external_idp_start_url, external_idp_region, signin_help_url. 모두 선택이며, 제어 문자 없는 2,048자 이하 문자열이고 URL은 https여야 합니다. 조건을 어긴 값은 그 값만 버려지고 나머지는 적용됩니다. settings의 모르는 키는 무시됩니다. 도움말 링크는 클라이언트만 표시하고 로그인 서비스로 보내지 않으므로 사내 URL이어도 됩니다.
  • settings만 쓸 때도 "rules": []는 남겨 둡니다.
  • 로그인 URL을 고쳐 막힌 방식으로 로그인해도, 토큰 발급 전에 클라이언트가 다시 확인해 거부합니다.

오류 처리는 fail open입니다. 실수가 있어도 로그인이 막히지 않고, 해당 제어만 빠진 채 경고가 뜹니다. 다음 경우에는 로그인 제한만 무시되고 settings는 계속 적용됩니다: effect가 deny가 아닐 때, exclude에 모르는 이름이 있을 때, match에 아는 이름이 하나도 없을 때, 규칙들이 모든 방식을 막거나 아무 방식도 막지 않을 때, 한 규칙이 16개를 넘는 이름을 적었을 때. match에 아는 이름과 모르는 이름이 섞여 있으면 아는 이름은 계속 막고 경고합니다. 단 파일이 JSON으로 읽히지 않으면 같은 파일의 권한 정책 때문에 에이전트 도구가 막힙니다.

확인: 테스트 기기에서 로그아웃하고 다시 로그인해 허용한 방식만 보이는지, 시작 URL·리전이 채워졌는지, IDE에 Need help signing in? 링크가 보이는지(CLI는 kiro-cli login이 이 줄을 출력) 확인합니다.

Device flow 로그인 (프로필별) ​

브라우저 없이 로그인하는 device flow는 콘솔에서 프로필마다 끌 수 있습니다. Settings > Device flow authentication에서 Users can sign in to the Kiro CLI using device flow를 끕니다.

  • kiro-cli login과 kiro-cli profile이 device flow 중에 그 프로필을 숨깁니다. 남는 프로필이 없으면 device flow 로그인을 거부하고 브라우저 로그인으로 안내합니다.
  • 브라우저 로그인은 그대로입니다. 이미 실행 중인 세션은 끝나지 않고, 다음에 device flow 자격 증명이 프로필에 묶일 때부터 적용됩니다.

더 알아보기 ​

출처: 위 kiro.dev Enterprise Governance 문서 (2026-10-26 확인)

© 2026 Kiro 핸드북 · 비공식 자료이며 AWS와 무관합니다.