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

Previous: Chapter 3 Installing the Policy Agent for WebLogic Server/Portal 10
Next: Chapter 5 Installing and Configuring the WebLogic Server/Portal 10 Agent in a Cluster

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

This chapter describes post-installation considerations and tasks, including:

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

Once you have installed the WebLogic Server/Portal 10 agent, complete the following agent-specific steps:

Configuring WebLogic Server/Portal 10 Instance With the Agent Classpath and Agent Java Options

This section applies to both WebLogic Server 10 and WebLogic Portal 10 and provides a lot of background information and explanation. However, if you are interested only in the key information required to configure the agent classpath and agent Java options, see Configuring WebLogic Portal 10 Instance With Agent Classpath and Agent Java Options.

During agent installation, the installer creates an environment variable script in domain-directory named as follows:

UNIX Platforms: setAgentEnv_server-instance.sh
Windows Platforms: setAgentEnv_server-instance.cmd

domain-directory

a place holder that represents the domain name associated with the WebLogic Server/Portal 10 instance. The following is the default full path name of domain-directory:

/usr/local/bea/user_projects/domains/mydomain

server-instance

a place holder that represents the WebLogic Server/Portal 10 instance name entered during installation. For example Server1 or Server2.

The agent environment variable script, setAgentEnv_server-instance.sh, is an environment script which is called up during the server's start up sequence.

This agent environment variable script is associated with Agent for WebLogic Server/Portal 10 and is used to set up the environment for the agent. This script is called up during the server's start up sequence and sets the classpath and Java options for the agent. The following instructions describe how to configure the WebLogic Server/Portal 10 start up script to call the agent environment variable script.

To Configure WebLogic Server/Portal 10 Instance With Agent Classpath and Agent Java Options

Note –

This step is required. Agent for WebLogic Server/Portal 10 will not work if the agent startup script is added incorrectly to the WebLogic Server/Portal 10 instance start up script. If the agent startup script does not get invoked properly from the WebLogic Server/Portal 10 start up script, WebLogic Server/Portal 10 will not function appropriately after the Agent Authenticator is set.

To the WebLogic Server/Portal 10 instance start up script, add the path of the agent environment variable script.

The substeps that follow provide the details of adding the agent-environment-variable-script path to the WebLogic Server/Portal 10 start up script.

Note –
Throughout this guide scripting files apply to both UNIX platforms and Windows platforms even when the script for Windows platforms is not expressly mentioned. The difference is that scripts for UNIX platforms have the .sh extension while scripts for Windows platforms have the .cmd extension.
1. Using the text editor of your choice, access the applicable WebLogic Server/Portal 10 instance start up script.
  
  The start up script is available as follows:
  
  UNIX Platforms
  
  domain-directory/bin/startWebLogic.sh
  
  Windows Platforms
  
  domain-directory\bin\startWebLogic.cmd
  
  where domain-directory represents the domain name associated with the WebLogic Server/Portal 10 instance.
  
  Caution –
  Ensure that you access the startWebLogic file in the respective bin directory.
2. After the line, . ${DOMAIN_HOME}/bin/setDomainEnv.sh $*, add the path to the agent environment variable script.
  
  The following examples, for both UNIX platforms and Windows platforms, demonstrate the process of adding the agent-environment-variable-script path by specifying the fully qualified path. See the important explanation that follows these examples about the variables ${SERVER_NAME} and %SERVER_NAME%.
  - UNIX Platforms
    . domain-directory/setAgentEnv_${SERVER_NAME}.sh
    For this scenario, the following is a conceivable line if the domain directory is named mydomain:
    . /usr/local/bea/user_projects/domains/mydomain/setAgentEnv_${SERVER_NAME}.sh
    Therefore, in this scenario, the start up script would then, amongst other lines, contain these two lines as shown:
    . ${DOMAIN_HOME}/bin/setDomainEnv.sh $* . /usr/local/bea/user_projects/domains/mydomain/setAgentEnv_${SERVER_NAME}.sh
  - Windows Platforms
    call "domain-directory\setAgentEnv_%SERVER_NAME%.cmd"
    For this scenario, the following is a conceivable line if the domain directory is named mydomain:
    call "C:\bea\user_projects\domains\mydomain\setAgentEnv_%SERVER_NAME%.cmd"
    Therefore, in this scenario, the start up script would then contain, amongst other lines, these two lines as shown:
```
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd" %*
call "C:\bea\user_projects\domains\mydomain\setAgentEnv_%SERVER_NAME%.cmd"
```
  ${SERVER_NAME} or %SERVER_NAME%
  
  a variable for the WebLogic Server/Portal 10 instance that is dynamically replaced. Do not replace or modify this variable. Therefore, ensure that the variable is entered and remains character for character as ${SERVER_NAME} for UNIX platforms and %SERVER_NAME% for Windows platforms.

Restart the WebLogic Server/Portal 10 instance.

Caution –
Restarting the WebLogic Server/Portal 10 instance at this point is necessary. Otherwise, upcoming tasks will fail.

Deploying the Agent Application

If you are configuring WebLogic Server 10, deploy the Agent Application at this point in the configuration process.

If you are configuring WebLogic Portal 10, see Appendix D, Installation and Configuration of WebLogic Portal 10.

Deploy the URI for the agent application using the deployment container. The agent application is a housekeeping application used by the agent for notifications and other internal functionality. This application is bundled with the agent binaries and can be found at the following location:

PolicyAgent-base/etc/agentapp.war

For more information about base directory (PolicyAgent-base), see WebLogic Server/Portal 10 Agent Directory Structure.

The agentapp application is deployed as a post-installation step. In order for the agent to function correctly, this application must be deployed on the agent-protected deployment container instance using the same URI that was supplied during the agent installation process. For example during the installation process, if you entered /agentapp as the deployment URI for the agent application, then use that same context path to deploy the .war file in the deployment container.

Using the administration console or command-line utilities of your deployment container, deploy this application using the Application Context Path as the URI specified during agent installation.

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

This section is specific to WebLogic Server 10. For instructions specific to WebLogic Portal 10, see To Configure the Agent Authentication Provider Specifically for WebLogic Portal 10.

Using security service provider API exposed by WebLogic Server/Portal 10, the agent plugs its custom security Authenticator into the container. Once the Agent Authenticator is configured, all requests call it. You only need to set the Agent Authenticator once per WebLogic domain. For more information about security providers, seehttp://e-docs.bea.com/wls/docs100/dvspisec/intro.html.

The authentication provider can be added by using the WebLogic Server/Portal 10 Administration Console. The information provided in this section serves to facilitate the configuration of the Agent Authentication Provider and is in no means a substitute for the information provided in WebLogic Server/Portal documentation. For a detailed discussion on WebLogic Authentication providers, search for the proper WebLogic documentation at http://www.bea.com.

To Configure the Agent Authentication Provider Specifically for WebLogic Server 10

This task description is specific to WebLogic Server 10. For the task description specific to WebLogic Portal 10, see Portal: Configuring the Agent Authentication Provider on Agent for WebLogic Portal 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.

After you are finished, restart WebLogic 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.

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

This section is applicable to both WebLogic Server 10 and WebLogic Portal 10.

The task description that follows involves editing the J2EE agent AMAgent.properties configuration file in order to add the user ID of the WebLogic administrative user to the list of bypassed principals. This administrative user may then bypass the authentication process involving Access Manager realm.

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

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

Add the user ID of the WebLogic administrative user to the bypass principal list.

For example, to add the administrative user whose user ID is weblogic to the bypass principal list, set the following property as shown:
```
com.sun.identity.agents.config.bypass.principal[0] = weblogic
```

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

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

The following task applies to both BEA WebLogic Server 10 and BEA WebLogic Portal 10. However, for additional information, see Post-Installation Tasks for the Agent on WebLogic Portal 10

The agent filter must be installed by modifying the deployment descriptor of each application to be protected.

To Install the Agent Filter for the Deployed Application on Agent for WebLogic Server/Portal 10

The following steps explain how to install the agent filter for an application you want the agent to protect.

Ensure that the application is not currently deployed on WebLogic Server/Portal 10.

If it is currently deployed, undeploy it before proceeding any further.

Create the necessary backups before modifying the deployment descriptor in the next step.

Since you will modify the deployment descriptor in the next step, creating backup files at this point is important.

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.

Next Steps

Focus on WebLogic Server 10

Note –

The remainder of this section focuses on WebLogic Server 10, and not on WebLogic Portal 10. For information specific to the web.xml deployment descriptor for WebLogic Portal 10, see Portal: Installing the Agent Filter for the Deployed Application on Agent for WebLogic Server/Portal 10.

