Novell Doc: Novell Access Manager 3.1 SP2 Setup Guide

2.4 Using an SSL Terminator

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

The most processing-intensive part of an SSL session is the stage where the SSL server (the Identity Server or Access Gateway) 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 offloads the processing of the SSL handshake while leaving the server software to process the less intense symmetric cryptography of the actual SSL data exchange. The terminator can also act as a proxy and handle all SSL operations, which allows the server that is behind the terminator use unencrypted connections.

The performance benefits to the Access Manager servers are very high, often resulting in faster performance and higher throughput.

Although the Access Manager configuration settings are the same for any SSL terminator, the process for configuring the terminator for rewriting varies with the hardware. The following explanations use the Citrix Netscaler SSL terminator to explain the required rewriter configuration. For more information about this SSL terminator, see the following documents:

Citrix NetScaler Traffic Management Guide was used for general information about the device.
SharePoint Deployment Guide was used for the actual setup of the SSL terminator.

The following sections describe the required network configuration, the required Access Manager components, and the terminator and Access Gateway configuration process.

2.4.1 Required Setup

The diagram below illustrates the sample setup that was used for the configuration steps.

This setup has the following features:

The Citrix Netscaler SSL terminator is configured to load balance (it provides the L4 switch functionality) and to offload the SSL traffic.
The Identity Servers and the Access Gateways are accessible only through the SSL terminator via HTTP.
The Identity Servers and the Access Gateways communicate to each other through the SSL terminator.
The Identity Server cluster is configured to use HTTP on port 80. For information on translating the default 8080 port to 80, see Translating the Identity Server Configuration Port in the Novell Access Manager 3.1 SP2 Identity Server Guide.

2.4.2 Configuring the SSL Terminator

The configuration instructions assume that the SSL virtual servers have been created for the Access Gateways and Identity Servers on the SSL terminator. This sample configuration uses the logical name of “Access Manager Access Gateway” for the Access Gateway virtual server, and “Access Manager Identity Server” for the Identity Sever virtual server. The virtual server setup details are available in the documentation links referenced in Section 2.4, Using an SSL Terminator.

To enable the rewrite functionality:

Configure the SSL terminator to rewrite information in the HTTP header to be HTTPS:

The string used within the quotes is the virtual server name of the SSL virtual server. Each Access Manager component set has a different name for the virtual server.
1. At the command line, enter the following command for the Access Gateway:
```
set ssl vserver "Access Manager Access Gateway" -sslRedirect ENABLED -redirectPortRewrite ENABLED 
```
  The "Access Manager Access Gateway" string needs to be replaced with the name you have specified for the Access Gateway virtual server.
  
  Enabling SSL Redirect (-sslRedirect) causes the SSL terminator to convert any HTTP 302 redirect responses from back-end servers to HTTPS redirects.
2. At the command line, enter the following command for the Identity Server.
```
set ssl vserver "Access Manager Identity Server" -sslRedirect ENABLED -redirectPortRewrite ENABLED 
```
  The "Access Manager Identity Server" string needs to be replaced with the name you have specified for the Identity Server virtual server.
Create a policy to scan the HTTP data (as opposed to headers) as it passes through the SSL terminator and replace references to http:// with references to https://.

