Getting Started
The Security module is always available — but the individual tools and who can use them still need a little setup. This page takes an administrator from a fresh install to a working Device Management, Offsite Access, Locked Accounts / Active Sessions, and Access Device Logs.
Prerequisites
- PHP ≥ 8.2 and ERPat core ≥ 1.10.0 — required by the module manifest.
- Admin access to the Roles editor (Settings → Roles) for granting permissions.
- Staff users must already exist — Offsite Access windows and access-device passes are assigned to active staff members.
- Your office IP whitelist should be configured (a core setting) for Offsite Access to be meaningful — a grant is an exception to that whitelist. If no IP restriction is enforced, an offsite grant simply has nothing to relax.
- People need at least one sign-in before they show up in Device Management — that list is built from sign-in history, so a brand-new account that has never logged in yet has no devices to show.
The module is on by default
Unlike most modules, Security cannot be turned off. Its umbrella setting
module_security is seeded on and locked — it is listed in
Settings → Manage Modules under the Security category but has no disable
switch (can_disable = false). That guarantees the Security tools are always
reachable. It is the module's only enable setting — everything below it is controlled
by permissions. See Administration for the full map.
php erpat migrate:modules on every database — the six backing tables are
created by this module's migrations and are not part of the base install. Re-running is
always safe.
- Opening the page now requires a permission. Previously anyone signed in could reach it by typing the address; now only administrators and roles you explicitly grant Device Management: Module can open it.
- Its old separate on/off switch is retired — it no longer has its own row in Settings → Manage Modules. Who sees it is now purely a permission decision. On a brand-new tenant that switch used to ship off, so nobody could open the page at all; now administrators can, and anyone else needs the permission granted.
Activation — two steps
-
Run the module migrations
From the project root. The migrations are idempotent (CREATE-IF-NOT-EXISTS) and are tracked in the module's own
migrations_securitytable. On an existing database they do nothing; on a fresh install or a newly provisioned tenant they create the six tables.php erpat migrate:modules # (or) php erpat migrate:latest -
Grant permissions in Roles
Go to Settings → Roles and give the right roles the Security permission groups (below). Administrators see everything by default. That's it — there is no module to "switch on".
What the migrations create
Six tables across the feature areas. These migrations are the only thing that creates them —
they are not part of the base-install schema, so run
php erpat migrate:modules on every database before anyone signs in. Re-running
is a safe no-op. Until banned_devices exists, the sign-in device check has
nothing to read and refuses sign-in rather than waving devices through, logging the missing
table to the server error log:
| Table | Feature | Holds |
|---|---|---|
banned_devices | Device Management | One row per ban — the person, the browser it applies to, the IP, the reason, and who banned it. |
device_management_groups | Device Management | Each named device group — title, the browser it matches, status. |
offsite_access | Offsite Access | One row per grant — user, start date, end date. |
access_device_categories | Access Device Logs | Device category — title, detail, status. |
access_devices | Access Device Logs | Each device — name, category, API key/secret, its "passes" (allowed staff), status. |
access_logs | Access Device Logs | Each access event — device, user, remark, timestamp. |
Locked Accounts & Active Sessions has no table of its own — it reads existing
columns on the users table (failed-attempt counters) and the core session store
(ci_sessions). Device Management's list has no table either — the devices
you see are worked out live from sign-in history, and only the bans and the
groups are stored. Full schema on the Reference page.
Granting access in Roles
Eight permission groups appear in the Roles editor — four under Device Management: … and four under Security: …. Device Management needs one permission to open the page and separate ones to act on a device. Grant them to the roles that need each tool:
| Roles-editor group | Base key | Style | Unlocks |
|---|---|---|---|
| Device Management: Module | device_management |
Access (module-level) | Opening the Security → Device Management page at all, and reading the Entries list. New in 3.0.0 — without it the page is closed, even to a direct address. |
| Device Management: Groups | device_management_groups (+ _create / _update / _delete) |
Enabled (module-level) | The Groups tab — creating, editing, and removing named device groups. |
| Device Management: Block Device | block_device |
Simple Enabled | The ban action — stopping a person from signing in on one particular browser. |
| Device Management: Unblock Device | unblock_device |
Simple Enabled | The restore action — lifting a ban so the person can sign in from that browser again. |
| Security: Offsite Access | offsite_access (+ _create / _update / _delete) |
Dropdown — All / Specific members | The Security → Offsite Access page and the grant/edit/revoke actions. |
| Security: Locked Accounts | locked_accounts |
Simple View | The Security → Locked Accounts page (its Browse tab) and the "Clear Attempts" unlock action. (Holders of the core staff_support permit can also reach it.) |
| Security: Active Sessions | active_sessions (+ _create / _update / _delete) |
Manage (module-level) | The session-management capability on the Active Sessions tab — view, terminate a single session, log a user out of all devices. |
| Security: Access Logs | access_logs (+ _create / _update / _delete) |
Enabled (module-level) | The whole Access Device Logs page — all three tabs (Logs, Devices, Categories). |
The Security sidebar group
With the permissions granted, a Security section appears in the left sidebar. This module owns all four items in it, in this order:
| Menu item | Opens | Shown when |
|---|---|---|
| Device Management | The two-tab Device Management page (Entries · Groups). | device_management permission. |
| Offsite Access | The Offsite Access grants page. | offsite_access permission. |
| Locked Accounts | The two-tab Locked Accounts / Active Sessions page. | locked_accounts permission. |
| Access Logs | The three-tab Access Device Logs page. | access_logs permission. |
module_security, and it is always on and cannot be turned off. Every item above
is shown or hidden purely by permission — there is no on/off switch anywhere that can
hide one of these menu items. If a colleague cannot see one, grant them its permission; that
is the only lever.
First-run checklist
Who: an administrator.
Preconditions: migrations run, at least one active staff user.
Run the migrations
php erpat migrate:modules— confirms the six tables exist.Grant the permission groups
In Roles, give IT/admin roles Device Management (plus Groups, Block Device and Unblock Device), Offsite Access, Locked Accounts, Active Sessions, and Access Logs. Give HR/support at least Locked Accounts.
Confirm the sidebar
Reload and check the Security group shows Device Management, Offsite Access, Locked Accounts, and Access Logs. If one is missing, the role is simply missing that item's permission — there is no toggle to check.
Look at one person's devices
Open Security → Device Management. The list starts empty on purpose — pick a person (or a team) in the filter at the top and the page fills in with the browsers they have signed in from, each with its own status. Don't ban anything yet; this is just to confirm the page works and to see what "one row per person per browser" looks like.
Seed your access-device categories
Only if you use door/access devices: open Access Logs → Categories and add a category or two before registering devices.
Try one action end-to-end
Follow a procedure on Daily Operations — e.g. grant a short offsite window to yourself — and confirm it appears in the tenant's audit log.