> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 조직 관리

> 조직 구조 관리, Microsoft Entra ID 동기화, 조직 단위 기반 접근 제어

<Info>관리자 › 사용자 › 조직</Info>

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

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

<Frame caption="조직 관리 화면">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/orgs-main.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=d5534b08f5800a4d679bc3b7ab98d5fe" alt="조직 관리 화면" width="2880" height="1800" data-path="images/admin/orgs-main.png" />
</Frame>

***

## 조직 계층 구조

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

```mermaid theme={null}
flowchart TD
    A[조직 Organization] --> B[조직 단위 OU - Level 0]
    B --> C[조직 단위 OU - Level 1]
    B --> D[조직 단위 OU - Level 1]
    C --> E[조직 단위 OU - Level 2]
    C --> F[조직 단위 OU - Level 2]

    A -.- A1["tenant_id, domain"]
    B -.- B1["type: department"]
    C -.- C1["type: department"]
    E -.- E1["member_ids: 사용자 목록"]
```

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

### 조직 단위 타입

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

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

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

***

## 조직과 그룹의 차이

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

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

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

***

## 조직 생성

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

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

지원되는 동기화 방식:

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

자세한 동기화 방법은 아래 [Microsoft Entra ID 동기화](#microsoft-entra-id-동기화) 및 [JSON Import](#json-import) 섹션을 참고하세요.

***

## Microsoft Entra ID 동기화

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

```mermaid theme={null}
flowchart LR
    A[Microsoft Entra ID] -->|MS Graph API| B[Cloosphere]
    B --> C[조직 생성/업데이트]
    B --> D[조직 단위 트리 구성]
    B --> E[멤버 매핑]
```

### 사전 요구사항

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

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

### 동기화 실행

<Steps>
  <Step title="동기화 창 열기">
    조직 목록 우측 상단 **검색창 옆의 동기화 버튼**(<Icon icon="arrows-rotate" iconType="solid" />)을 클릭하면 **조직 동기화** 창이 열립니다.
  </Step>

  <Step title="데이터 소스 선택">
    **데이터 소스** 드롭다운에서 동기화 방식을 선택합니다 — 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**                 | 특정 그룹만 필터링 (선택)                 |  -  |

    <Frame caption="데이터 소스 = Microsoft Graph 선택 시 동기화 옵션">
      <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/orgs-sync-msgraph.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=4681a4f722955b86dbc63d2b843194b1" alt="Microsoft Graph 동기화 옵션" style={{ maxWidth: '480px' }} width="1024" height="992" data-path="images/admin/orgs-sync-msgraph.png" />
    </Frame>
  </Step>

  <Step title="동기화 실행">
    창 하단의 **"동기화"** 버튼을 클릭합니다.

    <Frame caption="조직 동기화 창 — 데이터 소스 선택(기본값 JSON Import)">
      <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/admin/orgs-sync-modal.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=79ee1e9aca45dd64a7067ebc8c766cdf" alt="조직 동기화 창" style={{ maxWidth: '480px' }} width="1526" height="1379" data-path="images/admin/orgs-sync-modal.png" />
    </Frame>
  </Step>

  <Step title="결과 확인">
    동기화된 조직 단위 트리와 멤버 매핑 결과를 확인합니다.
  </Step>
</Steps>

## JSON Import

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

```json theme={null}
{
  "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 멤버가 리소스를 편집 가능    |

### 권한 상속

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

```mermaid theme={null}
flowchart TD
    A["개발본부 (Read 권한)"] --> B["백엔드팀 (상속)"]
    A --> C["프론트엔드팀 (상속)"]
    B --> D["백엔드팀 멤버: 접근 가능"]
    C --> E["프론트엔드팀 멤버: 접근 가능"]
```

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

### 활용 예시

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

***

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

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

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

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

***

## 조직별 사용량 제한

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

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

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

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

***

## 조직 단위별 가드레일

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

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

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

### 적용 우선순위

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

```mermaid theme={null}
flowchart LR
    A[에이전트 가드레일] --> R([모든 계층<br/>합산 적용])
    G[그룹 가드레일] --> R
    O[조직 단위 가드레일] --> R
    E["전역 가드레일<br/>(전역 상속 ON일 때)"] --> R
```

<Info>
  전역 가드레일은 [관리자 > 설정 > 코드 게이트웨이](/ko/admin/code-gateway)에서 설정합니다. 조직 단위에서 `전역 가드레일 상속`을 끄면 해당 OU는 전역 가드레일의 영향을 받지 않습니다.
</Info>

***

## 동기화 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

<Accordion title="조직 동기화가 실패해요">
  1. Azure App Registration에 `Directory.Read.All` 권한이 있는지 확인하세요.
  2. 환경 변수 `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_CLIENT_TENANT_ID`가 올바르게 설정되었는지 확인하세요.
  3. 서버 로그에서 상세 오류 메시지를 확인하세요.
</Accordion>

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

<Accordion title="조직 단위를 삭제하면 멤버도 삭제되나요?">
  조직 단위를 삭제해도 소속 사용자 계정은 삭제되지 않습니다. 해당 OU에 설정된 리소스 접근 권한만 해제됩니다.
</Accordion>

***

## 관련 페이지

<Columns cols={2}>
  <Card title="사용자 관리" icon="users" href="/ko/admin/users">
    사용자 목록, 역할·그룹, 권한 설정
  </Card>

  <Card title="가드레일" icon="shield-halved" href="/ko/admin/settings/guardrails">
    조직 단위로 적용하는 입출력 안전 정책
  </Card>

  <Card title="사용량" icon="chart-line" href="/ko/monitoring/usage">
    조직·사용자별 사용량 및 비용 모니터링
  </Card>

  <Card title="배포 체크리스트" icon="list-check" href="/ko/admin/deployment-checklist">
    Keycloak/Entra 동기화에 필요한 OIDC 환경변수
  </Card>
</Columns>