Imports
Several Web App Firewall features make use of external files that you upload to the Web App Firewall when configuring it. Using the GUI, you manage those files in the Imports pane, which has four tabs corresponding to the four types of files you can import: HTML error objects, XML error objects, XML schemas, and Web Services Description Language (WSDL) files. Using the NetScaler command line, you can import these types of files, but you cannot export them.
HTML error object
When a user’s connection to an HTML or Web 2.0 page is blocked, or a user asks for a non-existent HTML or Web 2.0 page, the Web App Firewall sends an HTML-based error response to the user’s browser. When configuring which error response the Web App Firewall must use, you have two choices:
- You can configure a redirect URL, which can be hosted on any Web server to which users also have access. For example, if you have a custom error page on your Web server, 404.html, you can configure the Web App Firewall to redirect users to that page when a connection is blocked.
- You can configure an HTML error object, which is an HTML-based Web page that is hosted on the Web App Firewall itself. If you choose this option, you must upload the HTML error object to the Web App Firewall. You do that in the Imports pane, on the HTML Error Object tab.
The error object must be a standard HTML file that contains no non-HTML syntax except for Web App Firewall error object customization variables. It cannot contain any CGI scripts, server-parsed code, or PHP code. The customization variables enable you to embed troubleshooting information in the error object that the user receives when a request is blocked. While most requests that the Web App Firewall blocks are illegitimate, even a properly configured Web App Firewall can occasionally block legitimate requests, especially when you first deploy it or after you make significant changes to your protected websites. By embedding information in the error page, you provide the user with the information that he or she needs to give to the technical support person so that any issues can be fixed.
The Web App Firewall error page customization variables are:
- ${NS_TRANSACTION_ID}. The transaction ID that the Web App Firewall assigned to this transaction.
- ${NS_APPFW_SESSION_ID}. The Web App Firewall session ID.
- ${NS_APPFW_VIOLATION_CATEGORY}. The specific Web App Firewall security check or rule that was violated.
-
${NS_APPFW_VIOLATION_LOG}. The detailed error message associated with the violation.
- ${COOKIE The contents of the specified cookie. For
<CookieName>, substitute the name of the specific cookie that you want to display on the error page. If you have multiple cookies whose contents you want to display for troubleshooting, you can use multiple instances of this customization variable, each with the appropriate cookie name. Note: If you have blocking enabled for the Cookie Consistency Check, any blocked cookies are not displayed on the error page because the Web App Firewall blocks them.
To use these variables, you embed them in the HTML or XML of the error page object as if they were an ordinary text string. When the error object is displayed to the user, for each customization variable the Web App Firewall substitutes the information to which the variable refers. An example HTML error page that uses custom variables is shown below.
<!doctype html public "-//w3c//dtd html 4.0//en"> <html> <head> <title>Page Not Accessible</title> </head> <body> <h1>Page Not Accessible</h1> <p>The page that you accessed is not available. You can:</p> <ul> <li>return to the <b><a href="[homePage]">home page</a></b>, re-establish your session, and try again, or,</li> <li>report this incident to the help desk via <b><a href="mailto:[helpDeskEmailAddress]">email</a></b> or by calling [helpDeskPhoneNumber].</li> </ul> <p>If you contact the help desk, please provide the following information:</p> <table cellpadding=8 width=80%> <tr><th align="right" width=30%>Transaction ID:</th><td align="left" valign="top" width=70%>${NS_TRANSACTION_ID}</td></tr> <tr><th align="right" width=30%>Session ID:</th><td align="left" valign="top" width=70%>${NS_APPFW_SESSION_ID}</td></tr> <tr><th align="right" width=30%>Violation Category:</th><td align="left" valign="top" width=70%>${NS_APPFW_VIOLATION_CATEGORY}</td></tr> <tr><th align="right" width=30%>Violation Log:</th><td align="left" valign="top" width=70%>${NS_APPFW_VIOLATION_LOG}</td></tr> <tr><th align="right" width=30%>Cookie Name:</th><td align="left" valign="top" width=70%>${COOKIE("[cookieName]")}</td></tr> </table> <body> <html>
<!--NeedCopy-->
To use this error page, copy it into a text or HTML editor. Substitute the appropriate local information for the following variables, which are enclosed in square brackets to distinguish them from the NetScaler variables. (Leave those unchanged.):
-
[homePage]. The URL for your website’s home page. -
[helpDeskEmailAddress]. The email address that you want users to use to report blocking incidents. -
[helpDeskPhoneNumber]. The phone number that you want users to call to report blocking incidents. -
[cookieName]. The name of the cookie whose contents you want to display on the error page.
XML error object
When a user’s connection to an XML page is blocked, or a user asks for a nonexistent XML application, the Web App Firewall sends an XML-based error response to the user’s browser. You configure the error response by uploading an XML-based error page to the Web App Firewall in the Imports Pane, on the XML Error Object tab. All XML error responses are hosted on the Web App Firewall. You cannot configure a redirect URL for XML applications.
Note: You can use the same customization variables in an XML error object as in an HTML error object.
XML Schema
When the Web App Firewall performs a validation check on a user’s request for an XML or Web 2.0 application, it can validate the request against the XML schema or design type document (DTD) for that application and reject any request that does not follow the schema or DTD. Both an XML schema and a DTD are standard XML configuration files that describe the structure of a specific type of XML document.
WSDL
When the Web App Firewall performs a validation check on a user’s request for an XML SOAP-based web service, it can validate the request against the web services type definition (WSDL) file for that web service. A WSDL file is a standard XML SOAP configuration file that defines the elements of a specific XML SOAP web service.
API Specification Import Object
API specification defines the design of an API, including endpoints, methods, parameters, and data formats. The import API specification capability allows you to import the open API specification, which is generally used to describe the REST API. When the Web App Firewall performs a validation check on a user’s request for an API-based web service, it validates the request against the schema specified in the API specification file for that web service. NetScaler supports schema validations for a REST API with payload being application JSON and ProtoBuf for gRPC API requests.
NetScaler supports the following specification formats:
- Open API - Swagger 2.0, OAS 3.0,3.1
- ProtoBuf - v3 and v2
For more information, see API Specification Import.