Configuring the Web Server SSM

This section describes tasks you must perform after installing the Web Server SSM. This SSM supports Microsoft IIS and Apache Web Server.

Requirements

The Web Server SSM uses the Web Service SSM. Before performing the tasks described in this chapter, you must configure the Web Service SSM as described in Configuring SSMs Using ConfigTool.

Creating a Web Server SSM Instance

Start the Instance Wizard:

On Windows, click Start > Programs > BEA AquaLogic Enterprise Security > <Type of Security Service Module> > Create New Instance.
On UNIX, if you are using X-windows, go to BEA_HOME/ales30-ssm/<ssm-type>/adm and enter: instancewizard.sh. If you are not using X-windows, use a console based installer.

In the Instance Name field, enter an instance name. Then specify Web Service SSM port number and click Next.
In the Location field, accept the default location or specify a different directory and click Next.
When wizard completes, click Done.

After creating an Apache Web Server SSM, you must add the Apache user to the asiusers group. This gives the Administration Server the permissions required to access the Apache Web Server SSM instance and deploy the security policy and the security configuration.
For the IIS Web Server SSM, Table 5-1 indicates information that is added to the Microsoft Windows Registry:

HKEY_LOCAL_MACHINE\SOFTWARE\BEA Systems\ALES\IIS Module\3.0

Table 5-1 IIS SSM Registry Entries
Value Name	Description/Setting
`ALES_HTTP_SERVER`	The IIS SSM instance’s `config` directory.
ALES_INSTALL_DIR	The SSM’s installation directory.
`ALES_LOG_LEVEL`	The log level. The default level is `2` (INFORMATIONAL).

Enrolling the Web Server SSM Instance

Enrollment is the process by which an ALES component such as an SCM or SSM registers with an Administration Server.

As part of this process, the SSM system exchanges security certificates with the associated ALES Administration Server.

You must have the Administration Server running prior to enrolling the Security Service Module.

Open a command window and go to the Security Service Module instance /adm directory: BEA_HOME/ales30-ssm/<ssm-type>/instance/instancename/adm, where instancename is the name you assigned to the instance when you created it.
Run the following script:

enroll demo

Enter the admin username and password. This is the username and password of the Security Administrator doing the enrollment (if you used the default values and have not yet changed them, the default username is system and the password is weblogic).
Enter and confirm the following passwords:

Private key password—This password protects the identity of the Security Service Module that you are creating.
identity.jceks password—This password protects the ssl\identity.jks keystore. This keystore contains the identities for all the components you are enrolling.
peer.jks password—This password protects the ssl\peer.jks keystore. This keystore contains the certificates of components with which this Security Service Module can communicate.
trust.jks password—This password protects the ssl\trust.jks keystore. This keystore contains the AquaLogic Enterprise Security CA certificate used for enrollment.

For more information on enrolltool utility options, see Administrative Utilities in the ALES Administration Reference.

Start the Web Service SSM

Create and Bind the Corresponding SSM

Use the Administration Console to create a corresponding SSM.
Specify which security providers it will use.
Bind it to the SCM in the Administration Console.

Create a Corresponding SSM in the Administration Console

The Web Service SSM and the Web Server SSM are installed as a combo. The Web Service SSM instance you created on the remote system has a Configuration ID that will correspond to the SSM you create in the Administration Console. (The Web Server SSM does not have a Configuration ID.)

That is, in your ALES environment you will have two SSMs with the same Configuration ID: one (the instance) on the system where the SSM is installed, and a corresponding one on the Administration Server system.

In the Administration Console, expand the Security Configuration node in the left pane, and click Unbound Configurations. The Unbound Security Service Module Configurations page displays.
Click Create a New Security Service Module Configuration. The Edit Security Service Module Configuration page displays.
In the Configuration ID text box, enter the matching Configuration ID for the SSM.
In the Configuration Version dropdown box, select Java SSM 3.0, WS SSM 3.0.
Click Create.

Add Security Providers

After you create the SSM, the Providers tab becomes active. The tab for a given provider type provides additional information. At a minimum you must have one authorization provider for each SSM.

Bind Everything Together

Click on the SCM that you previously configured for this SSM. The Edit a Service Control Manager Configuration page displays.
Click on the Binding tab and bind your new SSM configuration to the SCM.

