Use Case

In this post, I show how to add SOAP headers to SOAP request/response. If you have Code First Webservice OR WSDL Contract based WebService, you will be responding to your client requests with a SOAP response. In my case, it was a WS-Trust Security Token Web Service and the endpoint was correctly responding with a WS-Trust Response. This SOAP response will include SAMLv1.1 OR SAMLv2.0 token. Now consumer of this web service can either trust the server response or also validate the response for few things like time validity, signature validity, and even security header validity.

If you are supporting Transport Binding on this Web Service endpoint, it will be straight forward. Web Service response will have security headers

But as per my use case, if you are merely using UsernameToken Binding , Web Service response will not include security headers, especially if you are using Apache CXF libraries, these libraries will not always add security headers.

Likewise, if a consumer needs security headers for validation purposes, how do you add these security headers in response from your server endpoint?

Solution

In this particular case, the Web Service response needed Security header with timestamp only.

What is the security header and why Timestamp is required?

In a SOAP request or response, you will need Security header element based on security policy that Web Service will be using. This header in a request will look like below:

<wsse:Security soapenv:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
     <wsu:Timestamp wsu:Id="TS-D3788B6EB508E3A553155173495342917">
         <wsu:Created>2019-03-04T21:29:13.429Z</wsu:Created>
         <wsu:Expires>2019-03-04T21:30:13.429Z</wsu:Expires>
     </wsu:Timestamp>
     <wsse:UsernameToken wsu:Id="UsernameToken-6CBAAFA3A8815F71FC15511581437664">
        <wsse:Username>john.doe@betterjavacode.com</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
     </wsse:UsernameToken>
</wsse:Security>

Once a Web Service endpoint receives this request, it will validate the username and password and will verify if timestamp validity is accurate. On successful validation, Web Service will generate a response that will also include Security header with Timestamp. Consumer will validate that timestamp. Having a timestamp in SOAP header minimizes the risk of Replay attack as in an attacker can’t either use the SOAP response after Expiration time or even can’t send the same request after Expiration time.

How do you add this security header of timestamp if using Apache CXF libraries?

Apache CXF libraries offer few ways to achieve this:

1. JAX-WS standard way is to write a SOAP handler that will add headers to the SOAP message. To simplify this, you will have to register the SOAP handler on the client or server-side.
2. JAX-WS offers another way through annotation @WebParam(header = true, mode = Mode.OUT).
3. wsdl first way wherein your WSDL operation you specify SOAPHeader as part of your SOAP binding.
4. CXF offers its own way to add these headers. In this post, I will show how you can leverage CXF libraries to add these headers.

How to add Security headers using CXF libraries?

Assumption is that you have used apache CXF libraries to build Web Service endpoint. JAX-WS offers a WebServiceContext which makes a Web Service endpoint to access message context. This message context can help to retrieve details for username, password, and other security headers from the request.

Same way, this message context can be used to grab a list of headers List<org.apache.cxf.headers.Header> . We will create our Soap header for security element and then add this header in the list of headers. The code for this will look like below:

SOAPFactory soapFactory = SOAPFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);

SOAPElement securityElement = soapFactory.createElement("Security",
        "wsse", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd");
SOAPElement timestampElement = soapFactory.createElement("Timestamp",
        "wsu", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd");
timestampElement.setAttribute(WSTrustConstants.WSU_ID, "_0");

String created = getCurrentDateTime();
String expires = getCurrentDateTimePlusDelay(300L);
SOAPElement createdSOAPElement = soapFactory.createElement("Created",
        "wsu", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd");
createdSOAPElement.addTextNode(created);
SOAPElement expiresSOAPElement = soapFactory.createElement("Expires",
        "wsu", "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd");
expiresSOAPElement.addTextNode(expires);

timestampElement.addChildElement(createdSOAPElement);
timestampElement.addChildElement(expiresSOAPElement);
securityElement.addChildElement(timestampElement);
SoapHeader soapHeader = new SoapHeader(securityElement.getElementQName(), securityElement);

List<Header> headers = new ArrayList<>();
headers.add(soapHeader);
webServiceContext.getMessageContext().put(Header.HEADER_LIST, headers); 

Conclusion

In this post, I showed how we can leverage Apache CXF libraries to add SOAP headers in a web service response. Similarly, the same libraries can be used to add these headers to the request.

References

1. Apache CXF Libraries – Apache CXF
2. Adding SOAP header – Adding SOAP header
3. Interceptors – interceptors