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
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
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
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
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
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
The Domain Administration Server (DAS) manages the cluster.
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.
Create an agent password file, as described in Creating a Password File.
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.
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.
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).
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
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.
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.
Start the DAS instance (but not the cluster instances).
Login to the DAS server (Host A).
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:
Change to the <BASE_DIR>/j2ee_agents/appserver_v9_agent directory, where <BASE_DIR> is where you unzipped the agent distribution file.
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.
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
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"
Set the compatibility mode to OFF. For example:
./asadmin create-jvm-options --port 34848 --user admin --passwordfile $P_FILE --target agents30config "-DLOG_COMPATMODE=Off"
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
Set the default realm to the agents realm. For example:
./asadmin set agents30-config.security-service.default-realm=agentRealm
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.
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; };
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).
Restart the DAS instance and then start the cluster instances.
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
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
On the OpenSSO server, modify the Agent Filter Mode:
Log in to the OpenSSO Administration Console.
Click Access Control, realm-name, Agents, J2EE, and then the name of the agent profile (remotecluster).
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.
Click Save.
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.
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.