Sun Java System Access Manager 7 2005Q4 Deployment Planning Guide

Using a Load Balancer With Access Manager

The load balancer distributes the client requests between the Access Manager instances in multiple server deployment. Before you use this information in the section, configure your Access Manager deployment as a site, as described in Configuring an Access Manager Deployment as a Site. A site includes multiple (two or more) instances of Access Manager installed on different host servers. All Access Managers instances must access the same Directory Server and use the same password encryption key. For information about installing Access Manager, see Installing Access Manager on Multiple Host Servers.

This section include the following information about using a load balancer:

Configuring SSL Termination for a Load Balancer

Before you configure a load balancer to handle SSL requests, first configure SSL for the Access Manger web container. For instructions, see Chapter 3, Configuring Access Manager in SSL Mode, in Sun Java System Access Manager 7 2005Q4 Administration Guide.

To configure SSL for a load balancer and Access Manager servers, consider the following cases:

SSL configuration for only the load balancer: SSL termination.

The load balancer terminates the SSL connection from the client and makes a separate SSL connection to the Access Manager servers.
SSL configuration for only the Access Manager servers: SSL pass-through.

The load balancer bypasses all the requests from the client to the Access Manager servers.
SSL configuration for both the load balancer and Access Manager servers.

For all cases, except for the SSL pass-through configuration, you can use a normal server certificate to enable SSL termination for the load balancer. However, when you configure SSL pass-through for the load balancer and the Access Manager servers and the load balancer bypasses all the requests from the client to the Access Manager server, the following SSL problems exist for a normal server certificate:

When a client accesses the Access Manager servers through the load balancer, the client gets the server certificate from the Access Manager server. The load balancer doesn't have an SSL server certificate and just bypasses the client requests to the back-end Access Manager servers. The client then receives a warning message saying that the host name and subject name in server certificate are different.
To avoid the above problem, install a server certificate with the SubjectDN of the load balancer name; however, a problem occurs in the session validation between two Access Manager servers.

For example, if a user gets a session from amserver1 and a second request for the same user is directed to amserver2, then amserver2 has to validate the users session to amserver1. When amserver2 sends a session validation request to amserver1, it makes an SSL connection to amserver1 and then gets the server certificate with the SubjectDN of the load balancer from amserver1. Because those two names (host name of amserver1 and subjectDN in certificate) differ, amserver2 stops the SSL handshaking, and the session validation fails.

To solve these problems, Access Manager provides these properties:

com.iplanet.am.jssproxy.trustAllServerCerts

If enabled (true), Access Manager ignores all certificate related issues (such as a name conflict) and continues the SSL handshaking.

Caution –
To prevent a possible security risk, enable this property only for testing or when the enterprise network is tightly controlled. Avoid enabling this property if a security risk might occur (for example, if a server connects to a server in a different network).
com.iplanet.am.jssproxy.SSLTrustHostList

If enabled (true), Access Manager checks the platform server list in the AMConfig.properties file. If the server FQDNs of the two servers in the platform server list match, Access Manager continues the SSL handshaking.
com.iplanet.am.jssproxy.checkSubjectAltName

If enabled (by specifying a comma separated list of trusted FQDNs) and a server certificate includes the Subject Alternative Name (SubjectAltName) extension, Access Manager checks all name entries in the extension. If one of names in the SubjectAltName extension is the same as the server FQDN, Access Manager continues the SSL handshaking. Using this property is more secure than enabling the com.iplanet.am.jssproxy.trustAllServerCerts property. With a Public-Key Infrastructure (PKIX) definition, a certificate can have multiple subject names with SubjectAltName extension.

To enable this property, set it to a comma separated list of trusted FQDNs. For example:
```
com.iplanet.am.jssproxy.checkSubjectAltName=
amserv1.example.com,amserv2.example.com
```
To get a certificate with SubjectAltName extension, see the next section.

Generating a CSR with the SubjectAltName Extension

To generate a certificate signing request (CSR) with the SubjectAltName extension, use the Certificate Database Tool (certutil). If certutil is not available in the /usr/sfw/bin directory, first install the SUNWtlsu package on Solaris systems or the sun-nss-sun-nss-devel RPM on Linux systems. If necessary, set the LD_LIBRARY_PATH environment variable to the appropriate certutil path.

For information about certutil, see: http://www.mozilla.org/

This section describes how to use the certutil if you are using Web Server or Application Server as the web container. If you are using BEA WebLogic Server or IBM WebSphere Application Server as the web container, refer to the respective BEA or IBM product documentation.

To generate a CSR with the SubjectAltName extension, follow these steps:

Create a new certificate database (cert8.db) using the certutil -N option. If necessary, first create a directory for your database. For example:

# mkdir certdbdir 
# cd certdbdir 
# certutil -N -d .

When prompted by certutil, enter the password to encrypt your keys:

Enter a password which will be used to encrypt your keys. 
The password should be at least 8 characters long, 
and should contain at least one non-alphabetic character.

Enter new password: your-password 
Re-enter password:  your-password

