Working with FirePass Portal Access (Reverse Proxy)

Deployment Guide Working with the FirePass Controller Portal Access (Reverse Proxy) Mode

Working with FirePass Portal Access (Reverse Proxy) The FirePass controller, the industry leading SSL VPN solution that enables organizations of any size to provide ubiquitous secure access to employees, partners and customers, provides a variety of different way to securely access internal applications by remote users. This document focuses on the FirePass Portal Access (Reverse Proxy) mode, and was designed to inform users of what to be aware of when creating and integrating applications for use with the Reverse Proxy. This document contains tips aimed toward web application developers and User Interface designers on creating web content that works through the Reverse Proxy, as well as detailed descriptions of specific content types that should or should not be used through the reverse proxy, and troubleshooting options (including using Bypass mode) if an application is not functioning properly through the proxy. This document was written as of version 5.5 of the FirePass controller. Description of Web Applications <a Portal Access (formerly MyIntranet) provides remote users with web-based remote access to a wide variety of network applications and resources without requiring client configuration changes or software downloads. You can use Portal Access when you want to allow users to access a specific web application, but not provide full network access. The FirePass controller provides security by proxying all requests to internal applications. When proxying connections, the controller uses its content parsing/patching engine and content-processing scripts to modify the URLs and anchor tags in the original HTML document by rewriting the URI to replace the hostname with that of the FirePass controller and to add additional information indicating the actual internal server. For example, if a link on a page looks like the following: <a href='http://company.com/...'> The FirePass content processing engine converts this to something similar to the following example: href='https://firepass.company.com/f5-w-x8d676sba8c650337ebf0937652fd67828ac8a76653627 88f8a7d9449c9/...'> You can configure the controller to use specialized UNIX-style stream editor (SED) scripts to modify intranet web pages as the content passes through web applications, to handle issues related to proxying complex content. Global settings address specific issues, such as handling non-html content and obfuscating cleartext cookies. 1

Working with the FirePass Reverse Proxy F5 Networks has tested Microsoft Outlook Web Access (OWA), Microsoft SharePoint, IBM Lotus Domino Web Access (also known as IBM Lotus inotes or Notes ), and Microsoft file servers configured for Common Internet File System (CIFS, the remote file access system that runs over TCP/IP but uses the Server Message Block (SMB) protocol), for compatibility through Portal Access. Other web applications work with Portal Access without requiring additional configuration, but some, particularly those that make extensive use of JavaScript, Java applets, ActiveX controls, Flash Components, and XML might require that you use content processing scripts or other workarounds described in this document. The FirePass controller Reverse Proxy functionality handles complex JavaScript and Java applets. The process uses the proxy engine and a dynamic cache on the FirePass controller to increase proxy performance. The FirePass controller rewrites the content before caching it, although, with the dynamic cache, the FirePass controller does not always have to rewrite content for static objects such as HTML, JavaScript, style sheets, and Java apples. Also, the Reverse Proxy engine supports rewrite of complex applets such as Citrix, VNC, and.jar and.cab archive resigning. The nature of web applications, especially those that rely heavily on dynamic content such as JavaScript, Java applets, ActiveX controls and Flash components, can make some applications difficult to support through a reverse proxy. This is further complicated if the application was poorly written, or does not use well formed HTML. The FirePass controller Reverse Proxy fully supports web applications written in standard HTML, CSS, JavaScript, Flash and Java. See the following section, Content Types, for specific details on these and other content types. The Troubleshooting tools for difficult applications section, on page 8, describes some common issues with complex applications, and suggests possible resolutions. Content Types This section describes specific content types which may have specific factors to be aware of when writing code or applications for use with the FirePass controller Reverse Proxy. HTTP The FirePass controller Reverse Proxy supports HTTP/1.1 and 1.0 when communicating to the browser, whereas only HTTP/1.0 is supported to the backend server. Make sure that all HTTP headers adhere to the HTTP specification for the version being employed. FirePass Deployment Guide 2

