Chapter 11 Deploying a Distributed Authentication UI Server

A Distributed Authentication UI server provides for secure, distributed authentication across two firewalls in an Access Manager deployment. You install the Distributed Authentication UI subcomponent on one or more servers within the non-secure (DMZ) layer of an Access Manager deployment. This subcomponent acts as an authentication interface between end users and the Access Manager instances behind the second firewall, thus eliminating the exposure of the Access Manager service URLs to the end users.

A Distributed Authentication UI server does not run Access Manager; it exists only to provide the authentication interface between end users and an Access Manager instance. This chapter describes these topics:

• Distributed Authentication UI Server Overview

• Installing and Configuring a Distributed Authentication UI Server Using the Java ES Installer

• Deploying a Distributed Authentication UI Server WAR File

• Tuning the Web Container

• Accessing the Distributed Authentication User Interface Web Application

Distributed Authentication UI Server Overview

• Requirements for a Distributed Authentication UI Server Deployment

• Distributed Authentication UI Server Deployment Scenario

• Flow for a Distributed Authentication End-User Request

Requirements for a Distributed Authentication UI Server Deployment

Requirements for a Distributed Authentication UI server deployment include:

• The Distributed Authentication UI server must be installed in one of these web containers:

  • Sun Java System Application Server

  • Sun Java System Web Server

  • BEA WebLogic Server

  • IBM WebSphere Application Server

  For the specific versions supported of each web container, see the Sun Java System Access Manager 7.1 Release Notes.

• A Distributed Authentication UI server must use the same password encryption key as the Access Manager server instances in the deployment.

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 HTTP Basic and MSISDN authentication modules are not supported through the Distributed Authentication UI.

Distributed Authentication UI Server Deployment Scenario

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

Figure 11–1 Distributed Authentication UI Server Deployment Scenario

Flow for a Distributed Authentication End-User Request

In a typical deployment scenario using one or more Distributed Authentication UI servers, an end-user request follows this flow:

1. An end user sends an HTTP or HTTPS request from a Web browser to access a protected resource.

2. If the request does not have a cookie containing an SSO token, the Access Manager policy agent issues a redirect to its authentication URL, which is the URL of the Distributed Authentication UI server in the DMZ (usually through a load balancer).

3. The end user follows the redirect and sends a request to the Distributed Authentication UI server.

4. The Distributed Authentication UI server communicates the request to an Access Manager instance behind the second firewall to determine the appropriate authentication method.

5. The Access Manager instance determines the appropriate authentication method and then returns the presentation framework to the Distributed Authentication UI server.

6. Using the information from the Access Manager instance, the Distributed Authentication UI server returns a login page to the user's Web browser.

7. The end user replies with the login credentials (such as user name and password) to the Distributed Authentication UI server.

8. The Distributed Authentication UI server uses the Access Manager Client SDK to send the end user's credentials to the Access Manager instance behind the second firewall.

9. Access Manager tries to authenticate the end user using the appropriate authentication method:

   • If the authentication is successful, Access Manager returns the SSO token, and the Distributed Authentication UI server redirects the end user to the protected resource.

   • If the authentication is not successful, Access Manager returns the appropriate error information.

Installing and Configuring a Distributed Authentication UI Server Using the Java ES Installer

Installing and configuring (or reconfiguring) a Distributed Authentication UI server involves running the Java ES installer and the amconfig script on the server. One or more Access Manager full server instances must be installed and running remotely in the deployment.

To Install and Configure a Distributed Authentication UI Server

1. Log in as or become superuser (root) on the Distributed Authentication UI server.

2. Get the Java ES installer. For information, see Getting the Java ES Installer.

3. Install the Access Manager web container that you plan to use for the Distributed Authentication UI server:

   • Web Server or Application Server: Install using the Java ES installer.

   • BEA WebLogic Server or IBM WebSphere Application Server: See the respective BEA or IBM product documentation for installation instructions.

4. Install the Distributed Authentication UI subcomponent by running the Java ES installer with either the Configure Now or Configure Later option. On the installer Component Selection page, check Distributed Authentication.

   If you are using the Configure Now option, see Distributed Authentication UI Server Configuration Variables for the values that you must specify during installation.

