Building and Installing OpenSSO J2EE agents on Glassfish Application Server
In this article I am going show you how to build and install OpenSSO J2EE agents on Glassfish Application server. I assume the opensso war is already been built and installed somewhere which can be used while installing the agents on glassfish. It consists following steps which needs to be carried on the same workspace where the OpenSSO server was built.
Building the Installer JARs
As I mentioned earlier you need to be using the same workspace where the OpenSSO server was built(this is to make sure the amclientsdk.jar is compatible with the server you are running). Typically your opensso workspace will have a directory structure like this
CVS/ legal/ lightbulb/ products/ resources/ www/
change your working directory to the opensso workspace then run the following sequence of commands. You should be using ant version 1.6.5+
% cd products/installtools % ant clean % ant all % cp built/dist/\*.jar ../j2eeagents/appserver/v81/extlib/
Eventhough the agents directory named as v81, the agents built from this source works fine with the Glassfish server.(note you need to make little code change for the agent’s installer to configure the Glassfish domain.xml properly.)
Building the amcliensdk.jar
To build the J2EE policy agents for glassfish server you need to have the amclientsdk.jar built from the opesso server workspace. I would recommend you build the amclientsdk.jar from the same workspace of the opensso server. Using a stale out of date amclientsdk.jar could lead to a compatibility issues as OpenSSO server code base is being updated regularly.
If you are successfull in building the agents installer JARs then you can proceed with the following sequence of steps after changing your working directory to the opensso workspace.
% cd products/amserver % ant clientsdk-clean % ant clientsdk % cp built/dist/amclientsdk.jar ../j2eeagents/appserver/v81/extlib/
Building the J2EE agents for Glassfish
Once you built the installer JARs and OpenSSO client SDK JARs, you can proceed to build the J2EE agents for Glassfish. Since the Glassfish application server is little bit different from its predecessor Application Server 8.1, you need to make a code modification so that the agents installer can recognize the Glassfish server to configure agents class JARs in domain.xml.
You need to modify the DomainXMLBase.java to reflect the changes as shown in the cvs diff below.
Index: DomainXMLBase.java =================================================================== RCS file: /cvs/opensso/products/j2eeagents/appserver/v81/source/com/sun/identity/agents/install/appserver/v81/DomainXMLBase.java,v retrieving revision 1.1 diff -r1.1 DomainXMLBase.java 450c450 < public static final String STR_CLASSPATH_ATTR = "server-classpath"; --- > public static final String STR_CLASSPATH_ATTR = "classpath-suffix";
Glassfish documents recommends using classpath-suffix in lieu of server-classpath
From your glassfish installation, copy appserv-ext.jar appserv-rt.jar j2ee.jar and javaee.jar files to the J2EE agents workspace. Assuming your Glassfish is installed in /export1/glassfish/glassfish/lib
% cp /export1/glassfish/glassfish/lib/appserv-rt.jar products/j2eeagents/appserver/v81/extlib % cp /export1/glassfish/glassfish/lib/appserv-ext.jar products/j2eeagents/appserver/v81/extlib % cp /export1/glassfish/glassfish/lib/javaee.jar products/j2eeagents/appserver/v81/extlib % cp /export1/glassfish/glassfish/lib/j2ee.jar products/j2eeagents/appserver/v81/extlib % cd products/j2eeagents % ant clean % ant appserver_v81 % ls built/dist/ appserver_v81_agent.zip appserver_v81_agent.zip.sha
Now you can copy the appserver_v81_agent.zip to your Glassfish host to install the agents on to the glassfish application server.
A simple agents configuration session could be some thing like shown below. You need to set the JAVA_HOME to the Glassfish server’s java_home before invoking the agentadmin –install
[auduin]:/export1/agents/j2ee_agents/appserver_v81_agent/bin>./agentadmin --install <accept the license> --> removed this part for readability \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Welcome to the Access Manager Policy Agent for Sun Java(TM) System Application Server 8.1. If the Policy Agent is used with Federation Manager services, User needs to enter information relevant to Federation Manager. \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Enter the complete path to the directory which is used by Application Server to store its configuration Files. This directory uniquely identifies the Application Server instance that is secured by this Agent. [ ? : Help, ! : Exit ] Enter the Application Server Config Directory Path [/var/opt/SUNWappserver/domains/domain1/config]: /export1/glassfish/glassfish/domains/domain1/config/ Enter the name of the Application Server instance that is secured by this Agent. [ ? : Help, < : Back, ! : Exit ] Enter the Application Server Instance name [server]: Enter the fully qualified host name of the server where Access Manager Services are installed. [ ? : Help, < : Back, ! : Exit ] Access Manager Services Host: auduin.example.com Enter the port number of the Server that runs Access Manager Services. [ ? : Help, < : Back, ! : Exit ] Access Manager Services port : 8080 Enter http/https to specify the protocol used by the Server that runs Access Manager services. [ ? : Help, < : Back, ! : Exit ] Access Manager Services Protocol [http]: Enter the Deployment URI for Access Manager Services. [ ? : Help, < : Back, ! : Exit ] Access Manager Services Deployment URI [/amserver]: /opensso Enter the fully qualified host name on which the Application Server protected by the agent is installed. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Host name: auduin.example.com Enable this field only when the agent is being installed on a remote server instance host. [ ? : Help, < : Back, ! : Exit ] Is Domain administration server host remote ? [false]: Enter the preferred port number on which the application server provides its services. [ ? : Help, < : Back, ! : Exit ] Enter the port number for Application Server instance : 18080 Select http or https to specify the protocol used by the Application server instance that will be protected by Access Manager Policy Agent. [ ? : Help, < : Back, ! : Exit ] Enter the Preferred Protocol for Application Server instance [http]: Enter the deployment URI for the Agent Application. This Application is used by the agent for internal housekeeping. [ ? : Help, < : Back, ! : Exit ] Enter the Deployment URI for the Agent Application [/agentapp]: Enter a valid Encryption Key. [ ? : Help, < : Back, ! : Exit ] Enter the Encryption Key [wa9N9sNCiW5oZJTl+IEdEV+4UZuPAjDG]: Enter a valid Agent profile name. Before proceeding with the agent installation, please ensure that a valid Agent profile exists in Access Manager. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: asagent Enter the path to a file that contains the password to be used for identifying the Agent. [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file: /tmp/pass1 Enter true only if agent is being installed on a remote instance from the Domain Administration server host. [ ? : Help, < : Back, ! : Exit ] Is the agent being installed on the DAS host for a remote instance ? [false]: Enter true if the Agent is being installed on the same instance of Application Server on which Access Manager is deployed. Enter false if that is not the case. [ ? : Help, < : Back, ! : Exit ] Are the Agent and Access Manager installed on the same instance of Application Server ? [false]: ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Application Server Config Directory : /export1/glassfish/glassfish/domains/domain1/config/ Application Server Instance name : server Access Manager Services Host : auduin.example.com Access Manager Services Port : 8080 Access Manager Services Protocol : http Access Manager Services Deployment URI : /opensso Agent Host name : auduin.example.com Domain Administration Server Host is remote : false Application Server Instance Port number : 18080 Protocol for Application Server instance : http Deployment URI for the Agent Application : /agentapp Encryption Key : wa9N9sNCiW5oZJTl+IEdEV+4UZuPAjDG Agent Profile name : asagent Agent Profile Password file name : /tmp/pass1 Agent installed on the DAS host for a remote instance : false Agent and Access Manager on same application server instance : false Verify your settings above and decide from the choices below. 1. Continue with Installation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection : Creating a backup for file /export1/glassfish/glassfish/domains/domain1/config//login.conf ...DONE. Creating a backup for file /export1/glassfish/glassfish/domains/domain1/config//server.policy ...DONE. Adding Agent Realm to /export1/glassfish/glassfish/domains/domain1/config//login.conf file ...DONE. Adding java permissions to /export1/glassfish/glassfish/domains/domain1/config//server.policy file ...DONE. Creating directory layout and configuring Agent file for Agent_001 instance ...DONE. Reading data from file /tmp/pass1 and encrypting it ...DONE. Generating audit log file name ...DONE. Creating tag swapped AMAgent.properties file for instance Agent_001 ...DONE. Creating a backup for file /export1/glassfish/glassfish/domains/domain1/config//domain.xml ...DONE. Adding Agent parameters to /export1/glassfish/glassfish/domains/domain1/config//domain.xml file ...DONE. SUMMARY OF AGENT INSTALLATION ----------------------------- Agent instance name: Agent_001 Agent Configuration file location: /export1/agents/j2ee_agents/appserver_v81_agent/Agent_001/config/AMAgent.properties Agent Audit directory location: /export1/agents/j2ee_agents/appserver_v81_agent/Agent_001/logs/audit Agent Debug directory location: /export1/agents/j2ee_agents/appserver_v81_agent/Agent_001/logs/debug Install log file location: /export1/agents/j2ee_agents/appserver_v81_agent/logs/audit/install.log Thank you for using Access Manager Policy Agent
Now the agent is configured successfully on glassfish. I have assumed the following
- OpenSSO server is installed on host auduin.example.com on port 8080
- Glassfish server installed on host auduin.example.com on port 18080
They are altogether two different installations not from the same server with different listener ports.
Post installation Steps
Creating the agent profile ID in the OpenSSO Server
You need to create a agent profile ID ‘asagent‘ in the OpenSSO server, this is ID that will be used by the J2EE agents installed on Glassfish to communicate to the OpenSSO server. To create this ID simply login to the OpenSSO server administrative console(http://auduin.example.com:8080/opensso/console) as top level admin user ‘amadmin’. Select the root realm->subjects->agents
You need to provide the same password as in file /tmp/pass1
Add com.sun.identity.agents.config.composite.advice.file in AMAgent.properties
Find the AMAgent.properties(for eg: /export1/agents/j2ee_agents/appserver_v81_agent/Agent_001/config/AMAgent.properties) and include the following propery in it.
com.sun.identity.agents.config.composite.advice.file = /export1/agents/j2ee_agents/appserver_v81_agent/locale/CompositeAdviceForm.txt
Any time you modify the AMAgent.properties, you need to restart the servlet container.
(optional) Build the agentsample
The J2EE agents provide a comprehensive sample WAR file that pretty much cover the core features of the policy agents. This sample is available under the j2ee_agents/appserver_v81_agent/sampleapp directory. To build the sample refer the readme file in the j2ee_agents/appserver_v81_agent/sampleapp directory.
Updated steps for deploying agentsample on Glassfish
- You need to replace j2ee.jar with javaee.jar and APPSERV_LIB_DIR with Glassfish lib directory in j2ee_agents/appserver_v81_agent/sampleapp/build.xml
- If you are using flatfile repository then use authenticated users subject for the policy rule1
- You cannot test rule2 in the sample if you are not using LDAPv3 repository which supports groups.
- Use the Glassfish JAVA_HOME to build the sample
After you deploy the agentsample application you should be able to access it by entering the http://auduin.example.com:18080/agentsample/index.html,Accessing this page should not require you to authenticate. If it redirects to OpenSSO server then check your AMAgent.properties for notenforced.uri property. The notenforced uri property should have a value agentsample/index.html
If you have already applications deployed on glassfish which you want to protect by using the agents then you need to add the agents filter in to the deployed webapp’s web.xml. Refer the documentation http://docs.sun.com/app/docs/doc/819-3201/6n5eht3k7?a=view