Configuring the Web Server Environmental Binding

The Web Server Environmental Binding configuration procedures vary depending on the type of Web Server SSM you are configuring. AquaLogic Enterprise Security supports two Web server SSMs that require configuration of the Web Server Environmental Binding: the Microsoft IIS Web Server SSM and the Apache Web Server SSM.

Microsoft IIS Web Server

To configure the environmental binding for Microsoft IIS Web Server, perform the following tasks:

Configuring the Microsoft IIS Web Server Binding Plug-In File

The IIS Web Server Binding plug-in file is named wles_isapi.dll. This file is located in the BEA_HOME\ales30-ssm\iis-ssm\lib directory.

To configure the Microsoft IIS Web Binding plug-in, perform the following steps:

To open the Internet Information Services Manger, click Start>Settings>Control Panel, select Administrative Tools, and double-click Internet Services Manager. The Internet Information Services Window appears.
In the left-hand pane, expand the machine node, right click Default Web Site, and select Properties. The Default Web Site Properties dialog box appears (see Figure 5-1).

Figure 5-1 IIS Web Site Properties Dialog

IIS Web Site Properties Dialog

Click the ISAPI Filters tab, click the Add button, assign a name to the ISAPI filter, use the Browse button to add the wles_isapi.dll file (which is located in BEA_HOME\ales30-ssm\iis-ssm\lib directory), and click OK.
Click the Directory Security tab. The Authentication Methods dialog appears (see Figure 5-2).

Figure 5-2 Authentication Methods Dialog

Authentication Methods Dialog

Click the Edit button for Anonymous Access, check the Anonymous username, and, if necessary, change the username and password to ensure that the Anonymous user has Read and Read/Execute permissions on the following directories:

BEA_HOME\ales30-ssm\iis-ssm\lib
BEA_HOME\ales30-ssm\iis-ssm\instance\iisssmdemo\ssl
BEA_HOME\ales30-ssm\iis-ssm\instance\iisssmdemo\config

If you put the NamePasswordForm.acc file in a virtual directory, repeat the previous step for the virtual directory as well.
Return to the Default Web Site Properties dialog box (see Figure 5-1) and click the Home Directory tab. The Home Directory dialog appears (see Figure 5-3).

Figure 5-3 IIS Web Site Home Directory Dialog

IIS Web Site Home Directory Dialog

Verify that the property settings match the information in Table 5-2 and click Apply and OK.

Table 5-2 Home Directory Setting
Property	Setting
Local Path	`c:\inetpub\wwwroot`
Application name	Default Application
Execute Permissions	Scripts Only

Click the Configuration button. The Application Configuration dialog appears (see Figure 5-4).

Figure 5-4 IIS Web Site Application Configuration Dialog

IIS Web Site Application Configuration Dialog

Click the Add button. The Add/Edit Application Extension Mapping Dialog appears (see Figure 5-5).

Figure 5-5 IIS Web Site Add/Edit Application Extension Mapping Dialog

IIS Web Site Add/Edit Application Extension Mapping Dialog

Use the Browse button to add the wles_isapi.dll file to the Executable field, fill in the other fields as shown in Figure 5-5, and click OK.
Click OK to close the remaining windows.
Right click the Default Web Site again and start the Default Web Site. (Stop the Web Site first if necessary.)
Re-open the Default Web Site Properties dialog box and select the ISAPI Filters tab. The IIS Web Server Binding Plug-in status shows a green arrow to indicate that the IIS Web Server Binding Plug-in is loaded. If the green arrow is not displayed, add the wles_isapi.dll file again and start the IIS Web Server.

Note:

Be sure to start the IIS Web server with IIS SSM after you have started the Web Service SSM and ARME.

Configuring the NamePasswordForm.acc File for the IIS Web Server

Deploying and Testing the IIS Web Server Sample Application

Set up the IIS Server/wwwroot/test directory as shown in Figure 5-6 and copy the following files to the test directory:

NamePasswordForm.acc
foo.html
atnfailure.html
atzfailure.html

Note: The NamePasswordForm.acc file is provided in the BEA_HOME\ales30-ssm\iis-ssm\instance\<instancename>\templates directory. The foo.html, atnfailure.html and atzfailure.html files are not provided in the product installation kit. You should use your own versions of these files.

