+

Search Tips   |   Advanced Search

Web Services Security API programming model

The application server programming model provides Web Services Security programming application programming interfaces (WSS API) for securing SOAP messages.

The API programming model is an interface-based programming model based on Web Services Security Version 1.1 standards, but the design also includes support for Web Services Security Version 1.0 for securing SOAP messages. 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 Services 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.

The configuration model for web services has also been redesigned from a deployment descriptor model to a policy set model. Web Services Security can be enabled by either using a policy set configured using the administrative console, or 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 Services Security run time. 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, 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.

We can still use our existing JAX-RPC applications with Web Services Security; however, those applications cannot take advantage of the Web Services Security Version 1.1 functions, such as configuring the security policy using a policy set, OM filter performance improvements, WSS API, Web Services Secure Conversation (WS-SecureConversation), Kerberos token and the associated SHA-1 key for message protection and identity propagation, and Web Services Trust (WS-Trust) features.

In order to take advantage of the Web Services Security Version 1.1 functions, we must rewrite an existing JAX-RPC application as 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.

For example, when using JAX-WS, the improved design of the pluggable token framework allows the same security implementation to be used for both the API and policy sets. The framework uses the JAAS Login Module and JAAS Callback Handler for token creation and token validation.

The following diagrams illustrate differences between the programming models.

Figure 1. Pluggable token architecture using the JAX-WS programming model

Figure 2. Pluggable token architecture using the JAX-RPC programming model


What is supported when using the WSS APIs

The WSS API can only be used on the client. Use the Java SE 6 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:

The default values for the WSS API are predefined and are part of the Web Services Security run time. 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

The WSS API provided with the application server does not support the following function:


WS-Trust and WS-SecureConversation scenarios

There are several ways to secure the WS-Trust SOAP messages:

An application would use the WSS API to acquire a security context token for programmatic API-based secure conversation. The WAS trust service provides an application the ability to request a security token for access to a service. The scope and focus of the trust service is only for a WAS 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. We 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 using the WSS API. Then the Derived Key Token can be used for signature and encryption.

See the examples that describe the following security context token usage scenarios:

There are two conditions when using the WSS API to secure the SOAP message with Web Services Security:

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


Web services client security context

When the JAX-WS client invokes web services, the current security context that is constructed by the security handler is stored in the RequestContext object. By default, the security context in the JAX-WS web services client runtime environment is reconstructed for the next web services request invocation. We can preserve the security context for subsequent web services invocations. An example of this is a scenario where the security policy requires the client to send a username security token with the user name and password. When the client sends the first request to invoke the service, we are prompted to enter the required user name and password. The user name and password is saved in a Username SecurityToken token in a Subject in the security context. To avoid being prompted to enter the same user name and password again in subsequent request invocations, we can preserve the security context. There are two methods to preserve the security context: 1) configure the client run time to automatically preserve the client security context for subsequent request invocations; or 2) preserve the security context manually.

To configure the JAX-WS client run time environment to automatically preserve the security context, set the Java system property com.ibm.websphere.wssecurity.context.management to true. When this system property is true, the JAX-WS client run time copies the security context constructed by the security handler to the RequestContext automatically, and the context is used for subsequent request invocations.

To manually preserve the security context, use the following sample code: 

// First request
Service svc = Service.create(...);
svc.addPort(...);
Dispatch<String> dispatch = svc.createDispatch(...);
ap<String, Object> requestContext = dispatch.getRequestContext();
String response = dispatch.invoke(body.toString());

Object securityContext = requestContext.get(com.ibm.wsspi.websvcs.Constants.WEBSPHERE_SECURITY_CONTEXT);

// Subsequent request

Dispatch<String> dispatch = svc.createDispatch(...);
ap<String, Object> requestContext = dispatch.getRequestContext();
Object securityContext = requestContext.put(com.ibm.wsspi.websvcs.Constants.WEBSPHERE_SECURITY_CONTEXT, securityContext);

  • Web Services Security APIs