Securing APIs with Mutual SSL

In contrast to the usual one-way SSL authentication where a client verifies the identity of the server, in Mutual SSL the server validates the identity of the client so that both parties trust each other. This builds a system that has a very tight security and avoids any requests made to the client to provide the username/password, as long as the server is aware of the certificates that belong to the client. 

This section explains how APIs in WSO2 API Manager can be secured using Mutual SSL in addition to OAuth2.

Enable securing APIs with Mutual SSL

Follow the steps below to enable this feature in WSO2 API Manager.

1. Create the  AM_API_CLIENT_CERTIFICATE table in the APIM DB using the appropriate script given below. Note that the database name will depend on the databases present in your environment. 
   

2. Open the  <API-M_HOME>/repository/conf/axis2/axis2.xml file. Locate the transportReceiver for https as shown below.
   

   <transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener">

   Change the class name to  org.apache.synapse.transport.passthru.PassThroughHttpMultiSSLListener. The sample is given below.
   

   <transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpMultiSSLListener">

   
   

3. Add the following parameters under transportReceiver similar to the sample given below.
   

   <parameter name="dynamicSSLProfilesConfig">
   	<filePath>repository/resources/security/listenerprofiles.xml</filePath>
   	<fileReadInterval>600000</fileReadInterval>
   </parameter>
   <parameter name="SSLVerifyClient">optional</parameter>

   The dynamicSSLProfilesConfig specifies the file read to load the dynamic SSL profile and the time interval in which it will be read. 
   Note that if the fileReadInterval parameter is set to 600000, it will take at least 10 minutes for the gateway to accept a newly added client certificate.

    Expand to see the transportReceiver segment after the changes mentioned above have been made...

   <transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpMultiSSLListener">
           <parameter name="port" locked="false">8243</parameter>
           <parameter name="non-blocking" locked="false">true</parameter>
           <!--parameter name="bind-address" locked="false">hostname or IP address</parameter-->
           <!--parameter name="WSDLEPRPrefix" locked="false">https://apachehost:port/somepath</parameter-->
          <parameter name="httpGetProcessor" locked="false">org.wso2.carbon.mediation.transport.handlers.PassThroughNHttpGetProcessor</parameter>
           <parameter name="keystore" locked="false">
               <KeyStore>
                   <Location>repository/resources/security/wso2carbon.jks</Location>
                   <Type>JKS</Type>
                   <Password>wso2carbon</Password>
                   <KeyPassword>wso2carbon</KeyPassword>
               </KeyStore>
           </parameter>
           <parameter name="truststore" locked="false">
               <TrustStore>
                   <Location>repository/resources/security/client-truststore.jks</Location>
                   <Type>JKS</Type>
                   <Password>wso2carbon</Password>
               </TrustStore>
           </parameter>
          <!-- ============================================== -->
          <!-- Configuration for Listener Dynamic SSL Profile loading. -->
          <!-- Configured for 10 mins. -->
          <!-- ============================================== -->
          <parameter name="dynamicSSLProfilesConfig">
              <filePath>repository/resources/security/listenerprofiles.xml</filePath>
              <fileReadInterval>600000</fileReadInterval>
          </parameter>
          <parameter name="SSLVerifyClient">optional</parameter>
           <!--<parameter name="SSLVerifyClient">require</parameter>
               supports optional|require or defaults to none -->
   </transportReceiver>

4. Copy the code given below to create the  listenerprofiles.xml file in the  <API-M_HOME>/repository/resources/security directory.
   

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <parameter name="SSLProfiles">
   <profile>
           <bindAddress>0.0.0.0</bindAddress>
            <KeyStore>
               <Location>repository/resources/security/wso2carbon.jks</Location>
               <Type>JKS</Type>
               <Password>wso2carbon</Password>
               <KeyPassword>wso2carbon</KeyPassword>
           </KeyStore>
           <TrustStore>
               <Location>repository/resources/security/client-truststore.jks</Location>
               <Type>JKS</Type>
               <Password>wso2carbon</Password>
           </TrustStore>
           <SSLVerifyClient>optional</SSLVerifyClient>
       </profile>
   </parameter>

   
   

   The  <API-M_HOME>/repository/resources/security directory can be changed according to the file path you have configured in Step 2.

5. Open the <API-M_HOME>/repository/conf/api-manager.xml file. Set the  EnableMTLSForAPIs parameter to true.
   
   

   <APIManager>
   	...
     <EnableMTLSForAPIs>true</EnableMTLSForAPIs>

6. Restart the server.

Create an API secured with Mutual SSL

1. Create an API.
2. Edit the API and navigate to the Manage tab.

3. Select Mutual SSL under API Security.
   

   You can select both OAuth2 and Mutual SSL options. This means that the user can access the API using a valid OAuth2 token or using a valid client certificate. When OAuth2 and Mutual SSL are both enabled, Mutual SSL authentication will have a higher priority than OAuth2 as explained as follows:

   API Security		User's Response		Outcome
   OAuth2	Mutual SSL	OAuth2 token	Mutual SSL Certificate
   Enabled	Enabled	Sent	Sent	Initially, the Mutual SSL certificate is validated. If the validation is successful, the OAuth2 token is ignored. If the Mutual SSL certificate fails, the OAuth2 token is validated, but if the OAuth2 token fails as well, the API call will fail.
   Enabled	Enabled	Not sent	Sent	The Mutual SSL certificate is validated. If the validation fails, the API call will fail.
   Enabled	Enabled	Sent	Not sent	The OAuth2 token is validated. If the validation fails, the API call will fail.

4. Click Manage Certificates to upload a new client certificate. Select Add New Certificate.
   
   
   

   This feature currently supports only the following formats for keystores and certificates.

   • Keystore : .jks
   • Certificate : .crt

   If you need to use a certificate in any other format, you can convert it using a standard tool before uploading.

   After configuring, the certificate will be added to the Gateway nodes which are defined under the Environments in api-manager.xml. In a clustered setup, as gateway configurations are identical, sync the <API-M_HOME>/repository/resources/security/listenerprofiles.xml and <API-M_HOME>/repository/resources/security/client-truststore.jks among the gateway nodes. After the configured interval, the synapse transport will be reloaded in all the gateway nodes.

5. Provide an alias and public certificate. Select the tier that should be used to throttle out the calls using this particular client certificate and click Upload.
   
6. Save and Publish the API

Invoke an API secured with Mutual SSL from the API Store

1. Invoke an API from the API Store.
2. When you click Execute the browser will send a prompt similar to the one shown below. Select the corresponding certificate for the API.
   

Limitations

Listed below are the known limitations for this feature.

• Application subscription is not permitted for APIs that are only protected with Mutual SSL. Hence, subscription/application level throttling is not applicable for these type of APIs.

• Resource level throttling is not applicable for the APIs that are only protected with Mutual SSL.

• Resource level security will not be applicable for the APIs that are only protected with Mutual SSL.

• Scope level security will not be applicable for the APIs that are only protected with Mutual SSL.