Setting up Debugging Environment for ASP.NET Katana and Windows Azure Active Directory

The process described in this post was tested on 01/13/2013 using Katana 2.0.2, Visual Studio 2013 and .NET Framework 4.5.

The authentication and authorization space is riddled with acronyms and cryptic terms like realm, issuer, tenant, audience URI and when you combine this with OAuth terminology and implementation specific terms, it becomes even more confusing and it is pretty easy to make mistakes especially if you are handling multiple identity providers.

There are good chances that you may mess up the configuration either in WAAD (Windows Azure Active Directory) or in the application server code. It exactly happened to me while working on a multi-tenant auth handling components for WebAPI; I was running into an authorization error which I had no idea why it’s happening.

I wasn’t sure how to enable tracing on Katana to see if it even helps. So, I resorted to the brute force approach of source code level debugging and thought that this process will save some time if you ever run into this issue.

Here is the process:

Step 1: git clone https://git01.codeplex.com/katanaproject

Step 2: Open “katana.sln” and add your existing ASP.NET WebAPI project to Katana solution.

[I prefer to configure authentication manually than using the VS 2013 WebAPI template. Manual approach will help me undo it if needed and also the wizard messes up with my app definitions inside WAAD. The steps for manual configuration are:

a. Install Microsoft.Owin.Security.ActiveDirectory and Microsoft.Owin.Host.SystemWeb and the associated dependencies

b. Add Startup.cs to contain code as seen in Step 5 later

c. Decorate the WebAPI controllers with [Authorize] attribute as needed]

Step 3: Install Owin using “install-package Owin” from nuget package manager

 [Note: Katana builds upon Owin]

Step 4: Add references to the following projects in the solution:

• Microsoft.Owin.Net45

This gets built as Microsoft.Owin.dll which contains fundamental interfaces (e.g. IHostingEngine, IAppLoader), core components (e.g. HostingEngine, AppActivator) and utilities for tracing. If you are targeting .NET 4.0, be sure to add a project reference to Microsoft.Owin.Net40 project.

• Microsoft.Owin.Host.SystemWeb.Net45

This gets built as Microsoft.Owin.Host.SystemWeb.dll which is necessary for integrating with ASP.NET pipeline]

• Microsoft.Owin.Security
• Microsoft.Owin.Security.ActiveDirectory

       [Note: our WebAPI project targets netfx 4.5]

Step 5: Add Startup.cs with the following code:

       public partial class Startup

{

    public void ConfigureAuth(IAppBuilder app)

    {

        app.UseWindowsAzureActiveDirectoryBearerAuthentication(

            new WindowsAzureActiveDirectoryBearerAuthenticationOptions

            {

                Audience = "[APP ID URI FROM WAAD]”,

                MetadataEndpoint = "[FEDERATION METADATA DOCUMENT URL]”,

                Realm = "[YOUR_TENANT.onmicrosoft.com"]

                      });

    }

}

Step 6: Set up break points in OAuthBearerAuthenticationHandler.cs which is located in the project Microsoft.Owin.Security.Oauth.

[Note: I set up breakpoint in the method “protected override async Task<AuthenticationTicket> AuthenticateCoreAsync()” as WS-Federation and OAuth JWT tokens ultimately gets validated in this code]

After all this effort, my problem was caused by a configuration mismatch for the “Audience” URI. App ID URI in the WAAD tenant is equivalent to “ActiveDirectoryFederationServicesBearerAuthenticationOptions.Audience” used by the above configured app.UseActiveDirectoryFederationServicesBearerAuthentication() extension method.

I hope this saves you some time in setting up your debugging environment in troubleshooting authentication issues.