조직 관리 - Cloosphere Guide

관리자 › 사용자 › 조직

조직 관리는 기업의 부서 구조를 Cloosphere에 반영하여 리소스 접근을 체계적으로 제어하는 기능입니다.

Microsoft Entra ID(Azure AD), Keycloak, Google Workspace와 동기화하거나, JSON Import로 조직 구조를 직접 구성할 수 있습니다.

조직 계층 구조

Cloosphere의 조직 시스템은 조직(Organization)과 조직 단위(Organizational Unit)의 계층 구조로 구성됩니다.

개념	설명	예시
조직 (Organization)	최상위 엔터티. 테넌트 ID와 도메인으로 식별	”Cloocus Inc.”
조직 단위 (OU)	부서, 팀 등 하위 단위. 계층적으로 중첩 가능	”개발본부 > 백엔드팀”
멤버	조직 단위에 소속된 사용자 목록	user_id 배열

조직 단위 타입

조직 단위는 type 필드로 용도를 구분합니다.

타입	설명
department	부서 (본부, 실 등 상위 조직)
team	팀 (실무 단위 조직)
group	그룹 (프로젝트팀 등 기능적 단위)

현재 운영 환경에서 관측되는 조직 단위는 대부분 department 타입입니다.

조직과 그룹의 차이

Cloosphere는 그룹과 조직 두 가지 사용자 묶음을 제공합니다. 목적에 따라 적절히 사용하세요.

구분	그룹 (Group)	조직 (Organization)
목적	권한 관리	조직 구조 반영
구조	평면 (계층 없음)	트리 (계층 구조)
권한 설정	그룹에 직접 권한 할당	리소스의 access_control에서 OU 지정
외부 연동	수동 관리	Entra ID 자동 동기화
사용 시나리오	”에이전트 생성 권한 부여"	"인사팀만 인사규정 KB 접근”

권한 제어 (무엇을 할 수 있는가)에는 그룹을 사용하고, 접근 제어 (무엇을 볼 수 있는가)에는 조직을 사용하는 것을 권장합니다. 두 시스템을 병행할 수 있습니다.

조직 생성

조직과 조직 단위는 동기화(Sync)를 통해서만 생성됩니다.

수동으로 직접 생성하는 UI는 제공되지 않습니다.

지원되는 동기화 방식:

방식	설명
Microsoft Graph	Entra ID(Azure AD)에서 조직 구조를 자동 동기화
Keycloak	Keycloak 그룹·조직에서 동기화
Google Workspace	Google Workspace 디렉터리에서 동기화
JSON Import	JSON 데이터를 업로드하여 조직 구조를 구성

자세한 동기화 방법은 아래 Microsoft Entra ID 동기화 및 JSON Import 섹션을 참고하세요.

Microsoft Entra ID 동기화

Microsoft Entra ID(Azure AD)와 연동하여 조직 구조를 자동으로 동기화합니다.

사전 요구사항

Entra ID 동기화를 위해서는 Microsoft OAuth 설정이 필요합니다. 다음 환경 변수를 서버에 설정하세요.

환경 변수	설명
`MICROSOFT_CLIENT_ID`	Azure App Registration의 Client ID
`MICROSOFT_CLIENT_SECRET`	Client Secret
`MICROSOFT_CLIENT_TENANT_ID`	Azure AD Tenant ID

동기화 실행

동기화 창 열기

조직 목록 우측 상단 검색창 옆의 동기화 버튼()을 클릭하면 조직 동기화 창이 열립니다.

데이터 소스 선택

데이터 소스 드롭다운에서 동기화 방식을 선택합니다 — JSON Import(기본값) · Microsoft Graph · Keycloak · Google Workspace. Entra ID 연동은 Microsoft Graph 를 선택합니다.Microsoft Graph 선택 시 가져올 항목을 옵션으로 지정합니다.

옵션	설명	기본값
관리 단위 (Administrative Units)	Entra ID의 조직 관리 기능. 계층 구조에 적합	ON
보안 그룹 (Security Groups)	보안 그룹을 조직 단위로 사용. OData 쿼리로 필터링	OFF
부서 (Departments)	사용자 프로필에서 부서명을 자동 추출	OFF
Group Filter	특정 그룹만 필터링 (선택)	-

Microsoft Graph 동기화 옵션 — 데이터 소스 = Microsoft Graph 선택 시 동기화 옵션

동기화 실행

창 하단의 “동기화” 버튼을 클릭합니다.

결과 확인

동기화된 조직 단위 트리와 멤버 매핑 결과를 확인합니다.

JSON Import

Entra ID가 없는 환경에서는 JSON 데이터로 조직 구조를 직접 import할 수 있습니다.

{
  "organization": {
    "tenant_id": "my-company",
    "name": "My Company",
    "domain": "mycompany.com"
  },
  "units": [
    {
      "id": "dept-1",
      "name": "Engineering",
      "type": "department",
      "children": [
        { "id": "team-1", "name": "Backend Team", "type": "team" },
        { "id": "team-2", "name": "Frontend Team", "type": "team" }
      ]
    }
  ]
}

조직 기반 접근 제어

조직 단위를 활용하여 리소스(에이전트, 지식 기반, 데이터베이스 등)의 접근 범위를 제어합니다.

리소스에 조직 단위 권한 설정

각 워크스페이스 리소스의 접근 권한 설정에서 조직 단위를 지정합니다.

접근 레벨	설명
읽기 (Read)	해당 OU 멤버가 리소스를 조회/사용 가능
쓰기 (Write)	해당 OU 멤버가 리소스를 편집 가능

권한 상속

상위 조직 단위에 부여된 권한은 하위 조직 단위로 상속됩니다.

상위 OU에 리소스 접근 권한이 설정되면, 하위 OU의 모든 멤버도 동일한 권한을 자동으로 부여받습니다.

활용 예시

리소스	접근 제어	설명
인사규정 KB	인사팀 OU (Read)	인사팀만 인사규정 조회 가능
영업 에이전트	영업본부 OU (Read)	영업 부서 전체가 사용 가능
매출 DB	경영지원본부 OU (Read)	경영지원 부서만 매출 데이터 조회
전사 공지 KB	최상위 OU (Read)	전체 조직이 접근 가능

조직 단위별 리소스 권한 조회

관리자는 특정 조직 단위에 할당된 리소스 권한을 조회할 수 있습니다. 조회 항목은 다음과 같습니다.

조직 단위별 리소스 권한을 한 화면에 모아 보는 목록은 현재 배포 버전에는 포함되어 있지 않습니다. 개별 권한은 각 리소스(지식 기반·에이전트·데이터베이스 등)의 접근 권한 설정에서 조직 단위 지정 여부로 확인할 수 있습니다.

리소스 종류	조회 항목
지식 기반	이름, 읽기/쓰기, 상속 여부
도구	이름, 읽기/쓰기, 상속 여부
프롬프트	이름, 읽기/쓰기, 상속 여부
모델	이름, 읽기/쓰기, 상속 여부
데이터베이스	이름, 읽기/쓰기, 상속 여부
용어 사전	이름, 읽기/쓰기, 상속 여부

조직별 사용량 제한

조직 단위 상세 패널에서 일별 토큰 제한을 설정할 수 있습니다.

설정	설명
일별 토큰 제한	해당 OU 소속 사용자의 일일 토큰 한도 (0 = 무제한)

이 기능은 관리자 설정에서 사용량 제한 (enable_usage_limit) 기능이 활성화되어 있어야 동작합니다.

사용량 제한은 전역, 사용자, 그룹, 조직 네 계층에서 설정 가능합니다. 여러 계층에 설정된 경우 가장 관대한(높은) 값이 적용됩니다.

조직 단위별 가드레일

조직 단위(OU)에 가드레일을 연결하여 해당 OU 소속 사용자의 AI 입출력을 자동으로 검증할 수 있습니다.

조직 단위 상세 패널의 가드레일 설정에서 구성합니다.

설정	설명
가드레일 선택	이 OU에 적용할 가드레일 목록 (복수 선택 가능)
전역 가드레일 상속	켜면 전역(코드 게이트웨이) 가드레일도 함께 적용. 끄면 OU에 지정한 가드레일만 적용

적용 우선순위

가드레일은 여러 계층에서 설정할 수 있으며, 사용자에게는 모든 계층의 가드레일이 합산되어 적용됩니다.

전역 가드레일은 관리자 > 설정 > 코드 게이트웨이에서 설정합니다. 조직 단위에서 전역 가드레일 상속을 끄면 해당 OU는 전역 가드레일의 영향을 받지 않습니다.

동기화 Provider 목록

현재 지원하는 동기화 Provider는 다음 네 가지입니다.

Provider	설명	요구 사항
JSON Import	JSON 데이터로 직접 구성	없음
Microsoft Graph	Entra ID(Azure AD)에서 자동 동기화	`MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_CLIENT_TENANT_ID`
Keycloak	Keycloak 그룹·조직에서 동기화	`OPENID_PROVIDER_URL`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`
Google Workspace	Google Workspace 디렉터리에서 동기화	`GOOGLE_ADMIN_SERVICE_ACCOUNT_KEY`, `GOOGLE_ADMIN_IMPERSONATE_EMAIL`

FAQ

조직 동기화가 실패해요

Azure App Registration에 Directory.Read.All 권한이 있는지 확인하세요.
환경 변수 MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_CLIENT_TENANT_ID가 올바르게 설정되었는지 확인하세요.
서버 로그에서 상세 오류 메시지를 확인하세요.

조직과 그룹을 모두 사용해야 하나요?

반드시 모두 사용할 필요는 없습니다. 권한 관리만 필요하면 그룹으로 충분합니다. Entra ID와 연동하여 부서 기반 접근 제어가 필요한 경우 조직을 추가로 활용하세요.

조직 단위를 삭제하면 멤버도 삭제되나요?

조직 단위를 삭제해도 소속 사용자 계정은 삭제되지 않습니다. 해당 OU에 설정된 리소스 접근 권한만 해제됩니다.

사용자 관리

사용자 목록, 역할·그룹, 권한 설정

가드레일

조직 단위로 적용하는 입출력 안전 정책

사용량

조직·사용자별 사용량 및 비용 모니터링

배포 체크리스트

Keycloak/Entra 동기화에 필요한 OIDC 환경변수

​조직 계층 구조

​조직 단위 타입

​조직과 그룹의 차이

​조직 생성

​Microsoft Entra ID 동기화

​사전 요구사항

​동기화 실행

​JSON Import

​조직 기반 접근 제어

​리소스에 조직 단위 권한 설정

​권한 상속

​활용 예시

​조직 단위별 리소스 권한 조회

​조직별 사용량 제한

​조직 단위별 가드레일

​적용 우선순위

​동기화 Provider 목록

​FAQ

​관련 페이지

사용자 관리

가드레일

사용량

배포 체크리스트

조직 계층 구조

조직 단위 타입

조직과 그룹의 차이

조직 생성

Microsoft Entra ID 동기화

사전 요구사항

동기화 실행

JSON Import

조직 기반 접근 제어

리소스에 조직 단위 권한 설정

권한 상속

활용 예시

조직 단위별 리소스 권한 조회

조직별 사용량 제한

조직 단위별 가드레일

적용 우선순위

동기화 Provider 목록

FAQ

관련 페이지