Appendix A       Configuration Tasks Performed by Installer


The Sun ONE Identity Server Policy Agent Installer performs certain configuration tasks. Depending on your system configuration and various other factors, these tasks can occasionally fail resulting in a unusable installation. Fortunately, such failures in most cases are recoverable by manually performing these tasks.

This appendix explains how to configure your application server to recover from installation failure.

WebLogic 6.1 SP2

---

The following sections describe the configuration tasks performed by Sun ONE Identity Server Policy Agent Installer.

WebLogic Server Startup Script Modifications

The Installer modifies the WebLogic Server startup script in order to add the newly installed libraries to the CLASSPATH as well as to add certain startup properties for the Java Virtual Machine.

Solaris and HP-UX CLASSPATH Modifications

The following new lines are added to the WebLogic Server startup script, above the line where CLASSPATH variable is defined:

AM_INSTALL_DIR=/opt/SUNWam/wlAgent

AM_SDK_DIR=$AM_INSTALL_DIR/amSDK

AM_SDK_LIB_DIR=$AM_SDK_DIR/lib

AM_SDK_LOCALE_DIR=$AM_SDK_DIR/locale

AM_SDK_JAR1=$AM_SDK_LIB_DIR/am_sdk.jar

AM_SDK_JAR2=$AM_SDK_LIB_DIR/am_services.jar

AM_SDK_JAR3=$AM_SDK_LIB_DIR/am_sso_provider.jar

AM_SDK_JARS=$AM_SDK_JAR1:$AM_SDK_JAR2:$AM_SDK_JAR3

AM_SDK_PATH1=$AM_SDK_DIR:$AM_SDK_LIB_DIR

AM_SDK_PATH2=$AM_SDK_LOCALE_DIR:$AM_SDK_JARS

AM_SDK_CLASSPATH=$AM_SDK_PATH1:$AM_SDK_PATH2

AM_AGT_DIR=$AM_INSTALL_DIR/amAgent

AM_AGT_CONFIG_DIR=$AM_AGT_DIR/config

AM_AGT_LOCALE_DIR=$AM_AGT_DIR/locale

AM_AGT_LIB_DIR=$AM_AGT_DIR/lib

AM_AGT_JAR1=$AM_AGT_LIB_DIR/amagent_core.jar

AM_AGT_JAR2=$AM_AGT_LIB_DIR/amagent_weblogic.jar

AM_AGT_JAR3=$AM_AGT_LIB_DIR/amagent_filter.jar

AM_AGT_JAR4=$AM_AGT_LIB_DIR/amagent_tools.jar

AM_AGT_JARS12=$AM_AGT_JAR1:$AM_AGT_JAR2

AM_AGT_JARS34=$AM_AGT_JAR3:$AM_AGT_JAR4

AM_AGT_JARS=$AM_AGT_JARS12:$AM_AGT_JARS34

AM_AGT_PATH1=$AM_AGT_DIR:$AM_AGT_CONFIG_DIR

AM_AGT_PATH2=$AM_AGT_LOCALE_DIR:$AM_AGT_LIB_DIR:$AM_AGT_JARS

AM_AGT_CLASSPATH=$AM_AGT_PATH1:$AM_AGT_PATH2

AM_CLASSPATH=$AM_SDK_CLASSPATH:$AM_AGT_CLASSPATH

Once these entries have been added, the AM_CLASSPATH is appended to the CLASSPATH variable.

CLASSPATH=$WL_HOME:$WL_HOME/lib/weblogic_sp.jar:$WL_HOME/lib/web logic.jar:$WL_HOME/samples/eval/cloudscape/lib/cloudscape.jar:./ config/examples/serverclasses:$AM_CLASSPATH

Windows CLASSPATH Modifications

The CLASSPATH is modified by adding the following lines to the WebLogic Server startup script immediately after the definition of the CLASSPATH variable.

set AM_SDK_DIR=%AM_INSTALL_DIR%\amSDK

set AM_SDK_LIB_DIR=%AM_SDK_DIR%\lib

set AM_SDK_LOCALE_DIR=%AM_SDK_DIR%\locale

set AM_SDK_JAR1=%AM_SDK_LIB_DIR%\am_sdk.jar

