Setting Up Mutual SSL in WSO2 ESB - Enable only for selected proxy services

This Blog post is an updated version of Asela's Blog 

I am using same environment described in my previous blog for this tutorial

Configure WSO2 ESB Server 

1) Edit https transportReceiver in axis2.xml, which is located in /repository/conf/axis2/ folder and Add SSLVerifyClient to optional as follows.

2) Restart ESB Server.

Note: This will make Mutual SSL optional for proxy services exposed on https transport.

Now you will able to Invoke Test Proxy without SSL KeyStore property in SOAP UI. To verify this remove value of SSL KeyStore and Invoke Request 1 Again.

Enable Mutual SSL for Test Proxy

1) Create a ESB XML local entry called MutualSSLPolicy.xml with following content.

2) Add following parameters to Test Proxy. 


( Add these parameters to proxy services you want to enable mutual authentication. )'

3) Final Test proxy will look like this

Testing With SOAP UI 

1) Try Request 1 without SSL KeyStore parameter. Request Fails with SOAP Fault

2) Now try with SSL KeyStore Parameter, Now you will able to invoke Test Proxy Service.

Setting Up Mutual SSL in WSO2 ESB and Testing Using SOAP UI

This Blog post is an updated version of Asela's Blog 

Exchanging Certificates with Client and Server. 

First step is to create Client Key Store and Client Trust Store. Here I am using Java Keytool, which can be found in JDK bin directory.

1) Create Client ( let's call wso2client ) Key Store (wso2clientkeystore.jks)

keytool -genkey -keyalg RSA -keystore wso2clientkeystore.jks  -alias wso2client -dname "CN=wso2client" -validity 3650 -keysize 2048

Provide Store password and Key password.

2) Create Client Certificates. 

keytool -export -keyalg RSA -keystore wso2clientkeystore.jks -alias wso2client  -file wso2client.cert

3) Create Client Trust Store (wso2clientTrustStore.jks)

keytool -import -file wso2client.cert -alias wso2client -keystore wso2clientTrustStore.jks

Provide Trust store password.

4) Export ESB Server Certificate

keytool -export -keyalg RSA -keystore /repository/resources/security/wso2carbon.jks -alias wso2carbon -file wso2carbon.cert

Provide wso2carbon store password "wso2carbon"

5) Import Client Certificate wso2client.cert to WSO2 ESB client-trustStore.jks

keytool -import -file wso2client.cert -alias wso2client -keystore /repository/resources/security/client-truststore.jks

Provide wso2carbon store password "wso2carbon"

6) Import ESB Server Certificate wso2carbon.cert to client-trust store 

keytool -import -file wso2carbon.cert -alias wso2carbon -keystore wso2clientTrustStore.jks

Configure WSO2 ESB Server 

1) Edit https transportReceiver in axis2.xml, which is located in /repository/conf/axis2/ folder and Add SSLVerifyClient to require as follows.

2) Restart ESB Server.

Note: This will Enable Mutual SSL for Proxies on https transport in ESB.

Create Test Proxy

Create a test proxy with Following Content

Testing Test Proxy Using SOAP UI

1) Open SOAP UI and create a SOAP UI project using Test Proxy WSDL. ( https://localhost:9443/services/Test?wsdl )

2) Try to Invoke Test Proxy with default configuration.

As shown bellow, it will fail with javax.net.SSLHandshakeException. This is because Soap UI doesn't have wso2client key store and trust store.

3) Let's Add Key store and Trust Store to Project.  Open Test Project Properties. -> WS-Security Configuration -> Key Store -> Add Key Store as shown in following picture. -> Select wso2clientkeystore.jks

4) Enter store password for wso2clientkeystore.jks

5) Similarly add Client Trust store to SOAP UI ( An optional step for this tutorial )

6) Select SSL Keystore to wso2clientkeystore.jks.

7) Invoke Request 1 again with SSL configuration.

Now you will be able to invoke Test proxy service with Mutual SSL enabled.

In Next blog, I will discuss how to Enable Mutual SSL only for One proxy.

