Skip navigation.
Downloads | Product Documentation | Support

Programming Security for Web Services

# Introduction to the Web Services Security Service Module

This section provides an introduction to AquaLogic Enterprise Security Web Services Security Service Module and describes interfaces clients use to interact with it.

This section covers the following topics:

- Overview of Web Services
- Product Overview
- Product Features

# Overview of Web Services

Web services are a special type of service that can be shared by and used as components of distributed Web-based applications. Web services interface with existing back-end applications, such as customer relationship management systems, order-processing systems, and so on.

Traditionally, software application architecture tended to fall into two categories: huge monolithic systems running on mainframes or client-server applications running on desktops. Although these architectures work well for the purpose the applications were built to address, they are closed and cannot be easily accessed by the diverse users of the Web. Thus the software industry has evolved toward loosely coupled service-oriented applications that interact dynamically over the Web. The applications break down the larger software system into smaller modular components, or shared services. These services can reside on different computers and can be implemented by vastly different technologies, but they are packaged and transported using standard Web protocols, such as Extensible Markup Language (XML) and Hyper Text Transfer Protocol (HTTP), thus making them easily accessible by any user on the Web.

This concept of services is not new. Remote Method Invocation (RMI), Component Object Model (COM), and Common Object Request Broker Architecture (CORBA) are all service-oriented technologies. However, applications based on these technologies must be written using that particular technology, often as implemented by a particular vendor. This requirement typically hinders widespread acceptance of such services on the Web. To solve this problem, web services are defined to share the following properties that make them easily accessible from heterogeneous environments:

- Web services are accessed over the Web.
- Web services describe themselves using an XML-based description language.
- Web services communicate with clients (both end-user applications or other web services) through XML messages that are transmitted by standard Internet protocols, such as HTTP.

# Product Overview

The BEA AquaLogic Enterprise Security provides three Web Server Security Service Modules (SSMs): the IIS Web Server SSM, the Apache Web Server SSM, and the Web Services SSM (see Figure 1-1). This document only describes the Web Services SSM and the security service application programming interfaces (APIs) that it supports.

Figure 1-1 Web Server and Web Services SSMs

The following topics provide more information on the these products:

- Web Services Environment
- Web Services Security Service Module
- Client Trust Model
- Deployment Model
- Usage Model

## Web Services Environment

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

Figure 1-2 AquaLogic Enterprise Security Product Environment

- Administration Server

The Administration Server 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 Server 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 SCM is a machine agent that exposes a provisioning, or deployment, interface to the Administration Server to facilitate the management of a potentially large number of distributed Security Service Modules (SSMs). The SCM can receive and store meta-data updates, both full and incremental, initiated by the Administration Server.

The Administration Server uses this provisioning mechanism to distribute configuration data to each created instance of a SSM where it is consumed 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 Services Security Service Module

The Web Services SSM provides an application programming interface (API) that allows security developers to write custom applications that invoke AquaLogic Enterprise Security services through SOAP. These interfaces support the most commonly required security functions and are organized into services that are logically grouped by functionality. You define and deploy the security configuration using the Administration Server. You can configure more than one instance of the Web Services SSM on a single machine, however, each instance must run in separate process. The number of machines in your network on which you can configure a Web Services SSM 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 Services SSM instance so that it can distribute, or deploy, full and incremental security configuration and updates and updates to access control policies.

Figure 1-3 Deploying Security Configuration and Policy Data

## Web Services Security Service Module

The Web Services Security Service Module (SSM) provides five security service APIs: Authentication, Authorization, Auditing, Role Mapping, and Credential Mapping (see Figure 1-4). These APIs can be used to developed web services clients to access the AquaLogic Enterprise Security infrastructure and use it to make access control decisions for users attempting to access web server application resources. Once the web services client is implemented, it uses the Web Services SSM (which incorporates the Security Services APIs, the Security Framework, and the configured security providers) to make access control decisions for the web server to which it is connected. Then you can use the AquaLogic Enterprise Security Administration Server to configured and deploy a security configuration to protect the web server application resources. Thus, the Web Services SSM enables security administrators and web developers to perform security tasks for applications running on a web server. Additionally, you can use the Web Services SSM to add information provided by the Security Framework (such as roles and response attributes) to the HTTP requests handled by the protected web server applications.

Figure 1-4 shows the components of the Web Services SSM.

Figure 1-4 Web Services SSM Architecture

For a description of the Web Services Security Service APIs, see Web Services Interfaces

## Client Trust Model

To protect messages in transit between the client and the Web Services SSM, a channel security protocol (SSL 3.0 or TLS 1.0) is used for all communication between the two. The Web Services SSM supports both one-way and two-way SSL (see Figure 1-5). To establish an SSL connection with one-way SSL, only the server is required to present a digital certificate. With two-way SSL authentication, both the client and server must present digital certificates before the SSL connection is enabled between the two. Thus, with two-way SSL, the Web Services SSM not only authenticates itself to the client to complete the SSL handshake (which is the minimum requirement for certificate authentication), but it also requires authentication from the requesting client. The client first authenticates the server's certificate, and then the server authenticates the client's certificate. The client certificate must be signed by a recognized certificate authority (CA).

As mentioned, Web services clients can communicate with the Web Services SSM over one-way or two-way SSL connections. However, when the client communicates over a one-way SSL, each client request be accompanied by a valid client name/password pair or a ALES cookie. Figure 1-5 shows the Web Services SSM client trust model.

For more information on authentication, see Authentication Service Interface.

Figure 1-5 Client Trust Model

## Deployment Model

Figure 1-6 shows how you typically deploy instances of Web Services Security Service Modules (SSM) to protect application resources. The web servers (the web services clients) are located in the web tier, which is in the Demilitarized Zone (DMZ), and are protected from unwanted traffic on the Internet by a firewall. The DMZ is created by using two firewalls. If the web servers and Web Services SSMs are running on different machines, the Web Services SSMs are located in the application tier behind the second firewall for added security. The Web Services SSM supports Secure Sockets Layer (SSL) communication so all traffic between the web servers and the SSM is encrypted.

Figure 1-6 Typical Web Services Deployment Model

## Usage Model

Once the Web Services client has established an SSL connection with the Web Services SSM, it can issue requests on behalf of users for access to the web resources protected by the Web Services SSM (see Figure 1-7).

- User A uses web servers with web services client plug-ins to access the Registry Service and locate specific instances of SSMs and a specific security service on that SSM instance. The Web servers use that information to make requests access to application resources on behalf of users. BEA provides two web server products that have built-in web services clients, the IIS Web Server SSM and the Apache Web Server SSM.
- User B uses a custom SSM client, which has a user-written web services client, to access the Registry Service and in turn the specific SSM security service. Because communication between the custom SSM client and the Web Services SSMs is placed on the network, the custom SSM clients can be located any where on the network. Their location is not restricted to the local machine.
- The Admin user uses the administration console to the distribute the initial security configuration and all updates over the network. If the Administration Server is disconnected from the Web Services SSMs, the SSMs continue to function.

Figure 1-7 Usage Model

The interaction between the client and the Web Services SSM is as follows (see Figure 1-7):

1. The client issues a user request that includes the following:

- A user identity credential (a username/password pair, a signed SAML 1.1 assertion, or ALES cookie)
- The resource to which the user wants access and the action to be performed
- The Authentication Service

2. The client queries the local Registry Service to retrieve the fully qualified URL for the endpoint of the authentication service. If the authentication service exists on the local machine, the SSM returns the URL to the client. If it does not exist, the request fails. If the Authentication Service is omitted from the client request, the URL for the default authentication service on the local machine is returned.
3. The web services client calls the Authentication Service, uses the user credentials to authenticate the user. If authentication succeeds, the service returns an identity assertion token that is an internal representation of the user's identity. If the authentication fails, the service returns an AuthenticationFaliure SOAP Fault.
4. The client queries the local Registry Service to retrieve the fully qualified URL for the endpoint of the Authorization Service.
5. The Authorization Service and the associated Role Mapping Service determine whether the user has been granted the privileges required to access to the specified resource and perform the requested action. The service answers the question "Is this user allowed to perform the particular action on specified resource?" To make the access decision, the service compares the roles granted to the user to the policy written to protect the requested resource. If none of the user's roles match the roles allowed to access the requested resource, or if the resource does not have any policy to protect it, access is denied.
6. If access is allowed, the user is granted access to the resource and the request is serviced.

# Product Features

The Web Services Security Service Module (SSM) has the following features:

- Standalone Deployment

Each instance of a Web Services SSM is made accessible to clients via a separate SOAP endpoint with a unique URL. Further, each security service is deployed as a separate component inside the hosting process, with each service using disparate configuration entry to identify and initialize itself. Figure 1-8 shows how each Web Services SSM is deployed and initialized in an environment where multiple Web Services SSMs are deployed.

Figure 1-8 Multiple Web Services SSM Deployments

- Credentials Protection

Identity assertions must be signed by a trusted entity. An assertion that is not signed or signed by an unknown authority is rejected and the processing stopped. The digital signature is attached to the identity assertion and covers the entire assertion.

- XML Structures Follow Industry Standards

The XML structures defined by the OASIS WS-Security Standard v1.0 for passing username/password during client authentication with one-way SSL. See Figure 1-9 for the general format of the SOAP messages exchanged between the web services client and the Web Services SSM.

Figure 1-9 SOAP Message Format

- Secure Web Services security service APIs

Access to the Web Services SSM security service APIs is restricted to clients that have been authenticated.

- Channel and message protection

In order to protect messages in transit, the Web Services SSM supports a channel security protocol (SSL 3.0 or TLS 1.0) for all communication that takes place between the SSM and its clients.

- Support for one-way and two-way SSL client connections

The Web Services SSM always authenticates itself to client using its X.509 site certificate.

A client presents its certificate as part of a two-way SSL handshake with the Web Services SSM servlet container. The client's identity, contained in the SSL certificate, is subsequently used for client authentication.

Note: For two-way SSL authentication, any certificate authority (CA) used to generate the client certificate must be manually added to the Web Services SSM `peer.jks` keystore.

- Automatic restart of security services

The Web Services SSM uses the AquaLogic Enterprise Security process monitoring and management mechanism to automatically restarted a security service if it is found to be unresponsive. Upon restart, the service is initialized using the latest configuration and automatically resumes its normal operation.

- Event auditing capabilities

The Web Services SSM relies on the AquaLogic Enterprise Security auditing capabilities to provide a file-based, audit logging facility with configurable audit log filename. Any service or request-related failures produce an audit trail. Additionally, the following Web Service SSM instance lifecycle events produce audit trails:

- Initialization complete, ready to serve requests
- Shutdown initiated
- Restarted after a process crash

- Configuration stored locally

The Web Services SSM relies only on the local configuration for its operation. The local configuration includes all necessary information to start-up Web Services SSM process, identify its instance, and set up a two-way SSL connection to the local Service Control Manager (SCM) process.

- WSDL 1.1

The Web Services Description Language (WSDL) is an XML-based specification that describes a web service. A WSDL document describes web service operations, input and output parameters, and how a client application connects to the web service.

For more information, see http://www.w3.org/TR/wsdl.