BizTalk HTTPs Adapter and Certificate Configurations

1. INTRODUCTION

The HTTP send adapter gets messages from BizTalk Server and sends them to a destination URL on an HTTP POST request. The HTTP send adapter gets the message content from the body part of the BizTalk Message object. The HTTP send adapter ignores all other parts of the BizTalk Message object.

After the adapter sends the message to a destination URL and the BizTalk Messaging Engine receives the HTTP success status code, the HTTP send adapter deletes the message from the MessageBox database.

BizTalk Server hosts the HTTP send adapter as a native BizTalk application. It supports one-way sending on messages as well as solicit-response transmission. The send location for the HTTP send adapter is a distinct URL that you configure through the send port. This unique URL can include query strings appended to the base URL.

2. Steps To Configure the HTTPs Send Port

1. For Creating a new HTTP Send port you need to configure few details. First of all you need to define the name of the send port and select the transport type as HTTP. Select the pipeline as per the requirement. Please check the following screen shot:-

2. Click the configuration button. On the General tab we need to mention the URL of Website/ Web Service. Check the option Enable chunked encoding. The HTTP send adapter sends request messages using chunked encoding if the request size exceeds 48 KB. If the HTTP proxy server is used, the HTTP send adapter does not use chunked encoding and always stages the data before sending. When the send adapter receives a response message, it can accept response messages with a chunked encoded body part.

Request timeout Specify the time-out in seconds for the HTTP/HTTPS transmission. If the HTTP adapter does not receive the response within this time, the service logs the error and resubmits the message based on the retry infrastructure.

Maximum redirects are used to specify the maximum redirects allowed for the message being sent.

3. For Proxy (Handler Ovverride) tab, I have configured it as Use Handler’s default proxy configuration. It depicts that the send port configuration must use the proxy settings specified for the HTTP send handler.

We can configure the other options which are available for the user. Do not use proxy options specify whether the HTTP send handler uses the proxy server. If selected, the HTTP send handler for this send port does not use the proxy server.

If Use Proxy is selected the HTTP send handler uses the proxy server. In Server specify the proxy server address for the send port. We need to mention the port which is being used to access the proxy server. User Name Specify the user name for authentication with the proxy server and specify the user password for authentication with the proxy server in password option.

4. In authentication tab user can select the authentication type which is used on destination server. I am currently using Anonymous. Valid options are:-

A) Anonymous

b) Basic

c) Digest

d) Kerberos

Default Value: Anonymous

Specify the type of credentials to use. Credentials are available if the Authentication Type is Basic or Digest.

Valid options are: Do Not Use Single Sign-On

User name: The user name to use for authentication with the destination server. If the Authentication Type property is Anonymous or Kerberos, this option is disabled. This property requires a value if Basic or Digest is selected, and Enterprise Single Sign-On is not used.

Password: The password to use for authentication with the destination server. If the Authentication Type property is Anonymous or Kerberos, this option is disabled. This property requires a value if Basic or Digest is selected, and Single Sign-On is not used.

Use Single Sign-On: Specify whether to use Single Sign-On to retrieve client credentials for authentication with the destination server.

Affiliate Application: Specifies the affiliate application to use for Single Sign-On. Choose the applications that you want to include in Single Sign-On.

On the “SSL Client certificate thumbprint” we need to mention the thumbprint of the certificate. Thumbprint can be found easily when you open certificate details copy it and paste the same in Send Port Thumbprint Configuration.

Note: – Sometimes when you copy the Certificate thumbprint, you will not be able to paste the same whole string on the send port thumbprint certificate area. If you incurred similar kind of scenario then what you need to do is copy thumbprint from the certificate details, paste the same on some text editor. Go to the starting of the thumbprint, press delete. You will not be able to see what value got deleted. Copy rest of the text and paste it on HTTP send port configuration.

3. Steps to Download Certificate from Web Page:-

1. If you try to open a secure web page then you will get error on a webpage something as mentioned in the following screenshot:-

2. You can simply click on “Continue to this web site (not recommended)”. This will redirect you to website page. Once you are able to view the webpage, then you can download the certificate which is required to access the webpage. Usually certificate details are mentioned besides the address bar. Please check the below screen shot:-

Click on the certificate tab, you will be able to see the Untrusted Certificate error. At the end of the Certificate click on the “View Certificates”:-

Click on details tab and you will get the options as given below:-

Click the option “Copy to File…” this will open another wizard which will give you instructions to save the certificate on your local system.

Save the certificate by selected “DER encoded binary”. We have more options to save the certificate in different formats. One can select the same as per His/her requirements. Once you finish the wizard you will be having the “.CER” file certificate.

4. Importing the certificate:-

1. To use the certificate and send message properly to Target side, you need to import the certificate in different certificate stores. To import the certificate you need to perform the following steps:-

a) First you need to check under which user BizTalk Services are running. You can check the same by checking HostInstance user configurations.

b) Login to system using the account which is being used to run BizTalk Services. Go to Run->Type MMC. Open the console, click on the file menu and open the menu Add/Remove Snap In.

Click on the certificates and then click add -> add my user account. It will open the certificates store under current user account. Click Finish.

Your console should look like this:-

2. Now you need to import the certificate which we have downloaded from webpage. You need to import the certificate under “Personal “ folder and “Trusted Root Certification Authorities ”. To do the same right click on the folder and click on all tasks->import. Select the path of the certificate and click finish. This will import the certificate in the store.

5. Common errors:-

a) Error: – The client certificate is not found in the certificate store. Parameter name: Certificate

Solution: – You need to verify that certificates are installed properly under the mentioned stores for correct service account

b) Error: – Details: “System.ServiceModel.Security.SecurityNegotiationException: Could not establish trust relationship for the SSL/TLS secure channel with authority ‘abc.sg.com’. —> System.Net.WebException: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.

Solution: The error message normally occurs if the client certificate is not configured correctly.  You should check that you have configured your client certificate in certificate store under BizTalk service account that hosts the HTTP adapter.