BizTalk 2016 Relay Endpoint

In this post, I want to describe a hybrid integration scenario where a BizTalk 2016 service is exposed to Azure using a service bus relay. Note that the relay is not found under Service Bus, but under resource named Relays. This may be a point of confusion. First you will have to create a relay namespace. Then you add a WCF Relay to this namespace. I used an excellent QuickLearn YouTube video as the basis for this post. Let’s dive into it.

The first gotcha, is that you can now use SAS for service bus relays. Prior to BizTalk 2016, you could only use ACS. ACS is a federated identity solution with trusted authentication providers like Google, Facebook and Microsoft LiveID. ACS is quite complicated for the relay scenario. It’s actually better to use SAS. SAS simply uses a shared secret token for authentication. It’s recommended to use SAS over ACS as it provides a simple, flexible and eay-to-use authentication scheme for hosting a relay in the Azure Service Bus.

BizTalk 2016 has two relay bindings that use SAS: BasicHttpRelay and NetTcpRelay. Both adapters expose a https relay endpoint by default. To configure the relay endpoint with SAS, create a receive location with the BasicHttpRelay Adapter. On the Security tab, specify the Shared Access Signature. The SAS key needs to have Manage level access to the entire service bus namespace, because it actually needs to create a relay endpoint. It’s not enough to just have Send or Listen level access.

On the same security tab, you can specify client security. The client can have anonymous access, but more likely the client will have to provide an access key (relay access token) as well. That would be a SAS signature with Send level access.

You can directly use the primary SAS token from the Azure Portal (as contained under Shared access policies). But, this token protects the Azure Service Bus at the namespace level. For more fine-grained access you can generate a fine-grained SAS token. A SAS token let’s you control the start and expiration time, the resources (ie relay services) you are granting access to and the permissions being granted (manage, send, receive). To generate a SAS token you need to have a reference to the servicebus NuGet package. Then you can use the following code in C# to get a token to send messages to a specific relay service for the period of a year.

The SAS token ends up in a so-called servicebus authentication header.

There’s another gotcha. It’s important to realize, that the BizTalk relay adapters are in-process adapters. That’s different from the regular WCF adapters. These are isolated adapters, meaning that the services are hosted in IIS. As a consequence of being in-process, relay services don’t have access to additional processing in the IIS request pipeline like rate limiting, throttling and/or caching. We can make up for this missing functionality by using Azure API Management. Note that API Management cannot only add policies, but also has the capability to give a REST/JSON endpoint to the SOAP/XML service exposed by BizTalk.

As an example a two-way receive port is created that uses the BasicHttpRelay adapter and a map that transforms the input message to an output message. On enabling the receive port, we’ll see the relay endpoint is created in the Azure Portal. In Azure API Management the set-header policy is used to add the servicebus authorization header. That means, I don’t have to distribute the secret key to all the clients. To prove that it works, we can use the Azure API Management Developer Portal.