Administration
How the module is enabled, who can do what across its four tools, and how every sensitive action is recorded. This is the control panel for the whole Security section.
Enablement model
Security has exactly one enable setting, and it is always on. There are no sub-toggles: each of the four tools underneath it is controlled purely by permissions.
| Setting | Default | Controls | Can turn off? |
|---|---|---|---|
module_security the only one |
On (seeded) | Whether the Security module and its whole menu slice are available — Device Management, Offsite Access, Locked Accounts & Active Sessions, and Access Device Logs. | No — can_disable = false. It is listed in Manage Modules but has no disable switch, so the Security tools are always present. |
module_offsite_access, module_access
(both retired in 2.0.0) and module_device_management (retired in 3.0.0). All
three have been folded into module_security and no longer appear as their own
rows in Settings → Manage Modules. Nothing to do on upgrade: a tool that was
switched on before stays on, and its permission grants are untouched.
module_security is seeded on and cannot be disabled.
The tooling / protection-layer boundary
This module is the admin tooling. The protection layer it operates on stays in ERPat core — do not expect to configure guards, middleware, or RBAC inside this module:
| Control | Where it lives | This module's relationship |
|---|---|---|
| Authentication guards | Core (application/guards/) | Not owned here. |
| Request middleware (secure headers, input sanitization, CSRF, rate-limit, IP restriction, file security) | Core (application/middleware/) | The IP-restriction middleware reads this module's Offsite Access grants. |
| Roles / permissions RBAC editor | Core (Settings → Roles) | This module contributes its eight permission groups into it. |
| System audit log | Core (system_logs) | This module writes to it on every sensitive action. |
| Office-IP whitelist | Core IP-restriction settings | Offsite Access grants are time-boxed exceptions to it. |
| Sign-in (authentication) | Core sign-in, running the checks modules register with it | This module registers the banned-device check that core runs on every sign-in attempt — that is how a Device Management ban takes effect. See The sign-in check below. |
The sign-in check
A Device Management ban is enforced during sign-in itself — not by anything on the Security screens. The way that happens changed in this release, and while nothing about it needs configuring, two of its properties are worth understanding before you troubleshoot a sign-in problem.
The module now ships a small declaration file (config/auth_checks.php)
that registers its banned-device check with ERPat's sign-in machinery. Core no longer
reaches into this module by name; it simply runs whichever checks the installed modules
have registered. Practically, that means the ban check travels with the module —
there is nothing to wire up, and nothing in core to keep in step.
| Property | How it behaves | Why it matters to you |
|---|---|---|
| Where it comes from | Declared by this module in config/auth_checks.php |
Ships with the module. Nothing to switch on, nothing to configure. |
| When it runs | Every sign-in attempt, before the password is compared | A banned device is turned away without using up one of the person's three login attempts, so a ban never drags anyone towards a lockout. The attempt is recorded separately as a banned-device attempt. |
| Can it be switched off? | No — deliberately not tied to module_security |
An enforcement check must not be disableable. See below. |
| If it cannot run | Sign-in is denied and the reason is written to the error log | It fails safe rather than silently letting banned devices through. See below. |
module_security. The
sign-in check deliberately does not. A setting that could stop a ban being enforced
would be an authentication bypass dressed up as a settings toggle: anyone who could
reach Manage Modules could quietly let every banned device back in, with no trace on
the Security screens. Since module_security is locked on
(can_disable = false) there was never a legitimate way to turn it off anyway —
this removes the possibility entirely.
logs/log-YYYY-MM-DD.php). A sudden, unexplained "nobody can sign in" is
therefore a diagnosable event, and the log is where the answer is.
banned_devices
table to answer its question. Fresh installations and newly provisioned tenants get that
table from the standard database schema, and the module's migrations re-create it wherever
it is missing — so on a healthy database there is nothing to do. If a particular database
is missing it, every sign-in on that database is refused and each attempt logs
"banned_devices is missing … run php erpat migrate:modules".
Running the module migrations against that database is the fix, and it takes effect
immediately. Worth checking after restoring an old backup or bringing up a tenant by hand.
Permissions
The Roles editor gains eight permission groups from this module — four Device
Management groups and four Security groups. The keys are unchanged from before
each feature was modularized, so existing role grants keep working; only
device_management is new (see below).
They are listed here in menu order.
| Group (Roles editor) | Keys | Style | Governs |
|---|---|---|---|
| Device Management: Module new in 3.0.0 | device_management |
Access (module-level) | Opening the Device Management page at all — both the menu link and the direct web address. Without it, the whole tool is invisible and unreachable. |
| Device Management: Groups | device_management_groups, device_management_groups_create, device_management_groups_update, device_management_groups_delete |
Enabled (module-level) | The Groups tab — creating, editing and removing the named device (user-agent) groups used to label and filter the Entries list. |
| Device Management: Block Device | block_device |
Enabled (no children) | Banning a device, so that person can no longer sign in from that browser. |
| Device Management: Unblock Device | unblock_device |
Enabled (no children) | Restoring a banned device so the person can sign in from it again. |
| Security: Offsite Access | offsite_access, offsite_access_create, offsite_access_update, offsite_access_delete |
Dropdown — All / Specific members | Viewing and managing offsite grants; "Specific" scopes the list to allowed members. |
| Security: Locked Accounts | locked_accounts |
Simple View (no children) | Opening the Locked Accounts page and clearing failed attempts. The core staff_support permit also grants entry. |
| Security: Active Sessions | active_sessions, active_sessions_create, active_sessions_update, active_sessions_delete |
Manage (module-level) | Viewing and terminating live login sessions. |
| Security: Access Logs | access_logs, access_logs_create, access_logs_update, access_logs_delete |
Enabled (module-level) | The whole Access Device Logs page — Logs, Devices, and Categories tabs. |
What changed for Device Management in 3.0.0
Device Management used to be a core ERPat feature sitting in the Security menu group. In 3.0.0 it moved into this module and became its fourth tool. Three things changed that administrators need to know about:
- Opening the page now requires a permission. Before 3.0.0 the page had no gate on the direct web address — any signed-in staff member who typed the address could open it, and only the menu link was hidden. Worse, that menu link checked a permission that no role could actually be given, so in practice the tool was administrators-only. Now the Device Management: Module permission genuinely exists: it is enforced on the page itself, and it can be granted to a role.
- Its enable toggle was retired. The old
module_device_managementsetting is gone; the tool is now covered by the always-onmodule_securitysetting, so it no longer has its own row in Settings → Manage Modules. Visibility is purely a permission decision. On a brand-new tenant the tool used to ship switched off, so nobody could open it; it now ships reachable by administrators, and by any role you explicitly grant the permission. No non-admin gains access on upgrade. - Banning and restoring a device are now recorded. Both actions were previously silent. They now land in the tenant's audit log — see Audit logging below.
The Security menu group
The module contributes the whole Security sidebar section — four items, in this order. Device Management was previously a separate core item sharing this group; since 3.0.0 it belongs to this module like the other three. Every item is now gated by a permission alone, with no setting to check.
| Item | Icon | URL | Gated by |
|---|---|---|---|
| Device Management | fa-mobile | device_management | perm device_management |
| Offsite Access | fa-globe | offsite_access | perm offsite_access |
| Locked Accounts | fa-shield | Locked_Accounts | perm locked_accounts |
| Access Logs | fa-history | access_logs | perm access_logs |
The Groups tab of Device Management lives at its own address
(device_management_groups) and is reached from the page's second tab rather
than from a menu item of its own.
Each item also ships a hover description (its nav_desc_* line) for the smart
sidebar and the Left Menu Customization editor. "Restore to default" reproduces exactly this
four-item slice under the Security header.
Audit logging
Every sensitive action in the module writes to the tenant's own system audit log, categorized Security. Nothing sensitive happens silently. The events, with their severities — the Device Management rows are new in 3.0.0, where those actions were previously not recorded at all:
| Action | Severity | Logged as |
|---|---|---|
| Device banned new in 3.0.0 | critical | "A user's sign-in device was banned" |
| Device ban lifted (restored) new in 3.0.0 | warning | "A user's sign-in device ban was lifted" |
| Device group created / updated new in 3.0.0 | info | "Device management group was created / updated" |
| Device group deleted new in 3.0.0 | warning | "Device management group was deleted" |
| Offsite window granted / updated / revoked | warning | "Offsite access window was granted / updated / revoked" |
| Account unlocked (attempts cleared) | warning | "Account was unlocked (failed login attempts cleared)" |
| All sessions terminated for a user | warning | "All active sessions for a user were terminated" |
| Single session terminated | warning | "A single active session was terminated" |
| Access device registered / updated | info | "Access device was registered / updated" |
| Access device deleted | warning | "Access device was deleted" |
| Device API secret regenerated | critical | "Access device API secret was regenerated" |
| Device category created / updated / deleted | info / warning | "Access device category was created / updated / deleted" |
| Access log entry deleted | warning | "Access log entry was deleted" |