Migrate a VS2013 Web Project From WIF to Katana

As you already know, VS2013 introduced a new ASP.NET project creation experience that closely integrates with Azure AD – allowing you to provision an entry for your application right at project creation time, without the need to visit the portal.

Projects created through that experience implement their identity functionality with Windows Identity Foundation. WIF is great- it is the technology that brought claims-based identity from its obscure origin to the preferred way of securing access to cloud and in general remote resources –  it is fully supported and it will remain supported in lockstep with the .NET Framework in which it lives. Now that we introduced a simpler claims identity programming model in Katana, however, it does feel a bit dated!
The VS tools did not really have any alternative to WIF – when the new ASP.NET project creation experience originally shipped, our support for WS-Federation and OpenId Connect in form of OWIN middleware wasn’t around yet. In fact, it reached GA less than one month ago!

As we move forward, you can expect the simpler model to replace the WIF codebase in the templates as well; but in the meanwhile, I know that a lot of you would like to make the jump already today and convert projects created and provisioned with VS2013 from WIF to OWIN. The good news is that as long as you are willing to do some light handiwork, it is quite easy to do.

In this post I’ll tell you about one quick & dirty way of doing that, meant to be used right after you created the project. If you developed the project further, this trick won’t help you: the migration is still possible, but it would require more work to identify and eliminate the moving parts needed by WIF but no longer required by the new OWIN middleware. Let me know in the comments if many of you are in that situation, and I’ll write a new post with all the details.

Step 1 – Create a Web App with VS2013

You have seen this tons of times already, but I’ll add the sequence again just in case.

Create a new ASP.NET project.

You’ll get the usual One ASP.NET dialog.

Choose MVC and click Change Authentication.

Choose Organizational Account, enter the domain of your Azure AD tenant you want to provision the app to, and click OK.

You’ll get the classic ADAL dialog that prompts you for your Azure AD credentials, so that VS can reach out to your directory and create the app entry on your behalf. Note: the dialog is so long because I have an awesomely big monitor

Click OK again. VS will generate your project and will create an entry for it in your Azure AD tenant.

The Application’s Coordinates

The project creation logic generates a lot of moving parts that contribute to the identity functionality. We are going to ignore most of those, given that the OWIN middleware does not need them, and stay laser focused on the few info we do need.

We need to find the coordinates that were used to create the application’s entry in Azure AD, given that those values will be what we need to use when creating protocols request at authentication time – no matter which development stack we use.

We’ll find most of what we need in the web.config file. Open it, then find the appSettings element.

  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ida:FederationMetadataLocation" 

      value="https://login.windows.net/developertenant.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml" />
    <add key="ida:Realm" value="https://developertenant.onmicrosoft.com/WIF2OWINWebApp" />
    <add key="ida:AudienceUri" value="https://developertenant.onmicrosoft.com/WIF2OWINWebApp" />
  </appSettings>

The highlighted part is what we need.
Realm indicates the identifies assigned to the app for WS-Federation flows.
FederationMetadataLocation is the endpoint from which Azure AD publishes the tenant’s issuer coordinates. Technically, for this tutorial all you need is the tenant portion (in this case developertenant.onmicrosoft.com) but in the general case (e.g. any WS-Federation provider, as opposed to just Azure AD) you would need the entire metadata address.

Save those values somewhere, I usally just whip them in a notepad window.

Note: Those handy appSettings values are inserted by the ASP.NET project configurator logic; however, here there’s a trick that will work with ANY web app using WIF regardless of how it was configured. If you scroll a bit further, you’ll find the <wsFederation> element.

 <wsFederation passiveRedirectEnabled="true"

   issuer="https://login.windows.net/developertenant.onmicrosoft.com/wsfed"

   realm="https://developertenant.onmicrosoft.com/WIF2OWINWebApp"

   requireHttps="true" />

This is the element that is actually picked up by WIF at authentication time. The realm value is the same as the above. The issuer value indicates the endpoint of the STS you want to connect with; this is not as good as having the address of the metadata, but provides a great starting point given that you can usually get to it by goofing around with the base URL of the STS endpoint and append “FederationMetadata/2007-06/FederationMetadata.xml” to it to find the true metadata location.

