test

Sun Java System Access Manager 7.1 Postinstallation Guide

Chapter 12 Deploying Access Manager as a Single WAR File

This chapter describes how to deploy Access Manager 7.1 as an application (single WAR file), including:

Getting an Access Manager 7.1 War File

You can get an Access Manager 7.1 WAR file from the following sources:

Requirements for an Access Manager Single WAR File Deployment

The following table lists the requirements for creating and deploying an Access Manager WAR file.

Table 12–1 Requirements for a Single WAR File Deployment of Access Manager

Item 

Requirement 

Access Manager web container 

One of the following web containers must be running on the host server where you plan to deploy an Access Manager WAR file:  

  • Sun Java System Web Server 7

  • Sun Java System Application Server Enterprise Edition 8.2

  • BEA WebLogic Server

  • IBM WebSphere Application Server

For the versions of WebLogic Server and WebSphere Application Server that are supported as web containers for Access Manager 7.1, see the Sun Java System Access Manager 7.1 Release Notes.

Directory Server 

To store Access Manager configuration data, Directory Server Enterprise Edition 6 is required only for a production deployment. In a test or evaluation environment, you can use the File System option to store the Access Manager configuration data.

The Java ES installer might enforce the Directory Server dependency for Access Manager, but Directory Server is not required if you select the File System option when you configure Access Manager after you deploy the WAR file. For more information, see Configuring Access Manager 7.1 Using the Configurator.

Multiple server deployment: If you are deploying multiple Access Manager instances in a multiple server deployment:

  • All Access Manager instances must access the same instance of Directory Server.

  • The File System option to store the Access Manager configuration data is not supported.

The Java ES 5 release includes Sun Java System Directory Server Enterprise Edition 6. 

Password encryption key 

Multiple server deployment: If you are using the same WAR file to deploy multiple Access Manager instances in a multiple server deployment, you must use the same password encryption key value for each instance. Copy the encryption key value from the first instance and use this value when you configure each additional instance. You can determine this value from the am.encryption.pwd attribute in the AMConfig.properties file after you deploy the first instance.

Web container runtime user permissions 

If the runtime user of the Access Manager web container instance is a non-root user, this user must be able to write to its own home directory. For example, when installing Web Server 7, the default runtime user for the Web Server instance is webservd. On Solaris systems, the webservd user has the following entry in the /etc/passwd file:

webservd:x:80:80:WebServer Reserved UID:/:

The webservd user does not have permission to write to its default home directory (/). Therefore, you must change the permissions to allow the webservd user to write to its default home directory. Otherwise, the webservd user will encounter an error after you configure Access Manager using the Configurator (configurator.jsp).

LANG environment variable

To run the Configurator, the code set in the LANG environment variable must be set to ISO8859-1.

Access Manager mode 

An Access Manager instance deployed from an Access Manager 7.1 WAR file is always in Realm Mode (AM_REALM=enabled).

Sun Java Enterprise System (Java ES) installer 

To generate an Access Manager 7.1 WAR file, see Generating an Access Manager 7.1 WAR File Using the Java ES Installer.

For information about the installer, see Overview of the Installation Process.

Where to Find More Information

The following table shows where you can find more information if you are deploying an Access Manager 7.1 WAR file.

Component 

Where to find more information 

Access Manager 7.1 

Access Manager 7.1 documentation collection: 

http://docs.sun.com/coll/1292.2

Access Manager Console 

Access Manager 7.1 Console online help after you deploy the WAR file. 

Sun Java System Web Server 7.0 

Web Server 7.0 documentation collection: 

http://docs.sun.com/coll/1308.3

Sun Java System Application Server Enterprise Edition 8.2 

Application Server EE 8.2 documentation collection: 

http://docs.sun.com/coll/1310.3

Sun Java System Directory Server 6 

Directory Server 6 documentation collection: 

http://docs.sun.com/coll/1224.1

Downloading an Access Manager 7.1 WAR File

You can download a Sun Java System Access Manager 7.1 WAR file from the following sites:

Sun Download Site

You can download an Access Manager 7.1 WAR file and a Distributed Authentication UI server WAR file as part of the Access Manager 7.1 ZIP file under “Identity Management > Access Manager” on the following web site:

http://www.sun.com/download/index.jsp

The ZIP file name is AccessManager7_1release.zip, where release specifies the Access Manager release. For example, AccessManager7_1RTM.zip is the initial release of Access Manager 7.1.

Table 12–2 describes the files in the Access Manager 7.1 ZIP file. The directory where you unzip the file is represented by zip_root.

Table 12–2 Layout of the Access Manager 7.1 ZIP File

Directory 

Description 

zip_root

README describes the contents of the ZIP file.

Software_License_Agt_SLA.txt is the Software License Agreement.

zip_root/applications

README is a brief explanation of the web applications.

amDistAuth.zip contains the files to configure and deploy a Distributed Authentication UI server WAR file (amauthdistui.war). For more information, see Deploying a Distributed Authentication UI Server WAR File.

zip_root/applications/jdk14

Contains the Access Manager 7.1 WAR file (amserver.war) for web containers running under JDK 1.4.x.

For more information, see Deploying an Access Manager 7.1 WAR File.

zip_root/applications/jdk14/jarFix

Contains the following JAR files required for specific deployments: commons-logging.jar, dom.jar, jaxrpc-api.jar, jaxrpc-ri.jar, xalan.jar, and xercesImpl.jar.

zip_root/applications/jdk15

Contains the Access Manager 7.1 WAR file (amserver.war) for web containers running under JDK 1.5.x.

For more information, see Deploying an Access Manager 7.1 WAR File.

zip_root/samples

README provides instructions about the Access Manager samples.

zip_root/tools

README describes the contents of the tools ZIP files.

amAdminTools.zip contains:

  • Files to run the Access Manager CLI utilities and scripts such as amadmin, ampassword, amtune and amsfoconfig.

  • Properties files for various locales, including English, French, German, Spanish, Japanese, Korean, Simplified Chinese, and Traditional Chinese.

amSessionTools.zip contains the files to install Sun Java System Message Queue and the Berkeley DB, which then allows you to configure Access Manager session failover.

zip_root/legal

Contains locale specific legal files 

Java EE 5 SDK Web Site

You can also download a Sun Java System Access Manager 7.1 WAR file (and other components) from the Java EE 5 SDK web site:

http://java.sun.com/javaee/downloads/index.jsp

Note –

This web site has the Access Manager 7.1 WAR file (amserver.war). If you also need the Distributed Authentication UI server WAR file (amauthdistui.war), download the Access Manager 7.1 ZIP file from the Sun Download Site.

Generating an Access Manager 7.1 WAR File Using the Java ES Installer

To generate an Access Manager 7.1 WAR file (amserver.war), you first install Access Manager by running the Java ES installer with the Configure Later option. You then set variables in the amsamplesilent file (or a copy of the file) and run the amconfig script.

ProcedureTo Generate an Access Manager WAR File Using the Java ES Installer

  1. Login as (or become) superuser (root).

  2. Install Access Manager by running the Java ES installer with the Configure Later option.

    The installer installs the amconfig script and amsamplesilent file in the following directory:

    • Solaris systems: AccessManager-base/SUNWam/bin

    • Linux and HP-UX systems: AccessManager-base/identity/bin

    • Windows systems: AccessManager-base\identity\bin

      On Windows systems, the files are amconfig.bat and AMConfigurator.properties.

    The default value for AccessManager-base is /opt on Solaris systems or /opt/sun on Linux systems.

  3. Make a copy of the amsamplesilent configuration file.

    The following examples use amwardeploy as the configuration file name. On Windows systems, the examples use AMConfigurator-singlewar.properties as the configuration file name.

  4. Set the following variables in the amwardeploy configuration file.

    Variable 

    Description 

    DEPLOY_LEVEL=10

    Causes the amconfig script to generate an Access Manager 7.1 WAR file as follows, depending on your platform:

    • Solaris systems: /opt/SUNWam/amserver.war

    • Linux and HP-UX systems: /opt/sun/identity/amserver.war

    • Windows systems: AccessManager-base\identity\amserver.war

    JAVA_HOME

    Specifies the path to the JDK installation directory and the JDK version used by Access Manager. The JDK version must be 1.5 or later. 

    Default: /usr/jdk/entsys-j2se

    SERVER_DEPLOY_URI

    Specifies the name of the new Access Manager WAR file: $SERVER_DEPLOY_URI.war

    Default: amserver

    Note –

    An Access Manager instance deployed from an Access Manager 7.1 WAR file is always in Realm Mode (AM_REALM=enabled). If you set AM_REALM=disabled, the amconfig script ignores the variable.

  5. Run the amconfig script with the edited amwardeploy configuration file.

    For example, on Solaris systems with Access Manager installed in the default directory:

    # cd /opt/SUNWam/bin
