Chapter 9 Deploying a Distributed Authentication UI Server

A Sun OpenSSO Enterprise Distributed Authentication UI server provides for secure, distributed authentication across two firewalls in an OpenSSO Enterprise deployment.

A Distributed Authentication UI server does not run OpenSSO Enterprise. This server exists only to provide the customizable authentication interface between end users and an OpenSSO Enterprise instance.

Topics in this chapter include:

• Distributed Authentication UI Server Overview

• Generating a Distributed Authentication UI Server WAR File

• Deploying the Distributed Authentication UI Server WAR File

• Configuring the Distributed Authentication UI Server

• Accessing the Distributed Authentication User Interface Web Application

Distributed Authentication UI Server Overview

• Distributed Authentication UI Server Deployment Scenario

• Requirements for a Distributed Authentication UI Server Deployment

Distributed Authentication UI Server Deployment Scenario

You install the Distributed Authentication UI server subcomponent on one or more servers within the DMZ layer of an OpenSSO Enterprise deployment. This subcomponent acts as an authentication interface between end users and the OpenSSO Enterprise instances behind the second firewall, thus eliminating the exposure of the OpenSSO Enterprise service URLs to the end users.

The following figure shows a Distributed Authentication UI server deployment scenario.

Figure 9–1 Distributed Authentication UI Server Deployment Scenario

Requirements for a Distributed Authentication UI Server Deployment

The Distributed Authentication UI server must be installed in a supported web container, as listed in OpenSSO Enterprise 8.0 Requirements.

To generate a Distributed Authentication UI server WAR file, your JAVA_HOME environment variable must point to a JDK of version 1.5 or later.

Several other considerations for a Distributed Authentication UI server include:

• If you are deploying multiple Distributed Authentication UI servers behind a load balancer, stickiness is not required for the load balancer to talk to only one Distributed Authentication UI server for authentication process completion.

• The Windows Desktop SSO and MSISDN authentication modules are not supported through the Distributed Authentication UI.

Generating a Distributed Authentication UI Server WAR File

To generate a Distributed Authentication UI server WAR file, use the jar command to extract the files from the opensso.war file and then to generate the specialized WAR file.

To Generate a Distributed Authentication UI Server WAR File

Before You Begin

If you have not already done so, download and unzip the opensso_enterprise_80.zip file. You will then need the following files:

• zip-root/deployable-war/opensso.war is the OpenSSO Enterprise WAR file that contains all components, including the Distributed Authentication UI server files.

• zip-root/deployable-war/fam-distauth.list specifies the files that are required to generate a Distributed Authentication UI server WAR file.

• zip-root/deployable-war/distauth contains the additional files you will need to deploy and configure a Distributed Authentication UI server.

where zip-root is the directory where you unzipped the opensso_enterprise_80.zip file.

For more information about the opensso.war file, see Downloading OpenSSO Enterprise.

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

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

   # mkdir dastaging
   # cd dastaging
   # jar xvf zip-root/opensso/deployable-war/opensso.war

3. Create the Distributed Authentication UI server WAR using the files in fam-distauth.list:

   # cd dastaging
   # jar cvf zip-root/opensso/deployable-war/openssoDistauth.war \
      @zip-root/opensso/deployable-war/fam-distauth.list

   where openssoDistauth.war is the name of the new Distributed Authentication UI server WAR file.

   Note: Some web containers require the Distributed Authentication WAR file name to use the same name as the deployment URI.

4. Update the WAR file created in previous step with the additional files required for the Distributed Authentication UI server WAR. For example:

   # cd zip-root/opensso/deployable-war/distauth
   # jar uvf zip-root/opensso/deployable-war/openssoDistauth.war *

   You are now ready to configure the new openssoDistauth.war, as described in the next section.

Deploying the Distributed Authentication UI Server WAR File

To Deploy the Distributed Authentication UI Server WAR File

Before You Begin

• The web container that you plan to use for the Distributed Authentication UI server must be installed. See Requirements for a Distributed Authentication UI Server Deployment for a list of the supported web containers.

• One or more OpenSSO Enterprise full server instances must be running remotely in the deployment.

1. Login as a user who has the following privileges:

   • Access to the web container administration console, if you plan to deploy Distributed Authentication UI server WAR file using the console.

     or

   • The capability to execute the web container's deploy command-line utility, if you plan to deploy the WAR file using the CLI.

2. Make sure that the Distributed Authentication UI server web container is running.

3. Deploy the Distributed Authentication UI WAR file using the using the web container administration console or deployment command.

Configuring the Distributed Authentication UI Server

OpenSSO Enterprise includes the Distributed Authentication UI server Configurator (distAuthConfigurator.jsp) to configure a Distributed Authentication UI server after you deploy the WAR file.

Default values. The default values for the Distributed Authentication UI server protocol, host, port, and deployment URI will be based on the URL used to access the Distributed Authentication UI server WAR file. For example, if you use http://distauth.example.com:8080/openssoDistAuth to access the Configurator, the protocol will be http, the host will be distauth.example.com, the port will be 8080, and the deployment URI will be /openssoDistAuth.

To Configure the Distributed Authentication UI Server

1. Make sure that the Distributed Authentication UI server web container is running.

2. Launch the Distributed Authentication UI server WAR file using the following URL:

   protocol://host.domain:port/distauth_uri
   

   For example: http://distauth.example.com:8080/openssoDistauth

   If the Distributed Authentication UI server is not already configured, you will be directed to the Configurator (distAuthConfigurator.jsp) page. (If the Distributed Authentication UI server is already configured, you will be directed to the login page.)

3. On the Configurator page, specify the following information:

   • Server Protocol is the OpenSSO Enterprise server protocol: http or https. Default: http

     Note: If the Distributed Authentication UI Server is being configured to use an SSL-enabled OpenSSO Enterprise server, you must import the root CA certificate for the server certificate on the OpenSSO Enterprise server into the trust store of the web container JVM on which the Distributed Authentication UI Server is being deployed. After you import the certificate, restart the web container instance.

   • Server Host is the fully qualified host name of the system where OpenSSO Enterprise server is deployed.

   • Server Port is the OpenSSO Enterprise server port number. Default: 8080

   • Server Deployment URI is the URI prefix for accessing the HTML pages, classes, and JAR files associated with OpenSSO Enterprise server.

   • DistAuth Server Protocol is the protocol (http or https) used by the Distributed Authentication UI server web container. Default: http

   • DistAuth Server Host is the fully qualified host name where the Distributed Authentication UI server is deployed.

   • DistAuth Server Port is the port number on DistAuth Server Host where the Distributed Authentication UI server is deployed. Default: 80

   • DistAuth Server Deployment URI is the deployment URI that will be used on the host by the Distributed Authentication UI server.

   • DistAuth Cookie Name is the cookie name used on the host by the Distributed Authentication UI server.

   • Debug directory is the directory where the debug files will be created.

   • Debug level is the level for the debug service. Values can be: error, warning, message or off. Default: error

   • Encryption Key is the password encryption key.

   • Application user name is the user name for the Distributed Authentication UI server application. For example: UrlAccessAgent

   • Application user password is the password of the user for the application.

   • Confirm Application user password is confirmation for the password.

4. After you have specified all configuration values (or accepted the default values), click Configure.

   (Or, to reset all values, click Reset.)

Next Steps

After the configuration finishes, you will get a message showing the location of the AMDistAuthConfig.properties configuration file. This file is created in the home directory of the runtime user who owns the web container instance on which the Distributed Authentication UI WAR file is deployed.

Important: It is highly recommended that you change the permissions of this configuration file to limit access to the sensitive configuration information.

Accessing the Distributed Authentication User Interface Web Application

To access the Distributed Authentication UI server application, use the following URL in your browser:

daserver_protocol://daserver_host:daserver_port/dadeploy_uri/UI/Login

Where:

• daserver_protocol is the protocol (http or https) used by the Distributed Authentication UI server web container instance.

• daserver_host is the fully qualified host name of the Distributed Authentication UI server.

• daserver_port is the port for the Distributed Authentication UI server host.

• dadeploy_URI is the deployment URI prefix for the Distributed Authentication UI server. The default value is the URI used to access the Configurator..

For example:

https://daserver.example.com:80/openssoDistauth/UI/Login

• In a production environment, the Distributed Authentication UI server web application is usually deployed in the DMZ layer. So, always specify the successful redirect URL to an absolute URL. For example:

  https://daserver.example.com:80/openssoDistauth/UI/Login?goto=/absolute-successful-redirect-URL/

• For testing purposes, if you use the server returned default successful redirect URL (which is the server OpenSSO Enterprise Admin Console URL) , make sure that you change this URL from its relative value to the absolute value before your move to a production environment by using the server Administration Console (Authentication Configuration > Properties).