Sun Java System Access Manager Policy Agent 2.2 Guide for BEA WebLogic Server/Portal 9.2

Previous: Appendix C Troubleshooting a J2EE Agent Deployment in Policy Agent 2.2

Appendix D Installation and Configuration Specific to BEA WebLogic Portal 9.2

The intent of this appendix is to focus on BEA WebLogic Portal 9.2. This appendix illustrates the flow of tasks for installing and configuring Agent for BEA WebLogic Server/Portal 9.2 specifically on BEA WebLogic Portal 9.2 (not BEA WebLogic Server 9.2).

The installation and configuration of this agent is complex. Since some differences exist in configuring BEA WebLogic Server 9.2 and BEA WebLogic Portal 9.2, providing tasks and examples that are specific to BEA WebLogic Portal 9.2 helps keep the focus on the portal server.

In this appendix, at times you are directed to other sections of this document for information and at times information is repeated in this section from other sections. Generally, when information is repeated, it is integrated with more specific information or examples.

Note –

This appendix provides examples of how to protect the sample portal. By default, the sample portal is named groupspace. Therefore, groupspace is the name of the portal referred to throughout this appendix. All the same, you can protect multiple portals with a single BEA WebLogic Portal 9.2 instance. For each portal you configure, ensure that you use the correct portal application name.

Installing Policy Agent 2.2 on BEA WebLogic Portal 9.2

For the installation process, follow the steps as described in Chapter 3, Installing Policy Agent 2.2 for BEA WebLogic Server/Portal 9.2. However, see the example installation interaction that follows in this section for an example that is specific to BEA WebLogic Portal 9.2. Notice in the interaction, the following two portal-specific 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 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

As the two preceding prompt examples indicate, to install this agent on BEA WebLogic Portal 9.2, provide a response of true to the first of these prompts, which in effect invokes the second prompt. For the second prompt, provide the name of the application to be protected. For the example used in this appendix, the sample portal is the application to be protected. Again, the default portal is named groupspace.

Notice that a summary of the agent installation is included at the end of this example interaction. However, the installation summary is described more thoroughly in Summary of a J2EE Agent Installation in Policy Agent 2.2. See that section if you would like a more thorough explanation of the installation summary.

************************************************************************
Welcome to the Access Manager Policy Agent for BEA WebLogic 9.2 Platform. If
the Policy Agent is used with Federation Manager services, User needs to
enter information relevant to Federation Manager.

************************************************************************


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/mydomain/startWebLogic.sh]: /usr/local/
bea/weblogic92/samples/domains/portal/startWebLogic.sh


Enter the name of the WebLogic Server instance secured by the agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the WebLogic Server instance name [myserver]: portalServer


Enter the fully qualified host name of the server where Access Manager
Services are installed.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Host: amHost.example.com


Enter the port number of the Server that runs Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services port [80]: 58080


Enter http/https to specify the protocol used by the Server that runs Access
Manager services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Protocol [http]: 


Enter the Deployment URI for Access Manager Services.
[ ? : Help, < : Back, ! : Exit ]
Access Manager Services Deployment URI [/amserver]: 


Enter the fully qualified host name on which the Application Server
protected by the agent is installed. 
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Host name: agentHost.example.com


Enter the WebLogic home directory
[ ? : Help, < : Back, ! : Exit ]
Enter the WebLogic home directory [/usr/local/bea/weblogic92]: 


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 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 preferred port number on which the application server provides its
services. 					
[ ? : Help, < : Back, ! : Exit ]
Enter the port number for Application Server instance [80]: 7041


Select http or https to specify the protocol used by the Application server
instance that will be protected by Access Manager Policy Agent.
[ ? : Help, < : Back, ! : Exit ]
Enter the Preferred Protocol for Application Server instance [http]: 


Enter the deployment URI for the Agent Application. This Application is used
by the agent for internal housekeeping.
[ ? : Help, < : Back, ! : Exit ]
Enter the Deployment URI for the Agent Application [/agentapp]: 


Enter a valid Encryption Key.
[ ? : Help, < : Back, ! : Exit ]
Enter the Encryption Key [VBjnVlCEgfez/ivS34ALv0c41Ym7gWyX]: 


Enter a valid Agent profile name. Before proceeding with the agent
installation, please ensure that a valid Agent profile exists in Access
Manager.
[ ? : Help, < : Back, ! : Exit ]
Enter the Agent Profile name: exampleagentportal


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: /export/tmp/portalpasswordfile


Enter true if the Agent is being installed on the same instance of Application
Server on which Access Manager is deployed. Enter false if that is not the
case.
[ ? : Help, < : Back, ! : Exit ]
Are the Agent and Access Manager installed on the same instance of
Application Server ? [false]: 


-----------------------------------------------
SUMMARY OF YOUR RESPONSES
-----------------------------------------------
Startup script location :
/usr/local/bea/weblogic92/samples/domains/portal/startWebLogic.sh

WebLogic Server instance name : portalServer 
Access Manager Services Host : amHost.example.com 
Access Manager Services Port : 58080 
Access Manager Services Protocol : http 
Access Manager Services Deployment URI : /amserver 
Agent Host name : agentHost.example.com 
WebLogic home directory : /usr/local/bea/weblogic92 
Agent Installed on Portal domain : true 
Deployment URI for the portal Application : /groupspace 
Application Server Instance Port number : 7041 
Protocol for Application Server instance : http 
Deployment URI for the Agent Application : /agentapp 
Encryption Key : VBjnVlCEgfez/ivS34ALv0c41Ym7gWyX 
Agent Profile name :exampleagentportal 
Agent Profile Password file name : /export/tmp/portalpasswordfile 
Agent and Access Manager on same application server instance : false 

Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]: 

...
...
SUMMARY OF AGENT INSTALLATION
-----------------------------
Agent instance name: agent_001
Agent Configuration file location:
PolicyAgent-base/j2ee_agents/am_wl92_agent/agent_001/config/
AMAgent.properties
Agent Audit directory location:
PolicyAgent-base/j2ee_agents/am_wl92_agent/agent_001/logs/audit
Agent Debug directory location:
PolicyAgent-base/j2ee_agents/am_wl92_agent/agent_001/logs/debug


Install log file location:
PolicyAgent-base/j2ee_agents/am_wl92_agent/logs/audit/install.log

Thank you for using Access Manager Policy Agent

Once the installation is complete, perform the applicable installation-related tasks described in Implications of Specific Deployment Scenarios in Agent for BEA WebLogic Server/Portal 9.2.

Post-Installation of Policy Agent 2.2 on BEA WebLogic Portal 9.2

This section provides and directs you to post-installation information and instructions applicable to BEA WebLogic Portal 9.2. Many of the instructions are the same for BEA WebLogic Server 9.2 and BEA WebLogic Portal 9.2 When the information is the same, you are referred back to Chapter 4, Post-Installation Tasks of Policy Agent 2.2 for BEA WebLogic Server/Portal 9.2. When information is specific to BEA WebLogic Portal 9.2, it is provided in this section.

This post-installation section addresses the following topics:

Portal: Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2

After you have performed the applicable installation-related tasks described in Implications of Specific Deployment Scenarios in Agent for BEA WebLogic Server/Portal 9.2, perform the common post-installation steps for all J2EE agents.

For information on these steps, refer to Common Post-Installation Steps for All J2EE Agents in Policy Agent 2.2.

Configuring BEA WebLogic Portal 9.2 Instance With Agent Classpath and Agent Java Options

The basic steps involved in this task are the same for BEA WebLogic Portal 9.2 and for BEA WebLogic Server 9.2. The instructional information that follows consists of the most important information required to configure agent classpath and agent Java options specifically for BEA WebLogic Portal 9.2. For complete instructions, see Configuring BEA WebLogic Server/Portal 9.2 Instance With Agent Classpath and Agent Java Options.

To Configure BEA WebLogic Portal 9.2 Instance With Agent Classpath and Agent Java Options

Access and edit the appropriate start up script in the manner illustrated by the following examples:

where DeployContainer-base represents the directory in which BEA WebLogic Server/Portal 9.2 was installed.

UNIX Platforms

The file to access:

DeployContainer-base/weblogic92/samples/domains/portal/bin/startWeblogic.sh

The information to be added:

. DeployContainer-base/samples/domains/portal/bin/setAgentEnv_${SERVER_NAME}.sh

The line after which to add the information:

. ${DOMAIN_HOME}/bin/setDomainEnv.sh $*

Windows Platforms