The only other piece of info we need is the port number that IIS express assigned to our app for the SSL binding – that value has been used to provision the return URI in the Azure AD application entry, and unless we want to go to the portal and modify it manually we have to ensure we’ll use the same value. You can find it in the project properties, in the SSL URL field.

Paste that in the same notepad window, and close VS.

Step 2 – Get the Katana WS-Federation Sample and Configure it With Your App Coordinates

As I anticipated earlier, this is a quick and dirty trick. Instead of modifying the project created with the template, I will simply abandon it – and reuse its coordinates in a new project configured to use OWIN. This will take advantage of the application entry that was created for it in the Azure AD tenant.

We already have a project ready for you – it’s the WS-Federation sample we released with Katana. You can find it here.

From the GitHub page Choose Clone in desktop or download ZIP, whatever works best for you. Once you have the project locally, open it.

Head to the web.config file. You’ll find the appSettings right on top. Replace the value of ida:Wtrealm with the realm value you saved from the first app. Do the same with ida:Tenant and the tenant value you used in the original project.

<appSettings>
  <add key="webpages:Version" value="3.0.0.0" />
  <add key="webpages:Enabled" value="false" />
  <add key="ClientValidationEnabled" value="true" />
  <add key="UnobtrusiveJavaScriptEnabled" value="true" />
  <add key="ida:Wtrealm" value="https://developertenant.onmicrosoft.com/WIF2OWINWebApp" />
  <add key="ida:AADInstance" value="https://login.windows.net" />
  <add key="ida:Tenant" value="developertenant.onmicrosoft.com" />
</appSettings>

Note: If you would be working with a provider other than Azure AD, you’d: a) skip the tenant part in the config b) go directly to App_Start/Startup.Auth.cs, scroll to the code that initializes the WsFederationAuthenticationOptions, and assign to the MetadataAddress property the full address of the metadata document you obtained earlier.

Done? Very good!

Now, the most delicate part. We need to tell VS that we want our project to start on the port that was assigned to the OTHER project (in this case https://localhost:44300/), instead of the one port the sample was configured to run on (https://localhost:44320/).

Right-click on the project in the solution explorer and choose properties. Click on the web tab on the left.

Find the Project URL field. Change the port shown there to match the one of the original project. Click Create Virtual Directory. You’ll get the following warning:

VS knows that there’s already a project mapped to that port, the original one, and just wants to make sure you’re OK to remap that port to the current project. That’s exactly what we want. Click OK. If everything goes well, you’ll get a confirmation.

That’s it! Shift+CTRL+S for saving everything, Shift+CTRL+B for building the project. Yes, I am a big fan of shortcuts.

It will take some time, given that on the very 1st build it needs to restore all NuGet packages, but it should be ready pretty soon.

Once it’s done, press F5.

One small difference from the original template is that this project is designed to offer an unauthenticated landing rather than imposing authentication for every resource. You can easily change this by moving the [Authorize] attribute around.

Hit Sign In.

So far so good… enter the creds of any user in the target Azure AD tenant.

Aaaaaand it’s done. Our OWIN-secured project successfully re-used the coordinates that the ASP.NET project creating experience originally provisioned in Azure AD.

Summary

When I bought my Surface Pro 2 I was super enthusiastic. Awesome screen, great stylus responsiveness. I loved it.
A couple of months ago the i7 version of the Surface Pro 3 came out, and I promptly grabbed one. The screen is absolutely incredible, it is feather light, super-fast… I use it all the time, including for writing this post.
And the Surface Pro 2? It’s no less great than when I got it, but I like the Pro 3 better… hence the Pro 2 is hitting eBay.

You know where I am going with this. WIF is still a great technology, super flexible, 100% supported… but now that Katana is out, I’d use it all the time if I could. I know this is the same for many of you, which is why I wrote this post. The support for the new model in the rest of our dev stack will come: in the meanwhile, if you have specific WIF->OWIN migration scenarios you’d like to get guidance for, feel free to drop me a line or hit me on twitter –  I’ll do my best to help