Sun OpenSSO Enterprise 8.0 Developer's Guide

Chapter 12 Creating and Deploying OpenSSO Enterprise WAR Files

SunTM OpenSSO Enterprise is distributed as a web archive (WAR) file named opensso.war. In addition to deploying OpenSSO Enterprise server, you can also use opensso.war to create a customized server WAR file and specialized WAR files for an OpenSSO Enterprise Distributed Authentication UI server, the IDP Discovery Service, OpenSSO Enterprise Administration Console only, and OpenSSO Enterprise server without the Administration Console. This chapter describes these sections:

Overview of WAR Files in Java EE Software Development

OpenSSO Enterprise is built on the Java EE platform, which uses a component model to create full-scale applications. A component is self-contained functional software code assembled with other components into a Java EE application. The Java EE application components can be deployed separately on different servers. Java EE application components include the following:

Web Components

When a web browser executes a Java EE application, it deploys server-side objects known as web components. JSP and corresponding servlets are two such web components.


Small Java programs that dynamically process requests and construct responses from a web browser. Servlets run within web containers.

Java Server Pages (JSPs)

Text-based documents that contain static template data such as HTML, Scalable Vector Graphics (SVG), Wireless Markup Language (WML), or eXtensible Markup Language (XML). JSPs also contain elements such as servlets that construct dynamic content.

How Web Components are Packaged

Java EE components are usually packaged separately, and then bundled together into an Enterprise Archive (EAR) file for application deployment. Web components are packaged in WAR files. Each WAR file contains servlets, JSPs, a deployment descriptor, and related resource files.

Static HTML files and JSP are stored at the top level of the WAR directory. The top-level directory contains the WEB-INF subdirectory which contains tag library descriptor files in addition to the following:

Server-side classes

Servlets, JavaBean components and related Java class files. These must be stored in the WEB-INF/classes directory.

Auxiliary JARs

Tag libraries and any utility libraries called by server-side classes. These must be stored in the WEB-INF/lib directory.


The web component deployment descriptor is stored in the WEB-INF directory

Deploying the OpenSSO Enterprise WAR File

OpenSSO Enterprise Deployment Considerations

Before you deploy the OpenSSO Enterprise WAR file, here are a few changes to consider from previous releases of Access Manager and Federation Manager:

ProcedureTo Deploy the OpenSSO Enterprise Server WAR File:

The following procedure summarizes the OpensSSO Enterprise WAR file deployment. Links are provided to the detailed steps in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

  1. If necessary, install, configure, and start one of the supported web containers listed in Chapter 2, Deploying the OpenSSO Enterprise Web Container, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

  2. Download and unzip the file from one of the following sites:

    Be sure to check the Sun OpenSSO Enterprise 8.0 Release Notesfor any current issues.

  3. Deploy the opensso.war file to the web container, using the web container administration console or deployment command.

    Detailed steps are in Chapter 3, Installing OpenSSO Enterprise, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

  4. Run either the GUI or command-line Configurator.

    To run the GUI Configurator, enter the following URL in your browser:


    For example:

    If you are running the GUI Configurator, enter values in the Configurator fields or accept the default value for some fields. The GUI Configurator has two configuration options:

    • The Default Configuration option requires you to enter only the OpenSSO Enterprise administrator (amAdmin) and default policy agent (UrlAccessAgent) passwords. The Configurator then uses default values for the other configuration options.

      Use the Default Configuration for development environments or simple demonstration purposes when you just want to evaluate OpenSSO Enterprise features.

    • The Custom Configuration option allows you to enter specific configuration values for your deployment (or accept the default values).

      Use the Custom Configuration for production and more complex environments. For example, a multi-server installation with several OpenSSO Enterprise instances behind a load balancer.

    Detailed steps for configuring OpenSSO Enterprise are in:

  5. Launch OpenSSO Enterprise using the specific web container console or deployment command, or by specifying the URL from Step 4 in your browser.

  6. Login to the Console as the OpenSSO Enterprise administrator (amadmin) using the password you specified when you ran the Configurator.

  7. To make additional configuration changes to your deployment, use the OpenSSO Administration Console or the ssoadm command-line utility.

    For information, refer to the OpenSSO Administration Console Online Help or the Sun OpenSSO Enterprise 8.0 Administration Reference.

Customizing and Redeploying opensso.war

The opensso.war file contains all OpenSSO Enterprise components. To customize OpenSSO Enterprise, you must update and redeploy this file.

If you have not already done so, download and unzip the file. The opensso.war file is then in the zip-root/deployable-war directory, where zip-root is where you unzipped the file.

ProcedureTo Customize and Redeploy opensso.war

  1. Make sure that your JAVA_HOME environment variable points to a JDK of version 1.5 or later.

  2. Create a staging directory for your customized WAR file. For example:

    # mkdir customized-opensso
  3. In the staging directory, extract the files from opensso.war:

    # cd customized-opensso
    # jar xvf zip-root/opensso/deployable-war/opensso.war
  4. Customize the files required for your deployment.

  5. Create the new customized WAR file:

    # cd customized-opensso
    # jar cvf zip-root/opensso/deployable-war/customized-opensso.war

    In this example. customized-opensso.war is the name of the new customized OpenSSO Enterprise WAR file.

  6. Deploy and configure the new customized OpenSSO WAR file in your specific web container, as described in the Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

Creating Specialized OpenSSO Enterprise WAR Files

You can use the opensso.war file to create these specialized WAR files:

If you have not already done so, download and unzip the file. You will then need the following files in the zip-root/deployable-war directory to create a specialized WAR file, where zip-root is where you unzipped the file:

ProcedureTo Create a Specialized OpenSSO Enterprise WAR File

  1. Make sure that your JAVA_HOME environment variable points to a JDK of version 1.5 or later.

  2. Create a staging directory and extract the files from opensso.war in this staging directory. For example:

    # mkdir opensso-staging
    # cd opensso-staging
    # jar xvf zip-root/opensso/deployable-war/opensso.war
  3. Create the new specialized WAR file, as follows:

    # cd opensso-staging
    # jar cvf zip-root/opensso/deployable-war/new-war-filename.war \
    • new-war-filename is the name of the new WAR file. For example: opensso-distauth.war, opensso-idpdiscovery.war, opensso-consoleonly.war, or opensso-noconsole.war.

      Note: Some web containers require the Distributed Authentication UI server WAR file name to use the same name as the deployment URI. Check with your web container documentation for more information.

    • war-file.list specifies the list of files required for the new WAR file, as follows: fam-distauth.list, fam-console.list, or fam-noconsole.list, or fam-idpdiscovery.list.

  4. Update the WAR file created in previous step with the additional files required for new specialized WAR file. For example:

    # cd zip-root/opensso/deployable-war/specialized-files-directory
    # jar uvf zip-root/opensso/deployable-war/new-war-filename.war *
    • specialized-files-directory specifies the directory where the additional files reside:

      • distauth

      • console

      • noconsole

      • idpdiscovery

    • new-war-filename is the name of the new specialized WAR file.

Next Steps

You are now ready to deploy and configure the new specialized WAR file. For the detailed steps, see the following chapters: