> Integrating ALES with Application Environments > Configuring the Web Server SSM

Integrating ALES with Application Environments

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

Configuring the Web Server SSM

This section describes the Web Server Security Service Module, including tasks that you must perform after installing and completing the post-installation tasks. See Installing Security Service Modules for information about how to install the Web Server Security Service Module for Microsoft IIS or the Apache Web Server. The following topics are covered in this section:

 

Understanding the Web Server SSMs

This section includes the following topics describing the Web Server SSMs:

Web Server SSM Overview

An ALES Web Server SSM provides the environmental bindings between the ALES and a web server. It can provide six distinct services: Registry, Authentication, Authorization, Auditing, Role Mapping, and Credential Mapping.

Figure 5-1 Web Server SSM Components

Web Server SSM Components

A Web Server SSM makes access decisions for the web server to which it is bound. The security configuration on which the access control decisions are based is defined and deployed by the Administration Server via the Security Control Module.

A Web Server SSM can be tailored to specific needs. Using templates provided as part of the product, security developers can customize the look and feel of authentication pages and configure parameters that allow fine tuning for a particular installation. Web applications can have information added to the HTTP request by the security framework, such as roles and response attributes.

ALES provides three Web Server SSMs: IIS Web Server SSM (SSM), Apache Web Server SSM, and Web Services SSM (see Figure 5-2).

Figure 5-2 Web Server SSM Components

Web Server SSM Components

Web Server Environmental Binding

The environmental binding is used to bind to and interact with web servers. Binding a Web Server SSM to the server projects the ALES subsystem into the web server environment. The SSM accepts HTTPS requests from the web server and presents them to the ALES security framework.

Bindings are provided for two types of web servers: ASF Apache and Microsoft IIS. The second function is ultimately for enforcing access control and providing a means of implementing the SAML Browser/POST profile. Additionally, the Web Server SSM implements the server-side includes (SSIs) that process SAML Browser/POST profile.

Web Server SSM Features

This section describes the Web Server SSM features in the following sections

Web Single Sign-on Capabilities

This section covers the following topics:

What is Web Single Sign-On?

Web single sign-on enables users to log on to one web server and gain access to other web servers in the same domain without supplying login credentials again, even if the other web servers have different authentication schemes or requirements. Figure 5-3 shows the basic components of a web single sign-on service.

Figure 5-3 Web Single Sign-on

Web Single Sign-on

While web single sign-on facilitates access and ease of use, it does not improve security. In fact, security requirements should be considered when implementing a web single sign-on solution.

Single Sign-On Use Cases

The Web Server SSM supports the following single sign-on (SSO) use cases.

Single Sign-On with ALES Identity Assertion

The Web Server and WebLogic Server SSMs support single sign-on using the ALES Identity Assertion provider. For instructions on how to implement Single Sign-On, see Enabling SPNEGO-based Single Sign-on.

Authentication Service Features

The authentication service supports the following features:

Authorization Service Features

The authorization service supports the following features:

Auditing Service Features

The auditing service has the following capabilities:

Role Mapping Features

The role mapping service supports hard-coded roles in applications. Generally hard-coding behavior into an application based on roles is not recommended. It is possible, however, that some customers may need to replace an existing system that uses this mechanism or may want to use roles for user interface personalization. Support for this feature requires that a list of mapped roles available from a security provider for a particular request be provided in a usable form by applications running within the web server.

Note: It is important to note that roles are not global in ALES but can change depending upon the resource and various elements of the context.

Credential Mapping Features

ALES defines two types of credential objects: username/password credentials and generic credentials; however, there is no limitation as to the format of objects that can be used. Credentials can be mapped and associated with a resource and identity or an alias.

The credential mapping service has the following features:

Administration Features

Administering the security configuration involves writing policies for users, groups, roles, and the web application resources that the SSM protects. The Web Server SSM has the following features:

Session Management Features

To manage session behavior, the Web Server SSM supports the following capabilities:

Configuration Features

The web server is configured to use the filter component of the Web Server SSM. Local configuration of the web server should only be necessary once and should be static. The Web Server SSM has the following configuration capabilities:

Web Server Constraints and Limitations

The Web Server SSM has the following constraints and limitations:

Web Server SSM Integration Tasks

This section provides an overview of integration tasks. Integration tasks center on managing SSM configurations (including the security providers) and configuring the web server to use the web filters. For additional information, see Installing Security Service Modules.

The major tasks performed are:

  1. Create a SCM and a SSM configuration using the Administration Console. This includes specifying the security providers.
  2. Create a parent resource for the application. This will contain ALES's representation of the application.
  3. Create the SSM instance on the web server machine and enroll it in the ALES trust environment. The instance will use the security providers defined in step 1 above.

    4. During the instance creation process, the default.properties configuration file is created. This file contains the connection information for the ALES services.

  4. Configure the web server environmental binding. This loads the web filter on the server and establishes the connection between the web server and ALES.

 

Configuring and Deploying Policy for the Web Server SSM

Developing a policy for a web application typically begins by determining which resources you want to protect. You then create authorization mapping policies to define access privileges and roles for each resource, and under what specific conditions. Next, you create role mapping policies that control which users and groups have membership in the defined roles, and under what conditions.

This section describes how to create resources and define authorization and role mapping policies to protect a sample Web server application. This section also describes how to deploy this policy to the Web Services SSM that you will use to control access to sample Web server application resources.

AquaLogic Enterprise Security provides three tools for configuring application policy: the Administration Console, the Policy Import Tool, and Business Logic Manager (BLM) API. In this section you are directed to use the Administration Console to configure policy.

For more information on how to use the Administration Console to configure policy, see the Policy Managers Guide and Console Help.

For instructions on how to use the Policy Import Tool to import policy files, see the Importing Policy section in the Policy Managers Guide.

For information on the BLM, see the BLM API Javadocs.

To configure and deploy policy for the Web Server SSM, perform the following tasks:

Creating Resources

This section describes how to use the Administration Console to create resources for the sample web server application resource.

Figure 5-6 shows the resources that you must create for the sample IIS Web Server configuration. You create the same resources for the Apache Web Server, except that you assign the NamePasswordForm a file extension of .html, instead of .acc.

Figure 5-6 Resources Tree for the IIS Web Server

Resources Tree for the IIS Web Server

To create these resources, perform the following steps:

  1. In the Administration Console, open the Resources folder, and click Resources to display the Resources page.
  2. Select Policy and click New. The Create Resource dialog box appears.
  3. In the Name text box, enter ssmws, select Binding from the Type drop-down list box, and click Ok. The ssmws resource appears under the Policy node.
  4. Select the ssmws resource and click Configure. The Configure Resource dialog box appears.
  5. From the Type drop-down list box, select Binding Application, check the Distribution Point check box to on, and click Ok.
  6. Select the ssmws resource and click New. The Create Resource dialog box appears.
  7. In the Name text box, enter favicon.ico, and click Ok. The resource appears under ssmws.
    8. Note: The favicon.ico file is an icon requested by the Internet Explorer and Mozilla browsers for bookmarking a URL.
  8. Select the ssmws resource and click New. The Create Resource dialog box appears.
  9. In the Name text box, enter test, and click Ok. The resource appears under ssmws.
  10. Select the test resource and click New. The Create Resource dialog box appears.
  11. In the Name text box, enter foo.html and click Ok. The foo.html resource appears under the test resource.
  12. Click the test resource and click New. The Create Resource dialog box appears.
  13. In the Name text box, enter NamePasswordForm.acc for IIS (or NamePasswordForm.html for Apache), and click Ok. The resource appears under test.

Creating Policies

This section describes how to use the Administration Console to create authorization and role mapping policies to protect the sample Web server application resources. It includes authorization policies for the HTML files and role mapping policies to assign membership to those roles.

Table 5-1 lists and describes the authorization policies that you will create to protect the sample Web server application resources. These authorization policies allow users who are members of the Everyone role the Get access privilege to the favicon.ico and GET and POST access privileges to NamePasswordForm.acc (so users who have membership in the Everyone role can access the username/password form when authentication for a protected resource is needed). The policy also restricts access to foo.html to users in the Admin role.

Table 5-1 Sample Web Server Application Resources Authorization Policies 
Policy
Description
grant(GET, //app/policy/ssmws/favicon.ico,
//role/Everyone) if true;
Allows unauthenticated users to access images used on the application login page.
grant(GET, POST, //app/policy/ssmws/test/NamePasswordForm.acc, //role/Everyone) if true;
On the IIS Web Server, grants GET and POST privileges for those in the Everyone role to access the NamePasswordForm.acc page.

Note: For the Apache Web Server, use NamePasswordForm.html.
grant(GET, //app/policy/ssmws/test/foo.html, //role/Admin) if true;
Grants GET privileges for those in the Admin role to access the foo.html page.

To create the authorization polices listed in Table 5-1, perform the following steps:

  1. Open the Policy folder, and click Policy. The Policy page appears.
  2. Click Authorization Policies and click New. The Create Authorization Policy dialog box appears.
  3. Select the Grant radio button.
  4. To add privileges for the first policy listed in Table 5-1, click the Privileges tab, select the GET privilege from the Select Privileges from Group list box and add it to the Selected Privileges box.
  5. Click the Resources tab, select the favicon.ico resource from the Child Resource box and add it to the Selected Resources box.
  6. Click the Policy Subjects, select the Everyone role from the Roles List box, add it to the Selected Policy Subjects box, and click Ok.
  7. Repeat steps 2 to 6 for each of the remaining authorization policies listed in Table 5-1. Notice that the Admin role is assigned to the foo.html resource.

Modifying Admin and Everyone Role Mapping Policies

This section describes how to use the Administration Console to modify the role mapping policies that will be used to control access to the sample Web Server application resources.

To modify the Admin and Everyone role mapping policies, perform the following steps:

  1. Open the Policy folder, and click Role Mapping Policies. The Role Mapping Policies page appears.
  2. Select the Admin role for ASI, and click Edit. The Edit Role Policy dialog appears.
  3. Click the Resources tab, add the ssmws resource, and click Ok.
  4. Repeat steps 2 to 4 for the Everyone role to add ssmws to the Everyone role.

Configuring the Application Deployment Parent

For the sample Web server application, the Application Deployment Parent setting on the ASI Authorization provider and the ASI Role Mapping provider must be set to //app/policy/ssmws and must be bound to the provider.

To configure these providers, perform the following steps:

  1. In the Administration Console, click the ASI Authorization provider and click the Details tab.
  2. Set the Application Deployment parent to //app/policy/ssmws, and click Apply.
  3. Click on the Bindings tab and click bind to bind //app/policy/ssmws to this provider.
  4. Repeat steps 1 to 3 for the ASI Role Mapping provider.

Configuring the ALES Identity Assertion and Credential Mapping Providers

To configure the ALES Identity Assertion and ALES Credential Mapping providers, perform the following steps:

Note: The ALES Identity Assertion provider and the ALES Credential Mapping provider work with one another; therefore, it is important that you ensure that their configuration settings match.
  1. In the Administration Console, click the ALES Identity Assertion provider, select the Details tab, set the parameters as listed in Table 5-2, and click Apply.
  2. Click the ALES Credential Mapping provider, select the Details tab, set the parameters as listed in Table 5-2, and click Apply.

    3. Table 5-2 ALES Identity Asserter and Credential Mapper Provider Settings 
    Parameter
    Setting
    Trusted CAKeystore
    {HOME}/ssl/demoProviderTrust.jks
    {HOME} is replaced with the SSM instance directory at runtime.
    Trusted CAKeystore Type
    JKS
    Trust Cert Alias
    demo_provider_trust
    Trusted Cert Alias Password and Confirmation
    password
    Trusted Keystore
    {HOME}/ssl/demoProviderTrust.jks
    {HOME} is replaced with the SSM instance directory at runtime.
    Trusted Keystore Type
    JKS

Distributing Policy and Security Configuration

Distribute the policy and security configuration to the Web Server SSM.

For information on how to distribute policy and security configuration, see the Console Help. Be sure to verify the results of your distribution.

 

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. For configuration instructions, see the appropriate topic below:

Configuring the Environmental Binding for the 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 according instructions provided in Creating an Instance of a Security Service Module in Installing Security Service Modules.

The IIS Web Server Binding plug-in file is named wles_isapi.dll. This file is located in the BEA_HOME\ales25-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-7).
    3. Figure 5-7 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\ales25-ssm\iis-ssm\lib directory), and click OK.
  4. Click the Directory Security tab. The Authentication Methods dialog appears (see Figure 5-8).
    5. Figure 5-8 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\ales25-ssm\iis-ssm\lib
    BEA_HOME\ales25-ssm\iis-ssm\instance\iisssmdemo\ssl
    BEA_HOME\ales25-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-7) and click the Home Directory tab. The Home Directory dialog appears (see Figure 5-9).
    8. Figure 5-9 IIS Web Site Home Directory Dialog


    IIS Web Site Home Directory Dialog

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

    9. Table 5-3 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-10).
    10. Figure 5-10 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-11).
    11. Figure 5-11 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-11, 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 Services 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 Services SSM must be started before you perform this task because the filter and extension attempt to connect to the Web Services SSM when they are loaded by the Web server.
  1. Set up the IIS Server/wwwroot/test directory as shown in Figure 5-12 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\ales25-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-12 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.

Configuring the Environmental Binding for the 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

Note: This task assumes you have created an instance of the Apache Web Server SSM according instructions provided in Creating an Instance of a Security Service Module in Installing Security Service Modules.

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\ales25-ssm\apache-ssm\lib\mod_wles.dll

    For UNIX systems:

    LoadModule wles_module /home/tiger/bea/ales25-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-13 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\ales25-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-13 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 Single Sign-on with ALES Identity Assertion

You can configure web single sign-on (SSO) for the following use cases:

For configuration instructions, see the following topics:

Configuring Web Server SSMs to Web Server SSMs for SSO

To configure Web Server SSM to Web Server SSM to support web single sign-on, perform the following steps:

  1. Using the Administration Console, configure the ALES Identity Assertion and ALES Credential Mapping providers for each Web Server SSM that is to participate in web single sign-on.
  2. Configure the ALES Identity Assertion provider and the ALES Credential Mapping provider in each of the Web Server SSMs to use the same Trusted Cert Alias, Trusted Keystore, and Trusted Keystore Type.
  3. Deploy the SSM configurations to the SSMs.

For instructions on how to perform the above steps, see the Console Help for the Administration Console.

Configuring Web Server SSMs to WebLogic Server SSMs for SSO

To configure Web Server SSM to WebLogic Server SSM to support web single sign-on, perform the following steps:

  1. Using the Administration Console, configure the ALES Identity Assertion and ALES Credential Mapping providers for each Web Server SSM and WebLogic Server SSM that is to participate in web single sign-on.
  2. Configure the ALES Identity Assertion provider and the ALES Credential Mapping provider in each of the SSMs to use the same Trusted Cert Alias, Trusted Keystore, and Trusted Keystore Type.
  3. When configuring the ALES Identity Assertion provider for each of the WebLogic Server SSMs, on the Details tab, be sure leave the Base64 Decoding attribute box unchecked, which is the default setting.
  4. Deploy the SSM configurations to the SSMs.

For instructions on how to perform the above steps, see the Console Help.

 

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 Services 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-4 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-4 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-5 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-5 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-6 describes the different types of authentication callbacks that are supported by the Web Server SSM.

Table 5-6 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 setting 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-7 provides examples of callback usage and more information on each supported callback type.

Table 5-7 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-8 describes the settings that you use to configure the Web server role mapping behavior for the policy domain to which it applies.

Table 5-8 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-9 describes the settings that you use to configure the Web server credential mapping behavior for the policy domain to which it applies.

Table 5-9 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 Services 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 Services 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-10 describes the settings that you use to configure the Web Server SSM naming authority.

Table 5-10 Naming Authority Settings 
Setting
Description
namingauthority.resource

Specifies the naming authority for the resource. The naming authority is configured in the Web Services 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-11 describes the settings that you use to configure the Web Server SSM naming authority.

Table 5-11 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