Quick Links

Overview

The Microsoft .NET Service Bus provides a range of unidirectional and bidirectional, peer-to-peer connectivity options for NAT and Firewall traversal and Internet-scope event distribution. The Service Bus covers four logical feature areas: Naming, Service Registry, Connectivity, and Eventing.

Naming

The Service Bus Naming system is a forest of federated naming trees. The Naming system maintains an independent naming tree for each tenant’s solution scope, and the solution determines how to shape its tree. The Service Bus Naming system provides an endpoint-level naming system for services that complements DNS.

The Internet’s Domain Name System (DNS) is a naming system primarily optimized for assigning names and roles to hosts. The registration records either provide a simple association of names and IP addresses or a more granular association of particular protocol roles (such as identifying a domain’s mail server) with an IP address. In either case, the resolution of the DNS model is at the IP address level, which is very coarse grained. A DNS registration is IP-address-centric, so it requires a public IP address. Systems behind NAT cannot participate. Even though Dynamic DNS services can provide names to systems that do have a public IP address, relying on DNS means for most ISP customers that the entire business site or home is identified by a single DNS host entry with dozens or hundreds of hosts sitting behind the NAT device.

If you want to uniquely name individual hosts behind NATs, differentiate between individual services on hosts, or name services based on host-independent criteria (such as the name of a user or tenant), the DNS system is not an ideal fit.

The Service Bus naming system is DNS integrated with the root of the naming tree being resolvable through DNS. Any path through a naming tree has a projection that directly maps to a URI. 

Assume you design a logistics system for a trucking company where you need to route information to service instances at particular sites. The solution scope's owner is the company ContosoTrucks, which has a number of logistics centers where they want to deploy the application. Your application is called Shipping and the endpoints through which the shipping orders are received at the individual sites are named OrderManagement.

The canonical URI projection of the mapping of New York’s order management application endpoint instance into the Service Bus Naming system might be http://contoso.servicebus.windows.net/NewYork/Shipping/OrderManagement/, whereby "contoso" is the solution name.

Note: For the PDC Community Technology Preview, the URI projection still differs from the described canonical form. In this release, the solution name is mapped into the URI as a segment http://servicebus.windows.net/service/[solution]/[user-namespace...]. Therefore, the correct URI for .NET Services December 2008 CTP for the above example is http://servicebus.windows.net/services/contoso/NewYork/Shipping/OrderManagement/.

The significant difference from DNS naming is that the identification of services and endpoints moves from the host portion of the URI to the path portion and becomes entirely host-agnostic. The DNS name identifies the scope and the entry point for accessing the naming tree. That also means that the path portion of the URI represent a potentially broadly distributed federation of services in the Naming service that are mapped into the naming structure from different locations, while the path portion of a normal URI typically designates a narrowly collocated set of resources.

There is no immediate access API for the Naming system itself. Instead, access to the Naming system is provided through the overlaid Service Registry.

Service Registry

The Service Registry allows publishing service endpoint references (URIs or WS-Addressing EPRs) into the Naming system and to discover services that have been registered. The primary external access mechanism for the Service Registry is based on the Atom Publishing Protocol (APP), allowing clients to publish URIs or EPRs by sending a simple HTTP PUT request with an Atom 1.0 entry to any name in the naming tree. It is removed by sending an HTTP DELETE request to the same name. There is no need to explicitly manage names—names are automatically created and deleted as you create or delete service registry entries.

Service discovery is performed by navigating the naming hierarchy, which is accessible through a nested tree of Atom 1.0 feeds whose root-feed is located at http://servicebus.windows.net/services/[solution]/ for any solution.

In addition to the Atom Publishing Protocol, the Service Registry also supports publishing, accessing, and removing endpoint references using WS-Transfer, and the Relay service will automatically manage its endpoints in the Service Registry without requiring any additional steps. The Service Registry is an area that will see significant further additions over the next few releases including support for service categorization, search across the hierarchy, and additional high-fidelity discovery protocols.

Most commonly, though, the Service Registry is automatically populated by creating listening services in the Service Bus Relay.

Connectivity

The core of the connectivity feature area of the Service Bus is a scalable, general-purpose Relay service. The Relay’s communication fabric supports unicast and multicast datagram distribution, connection-oriented bidirectional socket communication, and request-response messaging.

Toward listening services, the Relay takes on the same role as operating-system-provided listeners, such as Windows’ HTTP.SYS. Instead of listening for HTTP requests locally, a relayed HTTP service establishes an HTTP listener endpoint inside the cloud-based Relay, and clients send requests to that cloud-based listener, from where they are forwarded to the listening service.

The connection between any listener and the Relay is always initiated from the listener side. In most connection modes, the listener initiates a secured outbound TCP socket connection into the Relay, authenticates, and then tells the Relay at which place in the naming tree it wants to start listening and what type of listener should be established.

Since a number of tightly managed networking environments block outbound socket connections and permit only outbound HTTP traffic, the socket-based listeners are complemented by an HTTP-based multiplexing polling mechanism that builds on a cloud-based message buffer. In the PDC release, the HTTP-based listeners support only the unicast and multicast datagram communication, but bidirectional connectivity is easily achievable by pairing two unicast connections with mutually reversed client and listener roles (see Creating a Composite Duplex Binding Over Oneway).

