Deep Agent Builder 시크릿과 권한
시크릿을 저장하거나 에이전트가 도구와 모델을 사용할 수 있는지 확인할 때는 인증 정보와 권한 판정을 따로 봐야 합니다. 시크릿 값은 문서나 로그에 남기지 않고, 요청이 거부된 이유는 RBAC, 워크스페이스 권한, 리소스 capability 중 어느 단계에서 실패했는지로 좁혀야 합니다.
시크릿을 다룰 때 지킬 경계
시크릿은 값 자체가 아니라 접근이 필요한 자원으로 다룹니다. 다음 원칙을 지킵니다.
- 시크릿 값, 토큰, 호스트와 같은 인증 정보를 문서, 로그, 테스트 입력에 직접 넣지 않습니다.
- 에이전트가 사용할 리소스만 선택하고, 실행에 필요한 권한과 리소스 capability를 따로 확인합니다.
- 권한이 없을 때 다른 권한 원천이나 개인 리소스로 임의 대체하지 않습니다.
- 원격 권한 Provider를 사용할 때 내부 권한 테이블과 결과를 합쳐서 판단하지 않습니다.
Code Sandbox 실행에서도 Runtime은 실제 Sandbox 주소나 JWT secret을 알지 못합니다. Service API가 인증 토큰 발급과 세션 관리를 맡고, Runtime에는 실행 결과만 전달합니다. 따라서 실행 코드나 에이전트 지침에 Sandbox secret을 넣는 방식으로 문제를 해결하지 마세요.
권한 판정은 세 단계로 나눠 확인합니다
Deep Agent Builder의 권한 모델은 서로 다른 범위를 검사합니다.
| 판정 | 질문 | 예시 |
|---|---|---|
| RBAC | 사용자가 해당 작업을 수행할 수 있는가 | 에이전트 생성, 시크릿 생성, 모델 조회 |
| WBAC | 사용자가 특정 workspace에서 작업할 수 있는가 | workspace 범위의 읽기·관리 작업 |
| ABAC | 해당 리소스가 이 동작을 허용하는가 | 도구·모델 사용, 수정, 삭제 |
workspace 리소스를 다루는 요청은 일반적으로 세 판정을 모두 통과해야 합니다. RBAC가 허용돼도 개별 리소스의 capability가 없으면 요청은 거부됩니다. 반대로 리소스 capability가 있어도 사용자 작업 권한이나 workspace 범위를 대신하지 않습니다.
시크릿과 관련해 확인할 대표 RBAC 코드는 USER_SECRET_READ, USER_SECRET_CREATE, USER_SECRET_UPDATE, USER_SECRET_DELETE입니다. 에이전트 조회와 수정은 USER_AGENT_VIEW, USER_AGENT_EDIT가 관여하고, 도구와 모델은 각각 USER_TOOL_READ, USER_TOOL_USE, USER_MODEL_READ 같은 별도 권한을 사용합니다. 전체 코드 목록은 권한 카탈로그에서 확인하고, 이 페이지의 예시만으로 권한을 추정하지 마세요.
에이전트에 리소스를 연결하기 전 확인 순서
- 현재 사용자와 대상 workspace가 맞는지 확인합니다. 사용자 API는 로그인 세션과 현재 사용자의 범위를 기준으로 동작합니다.
- 에이전트 조회 또는 수정 권한을 확인합니다. 에이전트 설정을 바꾸는 작업에는 보통 USER_AGENT_VIEW와 USER_AGENT_EDIT가 필요합니다.
- 연결할 도구·모델·스킬의 조회 권한과 사용 capability를 확인합니다. 자연어 생성에서 리소스를 선택할 때도 사용 capability가 검사됩니다.
- 시크릿이 필요한 도구라면 시크릿을 새로 만들거나 수정할 권한과 도구 자체를 사용할 권한을 분리해 확인합니다. 하나가 없다고 다른 권한을 대신 부여하지 않습니다.
- 저장 또는 연결 후 에이전트 설정을 다시 조회합니다. 선택한 리소스와 권한 상태가 기대한 범위인지 확인한 뒤 비식별 입력으로 실행을 점검합니다.
실행 시점에도 RESOURCE_CAN_USE가 다시 평가됩니다. 설정 화면에서 사용 가능으로 보였더라도 실행 시점의 capability가 없으면 실행이 허용된다고 판단하지 마세요.
원격 권한 Provider를 사용할 때
권한 판정 원천은 PERMISSION_AUTHORITY_MODE로 internal 또는 deep_permission 중 하나를 선택합니다. 두 원천을 요청마다 섞거나, 한쪽이 실패했을 때 다른 쪽으로 자동 전환하는 계약은 없습니다.
deep_permission 모드에서는 DEEP_PERMISSION_BASE_URL, DEEP_PERMISSION_JWT_SECRET 같은 설정이 필요하며, 원격 서버의 인증 정보는 환경 설정으로 주입해야 합니다. 실제 값을 매뉴얼, 셸 기록, 에이전트 입력에 복사하지 않습니다. 원격 모드는 기동 시 health, capability mapping, management readiness를 순서대로 확인합니다. health 또는 capability mapping이 실패하면 기동을 중단하지만, management readiness에서 404가 돌아오는 경우는 구버전 서버와의 호환성 경고로 처리되어 기동을 막지 않을 수 있습니다. 그 밖의 필수 프로브 실패는 기동 중단으로 이어질 수 있습니다.
원격 읽기 경로에서 일시적인 5xx, timeout, connection failure가 발생하면 유효한 snapshot이 있고 허용된 fail-static 기간 안인 경우에만 마지막 값을 사용할 수 있습니다. 캐시가 없거나 기간을 넘겼다면 권한을 임의로 허용하거나 단순 거부로 바꾸지 않고 Provider 장애로 처리합니다.
실패 유형별 다음 판단
- RBAC_DENIED: 현재 사용자에게 작업 권한이 없습니다. 작업을 반복하기 전에 필요한 action code와 사용자 그룹 배정을 확인합니다.
- ABAC_DENIED: 리소스에 필요한 capability가 없거나 바인딩이 비어 있거나 비활성 상태입니다. 리소스 바인딩과 capability를 확인합니다.
- workspace 범위 거부: 사용자 membership과 workspace 권한을 확인합니다. 전역 권한만으로 workspace 접근이 허용된다고 보지 않습니다.
- 인증·Provider 오류: 시크릿 값을 본문에 다시 넣지 말고 issuer, audience, actor, Provider 상태와 설정된 권위 모드를 운영 경계에서 확인합니다.
- 입력 검증 오류: 권한 문제로 바꾸어 해석하지 않습니다. 요청 형식과 허용된 식별자·필드를 먼저 확인합니다.
오류 응답의 권한 거부는 detail 안의 code로 전달될 수 있습니다. 로그를 공유하거나 지원을 요청할 때는 원래 시크릿과 토큰을 제거하고 오류 코드와 request ID처럼 진단에 필요한 비밀이 아닌 값만 남깁니다.
저장 후 완료 확인
시크릿 또는 권한 설정을 바꾼 뒤에는 다음을 확인합니다.
- 변경 대상이 기대한 사용자, workspace, 에이전트, 리소스인지 확인합니다.
- 변경 응답만 보지 말고 다시 조회해 권한과 리소스 연결 상태를 비교합니다.
- 화면의 capability 표시와 실제 실행 권한을 같은 것으로 단정하지 않습니다. 실행 시점 검사를 비식별 테스트로 확인합니다.
- 시크릿 값이 응답, 로그, 캡처, 공개 문서에 노출되지 않았는지 점검합니다.
- 권한을 바꿨다고 기존 실행이나 다른 구성원의 모델·에이전트 설정까지 바뀌었다고 추정하지 않습니다.
시크릿 값이 노출됐다고 의심되면 같은 값을 반복해서 확인하지 말고 해당 자격 증명의 회전과 접근 로그 확인을 운영 절차에 따라 수행합니다. 이 페이지는 제품의 권한 판정과 비식별 원칙을 설명하며, 특정 배포 환경의 회전 절차나 승인 체계를 대신 정의하지 않습니다.