As Published In
Oracle Magazine
January/February 2005

DEVELOPER: Web Services

Securing Web Services

By Mike Lehmann

Move from transport-based security to message-based security.

When I give presentations about Web services, questions inevitably come from the audience regarding security. The most common question is, "How do you secure Web services?" often followed by the skeptical statement "Web services can't be secured."

But, remember, the majority of Web services today are based on the same enabling technology that underlies the Web, namely HTTP. As a result, all of the common technologies that secure Web applications—basic authentication and SSL being the most common—work equally well with Web services. These security technologies have been amazingly effective for years for all sorts of online business transactions, and they work equally well for Web services.

However, the main issue organizations have with Web-based security approaches is that common solutions such as SSL are a little heavy-handed, because they often secure the entire wire protocol rather than just the SOAP message sent over the protocol. Further, for many message-based integration projects, several intermediary steps are necessary before messages arrive at their target end point, and transport-level security leaves the messages unsecured at each intermediary checkpoint.

To get a finer level of control and avoid the intermediary security issues, what organizations doing SOAP-based message integration typically want is security at the message level rather than at the transport level. What this means is securing the message itself, independently of the transport. Several things become apparent when securing just the message. First, the SSL capabilities typically provided by most Web services are replaced by something I'll call message security, necessary for any client or server to interact with the secure message. Second, the security information is carried in the message itself. Third, unless the intermediary or end point has the correct security infrastructure and is trusted, the message will remain secure and unreadable and can be forwarded to the next end point.

Web Services Security: WS-Security

How do you secure the message rather than the transport? The answer lies with the OASIS standard, WS-Security, released as a full industry-recognized recommendation in April 2004. What WS-Security defines is a mechanism for adding three levels of security to SOAP messages.

Authentication Tokens: WS-Security authentication tokens enable clients to send, in a standardized fashion, username and password or X.509 certificates for purposes of authentication within the SOAP message headers. Although SAML and Kerberos tokens are also common, the WS-Security profile for these tokens has not been released yet.

XML Encryption: WS-Security's use of the W3C's XML Encryption standard enables the SOAP message body or portions of it to be encrypted to ensure message confidentiality. Typically, various encryption algorithms are supported—in Oracle Application Server 10g Release 10.1.3, the algorithms supported are 3DES, AES-128, and AES-256.

XML Digital Signatures: WS-Security's use of the W3C's XML Digital Signature standard enables SOAP messages to be digitally signed to ensure message integrity. Typically, the signature is a computed value based on the content of the message itself: If the message is altered en route, the digital signature becomes invalid. Oracle Application Server supports DSA-SHA1, HMAC-SHA1, RSA-SHA1, and RSA-MD5 algorithms.

Configuring Web Services Server-Side

Typically when developers see the three components of WS-Security, some concern is raised about how they are going to programmatically handle the authentication, encryption, and digital signature steps in their specific application.

Fortunately, the way most vendors such as Oracle are implementing WS-Security is as a declarative mechanism that is applied to new and existing Web services. In Oracle JDeveloper 10g Release 10.1.3, for example, you simply right-click on a Web service node, select Secure Web Service, and walk through a simple wizard. Figure 1 is a screen shot of what the basic tooling for WS-Security looks like in Oracle JDeveloper.

figure 1
Figure 1: Securing a Web service with Oracle JDeveloper 10g Release 10.1.3

To provide a simple use case of WS-Security in action, I take the authentication properties provided in Figure 1—username, password authentication token, and nothing else—and apply them to the HRService Web service with the getEmpSalary method.

After I click on OK in the security wizard, the Oracle-specific descriptor file oracle-webservices.xml in Listing 1 is generated (shown with the namespace definitions removed to minimize space). Note that the WS-Security runtime capabilities are enabled with the <runtime> element and the requirement on the server to authenticate with username and password is defined by the <verify-username-token> element.

Code Listing 1: Server configuration for WS-Security in oracle-webservices.xml. 

  <webservice-description name="HRService">
    <port-component name="HRServicePort">
      <runtime enabled="security">
            <verify-username-token password-type="Plain Text"
        <operation name="getEmpSalary"

Once this configuration is deployed in a normal Web service ear file, the management configuration file on the Oracle Application Server runtime side, wsmgmt .xml, is updated with this information. I illustrated this process diagrammatically in last month's column on Web services management. After deployment, the Web service is ready to be tested with a WS-Security username password token.

Configuring Web Service Clients

The next step is to determine how to get the username and password WS-Security token into SOAP messages from a Web service client. Typically, Web service toolkits provide either an API or a declarative mechanism to do this.

figure 1
Web services security with message-level security

Because of the declarative nature of the WS-Security implementation provided by Oracle Application Server, it is important to realize that just as on the server side, where there is a configuration file defining the WS-Security characteristics, a mirror image is required on the client side, so that the Web services client-side runtime can determine the appropriate security settings to apply to the outbound requests and inbound response messages.

To configure this information, Oracle JDeveloper provides a mirror image of the wizard shown in Figure 1 for the Web service client side. The primary difference between the two wizards is that the client wizard provides the ability to capture a username and a password whereas the server wizard does not. Listing 2 provides the generated client-side configuration. Alternatively, because many developers will be loath to embed such information in configuration files (although it is useful for testing), Oracle Application Server provides a simple client API for programmatically setting username and password tokens in Web services clients.

When I run the generated client, the message in Listing 3 is generated, containing—besides the request for the employee salary—the username and the password token carried in the header and the WS-Security references to supporting standard schemas preceded with the standard WS-Security wsse namespace prefix.


Next Steps

 READ past Mike Lehmann articles

As with many other WS-* standards, there is often a concern with WS-Security about interoperability in a heterogeneous environment. In my example, I chose the simplest-possible scenario, but in real life, with more-complex authentication tokens, encryption, and digital signatures, interoperability soon becomes paramount.

The industry is well aware of the issue, and company-neutral forums such as the Web Services Interoperability Organization (WS-I) have begun work, participated in by major vendors including Oracle, to ensure that the WS-Security implementations of Oracle, IBM, Microsoft, Sun, and BEA are interoperable.

What will emerge from this effort is a profile of, or a set of recommended best practices, for how to use WS-Security, called the Basic Security Profile. It will complement the other key interoperability profile released by WS-I, Basic Profile 1.1, which focuses on best practices with SOAP, UDDI, and WSDL.

Stay tuned: in the next issue I'll discuss X.509 certificates, digital signatures, and encryption with WS-Security.

Send us your comments