nedCAPTCHA (REDCap External Module)

A REDCap External Module that adds CAPTCHA protection to public surveys without any dependencies on external services (hence the name ned = no external dependencies).

Purpose

To protect a public survey with a CAPTCHA. While REDCap 8.11.0 and newer provides Google reCAPTCHA as an integrated service, this may not be suitable in all circumstances (e.g. servers with tight IPTABLES firewall or privacy rules, where sharing user IPs with Google is problematic).

Effect

When enabled in a project, the module will protect the public survey with a CAPTCHA (either a classic image CAPTCHA with distorted text, a math problem, or a custom challenge). A user will first have to complete the CAPTCHA challenge before being allowed to proceed to the survey. The captcha has to be completed at most once per user session.

The Custom CAPTCHA option could be used to implement simple password protection of a survey. Only users who know the "password" can then access the survey.

Requirements

• REDCap 11.1.5 or newer.
• The GD library with FreeType support must be installed in PHP.

Installation

• Clone this repo into <redcap-root>/modules/redcap_nedcaptcha_v<version-number>, or
• Obtain this module from the Consortium REDCap Repo via the Control Center.
• Go to Control Center > Technical / Developer Tools > External Modules and enable 'nedCAPTCHA'.
• Enable in projects that require public survey protection.

Configuration

System-Level Settings

• Global - Debug Mode: When enabled, some debug information will be printed to the Web-browser's console. This setting is global, i.e. debug info will be shown regardless of the debug setting in a project.

Project-Level Settings

• Debug Mode: When enabled, some additional information that may help troubleshooting will be printed to the Web-browser's console.

• Show error messages in the browser: When enabled, error messages such as PHP exceptions are shown in the browser at the top of survey pages.

• Always require the CAPTCHA to be answere: When checked, the CAPTCHA will be presented on each (repeat) survey, even when the request originates from the same browser.

• CAPTCHA Type: Sets the type of CAPTCHA that is used to protect the public survey.

  • None: The CAPTCHA is deactivated.
  • Simple Math Problem: A math problem will need to be solved to get to the survey. Solutings are never negative. The problem is shown as an image.
  • Distorted Text Image: A sequence of digits/letters has to be entered exactly as shown in the displayed image.
  • Custom: Custom challenge-response pairs can be set.

Math-specific settings:

• Complexity: Can be set to 'Simple' or 'Complex'. Simple problems will be limited to additions, while complex problems include two of addition, subtraction, and multiplication (however, there will never be two multiplications, as results can get quite large).

• Minimum / Maximum operand values: Sets the range of operand values. By default, the range of operand values is 1 to 10. In complex problems, the first operand my be set to a higher value to ensure a non-negative results when subtractions are present.

• Show as text: By default, math problems are rendered as images to make it harder for bots to beat the CAPTCHA. With this option, the math problem will be rendered as text. This may be useful in order to support persons relying on screen readers to be able to complete the CAPTCHA.

Image-specific settings:

• Length: The length of the challenge text (defaults to 6 characters).

• Challenge reuse: By default, a new challenge is recreated for each try. By enabling this option, in case of retries, the same challenge is reused.

• Angle variation: Determines the amount of random rotation that is applied to individual characters. Can be set to 'None' (no rotation), 'Slight' (up to ±7°), 'Medium' (up to ±11°; this is the default setting), or 'Strong' (up to ±15°).

• Noise density: Determins the amount of noise that is added to the image: 'Off' (no noise), 'Low' (a low amount of noise, 60% of the default amount), 'Medium' (the default amount), or 'High' (150% of the default amount).

Color settings (math and image CAPTCHAs):

For math and image CAPTCHAs, text and background colors (in case of image CAPTCHAs also the color or the added noise) can be set. To do so, enter a color value either as triplets of comma-separated integers (0-255) or as hex values (with or without leading #): e.g. the color red could be specified as 255,0,0 or #ff0000.

Custom-specific setting:

• Challenge-response pairs: Enter pairs of challenges (displayed to the user) and response (the expected answer), separated by the equal sign (=), one pair per line. For the CAPCHA, a random pair will be chosen each time. Answers are not case-sensitive. Examples:

text The color of the sky? = Blue The color of grass? = Green Snowwhite and the __?__ dwarves (enter as text). = Seven ...

text Type the access key to proceed. = secretaccesskey

Customization of text elements of the CAPTCHA page:

• Introduction: This is displayed immediately below the survey title. By default, this is blank.

• Label: The label of the CAPCHA (displayed abouve the challenge). Default values vary by CAPCHA type (Math: 'Please solve this math problem:', Image: 'Please type in the text exactly as displayed', Custom: none).

• Button: The label of the submit button (defaults to 'Submit').

• Fail message: The message that is shown upon failure to solve the CAPTCHA (shown below the submit button; defaults to 'Validation failed. Please try again.').

Testing

Instructions for testing the module can be found here.

Changelog

Version | Changes ------- | ----------- 1.4.2 | Fix repo link.
Add citation info. 1.4.1 | Better screenreader support. 1.4.0 | Adds "Math as text" configuration option to support people relying on screen readers. 1.3.0 | Requires EM Framework version 14 (REDCap 13.7.3).
Additional input validations. 1.2.0 | Requires EM Framework version 8 (REDCap 11.1.5). 1.1.0 | Add "Always ask" option.
Bugfix: Debug mode was not working as intended. 1.0.6 | Re-Fix: Prevent "hook not completed" error. 1.0.5 | Bugfix: Prevent "hook not completed" error. 1.0.4 | Updated behavior: Query params for setting fields is now supported (no need for _startover any longer). 1.0.3 | Add the GD + FreeType requirement to the documentation. Improved error handling. 1.0.2 | Add instructions for testing the module. 1.0.1 | Bug fixes. 1.0.0 | Initial release.

How to cite this work

If you use this external module for a project that generates a research output, please cite this software in addition to citing REDCap. You can do so using the APA referencing style as below:

Rezniczek, G. A. (2025). nedCAPTCHA (REDCap External Module) [Computer software]. https://doi.org/10.5281/zenodo.15411596.

Or by adding this reference to your BibTeX database:

bibtex @software{Rezniczek_nedCAPTCHA_REDCap_External_Module_2025, author = {Rezniczek, Günther A.}, title = {{nedCAPTCHA (REDCap External Module)}}, version = {1.4.2}, year = {2025} month = {5}, doi = {10.5281/zenodo.15411596}, url = {https://github.com/grezniczek/redcap_nedcaptcha}, }

These instructions are also available in GitHub under 'Cite This Repository'.