About the Author Writen By Steef-Jan Wiggers [Microsoft Integration MVP]
Steef-Jan is an information architect working for a consultancy firm in the Netherlands (Inter Access). He has almost 15 years’ experience as a technical lead developer, application architect and consultant, specializing in custom applications, enterprise application integration (BizTalk), Web services and Windows Azure. Steef-Jan is very active in the BizTalk community as a blogger, Wiki
author/editor, forums, writer and public speaker in the Netherlands and Europe. He has been a BizTalk MVP for 4 years.
WCF-BasicHttpRelay Adapter Deep Dive
Contents WCF-BasicHTTPRelay Deep Dive.................................................................................................................... 0
About the Author ........................................................................................................................................... 1
BizTalk Server 2013: WCF-BasicHttpRelay Adapter .......................................................................................................... 3
Purpose of this document................................................................................................................................................. 4
Possible solution architecture using WCF-BasicHttpRelay Adapter in BizTalk Server 2013 ............................................. 5
WCF-BasicHttpRelay adapter characteristics.................................................................................................................... 7
Configuring the WCF-BasicHttpRelay adapter .................................................................................................................. 8
A basic scenario with the new BizTalk WCF-BasicHttpRelay .......................................................................................... 13
How it works ................................................................................................................................................................... 14
Wrap-up .......................................................................................................................................................................... 21
Acknowledgements ........................................................................................................................................................ 22
BizTalk Server 2013: WCF-BasicHttpRelay Adapter BizTalk Server 2013 offers a few new adapters. Three of them enable connectivity with the Windows Azure Service Bus.
These adapters are the WCF-BasicHttpRelay, WCF-NetTcpRelay, and SB-Messaging. The first two leverage the ability to
use the Service Bus Relay. The relay service is one of the entities within the Windows Azure Service Bus. Benefits of using
the relay service are that:
you can share data between an on premise application, Line-of-Business system or databases with a service
hosted elsewhere (in the cloud or other enterprise)
you have a secure connection between both sender and receiver of data with simplified networking (less dealing
with firewalls, dynamic IP addresses or Network Area Translation (NAT))
you can easily set up a listener in Windows Azure Service Bus through BizTalk Server 2013 or .NET using WCF-
BasicHttpRelay or WCF-NetTcpRelay.
WCF-BasicHttpRelay Adapter Deep Dive
Purpose of this document This article will discuss the WCF-BasicHttpRelay adapter, its characteristics, how to configure it, and how to use it within
a basic hybrid scenario. You will learn how to setup an endpoint in BizTalk Server without using the BizTalk Service
Publishing Wizard. This is article will strictly confine to BizTalk Server Administration console to configure a receive port
with a location configured with WCF-BasicHttpRelay adapter. Why this can be useful and what happens in the
background when a message is sent to configured endpoint.
Possible solution architecture using WCF-BasicHttpRelay Adapter in
BizTalk Server 2013 Below you will find a possible solution architecture, where one enterprise (X) will collect data from another enterprise
(Y).
BizTalk Server
Receive Port
BasicHttpRelay Binding
Relay Service
Register Endpoint
Database View
Connect to Service
Bus Namespace
Soap Envelope
Header: RelayAccessToken
Body: request payload
Soap Envelope
Body: request payload
Enterprise X
Enterprise Y
Issuer Name
Issuer Secret
Scope
RelayAccessToken
Access Control ServiceService Bus
HTTPS/SOAP
Windows Azure
1
Token issuing
endpoint
2
3
4
5
6
RelayAccessToken
Issuer Name
Issuer Secret
Scope
Figure 1. Sample architecture with a relay between two enterprises.
Connection is opened to Access Control Service (ACS) and then authentication credentials using the OAuth WRAP
Protocol. BizTalk Server sends a request to ACS using a HTTPS form POST. ACS issues and returns a security token (1).
Within the token permissions are included like listen.
The same mechanism applies for the client that wants to send messages to the relay endpoint (2). Again ACS issues and
returns a security token. Within the token permissions are included like send.
The client extracts the RelayAccessToken from the security token issued by ACS and uses that for the header in the soap
envelope of message it be sending. The body of the message will contain the payload, which can be a query for a database
view (3).
WCF-BasicHttpRelay Adapter Deep Dive
The Service Bus Relay Service validates and remove the security token from the message and will then forward it to the
registered listener(4); the address configured in the BizTalk receive location.
BizTalk will process the message by making a call to the database view based on the payload and will return the result to
relay service (5).
The Service Bus Relay service will forward the response back to the client (6).
The underlying technology behind the described architecture will be discussed in more detail in this article.
WCF-BasicHttpRelay adapter characteristics The WCF-BasicHttpRelay adapter can be used with BizTalk to send and receive messages from the Service Bus relay
endpoints using the BasicHttpRelayBinding. This is a binding that BizTalk can use to configure endpoints, which can
communicate with ASMX-based Web services and other services that conform to the WS-I Basic Profile 1.1.
The BasicHttpRelayBinding is derived from the standard BasicHttpBinding, part of the System.ServiceModel
namespace. The key difference between BasicHttpBinding and its cloud related relative BasicHttpRelayBinding is that
with the latter you can create an endpoint which can be reachable from outside your organization, by utilizing the Azure
Service Bus, in a secure way. This endpoint is, if required, a publicly discoverable HTTP listener endpoint listening on the
Windows Azure Service Bus. The BasicHttpBinding listens through the standard HTTP.sys listener on the local Windows
computer.
Note: Technically you can expose a BasicHttpBinding endpoint and expose it in a secure way (using SSL, Certs, Firewalls
etcetera). However with the BasicHttpRelayBinding the steps required to provide an externally accessible endpoint are
simplified.
WCF-BasicHttpRelay Adapter Deep Dive
Configuring the WCF-BasicHttpRelay adapter With BizTalk Server 2013 you can easily register an endpoint in the Windows Azure Service Bus. You can create a receive
port and within that port you can create one or more receive locations. The receive location can be configured choosing
the WCF-BasicHttpRelay. You configure the adapter through a dialog WCF-BasicHttpRelay Transport Properties that has
four tabs.
The first tab is named General (see Figure 1). In this tab you can specify the endpoint address that will be registered in
the Windows Azure Service Bus. When specifying the address the "http" or "https" URI scheme can be used depending
on the means of security that will be applied.
Figure 2: Specifying the Endpoint address.
The next tab of the WCF-BasicHttpRelay Transport Properties is the Binding tab. In this tab you can specify the time-out
and encoding-related properties. As seen in the screenshot below (Figure 2), depending on your requirements, you can
adjust the defaults and specify different values.
Figure 3. Specifying the Binding properties.
The third tab of the WCF-BasicHttpRelay Transport Properties is the Security tab. Here you can specify the security
mode. In case you choose Transport than the created channel will be SSL-protected. The endpoint URI scheme in the
address of the endpoint will be https. When setting the mode to None than the scheme will be “http”.
Note: Setting it to none could possibility expose a vulnerability.
The other two modes are Message and TransportWithMessageCredential. In case the messages are encrypted and/or
signed you will choose Message and specify algorithms and/or certificates that apply. With
TransportWithMessageCredential the transport determines the actual mechanism that provides the transport-level
security. For HTTP, the mechanism is Secure Sockets Layer (SSL) over HTTP (HTTPS).
Note: With transport security your security boundary stops at the service bus endpoint, however the message credential
allows you to flow an additional identity on premise for further security purposes.
WCF-BasicHttpRelay Adapter Deep Dive
Figure 4. Specifying the Security settings.
In case you want to enforce that the client authenticates itself to be able to reach your endpoint in Windows Azure you
specify the relay client authentication type by choosing RelayAccessToken. This is the default value. You can choose
None, but then your endpoint is exposed to the public and can be exploited. In case the relay client authentication type
is specified with RelayAccessToken you subsequently have to provide the credentials by selecting edit in the last group
box called Access control service credentials. A dialog will appear where you specify the Access Control Service STS Uri,
Issuer Name and Issuer Key.
Figure 5. Access control service credentials dialog.
These values can be obtained through the Windows Azure Portal (Access Control Service).
Finally you can specify the behavior if the service (endpoint) is published in the Service Registry. By checking the “Enable
service discovery” the Display name text box and Discovery mode combo box will be enabled. In the text box you can
specify the name with which the service (endpoint) is published to the Service Registry. The Discovery mode can be
private or public. Public means publishing in the Service Registry, while private means this will not happen.
Figure 6. Service Registry listing.
As seen above with public the service is discoverable in the service registry of your namespace. Marking it public has
benefits for the operations team and monitoring purposes, but perhaps not for those who want to search for your
service. Note that there is a trade-off here.
The final tab of the WCF-BasicHttpRelay Transport Properties is the Messages tab. In this tab you can specify the data
selection for the SOAP Body element of your incoming messages. Depending on your requirements you can make
changes, for instance suspending the request message on failure in a pipeline.
Figure 7. Specifying messages properties.
WCF-BasicHttpRelay Adapter Deep Dive
Enabling the receive location will result in registration of receive location as an endpoint on Windows Azure Service Bus.
This will be visible in Windows Azure Portal under the Service Bus, your namespace and then connection information.
Figure 8. Access connection information dialog in the Windows Azure Portal.
A basic scenario with the new BizTalk WCF-BasicHttpRelay The following scenario will describe a way to send messages to a Service Bus relay endpoint configured through WCF-
BasicHttpRelay adapter in BizTalk Server 2013.
A message from a client application will be send to registered endpoint in Windows Azure. The communication with the
endpoint in this scenario will be one-way. Therefore the message exchange will be fire-and forget. However, it is also
possible to do two way Synchronous Request-Response. Below you will find a diagram that shows the flow of a message
from the client sending a message to an endpoint registered in Windows Azure Service Bus, which will be relayed through
to BizTalk.
Figure 9. Scenario diagram of basic use case of WCF-BasicHttpRelay
When the receive location is enable you will be able to see that via the portal under the namespace listed under Service
Bus relays.
Figure 10. Relay endpoint is up and running in Windows Azure Service Bus Relays.
Tip: To test your endpoint that is up in the Windows Azure Service Bus you can use the Service Bus Explorer
written by Paolo Salvatori. This will save you time in writing a test client.
WCF-BasicHttpRelay Adapter Deep Dive
How it works As we can see in Figure 11 enabling the receive location will start the process of registering the endpoint. Instead of
listening to the local network port, shared tcp listener or on http.sys it walks up to the service bus namespace and
reserves a name (with scenario in this article the name is ‘data’)(1). The namespace is created through the Windows
Azure Portal. The namespace and the name form a unique name worldwide. Within namespace/name i.e.
tnwiki.servicebus.windows.net/data you can create an entity, which is an endpoint. This is accessible anywhere in world,
while the actual network location is hidden within Windows Azure.
To send a message to that endpoint: a client will create a connection to the frontend node on the service bus, where it
connects to a forwarder (2). The forwarder will communicate with the routing fabric and wants to know who owns the
address (3). It will send a control message to the address that will flow to the receiver (i.e. receive location) and then will
go rendezvous with the forwarder (4). Now the relayed connection is realized and regular web service traffic will flow
through it. It allows tcp, net.tcp or http connections. This capability supports http, https and net.tcp using outbound
connections only. Inbound no firewall ports have to open. Outbound tcp ports firewall are used 9350 – 9354.
Port 9350 Unsecured TCP One-Way(Client)
Port 9351 Secured TCP One-Way (all listeners, secured clients)
Port 9352 Secured TCP Rendezvous (all listeners except One-Way)
Port 9353 Direct Connect Probing Protocol (TCP listeners with direct connect)
If these are not open than that will be detected and fallback on to http will occur. This means a TCP equivalent tunnel
with overlaid TLS/SSL formed over pair of HTTP requests.
Service Bus
Client BizTalk
Forwarder
Ctrl
Ctrl1
2
3
4
Figure 11. The working of the relay service in Windows Azure Service Bus.
You can use Fiddler to monitor the traffic between BizTalk and Service Bus and between the client and the service bus.
Enabling the receive location you will see that first a HTTP connection will be set up by BizTalk Server 2013 to the Access
Control Service.
Figure 12. Fiddler screenshot of connection to the access control service in Windows Azure.
As soon as the connection is established the credentials specified in the security tab of WCF-BasicHttpRelay Transport
Properties will be send to the Access Control Service to authenticate the receive location (listener). BizTalk Server sends
a request (OAuth WRAP Protocol) to ACS using a HTTPS form POST, which contains the following information:
wrap_name: the name of a service identity within the Access Control namespace of the Service Bus Relay Service (see figure 6. e.g. default issuer)
wrap_password: the password of the service identity specified by the wrap_name parameter (see figure 6. e.g. default key)
wrap_scope: this parameter contains the relying party application realm. In our case, it contains the http base address of the Service Bus Relay Service (e.g. http://tnwiki.servicebus.windows.net/)
WCF-BasicHttpRelay Adapter Deep Dive
Figure 13. Fiddler screenshot of request for a token.
The response that is returned (see right side below of the Fiddler screenshot) is the token containing 5 claims and a
signature:
1. net.windows.servicebus.action%3dListen%252cManage%252cSend%26 : The permissions this token grants (in
this case, Listen, Send and Manage)
2. http%253a%252f%252fschemas.microsoft.com%252faccesscontrolservice%252f2010%252f07%252fclaims%25
2fidentityprovider%3dhttps%253a%252f%252ftnwiki-sb.accesscontrol.windows.net%252f%26 : The authority
that actually identified the user (Access Control in this case)
3. Audience%3dhttp%253a%252f%252ftnwiki.servicebus.windows.net%252fdata%252f%26 : The URL that this
token applies to i.e. URI specified in BasicHttpRelay Transport Properties General tab.
4. ExpiresOn%3d1378514166%26 : The time that this token is valid until; expressed as a Unix file time (that is the
number of seconds past January 1, 1970 at 12:00:00 am (UTC))
5. Issuer%3dhttps%253a%252f%252ftnwiki-sb.accesscontrol.windows.net%252f%26 : The Security Token Service
which issued this security token (ACS), this is configured in BasicHttpRelay Transport Properties Security tab
under Access control service credentials.
6. HMACSHA256aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa : The token signature
The values presented in the token can help you to figure out how the receive location was authenticated and which
actions the receive location is permitted to perform.
When you send a message to the service bus using a client for instance the service bus explorer you can also use Fiddler
to monitor the traffic. For a client to send message to relay endpoint in the Windows Azure Service Bus first an outbound
connection must be made. As we can see in the screenshot below, a connection to the Access Control Service is
established first.
Figure 14. Fiddler screenshot of the connection to the Access Control Service.
Subsequently the same credentials as for the receive location will be send to the service bus for authentication.
Figure 15. Fiddler screenshot of request for an access token.
You will receive a token, which is required when sending the message to the endpoint. When you fire up the Service Bus
Explorer you have to connect to your namespace in the Service Bus.
WCF-BasicHttpRelay Adapter Deep Dive
Figure 16. Connect to the Service Bus Namespace using the Service Bus Explorer.
As soon as you’re connected you will see, depending what has been configured within the namespace, queues, topics
and relays.
Figure 17. Service Bus Namespace.
The credentials used to connect to namespace are being used to get the necessary token to send a message to the relay
endpoint: https://tnwiki.servicebus.windows.net/data/, which is the address specified BasicHttpRelay Transport
Properties General tab.
After the token is obtained a connection will be established with tnwiki.servicebus.windows.net. This is the address of
service registry where endpoint resides.
Figure 18. Fiddler screenshot connection setup to service bus namespace.
Finally the message itself will be send.
Figure 19. Fiddler screenshot of message sent to service bus endpoint.
Above you have seen screenshots of traffic between the service bus explorer and the Service Bus. To send the message
using the Service Bus Explorer, you provide the payload in the Message Text area, select the appropriate binding in
Sender Tab and click start to send the message.
WCF-BasicHttpRelay Adapter Deep Dive
Figure 20. Service Bus Explorer send message.
Wrap-up This article demonstrated how you can easily configure a receive location in a port that acts as a listener in the Windows
Azure Service Bus. The registered endpoint can be setup to receive and/or send messages; that is to support 1 way
Asynchronous or 2 way Synchronous Request-Response Interactions.
The benefit of having a listener up in Windows Azure for enterprises is that they will have a secure (through access control
and firewall) and easy way of communication with external services and partners. The cost of such is a listener is low and
easy to maintain. Hosting of the listener is on-premises through BizTalk Server. Thus BizTalk needs to ensure high
availability (i.e. host instance).
The listener can be setup to facilitate in kick starting a process within your enterprise or to collect data from another
system, application or service. The outline in this article can also be easily applied, by using the WCF-NetTcpRelay
adapter instead of the WCF-BasicHttpRelay. The difference between the two are protocol related yet the concepts
remain the same.
WCF-BasicHttpRelay Adapter Deep Dive
Acknowledgements I like to thank the following people for reviewing this article and providing me with some valuable input:
Michael Stephenson, Microsoft Integration MVP
Sandro Pereira, Microsoft Integration MVP
Kent Weare, Microsoft Integration MVP
Edward Bakker, Windows Azure MVP
