spryker / captcha
Captcha module
Requires
- php: >=8.3
- spryker-shop/agent-page-extension: ^1.3.0
- spryker-shop/customer-page-extension: ^1.10.0
- spryker/captcha-extension: ^1.0.0
- spryker/event-dispatcher-extension: ^1.0.0
- spryker/kernel: ^3.84.0
- spryker/log: ^3.0.0
- spryker/messenger: ^3.0.0
- spryker/redis: ^2.15.0
- spryker/security-gui-extension: ^1.6.0
- spryker/security-merchant-portal-gui-extension: ^1.6.0
- spryker/symfony: ^3.20.0
- spryker/transfer: ^3.27.0
- spryker/zed-ui: ^4.3.0
Requires (Dev)
Suggests
- spryker-eco/captcha-altcha: Provides the ALTCHA CAPTCHA provider plugin.
- spryker-shop/shop-ui: Renders the Storefront form theme of the CAPTCHA field.
- spryker/container: If you want to use the EventDispatcher plugins.
- spryker/event-dispatcher: If you want to use the EventDispatcher plugins.
- spryker/gui: Renders the Back Office form theme of the CAPTCHA field.
- spryker/router: Use this module when you want to use the Router.
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 16:06:02 UTC
README
Captcha module provides vendor-agnostic CAPTCHA support: a client that creates and verifies challenges through a wired provider plugin and accepts each solved challenge once, and a CaptchaType form field with a validation constraint and form themes for the Storefront and the Back Office. It owns the CAPTCHA of the five login forms: the expander plugins CustomerLoginFormCaptchaExpanderPlugin, AgentLoginFormCaptchaExpanderPlugin (Yves), UserLoginFormCaptchaExpanderPlugin, MerchantPortalLoginFormCaptchaExpanderPlugin, AgentMerchantPortalLoginFormCaptchaExpanderPlugin (Zed) add the field, and LoginCaptchaEventDispatcherPlugin (Yves, Zed) checks the submission on kernel.request at priority 10, after the login blockers' blocked check (11) and before their counting (9) and the firewall (8), and answers a rejection per form. The Back Office setting security:captcha:login:is_enabled switches the CAPTCHA on or off; it is off by default, so a project turns it on once the CAPTCHA provider is set up. Its constraint CaptchaProviderConfiguredConstraint refuses to turn it on while CaptchaClientInterface::isCaptchaProviderConfigured() returns false: no provider plugin is wired, or the provider reports through CaptchaProviderPluginInterface::isConfigured() that its saved settings are incomplete (for example a missing secret); turning it off is always accepted. The Back Office setting security:captcha:login:mode, shown only while the CAPTCHA is on, selects after_failed_attempts (default, only while a CaptchaRequirementPluginInterface plugin requires it) or always (every login). In after_failed_attempts, the SecurityBlocker step-up plugins decide when a CAPTCHA is required, with the Security Check after Failed Attempts limits on the Back Office tab Configuration → Security → Login Lock (security:login_lock:{customer,user}:challenge_*). A login page render creates no challenge for a provider that implements CaptchaChallengeUrlProviderPluginInterface: CaptchaClientInterface::createChallenge() returns a widget that fetches its challenge from a challenge endpoint (the ALTCHA widget does so when the user ticks its checkbox, one challenge per tick), and CaptchaClientInterface::createChallengeData() creates that challenge behind a rate limit in Redis (Client CaptchaConfig::getChallengeRateLimitPerIp() 30 per context and IP, an IPv6 address per /64 network, in a window of getChallengeRateLimitWindowSeconds() 60). The requests of a context from all IPs only log a warning at getChallengeRateWarningThresholdPerContext() 600 and are never rejected, because a limit for all visitors would let anyone lock them out of the login form; limit a flood from many IPs in the load balancer. The endpoints are GET /captcha/challenge?context=<context> on the Storefront (route captcha-challenge, registered by CaptchaRouteProviderPlugin) and the Back Office (ChallengeController), and GET /captcha/merchant-portal-challenge?context=<context> on the Merchant Portal (MerchantPortalChallengeController); they answer 200 with the JSON challenge, 404 for an unknown context or one of another application, 429 above the rate limit and 503 when no challenge can be created. The Back Office and Merchant Portal endpoints need anonymous access in the project firewall patterns and ACL rules. Each Zed login form of CaptchaConfig::getLoginForms() names its challenge URL and its rejection answer (REJECTION_RESPONSE_TYPE_REDIRECT or REJECTION_RESPONSE_TYPE_ZED_UI); a project adds a login form by overriding the method and appending a CaptchaLoginFormTransfer.
Installation
composer require spryker/captcha