set AM_SDK_JAR2=%AM_SDK_LIB_DIR%\am_services.jar

set AM_SDK_JAR3=%AM_SDK_LIB_DIR%\am_sso_provider.jar

set AM_SDK_JARS=%AM_SDK_JAR1%;%AM_SDK_JAR2%;%AM_SDK_JAR3%

set AM_SDK_PATH1=%AM_SDK_DIR%;%AM_SDK_LIB_DIR%

set AM_SDK_PATH2=%AM_SDK_LOCALE_DIR%;%AM_SDK_JARS%

set AM_SDK_CLASSPATH=%AM_SDK_PATH1%;%AM_SDK_PATH2%

set AM_AGT_DIR=%AM_INSTALL_DIR%\amAgent

set AM_AGT_CONFIG_DIR=%AM_AGT_DIR%\config

set AM_AGT_LOCALE_DIR=%AM_AGT_DIR%\locale

set AM_AGT_LIB_DIR=%AM_AGT_DIR%\lib

set AM_AGT_JAR1=%AM_AGT_LIB_DIR%\amagent_core.jar

set AM_AGT_JAR2=%AM_AGT_LIB_DIR%\amagent_weblogic.jar

set AM_AGT_JAR3=%AM_AGT_LIB_DIR%\amagent_filter.jar

set AM_AGT_JAR4=%AM_AGT_LIB_DIR%\amagent_tools.jar

set AM_AGT_JARS12=%AM_AGT_JAR1%;%AM_AGT_JAR2%

set AM_AGT_JARS34=%AM_AGT_JAR3%;%AM_AGT_JAR4%

set AM_AGT_JARS=%AM_AGT_JARS12%;%AM_AGT_JARS34%

set AM_AGT_PATH1=%AM_AGT_DIR%;%AM_AGT_CONFIG_DIR%

set AM_AGT_PATH2=%AM_AGT_LOCALE_DIR%;%AM_AGT_LIB_DIR%;%AM_AGT_JARS%

set AM_AGT_CLASSPATH=%AM_AGT_PATH1%;%AM_AGT_PATH2%

set AM_CLASSPATH=%AM_SDK_CLASSPATH%;%AM_AGT_CLASSPATH%

set CLASSPATH=%CLASSPATH%;%AM_CLASSPATH%

The last line in the added text modifies the CLASSPATH to include the libraries provided by the Agent.

Adding Parameters to Java Virtual Machine

For the installation platforms Solaris 8, Windows 2000, and HP-UX 11 the following parameters are added to the Java Virtual Machine (JVM) invocation command that loads the WebLogic Server:

-D"com.iplanet.coreservices.configpath=/opt/SUNWam/wlAgent/amSDK /config/ums"

-D"max_conn_pool=10"

-D"min_conn_pool=1"

The resulting command on Solaris and HP-UX:

java $JAVA_OPTIONS -classpath $CLASSPATH -Dweblogic.Domain=examples -Dweblogic.Name=examplesServer -Dweblogic.management.password=$WLS_PW -Dbea.home=/bea -Dcloudscape.system.home=./samples/eval/cloudscape/data -Djava.security.policy==$WL_HOME/lib/weblogic.policy -D"com.iplanet.coreservices.configpath=/opt/SUNWam/wlAgent/amSDK /config/ums" -D"max_conn_pool=10" -D"min_conn_pool=1" weblogic.Server

On Windows:

"%JAVA_HOME%\bin\java" -hotspot -ms64m -mx64m -classpath "%CLASSPATH%" -Dweblogic.Domain=examples -Dweblogic.Name=examplesServer -Dweblogic.management.password=%WLS_PW% -Dbea.home="C:\bea" -Dcloudscape.system.home=./samples/eval/cloudscape/data -Djava.security.policy=="C:\bea\wlserver6.1/lib/weblogic.policy" -D"com.iplanet.coreservices.configpath=C:/Sun/SUNWam/wlAgent/amS DK/config/ums" -D"max_conn_pool=10" -D"min_conn_pool=1" weblogic.Server

Installation of JCE 1.2.1 and JSSE 1.0.2 Extensions

