Calling ADFS Secured Web Services from BizTalk Server

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.

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?

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.

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).

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.

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

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.

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.

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.

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.

Using the Identity and Access extension in Visual Studio with an Azure ACS namespace created in the new Azure Management Portal (working around error ID1113)

Continuing my foray into the world of Azure I started playing with using my Azure VM as an ADFS server with the goal of using it as an identity provider in Windows Azure ACS for the appropriate candidate azure services. I followed the instructions on this fantastic step by step walkthrough by Haishi Bai (he sure does make it easy for those who are learning their way) but I ran into a problem when I tried to get the Identity and Access extension (on a side note make sure you have the WIF runtime installed on the server, then install the WIF SDK, and only then install the Identity and Access Visual Studio extension or you will face a null object reference type error when opening Visual Studio and the extension won’t load) in Visual Studio to use my Azure ACS namespace as an identity provider.

According to the instructions on this blog post and on many others one should browse to the Access Control Services management portal, click on the Management Service link, click on ManagementClient then symmetric key and take down the key value that is listed here.

Now to have Visual Studio connect to your ACS namespace you need to open the Identities and Access menu by right clicking on the project and selecting that item, choosing to use the Windows Azure Access Control Service and then pressing the configure link to choose an ACS namespace.  Now the guidance says that you should place your ACS namespace in the first textbox and your symmetric key in the second.

Unfortunately you’ll find that chances are this wont work.  You will be faced with a ID1113 error (you can see it by hovering over the red exclamation mark) which states that the combination of namespace and management key are invalid.  Browsing around the internet (there are many places where this suggestion is made but it is probably worded best in this blog post) suggests that this is a common problem when you have created the ACS namespace in the new Azure Management Portal and have suggested that you should instead create the ACS namespace in the old portal instead (you can access the old portal by clicking on your name on the top right hand side of the portal screen and choosing previous portal).

What I have found however is that if I instead entered the ManagementClient password instead of the symmetric key then the extension seems to accept the combination and allows me to choose from the identity providers that I have configured in the ACS management portal.  I do not know why the password is accepted while the symmetric key isn’t when that is apparently what is being asked for, but for others who are also stuck at this step use the password instead.