Monday 10 October 2016

How to Configure SSL for BizTalk HTTPS Receive Port Adapter

Here I am coming back for the BizTalk receiving message via HTTP/S protocols article. In short, the business partner system is using SAP XI and will send their transaction XML message over HTTP/S protocol with POST method. This is the extension part from earlier post article which explain certificate and configuration of SSL with BizTalk HTTP Adapter to send out the message. Do remember my project was done few years back where I was using BizTalk 2006R2 with windows server 2003.


Overview BizTalk HTTP Architecture

BizTalk require IIS component on the same machine in order to use HTTP adapter to receive the message. This is the fact that is inevitable as the adapter need collaborate with local IIS. Indeed, you feel unhappy about this and you should need to find another way round to achieve high availability solution architecture. Let’s say you have multiple BizTalk servers and you have enable BizTalk group. Enabling the HTTPS receive adapter on both BizTalk machine definitely would have an issue to determine a URL receiving point for both BizTalk Server.  At best you would make the second BizTalk server as standby server and you would need to fail over manually.  Below diagram below describe the situation.
BizTalk Group with HTTP receive adapter


Despite of BizTalk Server 1 is the receiving point it does not mean the message transformation process and sending process would only occur in BizTalk Server 1. The other BizTalk servers would possible to take the ownership to host the process and send the message away. Recently I have been thinking to improve above architecture limitation and try to achieve high availability architecture design. The new design is unproven design and hopefully you can consider it and test it out as well. Here below the revised solution.

High Availability BizTalk HTTP receive


In my new design I would assume we are still use BizTalk HTTP adapter as solution and in here I introduced a new cluster server and IIS 7.0 server as main component. Details below are some point of new solution:
  1. The new cluster server above must be in cluster enable and the objective is to eliminate single point of failure against this server itself. Perhaps you might think why can’t we cluster the BizTalk server instead? Although BizTalk Server is cluster aware and compatible, you should consider the required BizTalk adapters are cluster aware and compatible. Namely SAP adapter and Navision Commerce Gateway are few of adapters that have “issue” under MS cluster environment. Another factor to consider is the license that requires you to buy 2 or more license of BizTalk software but you only get 1 instance BizTalk running under MS clustering.
  2. The IIS service component in the new server would be the receiving point. The external partner would only know the URL pointing to this web server under HTTPS connection. The IIS in web server should provide load distribution to BizTalk Server 1 and BizTalk Server 2. I do believe you need to configure URL rewriting and request routing to either one of BizTalk server.
  3. Since the cluster web server and BizTalk Servers is between the networks, you might to choose non secure connection. There is one issue that you should consider with it is whether the client session is maintain after the request is routed to BizTalk Server.
  4. You should evaluate this proposal solution as they are requires the latest operating system and others components. Namely windows 2008 server, IIS 7.0 server, etc.
Above idea is made possible in IIS 7.0 server which provide the load balancing, URL rewriting and request routing.  Please see this link for your reference.


BizTalk Web Service Extension

BizTalk provide web service extension component which will talk to BizTalk API and store the incoming message. The component filename is BTSHTTPReceive.dll and you should able to find this file under folder: “\Program Files\Microsoft BizTalk Server 2006\HttpReceive”. If you able to find it, please check that this component already registered in IIS web extension folder. Make sure the component is allowed to run in web serviced extension. If you cannot see the web extension is registered in here, you should add a new one and point the location folder at the installation BizTalk program files.  Please refer below screen:

BizTalk HttpReceive Web extention

Application Pools

By default, you should able to find the application pool for BizTalk HTTP receiver already created for you. You can create a new pool with any name you like and make sure the pool identity is having correct roles required to access BizTalk API and its databases. Following screen is the pool that I use to address the BizTalk HTTP receive virtual folder.

BizTalk HTTP application pool

The Identify tab of properties windows determine the credential account that IIS will use upon running the web service extension component. It does not need to be local Administrator and if you have multiple BizTalk under BizTalk Groups, you should use the domain user account in here.

Account for application pool

Following picture show all relevant roles with BizTalk Server and only 3 roles which in the circle are required. These roles are the roles that allow the component access the API and store the message in SQL message box.
Role for app pool

Installing the Server Certificate

The certificate installation should be like normal installation. If you have certificate generated from freeware organization, you could just import the certificate from the server certificate directly. Make sure your certificate has private key and it has server authentication function inside. You will able to find your certificate at personal folder of certificate store under local computer level. Please do remember that the commercial SSL certificate normally requires Certificate Revocation List (CRL) to be installed and if your server can’t access internet, you should install the CRL manually. (Please refer to my other post article about configure SSL with send HTTP adapter part 1). At this time, you can install SSL Diagnostics Tools from Microsoft to test the SSL handshake is working and has nothing wrong with your certificate.
Installing server certificate

Creating Virtual Directory

The web service extension component would not be useful unless you expose it in virtual directory. It is just like any virtual directory, you point the physical folder to the folder that contain BTSHTTPReceive.dll and give virtual name as you like. Following picture show that I have created a virtual directory as BTHTTPReceive. The web.config file will be auto generate after you have done editing the configuration via ASP.NET tab or amend the authentication methods.
Virtual directory for HTTP receive

