Yii CSRF Protection Library

The package provides PSR-15 middleware for CSRF protection:

• It supports two algorithms out of the box:
  • Synchronizer CSRF token with customizable token generation and storage. By default, it uses random data and session.
  • HMAC based token with customizable identity generation. Uses session by default.
• It has ability to apply masking to CSRF token string to make BREACH attack impossible.
• It supports CSRF protection by custom header for AJAX/SPA backend API.

Requirements

• PHP 7.4 - 8.5.

Installation

The package could be installed with Composer:

General usage

In order to enable CSRF protection you need to add CsrfTokenMiddleware to your main middleware stack. In Yii it is done by configuring MiddlewareDispatcher:

or define the MiddlewareDispatcher configuration in the DI container:

By default, CSRF token is obtained from _csrf request body parameter or X-CSRF-Token header.

You can access currently valid token as a string using CsrfTokenInterface:

If the token does not pass validation, the response 422 Unprocessable Entity will be returned. You can change this behavior by implementing your own request handler:

or define the CsrfTokenMiddleware configuration in the DI container, using your own RequestHandlerInterface implementation as a regular service instead of the anonymous class above:

By default, CsrfTokenMiddleware considers GET, HEAD, OPTIONS methods as safe operations and doesn't perform CSRF validation. You can change this behavior as follows:

or define the CsrfTokenMiddleware configuration in the DI container:

CSRF Tokens

In case Yii framework is used along with config plugin, the package is configured automatically to use synchronizer token and masked decorator. You can change that depending on your needs.

Use synchronizer token for sensitive anonymous forms; use HMAC signed token for authenticated-only forms when it is acceptable for a submitted token to stay valid until it expires.

Detailed comparison:

To switch to HMAC signed token:

Synchronizer CSRF token

Synchronizer CSRF token is a stateful CSRF token that is a unique random string. It is saved in persistent storage available only to the currently logged-in user. The same token is added to a form. When the form is submitted, token that came from the form is compared against the token stored.

SynchronizerCsrfToken requires implementation of the following interfaces:

• CsrfTokenGeneratorInterface for generating a new CSRF token;
• CsrfTokenStorageInterface for persisting a token between requests.

Package provides RandomCsrfTokenGenerator that generates a random token and SessionCsrfTokenStorage that persists a token between requests in a user session.

To learn more about the synchronizer token pattern, check OWASP CSRF cheat sheet.

HMAC signed token

HMAC signed token is a stateless CSRF token that does not require any storage. The token contains expiration timestamp and its signature is bound to the current identity. The token is added to a form. When the form is submitted, we verify the token signature, check that it belongs to the current identity, and check that it has not expired.

HmacCsrfToken requires implementation of CsrfTokenIdentityGeneratorInterface for generating an identity. The package provides SessionCsrfTokenIdentityGenerator that is using session ID thus making the session a token scope.

Parameters set via the HmacCsrfToken constructor are:

• $secretKey — shared secret key used to generate the hash;
• $algorithm — hash algorithm for message authentication. sha256, sha384 or sha512 are recommended;
• $lifetime — number of seconds that the token is valid for.

When using HMAC with the config plugin, configure these constructor arguments through parameters:

To learn more about employing HMAC CSRF tokens, check the OWASP CSRF cheat sheet.

Stub CSRF token

The StubCsrfToken simply stores and returns a token string. It does not perform any additional validation. This implementation can be useful when mocking CSRF token behavior during unit testing or when providing placeholder functionality in temporary solutions.

Masked CSRF token

MaskedCsrfToken is a decorator for CsrfTokenInterface that applies masking to a token string. It makes BREACH attack impossible, so it is safe to use token in HTML to be later passed to the next request either as a hidden form field or via JavaScript async request.

It is recommended to always use this decorator.

CSRF protection for AJAX/SPA backend API

If you are using a cookie to authenticate your AJAX/SPA, then you do need CSRF protection for the backend API.

Employing custom request header

In this pattern, AJAX/SPA frontend appends a custom header to API requests that require CSRF protection. No token is needed for this approach. This defense relies on the CORS preflight mechanism which sends an OPTIONS request to verify CORS compliance with the destination server. All modern browsers, according to the same-origin policy security model, designate requests with custom headers as "to be preflighted". When the API requires a custom header, you know that the request must have been preflighted if it came from a browser.

The header can be any arbitrary key-value pair, as long as it does not conflict with existing headers. Empty value is also acceptable.

When handling the request, the API checks for the existence of this header. If the header does not exist, the backend rejects the request as potential forgery. Employing a custom header allows to reject simple requests that browsers do not designate as "to be preflighted" and permit them to be sent to any origin.

In order to enable CSRF protection you need to add CsrfHeaderMiddleware to the MiddlewareDispatcher configuration:

or in the DI container:

or add CsrfHeaderMiddleware to the routes that must be protected to the router configuration:

By default, CsrfHeaderMiddleware considers only GET, HEAD, POST methods as unsafe operations. Requests with other HTTP methods trigger CORS preflight and do not require CSRF header validation. You can change this behavior as follows:

or define the CsrfHeaderMiddleware configuration in the DI container:

The use of a custom request header for CSRF protection is based on the CORS Protocol. Thus, you must configure the CORS module to allow or deny cross-origin access to the backend API.

Warning

CsrfHeaderMiddleware can be used to prevent forgery of same-origin requests and requests from the list of specific origins only.

Protecting same-origin requests

In this scenario:

• AJAX/SPA frontend and API backend have the same origin.
• Cross-origin requests to the API server are denied.
• Simple CORS requests must be restricted.

Configure CORS module

• Responses to a CORS preflight requests must not contain CORS headers.
• Responses to an actual requests must not contain CORS headers.

Configure middlewares stack

Add CsrfHeaderMiddleware to the MiddlewareDispatcher configuration:

or to the routes that must be protected to the router configuration:

Configure frontend requests

On the frontend add to the GET, HEAD, POST requests a custom header defined in the CsrfHeaderMiddleware with an empty or random value.

Protecting requests from the list of specific origins

In this scenario:

• AJAX/SPA frontend and API backend have different origins.
• Allow cross origin requests to the API server from the list of specific origins only.
• Simple CORS requests must be restricted.

Configure CORS module

• A successful responses to a CORS preflight requests must contain appropriate CORS headers.
• Responses to an actual requests must contain appropriate CORS headers.
• Value of the CORS header Access-Control-Allow-Origin must contain origin from the predefined list.

Configure middlewares stack

Add CsrfHeaderMiddleware to the MiddlewareDispatcher configuration:

or to the routes that must be protected to the router configuration:

Configure frontend requests

On the frontend add to the GET, HEAD, POST requests a custom header defined in the CsrfHeaderMiddleware with an empty or random value.

Protecting requests passed from any origin

In this scenario:

• AJAX/SPA frontend and API backend have different origins.
• Allow cross origin requests to the API server from any origin.
• All requests are considered unsafe and must be protected against CSRF with CSRF-token.

Configure CORS module

• A successful responses to a CORS preflight requests must contain appropriate CORS headers.
• Responses to an actual requests must contain appropriate CORS headers.
• The CORS header Access-Control-Allow-Origin has the same value as Origin header in the request.

Configure middlewares stack

By default, CsrfTokenMiddleware considers GET, HEAD, OPTIONS methods as safe operations and doesn't perform CSRF validation. In JavaScript-based apps, requests are made programmatically; therefore, to increase application protection, the only OPTIONS method can be considered safe and need not be appended with a CSRF token header.

Configure CsrfTokenMiddleware safe methods:

or in the DI container:

Add CsrfTokenMiddleware to the MiddlewareDispatcher configuration:

or to the routes that must be protected to the router configuration:

Configure routes

Create a route for acquiring CSRF-tokens from the frontend application to the router configuration.

Configure frontend requests

On the frontend first make a request to the configured endpoint and acquire a CSRF-token to use it in the subsequent requests.

Add to all requests a custom header defined in the CsrfTokenMiddleware with acquired CSRF-token value.

Publishing the CSRF token in a cookie

Instead of a dedicated endpoint, CsrfTokenCookieMiddleware publishes the current token in a JavaScript-readable cookie on every response. SPA HTTP clients such as Axios and Inertia read this cookie automatically and send it back in a request header.

The middleware only writes the cookie. Token validation stays the responsibility of CsrfTokenMiddleware, and the token from the request cookie is never trusted as proof — the submitted value is always taken from the request header or body parameter.

Add CsrfTokenCookieMiddleware to the stack before CsrfTokenMiddleware. It decorates the response returned by the inner handlers, so this placement lets it publish the token even when CsrfTokenMiddleware rejects the request with 422 Unprocessable Entity and a stale SPA can recover with the fresh value.

Every cookie attribute is set through the constructor. By default, the cookie is named XSRF-TOKEN, is available for the / path, has no Domain, and is marked SameSite=Lax. The Secure attribute defaults to null, which means it is resolved per request from the request URI scheme (Secure is added when the scheme is https). It is not HttpOnly, so that the frontend can read it.

A Set-Cookie header does not by itself prevent a response from being cached (RFC 9111 section 7.3), so a response that publishes the token may be cached and later replay a stale token, or end up in a shared (proxy or CDN) cache and hand one user's token to another. The last constructor argument controls the Cache-Control response header:

• true (default) — set Cache-Control to no-store, replacing any existing value (the middleware makes the response user-specific, so a previously cacheable Cache-Control is no longer safe);
• false — leave the header untouched (use this when the application already manages caching for these responses);
• a string — set Cache-Control to that exact value, for example 'private'.

For example, Axios and Inertia send the token back in the X-XSRF-TOKEN header, so set the same name on CsrfTokenMiddleware:

In a Yii application, add both middlewares to the MiddlewareDispatcher configuration:

To customize the cookie, replace CsrfTokenCookieMiddleware::class with an array definition:

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii CSRF Protection Library is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates