Hello, all! As promised, here comes my second article in the series of posts on message-based security for web services in webMethods. If you missed the first one, you can check it out here.
In the previous post, we saw a policy that is used to perform open authentication to the server using SOAP header instead of transport header. It was just a different way of presenting credentials on secured endpoints. The request and response messages are still unsecured on the wire. Messages can be exposed to threats such as eavesdropping, message replay, etc.
The WS-Security policy design caters to the securing of the message transmission environment between endpoints. You can use authentication safeguards such as signing and encryption at the individual message level to provide greater data protection than just using similar authorization features in a transport-based security.
In this post, we will focus on the message integrity, which can be achieved using digital signatures. We will be using out of the box policy Username_Signature to implement the same.
This policy uses a Username token to provide client authentication, uses symmetric binding to sign messages to ensure message integrity, and includes a Timestamp token to guard against replay attacks. Because this policy uses symmetric binding, the sender of an outbound message does not need a private key. Instead, the client generates a symmetric key.
- Keystore setup with valid keys.
- Keystore alias creation on the Integration Server.
- Certificates configuration on the Integration Server.
You must be wondering why we need a keystore if our Username_Signature policy is going to use Symmetric Binding for signing the SOAP message. Though symmetric binding is used, WS-Security spec says that the generated symmetric key that is used for signing the message should be encrypted and injected into the SOAP header during the message transmission. In order to do this, the public key of the Integration Server should be shared with the client to set up on the consumer side. The client then uses this public key to encrypt the symmetric key and inject into the SOAP header. On the provider side, the integration server uses its private key to decrypt the symmetric key and uses it to verify the signature.
Enough theory. Let’s get started with the implementation.
First, you should be ready with a Keystore with your pair of keys (public and private). If you do not have one, then create a Keystore using Java toolkit. You can refer to this link to learn how to do the same.
Once ready, you have to create Keystore and Truststore Aliases on Integration Server.
- On Integration Server Administration screen, Navigate to Security > Keystore.
- You will see two links: Create Keystore Alias and Create Truststore Alias.
- The integration server used the keys from the configured keystores to perform safeguard activties like signing or decrypting a message, i.e., using private keys. The truststore will be used to perform the counterpart of the previously mentioned safeguards which are verifying or encrypting a message, i.e., using public keys.
- Click on Create Keystore Alias. Fill in the details and click on the Submit button.
- Make sure your custom Keystore alias is created and loaded.
Now that the required configuration is done, let's see the policy enforcement on Webservice.
Policy Enforcement Webservice Provider
- First, we shall create an Endpoint alias for the provider so that all the necessary configuration can be saved at server administration.
- Navigate to Settings > Web Services on Integration server management page.
- Click on Create Web Service Endpoint Alias.
- Fill in details as shown in the screenshot below.
- Notice that we have selected the Keystore Alias and Key Alias that we have created earlier.
Web service providers use this keystore to get the private key that is required to decrypt the symmetric token from inbound SOAP message header. After decrypting, it used this symmetric key to verify the digitally signed SOAP message for its integrity. If the keystore details are not mentioned in the endpoint alias, then Integration server will look for them at the server level. So, make sure you configured server level certificates at Security > Certificates in Integration server administration.
- Click on Save Changes.
- Now, Open your Webservice provider descriptor in Software AG Designer and attach the Username_Signature policy to it. If you are new to this, then refer to the Attaching the Policy section from the previous post.
- We should now bind the provider endpoint alias we created earlier to the web service binder.
- Click on Binders tab. Select the binder and from the Properties section choose the Port alias as the provider endpoint alias.
Policy Enforcement on Web Service Consumer
We shall follow similar steps we took for the implementation of policy on Webservice provider.
- Create an endpoint alias for the consumer on IS.
- Navigate to Settings > Web Services on Integration server administration page.
- Click on Create Web Service Endpoint Alias.
- Fill in details as shown in the screenshot below. Parter’s Certificate is the public key of the server on which the web service provider is hosted. For this demo, you can export the public key certificate from the keystore that you created using Java toolkit. Check this short tutorial to learn more.
- Notice that we have not provided the details of Keystore in the consumer endpoint alias as it is not required (at least for this moment, i.e., for the Username_Signature policy). Only Partner’s Certificate is required to encrypt the symmetric key that is used for signing the SOAP message.
- Click on Save Changes.
- Now, Open your Webservice consumer descriptor in Software AG Designer and attach the Username_Signature policy to it. If you are new to this, then refer to the Attaching the Policy section from the previous post.
- We should now bind the consumer endpoint alias we created earlier to the web service binder.
- Click on Binders tab. Select the binder and from the Properties section choose the Port alias as the consumer endpoint alias.
All the setup is done. Now, just go to the connector service and run it. Provide the required inputs and click OK. You should get the sum of the numbers as the response.
To verify if the policy is being enforced, the SOAP message is being signed and the symmetric key is being encrypted. The only best way is to have a look at the SOAP message itself.
Unfortunately, there is no fair way to have an eye on this on the integration server. Increasing SOAP log levels would help only a little, but it is definitely not a relatively obvious option. So, my favorite in this case is TCPMon utility.
TCPMon is a light-weight request sniffing utility which comes very handy for monitoring the request and response of HTTP transactions. It allows you to enable a proxy port which will accept the original request and forwards it to the originally intended endpoint.
I have launched my TCPMon on port 15555, pointed my consumer endpoint alias to this TCPMon port and re-ran the Webservice connector. Below is how the request and response were captured on the wire.
These long series of tags in the SOAP header are the result of various assertions inside the policy. If zoomed in, it can also be noticed that the digest of the signed message is part of the header, along with the encrypted symmetric key.
With this, I conclude this article. I hope you got some understanding on the second level of security, i.e., signing SOAP messages for their integrity.
You’ve now learned following things today:
- How to Configure Keystores on Integration Server.
- How to set endpoint aliases for provider and consumer with certificate related details.
- How to bind endpoint aliases to Webservice descriptors.
- How to monitor a request-response going out of Webservice connector using TCPMon.
Thank you for reading this post and happy integration!