# ./amconfig -s ./amwardeploy

    On Windows systems, in the amconfig.bat file, change AMConfigurator.properties to AMConfigurator-singlewar.properties, and then run the edited amconfig.bat file.

    The amconfig script or amconfig.bat file generates the Access Manager WAR file as follows.

    • Solaris systems: /opt/SUNWam/amserver.war

    • Linux and HP-UX systems: /opt/sun/identity/amserver.war

    • Windows systems: AccessManager-base\identity\amserver.war

Deploying an Access Manager 7.1 WAR File

Deploy the Access Manager 7.1 WAR file, depending on the web container you are using:

Note: Samples and Javadocs are not provided after you deploy the Access Manager 7.1 WAR file.

Deploying an Access Manager 7.1 WAR File in Sun Java System Web Server 7

Before you deploy the Access Manager WAR file, Web Server 7 must be installed and running on the host server.

ProcedureTo Deploy the Access Manager WAR File in Web Server 7

  1. Login as (or become) superuser (root).

  2. Copy the amserver.war file to the host server where you want to deploy Access Manager.

    To get the amserver.war file, see Getting an Access Manager 7.1 War File.

    For example, copy the WAR file to the /opt/SUNWam/amwar_staging directory.

  3. Backup the server.policy file and then add the Java security permissions to the file, as shown in Adding Access Manager Permissions to the Server Policy File.

  4. Restart the Web Server instance for the new entries to take effect.

  5. Deploy the Access Manager amserver.war file using the Web Server Admin Console or CLI command:

    • For example, the following Web Server 7 wadm command deploys the WAR file on Solaris systems:

      cd /opt/SUNWwbsvr7/bin
./wadm add-webapp --user=admin --host=${SERVER_HOST}
--port=${WS_ADMIN_PORT} --config=${WS_CONFIG} 
--vs=${WS_VIRTUAL_SERVER} --uri=/${SERVER_DEPLOY_URI}
/opt/SUNWam/amwar_staging/amserver.war

./wadm deploy-config --user admin --host=${SERVER_HOST}
--port=${WS_ADMIN_PORT} --restart=true ${WS_CONFIG}

      Enter the Web Server administration password when you are prompted.

      For more information about the wadm command, see Chapter 9, Deploying Web Applications, in Sun Java System Web Server 7.0 Developer’s Guide to Java Web Applications.

  6. Depending on your platform, add the following JavaHelp JAR file (jhall.jar) to the classpath so the Access Manager Console online help is accessible:

    • Solaris systems: /usr/jdk/packages/javax.help-2.0/lib/jhall.jar

    • Linux systems: /usr/java/packages/javax.help-2.0/javahelp/lib/jhall.jar

  7. Continue with Configuring Access Manager 7.1 Using the Configurator.

Deploying an Access Manager 7.1 WAR File in Sun Java System Application Server Enterprise Edition 8.2

Before you deploy the Access Manager WAR file, Application Server 8.2 must be installed and running on the host server.

ProcedureTo Deploy the Access Manager 7.1 WAR File in Application Server 8.2

  1. Login as (or become) superuser (root).

  2. Copy the amserver.war file to the host server where you want to deploy Access Manager.

    To get the amserver.war file, see Getting an Access Manager 7.1 War File.

    For example, copy the WAR file to the /opt/SUNWam/amwar_staging directory.

  3. Backup the server.policy file and then add the Java security permissions to the file, as shown in Adding Access Manager Permissions to the Server Policy File.

  4. Restart the Application Server instance for the new entries to take effect.

  5. Create a file containing the Application Server administration password.

    For example, if you use /tmp/pwdfile as the password file:

    echo "AS_ADMIN_PASSWORD=application-server-administration-password" > /tmp/pwdfile

  6. Deploy the amserver.war file using the Application Server Admin Console or the asadmin deploy command.

    For example, the following asadmin deploy command deploys the WAR file on Solaris systems:

    # cd /opt/SUNWappserver/appserver/bin