The file to access:

DeployContainer-base\weblogic92\samples\domains\portal\bin\startWeblogic.cmd

The information to be added:

call DeployContainer-base\weblogic92\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd

The line after which to add the information:

call. ${DOMAIN_HOME}\bin\setDomainEnv.sh $*

Portal: Configuring the Agent Authentication Provider on Agent for BEA WebLogic Server/Portal 9.2

The task describing how to configure the agent Authentication Provider specifically for this agent on BEA WebLogic Portal 9.2 follows subsequently. However, if you want more background information about the task, seeConfiguring the Agent Authentication Provider on Agent for BEA WebLogic Server/Portal 9.2.

To Configure the Agent Authentication Provider Specifically for BEA WebLogic Portal 9.2

In the left pane, under Domain Structure and under 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 the Providers tab.

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 the Providers tab.

The Authentication Providers Table appears.

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.

The Default Security Realm

If you choose to 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.

Portal: Adding a WebLogic Administrator to the Bypass List of Agent for BEA WebLogic Server/Portal 9.2

For information on this topic, see Adding a WebLogic Administrator to the Bypass List of Agent for BEA WebLogic Server/Portal 9.2.

Configuring the Agent Filter Modes Applicable to BEA WebLogic Portal 9.2

The agent filter modes that apply to Agent for BEA WebLogic Server/Portal 9.2 differ between BEA WebLogic Portal 9.2 and BEA WebLogic Server 9.2. The key difference being that SSL_ONLY and URL_POLICY are not applicable to BEA WebLogic Portal 9.2.

Note –

If you are using BEA WebLogic Portal 9.2 solely to apply SSO, you cannot use the SSL_ONLY filter mode. The correct mode to use in this scenario is the J2EE_POLICY mode.

Similarly, if you are using the BEA WebLogic Portal 9.2 to protect URLs, such as portal JSP files, from being accessed directly, you cannot use the URL_POLICY filter mode. The correct mode to use in this scenario is the ALL mode.

These settings might seem counterintuitive, but they are the correct modes given that the SSL_ONLY mode and the URL_POLICY mode are inoperable with BEA WebLogic Portal 9.2.

The following task describes how to set the appropriate properties in the J2EE agent AMAgent.properties configuration file. The instructions that follow describe how to set the filter mode to J2EE_POLICY mode and ALL mode. The instructions do not include information about setting the filter mode to none, which is set in the same manner for both BEA WebLogic Portal 9.2 and BEA WebLogic Server 9.2 as described in J2EE Agent Filter Modes.

To Configure Agent Filter Modes Applicable to BEA WebLogic Portal 9.2

Using the text editor of your choice, access the J2EE agent AMAgent.properties configuration file.

The following path serves as an example of the path to the J2EE agent AMAgent.properties configuration file:
PolicyAgent-base/agent_001/AMAgent.properties

Edit the filter mode to match your site's requirements.

Therefore, edit the following property:
```
com.sun.identity.agents.config.filter.mode
```
The following alternatives indicate how to set the property to J2EE_POLICY or All.
- To set the value of the property to J2EE_POLICY.
```
com.sun.identity.agents.config.filter.mode = J2EE_POLICY
```
  This setting is appropriate if your site is using the BEA WebLogic Portal 9.2 instance solely for enabling SSO.
- To set the value of the property to All.
  
  This setting is appropriate if the BEA WebLogic Portal 9.2 instance is to be protected by an Access Manager policy.
```
com.sun.identity.agents.config.filter.mode = ALL
```
  Note –
  When creating an Access Manager policy to protect the BEA WebLogic Portal 9.2 instance, define the policy to give permission to only public portal URLs, such as the following:
```
http://agentHost.example.com:7041/groupspace/
```
```
http://agentHost.example.com:7041/groupspace/groupspace.jsp
```

Next Steps

Since forthcoming tasks require you to configure the J2EE agent AMAgent.properties configuration file, you can keep the file open at this time.

Setting Logout-Related Properties for the Sample Portal

Agent for BEA WebLogic Server/Portal 9.2 comes with a sample portal named groupspace. The task that follows involves configuring logout-related properties in the J2EE agent AMAgent.properties configuration file for the sample portal.

To Set Logout-Related Properties for the Sample Portal

