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 Windows Identity Foundation.


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 Winodws Identity Foundation: 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.

The last figure 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

The last figure 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 Windows Identity Foundation. If you have feedback, we will be glad to do our best for incorporating it in the next deliverables.