Skip navigation.
Downloads | Product Documentation | Support

Web Server Installation

# Web Server Security Service Module Introduction

This section covers the following topics:

- About this Document
- Product Overview
- Product Features
- Product Constraints and Limitations

# About this Document

This document provides security administrators with the information needed to install and configure three BEA® WebLogic® Enterprise Security products:

- IIS Web Server Security Service Module
- Apache Web Server Security Service Module
- Web Services Security Service Module

This section covers the following topics:

- Audience for This Guide
- Prerequisites for this Guide
- How this Document is Organized
- Product Documentation on the dev2dev Web Site
- Related Information
- Contact Us!

## Audience for This Guide

It is assumed that readers understand web technologies and have a general understanding of the Microsoft Windows or UNIX operating systems being used. The general audience for this installation guide includes:

- Security Administrators—Administrators that are responsible for installing and configuring the Web Server Server Security Service Module and the Web Services Security Service Module products, implementing the callback templates, and writing the security policy based upon the unique Universal Resource Locator (URL) structure and values of the application in question.
- Web Developers—Developers that use the Web Server Security Service Module can rely on security to exist for their application, and merely need to structure the URLs they use to allow for easy policy creation by the security administrator. Developers may also use the Common Gateway Interface (CGI) to interact with the Web Server Security Service Module so as to customize the user interface based upon user roles.

## Prerequisites for this Guide

Prior to reading this guide, you should read the Introduction to BEA WebLogic Enterprise Security. This document describes how the product works and provides conceptual information that is helpful to understanding the necessary installation components.

Additionally, BEA WebLogic Enterprise Security includes many unique terms and concepts that you need to understand. These terms and concepts—which you will encounter throughout the documentation—are defined in the Glossary.

This document provides security administrators with the information needed to install and configure the Web Server Security Service Module.

## How this Document is Organized

The document is organized as follows:

- This chapter, "Introduction," provides an introduction to the Web Server Security Service Module (SSM) and the Web Services SSM products.
- Preparing to Install,describes system requirements (software and hardware) that must satisfied before you install the products.
- Installing, describes how to install the products.
- Post Installation Tasks, describes the tasks that you must perform after installing the Web Server Security Service Module.
- Configuring the Web Server SSM, describes the tasks that you must perform after completing the post-installation tasks for the Web Server Security Service Module.
- Configuring the Web Services SSM, describes the tasks that you must perform after completing the post-installation tasks for the Web Services Security Service Module.
- Configuration Options, describes the configuration options supported by the Web Services Security Service Module.
- Uninstalling, describes how to uninstall the Web Server SSM, the Web Services SSM, and the Service Control Manager.

## Product Documentation on the dev2dev Web Site

BEA product documentation, along with other information about BEA software, is available from the BEA dev2dev web site:

http://dev2dev.bea.com

To view the documentation for a particular product, select that product from the Product Centers menu on the left side of the screen on the dev2dev page. Select More Product Centers. From the BEA Products list, choose WebLogic Enterprise Security 4.2. The home page for this product is displayed. From the Resources menu, choose Documentation 4.2. The home page for the complete documentation set for the product and release you have selected is displayed.

## Related Information

The BEA corporate web site provides all documentation for BEA WebLogic Enterprise Security products. Other documents that may be of interest to the reader include:

- Introduction to BEA WebLogic Enterprise Security—This document provides overview, conceptual, and architectural information for all WebLogic Enterprise Security products.
- BEA WebLogic Enterprise Security Administration Application Guide—This document provides a complete overview of the product and includes step-by-step instructions on how to perform various administrative tasks.
- BEA WebLogic Enterprise Security Policy Managers Guide—This document defines the policy model used by BEA WebLogic Enterprise Security, and describes how to generate, import and export policy data.
- Programming Security for Java Applications—This document describes how to implement security in Java applications. It includes descriptions of the security service Application Programming Interfaces and programming instructions.
- Developing Security Providers for BEA WebLogic Enterprise Security —This document provides security vendors and security and application developers with the information needed to develop custom security providers.
- Javadocs for Java API—This document provides reference documentation for the Java Application Programming Interfaces that are provided with and supported by this release of BEA WebLogic Enterprise Security.
- Javadocs for Security Service Provider Interfaces—This document provides reference documentation for the Security Service Provider Interfaces that are provided with and supported by this release of BEA WebLogic Enterprise Security.
- Programming Security for Web Services—This document describes the Web Services programming interfaces.

## Contact Us!

Your feedback on the BEA Web Server documentation is important to us. Send us e-mail at docsupport@bea.com if you have questions or comments. Your comments will be reviewed directly by the BEA professionals who create and update the Web Server documentation.

In your e-mail message, please indicate that you are using the documentation for BEA WebLogic Enterprise Security Web Server Security Service Module 4.2 SP2.

If you have any questions about this version of Web Server, or if you have problems installing and running the product, contact BEA Customer Support at http://support.bea.com. You can also contact Customer Support by using the contact information provided on the quick reference sheet titled "BEA Customer Support," which is included in the product package.

When contacting Customer Support, be prepared to provide the following information:

- Your name, e-mail address, phone number, and fax number
- Your company name and company address
- Your machine type and authorization codes
- The name and version of the product you are using
- A description of the problem and the content of pertinent error messages

# Product Overview

The BEA Weblogic Enterprise Security provides three Web Server products: the IIS Web Server Security Service Module (SSM), the Apache Web Server SSM, and the Web Services SSM (see Figure 1-1).

Note: Henceforth, the IIS and Apache Web Server SSM products will be generally referred to in this document as the Web Server SSM. When it is necessary to highlight differences, they will be referred to specifically be name.

Figure 1-1 Web Server Product Components

The following topics provide more information on the these products:

- Web Server Product Environment
- Web Server Security Service Module

## Web Server Product Environment

Figure 1-2 shows the major components that make up the BEA WebLogic Enterprise Security Web Server product environment.

Figure 1-2 Web Server Product Environment

- Administration Application

The Administration Application allows you to configure, deploy, and manage multiple Security Service Modules in a distributed environment. While the modules consume configuration data and then service security requests accordingly, the Administration Application allows you to configure and deploy security configuration information to the modules and modify that information as needed.

- Service Control Manager

The Service Control Manager (SCM) is an essential component of the configuration provisioning mechanism and a key component of a fully-distributed security enforcement architecture. A Service Control Manager is a machine agent that exposes a provisioning, or deployment, interface to the Administration Application to facilitate the management of a potentially large number of distributed Security Service Modules (SSMs). The Service Control Manager can receive and store meta-data updates, both full and incremental, initiated by the Administration Application.

The Administration Application uses this provisioning mechanism to distribute configuration data to each enrolled instance of a SSM where it is stored locally (see Figure 1-3). Each instance of a SSM is assigned a unique configuration ID, which is registered with the SCM when the SSM is enrolled. The SCM uses the configuration ID when distributing and updating configuration data to each SSM instance to ensure that the correct data is distributed.

- Web Server Security Service Module

The Web Server Security Service Module (SSM) is used to adapt web servers to the WebLogic Enterprise Security infrastructure so that web server resources can be protected by a custom security configuration. You define and deploy the security configuration using the Administration Application. You can only configure one instance of each type of Web Server SSM (IIS, Apache and Web Services) on a single machine, however, the number of machines in your network on which you can configure Web Server SSMs is unlimited (see Figure 1-3). After you deploy the initial security configuration to a Web Server SSM, it does not require any additional communication with the Service Control Manager (SCM) to perform runtime security functions. However, the SCM does maintain communication with each Web Server SSM instance so that it can distribute, or deploy, full and incremental security configuration updates.

Figure 1-3 Deploying Security Configuration Data

## Web Server Security Service Module

The Web Server Security Service Module (SSM) provides an environmental binding between the WebLogic Enterprise Security infrastructure and IIS and Apache web servers. The WebLogic Enterprise Security infrastructure provides six distinct services: Registry, Authentication, Authorization, Auditing, Role Mapping, and Credential Mapping. Each of these services is expressed in a way that is understandable to applications running within a web server that is protected by the WebLogic Enterprise Security infrastructure. Therefore, the SSM can be used to configured and enforce security for web server applications and resources.

The Web Server SSM makes access control 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.

You can tailor the Web Server SSM to meet your 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. Additionally, the Web Server SSM enables security administrators and web developers to perform security tasks for applications running on a web server.

Figure 1-4 shows the components of the Web Server SSM. The following topics describe the components:

- Web Server Environmental Binding
- Web Services Security Service APIs
- Security Providers

Figure 1-4 Web Server SSM Components

### Web Server Environmental Binding

The environmental binding is used to bind with and interact with specific types of web servers. 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.

After you install the Web Server SSM, you use it to bind it to the web server, which, in effect, projects the WebLogic Enterprise Security subsystem into the web server environment. For the Microsoft IIS Web Servers, the binding is implemented using the ISAPI. For the Apache Web Servers, the binding is implemented using an Apache module. The Web Server SSM accepts HTTPS requests from the web server and presents them to the Security Framework using the Web Services SSM.

Additionally, the Web Server SSM implements the server-side includes (SSIs) that process SAML Browser/POST profile.

### Web Services Security Service APIs

The Web Services Security Service APIs enable access to the Security Framework. These APIs provide the following security services:

Note: The following topics provide a very brief description of these APIs. For more information, see Programming Security for Web Services.

- Authentication Service
- Authorization Service
- Auditing Service
- Role Mapping Service
- Credential Service

#### Authentication Service

There are two variations of authentication, JAAS-based and identity assertion. JAAS-based authentication collects evidence (credentials) from a user in order to establish user identity.

Note: For more information on JAAS, see Java Authentication and Authorization Service (JAAS) on the Web at http://java.sun.com/products/jaas/.

Identity assertion authentication consumes a trusted token object to establish identity. The Web Services SSM supports both types of authentication.

- JAAS authentication is highly variable and is dependent upon the configured authentication provider. An authentication provider can use several different types of questions (modeled as callbacks) to collect information from the user.

Note: The Web Services SSM does not support custom callback types.

- Identity assertion authentication is linked to a specific protocol. For example, X.509 certificate assertion is only valid within the context of a 2-way SSL handshake, and SAML identity assertion is only valid in the context of an Oasis SAML profile. The Web Services SSM implements the Oasis SAML Browser/POST profile and consumes or produces a SAML Indentity Assertion.

#### Authorization Service

The Web Services SSM security infrastructure provides fine grained highly contextual authorization. However, the granularity of the authorization decision is often restricted by the web server you are protecting. The only standard form of addressable resource in a web server is a URL, so that is the resource that is protected with the HTTP method as the operation on the resource.

In addition to providing a simple permit or denied decision on a URL, the authorization service also has the ability to return attributes into the request as determined by security policy. Because the inclusion of coding in the application to handle these attributes creates an undue coupling between the application and security infrastructure, the Security Service Module inserts these returned attributes into the HTTP request header. Depending upon the technology used (ASP, CGI, ISAPI), these headers can be extracted and used by the application.

#### Auditing Service

The auditing service audits all transactions through the security subsystem. Every URL accessed is sent through the auditing infrastructure.

#### Role Mapping Service

Although roles are primarily used in authorization, some applications may wish to have access to the roles to which a user is mapped for the purposes of role-based personalization. In order to provide this information to the running applications, the Web Services SSM adds a list of roles to the HTTP request header. Depending upon the technology used (ASP, CGI, ISAPI), the application can extract this list of roles from the header and use it.

#### Credential Service

The credential service returns sensitive credentials to an application so that the application can use systems that require a secondary (or tertiary) layer of authentication. The Web Services SSM extracts mapped credentials from the security system and makes them available in the HTTP header for use by the application. Depending upon the technology used (ASP, CGI, ISAPI), the application can extract the credential headers and use them to authenticate to other back-end systems.

### Security Providers

When you install a Security Service Module, a JAR file is deployed that contains all the security providers that ship with the product. However, before any of the security providers can be used, you must use the Administration Console to configure them. You have the option of configuring either the security providers that ship with the product or custom security providers, which you may develop yourself or purchase from third-party security vendors.

Note: To use security providers with the Security Service Module, you must deploy the security provider MBean JAR file (MJF) to the providers directory on both the machine on which you install the Security Service Module and on the machine on which you install the Administration Console.

The Security Service Module supports the following security providers:

- ALES Credential Mapping provider
- ALES Identity Assertion provider
- ASI Adjudication provider
- ASI Authorization provider
- ASI Role Mapping provider
- Database Authentication provider
- Log4j Auditing provider

For more information on security providers, see Introduction to BEA WebLogic Enterprise Security, the Administration Application Guide, and the Console Help.

For more information on how to develop custom security providers, see Developing Security Providers for BEA WebLogic Enterprise Security.

# Product Features

This section describes the features of the Web Server Security Service Module. The following topics are covered:

- Web Single Sign-on Capabilities
- Authentication Service Features
- Authorization Service Features
- Auditing Service Features
- Role Mapping Features
- Credential Mapping Features
- Administration Features
- Session Management Features
- Configuration Features

## Web Single Sign-on Capabilities

This section covers the following topics:

- What is Web Single Sign-On?
- Single Sign-On Use Cases
- Single Sign-On with SAML on page 1-15

### What is Web Single Sign-On?

Web single sign-on is an access-control mechanism that enables users to log on to one web server and gain access to other web servers in the same domain without supplying log-in credentials again, even though the other web servers may have their own authentication schemes or requirements. Figure 1-5 shows the basic components of a web single sign-on service.

Figure 1-5 Web Single Sign-on

While web single sign-on removes the requirement for users to log on every time they access a different web server and thus makes user access easier, it does not improve security. In fact, you should take security requirements into consideration when implementing a web single sign-on solution.

### Single Sign-On Use Cases

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

- Bi-directional single sign-on among instances of Web Server SSMs—Once users are authenticated by a Web Server SSM instance, they are given a identity assertion token that they can use to access other Web Server SSM instances without being required to authenticate again (see Figure 1-6).

Figure 1-6 Web Server SSM to Web Server SSM Single Sing-on

- Uni-directional single sign-on from Web Server SSM instances to WebLogic Server 8.1 SSM instances—Once users are authenticated by a Web Server Security Service Module instance, they are given an identity assertion token that they can use to access WebLogic Server 8.1 Security Service Module instances without being required to authenticate again (see Figure 1-7).

Figure 1-7 Web Server SSM to WebLogic Server SSM Single Sign-On

### Single Sign-On with ALES Identity Assertion

The Web Server Security Service Module (SSM) and WebLogic Server 8.1 SSM support single sign-on using the ALES Identity Assertion provider.

For instructions on how to implement Single Sign-On, see Configuring Web Single Sign-on with ALES Identity Assertion.

## Authentication Service Features

The authentication service supports the following features:

- Converts JAAS callbacks to asynchronous—The authentication service used in the Security Framework is JAAS based, however, the Web Server SSM masks the JAAS synchronous callback protocol from the web server. When form-based authentication is configured, the credentials are initially gathered and used for authentication. In most cases, an initial form gathers all credentials necessary for authentication.
- Supports all seven standard JAAS callbacks—Sun Microsystems defines seven types of callbacks: NameCallback, PasswordCallback, ChoiceCallback, ConfirmationCallback, LanguageCallback, TextInputCallback, TextOutputCallback. The authentication service used in the Security Framework is JAAS based.

Note: If a new callback type is encountered during authentication, the Web Server SSM ignores it.

- Supports multiple phases of authentication—JAAS may ask several series of questions using callbacks. Therefore, the SSM does not assume that answering one set of callbacks is sufficient.
- Supports web farms—The following features are supported for web farms:

- Redirect during credential gathering—Within a web farm it is possible for a series of questions (on a form) to start on one machine and be transparently redirected to another machine within that web farm.
- Single sign-on—Within a web farm it is possible that a user is authenticated on one machine and transparently redirected to another. However, a mechanism must be available by which the second machine can accept the identity from the first without having to re-authenticate the user. The identity is only shared within the same cookie domain.

- Supports single sign-on with other Security Service Modules—The Web Server SSM can share identity with a custom application that is protected by the Java SSM or another client of the Web Server SSM. The Java SSM and the Web Server SSM use the ALES Credential Mapper and ALES Identity Assertion providers. Single sign-on is limited to a cookie domain.
- Supports SAML Browser/POST profile—The Web Server SSM consumes an identity assertion from a SAML 1.1 Browser/POST transaction and provides an identity transfer service to serve SAML 1.1 identities to remote systems.
- Supports custom, form-based authentication—The Web Server SSM allows the user to edit and customize the forms used in form-based authentication.

## Authorization Service Features

The authorization service supports the following features:

- Resource form—The Web Server SSM de-references any use of "`..`" and decodes URL encoding. The resource is presented as the path element of a URL and the file or application name. For example, the following URL:

>     http://www.bea.com/framework.jsp?CNT=index.htm&FP=/content/products/aqualogic/

is presented as /framework.jsp. The query arguments CNT and FP and their associated values are made available in the application context.

- Allows for unprotected URLs—The Web Server SSM always uses the `isAuthenticationRequired()` method to check whether a resource is protected by a security system. This feature is important because you may want to leave some web server resources unprotected.
- Checks for a resource authorization—When checking for resource authorization, the following features are supported:

- Includes rich web service request context—Because a web application cannot know what elements may be required for enforcement of security at the time of its authoring, it is important that information about the web services request be available in the context given to the security subsystem. The Web Server SSM provides HTTP headers, cookies, query arguments, and form values to the security subsystem. The SSM also decodes all URL encoded context elements before presenting them to the security subsystem.
- Works with existing unmodified web applications—The Web Server SSM does not require modification or special code to work with existing web applications running on the web server.

- Retrieves response attributes during authorization—The Web Server SSM retrieves response attributes during the authorization process and provides them in a form that a layered web application can use.

## Auditing Service Features

The auditing service has the following capabilities:

- All transactions are audited—All authentications, identity assertions, authorizations, role mappings, credential mappings and audit failures are automatically made available to the auditing infrastructure by the Security Framework.
- Session cleanup activity is audited—The occurrence of idle and absolute timeouts are audited by the Web Server SSM.

## Role Mapping Features

The role mapping service has the following capabilities:

- 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 WebLogic Enterprise Security but can change depending upon the resource and various elements of the context.

## Credential Mapping Features

Credentials are any objects or set of objects that can be used as evidence for the propagation of identity or for impersonation. WebLogic Enterprise Security 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:

- Provides mapped username/password credentials—The Web Server SSM extracts mapped username/password credentials to the application running within the SSM. This username/password can be used for legacy SSO to log into a database or other system. The Web Server SSM does not use these credentials itself; it will make them available to the web server application.
- Supports unknown credential types—The Web Server SSM provides a way to inject other credential formats. Since these other formats are unknown to the SSM, they must be converted to a string before being presented to the application.

## Administration Features

In addition to configuring security providers for the SSM, administering the security configuration involves writing security policy for users, groups, roles, and resources policy for the web application resources the SSM protects. The Web Server SSM has the following features:

Presents the full URL—The Web Server SSM makes the full URL, including the protocol, server name, port, full path, and query string, available to the security framework. The full URL is presented as part of the context to allow its use in security policy. However, the resource presented to the system is in the canonical form. For example, for a web server with the names www.bea.com, www.beasys.com, www. web.internal.bea.com, and 204.236.43.12 , the canonical name is www.bea.com.

- Uses the HTTP method as the action—The HTTP method (GET, POST, HEAD, PUT) is presented by the Web Server SSM as the action for authorization. In the administration system the privilege must match the action for a rule so this feature allows for separate security policies to be applied to POSTs, GETs, and other methods.
- Passes in an application context—The application context is passed through to the authorization and role mapping security providers configured in the SSM and is associated with any audit records logged. This context contains values relevant to the request environment at the time the security provider processes the call.

## Session Management Features

The WebLogic Enterprise Security services are stateless services, so it is the client of the Web Services SSM that is responsible for determining session related information. In addition, in HTTP, there is no notion of a logout, and so session termination must be inferred by a lack of activity. Therefore, to manage session behavior, the Web Server SSM has the following capabilities:

- Supports session inactivity timeout—Based upon the inactivity timer, a session can be considered terminated after it has been inactive for a configurable period of time
- Supports Absolute timeout—An absolute timer that terminates a session after a certain (usually large) period of time prevents a remote client from staying connected perpetually, which can be a security risk.
- Supports forced logoff—The Web Server SSM provides a means to force a logoff by immediately terminating the session for a single DNS domain.
- Supports session cookie—The Web Server SSM only uses a session cookie, not a persistent cookie.

## Configuration Features

Configuration includes the process by which the web server is integrated with the Web Server SSM. Specifically, 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:

- Provides a logging channel—To facilitate configuration and debugging, the Web Server SSM provides logging.
- Supports a flag to control logging and debug mode—To determine what kinds of messages are logged, the Web Server SSM provides a configurable flag that is used to determine which messages are logged.

# Product Constraints and Limitations

The Web Server SSM has the following constraints and limitations:

- Does not support cross cookie domain Single Sign-On (SSO) except through SAML Browser/POST profile.
- Does not support cross cookie domain forced logoff.
- Because some Web SSM configuration is local to the web server machine, local configurations on each web server machine must be manually synchronized in order to support web farms.
- Does not support special handling of third-party cookies.
- Requires use of cookies to maintain session state.
- The web server must be manually configured to use the Web Server SSM.
- Does not support load-balancing or failover in accessing the Web Services SSM.
- The Web Server SSM must be installed on the same machine as the web server to which it is bound.
- Does not support SAML Browser/Artifact profile.
- Does not preserve the original POST data during redirection to an authentication form.
- Does not save and transfer credentials between machines when more than one machine is involved in an attempt to authenticate a user Within a web farm, it is possible for a series of questions (on a form) to start on one machine and be transparently redirected to another machine within that web farm. The SSM does not save credentials that have already been entered in the same authentication attempt. Therefore, users are forced to re-enter credential information when more than one machine is involved.