Web services security API programming model

The WebSphere Application Server programming model provides Web Services Security programming application programming interfaces (WSS API) for securing SOAP message.

The API programming model design has been redesigned. The new design is an interface-based programming model and is based on Web Services Security Version 1.1 standards but the design also includes support for Web Services Security Version 1.0 for securing the SOAP message. The WSS API programming model implementation is a simplified version, which is based on an early draft proposal of JSR-183, which is the JSR for defining Java API binding for Web Service Security. By design, because the application code is programmed to the interface, any application code that is programmed with the open source implementation should be able to run on the WebSphere Application Server with minimal changes or no changes at all.

In addition to the two different Web services security runtimes, other differences between WebSphere Application Server Version 6.1 and the Feature Pack for Web Services include:

The configuration model for Web services has also been redesigned from a deployment descriptor model to a policy set model. Web Service Security can be enabled by either using a policy set that is configured by using the administrative console, or by using the WSS API for configuration. The functions provided by the policy set configurations are the same as the functions supported by the WSS API for the Web Service Security runtime. However, the security policy that is defined using policy sets has a higher priority over the WSS API. When the WSS API and the policy set are both used in the application, the default behavior is for the security policy from the policy set to be enforced and the WSS API to be ignored. To use the WSS API in the application, you must make sure that there is no policy set attached to the application or to the application resources, or make sure there is no security policy in the attached policy set.

Existing JAX-RPC applications with Web Service Security are still being supported in the Version 6.1 runtime. However, those applications cannot take advantage of the new features that are added in the Feature Pack for Web Services, such as the new Web Services Security Version 1.1 functions, configuring the security policy using a policy set, OM filter performance improvements, WSS API, Web Services Secure Conversation (WS-SecureConversation), and Web Services Trust (WS-Trust) features.

For migration, you would explicitly have to do a code migration from a JAX-RPC application to a JAX-WS application, manually re-configure the security constraints to a policy set, and perform code migration of the DOM-based SPIs to the OM-based SPIs in the Feature Pack for Web Services. However, because both Version 6.1 and the Feature Pack for Web Services version are provided simultaneously, no migration is required at this time.

What is supported when using the WSS APIs

The WSS API can only be used on the client. You can use the J2SE client, the J2EE Application client, or a server client (a service provider acting as client) using the API to secure SOAP message with message-level security.

You should have Web Services Security (WSS) knowledge to use the WSS APIs. Before using the WSS API, keep in mind that the WSS API:
  • Are Java-based interfaces.
  • Are implemented by using a factory model (WSSFactory).
  • Supports the WS-Security Version 1.0 and 1.1 standards, which include the Username and X.509 token profiles, Versions 1.0 and 1.1.
  • Are very XML centric.
  • Include an object-oriented design which simplifies the APIs.
  • Are task oriented and allow common usage scenarios, such as: signing the body and encrypting the SOAP message body content.
  • Are flexible and extensible, and they let you to extend the token type support.
  • Are based on the provider framework and allow the use of different data models to be used, such as: AXIOM or DOM.
  • Provides application programmer with better control and flexibility in applying WSS in their applications.

The default values for the WSS API are predefined and are part of the Web services security runtime. Default values are provided for:

The signature validation has similar default values as the signature (signing information). Similarly, decryption has similar default values as encryption.

What is not supported when using the WSS APIs

For the IBM WebSphere Application Server Version 6.1 Feature Pack for Web Services, the WSS API provided with WebSphere Application Server, do not support the following function:

Service Programming Interfaces

Similarly, the Web Service Security runtime token generation and token consuming Service Programming Interfaces (SPI) have been redesign so that the same security token interface and JAAS Login Module implementation can be used for both the WSS API and the SPI. The WSS SPI for the service provider extend the security token types and provide keys and deriving keys for signing, signature verification, encryption and decryption.

Due to the differences in the programming model, any WebSphere Application Server or custom SPI implementation from the Web Service Security Version 6.1 runtime is not supported to run on the new Web Service Security runtime with the Feature Pack for Web Services. However, the Web Service Security Version 6.1 runtime is supported simultaneously with the Feature Pack for Web Services, meaning the Version 6.1 SPI implementations are still supported through the original runtime. Before using the new Web Service Security runtime, a code migration would be required of the Version 6.1 DOM-based SPIs to the AXIOM-based SPIs in the Feature Pack for Web Services before the SPI could be used.

WS-Trust and WS-SecureConversation scenarios

There are two ways to secure the WS-Trust SOAP messages. One method is to use the bootstrap policy that is defined in the policy set or another way is using the WSS API. The WSS APIs also support WS-SecureConversation.

An application would use the WSS API to acquire a security context token for programmatic API-based secure conversation. The WebSphere Application Server trust service provides an application the ability to request a security token for access to a service. For the Feature Pack for Web Services, the scope and focus of the trust service is only for a WebSphere Application Server Security Context Token (SCT) for WS-SecureConversation.

The WS-SecureConversation and WS-Trust scenarios focus on the inter-operability functions, such as the configuration and runtime interaction of various components. You would use the WSS API to secure the bootstrap RST and RSTR to acquire the security context token from the trust service. After acquiring the security context token, a Derived Key Token is created by using the WSS API. Then the Derived Key Token can be used for signature and encryption.

There are two conditions when using the WSS API to secure the SOAP message with Web Service Security:
  • Generation of the secure SOAP message, which is in the request generator application code.
  • Consuming of the secured SOAP message, which is in the response consumer application code.

In both cases, a Java exception class com.ibm.websphere.wssecurity.wssapi.WSSException is provided if an error is encountered.




Related concepts
Web services security provides message integrity, confidentiality, and authentication
Related reference
Example: Establishing a security context token to secure a secure conversation
Example: Establishing a security context token to secure reliable messaging
Web services security APIs
Concept topic Concept topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 1:23:07 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=cwbs_wss_api
File name: cwbs_wss_api.html