Please ensure the Execute permission is “Scripts and Executables” and you selecting the correct Application pool that we setup earlier.
Virtual directory permission

Configuring Client Certificate

In here I would like to use client certificate to authenticate the client connection and you need to ensure to unchecked all of any other authentication in Authentication and access control. Following screen show the situation.
Client certificate authenticate setup check

In Secure communications section in below screen, click the Edit… button to change the default setting.

Secure communication setup

You would need to ticked the connection require secure channel and client certificate is required. This setting is to ensure the client always using secure connection and the client must transmit their certificate for client authentication. Other than that we ticked the “Enable client certificate mapping” as we would do mapping with one of windows account.

Enabling client cert mapping


Click the Edit… button and you will see Account Mappings screen like below. For the first time, you should has nothing is mapped in here and you can straight away click Add button.
Client account mapping

You should find the certificate (.cer) file to map and once you have selected the file you will need given some information such the map name and importantly the mapped windows account and password. Below screen show the map to account screen look like.
Map to window account

In general I would like to point out some important note to share with you:
  1. The certificate file is belonging to your associate partner (sender). You should check that the certificate has function to perform client authentication. Please check the Enhanced Key Usage properties to find out the certificate functions. Again, I would remind you that one certificate can perform both function as server and client authentication.
  2. It is not necessary to register the client certificate in certificate store but its trusted root certificate CA and intermediate CA need to register into your certificate store at computer level.  Apart from that you should determine if you need to install the certificate revocation list.
  3. The Map to account can be local account or domain account and the account at least must be member of IIS_WPG.

Configuring SSL Host Headers

Upon purchasing the certificate, you should inform the Certificate Authority about the common name (CN) that you want the SSL will bind with. On certain circumstances you would like to register it with FQDN (Full qualified domain name, i.e. www.myserver.mycompany.com) and unfortunately due some reason the preferred CN is rejected by CA. You have no other option to register the CN with other name which different from your server host name. Certainly IIS server could not make this certificate run properly as it has invalid against the binding rule.This is the situation where you need to configure the host headers in IIS server. As you notice from IIS Manager, the user interface don’t provide us the place for you to enter in the alternate host name and it is seem the host headers for SSL is not possible. According to Microsoft website, the features would be available in windows 2003 sp2 and thru the command line we would configuring the host name. Here is the way we configure the SSL host headers and the first we would open the command line and go to the certain folder specified below. We are looking for the adsutil.vbs file as this is the script providing the bindings.
IIS Admin Script utilities
We have to call the cscript.exe to run the scripts and if you run the script without any parameters it will show like below screen.

Command list configuration

You have to type the command line with this format: cscript.exe adsutil.vbs set /w3svc/<site identifier>/SecureBindings ":443:<host header>". The site identifier is the unique ID given by IIS for every web site you have created.  Screen below show web sites identifier.

IIS identifier


The complete information about SSL host header and the scripting can be found in this URL.


Configuring BizTalk HTTP Adapter

The configuration at BizTalk HTTP adapter for receiving is pretty straight forward, since IIS has handling the Server encryption and authentication. I have created a new HTTP receive location with receive handler is “BizTalkServiceIsolatedHost”. This is means the receiving host services handled by IIS server and push the message to BizTalk message box directly. I have choose the receive pipeline is “XMLReceive”  so that BizTalk could auto route the message base on message type to the right active subscriber (orchestration).  
HTTP receive location properties


You can specify the URI by pressing the Configure… button. The important setting is to provide the virtual directory like following picture meanwhile the public address is an optional.
URI HTTP Transport properties

  

Do Testing

Our objective is to test our configuration more or less is correct and BizTalk able to receive the message even though testing with simple text messages. There is one challenging to do this simple internal testing is to test the client authentication. Unless you have your partner system certificate with private key the client authentication, perform testing seem not possible and must do testing with your partner system. Let us test our BizTalk without the client authentication. First, temporarily you need to enable anonymous access and map to a windows account on the virtual directory HTTP receive. Then, you have set ignore client certificates and disable client certificate mapping. Now you can use the any browser to type in the URL to https://localhost/BTHTTPReceive/BTSHTTPReceive.dll?testingdata. You could run the browser from the local machine and please remember to write the port number in the URL if your HTTPS port is not at 443. This testing is to send the text message “testingdata” to BizTalk via Get method (Querystring) and if your SSL working fine, you will see the response back at your browser like following picture.
Successful HTTP response
If above testing is successful then you can do testing with your own freeware client certificate and the expected result should be the same like above screen. Certainly, you have to configure your client certificate before hand. The browser prompt you a list of client certificate that you want to use to access the URL. You will see below screen with list of the client certificate; however you need to check on your configuration if you see nothing.
Empty match client certificate list

In normal case, you would experience some error return in your browser, and each error code has its own issue how to solve and to identify the ground issue. I have this and that URL that explains the detail of the issue and also the solution.


Summary

You have notice that BizTalk actually did not get involved in the SSL certification for receiving and that is because IIS server manages the receiving host process. This is made overall design clean, however the complexity will rise if you have requirement for high availability and load balancing. Like I describe in overall architecture, the possibility to extend and leverage the design is left few options unless you would consider other adapter that available in BizTalk such SOAP, WCF, etc. Thanks for your time..:D

No comments:

Post a Comment