5. If you specified the Configure Later option during the previous step, or if you need to reconfigure the Distributed Authentication UI server, run the amconfig script as follows:

   1. Copy the amsamplesilent file and set the configuration variables in the new file. For example, you might name the new file as DistAuth_config.

      On Windows systems, copy the AMConfigurator.properties file to AMConfigurator-distauth.properties.

      For the variables that you need to set, see Distributed Authentication UI Server Configuration Variables.

   2. Run the amconfig script using the new configuration file. For example, on a Solaris system with Access Manager installed in the default directory:

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

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

6. Restart the web container on the Distributed Authentication UI server.

---

Example 11–1 Distributed Authentication UI Server Sample Configuration File

DEPLOY_LEVEL=8
DISTAUTH_PROTOCOL=http
DISTAUTH_HOST=distauth.example.com
DISTAUTH_PORT=80
APPLICATION_USER=username
APPLICATION_PASSWD=application-user-password
AM_ENC_SECRET=am-secret-password
AM_ENC_LOCAL=am-password-encryption-key-used-by-the-Access-Manager-server
DEBUG_LEVEL=error
DEBUG_DIR=/var/opt/SUNWam/logs

---

Distributed Authentication UI Server Configuration Variables

Table 11–1 Distributed Authentication UI Server Configuration Variables

Variable	Description
DEPLOY_LEVEL	DEPLOY_LEVEL=8  - Configure (or reconfigure) a Distributed Authentication UI server. DEPLOY_LEVEL=18 - Uninstall a Distributed Authentication UI server.
SERVER_HOST, SERVER_PORT SERVER_DEPLOY_URI, CONSOLE_DEPLOY_URI ADMINPASSWD, AMLDAPUSERPASSWD, COOKIE_DOMAIN, AM_ENC_PWD	Corresponding values that used for the full Access Manager server installation.  Important You must set the password encryption key (AM_ENC_PWD) to the same value used by the Access Manager server instance.
DS_HOST, DS_DIRMGRPASSWD, and ROOT_SUFFIX	Corresponding Directory Server values that were used for the full Access Manager server installation.
NEW_OWNER and NEW_GROUP	Runtime user and group that will own the web container processes on which the Distributed Authentication UI server will be deployed.
PAM_SERVICE_NAME	If the Distributed Authentication UI server host is running the Linux OS, set to password.
WEB_CONTAINER Web container configuration variables	Web container on which the Distributed Authentication UI server is or will be deployed.  For example, if the web container is Sun Java System Web Server 7, set WEB_CONTAINER=WS. Set the configuration variables for the web container specified by WEB_CONTAINER. For more information, see Web Container Configuration Variables.
DISTAUTH_PROTOCOL	Protocol (http or https) used by the web container instance on which the Distributed Authentication UI server is or will be deployed. Default: http
DISTAUTH_HOST	Fully qualified host name where the Distributed Authentication UI server is located. Default: distAuth_sample.com
DISTAUTH_PORT	Port on DISTAUTH_HOST on which the Distributed Authentication UI server has been or will be deployed. Default: 80
APPLICATION_USER	User name for the application. Default: username
APPLICATION_PASSWD	Password of the user for the application. Default: none
AM_ENC_SECRET	Password encryption secret key from the server. Default: none
AM_ENC_LOCAL	Password encryption key. Default: none
DEBUG_LEVEL	Level for the debug service. Values can be: error, warning, or message. Default: error
DEBUG_DIR	Directory where the debug files will be created. Default:   Solaris systems: /var/opt/SUNWam/logs Linux and HP-UX systems: /var/opt/sun/identity/logs Windows systems: javaes-install-dir\identity\logs javaes-install-dir represents the Java ES 5 installation directory. The default value is C:\Program Files\Sun\JavaES5.
BASEDIR	Base directory where the Distributed Authentication UI server was installed.
CONSOLE_HOST, CONSOLE_PORT, and CONSOLE_PROTOCOL	Corresponding values for the host on which the Access Manager console has been deployed.
CONSOLE_REMOTE	Specifies whether the Access Manager Console is on a different web container than the Access Manager server. The default value is false.
DISTAUTH_DEPLOY_URI	Deployment URI that will be used on the local host by the Distributed Authentication UI server. The default value is /amdistauth.

Deploying a Distributed Authentication UI Server WAR File

Deploying a Distributed Authentication UI server WAR file involves these steps:

• Getting the amauthdistui.war File

• Copying and Unzipping the amDistAuth.zip File

• Building the amauthdistui.war File

• Deploying the Distributed Authentication UI Server WAR File

You can also deploy a Distributed Authentication UI server using the Java ES installer and amconfig script. For more information, see Installing and Configuring a Distributed Authentication UI Server Using the Java ES Installer.

