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

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.

To Set the Java Options on IBM AIX Systems

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

In the setDomainEnv.sh file, find these lines:

JAVA_OPTIONS="${JAVA_OPTIONS}"
export JAVA_OPTIONS

Change the first line to:

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

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

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:

Solaris and Linux systems: setAgentEnv_server-instance.sh
Windows systems: setAgentEnv_server-instance.cmd

where:

domain-directory represents the domain name associated with the WebLogic Server 10 instance. The default path name of domain-directory is:

/usr/local/bea/user_projects/domains/domain-name
server-instance represents the WebLogic Server 10 instance name entered during installation. For example: server1 or server2.

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

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

Using a text editor, edit the following WebLogic Server 10 instance startup script, depending on your platform:
- Solaris and Linux systems: domain-directory/bin/startWebLogic.sh
- Windows systems: domain-directory\bin\startWebLogic.cmd
domain-directory represents the domain name associated with the WebLogic Server 10 instance.

Add the path of the agent environment variable script to the WebLogic Server 10 startup script:
- Solaris and Linux systems: After the line, . ${DOMAIN_HOME}/bin/setDomainEnv.sh $*, add the path:
  . domain-directory/setAgentEnv_${SERVER_NAME}.sh
  For example, for a domain directory named base_domain:
  . /usr/local/bea/user_projects/domains/base_domain/setAgentEnv_${SERVER_NAME}.sh
  Therefore, the startup script would then contain these two lines:
  . ${DOMAIN_HOME}/bin/setDomainEnv.sh $* . /usr/local/bea/user_projects/domains/base_domain/setAgentEnv_${SERVER_NAME}.sh
- Windows systems: After the line, call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*, add the path:
  
  call "domain-directory\setAgentEnv_%SERVER_NAME%.cmd"
  
  For example, for a domain directory named base_domain:
  
  call "C:\bea\user_projects\domains\base_domain\setAgentEnv_%SERVER_NAME%.cmd"
  
  Therefore, the startup script would then contain these two lines:
```
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*
call "C:\bea\user_projects\domains\base_domain\setAgentEnv_%SERVER_NAME%.cmd"
```
The ${SERVER_NAME} or %SERVER_NAME% variable represents the WebLogic Server 10 instance and is dynamically replaced when the script is executed.

Restart the WebLogic Server 10 instance.

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.

To 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

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.

To Configure the Agent Authentication Provider for WebLogic Server 10

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

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

Click Providers.

Click the Authentication tab.

In the left pane, click Lock & Edit.

In the right pane, click New.

Specify Type as AgentAuthenticator.

Specify Name with a name of your choice.

Click OK.

Click the newly created policy agent authentication provider.

Change the control flag value to OPTIONAL.

Click Save.

Click Providers.

The Authentication Providers Table appears.

Click Default Authenticator.

Change the control flag to OPTIONAL.

Click Save.

In the left pane, click Activate changes.

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

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.

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

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

The Console displays the Edit page for the agent profile.

Click Miscellaneous and then Bypass Principal List.

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

Click Save.

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.

To Install the Agent Filter

Ensure that the application you want to protect is not currently deployed on WebLogic Server/Portal 10.

If the application is deployed, undeploy it before continuing.

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

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

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

Set the <DOCTYPE> element as shown in the following example:

<!DOCTYPE web-app version="2.4"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

Note: WebLogic Server/Portal 10 supports the Java Servlet specification version 2.4. Version 2.4 is fully backward compatible with version 2.3. Therefore, all existing servlets should work without modification or recompilation.

Add the <filter> elements to the deployment descriptor.

Specify the agent filter as the first <filter> element and the agent filter mapping as the first <filter-mapping> element. For example:

<web-app>
...
    <filter>
        <filter-name>Agent</filter-name>
        <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
    </filter>
    <filter-mapping>
        <filter-name>Agent</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>INCLUDE</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>ERROR</dispatcher>
    </filter-mapping>
...
</web-app>

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

The agent filter is added to the application.

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.

To Change the Password for an Agent Profile

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.

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:

Single sign-on (SSO)
Web-tier declarative security
Programmatic security
URL policy evaluation
Session, policy, and profile attribute fetch

The sample application can be especially useful if you are writing a custom agent application.

After you install the WebLogic Server/Portal 10 agent, the sample application is available as:

PolicyAgent-base/sampleapp/dist/agentsample.ear

For information about compiling, deploying, and running the sample application, see the readme.txt file in the /sampleapp directory.

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

weblogic.xml
weblogic-ejb-jar.xml

OpenSSO Enterprise roles are represented in UUIDs. Ensure that the keys in the mapping are UUIDs corresponding to your site's OpenSSO Enterprise installation. A UUID for a OpenSSO Enterprise role is mapped to the respective principal name in the weblogic.xml or weblogic-ejb-jar.xml file. Specifically, the principal name is located within the <principal-name> element.

To configure the WebLogic Server/Portal 10 agent to use privileged attribute mapping. use one of these methods:

In the OpenSSO Enterprise Administration Console:
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 Application, click Privilege Attributes Processing.
4. For Enable Privileged Attribute Mapping, check Enabled.
5. In the Privileged Attribute Mapping list, Add the mapping entries.
6. When you are finished, click Save.
or

Use the ssoadm utility to set the these properties:

com.sun.identity.agents.config.privileged.attribute.mapping.enable=true
com.sun.identity.agents.config.privileged.attribute.mapping[id=manager,
ou=group,dc=example,dc=com]=am_manager_role

Starting with WebLogic Server 9.0, a principal name in the weblogic.xml file or weblogic-ejb-jar.xml file must use the NMTOKEN format, which is mandated by the corresponding schema files. Access Manager UUIDs include the following characters: equal sign (=), comma (,), and ampersand (&).

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.

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

Perform the general steps, as described in Web Services Security Support for J2EE Agents in Policy Agent 3.0 in Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

Stop the WebLogic Server 10 instance.

Copy the xmlsec.jar file from the OpenSSO Enterprise server deployment to the PolicyAgent-base/lib directory.

PolicyAgent-base is AgentHome/j2ee_agents/weblogic_v10_agent, where AgentHome is where you unzipped the agent distribution file.

For example: /opt/j2ee_agents/weblogic_v10_agent/lib

Add the xmlsec.jar file to the AGENT_CLASSPATH variable:
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.

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.

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.

Start the WebLogic Server 10 instance.