CiviCRM web-pages must frequently make small requests for specific pieces of data (AJAX requests). Modern CiviCRM web-pages process these requests through an opinionated framework (APIv4 AJAX), but many pages use an older framework (basic/legacy AJAX).
Within the basic/legacy framework, there were multiple issues:
- For multiple end-points, it was possible to bypass "Permission" checks.
- For multiple end-points, it was possible to bypass "CSRF" defenses.
- Multiple end-points had their own unique security issues, such as information disclosure or SQL injection.
For parts (1) and (2), the current release provides systemic changes. These changes aim to improve security while generally retaining compatibility, but some extensions may require updates. For the benefit of extension-authors and core-contributors, we will review the evolving conventions for AJAX handlers.
For part (3), the current release has several patches for specific AJAX end-points. These are based on a mix of manual reviews and AI-assisted reviews. The list is too long to detail here. (The rest of this advisory will focus on the systemic changes.)
Evolving Code Conventions for AJAX Handlers
Change #1: Convert validateAjaxRequestMethod() to <is_ajax>
CiviCRM provides a defensive guard for AJAX handlers, which should be enabled most of the time. The old coding convention made it easy to forget this. The new convention flips the default (and makes it easier to discover anomalies). Let's consider a few examples.
-
Enable Defense (Old Style): Your PHP method calls the helper
validateAjaxRequestMethod(), as in:FIGURE 1: Enable CiviCRM's AJAX guard. Old code convention (up to 6.19.2).<item> <path>civicrm/ajax/my-handler</path> <page_callback>CRM_Mymodule_Page_AJAX::myHandler</page_callback> <access_arguments>administer my module</access_arguments> </item>class CRM_Mymodule_Page_AJAX { public static function myHandler() { CRM_Core_Page_AJAX::validateAjaxRequestMethod(); // <== Important doMyStuff(); } } -
Enable Defense (New Style): Your XML registration declares the flag
<is_ajax>.FIGURE 2: Enable CiviCRM's AJAX guard. New code convention (circa 6.19.3+).<item> <path>civicrm/ajax/my-handler</path> <page_callback>CRM_Mymodule_Page_AJAX::myHandler</page_callback> <access_arguments>administer my module</access_arguments> <is_ajax>true</is_ajax> <!-- Important --> </item>class CRM_Mymodule_Page_AJAX { public static function myHandler() { doMyStuff(); } } -
Enable Defense (Portable Style): If you publish an extension which runs on (say) CiviCRM 6.18 and 6.20, then you can combine the notations. For example, this is valid:
FIGURE 3: Enable CiviCRM's AJAX guard. Portable style (duplicate defense).<item> <path>civicrm/ajax/my-handler</path> <page_callback>CRM_Mymodule_Page_AJAX::myHandler</page_callback> <access_arguments>administer my module</access_arguments> <is_ajax>true</is_ajax> <!-- NOTE: <is_ajax> does not do anything before 6.19.3. See myHandler() for compatibility code. --> </item>class CRM_Mymodule_Page_AJAX { public static function myHandler() { CRM_Core_Page_AJAX::validateAjaxRequestMethod(); // FIXME: On 6.19.3+, ^^^ is redundant with <is_ajax>. This is double-execution. Drop it in the future. doMyStuff(); } }This variant will double-execute. For tighter behavior, you could disable the XML tag or make the PHP conditional. In either case, be sure to add comments for your approach.
-
Disable Defense (Portable): Some integrations (such as external web-hooks or external Javascript libraries) may not be compatible with CiviCRM's default guard. (They probably specify different defenses.) You can disable CiviCRM's defense.
FIGURE 4: Disable CiviCRM's AJAX guard. Portable style.<item> <path>civicrm/ajax/my-handler</path> <page_callback>CRM_Mymodule_Page_AJAX::myHandler</page_callback> <access_arguments>administer my module</access_arguments> <is_ajax>false</is_ajax> </item>class CRM_Mymodule_Page_AJAX { public static function myHandler() { doCustomDefense(); // Check the specs for your external caller. doMyStuff(); } }
If you have an old extension (which does not follow any of these patterns), then you should be aware of default behaviors across different versions:
- CiviCRM 6.19.2 (and earlier)
- Route matches "
/ajax/": No automatic guard - All other routes: No automatic guard
- Route matches "
- CiviCRM 6.19.3 (and later)
- Route matches "
/ajax/": Enable guard (<is_ajax>true</is_ajax>). Log warning about missing tag. - All other routes: Disable guard (
<is_ajax>false</is_ajax>)
- Route matches "
Change #2: Require named HTTP routes
-
Before v6.19.3: You define AJAX handlers in a method like
CRM_Mymodule_Page_AJAX::myHandler.You have a choice about how to call the method over HTTP. You should register an HTTP route (XML) for each AJAX handler and call the assigned route. However, it is possible to invoke the handler by class and method.
## SHOULD: Call handler via dedicated route GET /civicrm/ajax/my-handler ## MAY: Call handler by class name and method GET /civicrm/ajax/rest?className=CRM_Mymodule_Page_AJAX&fnName=myHandler... -
After v6.19.3: As before, you define AJAX handlers in a method like
CRM_Mymodule_Page_AJAX::myHandler.But now, you must define an HTTP route. You must not use
?className=or&fnName=.## MUST: Call handler via dedicated route GET /civicrm/ajax/my-handler ## MUST NOT: Call handler by class name and method GET /civicrm/ajax/rest?className=CRM_Mymodule_Page_AJAX&fnName=myHandler...
CiviCRM v6.19.2 and earlier
CiviCRM v6.19.3, v6.16.6 (ESR), and later
Upgrade to a fixed version of CiviCRM
(Alphabetically) Coleman Watts (CiviCRM), DaveD, James Newey, John Kingsnorth, Kevin Cristiano (Tadpole Collective), Seamus Lee (JMA Consulting), Tim Otten (CiviCRM)
