During the implementation phase of the solution life cycle, you implement various solutions for your deployment. This chapter describes the following implementation scenarios for Sun JavaTM System Access Manager:
Installing Access Manager instances on multiple host servers, with each instance accessing the same Directory Server, includes these steps:
To install Access Manager instances on multiple host servers, with each instance accessing the same Directory Server, follow these steps.
Install Access Manager on a host server by running the Java Enterprise System (Java ES) installer. When you run the installer, specify either the Configure Now or Configure Later option. For information about running the installer, see the Sun Java Enterprise System 2005Q4 Installation Guide for UNIX.
When you run the installer, you can also install Web Server or Application Server as the Access Manager web container. To use BEA WebLogic Server or IBM WebSphere Application Server as the web container, you must first install the product before you run the run the amconfig script in the following steps. For installation instructions, see the respective BEA or IBM product documentation.
If you specified the Configure Later option during installation or if you need to reconfigure the Access Manager instance (for example, to use BEA WebLogic Server or IBM WebSphere Application Server as the web container), you must run the amconfig script. The amconfig script and the amsamplesilent configuration file are located in the AccessManager-base/bin directory, where AccessManager-base represents the default installation directory: /opt/SUNWam on Solaris systems and /opt/sun/identity on Linux systems.
Run the amconfig script as follows:
Copy the amsamplesilent file to a writable directory and make that directory your current directory. For example, you might create a directory named /newinstances.
Rename the copy of the amsamplesilent file to describe the new instance you want to configure. For example, if you plan to create a new Access Manager instance for Web Server 6.1, you might rename the file to amwebsvr6.
Set the variables in the amwebsvr6 file to configure the new instance. For example, to configure Access Manager in Realm mode:
AM_REALM=true DEPLOY_LEVEL=1 NEW_INSTANCE=true WEB_CONTAINER=WS6 # Web Server is the web container DIRECTORY_MODE=1 ...
In case you might need to reconfigure or uninstall this instance later, save the new amwebsvr6 file.
Run the amconfig script, specifying the new amwebsvr6 file as the silent configuration input file. For example, on Solaris systems with Access Manger installed in the default directory:
# cd /opt/SUNWam/bin/ # ./amconfig -s ./newinstances/amwebsvr6 |
Run amconfig with full path to the amsamplesilent file (or copy of the file). The script reads the variables in the amwebsvr6 file and then runs in silent mode (-s option) to configure Access manager for the web container. For more information about the amsamplesilent file and running the amconfig script, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.
Repeat these steps on the other host servers to deploy additional Access Manager instances.
Several considerations for deploying additional Access Manager instances are:
If you are running the Java ES installer and you want to use the same Directory Server as the first instance, check ”Yes” for “Is Directory Server provisioned with user data?”.
If you are running the amconfig script, set variables in the copy of the amsamplesilent file. For example, to deploy Access Manager in Realm mode:
AM_REALM=true DEPLOY_LEVEL=1 NEW_INSTANCE=true WEB_CONTAINER=WS6 # Web Server is the web container DIRECTORY_MODE=4 # Directory Server is provisioned with user data AM_ENC_PW=password-encryption-key-value-from-the-first=instance ...
If you are using non-default naming attributes and object classes, specify the custom values as appropriate for the user naming and organization naming attributes and object classes. Also, all deploy URIs (SERVER_DEPLOY_URI, CONSOLE_DEPLOY_URI, PASSWORD_DEPLOY_URI, and COMMON_DEPLOY_URI) for the web applications must match the previous installation.
Use the same password encryption key as the first instance, as described in following Caution.
In a multiple server deployment that shares the same Directory Server, all Access Manager instances must use the same value for the password encryption key.
If you run the Java ES installer to install Access Manager on subsequent (second, third, and so on) servers in a multiple server deployment, the installer generates a new random password encryption key for each server. Therefore, when you run the installer on a subsequent server, use the encryption key value from the first Access Manager instance, which you can copy from the am.encryption.pwd attribute in the AMConfig.properties file and set as follows:
Configure Now option. Replace the new random encryption key generated by the installer with the encryption key value from the first instance.
Configure Later option. Set the AM_ENC_PWD variable in the copy of the amsamplesilent file with the encryption key value from the first instance before you run the amconfig script.
However, if you need to change the password encryption key for an Access Manager instance, see Appendix B, Changing the Password Encryption Key.
When you install multiple instances of Access Manager on different host servers, the additional instances are not added to the platform server list or the realm/DNS aliases. You must explicitly add the values for the additional Access Manager instances, as follows:
Log in to the Access Manager 7 2005Q4 Console as amadmin on the first Access Manager host server.
In the Access Manager Console, click Configuration, System Properties, and then Platform.
Add each additional Access Manager instance to the Platform Server List under Instance Name:
Add the Realm/DNS alias for each additional Access Manager instance:
In the Access Manager Console, click Access Control and then the root (top-level) realm under Realm Name.
Under Realm Attributes, add the Access Manager instance to Realm/DNS Aliases and then click Add. For example: amserver2.example.com
After you have added all instances, click Save.
Access Manager 7 2005Q4 introduces the “site concept,” which provides centralized configuration management for an Access Manager deployment. When Access Manager is configured as a site, client requests always go through the load balancer, which simplifies the deployment as well as resolves issues such as a firewall between the client and the back-end Access Manager servers. A site includes the following components:
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.
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.
All Access Manager instances access the same Directory Server.
The following procedures refer to the Access Manager 7 2005Q4 Console in Realm Mode.
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 Implementing Access Manager Session Failover.
If you don't plan to implement session failover, follow the steps in this section.
When you configure a deployment as a site, you perform these functions in the Access Manager Console:
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.
To configure an Access Manager deployment as a site, follow this procedure:
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:
In the Access Manager Console, click Access Control and then the root or top-level realm under Realm Name.
Under Realm Attributes, add the load balancer to Realm/DNS Aliases and then click Add. For example: lb.example.com.
Click Save to save your changes.
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 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:
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.
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.
To generate a CSR with the SubjectAltName extension, follow these steps:
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
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.
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.
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 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
Access Manager provides a web container independent session failover implementation using Sun Java System Message Queue (Message Queue) as the communications broker and the Berkeley DB by Sleepycat Software, Inc. as the session store database. Access Manager 7 2005Q4 enhancements includes the amsfoconfig script to configure the session failover environment and the amsfo script to start and stop the Message Queue broker and Berkeley DB client.
This section covers these topics:
The following figure shows an Access Manager session failover deployment scenario that includes these components:
Three Access Manager instances, running on different host servers on supported web containers. All Access Manager instances access the same Directory Server (not shown in the figure).
Message Queue brokers, running in cluster mode on different servers.
Berkeley DB client (amsessiondb), running on the same servers as the Message Queue brokers.
Load balancer to improve performance and security.
Client requests can originate from a Web browser, C or Java application using the Access Manager SDK, or a J2EE/Web agent.
The following table describes how to install the components required for Access Manager session failover.
Table 6–1 Installation of Access Manager Session Failover Components
Component |
How to install ... |
---|---|
Access Manager |
Install the first instance of Access Manager on each host server using the Java ES Installer. The installer adds the required session failover Solaris packages or Linux RPMs. Reference: Sun Java Enterprise System 2005Q4 Installation Guide for UNIX When you install Access Manager using the Java ES installer, you can select either Realm Mode (version 7.x) or Legacy Mode (version 6.x). Access Manager session failover is supported in both modes. After you run the Java ES installer, run the amconfig script to:
For information, see Installing Access Manager on Multiple Host Servers. |
Message Queue |
Install Message Queue using the Java ES installer. Reference: Sun Java Enterprise System 2005Q4 Installation Guide for UNIX |
Berkeley DB Client (Access Manager subcomponent) |
The Java ES installer and amconfig script adds the Access Manager packages or RPMs required for the Berkeley DB client. However, if you want to install the Berkeley DB client on a server where you have not installed Access Manager, you must manually add the following packages or RPMs, depending on your operating system. For the Solaris OS, add the following packages using the pkgadd command: SUNWamsfodb, SUNWbdb, and SUNWbdbj. Reference: Solaris documentation For the Linux OS, add the following RPMs using the rpm command: sun-identity-sfodb, sun-berkeleydatabase-core, and sun-berkeleydatabase-java. Reference: Linux online man pages. |
In a multiple server deployment that shares the same Directory Server, all instances of Access Manager must use the same password encryption key value. When you install the first Access Manager instance, save the password encryption key value from the am.encryption.pwd property in the AMConfig.properties file. Then, when you run the Java ES installer or amconfig script to deploy Access Manager instances on other host servers, use this same value for the password encryption key.
To configure Access Manager for session failover, follow these steps:
Each step is described in detail in the following sections.
To determine if session failover is enabled for a deployment, change the com.iplanet.services.debug.level property from error to message in the AMConfig.properties file. Then, check the amSession logs in the /var/opt/SUNWam/debug directory on Solaris systems or the /var/opt/sun/identity/debug directory on Linux systems.
On each host server that is running an Access Manager instance, disable cookie encoding:
If Web Server is the web container, make sure the following property in the AMConfig.properties file is set to false (which is the default value set by the Java ES installer):
com.iplanet.am.cookie.encode=false
In the sun-web.xml file, set the encodeCookies property to false. For example:
<sun-web-app> <property name="encodeCookies" value="false"/> ... </sun-web-app>
If Application Server, BEA WebLogic, or IBM WebSphere Application Server is the web container, set the following property in the AMConfig.properties file to false:
com.iplanet.am.cookie.encode=false
The Access Manager client should not do any cookie encoding or decoding. A remote SDK client must be in sync with the Access Manager server side settings, either in the AMConfig.properties file or the web container’s sun-web.xml file.
On each host server that is running an Access Manager instance, add the installed locations of imq.jar and jms.jar in the server.xml (or equivalent) configuration file for the Access Manager web container. For example, on Solaris systems:
<JAVA javahome="/usr/jdk/entsys-j2se" serverclasspath= "/usr/share/lib/imq.jar:/usr/share/lib/jms.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-rt.jar: ${java.home}/lib/tools.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-ext.jar: /opt/SUNWwbsvr/bin/https/jar/webserv-jstl.jar: /usr/share/lib/ktsearch.jar"
If you don’t want to use the guest user as the Message Queue user name and password, add a new user and password to connect to the Message Queue broker on servers where Message Queue is installed. For example, on Solaris systems, to add a new user named amsvrusr:
# /usr/bin/imqusermgr add -u amsvrusr -p password
Then, make the guest user inactive by issuing the following command:
# /usr/bin/imqusermgr update -u guest -a false
The amsessiondb script is called by the amsfo script to start the Berkeley DB client (amsessiondb), create the database, and set specific database values. The script contains variables that specify various default paths and directories:
JAVA_HOME=/usr/jdk/entsys-j2se/ IMQ_JAR_PATH=/usr/share/lib JMS_JAR_PATH=/usr/share/lib BDB_JAR_PATH=/usr/share/db.jar BDB_SO_PATH=/usr/lib AM_HOME=/opt/SUNWam
If any of these components are not installed in their default directories, edit the amsessiondb script and set the variables, as needed, to the correct locations.
Access Manager 7 2005Q4 provides the amsfoconfig script to configure an Access Manager deployment for session failover.
To run the amsfoconfig script, an Access Manager deployment must meet the following requirements:
Two or more Access Manager instances must be installed and configured in the deployment, but the deployment cannot be configured as a site. If the amsfoconfig script determines that the deployment is configured as a site or that any of the server entries in the platform server list are site enabled, the script displays a message and exits. To configure session failover manually, see Configuring Session Failover Manually
The Java Message Queue (MQ) broker must be installed and configured on at least two servers in the deployment.
The Berkeley DB client and database must be installed and configured in the deployment.
Directory Server must be running, accessible to the script, and configured with Access Manager data.
The amsfoconfig script reads the amsfo.conf configuration file and then configures an Access Manager deployment for session failover by performing these functions:
Configures a new site. The script uses the Access Manager instances in the platform server list and the load balancer information from the amsfo.conf file to create a new site for the Access Manager session failover deployment. The script modifies the existing platform server list, so that after the site is configured, all server entries under the platform server list then belong to the site.
For example, http://server1.example.com:80|01 changes to http://server1.example.com:80|01|10, if the default value of 10 is used as the SiteID.
Modifies the existing Realm/DNS alias list. The script appends the host name of the load balancer to the list. This host name is obtained from the lbServerHost variable of the amsfo.conf file.
Loads session failover configuration XML into Directory Server. The script dynamically generates the session configuration XML file based on the configuration information and loads the generated XML into Directory Server. This information corresponds to the Secondary Configuration Instance under Session in the Access Manager Console.
The following table lists the Access Manager session failover scripts and configuration files.
Table 6–2 Access Manager Session Failover Scripts and Configuration Files
Name |
Description and Location |
---|---|
amsofconfig |
Script to configure Access Manager for session failover. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfo |
Script to start and stop the Message Queue broker and amsessiondb client. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfopasswd |
Script to generate the encrypted Message Queue broker user password. Solaris systems: AccessManager-base/SUNWam/bin Linux systems: AccessManager-base/identity/bin |
amsfo.conf |
Session failover configuration file. Solaris systems: AccessManager-base/SUNWam/lib Linux systems: AccessManager-base/sun/identity/lib |
amProfile.conf |
Session failover environment file. Solaris systems: etc/opt/SUNWam/config Linux systems: etc/opt/sun/identity/config |
AccessManager-base represents the base installation directory for Access Manager. The default values are: Solaris systems: /opt Linux systems: /opt/sun |
To run the amsfoconfig script to configure Access Manager for session failover, follow these steps.
Log in as or become superuser (root).
Set the variables in the amsfo.conf file, as described in Table 6–3.
Run the script. For example, on a Solaris system with Access Manager installed in the default directory:
# cd /opt/SUNWam/bin # ./amsfoconfig
The script displays status information as it runs.
When the amsfoconfig script prompts you, enter the following passwords:
Access Manager administrator (amAdmin) password
Message Queue broker user password
To check the results, see the /var/tmp/amsfoconfig.log file.
The following table describes the variables in the amsfo.conf file that are used by the amsfoconfig script. Set these variables as needed for your deployment before you run the amsfoconfig script.
Table 6–3 Variables in the amsfo.conf File Used by the amsfoconfig Script
Variable |
Description |
---|---|
CLUSTER_LIST |
Message Queue broker list participating in the cluster. The format is: host1:port,host2:port,host3:port For example: jmq1.example.com:7777,jmq2.example.com:7777,jmq3.example.com:7777 There is no default. |
lbServerPort |
Port for the load balancer. The default is 80. |
lbServerProtocol |
Protocol (http or https) used to access the load balancer. The default is http. |
lbServerHost |
Name of the load balancer. For example: lbhost.example.com |
SiteID |
Identifier for the new site (and the load balancer) that the amsfoconfig script will create. SiteID can be any value greater than the Server IDs that already exist in the platform server list. The default is 10. |
The following example shows a sample run of the amsfoconfig script.
Welcome to Sun Java System Access Manager 7 2005Q4 Session Failover Configuration Setup script. ========================================================= ========================================================= Checking if the required files are present... ========================================================= Running with the following Settings. ------------------------------------------------- Environment file: /etc/opt/SUNWam/config/amProfile.conf Resource file: /opt/SUNWam/lib/amsfo.conf ------------------------------------------------- Using /opt/SUNWam/bin/amadmin Validating configuration information. Done... Please enter the LDAP Admin password: (nothing will be echoed): password1 Verify: password1 Please enter the JMQ Broker User password: (nothing will be echoed): password2 Verify: password2 Retrieving Platform Server list... Validating server entries. Done... Retrieving Site list... Validating site entries. Done... Validating host: http://amhost1.example.com:7001|02 Validating host: http://amhost2.example.com:7001|01 Done... Creating Platform Server XML File... Platform Server XML File created successfully. Creating Session Configuration XML File... Session Configuration XML File created successfully. Creating Organization Alias XML File... Organization Alias XML File created successfully. Loading Session Configuration schema File... Session Configuration schema loaded successfully. Loading Platform Server List File... Platform Server List server entries loaded successfully. Loading Organization Alias List File... Organization Alias List loaded successfully. Please refer to the log file /var/tmp/amsfoconfig.log for additional information. ############################################################### Session Failover Setup Script. Execution end time 10/05/05 13:34:44 ###############################################################
Access Manager 7 2005Q4 provides the amsfo script to perform these functions:
Start and stop the Java Message Queue (MQ) broker specified for the session failover deployment.
Start and stop the amsessiondb client specified for the session failover deployment.
Read the amsfo.conf configuration file and take specific actions based on variables in the file. For example, you can have the script first delete and then recreate the Berkeley DB database.
Write the amsessiondb.log, jmq.pid, and amdb.pid files in the /tmp/amsession/logs/ directory. The default log directory is determined by the LOG_DIR variable in the amsfo.conf file.
To start the Access Manager session failover components, follow this sequence:
Set the variables in the in the amsfo.conf configuration file, as required by your deployment. For a description of these variables, see Table 6–4
Run the amsfo script to start the Java Message Queue (MQ) broker and the amsessiondb client. For detailed information, see Running the amsfo Script.
Start each Access Manager instance by starting the respective web container. For information, see the Sun Java System Access Manager 7 2005Q4 Administration Guide.
The amsfo script includes the start and stop options:
Usage: amsfo { start | stop }
To run the amsfo script, follow these steps:
Log in as or become superuser (root).
Set the variables in the amsfo.conf file, as required for your deployment. For a description of these variables, see Table 6–4.
Run the script. For example, to start the session failover components on a Solaris system with Access Manager installed in the default directory:
# cd /opt/SUNWam/bin # ./amsfo start
To check the results of the script, see the /tmp/amsession/logs/amsessiondb.log file.
The following table describes the variables in the amsfo.conf configuration file. Set these variables as needed for your deployment before you run the amsfo script.
Table 6–4 amsfo.conf Configuration File
Variable |
Description |
---|---|
AM_HOME_DIR |
Access Manager default installation directory. The default directory depends on the platform: Solaris systems: AccessManager-base/SUNWam Linux systems: AccessManager-base/identity AccessManager-base represents the base installation directory for Access Manager. The default values are /opt on Solaris systems and /opt/sun on Linux systems. |
AM_SFO_RESTART |
Specifies (true or false) whether the script should automatically restart the amsessiondb client. The default is true (restart the amsessiondb client). |
CLUSTER_LIST |
Message Queue broker list participating in the cluster. The format is: host1:port,host2:port,host3:port For example: jmq1.example.com:7777,jmq2.example.com:7777,jmq3.example.com:7777 There is no default. |
DATABASE_DIR |
Directory where the session database files will be created. The default is "/tmp/amsession/sessiondb". |
DELETE_DATABASE |
Specifies (true or false) whether the script should delete and then create a new database when the amsessiondb process is restarted. The default is true. |
LOG_DIR |
Location of the log directory. The default is "/tmp/amsession/logs". |
START_BROKER |
Specifies (true or false) whether the Message Queue broker should be started with the amsessiondb process. Set this variable as follows: true - The Message Queue broker will run on the same machine as the amsessiondb process. false - The Message Queue broker and the amsessiondb process will run on different machines. The default is true. |
BROKER_INSTANCE_NAME |
Name of the Message Queue broker instance to start. The default is aminstance. |
BROKER_PORT |
Port for the local Message Queue broker instance. The default is 7777. |
BROKER_VM_ARGS |
Java VM arguments. The default is "-Xms256m -Xmx512m", which sets the maximum value based on the system resources. |
USER_NAME |
User name used to connect to the Message Queue broker. The default is guest. If you specified a different user name under step 3–Add a New User in the Message Queue Server, set USER_NAME to that name. |
PASSWORDFILE |
Location of the password file that contains the encrypted password used to connect to the Message Queue broker. To generate the encrypted password, use the amsfopasswd script, as described in amsfopasswd Script The default is $AM_HOME_DIR/.password, where $AM_HOME_DIR specifies the Access Manager default installation directory. |
The amsfopasswd script accepts the Message Queue broker password in clear text and returns the encrypted password in a file. You can then use this file as input to the amsfo script (PASSWORDFILE variable).
The amsfopasswd script is located in the following directory:
Solaris systems: AccessManager-base/SUNWam/bin
Linux systems: AccessManager-base/identity/bin
The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.
Use the following syntax to run the amsfopasswd script.
amsfopasswd -f filename | --passwordfile filename -e password | --encrypt password amsfopasswd -h | --help
The following table describes the amsfopasswd script arguments.
Table 6–5 amsfopasswd Script Arguments
Argument |
Description |
---|---|
-f filename | --passwordfile filename |
Path to the destination file where amsfopasswd stores the encrypted password. |
-e password | --encrypt password |
Clear text password that amsfopasswd encrypts. |
-h | --help |
Display the amsfopasswd command usage and then exit. |
The following example shows the amsfopasswd script. The encrypted password is stored in the /opt/SUNWam/.password file.
# ./amsfopasswd -f /opt/SUNWam/.password -e mypassword
In some situations, you might need to manually configure Access Manager for session failover. For example, you do not plan to run the amsfoconfig script. Or, the amsfoconfig script exited with one of the following messages before finishing the configuration: “Site is already configured” or “Server entry is already site configured”.
These steps describe how to manually configure Access Manager for session failover:
3–Create a New Secondary Configuration Instance for the Load Balancer
4–Perform Session Failover Miscellaneous Configuration Tasks
These steps are equivalent to the previous steps that described how to install the required components, configure session failover using the amsfoconfig script and then start the various components.
Install all components in the deployment, including Access Manager instances, load balancer, Message Queue, and the Berkeley DB client. For more information, see Installing the Session Failover Components.
If you do not plan to run the amsfoconfig script, which configures multiple Access Manager instances and a load balancer as a site, you must configure the deployment, as described in Configuring an Access Manager Deployment as a Site.
To create a new secondary configuration instance for your load balancer, follow these steps:
Log in to the Access Manager 7 2005Q4 Console as amAdmin.
Click Configuration, Global Properties, Session, and then Secondary Configuration Instance.
c. Click New, and add the following values:
Name. Load balancer URL. For example: http://lb.example.com:80
Session Store User. Name you are using to connect to the Message Queue Server (if other than guest).
Session Store Password. Password for the Session Store User.
Maximum Wait Time. 5000 (Use the default unless you require another value).
Database Url: Message Queue broker address list. For example:
mqsvr1.example.com:7777,mqsvr2.example.com:7777,mqsvr3.example.com:7777
The default Message Queue port is 7676. If you are using Application Server as the web container, however, consider using another port, because port 7676 might already be in use by Application Server. For the range of the valid port numbers, refer to the Message Queue documentation.
Click Add to save your changes.
Perform the following tasks (which are the same as if you are running the amsfoconfig script):
Run the amsfo script to start the Message Queue broker and Berkeley DB client (amsessiondb). Then, start each Access Manager instance by starting the respective web container. See Starting the Session Failover Components.
The amsessiondb script is called by the amsfo script to start the Berkeley DB client (amsessiondb), create the database, and set specific database values.
The recommended method to start and stop the Access Manager session failover components is to run the amsfo script and let it call the amsessiondb script. The following information is included only in case you might need to run the amsessiondb script independently.
Before you run the amsessiondb script, make sure you have the paths set correctly, as described under 4–Edit the amsessiondb Script (if Needed).
When you run the amsessiondb script, you can enter the Message Queue broker password on the command line as clear text (-w or --password option). However, if you prefer to use an encrypted password in a file (-f or --passwordfile option), first run the amsfopasswd script to encrypt the Message Queue broker clear text password to a file. Then run the amsessiondb script, using this file for the -f or --passwordfile option.
Use the following syntax to run the amsessiondb script.
amsessiondb [ -u username | --username username ] [ -w password | --password password | -f filename | --passwordfile filename ] [ -c cachesize | --cachesize cachesize ] [ -b dbdirectory | --dbdirectory dbdirectory ] -a MQServerAddressList | --clusteraddress MQServerAddressList [ -s numcleanexpiredsessions | --numcleansessions numcleanexpiredsessions ] [ -v | --verbose ] [ -i statsinterval | --statsInterval statsinterval ] amsessiondb -h | --help amsessiondb -n | --version
The following table describes the amsessiondb script arguments.
Table 6–6 amsessiondb Script Arguments
Argument |
Description |
---|---|
-u username | --username username |
User name to connect to the Message Queue broker. Specify the user you specified under 3–Add a New User in the Message Queue Server. Default is “guest”. |
-w password | --password password |
Clear text password for the user name used to connect to the Message Queue broker. Specify the password you specified under 3–Add a New User in the Message Queue Server. Default is “guest”. |
-f filename | --passwordfile filename |
File that contains the encrypted password for accessing the Message Queue broker. Note If you specify this option, do not specify the -w or --password option. |
-c cachesize | --cachesize cachesize |
Cache size in MB. Default is 8 MB. |
-b dbdirectory | --dbdirectory dbdirectory |
Base directory where the Berkeley DB database (amsessions.db) is created. Default is “sessiondb”, created in the directory where you are running the amsessiondb script. Note To ensure that you have sufficient disk space where you are creating the database, allow 1 GB for each 100,000 sessions. |
-a MQServerAddressList | --clusteraddress MQServerAddressList |
Message Queue broker address list, in the format: host1:port[,host2:port,host3:port,...] For example: mqsvr1:7777,mqsvr2:7777 |
-s numcleanexpiredsessions | --numcleansessions numcleanexpiredsessions |
Number of expired sessions to be deleted for each cleanup interval. Default is 1000. |
-v | --verbose |
Run in verbose mode. Results are sent to the standard output. Default is non-verbose mode. |
-i statsinterval | --statsInterval statsinterval |
Interval in seconds to print the statistics for total requests, reads, writes, and deletes to the standard output. Default is 60 seconds. |
-h | --help |
Display amsessiondb command usage and then exit. |
-n | --version |
Return the version of Access Manager currently installed and then exit. |
The following example shows the amsessiondb script.
amsessiondb -u amsvrusr -f pwfile -c 128 -b sessiondb -a host1:7777,host2:7777
Performance tests with the amsessiondb client include this criteria:
The approximate number of operations on the Berkeley DB was two times the number of authentications per second.
Tests were conducted with the following configuration:
Write data – 3 Kbytes
Duration – 1 minute
Berkeley DB cache size – 28 Mbytes (default cache size in Access Manager 7 2005Q4 is 32 Mbytes)
The following table shows the results of the tests.
Table 6–7 Performance Tests With the amsessiondb Client
Disk |
Notes |
---|---|
Normal IDE disk: 666 writes per second |
Each site can support up to 300 authentications per second. Therefore, IDE disks are not recommended. |
Normal 10K RPM SCSI disk on Sun Blade server: 1520 writes per second |
Each site can support up to 750 authentications per second. |
Seagate Cheetah 15K RPM SCSI disk: 1860 writes per second |
Each site can support up to 900 authentications per second. |
Sun T-300 disk array: 2700 writes per second |
Each site can support up to 1300 authentications per second. |
Disk using swap space in /tmp: 3300 writes per second |
Each site can support up to 1600 authentications per second. |
Access Manager 7 2005Q4 includes the new session quota constraints feature, which allows Access Manager to limit users to a specific number of active, concurrent sessions based on configurable attributes. An Access Manager administrator can set session quota constraints at the following levels:
Globally. Constraints apply to all users.
To an entity (organization or realm, role, or user). Constraints apply only to the specific users that belong to the entity.
The following Access Manager deployments support session quota constraints:
Access Manager Single Server Deployment
In this scenario, Access Manager is deployed on a single host server. Access Manager maintains the active session counts in memory for all logged in users. When a user attempts to log in to the server, Access Manager checks whether the number of the valid sessions for the user exceeds the session quota and then takes action based on the configured session quota constraints options.
Access Manager Session Failover Deployment
In this scenario, multiple instances of Access Manager are deployed on different host servers in a session failover configuration. The Access Manager instances are configured for session failover using Sun Java System Message Queue (Message Queue) as the communications broker and the Berkeley DB by Sleepycat Software, Inc. as the session store database. For more information about Access Manager session failover, see Implementing Access Manager Session Failover.
In a session failover deployment, when a user attempts to log in, the Access Manager server receiving the session creation request first retrieves the session quota for the user from the Access Manager identity repository. Then, the Access Manager server fetches the session count for the user directly from the centralized session repository (accumulating all the sessions from all the Access Manager servers within the same site) and checks whether the session quota has been exhausted. If the session quota has been exhausted for the user, the Access Manager server takes action based on the configured session quota constraints options.
If session constraints are enabled in a session failover deployment and the session repository is not available, users (except superuser) are not allowed to log in.
In a session failover deployment, if an Access Manager instance is down, all the valid sessions previously hosted by that instance are still considered to be valid and are counted when the server determines the actual active session count for a given user. An Access Manager multiple server deployment that is not configured for session failover does not support session quota constraints.
To configure session quota constraints, the top-level Access Manager administrator (such as amAdmin) must set the following attributes in the Access Manager Console for one of the Access Manager instances. If you reset any of these attributes, you must restart the server for the new value to take effect.
Enable Quota Constraints is a global attribute that enables or disables the session quota constraints feature. If this attribute is enabled, Access Manager enforces session quota constraints whenever a user attempts to logs in via a new client (and thus create a new session).
The default is disabled (OFF).
Read Timeout for Quota Constraint defines the time in milliseconds that an inquiry to the session repository for the active user session counts continues before timing out. If the maximum wait time is reached due to the unavailability of the session repository, the session creation request is rejected.
The default is 6000 milliseconds.
Resulting Behavior If Session Quota Exhausted determines the behavior if a user exhausts the session constraint quota. This attribute takes effect only if the “Enable Quota Constraints” attribute is enabled. Values can be:
DENY_ACCESS. Access Manager rejects the login request for a new session.
DESTROY_OLD_SESSION. Access Manager destroys the next expiring existing session for the same user and allows the new login request to succeed.
The default is DESTROY_OLD_SESSION.
Exempt Top-Level Admins From Constraint Checking specifies whether session constraint quotas apply to the administrators who have the Top-level Admin Role. This attribute takes effect only if the “Enable Quota Constraints” attribute is enabled.
The default is NO.
The super user defined for Access Manager in the AMConfig.properties file (com.sun.identity.authentication.super.user) is always exempt from session quota constraint checking.
Active User Sessions defines the maximum number of concurrent sessions for a user. Access Manager includes both a dynamic attribute and a user attribute, with same attribute name.
The default is 5.
If a user has multiple settings for session quotas at different levels, Access Manager follows this precedence to determine the actual quota for the user:
user (highest)
role/organization/realm (based on the conflict resolution levels)
global (lowest)
For example, Ken is a member of both the marketing and management roles. Session quotas are defined as follows (all have the same conflict resolution level):
organization - 1
marketing role - 2
management role - 4
user Ken - 3
Ken's quota is 3.
For more information about the session quota constraints attributes, see the Access Manager Console online help.
The session property change notification feature causes Access Manager to send a notification to all registered listeners when a change occurs on a specific session property. This feature takes effect when the “Enable Property Change Notifications” attribute is enabled (ON) in the Access Manager Console.
For example, in a single sign-on (SSO) environment, one Access Manager session can be shared by multiple applications. When a change occurs on a specific session property defined in the “Notification Properties” list, Access Manager sends a notification to all registered listeners.
All client applications participating in the SSO automatically get the session notification if they are configured in the notification mode. The client cached sessions are automatically updated based on the new session state (including the change of any session property, if there is any). An application that wants to take a specific action based on a session notification can write an implementation of the SSOTokenListener interface and then register the implementation through the SSOToken.addSSOTokenListener method. For more information, see the Sun Java System Access Manager 7 2005Q4 Developer’s Guide.
To configure session property change notifications, follow these steps:
Log in to Access Manager Console as amAdmin.
Click the Configuration tab.
Under Global Properties, click Session.
Set “Enable Property Change Notifications” to ON.
In the “Notification Properties” list, add each property for which you want a notification sent when the property is changed.
When you have finished adding properties to the list, click Save.
After you install Access Manager, you can tune your deployment for optimum performance using the amtune and related scripts. These scripts allow you to tune Access Manager, the SolarisTM Operating System (OS), the web container, and Directory Server.
The Java Enterprise System installer installs the tuning scripts and related files in the bin/amtune directory.
The amtune script is not interactive. Before you run amtune, you must edit the parameters in the amtune-env configuration file to specify the tuning you want amtune to perform for your specific environment. The amtune-env configuration file includes two major sections:
Performance related parameters that you set to control the tuning.
An internal section that is maintained by Access Manager engineering and should not be modified.
You can run the amtune script in two modes:
Review mode: amtune reports tuning recommendations but does not make any actual changes to your environment.
Change mode: amtune makes actual changes, except for Directory Server, depending on parameters in the amtune-env configuration file.
The amtune script does not automatically tune Directory Server. Most deployments have applications other than Access Manager that also access Directory Server, so you don’t want to make tuning changes without considering how they would affect your other applications.
Before you tune Directory Server, first back up your Directory Server data using db2bak.
When you run amtune, the script creates a tar file that contains the Directory Server tuning script, amtune-directory. Untar this file in a temporary directory and then run the script in review mode. When you are certain that your changes are acceptable for all applications at your deployment, run amtune-directory in change mode.
For detailed information about running the tuning scripts and setting tuning parameters in the amtune-env configuration file, see the Sun Java System Access Manager 7 2005Q4 Performance Tuning Guide.