Last updated December 11, 2009
The WebLogic Server/Portal 10 policy agent is a version 3.0 Java EE agent (formerly called a J2EE agent) that functions with SunTM OpenSSO Enterprise to protect applications and resources such as HTML files, servlets, JSPs, and EJBs deployed on Oracle WebLogic® Server 10 or WebLogic Portal 10.
Contents
Supported Platforms, Compatibility, and Coexistence for the WebLogic Server/Portal 10 Agent
Pre-Installation Tasks for the WebLogic Server/Portal 10 Agent
Post-Installation Tasks for the WebLogic Server/Portal 10 Agent
Installing and Configuring the WebLogic Server/Portal 10 Agent in a Cluster
Installing and Configuring the WebLogic Server/Portal 10 Agent on WebLogic Portal 10
Migrating a Version 2.2 WebLogic Server/Portal 10 Policy Agent
For general information about J2EE policy agents, including the features for version 3.0 agents, see the Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.
Sun also provides a version 2.2 policy agent for WebLogic Server/Portal 10. However, to use the new version 3.0 policy agent features, you must deploy the version 3.0 WebLogic Server/Portal 10 agent described in this guide.
Supported Containers for the WebLogic Server/Portal 10 Agent
Compatibility With Access Manager 7.1 and Access Manager 7 2005Q4
Agent For |
Supported Container and Information |
---|---|
WebLogic Server/Portal 10 |
|
Minor versions of these containers, including updates, service packs, and patches, are also supported. |
Access Manager 7.1 and Access Manager 7 2005Q4 are compatible with version 3.0 policy agents. However, because Access Manager does not support the centralized agent configuration feature, a version 3.0 agent deployed with Access Manager must store its configuration data locally in the OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties files. The OpenSSOAgentBootstrap.properties file on the server where the agent is deployed contains the information required for the agent to start and initialize itself.
OpenSSO Enterprise supports both version 3.0 and version 2.2 agents in the same deployment. The version 2.2 agents, however, must continue to store their configuration data locally in the AMAgent.properties file. And because the version 2.2 agent configuration data is local to the agent, OpenSSO Enterprise centralized agent configuration is not supported for version 2.2 agents. To configure a version 2.2 agent, you must continue to edit the agent's AMAgent.properties file.
For documentation about version 2.2 agents, see http://docs.sun.com/coll/1322.1.
Version 3.0 agents including the agentadmin program require JDK 1.5 or later on the server where you want to install the agent. Before you install the agent, set your JAVA_HOME environment variable to point to the JDK installation directory.
Login to the server where you want to install the agent.
Create a directory to unzip the agent distribution file.
Download and unzip the weblogic_v10_agent_3.zip distribution file from one of the following sites:
Sun Downloads site under View by Category, Identity Management, and Policy Agents: http://www.sun.com/download/index.jsp
OpenSSO project: https://opensso.dev.java.net/public/use/index.html
The following table shows the layout after you unzip the agent distribution file.
These files are relative to AgentHome/j2ee_agents/weblogic_v10_agent, where AgentHome is where you unzipped the agent distribution file.
PolicyAgent-base (also used in this guide) is AgentHome/j2ee_agents/weblogic_v10_agent.
File or Directory |
Description |
---|---|
README.txt and license.txt |
Readme and license files |
/bin |
agentadmin and agentadmin.bat programs |
/config |
Template, properties, and XML files |
/data |
license.log file. Do not edit this file. |
/etc |
Agent application (agentapp.war) For information, see Deploying the Agent Application. |
/lib |
Required JAR files |
/locale |
Required properties files |
/install-logs |
Log files |
/sampleapp |
Policy agent sample application. For information, see Deploying the Policy Agent Sample Application. |
A password file is an ASCII text file with only one line specifying the password in clear text. By using a password file, you are not forced to expose a password at the command line during the agent installation.
When you install the WebLogic Server/Portal 10 agent using the agentadmin program, you are prompted to specify paths to following password files:
An agent profile password file is required for both the agentadmin default and custom installation options.
An agent administrator password file is required only if you use the custom installation option and have the agentadmin program automatically create the agent profile in OpenSSO Enterprise server during the installation.
Create an ASCII text file for the agent profile. For example: /tmp/wl10agentpw
If you want the agentadmin program to automatically create the agent profile in OpenSSO Enterprise server during the installation, create another password file for the agent administrator. For example: /tmp/agentadminpw
Using a text editor, enter the appropriate password in clear text on the first line in each file.
Secure each password file appropriately, depending on the requirements for your deployment.
An agent administrator can manage agents in OpenSSO Enterprise, including:
Agent management: Use the agent administrator to manage agents either in the OpenSSO Enterprise Console or by executing the ssoadm utility.
Agent installation: If you install the agent using the custom installation option (agentadmin --custom-install) and want to have the installation program create the agent profile, specify the agent administrator (and password file) when you are prompted.
Login to OpenSSO Enterprise Console as amadmin.
Create a new agents administrator group:
Create a new agent administrator user and add the agent administrator user to the agents administrator group:
Click Access Control, realm-name, Subjects, and then User.
Click New and provide the following values:
ID: Name of the agent administrator. For example: agentadminuser
This is the name you will use to login to the OpenSSO Enterprise Console .
First Name (optional), Last Name, and Full Name.
For simplicity, use the same name for each of these values that you specified in the previous step for ID.
Password (and confirmation)
User Status: Active
Click OK.
Click the new agent administrator name.
On the Edit User page, click Group.
Add the agents administrator group from Available to Selected.
Click Save.
Assign read and write access to the agents administrator group:
Login into the OpenSSO Enterprise Console as the new agent administrator. The only available top-level tab is Access Control. Under realm-name, you will see only the Agents tab and sub tabs.
The WebLogic Server/Portal 10 agent uses an agent profile and associated password to communicate with OpenSSO Enterprise server. You can create an agent profile using any of these three methods:
Create the agent profile automatically during installation when you run the agentadmin program with the --custom-install option.
Note: To create the agent profile automatically during installation, the agentadmin program prompts you for an administrator with agent administrative privileges in OpenSSO Enterprise (and the path to the associated password file). Therefore, this user must exist in OpenSSO Enterprise before you run the agentadmin program. If you prefer, you can specify amadmin as this user.
Use the OpenSSO Enterprise Administration Console, as described in To Create an Agent Profile in the OpenSSO Enterprise Console.
Use the ssoadm command-line utility with the create-agent subcommand. For more information about the ssoadm command, see the Sun OpenSSO Enterprise 8.0 Administration Reference.
Login to the Console as amAdmin.
Click Access Control, realm-name, Agents, and J2EE.
Under Agent, click New.
In the Name field, enter the name for the new agent profile. For example: WLS10Agent
Enter and confirm the Password.
Important: This password must be the same password that you enter in the agent profile password file that you specify when you run the agentadmin program to install the agent.
For Configuration, check the location of the agent configuration properties:
Local: Properties are stored in the OpenSSOAgentConfiguration.properties file on the server where the agent is deployed.
Centralized: Properties are stored in the OpenSSO Enterprise centralized data repository. (This option applies to OpenSSO Enterprise only and not to Access Manager 7.1 or Access Manager 7 2005Q4.)
In the Server URL field, enter the OpenSSO Enterprise server URL.
For example: http://openssohost.example.com:58080/opensso
In the Agent URL field, enter the URL for the agent application (agentapp).
For example: http://agenthost.example.com:8090/agentapp
Click Create.
The console creates the agent profile and displays the J2EE Agent page again with a link to the new agent profile.
To do additional configuration for the agent, click this link to display the Edit agent page. For information about the agent configuration fields, see the Console online Help.
Gathering Information to Install the WebLogic Server/Portal 10 Agent
Installing the WebLogic Server/Portal 10 Agent Using the agentadmin Program
Considering Specific Deployment Scenarios for the WebLogic Server/Portal 10 Agent
The version 3.0 agentadmin program includes these installation options:
Default installation (agentadmin --install): The program displays a minimum number of prompts and uses default values for the other options. Use the default install option when the default options, as shown in Table 3, meet your deployment requirements.
or
Custom installation (agentadmin --custom-install): The program displays a full set of prompts, similar to the version 2.2 program. Use the custom install option when you want to specify values other than the default options shown in Table 3, or when you want to install the agent in a WebLogic Portal domain.
Prompt Request |
Description |
---|---|
Startup script location |
Path to the location of the script used to start the WebLogic domain. Applies to both default and custom installation options. Default: /usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh |
WebLogic server instance |
WebLogic Server instance secured by the agent. Applies only to the custom installation option. Default: AdminServer |
WebLogic home directory |
WebLogic Server home directory. Applies to both default and custom installation options. Default: /usr/local/bea/wlserver_10.0 |
OpenSSO Enterprise URL |
URL where OpenSSO Enterprise is running. Applies to both default and custom installation options. For example: http://openssohost.example.com:58080/opensso |
Portal domain |
WebLogic Portal domain Applies only to the custom installation option. Default: false. Specify true only if you are installing the agent on a WebLogic Portal domain. |
Deployment URI for the portal application |
Deployment URI for the portal application that is protected by the agent. Applies only to the custom installation option. Displayed if you answered true to the previous prompt, because your are installing the agent on a WebLogic Portal domain. |
Agent URL |
Agent URL, including the deployment URI. Applies to both default and custom installation options. For example: http://agent.example.com:8090/agentapp |
Encryption Key |
Key used to encrypt the agent profile password. Applies only to the custom installation option. The encryption key should be at least 12 characters long. You can accept the default key or create a new key using the agentadmin --getEncryptKey command. |
Agent profile name |
Agent profile name. A policy agent communicates with OpenSSO Enterprise using the name and password in the agent profile. Applies to both default and custom installation options. For information, see Creating an Agent Profile. |
Agent profile password file |
ASCII text file with only one line specifying the agent profile password. Applies to both default and custom installation options. For information, see Creating a Password File. |
Option to create the agent profile The agentadmin program displays the following prompt if the agent profile previously specified for the Agent Profile Name prompt does not already exist in OpenSSO Enterprise: Enter true if the Agent Profile is being created into OpenSSO Enterprise by the installer. Enter false if it will be not be created by installer. |
To have the installation program create the agent profile, enter true. The program then prompts you for:
Applies only to the custom installation option. |
This section describes how to install the agent in a standalone environment. For information about a cluster, see Installing and Configuring the WebLogic Server/Portal 10 Agent in a Cluster.
Requirements. Before you install the WebLogic Server/Portal 10 agent:
OpenSSO Enterprise server must be installed and accessible.
The WebLogic Server/Portal 10 container must be installed and configured on the server where you plan to install the agent.
You must have downloaded and unzipped the distribution file, as described in Downloading and Unzipping the WebLogic Server/Portal 10 Agent Distribution File.
Login to the server where you want to install the agent.
Important: To install the agent, you must have write permission to the WebLogic Server/Portal 10 agent container files and directories.
Change to the following directory:
PolicyAgent-base/bin
On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:
# chmod 755 agentadmin
Stop the WebLogic Server/Portal 10 container.
Start the agent installation:
Default installation: ./agentadmin --install
or
Custom installation: ./agentadmin --custom-install
On Windows systems, run the agentadmin.bat program.
Enter information as requested by the agentadmin program, or accept the default values.
After you have made your choices, the agentadmin program displays a summary of your responses. For example, for an --custom-install installation:
----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Startup script location : /opt/bea/user_projects/domains/base_domain/startWebLogic.sh WebLogic Server instance name : AdminServer WebLogic home directory : /opt/bea/wlserver_10.0 OpenSSO Enterprise URL : http://openssohost.example.com:58080/opensso Agent Installed on Portal domain : false Agent URL : http://agent.example.com:8090/agentapp Encryption Key : 6w2Tb03H0crtOcU2G5JmphiOoY6e42Pn Agent Profile name : WebLogicAgent Agent Profile Password file name : /tmp/wl10agentpw Agent Profile will be created right now by agent installer : true Agent Administrator : agentadmin Agent Administrator's password file name : /tmp/agentadminpw 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 [1]:
Verify your choices and either continue with the installation (1, the default), or make any necessary changes.
If you continue, the program installs the agent and displays a summary of the installation. For example:
SUMMARY OF AGENT INSTALLATION ----------------------------- Agent instance name: Agent_001 Agent Bootstrap file location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent /Agent_001/config/OpenSSOAgentBootstrap.properties Agent Configuration file location /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent /Agent_001/config/OpenSSOAgentConfiguration.properties Agent Audit directory location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/Agent_001/install-logs/audit Agent Debug directory location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/Agent_001/install-logs/debug Install log file location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/install-logs/audit/custom.log Thank you for using Sun OpenSSO Enterprise Policy Agent 3.0.
After the installation finishes successfully, if you wish, check the installation log file in the following directory:
PolicyAgent-base/install-logs/audit
Restart the WebLogic Server/Portal 10 container.
After you install the WebLogic Server/Portal 10 agent for a specific domain, you cannot use that same agent on the same host for a different domain. To use the WebLogic Server/Portal 10 agent for another domain on the same host, you must install the agent specifically for that domain.
************************************************************************ Welcome to the Sun OpenSSO Enterprise Policy Agent 3.0 for BEA WebLogic 10.0 Platform. ************************************************************************ Enter the path to the location of the script used to start the WebLogic domain. Please ensure that the agent is first installed on the admin server instance before installing on any managed server instance. [ ? : Help, ! : Exit ] Enter the Startup script location [/usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh]: /opt/bea/user_projects/domains/base_domain/startWebLogic.sh Enter the name of the WebLogic Server instance secured by the agent. [ ? : Help, < : Back, ! : Exit ] Enter the WebLogic Server instance name [AdminServer]: Enter the WebLogic home directory [ ? : Help, < : Back, ! : Exit ] Enter the WebLogic home directory [/usr/local/bea/wlserver_10.0]: /opt/bea/wlserver_10.0 Enter the URL where the OpenSSO Enterprise is running. Please include the deployment URI also as shown below: (http://opensso.sample.com:58080/opensso) [ ? : Help, < : Back, ! : Exit ] OpenSSO Enterprise URL: http://openssohost.example.com:58080/opensso Enter true if the agent is being installed on a Portal domain [ ? : Help, < : Back, ! : Exit ] Is the agent being installed on a Portal domain ? [false]: Enter the Agent URL. Please include the deployment URI also as shown below: (http://agent1.sample.com:1234/agentapp) [ ? : Help, < : Back, ! : Exit ] Agent URL: http://agent.example.com:8090/agentapp Enter a valid Encryption Key. [ ? : Help, < : Back, ! : Exit ] Enter the Encryption Key [6w2Tb03H0crtOcU2G5JmphiOoY6e42Pn]: Enter the Agent profile name [ ? : Help, < : Back, ! : Exit ] Enter the Agent Profile name: WebLogicAgent 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/wl10agentpw WARNING: Agent profile/User: WebLogicAgent does not exist in OpenSSO! Either "Hit the Back button, and re-enter the correct agent profile name/user name", or "Create this agent profile when asked (available only in custom-install)", or "Continue without validating it because agent profile is in sub realm", or "Continue without validating/creating it, and manually validate/create it in OpenSSO Enterprise after installation". Enter true if the Agent Profile is being created into OpenSSO by the installer. Enter false if it will be not be created by installer. [ ? : Help, < : Back, ! : Exit ] This Agent Profile does not exist in OpenSSO Enterprise, will it be created by the installer? (Agent Administrator's name and password are required) [true]: Agent Administrator is the Administrator user that can create, delete or update agent profile. [ ? : Help, < : Back, ! : Exit ] Enter the Agent Administrator's name: agentadmin Enter the path to a file that contains the password of Agent Administrator [ ? : Help, < : Back, ! : Exit ] Enter the path to the password file that contains the password of Agent Administrator: /tmp/agentadminpw ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Startup script location : /opt/bea/user_projects/domains/base_domain/startWebLogic.sh WebLogic Server instance name : AdminServer WebLogic home directory : /opt/bea/wlserver_10.0 OpenSSO Enterprise URL : http://openssohost.example.com:58080/opensso Agent Installed on Portal domain : false Agent URL : http://agent.example.com:8090/agentapp Encryption Key : 6w2Tb03H0crtOcU2G5JmphiOoY6e42Pn Agent Profile name : WebLogicAgent Agent Profile Password file name : /tmp/wl10agentpw Agent Profile will be created right now by agent installer : true Agent Profile type : J2EEAgent Agent Administrator : agentadmin Agent Administrator's password file name : /tmp/agentadminpw 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 [1]: Copy amauthprovider.jar to /opt/bea/wlserver_10.0/server/lib/mbeantypes ...DONE. Creating directory layout and configuring Agent file for Agent_001 instance ...DONE. Reading data from file /tmp/wl10agentpw and encrypting it ...DONE. Generating audit log file name ...DONE. Creating tag swapped OpenSSOAgentBootstrap.properties file for instance Agent_001 ...DONE. Configure /opt/bea/user_projects/domains/base_domain/setAgentEnv_AdminServer.sh ...DONE. Configure /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent /config/OpenSSOAgentBootstrap.properties ...DONE. Creating the Agent Profile WebLogicAgent ...DONE. SUMMARY OF AGENT INSTALLATION ----------------------------- Agent instance name: Agent_001 Agent Bootstrap file location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent /Agent_001/config/OpenSSOAgentBootstrap.properties Agent Configuration file location /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent /Agent_001/config/OpenSSOAgentConfiguration.properties Agent Audit directory location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/Agent_001/install-logs/audit Agent Debug directory location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/Agent_001/install-logs/debug Install log file location: /opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/install-logs/audit/custom.log Thank you for using Sun OpenSSO Enterprise Policy Agent 3.0.
Agent instance directory.The installation program creates the following directory for each agent instance:
PolicyAgent-base/Agent_nnn
where nnn identifies the agent instance as Agent_001, Agent_002, and so on for each additional agent instance.
Each agent instance directory contains the following subdirectories:
/config contains the configuration files for the agent instance, including OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties.
/install-logs contains the following subdirectories:
/audit contains local audit trail for the agent instance.
/debug contains the debug files for the agent instance when the agent runs in debug mode.
Installing the Agent on Multiple WebLogic Server/Portal 10 Instances on the Same Domain
Installing the Agent on a Different WebLogic Server/Portal 10 Domain
If the agent is installed on a particular domain, you can install the agent on more than one WebLogic Server/Portal 10 instance associated with the same domain by running the agentadmin program again with the -custom-install option. When you are prompted to enter the startup script location and WebLogic Server instance name, enter values for the new instance, so the agent can distinguish between the various instances.
After the agent is installed for a specific WebLogic Server/Portal 10 domain, you cannot use the same agent binary files on the same server for a different domain. If you attempt to use previously installed agent binary files on the same server but on a different domain, the installation will fail. The agent associates a specific set of agent binary files with a particular domain on WebLogic Server/Portal 10.
To install the agent on a different domain, copy the agent distribution file (weblogic_v10_agent_3.zip) to a different location before you install the agent on the second domain.
Required Post-Installation Tasks for the WebLogic Server/Portal 10 Policy Agent
Optional Post-Installation Tasks for the WebLogic Server/Portal 10 Agent
Configuring a WebLogic Server 10 Instance With the Agent classpath and Java Options
Configuring the Agent Authentication Provider for the WebLogic Server/Portal 10Agent
Adding a WebLogic Administrator to the Bypass List for the WebLogic Server/Portal 10 Agent
Installing the Agent Filter for the WebLogic Server/Portal 10 Agent
Perform this task applies only if the WebLogic Server 10 agent is deployed on an IBM AIX system.
Using a text editor, open the domain-directory/bin/setDomainEnv.sh file for the WebLogic Server 10 instance:
In the setDomainEnv.sh file, find these lines:
JAVA_OPTIONS="${JAVA_OPTIONS}" export JAVA_OPTIONS
Change the first line to:
JAVA_OPTIONS="-DamKeyGenDescriptor.provider=IBMJCE -DamCryptoDescriptor.provider=IBMJCE -DamRandomGenProvider=IBMJCE ${JAVA_OPTIONS}"
Save the setDomainEnv.sh file and restart the WebLogic Server 10 instance.
This section applies to WebLogic Server 10 only. For instructions specific to WebLogic Portal 10, see Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10.
During the agent installation, the installer creates the following environment variable script in domain-directory:
Solaris and Linux systems: setAgentEnv_server-instance.sh
Windows systems: setAgentEnv_server-instance.cmd
where:
domain-directory represents the domain name associated with the WebLogic Server 10 instance. The default path name of domain-directory is:
/usr/local/bea/user_projects/domains/domain-name
server-instance represents the WebLogic Server 10 instance name entered during installation. For example: server1 or server2.
The agent environment variable script is called during the server's startup sequence and sets the classpath and Java options for the agent.
Using a text editor, edit the following WebLogic Server 10 instance startup script, depending on your platform:
Solaris and Linux systems: domain-directory/bin/startWebLogic.sh
Windows systems: domain-directory\bin\startWebLogic.cmd
domain-directory represents the domain name associated with the WebLogic Server 10 instance.
Add the path of the agent environment variable script to the WebLogic Server 10 startup script:
Solaris and Linux systems: After the line, . ${DOMAIN_HOME}/bin/setDomainEnv.sh $*, add the path:
. domain-directory/setAgentEnv_${SERVER_NAME}.sh |
For example, for a domain directory named base_domain:
. /usr/local/bea/user_projects/domains/base_domain/setAgentEnv_${SERVER_NAME}.sh |
Therefore, the startup script would then contain these two lines:
. ${DOMAIN_HOME}/bin/setDomainEnv.sh $* . /usr/local/bea/user_projects/domains/base_domain/setAgentEnv_${SERVER_NAME}.sh |
Windows systems: After the line, call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*, add the path:
call "domain-directory\setAgentEnv_%SERVER_NAME%.cmd"
For example, for a domain directory named base_domain:
call "C:\bea\user_projects\domains\base_domain\setAgentEnv_%SERVER_NAME%.cmd"
Therefore, the startup script would then contain these two lines:
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %* call "C:\bea\user_projects\domains\base_domain\setAgentEnv_%SERVER_NAME%.cmd"
The ${SERVER_NAME} or %SERVER_NAME% variable represents the WebLogic Server 10 instance and is dynamically replaced when the script is executed.
Restart the WebLogic Server 10 instance.
This section applies to both WebLogic Server 10 and WebLogic Portal 10. The agent application (agentapp.war) is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support.
This application is bundled with the weblogic_v10_agent_3.zip distribution file and is available as a WAR file in the following location after you unzip the file:
PolicyAgent-base/etc/agentapp.war
Deploy the agent application on the WebLogic Server/Portal 10 container using the WebLogic Server/Portal 10 administration console or deployment command.
You must use the same deployment URI that you specified for the “Agent Protected Application Server URL” prompt during the agent installation.
For example, if you entered http://agenthost:port/agentapp as the “Agent Protected Application Server URL”, then use this same URI to deploy the agentapp.war file in the WebLogic Server/Portal 10 container.
This section applies only to WebLogic Server 10. For instructions specific to WebLogic Portal 10, see Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10.
Using the security service provider API provided by WebLogic Server 10, the agent plugs its custom security authenticator into the container. Once the Agent Authenticator is configured, all requests call it. You need to set the Agent Authenticator only once per WebLogic Server 10 domain.
For more information about WebLogic Server 10 security providers, see http://e-docs.bea.com/wls/docs100/dvspisec/intro.html.
Add the authentication provider using the WebLogic Server 10 Administration Console.
Log in to the WebLogic Server 10 Administration Console.
In the left pane, under Domain Structure and under the host name of the server you are configuring, click Security realms.
In the right pane, click the name of the realm you are configuring.
Click Providers.
Click the Authentication tab.
In the left pane, click Lock & Edit.
In the right pane, click New.
Specify Type as AgentAuthenticator.
Specify Name with a name of your choice.
Click OK.
Click the newly created policy agent authentication provider.
Change the control flag value to OPTIONAL.
Click Save.
Click Providers.
The Authentication Providers Table appears.
Click Default Authenticator.
Change the control flag to OPTIONAL.
Click Save.
In the left pane, click Activate changes.
Restart the WebLogic Server 10 instance for the changes to take effect.
If you create a new security realm instead of using the default security realm to configure the agent, ensure that the control flag value for the Agent Authenticator and any additional authentication providers are set to OPTIONAL.
This section applies to both WebLogic Server 10 and WebLogic Portal 10. After you complete this task, the WebLogic administrator you add can bypass the authentication process for the OpenSSO Enterprise realm.
Login to the OpenSSO Enterprise Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Click Miscellaneous and then Bypass Principal List.
Enter the WebLogic administrator name in New Value and click Add.
Click Save.
If you prefer to set this option using ssoadm, set the com.sun.identity.agents.config.bypass.principal property. This property is hot-swappable, so you do not need to restart the WebLogic Server/Portal 10 container after you set the property.
This section applies to both WebLogic Server 10 and WebLogic Portal 10. Install the agent filter by modifying the deployment descriptor of each application that you want to protect.
Ensure that the application you want to protect is not currently deployed on WebLogic Server/Portal 10.
If the application is deployed, undeploy it before continuing.
Backup the application's web.xml file before modifying the descriptors.
The backup copy can be useful if you need to uninstall the agent.
Edit the application's descriptors in the web.xml file as follows:
Set the <DOCTYPE> element as shown in the following example:
<!DOCTYPE web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> |
Note: WebLogic Server/Portal 10 supports the Java Servlet specification version 2.4. Version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation.
Add the <filter> elements to the deployment descriptor.
Specify the agent filter as the first <filter> element and the agent filter mapping as the first <filter-mapping> element. For example:
<web-app> ... <filter> <filter-name>Agent</filter-name> <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> ... </web-app> |
Deploy (or redeploy) the application on WebLogic Server/Portal 10.
The agent filter is added to the application.
You can also protect an application with J2EE declarative security. To learn more about protecting your application with J2EE declarative security, consider deploying the sample application. For information, see Deploying the Policy Agent Sample Application.
Ensure that role-to-principal mappings in container specific deployment descriptors are replaced with OpenSSO Enterprise roles or principals. To retrieve OpenSSO Enterprise roles or principals, use the OpenSSO Enterprise Console to browse the user profile. For more information, see Mapping OpenSSO Enterprise Roles to Principal Names.
This section applies to both WebLogic Server 10 and WebLogic Portal 10. After you install the agent, you can change the agent profile password, if required for your deployment.
On the OpenSSO Enterprise server:
On the server where the WebLogic Server/Portal 10 agent is installed:
In the agent profile password file, replace the old password with the new unencrypted password.
Change to the PolicyAgent-base/bin directory.
Encrypt the new password using the agentadmin --encrypt command following this syntax.
agentadmin --encrypt agent-instance password-file
For example:
# ./agentadmin --encrypt Agent_001 /tmp/wl10agentpw
The agentadmin --encrypt command returns the new encrypted password. For example:
ASEWEJIowNBJHTv1UGD324kmT==
In the agent-instance/config/OpenSSOAgentBootstrap.properties file, set the following property to the new encrypted password from the previous step. For example:
com.iplanet.am.service.secret=ASEWEJIowNBJHTv1UGD324kmT==
Restart the WebLogic Server/Portal 10 container.
This section applies only to WebLogic Server 10. For instructions specific to WebLogic Portal 10, see Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10.
If the WebLogic Server 10 agent is configured to operate in the URL_POLICY or ALL filter mode, you must create the appropriate URL policies. For instance, if WebLogic Server 10 is available on port 8080 using the HTTP protocol, you must create at minimum, a policy to allow access to the sample application. For example:
http://agenthost.example.com:8090/agentsample |
where agentsample is the context URI for the sample application.
If no policies are defined and the agent is configured to operate in the URL_POLICY or ALL filter mode, then no user is allowed access to the resources protected by the WebLogic Server 10 agent.
For information about how to create these policies using the OpenSSO Enterprise Console or ssoadm utility, see the Sun OpenSSO Enterprise 8.0 Administration Guide.
This section applies to both WebLogic Server 10 and WebLogic Portal 10.
After you install the WebLogic Server/Portal 10 agent, consider deploying the J2EE policy agent sample application to help you better understand the key features, functions, and configuration options of J2EE agents, including:
Single sign-on (SSO)
Web-tier declarative security
Programmatic security
URL policy evaluation
Session, policy, and profile attribute fetch
The sample application can be especially useful if you are writing a custom agent application.
After you install the WebLogic Server/Portal 10 agent, the sample application is available as:
PolicyAgent-base/sampleapp/dist/agentsample.ear
For information about compiling, deploying, and running the sample application, see the readme.txt file in the /sampleapp directory.
This section applies only to WebLogic Server 10. If the agent is set to the J2EE_POLICY filter mode, map OpenSSO Enterprise roles to the principal names in the respective application's deployment descriptor file(s):
weblogic.xml
weblogic-ejb-jar.xml
OpenSSO Enterprise roles are represented in UUIDs. Ensure that the keys in the mapping are UUIDs corresponding to your site's OpenSSO Enterprise installation. A UUID for a OpenSSO Enterprise role is mapped to the respective principal name in the weblogic.xml or weblogic-ejb-jar.xml file. Specifically, the principal name is located within the <principal-name> element.
To configure the WebLogic Server/Portal 10 agent to use privileged attribute mapping. use one of these methods:
In the OpenSSO Enterprise Administration Console:
Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Under Application, click Privilege Attributes Processing.
For Enable Privileged Attribute Mapping, check Enabled.
In the Privileged Attribute Mapping list, Add the mapping entries.
When you are finished, click Save.
or
Use the ssoadm utility to set the these properties:
com.sun.identity.agents.config.privileged.attribute.mapping.enable=true com.sun.identity.agents.config.privileged.attribute.mapping[id=manager, ou=group,dc=example,dc=com]=am_manager_role
Starting with WebLogic Server 9.0, a principal name in the weblogic.xml file or weblogic-ejb-jar.xml file must use the NMTOKEN format, which is mandated by the corresponding schema files. Access Manager UUIDs include the following characters: equal sign (=), comma (,), and ampersand (&).
The WebLogic Server/Portal 10 agent supports Web Services Security (WSS) for web service providers on WebLogic Server 10 (but not on WebLogic Portal 10).
A web service provider (WSP) deployed on WebLogic Server 10 protected by the agent can have additional security. For example, you can configure the WebLogic Server/Portal 10 agent and OpenSSO Enterprise server to support various Web Services Security profiles, including Username token, X509 token, and SAML2 token.
Configuring the WebLogic Server/Portal 10 agent to use Web Services Security with OpenSSO Enterprise is similar to configuring other Java EE policy agents, with several additional steps specific to WebLogic Server 10.
Perform the general steps, as described in Web Services Security Support for J2EE Agents in Policy Agent 3.0 in Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.
Stop the WebLogic Server 10 instance.
Copy the xmlsec.jar file from the OpenSSO Enterprise server deployment to the PolicyAgent-base/lib directory.
PolicyAgent-base is AgentHome/j2ee_agents/weblogic_v10_agent, where AgentHome is where you unzipped the agent distribution file.
For example: /opt/j2ee_agents/weblogic_v10_agent/lib
Add the xmlsec.jar file to the AGENT_CLASSPATH variable:
Find the setAgentEnv_weblogic-server-name.sh script.
For example, if WebLogic Server 10 is installed at /usr/local/bea, change to the /usr/local/bea/user_projects/domains/base_domain directory.
In setAgentEnv_weblogic-server-name.sh, add the PolicyAgent-base/lib/xmlsec.jar at the beginning of the AGENT_CLASSPATH variable.
Save the change.
Edit the setDomainEnv.sh script as follows:
Change to the /usr/local/bea/user_projects/domains/base_domain/bin directory.
In setDomainEnv.sh, near the end of the file, find the following lines:
JAVA_OPTIONS="${JAVA_OPTIONS}" export JAVA_OPTIONS
Change the JAVA_OPTIONS="${JAVA_OPTIONS}" line to:
JAVA_OPTIONS="${JAVA_OPTIONS} -Djavax.xml.soap.MessageFactory=com.sun.xml.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0"
Note: The above entry must be on one line in the setDomainEnv.sh file.
Save the change.
Make the following configuration change in the Security Token Service.
Start the WebLogic Server 10 instance.
OpenSSO Enterprise stores version 3.0 policy agent configuration data (as well as server configuration data) in a centralized repository. To manage this configuration data, use these options:
OpenSSO Enterprise Administration Console
You can manage both version 3.0 J2EE and web agents from the OpenSSO Enterprise Console. Tasks that you can perform include creating, deleting, updating, listing, and displaying agent configurations. Using the Console, you can set properties for an agent that you previously set by editing the agent's AMAgent.properties file.
For more information, refer to the Administration Console online Help.
ssoadm command-line utility
The ssoadm utility is the command-line interface to OpenSSO Enterprise server and is available after you install the tools and utilities in the ssoAdminTools.zip file. The ssoadm utility includes subcommands to manage policy agents, including:
Creating, deleting, updating, listing, and displaying agent configurations
Creating deleting, listing, and displaying agent groups
Adding and removing an agent to and from a group
Set agent configuration properties
For information about the ssoadm utility, including the syntax for each subcommand, see the Sun OpenSSO Enterprise 8.0 Administration Reference.
In some scenarios, you might need to deploy a version 3.0 agent using a local configuration. For example, if you deploy the agent with Access Manager 7.1 or Access Manager 7 2005Q4, which do not support centralized agent configuration, local configuration is used by default.
When you deploy the WebLogic Server/Portal 10 agent with OpenSSO Enterprise to use a local configuration, use one of these methods:
In the OpenSSO Enterprise Administration Console, on the Edit agent-name page, set Location of Agent Configuration Repository to local.
or
Use the ssoadm utility to set the following property:
com.sun.identity.agents.config.repository.location=local
Then, you must manage the version 3.0 agent by editing properties in the agent's local OpenSSOAgentConfiguration.properties file (in the same manner that you edit the AMAgent.properties file for version 2.2 agents).
A version 3.0 agent also stores configuration information in the local OpenSSOAgentBootstrap.properties file. The agent uses information in the bootstrap file to start and initialize itself and to communicate with OpenSSO Enterprise server. In most cases, you won't need to edit the bootstrap file; however, if you do edit the file, be careful, or the agent might not function properly.
To remove the Agent Authentication Provider that was configured after the agent was installed, use the WebLogic Server/Portal 10 Administration Console.
Login to the WebLogic Server/Portal 10 Administration Console.
In the left pane, under Domain Structure and under the host name of the server you are configuring, click Security realms.
In the right pane, click the name of the realm you are configuring.
Click Providers.
Click the Authentication tab.
In the left pane, click Lock & Edit.
In the right pane, specify the Policy Agent Authentication Provider.
Click Delete.
Click Yes.
In the left pane, click Activate changes.
The Agent Authentication Provider is not removed from the configuration until you restart the WebLogic Server/Portal 10 instance. The best practice is to restart the WebLogic Server/Portal 10 instance after you perform the following tasks.
Undeploy any applications protected by the WebLogic Server/Portal 10 agent.
Restore the deployment descriptors of these applications to their original deployment descriptors. (Backup files are useful here if you have them.)
If you are permanently removing the WebLogic Server/Portal 10 agent, undeploy the agent application.
However, if you plan to re-install this agent , you don't need to undeploy the agent application.
If the WebLogic Server/Portal 10 instance was originally configured using Node Manager, remove the classpath and agent Java options using the WebLogic Server/Portal 10 Administration Console. For more information, see:
Configuring a WebLogic Server 10 Instance With the Agent classpath and Java Options
or
WebLogic Portal 10: Configuring the Agent classpath and Java Options
Ensure that the WebLogic Server/Portal 10 container is stopped.
Change to the following directory:
PolicyAgent-base/bin
Issue one of the following commands:
# ./agentadmin --uninstall
or
# ./agentadmin --uninstallAll
The --uninstall removes only one instance of the agent, while the --uninstallAll option prompts you to remove all configured instances of the agent.
When prompted, enter the Startup script location.
The uninstall program displays your response and then asks if you want to continue:
To continue with the uninstallation, select 1 (the default).
************************************************************************ Welcome to the Sun OpenSSO Enterprise Policy Agent 3.0 for BEA WebLogic 10.0 Platform. ************************************************************************ Enter the path to the location of the script used to start the WebLogic domain. Please ensure that the agent is first installed on the admin server instance before installing on any managed server instance. [ ? : Help, ! : Exit ] Enter the Startup script location [/usr/local/bea/user_projects/domains/base_domain/startWebLogic.sh]: /opt/bea/user_projects/domains/base_domain/startWebLogic.sh ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- Startup script location : /opt/bea/user_projects/domains/base_domain/startWebLogic.sh Verify your settings above and decide from the choices below. 1. Continue with Uninstallation 2. Back to the last interaction 3. Start Over 4. Exit Please make your selection [1]: Remove amauthprovider.jar from /export/home/opt/bea/wlserver_10.0/server/lib/mbeantypes ...DONE. Deleting the config directory /export/home/opt/agents/weblogic10/j2ee_agents/weblogic_v10_agent/Agent_001/config ...DONE. UnConfigure /opt/bea/user_projects/domains/base_domain/setAgentEnv_AdminServer.sh ...DONE. Uninstall log file location: /export/home/opt/agents/weblogic10/j2ee_agents /weblogic_v10_agent/install-logs/audit/uninstall.log Thank you for using Sun OpenSSO Enterprise Policy Agent 3.0.
The /config directory is removed from the agent instance directory, but the /install-logs directory still exists.
The uninstall program creates an uninstall log file in the PolicyAgent-base/install-logs/audit directory.
The agent instance directory is not automatically removed. For example, if you uninstall the agent for Agent_001, a subsequent agent installation creates the Agent_002 instance directory. To remove an agent instance directory, you must manually remove the directory.
Installing and configuring the WebLogic Server/Portal 10 agent in a clustered environment is similar to the process for a stand-alone environment. Exceptions are noted in this section.
In a cluster, you must install the WebLogic Server/Portal 10 agent in this order:
First, install the agent on the Administration Server. The agent on the Administration Server sets up the Agent Authenticator for the entire domain. See Installing the WebLogic Server/Portal 10 Agent on the Administration Server.
Then, install the agent on each of the Managed Servers that you want to protect. See Installing the WebLogic Server/Portal 10 Agent on a Managed Server.
Ensure that the Administration Server is not running.
Install the agent as you would in a stand-alone environment. See Installing the WebLogic Server/Portal 10 Agent.
Configure the agent classpath for the Administration Server. See Configuring a WebLogic Server 10 Instance With the Agent classpath and Java Options.
Start the Administration Server.
Configure the Agent Authentication Provider. See Configuring the Agent Authentication Provider for the WebLogic Server/Portal 10Agent.
Ensure that the Managed Server is not running.
Install the WebLogic Server/Portal 10 agent as you would in a stand-alone environment, with these exceptions:
When you are prompted to enter the startup script location, specify the same path that you provided when you installed the agent on the Administration Server.
When you are prompted to enter the WebLogic Server instance name, specify the Managed Server instance name. For example: server1
Start the Managed Server using the appropriate startup script:
Solaris and Linux systems: domain-name/bin/startManagedWeblogic.sh
Windows systems: domain-name\bin\startManagedWeblogic.cmd
where domain-name is where you located the domain.
For example, on a Solaris system:
cd /opt/bea/user_projects/domains/domain1/bin ./startManagedWeblogic.sh server1 http://adminhost.example.com:7001
Alternatively, you can start a Managed Server instance using Node Manager. See Configuring Node Manager for the WebLogic Server/Portal 10 Agent in a Cluster.
Post-Installation Task |
Where to go for Information |
---|---|
Setting the Java Options on IBM AIX Systems | |
Adding a WebLogic Administrator to the Bypass List |
Adding a WebLogic Administrator to the Bypass List for the WebLogic Server/Portal 10 Agent |
Enabling Agent Protection in Web Applications |
Installing the Agent Filter for the WebLogic Server/Portal 10 Agent |
Deploying the Agent Application in a Cluster |
Deploying the Agent Application for the WebLogic Server/Portal 10 Agent in a Cluster |
Configuring Node Manager for the WebLogic Server/Portal 10 Agent in a Cluster |
Configuring Node Manager for the WebLogic Server/Portal 10 Agent in a Cluster. |
For additional tasks, see Post-Installation Tasks for the WebLogic Server/Portal 10 Agent
Deploy the agent application (agentapp.war) on each instance in the cluster on which the agent is installed, including the Administration Server and each Managed Server. Instances in the cluster require the agent application to receive notifications.
A deployment can have multiple applications protected by the same agent running on the same Managed Server instance. All applications hosted on the same Managed Server instance use the agent application deployed for that instance.
Deploy the agent application using either the WebLogic Server command-line tools or Administration Console.
Login to the WebLogic Server/Portal 10 Administration Console
Expand the Deployments tab.
Click Lock & Edit.
In the right pane, click Install.
Click upload your file(s).
Upload the agentapp.war file from the following directory:
PolicyAgent-base/etc/agentapp.war
When selecting the target for the Web Application module, select either the entire cluster or individual servers. Deploy the agentapp.war file for each server node on which you installed the agent.
You have the option of starting Managed Servers in a cluster using the WebLogic Server/Portal 10 Node Manager.
In the WebLogic Server/Portal 10 Administration Console, expand the Servers node.
Select the node for the server you want to manage with Node Manager.
Configure the agent classpath in Node Manager:
In the Administration Console, select the Configuration tab.
Select the Server Start tab.
Locate the agent classpath for the specific Managed Server as found in setAgentEnv_sever-instance.sh.
Add the agent classpath to the following classpath text field:
${CLASSPATH}:PolicyAgent-base/lib/agent.jar:PolicyAgent-base/ lib/openssoclientsdk.jar:PolicyAgent-base/locale:PolicyAgent-base/ AgentInstance/config
where AgentInstance represents the agent instance directory, such as Agent_001.
To avoid typing errors, copy and paste the agent classpath entries from the setAgentEnv_managed-sever-instance.sh file.
managed-server-instance is the name of the Managed Server instance. For example, server1.
To the same classpath text field referred to in the previous step, prepend the following classpath entries:
DeployContainer-base/BEA-Java-Home/lib/tools.jar: DeployContainer-base/wlserver_10.0/server/lib/weblogic.jar
DeployContainer-base is the directory in whichWebLogic Server/Portal 10 was installed.
BEA-Java-Home is the directory that contains the JDK for theWebLogic Server/Portal 10 instance.
Click Save.
Click Activate Changes.
Configure the agent Java options in Server Start.
In the WebLogic Server/Portal 10 Administration Console, select the Configuration tab.
Select the Server Start tab.
Locate the Java options as found in setAgentEnv_sever-instance .sh for the specific Managed Server.
Add the Java options to the Arguments text field as follows:
-Djava.util.logging.config.file=PolicyAgent-base/config/ OpenSSOAgentLogConfig.properties -DLOG_COMPATMODE=Off
To avoid typing errors, copy and paste the agent Java option entries from the setAgentEnv_managed-sever-instance.sh file.
Click Save.
Click Activate Changes.
Installation and configuration of the agent on WebLogic Portal 10 is similar to the same tasks on WebLogic Server 10. This section describes the differences, including:
Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10
Testing the WebLogic Server/Portal 10 Agent on WebLogic Portal 10
The examples in this section show how to protect the sample portal, which by default is named groupspace. You can protect multiple portals with a single WebLogic Portal 10 instance. For each portal you configure, ensure that you use the correct portal application name.
To install the agent on WebLogic Portal 10, use the custom installation option. For example:
# ./agentadmin --custom-install
The installation process is then similar to installing the agent on WebLogic Server 10, with the exception of these prompts:
... Enter true if the agent is being installed on a Portal domain [ ? : Help, < : Back, ! : Exit ] Is the agent being installed on a Portal domain ? [false]: true
Enter true.
... Enter the Deployment URI for the portal application that is protected by the agent. [ ? : Help, < : Back, ! : Exit ] Enter the Deployment URI for the portal Application [/]: /groupspace
Enter the deployment URI. Examples in this section use the default sample portal, /groupspace.
For a description of the other installation prompts, see Installing the WebLogic Server/Portal 10 Agent.
The post-installation tasks are similar to configuring the agent on WebLogic Server 10, with the exceptions noted in the following tables.
Table 5 Required Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10
Required Post-Installation Task |
Where to go for Information |
---|---|
Configuring the Agent classpath and Java Options |
Different for WebLogic Portal 10. See WebLogic Portal 10: Configuring the Agent classpath and Java Options. |
Configuring the Agent Authentication Provider |
Different for WebLogic Portal 10. See WebLogic Portal 10: Configuring the Agent Authentication Provider. |
Adding a WebLogic Administrator to the Bypass List |
Same as for WebLogic Server 10. See Adding a WebLogic Administrator to the Bypass List for the WebLogic Server/Portal 10 Agent. |
Configuring the Agent Filter Modes |
Different for WebLogic Portal 10. |
Setting Logout-Related Properties for the Sample Portal |
Applies only to WebLogic Portal 10. See WebLogic Portal 10: Setting Logout-Related Properties for the Sample Portal. |
Deploying the Agent Application |
Same as for WebLogic Server 10. |
Table 6 Optional Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10
Optional Post-Installation Task |
Where to go for Information |
---|---|
Changing the Password for an Agent Profile |
Same as for WebLogic Server 10. |
Creating the Necessary URL Policies |
Same as for WebLogic Server 10. |
Deploying the Policy Agent Sample Application |
Same as for WebLogic Server 10. |
Mapping OpenSSO Enterprise Roles to Principal Names |
Same as for WebLogic Server 10. |
Using a text editor, edit the following WebLogic Portal 10 startup script, depending on your platform:
Solaris and Linux systems: DeployContainer-base/wlserver_10.0/samples/domains/portal/bin/startWeblogic.sh
Windows systems: DeployContainer-base\wlserver_10.0\samples\domains\portal\bin\startWeblogic.cmd
DeployContainer-base represents the directory where the WebLogic Portal 10 instance is installed.
Add the path of the agent environment variable script to the WebLogic Portal 10 startup script:
Solaris and Linux systems: After the line, . ${DOMAIN_HOME}/bin/setDomainEnv.sh $*, add:
. DeployContainer-base/samples/domains/portal/setAgentEnv_${SERVER_NAME}.sh |
Therefore, the startup script would then contain these two lines:
. ${DOMAIN_HOME}/bin/setDomainEnv.sh $* . DeployContainer-base/samples/domains/portal/setAgentEnv_${SERVER_NAME}.sh |
Windows systems: After the line, call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*, add:
call DeployContainer-base\wlserver_10.0\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd
Therefore, the startup script would then contain these two lines:
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %* call DeployContainer-base\wlserver_10.0\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd
The ${SERVER_NAME} or %SERVER_NAME% variable represents the WebLogic Portal 10 instance that is dynamically replaced.
Restart the WebLogic Portal 10 instance.
This section applies only to WebLogic Portal 10.
Log in to the WebLogic Portal 10 Administration Console.
In the left pane, under Domain Structure and the host name of the server you are configuring, click Security realm.
In the right pane, click the name of the realm you are configuring.
Click Providers.
Click the Authentication tab.
In the left pane, click Lock & Edit.
In the right pane, click New.
Specify Type as AgentAuthenticator.
Specify Name with a name of your choice.
Click OK.
Click the newly created policy agent authentication provider.
Change the control flag value to OPTIONAL.
Click Save.
Click Providers.
The console displays the Authentication Providers Table .
Click SQLAuthenticator
Change the control flag to OPTIONAL.
Click Save.
Click the Providers tab.
Click SAMLAuthenticator
Change the control flag to OPTIONAL.
Click Save.
In the left pane, click Activate changes.
After you are finished, restart the server for the changes to take effect.
If create a new security realm instead of using the default security realm to configure the agent, ensure that the control flag value for the Agent Authenticator and any additional authentication providers are set to OPTIONAL.
Configuring the agent filter modes for WebLogic Portal 10 agent is different than for the WebLogic Server 10 agent because the following filter modes do not apply to WebLogic Portal 10:
SSL_ONLY: If you are using WebLogic Portal 10 for single sign-on (SSO), use the J2EE_POLICY filter mode.
URL_POLICY: If you are using WebLogic Portal 10 to protect URLs such as portal JSP files from being accessed directly, use the ALL filter mode.
To set the filter modes for the WebLogic Server/Portal 10 agent, use one of these methods:
Use the OpenSSO Enterprise Administration Console:
Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Under Global, add the filter mode to the Agent Filter Mode.
Click Save.
or
Use the ssoadm utility to set the com.sun.identity.agents.config.filter.mode property.
When creating a OpenSSO Enterprise policy to protect the WebLogic Portal 10 instance, define the policy to give permission to only public portal URLs. For example:
http://agent.example.com:7041/groupspace/
http://agent.example.com:7041/groupspace/groupspace.jsp
This section use the sample portal (groupspace) as the application whose deployment descriptor is modified. For example, the web.xml file for the sample portal is in the following location:
/usr/local/bea/wlserver_10.0/samples/portal/portalApp/groupspaceSampleWeb/WEB-INF
Edit the application's web.xml descriptor by adding the <filter> elements.
Add the <filter>, <filter-mapping>, and <dispatcher> elements as the first filter element in the web.xml descriptor. For example:
<web-app> ... <filter> <filter-name>Agent</filter-name> <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> ... </web-app> |
Important: Make sure that this filter element is the first element in the descriptor.
This task involves configuring logout-related properties for the sample portal (groupspace), using either the either in the OpenSSO Enterprise Console or the ssoadm utility.
To set the logout-related properties in the OpenSSO Enterprise Console:
Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Click Application and then Logout Processing. then set the following fields, depending on your requirements:
Logout Application Handler: An application-specific map that identifies a handler to be used for logout processing. The corresponding property is com.sun.identity.agents.config.logout.application.handler.
Logout Application URI: An application-specific map that identifies a request URI that indicates a logout event. The corresponding property is com.sun.identity.agents.config.logout.uri.
Logout Request Parameter: An application-specific map that identifies a parameter that when present in the HTTP request indicates a logout event. The corresponding property is com.sun.identity.agents.config.logout.request.param.
Logout Introspect Enabled: Check Enabled to allow the agent to search an HTTP request body to locate the logout parameter. The corresponding property is com.sun.identity.agents.config.logout.introspect.enabled.
Logout Entry URI: An application-specific map that identifies a URI to be used as an entry point after a successful logout and subsequent successful authentication if applicable. The corresponding property is com.sun.identity.agents.config.logout.entry.uri.
Click Save.
To use the ssoadm utility, set the logout-related agent properties. For example:
com.sun.identity.agents.config.logout.application.handler[] = com.sun.identity.agents.config.logout.uri[groupspace] = /groupspace/communityFiles/shell/logout.jsp com.sun.identity.agents.config.logout.request.param[groupspace] = logout com.sun.identity.agents.config.logout.introspect.enabled = true com.sun.identity.agents.config.logout.entry.uri[groupspace] = /groupspace/groupspace.jsp
All of these logout-related properties are hot-swappable.
Before configuring the agent, create the same users in OpenSSO Enterprise that exist in WebLogic Portal 10.
If the users in OpenSSO Enterprise have different names than the names in WebLogic Portal 10, you must configure user mapping, using either the OpenSSO Enterprise Console or the ssoadm utility.
To configure user mapping in the OpenSSO Enterprise Console:
Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Click Global and then User Mapping, and then set the following fields, depending on your requirements:
User Mapping Mode: Mechanism the agent uses to determine the user ID (HTTP_HEADER, PROFILE_ATTRIBUTE, SESSION_PROPERTY, or USER_ID)
User Attribute Name: Name of the attribute that contains the user ID. The corresponding property is com.sun.identity.agents.config.user.attribute.name.
User Principal Flag: Check Enabled to use the principal instead of only the user ID for authenticating the user. The corresponding property is com.sun.identity.agents.config.user.principal.
User Token Name: Session property name for the user ID of the authenticated user in the session. The corresponding property is com.sun.identity.agents.config.user.token.
Click Save.
To use the ssoadm utility, set the following agent properties:
com.sun.identity.agents.config.user.mapping.mode[]
com.sun.identity.agents.config.user.attribute.name
com.sun.identity.agents.config.user.principal
com.sun.identity.agents.config.user.token
All of the user mapping properties are hot-swappable.
To further enforce security, configure the agent to verify users in the WebLogic Portal 10 user repository.
Configure a custom verification handler using either the OpenSSO Enterprise Console or the ssoadm utility.
To configure a custom verification handler in the OpenSSO Enterprise Console:
Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.
The Console displays the Edit page for the agent profile.
Click Application, and then set the Custom Verification Handler, which specifies an application specific verification handler to validate the user credentials with the local repository. The corresponding property is com.sun.identity.agents.config.verification.handler.
Click Save.
To use the ssoadm utility, set the com.sun.identity.agents.config.verfication.handler property. For example:
com.sun.identity.agents.config.verification.handler[groupspace] = com.sun.identity.agents.weblogic.v10.AmWLPortalVerificationHandler
This property is hot-swappable.
Create a user with the user ID of sean in both the WebLogic Portal Administration Console and OpenSSO Enterprise Console.
If the agent filter mode (com.sun.identity.agents.config.filter.mode property) is set to ALL, create the appropriate OpenSSO Enterprise policies for the portal URLs where sean is the user.
Using a browser, specify the URL of the sample portal. For example:
http://agent.example.com:7041/groupspace/groupspace.jsp
Login with the user ID of sean.
The sample portal home page should appear.
Click GS Example Community.
The portal web page appears.
Click Logout.
The version 3.0 agentadmin program includes the new --migrate option to migrate a version 2.2 agent to version 3.0. After you migrate a version 2.2 agent, the agent can use the new version 3.0 agent features.
The migration process migrates the agent's binary files, updates the agent's container configuration, and converts the agent's AMAgent.properties file to the new version 3.0 OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties files.
Migrating a version 2.2 agent involves these general steps:
On the server where the version 2.2 agent is installed, run the version 3.0 agentadmin program with the --migrate option.
To get the version 3.0 agentadmin program, you must download the version 3.0 agent that corresponds to the version 2.2 agent you are migrating. For example, if you are migrating the version 2.2 WebLogic Server/Portal 10 agent, download the version 3.0 WebLogic Server/Portal 10 agent.
On the OpenSSO Enterprise server, run the ssoadm utility to create the new version 3.0 agent configuration in the centralized agent configuration repository.
Therefore, the ssoadm utility must be installed from the ssoAdminTools.zip file on the OpenSSO Enterprise server. For information, see “Installing the OpenSSO Enterprise Utilities and Scripts” in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.
The agentadmin program creates a new deployment directory for the migrated agent, starting with Agent_001. The program does not modify the version 2.2 agent deployment directory files, in case you need these files after you migrate.
The following procedure, the migrated version 3.0 agent instance uses a new agent profile name, which is WL10v3Agent in the examples. The old version 2.2 and new version 3.0 agent profile passwords are the same. If you need to change the password for the new version 3.0 agent profile, see Changing the Password for an Agent Profile.
Login to the server where the version 2.2 agent is installed.
To migrate the agent, you must have write permission to the version 2.2 agent's container files and directories.
Stop the WebLogic Server/Portal 10 container for the version 2.2 agent.
Create a directory to download and unzip the version 3.0 agent. For example: v30agent
Download and unzip the version 3.0 agent that corresponds to the version 2.2 agent you are migrating.
The version 3.0 agents are available from the OpenSSO project site: https://opensso.dev.java.net/public/use/index.html
Change to the version 3.0 agent's /bin directory.
For example, if you downloaded and unzipped the version 3.0 WebLogic Server/Portal 10 agent in the v30agent directory:
cd /v30agent/j2ee_agents/weblogic_v10_agent/bin
On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:
# chmod 755 agentadmin
Run the version 3.0 agentadmin program with the --migrate option. For example:
./agentadmin --migrate
When the agentadmin program prompts you, enter the path to the version 2.2 agent's deployment directory. For example:
... Enter the migrated agent's deployment directory: /opt/j2ee_agents/weblogic_v10_agent ...
In this example, /opt is the directory where you downloaded and upzipped the version 2.2 agent.
The agentadmin program migrates the version 2.2 agent.
After the agentadmin program finishes, set the following properties:
Copy the Agent_nnn/config/OpenSSOAgentConfiguration.properties file to the /bin directory where ssoadm is installed on the OpenSSO Enterprise server.
In OpenSSOAgentConfiguration.properties, add the un-encrypted version 2.2 agent profile password at the end of the file, as follows:
userpassword=v2.2–agent-profile-password
On OpenSSO Enterprise server, create a password file for the OpenSSO Enterprise administrator (amadmin).
This password file is an ASCII text file with only one line specifying the amadmin password in plain text. For example: /tmp/amadminpw
On OpenSSO Enterprise server, run ssoadm to create a new agent configuration in the OpenSSO Enterprise centralized agent configuration repository. For example:
cd tools_zip_root/opensso/bin ./ssoadm create-agent -e / -b WL10v3Agent -t J2EEAgent -u amadmin -f /tmp/amadminpw -D ./OpenSSOAgentConfiguration.properties
In this example:
tools_zip_root is the directory where you unzipped ssoAdminTools.zip.
-e / specifies the specifies the root realm for the agent configuration.
WL10v3Agent is the version 3.0 agent configuration name.
-t J2EEAgent specifies the agent type for J2EE agents.
-u amadmin species the OpenSSO Enterprise administrator.
-f /tmp/amadminpw specifies the path to the administrator password file.
-D ./OpenSSOAgentConfiguration.properties specifies the agent configuration file.
Caution: After you run ssoadm, you might want to delete OpenSSOAgentConfiguration.properties from the /bin directory. This file contains sensitive information, including as the agent profile password, and the original file is maintained on the server where the agent is installed.
Restart the WebLogic Server/Portal 10 container for the migrated agent.
After you migrate the agent, you can manage the new 3.0 agent configuration using the OpenSSO Enterprise Administration Console or the ssoadm utility, as described in Managing the WebLogic Server/Portal 10 Agent.
You can find additional useful information and resources at the following locations:
Sun Services: http://www.sun.com/service/consulting/
Sun Software Products: http://wwws.sun.com/software/
Sun Support Resources http://sunsolve.sun.com/
Sun Developer Network (SDN): http://developers.sun.com/
Sun Developer Services: http://www.sun.com/developers/support/
To obtain accessibility features that have been released since the publishing of this media, consult Section 508 product assessments available from Sun upon request to determine which versions are best suited for deploying accessible solutions.
For information about Sun's commitment to accessibility, visit http://sun.com/access.
Third-party URLs are referenced in this document and provide additional, related information.
Sun is not responsible for the availability of third-party Web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.
If you have questions or issues with OpenSSO Enterprise, contact Sun as follows:
Sun Support Resources (SunSolve) services at http://sunsolve.sun.com/.
This site has links to the Knowledge Base, Online Support Center, and ProductTracker, as well as to maintenance programs and support contact numbers.
The telephone dispatch number associated with your maintenance contract
So that we can best assist you in resolving problems, please have the following information available when you contact support:
If you are requesting help for a problem, please include the following information:
Description of the problem, including when the problem occurs and its impact on your operation
Machine type, operating system version, web container and version, JDK version, and OpenSSO Enterprise version, including any patches or other software that might be affecting the problem
Steps to reproduce the problem
Any error logs or core dumps
Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com/ and click Feedback. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the title page or in the document's URL. For example, the title of this guide is Sun OpenSSO Enterprise Policy Agent 3.0 Guide for WebLogic Server/Portal 10, and the part number is 820-4580-13.
Part Number |
Date |
Description |
---|---|---|
820–4580–13 |
December 11, 2009 |
|
820–4580–12 |
February 19, 2009 |
Added the Configuring Web Services Security for the WebLogic Server/Portal 10 Agent section. |
820–4580–11 |
January 21, 2009 |
Added supported for Oracle® WebLogic Server 10g Release 3 (10.3). |
820–4580–10 |
November 11, 2008 |
Initial release. |
820-4580–05 |
June 25, 2008 |
Early Access (EA) release draft. |