Skip navigation.
Downloads | Product Documentation | Support

Web Server Installation

# Configuring the Web Server SSM

This section covers tasks that you must perform after completing the post-installation tasks for the Web Server Security Service Module. The following topics are covered in this section:

- Configuring and Deploying Policy for the Web Server SSM
- Configuring the Web Server Environmental Binding
- Configuring Web Single Sign-on with ALES Identity Assertion
- What's Next

# 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 the resources, roles and rules to define which privileges apply to each resource, and under what specific conditions. Next, you create policy rules that control which users and groups belong in the defined roles, and under what conditions.

In this section, you are instructed in how to create resources and define policy and rules for protecting a sample web server application. Later on in this section you are instructed to deploy this policy to the Web Services SSM that you will use to control access to sample web server application resources.

WebLogic Enterprise Security provides two means for configuring application policy, the Administration Console and the Policy Import Tool. 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 "Overview" in the Policy Managers Guide and "Policies" in the 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.

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

- Creating Resources
- Creating Policy Rules
- Modifying Admin and Everyone Roles
- Configuring the Application Deployment Parent
- Distributing Policy and Security Configuration

## Creating Resources

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

Figure 5-1 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 NamePassword a file extension of `.html`, instead of `.acc`.

Figure 5-1 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. The Resources page displays.
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, 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`.

Note: The `favicon.ico` file is an icon requested by the Internet Explorer and Mozilla browsers for book marking 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 `NamePassword.acc for IIS` (or `NamePassword.html` for Apache), and click Ok. The resource appears under `test`.

## Creating Policy Rules

This section describes how to use the Administration Console to create policy rules to protect the sample web server application resources. It includes policy for the html files as well as some basic role policy.

Table 5-1 lists and describes the policy rules that you have to create to protect the sample web server application resources. This policy allows everyone ANY access to the `favicon.ico` and `wles_isapi.dll`, everyone GET and POST access to `NamePasswordForm.html` and `wles_isapi.dll` (so everyone can reach the username/password form when authentication for a protected resource is needed), and restricts access to `foo.html` to users in the `Admin` role. The protected resource in this case `test/foo.html`, which can only be seen and accessed by users in the `Admin` role.

Table 5-1 Policy Rules

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/NamePassword.acc, //role/Everyone) if true;` | On the IIS Web Server, grants `GET` and `POST` privileges for those in the `Everyone` role to access the `NamePassword.acc` page. Note: For the Apache Web Server, use `NamePassword.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.

Perform the following steps create the policy rules listed in Table 5-1.

1. Open the Policy folder, and click Policy. The Policy page displays.
2. Click New. The Create Rule dialog box appears.
3. Select the Grant radio button.
4. To add privileges for the first policy rule listed in Table 5-1, click the Privileges tab, select the `any` 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 policy rules listed in Table 5-1. Notice that the `Admin` role is assigned to the `foo.html` resource.

## Modifying Admin and Everyone Roles

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

To modify the `Admin` and `Everyone` roles, perform the following steps:

1. Open the Roles folder, and click Roles. The Roles page displays.
2. Select the `Admin` role, click Assign. The Role Policy page displays.
3. Select the current policy for `Admin` on the WLES resource, and click Edit. The Edit Role Policy dialog displays.
4. Click the Resources tab, add the `ssmws` resource, and click Ok.
5. Repeat steps 2 to 4 for the `Everyone` role to add `ssmws` to the Everyone role.

## Configuring the Application Deployment Parent

Fro 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 bound to the provider.

To configure these providers, perform the following steps:

1. In the Administration Console, click on your ASI Authorization provider and click on 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 so you must ensure that their configuration settings match.

1. In the Administration Console, click on the ALES Identity Assertion provider, select the Details tab, set the parameters as listed in Table 5-2, and click Apply.
2. Click the click on the ALES Credential Mapping provider, select the Details tab, set the parameters as listed in Table 5-2, and click Apply.

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 "Deployment in the Administration Application Guide and 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 product you are configuring. BEA WebLogic Enterprise Security supports two web server products that require configuration of the Web Server Environmental Binding, the Microsoft IIS Web Server and the Apache Web Server. For configuration instructions, see to the appropriate topic below:

- Configuring the Environmental Binding for the Microsoft IIS Web Server
- Configuring the Environmental Binding for the Apache Web Server

## 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
- Configuring the NamePasswordForm.acc File for the IIS Web Server
- Deploying and Testing the IIS Web Server Sample Application

### 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 the Web Server Security Service Module.

The IIS Web Server Binding Plug-in file is named `wles_isapi.dll`. This file is located in the `BEA_HOME``\wles42-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-2).

Figure 5-2 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``\wles42-ssm\iis-ssm\lib` directory, and click Ok.
4. Click the Directory Security tab. The Authentication Methods dialog appears (see Figure 5-3).

Figure 5-3 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:

>     BEA_HOME\wles42-ssm\iis-ssm\lib
>     BEA_HOME\wles42-ssm\iis-ssm\instance\iisssmdemo\ssl
>     BEA_HOME\wles42-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-2) and click the Home Directory tab. The Home Directory dialog appears (see Figure 5-4).

Figure 5-4 IIS Web Site Home Directory Dialog

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

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-5).

Figure 5-5 IIS Web Site Application Configuration Dialog

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

Figure 5-6 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-6, 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. Reopen 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.

### 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 attempts 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-7 and copy the following files to the `test` directory:

- `NamePasswordForm.acc`
- `foo.html`
- `atnfailure.html`
- `atzfailure.html`

Note: The `NamePassword.acc` file is provided in the `BEA_HOME``\wles42-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-7 Deploying the Sample Application on the IIS Web Server

2. Start the IIS Web Server, open a browser and go to `http://localhost: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
- Configuring the WLES Module
- Configuring the NamePasswordForm.html File for the Apache Web Server
- Deploying and Testing the Apache Web Server Sample Application

### 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. If the download kit is the "no_ ssl" version of the Apache Web Server, the `mod_ssl.so` file is not included and you have to add it. There are sites on the Internet that offer this file along with installation instructions.

### Configuring the WLES Module

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

The WLES module, `mod_wles.so`, contains only one file.

To install and configure the WLES module, perform the following steps:

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:

>     LoadModule wles_module <APACHE_SSM_HOME>/lib/modules/mod_wles.so

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

For example: `LoadModule wles_module /home/tiger/bea/wles42-ssm/apache-ssm/lib/mod_wles.so`

2. Add an `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`.

3. Add an alias in the `http.conf` file for this directory. For example:

>     Alias /test c:/test/webdocs

4. To set up your machine as the server, add the following to the `http.conf` file:

>     ServerName mymachine.mydomain.abc.com:8080

5. Change the Group directive to have the Apache Web Server running as the `asiusers` group so it can read the `mod_wles.so` and other required files: `Group asiusers`
6. Edit the `envvars` file in the `ServerRoot/bin` directory, append 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 `mod_wles.so`.

1. 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 `NamePassword.html` file is provided in the `BEA_HOME``\wles42-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-8 Deploying the Sample Application on the Apache Web Server

2. Start the Apache Web Server, open a browser and go to `http://localhost: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:

- Bi-directional web single sign-on between Web Server Security Service Modules (SSMs)

With SSO configured, any user that authenticates to one Web Server SSM can access any other Web Server SSM in the cookie domain without having to re-authenticate.

- Uni-directional web single sign-on between Web Server SSMs and WebLogic Server 8.1 SSMs

With SSO configured, any user that authenticates to one Web Server SSM can access any other WebLogic Server 8.1 SSM in the cookie domain without having to re-authenticate. However, a user that authenticates to a WebLogic Server 8.1 SSM cannot access another WebLogic Server 8.1 SSM or another Web Server SSM without re-authenticating.

For configuration instructions, see the following topics:

- Configuring Web Server SSMs to Web Server SSMs for SSO
- Configuring Web Server SSMs to WebLogic Server 8.1 SSMs for SSO

## 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 Keystory 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 or the Administration Application Guide.

## Configuring Web Server SSMs to WebLogic Server 8.1 SSMs for SSO

To configure Web Server SSM to WebLogic Server 8.1 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 8.1 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 Keystory Type.
3. When configuring the ALES Identity Assertion provider for each of WebLogic Server 8.1 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 for the Administration Console or the Administration Application Guide.

# What's Next

You have completed the configuration tasks for the Web Server Security Service Module (SSM).

Refer the Policy Managers Guide for instructions on how to write security policy.