Chapter 12 Creating and Deploying OpenSSO Enterprise WAR Files

Sun^TM 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

• Deploying the OpenSSO Enterprise WAR File

• Customizing and Redeploying opensso.war

• Creating Specialized OpenSSO Enterprise WAR Files

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:

• Client components such as including dynamic web pages, applets, and a Web browser that run on the client machine.

• Web components such as servlets and Java Server Pages (JSPs) that run within a web container.

• Business components that meets the needs of a particular enterprise domain such as banking, retail, or finance. Such business components also run within a web container.

• Enterprise infrastructure software that runs on legacy machines.

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.

Servlets

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.

web.xml

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

Deploying the OpenSSO Enterprise WAR File

• OpenSSO Enterprise Deployment Considerations

• To Deploy the OpenSSO Enterprise Server 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:

• You deploy OpenSSO Enterprise from the opensso.war file, using the web container administration console or deployment command. You no longer run the Java Enterprise System installer.

• You initially configure OpenSSO Enterprise using either the GUI or command-line Configurator. Then, to perform additional configuration, you use either the Administration Console or the new ssoadm command-line utility. You no longer run the amconfig script using variables in the the amsamplesilent file as input.

• Configuration data, including policy agent configuration data, is stored in a centralized repository. This repository can be either Sun Java System Directory Server or the OpenSSO data store (which is usually transparent to the user). OpenSSO Enterprise server does not use the AMConfig.properties or serverconfig.xml files, except for co-existence with previous versions of Access Manager.

To 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 opensso_enterprise_80.zip file from one of the following sites:

   • Sun: http://www.sun.com/software/products/opensso_enterprise

     or

   • OpenSSO site: http://opensso.dev.java.net/public/use/index.html

   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:

   protocol://host.domain:port/deploy-uri
   

   For example: https://opensso.example.com:58080/opensso

   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:

   • Chapter 4, Configuring OpenSSO Enterprise Using the GUI Configurator, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide

     or

   • Chapter 5, Configuring OpenSSO Enterprise Using the Command-Line Configurator, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide

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 opensso_enterprise_80.zip file. The opensso.war file is then in the zip-root/deployable-war directory, where zip-root is where you unzipped the file.

To 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:

• Distributed Authentication UI server

• OpenSSO Administration Console only

• OpenSSO Enterprise server without the Administration Console

• IDP Discovery Service

If you have not already done so, download and unzip the opensso_enterprise_80.zip 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 opensso_enterprise_80.zip file:

• opensso.war contains all OpenSSO Enterprise components.

• fam-distauth.list, fam-console.list, fam-noconsole.list, or fam-idpdiscovery.list contain a list of files required to create a specialized WAR file.

• distauth, console, noconsole, and idpdiscovery directories contains the additional files you will need to create, deploy, and configure a specialized WAR file.

To 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 \
      @zip-root/opensso/deployable-war/war-file.list

   • 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:

• Chapter 8, Deploying a Distributed Authentication UI Server, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide

• Chapter 9, Deploying the Identity Provider (IDP) Discovery Service, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide

• Chapter 10, Installing the OpenSSO Enterprise Console Only, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide

• Chapter 11, Installing OpenSSO Enterprise Server Only, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide