조직 관리 - 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 선택 시 가져올 항목을 옵션으로 지정합니다.

옵션	설명	기본값
관리 단위	Entra ID의 조직 관리 기능. 계층 구조에 적합	ON
보안 그룹	보안 그룹을 조직 단위로 사용. OData 쿼리로 필터링	OFF
부서	사용자 프로필에서 부서명을 자동 추출	OFF

Group Filter 입력란은 보안 그룹을 켰을 때만 나타납니다. 특정 그룹만 가져오려면 OData 필터식을 입력하세요(선택 사항).

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

동기화 실행

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

결과 확인

동기화된 조직 단위 트리와 멤버 매핑 결과를 확인합니다. 성공하면 조직 N개, 단위 M개를 동기화했습니다 형태로 건수가 표시되고, 가져올 데이터가 없으면 “옵션을 다르게 켜 보라”는 안내가 나옵니다.

다른 데이터 소스의 옵션

데이터 소스를 Keycloak 또는 Google Workspace로 바꾸면 옵션 구성도 함께 바뀝니다.

Keycloak
Google Workspace

서버 URL과 인증 정보는 화면에서 입력하지 않고 OPENID_PROVIDER_URL · OAUTH_CLIENT_ID · OAUTH_CLIENT_SECRET 환경변수로 설정합니다.

옵션	설명	기본값
그룹	Keycloak 그룹 계층을 조직 단위로 동기화	ON
조직 (v26+)	Keycloak Organizations 기능을 사용 (Keycloak 26 이상 필요)	OFF

옵션	설명	기본값
조직 단위 (OU)	Google Workspace의 조직 단위 계층 구조를 가져옴	ON
그룹	Google Groups를 조직 단위로 가져옴	OFF

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)	전체 조직이 접근 가능

조직 단위 목록 보기

조직을 선택하면 아래에 그 조직의 조직 단위가 계층 순서대로 펼쳐집니다.

요소	설명
들여쓰기	계층 depth를 그대로 반영합니다. 하위 OU일수록 오른쪽으로 밀려납니다
타입 배지	이름 오른쪽의 회색 배지 (`department` · `team` · `group`)
멤버 수 버튼	사람 아이콘 + 숫자. 클릭하면 그 OU의 멤버 목록이 열립니다
타입 탭	타입이 두 종류 이상일 때만 `전체 / 부서 / 팀 / 그룹` 탭이 목록 위에 나타납니다

멤버 목록에는 IdP 동기화로 매핑된 멤버와 OAuth 로그인으로 자동 배정된 사용자가 함께 표시되며, 아직 Cloosphere 계정이 없는 구성원은 미등록으로 구분됩니다.

조직별 사용량 제한

조직 단위별 토큰 한도는 조직 화면이 아니라 관리자 > 설정 > 모델에서 관리합니다. 모델별로 지정하는 값이며, OU 하나에 일괄 적용되는 단일 한도는 없습니다.

사용량 제한 켜기

관리자 > 설정 > 모델 상단의 토큰 제한 버튼을 눌러 토큰 제한 관리 창을 엽니다. 사용량 제한 활성화를 켜고, 필요하면 기본 일별 토큰 제한과 초과 시 동작(경고 / 차단)을 지정합니다.

모델 펼치기

사용량 제한을 켜면 모델 목록의 각 행을 펼칠 수 있습니다. 펼치면 그 모델의 이 모델 기본값과 함께 예외 카드 3장이 나타납니다.

조직 단위 예외 지정

사용자 예외 · 그룹 예외 · 조직 단위 예외 중 조직 단위 예외를 열어 OU별 한도를 지정합니다. 카드에 표시되는 숫자는 현재 등록된 예외 건수입니다.

값	의미
비어 있음	상속 — 상위 계층에서 결정
0	명시적 무제한
양수	일일 토큰 한도

사용량 제한은 전역, 사용자, 그룹, 조직 단위 네 계층에서 설정할 수 있습니다. 여러 계층에 값이 있으면 가장 관대한(높은) 값이 적용되며, 어느 한 계층이라도 0(무제한)이면 그 값이 곧바로 적용됩니다. 예외는 한도를 올리는 용도로 설계되어 있어, 하위 계층에 낮은 값을 넣어 상위 한도를 깎을 수는 없습니다.

조직 단위별 가드레일

조직 단위에 가드레일을 직접 연결하는 화면은 현재 배포 버전에서 제공되지 않습니다. 조직 단위 행에는 멤버 수 버튼만 있습니다.

가드레일은 다음 경로로 적용하세요.

적용 대상	설정 위치
그룹 단위	관리자 > 사용자 > 그룹 및 권한 > 그룹 편집 > 일반 탭의 `채팅 가드레일`
에이전트 단위	워크스페이스 > 에이전트 > 해당 에이전트의 가드레일 설정
전역(AI 코딩 도구)	관리자 > 설정 > 코드 게이트웨이의 `보안` 항목

부서 단위로 가드레일을 걸어야 한다면, 해당 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에 설정된 리소스 접근 권한만 해제됩니다.

사용자 관리

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

그룹 및 권한

OU를 그룹에 매핑해 권한·채팅 가드레일 적용

사용량

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

배포 체크리스트

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

​조직 계층 구조

​조직 단위 타입

​조직과 그룹의 차이

​조직 생성

​Microsoft Entra ID 동기화

​사전 요구사항

​동기화 실행

​다른 데이터 소스의 옵션

​JSON Import

​조직 기반 접근 제어

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

​권한 상속

​활용 예시

​조직 단위 목록 보기

​조직별 사용량 제한

​조직 단위별 가드레일

​조직 삭제

​동기화 Provider 목록

​FAQ

​관련 페이지

사용자 관리

그룹 및 권한

사용량

배포 체크리스트

조직 계층 구조

조직 단위 타입

조직과 그룹의 차이

조직 생성

Microsoft Entra ID 동기화

사전 요구사항

동기화 실행

다른 데이터 소스의 옵션

JSON Import

조직 기반 접근 제어

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

권한 상속

활용 예시

조직 단위 목록 보기

조직별 사용량 제한

조직 단위별 가드레일

조직 삭제

동기화 Provider 목록

FAQ

관련 페이지