test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Oracle WebLogic Server/Portal 10

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Oracle WebLogic Server/Portal 10

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

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.

Note –

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 Platforms, Compatibility, and Coexistence for the WebLogic Server/Portal 10 Agent

Supported Platforms for the WebLogic Server/Portal 10 Agent

Table 1 Supported Platforms for the WebLogic Server/Portal 10 Agent

Agent For 

Supported Platforms 

WebLogic Server/Portal 10 

  • Solaris OS on SPARC platforms, versions 9 and 10 (32-bit and 64-bit systems)

  • Solaris OS on x86 platforms, versions 9 and 10 (32-bit and 64-bit systems)

  • Red Hat Enterprise Linux Advanced Server 4.0 and 5.0 (32-bit and 64-bit systems)

  • Windows 2008, Standard Edition and Enterprise Edition (32-bit and 64-bit systems)

  • Windows 2003, Standard Edition and Enterprise Edition (32-bit and 64-bit systems)

  • IBM AIX® 5.x and 6.x. (32-bit and 64-bit systems)

Minor versions of these platforms, including updates, service packs, and patches, are also supported. 

Supported Containers for the WebLogic Server/Portal 10 Agent

Table 2 Supported Containers for the WebLogic Server/Portal 10 Agent

Agent For 

Supported Container and Information 

WebLogic Server/Portal 10 

Minor versions of these containers, including updates, service packs, and patches, are also supported. 

Compatibility With Access Manager 7.1 and Access Manager 7 2005Q4

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.

Coexistence With Version 2.2 Policy Agents

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.

Pre-Installation Tasks for the WebLogic Server/Portal 10 Agent

Setting Your JAVA_HOME Environment Variable

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.

Downloading and Unzipping the WebLogic Server/Portal 10 Agent Distribution File

ProcedureTo Download and Unzip the Agent Distribution File

  1. Login to the server where you want to install the agent.

  2. Create a directory to unzip the agent distribution file.

  3. Download and unzip the weblogic_v10_agent_3.zip distribution file from one of the following sites:

    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.

Creating a Password File

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:

ProcedureTo Create a Password File

  1. Create an ASCII text file for the agent profile. For example: /tmp/wl10agentpw

  2. 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

  3. Using a text editor, enter the appropriate password in clear text on the first line in each file.

  4. Secure each password file appropriately, depending on the requirements for your deployment.

Creating an Agent Administrator

An agent administrator can manage agents in OpenSSO Enterprise, including:

ProcedureTo Create a Policy Agent Administrator

  1. Login to OpenSSO Enterprise Console as amadmin.

  2. Create a new agents administrator group:

    1. Click Access Control, realm-name, Subjects, and then Group.

    2. Click New.

    3. In ID, enter the name of the group. For example: agentadmingroup

    4. Click OK.

  3. Create a new agent administrator user and add the agent administrator user to the agents administrator group:

    1. Click Access Control, realm-name, Subjects, and then User.

    2. 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

    3. Click OK.

    4. Click the new agent administrator name.

    5. On the Edit User page, click Group.

    6. Add the agents administrator group from Available to Selected.

    7. Click Save.

  4. Assign read and write access to the agents administrator group:

    1. Click Access Control, realm-name, Privileges and then on the new agents administrator group link.

    2. Check Read and write access to all configured Agents.

    3. Click Save.

Next Steps

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.

Creating an Agent Profile

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:

ProcedureTo Create an Agent Profile in the OpenSSO Enterprise Console

  1. Login to the Console as amAdmin.

  2. Click Access Control, realm-name, Agents, and J2EE.

  3. Under Agent, click New.

  4. In the Name field, enter the name for the new agent profile. For example: WLS10Agent

  5. 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.

  6. 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.)

  7. In the Server URL field, enter the OpenSSO Enterprise server URL.

    For example: http://openssohost.example.com:58080/opensso

  8. In the Agent URL field, enter the URL for the agent application (agentapp).

    For example: http://agenthost.example.com:8090/agentapp

  9. 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.

Installing the WebLogic Server/Portal 10 Agent

Gathering Information to Install the WebLogic Server/Portal 10 Agent

The version 3.0 agentadmin program includes these installation options:

Table 3 Information Required to Install the WebLogic Server/Portal 10 Agent

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:

  • Agent administrator who can create, update, or delete the agent profile. For example: agentadmin

    Important: To use this option, the agent administrator must already exist in OpenSSO Enterprise and must have agent administrative privileges. For information see, Creating an Agent Administrator. If you prefer, you can also specify amadmin as this user.

  • Path to the agent administrator password file. For information, see Creating a Password File.