To protect your application with J2EE declarative security or with any other filter modes such as ALL or URL_POLICY, refer to the PolicyAgent-base/sampleapp directory for information about building and deploying an application. The sampleapp directory is not a complete J2EE application; however, it is a simple application that provides you with a quick reference to application specific deployment descriptors and various deployment modes of a J2EE agent. Once you successfully deploy sampleapp and test its features, you can use it as a reference to other applications that will be protected by the J2EE agent.

Note –

If you run this agent in J2EE_POLICY mode, map Access Manager roles to the principal names for the deployed application. The principal names are available in the weblogic.xml file and the weblogic-ejb-jar.xml file. Either or both of these files might exist.

You can retrieve Access Manager roles by issuing the agentadmin --getUuid command. For more information , see agentadmin --getUuid. You can also retrieve the universal ID for the user (UUID) using the Access Manager Console to browse the user profile.

Mapping that converts Access Manager roles to principal names is performed by configuring the following property:

com.sun.identity.agents.config.privileged.attribute.mapping[]

For more information about setting this property, see:

Mapping Access Manager Roles to Principal Names
Mapping-related attributes in Privileged Attribute Processing Properties

Conditional Post-Installation Steps for the WebLogic Server/Portal 10 Agent

The following steps might be required, depending on your site's specific deployment:

Updating the Agent Profile

The agent profile is created and updated in Access Manager Console. The agent profile should originally be created prior to installing an agent. However, after you install a J2EE agent, you can update the agent profile at anytime. If you do update the agent profile in Access Manager Console, you must then configure the J2EE agent accordingly as described in this section.

To Update the Agent Profile for J2EE Agents in Policy Agent 2.2

Before You Begin

Change the agent profile in Access Manager using Access Manager Console. For more information about the agent profile, see Creating a J2EE Agent Profile.

Change the password in the password file to match the new password you just created in Access Manager Console as a part of the agent profile.

The password file should originally have been created as a J2EE agent pre-installation task. For more information about pre-installation, seePreparing to Install the WebLogic Server/Portal 10 Agent.

In the command line, issue the agentadmin --encrypt command to encrypt the new password.

For more information on this command, see agentadmin --encrypt.

Access the J2EE agent AMAgent.properties configuration file at the following location:
```
PolicyAgent-base/AgentInstance/config
```

In this configuration file, edit the property for the agent ID to match the new ID in the agent profile as follows:
```
com.sun.identity.agents.app.username = agentID
```
where agentID represents the new agent ID that you created for the agent profile in Access Manager Console.

Edit the property for the agent password as follows:
```
com.iplanet.am.service.secret = encryptedPassword
```
where encryptedPassword represents the new encrypted password you created when you issued the agentadmin --encrypt command.

Restart the J2EE agent container.

The container needs to be restarted because neither property that you edited in this task is hot-swap enabled.

Creating the Necessary URL Policies

Note –

This section does not apply to WebLogic Portal 10. The manner in which the settings for the agent filter mode are applied to WebLogic Server 10 differs from WebLogic Portal 10. For WebLogic Portal 10, creating a policy to protect a resource requires you to set the filter mode to ALL, as described in Configuring the Agent Filter Modes Applicable to WebLogic Portal 10.

If the agent is installed and configured to operate in the URL_POLICY mode or ALL mode, the appropriate URL policies must be created. For instance, if WebLogic Server/Portal 10 is available on port 8080 using the HTTP protocol, at least a policy must be created to allow access to the following resource:

http://myhost.mydomain.com:8080/sampleApp/

where sampleApp is the context URI for the sample application.

If no policies are defined and the agent is configured to operate in the URL_POLICY mode or ALL mode, then no user is allowed access to WebLogic Server/Portal 10 resources. See Sun Java System Access Manager 7.1 Administration Guide to learn how to create these policies using the Access Manager Console or command-line utilities.

Mapping Access Manager Roles to Principal Names

If you are using this agent for WebLogic Server 10 and the agent is set to the J2EE_POLICY filter mode, map Access Manager roles to the principal names in the respective application's deployment descriptor file(s):

weblogic.xml
weblogic-ejb-jar.xml

Note –

This section does not ally to WebLogic Portal 10.

Access Manager roles are represented in UUIDs. Ensure that the keys in the mapping are UUIDs corresponding to your site's Access Manager installation. A UUID for an Access Manager 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. Mapping is established by setting the com.sun.identity.agents.config.privileged.attribute.mapping[] property in the J2EE agent AMAgent.properties configuration file.

For more information, see:

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