test

Sun OpenSSO Enterprise Policy Agent 3.0 Guide for Sun Java System Application Server 8.1/8.2/9.0/9.1 and GlassFish

Post-Installation Tasks for the Application Server and GlassFish Agent

Required Post-Installation Tasks for the Application Server and GlassFish Policy Agent

Deploying the Agent Application

The agent application (agentapp) is a housekeeping application used by the agent for notifications and other functions such as cross domain single sign-on (CDSSO) support.

ProcedureTo Deploy the Agent Application

Before You Begin

This application is bundled with the appserver_v9_agent.zip distribution file and is available as a WAR file in the following location after you unzip the file:

PolicyAgent-base/etc/agentapp.war

  1. Deploy the agent application on the Application Server or GlassFish instance using the Application Server or GlassFish administration console or deployment command.

    You must use the same deployment URI that you specified in the “Agent protected Application Server URL” prompt during the agent installation.

    For example, if you accepted the default value (/agentapp) as the deployment URI for the agent application, then use this same URI to deploy the agentapp.war file in the Application Server or GlassFish instance.

Installing the Agent Filter for the Application Server and GlassFishAgent

Install the agent filter by modifying the deployment descriptor of each application that you want to protect.

ProcedureTo Install the Agent Filter

  1. Ensure that the application you want to protect is not currently deployed on the Application Server or GlassFish instance.

    If the application is deployed, undeploy it before continuing.

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

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

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

    1. 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: Application Server and GlassFish 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.

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

  4. Deploy (or redeploy) the application on Application Server and GlassFish.

    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 (or Access Manager) Console to browse the user profile.

Optional Post-Installation Tasks for the Application Server and GlassFish Agent

Changing the Password for an Agent Profile

After you install the agent, you can change the agent profile password, if required for your deployment.

ProcedureTo Change the Password for an Agent Profile

  1. On the OpenSSO Enterprise server:

    1. Login into the Administration Console as amAdmin.

    2. Click Access Control, realm-name, Agents, J2EE, and then 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.

  2. On the server where the Application Server and GlassFish 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 /export/temp/as9agentpw

      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 Application Server or GlassFish instance that is being protected by the policy agent.

Creating the Necessary URL Policies

If the Application Server and GlassFish agent is configured to operate in the URL_POLICY or ALL filter mode, you must create the appropriate URL policies. For instance, if Application Server and GlassFish is available on port 8080 using the HTTP protocol, you must create at minimum, a policy to allow access to the following resource:


http://myhost.mydomain.com:8080/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 Application Server and GlassFish agent.

For information about how to create these policies using the OpenSSO Enterprise Console or command-line utilities, see the Sun OpenSSO Enterprise 8.0 Administration Guide.

Deploying the Policy Agent Sample Application

After you install the Application Server and GlassFish 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:

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

After you install the Application Server and GlassFish 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.