A special variation of the bidirectional socket communication mode is Direct Connect. The Direct Connect NAT traversal technology is capable of negotiating direct end-to-end socket connections between arbitrary endpoints even if both endpoints are located behind NAT devices and Firewalls. Using Direct Connect, you can start connections through the Relay, and Direct Connect will negotiate the most direct possible connectivity route between the two parties. After the route is established, the connection will be upgraded to the direct connection—without information loss (see NetTcpRelayBinding).

With these connectivity options, the Relay can provide public, bidirectional connectivity to almost any service, regardless of whether the hosting machine is located behind a NAT or whether the Firewalls layered up towards the public network do not allow inbound traffic. The automatic mapping into the Naming system means that the service also gains a public address and the service can, on demand, be automatically published into the Service Registry to make the service discoverable.

In addition to providing NAT and Firewall traversal and discoverability, the delegation of the public network endpoint into the Relay provides a service with a number of additional key advantages that are beneficial even if NAT traversal or discoverability are not an immediate challenge:

• The Relay functions as a perimeter network (also known as DMZ, demilitarized zone, and screened subnet) that is isolated from the service’s environment and takes on all external network traffic, filtering out unwanted traffic.

• The Relay anonymizes the listener and therefore effectively hides all details about the network location of the listener, thus reducing the potential attack surface of the listening service to a minimum.

• The Relay is integrated with the Access Control Service and can require clients to authenticate and be authorized at the Relay before they can connect through to the listening service. This authorization gate is enabled by default for all connections and can be selectively turned off if the application wants to perform its own authentication and authorization.

These points are important to consider in case you are worried about the fact that the Relay service provides Firewall traversal. Firewalls are a means to prevent undesired foreign access to networked resources—the Relay provides a very similar function but does so on an endpoint-by-endpoint basis and provides an authentication and authorization mechanism on the network path as well.

If your applications are already built on the .NET Framework and your services are built using the Windows Communication Foundation (WCF), it is often just a matter of changing your application’s configuration settings to have your services listen on the Relay instead on the local machine.

The Microsoft.ServiceBus client framework provides a set of WCF bindings that are very closely aligned with the WCF bindings available in the .NET Framework 3.5. If you are using the NetTcpBinding in your application, you switch to the NetTcpRelayBinding, the BasicHttpBinding maps to the BasicHttpRelayBinding, and the WebHttpBinding has its equivalent in the WebHttpRelayBinding. The key difference between the standards WCF bindings and their Relay counterparts is that they establish a listener in the cloud instead of listening locally.

All WS-Security and WS-ReliableMessaging scenarios that are supported by the standard bindings are fully supported through the Relay. Transport-level message protection using HTTPS or SSL-protected TCP connections is supported as well.

If the listener chooses to rely on WS-Security to perform its own authentication and authorization instead of using the security gate built into the Relay, the HTTP-based Relay bindings’ policy projection is indeed identical to their respective standard binding counterparts, which means that client components can readily use the standard .NET Framework 3.5 bindings (and other WS-* stacks, such as Sun Microsystems’ Metro Extensions for the Java JAX-WS framework).

If you prefer RESTful services over SOAP services, you can build them on the WebHttpRelayBinding using the WCF Web programming model introduced in the .NET Framework 3.5.

The Relay knows how to route SOAP 1.1, SOAP 1.2 messages, and HTTP requests transparently.

Eventing

The NetEventRelayBinding does not have an exact counterpart in the standard bindings.

This binding provides access to the multicast eventing capability in the Service Bus. Using this binding, clients act as event publishers and listeners act as subscribers. An event-topic is represented by an agreed-upon name in the naming system. There can be any number of publishers, and any number of subscribers that use the respective named rendezvous point in the Relay.

Listeners can subscribe independent of whether a publisher currently maintains an open connection, and publishers can publish messages regardless of how many listeners are currently active—including zero. The result is a very easy to use, lightweight, one-way rendezvous event distribution mechanism that does not require any particular setup or management.

Organizing Namespaces

The listener URIs generally have the form http://servicebus.windows.net/services/<solution>/endpoint/  whereby <solution> is the name of the solution account of the listening service. The endpoint portion of URI can be organized as seems appropriate for the solution and is not restricted to a single segment. A solution might organize endpoints by  modules, services, and endpoints, thus probably hosting listeners at ./Sales/Leads/ManageLeads/,  ./Sales/Leads/Statistics/, or ./OrderProcessing/Inbox/. Some other solution might organize endpoints by location, user, device, or other criteria.

If a listener is opened on a URI that is already used by some other listener, opening the listener fails. In particular, a listener cannot be opened within the URI scope of another listener. If there is a listener on ./Sales/Leads/ you cannot open an additional listener on any suffix of that scope, for example, at ./Sales/Leads/Statistics/. Messages are routed to services using a longest-prefix-match algorithm, allowing services to receive messages where the service wants to evaluate the URI suffix directly. Thus, any two listener URIs can share a common prefix, but neither URI must be a prefix of the other.