At the command line, enter the following commands:
```
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. This number can be tweaked for the size of the page; 50000 was from the Citrix support examples.

Bind the policy to the Identity Server virtual server.

At the command line, enter the following command:

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

This command rewrites all Identity Server generated references of http to the https scheme. For example, the following entry in the default login (login.jsp) page includes an HTML form with an action tag that indicates where the credentials are to be posted. The page includes the following line:

<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 Identity Server:

<form name="IDPLogin" enctype="application/x-www-form-urlencoded" method="POST" action="http://idp126.lab.novell.com/nidp/idff/sso?sid=4" AUTOCOMPLETE="off">

With the policy defined above, the action tag is rewritten to the following:

<form name="IDPLogin" enctype="application/x-www-form-urlencoded" method="POST" action="https://idp126.lab.novell.com/nidp/idff/sso?sid=4" AUTOCOMPLETE="off">

2.4.3 Configuring the Access Gateway

With the SSL terminator rewriting HTTP to HTTPS for the Identity Server, the only changes required on the Access Manager side are for the Access Gateway. There are three particular cases where the Access Gateway must have its scheme rewritten:

All Web pages rendered through the Access Gateway must have their schemes rewritten from HTTP to HTTPS.

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

By default, the Access Gateway rewriter does not rewrite the scheme if the proxy service and back-end Web servers use the same protocol. In this case, all traffic into the proxy is HTTP and all traffic to the back-end Web servers is also HTTP, which implies that no scheme rewriting takes place. Because the browser expects all links to reference HTTPS schemes, the Access Gateway must be configured to automatically rewrite all HTTP references on Web pages to HTTPS.
The Liberty Authentication request generated by the Access Gateway must have the target URL rewritten to HTTPS.

When a user accesses an Access Gateway protected resource, a corresponding Liberty authentication request is generated by the Embedded Service Provider and is sent to the Identity Server via the browser. This authentication request includes multiple attributes, including information about the trusted Liberty service provider generating the request, a target URL where the user must be redirected to post authentication, and the contract to be executed at the Identity Server. The target URL is embedded in this authentication request and references an HTTP resource. The Access Gateway must be able to rewrite this HTTP request to HTTPS. The following example was sent by the Access Gateway to the Identity Server via the browser.
```
HTTP/1.1 302 Moved Temporarily
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=AF5484F1CD4D218C5404A17A0DA86E5A; Path=/nesp; secure
Location: http://idp126.lab.novell.com/nidp/idff/sso?RequestID=idQgvQqocG6fgFrkeiUG6jlRD.LMk&MajorVersion=1&MinorVersion=2&IssueInstant=2010-05-18T13%3A53%3A26Z&ProviderID=https%3A%2F%2Flag129.lab.novell.com%3A443%2Fnesp%2Fidff%2Fmetadata&RelayState=MA%3D%3D&consent=urn%3Aliberty%3Aconsent%3Aunavailable&ForceAuthn=false&IsPassive=false&NameIDPolicy=onetime&ProtocolProfile=http%3A%2F%2Fprojectliberty.org%2Fprofiles%2Fbrws-art&target=http%3A%2F%2Flag129.lab.novell.com%3A443%2Fformfill%2Fphpinfo.phpentRef=u&AuthnContextStatemscell%2Fsecure%2Fname%2Fpassword%2Furi
Date: Tue, 18 May 2010 13:53:26 GMT
Content-Length: 0
Via: 1.1 lag129.lab.novell.com (Access Gateway 3.1.1-265_eng_600589-7AA324FFCBA4D4ED)
```
The target parameter embedded within the authentication request references HTTP in the following line:
```
http%3A%2F%2Flag129.lab.novell.com%3A443%2Fformfill%2Fphpinfo.php
```
This needs to be rewritten to use the HTTPS scheme, for example:
```
https%3A%2F%2Flag129.lab.novell.com%3A443%2Fformfill%2Fphpinfo.php
```
The Location HTTP header in the 302 redirects must have its scheme rewritten from HTTP to HTTPS. There are two cases where the Access Gateway sends 302 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 Access Gateway that redirect the user to the Embedded Service Provider or to the Identity Server server requesting the user’s 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 Access Gateway must interpret the URL and make any rewrites it deems necessary (such as scheme and path-based multi-homing path injection). Because the proxy and back-end Web server schemes are both HTTP in the setup, the Location header is not rewritten by default.

The Location header rewriting is handled by the SSL terminator. You have already enabled this rewriting in Step 1.a.

To configure the Access Gateway to rewrite Web page references and the target URL:

In the Administration Console, click Devices > Access Gateways > Edit > Reverse Proxy / Authentication.
In the Proxy Settings section, select Behind Third Party SSL Terminator, then click OK.
Click OK, then update the Access Gateway.