Token

The token feature is an additional security layer that helps protect your captcha and form from Cross-Site Request Forgery attacks.

Understanding CSRF

CSRF is a type of security vulnerability that can lead to unauthorized actions being performed on behalf of a user without their consent. CSRF attacks typically occur when a malicious website tricks a user's browser into making a request to another website. To prevent such attacks, web applications use CSRF tokens. These tokens are unique, random values generated on the server and associated with a user's session. They must be included in every form or request submitted by the user. When the server receives a request, it checks if the included CSRF token matches the one stored in the user's session. If they match, the request is considered valid, otherwise it's rejected.

Default token class

The included token class, located at \IconCaptcha\Token\IconCaptchaToken::class, uses server sessions to store CSRF tokens. While rendering a token, the class tries to start a server session on its own using session_start() in case none has been started yet.

The generated token will be rendered as a hidden HTML input element with the name _iconcaptcha-token and a random string value with the length of 32.

Protecting your form

To include the token into your form protected by IconCaptcha, simply add the following PHP snippet within the same form where the widget is placed. It's worth noting that if you are unable to execute PHP within your HTML page, this feature will not function and should be disabled.

<?php echo \IconCaptcha\Token\IconCaptchaToken::render(); ?>

This code will generate and render the CSRF token in your form, ensuring it is included in the form data when it's submitted. Additionally, any interaction with the captcha widget that results in a server request, such as requesting a challenge or validating an input, will automatically include this token. If, however, the token is either absent despite being configured or is invalid, the server will reject these requests.

Disabling the option

If you don't want to use the token feature, or if your application already has its own CSRF protection, you can easily turn it off. To do so, simply set the token option to null as described on the configuration wiki page.

'token' => null,

Creating a custom class

It is possible to create your own custom token class for generating and validating CSRF tokens if you wish to do so. Ensure that your custom class extends the \IconCaptcha\Token\AbstractToken class and implements the interface \IconCaptcha\Token\TokenInterface, which contains the function definitions which must be implemented.

To configure IconCaptcha to use your custom class, set the token option to the fully-qualified class name as shown below.

'token' => \Path\To\Your\CustomToken::class,

Custom class example:

use IconCaptcha\Token\AbstractToken;
use IconCaptcha\Token\TokenInterface;

class CustomToken extends AbstractToken implements TokenInterface
{
    public static function render(): string
    {
        // ...
    }

    public function get(): string
    {
        // ...
    }

    public function validate(string $payloadToken, string $headerToken = null): bool
    {
        // ...
    }
}

Function definitions

The following functions must be implemented in your custom token class.

Function	Description
render(): string	Returns an HTML input field as a string, containing the captcha token as its value.
get(): string	Returns the captcha token for the current request.
validate(string $payloadToken, string $headerToken = null): bool	Validates the stored token with the token included with the request.