How to invoke secured backend service using WSO2 Enterprise Integrator

WSO2 Enterprise Integrator (WSO2 EI) supports 16 predefined, commonly-used security scenarios. Understanding the exact security requirements is the first step in planning to secure Web services. Consider what security aspects are important to your service, whether it is integrity, confidentiality, or both.

👉 Let’s take the below use case.

Use case: There is a backend service that is secured by WS-Security Policy.Policy contains both signature and encryption and client needs to provide X509 certificate for authentication.Further we need to invoke this backend service through the Enterprise Integrator.

So WSO2 ESB proxy service must be authenticated to the backend service to achieve this requirement because our initial client(Postman or SoapUI) doesn’t provide any certificate when invoking the ESB proxy service.

In order to fulfill the above requirement we have to apply the Sign and Encrypt — X509 Authentication security scenario. In one of my previous blogs, I discussed another security scenario of Kerberos Token-based Security, and please follow the below article to find more information.

Securing WSO2 Services with Kerberos Token-based Security

🔽 In this post, I am going to explain and share each and every step that you need to implement the solution for the above use case. I am using Enterprise Integrator 6.6.0 and the below configurations are also supported for the Micro Integrator 1.2.0. Further, we are going to use another WSO2 EI server as the backend server.

Let’s start. 😀

Here I’m attaching an image that shows how the message mediation happens.

👉 Let’s understand the above message flow:

At the Initiator’s side

• Client should sign the messages using the client’s private key
• Client should encrypt the message using the server’s(recipient) public key
• Client should have the X.509 certificates

At the recipient’s side

• Messages are decrypted using the recipient’s private key
• Message signatures are validated using the sender’s public key

So we need to create two separate keystores for the Initiator and Recipient and each party should have the public certificate of the other party in its key store. Certificate alias and private key password of the client’s certificate are used to authenticate the client. Clients should provide that information in order to sign the message.

👉 To implement the use case we need to perform the following steps:

1. Create key stores and exchange the public certificates.
2. Create security policies and configure them.
3. Configure EI server (FrontEnd).
4. Configure the Backend Server.

✔️ Create key stores and exchange the public certificates

You can follow the below blog post to understand how to create new Keystores with new (self-signed) certificates, export and import their public certificates among them.

Creating New Keystores for WSO2 products

You can find the created keystores in this URL and please note that certificates may be expired when you are trying out. You can either create new keystores from the beginning by following the steps in the above blog or extend the validity period of the certificates.

✔️ Create security policies and configure

As I mentioned previously, we are going to use another EI server as a backend server. Then we have to create a proxy as a backend service and need to secure it. So we are going to follow the same approach to secure the backend service using a WS policy file. Hence we have to create two separate policy files.

ESB uses Apache rampart as the WS-Security implementation. Rampart has, its own way to define the key store and key data using a configuration called rampart configuration. We can add this rampart configuration to the security policy as an assertion. Please find more details about rampart configurations from here.

FrontEnd EI proxy’s policy file:

1. Private key that is going to sign the message. It is the alias name of the private key of the newkeystore1.jks file

<ramp:userCertAlias>wso2carbon1</ramp:userCertAlias>

2. Public key (certificate) that is going to encrypt the message. It is the certificate alias name of the public certificate of the Backend service. That also must be contained in the newkeystore1.jks.

<ramp:encryptionUser>backend</ramp:encryptionUser>

3. Create a password call back class to inject the private key password and you can find the relevant class mediator file from this URL.

<ramp:passwordCallbackClass>org.wso2.samples.pwcb.PWCBHandler</ramp:passwordCallbackClass>

4. Define the Signature and Encryption crypto configurations

<ramp:signatureCrypto>
                   <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp: property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.file">/home/asara/WSO2/EISetup/newkeystore1.jks</ramp:property> 
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">wso2carbon</ramp:property>
                  </ramp:crypto>
</ramp:signatureCrypto>

<ramp:encryptionCypto>
                  <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.file">/home/asara/WSO2/EISetup/newkeystore1.jks</ramp:property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">wso2carbon</ramp:property>
               </ramp:crypto>
</ramp:encryptionCypto>

You can find the complete policy file from here.

BackEnd EI proxy’s policy file:

1. Private key that is going to sign the message. It is the alias name of the private key of the newkeystore.jks file

<ramp:userCertAlias>wso2carbon</ramp:userCertAlias>

2. Public key (certificate) that is going to encrypt the message. It is the certificate alias name of the public certificate of the FrontEnd EI server. That also must be contained in the newkeystore.jks.

