Howto Front End Novell Access Manager with a Citrix Netscaler SSL Terminator



SSL acceleration is a method of offloading the processor-intensive public key encryption algorithms involved in SSL transactions to a hardware terminator, or accelerator. This may be a separate card that plugs into a PCI slot in a computer that contains one or more co-processors able to handle the SSL processing, or a dedicated (and expensive) hardware device.

The most computationally expensive part of an SSL session is the stage where the SSL server (the Identity or Proxy server in the case of this document) software is required to decrypt the SSL session key (an asymmetric key) that has been sent to it from the SSL client (usually a web browser). This is known as the SSL handshake. Typically a hardware SSL terminator will offload processing of the SSL handshake while leaving the server software to process the less intense symmetric cryptography of the actual SSL data exchange. As well as handling the handshake, the terminator acts as a proxy handling all SSL operations and leaving the server seeing only unencrypted connections.

The benefits in terms of performance of the Access Manager server are very high, often resulting in faster performance, and higher throughput.

Although this document focuses on the Citrix Netscaler SSL terminator rewriter configuration, the Access Manager configuration settings will be the same for any SSL terminator. The SSL terminator administration guide is available at The actual setup of the SSL terminator was based on the following example -

Environment details:

In the following setup:

  • The Identity (IDP) server and Linux Access Gateway (LAG) HTTP farm were only accessible via the HTTP VIP as shown in Figure 1 below
  • The IDP and LAG servers communicate with each other via the load balancer and not directly
  • All Access Gateway Servers are Linux, and the IDP servers are on SLES 10 SP2
  • The Netscaler is NS 9.1 build 95.3cl
  • The IDP server has TCP 80 defined as it's base URL so that only standard ports traverse the netscaler. The IDP uses iptables to translate requests destined for TCP 80 to TCP 8080 (add references).

Figure 1: Network overview

Click to view.

Netscalar Configuration Details:

Although there are GUI methods to do all of this, most of the examples in the Citrix documentation and web site tend to list the CLI solutions. For this reason, we have gone with the CLI options.

Most of the changes are for the IDP server and NOT the LAG ; the LAG, as shown in section below, is capable of rewriting the references itself.

The configuration instructions assume that the SSL Offload vservers have been created for the LAGs and the IDP servers. We have used the logical name of "Access Manager Access Gateway" for the LAG vserver, and "Access Manager IDP Server" for the IDPs. Vserver setup details are available from the links referenced in the Introduction.

To enable all the rewrite functionality needed, do the following:

  1. Tell the Netscaler to rewrite information in the HTTP header to be HTTPS:

    The string used within the quotes is the vserver name of the SSL Offload virtual server. Each Access Manager component set will have different names for these things.

    In the CLI:

    set ssl vserver "Access Manager Access Gateway" -sslRedirect ENABLED -redirectPortRewrite ENABLED
    set ssl vserver "Access Manager IDP Server" -sslRedirect ENABLED -redirectPortRewrite ENABLED

    Enabling SSL Redirect (-sslRedirect) causes the NetScaler system to convert any HTTP 302 redirect responses from backend servers to HTTPS redirects.
  • Create a policy to scan the HTTP data (as opposed to headers) as is passes through the netscaler device and replace references of http:// with https://

    In the CLI:

    add rewrite action httpRewriteAction replace_all "http.res.body(50000)" "\"https://\"" -pattern "http://"
    add rewrite policy HttpToHttpsRewrite "http.res.body(50000).contains(\"http://\")" httpRewriteAction

    The (50000) value references the number of bytes to scan through to replace. This number can be tweaked for the size of the page, 50000 was from the citrix support examples.
  • Bind the policy to the IDP Server VIP

    In the CLI:

    bind lb vserver "Access Manager IDP Server" -policyName HttpToHttpsRewrite -priority 100 -gotoPriorityExpression END -type RESPONSE

    This will rewrite the all IDP generated references of http to the https scheme. An example of this would be the following entry in the default login (login.jsp) page which includes the HTML form with an action tag indicating where the credentials are to be posted. The page itself includes the following:

    <form name="IDPLogin" enctype="application/x-www-form-urlencoded" method="POST" action="<%= (String) request.getAttribute("url") %>" AUTOCOMPLETE="off">

    When the JSP is executed, the following is sent back to the browser by the IDP server:

    <form name="IDPLogin" enctype="application/x-www-form-urlencoded" method="POST" action="" AUTOCOMPLETE="off">

    With our policy defined above, the action tag will be rewritten to:

    <form name="IDPLogin" enctype="application/x-www-form-urlencoded" method="POST" action="" AUTOCOMPLETE="off">

