I have been working with the ESB toolkit and following MSDN Social. If you have worked through some of the Development Activities you may have come across How to: Route a Single Message to Multiple Recipients Using an Itinerary Routing Slip.

You may have thought what I thought.. what if I need to use a different transform for each recipient? I would suggest you read the above development activity and understand it, then come back to the blog.

To summarize :

A message comes in
A Message Extender extends the onramp
The Message Extender has more than one resolver
The toolkit will send the message to each resolver.

If you select one of the Resolvers you will see that you can specify a transform type. For a route message extender this has no affect. The message will NOT be transformed.

In order for the message to be transformed you need to create your own Custom Itinerary Messaging Service this new service will need to route and transform. You may think this sounds hard, but really.. it’s easy.

I set about creating this, I had reflector open on one window and Visual Studio open on the other. I wanted to reuse the existing ESB code has much as possible (without copy and pasting code blocks). The ESB Assembly Microsoft.Practices.ESB.Itinerary.Services.dll contains the class for each Service, these classes have public methods for transform and route. So all we need to do is call these.

The is the code :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Reflection;
using System.IO;
using System.Globalization;
using Microsoft.Practices.ESB.Exception.Management;
using Microsoft.Practices.ESB.Resolver;
using Microsoft.Practices.ESB.Itinerary.Services;
using Microsoft.BizTalk.Message.Interop;
using Microsoft.BizTalk.Streaming;

namespace Diagonal.ESB.Services
{
    public class TransformAndRouteService : IMessagingService
    {
        public IBaseMessage Execute(IPipelineContext context, IBaseMessage msg, string resolverString, IItineraryStep step)
        {
            if (context == null)
                throw new ArgumentNullException("context");
            if (msg == null)
                throw new ArgumentNullException("msg");
            if (string.IsNullOrEmpty(resolverString))
                throw new ArgumentException("Properties.Resources.ArgumentStringRequired", "resolverString");
            try
            {

                msg = route(context, msg, resolverString);
                msg = transform(context, msg, resolverString);
                return msg;
                
            }
            catch (System.Exception ex)
            {
                EventLogger.Write(MethodInfo.GetCurrentMethod(), ex);
                throw;
            }      
        }

        private static IBaseMessage transform(IPipelineContext context, IBaseMessage msg, string resolverString)
        {
            // Get settings for transform to see if we need to call it
            ResolverInfo info = ResolverMgr.GetResolverInfo(ResolutionType.Transform, resolverString);

            if (info.Success)
            {
                // if we dont find transform info, we dont mind
                Dictionary<string, string> resolverDictionary = ResolverMgr.Resolve(info, msg, context);

                string transformMap;
                resolverDictionary.TryGetValue("Resolver.TransformType", out transformMap);
                if ((!string.IsNullOrEmpty(transformMap)) && (!transformMap.Equals("(None)")))
                {
                    IBaseMessage transformedmessage;
                    Stream safeDataStream = new ReadOnlySeekableStream(msg.BodyPart.GetOriginalDataStream());

                    // move the stream pointer back to the start; could theoretically throw an exception if BizTalk
                    // Server were to return a non-seekable clone of the original stream within GetSafeDataStream
                    safeDataStream.Position = 0L;

                    msg.BodyPart.Data = safeDataStream;

                    // Backup the stream
                    MemoryStream ms = new MemoryStream();
                    byte[] respBuffer = new byte[1024];

                    int bytesRead = safeDataStream.Read(respBuffer, 0,
                        respBuffer.Length);

                    while (bytesRead > 0)
                    {
                        ms.Write(respBuffer, 0, bytesRead);
                        bytesRead = safeDataStream.Read(respBuffer, 0,
                        respBuffer.Length);
                    }

                    msg.BodyPart.Data.Position = 0;
                    TransformationService transform = new TransformationService();
                    transformedmessage = transform.ExecuteTransform(context, msg, resolverDictionary["Resolver.TransformType"], false);

                    // restore the stream
                    ms.Position = 0L;
                    msg.BodyPart.Data = ms;

                    return transformedmessage; // Pass back the transformed message
                }
            }
            // not getting transformed.
            return msg; // Pass back non transformed message
        }

        private static IBaseMessage route(IPipelineContext context, IBaseMessage msg, string resolverString)
        {
            // Pass to routeservice
            RoutingService routeService = new RoutingService();
            msg = routeService.ExecuteRoute(context, msg, resolverString);
            return msg;
        }

        public string Name
        {
            get {
                System.Diagnostics.Trace.WriteLine("custom code 2");
                return "Diagonal.ESB.Services.TransformAndRoute";
            }
        }

        public bool ShouldAdvanceStep(IItineraryStep step, Microsoft.BizTalk.Message.Interop.IBaseMessage msg)
        {
            return true;
        }

        public bool SupportsDisassemble
        {
            get { return true; }
        }

    }
}

You will need edit the esb.config to allow you to use your new service, add

      <itineraryService 
        id="A5414011-7D60-4670-8AB5-9B6F14C4F0FF" 
        name="Diagonal.ESB.Services.TransformAndRoute" 
        type="Diagonal.ESB.Services.TransformAndRouteService, Diagonal.ESB.Services, Version=1.0.0.0, Culture=neutral, PublicKeyToken=bf0fd96c065177b4" 
        scope="Messaging"
        stage="AllReceive"/>

to itineraryServices node.

Once this is in place you can select TransformAndRoute from the list of ServiceNames. When you use this Service the MAP specified by Transform Type will be used to transform the message. You can set this statically , BRE etc. Note if you don’t select a MAP it won’t crash.

I will put the code on codeplex when time permits.

More ESB blogs to follow ;

Background

A customer had a problem; they wanted a web service that was called by user UserA to run a BizTalk orchestration and at the end of the orchestration another web service would be called and they wanted that to be executed in the context of the caller.

Fig 1: Illustration of problem

Above, the user token is lost when we enter the BizTalk orchestration. BizTalk will call any external services as the BizTalk process account. Setting up Kerberos will not fix this. This problem is not the typical double hop issue.

Workaround with Trusted sub system

This problem can be tacked with the trusted subsystem model. The caller (Biztalk) sets the username in a header and the receiver acts as this user. Note that Biztalk does not call the endpoint using the callers credentials; It merely passes the username as a string. The web services must trust that if they are called from the BizTalk server the user parameter is correct. The web services are using API’s that allow impersonation. The effort to get this working is placed on both BizTalk and the endpoint, we have to pass the username around and we have to act as this user on the receiver.

For example
User calls service a as user UserA
BizTalk gets the username by using BTS.WindowsUser.
BizTalk calls the endpoint and passes the username.
The APIs that are used in the backend system behind the endpoint impersonate UserA (Note; no operating system level impersonation is done)

To make the above secure, the endpoint only accepts calls from the BizTalk server and it trusts the claims it makes.

Workaround with Constrained delegation

Another way to tackle this problem is to use constrained delegation. The works as follows :
User calls service a as user UserA

BizTalk gets the username by using BTS.WindowsUser.
BizTalk calls the endpoint and inserts the username in the message context.
A WCF adapter intercepts message and impersonates the user at the operating system level. (We are still on the BizTalk server at this point)
The receiving WCF endpoint is now running in the context of the user.
Why is this safe? How can you just impersonate a user? Without the password? Well you can and it’s safe (please read )

Trusted subsystem vs Constrained delegation

A simple way to think of this is, with Constrained delegation you put the effort into the BizTalk and the infrastructure hosting the BizTalk. With trusted sub system you put the effort into the receiver.

Please note, that the term “trusted sub system” can be used to describe other solutions to similar security related problems.

If you OWN and control all the endpoints then I would consider using the trusted sub system model. Your dev team may find this easier to get working and does not rely on setting up your domain. Saying that, once you do get this working you will probably find it easier to add more systems along the way.

How to

The solution that has been built by following these steps can be found on codeplex. I tend to-do things the TDD way (as much possible) this goes for BizTalk too. I tend not to drop files to test things, I hit web services and expect things to get returned. This step by step guide will go through creating the web services that call BizTalk.

Prerequisites

Visual Studio 2008.
BizTalk 2009 Installed and working.
Domain Admin privileges.
Access to setspn. (Comes with windows 2003 support tools, I think it’s built into 2008 r2)
An account to delegate to (just ask a colleague if you can impersonate them).
Windows 2008 R2 (That's what I used, you can get this working with other versions but things may not be exactly the same).
A Windows 2008 R2 Server to host the final WCF service. (To test properly, this NEEDS to be a separate server or VM)

Step One (Setup Delegation)

running as a domain admin run the following SETSPN commands
Setup for BIZTALK server running as DOM\BizTalkUser

setspn –A HTTP/BIZTALKSERVER DOM\BizTalkUser 
setspn –A HTTP/BIZTALKSERVER.FQDN DOM\BizTalkUser

Setup for WCF server running as network system.

setspn –A HTTP/WCFSERVER WCFSERVER 
setspn –A HTTP/WCFSERVER.FQDN WCFSERVER

Note, .FQDN is the full qualified domain name, eg server.domain.local

On the BIZTALK server ensure the account has the “act as part of operating system” right.

Using AD enable constrained delegation from the user DOM\Biztalk to WCFSERVER over HTTP. Edit settings on the Biztalk server. You will need to do this for the account. If you do not see the delegate options on the account this means the spns have not been created.

Step Two (Create the solution)

Create a blank solution in Visual Studio 2008 called LetsDoProtocolTransition. Add it empty tests project to this. Call this Tests (or what ever you wish)

Step Three (create EndPoint system and test constrained delegation works)

We will be creating a WCF web service and some tests to call this. One test will impersonate the other will not.

Select Add New Web Site, select WCF Service, set location to HTTP and call this http://localhost/WCFStartBiztalk

Delete Service.cs and IService.cs.

Using add new item, select WCF Service, call this NameService

Open INameService, remove
```
[OperationContract] 
void DoWork();
```

Add
```
[OperationContract] 
string WhatsLoginName();
```

Implement, just have it return “” for now as we are doing this the TDD way :)

Build and add a reference to this service from your test project. Enter WCFBackEndSystem in the namespace.

Add the following settings to your tests (right click on project, select settings to get to this screen) :

Add a test file to your test project, name this file WCFBackEndTest.cs add the following code to your test :
```
[TestMethod]
public void SimpleCall()
{
NameServiceClient client = new NameServiceClient();
Assert.AreEqual(WindowsIdentity.GetCurrent().Name, client.WhatsLoginName(), true);
}
```

Run the tests and you will get Assert.AreEqual failed. Expected:<DOM\User>. Actual:<>.

Implement the backend code :
```
public string WhatsLoginName() 
{ 
return OperationContext.Current.ServiceSecurityContext.WindowsIdentity.Name; 
}
```

Run your test and it should pass.

Add a new tests with the following code
```
[TestMethod]
public void SimpleCallAsUser()
{
WindowsIdentity wi = new WindowsIdentity(Tests.Properties.Settings.Default.remoteUPN);
WindowsImpersonationContext imp = wi.Impersonate();
NameServiceClient client = new NameServiceClient();


Assert.AreEqual(Tests.Properties.Settings.Default.remoteUser , wi.Name, true,
"Could not impersonate, make sure you can act as part of operating  system");
Assert.AreEqual(Tests.Properties.Settings.Default.remoteUser, client.WhatsLoginName(), true, 
"Call to service failed, delegation not working");
imp.Undo();
}
```

Run your test and it should pass.

If you get Call to service failed, then you don't have delegation setup correctly. Or…. you have problems with SPNs, you may need to get out ADSI edit have a look around.

The above tests should work, we are not calling a remote server but we are proving that part of this works.

