Skip to content

Admin Password and Login Security Configuration

Jump to bottom Edit New page
Dr M H B Ariyaratne edited this page May 24, 2026 · 2 revisions

Language: English · සිංහල

Password and Login Security Configuration

Overview

This page lists every configuration option that controls password strength, password expiration, password reuse, forced password change, and session timeout in HMIS. All of these are application-level settings — they apply to every institution, department, and user across the installation.

This article is the configuration reference. For the day-to-day user workflow (how an administrator opens the change-password screen, etc.), see Resetting Passwords and Changing User Details.

Where These Settings Take Effect

The same configuration keys are read at three points in the application:

Where What the user sees When the configuration is evaluated
Login page (ez:login, displayed before the user is authenticated) Generic Login form with username and password After the user clicks Login — SessionController.loginActionWithoutDepartment() runs arePasswordRequirementsFulfilled() and may block entry if the password is expired or the user is flagged for reset
Select Department page (ez:select_department, shown after login when no department is yet selected) Select Department card If the password requirements are not fulfilled, the template redirects to the embedded change-password panel instead of rendering the menu (template.xhtml, passwordRequirementsFulfilled panel)
Change Password page (/admin/users/change_password.xhtml) Three-field form (Name / Username / New Password / Re-enter) with optional Force Password Reset on Next Login button When the form is rendered (to display the relevant rule text) and when the new password is saved (validation)

The same logic also fires on the embedded post-login change-password screen (ezcomp/pages/admin/change_password.xhtml) — that screen prints the active rules ("Password must include uppercase, lowercase, a number, and a special character", "Password must be changed every N days", etc.) directly from these configuration values so users see only the rules that are currently enforced.

Where to Edit These Options

  1. Click Administration → Manage Institutions → Application Options
  2. Type the Key into the filter box (keys are listed below — copy/paste them verbatim, including underscores and capitalisation)
  3. Click the row, change the value, save
  4. Click Reload Config in the header — without a reload, sessions continue to use the cached value

Required privilege: AdminInstitutions (Admin role recommended)

See the full Application Options reference: Application-Level Configuration.

Password Strength Configuration

Key Type Default What It Does
Prevent matching password with username Boolean false If true, rejects any password equal to the username. Checked at login and at password change.
Enforce password complexity Boolean false If true, the new password must match the regex below. The change-password screen also lists the rule "Password must include uppercase, lowercase, a number, and a special character" only when this is on.
Password complexity regex Short Text ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$ The regex applied when complexity is enforced. The default requires: at least 8 characters, one lowercase letter, one uppercase letter, one digit, one of @ $ ! % * ? &. Override with caution — a malformed regex blocks every login.

Maximum password length: 15 characters. This is hard-coded on the change-password input (maxlength="15") and is not configurable. Any complexity regex must accept passwords no longer than 15 characters.

Password Expiration Configuration

Key Type Default What It Does
Enable password expiration Boolean false Master switch for the expiry feature. When false, passwords never expire and the days setting is ignored.
Set password expiration period (days) Long (integer) 30 Number of days from the user's lastPasswordResetAt after which the system blocks login with "Password has expired. Please reset your password." Only effective when expiration is enabled.

The clock starts at the most recent password change, recorded in WebUser.lastPasswordResetAt. If a user has never changed their password since the field was introduced, the value defaults to "now" on first read, so expiry counts from the first login under the new policy rather than from account creation.

Forced Password Change (Admin-Triggered) Configuration

Key Type Default What It Does
Allow admin to force password change Boolean false If true, the Force Password Reset on Next Login and Reverse Request to Reset Password on Next Login buttons on the admin Change Password screen become clickable. If false, the buttons are visible but disabled.

When the admin forces a reset, the user's needToResetPassword flag is set on the WebUser record. At the next login, arePasswordRequirementsFulfilled() returns false and the template renders the inline change-password panel until the user supplies a new password.

Password Reuse Configuration

Key Type Default What It Does
prevent_password_reuse Boolean false When true, a new password is rejected if its hash matches any entry in the user's WebUserPasswordHistory within the limit below.
password_history_limit Integer 5 How many most recent previous passwords are checked. A value of 5 blocks reuse of the last five passwords.

The key prevent_password_reuse is all-lowercase with underscores — it is not the same as the friendlier Prevent Password Reuse shown in some older documentation. Use the exact lowercase key.

Each successful password change adds an entry to WebUserPasswordHistory and updates lastPasswordResetAt, so the expiration timer and the reuse history stay in sync.

Session Timeout

The auto-logout interval is not an Application Option. It is fixed in WEB-INF/web.xml:

<session-config>
    <session-timeout>60</session-timeout> <!-- minutes -->
</session-config>
  • Default: 60 minutes of inactivity (lowered from 180 for patient-data security, issue #19867).
  • After expiry the user is redirected to /timeout.xhtml with the message "For security reasons, your session was automatically terminated due to inactivity."
  • Changing this value requires editing web.xml and redeploying the WAR through CI/CD — it cannot be toggled from the Application Options screen.

Recommended Baselines

There is no single "correct" combination — pick the strictest set your users can tolerate. A reasonable production baseline:

Setting Recommended
Prevent matching password with username true
Enforce password complexity true
Password complexity regex (leave at default)
Enable password expiration true
Set password expiration period (days) 60 or 90
Allow admin to force password change true
prevent_password_reuse true
password_history_limit 5

For deployments handling clinical or financial data (hospitals, claims processing) all the above should be on.

Quick Reference: All Keys on One Screen

Prevent matching password with username     (Boolean, default false)
Enforce password complexity                 (Boolean, default false)
Password complexity regex                   (Short Text, default 8-char mixed regex)
Enable password expiration                  (Boolean, default false)
Set password expiration period (days)       (Long,    default 30)
Allow admin to force password change        (Boolean, default false)
prevent_password_reuse                      (Boolean, default false)
password_history_limit                      (Integer, default 5)

Troubleshooting

Force Password Reset buttons are greyed out

The Allow admin to force password change option is false (the default). Set it to true and click Reload Config.

A user is locked out with "Password has expired"

Either disable Enable password expiration (system-wide) or open Manage Users, select the user, click Manage Password, and set a new password. The save updates lastPasswordResetAt and clears the expiry condition for that user.

Users can still set "password" or "12345"

Enforce password complexity is false. Switch it on. The default regex enforces 8+ characters with mixed case, digit, and special.

Reuse policy is not blocking old passwords

  • Verify the key is prevent_password_reuse (lowercase with underscores), not Prevent Password Reuse.
  • After enabling, click Reload Config.
  • Passwords set before the option was enabled still create history entries from that point forward — older entries are only present if they were captured by a prior change.

Complexity rule shown to the user is wrong

The change-password screen shows rule text only when the matching Boolean is true. If a rule is unexpectedly visible or hidden, recheck Enforce password complexity, Enable password expiration, Prevent matching password with username, and Allow admin to force password change and click Reload Config.

Related Pages

සිංහල English

Add a custom sidebar

Clone this wiki locally