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:
In the
csrf-protection
section, enable CSRF protection. This is a global configuration option and applies to all policy elements.Enable the CSRF violation
VIOL_CSRF
in the violations section (the violation is already enabled inAlarm
mode in the base template). This is a global configuration option and applies to all policy elements.In the
csrf-urls
section, the user can define method and URL configurations. By default, the wildcard URL*
with thePOST
method is configured to enforce Origin validation. The default configuration can be deleted to allow for customized configuration for specific methods and URLs.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.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
andcsrf-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. ThecrossDomainAllowedOrigin
in theurls
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:
Origin header must exist in the request.
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”.