Copy the WCF service to the remote server and create a new test that looks like
```
[TestMethod]
public void RemoteCall()
{
NameServiceClient client = new NameServiceClient();
client.Endpoint.Address = new EndpointAddress(Settings.Default.WCFService);
Assert.AreEqual(WindowsIdentity.GetCurrent().Name, client.WhatsLoginName(), true);
}

[TestMethod]
public void RemoteCallAsUser()
{
NameServiceClient client = new NameServiceClient();
client.Endpoint.Address = new EndpointAddress(Settings.Default.WCFService);

WindowsIdentity wi = new WindowsIdentity(Settings.Default.remoteUPN);
WindowsImpersonationContext imp = wi.Impersonate();

Assert.AreEqual(Settings.Default.remoteUser, wi.Name, true, "Could not impersonate, make sure you can act as part of operating system");
Assert.AreEqual(Settings.Default.remoteUser, client.WhatsLoginName(), true, "Call to service failed, delegation not working");

imp.Undo();
}
```

if everything is setup correctly you should get all greens.

Step Four (The BizTalk bits)

For this part, lets assume the following understanding of biztalk :

How to create a biztalk orchestration that is created by calling a SOAP web service.

How to consume a WCF service.

How to setup the ports for the above service.

I assume that you may not have done the following :

Passed calling user name to a header

Installed a WCF extension

Editing the custom binding

Our incoming message is the same as the outgoing to keep this simple. This message has the CallerName, BizTalk Username and the WCF Service Name. They should all match. The XML will look like :

<ns0:userDetails callerClaim="DOM\ExampleUser" biztalkClaim="DOM\ExampleUser" wcfClaim="DOM\ExampleUser" xmlns:ns0="LetsDoProtocolTransition" />

When I create these types of POC I tend to put exception handling into BizTalk and have it write out details using Debug.WriteLine. You can then run debug view and see the messages.

This also means if things don't work you don't get things stuck in any BizTalk queues so this makes redeploying easier. Any outgoing ports are setup with zero retries for the same reason.

Your final orchestration will look like this:

When you are wiring up the WCF endpoints use Custom Bindings as we will be editing these.

We won’t be adding the custom WCF behaviour yet, we will get this working without. The WCF services will return the BizTalk process account.

Publish the orchestration as a web service with the address http://localhost/LetsDoProtocolTransition

For now, just get BizTalk calling your WCF endpoint. Don't worry about passing the user. Look at the next section for the test used to test BizTalk.

Step Five (The Tests)

Add a ASMX reference to http://localhost/LetsDoProtocolTransition

Call this BizTalkService with this code

[TestMethod]
public void CallBiztalk()
{
//
// TODO: Add test logic    here
//
BizTalkService.LetsDoProtocolTransition_Protocol_Transition_Orchestration_Port_1 client;
client = new Tests.BizTalkService.LetsDoProtocolTransition_Protocol_Transition_Orchestration_Port_1();
client.Credentials = CredentialCache.DefaultCredentials;

WindowsIdentity wi = new WindowsIdentity(Tests.Properties.Settings.Default.remoteUPN);
WindowsImpersonationContext imp = wi.Impersonate();

var userDetails = new Tests.BizTalkService.userDetails();
userDetails.callerClaim = WindowsIdentity.GetCurrent().Name;
userDetails.biztalkClaim = "";
userDetails.wcfClaim = "";

client.Operation_1(ref userDetails);

Trace.WriteLine("You are\t\t\t\t: " + userDetails.callerClaim);
Trace.WriteLine("BizTalk thinks are\t\t\t: " + userDetails.biztalkClaim);
Trace.WriteLine("The WCF Services thinks you are\t: " + userDetails.wcfClaim);

Assert.IsTrue( string.Equals(userDetails.callerClaim,userDetails.biztalkClaim ,StringComparison.CurrentCultureIgnoreCase ), string.Format( "BizTalk does not agree that you are who you say you are. You Say {0}, BizTalk Says {1}", userDetails.callerClaim,userDetails.biztalkClaim ));
Assert.IsTrue(string.Equals(userDetails.callerClaim, userDetails.wcfClaim , StringComparison.CurrentCultureIgnoreCase), string.Format("WCF does not agree that you are who you say you are. You Say {0}, BizTalk Says {1}", userDetails.callerClaim, userDetails.wcfClaim));

imp.Undo();
}