The Reverse Proxy passes all headers from the web servers to the browser. Avoid using custom headers with URLs as a value, because the Reverse Proxy does not modify custom headers and passes them without rewriting. Use the standard headers defined by HTTP. Note Custom content processing (SED) scripts can only rewrite page content. The Content-Type header should match the actual content of the document. For example, do not send a content type of text/html if the content is not true HTML content (for example, a GIF or JPEG image). The Reverse proxy attempts to detect and correct the Content-Type, but it is better if the header matches the actual content. If Content-Type headers are not properly sent, web applications performance may be negatively affected. HTML HTML 4.0 is fully supported through the FirePass controller Reverse Proxy. HTML 3.2 and earlier are officially supported. Refer to http://www.w3.org/markup/ for HTML specifications. Be sure to use valid, well-formed HTML. Check your pages through HTML syntax checker; there are a number of free sites that will check the syntax of your HTML. The Reverse Proxy parser does not fail on improperly coded HTML, but there are limitations. Follow the URL specification, http://www.faqs.org/rfcs/rfc1738.html when constructing URLs in HTML pages. Avoid using HTML escape codes in the URLs. Use forward slashes ('/') in URLs instead of backward slashes ('\'). CSS Cascading style sheets are supported. Be sure the content type is set to text/css for cascading stylesheets. If the content type is set incorrectly, errors can occur through the Reverse Proxy. JavaScript code within a cascading style sheet is not supported. Refer to http://www.w3.org/style/css/ for the CSS specification. JavaScript The Reverse Proxy engine handles complex uses of JavaScript. All JavaScript passed from internal servers is parsed and patched by the Reverse Proxy engine. The FirePass controller then passes additional JavaScript helper include files to the client in order to help with dynamic analysis/patching of the JavaScript as it is executed on the client. 3

Working with the FirePass Reverse Proxy To use the Reverse Proxy in more effective way, please keep in mind following caveats. Note All of the following recommendations are applicable only for the portions of your code that must process or compute URL references for interaction with browser and network. Wherever possible, use simple, straight-forward JavaScript coding. We recommend you avoid using dynamic compilation with arguments which contain complex scripts (for example: eval, Function, and document.write). Avoid JavaScript scripts within frames which write active content into other, sibling frames. JavaScript has a feature which also allows dynamic generation of code on the browser. For example, the eval() function allows for dynamic generation and execution on the client-side. It is not possible for the Reverse Proxy to accurately intermediate this code. It is recommended you write code using as few indirect references to objects and functions as possible, and avoid using the Eval function. The use of document.write is supported by Reverse Proxy. However, as mentioned previously, it is not recommended. We do not recommend using the with statement. Do not use $ in JavaScript names to avoid conflicts with Reverse Proxy generated names. Use of relative URLs within JavaScript is highly recommended. Please also limit the dynamic construction of URLs and client-side cookie parsing/checking from JavaScript. Note that a Proxy Bypass (minimal content re-write) mode is available as a hotfix for FirePass version 5.4.2 and as part of the FirePass version 5.5 release. When this mode is enabled, client-side JavaScript is not modified/patched by the FirePass controller. See the Using the Reverse Proxy Bypass mode section for more information. Following is a current list of JavaScript methods which are currently modified/patched by the FirePass Reverse Proxy: write, writeln, open, close, createpopup, addrule, ClearBrowserCache, SetApplicationDataURL, getresponseheader, insertadjacenthtml, load, LoadURL, Download, Upload, showhelp, createstylesheet, Navigate, Navigate2, NavigateAndFind, assign, startdownload, Install, InitPath, InitLanguage, DownloadAttach, OpenSession, RetrieveData, addparam, ModifyProc21, replace, save, search, setattribute, setinterval, settimeout, showmodaldialog, tostring, addbehavior, charat, charcodeat, concat, match, search, slice, substr, substring, tolowercase, tolocalelowercase, touppercase, tolocaleuppercase, action, backgroundimage, background, cookie, filter, domain, host, hostname, href, innerhtml, location, outerhtml, pathname, port, FirePass Deployment Guide 4