Access Manager Configuration Details:

With the Netscalar taking care of the rewrites of HTTP to HTTPS on the Identity Server, the only changes required on the Access Manager side are for the Linux Access Gateway proxy servers. There are three particular cases where the LAG must have it's scheme rewritten correctly:

  1. All web pages rendered through the LAG must have their schemes rewritten from HTTP to HTTPS.

    With the complexity of Web pages, many SSL terminators have issues rewriting all references in a web page from HTTP to HTTPS. The LAG must take responsibility for this work.

    By default, the LAG rewriter will not rewrite the scheme if the proxy and back-end Web servers being accelerated talk the same protocol. In our case, all traffic into the proxy will be HTTP and all traffic to the back-end Web servers will also be HTTP – implying that no scheme rewriting will take place. Since the browser expects all links to reference HTTPS schemes, the LAG must be configured to automatically rewrite all HTTP references on Web pages to HTTPS.
  • The Liberty Authentication request generated by the LAG must have the target URL rewritten to HTTPS.

    When a user accesses a LAG protected resource, a corresponding Liberty Authentication request is generated by the ESP and sent to the IDP server via the browser. This authentication request includes multiple attributes, including information about the trusted Liberty SP generating the request, a target URL the user must be redirected to post authentication, and the contract to be executed at the IDP server. The target URL will be embedded in this Authentication request and will reference a HTTP resource. The LAG must be able to rewrite this HTTP request to HTTPS. An example of this is the following, sent by the LAG to the IDP via the browser

    HTTP/1.1 302 Moved Temporarily
    Server: Apache-Coyote/1.1
    Set-Cookie: JSESSIONID=AF5484F1CD4D218C5404A17A0DA86E5A; Path=/nesp; secure
    Date: Tue, 18 May 2010 13:53:26 GMT
    Content-Length: 0
    Via: 1.1 (Access Gateway 3.1.1-265_eng_600589-7AA324FFCBA4D4ED)

    The target parameter, embedded within the Authentication request references "". This needs to be rewritten to use the https scheme e.g. ""

  • The 'Location' HTTP header in the 302 redirects must have it's scheme rewritten from HTTP to HTTPS

    There are two cases where the LAG sends redirects back to the browser:

    • When a non authenticated user tries to access a protected resource, a series of HTTP redirects are generated by the LAG that will redirect the user to the onboard ESP (see XXX for more details), or to the IDP server requesting the users credentials. Browsers execute on these 302 Redirect status codes and generate corresponding requests to the URL defined in the 'Location' HTTP header. The scheme on the 'Location' header must be HTTPS and not the default HTTP.
  • When the back-end Web server sends a 302 Redirect to the browser, the LAG must interpret the URL and make any rewrites it deems necessary (such as scheme and path based multihomed path injection). Since the proxy and back-end Web server scheme are both HTTP in the setup, the Location header will not be rewritten by default.

The following two files exist on the LAG to handle the first two cases above (a and b), whereas the SSL terminator will handle the later case. The SSL terminator will handle any 'Location' HTTP header rewrites generated by the Web server or LAG.

  1. Rewriting all HTTP references to HTTPS. In the CLI:

    # touch /tmp/.rewriteAlwaysHTTPS

    If this touch file is enabled, the Linux Access Gateway rewrites all HTTP links to HTTPS before rendering the pages to the browser.

  • Rewriting target URL within Liberty Authentication Request. In the CLI

    # touch /var/novell/.ForceHTTPSSchemeInESPRedirection

    In this case, the original URL accessed by the browser is rewritten with the HTTPS scheme. This ensures that the traffic is sent back to the browser after the authentication contains the right protocol (SSL/TLS).

  • Restart the LAG. In the CLI:

    # /etc/init.d/novell-vmc restart 

    Any time a change is made to a touch file, the VMC services must be restarted on the LAG for the changes to register.


How To-Best Practice
Comment List