Securing Proxy Services

Soap message security (also known as Web Services Security) identifies and provides solutions for general computer security threats as well as threats unique to web services. WSO2 supports WS Security, WS-Policy and WS-Security Policy specifications. These specifications define a behavioral model for web services. A requirement for one proxy service may not be valid for another. Therefore, WSO2 provides the option to define service specific requirements.

Security functionality is provided by the Security Management feature which is bundled by default in the Service Management feature of the WSO2 feature repository. The Security Management feature makes it easy to secure the proxy services of the ESB by providing twenty pre-defined, commonly-used security scenarios. These security policies are disabled by default.

This section describes how you can enable and disable these predefined and custom security policies using the ESB management console. The following configuration elements are modified when you enable security and policies:

<policy key="gov:devl/policies/YourPolicy.xml"/>
<parameter name="allowRoles">role1,role2</parameter>
<enableSec/>

Enabling security features

Understanding the exact security requirements is the first step in planning to secure a proxy service. For example, consider what security aspects are important to your proxy service; whether it is the integrity, confidentiality, or both. Follow the instructions below to enable a security feature.

Enabling a pre-defined security scenario

In this example, basic authentication is applied to the Admin user group for the StockQuoteProxy proxy service.

Open the ESB management console. See Running the Product.
Click List under Services in the Main tab to view all the available proxy services.
Click the name of the required proxy service (StockQuoteProxy in this example) to open its service dashboard.
Click Security under Quality of Service Configuration in the service dashboard to open the Security for the service page. Select Yes for the Enable Security? field to view the pre-defined security scenarios available as shown below.

Click the icon in the middle column to view a graphical illustration of each security scenario.
Select the required security scenario ( UsernameToken in this example) and click Next to open the Activate Security page.
In the Search section, enter the search criteria required to search for the user group (role) who will have access to this proxy service. In this example, you can enter All_User_Store_Domains in the Select Domain field to search for the admin user group, and then select the admin check box in the User Groups section to allow users in the admin group to access this proxy service.

If you select security scenario 16 , you have to associate your proxy service with a service principle. The name and the password of the service principle should be specified in the Activate Security page. The service principal need to be defined in the LDAP Directory server before it is entered in the Activate Security page.
Security scenario 16 (i.e. Kerberos Authentication) is only applicable if you have a Key Distribution Center (KDC) and an authentication server in your environment. e KDC and the authentication server is usually found in the LDAP Directory server.
The following two configuration files (usually found in the <ESB_HOME>/repository/conf/security folder) are used to specify the Kerberos related parameters as follows.
krb5.conf: Includes KDC server details, encryption/decryption algorithms etc.
jaas.conf: Includes information relevant to authorization.

If you have selected a policy that requires signing or encryption, the Trusted KeyStores and Private KeyStore sections appear. You can select the wso2carbon.jks check box under Trusted KeyStores and then select a value for the Private Key Store field (which is populated with only the wso2carbon.jks keystore by default).
Click Finish. An information message would appear to indicate that security was applied successfully.

Using the secured proxy service

The following procedure shows how a proxy service is secured when the security configuration is applied as explained above. In this example, a request is sent to the StockQuoteProxy proxy service to which you applied basic authentication.

Open the service dashboard of the StockQuoteProxy proxy service and click Try this service to open the Try It tool. Note that the Security tab is displayed for all the operations of the proxy service.

Enter admin as both the username and the password. Then send the following request using the placeOrder operation:

 <xs:price xmlns:xs="http://services.samples/xsd">2</xs:price>
 <xs:quantity xmlns:xs="http://services.samples/xsd">200</xs:quantity>
 <xs:symbol xmlns:xs="http://services.samples/xsd">IBM</xs:symbol>

You would get the following response:

<success details="in-only operation"/>

Note that you would get the following response if you send the request without specifying the username and the password:

<TryitProxyError xmlns:h="http://wso2.org/ns/TryitProxy" h:status="SOAP envelope error">org.apache.axis2.AxisFault: No user value in the rampart configuration policy</TryitProxyError>

Enabling a custom security scenario

In addition to the default security scenarios, you also have the option to refer to a custom security policy which is stored in Configuration Registry or Governance Registry. When you refer to a custom policy from Registry, you will be provided with all possible options to select user groups, trusted key stores and a private key store. You can select only the required options according to your custom policy and ignore others. Even if you select unwanted options, they will not be used at runtime.

You can refer to a custom security policy as explained in the following procedure.

Open the ESB management console. See Running the Product.
Click List under Services in the Main tab to view all the available proxy services.
Click the name of the required proxy service (StockQuoteProxy in this example) to open its service dashboard.
Click Security under Quality of Service Configuration in the service dashboard to open the Security for the service page. Make sure that Yes is selected for the Enable Security? field.
Select Policy Path under Policy From Registry.
Click either Configuration Registry or Governance Registry as relevant to open the navigation tree from which the required policy path can be selected. Click OK after selecting the policy. In this example, we will click on Configuration Registry and select the policy path as shown below:
Click Next to open the Activate Security page.
In the Search section, enter the search criteria required to search for the user group to which you want to apply basic authentication. In this example, All_User_Store_Domains can be entered in the Select Domain field in order to search for the Admin user group. Select the Admin check box In the User Groups section to apply basic authentication to the admin user group.

If you have selected a policy that requires signing or encryption, the Trusted KeyStores and Private KeyStore sections appear. You can select the wso2carbon.jks check box under Trusted KeyStores and then select a value for the Private Key Store field (which is populated with only the wso2carbon.jks keystore by default).
Click Finish. An information message would appear to indicate that security was applied successfully.

When you secure a proxy service, its HTTP endpoint gets removed. Thus, HTTP requests sent to the proxy service will not be delivered. In order to enable a secured proxy service to receive HTTP requests, you should front it with a REST API as shown below. The REST API would receive the HTTP request and forward it to the HTTPS endpoint of the proxy service.

Handling HTTP requests to a secured proxy service

Use the following procedure to configure a secured proxy service and a REST API which would forwards authenticated HTTP requests to the proxy service.

Create a pass through proxy service with the following configuration.

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="SecuredProxy"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <outSequence>
         <send/>
      </outSequence>
      <endpoint>
         <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
      </endpoint>
   </target>
   <description/>
</proxy>

Open the service dashboard of the proxy service by clicking on the proxy name. You will notice the following two endpoints:

https://local:8243/services/SecuredProxy
http://local:8280/services/SecuredProxy

Apply basic authentication to the proxy service by following the procedure under Enabling a pre-defined security scenario . Then check the service dashboard of the proxy service again. You will notice that the HTTP endpoint has been removed.

Click APIs under Service Bus in the Main tab of the ESB management console. Click Add API and create an API with the following configuration.

<api xmlns="http://ws.apache.org/ns/synapse" name="forwardhttprequest" context="/externalServicesP/SecuredProxy">
   <resource methods="POST DELETE PUT GET">
      <inSequence>
         <send>
            <endpoint>
               <address uri="https://localhost:8243/services/SecuredProxy"></address>
            </endpoint>
         </send>
      </inSequence>
      <outSequence>
         <send></send>
      </outSequence>
   </resource>
</api>

Send the following HTTP request to the URI of the forwardhttprequest API using an application of your choice. The base64 encoded value of the users credentials (i.e. the user of the user group to which the security policy applies) should be sent with the request. In this example, The request is sent using the SOAPUI with Basic YWRtaW46YWRtaW4= (which is the base64 encoded value of the credentials of admin) as the SOAP header value.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getQuote>
         <!--Optional:-->
         <ser:request>
            <!--Optional:-->
            <xsd:symbol>IBM</xsd:symbol>
         </ser:request>
      </ser:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

You would get a response similar to the following:

.<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="Timestamp-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2014-07-14T04:34:28.959Z</wsu:Created>
<wsu:Expires>2014-07-14T04:39:28.959Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<ns:getQuoteResponse xmlns:ns="http://services.samples">
<ns:return xsi:type="ax21:GetQuoteResponse" xmlns:ax21="http://services.samples/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:change>3.778467456882211</ax21:change>
<ax21:earnings>-8.822769178864421</ax21:earnings>
<ax21:high>58.8203977859274</ax21:high>
<ax21:last>56.27356765236518</ax21:last>
<ax21:lastTradeTimestamp>Mon Jul 14 10:04:28 IST 2014</ax21:lastTradeTimestamp>
<ax21:low>58.875647889385405</ax21:low>
<ax21:marketCap>2356246.168443192</ax21:marketCap>
<ax21:name>IBM Company</ax21:name>
<ax21:open>-55.015393199357014</ax21:open>
<ax21:peRatio>-19.77398889127926</ax21:peRatio>
<ax21:percentageChange>6.144142064901374</ax21:percentageChange>
<ax21:prevClose>61.497071795700144</ax21:prevClose>
<ax21:symbol>IBM</ax21:symbol>
<ax21:volume>19348</ax21:volume>
</ns:return>
</ns:getQuoteResponse>
</soapenv:Body>
</soapenv:Envelope>

Disabling security features

The following procedure can be used to disable any security policy applied to a proxy service.

Open the ESB management console. See Running the Product.
Click List under Services in the Main tab to view all the available proxy services.
Click the name of the required proxy service (StockQuoteProxy in this example) to open its service dashboard.
Click Security under Quality of Service Configuration in the service dashboard to open the Security for the service page.
Select Yes for the Enable Security? field. A message will appear to inform that selecting this value would disable security. Click Yes to confirm that you want to proceed. Another message would appear to inform you that the security was disabled successfully.