The Installer also performs the installation of JCE 1.2.1 and JSSE 1.0.2 extensions which result in the modification of the file JAVA_HOME/jre/lib/secrurity/java.security and the copying of various jar files in the JAVA_HOME/jre/lib/ext directory. If the installation of any of these extensions fails, you can manually install them. For obtaining these extensions and documentation on how to install them, refer to the product website:

http://java.sun.com/products/jce and

http://java.sun.com/products/jsse

WebSphere 4.0.3 AE

---

The following sections describe the configuration tasks performed by Sun ONE Identity Server Policy Agent Installer.

Modifications to WebSphere Command-Line Setup Script

• Append the following lines to WebSphere command-line setup script WAS_root_dir/bin/setupCmdLine.sh.
  

  ---

  BASEDIR=Agent_Install_Dir

  PRODUCT_DIR=SUNWam

  AM_INSTALL_DIR=$BASEDIR/$PRODUCT_DIR/wasAgent

  AM_SDK_DIR=$AM_INSTALL_DIR/amSDK

  AM_AGT_DIR=$AM_INSTALL_DIR/amAgent

  SDK_CLASSPATH=$AM_SDK_DIR:$AM_SDK_DIR/locale:$AM_SDK_DIR/lib:$AM _SDK_DIR/lib/am_sdk.jar:$AM_SDK_DIR/lib/am_services.jar: \

  $AM_SDK_DIR/lib/am_sso_provider.jar:$AM_SDK_DIR/lib/jaas.jar

  AGENT_CLASSPATH=$AM_AGT_DIR:$AM_AGT_DIR/config:$AM_AGT_DIR/local e:$AM_AGT_DIR/lib:$AM_AGT_DIR/lib/amagent_core.jar: \

  $AM_AGT_DIR/lib/amagent_tools.jar:$AM_AGT_DIR/lib/amagent_was.ja r: $AM_AGT_DIR/lib/amagent_interceptor.jar

• Update the WAS_EXT_DIRS and WAS _CLASSPATH by adding SDK_CLASSPATH and AGENT_CLASSPATH
  

  ---

  WAS_EXT_DIRS=$JAVA_HOME/lib:$WAS_HOME/classes:$WAS_HOME/lib:$WAS _HOME/lib/ext:$WAS_HOME/web/help: \

  $DBDRIVER_JARS:$SDK_CLASSPATH:$AGENT_CLASSPATH

  WAS_CLASSPATH=$WAS_HOME/properties:$WAS_HOME/lib/bootstrap.jar:$ SDK_CLASSPATH:$AGENT_CLASSPATH

Modifications to WebSphere Server Startup Script

• Add the System property for the Identity Server SDK config directory to WebSphere Server startup script WAS_root_dir/bin/startupServers.sh
  

  ---

  BASEDIR=Agent_Install_Dir

  PRODUCT_DIR=SUNWam

  AM_INSTALL_DIR=$BASEDIR/$PRODUCT_DIR/wasAgent

  AM_SDK_DIR=$AM_INSTALL_DIR/amSDK

• Add the property -Dcom.iplanet.coreservices.configpath=$AM_SDK_DIR/config/ums to the JAVA command line that invokes com.ibm.ws.bootstrap.WSLauncher, to the appropriate section depending on the configuration database used by the WebSphere.

Modifications to Admin Server Configuration File

• Update the property com.ibm.ejs.sm.adminserver.classpath and add all the SDK and AGENT related directories that contain property files.

• Update the -Dws.ext.dirs value for com.ibm.ejs.sm.util.process.Nanny.adminServerJvmArgs, to include SDK and agent related directories and jars.

• Add the following arguments to com.ibm.ejs.sm.util.process.Nanny.adminServerJvmArgs property:

  -Djava.protocol.handler.pkgs=com.ibm.net.ssl.internal.www.protocol

  -Dcom.iplanet.coreservices.configpath= Agent_Install_Dir/SUNWam/wasAgent/amSDK/config/ums

Modifications to trustedserver.properties

• Comment out all the lines that are not commented, and add the following lines to WAS_root_dir/properties/trustedservers.properties file

  com.ibm.websphere.security.trustassociation.enabled=true

  com.ibm.websphere.security.trustassociation.types=amagent

  com.ibm.websphere.security.trustassociation.amagent.interceptor=com.sun.amagent.websphere.interceptor.AgentInterceptor

  com.ibm.websphere.security.trustassociation.amagent.config=AMAgent

