Transcription
WCFBasicHTTPRelayDeep DivePublication ofhttp://www.biztalk360.com
About the AuthorWriten By Steef-Jan Wiggers [Microsoft Integration MVP]Steef-Jan is an information architect working for aconsultancy firm in the Netherlands (Inter Access). He hasalmost 15 years’ experience as a technical lead developer,application architect and consultant, specializing incustom applications, enterprise application integration(BizTalk), Web services and Windows Azure. Steef-Jan isvery active in the BizTalk community as a blogger, Wikiauthor/editor, forums, writer and public speaker in the Netherlands andEurope. He has been a BizTalk MVP for 4 years.
WCF-BasicHttpRelay Adapter Deep DiveContentsWCF-BasicHTTPRelay Deep Dive. 0About the Author . 1BizTalk Server 2013: WCF-BasicHttpRelay Adapter . 3Purpose of this document. 4Possible solution architecture using WCF-BasicHttpRelay Adapter in BizTalk Server 2013 . 5WCF-BasicHttpRelay adapter characteristics. 7Configuring the WCF-BasicHttpRelay adapter . 8A basic scenario with the new BizTalk WCF-BasicHttpRelay . 13How it works . 14Wrap-up . 21Acknowledgements . 22
BizTalk Server 2013: WCF-BasicHttpRelay AdapterBizTalk 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 touse the Service Bus Relay. The relay service is one of the entities within the Windows Azure Service Bus. Benefits of usingthe relay service are that: you can share data between an on premise application, Line-of-Business system or databases with a servicehosted elsewhere (in the cloud or other enterprise)you have a secure connection between both sender and receiver of data with simplified networking (less dealingwith 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 WCFBasicHttpRelay or WCF-NetTcpRelay.
WCF-BasicHttpRelay Adapter Deep DivePurpose of this documentThis article will discuss the WCF-BasicHttpRelay adapter, its characteristics, how to configure it, and how to use it withina basic hybrid scenario. You will learn how to setup an endpoint in BizTalk Server without using the BizTalk ServicePublishing Wizard. This is article will strictly confine to BizTalk Server Administration console to configure a receive portwith a location configured with WCF-BasicHttpRelay adapter. Why this can be useful and what happens in thebackground when a message is sent to configured endpoint.
Possible solution architecture using WCF-BasicHttpRelay Adapter inBizTalk Server 2013Below you will find a possible solution architecture, where one enterprise (X) will collect data from another enterprise(Y).Enterprise X5BizTalk ServerReceive PortBasicHttpRelay BindingDatabase ViewRegister Endpoint Issuer Name Issuer SecretRelayAccessToken ScopeHTTPS/SOAPWindows Azure4Relay ServiceToken issuingendpointService Bus3Soap EnvelopeHeader: RelayAccessTokenBody: request payload1Access Control ServiceSoap EnvelopeBody: request payload62 Issuer NameIssuer SecretScopeRelayAccessTokenConnect to ServiceBus NamespaceEnterprise YFigure 1. Sample architecture with a relay between two enterprises.Connection is opened to Access Control Service (ACS) and then authentication credentials using the OAuth WRAPProtocol. 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 andreturns 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 soapenvelope of message it be sending. The body of the message will contain the payload, which can be a query for a databaseview (3).
WCF-BasicHttpRelay Adapter Deep DiveThe Service Bus Relay Service validates and remove the security token from the message and will then forward it to theregistered 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 torelay 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 characteristicsThe WCF-BasicHttpRelay adapter can be used with BizTalk to send and receive messages from the Service Bus relayendpoints using the BasicHttpRelayBinding. This is a binding that BizTalk can use to configure endpoints, which cancommunicate 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.ServiceModelnamespace. The key difference between BasicHttpBinding and its cloud related relative BasicHttpRelayBinding is thatwith the latter you can create an endpoint which can be reachable from outside your organization, by utilizing the AzureService Bus, in a secure way. This endpoint is, if required, a publicly discoverable HTTP listener endpoint listening on theWindows Azure Service Bus. The BasicHttpBinding listens through the standard HTTP.sys listener on the local Windowscomputer.Note: Technically you can expose a BasicHttpBinding endpoint and expose it in a secure way (using SSL, Certs, Firewallsetcetera). However with the BasicHttpRelayBinding the steps required to provide an externally accessible endpoint aresimplified.
WCF-BasicHttpRelay Adapter Deep DiveConfiguring the WCF-BasicHttpRelay adapterWith BizTalk Server 2013 you can easily register an endpoint in the Windows Azure Service Bus. You can create a receiveport and within that port you can create one or more receive locations. The receive location can be configured choosingthe WCF-BasicHttpRelay. You configure the adapter through a dialog WCF-BasicHttpRelay Transport Properties that hasfour tabs.The first tab is named General (see Figure 1). In this tab you can specify the endpoint address that will be registered inthe Windows Azure Service Bus. When specifying the address the "http" or "https" URI scheme can be used dependingon 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-outand encoding-related properties. As seen in the screenshot below (Figure 2), depending on your requirements, you canadjust 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 securitymode. In case you choose Transport than the created channel will be SSL-protected. The endpoint URI scheme in theaddress 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/orsigned you will choose Message and specify algorithms and/or certificates that apply. WithTransportWithMessageCredential the transport determines the actual mechanism that provides the transport-levelsecurity. 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 credentialallows you to flow an additional identity on premise for further security purposes.
WCF-BasicHttpRelay Adapter Deep DiveFigure 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 youspecify the relay client authentication type by choosing RelayAccessToken. This is the default value. You can chooseNone, but then your endpoint is exposed to the public and can be exploited. In case the relay client authentication typeis specified with RelayAccessToken you subsequently have to provide the credentials by selecting edit in the last groupbox 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 “Enableservice discovery” the Display name text box and Discovery mode combo box will be enabled. In the text box you canspecify the name with which the service (endpoint) is published to the Service Registry. The Discovery mode can beprivate 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 hasbenefits for the operations team and monitoring purposes, but perhaps not for those who want to search for yourservice. 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 dataselection for the SOAP Body element of your incoming messages. Depending on your requirements you can makechanges, for instance suspending the request message on failure in a pipeline.Figure 7. Specifying messages properties.
WCF-BasicHttpRelay Adapter Deep DiveEnabling 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-BasicHttpRelayThe following scenario will describe a way to send messages to a Service Bus relay endpoint configured through WCFBasicHttpRelay adapter in BizTalk Server 2013.A message from a client application will be send to registered endpoint in Windows Azure. The communication with theendpoint in this scenario will be one-way. Therefore the message exchange will be fire-and forget. However, it is alsopossible to do two way Synchronous Request-Response. Below you will find a diagram that shows the flow of a messagefrom the client sending a message to an endpoint registered in Windows Azure Service Bus, which will be relayed throughto BizTalk.Figure 9. Scenario diagram of basic use case of WCF-BasicHttpRelayWhen the receive location is enable you will be able to see that via the portal under the namespace listed under ServiceBus 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 Explorerwritten by Paolo Salvatori. This will save you time in writing a test client.
WCF-BasicHttpRelay Adapter Deep DiveHow it worksAs we can see in Figure 11 enabling the receive location will start the process of registering the endpoint. Instead oflistening to the local network port, shared tcp listener or on http.sys it walks up to the service bus namespace andreserves a name (with scenario in this article the name is ‘data’)(1). The namespace is created through the WindowsAzure 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 itconnects to a forwarder (2). The forwarder will communicate with the routing fabric and wants to know who owns theaddress (3). It will send a control message to the address that will flow to the receiver (i.e. receive location) and then willgo rendezvous with the forwarder (4). Now the relayed connection is realized and regular web service traffic will flowthrough it. It allows tcp, net.tcp or http connections. This capability supports http, https and net.tcp using outboundconnections only. Inbound no firewall ports have to open. Outbound tcp ports firewall are used 9350 – 9354.Port 9350Port 9351Port 9352Port 9353Unsecured TCP One-Way(Client)Secured TCP One-Way (all listeners, secured clients)Secured TCP Rendezvous (all listeners except One-Way)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 tunnelwith overlaid TLS/SSL formed over pair of HTTP requests.Service BusCtrl312ForwarderClientCtrl4BizTalkFigure 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 AccessControl 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 TransportProperties will be send to the Access Control Service to authenticate the receive location (listener). BizTalk Server sendsa 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 RelayService (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 httpbase address of the Service Bus Relay Service (e.g. http://tnwiki.servicebus.windows.net/)
WCF-BasicHttpRelay Adapter Deep DiveFigure 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 asignature:1. 252cSend%26 : The permissions this token grants (inthis case, Listen, Send and Manage)2. sscontrol.windows.net%252f%26 : The authoritythat actually identified the user (Access Control in this case)3. ndows.net%252fdata%252f%26 : The URL that thistoken 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 thenumber of seconds past January 1, 1970 at 12:00:00 am (UTC))5. ol.windows.net%252f%26 : The Security Token Servicewhich issued this security token (ACS), this is configured in BasicHttpRelay Transport Properties Security tabunder Access control service credentials.6. HMACSHA256aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa : The token signatureThe values presented in the token can help you to figure out how the receive location was authenticated and whichactions 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 Fiddlerto monitor the traffic. For a client to send message to relay endpoint in the Windows Azure Service Bus first an outboundconnection must be made. As we can see in the screenshot below, a connection to the Access Control Service isestablished 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 BusExplorer you have to connect to your namespace in the Service Bus.
WCF-BasicHttpRelay Adapter Deep DiveFigure 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, topicsand 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 relayendpoint: https://tnwiki.servicebus.windows.net/data/, which is the address specified BasicHttpRelay TransportProperties General tab.After the token is obtained a connection will be established with tnwiki.servicebus.windows.net. This is the address ofservice 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 messageusing the Service Bus Explorer, you provide the payload in the Message Text area, select the appropriate binding inSender Tab and click start to send the message.
WCF-BasicHttpRelay Adapter Deep DiveFigure 20. Service Bus Explorer send message.
Wrap-upThis article demonstrated how you can easily configure a receive location in a port that acts as a listener in the WindowsAzure Service Bus. The registered endpoint can be setup to receive and/or send messages; that is to support 1 wayAsynchronous 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 controland firewall) and easy way of communication with external services and partners. The cost of such is a listener is low andeasy to maintain. Hosting of the listener is on-premises through BizTalk Server. Thus BizTalk needs to ensure highavailability (i.e. host instance).The listener can be setup to facilitate in kick starting a process within your enterprise or to collect data from anothersystem, application or service. The outline in this article can also be easily applied, by using the WCF-NetTcpRelayadapter instead of the WCF-BasicHttpRelay. The difference between the two are protocol related yet the conceptsremain the same.
WCF-BasicHttpRelay Adapter Deep DiveAcknowledgementsI like to thank the following people for reviewing this article and providing me with some valuable input: Michael Stephenson, Microsoft Integration MVPSandro Pereira, Microsoft Integration MVPKent Weare, Microsoft Integration MVPEdward Bakker, Windows Azure MVP
With BizTalk Server 2013 you can easily register an endpoint in the Windows Azure Service Bus. You can create a receive . (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 .
