test

Sun Java System Access Manager 7.1 Postinstallation Guide

Chapter 4 Configuring Access Manager With a Load Balancer

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:

Configuring an Access Manager Deployment as a Site

An Access Manager deployment configured as a site allows centralized configuration management for the entire deployment.

Requirements for an Access Manager Site

An Access Manager site includes the following components:

Figure 4–1 Access Manager Site

Access Manager site

Access Manager Site Configuration

If you have an Access Manager multiple server deployment, use either of these methods to configure your deployment as a site:

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.

ProcedureTo Configure Access Manager as a Site in Realm Mode

The following procedure refers to the Access Manager 7.1 Console in Realm Mode.

  1. Log in to the Access Manager Console as amAdmin.

  2. Add the load balancer URL to the Site Name:

    1. In the Access Manager Console, click Configuration, System Properties, and then Platform.

    2. 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.

    3. 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.

  3. On the same Console panel, map the load balancer to each Access Manager instance:

    1. In the Server list under Instance Name, click each instance name to display the Edit Server Instance panel for the instance.

    2. 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.

    3. 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

    4. Click Save to save the configuration.

  4. Add the Realm/DNS alias for the load balancer:

    1. In the Access Manager Console, click Access Control and then the root or top-level realm under Realm Name.

    2. Under Realm Attributes, add the load balancer to Realm/DNS Aliases and then click Add. For example: lb.example.com.

    3. Click Save to save your changes.

  5. 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.

ProcedureTo Configure Access Manager as a Site in Legacy Mode

The following procedure refers to the Access Manager 7.1 Console in Legacy Mode.

  1. Log in to the Access Manager Legacy Console as amadmin on the first Access Manager host server.

  2. Add each additional instance to the Platform Server List:

    1. Click Service Configuration.

    2. In the left pane, click the Platform link.

    3. Under the Server List, add each additional host server.

      For example:

      http://amserver2.example.com:58080|02
http://amserver3.example.com:58080|03

    4. After you have added all instances, click Save.

  3. Add each additional instance to the DNS Alias List:

    1. Click Identity Management.

    2. Make sure that View: Organizations is selected in the left pane.

    3. In the DNS Alias Name field in the right pane, add each additional host server name.

      For example:

      amserver2.example.com
amserver3.example.com

    4. After you have added all instances, click Save.

Configuring Cookie-Based Sticky Request Routing

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.

ProcedureTo Configure Cookie-Based Sticky Request Routing

Before You Begin

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.

  1. 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.

  2. 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.

  3. 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.

Configuring SSL Termination for a Load Balancer

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:

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:

To solve these problems, Access Manager provides these properties:

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.

ProcedureTo Generate a CSR with the SubjectAltName Extension

  1. Log in as or become superuser (root}.

  2. 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

  3. 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...

  4. 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.

  5. 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 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.

ProcedureTo Configure a Load Balancer with SAML

  1. 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.

  2. Log in to the Access Manager Console as amadmin.

  3. In the Access Manager Console, click Federation and then SAML.

  4. 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.

  5. 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:

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:

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

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