Installing and Configuring the Agent in an Application Server 9.1 or Sun GlassFish 2.1 Cluster

In this deployment scenario, you want to deploy the agent to protect Java EE applications deployed in a Sun Java System Application Server 9.1 or Sun GlassFish Enterprise Server 2.1 cluster.

• Application Server 9.1 or Sun GlassFish 2.1 Cluster Deployment Scenario

• Installing the Application Server 9.1 / GlassFish 2.1 Agent on the Domain Administration Server (DAS)

• Configuring the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

• Verifying the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

Application Server 9.1 or Sun GlassFish 2.1 Cluster Deployment Scenario

The cluster deployment scenario described in this section includes the following components:

• Software or hardware load balancer. For example, the Big-IP load balancer

• Application Server 9.1 or Sun GlassFish 2.1 cluster named agents30 with these components:

  • Domain Administration Server (DAS) on Host A

  • Remote Node Agent on Host B with two Application Server 9.1 or Sun GlassFish 2.1 instances

Figure 1 Policy Agent in an Application Server 9.1 or GlassFish 2.1 Cluster

Setting up the cluster is outside the scope of this guide. For information, see the following documentation:

• Sun GlassFish Enterprise Server 2.1:

  • Sun GlassFish Portfolio: http://www.sun.com/software/products/glassfish_portfolio/index.jsp

  • Sun documentation collection: http://docs.sun.com/coll/1343.6

• Sun Java System Application Server 9.1: http://docs.sun.com/coll/1343.5

Considerations for the Cluster

Several considerations for the cluster are:

• Because the cluster profile sets the admin port as non-SSL, set AS_ADMIN_SECURE=false in the config/asadminenv.conf file.

• After the cluster is setup, you are ready to install the agents. This section uses agents30 as the cluster name with the corresponding 'agents30-config' node in the domain.xml file (or agents30-config from the console) This configuration name is key information that you will need to configure the Application Server and GlassFish agent.

• To verify the cluster setup, access the clusterjsp sample application using the load balancer URL. For example:

  http://is-lb-2.example.com:38181/clusterjsp

Useful Commands for the Cluster

To create a password file:

P_FILE=/tmp/.gfpass
echo 'AS_ADMIN_ADMINPASSWORD=password' > $P_FILE
echo 'AS_ADMIN_PASSWORD=password'' >> $P_FILE
echo 'AS_ADMIN_MASTERPASSWORD=password'' >> $P_FILE

To create a cluster using the following names:

• Cluster name: agents30

• Domain name: telco

• Instance names: sales and eng

INSTALL_DIR/bin/asadmin create-domain --adminport 34848 
--user admin --passwordfile $P_FILE --interactive=false --profile cluster telco

INSTALL_DIR/bin/asadmin start-domain --user admin --passwordfile $P_FILE telco

INSTALL_DIR/bin/asadmin create-node-agent --user admin --port 34848 
--interactive=false --passwordfile $P_FILE telco-nodeagent

INSTALL_DIR/bin/asadmin create-cluster --port 34848 agents30

INSTALL_DIR/bin/asadmin create-instance --port 34848 --nodeagent telco-nodeagent 
--systemproperties HTTP_LISTENER_PORT=38080 --cluster agents30 sales

INSTALL_DIR/bin/asadmin create-instance --port 34848 --nodeagent telco-nodeagent 
--systemproperties HTTP_LISTENER_PORT=38081 --cluster agents30 eng

INSTALL_DIR/bin/asadmin start-node-agent --user admin --interactive=false 
--passwordfile $P_FILE telco-nodeagent    

INSTALL_DIR/bin/asadmin deploy --target agents30 --port 34848 -
-availabilityenabled=true samples/quickstart/clusterjsp/clusterjsp.ear

INSTALL_DIR/bin/asadmin start-cluster --port 34848 --interactive=false 
--passwordfile $P_FILE agents30

To start and stop a cluster:

asadmin stop-cluster --port 34848 agents30
asadmin stop-node-agent
asadmin stop-domain telco

asadmin start-domain telco
asadmin start-node-agent --syncinstances=true
asadmin start-cluster agents30

Installing the Application Server 9.1 / GlassFish 2.1 Agent on the Domain Administration Server (DAS)

The Domain Administration Server (DAS) manages the cluster.

To Install the Application Server 9.1 / GlassFish 2.1 Agent on the DAS

1. Download and unzip the appserver_v9_agent_3.zip distribution file in a directory that can be accessed by the DAS instance.

   Follow the instructions described in Downloading and Unzipping the appserver_v9_agent.zip Distribution File.

2. Create an agent password file, as described in Creating a Password File.

3. Stop all GlassFish domains, instances, and node agents before starting the installation process.

   Otherwise, you might lose the OpenSSO policy agent installation changes in the DAS domain.xml file.

4. Install the agent using the agentadmin --custom-install option, as described in Installing the Application Server and GlassFish Agent. The installer prompts you for the following values:

   • CONFIG_DIR is the path to the GlassFish configuration directory.

   • INSTANCE_NAME should be the default value server.

   • AM_SERVER_URL is URL where OpenSSO server is running. For example: http://openssohost.example.com:8080/opensso

   • DAS_HOST_IS_REMOTE should be false.

   • AGENT_URL is the agent URL. For example: http://agenthost.example.com:8090/agentapp

   • AGENT_ENCRYPT_KEY is the key used to encrypt the agent profile password. Use the default value or specify a new value as described in Table 1.

   • AGENT_PROFILE_NAME is the agent profile name. This guide uses remotecluster as the name.

   • AGENT_PASSWORD_FILE is the agent profile password file, which is an ASCII text file with only one line specifying the agent profile password in plain text.

   • CREATE_AGENT_PROFILE_NAME should be false in this scenario.

   • AGENT_ADMINISTRATOR_NAME should be blank, unless you have created an agent administrator.

   • AGENT_ADMINISTRATOR_PASSWORD_FILE should be blank, unless you have created an agent administrator and corresponding password file.

   • REMOTE_INSTANCE_LOCAL_DAS should be false.

   • AGENT_INSTANCE_NAME should be blank.

   • REMOTE_AGENT_INSTALL_DIR should be blank.

   For an example response file for a silent installation, see Silent Agent Installation and Configuration Response File.

5. In the OpenSSO Console, create an agent profile, as described in Creating an Agent Profile.

   For the agent profile Name (remotecluster used in examples), Password, Server URL, and Agent URL, use same values you specified during the agent installation in the previous step. For Configuration, specify Centralized (the default).

Silent Agent Installation and Configuration Response File

The following example shows a response file named agentinstall.inf that you could use as input for a silent installation and configuration of the agent to the DAS instance. To use this file, invoke the following command:

./agentadmin custom-install useResponse agentinstall.inf

## Agent User Response File START OF FILE 
CONFIG_DIR= /export/sun/gf2.1/domains/telco/config 
INSTANCE_NAME= server 
AM_SERVER_URL= http://openssohost.example.com:8080/opensso
DAS_HOST_IS_REMOTE= false 
AGENT_URL= http://is-lb-2.example.com:38181/agentapp 
AGENT_ENCRYPT_KEY= cW18Pj2R9Mt7mdvzDUL5+LMMUhm+qeIp 
AGENT_PROFILE_NAME= remotecluster 
AGENT_PASSWORD_FILE= /tmp/pass 
CREATE_AGENT_PROFILE_NAME= false 
AGENT_ADMINISTRATOR_NAME= 
AGENT_ADMINISTRATOR_PASSWORD_FILE= 
REMOTE_INSTANCE_LOCAL_DAS= false 
AGENT_INSTANCE_NAME= 
REMOTE_AGENT_INSTALL_DIR= 
##Agent User Response File END OF FILE 

Changes Made by the Agent Installer

The policy agent installer (agentadmin) makes following changes in the DAS instance:

• Adds the Java Class Path Suffix with the JAR and locale files of the agent to the domain.xml file for the server-config target only (because server was the instance name specified during the installation). This change is not made to the default-config or the agents30-config targets. This distinction is critical to make sure you properly configure the agent to protect the applications deployed on the target agents30-config. For example:

  ${path.separator}/export/sun/j2ee_agents/appserver_v9_agent/lib/agent.jar\$
  {path.separator}/export/sun/j2ee_agents/appserver_v9_agent/lib/openssoclientsdk.-
  jar\${path.separator}/export/sun/j2ee_agents/appserver_v9_agent/locale\$
  {path.separator}/export/sun/j2ee_agents/appserver_v9_agent/Agent_001/config

  where:

  • /export/sun is the base directory (BASE_DIR) where you unzipped the agent distribution file (appserver_v9_agent_3.zip).

  • Agent_001 identifies the agent instance that was created during installation.

• Adds the JVM option for the target server-config to enable the policy agents logging:

  - Djava.util.logging.config.file=<BASE_DIR>/j2ee_agents/appserver_v9_agent/config/
  OpenSSOAgentLogConfig.properties

• Adds the following J2EE permissions to read the agent JAR files in the server.policy file:

  grant codeBase "file:<BASE_DIR>/j2ee_agents/appserver_v9_agent/lib/*" { 
  permission java.security.AllPermission; 
  };

• Adds the agent realm in config/login.conf as follows:

  agentRealm {
  com.sun.identity.agents.appserver.v81.AmASLoginModule required;
  };

• Creates a new default authentication realm named agentRealm for the server instance.

Now, you must apply these changes to the cluster configuration so the applications deployed on the cluster can be protected by the agent.

Configuring the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

This task involves running a sequence of GlassFish administrative commands using the asadmin command-line utility. If you also plan to use asadmin, make sure that the command is in your PATH variable. For example:

export PATH=/export/sun/gf2.1/bin/:$PATH

where /export/sun/gf2.1 is the GlassFish installation directory.

To Configure the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

1. Start the DAS instance (but not the cluster instances).

2. Login to the DAS server (Host A).

