Getting Started

Minimal Steps to First Use

Install the Package
```
composer require symfony/security-csrf
```
For Laravel, ensure compatibility with your Symfony components (e.g., symfony/http-foundation).

Register the Service Bind the CsrfTokenManagerInterface to a concrete implementation in Laravel’s service container (e.g., app/Providers/AppServiceProvider.php):

use Symfony\Component\Security\Csrf\CsrfTokenManager;
use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;

public function register()
{
    $this->app->singleton(CsrfTokenManagerInterface::class, function ($app) {
        $tokenGenerator = new UriSafeTokenGenerator();
        return new CsrfTokenManager($tokenGenerator);
    });
}

Generate a Token Inject CsrfTokenManagerInterface into a controller or service:

use Symfony\Component\Security\Csrf\CsrfTokenManagerInterface;

public function showForm(CsrfTokenManagerInterface $csrfTokenManager)
{
    $token = $csrfTokenManager->getToken('form_token')->getValue();
    return view('form', ['csrf_token' => $token]);
}

Validate a Token In a form handler or API endpoint:

public function submitForm(Request $request, CsrfTokenManagerInterface $csrfTokenManager)
{
    $token = $request->request->get('_csrf_token');
    if (!$csrfTokenManager->isTokenValid(new CsrfToken('form_token', $token))) {
        throw new \Symfony\Component\Security\Core\Exception\AccessDeniedException('Invalid CSRF token.');
    }
    // Process the form...
}

Laravel Integration (Optional) Extend Laravel’s built-in CSRF middleware (app/Http/Middleware/VerifyCsrfToken.php) to use Symfony’s token manager:

use Symfony\Component\Security\Csrf\CsrfTokenManagerInterface;

protected function validateCsrfToken($request, $exception)
{
    $token = $request->input('_csrf_token');
    if (!$this->csrfTokenManager->isTokenValid(new CsrfToken('laravel_csrf_token', $token))) {
        throw $exception;
    }
}

First Use Case: Protecting a Form

Scenario: Secure a form submission (e.g., payment, user profile update).

Steps:

Generate a token in the form view:

<input type="hidden" name="_csrf_token" value="{{ $csrf_token }}">

Validate the token in the controller:

$this->validate($request, ['_csrf_token' => 'required|string']);
if (!$this->csrfTokenManager->isTokenValid(new CsrfToken('form_token', $request->input('_csrf_token')))) {
    abort(403, 'Invalid CSRF token.');
}

Implementation Patterns

Core Workflows

1. Token Generation and Storage

Default Behavior: Tokens are generated using UriSafeTokenGenerator (base64-encoded random bytes) and stored in memory or a session.

Custom Storage:

Implement CsrfTokenStorageInterface for database/Redis storage:

use Symfony\Component\Security\Csrf\TokenStorage\TokenStorageInterface;

class DatabaseTokenStorage implements TokenStorageInterface
{
    public function getToken($tokenId): ?CsrfToken
    {
        // Fetch from database...
    }

    public function deleteToken($tokenId): void
    {
        // Delete from database...
    }
}

Bind the custom storage to CsrfTokenManager:

$this->app->singleton(CsrfTokenManagerInterface::class, function ($app) {
    $storage = new DatabaseTokenStorage();
    $tokenGenerator = new UriSafeTokenGenerator();
    return new CsrfTokenManager($tokenGenerator, $storage);
});

2. Stateless CSRF Protection (APIs)

Use SameSite attributes and headers (e.g., Sec-Fetch-Site) for stateless validation:

use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
use Symfony\Component\Security\Csrf\TokenStorage\CookieTokenStorage;

$tokenStorage = new CookieTokenStorage(
    $requestStack,
    'XSRF-TOKEN',
    'X-CSRF-TOKEN',
    ['same_site' => 'lax']
);
$csrfTokenManager = new CsrfTokenManager(new UriSafeTokenGenerator(), $tokenStorage);

Laravel-Specific: Use middleware to inject the token into headers:

public function handle($request, Closure $next)
{
    $token = $this->csrfTokenManager->getToken('api_token')->getValue();
    $request->headers->set('X-CSRF-Token', $token);
    return $next($request);
}

3. Token Rotation

Rotate tokens after each use (e.g., for sensitive forms):

$token = $csrfTokenManager->getToken('form_token');
$csrfTokenManager->deleteToken('form_token'); // Invalidate old token

4. Multi-Token Support

Use different token IDs for different forms/endpoints:

// Generate for login form
$loginToken = $csrfTokenManager->getToken('login_token')->getValue();

// Generate for profile form
$profileToken = $csrfTokenManager->getToken('profile_token')->getValue();

Integration Tips

Laravel-Specific Patterns

Middleware Integration Create a custom middleware to validate CSRF tokens:

namespace App\Http\Middleware;

use Closure;
use Symfony\Component\Security\Csrf\CsrfTokenManagerInterface;
use Symfony\Component\Security\Csrf\CsrfToken;

class CsrfTokenMiddleware
{
    public function __construct(protected CsrfTokenManagerInterface $csrfTokenManager)
    {
    }

    public function handle($request, Closure $next)
    {
        if ($request->isMethod('post') && !$request->has('_csrf_token')) {
            abort(403);
        }

        $token = $request->input('_csrf_token');
        if (!$this->csrfTokenManager->isTokenValid(new CsrfToken('laravel_csrf_token', $token))) {
            abort(403, 'Invalid CSRF token.');
        }

        return $next($request);
    }
}

protected $middleware = [
    // ...
    \App\Http\Middleware\CsrfTokenMiddleware::class,
];

Blade Directives Create a Blade directive for token generation:

Blade::directive('csrfToken', function ($expression) {
    $token = app(CsrfTokenManagerInterface::class)->getToken($expression)->getValue();
    return "<?php echo '{$token}'; ?>";
});

Usage in views:

<input type="hidden" name="_csrf_token" value="{{ csrfToken('form_token') }}">

API Resource Protection For APIs, use a header-based approach:

// Middleware
public function handle($request, Closure $next)
{
    $token = $request->header('X-CSRF-TOKEN');
    if (!$this->csrfTokenManager->isTokenValid(new CsrfToken('api_token', $token))) {
        abort(403);
    }
    return $next($request);
}

Testing Patterns

Unit Testing Tokens Mock CsrfTokenManager in tests:

$tokenManager = $this->createMock(CsrfTokenManagerInterface::class);
$tokenManager->method('isTokenValid')->willReturn(true);

$this->app->instance(CsrfTokenManagerInterface::class, $tokenManager);

Integration Testing Test token validation with real requests:

public function test_csrf_protection()
{
    $response = $this->post('/submit-form', [
        '_csrf_token' => $this->csrfTokenManager->getToken('form_token')->getValue(),
        'data' => 'test',
    ]);
    $response->assertStatus(200);
}

Gotchas and Tips

Pitfalls

Token Storage Assumptions
- Issue: Symfony’s CsrfTokenManager defaults to in-memory storage, which is not persistent across requests.
- Fix: Use a session or database-backed storage (e.g., SessionTokenStorage or a custom implementation).
- Laravel Note: Laravel’s session driver works but may require adapter logic.
Token ID Collisions
- Issue: Using the same token ID (e.g., 'form_token') for multiple forms can cause validation failures if tokens are rotated.

Security Csrf Laravel Package