<ramp:encryptionUser>frontend</ramp:encryptionUser>

3. Create a password call back class to inject the private key password and you can find the relevant class mediator file from this URL.

<ramp:passwordCallbackClass>org.wso2.samples.pwcb.PWCBHandler</ramp:passwordCallbackClass>

4. Define the Signature and Encryption crypto configurations

<ramp:signatureCrypto>
                   <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp: property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.file">/home/asara/WSO2/EISetup/newkeystore.jks</ramp:property> 
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">wso2carbon</ramp:property>
                  </ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
                  <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.file">/home/asara/WSO2/EISetup/newkeystore.jks</ramp:property>
                  <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">wso2carbon</ramp:property>
               </ramp:crypto>
</ramp:encryptionCypto>

You can find the complete policy file from here.

ℹ️ Further, I’m sharing the maven project of password call back handler and you can download it from this URL.

✔️ Configure EI server (FrontEnd)

step 1: Download and Copy org.wso2.samples.pwcb-1.0.0.jar to the <EI1_HOME>/lib directory.

step 2: Update the Keystore(newkeystore1.jks) path in the FrontEndPolicy.xml policy file.

step 3: Start the EI server

step 4: Add the FrontEndPolicy.xml policy file to the registry under the gov:/FrondEndServicePolicies folder like below.

step 5: Create an endpoint(EndpointBackend) by adding the policy file

<endpoint xmlns="http://ws.apache.org/ns/synapse" name="EndpointBackend">
   <address uri="https://localhost:8244/services/BackendService">
      <suspendOnFailure>
         <progressionFactor>1.0</progressionFactor>
      </suspendOnFailure>
      <markForSuspension>
         <retriesBeforeSuspension>0</retriesBeforeSuspension>
         <retryDelay>0</retryDelay>
      </markForSuspension>
      <enableSec policy="gov:/FrondEndServicePolicies/FrontEndPolicy.xml"/>
   </address>
</endpoint>

Please change the backend service URI according to your environment.

step 6: Create a Proxy service

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="TestProxy"
       startOnLoad="true"
       statistics="disable"
       trace="disable"
       transports="http,https">
   <target endpoint="EndpointBackend">
      <outSequence>
         <send/>
      </outSequence>
   </target>
   <description/>
</proxy>

That’s all for configuring the EI server (FrontEnd) 🤓

✔️ Configure Backend Server

• Take another WSO2EI-6.6.0 pack and offset the port by one in carbon.xml which is inside the <EI_HOME>/conf folder. So the new URL of the backend server’s management console will be https://localhost:9444/carbon

<Ports>
 <!-- Ports offset. This entry will set the value of the ports defined below to the define value + Offset-->
    <Offset>1</Offset>

step 1: Download and Copy org.wso2.samples.pwcb-1.0.0.jar to the <EI2_HOME>/lib directory.

step 2: Update the Keystore(newkeystore.jks) path in the BackEndPolicy.xml policy file.

step 3: Start the EI server

step 4: Add the BackEndPolicy.xml policy file to the registry under the gov:endpoints folder like below.

step 5: Create the BackendService proxy

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="BackendService"
       startOnLoad="true"
       statistics="disable"
       trace="disable"
       transports="http,https">
   <target>
      <inSequence>
         <payloadFactory media-type="xml">
            <format>
               <root xmlns="">
                  <customFieldOne>$1</customFieldOne>
                  <customFieldTwo>$2</customFieldTwo>
               </root>
            </format>
            <args>
               <arg value="Some value 1"/>
               <arg value="Some value 2"/>
            </args>
         </payloadFactory>
         <respond/>
      </inSequence>
      <outSequence/>
      <faultSequence/>
   </target>
   <parameter name="ScenarioID">scenario5</parameter>
   <enableSec/>
   <policy key="gov:endpoints/BackEndPolicy.xml"/>
   <description/>
</proxy>

If you have applied the policy correctly, you can see the secured proxy as below.

Then Go to the FrontEnd EI server which will start from the 9443 port and invoke the TestProxy service using SOAP UI. Any soap request would work and you can easily try out the service via the management console. Please refer to the attached screenshot of the expected response.

🙋 If you need to see the incoming messages to the EI server and outgoing messages from the EI server enable the wire logs. Please change the configs in the <EI_HOME>/conf/log4j2.properties file as in this documentation.

That’s all the configurations you have to do👏🤓 and hope this article will be helpful to implement such kinds of use cases.