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

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

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

Using a text editor, edit the following WebLogic Portal 10 startup script, depending on your platform:
- Solaris and Linux systems: DeployContainer-base/wlserver_10.0/samples/domains/portal/bin/startWeblogic.sh
- Windows systems: DeployContainer-base\wlserver_10.0\samples\domains\portal\bin\startWeblogic.cmd
DeployContainer-base represents the directory where the WebLogic Portal 10 instance is installed.

Add the path of the agent environment variable script to the WebLogic Portal 10 startup script:
- Solaris and Linux systems: After the line, . ${DOMAIN_HOME}/bin/setDomainEnv.sh $*, add:
  . DeployContainer-base/samples/domains/portal/setAgentEnv_${SERVER_NAME}.sh
  Therefore, the startup script would then contain these two lines:
  . ${DOMAIN_HOME}/bin/setDomainEnv.sh $* . DeployContainer-base/samples/domains/portal/setAgentEnv_${SERVER_NAME}.sh
- Windows systems: After the line, call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*, add:
  
  call DeployContainer-base\wlserver_10.0\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd
  
  Therefore, the startup script would then contain these two lines:
```
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*
call DeployContainer-base\wlserver_10.0\samples\domains\portal\setAgentEnv_%SERVER_NAME%.cmd
```
The ${SERVER_NAME} or %SERVER_NAME% variable represents the WebLogic Portal 10 instance that is dynamically replaced.

Restart the WebLogic Portal 10 instance.

WebLogic Portal 10: Configuring the Agent Authentication Provider

This section applies only to WebLogic Portal 10.

To Configure the Agent Authentication Provider for WebLogic Portal 10

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

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

Click Providers.

Click the Authentication tab.

In the left pane, click Lock & Edit.

In the right pane, click New.

Specify Type as AgentAuthenticator.

Specify Name with a name of your choice.

Click OK.

Click the newly created policy agent authentication provider.

Change the control flag value to OPTIONAL.

Click Save.

Click Providers.

The console displays the Authentication Providers Table .

Click SQLAuthenticator

Change the control flag to OPTIONAL.

Click Save.

Click the Providers tab.

Click SAMLAuthenticator

Change the control flag to OPTIONAL.

Click Save.

In the left pane, click Activate changes.

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

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:

SSL_ONLY: If you are using WebLogic Portal 10 for single sign-on (SSO), use the J2EE_POLICY filter mode.
URL_POLICY: If you are using WebLogic Portal 10 to protect URLs such as portal JSP files from being accessed directly, use the ALL filter mode.

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

Use the OpenSSO Enterprise Administration Console:
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. Under Global, add the filter mode to the Agent Filter Mode.
4. Click Save.
or
Use the ssoadm utility to set the com.sun.identity.agents.config.filter.mode property.

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

To Install the Agent Filter for the Deployed Application 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.

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:

Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.

The Console displays the Edit page for the agent profile.
Click Application and then Logout Processing. then set the following fields, depending on your requirements:
- Logout Application Handler: An application-specific map that identifies a handler to be used for logout processing. The corresponding property is com.sun.identity.agents.config.logout.application.handler.
- Logout Application URI: An application-specific map that identifies a request URI that indicates a logout event. The corresponding property is com.sun.identity.agents.config.logout.uri.
- Logout Request Parameter: An application-specific map that identifies a parameter that when present in the HTTP request indicates a logout event. The corresponding property is com.sun.identity.agents.config.logout.request.param.
- Logout Introspect Enabled: Check Enabled to allow the agent to search an HTTP request body to locate the logout parameter. The corresponding property is com.sun.identity.agents.config.logout.introspect.enabled.
- Logout Entry URI: An application-specific map that identifies a URI to be used as an entry point after a successful logout and subsequent successful authentication if applicable. The corresponding property is com.sun.identity.agents.config.logout.entry.uri.
Click Save.

To use the ssoadm utility, set the logout-related agent properties. For example:

com.sun.identity.agents.config.logout.application.handler[] = 
com.sun.identity.agents.config.logout.uri[groupspace] = /groupspace/communityFiles/shell/logout.jsp
com.sun.identity.agents.config.logout.request.param[groupspace] = logout
com.sun.identity.agents.config.logout.introspect.enabled = true
com.sun.identity.agents.config.logout.entry.uri[groupspace] = /groupspace/groupspace.jsp

All of these logout-related properties are hot-swappable.

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:

Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.

The Console displays the Edit page for the agent profile.
Click Global and then User Mapping, and then set the following fields, depending on your requirements:
- User Mapping Mode: Mechanism the agent uses to determine the user ID (HTTP_HEADER, PROFILE_ATTRIBUTE, SESSION_PROPERTY, or USER_ID)
- User Attribute Name: Name of the attribute that contains the user ID. The corresponding property is com.sun.identity.agents.config.user.attribute.name.
- User Principal Flag: Check Enabled to use the principal instead of only the user ID for authenticating the user. The corresponding property is com.sun.identity.agents.config.user.principal.
- User Token Name: Session property name for the user ID of the authenticated user in the session. The corresponding property is com.sun.identity.agents.config.user.token.
Click Save.

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

com.sun.identity.agents.config.user.mapping.mode[]
com.sun.identity.agents.config.user.attribute.name
com.sun.identity.agents.config.user.principal
com.sun.identity.agents.config.user.token

All of the user mapping properties are hot-swappable.

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:

Login to the Console as amadmin.
Under Access Control, realm-name, Agents, and J2EE, click the name of the agent profile you want to update.

The Console displays the Edit page for the agent profile.
Click Application, and then set the Custom Verification Handler, which specifies an application specific verification handler to validate the user credentials with the local repository. The corresponding property is com.sun.identity.agents.config.verification.handler.
Click Save.

To use the ssoadm utility, set the com.sun.identity.agents.config.verfication.handler property. For example:

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

This property is hot-swappable.

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

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

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

If the agent filter mode (com.sun.identity.agents.config.filter.mode property) is set to ALL, create the appropriate OpenSSO Enterprise policies for the portal URLs where sean is the user.

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

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

Click GS Example Community.

The portal web page appears.

Click Logout.