NAT and Firewall Traversal

Whenever a service endpoint is opened using any of the WCF bindings provided in the Microsoft.ServiceBus namespace, the listener establishes an outbound-only connection to the cloud-based Service Bus, creating a cloud-based listener that resides at the selected URI in the solution namespace. To establish the listener connection(s), most Microsoft.ServiceBus bindings require TCP ports 808, 818, 819, and 828 to be opened for outbound traffic on the Firewall(s) towards your Internet gateway. Exceptions are the NetEventRelayBinding and NetOnewayRelayBinding, which can optionally communicate relying solely on ports 80 and 443.

You do not have to open any inbound ports on your firewall or perform any kind of port mapping on your NAT/Router device.  

Service Bus Bindings

This section provides detailed information about the Windows Communication Foundation Binding Classes included in the .NET Services December 2008 CTP for the Service Bus. The Bindings covered in this section are:

• BasicHttpRelayBinding
• NetEventRelayBinding
• NetOnewayRelayBinding
• NetTcpRelayBinding
• WebHttpRelayBinding
• WS2007HttpRelayBinding
• WSHttpRelayBinding

We recommend that you prefer the NetTcpRelayBinding for most solution scenarios. This binding uses the .NET Binary wire representation and is based on a highly efficient connection-oriented communication path through the Service Bus infrastructure that yields the highest throughout of all available bindings with the lowest processing overhead on the listening service.

The HTTP-based bindings (BasicHttpRelayBinding, WebHttpRelayBinding, WS2007HttpRelayBinding, WSHttpRelayBinding) provide the highest degree of interoperability with external clients since they provide services with an HTTP listener in the Service Bus fabric that supports SOAP 1.1, SOAP 1.2, and HTTP messages, but they have a comparatively larger processing overhead on the listening service. To provide the desired NAT/Firewall traversal, services must establish outbound rendezvous connections with the Service Bus for requests whenever no keep-alive connection is available.

Note: In the .NET Services December 2008 CTP, the HTTP connection path is optimized for transferring larger payloads with moderate message request rates because it is common for Web Services scenarios, and not for high-request-rate scenarios as is common for HTML Web site scenarios.

The NetOnewayRelayBinding provides the most aggressive NAT/Firewall traversal options because it features an optional HTTP connectivity mode (also see ConnectivitySettings) that enables it to listen for messages using the standard TCP ports 80 and 443 using a fully HTTP 1.1-compliant polling mode that is backed by Service Bus hosted message buffering infrastructure. Unless you need these extended NAT/Firewall traversal capabilities (as is the case in some very tightly managed corporate networking environments), the NetTcpRelayBinding should be the preferred choice even for one-way communication due to its higher efficiency.

The NetEventRelayBinding provides the same aggressive NAT/Firewall traversal options as the NetOnewayRelayBinding and additionally provides a unique multicast event distribution capability that is further discussed in its description below.

Note: For the .NET Services December 2008 CTP, the optimization focus for this binding is on application integration scenarios with a relatively small number of event subscribers (up to 10), not on consumer scenarios with significantly larger subscriber numbers.

Note: For the .NET Services December 2008 CTP, all solutions are throttled to at most five (5) concurrently listening endpoints.

BasicHttpRelayBinding

The BasicHttpRelayBinding is closely aligned with the standard BasicHttpBinding in the .NET Framework. The key difference between the standard BasicHttpBinding and the BasicHttpRelayBinding is that the Relay variant creates publicly reachable and, if desired, publicly discoverable HTTP listener endpoint listening on the cloud-based Service Bus, while the standard binding listens through the standard HTTP.sys listener on the local Windows machine.

With its default settings, the BasicHttpRelayBinding supports SOAP 1.1 messaging conforming to the WS-I Basic profile 1.1.

Services using the BasicHttpRelayBinding are registering their endpoints on the Service Bus using the "http" or "https" URI scheme. Client channels created using the BasicHttpRelayBinding use HTTP/HTTPS on the default TCP ports 80 and 443 as the transport mechanism to talk to the respective endpoint in the Service Bus cloud. Service listeners created using this binding are using a pair of TCP socket connections to the cloud-based listener. The SSL-protected control channel is using outbound TCP port 828, and the data channel is using outbound port 818. The data channel is SSL-protected if the endpoint URI scheme is "https" and the Security.Mode property is set to one of the EndToEndBasicHttpSecurityMode values Transport or TransportWithMessageCredential.

For this CTP release, refer to BasicHttpBinding in the Windows Communication Foundation  documentation for the majority of the settings.

The BasicHttpRelayBinding does not support the following properties (and corresponding configuration settings) of the BasicHttpBinding.

The following table lists newly introduced members for the BasicHttpRelayBinding.

NetEventRelayBinding

The NetEventRelayBinding has no directly corresponding binding in the .NET Framework. The binding supports one-way multicast eventing and allows N event publishers and M event consumers to rendezvous at the same endpoint.   

The NetEventRelayBinding shares much of its underlying infrastructure with the NetOnewayRelayBinding. For information about the connectivity options, see the NetOnewayRelayBinding section in this document.