Getting the amauthdistui.war File

The amauthdistui.war file is in the amDistAuth.zip file, which is part of the Access Manager 7. 1 ZIP file.

To Get the amauthdistui.war File:

1. Create a new directory to download and unzip the Access Manager 7. 1 ZIP file.

2. Download the Access Manager 7. 1 ZIP file to the new directory you created in Step 1 from “Identity Management > Access Manager” on the following web site:

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

3. Unzip the Access Manager 7. 1 ZIP file.

   The amDistAuth.zip file contains the amauthdistui.war file as well as other files required to configure the WAR file.

   For the layout of the Access Manager 7. 1 ZIP file, see Table 12–2.

Copying and Unzipping the amDistAuth.zip File

If you downloaded and unzipped the Access Manager 7. 1 ZIP file on the host server where Access Manager server is (or will be) deployed, you must copy the amDistAuth.zip file to the server where you plan to deploy the amauthdistui.war file.

To Copy and Unzip the amDistAuth.zip File:

1. On the server where you plan to deploy the WAR file, create a directory for the ZIP file.

2. Copy the amDistAuth.zip file to the new directory you created in Step 1.

3. Unzip the amDistAuth.zip file.

   Table 11–2 shows the amDistAuth.zip file layout. The directory where you unzip the file is represented by zip_root.

Layout of the amDistAuth.zip File

Table 11–2 Layout of the amDistAuth.zip File

Directory	Description
zip_root	README.distAuthUI describes the contents of the ZIP file. amauthdistui.war is the Distributed Authentication UI server WAR file. Setup scripts are used to build the properties files and Distributed Authentication UI server web application:  Solaris and Linux systems: setup.sh Windows systems: setup.bat
zip_root/lib/	setup.jar is a JAR file used by the setup scripts.
zip_root/WEB-INF/classes/	AMConfigTemplate.properties is the configuration template file used to update the AMConfig.properties file in the amauthdistui.war file. Important: Do not edit this file manually.

Building the amauthdistui.war File

Before you can deploy the amauthdistui.war file, you must run the setup script to add the configuration values to the AMConfig.properties configuration file in the amauthdistui.war file. The setup script uses the WEB-INF/classes/AMConfigTemplate.properties file to generate the AMConfig.properties file.

---

Note –

Before you run the setup script, make sure that your JAVA_HOME environment variable is set to the JDK installation directory for the version of the JDK that you are using.

---

To Build the amauthdistui.war File:

1. Change to the directory on the server where you copied and unzipped the WAR file.

2. Change the permissions on the appropriate setup script to allow the script to execute:

   • Solaris and Linux systems: setup.sh

   • Windows systems: setup.bat

3. Invoke the appropriate setup script, depending on your platform.

   For example, on Solaris systems:

   # ./setup.sh

4. When the setup script prompts you, enter values for the following items:

   • Debug directory where the debug files will be created

   • Application user name and password

   • Access Manager server protocol. For example: http or https

   • Access Manager server fully qualified host name

   • Access Manager server port

   • Access Manager server deployment URI. For example: amserver. Do not specify the slash (/).

   • Access Manager server naming URL to get the naming service

   • Distributed Authentication UI server protocol

   • Distributed Authentication UI server fully qualified host name

   • Distributed Authentication UI server port

   • Distributed Authentication UI server deployment URI. For example: distauth. Do not specify the slash (/).

   • Notification URL where notifications will be sent

   After you provide these values, the setup script updates the AMConfig.properties file in the amauthdistui.war file.

WAR File Name

Some web containers require the WAR file name to use the same name as the deployment URI. If so, rename the amauthdistui.war file to the Distributed Authentication UI server deployment URI that you provided when you ran the setup script in the previous Step 4.

Deploying the Distributed Authentication UI Server WAR File

Deploy the Distributed Authentication UI server WAR file (amauthdistui.war, or the name you are using for the WAR file, if you changed the name), to one of the following web containers:

• Sun Java System Web Server 7

• Sun Java System Application Server Enterprise Edition (EE) 8.2

• BEA WebLogic Server

• IBM WebSphere Application Server

For the supported web container versions, see the Sun Java System Access Manager 7.1 Release Notes.

To Deploy the Distributed Authentication UI Server WAR File:

Before You Begin

Before you deploy the WAR file, the web container must be installed and running on the server where you plan to deploy the WAR file.

1. Login as (or become) superuser (root) on the server where you plan to deploy the WAR file.