# ./asadmin deploy --user appserver-admin
--passwordfile /tmp/pwdfile --port 4849
--contextroot amserver --name amserver
--target server /opt/SUNWam/amwar_staging/amserver.war

  7. Continue with Configuring Access Manager 7.1 Using the Configurator.

Deploying the Access Manager WAR File in BEA WebLogic Server

Before you deploy the Access Manager WAR file, WebLogic Server must be installed and running on the host server.

For more information, see the WebLogic Server documentation: http://www.bea.com/.

For the versions of WebLogic Server that are supported as web containers for Access Manager 7.1, see the Sun Java System Access Manager 7.1 Release Notes.

Also, check the Release Notes for any issues and workarounds that apply to WebLogic Server.

ProcedureTo Deploy an Access Manager 7.1 WAR File in WebLogic Server

  1. On the host server where you want to deploy Access Manager, create a staging directory for the WAR file.

    For example, on a Solaris system: /opt/SUNWam/amwar_staging

  2. Copy the amserver.war file to the staging area.

    To get the amserver.war file, see Getting an Access Manager 7.1 War File.

  3. Backup the weblogic.policy file and then add the Java security permissions to this file, as shown in Adding Access Manager Permissions to the Server Policy File.

  4. Restart the WebLogic Server instance for the new entries to take effect.

  5. Deploy the amserver.war file using either the WebLogic Server Admin Console or the CLI.

  6. Depending on your platform, add the following JavaHelp JAR file (jhall.jar) to the CLASSPATH so the Access Manager Console online help is accessible:

    • Solaris systems: /usr/jdk/packages/javax.help-2.0/lib/jhall.jar

    • Linux systems: /usr/java/packages/javax.help-2.0/javahelp/lib/jhall.jar

  7. Continue with Configuring Access Manager 7.1 Using the Configurator.

Deploying an Access Manager 7.1 WAR File in IBM WebSphere Application Server

Before you deploy the Access Manager WAR file, WebSphere Application Server must be installed and running on the host server.

For more information, see the WebSphere Application Server documentation: http://www-306.ibm.com/software/webservers/appserv/was/.

For the versions of WebSphere Application Server that are supported as web containers for Access Manager 7.1, see the Sun Java System Access Manager 7.1 Release Notes.

Also, check the Release Notes for any issues and workarounds that apply to WebSphere Application Server.

ProcedureTo Deploy an Access Manager 7.1 WAR File in WebSphere Application Server

  1. On the host server where you want to deploy Access Manager, create a staging directory for the WAR file.

    For example, on a Solaris system: /opt/SUNWam/amwar_staging

  2. Copy the amserver.war file to the staging area.

    To get the amserver.war file, see Getting an Access Manager 7.1 War File.

  3. Modify the server.xml file as follows:

    1. Add the following JVM entries to allow Access Manager to function:

      genericJvmArguments="-Djava.awt.headless=true 
-DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE"/>

    2. If you are using SSL, add the following properties and JVM entry:

      </cacheGroups>
</services>
<properties xmi:id="Property_1120370477732" name="amCryptoDescriptor.provider" 
value="IBMJCE" required="false"/>
<properties xmi:id="Property_1120370511939" name="amKeyGenDescriptor.provider" 
value="IBMJCE" required="false"/>
      genericJvmArguments="-Djava.awt.headless=true 
-Djava.protocol.handler.pkgs=com.ibm.net.ssl.internal.www.protocol 
-DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE"/>

  4. Backup the server.policy file and then add the Java security permissions to the file, as shown in Adding Access Manager Permissions to the Server Policy File.

  5. Restart the WebSphere instance for the new entries to take effect.

  6. Deploy the amserver.war file using either the WebSphere Application Server Admin Console or the CLI.

  7. Depending on your platform, add the following JavaHelp JAR file (jhall.jar) to the classpath so the Access Manager Console online help is accessible:

    • Solaris systems: /usr/jdk/packages/javax.help-2.0/lib/jhall.jar

    • Linux systems: /usr/java/packages/javax.help-2.0/javahelp/lib/jhall.jar

  8. Continue with Configuring Access Manager 7.1 Using the Configurator.

Adding Access Manager Permissions to the Server Policy File

If Security Manager is enabled, add the Access Manager 7.1 permissions to the server policy file for the web container on which Access Manager will be deployed. The name of the server policy depends on the web container you are using.