ESB: Invoking secured backend - Part 3 - Username Token with BasicAuth

This post shows, how to invoke an UsernameToken secured backend ( Hosted in WSO2 AS ), using basic auth. For this we use POXSecurityHandler, (Which comes default with WSO2 Products) to convert the HTTP basic auth information into wsse:UsernameToken.

Setting up environment : 

Setup both WSO2 AS and WSO2 ESB as mentioned in previous post.


ESB Proxy

• Create a proxy called EchoUTBasicProxy with following content. 

Testing Scenario

• Enable Soap tracer on WSO2 AS.
• Enable wire log in WSO2 ESB.
• Invoke EchoUTBasicProxy  using SOAP UI. 

You can see, there is no username token in incoming message to backend. Instead you see basic auth header in outgoing message to backend from ESB.

ESB: Invoking secured backend - Part 2 - Username Token - Dynamic username

My previous post shows how to invoke an username token secured backend using an ESB proxy. But we used static value for the username ( tom ), which is hard coded in the policy file. So each request authenticated as tom at the backend service.

But some may wants to access backend service as different users. This post discusses how you can extend it to support dynamic user name in policy file.


Setting up environment : 

Setup both WSO2 AS and WSO2 ESB as mentioned in previous post. 


ClassMediator (ESB)

• In this scenario, we set username as a property in the ESB proxy. 
• To pass username into RampartConfiguration, we use custom class mediator called, SetUserMediator.
• This custom mediator, adds username into rampartConfigCallbackProperties map and set the map into Axis2MessageContext. So later we can access these properties from Rampart ConfigCallbackHandlers. 
• We have to use customMediator, since we can't set a Map using standard ESB mediators.  
• ( Maven Project is located here. )

Rampart ConfigCallbackHandler (ESB)

• Similar to PasswordCallback handler, Rampart provides Configuration Callback handler to dynamically load Rampart configuaraion to runtime. We use this to set username dynamically. 
• ( Maven Project is located here. )

Policy for UsernameToken  ( ESB )

• Create an ESB in-line xml local entry called "UTOverTransportDynamic.xml" with following content. 

Proxy Service (ESB)

• Create a proxy called EchoUTDynamicProxy with following content. 

Testing Scenario

• Enable Soap tracer on WSO2 AS.
• Invoke EchoUTDynamicProxy  using SOAP UI. 

You can see Username token in request message as follows.

ESB: Invoking secured backend - Part 1 - Username Token

Scenario 

1. Backend service is secured using Username token. 
2. Client invokes ESB proxy using http. ( no security between client and ESB) 
3. At the ESB, proxy adds username token to outgoing message and invokes secured backend.
4. ESB sends back echo service's response back to client. 

Setting up environment 

Backend ( WSO2 Application server 5.2.1)

