Installing Java EE Agents in Oracle WebLogic

This chapter covers installation of the policy agent for Oracle WebLogic.

Before You Install

Make sure OpenAM is installed and running, and that you can contact OpenAM from the system running the policy agent. Next, create a profile for your policy agent as described in Creating Agent Profiles. To protect resources with the agent, create at least one policy as described in Configuring Policies in the OpenAM Administration Guide. Consider creating a simple policy, such as a policy that allows only authenticated users to access your resources in order to test your policy agent after installation.

You must install WebLogic before you install the policy agent, and you must stop the server during installation.

You must install a supported version of the Java runtime environment. Set the JAVA_HOME environment variable accordingly. The policy agent installer requires Java.

$ echo $JAVA_HOME
/path/to/java

See the OpenAM Installation Guide section, Obtaining OpenAM Software to determine which version of the agent to download, and download the agent. Also verify the checksum of the file you download against the checksum posted on the download page.

Unzip the file in the directory where you plan to install the J2EE policy agent. The agent you install stores its configuration and logs under this directory.

When you unzip the policy agent, you find the following directories under the j2ee_agents/weblogic_v10_agent directory.

Despite the directory name, the policy agent supports multiple container versions.

bin: The installation and configuration program agentadmin. For more details about the available command-line tools, see Command-Line Tool Reference.
config: Configuration templates used by the agentadmin command during installation
data: Not used
etc: Configuration templates used during installation
installer-logs: Location for log files written during installation
legal-notices: Contains licensing information including third-party licenses
lib: Shared libraries used by the Java EE policy agent
locale: Property files used by the installation program
README: README file containing platform and install information for the agent

Installing the WebLogic Policy Agent

Complete the following procedures to install the policy agent.

To Create the Agent Profile

Regardless of whether you store configurations centrally in OpenAM or locally with your agents, the agent requires a profile so that it can connect to and communicate with OpenAM.

In the OpenAM console, browse to Realms > Realm Name > Agents > J2EE, and then click the New… button in the Agent table.
Complete the web form using the following hints:

Name

The name for the agent profile used when you install the agent

Password

Password the agent uses to authenticate to OpenAM

Configuration

Centralized configurations are stored in the OpenAM configuration store. You can manage the centralized configuration through the OpenAM console. Local configurations are stored in a file alongside the agent.

Server URL

The full URL to an OpenAM instance, or if OpenAM is deployed in a site configuration (behind a load balancer) then the site URL

In centralized configuration mode, the Server URL is used to populate the agent profile for services, such as Login, Logout, Naming, and Cross Domain SSO.

Agent URL

The URL to the J2EE agent application, such as http://www.example.com:8080/agentapp

In centralized configuration mode, the Agent URL is used to populate the Agent Profile for services, such as notifications.

To Create a Password File

Create a text file containing only the password specified when creating the agent profile.

UNIX example:
```
$ echo password > /tmp/pwd.txt
```
Windows example:
```
C:\> echo password > pwd.txt
```
Protect the password file you create as appropriate for your operating system:

UNIX example:
```
$ chmod 400 /tmp/pwd.txt
```
Windows example:

In Windows Explorer, right-click the created password file, for example pwd.txt, select Read-Only, and then click OK.

To Install the Policy Agent into WebLogic

Shut down the WebLogic server where you plan to install the agent.
Make sure OpenAM is running.

Run agentadmin --install to install the agent.

When you run the command, you will be prompted to read and accept the software license agreement for the agent installation. You can suppress the license agreement prompt by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open <server-root>/legal-notices/license.txt.

$ /path/to/j2ee_agents/weblogic_v10_agent/bin/agentadmin --install --acceptLicense
...
-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Startup script location :
/path/to/domain/mydomain/bin/startWebLogic.sh
WebLogic Server instance name : AdminServer
WebLogic home directory : /path/to/wlserver
OpenAM server URL : http://openam.example.com:8080/openam
Agent URL : http://www.example.com:7001/agentapp
Agent Profile name : WebLogic Agent
Agent Profile Password file name : /tmp/pwd.txt

...
SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: Agent_001
Agent Bootstrap file location:
/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config/
 OpenSSOAgentBootstrap.properties
Agent Configuration file location
/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config/
 OpenSSOAgentConfiguration.properties
Agent Audit directory location:
/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/audit
Agent Debug directory location:
/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/logs/debug


Install log file location:
/path/to/j2ee_agents/weblogic_v10_agent/installer-logs/audit/install.log
...

Upon successful completion, the installer updates the WebLogic configuration, copies the agent libraries to WebLogic’s library directory, and also sets up configuration and log directories for the agent.

If the agent is in a different domain than the server, refer to the Administration Guide procedure, Configuring Cross-Domain Single Sign On.

Take note of the configuration files and log locations.

Each agent instance that you install on the system has its own numbered configuration and logs directory. The first agent’s configuration and logs are thus located under the directory j2ee_agents/weblogic_v10_agent/Agent_001/:

config/OpenSSOAgentBootstrap.properties

Used to bootstrap the Java EE policy agent, allowing the agent to connect to OpenAM and download its configuration.

config/OpenSSOAgentConfiguration.properties

Only used if you configured the Java EE policy agent to use local configuration.

logs/audit/

Operational audit log directory, only used if remote logging to OpenAM is disabled.

logs/debug/

Debug directory where the debug file resides. Useful in troubleshooting policy agent issues.
If your policy agent configuration is not in the top-level realm (/), then you must edit config/OpenSSOAgentBootstrap.properties to identify the sub-realm that has your policy agent configuration. Find com.sun.identity.agents.config.organization.name and change the / to the path to your policy agent profile. This allows the policy agent to properly identify itself to the OpenAM server.

The agent requires sourcing before it will work properly. There are two ways to source:

Manually source the file containing the policy agent environment settings for WebLogic before starting the application server.
```
$ . /path/to/setAgentEnv_AdminServer.sh
```
Or edit the startWebLogic.sh script to set the sourcing needed for the agent, by adding these lines after the code block shown. Add the setAgentEnv_AdminServer.sh line to the following location in the file. The drawback to this approach is that it could be overwritten, as noted in the file:
```
$ cat /path/to/startWebLogic.sh
...
# Any changes to this script may be lost when adding extensions to this
# configuration.
DOMAIN_HOME="/opt/Oracle/Middleware/user_projects/domains/base_domain"
 . /path/to/setAgentEnv_AdminServer.sh
${DOMAIN_HOME}/bin/startWebLogic.sh $*
```

If the sourcing is not set properly, the following message appears:

<Error> <HTTP> <cent.example.com>
<AdminServer> <[STANDBY] ExecuteThread: '5' for queue: 'weblogic.kernel.
Default (self-tuning)'> <<WLS Kernel>> <><> <> (1360800613441)
<BEA-101165> <Could not load user defined filter in web.xml:
ServletContext@1761850405[app:agentapp module:agentapp.war path:null
spec-version:null] com.sun.identity.agents.filter.AmAgentFilter.
java.lang.ClassNotFoundException:
com.sun.identity.agents.filter.AmAgentFilter

Start the WebLogic server.

To Protect Applications After Agent Installation

(Optional) Deploy the /path/to/j2ee_agents/weblogic_v10_agent/etc/agentapp.war agent application in WebLogic.

The agentapp.war application is required to enable notifications. If you decide not to deploy the application, you may want to enable the com.sun.identity.agents.config.load.interval property to allow the agent to fetch configuration changes from OpenAM.

For each web application to protect, add the following filter to the application’s WEB-INF/web.xml deployment descriptor, following the opening <web-app> tag:

<filter>
  <filter-name>Agent</filter-name>
  <display-name>Agent</display-name>
  <description>OpenAM Policy Agent Filter</description>
 <filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
 </filter>
 <filter-mapping>
  <filter-name>Agent</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>INCLUDE</dispatcher>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>ERROR</dispatcher>
 </filter-mapping>

You might also have to update additional configuration files. See the sample application located under /path/to/j2ee_agents/weblogic_v10_agent/sampleapp for examples.

(Optional) If you have a policy configured, you can test your policy agent. For example, try to browse to a resource that your policy agent protects. You should be redirected to OpenAM to authenticate, for example, as user demo, password changeit. After you authenticate, OpenAM then redirects you back to the resource you tried to access.

Silent WebLogic Policy Agent Installation

When performing a scripted, silent installation, use agentadmin --install --saveResponse response-file to create a response file for scripted installation. Then install silently using agentadmin --install --acceptLicense --useResponse response-file.

Post Installation of WebLogic Policy Agent

After installing WebLogic, some configuration is required before the policy agent will work.

To Configure the WebLogic Policy Agent

WebLogic is unique in that it requires additional configuration after the installation is complete:

Go to the WebLogic Server Administration Console and login.
Click Security realms.
Click the name of the realm to use for OpenAM.
Click Providers > Authentication.
Click Lock & Edit > New.
Enter the desired type in Type as AgentAuthenticator, provide a name, and click OK.
Click on the name of the agent authenticator you just created.
Use OPTIONAL for the control flag and save.
Click on Providers to display the Authentication Providers Table.
Click on Default Authenticator, use OPTIONAL for the control flag, and save.
Activate the changes once the default authenticator is done saving.

You will need to restart the WebLogic Server to implement the changes.

Installing WebLogic Policy Agents in Multi-Server Domains

In many WebLogic domains, the administration server provides a central point for controlling and managing the configuration of the managed servers that host protected applications.

If WebLogic-managed-servers run on different hosts, you must create separate agent profiles and perform separate installations for each so that OpenAM can send notifications to the appropriate addresses.

To Install the Policy Agent on Administration & Managed Servers

For multi-server WebLogic domains, install policy agent as follows:

If servers are on different hosts, create agent profiles for each server where you plan to install the policy agent.

The steps are described under Installing the WebLogic Policy Agent.
Prepare your protected web applications by adding the policy agent filter configuration as described in To Protect Applications After Agent Installation.
Use the agentadmin command to install the policy agent either interactively, or silently on each server in the domain.
- For interactive installation, prepare password files for the servers as described under Installing the WebLogic Policy Agent.
  
  Then install the policy agent on the servers as described in To Install the Policy Agent into WebLogic.
- For silent installation, follow the instructions in Silent WebLogic Policy Agent Installation.
Start WebLogic, and then set up an authentication provider as described in To Configure the WebLogic Policy Agent.
On each server in the domain, deploy the policy agent agentapp.war.
On each managed server in the domain, update the classpath to include policy agent .jar files.

In WebLogic Node Manager console, browse to Environment > Servers > server > Server Start > Class Path, and then edit the classpath as in the following example, but all on a single line:
```
/path/to/j2ee_agents/weblogic_v10_agent/lib/agent.jar:
/path/to/j2ee_agents/weblogic_v10_agent/lib/openssoclientsdk.jar:
/path/to/j2ee_agents/weblogic_v10_agent/locale:
/path/to/j2ee_agents/weblogic_v10_agent/Agent_001/config:
$CLASSPATH
```
Replace the paths in the example with the actual paths for your domain.
Restart the managed servers.

Removing WebLogic Policy Agent Software

Shut down the WebLogic server before you uninstall the policy agent.

To remove the Java EE policy agent, use agentadmin --uninstall. You must provide the WebLogic configuration directory location.

Uninstall does not remove the agent instance directory, but you can do so manually after removing the agent configuration from WebLogic.