Unlike any of the other Relay bindings, the NetEventRelayBinding supports multiple listeners on the same URI. To set up an event rendezvous point (also called topic), the clients and listeners merely need to agree on a shared URI within the scope of a solution and send to or listen on it. Messages that get sent by any of the clients get distributed to all listeners.

Note: For the .NET Services December 2008 CTP, the number of listeners is constrained to fit departmental scenarios with fewer than 20 concurrent listeners. Messages sent through this binding are constrained to at most 60KB in wire size.

There are no assurances about messages arriving in sequence or being delivered at all. The delivery guarantees are thus somewhat similar to UDP multicast, even though the NetEventRelayBinding is not quite as prone to message loss as UDP is, because the message routing into and out of the cloud-based event distribution fabric is performed over TCP.  

With its default settings, the NetEventRelayBinding supports SOAP 1.2 messaging over TCP using .NET Framing and .NET Binary Serialization.

Services and Clients using the NetTcpRelayBinding are registering their endpoints on the Service Bus using the "sb" URI scheme, regardless of the active connectivity mode.

The channel is SSL-protected if the Security.Mode property is set to one of the EndToEndSecurityMode values Transport or TransportWithMessageCredential.

The transport channel protection guards all traffic to and from the Relay, but the data is visible to (but not observed by) the Service Bus infrastructure at the socket relay point. You can employ message security (Security.Mode=EndToEndSecurityMode.Message) to ensure that payload data is protected end-to-end without ever becoming visible to a third party (including the Service Bus infrastructure) at any waypoint. However, when using message security, all receivers must share the same service identity.

The following table lists the NetEventRelayBinding members.

NetOnewayRelayBinding

The NetOnewayRelayBinding has no directly corresponding binding in the .NET Framework. As a one-way only binding, it is similar to the NetMsmqBinding from which it borrows its security options. Its communication path is TCP based without durability on the message path, however, and thus a range of options are similar to the NetTcpBinding.

The NetOnewayRelayBinding is the most constrained of all the Relay bindings because it supports only one-way messages. At the same time, it is also the binding that is most successful at providing listeners with an inbound communication path because it supports listeners to acquire messages destined for them though TCP and HTTP. For information about how to create a bidirectional communication path on top of the one-way primitives, see the discussion of OnewayRelayTransportBindingElement.

With its default settings, the NetOnewayRelayBinding supports SOAP 1.2 messaging over TCP using .NET Framing and .NET Binary Serialization.

Note: For the .NET Services December 2008 CTP, messages sent through this binding are constrained to at most 60KB in wire size.

The NetOnewayRelayBinding has three different connectivity options that can be set only at the Application Domain scope through the ServiceBusEnvironment.OnewayConnectivity property. The three connectivity options are shared by all services and channels using the binding. Be aware that all other bindings use the NetOnewayRelayBinding under the covers for control connections. For a detailed discussion of all connectivity options, see the ServiceBusEnvironment reference section.

• ConnectivityMode.Tcp: In this mode, all one-way and event communication is relayed over outbound TCP ports 828 and 808. SSL-secured traffic uses port 828, while unsecured traffic uses port 808.

• ConnectivityMode.Http: In this mode, all one-way and event communication is relayed over outbound ports 80 and 443 using HTTP or HTTPS. This mode is the backup communication option for environments where outbound communication is constrained to HTTP/HTTPS, where outbound ports 808 and 828 are not available, or where the service/client cannot resolve external DNS names. For more information about this mode, see the ServiceBusEnvironment section.

• ConnectivityMode.AutoDetect: This mode automatically selects between the ConnectivityMode.Tcp and ConnectivityMode.Http, and favors TCP if it is available.

Services and Clients using the NetTcpRelayBinding are registering their endpoints on the Service Bus using the "sb" URI scheme, regardless of the active connectivity mode.

The channel is SSL-protected if the Security.Mode property is set to one of the EndToEndSecurityMode values Transport or TransportWithMessageCredential.

The transport channel protection guards all traffic to and from the Relay, but the data is visible to (but not observed by) the Service Bus infrastructure at the socket relay point. You can employ message security (Security.Mode=EndToEndSecurityMode.Message) to ensure that payload data is protected end-to-end without ever becoming visible to a third party (including the Service Bus infrastructure) at any waypoint. 

The following table lists the NetOnewayRelayBinding members.

NetTcpRelayBinding

The NetTcpRelayBinding is closely aligned with the standard NetTcpBinding from the .NET Framework. The key difference between the standard NetTcpBinding and the NetTcpRelayBinding is that the Relay variant creates publicly reachable and, if desired, publicly discoverable TCP listener endpoint listening in the Service Bus fabric while the standard binding listens on a local TCP socket.

With its default settings, the NetTcpRelayBinding supports SOAP 1.2 messaging over TCP using .NET Framing and .NET Binary Serialization. The underlying TCP socket layer is different from the standard NetTcp bindings and, even though the characteristics are very similar, the wire projections of the NetTcpBinding and NetTcpRelayBinding are not directly compatible. 

The NetTcpRelayBinding has three different connection modes that can be set through the ConnectionMode property:

• TcpConnectionMode.Relayed: In this mode, all communication is relayed through the Service Bus cloud. The SSL-protected control connection is used to negotiate a relayed end-to-end socket connection that all Client-Service communication flows through. After the connection is established, the Service Bus infrastructure acts much like a socket forwarder proxy relaying a bidirectional byte stream.

• TcpConnectionMode.Hybrid: In this mode, communication is relayed through the Service Bus infrastructure while the Client and Service endpoints negotiate a direct socket connection to each other. The coordination of this direct connection is governed by the Service Bus cloud service. The direct socket connection algorithm is capable of establishing direct connections between two parties that sit behind opposing Firewalls and NAT devices. The algorithm uses only outbound connections for Firewall traversal and relies on a mutual port prediction algorithm for NAT traversal. Since the NAT traversal algorithm is dependent on a very narrowly timed coordination and a best-guess prediction about the expected NAT behavior, the algorithm tends to have a very high success rate for Home and Small Business scenarios with a small number of clients and degrades in its success rate with larger NATs. If a direct connection can be established, the relayed connection is automatically upgraded to the direct connection without message or data loss. If the direct connection cannot be established, data will continue to flow through the Service Bus Relay.

• TcpConnectionMode.Direct: This mode is identical to TcpConnectionMode.Hybrid in the .NET Services December 2008 CTP. In a future release, this mode will use the direct connection only once and, if established, never relay any application data through the Service Bus Relay.

Services using the NetTcpRelayBinding are registering their endpoints on the Service Bus using the "sb" URI scheme. Clients and service listeners created using this binding are each using a pair of TCP socket connections to the cloud-based listener. The SSL-protected control channel is using outbound TCP port 828, while the data channel is using outbound port 818.

The TcpConnectionMode.Hybrid/Direct modes additionally require outbound port 819 for the NAT prediction algorithm. With most personal firewall products, the outbound socket connection that is being established by the direct connect mode will also require a one-time policy exception to be granted by the user (the Windows Personal Firewall and other products will typically prompt the user) to the hosting application.

In TcpConnectionMode.Relayed (the default), the data channel is SSL-protected if the Security.Mode property is set to one of the EndToEndSecurityMode values Transport or TransportWithMessageCredential. Transport-level channel protection is not available in the Hybrid/Direct modes.

The transport channel protection guards all traffic to and from the Relay, but the data is visible to (but not observed by) the Service Bus infrastructure at the socket relay point. You can employ message security (Security.Mode=EndToEndSecurityMode.Message) to ensure that payload data is protected end-to-end without ever becoming visible to a third party (including the Service Bus infrastructure) at any waypoint. 

Even though the combination is not explicitly disabled, the TcpConnectionMode.Hybrid/Direct modes are currently (in this CTP) not correctly supporting WS-ReliableMessaging on the channel (which is enabled by, setting the ReliableSession property flag).  

For this CTP release, see NetTcpBinding in the Windows Communication Foundation documentation for the majority of the settings. The NetTcpRelayBinding does not support the following properties (and corresponding configuration settings) of the NetTcpBinding.

The following table lists newly introduced members for the NetTcpRelayBinding.

WebHttpRelayBinding

The WebHttpRelayBinding is very closely aligned with the standard WebHttpBinding in the .NET Framework 3.5. The key difference between the standard WebHttpBinding and the WebHttpRelayBinding is that the Relay variant creates publicly reachable and, if desired, publicly discoverable HTTP listener endpoint listening on the cloud-based Service Bus, while the standard binding listens through the standard HTTP.sys listener on the local Windows machine.

With its default settings, the WebHttpRelayBinding supports plain HTTP messages with support for XML and Raw (binary) message encodings.

Services using the WebHttpRelayBinding are registering their endpoints on the Service Bus using the "http" or "https" URI scheme. Client channels created using the WebHttpRelayBinding use HTTP/HTTPS on the default TCP ports 80 and 443 as the transport mechanism to talk to the respective endpoint in the Service Bus cloud. Service listeners created using this binding are using a pair of TCP socket connections to the cloud-based listener. The SSL-protected control channel is using outbound TCP port 828, while the data channel is using outbound port 818. The data channel is SSL-protected if the endpoint URI scheme is "https" and the Security.Mode property is set to EndToEndWebHttpSecurityMode.Transport.

The WebHttpRelayBinding is compatible with the WCF Web Programming Model and the WebServiceHost.  In this CTP, the WebHttpRelayBinding is not fully compatible with the WebScriptEnablingBehavior that autogenerates JavaScript proxy objects at run time. The special endpoint for the JavaScript proxy is not reachable through the Service Bus Relay at this time.

For this CTP release, see WebHttpBinding in the Windows Communication Foundation documentation for the majority of the settings. The WSHttpRelayBinding does not support the following properties (and corresponding configuration settings) of the WebHttpBinding.

The following table lists newly introduced members for the WebHttpRelayBinding.

WS2007HttpRelayBinding

The WS2007HttpRelayBinding is very closely aligned with the standard WS2007HttpBinding in the .NET Framework 3.5 that supersedes the WSHttpBinding with updated standards support. The key difference between the standard WS2007HttpBinding and the WS2007HttpRelayBinding is that the Relay variant creates publicly reachable and, if desired, publicly discoverable HTTP listener endpoint listening on the cloud-based Service Bus, while the standard binding listens through the standard HTTP.sys listener on the local Windows machine.

With its default settings, the WS2007HttpRelayBinding supports SOAP 1.2 messaging with the latest OASIS standards for Reliable Message Exchange and Security.

Services using the WS2007HttpRelayBinding are registering their endpoints on the Service Bus using the "http" or "https" URI scheme. Client channels created using the WS2007HttpRelayBinding use HTTP or HTTPS on the default TCP ports 80 and 443 as the transport mechanism to talk to the respective endpoint in the Service Bus cloud. Service listeners created using this binding are using a pair of TCP socket connections to the cloud-based listener. The SSL-protected control channel is using outbound TCP port 828, while the data channel is using outbound port 818. The data channel is SSL-protected if the endpoint URI scheme is "https" and the Security.Mode property is set to one of the EndToEndSecurityMode values Transport or TransportWithMessageCredential.

For this CTP release, see WS2007HttpBinding in the Windows Communication Foundation documentation for the majority of the settings. The following table lists the properties of the WSHttpBinding that WSHttpRelayBinding does not support.

The following table lists newly introduced members for the WS2007HttpRelayBinding.

WSHttpRelayBinding

The WSHttpRelayBinding is very closely aligned with the standard WSHttpBinding from the .NET Framework. The key difference between the standard WSHttpBinding and the WSHttpRelayBinding is that the Relay variant creates publicly reachable and, if desired, publicly discoverable HTTP listener endpoint listening on the cloud-based Service Bus, while the standard binding listens through the standard HTTP.sys listener on the local Windows machine.

With its default settings, the WSHttpRelayBinding supports SOAP 1.2 messaging with the draft WS-* standards for Reliable Message Exchange and Security that were available at the release of WCF 3.0. 

Services using the WSHttpRelayBinding are registering their endpoints on the Service Bus using the "http" or "https" URI scheme. Client channels created using the WSHttpRelayBinding use HTTP or HTTPS on the default TCP ports 80 and 443 as the transport mechanism to talk to the respective endpoint in the Service Bus cloud. Service listeners created using this binding are using a pair of TCP socket connections to the cloud-based listener. The SSL-protected control channel is using outbound TCP port 828, while the data channel is using outbound port 818. The data channel is SSL-protected if the endpoint URI scheme is "https" and the Security.Mode property is set to one of the EndToEndSecurityMode values Transport or TransportWithMessageCredential.

For this CTP release, see WSHttpBinding in the Windows Communication Foundation documentation for the majority of the settings. The following table list the properties (and corresponding configuration settings) of WSHttpBinding that WSHttpRelayBinding does not support.

The following table lists newly introduced members for the WSHttpRelayBinding.

Relay Authentication

The Service Bus requires all listeners and most clients (for all bindings) to be authenticated and authorized for accessing the namespace in which they want open an endpoint. Authentication and authorizations are two distinct steps; however, to simplify the majority of use cases, the Service Bus programming model does not make this obvious.

The authentication step is performed against an Identity Provider that is trusted by the Microsoft .NET Services Access Control Service. The Access Control Service itself directly embeds an Identity Provider for solution accounts, which is the Identity Provider that is used in the vast majority of the samples in the Microsoft .NET Services SDK, which makes the authentication and authorization look like a single step.

In more sophisticated scenarios, however, the Access Control service for a particular solution will be set up to trust additional Identity Providers. The Access Control service implicitly trusts Windows Live ID as an Identity Provider, allowing the creation of access control rules that grant access to particular Windows Live IDs to a particular solution. Using the next-generation Active Directory Federation Services (code-named "Geneva"), corporations can federate Active Directory security groups, with the Access Control service allowing the creation of access control rules based on Active Directory access control data. The Access Control service can simultaneously federate with multiple Identity Providers, and can thus act as centrally managed access control authority.

Like any other service can be set up to trust the Access Control service to act as a federated access control clearing house, the Service Bus leverages this capability by trusting tokens issued by the Access Control service as authorization tokens.

A client can present either a solution credential or a security token issued by a trusted Identity Provider to the Access Control service. Based on the verification of the identity claim conveyed by the credential or the claims carried in the token issued by the external Identity Provider, the Access Control service makes a rules-driven decision on whether to issue an authorization token to the target service—in this case, the Service Bus.

If the requestor is authorized to acquire the token, it will be issued by the Access Control service to the Service Bus. The requestor merely acts as the courier between the services, acquiring the token and passing the token on to the target service. Except for very few data items that are of immediate importance to token handling on the requestor side (such as expiration times that allow for managing caches), all contents of the token are signed and encrypted for the exclusive use by the target service. Only the target service is able to decrypt the token, and it will verify the signature of the token to ensure that the token was issued by an Access Control provider it trusts.

TransportClientEndpointBehavior

The TransportClientEndpointBehavior is a WCF endpoint behavior that is used to specify the Service Bus credentials for a particular endpoint. Instances of this behavior are shareable across endpoints so that the descriptions of multiple endpoints (listener and channels) using the same Service Bus credentials can be populated with the same configured instance of this class.

