Last week, I filled in for Mike Benkovich on his weekly Cloud Computing: Soup to Nuts series with a presentation on the Windows Azure Service Bus.  The recording should be available soon, if not already, but I thought I’d follow up with a multi-part blog series that covers the material I presented.

The context for the talk was pretty simple, an application running “on-premises” and behind the firewall (your local machine, in this case) that echoes messages sent via a public website, hosted on Windows Azure (but it could be anywhere).  When the message arrives at the service host, a window pops up showing the message.

The ‘on-premises’ piece of this example is a very simple WPF application that listens for messages, either on a WCF endpoint or via the Windows Azure Service Bus..  Messages in this context have three fields: the message text, name of the sender, and a string indicating the color of the window that displays the message on-premises.  The result looks something like the following, where the browser on the left is the client, and the simple WPF application at the bottom right is the service host.  The Metro-esque windows are the result of three messages having been sent and processed by the service hosted by the WPF application.

Service Contract

using System.ServiceModel;

namespace RelayService.Interfaces
{
    [ServiceContract(Name = "IEchoContract", 
                     Namespace = "http://samples.microsoft.com/ServiceModel/Relay/")]
    public interface IEchoContract
    {
        [OperationContract]
        void Echo(string sender, string text, string color);
    }

    public interface IEchoChannel : IEchoContract, IClientChannel { }
}

On-Premises WCF Sample

The WPF application in the sample project can either self-host a WCF service or open an endpoint exposed on the Service Bus; a simple checkbox on the main window controls the behavior. To keep things simple, the WCF service endpoint is set up with a simple BasicHttpBinding (that means no authentication on the service, not something you’d do in production!).

ServiceHost host = default(ServiceHost);

