> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/user/security.md).

# 보안 관리

## 목차

* [개요](#overview)
* [화면 구성 — 3개 하위 메뉴](#layout)
* [사용자 화면](#user)
  * [사용자 목록 테이블](#user-list)
  * [사용자 추가/수정 양식](#user-form)
  * [사용자 역할 의미](#user-roles)
* [보안 정책 화면](#security-policy)
  * [보안 정책 목록 테이블](#security-list)
  * [보안 정책 양식](#security-form)
* [API 인증 토큰 화면](#api-token)
  * [토큰 목록 테이블](#token-list)
  * [토큰 추가/수정 양식](#token-form)
  * [API 토큰 배포](#token-deploy)
  * [접근 가능한 IP 패턴](#token-ip)
* [활용 시나리오](#use-cases)
* [자주 묻는 질문](#faq)
* [관련 화면](#related)

***

## 개요 <a href="#overview" id="overview"></a>

System 그룹의 보안 관리 항목은 **사용자 계정**, **보안 정책**(역할 외 추가 권한 그룹), **API 인증 토큰**(외부 시스템이 플랫폼 API 를 호출할 때 사용하는 키) 세 가지를 관리합니다. 모든 메뉴는 ADMIN 권한을 가진 시스템 관리자만 접근할 수 있습니다.

이 화면은 다음 작업에 사용됩니다.

* 신규 운영자 계정 발급·기존 사용자 정보 수정·삭제
* 사용자별 보안 정책 부여
* 외부 시스템(MES·ERP 등)이 플랫폼 API 를 호출할 수 있도록 토큰 발급·IP 제한·배포

**경로**: 왼쪽 메뉴 > **System > 사용자 / 보안 정책 / API 토큰**

***

## 화면 구성 — 3개 하위 메뉴 <a href="#layout" id="layout"></a>

| 하위 메뉴         | URL               | 용도                             |
| ------------- | ----------------- | ------------------------------ |
| **사용자**       | `/user/index`     | 시스템에 로그인할 수 있는 사용자 계정 관리       |
| **보안 정책**     | `/security/index` | 사용자에게 부여할 수 있는 권한 그룹(보안 정책) 관리 |
| **API 인증 토큰** | `/token/index`    | 외부 API 호출용 인증 토큰 발급·IP 제한·배포   |

각 하위 메뉴는 **목록 화면**(`index.jsp`)과 **양식 화면**(`form.jsp`)으로 구성되어, 목록에서 항목을 추가/수정 클릭 시 양식 화면으로 전환됩니다.

***

## 사용자 화면 <a href="#user" id="user"></a>

**경로**: 보안 > **사용자** (`/user/index`)

상단에는 페이지 제목 "사용자" 와 우측 **사용자 추가** 빨강 버튼이 있습니다.

### 사용자 목록 테이블 <a href="#user-list" id="user-list"></a>

```
┌──────────────────────────────────── 목록 ────────────────────────────────────┐
│  - │ 로그인 ID │ 이름 │ 팀명 │ 이메일 │ 전화 │ 역할 │ 보안정책 │ 등록일 │ 마지막 수정일 │ 액션 │
└─────────────────────────────────────────────────────────────────────────────┘
```

| 컬럼          | 폭     | 정렬  | 표시                                    |
| ----------- | ----- | --- | ------------------------------------- |
| **체크/선택**   | 40px  | 가운데 | 행 선택 (운영 환경에 따라 활성/비활성)               |
| **로그인 ID**  | 120px | 가운데 | 사용자가 로그인할 때 사용하는 ID                   |
| **이름**      | 100px | 가운데 | 표시 이름                                 |
| **팀명**      | 자동    | 가운데 | 소속 팀(`address` 필드 — 양식에선 "팀명" 라벨로 표시) |
| **이메일**     | 200px | 가운데 | 이메일 주소                                |
| **전화**      | 200px | 가운데 | 휴대폰 번호                                |
| **역할**      | 80px  | 가운데 | ADMIN / API / USER 중 하나               |
| **보안정책**    | 120px | 가운데 | 부여된 보안 정책명 (없으면 비어 있음)                |
| **등록일**     | 150px | 가운데 | 계정 등록 시각                              |
| **마지막 수정일** | 150px | 가운데 | 정보 마지막 수정 시각                          |
| **액션**      | 80px  | 가운데 | 수정·삭제 버튼                              |

### 사용자 추가/수정 양식 <a href="#user-form" id="user-form"></a>

상단의 **사용자 추가** 버튼 또는 목록의 액션 버튼으로 양식 화면으로 이동합니다.

#### 1) 로그인 fieldset

| 입력         | path          | 폭     | 비고                                                                     |
| ---------- | ------------- | ----- | ---------------------------------------------------------------------- |
| **로그인 ID** | `user_id`     | 200px | 영문/숫자/언더스코어 권장                                                         |
| **패스워드**   | `password`    | 200px | **신규 등록 시(`mode='I'`)에만 표시**. 수정 모드에서는 보안상 입력 필드 숨김 — 비밀번호 변경은 별도 흐름   |
| **역할**     | `role`        | 200px | 셀렉터 — ADMIN/API/USER (변경 시 보안 필드 자동 토글)                                |
| **보안**     | `security_id` | 200px | 셀렉터 — 등록된 보안 정책 중 선택 (역할이 API 등 특정 케이스일 때 보임. `toggleSecurityField()`) |

#### 2) 기본 정보 fieldset

| 입력      | path      | 폭     | placeholder                           |
| ------- | --------- | ----- | ------------------------------------- |
| **이름**  | `name`    | 200px | —                                     |
| **이메일** | `email`   | 200px | —                                     |
| **휴대폰** | `phone`   | 200px | "휴대폰번호는 숫자만 입력하여 주십시오. 예) 0104125678" |
| **팀명**  | `address` | 450px | —                                     |

#### 3) 추가 속성 fieldset

| 입력     | path      | 폭                      |
| ------ | --------- | ---------------------- |
| **노트** | `attr_01` | 800px × 150px (텍스트 영역) |

#### 폼 제출

| 버튼        | 위치             | 동작                           |
| --------- | -------------- | ---------------------------- |
| **목록(☰)** | 좌측             | `index()` — 사용자 목록 화면으로 돌아가기 |
| **저장**    | 우측 (파랑, 100px) | `saveEvent()` — 입력 검증 후 저장   |

### 사용자 역할 의미 <a href="#user-roles" id="user-roles"></a>

| 역할        | 라벨      | 설명                               |
| --------- | ------- | -------------------------------- |
| **ADMIN** | 시스템 관리자 | 모든 메뉴 접근. 사용자·보안 정책·시스템 설정 변경 가능 |
| **API**   | API 개발자 | API 호출용 계정. 보안 정책 필수 부여          |
| **USER**  | 일반 사용자  | 조회 중심 메뉴만 접근. 변경 권한 없음           |

> 역할 변경은 즉시 반영되지만, 사용자가 이미 로그인 중이면 다음 로그인 시 새 역할이 적용됩니다.

***

## 보안 정책 화면 <a href="#security-policy" id="security-policy"></a>

**경로**: 보안 > **보안 정책** (`/security/index`)

상단에는 페이지 제목 "보안 정책" 과 우측 **보안 추가** 빨강 버튼이 있습니다.

### 보안 정책 목록 테이블 <a href="#security-list" id="security-list"></a>

```
┌────────────────────────────── 목록 ──────────────────────────────┐
│  - │ 보안 ID │ 보안명 │ 설명 │ 등록일 │ 마지막 수정일 │ 액션 │
└──────────────────────────────────────────────────────────────────┘
```

| 컬럼          | 폭     | 표시                                 |
| ----------- | ----- | ---------------------------------- |
| **체크/선택**   | 40px  | 행 선택                               |
| **보안 ID**   | 150px | 시스템이 부여한 식별자 (예: `SECURITY_00001`) |
| **보안명**     | 250px | 사람이 읽기 쉬운 이름 (영문/숫자/`_`만 허용)       |
| **설명**      | 자동    | 정책 용도 메모                           |
| **등록일**     | 150px | 정책 등록 시각                           |
| **마지막 수정일** | 150px | 정책 마지막 수정 시각                       |
| **액션**      | 80px  | 수정·삭제 버튼                           |

### 보안 정책 양식 <a href="#security-form" id="security-form"></a>

#### 1) 기본정보 fieldset

| 입력        | path            | 폭     | 비고                                                   |
| --------- | --------------- | ----- | ---------------------------------------------------- |
| **보안 ID** | `security_id`   | 200px | **읽기 전용** — 시스템 자동 부여                                |
| **보안 명**  | `security_name` | 300px | placeholder: `SECURITY_NAME_00001 (영문 및 숫자, _ 만 입력)` |
| **설명**    | `security_desc` | 500px | 자유 텍스트                                               |

#### 2) 권한 fieldset

> 권한 상세(에셋 단위 오브젝트 권한 부여 UI)는 2026-03-21 자로 비활성화되었습니다. 현재 보안 정책은 **이름 + 설명** 만 등록·관리하며, 실제 권한 적용은 사용자의 역할(ADMIN/API/USER)을 기준으로 동작합니다.

#### 폼 제출

| 버튼        | 위치             | 동작                 |
| --------- | -------------- | ------------------ |
| **목록(☰)** | 좌측             | 보안 정책 목록 화면으로 돌아가기 |
| **저장**    | 우측 (파랑, 100px) | 입력 검증 후 저장         |

***

## API 인증 토큰 화면 <a href="#api-token" id="api-token"></a>

**경로**: 보안 > **API 인증 토큰** (`/token/index`)

API 인증 토큰은 외부 프로그램(MES/ERP/연동 도구 등)이 플랫폼 API 를 호출할 때 사용하는 키입니다. 토큰별로 사용 가능한 IP 대역을 제한할 수 있어 보안성을 높일 수 있습니다.

### 토큰 목록 테이블 <a href="#token-list" id="token-list"></a>

상단에는 페이지 제목 "API 인증 토큰" 과 우측 **API 토큰 추가**·**새로고침** 두 빨강 버튼이 있습니다. 목록 패널의 헤더 우측에는 **API 토큰 배포** 버튼(120px)이 있습니다.

| 컬럼            | 폭     | 표시                   |
| ------------- | ----- | -------------------- |
| **체크/선택**     | 40px  | 행 선택                 |
| **인증 토큰**     | 380px | 발급된 토큰 문자열 (16자리 이상) |
| **로그인 ID**    | 200px | 토큰을 발급받은 사용자 ID      |
| **접근 가능한 IP** | 200px | 토큰 사용이 허용된 IP 패턴     |
| **설명**        | 자동    | 토큰 용도                |
| **액션**        | 80px  | 수정·삭제 버튼             |

### 토큰 추가/수정 양식 <a href="#token-form" id="token-form"></a>

상단의 **API 토큰 추가** 버튼으로 양식 화면으로 이동합니다.

#### 안내 메시지(파란 박스)

```
ℹ️ API 인증 토큰 도움말
  API 인증 토큰은 API를 통해 플랫폼에 명령과 데이터 조회 등에 사용할 수 있는 보안 토큰입니다.
  • 접근 가능한 IP는 단일 IP 및 IP 대역, 모두 허용으로 등록할 수 있습니다.
    (예) 192.168.0.110, 192.168.10.*, 192.*, *
  • 토큰은 영문 또는 숫자, 특수문자를 포함하여 16자리 이상으로 등록하여 주십시오.
```

#### 1) 인증 정보 fieldset

| 입력               | path       | 폭     | 설명                                           |
| ---------------- | ---------- | ----- | -------------------------------------------- |
| **로그인 ID**       | `login_id` | 200px | 토큰을 발급받을 사용자 ID (사용자 화면에 등록된 계정)             |
| **접근 가능한 IP**    | `ip`       | 400px | 단일 IP 또는 와일드카드 패턴 (아래 [IP 패턴](#token-ip) 참고) |
| **인증 토큰**        | `token`    | 700px | 직접 입력하거나 우측 **API 토큰 자동 생성** 버튼으로 무작위 생성     |
| **API 토큰 자동 생성** | (버튼)       | 자동    | `generate()` — 16자리 이상 안전 토큰 자동 생성           |

#### 2) 추가 속성 fieldset

| 입력     | path          | 폭                      | 설명                 |
| ------ | ------------- | ---------------------- | ------------------ |
| **설명** | `description` | 700px × 100px (텍스트 영역) | 어떤 시스템·연동에 사용할지 메모 |

#### 폼 제출

| 버튼        | 위치             | 동작              |
| --------- | -------------- | --------------- |
| **목록(☰)** | 좌측             | 토큰 목록 화면으로 돌아가기 |
| **저장**    | 우측 (파랑, 100px) | 입력 검증 후 저장      |

### API 토큰 배포 <a href="#token-deploy" id="token-deploy"></a>

토큰을 **저장만** 했을 때는 인증 서버에 아직 적용되지 않은 상태입니다. 등록·수정·삭제한 토큰을 실제로 사용하려면 **API 토큰 배포** 버튼을 눌러야 합니다.

| 항목        | 설명                                        |
| --------- | ----------------------------------------- |
| **버튼 위치** | 토큰 목록 패널의 헤더 우측                           |
| **버튼 라벨** | "API 토큰 배포"                               |
| **툴팁**    | "등록 및 수정, 삭제된 토큰을 사용할 수 있도록 인증서버에 배포합니다." |
| **동작**    | `deployToken()` — 변경된 토큰 일괄을 인증 서버에 배포    |

> 운영 안전 절차: 새 토큰을 등록하면 즉시 외부에서 사용되도록 **API 토큰 배포** 를 잊지 마세요. 반대로 사용 중인 토큰을 삭제하면 배포 직후부터 외부 호출이 차단됩니다.

### 접근 가능한 IP 패턴 <a href="#token-ip" id="token-ip"></a>

| 패턴              | 의미                                   |
| --------------- | ------------------------------------ |
| `192.168.0.110` | 정확한 단일 IP만 허용                        |
| `192.168.10.*`  | 192.168.10.0 \~ 192.168.10.255 대역 허용 |
| `192.168.*`     | 192.168.0.0 \~ 192.168.255.255 대역 허용 |
| `192.*`         | 192.0.0.0 \~ 192.255.255.255 대역 허용   |
| `*`             | 모든 IP 허용 (보안상 권장하지 않음)               |

> 운영 환경에서는 가능한 한 **단일 IP** 또는 **C 클래스(`x.x.x.*`) 대역**으로 제한하시기 바랍니다.

***

## 활용 시나리오 <a href="#use-cases" id="use-cases"></a>

| 시나리오                   | 절차                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **신규 운영자 계정 발급**       | 사용자 → **사용자 추가** → 로그인 ID·패스워드·이름·이메일·역할(USER) 입력 → 저장                                          |
| **외부 분석가에게 API 권한 부여** | 1) 보안 정책 → API 분석 정책 등록 2) 사용자 → 새 사용자 추가, 역할 API + 보안 정책 부여 3) API 인증 토큰 → 그 사용자에 토큰 발급, IP 제한 |
| **MES 연동 API 토큰 발급**   | API 인증 토큰 → 추가 → 로그인 ID(연동 전용 계정) + IP 패턴 + 자동 생성 → 저장 → **API 토큰 배포**                          |
| **사용 중인 토큰 회전**        | 새 토큰 발급 → 외부 시스템에 새 토큰 적용 → 기존 토큰 삭제 → 배포                                                       |
| **퇴사자 계정 비활성**         | 사용자 목록 → 해당 사용자 액션 → 삭제 (또는 역할을 USER 로 강등 후 패스워드 변경)                                            |

***

## 자주 묻는 질문 <a href="#faq" id="faq"></a>

**Q. 사용자 수정 화면에 패스워드 입력란이 안 보입니다.** A. 정상 동작입니다. 신규 등록 시(`mode='I'`)에만 패스워드 필드가 표시됩니다. 비밀번호 변경은 사용자가 직접 로그인 후 사용자 메뉴 → "비밀번호 변경" 으로 진행해야 합니다. 관리자가 강제로 초기화해야 한다면 사용자를 삭제 후 재등록하시거나 별도의 비밀번호 초기화 절차를 사용하세요.

**Q. 보안 정책의 ID 가 자동 부여되는데 직접 정할 수 없나요?** A. 보안 ID 는 시스템이 자동 부여합니다(읽기 전용). 사람이 식별하는 이름은 **보안 명** 필드에 영문·숫자·`_` 만 사용해 등록하세요.

**Q. 보안 정책의 권한 상세가 비어 있습니다.** A. 에셋 단위 권한 부여 UI 는 2026-03-21 부로 비활성화되었습니다. 현재 권한은 사용자 역할(ADMIN/API/USER)에 따라 결정됩니다. 보안 정책은 이름·설명을 통한 그룹 분류 용도로 사용됩니다.

**Q. API 토큰을 등록했는데 외부에서 호출이 안 됩니다.** A. 토큰을 등록·수정·삭제한 후에는 반드시 **API 토큰 배포** 버튼을 누르셔야 합니다. 또한 호출 측 IP 가 토큰의 "접근 가능한 IP" 패턴에 포함되는지 확인하세요.

**Q. 토큰의 "접근 가능한 IP" 를 변경했습니다. 즉시 반영되나요?** A. 변경 후 **API 토큰 배포** 를 눌러야 인증 서버에 반영됩니다. 배포 완료까지는 외부 호출이 이전 IP 정책으로 동작합니다.

**Q. 토큰 자동 생성 시 어떤 형식의 토큰이 만들어지나요?** A. 영문·숫자·특수문자 16자리 이상의 안전한 토큰이 무작위로 생성됩니다. 보안상 직접 단순한 토큰을 입력하시지 말고 자동 생성을 사용하시기 바랍니다.

**Q. API 사용자(역할 API)에는 왜 보안 정책이 필수인가요?** A. API 호출이 어떤 권한 그룹에 속하는지 명시하기 위함입니다. 추후 권한 정책이 강화될 때를 대비해 그룹 단위로 관리합니다.

**Q. 비밀번호 정책(길이, 복잡도)을 강제로 적용할 수 있나요?** A. 운영 환경 설정에 따라 다르며 화면에서 직접 변경하시는 항목은 아닙니다. 정책 변경이 필요하면 시스템 설정으로 관리자에게 문의하세요.

**Q. 사용자 동시 로그인을 막을 수 있나요?** A. 기본적으로 동시 로그인이 허용됩니다. 운영 환경 설정으로 단일 세션만 허용하도록 변경할 수 있으니 관리자에게 문의하세요.

**Q. 토큰 사용 이력을 어디서 볼 수 있나요?** A. 토큰 사용 이력은 [진단](/plantpulse-platform/user/diagnostic.md) 화면의 SERVER 애플리케이션 로그에서 확인할 수 있습니다. 인증 실패는 ERROR 레벨로 기록됩니다.

***

## 관련 화면 <a href="#related" id="related"></a>

* [로그인](/plantpulse-platform/user/login.md) — 사용자 로그인 절차·역할별 메뉴 차이
* [진단](/plantpulse-platform/user/diagnostic.md) — 인증 실패·토큰 사용 이력 로그
* [시스템 > 설정](/plantpulse-platform/user/system.md) — 비밀번호 정책 등 운영 환경 설정