How to configure SSL Certificate for BizTalk HTTP send port adapter (Part 2/2)

This is the second part article from the part 1 that mostly addressing the basic knowledge of certificate. In this post article I will explain more toward the implementation area where all pieces put together in BizTalk Server.

BizTalk HTTP Adapter Configuration

First of all, we should check the HTTP adapter is there in the system. You should able to see the entire available adapter under Platform Settings-->Adapters. From there you can find the information of HTTP adapter host name and whether the adapter is configured correctly. There are two direction on each adapter and for send direction, HTTP adapter is hosted under BizTalk own host process meanwhile the receive direction is under BizTalk Server Isolation which is mean BizTalk depend on local IIS service.

BizTalk HTTP adapter

You can see the detail on each direction and from the properties you can select available BizTalk host process that HTTP will bind into. The selected host name in this property would be the defaulted value for every HTTP send port you have.

HTTP adapter host binding

BizTalk Group And Hosts Instances

You will see multiple host instances per BizTalk Server if you configure your BizTalk as a group. In here you can dedicate the host process for HTTP adapter to certain host server. In my recent project implementation, I have a situation the client only purchased a SSL certificate meanwhile they have two BizTalk server runs on BizTalk Group. The solution for this is to create a new host with new host instance only at one of the BizTalk server. Afterward you can set your HTTP adapter to bind with the new Hosts that you create earlier. Foloowinng screen show a new host called “BizTalkServerHTTPApplication” that runs on ServerA. 

New Host Instance  dedicated for HTTP

BizTalk will create a new service for your new host instance service and you should able to see in under window services. Take a look that the logon that you specified in BizTalk will be the account that run the service as well.

New BizTalk Service

Create New Send Port

To make it simple, I am creating a new Static One-Way send port that will send XML to secure URL address.The adapter type should be the HTTP adapter and use XML transmit pipeline as you need the xml data format is send by BizTalk in proper format. You notice the handler is the host that you selected earlier in HTTP adapter properties.

New HTTP send port

Partner Public Certificate. 

The SSL certificate that we looking at in here is the public server certificate belong to your partner business. The certificate should be able to perform server authentication (encrypt/decrypt) when the data is being sent from BizTalk. Whenever you assign a certificate to this send port, the URI is should respect the Common Name (CN) of the certificate properties. For example if the CN is www.abc.com then your URI must be https://www.abc.com/paths/page.../... Meanwhile your network setting should able to resolve the IP address for the CN. Thus it is disregard of the IP address, the domain URI must be match with the CN of the certificate. Adding the CN inside the host file of local server is the easy way to resolve the public IP. Following list elaborate the required certificates and to be installed under local computer certificate store:

1. Server Public certificate belong to your partner website. Register this certificate under other people folder
2. Intermediate trusted certificate. If any, you should register this certificate in Intermediate Certificate Authority folder.
3. Root trusted certificate. Register this certificate in Trusted Root Certificate Authority folder
4. Certificate revocation list (CRL). If the server public certificate specifies the CRL, then you should install the CRL at intermediate/trusted root certificate authority.

Please double check that all those certificate still in valid period and should register these certificates at the same server that has HTTP adapter BizTalk host is running. Following screen is the place to assign the certificate:

Browse and assign a certificate

When you click the browse button, BizTalk will give you a new screen to choose the available certificate list:

Select installed certificate

The list shows in this screen is those certificate registered in “Other Peoples” folder of Local Computer certificate stores. 

Configure The HTTP URI Transport Property 

If you click the Configure button at HTTP send property next to adapter transport type, you can start to enter the URI. You should enter starting with HTTPS for secure connection. You can query string behind the URI but it would be static query. Please always remember the URI should respect the CN that bind the SSL certificate.

URI HTTP property

Configure SSL Client Certificate 

The SSL client feature is a way to authenticate the client connecting to the web server. The client certificate would be then at server side mapped to the valid windows account if the certificate is valid.  This is the way you prove who you are as client and personal certificate is only qualified certificate to be used as client SSL certificate. Below points are the conditions of a certificate that BizTalk can use as client authentication:

1. The certificate has private key inside.
2. Register the certificate inside “Personal” folder under BizTalk Host service account that hosts the HTTP adapter.
3. In “Enhanced Key Usage” property of the certificate you can see “Client Authentication”
4. You must install the Intermediate trusted certificate, trusted root certificate and certificate revocation list (if specified) that related to your client certificate. You should configure the certificates from Local Computer certificate store and system will automatically copy down to respective windows account. You will get the error response of 403 if you missed out one of these certificates.

I ever mentioned, a certificate can perform both server certificate and client certificate. You have better option to maintain one certificate if the communication is two ways between BizTalk Server and your business partner system. Inside the Authentication tab of HTTP Transport Properties you can specify the authentication type and the client thumbprint ID. For our purposes the authentication type should be Anonymous and enter in the thumbprint ID and this ID can be found inside the certificate properties. 

Client SSL thumbprint

The configuration is completed and please remembers to restart the host instance right before the testing. 

Test The Water Before Jump In 

I find the integration project is always has a challenge that both parties must do the correct configuration to make a successful connection. It is necessary to understand both are exchanging the correct certificate and information.  Yet, there is always a way to test your partner setting is as what you expected event before you touch at BizTalk. Below steps is the way to test the certificate configuration: Configure the partner certificates and your client certificates inclusive the CA certificates and CRL certificates.

• Logged on to your BizTalk Server using BizTalk Service account that host HTTP adapter.
• Open a browser from the BizTalk server and enter in the URL exactly the same URI that you enter at HTTP send adapter.
• When you enter the URL, You should not get any security alert like below screen. Obviously, BizTalk wouldn’t able to a give the answer Yes or No if you let this prompt occurs.

Security alert prompt

• You can verify the certificate by clicking the “View Certificate” button. The certification path should be cleared if the certification setting is right.  Please compare the Serial Number of the certificate if necessary. The certificate show in here should be match to what you have configured.
• You will be prompt to choose client certificate. Your client certificate should show in this screen. The client certificate will be shown in this screen if the CA certificates are registered in both servers; one acting as the client (in this case BizTalk server) and also the partner server.

Select client certificate

Once above test is passed, you should have a very high chance that BizTalk will successfully send the message to partner web URI. Following 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. 

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. ---> 

In Summary 

The key important of SSL with BizTalk HTTP adapter is to understand on how BizTalk would find the certificates in certificate store and to understand the concept of certificate itself. I hope this blog post will benefit to you and able to expedite to accomplish their project implementation. I will writing the next blog with similar subject but from different direction of connectivity which the configuration of BizTalk Server to receive XML message using secure channel SSL.