Applies only to the custom installation option. 

Installing the WebLogic Server/Portal 10 Agent Using the agentadmin Program

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:

Procedure To Install the WebLogic Server/Portal 10 Agent Using the agentadmin Program

  1. 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.

  2. Change to the following directory:

    PolicyAgent-base/bin

  3. On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:

    # chmod 755 agentadmin

  4. Stop the WebLogic Server/Portal 10 container.

  5. Start the agent installation:

    Default installation: ./agentadmin --install

    or

    Custom installation: ./agentadmin --custom-install

    On Windows systems, run the agentadmin.bat program.

  6. 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]:

  7. 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.

  8. After the installation finishes successfully, if you wish, check the installation log file in the following directory:

    PolicyAgent-base/install-logs/audit

  9. Restart the WebLogic Server/Portal 10 container.

    Note –

    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.

Example 1 Sample agentadmin --custom-install for the WebLogic Server/Portal 10 Agent

************************************************************************
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.

After You Finish the Install

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:

Considering Specific Deployment Scenarios for the WebLogic Server/Portal 10 Agent

Installing the Agent on Multiple WebLogic Server/Portal 10 Instances on the Same 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.

Installing the Agent on a Different WebLogic Server/Portal 10 Domain

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.

Post-Installation Tasks for the WebLogic Server/Portal 10 Agent

Required Post-Installation Tasks for the WebLogic Server/Portal 10 Policy Agent

Setting the Java Options on IBM AIX Systems

Perform this task applies only if the WebLogic Server 10 agent is deployed on an IBM AIX system.

ProcedureTo Set the Java Options on IBM AIX Systems

  1. Using a text editor, open the domain-directory/bin/setDomainEnv.sh file for the WebLogic Server 10 instance:

  2. In the setDomainEnv.sh file, find these lines:

    JAVA_OPTIONS="${JAVA_OPTIONS}"
export JAVA_OPTIONS

  3. Change the first line to:

    JAVA_OPTIONS="-DamKeyGenDescriptor.provider=IBMJCE
-DamCryptoDescriptor.provider=IBMJCE
-DamRandomGenProvider=IBMJCE ${JAVA_OPTIONS}"

  4. Save the setDomainEnv.sh file and restart the WebLogic Server 10 instance.

Configuring a WebLogic Server 10 Instance With the Agent classpath and Java Options

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:

where:

The agent environment variable script is called during the server's startup sequence and sets the classpath and Java options for the agent.

ProcedureTo Configure a WebLogic Server 10 Instance With the Agent classpath and Java Options

  1. 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.

  2. 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.

  3. Restart the WebLogic Server 10 instance.

Deploying the Agent Application

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.

ProcedureTo Deploy the Agent Application

Before You Begin

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

  1. 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.

Configuring the Agent Authentication Provider for the WebLogic Server/Portal 10Agent

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.

ProcedureTo Configure the Agent Authentication Provider for WebLogic Server 10

  1. Log in to the WebLogic Server 10 Administration Console.

  2. In the left pane, under Domain Structure and under the host name of the server you are configuring, click Security realms.

  3. In the right pane, click the name of the realm you are configuring.

  4. Click Providers.

  5. Click the Authentication tab.

  6. In the left pane, click Lock & Edit.

  7. In the right pane, click New.

  8. Specify Type as AgentAuthenticator.

  9. Specify Name with a name of your choice.

  10. Click OK.

  11. Click the newly created policy agent authentication provider.

  12. Change the control flag value to OPTIONAL.

  13. Click Save.

  14. Click Providers.

    The Authentication Providers Table appears.

  15. Click Default Authenticator.

  16. Change the control flag to OPTIONAL.

  17. Click Save.

  18. In the left pane, click Activate changes.

  19. Restart the WebLogic Server 10 instance for the changes to take effect.

Default Security Realm

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.

Adding a WebLogic Administrator to the Bypass List for the WebLogic Server/Portal 10 Agent

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.

ProcedureTo Add a WebLogic Administrator to the Bypass List for the WebLogic Server/Portal 10 Agent

  1. Login to the OpenSSO Enterprise Console as amadmin.

  2. 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.

  3. Click Miscellaneous and then Bypass Principal List.

  4. Enter the WebLogic administrator name in New Value and click Add.

  5. Click Save.

Using the ssoadm Utility

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.

