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

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

Appendix D Installation and Configuration of WebLogic Portal 10

This appendix describes the installation and configuration of the agent on WebLogic Portal 10 (not WebLogic Server 10), including:

Note –

This appendix provides examples of 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.

Installation of the Agent on WebLogic Portal 10

For the installation process, follow the steps as described in Chapter 3, Installing the Policy Agent for WebLogic Server/Portal 10. However, see the sample installation interaction in this section for an example that is specific to WebLogic Portal 10. 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 WebLogic Portal 10, 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 10 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/wlserver_10.0/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/wlserver_10.0]: 


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/wlserver_10.0/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/wlserver_10.0 
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/Agent_001/config/
AMAgent.properties
Agent Audit directory location:
PolicyAgent-base/Agent_001/logs/audit
Agent Debug directory location:
PolicyAgent-base/Agent_001/logs/debug


Install log file location:
PolicyAgent-base/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 for the WebLogic Server/Portal 10 Agent.

Post-Installation Tasks for the Agent on WebLogic Portal 10

This section provides and directs you to post-installation information and instructions applicable to WebLogic Portal 10. Many of the instructions are the same for WebLogic Server 10 and WebLogic Portal 10 When the information is the same, you are referred back to Chapter 4, Post-Installation Tasks for the WebLogic Server/Portal 10 Agent. When information is specific to WebLogic Portal 10, 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 for the WebLogic Server/Portal 10 Agent, perform the common post-installation steps for all J2EE agents.

For information on these steps, refer to Post-Installation Steps for the WebLogic Server/Portal 10 Agent.

Configuring WebLogic Portal 10 Instance With Agent Classpath and Agent Java Options

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

To Configure WebLogic Portal 10 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 WebLogic Server/Portal 10 was installed.
- UNIX Platforms
  
  The file to access:
  
  DeployContainer-base/wlserver_10.0/samples/domains/portal/bin/startWeblogic.sh
  
  The information to be added:
  
  DeployContainer-base/samples/domains/portal/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\wlserver_10.0\samples\domains\portal\bin\startWeblogic.cmd
  
  The information to be added:
  
  call DeployContainer-base\wlserver_10.0\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd
  
  The line after which to add the information:
  
  call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*

Portal: Configuring the Agent Authentication Provider on Agent for WebLogic Portal 10

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

To Configure the Agent Authentication Provider Specifically for WebLogic Portal 10

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

Click the Authentication tab.

In the left pane, click Lock & Edit.

In the right pane, click New.

Specify Type as AgentAuthenticator.

Specify Name with a name of your choice.

Click OK.

Click the newly created policy agent authentication provider.

Change the control flag value to OPTIONAL

Click Save.

Click Providers.

The Authentication Providers Table appears.

Click SQLAuthenticator

Change the control flag to OPTIONAL.

Click Save.

Click the Providers tab.

Click SAMLAuthenticator

Change the control flag to OPTIONAL.

Click Save.

In the left pane, click Activate changes.

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

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 WebLogic Server/Portal 10

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

Configuring the Agent Filter Modes Applicable to WebLogic Portal 10

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

Note –

If you are using WebLogic Portal 10 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 WebLogic Portal 10 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 WebLogic Portal 10.

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 WebLogic Portal 10 and WebLogic Server 10 as described in J2EE Agent Filter Modes.

To Configure Agent Filter Modes Applicable to WebLogic Portal 10

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 WebLogic Portal 10 instance solely for enabling SSO.
- To set the value of the property to All.
  
  This setting is appropriate if the WebLogic Portal 10 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 WebLogic Portal 10 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 WebLogic Server/Portal 10 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 WebLogic Portal 10 User Repository

You can further enforce security by configuring the agent to verify users in the WebLogic Portal 10 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 WebLogic Portal 10 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.v10.AmWLPortalVerificationHandler
```

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

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 WebLogic Server/Portal 10 Agent.

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/wlserver_10.0/samples/portal/portalApp/groupspaceSampleWeb/WEB-INF

To Install the Agent Filter for the Deployed Application Specifically for WebLogic Portal 10

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.

Portal: Deploying the Agent Application

For WebLogic Portal 10, deploy the Agent application at this point in the configuration by following the steps in Deploying the Agent Application.

About Portal Users in WebLogic Portal 10 Administrator

Before configuring the agent, you should create the same users in Access Manager as exist in the WebLogic Portal 10. If users in Access Manager have different names than the names in WebLogic Portal 10, 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 WebLogic Portal 10

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:

WebLogic Portal 10
Access Manager
Agent for WebLogic Server/Portal 10

To Test the Deployment of Policy Agent 2.2 on WebLogic Portal 10

Create a user with user ID of chris in both 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