(Conditional) If the J2EE agent AMAgent.properties configuration file is not currently open, access it now using the text editor of your choice.

Set the properties related to logging out.

As indicated in the substeps that follow, locate the respective properties in the file and set them as shown.
1. Set the following property as such:
  
  com.sun.identity.agents.config.logout.uri[groupspace] = /groupspace/communityFiles/shell/logout.jsp
2. Set the following property as such:
  
  com.sun.identity.agents.config.logout.request.param[groupspace] = logout
3. Set the following property as such:
  
  com.sun.identity.agents.config.logout.introspect.enabled = true

(Conditional) If you are finished editing the J2EE agent AMAgent.properties configuration file, save and close the file.

Verifying Users in the BEA WebLogic Portal 9.2 User Repository

You can further enforce security by configuring the agent to verify users in the BEA WebLogic Portal 9.2 user repository. This is accomplished by editing the J2EE agent AMAgent.properties configuration file as explained in the following task description.

To Verify Users in the BEA WebLogic Portal 9.2 User Repository

Before You Begin

If the J2EE agent AMAgent.properties configuration file is not currently open, access it now using the text editor of your choice. Also, once you complete this task, if you are then finished editing the J2EE agent AMAgent.properties configuration file, save and close the file.

Locate the respective property in the file and set it in a manner similar to that shown.

The following example illustrates how this property is set for the sample portal:

com.sun.identity.agents.config.verification.handler[groupspace] =
 com.sun.identity.agents.weblogic.v92.AmWLPortalVerificationHandler

Portal: Installing the Agent Filter for the Deployed Application on Agent for BEA WebLogic Server/Portal 9.2

The instructional information that follows consists of the most important information required for the configuration of the web.xml file. For a more thorough explanation, see Installing the Agent Filter for the Deployed Application on Agent for BEA WebLogic Server/Portal 9.2.

As consistent with the rest of this appendix, this section specifies the sample portal as the application whose deployment descriptor is modified.

The following is a conceivable location for the web.xml file for the sample portal:

/usr/local/bea/weblogic92/samples/portal/portalApp/groupspaceSampleWeb/WEB-INF

To Install the Agent Filter for the Deployed Application Specifically for BEA WebLogic Portal 9.2

Add the <filter> elements in the deployment descriptor by specifying the <filter> and the <filter-mapping> elements immediately following the description element of the <web-app> element in the descriptor web.xml.

The following is a sample web.xml descriptor with the <filter> and the <filter-mapping> elements added:

<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>
   </filter-mapping>
   
</web-app>

Portal: Deploying the Agent Application

For BEA WebLogic Portal 9.2, deploy the Agent application at this point in the configuration by following the steps in Deploying the Agent Application of Agent for BEA WebLogic Server/Portal 9.2.

About Portal Users in BEA WebLogic Portal 9.2 Administrator

Before configuring the agent, you should create the same users in Access Manager as exist in the BEA WebLogic Portal 9.2. If users in Access Manager have different names than the names in BEA WebLogic Portal 9.2, you must establish user mapping by setting the user mapping properties in the J2EE agent AMAgent.properties configuration file. See User Mapping Properties for more information.

Testing the Deployment of Policy Agent 2.2 on BEA WebLogic Portal 9.2

The following instructions lead you through a variety of broadly-defined tasks that serve as a test of the basic functionality of this deployment, which includes the following software components:

BEA WebLogic Portal 9.2
Access Manager
Agent for BEA WebLogic Server/Portal 9.2

To Test the Deployment of Policy Agent 2.2 on BEA WebLogic Portal 9.2

Create a user with user ID of chris in both BEA WebLogic Portal Administration Console and in Access Manager Console.

(Conditional) If the agent filter mode is set to ALL, create the proper Access Manager policies for the portal URLs where chris is the user.

Therefore, perform the preceding instructions in this step if the following property from J2EE agent AMAgent.properties configuration file is set as such:
```
com.sun.identity.agents.config.filter.mode = ALL
```

Using a browser, enter and submit the URL of the sample portal.

The following URL is a conceivable URL for the sample portal.
```
http://agentHost.example.com:7041/groupspace/groupspace.jsp
```

Click GS Example Community.

The portal web page appears.

Click Logout.

Previous: Appendix C Troubleshooting a J2EE Agent Deployment in Policy Agent 2.2