I have heard many integration specialists lament the fact that they could not get BizTalk Server to successfully connect to SOAP services secured by ADFS. This made me a bit nervous when I was recently tasked with doing exactly this.  The challenge was to call a WCF Service which was secured by ADFS with authentication based on AD username/password credentials.

This endeavour never got past the POC stage since the project I was working on decided to go another way rather than use ADFS, but I did manage to whip together a successful POC and thought I’d share my findings. This post is not a deep dive into ADFS (there are lots of those available if you search around, and I’m really not an expert) but will rather focus on providing a step by step guide to getting BizTalk Server to call on your ADFS secured service.

I was provided with a WSDL for the service in question and proceeded to run the “Consume WCF Service” wizard in Visual Studio. My plan was to use the generated binding file to automatically create the send port. However when I ran the wizard, I was met with the below screen at the last step. I can’t say if all of you will encounter this problem when trying to consume an ADFS secured WCF Service in a BizTalk project, but it certainly caused problems for me.

Error

Since this wasn’t going anywhere for me I decided to fall back to my favourite backup plan, whipping up a Console Application and adding a Service Reference corresponding to the ADFS secured service.  What I saw in the app.config surprised me.  Before jumping into what’s so different about the generated config file, below is what the config file looks like at the top level.  The client endpoint is based on a customBinding (pretty much equivalent to a basicHttpBinding with transport security since it is composed of the textMessageEncoding and httpsTransport binding element extensions).  So far that’s nothing too fancy, but what’s hidden within the collapsed security element within the custom binding, and what’s with all the extra bindings contained within the app.config?

TopLevelConfig

Below is a screenshot of a subset of the security element contained within the app.config file.  What you’ll notice is that within the security element is a sub-element called issuedTokenParameters.  Below this node you’ll notice that there are a whole lot more commented out alternative issuedTokenParameter nodes.  Each one of these issuedTokenParameter nodes (including the default one) corresponds to different STS issuer endpoint addresses, each one supporting various authentication modes (such as username, kerberos, or certificate) and various WCF bindings.

TheMeatOfTheConfig

This is actually the most important point.  The binding configuration used by the STS endpoints is actually independent from the binding configuration used against the client endpoint. When calling this WCF Service there are actually going to be two service calls, the first to the STS service and the second to the target service with the relevant security headers based on the response from the STS service.

The default issedTokenParameters element in my app.config file is based on the wsHttpBinding and is based on certificate authentication (the STS address/binding configuration name should give you a hint regarding this, but inspecting that specific binding configuration will confirm this).
CertificateWSHttp

This isn’t quite what I wanted so I commented out the default issuedTokenParameters element in the config file, and uncommented the alternative issuedTokenParameters node which was based on the ws2007HttpBinding binding (note that I could have achieved the same result by choosing the issuedTokenParameters node based on the wsHttpBinding binding) and username credentials.

ws2007usernamebinding

Now when I call on the service I get a successful response as long as I pass in the relevant client credentials.

ServiceReference

Ok, we’ve got this working in a Console Application, but wasn’t the whole point of this exercise to get this working in BizTalk Server? My belief is that it isn’t possible to create a send port directly in the BizTalk Administration console, as it is not possible to create the secondary binding that will be used by the STS endpoint, which as you’ve seen above has a binding that is independent of the target service’s binding. However, we can use the app.config file that got generated in our Console Application to load the relevant configuration into a WCF-Custom send port.

In order to achieve this we need to create a new WCF-Custom send port, browse to the Import/Export tab, click the import button and choose the aforementioned app.config file.
Import
You’ll be prompted to select a client endpoint from which configuration will be imported. Only one of them should name an address against it, so select that one and click ok.
SelectEndpoint

The result of this is that the endpoint address and binding information has been automatically populated in the send port based on the configuration contained within the app.config file.  If you click on the security/IssuedTokenParameters/Issuer node within the binding tab, you’ll notice that the binding and bindingConfiguration values match those that were specified in the app.config. Also of note is that there is nowhere within the send port UIs whereby you can adjust the binding configuration’s configuration for the STS endpoint.

CustomBinding

If you export the bindings for the send port you could adjust the secondary binding configurations manually, though do be careful because the XML configuration will be escaped. I’d also advise you to use lightweight editors like notepad when editing binding files, because Visual Studio is notorious for corrupting send port filters when you manually edit binding files using the built in XML editor.

That’s pretty much all there Is to it. The only additional step will be to set the SOAP Action Header mappings, and inbound/outbound maps/pipelines, and you will be ready to use your send port.

I would like to shout out to Yossi Dahan whose blog post (I can’t find it anymore though so can’t refer to it) gave me some hints that got me on the right path, as well as Chris Mellard who also gave me some hints that got me halfway to a solution – and after re-reading the information he gave me it looks like he actually provided me with the entire solution, which would’ve saved me a lot of pain if I had only read his email to me more carefully :)

As always, please feel free to share your own experiences, feedback, comments, and criticisms with the aforementioned solution.