Mutual SSL authentication with the Web Services adapter

Mutual authentication or two-way authentication refers to a client or user authenticating themselves to a server and that server authenticating itself to the user in such a way that both parties are assured of each others' identity. Using the Web Services adapter, you can set up the two-way authentication for the server and the client. 

Related Knowledge Base article

For troubleshooting adapter connectivity issues when SSL certificates are used, see knowledge article 000041806: Some adapters do not start with the error "Nested BER Data Value straddles end of definite length encoded constructed value".  

Before you begin

Before you set-up the two-way SSL authentication, ensure that the following conditions are met:

  • Install the client certificate (private key certificate "PKC") on the custom keystore file and specify the keystore file path in the <keystore-file> element in the adapter request.
  • Specify the client certificate alias in the <client-alias> element in the adapter request.
  • Specify the <install-certificate> as false in the adapter request.
    The Web Services adapter expects the server certificate (Public Key) to be already present in the client (for example, the CDP peer where the Web Services adapter is enabled) truststore file. The truststore file can be a default java truststore (cacerts file). You must specify the truststore file     <truststore-file> element if using a custom truststore file location.

    If true, the adapter downloads the     server certificates (similar to a one-way SSL handshake communication) to a default java truststore cacerts file.
  • Specify the value for the <allow-unsigned-certificate> element based on the signed or unsigned certificates used for SSL handshake communication. On the server side, the client certificate must also be present on the server truststore file to validate when a client presents its private key certificate (in a keystore file) to the server.

To set up the two-way SSL authentication

The following procedure describes how to set up the two-way SSL authentication between two grids, where one acts as a server and other acts as a client to invoke ORCA Web Service with mutual authentication. 

  1. Generate a digital certificate on the CDP Server by using the following command.
    keytool -genkey -alias AOCDP -keyalg RSA -validity 365

    Note

    Ensure that you specify the hostname as CN while generating the digital certificate.

  2. Export the certificate to a file by using the following command.
    keytool -export -alias AOCDP -file AOCDP.cer
  3. Copy the certificate to the client computer.
  4. Import the certificate to the client's truststore by using the following command.
    keytool -import -trustcacerts -alias AOCDP -file AOCDP.cer -keystore Client.truststore

  5. Generate the certificate on the client machine by using the following command.
    keytool -genkey -alias Client -keyalg RSA -validity 365 -keystore Client.keystore

    Note

    Ensure that you specify the hostname as CN while generating the digital certificate.

  6. Export the certificate to a file.
    keytool -export -alias Client -file Client.cer -keystore Client.keystore
  7. Copy the certificate to the CDP Server machine and import into the CDP's truststore.
    keytool -import -trustcacerts -alias Client -file Client.cer -keystore <AO_Home>\jvm\lib\security\cacerts 
  8. You must specify the path of the Client.truststore (generated at step 4) and Client.keystore (generated at step 5) files in the Web Services adapter requests.

Adapter request and response for the two-way SSL authentication

The following figure shows a sample adapter request with the JAX-WS approach.

<adapter-request>
  <target-adapter>soapAdapter</target-adapter>
   <peer-location>
     <location>this</location>
     <peer-name>peername</peer-name>
   </peer-location>
  <request-action/>
  <request-data>
     <soap-rpc-request>
  <wsdl-location>https://vw-pun-abc-1234:943/cdp/orca?wsdl</wsdl-location>
         <invocation-mode>synchronous</invocation-mode>
 <use-ssl-certificate>true</use-ssl-certificate>
 <install-certificate>true</install-certificate>
 <allow-unsigned-certificate>false</allow-unsigned-certificate>
 <truststore-file>C:\tomcatCert\client\trustserver.jks</truststore-file>
 <passphrase>changeit</passphrase>
<keystore-file>C:\tomcatCert\client\client.jks</keystore-file>
 <keystore-passphrase>changeit</keystore-passphrase>
 <client-alias>client_full</client-alias>
 <character-set />
 <download-attachments>false</download-attachments>
 <soap-message>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa" xmlns:oas=
"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
     <soapenv:Header>
       <oas:Security>
         <oas:UsernameToken>
           <oas:Username>admin</oas:Username>
           <oas:Password>admin123</oas:Password>
         </oas:UsernameToken>
       </oas:Security>
     </soapenv:Header>
     <soapenv:Body>
       <soa:executeProcess>
         <soa:gridName>GRID1</soa:gridName>
         <soa:processName>:SOAP_WF:Get Schema</soa:processName>
         <soa:parameters>
           <!--Optional:-->
           <soa:Input>
             <!--Zero or more repetitions:-->
             <soa:Parameter>
               <soa:Name required="true">adapter name</soa:Name>
               <!--Optional:-->
               <soa:Value soa:type="xs:string">
                 <!--Optional:-->
                 <soa:Text>Rem_AO_VM09</soa:Text>
                 <!--Optional:-->
               </soa:Value>
             </soa:Parameter>
             <soa:Parameter>
               <soa:Name required="true">schema name</soa:Name>
               <!--Optional:-->
               <soa:Value soa:type="xs:string">
                 <!--Optional:-->
                 <soa:Text>Alert Events</soa:Text>
               </soa:Value>
             </soa:Parameter>
           </soa:Input>
         </soa:parameters>
       </soa:executeProcess>
     </soapenv:Body>
   </soapenv:Envelope>
 </soap-message>
</soap-rpc-request>
  </request-data>
</adapter-request>bao

The following figure shows a sample adapter request with the Method 1 approach.

Note

Apache Tomcat is configured to Two-Way SSL authentication, so, Mutual Authentication is required while accessing the URL prior to accepting the actual SOAP request. 

<adapter-request>
  <target-adapter>soapAdapter</target-adapter>
  <peer-location>
     <location>this</location>
     <peer-name>peername</peer-name>
  </peer-location>
  <request-action/>
  <request-data>
     <soap-rpc-request>
 <use-ssl-certificate>true</use-ssl-certificate>
 <install-certificate>true</install-certificate>
 <allow-unsigned-certificate>false</allow-unsigned-certificate>
 <truststore-file>C:\tomcatCert\client\trustserver.jks</truststore-file>
 <passphrase>changeit</passphrase>
 <keystore-file>C:\tomcatCert\client\client.jks</keystore-file>
 <keystore-passphrase>changeit</keystore-passphrase>
 <client-alias>client_full</client-alias>
 <http-connection-properties>
   <SoapAction>POST</SoapAction>
 </http-connection-properties>
 <transport>https-rpc</transport>
 <soap-url>https://vw-pun-abc-pq34:943/baocdp/orca</soap-url>
 <character-set />
 <download-attachments>false</download-attachments>
 <soap-message>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa" xmlns:oas=
"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
     <soapenv:Header>
       <oas:Security>
         <oas:UsernameToken>
           <oas:Username>admin</oas:Username>
           <oas:Password>admin123</oas:Password>
         </oas:UsernameToken>
       </oas:Security>
     </soapenv:Header>
     <soapenv:Body>
       <soa:executeProcess>
         <soa:gridName>GRID1</soa:gridName>
         <soa:processName>:SOAP_WF:Get Schema</soa:processName>
         <soa:parameters>
           <!--Optional:-->
           <soa:Input>
             <!--Zero or more repetitions:-->
             <soa:Parameter>
               <soa:Name required="true">adapter name</soa:Name>
               <!--Optional:-->
               <soa:Value soa:type="xs:string">
                 <!--Optional:-->
                 <soa:Text>Rem_AO_VM09</soa:Text>
                 <!--Optional:-->
               </soa:Value>
             </soa:Parameter>
             <soa:Parameter>
               <soa:Name required="true">schema name</soa:Name>
               <!--Optional:-->
               <soa:Value soa:type="xs:string">
                 <!--Optional:-->
                 <soa:Text>Alert Events</soa:Text>
               </soa:Value>
             </soa:Parameter>
           </soa:Input>
           <!--            <soa:Output soa:type="?">
              <soa:Parameter>
                 <soa:Name required="true">adapter response</soa:Name>
                 <soa:Description>?</soa:Description>
                 <soa:Value soa:type="xs:string">
                    <soa:Text></soa:Text>            
                 </soa:Value>
              </soa:Parameter>
           </soa:Output> -->
         </soa:parameters>
       </soa:executeProcess>
     </soapenv:Body>
   </soapenv:Envelope>
 </soap-message>
</soap-rpc-request>      
  </request-data>
</adapter-request>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*