ocramius/psr7-csrf

PSR-7 Storage-less HTTP CSRF protection

, _(*1)

PSR7Csrf is a PSR-7 middleware that enables CSRF protection for PSR-7 based applications., _(*2)

DEPRECATED in favor of psr7-sessions/storageless 5.0.0+

Please note that this package is DEPRECATED., _(*3)

Since psr7-sessions/storageless 5.0.0, the generated cookies are CSRF-resistant by default for unsafe HTTP methods (POST/PUT/DELETE/PATCH/etc.), so the usage of this package is no longer needed. You can still install ocramius/psr7-csrf, but since there is no practical need for it, it is not necessary to do so., _(*4)

What is this about?

Instead of storing tokens in the session, PSR7Csrf simply uses JWT tokens, which can be verified, signed and have a specific lifetime on their own., _(*5)

This storage-less approach prevents having to load tokens from a session or from a database, and simplifies the entire UI workflow: tokens are valid as long as their signature and expiration date holds., _(*6)

Installation

composer require ocramius/psr7-csrf

Usage

The simplest usage is based on defaults. It assumes that you have a configured PSR-7 compatible application that supports piping middlewares, and it also requires you to run PSR7Session., _(*7)

In a zendframework/zend-expressive application, the setup would look like the following:, _(*8)

$app = \Zend\Expressive\AppFactory::create();

$app->pipe(\PSR7Session\Http\SessionMiddleware::fromSymmetricKeyDefaults(
    'mBC5v1sOKVvbdEitdSBenu59nfNfhwkedkJVNabosTw=', // replace this with a key of your own (see PSR7Session docs)
    1200 // 20 minutes session duration
));

$app->pipe(\PSR7Csrf\Factory::createDefaultCSRFCheckerMiddleware());

This setup will require that any requests that are not GET, HEAD or OPTIONS contain a csrf_token in the request body parameters (JSON or URL-encoded)., _(*9)

You can generate the CSRF token for any form like following:, _(*10)

$tokenGenerator = \PSR7Csrf\Factory::createDefaultTokenGenerator();

$app->get('/get', function ($request, $response) use ($tokenGenerator) {
    $response
        ->getBody()
        ->write(
            '

Examples

composer install # install at the root of this package first!
cd examples
composer install
php -S localhost:9999 index.php

Then try accessing http://localhost:9999: you should see a simple submission form., _(*11)

If you try modifying the submitted CSRF token (which is in a hidden form field), then the POST request will fail., _(*12)

Known limitations

Please refer to the known limitations of PSR7Session., _(*13)

Also, this component does NOT prevent double-form-submissions: it merely prevents CSRF attacks from third parties. As long as the CSRF token is valid, it can be reused over multiple requests., _(*14)

Contributing

Please refer to the contributing notes., _(*15)

License

This project is made public under the MIT LICENSE., _(*16)