Sun Java System Web Server 7.0 Update 5 Developer's Guide to Java Web Applications

Securing Web Services

Web Services Security SOAP Message Security (WS-Security) is an international standard for interoperable web services security that was developed in OASIS by a collaboration of all the major providers of web services technology (including Sun Microsystems). WS-Security is a message security mechanism that uses XML Encryption and XML Digital Signature to secure web services messages sent over SOAP. The WS-Security specification defines the use of various security tokens including X.509 certificates, SAML assertions, and username and password tokens to authenticate and encrypt SOAP Web Services messages. This section also includes the following sections:

Understanding Message Security in the Web Server

The Web Server offers integrated support for the WS-Security standard in the server-side container. This functionality is integrated with Web Services security and enforced by the container of the Web Server on behalf of applications. Web Server can protect any web service application without requiring changes to the implementation of the application. The Web Server achieves this effect by providing facilities to bind SOAP layer message security providers and message protection policies to container and to applications deployed in container.

Assigning Message Security Roles

In the Web Server, the system administrator and application deployer roles are expected to take primary responsibility for configuring message security. In some situations, the application developer also contribute, although in the typical case either of the roles might secure an existing application without changing its implementation and therefore without involving the developer. The responsibilities of the various roles are defined in the following sections.

System Administrator Tasks

The system administrator is responsible for the following tasks:

A system administrator uses the Admin Console to manage server security settings. Web Server stores certificates and private keys in an NSS database, the administrator can manage them using certutil. For an overview of message security tasks, see Configuring the Web Server for Message Security.

Application Deployer Tasks

The application deployer is responsible for the following tasks:

The application developer can setup message security but is not responsible for doing so. The system administrator can set the message security so that all Web Services are secured. The application deployer can set the message security when the provider or protection policy bound to the application must be different from that bound to the container.

Application Developer Tasks

The application developer or assembler is responsible for the following tasks:

Security Tokens and Security Mechanisms

The WS-Security specification provides an extensible mechanism for using security tokens to authenticate and encrypt SOAP Web Services messages. Use the SOAP-layer message security providers installed with the Web Server to employ username, password and X.509 certificate security tokens to authenticate and encrypt SOAP Web Services messages.

Username Tokens

The Web Server uses username tokens in the SOAP messages to establish the authentication identity of the message sender. The recipient of a message containing a Username token within an embedded password validates that the message sender is authorized to act as the user (identified in the token) by confirming that the sender knows the users secret password.

When using a Username token, a valid user database must be configured on the Web Server.

Digital Signatures

The Web Server uses XML Digital signatures to bind an authentication identity to the message content. Clients use digital signatures to establish their caller identity, analogous to basic authentication or SSL client certificate authentication. Digital signatures are verified by the message receiver to authenticate the source of the message content, which might be different from the sender of the message. When using digital signatures, valid keystore and truststore files must be configured on the Web Server.


The purpose of encryption is to modify the data such that it can only be understood by its intended audience. This modification is accomplished by substituting an encrypted element for the original content. When predicated on public key cryptography, encryption establishes the identity of the parties who can read the message.

Message Protection Policies

Message protection policies are defined for request message processing and response message processing. These policies are expressed in terms of requirements for source or recipient authentication. A source authentication policy requires that the identity of the entity that sent a message or that defined the content of a message be established in the message so that the message receiver can authenticate it. A recipient authentication policy represents a requirement that the message be sent such that the identity of the entities that can receive the message can be established by the message sender. The providers apply specific message security mechanisms so that the message protection policies are in SOAP Web Services messages.

Request and response message protection policies are defined when a provider is configured in a container. You can also configure application-specific message protection policies at the granularity of the web service port or operation within the Sun deployment descriptors of the application or application client. Where message protection policies are defined, the request and response message protection policies of the client must match the request and response message protection policies of the server.

Securing a Web Service

Web Services deployed on the Web Server are secured by binding SOAP-layer message security providers and message protection policies to the container in which the applications are deployed or to web service endpoints served by the applications. When the Web Server is installed, SOAP-layer message security providers are configured in the server-side container of the Web Server. The container or individual applications in the container can bind to them or to individual applications in the container. During installation, the providers are configured with a simple message protection policy that, if bound to a container or to an application, would cause the source of the content in all request and response messages to be authenticated by an XML digital signature.

Use the Admin Console and CLI to perform the following tasks:

By default, message layer security is disabled on the Web Server. For more information about how to configure message layer security for the Web Server, seeConfiguring the Web Server for Message Security. For more information about how to use Web Services security to protect all Web Services applications deployed on the Web Server, see Enabling Providers for Message Security.

Once this security is established, Web Services security will be applied to all Web Services applications deployed on the Web Server.

Configuring Application-Specific Web Services Security

Configure application-specific web services during application assembly by defining message-security-binding elements in the applications Sun deployment descriptors. Use these message-security-binding elements to associate a specific provider or message protection policy with a web services endpoint or service reference. You can also qualify these elements so that they apply to a specific port or method of the corresponding endpoint or referenced service.

Admin Console Tasks for Message Security

All the steps for setting up the Web Server for using message security can be accomplished using the Admin Console or the wadm command-line tool. For more information on message security, see Sun Java System Web Server 7.0 Update 5 Administrator’s Guide.

Support for message-layer security is integrated into the Web Server in the form of pluggable authentication modules. By default, message layer security is disabled on the Web Server. The tasks in this section provide the details for enabling, creating, editing, and deleting message security configurations and providers.

In most cases, you need to restart or reconfigure the Web Server after performing these tasks, especially to apply the change to applications already deployed on Web Server.

Procedure To Create a Message Security Provider

You can add or edit or modify the message protection policy. The provider type, implementation class, and provider-specific configuration properties should be modified.

  1. Login to the Admin Console.

  2. Select the configuration you want to modify and click Edit Configuration.

  3. Click the Java tab.

  4. Click the Authentication tab and scroll down to the SOAP Authentication.

    • To modify an existing provider, select the provider name and edit the values.

  5. Click New to add a provider.

  6. Add the new provider information

    In this page, following information is available for modification.

    Note –

    Only Name and class Name are required. If these two fields are not specified, no authentication is applied to request or response messages. All other values are optional.

    • Name: Identifier for this provider. You can use this identifier name to specify the default provider when using wadm.

    • Class Name: The Java implementation class of the provider. Server-side providers must implement the interface.

      The request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Type the policies in message-sender order. For example, a requirement that encryption occur after content means that the message receiver expects to decrypt the message before validating the signature.

    • Request Authentication Source— Possible values are:

      • sender: Message-layer sender authentication, such as username and password

      • content: Content authentication, for example, digital signature

      • null: Source authentication of the request is not required

  7. Click the Add Property button to add additional properties.

    The provider shipped with the Web Server requires the server-config property. If other providers are used, refer to their documentation for more information on properties and valid values.

    • server.config: The directory and file name of an XML file that contains the server configuration information. This file is in the following location install_dir/samples/java/webapps/webservices/security/etc/wss-server-config-2.0.xml.

  8. Click OK.

Example 3–1 To set the response policy, replace the word request in the following commands with response.

Enabling Providers for Message Security

You can enable the message security Web Services endpoints by specifying the default provider on the server side or by specifying in the message-binding element in sun-web.xml.

If you enable a default provider for message security, you also need an appropriate message security on the client side.

Note –

You cannot specify a default provider using the Admin Console. You have to specify the default provider through the wadm command-line interface.

../bin/wadm set-config-prop --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test default-soap-auth-provider-name=msgsecurity-provider

ProcedureTo Delete a Message Security Provider

  1. Login to the Admin Console.

  2. Select the configuration you want to modify and click Edit Configuration.

  3. Click the Java tab.

  4. Click the Authentication tab and scroll down to SOAP Authentication.

  5. Click Delete.

Example 3–2 To Delete a Message Provider

To delete a message security provider through the command-line interface, type the following command:wadm delete-soap-auth-provider --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test msgsecurity-provider

Enabling Message Security Clients

Configure the message protection policies of client so that they are equivalent to the message protection policies of the server-side providers with which they interact. A typical stand-alone client is illustrated by the bundled sample fromwsdl-soap12.