Example 12–1 Access Manager Permissions in the Server Policy File

The following permissions apply to all Access Manager web containers.

// ADDITIONS FOR Access Manager
grant {
  permission java.net.SocketPermission "*", "connect,accept,resolve";
  permission java.util.PropertyPermission "*", "read, write";
  permission java.lang.RuntimePermission "modifyThreadGroup";
  permission java.lang.RuntimePermission "setFactory";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.util.logging.LoggingPermission "control";
  permission java.lang.RuntimePermission "shutdownHooks";
  permission javax.security.auth.AuthPermission "getLoginConfiguration";
  permission javax.security.auth.AuthPermission "setLoginConfiguration";
  permission javax.security.auth.AuthPermission "modifyPrincipals";
  permission javax.security.auth.AuthPermission "createLoginContext.*";
  permission java.io.FilePermission "<<ALL FILES>>", "execute,delete";
  permission java.util.PropertyPermission "java.util.logging.config.class", "write";
  permission java.security.SecurityPermission "removeProvider.SUN";
  permission java.security.SecurityPermission "insertProvider.SUN";
  permission javax.security.auth.AuthPermission "doAs";
  permission java.util.PropertyPermission "java.security.krb5.realm", "write";
  permission java.util.PropertyPermission "java.security.krb5.kdc", "write";
  permission java.util.PropertyPermission "java.security.auth.login.config", "write";
  permission java.util.PropertyPermission "user.language", "write";
  permission javax.security.auth.kerberos.ServicePermission "*", "accept";
  permission javax.net.ssl.SSLPermission "setHostnameVerifier";
  permission java.security.SecurityPermission "putProviderProperty.IAIK";
  permission java.security.SecurityPermission "removeProvider.IAIK";
  permission java.security.SecurityPermission "insertProvider.IAIK";
  permission java.security.SecurityPermission "getProperty.ocsp.*";
    };
// END OF ADDITIONS FOR Access Manager

Modifying the Server Policy File For Specific Applications

You can also specify that the permissions apply only to a specific application in a specific web container. For example, the following statement grants security permissions only to Access Manager deployed on Sun Java System Application Server. For other web containers, refer to the respective web container documentation for more information.

Example 12–2 Additions to the Server Policy File For Sun Java System Application Server

// ADDITIONS FOR Access Manager on Sun Java System Application Server
grant codeBase "file:\${com.sun.aas.instanceRoot}/applications/j2ee-modules/amserver/-" 
{

... // Permissions from the previous example 

}

Also, if you deploy Access Manager using a name other than amserver, change that name in the grant statement.

Configuring Access Manager 7.1 Using the Configurator

Access Manager 7.1 includes the Configurator (configurator.jsp) to configure Access Manager after you deploy a WAR file.

Caution – Caution –

Before you run the Configurator, make sure that the code set in the LANG environment variable is set to ISO8859-1. For example, to set the code set for U.S. English if you are using the sh or ksh shell:

# LANG=en_US.ISO8859-1

To launch Access Manager 7.1, specify the following URL in your browser:

http://host.domain:port/amserver

When you launch Access Manager 7.1, if you have not already configured the Access Manager instance, you will be directed to the Configurator page. If the Access Manager 7.1 instance is already configured successfully, you will be directed to the Access Manager Console login page.

