User Management

Overview

This document explains how to manage user accounts, security groups, and permissions on the PlantPulse platform. User management is performed from the left menu System > Users (/user/index).

User Structure

User management in PlantPulse consists of three core elements.

• User: An individual account that logs into the platform.
• Security Group: A group that defines a user's role. Each user belongs to exactly one security group.
• Permission: Function-level access rights assigned to a security group. Controls access to menus, screens, and APIs.

The Three Roles

The product provides exactly three roles.

Role	Display Name	Purpose
ADMIN	System Administrator	Full functionality. Can change other users' passwords and perform user management
API	API Developer	Accounts for external system integration
USER	General User	Basic functionality

There is no OPERATOR · ENGINEER · VIEWER

These names appeared in older documentation, but they are not roles that exist in the product. They do not appear as role options on the user registration screen either.

MANAGER only exists "half-way" — do not use it

MANAGER is a different case from the three above.

User registration screen	Not in the options. The save path only accepts ADMIN·API·USER
Server access control	Exists — equipment command execution rules, and the conditions for exposing write buttons on tag, connection, and alarm screens are "ADMIN or MANAGER"
POST /api/v5/user	Does not validate the role value, so MANAGER is saved as-is
After login	The only navigation branches are ADMIN/API → Dashboard and USER → Shared Screen — MANAGER accounts stop at the loading screen

Therefore, inserting MANAGER via API makes an account unusable. If you already have such an account, change its role to one of the three.

Principle of Least Privilege: Start accounts used by people with USER, and only grant ADMIN to those who need to perform administration.

User Attributes

Attribute	Required	Description
User ID	O	Unique identifier used for login (English letters, numbers, 4~20 characters)
User Name	O	Name displayed on the screen
Password	O	Login password (12~50 characters, see Password Policy below)
Email	-	Email address for receiving notifications
Role	O	One of ADMIN / API / USER
Status	O	Active or Inactive
Description	-	Remarks about the user
Created	Automatic	Account creation timestamp
Last Login	Automatic	Timestamp of the last login

Viewing the User List

Select System > Users from the left menu to view the list of registered users.

• URL: /user/index
• You can view the user ID, name, security group, status, and last login timestamp.
• Use the search filter to quickly find a specific user.

Note: Only users belonging to the ADMIN security group can view the user list.

Adding a User

1. Click the Add button on the user list screen.
2. Enter the required fields.
   • User ID: A unique ID consisting of English letters and numbers (4~20 characters)
   • User Name: The name to display on the screen
   • Password: Must be 12~50 characters and include at least 3 of 4 character types: uppercase letters, lowercase letters, numbers, and special characters. If it doesn't meet this requirement, saving is rejected.
   • Role: Select one of ADMIN / API / USER.
3. Enter optional fields (email, description, etc.) as needed.
4. Click the Save button.

Note: The user ID cannot be changed after creation. Please set it carefully.

Modifying a User

1. Click on the user you want to modify in the user list.
2. Change the editable fields (name, email, security group, status, description, etc.).
3. Click the Save button.

Note: The user ID cannot be modified. To change the ID, you must delete the existing user and create a new one.

Deleting a User

1. Select the user to delete in the user list.
2. Click the Delete button.
3. Click Confirm in the confirmation popup.

Caution: Deleted users cannot be recovered. To temporarily block a user, we recommend using Deactivate instead of deletion.

Deactivating a User

To block a user from logging in without deleting the account, use the deactivation feature.

1. Change the Status to Inactive on the user edit screen.
2. Click the Save button.

A deactivated user is blocked from logging in, but their data (audit logs, configuration history, etc.) is retained. To reactivate, change the status to Active.

---

Password Management

Passwords are changed in one place on the screen — the System > Users list in the left menu.

Changing a Password (Replacing the Default Password)

This is the method for changing the default password right after installation.

1. Open System > Users from the left menu.
2. Click the 🔑 key icon on the target user's row (tooltip: "Change Password").
3. Enter the new password. If it's your own account, you must also enter your current password.
4. Save.

There are defined rules for who can change whose password.