The behavior can be defined and applied to endpoints in code and in configuration files.

For illustrations of how to apply this behavior in code and configuration, see the following samples:

• Relay Authentication with CardSpace Credential (in the Getting Started sample)
• Relay Authentication with AutomaticRenewal Credential
• Relay Authentication With Username Password Credential
• Relay Authentication With X.509 Certificate

RelayClientAuthenticationType Enumeration

The RelayClientAuthenticationType enumeration is referenced from the security settings in all of the Relay bindings. The use of this property is identical across all bindings. The following table lists the possible values for this enumeration.

Choosing between the options also directly affects how much a service can learn about the identity of the caller. When the RelayAccessToken option is chosen, all access control management is effectively delegated to the Access Control service. Since the Access Control service will yield an access control token for the Relay that indicates whether the requestor can listen on or send to the relay (or both) but protects the actual identity of the caller, the listening service will not be able to gather any user-specific information. The service is effectively operating in anonymous authentication mode trusting the Access Control service.

The None option causes the Relay to pass all traffic to the service, which enables the service to perform all access control locally and perform fine-grained access control depending on business data, local credentials stores, or other criteria—but it potentially exposes the service to unwanted traffic.

The hybrid solution is to combine the RelayAccessToken option with end-to-end message security, which is an option supported by most bindings. In this combination, the client is required to provide two separate credentials: One via TransportClientEndpointBehavior for gaining access to the service through the Service Bus, and the second one specified on the regular ClientCredentials property of the ChannelFactory, which is used to secure the end-to-end communication path. The latter credential can be a token issued by the Access Control service for the solution's own scope.

Web-Style (REST) Authentication

In the .NET Services December 2008 CTP, the Relay authentication options for Web clients accessing services built on the WebHttpRelayBinding are significantly more limited; these options will be expanded significantly in the near future. 

Most commonly, Web-style clients talk to services that choose to accept all incoming traffic and perform only lightweight authentication using a variety of custom techniques to enable and enrich AJAX-style user experiences. You can achieve the same and provide similar fidelity by setting the Security.Transport.RelayAuthenticationType property on the WebHttpRelayBinding to RelayClientAuthenticationType.None.

If you choose the RelayClientAuthenticationType.RelayAccessToken option, the Service Bus Relay provides a defense layer over plain HTTP services that require authentication and authorization to be performed before any HTTP traffic is forwarded to the listening service. If Relay authentication is enabled on the Service Bus, the required security token can be provided in one of two ways: interactive credentials or programmatic credentials.

Interactive Credentials

When the service policy requires authentication by setting the Security.Transport.RelayAuthenticationType property on the WebHttpRelayBinding to RelayClientAuthenticationType.RelayAccessToken and an interactive browser client issues a HTTP request to the service without providing any authentication information (such as a previously set cookie), the Service Bus will intercept the HTTP request and redirect the request to an interactive login page. The interactive login page accepts CardSpace or UserName credentials that have been associated directly with the solution account. Note that this interactive login implementation is scheduled to be replaced in a post-PDC release and will allow using federation of identity providers and their respective interactive login sites.

Programmatic Credentials

For programmatic access to secured Web-Style HTTP services, the Access Control Service provides a simple endpoint supporting UserName credentials to acquire a token that is accepted by the Relay for these types of requests. This endpoint accepts only a .NET Services Solution Credential at this time and is thus suitable only for local experimentation and not for inclusion into client-side Web applications that could easily expose those credentials or the acquired token.

Note: Along with the interactive credentials mechanism explained above, this is a temporary implementation for the .NET Services December 2008 CTP and will be superseded in a release in the near future.

With the temporary endpoint, tokens for accessing the Service Bus are acquired using a simple HTTP GET on:

 https://accesscontrol.[replaceme].com/issuetoken.aspx?u={solution-name}&p={solution-password}

The request's reply does not contain the actual security token, but rather a reference cookie to the actual token that is held by the Access Control service on behalf of the requesting client. The cookie is returned with a text/plain content type.

To use the cookie against the Relay, the client needs to read the reply content as a string value add a custom HTTP header named "X-MS-Identity-Token" to each request with the value of this reference cookie.

Note: We strongly recommend that you enable transport security on the WebHttpBinding by setting the Security.Mode property to EndToEndWebHttpSecurityMode.Transport and using the https scheme for the URIs. This will force the client to use HTTPS for all requests and thus protect the reference cookie on the wire.

Name and Service Settings

The NameSettings endpoint behavior and the related ServiceSettings class provide endpoint listeners with control over how and whether a given endpoint is published in the Service Registry. By default, all endpoints are "cloaked" and will not be visible in the Service Registry's ATOM feed.

If you want to publish an endpoint into the Service Registry, you need to create an instance of the NameSettings behavior and add it to the description of the respective endpoint.

The tables below lists only the public properties that are effective when used from the .NET programming model. All other values will be overwritten or are otherwise ineffective when used with any of the WCF bindings.

The following table describes the single effective ServiceSettings property.