Installing the Agent Filter for the WebLogic Server/Portal 10 Agent

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.

ProcedureTo Install the Agent Filter

  1. 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.

  2. Backup the application's web.xml file before modifying the descriptors.

    The backup copy can be useful if you need to uninstall the agent.

  3. Edit the application's descriptors in the web.xml file as follows:

    1. 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.

    2. 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>

  4. Deploy (or redeploy) the application on WebLogic Server/Portal 10.

    The agent filter is added to the application.

Next Steps

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.

Note –

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.

Optional Post-Installation Tasks for the WebLogic Server/Portal 10 Agent

Changing the Password for an Agent Profile

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.

ProcedureTo Change the Password for an Agent Profile

  1. On the OpenSSO Enterprise server:

    1. Login to the Administration Console as amAdmin.

    2. 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.

    3. Enter and confirm the new unencrypted password.

    4. Click Save.

  2. On the server where the WebLogic Server/Portal 10 agent is installed:

    1. In the agent profile password file, replace the old password with the new unencrypted password.

    2. Change to the PolicyAgent-base/bin directory.

    3. 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==

    4. 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==

    5. Restart the WebLogic Server/Portal 10 container.

Creating the Necessary URL Policies

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.

Deploying the Policy Agent Sample Application

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:

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.

Mapping OpenSSO Enterprise Roles to Principal Names

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):

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:

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 (&).

Configuring Web Services Security for the WebLogic Server/Portal 10 Agent

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.

ProcedureTo Configure Web Services Security for the WebLogic Server/Portal 10 Agent

  1. 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.

  2. Stop the WebLogic Server 10 instance.

  3. 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

  4. Add the xmlsec.jar file to the AGENT_CLASSPATH variable:

    1. 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.

    2. In setAgentEnv_weblogic-server-name.sh, add the PolicyAgent-base/lib/xmlsec.jar at the beginning of the AGENT_CLASSPATH variable.

    3. Save the change.

  5. Edit the setDomainEnv.sh script as follows:

    1. Change to the /usr/local/bea/user_projects/domains/base_domain/bin directory.

    2. In setDomainEnv.sh, near the end of the file, find the following lines:

      JAVA_OPTIONS="${JAVA_OPTIONS}"
export JAVA_OPTIONS

    3. 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.

    4. Save the change.

  6. Make the following configuration change in the Security Token Service.

    1. Log in to the OpenSSO Enterprise Console as amadmin.

    2. Click Configuration, Global , then Security Token Service.

    3. Under Signing and Encryption, deselect “is Request Signature Verified”.

    4. Click Save.

  7. Start the WebLogic Server 10 instance.

Managing the WebLogic Server/Portal 10 Agent

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:

Managing a Version 3.0 Agent With a Local Configuration

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:

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).

Caution – Caution –

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.

Uninstalling the WebLogic Server/Portal 10 Agent

Preparing to Uninstall the WebLogic Server/Portal 10 Agent

Removing the Agent Authentication Provider

To remove the Agent Authentication Provider that was configured after the agent was installed, use the WebLogic Server/Portal 10 Administration Console.

ProcedureTo Remove the Agent Authentication Provider

  1. Login to the WebLogic Server/Portal 10 Administration Console.

  2. In the left pane, under Domain Structure and under the host name of the server you are configuring, click Security realms.

  3. In the right pane, click the name of the realm you are configuring.

  4. Click Providers.

  5. Click the Authentication tab.

  6. In the left pane, click Lock & Edit.

  7. In the right pane, specify the Policy Agent Authentication Provider.

  8. Click Delete.

  9. Click Yes.

  10. 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.

Unconfiguring the WebLogic Server/Portal 10 Agent

ProcedureTo Unconfigure the WebLogic Server/Portal 10 Agent

  1. Undeploy any applications protected by the WebLogic Server/Portal 10 agent.

  2. Restore the deployment descriptors of these applications to their original deployment descriptors. (Backup files are useful here if you have them.)

  3. 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.

  4. 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

  5. Ensure that the WebLogic Server/Portal 10 container is stopped.

Uninstalling the WebLogic Server/Portal 10 Agent Using the agentadmin Program

ProcedureTo Uninstall the WebLogic Server/Portal 10 Agent

  1. Change to the following directory:

    PolicyAgent-base/bin

  2. 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.

  3. When prompted, enter the Startup script location.

  4. The uninstall program displays your response and then asks if you want to continue:

    To continue with the uninstallation, select 1 (the default).

