CAPTCHA protection for osTicket using Cloudflare Turnstile — with server-side token validation, a per-area kill switch, and a file-based emergency off switch that works even when you have locked yourself out.
Four areas, each toggled independently:
| Area | Path | Notes |
|---|---|---|
| Guest ticket form | open.php |
Requires the Turnstile field to be added to the form (see INSTALL step 5) |
| Client registration | account.php |
Requires the field on the User Information form |
| Client login | login.php, inline on tickets.php / profile.php, access link on view.php |
Widget is injected into the login and the ticket access-link form; a login or access-link POST to any client script is checked |
| Staff login | scp/login.php |
Enable last — see the lockout warning below |
Email intake and the JSON API are not covered. Turnstile is a browser mechanism; those channels need different controls.
Compared to nhaskaris/turnstile_osticket, the closest existing implementation:
| Concern | Reference plugin | This plugin |
|---|---|---|
| cURL timeout | none — login hangs during a Cloudflare outage | CURLOPT_TIMEOUT + CURLOPT_CONNECTTIMEOUT |
| Repeated validation in one request | static $was_validated flag skips every later check |
result cache keyed per token |
| Hostname check | none — tokens minted for other domains are accepted | optional, enforced against the hostname field of the siteverify response |
| Error messages | Cloudflare error codes are shown to the user verbatim | generic message to the user, detail only in the log |
| Login pages | not covered | TurnstileLoginGate |
| Content-Security-Policy | needs a core patch to allow challenges.cloudflare.com |
the plugin rewrites its own header, update-safe |
| Scope control | all or nothing | four independent switches plus a kill switch |
- osTicket 1.18.x (the plugin API is identical in 1.17.x, but only 1.18.x is verified)
- PHP 8.0–8.4 with the
curlextension. The plugin code is PHP 8.0-compatible and CI lints and tests it on 8.0, 8.1, 8.2, 8.3, and 8.4. In production it runs on 8.3.33. Which of those your instance may use is decided by osTicket, not by this plugin — 1.18.2 and newer support 8.3 and 8.4 - Outbound HTTPS to
challenges.cloudflare.com - A Cloudflare account (Turnstile is free)
Full step-by-step guide with abort points, smoke test, and security gate: docs/INSTALL.md (deutsch).
Short version:
- Download
turnstile-<version>.zipfrom the latest release. - Unzip into
include/plugins/so the result isinclude/plugins/turnstile/. - Match owner and permissions to the neighbouring plugin folders (
755dirs,644files). - Admin panel → Manage → Plugins → Add New Plugin → Cloudflare Turnstile → Install.
- Create an instance, enter the site key and secret key, enable only the guest ticket form for now.
- Admin panel → Manage → Forms → add a field of type Cloudflare Turnstile to the ticket form. Leave Required unticked — see the warning below.
- Run the smoke test before enabling any login area.
Do not tick Required on the Turnstile field. It protects nothing and breaks the other channels.
The plugin verifies the token itself and rejects an empty one, so the flag adds nothing on the web form. But osTicket's own required check lives in
FormField::validateEntry()and runs for every origin, andTicket::create()discards field errors only fororigin = email— for the API and for agent-created tickets it keeps them. With the box ticked,POST /api/tickets.jsonfails withUnable to create new ticket :<id> <label> is a required field, returned as HTTP 500 because osTicket maps validation errors without anerrnoto 500 (include/api.tickets.php).No payload can work around this: the token arrives as
cf-turnstile-response, not under the field's variable name, andto_database()deliberately stores nothing. A channel without a browser cannot supply it by design — which is exactly whatSECURITY.mdmeans by email intake and the JSON API being out of scope.
Lockout warning. Before enabling Staff login, keep a second, already authenticated agent session open in a different browser. If the widget fails to render, that session is your way back in. The alternative is the kill switch below.
Works without database access, without the admin panel, and while you are locked out:
touch include/plugins/turnstile/DISABLEDNo validation, no widget, no output buffer. Remove the file to re-enable.
The Cloudflare Turnstile field type stays registered while the file is present. That is deliberate: unregistering it would leave any form row of that type unresolvable, and osTicket then fatals in FormField::getImpl() on every form it builds — agent panel and customer portal included. The kill switch silences the plugin; it does not unregister it.
Further rollback stages are documented in INSTALL §8.
| Setting | Default | Purpose |
|---|---|---|
| Site key | — | Public key from the Cloudflare Turnstile dashboard |
| Secret key | — | Private key. Never rendered, never logged, never in an error message |
| Expected hostname | empty — set it | The hostname in the siteverify response must match. Left empty, a token minted on any other domain using the same widget is accepted |
| Guest ticket form | on | Protects open.php |
| Client registration | off | Protects account.php |
| Client login | off | Protects the client login wherever it is posted |
| Staff login | off | Protects scp/login.php |
| Fail mode | closed |
Behaviour when Cloudflare is unreachable: closed rejects, open lets through |
| siteverify timeout | 5 s | Total cURL timeout, connect timeout included |
| Widget theme | auto | auto, light, dark |
| Widget size | normal | normal, compact |
| Log failures | on | Writes area, reason, IP, and a truncated detail to the PHP error log |
Configuration is validated on save: an empty site or secret key is rejected, and hostnames are normalised to lowercase and syntax-checked. Two situations raise a warning without blocking the save — enabling Staff login together with fail_mode = closed, and running a protection area with no expected hostname.
closed is the safe default: if Cloudflare cannot be reached within the timeout, the request is rejected. During a prolonged Cloudflare outage, switch to open to keep forms usable — spam protection is off for that period.
The connect timeout fires first, so a blackholed endpoint answers in about 2 s at a 3 s setting rather than hanging.
osTicket hardcodes script-src 'self' 'unsafe-inline' via header() in five places, which blocks the Turnstile script.
TurnstileLoginGate::relaxCsp() runs inside an output-buffer callback — after osTicket's header() call and before headers are sent — and appends exactly one origin to script-src. No core patch, survives osTicket updates.
Only script-src is touched. osTicket sets neither default-src nor frame-src; adding a frame-src would restrict every other frame on the page rather than permit anything.
If a reverse proxy or web server sets its own CSP, the browser applies the intersection and the stricter policy wins. Fix it at that layer — see INSTALL §7.
PHP_BIN=/path/to/php8.3 tests/run-all.sh # lint, unit, fail-mode, integrationVerified on PHP 8.3.33 against a real osTicket 1.18.4 with MariaDB 10.6 — not only against stubs.
| Stage | Scope | Result |
|---|---|---|
| Lint | 8 files, php -l |
8/8 |
| Unit | config, settings, markup, verifier, login gate, form field, bootstrap | 95/95 |
| Fail-mode | endpoint redirected to a blackhole | 9/9 |
| Integration | php -S, real HTTP requests against a login rebuild |
25/25 |
| End-to-end | real osTicket 1.18.4, plugin active via the plugin manager | 37/37 |
The siteverify calls hit the real Cloudflare API using the official test keys (1x… always valid, 2x… always invalid, 3x… returns timeout-or-duplicate). No mock — the network path is exercised.
Details and the end-to-end setup: tests/README.md.
- No protection without JavaScript. Without JS there is no token, and at
fail_mode = closedthat is a hard block. Keep an alternative channel (email ticket) open for accessibility — email intake is unaffected by this plugin. - Email tickets and the API stay unprotected. Spam via
api/tickets.jsonor the mail pipe needs different controls. - The login injection operates on rendered HTML. It targets the first form containing a password field. An osTicket update that rebuilds the login templates can break this — re-run the login smoke tests after every osTicket update.
- The CSP rewrite is limited to seven scripts:
login.php,scp/login.php,tickets.php,profile.php,view.php,open.php,account.php. It runs inside an output-buffer callback, and a buffer over an attachment download would hold the whole file in memory — so the buffer is only started where a widget can appear. Attaching the field to a form rendered elsewhere means the widget is CSP-blocked there. CF-Connecting-IPis forgeable when the origin is reachable directly by IP. Harmless for theremoteipfield of siteverify, which is purely informational, but do not build authorisation decisions on it.- Browser execution of the AJAX fragment is not automatically verified. The delivered markup and re-render hook are covered by tests; whether Cloudflare's
api.jsactually starts inside the fragment depends on how osTicket injects it. A bootstrap poller re-renders every 250 ms for 10 s as a safety net. Smoke test step 6.1 confirms it. - The admin UI strings are German. The code, documentation, and issue templates are English; the plugin configuration labels are not yet localised. Tracked as a follow-up.
Turnstile loads a script from Cloudflare and transmits the visitor's IP address and browser signals to the United States. Cloudflare states it sets no tracking cookies. If you operate under the GDPR, add a corresponding paragraph to your privacy policy and put a data processing agreement with Cloudflare in place. This is not legal advice — have it reviewed.
Bug reports, compatibility reports, and pull requests are welcome. Please read CONTRIBUTING.md first — it covers the verification steps a change has to pass.
Security issues: do not open a public issue. See SECURITY.md.
GPL-2.0-or-later © studio-prisma. The plugin extends osTicket's GPL classes, so it carries osTicket's licence. Releases up to and including 1.0.3 were published under the MIT License and remain available under it.