User Guide | User Login CAPTCHA Functions

The flexi auth library includes a set of optional CAPTCHA functions that can be used to further secure the login process.

User Login CAPTCHA Functions

Login Index | Login Session/Cookie Config | Login reCAPTCHA Config | Login Functions
CAPTCHA Functions

recaptcha() | validate_recaptcha() | math_captcha() | validate_math_captcha() | ip_login_attempts_exceeded()

Help with Function Parameters

Show / Hide Help

Name: The name of the function parameter (argument).

Data Type: The data type that is expected by the parameter.

  • bool : Requires a boolean value of 'TRUE' or 'FALSE'.
  • string : Requires a textual value.
  • int : Requires a numeric value. It does not matter whether the value is an integer, float, decimal etc.
  • array : Requires an array.

Required: Defines whether the parameter requires a value to be submitted.

Default: Defines the default parameter value that is used if no other value is submitted.

recaptcha()

Generates the html for Google reCAPTCHA.

Library and Requirements

Available via the standard library.

Function Parameters
recaptcha(ssl) Help
Name Data Type Required Default Description
ssl bool No FALSE Defines whether the reCAPTCHA is to be displayed on an SSL secured page (https).
How it Works

The functions loads the reCAPTCHA helper file and then gets the 'Theme' and 'Language' settings from flexi auths config. file. The function then generates the captchas html using the helper file.

Notes

flexi auth loads the Google reCAPTCHA library as a helper. This file can be found in CI's 'application/helper' directory and is required for the reCAPTCHA to work.

To then use reCAPTCHA, you must signup for a set of API keys from http://www.google.com/recaptcha.

The API keys must then be set in flexi auths config. file, where additionally, reCAPTCHAs theme and language can also be set.

// Defining reCAPTCHA API Keys in flexi auth config. file.

$config['security']['recaptcha_public_key'] = 'ENTER_RECAPTCHA_PUBLIC_KEY_HERE';
$config['security']['recaptcha_private_key'] = 'ENTER_RECAPTCHA_PRIVATE_KEY_HERE';

If using the 'custom' reCAPTCHA theme (Defined via the config. file option 'recaptcha_theme'), note that the customised reCAPTCHA html code must be prepended to the code generated via the 'recaptcha()' function.

Examples of custom themes are available at https://developers.google.com/recaptcha/docs/customization.

// Defining a custom reCAPTCHA theme.
$custom_recaptcha = '
  <div id="recaptcha_widget" style="display:none">
    <div id="recaptcha_image"></div>
    <!-- Customised code ... -->
    <div><a href="javascript:Recaptcha.showhelp()">Help</a></div>
  </div>';

$custom_repcatcha .= $this->flexi_auth->recaptcha();
Return Values

Failure:n/a

Success:string

Examples
// Example : Display the reCAPTCHA on a NON SECURED page (http).

$this->flexi_auth->recaptcha(FALSE);

// Example : Display the reCAPTCHA on a SECURED page (https).

$this->flexi_auth->recaptcha(TRUE);

validate_recaptcha()

Validates if a Google reCAPTCHA answer is correct.

Library and Requirements

Available via the standard library.

How it Works

flexi auth loads the Google reCAPTCHA library as a CodeIgniter helper and validates the users IP address, and value of the submitted http POST data for the input fields 'recaptcha_challenge_field' and 'recaptcha_response_field'.

Notes

flexi auth loads the Google reCAPTCHA library as a helper. This file can be found in CI's 'application/helper' directory and is required for the reCAPTCHA to work.

This function can either be called directly or via CodeIgniters form validation library, see the examples below for further details.

The function must be called immediately by the page after the reCAPTCHA has been submitted as http POST data. Additionally, the input fields must be named 'recaptcha_challenge_field' and 'recaptcha_response_field' - as they are by default.

Return Values

Failure:FALSE

Success:TRUE

Examples
// Example : Validate a reCAPTCHA answer via a direct function call to validate_recaptcha().

$this->flexi_auth->validate_recaptcha();

// Example : Validate a reCAPTCHA answer via CodeIgniters form validation library.

$this->load->library('form_validation');
$this->form_validation->set_rules('recaptcha_response_field', 'Captcha Answer', 'required|validate_recaptcha');

math_captcha()

Generates a math captcha question and answer.

Library and Requirements

Available via the standard library.

How it Works

The function returns a basic math question and sets the answer to a CI flash session.

The returned question is meant to be immediately displayed to the user, whilst the answer in the CI flash session in validated on the next page load using the validate_math_captcha() function.

Notes

Use the validate_math_captcha() function to validate the users submitted answer.

Return Values

Failure:TRUE

Success:FALSE

Example
// Example : Generate a math question and answer, ouputting the question as a string.

$question = $this->flexi_auth->math_captcha(); // Output '19 - 5'

validate_math_captcha()

Validates if a math captcha answer is correct.

Library and Requirements

Available via the standard library.

Function Parameters
validate_math_captcha(answer) Help
Name Data Type Required Default Description
answer int Yes FALSE Defines the users submitted answer to a math captcha question.
How it Works

The function compares the users submitted answer to the math captcha answer stored via a CI flash session.

Return Values

Failure:FALSE

Success:TRUE

Example
// Example : An answer to the math captcha question '19 - 5'.

$answer = 14;

$this->flexi_auth->validate_math_captcha($answer);

ip_login_attempts_exceeded()

Validates whether the number of failed login attempts from a unique IP address has exceeded a defined limit.
The function would typically be used in conjunction with showing a captcha for users repeatedly failing login attempts.

Library and Requirements

Available via the standard library.

How it Works

When a user fails a login attempt, the library records their IP address and increments a counter tracking the number of failed attempts made by the user.

When this function is called, it checks the entire user table to find any user that last made a failed attempt using the current users IP address, and that has exceeded the defined limit of failed login attempts.

The failed login attempt limit is defined via the config. files 'login_attempt_limit' setting.

Return Values

Failure:FALSE

Success:TRUE

Examples
Note: The returned example values below are displaying live data from the current auth database and session data set via the demo.
ip_login_attempts_exceeded() Has the current users IP (3.135.192.97) exceeded 3 failed login attempts? bool(false)
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi auth was designed and developed by