Federated Authentication for Windows Azure Service Bus

• A Windows Azure subscription.
  
  
• ADFS 2.0 installed on an on-premise computer, and administrative rights to the server.
  
  
• The Federation Service component of ADFS. For more information, see Install the Federation Service component of ADFS
  
  
• Windows Azure client libraries.
  
  
• Windows Identity Framework SDK
  
  

This article assumes that you are familiar with brokered messaging in Windows Azure Service Bus. For more information, see Queues, Topics, and Subscriptions. The code example in the article uses Service Bus queues, but the same principles apply to topics and subscriptions.

The terminology used in ACS and ADFS can get somewhat confusing. Here are the main terms to understand:

• Claim: A statement about a subject. For example, “User A belongs to security group B.” Claims can be used to grant permissions. For example, you might allow users in security group B to create new service bus queues, while users in security group C have only Send and Receive permissions.
  
  
• Identity Provider: A service that authenticates a user’s identity. In this article, ADFS is the identify provider.
  
  
• Relying party: The application that consumes ADFS claims. In this article, Service Bus is the relying party.
  
  
• Relying party trust: An ADFS object that maintains the relationship with the relying party.
  
  
• Rule group: Rules that define which claims are passed from the identity provider (ADFS) to the relying party application (Service Bus). A rule group also defines mappings, so that claims from the identity provider translate into claims that are meaningful to the relying party application.
  
  
• Security Assertion Markup Language (SAML) token: The data format that ADFS uses to present claims to the relying party.
  
  

First, use the Windows Azure Platform Management Portal to create a Service Bus namespace. Follow the steps listed in How to: Create or Modify a Service Bus Service Namespace.

When the Service Bus namespace is activated, click Access Key, and then click Open ACS Management Portal. The name of your Service Bus namespace appears at the top of the portal in the Service Namespace field with a "-sb" suffix. For example, if your Service Bus namespace is "Contoso," it is displayed as "Service Namespace: Contoso-sb".

Then get the URI for WS-Federation Metadata, as follows:

For example, if the Service Bus namespace is “contoso,” the URI is https://contoso-sb.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml.

Next, add a relying party trust to ADFS.

In the Windows Azure Management Portal, add the ADFS identity provider.

Note
In the ADFS 2.0 Management Console, you can get the URI for the federation metadata as follows: Under the AD FS 2.0\Service folder, click Endpoints. The URI is listed under Metadata. Look for the URI with Type equal to “Federation Metadata.”

In the Windows Azure Management Portal, add a rule group to grant permissions to service bus. To keep the example simple, we will allow any user from the ADFS domain to have read, write, and manage rights.

Next, add rules to the rule group.

To authenticate with ACS, the client application must obtain a claims token from ADFS.

The following code shows how to obtain the token, using Kerberos for authentication.

using Microsoft.IdentityModel.Protocols.WSTrust;
using Microsoft.IdentityModel.Protocols.WSTrust.Bindings;
using Microsoft.ServiceBus;
using Microsoft.ServiceBus.Messaging;
using System;
using System.IdentityModel.Tokens;
using System.Net;
using System.ServiceModel;
using System.ServiceModel.Security;

class Program
{
    public static string GetSamlClaim(Uri tokenRequestUri, Uri kerberosEndpoint)
    {
        using (var trustChannelFactory = new WSTrustChannelFactory(
                new KerberosWSTrustBinding(SecurityMode.TransportWithMessageCredential),
                new EndpointAddress(kerberosEndpoint)))
        {
            trustChannelFactory.TrustVersion = TrustVersion.WSTrust13;
            trustChannelFactory.Credentials.Windows.ClientCredential = 
                CredentialCache.DefaultNetworkCredentials;

            RequestSecurityToken rst = new RequestSecurityToken(
                WSTrust13Constants.RequestTypes.Issue, WSTrust13Constants.KeyTypes.Bearer)
                {
                    AppliesTo = new EndpointAddress(tokenRequestUri),
                    TokenType =  
                        Microsoft.IdentityModel.Tokens.SecurityTokenTypes.Saml11TokenProfile11
                };

            WSTrustChannel channel = (WSTrustChannel)trustChannelFactory.CreateChannel();
            GenericXmlSecurityToken token = channel.Issue(rst) as GenericXmlSecurityToken;
            return token.TokenXml.OuterXml;
        };
    }

    static void Main(string[] args)
    {
        Uri tokenUri = new Uri("https://contoso-sb.accesscontrol.windows.net/");
        Uri kerberosEndpoint = 
            new Uri("https://yourhostname/adfs/services/trust/13/kerberosmixed");

        string token = GetSamlClaim(tokenUri, kerberosEndpoint);
    }
}

The GetSamlClaim method shown in this example has two input parameters:

• The management endpoint for your Service Bus namespace. For example, if the namespace is “contoso”, the management endpoint is https://contoso-sb.accesscontrol.windows.net. You can find the endpoint URI in the Management Portal. Go to the Service Bus portal, select your Service Bus namespace, and view the namespace properties.
  
  
• The ADFS Kerberos endpoint, which is https://hostname/adfs/services/trust/13/kerberosmixed
  
  

Once you have the SAML token, you can use the token to access your Service Bus namespace. The following code shows a simple example of sending and receiving a message on a Service Bus queue.

static void QueueMessage(string token, string serviceNamespace)
{
    string queueName = "myQueue";

    TokenProvider credentials = TokenProvider.CreateSamlTokenProvider(token);
    Uri uri = ServiceBusEnvironment.CreateServiceUri("sb", serviceNamespace, "");
    NamespaceManager manager = new NamespaceManager(uri, credentials);

    QueueDescription myQueue;
    if (manager.QueueExists(queueName))
    {
        myQueue = manager.GetQueue(queueName);
    }
    else
    {
        myQueue = manager.CreateQueue(queueName);
    }

    var factory = MessagingFactory.Create(uri, credentials);
    var queueClient = factory.CreateQueueClient(queueName);

    // Send a message.
    var message = new BrokeredMessage();
    message.Properties.Add("greeting", "hello!");
    queueClient.Send(message);

    // Receive a message
    message = queueClient.Receive(TimeSpan.FromSeconds(5));
    if (message != null)
    {
        Console.WriteLine(message.Properties["greeting"]);
        message.Complete();
    }

    queueClient.Close();
    factory.Close();
}

The TokenProvider.CreateSamlTokenProvider method creates a SamlTokenProvider object, which manages the SAML token.

Service Bus defines three claims that grant different permissions:

• Manage: Lets you create and delete Service Bus queues and topics.
  
  
• Send: Lets you send messages.
  
  
• Receive: Lets you receive messages.
  
  

For details, see Service Bus Authentication and Authorization with the Access Control Service.

In the previous sections, we granted all three of the permission types to every user. However, you might want to restrict access to certain users. For example, some users can create or delete queues, so these users have Manage permissions. Other users might have Listen and Send, but not Manage.

Suppose that you created an Active Directory security group named “SBAdmins.” Let’s see how you can restrict Manage permissions to members of this group.

First, add a claim rule in ADFS. This rule will convey the user’s security group to ACS.

Next, update the ADFS rule group in the Windows Azure portal.

Now members of the SBAdmins security group have permission to create or delete Service Bus queues. Other users can send or listen, but cannot create or delete queues.