I made you a token… but I eated it: or how to debug authentication issues in ASP.NET with SecurityTokenVisualizerControl

(in case Internet memes are not your thing: before you flame me for poor grammar, know that the “I eated it” is intentional: see https://icanhascheezburger.com/2007/01/15/i-made-you-a-cookie/)

Another week, another sample ASP.NET control for identity!

There are moments in the development of claims-based websites in which you want to take a good look at the token that you are getting from the STS: if your pages are not behaving in the way you’d expect, you never really know if that’s because you are not getting the claims you were expecting or if you are not processing them in the right way. That’s just one example of why you’d want to inspect the identity info in the current context.

Normally you have two strategies for inspecting the content of the current context:

1. You write some debugging/tracing code. You know, the classic foreach on all the claims in the current IClaimsIdentity that you see so often in the samples. The approach works, but it is pretty repetitive (it’s code that you rewrite almost verbatim across different projects) and it’s usually not very exhaustive (maybe you print the claim values but it turns out that the issue was in the IntendedAudience).
2. You attach a debugger to the web app. This works very well, however it implies that the system allows you to do so and that’s not always the case.

Today’s sample control provides you with a third way. Just drag the SecurityTokenVisualizerControl (STVC) on your page, you’ll obtain a fairly comprehensive view of what’s going on in your identity context in nice tabular format, collapsible in a tiny icon so that it does not interfere too much with the rest of the page. The STVC contains code that you would otherwise write yourself in 1, and at the same time it almost as exhaustive as if you’d explore the current context using 2: all this without leaving the browser.

Below there’s a copy of the documentation accompanying the sample package. The control is extremely easy to use: as usual, remember that this is just sample code and you should be careful in using it. This time there are some issues that we felt we should highlight: you will find them in the summary section. That said, have fun!

Kudos to the Southworks team (Ariel, Matias, Tim, Diego, Fernando) who helped us on this, whipping the entire thing in just a week!

Overview

The Security Token Visualizer control (STVC) is a simple ASP.NET server control which displays in a compact layout useful information about claims-based identity in a web site secured with the Geneva Framework.

Once expanded, the STVC displays information about the current identity context

The STVC is intended to be a debugging aid, which helps you to inspect what identity info you are receiving from the STS without the need for attaching a debugger to your website. Furthermore, STVC spares you the repetitive task of writing code that retrieves and render claim values or other info about the incoming security token that are typically needed in the development & testing phases of your application life cycle.

The Control in Action in the Sample Website

The STVC in Visual Studio’s toolbox

The sample package installs the STVC in your Visual Studio toolbox, under the DPE Identity Samples tab.

The Default.aspx and Public.aspx pages in the sample solution

The package includes a sample solution which is used for demonstrating how the control works, however its usage is so simple that you can try it on any web page from a web site protected with the Geneva Framework: just drag it on the page and you are good to go. At design time the control appears as a red token: at run time the control will maintain its design appearance, however it will also display a “+” sing on its left that, when clicked, will expand the control in order to show various tables containing the identity information being tracked. The only property exposed by the control, Font, influences which font settings will be used for displaying information when expanded.

Figure 3 shows a couple of simple pages from the sample solution. Default.aspx can be reached only by users who successfully authenticated with a certain STS (included in the solution). Public.aspx can instead be reached by unauthenticated users. Both pages carry an instance of STVC.

Let us start with Public.aspx: open a browser and navigate to https://localhost/FabrikamAirlinesWebSite/Public.aspx.

STVC on a page displayed by an unauthenticated user

Once expanded, the control will simply display a warning that the current user is not authenticated, or his or her identity is not based on claims.

Let us now try with Default.aspx: navigate to https://localhost/FabrikamAirlinesWebSite. You will be immediately redirected to a development STS, as shown below.

The credential gathering page at the local development STS

Just hit submit, you will land on Default.aspx. If you expand the control, you will now see the list of identity properties in the current context.

STVC fully populated & expanded

Figure 6 shows the kind of information STVC shows. Namely:

• Issued Identity – this section shows the content of the Claims collection in the first IClaimsIdentity in the current IClaimsPrincipal. For every claim we display:
  • Type
  • Value
  • Issuer
  • Original issuer
• Delegated Identity – shows claims in the delegate member of the IClaimsIdentity instance mentioned above
• Raw SAML – shows the XML of the SAML received
• SAML Properties – contains SAML-specific properties such as Intended Audience, ValidTo, certificates used to sign (from the token) and to encrypt (from the web site configuration), etc
• The signing certificate bits can be downloaded directly via the control

It’s as simple as that!

Summary

The Security Token Visualizer Control is a rudimentary but, we hope, useful tool that can help you to troubleshoot certain identity-related issues on your web pages by saving you the hassle to write repetitive debug & tracing code.

It is important to keep in mind that this is just a very simple sample, offered as a didactic tool: STVC does not pretend to be complete, should not be used in production and has various well-known shortcomings:

• Often the issues you need to solve prevent your web site from obtaining a token, or the token may be invalid and throw: in that case, STVC is not useful since the execution will halt before hitting its code
• While we made efforts for maintaining a pluggable architecture, the current release is strongly biased toward SAML: we wanted to make sure we covered the most common case, if you need to support different token types you can write your own handler and plug it in STVC
• Since STVC is very handy for situations in which you can’t attach a debugger, the risk is that you will use liberally and end up forgetting it on live pages: that may have unintended consequences, as STVC would show info that would not be normally available. We made the icon bright red in the hope of making the control very visible and minimize the chances you will forget it on

As usual, we hope that our sample will make your life easier as you take advantage of claims based identity and the Geneva Framework. If you have feedback, we will be glad to do our best for incorporating it in the next deliverables.