Custom CSRF Token Name Validation for AJAX and Form Requests in CodeIgniter 4

CSRF Token Configuration in CodeIgniter 4

Updating $csrfTokenName in app/Config/Security.php only affects the name of the hidden input field generated by form helpers. It does not automatically update the expected HTTP header for AJAX requests. To ensure consistency across both form submissions and AJAX requests, you must update two separate configuration properties.

Required Configuration Changes

To change the token name globally for both forms and headers, modify app/Config/Security.php as follows:

// The name of the hidden input field in forms
public $csrfTokenName = 'my_custom_csrf_token';

// The name of the HTTP header for AJAX requests
public $csrfHeaderName = 'X-MY-CUSTOM-CSRF-TOKEN';

Validation Priority and Behavior

Based on the internal logic of the CodeIgniter 4 Security middleware, the following behaviors apply:

• Priority: When both the custom header and the form field are present in a single request, the header value takes precedence. The middleware checks the header first; if found, it validates that value and ignores the form field.
• AJAX Impact: Because $csrfHeaderName is a distinct setting, changing it requires a manual update to your client-side JavaScript (e.g., Axios, Fetch, or jQuery) to send the new header name. A middleware-level change to $csrfTokenName alone will cause AJAX requests using the default X-CSRF-TOKEN header to fail.
• Request Types: The token name change affects all HTTP methods listed in the $csrfMethods array (typically POST, PUT, PATCH, and DELETE). Any request method not included in that array will bypass CSRF validation entirely, regardless of the token name used.

Verification Steps

To verify your configuration is working as expected, perform these checks:

1. Form Check: Render a form using csrf_field() and inspect the HTML source to confirm the name attribute matches your $csrfTokenName.
2. Header Check: Send an AJAX request using your new $csrfHeaderName. A 200 OK response confirms the header is recognized.
3. Priority Check: Send a request containing both the correct header and an incorrect form field value. If the request is accepted, the header priority is confirmed.

Diagnostic Note: If requests are still being rejected silently, please specify if you are using a custom Filter sequence in app/Config/Filters.php, as the order of the csrf filter relative to other middleware can impact how request bodies are read.