2. Deploy the amauthdistui.war file (or the name you are using for the WAR file, if you changed the name) using either the web container administration console or CLI command.

---

Example 11–2 Deploying the Distributed Authentication UI Server WAR File

The following examples use the web container CLI commands. You can also deploy the WAR file using the web container administration console.

Web Server 7

If Web Server 7 is the web container, use the wadm command to deploy the WAR file. For example, on Solaris systems:

# cd /opt/SUNWwbsvr7/bin
# ./wadm add-webapp --user=admin --host=dist-auth-server-host
--port=dist-auth-port --config=web-server-configuration-name
--vs=web-server-virtual-server --uri=/dist-auth-deploy-uri
zip_root/amauthdistui.war

# ./wadm deploy-config --user=admin --host=dist-auth-server-host
--port=dist-auth-port --restart=true web-server-configuration-name

Enter the Web Server 7 administration password when you are prompted.

Application Server EE 8.2

If Application Server EE 8.2 is the web container, first create a password file to be used when you deploy the WAR file. For example: /tmp/pwdfile.

Set the following variable in the password file:

AS_ADMIN_PASSWORD=application-server-admin-password

Then, use the asadmin deploy command to deploy the WAR file. For example, on Solaris systems:

# cd /opt/SUNWappserver/appserver/bin
# ./asadmin deploy --user appserver-admin
--passwordfile /tmp/pwdfile --port 4849
--contextroot dist-auth-deploy-uri --name dist-auth-deploy-uri
--target dist-auth-server-host 
zip_root/amauthdistui.war

---

See Also

• Web Server wadm command: Chapter 9, Deploying Web Applications, in Sun Java System Web Server 7.0 Developer’s Guide to Java Web Applications.

• Application Server asadmin deploy command: Deploying an Application in Sun Java System Application Server Enterprise Edition 8.2 Quick Start Guide

• BEA WebLogic Server documentation: http://www.bea.com/

• IBM WebSphere Application Server documentation: http://www-306.ibm.com/software/webservers/appserv/was/

• Issues and workarounds that apply to WebLogic Server or WebSphere Application Server: Sun Java System Access Manager 7.1 Release Notes

Tuning the Web Container

After you deploy the Distributed Authentication UI server on a web container, consider tuning the web container by running the Access Manager tuning scripts. The following tuning scripts set the JVM and other tuning options for the respective web containers:

Table 11–3 Access Manager Web Container Tuning Scripts

Web Container	Tuning Script Called by amtune Script
Web Server 7.0	amtune-ws7
Web Server 6.1 2005Q4 SP5	amtune-ws61
Application Server Enterprise Edition 8.2  Application Server Enterprise Edition 8.1	amtune-as8
Application Server 7	amtune-as7

To Tune a Web Container for a Distributed Authentication UI Server

Before You Begin

Install and configure the Distributed Authentication UI server on the web container.

1. Edit the parameters in the amtune-env configuration file to specify the web container and tuning options.

   To run the script in review mode, set the AMTUNE_MODE variable to REVIEW in the amtune-env file.

2. Run the amtune script in review mode, which calls the appropriate web container script based on values in the amtune-env file.

   In review mode, the amtune script suggests tuning recommendations but does not make any changes to the deployment.

3. Review the tuning recommendations in the debug log file. If needed, make changes to the amtune-env file based on this run.

4. To make tuning changes, set the AMTUNE_MODE variable to CHANGE in the amtune-env file.

5. Run the amtune script in change mode to make the tuning changes to the deployment.

See Also

For more information about running the amtune script to tune an Access Manager web container, see Chapter 2, Access Manager Tuning Scripts, in Sun Java System Access Manager 7.1 Performance Tuning and Troubleshooting Guide.

Accessing the Distributed Authentication User Interface Web Application

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

DA_server_protocol://DA_server_host: DA_server_port/DA_deploy_URI/UI/Login

Where:

DA_server_protocol	Protocol (http or https) used by the web container instance on which the Distributed Authentication UI server is deployed.
DA_server_host	Fully qualified host name of the Distributed Authentication UI server.
DA_server_port	Port for the host name of the Distributed Authentication UI server.
DA_deploy_URI	Deployment URI prefix for the Distributed Authentication UI server. The default value is /amdistauth.

For example:

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

---

Note –

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

For testing purposes, if you use the server returned default successful redirect URL (which is server Access Manager 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 Admin Console (Authentication Configuration > Properties).

---