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:
Installing and Configuring a Distributed Authentication UI Server Using the Java ES Installer
Accessing the Distributed Authentication User Interface Web Application
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.
The following figure shows a Distributed Authentication UI server deployment scenario.
In a typical deployment scenario using one or more Distributed Authentication UI servers, an end-user request follows this flow:
An end user sends an HTTP or HTTPS request from a Web browser to access a protected resource.
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).
The end user follows the redirect and sends a request to the Distributed Authentication UI server.
The Distributed Authentication UI server communicates the request to an Access Manager instance behind the second firewall to determine the appropriate authentication method.
The Access Manager instance determines the appropriate authentication method and then returns the presentation framework to the Distributed Authentication UI server.
Using the information from the Access Manager instance, the Distributed Authentication UI server returns a login page to the user's Web browser.
The end user replies with the login credentials (such as user name and password) to the Distributed Authentication UI server.
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.
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 (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.
Log in as or become superuser (root) on the Distributed Authentication UI server.
Get the Java ES installer. For information, see Getting the Java ES Installer.
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.
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.
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:
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.
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.
Restart the web container on the Distributed Authentication UI server.
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
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 involves these steps:
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.
The amauthdistui.war file is in the amDistAuth.zip file, which is part of the Access Manager 7. 1 ZIP file.
Create a new directory to download and unzip the Access Manager 7. 1 ZIP file.
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:
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.
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.
On the server where you plan to deploy the WAR file, create a directory for the ZIP file.
Copy the amDistAuth.zip file to the new directory you created in Step 1.
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.
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.
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.
Change to the directory on the server where you copied and unzipped the WAR file.
Change the permissions on the appropriate setup script to allow the script to execute:
Solaris and Linux systems: setup.sh
Windows systems: setup.bat
Invoke the appropriate setup script, depending on your platform.
For example, on Solaris systems:
# ./setup.sh
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.
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.
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.
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.
Login as (or become) superuser (root) on the server where you plan to deploy the WAR file.
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.
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
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
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 |
Install and configure the Distributed Authentication UI server on the web container.
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.
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.
Review the tuning recommendations in the debug log file. If needed, make changes to the amtune-env file based on this run.
To make tuning changes, set the AMTUNE_MODE variable to CHANGE in the amtune-env file.
Run the amtune script in change mode to make the tuning changes to the deployment.
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.
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
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).