Integrating your plugin with iThemes Security reCAPTCHA

Integrating your plugin with iThemes Security is a simple process. In this article, we cover how to display and validate the Recaptcha.

iThemes Security fires the itsec_recaptcha_api_ready hook when it is time for plugins to setup their Recaptcha integrations. At this point, iThemes Security has already verified that the site administrator has configured their access tokens. You can also check if the API is available by calling ITSEC_Recaptcha_API::is_available().

Technical Details: This happens during WordPress’ init hook on the standard 10 priority.

Displaying the Recaptcha

To display the Recaptcha, simply call the ITSEC_Recaptcha_API::display() function. If the API is not available, an empty string will be displayed.

You don’t need to worry about fetching API keys, or choosing whether to display Recaptcha V2 or Invisible Recaptcha, iThemes Security handles all of that. For example.

function my_plugin_display_recaptcha() {
	ITSEC_Recaptcha_API::display();
}
add_action( 'my_login_form_template', 'my_plugin_display_recaptcha' );

Technical Details: The Recaptcha field requires JavaScript to work properly. The show_recaptcha() method will automatically enqueue the necessary scripts. If you are loading your form via Ajax, you might need to manually print these scripts. Call wp_print_scripts() aftercalling the show_recaptcha() method.

By default, the V2 Recaptcha badge has 10 pixels of margin on the top and bottom. You can customize this by using the margin option. For example:

ITSEC_Recaptcha_API::display( array( 'margin' => array( 'top' => '20' ) ) );

This will change the top margin to 20 pixels, and leave the rest of the margins as their default values. You can completely disable the margin by passing null to the option.

Validating the Recaptcha

If your plugin ends up calling the authenticate filter, typically by calling the wp_signon() or wp_authenticate() functions or posting your login form directly to wp-login.php, then iThemes Security will automatically pick up that the Recaptcha was submitted.

Likewise, for the registration form, if you use the register_new_user() function, iThemes Security will work transparently.

Alternately, if you have a custom login or registration form, or a completely different use case, you can call the validation function directly.

function my_plugin_do_login() {
	$validated = ITSEC_Recaptcha_API::validate();

	if ( is_wp_error( $validated ) ) {
		// Show error message.
		return false;
	}
	// User submitted the Recaptcha. Continue with custom login.
}

This will look in the post variables for g-recaptcha-response. This will work automatically when using Recaptcha in a standard HTML Form context. If this value won’t be populated when calling the validate() function, when using a GET form for instance, you should manually set $_POST['g-recaptcha-response'] to the captcha value. iThemes Security does not currently support passing the response code directly to the validate() function.

Technical Details: The validation result is cached for the duration of the request. If Google’s Recaptcha API is temporarily unavailable, iThemes Security will treat the validation as successful.

Have more questions? Submit a request
Powered by Zendesk