Generate the CSR with the SubjectAltName extension. For example:

# certutil -R -s "cn=lb.example.com,o=example.com,c=us" 
-o server.req -d . -a -8 amserv1.example.com,amserv2.example.com

When prompted by certutil, enter the password (or pin) and then type keys to generate the random seed to create your key:

Enter Password or Pin for "NSS Certificate DB": your-password

A random seed must be generated that will be used in the  
creation of your key.  One of the easiest ways to create a  
random seed is to use the timing of keystrokes on a keyboard.   

To begin, type keys on the keyboard until this progress meter  
is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!   

Continue typing until the progress meter is full:   

|************************************************************|   

Finished.  Press enter to continue:   

Generating key.  This may take a few moments...

Send the CSR (server.req file in the example) to the Certificate Authority (CA). Get the server certificate and add it to the certificate database using the certutil -A option.
Copy the certificate database (cert8.db) to the web container directory.
- Web Server. Copy the cert8.db and key3.db databases to the /opt/SUNWwbsrv/alias directory and rename them using the Web Server instance name. For example:
```
https-webserver.example.com-webserver-cert8.db
https-webserver.example.com-webserver-key3.db
```
- Application Server. Copy the cert8.db and key3.db databases to the instance /config directory. For example:
```
/var/opt/SUNWappserver/domains/domain1/config/cert8.db 
/var/opt/SUNWappserver/domains/domain1/config/key3.db
```

Configuring Access Manager For Load Balancer Cookies

To configure Access Manager for load balancer cookies, update the configuration for all Access Manager instances in the deployment so that the instances can recognize the load balancer. In this scenario, multiple (two or more) Access Manager instances are deployed on different host servers. A load balancer routes client requests to the various Access Manager instances. All Access Manager instances use the same Directory Server.

In the Access Manager Console, configure the Access Manager deployment as a site, as described in Configuring an Access Manager Deployment as a Site. When you configure a deployment as a site, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer.
In the AMConfig.properties file for each Access Manager instance, add the following properties:
```
com.iplanet.am.lbcookie.name=amlbcookie
com.iplanet.am.lbcookie.value=amserver
```
where amlbcookie is the load balancer cookie, and amserver is the name of the Access Manager host server for the instance.
Restart all Access Manager instances by restarting the respective web container.

Configuring a Load Balancer with SAML

In this scenario, an Access Manager site is using a load balancer to distribute client requests to various Access Manager instances, and the site has implemented the Security Assertions Markup Language (SAML) service. When a request is sent to an Access Manager instance through a load balancer, the instance must know which other Access Manager server in the deployment issued the original assertion or artifact in order to retrieve the SAML assertion.

The deployment must first be configured as a site. Multiple Access Manager instances are installed on host servers, and a load balancer routes client requests to the various instances. All Access Manager instances access the same Directory Server. Access Manager session failover is optional.

To configure a site to use a load balancer with SAML, follow these steps:

The Access Manager deployment must be configured as a site in order for SAML load balancing to work. If you haven't configured the Access Manager deployment as a site, follow the instructions in Configuring an Access Manager Deployment as a Site.
Log in to the Access Manager Console as amadmin.
In the Access Manager Console, click Federation and then SAML.
Under the Properties section in SAML Profile, add or modify the following entries:
- Site Identifiers. Add each Access Manager instance in the deployment. All Access Manager instances must share the same Site ID and Site Issuer Name.
- Trusted Partners. Add your partner's deployment site's Source ID (site ID), Issuer Name, and Host List. The unique Source ID (site ID) and Issuer Name for the Access Manager servers and the URL or IP address or host name of the load balancer will identify the deployment and will be given out to your partner's site for configuration.
  
  For information about these fields, see the Sun Java System Access Manager 7 2005Q4 Federation and SAML Administration Guide.
Click Save to save your changes.

Setting the `fqdnMap` Property

If you have configured an Access Manager deployment as a site, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer , and you do not need to set this property in the AMConfig.properties file. However, for the following Access Manager deployments, you must explicitly set the property:

The deployment is not configured as a site.
The deployment has virtual hosts that are mapped to a physical host.

If you need to set the fqdnMap property, set the property to the load balancer in the AMConfig.properties file for each Access Manager instance in the deployment. If necessary, first remove the comment character (#) from the property. For example:

com.sun.identity.server.fqdnMap[lb.example.com]=lb.example.com

Accessing an Access Manager Instance Through a Load Balancer

Accessing an Access Manager instance through a load balancer depends on the mode (realm or legacy) and the console you want to access. Use the following syntax to access an Access Manager instance through a load balancer:

http://loadbalancer.domain:port/amserver/console|/amconsole

In legacy mode, you can access both consoles:

New Access Manager 7 2005Q4 Console. For example:

http://loadbalancer.example.com:80/amserver/console
Access Manager 6 2005Q1 Console. For example:

http://loadbalancer.example.com:80/amconsole

In realm mode, you can access only the new Access Manager 7 2005Q4 Console. For example:

http://loadbalancer.example.com:80/amserver/console