protocol, referrer, referer, search, src, DocumentHTML, BaseURL, ReportSource, AnnDataPath, BitmapDataPath, ReportURL, URL, BaseHref, tostring JavaScript content rewriting methodology The FirePass Reverse Proxy leaves much of the underlying JavaScript intact, but wraps the critical methods and properties into functions that FirePass includes as part of additional client-side JavaScript. These functions are used to parse/patch the data on the fly at run time (at the client). For example, a call might be re-written from: window.document.write('<a href="http://internal.site.com">internal link</a>'); to something similar to the following example: ur$call$method(window, "document", "write")('<a href="http://internal.site.com">internal link</a>'); Here the function ur$call$method(...) returns the function (technically, the closure), that, being applied to the original arguments of the document.write() method, modifies this argument appropriately, and calls document.write with the modified argument. So, the internal call of the document.write method will have an argument: '<a href="https://firepass.enerprise.com/f5-w-...">internal link</a>' Instead of the original one. Here is the list of all methods that are transformed to ur$call$method call: addbehavior, addhierarchy, appendchild, createelement, createpopup, close, execcommand, EditDocument, EditDocument2, ViewDocument, ViewDocument2, CreateNewDocument, CreateNewDocument2, SendForReview, SendForReview2, ImportList, getresponseheader, insertadjacenthtml, load, LoadURL, showhelp, createstylesheet,!navigate, NavigateAndFind, open, replace, save, search, setattribute, setinterval, settimeout, showmodaldialog, showmodelessdialog, tostring, write, writeln, createcontextualfragment, opennewwindow, addrule Additionally, all read and write access to DOM variables that reference URLs are transformed, for example document.location and form.action. The wrapper functions are: ur$get$property() and ur$set$property() functions The functions are used like the following example: document.cookie="foo=bar;;path=/"; In the previous example, the function is rewritten like the following: document.cookie=ur$set$property(document, "cookie", "foo=bar;;path=/"); With the 5.5 release, it is possible to wrap content with FirePass specific tags <FP_DO_NOT_TOUCH> and </FP_DO_NOT_TOUCH>. These tags indicate to the FirePass Reverse Proxy engine that the content between these tags should not be patched by the re-write engine. This can be used to help prevent the FirePass controller from patching sensitive JavaScript 5

Working with the FirePass Reverse Proxy content or for occasions where patched content is not needed. Note that the FirePass minimal bypass mode also results in FirePass not patching JavaScript (only minimal patching of HTML pages is performed). To use these tags, you may either include these in the web page source, or may be inserted through use of FirePass Content Processing SED scripts (see the Troubleshooting tools for difficult applications section for more information). Java Code Signing Certificates Macromedia Flash The Reverse Proxy rewrites client-side Java applets at the bytecode level. All network access initiated from the applet must be proxied through the FirePass controller to ensure it reaches the correct intranet server. Method calls originally made to Sun's network classes are replaced with equivalent calls to a special proxy class the Reverse Proxy inserts during the rewrite. Applets that use proprietary libraries or formats, or require socket connections initiated from the server may not function correctly when used through the Reverse Proxy. The applet that is delivered to the client is different than the original, so internal integrity testing methods based on bytecode checksums will fail. The FirePass re-signs the new applet after the rewriting it to ensure it can still run in privileged mode. The old signature is no longer valid for the new bytecode. The Reverse Proxy re-signs the applet with a real certificate issued by Thawte Code Signing CA to F5 Networks. While applet starts, the browser displays a warning that must be accepted. Check the Always Trust Content from F5 Networks options to eliminate further security warnings. Macromedia Flash files (*.SWF) are fully supported and rewritten. The Flash ActionScript format is also supported and rewritten. Because of the Flash file format, Flash files cannot be streamed through the Reverse Proxy, they are fully downloaded from the server by the FirePass Reverse Proxy, rewritten, and then sent to user. If you plan to deliver big flash files (such as files with a video stream inside a flash file) there will be a delay before the file download is started for the user, while the Reverse Proxy downloads and patches the file. FirePass Deployment Guide 6

