A load balancer distributes the client requests between the Access Manager instances in multiple server deployment. To use a load balancer, your deployment must be configured as a site. A site includes multiple (two or more) instances of Access Manager deployed on different host servers. All Access Managers instances must access the same Directory Server and use the same password encryption key.
This chapter includes the following configuration topics:
An Access Manager deployment configured as a site allows centralized configuration management for the entire deployment.
An Access Manager site includes the following components:
Multiple server deployment: Multiple (two or more) Access Manager instances are deployed on at least two different host servers. For example, you might deploy two instances on one server and a third instance on another server. Or you might deploy all instances on different servers. You can also configure the Access Manager instances in session failover mode, if required for your deployment.
Load balancer: One or more load balancers route client requests to the various Access Manager instances. You configure each load balancer according to your deployment requirements (for example, to use round-robin or load average) to distribute the load between the Access Manager instances. A load balancer simplifies the deployment, as well as resolves issues such as a firewall between the client and the back-end Access Manager servers.
You can use a hardware or software load balancer with your Access Manager deployment. For example, for information about the Application Server Load Balancing Plug-in, see the Sun Java System Application Server Enterprise Edition 8.2 Quick Start Guide.
Directory Server: All Access Manager instances access the same Directory Server.
If you have an Access Manager multiple server deployment, use either of these methods to configure your deployment as a site:
If you plan to implement Access Manager session failover, the amsfoconfig script configures a deployment as a site. See Chapter 6, Implementing Session Failover.
If you don't plan to implement session failover, perform these steps the Access Manager Console, as described in this section:
Add the load balancer URL to the Site Name (site ID).
Map the load balancer Site Name (site ID) to each Access Manager instance in the Platform Server List.
Add the load balancer to the Realm/DNS Aliases.
In addition, Access Manager automatically sets the fqdnMap property (in memory) to include the load balancer, so you do not need to explicitly set this property in the AMConfig.properties file.
The following procedure refers to the Access Manager 7.1 Console in Realm Mode.
Log in to the Access Manager Console as amAdmin.
Add the load balancer URL to the Site Name:
In the Access Manager Console, click Configuration, System Properties, and then Platform.
Under Site Name, click New and enter the following values for the load balancer:
Server: Load balancer protocol, host name, and port. For example: http://lb.example.com:80
Site Name: Unique two-digit site identifier (site ID). For example: 10
When you are finished, click OK.
After adding the load balancer to the Site Name, click Save. The entry for the load balancer now includes the site ID. For example: http://lb.example.com:80|10
The site ID must be unique with respect to server IDs and other site IDs. For example, you cannot use 01 for both a site ID and a server ID.
On the same Console panel, map the load balancer to each Access Manager instance:
In the Server list under Instance Name, click each instance name to display the Edit Server Instance panel for the instance.
Map the Site Name (site ID) for the load balancer to the Access Manager instance. For example, using a load balancer with a Site Name of 10, for the first server, the Instance Name would 01|10.
Click OK and repeat the steps for the other Access Manager instances.
When you are finished, all Access Manager instances should be mapped to the load balancer. For example:
http://amserver1.example.com:8080|01|10 http://amserver2.example.com:8080|02|10 http://amserver3.example.com:8080|03|10
Click Save to save the configuration.
Add the Realm/DNS alias for the load balancer:
For clients such as a policy agent, the load balancer (as opposed to the individual Access Manager instances) should be the sole entry point. For example, if you are using a policy agent, modify the appropriate entries in the AMAgent.properties file to point to the load balancer.
The following procedure refers to the Access Manager 7.1 Console in Legacy Mode.
Log in to the Access Manager Legacy Console as amadmin on the first Access Manager host server.
Add each additional instance to the Platform Server List:
Add each additional instance to the DNS Alias List:
When Access Manager servers are deployed behind a load balancer, cookie-based sticky request routing prevents a client request from being misrouted to an incorrect Access Manager server (that is, to a server that is not hosting the session).
In the previous behavior, without cookie-based sticky request routing, requests from non-browser based clients (such as policy agents and clients using the remote Access Manager client SDK) were often misrouted to an Access Manager server that was not hosting the session. Then, in order to send the request to the correct server, the Access Manager server had to validate the session using back-channel communication, which usually caused some performance degradation.
Cookie-based sticky request routing prevents the need for this back-channel communication and thus improves Access Manager performance.
The Access Manager deployment must be configured as a site. For information, see 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.
To specify a cookie name, set the com.iplanet.am.lbcookie.name property in the AMConfig.properties file.
Access Manager then generates the load balancer cookie value using the two-byte server ID (such as 01, 02, and 03). If you do not specific a cookie name, Access Manager generates the load balancer cookie value using the default name amlbcookie plus the two-byte server ID.
If you set the cookie name on the Access Manager server, you must use the same name in the AMAgent.properties file for a Policy Agent. Also, if you are using the Access Manager client SDK, you must also use the same cookie name used by the Access Manager server.
Note: Do not set the com.iplanet.am.lbcookie.value property, because Access Manager sets the cookie value using the two-byte server ID.
Configure the load balancer with the cookie name from Step 1.
You can use a hardware or software load balancer with your Access Manager deployment. For information about configuring the BIG-IP® load balancer manufactured by F5 Networks, see Deployment Example 1: Access Manager 7.1 Load Balancing, Distributed Authentication UI, and Session Failover.
If session failover is implemented, enable the com.sun.identity.session.resetLBCookie property for both Policy Agents and the Access Manager server. For example:
com.sun.identity.session.resetLBCookie='true'
For a Policy Agent, add and enable the property in the AMAgent.properties file.
For the Access Manager server, add and enable the property in the AMConfig.properties file.
If a failover situation occurs, the session is routed to a secondary Access Manager server, and the load balancer cookie value is set using the server ID for the secondary Access Manager server. Any subsequent requests for the session are routed to the secondary Access Manager server.
Before you configure a load balancer to handle SSL requests, first configure SSL for the Access Manager web container. For information, see Chapter 8, Configuring Access Manager in SSL Mode.
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.
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.
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.
Log in as or become superuser (root}.
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
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.
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.1 Federation and SAML Administration Guide.
Click Save to save your changes.
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 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.1 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.1 Console. For example:
http://loadbalancer.example.com:80/amserver/console