Target	Required Permission	Current Password Verification
Self	None (as long as you're logged in)	Required — rejected if incorrect
Another User	ADMIN	Not required

If a user who is not ADMIN tries to change someone else's password, it is rejected and an audit record is written to the server log. Successful changes are also recorded in the form of Password changed: session_user=[...], target_user=[...].

The same can be done via the REST API.

POST /api/v5/user/{user_id}/password
Content-Type: application/json

{ "current_password": "<current-password>", "password": "<new-password>" }

Handling a Lost Password

• Request from an administrator: A ADMIN user initializes it using the procedure above.
• Direct DB initialization (emergency only): Use this only if accounts, including ADMIN, are all locked.

Entering SHA-256 will permanently lock the account

Passwords are stored as BCrypt hashes. If you insert a value using the encode(digest(..., 'sha256'), 'hex') method described in older documentation, the BCrypt verification at login will fail to interpret that string, making it impossible to log in with any password. This procedure is used precisely when accounts are already locked, so it eliminates any recovery path.

The table name is also not pp_user, but USER_LOGIN.

First create a BCrypt hash, then insert that value.

# BCrypt 해시 생성 (htpasswd — apache2-utils / httpd-tools 패키지)
htpasswd -bnBC 10 "" '<new-password>' | tr -d ':\n'
# → $2y$10$... 형태의 문자열이 나옵니다

-- 비상 시에만. 위에서 만든 BCrypt 해시를 그대로 넣습니다.
UPDATE USER_LOGIN
SET PASSWORD = '<$2y$10$... paste-here>'
WHERE USER_ID = 'admin';

After inserting, always verify by logging in, and if successful, change the password once more through the normal screen procedure. For infrastructure service accounts (PostgreSQL, Aster TSDB, RustFS, etc.), follow Password Change (Credential Rotation), not this document — deviating from that order will prevent the platform from starting.

Password Policy

What the product enforces — violating anything below will reject the save outright.

Item	Value
Length	12 to 50 characters
Complexity	At least 3 of 4 character types: uppercase letters, lowercase letters, numbers, special characters

What the product does not enforce — these must be managed through operational policy. The platform has no functionality for the items below, so if needed, address them through your organization's procedures.

Item	Status
Enforced change cycle · expiration	Not available
Prohibition of reusing previous passwords	Not available
Dictionary word blocking	Not available
Permanent account lockout	Not available — instead, there is a temporary block described below

Brute-Force Attack Blocking (Temporary Block)

Accumulated login failures do not lock the account; instead, requests are blocked for a period of time (HTTP 429 + Retry-After). This resolves automatically after time passes, so there is no need for an administrator to unlock it.

Setting	Property	Default
Feature enabled	engine.session.bruteforce.enabled	Enabled
Failed attempts allowed per IP	engine.session.bruteforce.ip_limit	30
Failed attempts allowed per account	engine.session.bruteforce.user_limit	10
Aggregation window	engine.session.bruteforce.window.seconds	300 seconds (5 minutes)

The block is counted separately for the IP basis and the account basis. In an office where multiple people share the same public IP, others' failures can collectively consume the IP limit (30). Both blocks and failures are recorded in the audit log (LOGIN_BLOCKED / LOGIN_FAILURE).

---

Security Group Management

Default Security Groups

PlantPulse provides three default security groups.

Security Group	Description	Key Permissions
ADMIN	System Administrator	Full feature access (user management, system settings, all menus)
OPERATOR	Operator	Operational feature access (monitoring, alarm management, data queries)
USER	General User	Basic feature access (dashboard viewing, data queries)

Adding a Security Group

In addition to the default groups, you can add security groups that fit your organization's roles.

1. Select Security Management > Security Groups from the menu.
2. Click the Add button.
3. Enter the group ID, group name, and description.
4. Click the Save button.

Setting Permissions

Configure menu and function-level permissions for a security group.

1. Select the group from Security Management > Security Groups.
2. Click the Permission Settings tab.
3. Check Read, Write, and Delete permissions for each menu/function.
4. Click the Save button.

Example permission settings:

Menu	ADMIN	OPERATOR	USER
Connection Management	Read/Write/Delete	Read/Write	Read
Factory Management	Read/Write/Delete	Read/Write	Read
Alarm Management	Read/Write/Delete	Read/Write	Read
User Management	Read/Write/Delete	-	-
System Settings	Read/Write/Delete	Read	-
Canvas	Read/Write/Delete	Read/Write	Read

---

Access Control

Site Access Control

In multi-site environments, you can restrict the sites a user can access.

1. Select the Site Access Permissions tab on the user edit screen.
2. Check the sites you want to grant access to.
3. Click the Save button.

Note: Users without site access permissions configured can access all sites.

Canvas Sharing

Canvas screens can be shared with specific users or security groups.

1. Click Share Settings on the canvas edit screen.
2. Select the sharing target.
   • Public: All users can access.
   • Security Group: Only users in the selected security group can access.
   • Specific Users: Only the selected users can access.
3. Click the Save button.

---

Session Management

Session Timeout

A user's session timeout is set to a default of 30 minutes. If there is no activity for 30 minutes, the user is automatically logged out.

To change the session timeout, modify the setting in web.xml.

<!-- WEB-INF/web.xml inside the webapp (bundled in the WAR — reset on deploy, so change it in the source) -->
<session-config>
    <session-timeout>30</session-timeout> <!-- in minutes -->
</session-config>

Concurrent Logins

By default, the same account can be logged in simultaneously from multiple browsers/devices. In security-sensitive environments, we recommend issuing separate accounts for each user and supplementing with network-level controls such as IP restrictions.

---

Audit Log

Key user activities are automatically recorded in the audit log. You can track system change history through the audit log.

Activities recorded:

Activity Type	Description
Login/Logout	User authentication events
User Management	User creation, modification, deletion, deactivation
Security Group Changes	Group creation, modification, deletion, permission changes
System Settings Changes	Changes to property, connection information, and other settings
Data Modifications	Changes to master data such as factories, equipment, and points

The audit log can be viewed from the Tools > Audit Log menu and filtered by period, user, and activity type.

---

Bulk User Registration

To register many users at once, you can use an Excel file for bulk registration.

Registration Procedure

1. Click Excel Upload from the Security Management > User Management menu.
2. Download the template Excel file.
3. Enter user information according to the template.

Column	Required	Description	Example
user_id	O	User ID	operator01
user_name	O	User Name	홍길동
password	O	Initial password	Temp1234!
email	-	Email	hong@example.com
security_group	O	Security group ID	OPERATOR
description	-	Description	생산1팀

4. Upload the completed Excel file.
5. Review the user information to be registered in the preview.
6. Click the Register button.

Note: Validation is performed during upload. If there are errors such as duplicate IDs or missing required fields, those rows are highlighted; you can fix them and re-upload.

---

Best Practices

• Principle of least privilege: Grant users only the minimum permissions needed for their work.
• Minimize admin accounts: Keep the number of ADMIN group users minimal, and use the OPERATOR group for routine operations.
• Periodic audits: Review the user list and permissions quarterly, and deactivate unnecessary accounts.
• Handling departing employees: Immediately deactivate or delete accounts when an employee leaves.
• No shared accounts: Use individual accounts and avoid shared account usage.
• Password management: Ensure initial passwords are changed, and encourage regular password changes.
• Log monitoring: Monitor for abnormal login attempts (repeated failures, access at unusual times, etc.).

---

Frequently Encountered Issues

Login Failures

Symptom	Cause	Resolution
Login failed Please check your ID or password again.	Typo in ID · Typo in password · Non-existent account · Inactive account — all four show this same message	Re-check ID and password (including Caps Lock). If still failing, verify the account exists in the User List
Too many login attempts (N seconds until retry)	Blocked due to consecutive failures (HTTP 429)	Wait the specified seconds. This is not a lock an administrator can release — it clears automatically after time passes
Login screen does not appear	Web server not running or network issue	Check the server status and network connection

There is no administrator feature called "Unlock Account"

The consecutive failure block is only released by a time window (default 300 seconds) — there is no button in the admin screen to release it. If someone asks, the answer is "try again in a few seconds." To change the threshold, see engine.session.bruteforce.* in Responding to Login Failures.

Inactive accounts also show the same message as an incorrect password. The user cannot tell whether their account is disabled, so an administrator must check the status in the list on their behalf.

Insufficient Permissions

Symptom	Cause	Resolution
Menu not visible	The security group lacks access permission for that menu	Ask an administrator to grant permission.
"You do not have access permission" message	Insufficient API or function permission	Check the security group's permission settings.
Specific site data not displayed	Site access permission not configured	Check the user's site access permissions.

Session Expiration

Symptom	Cause	Resolution
Redirected to login screen while working	Session timeout (default 30 minutes)	Log in again. If the timeout is too short, adjust it in web.xml.
Logged out from another device	Forced termination by the concurrent login policy (KICK)	Check the concurrent login settings.
Repeated session-related errors	Redis cache failure	Check the Redis service status.