Using the Reverse Proxy Bypass mode Pattern-based bypass To allow the FirePass controller clients to access sites that are running complex applications via web applications without configuring content processing scripts, you can use the Minimal Content Rewriting Bypass feature. Unlike typical FirePass content processing, the FirePass controller does not rewrite URLs or parse cookies when the Minimal Content Rewriting Bypass feature is enabled. Only host names in URLs are re-written by the FirePass controller (in order to direct clients to FirePass instead of the internal server). There are some advantages to using Minimal Content Rewriting Bypass mode: The FirePass controller does not need to prefix every HTML link or dynamic URL with an rewritten string which encodes the internal destination host and port. Because there is less manipulation (only the host name and port are re-written), there is less chance for incompatibilities. Cookie processing is greatly simplified. Note that cookie pass-through should be explicitly enabled if necessary for a site. (This must be manually done if using bypass mode for a site, as automatic cookie passthrough is not supported with bypass mode). See the FirePass Controller Administrator Guide for more details. Bypass mode can only be used to solve problems on single internal intranet hosts (one-to-one mapping). It is not an appropriate solution for portals spanning multiple internal hosts. If cookie pass-through is enabled for bypass mode, the cookies are not obfuscated. Note We recommend you try the options in the Troubleshooting tools for difficult applications section before using bypass mode. There are two alternative methods for Bypass mode: pattern-based proxy and an alternate port-host based proxy. This mode provides a pattern matching mechanism for URLs. You specify a protocol, host, and directory for the FirePass controller to match. If the FirePass controller matches the URL with a Pattern Based Bypass Proxy rule, it does not modify the URL. You can implement the Pattern Based Bypass Proxy mode without making network changes, but it does require you to enter the protocol, host, and directories that are used by your application so that FirePass can match the incoming URLs. Patterns are case sensitive, so instances where upper case and lower case patterns are required necessitate multiple pattern-based entries. 7

Working with the FirePass Reverse Proxy Alternative Host/Port Based Proxy Care must be used when using the Pattern-based Proxy mode, as a page with URL references to other servers will not have those other server references rewritten. Therefore this technique should be applied only to difficult standalone web applications, not to application portals. For specific information on how to configure Pattern Based Proxy mode, see the following solution on the Ask F5 Technical Support web site: http://tech.f5.com/home/firepass/solutions/content/sol4746.html#bypass Alternative host/port based proxy mode allows a 1:1 mapping between a FirePass controller web service and an internal host (no path restrictions or conflicts with other internal hosts). This mode provides dedicated IP address and port combinations through which connections are proxied to the application server. When configuring FirePass in Alternative Port/Host Based Proxy mode, you must configure one FirePass port (and depending on your application requirements, an IP address), for each port that is used by the application server. If your application uses SSL encryption, you must also install a compatible SSL certificate and key on FirePass. For specific information on how to configure Alternative Host/Port Based Proxy mode, see the following solution on the Ask F5 Technical Support web site: http://tech.f5.com/home/firepass/solutions/content/sol4746.html#alternative Troubleshooting tools for difficult applications Compatibility Mode There are a number of ways to configure the FirePass device to allow difficult applications to work properly. We recommend you try these options before attempting to use bypass mode. As a starting point, we suggest you double check your Intranet connectivity to make sure there are no network problems. Also, test applications using different browsers to see if the problem can be narrowed to a specific browser. If you have recently upgraded your FirePass controller and an application that previously worked through the Reverse Proxy suddenly does not, you can use Compatibility mode. Compatibility mode allows you to continue to use the Web Applications routines that shipped with versions 5.2.1 and earlier of the FirePass controller. This is useful if you have developed SED scripts tuned to the particular requirements of your intranet, and you are satisfied with the legacy functionality of Portal Applications: Web Applications (formerly MyIntranet). FirePass Deployment Guide 8