Service Bus Environment Settings  

ServiceBusEnvironment

ServiceBusEnvironment is a static class that provides access to common environment parameters. It provides information about the current host names for the Service Bus and Access Control endpoints and to the globally effective ConnectivitySettings for all NetOnewayRelayBinding- and NetEventRelayBinding-based endpoints that are active in the current application domain.

ConnectivitySettings

The ConnectivitySettings class holds the settings effective for all NetOnewayRelayBinding- and NetEventRelayBinding-based endpoints that are active in the current application domain. The reason for these setting being shared is that the connectivity path to the Service Bus fabric is commonly identical across all endpoints in the same process—that is, the process being located on a machine residing in a tightly managed corporate networking environment that will only permit outbound HTTP traffic without exceptions for the TCP ports required by the other bindings.

By default, all service endpoints listening for messages using one of these two bindings will connect up to the Service Bus fabric using outbound TCP port 828 (for SSL-protected connections) or outbound TCP port 808.

If neither of these ports is available for outbound communication, the Mode of the connectivity settings can be set to ConnectivityMode.Http, which enables the HTTP polling mode that communicates only through outbound ports 80 and 443 using RFC 2616-compliant HTTP requests. RFC 2616 strongly recommends constraining the concurrent requests to a particular domain to be limited to two, and the operating system and networking devices or upstream proxies can enforce that limit, the HTTP polling mode is using a single HTTP connection to implement polling. All messages destined for all one-way and event endpoints in the current application domain are multiplexed through the HTTP polling connection and distributed locally.

The HTTP polling connection is backed by a Service Bus-hosted queue-like data structure called Message Buffer. If the HTTP connectivity mode is selected, the Service Bus logic on the client creates such a Message Buffer in the hosted Service Bus fabric, and opening a new listener endpoint will subsequently create a one-way delivery subscription into that Message Buffer inside the Service Bus fabric. To create the Message Buffer, the infrastructure on the client side requires some minimal configuration, which is provided through the HttpModeMessageBufferLocation, HttpModeRelayClientCredentials, and the proxy-related HttpMode* properties that are described in the following table.

Even though the Message Buffer structure has queue-like characteristics (and it is indeed possible to drop one-way messages directly into the message buffer endpoint on the Service Bus), there are no delivery assurances associated with this message buffer, and it is strictly designed to serve as the backing structure for the (eagerly polling) HTTP mode.

Note: The message buffer is throttled to 256KB total message content size, and messages cannot exceed 60KB in size for the .NET Services December 2008 CTP. After the size throttle is exceeded, further incoming messages are dropped.

Transport Binding Primitives   

This section discusses the transport binding primitives underlying the Bindings discussed above. If you want to create a WCF custom binding, you can use one of these binding elements to send to or listen on the Service Bus instead of using the corresponding WCF transport binding elements. Note that these primitives are typically subject to revision or expansion between CTP releases, and you should therefore rely on the standard bindings whenever possible.

TcpRelayTransportBindingElement

The TcpRelayTransportBindingElement is closely aligned with the WCF TcpTransportBindingElement and is the foundation for the NetTcpRelayBinding.

HttpRelayTransportBindingElement

The HttpRelayTransportBindingElement is closely aligned with the WCF HttpTransportBindingElement and is the foundation for all HTTP Relay bindings that are configured to use unsecured HTTP communication.

HttpsRelayTransportBindingElement

The HttpsRelayTransportBindingElement derives from the HttpRelayTransportBindingElement and is the foundation for all HTTP Relay bindings that are configured to use secured HTTPS communication.

OnewayRelayTransportBindingElement

The OnewayRelayTransportBindingElement is the foundation for the NetEventRelayBinding and NetOnewayRelayBinding. As a TCP-based transport binding element, it is similar to the WCF TcpTransportBindingElement, but supports only one-way communication.

Note: For the .NET Services December 2008 CTP, messages sent through this binding are constrained to at most 60KB in wire size.

Creating a Composite Duplex Binding over Oneway

The OnewayRelayTransportBindingElement provides the most aggressive NAT/Firewall traversal options because it features an optional HTTP connectivity mode (also see ConnectivitySettings) that enables it to listen for messages using the standard TCP ports 80 and 443 using a fully HTTP 1.1-compliant polling mode that is backed by Service Bus-hosted message buffering infrastructure.

You can create a bidirectional communication path over a pair of one-way connections through a WCF Custom Binding that leverages the WCF CompositeDuplexBindingElement.

Each of the endpoints of a composite communication path needs to have a distinct address in the Service Bus. In other words, the ClientBaseAddress URI that the client uses for its communication channel on the CompositeDuplexBindingElement must differ from the endpoint URI of the service.

Also note that the client must have Send permission on the service endpoint address and Listen permission on the endpoint indicated by its ClientBaseAddress. Conversely, the  service must have Send permissions on the client callback endpoint and Listen permissions on its own endpoint. Because both parties create a listener with a composite duplex binding, both parties must attach valid Relay credentials to their respective endpoints using a TransportClientEndpointBehavior regardless of the RelayClientAuthenticationType set on the OnewayRelayTransportBindingElement.