Applying Security to a Proxy Service

The steps below demonstrate how to apply security for a proxy service via WSO2 EI Tooling by creating a security policy, and then deploying it in the server. 

Creating the proxy service in WSO2 EI Tooling

You can create a new proxy service or import an existing proxy service from an XML file, such as a Synapse Configuration file.

Creating a new proxy service

Follow these steps to create a proxy service. Alternatively, you can import an existing proxy service.

1. In WSO2 EI Tooling, open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click Proxy Service in the Enterprise Service Bus area.
2. Select Create a New Proxy Service and click Next.
3. Type a unique name for the proxy service and specify the proxy type (see below).
4. Do one of the following:
   
   • To save the proxy service in an existing ESB Config project in your workspace, click Browse and select that project.
   • To save the proxy service in a new ESB Config project, click Create new ESB Project and create the new project.
5. If you specified a proxy type that requires that you enter the target endpoint (the endpoint that represents the actual service), do one of the following:
   
   • If you know the URL of the endpoint, select Enter URL and type it in the text box.
   • If you want to use an endpoint you've already defined in this workspace, select Predefined Endpoint and select it from the list.  
   • If you want to use an endpoint in the registry, select Pick from Registry, and then either type the endpoint's registry key or click Browse, click Registry, and navigate to the endpoint in the registry.
6. Fill in the advanced configuration based on the proxy service type you specified:
   
   • Transformer Proxy: Transforms all the incoming requests using XSLT and then forwards them to a given target endpoint. Specify the target endpoint as described in the previous step, and then specify the location of the XSLT you want to use to transform requests, either by typing the path or by clicking Browse and navigating to the XSLT, which can be a file in the workspace or registry or can be a local entry. If you also want to transform the responses from the backend service, click Transform Responses.
   • Log Forward Proxy: Logs all the incoming requests and forwards them to a given endpoint. It can also log responses from the backend service before routing them to the client. Specify the log level for requests and responses, where Simple logs To, From, WSAction, SOAPAction, ReplyTo, MessageID, and any properties, and Full logs all attributes of the message plus the SOAP envelope information.
   • Pass Through Proxy: Forwards messages to the endpoint without performing any processing on them. This proxy service is useful as a catch-all, so that messages that do not meet the criteria to be handled by other proxy services are simply forwarded to the endpoint. When you select this proxy service type, you just specify the target endpoint as described in the previous step.
   • WSDL Based Proxy: A proxy service that is created from the remotely hosted WSDL of an existing web service. The endpoint information is extracted from the WSDL. In the URI field, enter the URL and URN of the WSDL. The URL defines the host address of the network resource (can be omitted if resources are not network homed), and the URN defines the resource name in local namespaces. For example, if the URL is  ftp://ftp.dlink.ru  and the URN is /pub/ADSL/, you would enter  ftp://ftp.dlink.ru/pub/ADSL/  for the URI. To ensure that the URI is valid, click Test URI. You then enter the service name and port of the WSDL. Lastly, if you want to publish this WSDL, click Publish Same Service Contract.
   • Secure Proxy: Uses WS-Security to process incoming requests and forward them to an unsecured backend service. Specify the target endpoint as described in the previous step, and then specify the key of the security policy or click Browse and select it from the registry.
   • Custom Proxy: A custom proxy service in which you customize all the sequences, endpoints, transports, and other QoS settings by adding them to the mediation workflow after the proxy service is created.
7. Click Finish. The proxy service is created in the src/main/synapse-config/proxy-service folder under the ESB Config Project you specified, and the proxy service appears in the editor. Click its icon in the editor to view its properties.

Importing a proxy service

Follow these steps to import an existing proxy service from an XML file (such as a Synapse configuration file) into an ESB Config project. Alternatively, you can create a new proxy service.

1. In WSO2 EI Tooling, open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click Proxy Service in the Enterprise Service Bus area.
2. Select Import Proxy Service and click Next.
3. Specify the proxy service file by typing its full pathname or clicking Browse and navigating to the file.
4. In the Save Proxy Service In field, specify an existing ESB Config project in your workspace where you want to save the proxy service, or click Create new ESB Project to create a new ESB Config project and save the proxy service there.  
5. If there are multiple proxy services in the file, in the Advanced Configuration section select the proxy services you want to import.
6. Click Finish. The proxy services you selected are created in the src/main/synapse-config/proxy-service folder under the ESB Config project you specified, and the first proxy service appears in the editor.

Creating the security policy

Follow the steps below to create a security policy to define the required security configurations.

1. Open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click Registry Resource Project.
   

   If you already have a Registry Resource Project created, follow the steps below to create a Registry Resource in it.

   • Right-click on the Registry Resource Project it in the left navigation panel and click New, and then select Registry Resource.
     
   • Select the From existing template option and click Next. 
     
   • Continue from step 5 below.
2. Enter a name for the project and click Next.
   
3. Enter the Maven information about the project and click Finish.
    
4. Right-click on the Registry Resource Project in the left navigation panel and click New, and then select Registry Resource.
   
5. Enter a resource name and select the WS-Policy template along with the preferred registry path.
   
6. Click Finish. 
7. Open the created policy by double-clicking on the created policy file.
   
8. The policy file opens in a multi page editor with a Security Form Editor as the design view and an XML editor as the source view.
   Design View
   
    
   Source View
   
9. Enable security by specifying the required scenario in the Security Form Editor. Click the icon next to each scenario for more information.
   
10. You can provide the rampart configuration, as shown below.
     
11. If the security policy you selected requires keystores for signing and encryption, you can specify the keystore details as shown below.
    
12. For certain scenarios, you can specify user roles. After you select the scenario, scroll to the right to see the User Roles button. Alternatively, maximize the window. 
    
13. Either define the user roles inline or retrieve the user roles from the server.
    Define Inline
     
    Get from the server
    

Applying security to a proxy service

Follow the steps below to apply security to a proxy service.

1. Once you have configured the policy file, you can apply security for a proxy service by setting the Security Enabled property to true and pointing to the policy key under Service Policies in the proxy properties.
   
2. Specify the policy path inline or browse from the registry or workspace. You can also create and point to a new resource.
   

Deploying the secured proxy service in WSO2 EI

Create a Composite Application Project including the secured proxy service and the security policy registry resource, and then create a CAR file to deploy it in the WSO2 EI server.

1. Right-click the Project Explorer and click New -> Project.
2. From the window that opens, click Composite Application Project.
3. Give a name to the Composite Application project and select the projects that you need to group into your C-App from the list of available projects.

4. In the Composite Application Project POM Editor that opens, under Dependencies, note the information for each of the projects you selected earlier. Be sure that the server role selected for the registry resource in the Composite Application Project POM Editor is changed to EnterpriseServiceBus.

5. To deploy the artifacts using the ESB's management console, you need to create a CAR file as follows:
   • Right-click the C-App project and select Export Composite Application Project from the pop-up menu.
     OR
   • Open the pom.xml file in the Composite Application Project POM Editor and click the button for creating an archive in the upper-right corner.
     
     

6. Give the location of the CAR file and the artifacts you want to include in it.

7. You have now exported all your project's artifacts into a single CAR file. Next, deploy the Composite Application in the server.