1. Start WSO2 AS 5.2.1 using ( Unix: sh wso2server.sh / Windows: wso2server.bat ) 
2. Log in to management console. ( https://localhost:9443/carbon/ ) 
3. Create two user called tom and bom
• Goto Configure -> Users and Roles -> Users
• Create an user called tom with password "tompass". 
• Create another user called bob with password "bobpass"
• Assign both users to "admin" role.
4. Secure Echo service with Username token. 
• Goto Main -> Services -> List 
• Click on "echo" service. This will open up "Service Dashboard (echo)" page.
• Under "Quality of Service Configuration", Select "security".
• In "Security for the service" page, Select Enable security.
• Under Security scenarios, select "Username token"  ( First security policy) and click next. 
• In next page, select "admin" under user group. 
• Click Finish. 

ESB ( WSO2 ESB 4.8.1 )

1. Start WSO2 ESB with port offset =1 ( Unix: sh wso2server.sh -DportOffset=1 / Windows: wso2server.bat --DportOffset=1) 

Rampart configuration for UsernameToken  ( ESB )

• Create an ESB in-line xml local entry called "UTOverTransport.xml" with following content. 

Password callback Implementation

• Create a jar with following class, and drop it to /repository/components/lib/
• Then restart ESB server. 
• ( Maven Project is located here. )

Some useful References on Rampart password callback handler:  

1. http://wso2.com/library/3733/
2. http://wso2.com/library/240/

ESB Proxy

• Create a proxy called EchoUTProxy with following content. 

Testing Scenario

• Enable Soap tracer on WSO2 AS.
• Invoke EchoUTProxy  using SOAP UI. 

You can see Username token in request message as follows. 

Invoking Secured ESB Proxy Service Using SOAP UI

In this post, I am showing how you can invoked a secured proxy service, using SOAP UI tool.

Here I am using WSO2 ESB 4.6 and SOAP UI 4.5.1for this example.

Step 1: Create a proxy service 

Let's create a ESB proxy service first. Here I have created a proxy service to invoke echo service that comes with WSO2 ESB.


First let's try to invoke our proxy service without security. Here I am using tryIt tool. Click "Try this service" link in the EchoProxy row in the Deployed service. Use following sample request to invoke the service.

Request and Response of the EchoProxy

Step 2: Creating SOAP UI Project and Testing service.

• Open SOAP UI tool and Create an new soapUI Project. ( File -> New soapUI project )
• In the new soapUI project wizard, give the our EchoProxy service's wsdl url. (ex: http://localhost:8280/services/EchoProxy?wsdl ) 
• Give the project name as "EchoProxy". Fill other fields as necessary.
• Then Click Ok.
• Then try to invoke our proxy service using soapUI as well.

 

Step 3: Securing the proxy service

Let's secure our proxy service now.

• Go to service list (see 1 in Figure 1)
• In Service list view, click on unsecured link (see 2 in Figure 1) in the EchoProxy row to secure the proxy.

Figure 1

• In next Window, select "yes" to enable security for EchoProxy  ( Figure 2)

Figure 2

In this example, I am going to secure proxy service using security scenario 5 - "Sign and Encrypt - X509 Authentication"

• So select security scenario 5 under Advanced Scenarios ( Figure 3 ) and click next.

Figure 3

• For simplicity of this post, I am going to use wso2carbon.jks as Trusted Key Stores. So in next window ( Figure 4) Select wso2carbon.jks as Trusted Key Stores and click Finish. 

Figure 4

• Now we have secured proxy our service.

Figure 5

Note: If you try to invoke our proxy service now using tryit or soapUI tool, it will fails. In next step let's try to invoke it by adding Sign and Encrypt - X509 Authentication to the soapUI request.

Step 4: Adding Sign and Encrypt - X509 Authentication to soapUI request.

Step 4.1 - Setting up ws-security configuration to soapUI project.

• Right Click on your soapUI project (EchoProxy) and select "Show Project view" 
• In the opened sub window, click "ws-security configuration" tab.
• Now let's add a KeyStore first. For Simplicity I am adding wso2carbon.jks here again. You can find it from $ESB_HOME/repository/resources/security/ . But you can use your own valid keystore here.

Step 4.2 - Adding KeyStore

• Go to the keystores tab ( see figure 6)
• Add a keystore by clicking the button which is shown using arrow 1 in figure 6.
• Select key store file. (ex: $ESB_HOME/repository/resources/security/wso2carbon.jks) 
• It asks the password of the keystore. Give it. ( for wso2carbon.jks password is wso2carbon )
• Then fill the Default Alias and Alias password fields. I am using wso2carbon for both fields. 

Figure 6

Step 4.3 - Setting up Out going Security Configuration.

• Go to outgoing ws-security configuration tab.
• Click button 1 ( Figure 7 ) to add outgoing security configuration. 
• Give an unique name for the configuration. let's say it as EchoProxy-soap11SecuredRequest
• Then fill the default Alias/Default Password fields. Use wso2carbon for both fields.
• Then tick the must understand check box button.

Figure 7

• Now Let's add wss entries. Click button 1 ( Figure 8) to add new wss entry.
• First add Timestamp entry.
• In the option window, fill the "time to live" field (ex: 300000)

Figure 8

• Then let's add signature entry similar to timestamp.
• Fill the options fields as given in figure 9.  
• Keystore is wso2carbon.jks;
• both alias and password is wso2carbon;
• Key Identifier type is X509;
• tick the use single certificate check box;
• Leave other fields as default;
• Then add a new part; which describes what we are going to sign. Since we are signing body of the soap11 request, let's add new part like this.
• ID=Body
• Name=Body
• Namespace=http://schemas.xmlsoap.org/soap/envelope/
• Encode=content

Figure 9

• Since our proxy service is secured using sign and encryption, we need to add encryption as well. So add encryption entry similar to Timestamp and signature fields.
• Fill the option fields as given in figure 10. 
• Keystore is wso2carbon.jks;
• both alias and password is wso2carbon;
• Key Identifier type is X509;
• tick the create encryption key check box;
• Leave other fields as default;
• Then add a new part; which describes what we are going to encrypt. Since we are encrypting  body of the soap11 request, let's add new part like this.
• ID=Body
• Name=Body
• Namespace=http://schemas.xmlsoap.org/soap/envelope/
• Encode=content

Figure 10

Now we are done with configuring out going message.

[Important] Please note that order of the ws entries matters when we are invoking the secured service. So always add those three one after the other. As an exercise try to change order of timestamp, signature and encryption and try to invoke the service.

Step 4.4 - Setting up Incoming Security Configuration.

• Go to incoming ws-security configuration tab.
• Similar to outgoing ws-security configuration first add incoming security configuration profile. Name it as EchoProxy-securedResponse
• Fill the other fields as showing in figure 11.
• Decrypt Keystore=wso2carbon.jks
• Signature Keystore=wso2carbon.jks
• password=wso2carbon

Figure 11

 Step 5 - Invoking secured Proxy service.

 

• Open soap11 request. ( If you have already opened it, you may have to close and re-open it, to apply project changes which you did in step 4)
• Click on button aut ( arrow 2 in Figure 12 ). It contains authentication related details.
• Select outgoing wss that we created in step 4 from arrow 3.
• Select incoming wss that we created in step 5 from arrow 4.
• Then Invoke the request 1 by clicking green play arrow.

Figure 12

•  you can view decrypted response from response window.  it is Done :)