• Restart the Administration Server and the Application Server instance.

  
  

  ---

  Note

  Before performing Agent Realm configuration, the Administration Server and Application server instance must be restarted, so that the above modifications take effect. During the Agent Realm installation, the authenticate( ) method of Realm is invoked with the given Realm Administrator credentials. The SDK and the Agent related classes must be in the classpath. The realm is installed only when the authentication is successful.

  ---

  
  

Configurations Through Administrative Console

Setting System Properties for the Application Server Instance

The following property must be added to each Application server instance, through the Administrative console as shown in the Figure A-1.

-Djava.protocol.handler.pkgs=com.ibm.net.ssl.internal.www.protocol

-Dcom.iplanet.coreservices.configpath= Agent_Install_Dir/SUNWam/wasAgent/amSDK/config/ums

Figure A-1    Setting System Properties

Agent Realm Configuration

The Agent Realm can be configured from the Security Center of Administrative Console. Perform the following steps to configure the Agent Realm:

1. Start the WebSphere Administrative console using the following command:

   # WAS_roor_dir/bin/adminclient.sh

2. In the Administrative Console window, choose Console > Security Center.

3. In the Security Center window, click on Authentication tab. See Figure A-2.

4. Choose "Lightweight Third Party Authentication (LTPA)" for authentication mechanism.

5. Choose "Custom Registry Option."

6. Enter the Administrator's user ID for "Security Server Id." For example, amAdmin for o=sun.com.

7. Enter the password for the Administrative User for "Security Server Password."

8. Enter the value com.sun.amagent.websphere.realm.AgentRealm for Custom Registry Class.

9. Click on check box "Enable Web trust association."

10. Click Apply. A message "Changes will take effect only after Administration Server is restarted" will be displayed. Click OK

11. Click on General tab and enable the check box for "Enable Security."

12. Stop all Application Server instances.

13. Stop the Administration Server.

14. Restart Administration Server and Application Server instances for changes to take effect.

Figure A-2    Agent Realm Configuration

Sun ONE Application Server 7.0

---

The following sections describe the configuration tasks performed by Sun ONE Identity Server Policy Agent Installer.

Application Server Config Files

The following configuration files are modified by the Installer:

S1AS_Install_Dir/appserv/domains/domain1/server-instance/config/server.xml

S1AS_Install_Dir/appserv/domains/domain1/server-instance/config/login.conf

S1AS_Install_Dir/appserv/domains/domain1/server-instance/config/server.policy

Modifications in server.xml

Installer modifies server.xml in order to add all the newly installed libraries to the classpath as well as to add certain properties for the Java Virtual Machine. Also, it adds Agent Realm and makes it default to be used.

classpath Modifications

The classpath is modified by adding the following lines to the Application Server startup script immediately after the definition of the classpath variable.

Agent_Install_Dir/SUNWam/asAgent/amSDK;

Agent_Install_Dir/SUNWam/asAgent/amSDK/lib;

Agent_Install_Dir/SUNWam/asAgent/amSDK/locale;

Agent_Install_Dir/SUNWam/asAgent/amSDK/lib/am_sdk.jar;

Agent_Install_Dir/SUNWam/asAgent/amSDK/lib/am_services.jar;

Agent_Install_Dir/SUNWam/asAgent/amSDK/lib/am_sso_provider.jar;

Agent_Install_Dir/SUNWam/asAgent/amAgent;

Agent_Install_Dir/SUNWam/asAgent/amAgent/config;

Agent_Install_Dir/SUNWam/asAgent/amAgent/locale;

Agent_Install_Dir/SUNWam/asAgent/amAgent/lib;

Agent_Install_Dir/SUNWam/asAgent/amAgent/lib/amagent_core.jar;

Agent_Install_Dir/SUNWam/asAgent/amAgent/lib/amagent_as.jar;

Agent_Install_Dir/SUNWam/asAgent/amAgent/lib/amagent_filter.jar;

Agent_Install_Dir/SUNWam/asAgent/amAgent/lib/amagent_tools.jar

You can verify the modifications by invoking the Admin Console:

1. Click the server-instance under Application Server Instances.

2. On the right pane, click JVM Settings > Path Settings.

3. Check the values of Classpath Suffix, which includes the above values.

Adding Parameters to Java Virtual Machine

The following parameters are added to the Java Virtual Machine invocation command that loads the Application Server:

-Dcom.iplanet.coreservices.configpath=Agent_Install_Dir/SUNWam/asAgen t/amSDK/config/ums

-Dmax_conn_pool=10

-Dmin_conn_pool=1

Adding Agent Realm

The following lines are added under <security-service> element:

<auth-realm name="agentRealm" classname="com.sun.amagent.as.realm.AgentRealm">

<property name="jaas-context" value="agentRealm"/>

</auth-realm>

Here name=agnetRealm is value provided at installation time.

You can verify this using the Admin Console.

• Choose Security > Realms and verify the Agent Realm.

Making Agent Realm as Default

default-realm attribute of <security-service> element is modified as follows:

<security-service default-realm="agentRealm" anonymous-role="ANYONE" audit-enabled="false">

You can verify this using the Admin Console.

• Click Security and verify the value of Default Realm.

Modifications in login.conf

Installer modifies login.conf to define LoginModule for the jaas-context as follows:

agentRealm {

com.sun.amagent.as.realm.AgentLoginModule required;

};

Modifications in server.policy

Installer modifies server.policy to give Programmatic Login permission to agent-filter.jar as follows:

// ProgrammaticLoginPermission to Sun(TM) ONE Identity Server Policy Agent Filter

grant codeBase "file:Agent_Install_Dir/SUNWam/asAgent/amAgent/lib/amagent_filter.jar " {

permission com.sun.appserv.security.ProgrammaticLoginPermission "login";

};

PeopleSoft 8.3

---

The following sections describe the configuration tasks performed based on the selections you made during the installation of Sun ONE Identity Server Policy Agent for PeopleSoft 8.3.

When PeopleSoft Application Server is installed locally

These tasks are performed for both the deployment scenarios: Agent deployed on PeopleSoft-provided WebLogic Server or Agent deployed on a separate proxying web server.

On successful installation, a file psdsameenv.sh containing the environment is created under $PS_HOME/appserv/. The PS_CLASSPATH environment variable is required by PeopleCode to set up the appropriate CLASSPATH when authentication-related PeopleCode is invoked.

---

Note	It is recommended that $PS_HOME/appserv/psdsameenv.sh be added to the $HOME/.profile of the userid that executes PeopleSoft startup and shutdown.

---

In the file $PS_HOME/appserv/DOMAIN/psappsrv.cfg, the following JVM option is added:

JavaVM Options=-Dcom.iplanet.coreservices.configpath=Agent_Install_Dir/SUNWam/amSDK/config/ums

When WebLogic 5.1 Server installed locally

The following tasks are common to both deployment options: Agent deployed on PeopleSoft-provided WebLogic Server or Agent deployed on a separate proxying web server.

The files dsamesignin.html, dsamesignin1.html, and dsamesimplesignin.html are installed under:

WEBLOGIC-HOME/myserver/myserver/public_html/peoplesoft8

The file WEBLOGIC-HOME/myserver/psftdocs/peoplesoft8/ configuration.properties is updated with the following changes.

• PeopleSoft configured for SSO:

  byPassSignOn=true

  defaultUSERID=DEFAULT_USER

  defaultPWD=some-long-password

• Single Signout:

  signon_page=dsamesignin.html

  signonError_page=dsamesignin.html

  logout_page=dsamesignin.html

  expire_page=dsamesignin.html

The following symbolic links are created:

$ ln -s WEBLOGIC-HOME/myserver/psftdocsWEBLOGIC-HOME

$ ln -s WEBLOGIC-HOME/myserver/public_html/peoplesoft8WEBLOGIC HOME/myserver

$ ln -s WEBLOGIC-HOME/myserver/public_html/index.htmlWEBLOGIC HOME/myserver

Configuration Tasks when Deploying Agent on PeopleSoft Provided WebLogic 5.1 Server