ProcedureTo Configure Access Manager 7.1 Using the Configurator

  1. Enter the following values for the Access Manager Settings (or accept the default values).

    The Server Settings are independent of the datastore that you select (File System or Directory Server) to store the Access Manager configuration data.

    Server Settings

    Server URL 

    Host server where you plan to deploy Access Manager. Can be one of the following: 

    • Host name. For example: amhost1

    • Fully qualified domain name (FQDN). For example: http://amhost1.example.com

      If you plan to use the Access Manager client SDK or a policy agent, you must specify the FQDN.

    • localhost

    Default: Host where you are deploying Access Manager. 

    Cookie Domain 

    Name of the trusted DNS domain that Access Manager returns to a browser when it grants a SSO token to a user. Specify a value only if the FQDN is used as the Server URL. For example, if the FQDN for Server URL is http://amhost1.example.com, the default value is .example.com.

    If you selected only the host name or localhost for the Server URL, Cookie Domain is set to blank, and any value you enter is ignored.

    Administrator

    Name 

    amAdmin (read-only)

    Password 

    Access Manager administrator (amAdmin) password. Enter and then retype to confirm the password. The password must be at least 8 characters long.

    General Settings

    Configuration Directory 

    Base directory where the Access Manager configuration data is stored. The base directory applies to either File System or Directory Server, which you select under Configuration Store Settings.

    For example: /am_configuration_data

    Access Manager creates the following files and directories under the Configuration Directory: 

    • AMConfig.properties file

    • serverconfig.xml file

    • LDIF files (if you select Directory Server to store the service configuration data)

    • deploy-uri directory

    • deploy-uri/log directory

    • deploy-uri/stats directory

    • deploy-uri/debug directory

    • deploy-uri/idRepo directory: All users are created under this directory, even if you select Directory Server to store the service configuration data, since it is the default data store.

    • /deploy-uri/sms/ directory: Directories for the service configuration schema XML files

    deploy-uri is the Access Manager server deployment URI. The default is /amserver.

    The Access Manager instance determines the location of the Configuration Directory using the Access Manager 7.1 Single WAR Bootstrap File.

    Platform Locale 

    Default language subtype for Access Manager. Default: en_US (US English)

    Encryption Key 

    Random number that is used to encrypt passwords. Either accept the default encryption key value or specify a new value. The encryption key should be at least 12 characters long. 

    Multiple server deployment: If you are using the same WAR file to deploy multiple Access Manager instances in a multiple server deployment, you must use the same password encryption key value for each instance.

    See Requirements for an Access Manager Single WAR File Deployment.

  2. Select either of the following options to store the Access Manager configuration data:

    Configuration Store Settings

    File System 

    Access Manager stores the service configuration data in directories under the ConfigurationDirectory/amserver/sms directory.

    For example: /am_configuration_data/amserver/sms

    Default is File System. 

    Note: If you use an Access Manager server deployment URI other than amserver, that value is used instead of amserver for the directory name.

    Directory Server 

    Access Manager stores the service configuration data in Sun Java System Directory Server 6. 

    Directory Server 6 must be installed and running before you deploy the Access Manager 7.1 WAR file. 

    Note: All users are created under the /idRepo directory, even if you select Directory Server 6 to store the service configuration data.

  3. If you selected Directory Server in Step 2, provide values for the following settings:

    Server Settings

    Name 

    Fully qualified host name of Directory Server. For example: ds.example.com

    Port 

    Port at which Directory Server is running. Default: 389

    Suffix to store configuration data 

    Initial or root suffix in the directory where Access Manager configuration data will be stored. This value must exist in the Directory Server you are using. For example: dc=ds,dc=example,dc=com

    Directory Server Administrator

    Directory Administrator DN 

    Distinguished Name (DN) of the Directory Server Administrator. Default: cn=Directory Manager

    Password 

    Directory Server administrator password. Enter and then retype to confirm the password. The password must be at least eight characters long. 

    Load User Management Schema 

    Load Access Manager SDK Schema 

    If checked, the Configurator loads the Access Manager SDK schema object classes and attributes from sunone_schema2.ldif, ds_remote_schema.ldif, plugin.ldif, index.ldif and install.ldif into Directory Server.

    Otherwise, the Configurator loads only the Access Manager service management services (SMS) object classes and attributes from the am_sm_ds_schema.ldif file into Directory Server.

  4. Click Configure.

    (To reset all values, click Reset.)

Next Steps

The Configurator displays the configuration status:

Note –

If configuration was successful, you cannot reconfigure Access Manager using the Configurator. If you subsequently invoke the Configurator, Access Manager displays either the login page or the Console. If you are already logged in and have a valid session, you are redirected to the console. If you do not have a valid session, Access Manager displays the login page.

Access Manager 7.1 Single WAR Bootstrap File

An Access Manager instance deployed from a WAR file uses a bootstrap file to determine the location of its configuration data. The bootstrap file is an ASCII text file containing a single entry that specifies the location of the configuration directory for the specific Access Manager instance.

Each configured Access Manager instance on a host server has a unique bootstrap file. When you run the Configurator, a bootstrap file is created with the following name for the specific Access Manager instance: 

user-home-directory/AccessManager/AMConfig_deployed-instance-server-path_deploy-uri

Where:

For example, an Access Manager instance deployed by superuser (root) with Sun Java System Web Server 7 as the web container would have the following bootstrap file:

/AccessManager/AMConfig_var_opt_
SUNWwbsvr7_https-amhost.example.com_web-app_amhost.example.com_amserver

Each time the Access Manager web container is restarted, the Access Manager instance accesses the single WAR bootstrap file to determine the location of its configuration data. If the single WAR bootstrap file is deleted, Access Manager displays the Configurator page instead of the login page, which allows you to reconfigure the Access Manager instance.

The value in the bootstrap file is determined from the value you enter in the Configurator Configuration Directory field. For example:

/am_configuration_data

Specifying a Bootstrap File in a Different Directory

If you prefer, you can specify that the bootstrap file be created in a directory other than the user's home directory.

ProcedureTo Specify a Bootstrap File in a Different Directory:

  1. Create a staging area for the Access Manager WAR file (amserver.war) on the host server. For example: /amwar.

  2. Extract all files from the amserver.war file in the staging area. For example:

    # cd /amwar
# jar -xvf zip_root/applications/jdk15/amserver.war

    Where zip_root is the directory where you unzipped the Access Manager 7.1 WAR file.

  3. Add the following entry to the WEB-INF/web.xml file:

    <context-param>
<param-name>com.sun.identity.bootClassPath</param-name>
<param-value>/user_defined_directory</param-value>
</context-param>

    Where user_defined_directory is the new location of the bootstrap file.

  4. Create a new amserver.war file. For example: 

    # mkdir ../newamwar
# jar -cvf ../newamwar/amserver.war *

  5. Deploy the new Access Manager WAR file.

    In this example, if user_defined_directory is programs, the location of the bootstrap file would be:

    /programs/AccessManager/AMConfig_var_opt_
SUNWwbsvr7_https-amhost.example.com_web-app_amhost.example.com_amserver

Considerations for an Access Manager WAR File Deployment

If you deploy an Access Manager 7.1 WAR file, consider the following:

Using the Access Manager Utilities and Scripts with an Access Manager WAR File Deployment

After you have deployed and configured the Access Manager 7.1 from the WAR file, you will probably need to perform various administrative and configurations tasks. For example, you might need to run the amadmin utility or to configure Access Manager session failover. The Access Manager 7.1 ZIP file provides utilities, scripts, libraries, and other supporting files in the following zip files, available for you to download:

Each zip file contains files to support the following platforms:

For the specific versions that are supported for each platform, see the Sun Java System Access Manager 7.1 Release Notes.

Using the Utilities and Scripts in the amAdminTools.zip File

ProcedureTo Use the Utilities and Scripts in the amAdminTools.zip File

Before You Begin
Caution – Caution –

To run the setup utility, you must be using the Java Runtime Environment (JRE) 1.4 or later. Make sure that your JAVA_HOME and PATH environment variables point to the JDK installation directory for the version of the JDK that you are using.

  1. On Solaris and Linux systems, issue the following command before running the setup script:

    # chmod +x setup

  2. Create a new directory to unzip the files. For example: amtools

  3. Download the amAdminTools.zip file to the new directory and unzip the files.

  4. In the directory (amtools) where you unzipped the files, run the setup utility.

    On Windows systems, run the setup.bat utility.

    On Solaris and Linux systems, use this syntax to run the setup utility:

    setup -p | --path aminstancedir

    where aminstancedir is the path to the Access Manager configuration files, which includes the AMConfig.properties and serverconfig.xml files.

    If you run the setup utility without any options, the script prompts you for the path to the Access Manager configuration directory.

    If the path to the Access Manager configuration files contains a space, run the setup utility without any options and then provide the path when you are prompted.

    To display the help for the setup utility:

    setup -h | --help
Next Steps

You can now run the Access Manager CLI utilities and scripts from the directory where you unzipped the amAdminTools.zip file.

Troubleshooting

Using the amSessionTools.zip File For Access Manager Session Failover

ProcedureTo Use the Scripts and Related Files in the amSessionTools.zip File

Before You Begin
Caution – Caution –

To run the setup utility, you must be using the Java Runtime Environment (JRE) 1.4 or later. Make sure that your JAVA_HOME and PATH environment variables point to the JDK installation directory for the version of the JDK that you are using.

  1. Create a new directory to unzip the amSessionTools.zip file. For example: amsfotools

  2. Download the amSessionTools.zip file to the new directory and unzip the files.

  3. In the directory (amsfotools) where you unzipped the files, run the setup utility.

    On Windows systems, run the setup.bat utility.

    On Solaris and Linux systems, use this syntax to run the setup utility:

    setup -p | --path desireddir

    where desireddir is the directory where the setup utility unzips the session failover scripts and related files.

    If you run the setup utility without any options, the script prompts you for a path. If the path contains a space, run the setup utility without any options and then provide the path when you are prompted.

    The setup utility preforms these functions:

    • Unzips the session failover scripts and related files in the directory indicated by desireddir.

    • Unzips the files for Sun Java System Message Queue in the desireddir/jmq directory.

    • Unzips the files for BerkeleyDB in the desireddir/bdb directory.

    To display the help for the setup utility:

    setup -h | --help
Next Steps

You are now ready to configure Access Manager session failover. For more information, see Configuring Access Manager for Session Failover.

Managing an Access Manager 7.1 WAR File Deployment

After you deploy an Access Manager WAR file, you might need to perform the following tasks:

Redeploying an Access Manager Instance

In this scenario, you want to redeploy an Access Manager instance using the web container administration console or CLI commands, without having to reconfigure the Access Manager instance.

Access Manager uses the same datastore (either Directory Server or File System) that was configured to store the configuration data before the redeployment. The location of the configuration directory is not changed.

ProcedureTo Redeploy an Access Manager Instance

  1. Undeploy the Access Manager instance.

  2. Restart the Access Manager web container.

  3. Redeploy the Access Manager instance.

    After a successful redeployment, Access Manager accesses its configuration data either from Directory Server or File System by using the single WAR bootstrap file and then displays the login page.

Removing an Access Manager Instance

In this scenario, you want to completely remove an existing configured Access Manager instance that was deployed from a WAR file.

ProcedureTo Completely Remove an Access Manager Instance

  1. Undeploy Access Manager using the web container administration console or CLI command.

  2. Manually remove the Access Manager related additions from the server policy file.

  3. If you deployed Access Manager on IBM WebSphere Application Server, manually remove the Access Manager related entries from the web container's server.xml configuration file.

  4. From the Access Manager single WAR bootstrap file, determine the location of configuration directory for the instance.

    For information about the bootstrap file, see Access Manager 7.1 Single WAR Bootstrap File.

  5. Delete the Access Manager configuration directory.

  6. Delete the Access Manager instance specific single WAR bootstrap file.

  7. Restart the Access Manager web container for these changes to take effect.

Migrating From File System Configuration to Directory Server Configuration

In this scenario, you deployed Access Manager from a WAR file using the File System option to store the configuration data and you want to migrate the data to Directory Server. Command-line utilities are not provided to migrate the configuration data. Directory Server must be installed and running before you perform the following steps.

ProcedureTo Migrate From File System to Directory Server to Store Configuration Data

  1. From the Access Manager single WAR bootstrap file, determine the location of configuration directory for the instance.

    For information about the bootstrap file, see Access Manager 7.1 Single WAR Bootstrap File.

  2. Delete the configuration directory for the Access Manager instance.

  3. Restart the Access Manager web container using the web container administration console or CLI command.

  4. Reconfigure Access Manager using the Configurator and specify Directory Server to store the configuration data.

Uninstalling Access Manager Using the Java ES Uninstaller

Consider the following scenario:

  1. You installed Access Manager 7.1 by running the Java ES installer with the Configure Later option.

  2. You create an Access Manager WAR file by running the amconfig script with DEPLOY_LEVEL=10.

  3. You deployed the WAR file into a web container using the container's CLI or Admin console.

  4. You now want to uninstall Access Manager using the Java ES uninstaller.

The Java ES uninstaller uses the com.sun.identity.webcontainer property in the AMConfig.properties file to determine the Access Manager web container. For this scenario, this property is always set to WEB_CONTAINER, regardless of the web container where the Access Manager WAR file is actually deployed. During uninstallation, the uninstaller displays the Access Manager panel to gather Web Server information, even though the WAR file might be deployed on Sun Java System Application Server, BEA WebLogic Server, or IBM WebSphere Application Server.

To continue with the uninstallation, accept the default values in Access Manager Web Server uninstaller panel and click Force Uninstallation.