Figure 5-6 Deploying the Sample Application on the IIS Web Server

Deploying the Sample Application on the IIS Web Server

Start the IIS Web Server, open a browser and go to http://<machine_name_with DNS_suffix>:80/test/foo.html.
You are redirected to NamePasswordForm.acc.
Enter the system username/password (a default system username and password was set when you installed the Administration Application) and click OK. You are granted access to foo.html.

Apache Web Server

Downloading and Installing the Apache Web Server

To download and install the Apache Web Server software, perform the following steps:

Go to the Apache download web site at http://httpd.apache.org/download.cgi and download and install the software.
Verify the following two modules are included in the installation:

ServerRoot/modules/mod_include.so
ServerRoot/modules/mod_ssl.so

where ServerRoot is the Apache installation directory.

Note:

The Apache Web Server Security Service Module (SSM) requires that the above two modules be included in the Apache installation; otherwise the Secure Sockets Layer (SSL) and the Security Assertion Markup Language (SAML) server-server include (SSI) related functions will not work.

Note:

You may build your own 2.0.x version of the Apache Web Server with the above mentioned modules. If the modules are built into Apache, there may be no such files.

Configuring the ALES Module

The ALES module contains only one file. For Windows, the file name is mod_wles.dll. For Sun Solaris and Linux, the file name is mod_wles.so.

Open the ServerRoot/conf/httpd.conf file and add a LoadModule directive. There are several LoadModule directives in the LoadModule section of the httpd.conf file. Add the following line to the end of the LoadModule section:

LoadModule wles_module <APACHE_SSM_HOME>/lib/mod_wles.so

where <APACHE_SSM_HOME> is the Apache Web Server SSM installation directory.

For example:

For Windows systems:

LoadModule wles_module c:\bea\ales30-ssm\apache-ssm\lib\mod_wles.dll

For UNIX systems:

LoadModule wles_module /home/tiger/bea/ales30-ssm/apache-ssm/lib/mod_wles.so

Add a WLESConfigDir directive right after the above LoadModule directive as follows:

<IfModule mod_wles.cpp>
WLESConfigDir <APACHE_SSM_HOME>/instance/<instance_name>/config
</IfModule>

where the config directory is the directory that contains the default.properties file.

Note: In the IfModule condition, be sure to specify mod_wles.cpp, not mod_wles.c.

To make sure your server works properly, configure the ServerName. For example:

ServerName www.yourservername.com:8080

Change the Group directive to have the Apache Web Server running as the asiusers group so it can read the mod_wles file and other required files:

Group asiusers

Edit the envvars file in the ServerRoot/bin directory, appending the directory where mod_wles.so resides to the default LD_LIBRARY_PATH, so that the file looks like this:

  LD_LIBRARY_PATH="/www/apache/lib:$LD_LIBRARY_PATH:<APACHE_SSM_HOME>/lib"

Note: This step ensures that the Apache Web Server can load the dependency libraries for the mod_wles file.

Use the Apache ctl script to start or restart Apache Web Server in the ServerRoot/bin directory.

Configuring the NamePasswordForm.html File for the Apache Web Server

Configure the NamePasswordForm.html file for the Apache Web Server as follows:

Deploying and Testing the Apache Web Server Sample Application

Set up the Apache Server/wwwroot/test directory as shown in Figure 5-7 and copy the following files to the test directory:

NamePasswordForm.html
foo.html
atnfailure.html
atzfailure.html

Note: The NamePasswordForm.html file is provided in the BEA_HOME\ales30-ssm\apache-ssm\instance\<instancename>\templates directory. The foo.html, atnfailure.html and atzfailure.html files are not provided in the product installation kit. You should use your own versions of these files.

Figure 5-7 Deploying the Sample Application on the Apache Web Server

Deploying the Sample Application on the Apache Web Server

Start the Apache Web Server, open a browser, and go to http://<hostmachine.cookiedomain>:8088/test/foo.html.
You are redirected to NamePasswordForm.html
Enter the system username/password (a default system username and password was set when you installed the Administration Application) and click OK. You are granted access to foo.html.