Example 2 Uninstallation Sample for the WebLogic Server/Portal 10 Agent

************************************************************************
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.

After You Finish the Uninstall

Installing and Configuring the WebLogic Server/Portal 10 Agent in a Cluster

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.

Installing the WebLogic Server/Portal 10 Agent in a Cluster

In a cluster, you must install the WebLogic Server/Portal 10 agent in this order:

  1. 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.

  2. 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.

Installing the WebLogic Server/Portal 10 Agent on the Administration Server

ProcedureTo Install the WebLogic Server/Portal 10 Agent on the Administration Server

  1. Ensure that the Administration Server is not running.

  2. Install the agent as you would in a stand-alone environment. See Installing the WebLogic Server/Portal 10 Agent.

  3. Configure the agent classpath for the Administration Server. See Configuring a WebLogic Server 10 Instance With the Agent classpath and Java Options.

  4. Start the Administration Server.

  5. Configure the Agent Authentication Provider. See Configuring the Agent Authentication Provider for the WebLogic Server/Portal 10Agent.

Installing the WebLogic Server/Portal 10 Agent on a Managed Server

ProcedureTo Install the WebLogic Server/Portal 10 Agent on a Managed Server

  1. Ensure that the Managed Server is not running.

  2. 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

  3. 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 Tasks for the WebLogic Server/Portal 10 Agent in a Cluster

Table 4 Post-Installation Tasks 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 

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

Deploying the Agent Application for the WebLogic Server/Portal 10 Agent in a Cluster

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.

ProcedureTo Deploy the Agent Application Using the WebLogic Server/Portal 10 Administration Console

  1. Login to the WebLogic Server/Portal 10 Administration Console

  2. Expand the Deployments tab.

  3. Click Lock & Edit.

  4. In the right pane, click Install.

  5. 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.

Configuring Node Manager for the WebLogic Server/Portal 10 Agent in a Cluster

You have the option of starting Managed Servers in a cluster using the WebLogic Server/Portal 10 Node Manager.

ProcedureTo Configure Node Manager for the WebLogic Server/Portal 10 Agent in a Cluster

  1. In the WebLogic Server/Portal 10 Administration Console, expand the Servers node.

  2. Select the node for the server you want to manage with Node Manager.

  3. Configure the agent classpath in Node Manager:

    1. In the Administration Console, select the Configuration tab.

    2. Select the Server Start tab.

    3. Locate the agent classpath for the specific Managed Server as found in setAgentEnv_sever-instance.sh.

    4. 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.

      Tip –

      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.

    5. 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.

    6. Click Save.

    7. Click Activate Changes.

  4. Configure the agent Java options in Server Start.

    1. In the WebLogic Server/Portal 10 Administration Console, select the Configuration tab.

    2. Select the Server Start tab.

    3. Locate the Java options as found in setAgentEnv_sever-instance .sh for the specific Managed Server.

    4. Add the Java options to the Arguments text field as follows:

      -Djava.util.logging.config.file=PolicyAgent-base/config/
OpenSSOAgentLogConfig.properties 
-DLOG_COMPATMODE=Off
      Tip –

      To avoid typing errors, copy and paste the agent Java option entries from the setAgentEnv_managed-sever-instance.sh file.

    5. Click Save.

    6. Click Activate Changes.

Installing and Configuring the WebLogic Server/Portal 10 Agent on WebLogic Portal 10

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:

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.

Installing the Agent on WebLogic Portal 10

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.

Post-Installation Tasks for the WebLogic Server/Portal 10 Agent on WebLogic Portal 10

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. 

See WebLogic Portal 10: Configuring the Agent Filter Modes.

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. 

See Deploying the Agent Application.

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. 

See Changing the Password for an Agent Profile.

Creating the Necessary URL Policies 

Same as for WebLogic Server 10. 

See Creating the Necessary URL Policies.

Deploying the Policy Agent Sample Application 

Same as for WebLogic Server 10. 

See Deploying the Policy Agent Sample Application.

Mapping OpenSSO Enterprise Roles to Principal Names 

Same as for WebLogic Server 10. 

See Mapping OpenSSO Enterprise Roles to Principal Names.

WebLogic Portal 10: Configuring the Agent classpath and Java Options

ProcedureTo Configure the WebLogic Portal 10 Instance With the Agent classpath and Java Options

  1. 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.

  2. 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.

  3. Restart the WebLogic Portal 10 instance.

WebLogic Portal 10: Configuring the Agent Authentication Provider

