JarCastingSpring reCaptcha
Library providing a custom filter to validate reCaptcha
Requirements
- JDK 8 +
- Spring Boot 2.2+ MVC application
Supported reCaptcha version
- reCaptcha v2
- reCaptcha v3
Usage
To add the custom filter, you need to include the dependency and configure required property (see Required configuration).
dependencies {
...
implementation("com.ekino.oss.spring:spring-recaptcha:1.0.0")
...
}
When calling an url requiring reCaptcha validation, you must send the reCaptcha response parameter, either in a request parameter or in a request header.
By default the parameter (or header) name is : g-recacptcha-response (see Change default reponse parameter name)
NB : if you want to use snapshots you need to add the following configuration to your Gradle build script :
repositories {
maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots/") }
}
Configuration
Required configuration
The library comes with a configuration by default. However, you must configure the secret before using it.
security:
recaptcha:
secret: <your_secret>
By default, no url require reCaptcha validation. You must configure the url-patterns property to enable reCaptcha validation for your endpoints.
The patterns are a list of regular expressions matching the requested url.
Example :
security:
recaptcha:
url-patterns:
- "/api/resources/[^/]*/sub-resource"
- "/api/recaptcha/.*"
Other configuration
Disable filter
ReCaptcha validation filter can be disabled by setting the property :
security:
recaptcha:
enabled: false
Filter methods
By default, every urls matching one of the pattern for the POST method will need reCaptcha validation. You can modify the filtered methods by setting the properties :
security:
recaptcha:
filtered-methods:
- POST
- PUT
Note: The filtered method apply for all the url patterns.
By-passing the filter
Connection or validation issues could occur with external services.
To prevent re-deployment of the whole application to disable the filter and provide a quick fix, you can configure a private key and send it in a custom header X-ReCaptcha-ByPass-Key to by-pass the reCaptcha validation.
security:
recaptcha:
by-pass-key: <your_by_pass_private_key>
Change default response parameter name
To modify the default request parameter (or header) name, you can set the property :
security:
recaptcha:
response-name: other-response-parameter-name
Handle failure
The library provide you a default failure handling.
If the response request parameter is missing, the answer will be a 400 BAD REQUEST with message :
{
"code": "recaptcha.missing.response",
"message": "Unable to retrieve recaptcha response parameter. Please check configuration if endpoint really need reCaptcha validation or if response parameter name is correct."
}
If the validation fails, the response will be a 403 FORBIDDEN with message :
{
"code": "recaptcha.validation.failed",
"details": [ <list of error codes> ],
"message": "Validation failed for reCaptcha response."
}
Override default failure handling
You override the default failure handling by creating your own custom failure handling service :
@Service
class CustomReCaptchaFailureService(objectMapper: ObjectMapper): ReCaptchaFailureService(objectMapper) {
override fun handleMissingResponseParameter(response: HttpServletResponse) {
super.handleMissingResponseParameter(response)
}
override fun handleValidationFailure(validationFailure: ReCaptcaValidationResult.Failure, response: HttpServletResponse) {
super.handleValidationFailure(validationFailure, response)
}
}
To handle missing response request parameter, you must override the handleMissingResponseParameter method. To handle validatino failure, you must override the handleValidationFailure method.
A utility function fun handleResponse(response: HttpServletResponse, status: HttpStatus, responseContent: Any) is present to help you create you response with custom HttpStatus and content.
