HTTP Client Adapter

Implementing the HTTP Client Adapter

Configuring the HTTP Client Adapter

To configure the HTTP Client adapter, you must specify field settings in Sterling B2B Integrator:

Business Process Example

The following example business process illustrates the use of the HTTP Client services, which work through the HTTP Client adapter:

The associated BPML code is shown below:

 <process name="HTTPClientDemoAllServices">
  <sequence>
    <!-- Get obscured password -->
    <operation name="Obscure Password">
      <participant name="HTTPClientObscureParameter"/>
      <output message="outmsg">
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientObscureResults" from="*"></assign>
      </input>
    </operation>
     <!-- HTTP Client Begin Session service-->
     <!-- Create connection to specified host and port -->
    <operation name="HTTP Client Begin Session Service">
      <participant name="HTTPClientBeginSession"/>
      <output message="HTTPClientBeginSessionServiceTypeInputMessage">
        <assign to="HTTPClientAdapter">HTTPClientAdapter</assign>
        <assign to="RemoteHost">httpserver</assign>
        <assign to="RemotePort">12345</assign>
        <!-- If server requires Basic authentication -->
        <assign to="RemoteUserId">userid</assign>
        <assign to="RemotePasswd"  from="HTTPClientObscureResults/admin/text()"></assign> 
            RemoteUserId and RemotePasswd are not needed if using a 
            trading partner profile. The profile will supply this information.
        <!-- To use a Trading Partner profile -->
        <assign to="ProfileId">someExistingProfileId</assign>
        <!-- To override HTTPClientAdapter configuration settings -->
        <assign to="ConnectionRetries">10</assign>
        <assign to="RetryDelay">1</assign>
         <!-- If server requires SSL authentication -->
        <assign to="SSL">Must</assign>
        <assign to="CipherStrength">Strong</assign>
        <assign to="CACertificateId">SomeHttp-Id</assign>
        <assign to="SystemCertificateId">httpsampleclientcert1-Id</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientBeginSessionServiceResults" from="*"></assign>
      </input> 
</operation>
     <!-- HTTP Client Method Service -->
    <operation name="HTTP Client Method Service">
      <participant name="HTTPClientMethod"/>
      <output message="HTTPClientMethodServiceTypeInputMessage">
        <assign to="SessionToken"  from="HTTPClientBeginSessionServiceResults/
             SessionToken/text()"></assign>
        <assign to="MethodType">HEAD</assign>
        <assign to="URI">/hello</assign>
        <assign to="RawResponse">true</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientMethodServiceResults" from="*" append="true"/>
      </input>
    </operation>
    <!-- HTTP Client POST Service -->
    <operation name="HTTP Client Post Service">
      <participant name="HTTPClientPost"/>
      <output message="HTTPClientPostServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
             SessionToken/text()"></assign>
        <assign to="URI">/hello</assign>
        <assign to="RawResponse">false</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientPostServiceResults" from="*" append="true"/>
      </input>
    </operation>
    <!-- HTTP Client GET Service -->
    <operation name="HTTP Client Get Service">
      <participant name="HTTPClientGet"/>
      <output message="HTTPClientGetServiceTypeInputMessage">
        <assign to="SessionToken"  from="HTTPClientBeginSessionServiceResults/
               SessionToken/text()"></assign>
        <assign to="URI">/someURI/</assign>
        <assign to="ResponseTimeout">120</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientGetServiceResults" from="*" append="true"/>
      </input>
    </operation>
     <!-- HTTP Client End Session Service -->
     <!-- Ends session specified by SessionToken -->
    <operation name="HTTP Client End Session Service">
      <participant name="HTTPClientEndSession"/>
      <output message="HTTPClientEndSessionServiceTypeInputMessage">
        <assign to="SessionToken" from="HTTPClientBeginSessionServiceResults/
               SessionToken/text()"></assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientEndSessionServiceResults" from="*" append="true"/>
      </input>
    </operation>
  <!-- Provides error handling -->
  <onFault>
    <sequence name="End Session">
    <operation name="HTTP Client End Session Service">
      <participant name="HTTPClientEndSession"/>
      <output message="HTTPClientEndSessionServiceTypeInputMessage">
        <assign to="SessionToken"  from="HTTPClientBeginSessionServiceResults/
               SessionToken/text()"></assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="HTTPClientEndSessionServiceResults" from="*"></assign>
      </input>
    </operation>
    </sequence>
   </onFault>
  </sequence> 
</process>

Configuring Server Name Indication in HTTP Client Adapter

Server Name Indication (SNI) is an extension for the TLS protocol (formerly known as the SSL protocol), which is used in HTTPS. It is included in the TLS handshake process in order to ensure that client devices are able to see the correct TLS certificate for the website they are trying to reach. The extension makes it possible to specify the hostname or domain name of the website during the TLS handshake, instead when the HTTP connection opens after the handshake. SNI is added as an extension to TLS in 2003; it was not originally a part of the protocol.

Consider the following scenario:

There are multiple websites hosted on one server and share a single IP address. Each website has its own TLS certificate and the server may not know which TLS certificate to show when a client device tries to securely connect to one of the websites. This is because the TLS handshake occurs before the client device indicates over HTTP which website it is connecting to.

SNI is designed to solve this problem. It prevents what is known as a "common name mismatch error" - a client (user) device reaches the right IP address for a website, but the name on the TLS certificate does not match the name of the website. Often this kind of error results in a "Your connection is not private" error message in the user's browser.

Example:

SNI makes it possible for a user device to open a secure connection with https://www.example.com even if that website is hosted in the same place (same IP address) as https://www.something.com, https://www.another-website.com, and https://www.example.io.

Sterling B2B Integrator uses HTTP Client Adapter to send HTTP requests to a trading partner using a Perimeter Server. The business process sends a message to a trading partner and the profile of the trading partner profile specifies HTTP as the transport protocol. The business process passes the document as well as information about the trading partner to the HTTP Client adapter. Using the information provided in the business process, the HTTP Client Adapter connects to the trading partner and transfers the document, enforcing any security specifications from the business process.

SNI Usage

The HTTP client services must be able to connect any SNI-enabled server and pass servername/hostname as TLS parameters to the SSLEngine. You must have control over sending the SNI headers, if required you must be able to stop sending SNI headers.

<operation name="HTTP Client Begin Session Service">
<participant name="HTTPClientBeginSession"/>
<output message="HTTPClientBeginSessionServiceTypeInputMessage">
<assign to="." from="*"></assign>
<assign to="RemoteHost">verisign.co.uk</assign>
<assign to="HTTPClientAdapter">HttpClientAdapter </assign>
<assign to="CACertificateId">214267176d33e4732node1</assign>
<assign to="SSL">Must</assign>
<assign to="RemotePort">443</assign>
<assign to="CipherStrength">all</assign>
</output>
<input message="inmsg">
<assign to="." from="*"></assign>
</input>
</operation>

The HTTP Client Adapter completely controls the SNI headers. By default, the "Enable SNI" flag is set to false, You can set this flag value to true, if you wish to start using SNI, or create a copy of the HTTP Client Adapter and use it in the business process.

In case the same adapter is used in two different business processes and one of the business process requires SNI enabled/disabled, then the HTTP Client Adapter level setting can be overridden in the business process by adding the following parameter in the above business process. (SNI value can be set to Yes or No depending on the requirement.)

<assign to="SNI">No</assign>