Struct CsrfMiddlewareConfig

Source

pub struct CsrfMiddlewareConfig {Show 13 fields
    pub pattern: CsrfPattern,
    pub manual_multipart: bool,
    pub session_id_cookie_name: String,
    pub token_cookie_name: String,
    pub anon_token_cookie_name: String,
    pub token_form_field: String,
    pub token_header_name: String,
    pub token_cookie_config: Option<CsrfDoubleSubmitCookie>,
    pub secret_key: Zeroizing<Vec<u8>>,
    pub skip_for: Vec<String>,
    pub enforce_origin: bool,
    pub allowed_origins: Vec<String>,
    pub max_body_bytes: usize,
}

Expand description

Configuration for CsrfMiddleware.

Choose a CSRF defense pattern and adjust behavior such as token locations, cookie names, content-type handling, and origin checks.

For the Double-Submit Cookie pattern, use CsrfMiddlewareConfig::double_submit_cookie.
For the Synchronizer Token pattern (requires the actix-session feature), use [CsrfMiddlewareConfig::synchronizer_token].

§Defaults

Token header: DEFAULT_CSRF_TOKEN_HEADER
Token form/json field: DEFAULT_CSRF_TOKEN_FIELD
Session id cookie name: DEFAULT_SESSION_ID_KEY
Max body bytes to scan for token: 2 MiB

§Security

When using Double-Submit Cookie, ensure the token cookie is readable by the client (i.e., http_only must be false) so it can be mirrored into the header.
Consider enabling strict Origin/Referer enforcement with with_enforce_origin to mitigate CSRF even if a token leaks.
Avoid allowing multipart/form-data unless you can handle token extraction manually.

§Examples

Basic Double-Submit Cookie configuration:

use actix_csrf_middleware::{CsrfMiddlewareConfig, CsrfDoubleSubmitCookie};
use actix_web::cookie::SameSite;

let secret = b"at-least-32-bytes-of-secret-key-material...";
let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret)
    .with_enforce_origin(true, vec!["https://example.com".to_string()])
    .with_token_cookie_config(CsrfDoubleSubmitCookie {
        http_only: false, // must be false for Double-Submit
        secure: true,
        same_site: SameSite::Lax,
    });

Fields§

§pattern: CsrfPattern§manual_multipart: bool§session_id_cookie_name: String§token_cookie_name: String

Authorized (session-bound) tokens

§anon_token_cookie_name: String

Anonymous (pre-session) tokens

§token_form_field: String§token_header_name: String§token_cookie_config: Option<CsrfDoubleSubmitCookie>§secret_key: Zeroizing<Vec<u8>>§skip_for: Vec<String>§enforce_origin: bool

Enforce Origin/Referer checks for mutating requests

§allowed_origins: Vec<String>

Allowed origins (scheme://host[:port]) when enforce_origin = true

§max_body_bytes: usize

Maximum allowed body bytes to read when extracting CSRF tokens from body (POST/PUT/PATCH/DELETE)

Implementations§

Source §

impl CsrfMiddlewareConfig

Source

pub fn double_submit_cookie(secret_key: &[u8]) -> Self

Constructs a configuration for the Double-Submit Cookie pattern.

The CSRF token is placed in a cookie and echoed by clients in a header or form field. The token’s integrity is protected by an HMAC bound to the session id and the token.

§Examples

use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig};
use actix_web::{App};

let secret = b"a-very-long-application-secret-key-of-32+bytes";
let cfg = CsrfMiddlewareConfig::double_submit_cookie(secret);
let app = App::new().wrap(CsrfMiddleware::new(cfg));

Source

pub fn with_multipart(self, multipart: bool) -> Self

Controls whether multipart/form-data requests are allowed to pass through.

When set to true, the middleware does not attempt to extract the CSRF token from a multipart body. Your handler must read and validate the token manually.

Defaults to false for safety.

Source

pub fn with_max_body_bytes(self, limit: usize) -> Self

Sets the maximum number of request body bytes read when searching for a CSRF token in JSON or application/x-www-form-urlencoded bodies.

Defaults to 2 MiB.

Source

pub fn with_token_cookie_config(self, config: CsrfDoubleSubmitCookie) -> Self

Overrides cookie flags for token cookies (Double-Submit Cookie pattern).

For Double-Submit Cookie, http_only must be false so client-side code can read the cookie value and mirror it into a header or form field.

Source

pub fn with_skip_for(self, patches: Vec<String>) -> Self

Skips CSRF validation for requests whose path starts with any of the given prefixes.

Useful for health checks or public webhooks where CSRF is not applicable.

Source

pub fn with_enforce_origin(self, enforce: bool, allowed: Vec<String>) -> Self

Enables strict Origin/Referer checks for mutating requests and sets the allowed origins.

Origins are compared strictly by scheme, host, and port. If allowed is empty and enforce is true, all mutating requests are rejected.

Example enabling enforcement for a single origin:

use actix_csrf_middleware::CsrfMiddlewareConfig;

let cfg = CsrfMiddlewareConfig::double_submit_cookie(b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    .with_enforce_origin(true, vec!["https://example.com".to_string()]);