test

Sun Java System Access Manager Policy Agent 2.2 Guide for BEA WebLogic Server 9.0/9.1

Chapter 4 Post-Installation Tasks of Policy Agent 2.2 for BEA WebLogic Server 9.0/9.1

This chapter describes configuration and other post-installation considerations and tasks.

After completing the applicable tasks described in this chapter, perform the tasks to configure the agent to your site's specific requirements as described in Chapter 6, Managing Policy Agent 2.2 for BEA WebLogic Server 9.0/9.1.

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

The tasks described in this section apply to all J2EE agent installations.

Updating the Agent Profile for J2EE Agents in Policy Agent 2.2

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. After you update the agent profile in Access Manager Console, you must configure the J2EE agent accordingly as described in this section.

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

  1. 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, see Preparing to Install Agent for BEA WebLogic Server 9.0/9.1.

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

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

  3. Access the J2EE agent AMAgent.properties configuration file at the following location:

    PolicyAgent-base/AgentInstance-Dir/config

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

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

  6. Restart the J2EE agent container.

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

Deploying the Agent Application for J2EE Agents in Policy Agent 2.2

Note –

Do not perform this task in the order it appears in this document. This task is described in this section with other tasks that are common to all agents, even though this particular task should be performed in the order indicated by the location of following section, Deploying the Agent Application.

The task described in this section is required. 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.extension

where extension refers to the .war extension or the .ear extension. The extension varies depending on the deployment container.

For more information about the Policy Agent base directory (PolicyAgent-base), see J2EE Agent Directory Structure in Policy Agent 2.2.

The agentapp application has to be 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 or .ear file in the deployment container. Using the administration console or command-line utilities of your deployment container, deploy this application using Application Context Path as the URI specified during agent installation.

Post-Installation Steps Specific to Agent for BEA WebLogic Server 9.0/9.1

Once you have installed Policy Agent 2.2 for BEA WebLogic Server 9.0/9.1 and you have performed the post-installation steps that apply to all J2EE agents in the Policy Agent 2.2 release, complete the following agent-specific steps.

Configuring BEA WebLogic Server 9.0/9.1 Instance With Agent Classpath and Agent Java Options

During installation, the installer creates a script in domain-directory named as follows:

UNIX Platforms

setAgentEnv_server-instance.sh
Windows Platforms

setAgentEnv_server-instance.cmd
domain-directory

represents the domain name associated with your BEA WebLogic Server 9.0/9.1 instance. The following is the default full path name for the domain-directory:

/usr/local/bea/user_projects/domains/mydomain
server-instance

represents the BEA WebLogic Server 9.0/9.1 instance name entered during installation. For example Server1 or Server2.

This script is associated with Agent for BEA WebLogic Server 9.0/9.1 and is used to set up the environment for the agent. This script sets the classpath and java options for the agent. Administrators are responsible for calling the same script from their startup scripts. If the script is included correctly, the agent related classpath is appended to the WebLogic classpath. This script is required for the following task.

ProcedureTo Configure BEA WebLogic Server 9.0/9.1 Instance With Agent Classpath and Agent Java Options

Note –

This step is required. Agent for BEA WebLogic Server 9.0/9.1 will not work if the agent startup script is added incorrectly to the WebLogic startup script. If the agent startup script does not get invoked appropriately from the WebLogic startup script, BEA WebLogic Server 9.0/9.1 will not function appropriately after the Agent Authenticator is set.

    Add the environment script in the following file to the BEA WebLogic Server 9.0/9.1 instance 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.


    setAgentEnv_server-instance.sh

    This environment script is called during the server's start up sequence.

    1. Locate the following line in the startup script:

      . ${WL_HOME}/common/bin/commEnv.sh

    2. Determine which line in the following list is appropriate for your requirements and add that line immediately after the line you located in the previous substep.

      As the following list indicates, when adding the agent environment variable script, you have the choice of specifying the fully qualified path or a relative path to this script. The list that follows includes some use cases of how to add this script for UNIX platforms and Windows platforms.

      • UNIX Platforms (fully qualified path)


        fully-qualified-path/setAgentEnv_server-instance.sh

        For this scenario, the following is a conceivable line if server-instance is named server1 and the domain directory is named mydomain:


        /usr/local/bea/user_projects/domains/mydomain/setAgentEnv_server1.sh

        Therefore, in this scenario, the start up script would then, amongst other lines, contain these two lines as shown:

        . ${WL_HOME}/common/bin/commEnv.sh
/usr/local/bea/user_projects/domains/mydomain/setAgentEnv_server1.sh

      • Windows Platforms (fully qualified path)


        call "fully-qualified-path/setAgentEnv_server-instance.cmd"

        For this scenario, the following is a conceivable line if server-instance is named server1 and the domain directory is named mydomain:


        call "/usr/local/bea/user_projects/domains/mydomain/setAgentEnv_server1.cmd"

        Therefore, in this scenario, the start up script would then contain, amongst other lines, these two lines as shown:

        . ${WL_HOME}/common/bin/commEnv.sh
call "/usr/local/bea/user_projects/domains/mydomain/setAgentEnv_server1.cmd"

      • UNIX Platforms (relative path)


        ../setAgentEnv_server-instance.sh

        For this scenario, the following is a conceivable line if server-instance is named server1:

        ../setAgentEnv_server1.sh

        Therefore, in this scenario, the start up script would then, amongst other lines, contain these two lines as shown:

        . ${WL_HOME}/common/bin/commEnv.sh
../setAgentEnv_server1.sh

      • Windows Platforms (relative path)


        call "./setAgentEnv_server-instance.cmd"

        For this scenario, the following is a conceivable line if server-instance is named server1:


        call "./setAgentEnv_server1.cmd"

        Therefore, in this scenario, the start up script would then, amongst other lines, contain these two lines as shown:

        . ${WL_HOME}/common/bin/commEnv.sh
call "./setAgentEnv_server1.cmd"

      The following are descriptions for variable names used in this step:

      server-instance

      represents the BEA WebLogic Server 9.0/9.1 instance name entered during installation. For example Server1 or Server2.

      fully-qualified-path

      represents the fully qualified path to the following agent script: 


      /setAgentEnv_server-instance.cmd"
    Note –

    A safe practice is to cut and paste agent classpath and agent java option entries from the setAgentEnv_managed_server_name.sh file to avoid any misconfiguration due to typographical errors.

Deploying the Agent Application

Deploy the Agent Application at this point in the configuration process by following the steps in Deploying the Agent Application for J2EE Agents in Policy Agent 2.2.

This application traps notifications and performs other housekeeping tasks.

Configuring the Agent Authentication Provider on Agent for BEA WebLogic Server 9.0/9.1

Using security service provider API exposed by BEA WebLogic Server 9.0/9.1, 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 on security service provider architecture visit the appropriate site according to your site's respective version of BEA WebLogic Server.

BEA WebLogic Server 9.0:

http://e-docs.bea.com/wls/docs90/dvspisec/intro.html

BEA WebLogic Server 9.1:

http://e-docs.bea.com/wls/docs91/dvspisec/intro.html

The authentication provider can be added by using the BEA WebLogic Server 9.0/9.1 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 documentation. For a detailed discussion on WebLogic Authentication providers, see WebLogic Server documentation at http://www.bea.com.

ProcedureTo Configure the Agent Authentication Provider on Agent for BEA WebLogic Server 9.0/9.1

  1. Log on to the BEA WebLogic Server 9.0/9.1 Administration Console.

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

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

  4. Click the Providers tab.

  5. Click the Authentication tab.

  6. In the left pane, click Lock & Edit.

  7. In the right pane, click New.

  8. Specify Type as AgentAuthenticator.

  9. Specify Name with a name of your choice.

  10. Click OK.

  11. Click the newly created policy agent authentication provider.

  12. Change the control flag value from REQUIRED to OPTIONAL

  13. Click Save.

  14. In the right pane, at the top, click Providers.

    The Authentication Providers Table appears.

  15. Click Default Authenticator.

  16. Change the control flag from REQUIRED to OPTIONAL.

  17. Click Save.

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

Adding a WebLogic Administrator to the Bypass List of Agent for BEA WebLogic Server 9.0/9.1

This task 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.

ProcedureTo Add a WebLogic Administrator to the Bypass List of Agent for BEA WebLogic Server 9.0/9.1

    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

Installing the Agent Filter for the Deployed Application on Agent for BEA WebLogic Server 9.0/9.1

The agent filter can be installed by modifying the deployment descriptor of the application that needs to be protected.

ProcedureTo Install the Agent Filter for the Deployed Application on Agent for BEA WebLogic Server 9.0/9.1

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

  1. (Conditional) If the application is currently deployed on BEA WebLogic Server 9.0/9.1, remove it before proceeding any further.

  2. Create the necessary backups before proceeding to modify these descriptors.

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

  3. Edit the application’s web.xml descriptor.

    The filters were introduced in Servlet Specification 2.3. For more information about this specification, see http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html.

    The <DOCTYPE> element of the web.xml descriptor must be changed to reflect that the deployment descriptor is, at minimum, a Servlet 2.3 compliant deployment descriptor. To reflect this compliance perform the following substeps.

    1. Set the <DOCTYPE> element as follows:


      <!DOCTYPE web-app PUBLIC 
