SSM Installation and Configuration Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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.

The following tasks are described:

 

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

To create a Web Server SSM instance:

  1. 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.
  2. In the Instance Name field, enter an instance name. Then specify Web Service SSM port number and click Next.
  3. In the Location field, accept the default location or specify a different directory and click Next.
  4. When wizard completes, click Done.
Notes:

 

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.

Note: While you can use the demonstration digital certificate in a development environment, you should never use it in a production environment.

To enroll the Security Service Module:

  1. 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.
  2. Run the following script:

    3. enroll demo

  3. 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).
  4. 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

To start an instance of the Web Service SSM on Windows:

To start an instance of the Web Service SSM on UNIX:

 

Create and Bind the Corresponding SSM

This section describes how to:

  1. Use the Administration Console to create a corresponding SSM.
  2. Specify which security providers it will use.
  3. 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.

Perform the following steps:

  1. 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.
  2. Click Create a New Security Service Module Configuration. The Edit Security Service Module Configuration page displays.
  3. In the Configuration ID text box, enter the matching Configuration ID for the SSM.
  4. In the Configuration Version dropdown box, select Java SSM 3.0, WS SSM 3.0.
  5. 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.

Click the Providers tab and configure the desired providers.

Bind Everything Together

  1. Click on the SCM that you previously configured for this SSM. The Edit a Service Control Manager Configuration page displays.
  2. 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

Note: This task assumes you have created an instance of the IIS Web Server SSM.

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:

  1. 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.
  2. 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).
    3. Figure 5-1 IIS Web Site Properties Dialog


    IIS Web Site Properties Dialog

  3. 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.
  4. Click the Directory Security tab. The Authentication Methods dialog appears (see Figure 5-2).
    5. Figure 5-2 Authentication Methods Dialog


    Authentication Methods Dialog

  5. 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:
    6. 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
  6. If you put the NamePasswordForm.acc file in a virtual directory, repeat the previous step for the virtual directory as well.
  7. 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).
    8. Figure 5-3 IIS Web Site Home Directory Dialog


    IIS Web Site Home Directory Dialog

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

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

  9. Click the Configuration button. The Application Configuration dialog appears (see Figure 5-4).
    10. Figure 5-4 IIS Web Site Application Configuration Dialog


    IIS Web Site Application Configuration Dialog

  10. Click the Add button. The Add/Edit Application Extension Mapping Dialog appears (see Figure 5-5).
    11. Figure 5-5 IIS Web Site Add/Edit Application Extension Mapping Dialog


    IIS Web Site Add/Edit Application Extension Mapping Dialog

  11. 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.
  12. Click OK to close the remaining windows.
  13. Right click the Default Web Site again and start the Default Web Site. (Stop the Web Site first if necessary.)
  14. 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.
    15. 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

Configure the NamePasswordForm.acc file for the IIS Web Server as follows: 

<FORM METHOD=POST ACTION="test/NamePasswordForm.acc">

Deploying and Testing the IIS Web Server Sample Application

To set up the sample web application, perform the following steps:

Note: The Web Service SSM must be started before you perform this task because the filter and extension attempt to connect to the Web Service SSM when they are loaded by the Web server.
  1. 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

  2. Start the IIS Web Server, open a browser and go to http://<machine_name_with DNS_suffix>:80/test/foo.html.
  3. You are redirected to NamePasswordForm.acc.
  4. 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

To configure the Apache Web Server, perform the following tasks:

Downloading and Installing the Apache Web Server

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

  1. Go to the Apache download web site at http://httpd.apache.org/download.cgi and download and install the software.
  2. 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.

To install and configure the ALES module:

  1. 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:
    2. 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

  2. Add a WLESConfigDir directive right after the above LoadModule directive as follows:
    3. <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.
  3. To make sure your server works properly, configure the ServerName. For example:
    4. ServerName www.yourservername.com:8080
  4. 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: 
    5. Group asiusers
  5. 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:
    6.   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.
  6. 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: 

<FORM METHOD=POST ACTION="/test/NamePasswordForm.html">

Deploying and Testing the Apache Web Server Sample Application

To set up the sample web application, perform the following steps:

  1. 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

  2. Start the Apache Web Server, open a browser, and go to http://<hostmachine.cookiedomain>:8088/test/foo.html.
  3. You are redirected to NamePasswordForm.html
  4. 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.

Listing 5-1 Example of Using the POST Method in the Credential Gathering Form 
<FORM METHOD=POST ACTION="LoginNamePwdTextIn.html">
<!--#AUTHSTATE -->
<TABLE BGCOLOR="C0C0C0"><TR><TD>
<TABLE BGCOLOR="#FFFFFF">
<TR><TD COLSPAN="2" BGCOLOR="#C0C0C0">Please Login</TD></TR>
<TR><TD COLSPAN="2">User Name&nbsp;</TD><TR>
<TR><TD><!--#PROMPT --></TD><TD><INPUT NAME="username"></TD></TR>
<TR><TD COLSPAN="2">Password&nbsp;</TD><TR>
<TR><TD><!--#PROMPT.1--></TD><TD><INPUT TYPE=
             PASSWORD NAME="password"></TD></TR>
<TR><TD COLSPAN="2">Input Text&nbsp;</TD><TR>
<TR><TD><!--#PROMPT --></TD><TD><INPUT NAME="textinput"></TD></TR>
<TR><TD COLSPAN="2">&nbsp;</TD><TR>
<TR><TD COLSPAN="2" ALIGN="CENTER"><INPUT TYPE="SUBMIT" VALUE="OK"></TD><TR>
</TABLE>
</TD></TR></TABLE>
</FORM>


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

The settings have the following format: 

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, 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.

Table 5-6 Authentication Callback Usage Examples 
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.

Table 5-8 Credential Mapping Settings 
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.

You can use CGI to access the following environment variables:


  Back to Top       Previous  Next