Our valued colleague Wouter van Wijngaarden wrote a nice blog about setting up a certificate in WSO2 Integrator / WSO2 ESB which covers the topic of securing traffic with SSL. Sometimes though, two-way SSL is required. In that case look no further, this blog has got you covered!
What is two-way SSL?
When connecting to a webpage, say ‘https://yenlo.com’. Your browser will show that the Yenlo website is encrypted and a trusted website. This is due to a ‘trust-chain’, where your browser does not actually trusts Yenlo itself, but it trusts the party that has equipped Yenlo with a certificate. It is all nice and well that you trust us, but in webservices information can flow both ways, so how can Yenlo trust you?
Simple: In ‘one-way or just plain ‘SSL’ you trust the certificate that we provide and in two-way SSL you also provide US with a certificate during the SSL handshake to identify yourself.
1: One-way SSL, everyone can access the trusted server
2: Two-way SSL, only trusted parties can access the trusted server
Setting up two-way SSL
Create a keystore containing your client certificate (including a private key!) see this blog for details on a proper setup or use a third party tool like ‘KeyStore Explorer’.
In the axis2.xml configuration (https://j8a3m7f3.rocketcdn.me/ESB_HOME/conf/axis2/axis2.xml) within the
<transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender">
Add the following configuration:
KeyStore refers to the store containing your client certificate and the
TrustStore to the store containing a list of certificates and/or certificate chains you trust.
That is it! Restart your ESB so it will load the new configuration and you are good to go!
If you still receive an error after setting up the things above, it can be difficult to find the problem. Carefully examine your configuration, to help with this look at the following checklist:
- Does the keystore have a complete chain or only the client certificate (some servers only accept the certificate if the chain is complete)
- Does the keystore include a private key?
- Are you 100% sure the passwords match?
- Does your endpoint exactly match the hostname + port in the configuration? (so if your endpoint is https://yenlo.com:443/test , the hostname in the config should be ‘yenlo.com:443’ not ‘yenlo.com’)
- Did you give the server a reboot? Otherwise it will not pick up the changes in the axis2 configuration.
- Does the keystore contain only a single client-certificate (e.g. a certificate including private key)
So, if you have any questions about this blog, leave a comment in the comments section below. View also our webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.