hCaptcha

hCaptcha

oCMS includes an hCaptcha module to protect the login form, and public forms that have a captcha field, from automated attacks and bots.

Overview

hCaptcha is a privacy-focused CAPTCHA service that helps protect against:

• Automated brute force attacks
• Credential stuffing
• Bot registrations
• Spam submissions

Getting Started

1. Create an hCaptcha Account

1. Visit hCaptcha Dashboard
2. Create a free account
3. Add your site and obtain your Site Key and Secret Key

2. Configure hCaptcha

Option A: Admin Interface

1. Navigate to Admin > Modules > hCaptcha
2. Enter your Site Key and Secret Key
3. Choose theme and size preferences
4. Enable hCaptcha
5. Click Save

Option B: Environment Variables

OCMS_HCAPTCHA_SITE_KEY=your-site-key
OCMS_HCAPTCHA_SECRET_KEY=your-secret-key

Environment variables take precedence over database settings for the keys.

Configuration Options

Setting	Options	Description
Enabled	On/Off	Enable or disable hCaptcha protection
Site Key	String	Your hCaptcha public site key
Secret Key	String	Your hCaptcha secret key (masked in the admin interface)
Theme	light / dark	Widget color theme
Size	normal / compact	Widget size

If the stored settings cannot be read at startup (a database error), hCaptcha is turned on wherever the environment keys are set, even if the stored settings had it off (OCMS_HCAPTCHA_DISABLED=true still wins), with the default theme and size. The settings page shows a warning while it displays this fallback and disables saving; a save is refused until the stored settings load (the module retries the load at most once a minute when it is next used; saving a form opened before the restart retries it at once), and a form rendered from the fallback is refused even after they recover. Without environment keys there is nothing to verify against, so protection is off until the settings load.

How It Works

1. When enabled, the hCaptcha widget appears on the login form and on public forms that have a captcha field
2. Users must complete the CAPTCHA challenge before submitting
3. The server verifies the response with hCaptcha's API
4. Login proceeds only if verification succeeds

Test Keys

hCaptcha provides test keys for development. Set them yourself; they are not applied automatically:

Key Type	Value
Site Key	10000000-ffff-ffff-ffff-000000000001
Secret Key	0x0000000000000000000000000000000000000000

With test keys, the widget always passes automatically — no challenge is shown.

Disabling hCaptcha

Via Admin Interface

Go to Admin > Modules > hCaptcha and toggle it off.

Via Database

# Disable at setting level (keeps module loaded)
sqlite3 ./data/ocms.db "UPDATE hcaptcha_settings SET enabled = 0"

# Disable at module level (prevents module from loading)
sqlite3 ./data/ocms.db "UPDATE modules SET is_active = 0 WHERE name = 'hcaptcha'"

Restart the application after database changes.

Integration with Login Security

hCaptcha works alongside the existing Login Security protection:

Layer	Protection
1. hCaptcha	Blocks bots before login attempt
2. IP Rate Limiting	Limits requests per IP
3. Account Lockout	Locks account after failed attempts

For maximum security, enable all three layers.

Error Messages

Error	Cause	Solution
"Please complete the captcha"	User didn't complete the challenge	Complete the hCaptcha widget
"Captcha verification failed. Please try again."	Network or API error, or the token was rejected by hCaptcha	Check internet connection, complete the challenge again

Behind a Reverse Proxy

Ensure your proxy passes the real client IP. See Reverse Proxy for configuration.

The module uses the client IP resolved by oCMS. Forwarding headers are honored only when the direct peer is listed in OCMS_TRUSTED_PROXIES; the order is:

1. X-Forwarded-For (the first address from the right that is not a trusted proxy)
2. X-Real-IP, only when X-Forwarded-For is absent
3. RemoteAddr

Troubleshooting

Locked Out After Enabling hCaptcha

sqlite3 ./data/ocms.db "UPDATE hcaptcha_settings SET enabled = 0"
# Restart the application

Widget Not Appearing

1. Check that hCaptcha is enabled: sqlite3 ./data/ocms.db "SELECT * FROM hcaptcha_settings"
2. Verify both Site Key and Secret Key are set
3. Check browser console for JavaScript errors
4. Ensure hCaptcha script can load (check firewall/ad blockers)

Verification Always Fails

1. Verify your Secret Key is correct
2. Check server logs for error codes (missing-input-secret, invalid-input-secret, etc.)
3. Ensure your server can reach https://api.hcaptcha.com/siteverify

Privacy

hCaptcha is designed with privacy in mind — GDPR compliant, does not sell personal data, and can operate without cookies. See hCaptcha Privacy Policy.

Related

• Login Security — Rate limiting and account lockout
• Security — Full security overview
• Reverse Proxy — Proxy setup for correct IP detection