Internet Explorer gzip compression bug Compression and Cache settings Application Tunnels Compatibility mode does much less JavaScript parsing/patching than the default mode of operation. This means that there is less chance for incorrect patching of JavaScript, but some dynamically created URLs may not be re-written. To turn on Compatibility mode, from the navigation pane, click Portal Access and from the Web Applications menu, click Content Processing. At the top of the page, click the Global Settings tab, and find the Web Applications Global Settings section at the bottom of the page. Click a check in the Compatibility mode (enable legacy version of Web Applications handler) box, and then restart the service. If you are using compression, and any of your users may be using an unpatched version of Microsoft Internet Explorer 6, the application may not work correctly through the FirePass device. Unpatched versions of IE 6 contain a bug that strips off the leading two kilobytes of server messages when you use gzip compression. The FirePass device can add 2K of leading, padding blanks to remedy this bug for IE, and does not affect the appearance of the application on other browsers. To enable this fix, from the navigation pane, click Portal Access and from the Web Applications menu, click Content Processing. At the top of the page, click the Global Settings tab, and find the Web Applications Global Settings section at the bottom of the page. Click a check in the Remedy IE gzip compression bug by adding leading 2 kilobytes of whitespace to HTML pages box, and then restart the service. Rarely, using compression and/or caching on the FirePass controller may cause conflicts with difficult applications. If you are experiencing problems and are using compression and caching, try disabling these features one at a time, and testing the application again. There are also a number of granular caching global settings that can be used to tune the caching feature. To modify the compression and cache settings, from the navigation pane, click Portal Access, and from the Web Applications menu, click Caching and Compression. The Caching and Compression configuration options are found on this page. If acceptable for your configuration, using an Application Tunnel provides excellent results for difficult applications. The main difference between using Application Tunnels and Portal Access (Reverse Proxy) is that with an Application Tunnel, on the remote end, when it is a Windows platform, the browser loads an ActiveX control in Internet Explorer, or a self-installed plug-in in for Netscape or Mozilla browsers. Administrators have the flexibility to choose between Active-X and a Java client when enabling 9

Working with the FirePass Reverse Proxy Content Processing Scripts Troubleshooting Content Processing scripts Application Tunnels configured for Application access. For more information on configuring Application Tunnels, refer to the FirePass Handbook or the Online Help. The FirePass controller can perform additional special purpose processing of content passing through Web Applications, using Web Applications Content Processing (SED) scripts. With SED scripts, you can specify a single URL match pattern list for each particular processing type (for example, response pre-processing, response post-processing, and request processing). The FirePass device uses the first URL match in the list of entries defined for processing the URL content. For example, s/http:\/\//http:\/\//g will perform a global search of HTTP://, replacing each instance found with http:// (note that the backslash character escapes the forward slash). Much more complex scripts (supporting regular expressions) may be entered to replace or modify content, or to fix html errors within pages. Beginning in version 5.4, FirePass uses a new prefix in URLs that it rewrites. In versions prior to 5.4, the format for rewritten URLs is: https://<firepass>/i-tr-<obscured>/<path> In version 5.4 and later, the format for rewritten URLs is: https://<firepass>/f5-w-<obscured>/<path> As a result of this change, content processing scripts that search for rewritten URLs that include i-tr- no longer work and those URLs are not changed back to their original form. This results in broken links. To fix these scripts, perform the following steps: To fix existing content processing scripts 1. From the Administration Console, click Portal Access. 2. Click Content Processing. 3. Click each Processing Script Favorite and change every URL search instance of i-tr- to f5-w-. Another possible issue with content processing scripts is that the FirePass device uses the first script it finds that matches the content of a search. Once FirePass selects a script, it does not check the remaining scripts for a match. When you have multiple content processing scripts, it is important you provide content that is specific so the FirePass device does not make an incorrect match. For more information about how to configure Content Processing (SED) scripts, see the FirePass Controller Handbook, or the Online Help. FirePass Deployment Guide 10

11 For additional troubleshooting information, see Solution 3084 on Ask F5: How do I solve common problems introduced by the FirePass reverse proxy functions?