> ## 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.

# 일반

> 인증, 기능 활성화 등 시스템 전반의 기본 설정을 관리합니다.

<Info>관리자 › 설정 › 일반</Info>

인증 정책, 로그인 방식, 기능 활성화 등 시스템 전반의 기본 동작을 설정합니다.

* 여기서 변경한 값은 저장 즉시 전체 사용자에게 반영됩니다.

<Frame caption="관리자 > 설정 > 일반에서 인증 정책과 기능 토글을 관리합니다">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/settings-general-full.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=a539307be9fbd57208246af464300565" alt="일반 설정 탭" width="2880" height="1800" data-path="images/admin/settings-general-full.png" />
</Frame>

***

## 인증 설정

사용자 가입·로그인·세션 관련 정책을 설정합니다.

### 기본 사용자 역할

신규 가입자에게 자동 부여되는 역할입니다.

* 가입 직후 서비스 사용 가능 여부가 이 값에서 갈립니다.

| 역할            | 로그인 후 상태                                                                       | 적합 환경                |
| ------------- | ------------------------------------------------------------------------------ | -------------------- |
| **보류 중** (기본) | 승인 대기 화면만 표시, 채팅·워크스페이스 전부 잠김. 관리자가 [사용자 관리](/ko/admin/users)에서 역할을 상향해야 사용 가능 | 가입 후 관리자 승인이 필요한 운영  |
| **사용자**       | 가입 즉시 사용 가능(부여된 그룹 권한 범위 내)                                                    | 사내 SSO 등 신뢰된 사용자만 접속 |
| **관리자**       | 관리자 패널·설정까지 접근                                                                 | 신규 기본값으로는 비권장        |

### 인증 토글

| 설정                 | 목적          | 효과 · 연결                                                             |
| ------------------ | ----------- | ------------------------------------------------------------------- |
| **새 회원가입 활성화**     | 자체 가입 허용    | 로그인 화면에 회원가입 폼 노출. 비활성화 시 [사용자 관리](/ko/admin/users)에서 관리자가 계정 직접 생성 |
| **온보딩 활성화**        | 첫 방문 안내     | 로그인 전 서비스 소개 화면 우선 표시(비활성화 시 로그인 화면 직행)                             |
| **관리자 상세 정보 노출**   | 승인 문의처 안내   | '보류 중' 사용자의 승인 대기 화면 하단에 관리자 이름·이메일 표시                              |
| **API 키 활성화**      | 외부 프로그램 연동  | 개인 API 키(`sk-…`) 발급 허용 **→** 외부 스크립트·자동화 도구에서 Cloosphere API 호출     |
| **API 키 엔드포인트 제한** | API 키 범위 축소 | **허용 Endpoints**에 등록한 경로만 API 키 호출 허용, 그 외 차단                       |
| **JWT 만료**         | 세션 유지 기간    | 지정 기간 경과 시 자동 로그아웃·재로그인 필요 (`-1` = 만료 없음)                           |

<Note>
  JWT 만료 형식: `30m`(분), `1h`(시간), `10d`(일), `1w`(주), `-1`(만료 없음). `-1`은 편하지만 토큰 유출 시 회수가 어려우므로, 기업 환경에서는 `8h` \~ `1d`를 권장합니다.
</Note>

### Email 비식별화

환경변수 `ENABLE_EMAIL_DEIDENTIFY=true`로 활성화하면, 사용자 이메일 주소에서 **@ 이후 도메인 부분을 제거**하고 ID 부분만 저장합니다.

| 항목            | 비활성화 (기본)           | 활성화 시             |
| ------------- | ------------------- | ----------------- |
| **로그인/가입 라벨** | "Email"             | "Account ID"      |
| **입력 필드**     | `type="email"`      | `type="text"`     |
| **이메일 검증**    | @ 포함 필수             | 형식 무관 (사번, ID 허용) |
| **저장 값**      | `sykim@cloocus.com` | `sykim`           |

<Note>
  SSO/LDAP 환경에서 전체 이메일 주소를 DB에 저장하지 않아야 하는 **개인정보 보호 요건**이 있을 때 사용합니다. OAuth 로그인 사용자에게도 동일하게 적용됩니다.
</Note>

<Note>
  **SSO/OIDC(Keycloak·Entra ID·Google) 연동**은 GUI가 아니라 서버 **환경변수**(`OPENID_PROVIDER_URL`·`OAUTH_CLIENT_ID`/`SECRET` 등)로 설정합니다 → [배포 체크리스트](/ko/admin/deployment-checklist) 참조.
</Note>

***

## LDAP 설정

기업 LDAP/Active Directory 서버와 연동해 통합 인증을 구성합니다.

* 활성화 시 로그인 화면에 LDAP 옵션이 나타나고, 서버 접속 정보 입력 폼이 펼쳐집니다.
* LDAP 사용자가 처음 로그인하면 계정이 자동 생성되며, 기본 역할은 위 **기본 사용자 역할**이 적용됩니다.

