Protect Against Cross-Site Request Forgery Assertion
The Protect Against Cross-Site Request Forgery assertion helps detect and prevent against CSRF (Cross-Site Request Forgery) attacks.
Protect Against Cross-Site Request Forgeryassertion helps detect and prevent against CSRF (Cross-Site Request Forgery) attacks.
This assertion provides two mechanisms to help detect a CSRF attack:
- Double Submit Cookie Validation:This can be used to validate the contents of a cookie that contains some session identifier, to see if it matches the same session identifier contained in a request parameter.
- HTTP Referer validation:This can be used to ensure that the referer value belongs to a whitelist of domains. Although the referer domain is easily spoofed, this validation reduces the attack vectors for a CSRF attack.
This assertion can only work with HTTP requests and will fail if the request is not HTTP.
Double Submit Cookie Validation
If enabled, any of the following conditions will cause the assertion to fail:
- Required cookie is not present.
- Required cookie has a name that contains non-ASCII characters.
- Required parameter is not found or does not contain a single value.
- The parameter does not match the cookie's value.
For more information about double submit cookies, visit the OWASP site at: http://www.owasp.org/ and search for "CSRF double submit cookies".
HTTP-Referer Header Validation
If enabled, the following conditions will cause the assertion to fail:
- If the HTTP-Referer header is empty and theAllow empty valuescheck box is not selected.
- The value of HTTP-Referer is not a valid URL.
- The domain of the HTTP-Referer does not belong to the whitelist.
Context Variable Created by This Assertion
The Protect Against Cross-Site Request Forgery assertion will set the context variable
csrf.valid.tokento the value of the cookie. You can use this variable later in the policy to validate the value.
Using the Assertion
- Do one of the following:
- To add the assertion to the Policy Development window, see Add an Assertion.
- To change the configuration of an existing assertion, proceed to step 2 below.
- Right-clickProtect Against CSRF Forgeryin the policy window and selectCSRF Protection Propertiesor double-click the assertion in the policy window. The assertion properties are displayed.
- Configure the dialog as follows:SettingDescriptionEnable Double Submit Cookie ValidationSelect this check box to enable double submit cookie validation.Clear this check box to not check for double cookie submissions. This will deactivate the other settings in this section.Cookie NameEnter the name of the cookie that the HTTP parameter name will be checked against.HTTP Parameter NameEnter the name of the HTTP parameter to be checked against the cookie name.Allowable HTTP MethodsChoose the HTTP methods allowed:GET, POST,orGET and POST.Enable HTTP-Referer Header ValidationSelect this check box to enable validation of the HTTP-Referer header value.Clear this check box to not validate the HTTP-Referer header value. This will deactivate the other settings in this section.Skip validation if header is missing or emptySelect this check box to omit the validation step if the HTTP-Referer is missing or empty.Clear this check box to always validate the HTTP-Referer header.Valid DomainsFrom the drop-down list, choose the valid domains:
- Current Domain:Use the current domain of theAPI Gateway. This will match the header against the domain value associated with the request, which may be the domain of the clusterorthe individualAPI Gatewayhost.
- List of Trusted Domains:Enter your own list of trusted domains in the box below.
- Click [Add] to add a new domain.
- Click [Edit] to modify the selected domain.
- Click [Remove] to remove the selected domain from the list.
- Click [OK].