This section applies only to WebLogic Portal 10.

ProcedureTo Configure the Agent Authentication Provider for WebLogic Portal 10

  1. Log in to the WebLogic Portal 10 Administration Console.

  2. In the left pane, under Domain Structure and the host name of the server you are configuring, click Security realm.

  3. In the right pane, click the name of the realm you are configuring.

  4. Click Providers.

  5. Click the Authentication tab.

  6. In the left pane, click Lock & Edit.

  7. In the right pane, click New.

  8. Specify Type as AgentAuthenticator.

  9. Specify Name with a name of your choice.

  10. Click OK.

  11. Click the newly created policy agent authentication provider.

  12. Change the control flag value to OPTIONAL.

  13. Click Save.

  14. Click Providers.

    The console displays the Authentication Providers Table .

  15. Click SQLAuthenticator

  16. Change the control flag to OPTIONAL.

  17. Click Save.

  18. Click the Providers tab.

  19. Click SAMLAuthenticator

  20. Change the control flag to OPTIONAL.

  21. Click Save.

  22. In the left pane, click Activate changes.

  23. After you are finished, restart the server for the changes to take effect.

Default Security Realm

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.

WebLogic Portal 10: Configuring the Agent Filter Modes

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:

To set the filter modes for the WebLogic Server/Portal 10 agent, use one of these methods:

Note –

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

WebLogic Portal 10: Installing the Agent Filter for the Deployed Application

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

ProcedureTo Install the Agent Filter for the Deployed Application for WebLogic Portal 10

  1. 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.

WebLogic Portal 10: Setting Logout-Related Properties for the Sample Portal

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:

  1. Login to the Console as amadmin.

  2. 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.

  3. 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.

  4. 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.

Creating WebLogic Portal 10 Users in OpenSSO Enterprise

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:

  1. Login to the Console as amadmin.

  2. 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.

  3. 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.

  4. Click Save.

To use the ssoadm utility, set the following agent properties:

All of the user mapping properties are hot-swappable.

Verifying Users in the WebLogic Portal 10 User Repository

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:

  1. Login to the Console as amadmin.

  2. 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.

  3. 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.

  4. 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.

Testing the WebLogic Server/Portal 10 Agent on WebLogic Portal 10

ProcedureTo Test the WebLogic Server/Portal 10 Agent on WebLogic Portal 10

  1. Create a user with the user ID of sean in both the WebLogic Portal Administration Console and OpenSSO Enterprise Console.

  2. 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.

  3. Using a browser, specify the URL of the sample portal. For example:

    http://agent.example.com:7041/groupspace/groupspace.jsp

  4. Login with the user ID of sean.

    The sample portal home page should appear.

  5. Click GS Example Community.

    The portal web page appears.

  6. Click Logout.

Migrating a Version 2.2 WebLogic Server/Portal 10 Policy Agent

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:

  1. 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.

  2. 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.

ProcedureTo Migrate a Version 2.2 Agent:

  1. 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.

  2. Stop the WebLogic Server/Portal 10 container for the version 2.2 agent.

  3. Create a directory to download and unzip the version 3.0 agent. For example: v30agent

  4. 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

  5. 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

  6. On Solaris and Linux systems, set the permissions for the agentadmin program as follows, if needed:

    # chmod 755 agentadmin

  7. Run the version 3.0 agentadmin program with the --migrate option. For example:

    ./agentadmin --migrate

  8. 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.

  9. After the agentadmin program finishes, set the following properties:

    1. In Agent_nnn/config/OpenSSOAgentBootstrap.properties, change:

      com.sun.identity.agents.config.username = new-v3.0-agent-profile-name

      For example:

      com.sun.identity.agents.config.username = WL10v3Agent

  10. Copy the Agent_nnn/config/OpenSSOAgentConfiguration.properties file to the /bin directory where ssoadm is installed on the OpenSSO Enterprise server.

  11. 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

  12. 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

  13. 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.

  14. Restart the WebLogic Server/Portal 10 container for the migrated agent.

Next Steps

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.

Sun Related Information

Additional Sun Resources

You can find additional useful information and resources at the following locations:

Accessibility Features for People With Disabilities

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.

Related Third-Party Web Sites

Third-party URLs are referenced in this document and provide additional, related information.

Note –

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.

How to Report Problems and Provide Feedback

If you have questions or issues with OpenSSO Enterprise, contact Sun as follows:

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:

Sun Welcomes Your Comments

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.

Revision History

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.