Overview: CSRF Configuration

There are several settings that can be configured to enable CSRF protection, some are global while others are specific. Following is a list of all the settings that can be configured to enable or customize the CSRF settings:

  1. In the csrf-protection section, enable CSRF protection. This is a global configuration option and applies to all policy elements.

  2. Enable the CSRF violation VIOL_CSRF in the violations section (the violation is already enabled in Alarm mode in the base template). This is a global configuration option and applies to all policy elements.

  3. In the csrf-urls section, the user can define method and URL configurations. By default, the wildcard URL * with the POST method is configured to enforce Origin validation. The default configuration can be deleted to allow for customized configuration for specific methods and URLs.

  4. In the urls section, you can enable CSRF protection for specific URLs, and define a list of acceptable origins. If the wildcard URL * is selected, the configuration becomes global for all URLs. Otherwise, the configuration is applicable only to the specified URL.

  5. In the host-names section, you can add a list of the domains that are to be accepted when comparing the origin to the hostnames. The user can enable or disable the inclusion of subdomains. This is a global configuration option and applies to all policy elements.

Please note that:

  • Both VIOL_CSRF and csrf-protection settings need to be enabled for CSRF protection to be active. Disabling either setting will disable CSRF protection altogether.

  • Configuring urls is required only if there are external origins that have to be allowed.

  • host-names are internal, owned by the application and used by clients to reach it. The crossDomainAllowedOrigin in the urls are external domains, from other applications, that we wish to allow as origins.

CSRF Enforcement

If CSRF is enabled in the violation section and in the csrf-protection settings, when receiving a request to a URL that matches one of the csrf-urls and all its conditions: method and parameters (if applicable there), then the following conditions must be met:

  1. Origin header must exist in the request.

  2. The domain name from the origin header must match any of the following criteria:

    • The Host header in the same request.

    • One of the hostnames in the policy.

    • One of the allowed origins in the matching URL entity in the policy.

If the first condition is not met, the validation will fail with the message “Origin header validation failed: Origin is absent”. If the second condition fails to match any of the items, the validation will fail with the message “Origin header validation failed: Origin is not allowed”.