[Important] Troubleshooting.

• If you are running your system on a fresh JVM, you may face "Illegal key size or default parameters" [1] or similar problems since we are using encryption algorithms in this sample. To fix this you have to patch the JVM by applying "the Java Cryptography Extension (JCE), Unlimited Strength Jurisdiction Policy".
• You can download it from http://www.oracle.com/technetwork/java/javase/downloads/

 

[1]

.....

Caused by: org.apache.xml.security.encryption.XMLEncryptionException: Illegal key size or default parameters
Original Exception was java.security.InvalidKeyException: Illegal key size or default parameters
    at org.apache.xml.security.encryption.XMLCipher.encryptData(XMLCipher.java:1140)
    at org.apache.xml.security.encryption.XMLCipher.encryptData(XMLCipher.java:1081)
    at org.apache.xml.security.encryption.XMLCipher.encryptElementContent(XMLCipher.java:855)
    at org.apache.xml.security.encryption.XMLCipher.doFinal(XMLCipher.java:985)
    at org.apache.ws.security.message.WSSecEncrypt.doEncryption(WSSecEncrypt.java:602)
    ... 24 more
Caused by: java.security.InvalidKeyException: Illegal key size or default parameters
    at javax.crypto.Cipher.checkCryptoPerm(Cipher.java:1011)
    at javax.crypto.Cipher.implInit(Cipher.java:786)
    at javax.crypto.Cipher.chooseProvider(Cipher.java:849)
    at javax.crypto.Cipher.init(Cipher.java:1213)
    at javax.crypto.Cipher.init(Cipher.java:1153)
    at org.apache.xml.security.encryption.XMLCipher.encryptData(XMLCipher.java:1137)
    ... 28 more