<Accordion title="LDAP 연동 설정 항목" icon="server">
  | 설정 항목                       | 설명                       | 예시                                       |
  | --------------------------- | ------------------------ | ---------------------------------------- |
  | **Label**                   | LDAP 서버 식별 이름            | `Corporate AD`                           |
  | **Host**                    | LDAP 서버 주소               | `ldap.example.com`                       |
  | **Port**                    | 연결 포트 (TLS 활성화 시 636 기본) | `389`                                    |
  | **Application DN**          | 바인드 계정 DN                | `cn=admin,dc=example,dc=com`             |
  | **Application DN Password** | 바인드 계정 비밀번호              | -                                        |
  | **Attribute for Mail**      | 이메일 매핑 LDAP 속성           | `mail`                                   |
  | **Attribute for Username**  | 사용자명 매핑 LDAP 속성          | `uid`, `sAMAccountName`                  |
  | **Search Base**             | 사용자 검색 기준                | `ou=users,dc=example,dc=com`             |
  | **Search Filters**          | LDAP 검색 필터 (선택)          | `(&(objectClass=inetOrgPerson)(uid=%s))` |
  | **TLS**                     | TLS 암호화 통신 사용            | 비활성화                                     |
  | **Certificate Path**        | 인증서 경로 (TLS 활성 시 표시)     | -                                        |
  | **Ciphers**                 | 허용 암호 스위트 (TLS 활성 시 표시)  | -                                        |
</Accordion>

<Warning>
  LDAP 설정은 즉시 적용됩니다. 잘못된 설정 시 사용자 로그인이 차단될 수 있으므로 테스트 계정으로 먼저 검증하세요.
</Warning>

***

## 기능 토글

시스템 전체에서 특정 기능의 활성화 여부를 제어합니다.

* 비활성화 시 관련 메뉴·버튼이 사용자 화면에서 사라지고 해당 API 호출도 차단됩니다.

| 기능          | 목적           | 효과 · 연결                                                                                                 |
| ----------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| **커뮤니티 공유** | 외부 커뮤니티 연동   | 모델·프롬프트·채팅에 "커뮤니티에 공유" 버튼 노출 **→** [openwebui.com 커뮤니티](https://openwebui.com)와 모델·프롬프트 교환              |
| **메시지 평가**  | 응답 품질 피드백 수집 | AI 응답에 좋아요·싫어요 버튼 표시 **→** [평가](/ko/monitoring/evaluations)·[피드백](/ko/monitoring/feedback) 모니터링의 원본 데이터 |
| **채널 (베타)** | 팀 채팅         | 팀 채팅용 채널 기능 제공                                                                                          |
| **사용자 웹훅**  | 부재 중 개인 알림   | 사용자별 개인 웹훅 등록 허용 **→** 부재 중 완료 응답·[채널](/ko/admin/notifications) 메시지를 Slack·Teams 등으로 수신                 |

### 알림용 URL

기능 토글 아래에서 알림에 쓰이는 두 URL을 설정합니다.

* 이름이 비슷한 아래 세 항목은 역할이 서로 다릅니다.

| 항목                | 목적       | 효과 · 연결                                                       |
| ----------------- | -------- | ------------------------------------------------------------- |
| **WebUI URL**     | 알림 링크 생성 | 알림 메시지 내 "대화 열기" 링크(`…/c/…`) 생성용 공개 주소(발송 아님)                 |
| **Webhook URL**   | 신규 가입 알림 | 신규 가입·최초 SSO 로그인 시 관리자용 단일 URL로 알림 발송(Slack·Teams·Discord 지원) |
| **사용자 웹훅** (위 토글) | 개인 부재 알림 | 사용자 개개인이 각자 등록하는 개인 경로 — 위 둘과 별개                              |

<AccordionGroup>
  <Accordion title="새로 가입한 사용자가 로그인은 되는데 아무 기능도 못 써요" icon="circle-question">
    **기본 사용자 역할**이 '보류 중'(기본값)이면 정상 동작입니다. 가입자는 관리자 승인 전까지 "계정 승인 대기" 화면만 보게 됩니다. [사용자 관리](/ko/admin/users)에서 해당 사용자의 역할을 **사용자**로 바꾸면 바로 이용할 수 있습니다. 매번 승인이 번거롭다면 기본 사용자 역할 자체를 **사용자**로 변경합니다. 단, 아무나 가입해 즉시 사용하게 되므로 신뢰된 환경에서만 회원가입을 여세요.
  </Accordion>

  <Accordion title="LDAP과 로컬 계정을 동시에 사용할 수 있나요?" icon="circle-question">
    네. LDAP이 활성화되어도 기존 로컬 계정(이메일/비밀번호)으로 로그인할 수 있습니다. LDAP 사용자가 처음 로그인하면 자동으로 계정이 생성됩니다. 기본 역할은 "인증 설정"의 **기본 사용자 역할**이 적용됩니다.
  </Accordion>
</AccordionGroup>