3. Copy the agents configuration and library files from the DAS instance to the cluster configuration directory so that these files will be available to the remote instances:

   1. Change to the <BASE_DIR>/j2ee_agents/appserver_v9_agent directory, where <BASE_DIR> is where you unzipped the agent distribution file.

   2. Copy the config, lib, and locale directories to the cluster configuration directory. For example:

      /bin/cp -r Agent_001 config lib locale 
      ${com.sun.aas.instanceRoot}/config/agents30config/

   Agent_001 is the agent instance created by the agent installer (agentadmin).

   Now, you can manage the policy agent configuration files from the centralized location (in this case from the DAS). Any subsequent changes that you make in these directories must also be copied to the above location; otherwise, the cluster will not get the updates you make in the agent configuration files.

4. Create a text file named P_FILE containing the GlassFish administrator and master passwords. For example:

   P_FILE=/tmp/.gfpass
   echo 'AS_ADMIN_ADMINPASSWORD=adminpassword' > $P_FILE
   echo 'AS_ADMIN_PASSWORD=adminpassword' >> $P_FILE
   echo 'AS_ADMIN_MASTERPASSWORD=masterpassword' >> $P_FILE

5. Set the logging properties. For example:

   ./asadmin create-jvm-options --port 34848 --user admin --passwordfile $P_FILE 
   --target agents30config 
   "-Djava.util.logging.config.file=\${com.sun.aas.instanceRoot}
   /config/agents30config/config/OpenSSOAgentLogConfig.properties"

6. Set the compatibility mode to OFF. For example:

   ./asadmin create-jvm-options --port 34848 --user admin --passwordfile $P_FILE 
   --target agents30config "-DLOG_COMPATMODE=Off"

7. Create the agent authentication realm.

   ./asadmin create-auth-realm --port 34848 --user admin --passwordfile $P_FILE 
   --classname com.sun.identity.agents.appserver.v81.AmASRealm 
   --property jaas-context=agentRealm --target agents30-config agentRealm

8. Set the default realm to the agents realm. For example:

   ./asadmin set agents30-config.security-service.default-realm=agentRealm

9. Add the Classpath suffix. For example:

   ./asadmin set agents30-config.java-config.classpath-suffix="\${path.separator}/\$ 
   {com.sun.aas.instanceRoot}/config/agents30-config/lib/agent.jar\${path.separator}\$ 
   {com.sun.aas.instanceRoot}/config/agents30-config/lib/openssoclientsdk.jar\${path.separator}/\$ 
   {com.sun.aas.instanceRoot}/config/agents30-config/locale\${path.separator}\$ 
   {com.sun.aas.instanceRoot}/config/agents30-config/Agent_001/config"

   Note: The $ character is escaped with a backslash (\), which is required when the command is executed in the shell environment.

10. If you have enabled the Java Security Manager (that is, you have the -Djava.security.manager JVM option) for the cluster, you must allow permission to read the agent's JAR files located in the {com.sun.aas.instanceRoot}/config/agents30-config/lib directory.

    Edit the {com.sun.aas.instanceRoot}/config/server.policy file and append the following lines:

    grant codeBase "file:${com.sun.aas.instanceRoot}/config/agents30-config/lib/-" { 
    permission java.security.AllPermission; 
    }; 

11. Deploy the agent application (agentapp.war) on the cluster. For example:

    ./asadmin deploy --target agents30 --host hostA.example.com --port 34848 
    --availabilityenabled=true 
    /export/sun/j2ee_agents/appserver_v9_agent/etc/agentapp.war

    The agent application is required for the agent to receive notifications and to perform Cross Domain Single Sign-on (CDSSO).

12. Restart the DAS instance and then start the cluster instances.

Verifying the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

You can now test the cluster. This task uses the agentsample.ear sample application, which is in the following directory after you unzip the agent distribution file.

<BASE_DIR>/j2ee_agents/appserver_v9_agent/sampleapp/dist

To Verify the Application Server 9.1 / GlassFish 2.1 Agent in the Cluster

1. On the host where the DAS instance is running, deploy the agentsample.ear sample application to your cluster . For example, using asadmin with the deploy option:

   ./asadmin deploy --target agents30 --port 34848 --availabilityenabled=true
   /export/sun/j2ee_agents/appserver_v9_agent/sampleapp/dist/agentsample.ear

2. On the OpenSSO server, modify the Agent Filter Mode:

   1. Log in to the OpenSSO Administration Console.

   2. Click Access Control, realm-name, Agents, J2EE, and then the name of the agent profile (remotecluster).

   3. Under Agent Filter Mode, remove the value ALL and add the value SSO_ONLY.

      The SSO_ONLY value will ask only for authentication for the resource being accessed from the cluster URL, which is http://is-lb-2.example.com:38181/agentsample/index.html. When a user accesses this URL, the cluster will redirect the user to the OpenSSO server for authentication.

   4. Click Save.

3. Restart the DAS instance and cluster together with node agent to get the configuration changes propagated.

   Also, when you restart the node agent, specify the syncinstances=true option to have the configuration changes reflected in the remote instances.

See Also

You can use the agentsample.ear sample application to learn more about policy agents and OpenSSO server features. For information, see Deploying the Policy Agent Sample Application.