Security

Security

FreeITSM ships with several layers of defence covering authentication, sensitive-data storage, and brute-force resistance. This page is the security reference for evaluators and administrators.

Authentication

Analyst login

• Username + password stored as bcrypt hashes in analysts.password_hash
• Minimum password length: 8 characters (enforced on change and reset)
• Default admin: admin / freeitsm — change this immediately on first login

Multi-Factor Authentication (TOTP)

• Pure-PHP implementation of RFC 6238 (TOTP) and RFC 4226 (HOTP)
• No external dependencies — uses PHP's hash_hmac() and random_bytes()
• 6-digit codes, 30-second time step, ±1 window tolerance (90s)
• Compatible with any standard authenticator: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden
• Setup: account menu → MFA → scan QR (or paste secret) → verify a code → enabled
• Secrets encrypted at rest with AES-256-GCM in analysts.totp_secret

Password reset by email

• "Forgot password" sends a single-use token via email (configurable mail provider)
• Token expires after a short window
• Token comparison uses hash_equals() (timing-safe)

Single sign-on (SSO / OIDC)

• Optional OpenID Connect SSO alongside local login — works with Keycloak, Microsoft Entra ID, Okta, Google Workspace, Authentik, etc.
• Authorization Code + PKCE (S256), with state and nonce validation; ID-token signature verified against the provider's JWKS (vendored firebase/php-jwt)
• Client secrets encrypted at rest; local login retained as a break-glass fallback so a down IdP can't lock anyone out
• Full details: Single Sign-On (SSO / OIDC)

IP-based brute-force protection

• Repeated failed login attempts from the same IP are throttled
• Both username and IP-level lockouts to defend against credential stuffing
• Login attempts (success + failure) logged with IP and user agent in the Reporting module

Authorisation

Authorisation is three layers, each answering a different question, each enforced server-side and failing closed. Hiding a button is never the control; it is at most a courtesy on top of one.

Layer	Question	Gate	Default
1 — Module access	Can they enter this module?	requireModuleAccess() / requireModuleAccessJson()	Absence = everything (an analyst with no restriction gets all modules)
2 — Capabilities (Roles)	Can they administer this part of it?	requireCapability(Cap::X) / requireCapabilityJson(Cap::X)	Deny by default (no role, no settings)
3 — Administrator	Can they run the System module?	requireAdminJson() / the page gate	Deny by default (analysts.is_admin)

is_admin is a superset: an administrator implicitly holds every capability, which is what makes Layer 2's deny-by-default safe to switch on — the tightening can never lock the instance owner out.

Layer 1 — Module access control

• Per-analyst and per-team module grants, managed at System → Analysts / Teams; unioned at one choke-point (getAnalystAllowedModules()).
• Enforced on the launcher cards, the waffle menu, and on the pages and APIs themselves — a restricted analyst cannot simply type the URL.
• Checks are authoritative (re-read from the database per request), so a just-revoked analyst is stopped even on a stale session.
• See Module Access Control.

Layer 2 — Capabilities / Roles

• Permission goes down to the individual settings tab, so someone can maintain the ticket statuses without reaching the mailbox OAuth credentials two tabs along.
• A settings tab you lack is not rendered into the page at all — absent, not hidden. There is no DOM to un-hide.
• Every settings write endpoint carries its own guard. Operational reads are deliberately not guarded — they are what the everyday module needs to function. Except a read that returns credentials: ask what the response contains, not just what the endpoint does.
• Settings that share the generic save_system_settings.php endpoint are authorised per setting key (includes/settings_keys.php), because one guard cannot cover five callers with five audiences. A key no module claims cannot be written through it.
• See Roles & Permissions and the Developer Guide.

Layer 3 — Administrator (System)

• analysts.is_admin gates the whole System module — page and API (includes/admin_api_guard.php). Before this, every analyst was effectively an administrator and could self-escalate.
• The last administrator is protected from removal.
• See Admin Access Control.

Auditing it — the guard nobody wrote

Type-safe permissions catch a misspelled check. Nothing catches a check somebody simply forgot to write — no language feature saves you from a line that isn't there, and that omission has repeatedly turned out to be the real hole.

System → Debug tools → D005 (Endpoint permission coverage) reads every endpoint under api/ and reports what actually guards each one — a capability, administrator-only, module access, an API key, a webhook signature, a URL token, "logged in and nothing more", or nothing at all — ranked by how much damage the gap allows. It also flags capabilities offered on System → Roles that no endpoint enforces (a tick-box granting nothing), and capabilities passed as a bare string instead of a Cap:: constant.

Run it after adding endpoints and before a release. Endpoints that are public by design (login, self-service, the REST API, inbound webhooks) and those acting only on the caller's own account (your own password, your own MFA) are declared as exclusions with reasons, so the findings stay short enough to act on.

Multi-tenancy and team filtering

• Company (tenant) access is scoped per analyst and per team, unioned the same way, and applied at the query level.
• The Tickets module filters department visibility by team membership (get_my_departments.php vs get_departments.php).
• See Multi-Tenancy.

Encryption at Rest

AES-256-GCM authenticated encryption for sensitive database values.

• Key file: stored outside web root at C:\wamp64\encryption_keys\sdtickets.key
• Format: ENC: + base64(IV + auth tag + ciphertext) — auth tag prevents tampering
• Migration-safe: values without ENC: prefix pass through unchanged for gradual rollout
• Key generation: one-click from System → Encryption (or php -r "echo bin2hex(random_bytes(32));")
• No regenerate button — preventing accidental key destruction is more important than convenience

Encrypted columns

system_settings:

• vcenter_server, vcenter_user, vcenter_password
• knowledge_ai_api_key, knowledge_openai_api_key
• intune_tenant_id, intune_client_id, intune_client_secret
• (Per-feature AI keys — <ns>_api_key for knowledge_ai, cmdb_ai, workflow_ai, forms_ai, tickets_reply_cleanup, plus RFP Builder — each encrypted and masked separately; see AI Providers)

target_mailboxes:

• azure_tenant_id, azure_client_id, azure_client_secret
• oauth_redirect_uri, imap_server, target_mailbox

analysts:

• totp_secret

Masked API responses

A subset of true secrets listed in MASKED_SETTING_KEYS are returned as ****<last4> rather than plaintext by api/settings/get_system_settings.php. The corresponding save endpoints treat blank or asterisk-prefixed submissions as "leave unchanged" so the user can re-save the settings form without re-typing the secret each time.

Session Management

• Standard PHP sessions (session_start())
• Session key: $_SESSION['analyst_id'] for analyst auth, $_SESSION['ss_user_id'] for self-service portal users (separate auth domains)
• Password-expiry guard in includes/waffle-menu.php — if $_SESSION['password_expired'] is set, every page redirects to force_password_change.php until resolved

Email Security

• OAuth 2.0 for Microsoft 365 and Google Workspace mailboxes — no plaintext mailbox passwords
• Mailbox whitelist: per-mailbox domain and email-address whitelisting; non-whitelisted senders are rejected and logged
• Rejection actions: configurable per-mailbox actions for rejected emails (delete, move to Deleted Items, mark as read)
• Import actions: configurable post-import actions (delete, move to folder) with folder existence verified via Graph API before saving

File Uploads

• Module-specific upload folders (e.g. tickets/attachments/, lms/content/, forms/uploads/) — each is gitignored
• Generated filenames; original names stored in DB for display
• Served via PHP endpoints that check session auth before serving the file

API Keys (External Access)

For the browser extension and external integrations (e.g. PowerShell asset inventory):

• API keys generated at Software → Settings → API Keys
• Rate limited: 60 requests per minute per key (configurable in System Settings)
• Bearer-token style header
• Revocable per-key with last-used tracking

Going Live Checklist

When moving from evaluation to production:

1. Change the default admin password
2. Delete the /setup folder — it contains diagnostic info useful only during install
3. Generate a unique encryption key if you used a sample one
4. Back up the encryption key file — losing it makes encrypted columns unrecoverable
5. Configure OAuth for any mailboxes — avoid IMAP/password where possible
6. Enable MFA on the admin account
7. Restrict module access per analyst at System → Modules
8. Configure the password reset email so analysts can recover access without admin intervention
9. Review whitelist entries for each mailbox to limit who can create tickets via email