• In the file WEBLOGIC-HOME/setEnv.sh, the CLASSPATH is appended at the end of the file.

  INSTALL_DIR=Agent_Install_Dir WL_DIR= WEBLOGIC-HOME SDK_DIR=$INSTALL_DIR/amSDK SDK_LIB_DIR=$SDK_DIR/lib SDK_LOCALE_DIR=$SDK_DIR/locale SDK_JAR1=$SDK_LIB_DIR/am_sdk.jar SDK_JAR2=$SDK_LIB_DIR/am_services.jar SDK_JAR3=$SDK_LIB_DIR/am_sso_provider.jar SDK_JARS=$SDK_JAR1:$SDK_JAR2:$SDK_JAR3 SDK_PATH1=$SDK_DIR:$SDK_LIB_DIR SDK_PATH2=$SDK_LOCALE_DIR:$SDK_JARS SDK_CLASSPATH=$SDK_PATH1:$SDK_PATH2 AGT_DIR=$INSTALL_DIR/agent AGT_CONFIG_DIR=$AGT_DIR/config AGT_LOCALE_DIR=$AGT_DIR/locale AGT_LIB_DIR=$AGT_DIR/lib AGT_JAR=$AGT_LIB_DIR/am_ext.jar AGT_PATH1=$AGT_DIR:$AGT_CONFIG_DIR AGT_PATH2=$AGT_LOCALE_DIR:$AGT_LIB_DIR:$AGT_JAR AGT_CLASSPATH=$AGT_PATH1:$AGT_PATH2 EXT_LIB_DIR=$INSTALL_DIR/lib EXT_JARS=$EXT_LIB_DIR/servlet.jar:$EXT_LIB_DIR/crimson.jar:$EXT_ LIB_DIR/jaxp.jar:$EXT_LIB_DIR/jaas.jar:$EXT_LIB_DIR/xercesImpl.j ar:$EXT_LIB_DIR/xmlParserAPIs.jar EXT_CLASSPATH=$EXT_LIB_DIR:$EXT_JARS PS_WEB_DIR=$INSTALL_DIR/PS PS_WEB_CLASSPATH=$PS_WEB_DIR:$PS_WEB_DIR/classes:$WL_DIR/myserve r/WEB-INF AGENT_CLASSPATH=$SDK_CLASSPATH:$AGT_CLASSPATH:$EXT_CLASSPATH:$PS _WEB_CLASSPATH CLASSPATH=$CLASSPATH:.:$AGENT_CLASSPATH export CLASSPATH

• In the file WEBLOGIC-HOME/startWebLogic.sh, the above $CLASSPATH gets appended in the PRE-CLASSPATH variable after weblogic510sp.jar and the following JVM option in the Java invocation command:

  -Dcom.iplanet.coreservices.configpath=Agent_Install_Dir/SUNWam/amSDK/config/ums

  -Dcom.sun.am.policy.config.PIASiteName=PIA_SITE_NAME

Also, the following is added to the variable JAVACLASSPATH:

Agent_Install_Dir/SUNWam/agent/config

• In the file WEBLOGIC-HOME/weblogic.policy,the following are added to grant property read/write permission for the agent.

  // Grant property read/write permission for the agent

  grant { permission java.util.PropertyPermission "com.sun.am.policy.config.*", "read,write";};

• The following files are installed. These files represent redeployment of PeopleSoft application as a Web application. This is necessary for agent code executing the WebLogic server to work correctly.

  WEBLOGIC-HOME/myserver/WEB-INF

  WEBLOGIC-HOME/myserver/WEB-INF/web.xml

  WEBLOGIC-HOME/myserver/WEB-INF/weblogic.xml

• The file WEBLOGIC-HOME/weblogic.properties is updated to register PeopleSoft application as a Web application. The following line is appended at the end:

  weblogic.httpd.defaultWebApp=WEBLOGIC-HOME/myserver

JCE/JSSE

The Installer also performs the installation of JCE 1.2.1 and JSSE 1.0.2 extensions. While doing this, it modifies the file JAVA_HOME/jre/lib/secrurity/java.security and the copies various jar files to the JAVA_HOME/jre/lib/ext directory. If the installation of any of these extensions fails, you can manually install them. For obtaining these extensions and the documentation on how to install them, refer to the product website at:

http://java.sun.com/products/jce and

http://java.sun.com/products/jsse