Configuring Web Server SSM Properties

The Web Server SSM has a configuration file named default.properties. All configuration settings for the Web Server SSM instance are defined in this file. This file is pre-configured and placed in the proper location for you.

If you want to edit the default.properties file for your particular environment, refer to the parameters descriptions in the following sections:

Session Settings

The AquaLogic Enterprise Security services are stateless services; it is the calling Web Service client that is responsible for determining session related information. In addition, in a web environment, a session does not necessarily end with an explicit logout, so session termination must be inferred from a lack of activity.

Table 5-3 describes the settings used to manage session behavior. You use these settings to configure the Web server session related behavior for the security configuration to which it applies.

Table 5-3 Session Settings
Session Setting	Description
`session.inactivity.timeout`	The number of seconds of inactivity that causes a session to expire. Default value: 600 seconds (10 minutes)
`session.absolute. timeout`	The number of seconds an active session is allowed to be available before it expires and the user is forced to re-authenticate. If this setting is set to zero, then established active sessions can continue indefinitely. Default value: 3600 seconds (60 minutes)
`session.cookie.name`	The name of the session cookie. Default value: ALESIdentityAssertion.
`session.forcedlogoffURL`	The name of the URL that, when accessed, forces the session to logoff.

Authentication Settings

Table 5-4 describes the settings that you use to configure the Web server authentication behavior for the security configuration to which it applies. Also, for information on mapping JAAS Callbacks, see Mapping JAAS Callback Type to Form and Form Fields.

Table 5-4 Authentication Settings
Authentication Setting	Description
`authentication.precedence`	An ordered, comma-separated list of types of identity creation. If identity information is available from multiple types of identity transfers, this list determines which identity to use. The valid identity type is: FORM — credential information collected from an authentication provider using forms. Default value: `FORM`
`authentication.initialForm`	Specifies the first form presented for form-based authentication.
authentication. <callback type>[<prompt>] = <field>,<form URL>	Given a question, this setting specifies what field on what form will answer that question. Notice that the <prompt> is shown as optional. However, the prompt is required if there are multiple callbacks of the same type, because there is no other way for the SSM to distinguish identical callback types. The prompt is obtained from the callback by calling the `getPrompt()` method, but it is not used in the display of the form. If the prompt setting is missing, then the Web Server SSM attempts to answer the callbacks in the order of the settings. If the order does not match the order of the providers, then authentication fails. For more information on using this setting, see Mapping JAAS Callback Type to Form and Form Fields.
`authentication.onatnfailure`	If authentication fails, and this setting is set to a URL, then rather than issuing a 401 Authentication Failed, the user will be redirected to the specified URL.
`authentication.onatzfailure`	If authorization fails and this setting is set to a URL, then rather than issuing a 403 Permission Denied, the user is redirected to the specified URL.

Table 5-5 describes the different types of authentication callbacks that are supported by the Web Server SSM.

Table 5-5 Authentication Callback Type Descriptions
Authentication Callback Type	Description
`authentication. nameCallback`	The form template responsible for collecting a name for a name callback. This form must exist in the same directory as the post handler.
`authentication. passwordCallback`	The form template is responsible for collecting a password for a password callback. This form must exist in the same directory as the post handler.
`authentication. choiceCallback`	The form template is responsible for collecting a choice for a choice callback. This form must exist in the same directory as the post handler.
`authentication. confirmationCallback`	The form template is responsible for collecting a confirmation for a confirmation callback. This form must exist in the same directory as the POST handler.
`authentication. textInputCallback`	The form template is responsible for collecting some text input for a text input callback. This form must exist in the same directory as the post handler.

Mapping JAAS Callback Type to Form and Form Fields

There are two required and one optional configuration settings that specify what form and what field contain the information required to satisfy the authentication callbacks. The credential gathering form must use an HTTP POST method to specify this information. Listing 5-1 shows an example of how to use the POST method in the credential gathering form.

The form field defines the HTTP POST data name that results from a submitted form.

Given a question, this setting specifies what field on what form will answer that question. Notice that the <prompt> is shown as optional. However, if there are multiple callbacks of the same type, the <prompt> is required because there is no other way for the Web Server SSM to distinguish identical callback types. The <prompt> is obtained from the callback by calling the getPrompt() method, but it is not used in the display of the form. If the <prompt> setting is missing, then the Web Server SSM attempts to answer the callbacks in the order of the settings. If the order does not match the order of the authentication providers, then authentication fails.

The supported callback types are: nameCallback, passwordCallback, textInputCallback, textOutputCallback.

Table 5-6 provides examples of callback usage and more information on each supported callback type.

Authentication Callback Types

Example/Discussion

Name and password callbacks

authentication.nameCallback[]=username: /ales/NamePasswordForm.htm

authentication. passwordCallback []= password: /ales/NamePasswordForm.htm

Name, password, and textInput callbacks

authentication.initialForm=/test/NamePasswordForm.html
# username/password
authentication.nameCallback[]=username:/test/
NamePasswordForm.html
authentication.passwordCallback[]=password:/test/
NamePasswordForm.html

# username/password/textInput
authentication.nameCallback[]=username:/test/
LoginNamePwdTextIn.html
authentication.passwordCallback[]=password:/test/
LoginNamePwdTextIn.html
authentication.textInputCallback[]=textinput:/test/
LoginNamePwdTextIn.html

In this example the user will be prompted for username/password. The authentication provider then prompts for the user's mother's maiden name. The Web Server SSM redirects to QuestionForm.htm and knows from what field to get the information.

Name, password, and textInput callbacks

authentication.nameCallback[]=username: /ales/NamePasswordForm.htm

authentication. passwordCallback []= password: /ales/NamePasswordForm.htm

authentication. textInputCallback ["maiden name"]=maiden_name: /ales/ QuestionForm.htm

authentication. textInputCallback ["social security number"]=maiden_name: /ales/ QuestionForm.htm

In this example two providers require username/password callbacks, a third provider requires a textInputCallback for mother's maiden name, and a fourth provider requires a textInputCallback for a Social Security number: The prompts distinguish between the two textInputCallbacks.

Note:

The textInputCallback prompt requires quotes only if it contains embedded strings.

TextOutput Callback

The textOutputCallback is used to display a message to the user. Because the Web Server SSM does not create or update forms, if it gets a textOutputCallback, it redirects it to the form URL and adds the field as a query string argument and the message value. The application that processes the URL is responsible for parsing the query string and displaying the message.

Language callback

Language callbacks are handled internally by the Web server; the user is never prompted, so no configuration is needed. The user's browser Accept-Language header is checked for the preferred language it supports and that locale is returned to the authentication provider. If the user's browser has no Accept-Language header, the system default locale is used.

Role Mapping Settings

Table 5-7 describes the settings that you use to configure the Web server role mapping behavior for the policy domain to which it applies.

Table 5-7 Role Mapping Settings
Role Mapping Setting	Description
`rolemapping.enable`	If set to `true`, then roles are injected into the request stream as a comma separated list.
`rolemapping.name`	The name of the variable in which to put the roles. The default is: `ALES_ROLES.`

Credential Mapping Settings

Table 5-8 describes the settings that you use to configure the Web server credential mapping behavior for the policy domain to which it applies.

Credential Mapping Setting

Description

credentialmapping.
enable

If set to true, then credentials for each request are injected into the request stream.

credentialmapping.
credtypes

List of credential types to ask for in this policy domain. Only credentials that are mapped and that are supported by configured Credential Mapping provider are returned for a specific request. Therefore, asking for a credential does not guarantee that it is there.

For example, to configure credential mapping to support the password for the database server, perform the following steps:

Set credentialmapping.credtypes to: "credentialmapping.credtypes=DBPASSWORD"
On the Details tab of the Database Credential Mapping provider in the Web Service SSM, set the Allowed Types parameter to DBPASSWORD.

Note: The Database Credential Mapper provider provides identity credentials. An identity credential is the same as a PasswordCredential in Java. Others credentials, such SAML assertions, ALES Identity Assertions IA, and so on, are identity assertions. They are the same as a GenericCredential in Java. The Web Service SSM can have only one identity credential defined, but many identity assertions.

credentialmapping.
prefix

Prefix to prepend to credential names, for example CRED.

Naming Authority Settings

Table 5-9 describes the settings that you use to configure the Web Server SSM naming authority.

Table 5-9 Naming Authority Settings
Setting	Description
`namingauthority.resource`	Specifies the naming authority for the resource. The naming authority is configured in the Web Service SSM.
`namingauthority.action`	Specifies the action naming authority.
`namingauthority.audit`	Specifies the audit naming authority.
webservice.registry.url	Specifies the URL of the Web Services Registry Service. For example: `http://localhost:8000/ServiceRegistry`

Logging Level Setting

Table 5-10 describes the settings that you use to configure the Web Server SSM naming authority.

Table 5-10 Logging Level Setting
Setting	Description
`log.level`	Specifies the logging level for the log4j Auditing provider.

Environment Variables Accessible Using CGI

The Web Server Security Service Module (SSM) tool kit enables you to access user environment variables using Common Gateway Interface (CGI).

Although security is embedded within the web server itself, requiring no special programming (if the user does not have access, your code will never run), a security administrator may want to use CGI to access and modify environment variables passed in by the Web Server Security Service Module. In order to customize the application according to the details of the security being enforced, a web application may access several environmental values in order to provide a more integrated user experience.

ALES_IDENTITY — An authentication environment variable. It is available to a CGI programmer after a user successfully authenticates. This variable contains the username of the user, if available. It specifies the name of the HTTP header that will be added. The value of the variable is a list of the identity principals, including username and groups.
ALES_DECISIONTIME — An authorization environment variable. It is available to a CGI programmer after a user is authorized to access a secure resource. It contains the date and time this authorization decision was rendered and has this format: “Monday June 23 15:14:21 EDT 2003”
ALES_ROLES — A role environment variable that stores a list of roles calculated for the user.
Credential Environment Variable — Table 5-12 describes the credential that is injected into the request stream when the user is authenticated. A CGI application can use this variable to access an LDAP store or database with an appropriate credential, rather than hard coding usernames and passwords. The prefix to this credential variable is configurable, although CRED is the default. Different credential types are handled differently, but the general format of the variable is: CRED_{NAME}={VALUE}

Table 5-11 Credential Environment Variables
Environment Variable	Description
Password Credentials	Password credentials conform to the format `javax.resource.spi.security.PasswordCredential`. The `ManagedConnectionFactory` element of this class is ignored. This credential type is rendered in the CGI environment as: `{PREFIX}_PASSWORD={NAME}:{PASSWORD}` where `PREFIX` is the configured prefix, `NAME` is the username, and `PASSWORD` is the password as a string. This name must match the requested credential type from `credentialmapping.credtypes`. For example: `CRED_PASSWORD=system:weblogic`

Table 5-12 Credential Environment Variables
Environment Variable	Description
Password Credentials	Password credentials conform to the format `javax.resource.spi.security.PasswordCredential`. The `ManagedConnectionFactory` element of this class is ignored. This credential type is rendered in the CGI environment as: `{PREFIX}_PASSWORD={NAME}:{PASSWORD}` where `PREFIX` is the configured prefix, `NAME` is the username, and `PASSWORD` is the password as a string. This name must match the requested credential type from `credentialmapping.credtypes`. For example: `CRED_PASSWORD=system:weblogic`

SSM Installation and Configuration Guide

Configuring the Web Server SSM

Requirements

Creating a Web Server SSM Instance

Enrolling the Web Server SSM Instance

Start the Web Service SSM

Create and Bind the Corresponding SSM

Create a Corresponding SSM in the Administration Console

Add Security Providers

Bind Everything Together

Configuring the Web Server Environmental Binding

Microsoft IIS Web Server

Configuring the Microsoft IIS Web Server Binding Plug-In File

Configuring the NamePasswordForm.acc File for the IIS Web Server

Deploying and Testing the IIS Web Server Sample Application

Apache Web Server

Downloading and Installing the Apache Web Server

Configuring the ALES Module

Configuring the NamePasswordForm.html File for the Apache Web Server

Deploying and Testing the Apache Web Server Sample Application

Configuring Web Server SSM Properties

Session Settings

Authentication Settings

Mapping JAAS Callback Type to Form and Form Fields

Role Mapping Settings

Credential Mapping Settings

Naming Authority Settings

Logging Level Setting

Environment Variables Accessible Using CGI