Run the test, it will fail as the WCF service will be running as the BIZTALK user.

Step Six (Adding the WCF Custom Channel)

You will need to download this from codeplex, download the project and add it to your solution. Build it (make sure it goes in the GAC).

Open your machine.config (if you running 64bit then depending on your biztalk setup you may need to edit the 64bit version). Locate
<system.serviceModel>
<extensions>
And add
<add name="protocolTransition" type="Microsoft.BizTalk.Rangers.ProtocolTransition.WCFCustomChannel.InspectingBehaviorExtensionElement, Microsoft.BizTalk.Rangers.ProtocolTransition.WCFCustomChannel, Version=1.0.0.0, Culture=neutral, PublicKeyToken=874a60d7e5a4dd9b" />
To the behaviorExtensions node and bindingElementExtensions, this section of the config will look something like :

You can now use the protocol extension with WCF. This is done with a custom binding.

Step Seven (Testing the WCF Binding)

To make testing of the WCF custom binding less effort we are going to setup the channel / binding with code. This mean you don't need to edit the config file and break the other tests. With real code I would use the config file so it would be less ‘hard coded’.

Add the following code :
```
[TestMethod]
public void WCFCustomChannelTest()
{

var textMessageEncoding = new TextMessageEncodingBindingElement();
var protocolTransition = new InspectingBindingElement();
var httpTransport = new HttpTransportBindingElement();

textMessageEncoding.MessageVersion = MessageVersion.Soap11;
httpTransport.AuthenticationScheme = System.Net.AuthenticationSchemes.Negotiate;
protocolTransition.UserNameOverride = Settings.Default.remoteUPN ;

CustomBinding binding = new CustomBinding(
textMessageEncoding,
protocolTransition,
httpTransport
);

var channelFactory = new System.ServiceModel.ChannelFactory<INameService>(binding);
INameService client = channelFactory.CreateChannel(new EndpointAddress(Settings.Default.WCFService));

Assert.AreEqual(Settings.Default.remoteUser, client.WhatsLoginName(), true);
}
```

If you run debug view you will see trace information.

or double click on the test and you will see :

We have now proved that our WCF Extension is intercepting the call and impersonating a user.

Step Eight (Getting it working from Biztalk)

To get this to work from BizTalk we need to modify the port that biztalk sends the message through. Assuming you have got the BizTalk bits working.

Create an XML file that contains the following (naming it CustomBindingConfig.config) :

<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.serviceModel>
<client>
<endpoint address="http://<YOURSERVER>/WCFBackendSystem/NameService.svc" binding="customBinding" bindingConfiguration="customBinding" contract="BizTalk" name="WcfSendPort_NameService_BasicHttpBinding_INameService_Custom" />
</client>
<bindings>
<customBinding>
<binding name="customBinding">
<textMessageEncoding messageVersion="Soap11" />
<protocolTransition ContextPropertyName="WindowsUser" ContextPropertyNamespace="http://schemas.microsoft.com/BizTalk/2003/system-properties" />
<httpTransport authenticationScheme="Negotiate">
<extendedProtectionPolicy policyEnforcement="Never" />
</httpTransport>
</binding>
</customBinding>
</bindings>
</system.serviceModel>
</configuration>

In your send ports, select the WCF one

Select configure, select import (on the import/export tab).

Import the xml config file created above.

You should see the following binding details , ok these

Run your tests, you should get all greens.

The output of the biztalk tests should be something like :

As you can see we are running tests as wisdomv6 but all the checks return the user that we are impersonating.

What have we just done?

In simple terms we have extended WCF to allow it to impersonate a user before it calls the endpoint. We have configure our domain to allow impersonation. We have passed calling user to the WCF EndPoint in BizTalk.

2e2 Business Apps Technical Team Blog

Wednesday, April 28, 2010

Route and Map a Single Message to Multiple Recipients Using an Itinerary Routing Slip

Thursday, March 11, 2010

Protocol Transition with BizTalk