// local WCF service end point  
host = new ServiceHost(typeof(EchoService));
host.AddServiceEndpoint("RelayService.Interfaces.IEchoContract",
     new BasicHttpBinding(),
     http://localhost:7777/EchoService);

ASP.NET Client Implementation

The client implementation is straightforward, and here as in the rest of the examples in the series, I’m using code (versus configuration) to provide all of the details.  You can, of course, use the web.config file to specify the binding and endpoint.

ChannelFactory<IEchoContract> myChannelFactory =
    new ChannelFactory<IEchoContract>(
        new BasicHttpBinding(), "http://localhost:7777");

IEchoContract client = myChannelFactory.CreateChannel();
client.Echo(userName, txtMessage.Text, ddlColors.SelectedItem.Text);

((IClientChannel)client).Close();
myChannelFactory.Close();

Service Bus Relay Example

1. Select the Service Bus, Access Control & Caching portion of the portal.
2. Select Service Bus
3. Select New on the ribbon to create a new namespace. This will bring up the Create a new Service Namespace dialog. The same namespace can be used for Access Control, Service Bus, and Cache, but here we need only the Service Bus.
4. Enter a unique namespace name; the resulting Service Bus endpoint will be uniquenamespacename.servicebus.windows.net, which being a public endpoint must be unique across the internet.
5. Select the Windows Azure data center you wish to host your service.  As of this writing, the East and West US data centers do not yet support the Service Bus functionality, so you’ll see only six options.
6. Create the namespace.  This will set up a Service Bus namespace at uniquenamespacename.servicebus.windows.net and an Access Control Service namespace at uniquenamespacename-sb.accesscontrol.windows.net. A service identity is also created with the name of owner and the privileges (claims) to manage, listen, and send (messages) on that Service Bus endpoint.

• Trust relationships is where you configure identity providers, such as Windows Live ID, Google, Yahoo!, Facebook, or Active Directory Federation Services 2.0.  You can use these providers to authenticate and authorize access to the Service Bus endpoint.  The Service Bus endpoint itself is a relying party application, namely an application that is secured by ACS.  Each relying party application has at least one set of rules associated with it; these rules essentially define what operations a given identity can perform on the relying party application. 

  For a Service Bus endpoint, there are three operations that can be carried out:

  • Send – send messages to an endpoint, queue or topic.
  • Listen – receive messages from an endpoint, queue, or subscription.
  • Manage – set up queues, topics, and subscriptions.
• Service settings is where you manage certificates and keys as well as service identities that are not managed by other identity providers (like Live ID or Google). For the Service Bus, the ACS automatically manages the certificates and keys (so you don’t ever worry about that part), and it also creates a service identity with the name owner and claims that allow owner to perform all three of the operations (send, listen, and manage). You can think of owner as the sa, root, or superuser of the ACS namespace, and from that it should follow that you’ll rarely – if ever – want to use owner as part of your application. Instead you should create additional user(s) and apply the principle of least privilege.
• Administration is where you control who can administer the ACS endpoint.  The default administrator will be the Service Administrator of the subscription under which the namespace was created.  That last statement has specific implications when co-administrators of an Windows Azure subscription are in play.  The co-admin can create the Service Bus namespace, but she cannot manage its access and will be greeted by the rather cryptic error below if she tries:

The remedy is to add the co-admin as a portal administrator, by logging into the ACS portal with the identity of the subscription’s Service Administrator and adding the Live ID of the co-admin:

• The Development section provides guidance and code snippets to integrate the ACS ‘magic’ into your applications.

1. Specify the user identity, use ‘guest’ here to mesh with the default identity assumed by the sample code.
2. Provide an optional description visible only in the portal.
3. Select “Symmetric Key” for the credential type. There are two other options: Password and X.509 Certificate, but both require a bit more code and configuration to implement.  Consult the ACS samples on CodePlex for scenarios that make use of these alternative credential types.
4. Generate a key for the guest identity.  You’ll also need to add this key value in the web.config file for the RelayServiceClient application.  While you’re at it, you may as well change the SBNamespace value to the Service Bus namespace you just created.

   

5. Save the new identity. By default the credentials will expire in a year.

Claims can be just about any statement or fact about the user/identity that the identity provider is storing and willing to share.  Google, for instance, will provide a name, nameidentifier, and email address as claims; Windows Live ID provides only a nameidentifier (a tokenized version of your Live ID).  The types and number of claims emitted by different identity providers vary, and that’s where claim rules come in.  You want to insulate your relying application from the vagaries of all the identity provider options, so rather than tapping into the raw claims that each of those providers sends, you set up claims that are meaningful to your application and then map the various incoming claims to the contextual claims your application understands. 

In this case, the relying party is the Service Bus, and it understands three claims: Send, Manage, and Listen.  Our specific goal though is to allow the guest identity only the capability to Send messages on the Service Bus, not manage or listen, so you’ll need to create one claim that authorizes that function. Each claim rule is essentially an IF-THEN statement:.

1. The input claim issuer refers to the identifying party.  The dropdown contains whatever identity providers you have enabled for the ACS controlling the Service Bus endpoint (via the Identity providers option under Trust Relationships in the left sidebar (not shown)).  In this case, we’re using a service identity (guest) that is managed by the Access Control Service.
2. The input claim type refers to one of potentially many claims that the identity provider is willing to offer up about the user/identity that it has authenticated.  The list of claims relevant to the selected provider is prepopulated.  For ACS-controlled service identities, the user name is provided as a nameidentifier claim; you’ll need to consult your identity provider’s documentation to determine what each claim type actually contains.  Claims that aren’t pre-populated can be specified manually in the Enter type: text box.  If you only care that the identity provider authenticates a user, you can select Any for the claim type, which simply indicates you don’t care about the specifics of the claims.
3. To complete the “IF statement,” you specify what the specific claim value should be in order to fire the rule. If you don’t care about the specific value a claim has (and only that the identity provider offers up the given claim), you can specify Any here.  In our case, the requestor must be guest, so that’s added as a specific value.  If you have multiple other identities that you want to allow access, you would create additional rules.  And if you have more complex rules (with “AND” conditions) you can add a second input claim as a compound condition to govern the claim rule.

So that’s the IF part!  Now you need to map that input claim to output claims that the relying party (Service Bus) is interested in.  We don’t really care at this point that the user’s name is guest, but we do want to know what that user is allowed to do. Granted you could do all that checking in code – if (user == ‘guest’ ) then let user call methods, etc. – but that’s horribly hard-coded and very difficult to maintain from a code and security management perspective (what happens if the guest password is compromised? how do you revoke access?)  So what you’ll do instead is map the input claim to an output claim, namely one that gives Send privileges to guest.

1. The output claim type needed here is unique to the Service Bus, so the various options in the drop down aren’t applicable, and we specify the type net.windows.servicebus.action explicitly.
2. There are three possible values: Send, Listen, and Manage; of course, we want just Send for guest.
3. You can specify a description for the claim here; it will appear in the list of rules for the given Rule Group.  It’s a good idea to put something meaningful here, because the Rule Group page listing will show only the output claim type.  If you have multiple claims for different action values, they won’t otherwise be distinguishable in the listing.
4. Save the rule!

Note that the Used by the following relying party application text box is still empty; that’s because we haven’t associated this rule group with the relying party (the Service Bus).  There’s essentially a many-to-many relationship between relying party applications and the rule groups, so we’ll need to revisit the Relying party applications entry screen to associate the new rule group with the Service Bus.  Note that the default rule group created (for owner) is already in selected.

Блокировка служебной шины с помощью ACS была, по общему признанию, небольшим трудом и отчасти отклонением от нашей реальной цели (вероятно, поэтому многие примеры просто используют владельца, даже если они этого не делают!). Вооружившись новыми удостоверениями guest и wpfsample и их необходимыми утверждениями, давайте теперь посмотрим на код для использования конечной точки служебной шины вместо конечной точки WCF, с которой мы начали.

ServiceHost host = default(ServiceHost);

   // ServiceBusEndpoint
  host = new ServiceHost(typeof(EchoService));
  host.AddServiceEndpoint("RelayService.Interfaces.IEchoContract",
      new BasicHttpRelayBinding(),
      ServiceBusEnvironment.CreateServiceUri("https",
          Properties.Settings.Default.SBNamespace,
          "EchoService"));
             
  // Add the Service Bus credentials to all endpoints specified in configuration.
  foreach (ServiceEndpoint endpoint in host.Description.Endpoints)
  {
      endpoint.Behaviors.Add(new TransportClientEndpointBehavior()
          {
              TokenProvider = TokenProvider.CreateSharedSecretTokenProvider(
                  "wpfsample",
                  Properties.Settings.Default.SBListenerCredentials)
          });
  }

• Строка 6:   мы используем новый тип привязки, BasicHttpRelayBinding , который вы можете рассматривать как BasicHttpBinding, настроенный и адаптированный для служебной шины.  Существует ряд других привязок служебной шины, которые соответствуют традиционным локальным привязкам WCF, а также определенным для облачной среды.
• Строки 7-9: CreateServiceUri метод является предпочтительным механизмом для построения конечной точки Service Bus URI; однако в этом случае вы можете просто создать строку типа «https://yoursbnamespace.servicebus.windows.net/EchoService». Свойство SBNamespace в строке 8 относится к параметру, который вы указываете в приложении WPF ( App.config ), который указывает имя пространства имен служебной шины, созданного ранее.
• В строках 12–20 учетные данные служебной шины добавляются к конечным точкам, предоставляемым служебной шиной. Строка 17 показывает имя идентификатора службы (жестко закодировано в wpfsample ), а строка 18 указывает симметричный ключ, связанный с этим идентификатором службы на портале ACS. Вам нужно будет скопировать и вставить учетные данные из портала в параметр SBListenerCredentials в файле App.config приложения WPF (или через диалоговое окно свойств в Visual Studio).

  // ServiceBus endpoint constructed using App.config setting
  ChannelFactory<IEchoContract> myChannelFactory =
      new ChannelFactory<IEchoContract>(
          new BasicHttpRelayBinding(),
          new EndpointAddress(ServiceBusEnvironment.CreateServiceUri(
              "https", 
              ConfigurationManager.AppSettings["SBNameSpace"], 
              "EchoService")));
   
  // add credentials for user (hardcoded in App.config for demo purposes)
  myChannelFactory.Endpoint.Behaviors.Add(
      new TransportClientEndpointBehavior()
      {
          TokenProvider = TokenProvider.CreateSharedSecretTokenProvider(
              userName, ConfigurationManager.AppSettings["SBGuestCredentials"])
      }
  );
   
  // traditional WCF invocation
  IEchoContract client = myChannelFactory.CreateChannel();
  client.Echo(txtUser.Text, txtMessage.Text, ddlColors.SelectedItem.Text);
   
  ((IClientChannel)client).Close();
  myChannelFactory.Close();