"-//Sun Microsystems, Inc.//DTD Web Application2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

    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>
     <display-name>Agent</display-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>

    Ensure that the agent filter element precedes all the other <filter> elements. Similarly, the filter mapping element should be before all the other <filter-mapping> elements. In practice, the agent filter should first intercept the request to properly enforce policies on the whole application.

    If you want 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 to learn how to build and deploy an application. The sampleapp directory is by no means a full fledged J2EE application. Rather 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 all of its features, you can use it as a reference to other applications that will be protected by the J2EE agent.

    Once the web.xml deployment descriptor is modified to reflect the new <DOCTYPE> and <filter> elements, the agent filter is added to the application. You can now redeploy your application on BEA WebLogic Server 9.0/9.1.

    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 on this command, see agentadmin --getUuid. You can also retrieve the universal ID for the user (UUID) using the Access Manager 7 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 on setting this property, see the following:

Conditional Post-Installation Steps for J2EE Agents in Policy Agent 2.2

Steps described in this section might be required, depending on your site's specific deployment.

Creating the Necessary URL Policies

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 BEA WebLogic Server 9.0/9.1 is available on port 7001 using HTTP protocol, at least a policy must be created to allow access to the following resource:


http://myhost.mydomain.com:7001/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 BEA WebLogic Server 9.0/9.1 resources. See Sun Java System Access Manager 7 2005Q4 Administration Guide to learn how to create these policies using the Access Manager Console or command-line utilities.

Combining J2EE Agents With Access Manager

This is a conditional post-installation step that must be performed when the J2EE agent is installed on the same deployment container that hosts Access Manager. Note that Access Manager should be installed prior to the agent being installed. Therefore, the order to install these servers on the same machine is as follows:

  1. Deployment container

  2. Access Manager

  3. J2EE agent

This type of deployment not only requires that you perform a post-installation configuration step as described in the next subsection, this type of deployment also changes where J2EE agent debug log files are stored. For more information, see Locating the J2EE Agent Debug Log Files for Policy Agent 2.2.

Configuring the J2EE Agent in Policy Agent 2.2 to Use the Remote Client SDK of Access Manager

After the J2EE agent is installed, it must use the Remote Client SDK provided by the Access Manager installation.

Modify the Access Manager configuration file, AMConfig.properties, by specifically adding the following entry, which contains the agent configuration location information:


com.sun.identity.agents.config.location =
 PolicyAgent-base/AgentInstance-Dir/config/AMAgent.properties

Locating the J2EE Agent Debug Log Files for Policy Agent 2.2

Installing the J2EE agent and Access Manager on the same deployment container changes the file to which the J2EE agent debug log entries are written. This change occurs because the location of the debug files is set in the properties configuration file. In this type of deployment, two configuration files exist on the same host. However, the Access Manager AMConfig.properties configuration file takes precedence over the J2EE agent AMAgent.properties configuration file.

When the J2EE agent and the Access Manager are installed on separate hosts the debug information is stored in the following directory:

PolicyAgent-base/AgentInstance-Dir/logs/debug

However, when the J2EE agent and Access Manager are installed on the same host, the agent-specific debug information is stored in the following Access Manager directory:


/var/opt/SUNWam/debug

Mapping Access Manager Roles to Principal Names

If you run this agent in J2EE_POLICY mode, map Access Manager roles to the principal names in the respective application's deployment descriptor file (or files):

Access Manager roles are represented in UUIDs. For more information on UUIDs, see the following:

A UUID for an Access Manager role is mapped to the respective principal name in the weblogic.xml file or the weblogic-ejb-jar.xml file. Specifically, the principal name is located within the <principal-name> element.

Mapping is established by setting the property com.sun.identity.agents.config.privileged.attribute.mapping[] in the J2EE agent AMAgent.properties configuration file.

Note –

Ensure that the keys in the mapping are UUIDs corresponding to your site's Access Manager installation. The values are the principal names in the weblogic.xml file or the weblogic-ejb-jar.xml file.

In previous releases of BEA WebLogic, this mapping is not required. The UUIDs representing Access Manager roles are used directly in the weblogic.xml file or the weblogic-ejb-jar.xml file as principal names.

However, in BEA WebLogic 9.0, a principal name within the weblogic.xml file or the weblogic-ejb-jar.xml file must be of the NMTOKEN format. This format is mandated by the corresponding schema files.

Access Manager UUIDs contain characters, such as the following:

These characters are not in NMTOKEN character sets. Therefore, the UUIDs representing Access Manager roles cannot be used directly as principal names. Instead, they must be mapped to characters in the NMTOKEN character set, which includes letters and digits as well as the following characters (period, hyphen, underscore, and colon):

The following examples, which use “\” as an escape character before the special character “=,” illustrate how this property can be set:

com.sun.identity.agents.config.privileged.attribute.mapping[id\=manager,ou\=role,
dc\=iplanet,dc\=com] = am_manager_role
com.sun.identity.agents.config.privileged.attribute.mapping[id\=manager,ou\=role,
dc\=iplanet,dc\=com] = am_employee_role

For more information on this property, see the mapping-related attributes in Privileged Attribute Processing Properties.