Sebastian Iacomuzzi’s Blog

More info, here

Definition

“A Security Token Service (STS) is the plumbing that builds, signs, and issues security tokens using the interoperable protocols…”

“The “Zermatt” Framework makes it easy to build your own STS. It’s up to you to figure out how to implement the logic, or rules that drive it (often referred to as security policy).”

Active vs Passive

Steps to create our STS

1. Implement a custom STS class
2. Implement a custom STS configuration class
3. Integrate the STS implementation with the hosting environment. (Here’s the differences between an active and passive STS implementation)

#1 - Implement a custom STS class

SecurityTokenService class handles the task of serializing and de-serializing the protocols. We can implement a custom STS by inheriting from this class and providing the following functionality:

• Decide what claims to issue.
• Decide what STS signing credentials the STS should use to sign the issued token.
• Decide what relying party encrypting credentials the STS should use to encrypt the token before sending it (typically, the RP’s certificate information is shared out of band).
• Decide what URL the response message goes to.

We need to override two methods from SecurityTokenService class:

GetScope

/// <summary>
/// This methods returns the configuration for the token issuance request. The configuration
/// is represented by the Scope class.
/// </summary>
/// <param name=”principal”>The caller’s principal</param>
/// <param name=”request”>The incoming request</param>
/// <returns></returns>
protected override Scope GetScope(IClaimsPrincipal principal, RequestSecurityToken request)
{
            // Validate the request’s AppliesTo
            ValidateAppliesTo(request.AppliesTo);

            // Create the scope using the request and the STS signing credentials.
            // The request.appliesTo is automatically copied to the scope instance.
            Scope scope = new Scope(request, _signingCreds);

            // Setting the encrypting credentials
            scope.EncryptingCredentials = _encryptingCreds;

            // Set the ReplyTo address for the WS-Federation passive protocol
            // (THIS IS NOT USED IN THE WS-TRUST ACTIVE CASE)
            scope.ReplyToAddress = scope.AppliesToAddress + “/Default.aspx”;

            return scope;
}

GetOutputSubjects

/// <summary>
/// This methods returns the claims to be included in the issued token.
/// </summary>
/// <param name=”scope”>The scope that was previously returned by GetScope method</param>
/// <param name=”principal”>The caller’s principal</param>
/// <param name=”request”>The incoming request</param>
/// <returns>The claims to be included in the issued token.</returns>
public override ClaimsIdentityCollection GetOutputSubjects(Scope scope, IClaimsPrincipal principal, RequestSecurityToken request)
{
            IClaimsIdentity callerIdentity = (IClaimsIdentity)principal.Identity;
            ClaimsIdentity outputIdentity = new ClaimsIdentity();
            ClaimsIdentityCollection returnValue = new ClaimsIdentityCollection();

            // Name claim
            outputIdentity.Claims.Add(new Claim(System.IdentityModel.Claims.ClaimTypes.Name, callerIdentity.Name));

            // Age Claim (custom claim)
            outputIdentity.Claims.Add(new Claim(“http://ZermattSamples/2008/05/AgeClaim”, “25″, ClaimValueTypes.Integer));

            returnValue.Add(outputIdentity);
            return returnValue;
}

#2 - Implement a custom STS configuration class

We can implement a custom STS configuration class by inheriting from SecurityTokenServiceConfiguration class and configuring the following properties:

• The STS IssuerName. Configure this by passing the value to the base class constructor.
• The STS implementation class type. Configure this to point to your custom STS implementation class.

public class MySecurityTokenServiceConfiguration : SecurityTokenServiceConfiguration
{
        public MySecurityTokenServiceConfiguration()
            : base(“HelloWorldSTS”)
        {
            SecurityTokenService = typeof(MySecurityTokenService);
        }
}

#3 - Integrate the STS implementation with the hosting environment

The integration step varies between active and passive STSes.

Active STS

Hosted in a console application

SecurityTokenServiceConfiguration config = new MySecurityTokenServiceConfiguration();

// Add the STS endoint information
config.TrustEndpoints.Add(new ServiceHostEndpointConfiguration(“http://localhost:6000/HelloWorldSTS”, new WSHttpBinding(), typeof(IWSTrustFeb2005SyncContract)));

// Create the WS-Trust service host with our STS configuration
using (WSTrustServiceHost host = new WSTrustServiceHost(
            config,
            new Uri(“http://localhost:6000/HelloWorldSTS”)))
{
                host.Open();
                Console.WriteLine(“Active STS started, press ENTER to stop …”);
                Console.ReadLine();
                host.Close();
}

Hosted in a IIS Web-Based Service

We need to host it in IIS and set up a .svc file in the web site. In this case, the .svc file needs to contain a “Factory” parameter that points to WSTrustServiceHostFactory class or a class inherited from it (if programmatic configuration of the WCF service host is needed), and a “Service” parameter that points to a custom STS configuration class.

> .svc file:

<%@ServiceHost language=C#
                Factory=”MyTypes.ActiveSTSFactory”
                Service=”MyTypes.MySecurityTokenServiceConfiguration”%>

> Custom STS factory:

// Creating a WSTrustServiceHostFactory instance that is capable of handling WSTrust protocol
public class ActiveSTSFactory : WSTrustServiceHostFactory
{
        public override ServiceHostBase CreateServiceHost(string constructorString, Uri[] baseAddresses)
        {
            // Set the required parameters and return the serviceHost instance
            ServiceHostBase serviceHost = base.CreateServiceHost(constructorString, baseAddresses);

            //
            // Perform any necessary imperative configuration of the serviceHost instance here
            //

            // return the configured ServiceHost instance to WCF activation
            return serviceHost;
        }
}

Passive STS

Add the custom classes to the web application’s code behind file

To expose the STS functionality that you have implemented by using the WS-Federation passive protocol, we can use the “Zermatt” Framework FederatedPassiveTokenService control. (Note: make sure that you install the “Zermatt” Framework controls into the Visual Studio toolbox).

1. Create an ASP.NET web page to handle the WS-Federation passive protocol sign-in requests and add the FederatedPassiveTokenService control.
2. Set the Service attribute of the control to the type name of your STS configuration class.
3. When deployed, make sure that the intended authentication is enabled for the passive STS Web application. The FederatedPassiveTokenService control requires that the caller be authenticated before the page is rendered. If the caller of the page is not authenticated, the control will not do anything.

<idfx:FederatedPassiveTokenService
            ID=”TokenService1″
            runat=”server”
            Service=”PassiveSTS.MySecurityTokenServiceConfiguration”>
</idfx:FederatedPassiveTokenService>

Zermatt is a set of .NET Framework classes. It is a framework for implementing claims-based identity in your applications.

When you build claims-aware applications, the user presents an identity to your application as a set of claims. One claim could be the user’s name, another might be an e-mail address. The idea here is that an external identity system is configured to give your application everything it needs to know about the user with each request she makes, along with cryptographic assurance that the identity data you receive comes from a trusted source.

Object Model

Microsoft.IdentityModel namespace (included in Zermatt) extends the classical .NET model, based on the IPrincipal and IIdentity interfaces, by creating two specialized interfaces: IClaimsPrincipal and IClaimsIdentity:

IClaimsPrincipal

In the claims model multiple users or claims-based identities can be party to a single action. The IClaimsPrincipal interface defines the data and behavior of the identities associated with an execution context.

IClaimsPrincipal exposes a collection of identities, each of which implements IClaimsIdentity. In a common case, there will be a single issuer and a single token and the identities collection will only have one element. However, it’s possible in advanced scenarios for a relying party to ask (via policy) for more than one security token, potentially from different issuers.

IClaimsIdentity

This interface defines the basic functionality of a ClaimsIdentity object. It is recommended that this interface be used to access the methods and properties of ClaimsIdentity instead of using ClaimsIdentity directly.

All ClaimsIdentity objects implement the IClaimsIdentity interface.

IClaimsIdentity extends IIdentity and when you look at a user’s identity, you can get her name the same way you always have. In addition, you can look at IClaimsIdentity.Claims to get more information pertaining of the user’s identity, like her email address.

Claim

A Claim describes a property of a subject as observed by or attested to by an issuer. Examples include group or role membership, or age and geographic references. A claim can be evaluated to determine access rights to data and other secured resources during the process of authorization.

Claim.ClaimType is a string (typically a URI) that tells you what the value of the claim means. For example, a claim with a ClaimType of “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname” represents a user’s first name.

Once you know the type of the claim, you can read its value from Claim.Value and with Claim.ValueType you can deserialize the value of the claim getting the format of the value.

ClaimsPrincipal

ClaimsPrincipal has the static Current property that is the IClaimsPrincipal associated with the current context.

Helpful links

· Microsoft Code Name Zermatt Setup Package

· Microsoft Code Name “Zermatt” white paper for developers by Keith Brown

· Vittorio Bertocci’s blog

· Kim Cameron’s Identity Blog

· Pedro Felix’s blog

In the following posts, I’ll try to show some samples about how to implement Zermatt in our applications and services.

The Smart Client Software Factory (SCSF) provides a set of guidance for architects and developers building composite smart client applications. The factory includes samples, reusable code and a guidance package which automates key development tasks from within Visual Studio.

New In This Release

> Full support for Visual Studio 2008 and .NET Framework 3.5. This release does not support Visual Studio 2005.

> Side-by-side usage of the April 2008 Guidance Package with the May 2007 Guidance Package.

> Support for Enterprise Library 3.1.

> Fixed bugs indentified by the community.

> Requires Guidance Automation Extension 1.4.

• More info
• Smart Client Software Factory - April 2008
• Smart Client Software Factory Source Code - April 2008
• Smart Client Software Factory Documentation - April 2008

This is a release candidate, and may have bugs. We have not completed testing the factory.

Give us feedback on the discussion board.

Download

This is a beta release and still has known bugs. We have not completed testing the factory.

Download

New Features

• All solution and projects migrated to Visual Studio 2008 and .NET Framework 3.5.
• DockPanelWorkspace and FormWorkspace added to SCSFContrib.CompositeUI.WinForms project.
• Action Catalog Service added to SCSFContrib.Services project.
• Added Visual Studio templates and installer for Trusted and Untrusted modules in the WPF/CAB Shell.

New Samples

• BankTeller implementation using a pure WPF application.
• Demo Application with its Demo Script that provides step-by-step instructions to create a SC-SF application.
• OrdersManager application that demonstrates how to integrate the CAB and SC-SF with Windows Workflow Foundation.
• TestSuite reference application showing DockPanelWorkspace usage.
• WPF CAB Shell sample application (source code, libs and unit tests).

Download

Note: This is an alpha release and still has known bugs. We have not completed testing the factory. Use at your own risk.

Known issues

• If the SCSF source is installed on the default path, compiling Quickstarts.WPFIntegration.sln will fail with path too long error.
• If the SCSF source is installed on the default path, compiling GuidancePackage.sln will fail with path too long error.
• Unit tests of CompositeUI.WPF.Tests project (in CompositeUI-WPFExtensions.sln) will fail when executed under debug mode.

Give us feedback on the discussion board.

Download

In this post we described a bug in the Ajax Control Toolkit v1.0.10920 that caused the AutoComplete Extender to behave incorrectly. The main problem was that we were getting ‘undefined’ as the list of suggested words when using purely numeric values, as shown in the following figure:

Fortunately, the Ajax Toolkit Team managed to solve the issue in changeset 27752 so we do not get the list of ‘undefined’ options anymore*.

Download Ajax Control Toolkit changeset 27752

Note: To use the new toolkit version, simply extract zip file, load the "AtlasControlToolkit-27752\Development\AjaxControlToolkit.sln" solution in Visual Studio and run it to generate the assemblies.

*However, take into account that the first issue mentioned in this post has not been solved yet (No autocomplete list is shown until you hit the backspace key).

With Web Client Software Factory, when you require your application to store information in the session state, you can use the Composite Web Application Block class StateValue to store the information. This class supports code that runs both in a Web server environment (the session is available, and data is stored there) and outside of a Web server environment (no session is available, such as when you run your unit tests, and the data is stored in memory). Therefore, StateValue objects are useful to increase the testing surface of your application.

By default, StateValue objects use the ASP.NET Session when the code is running in a Web server. However, when persisting session information in ASP.NET web applications, developers may not want to rely on the ASP.NET Session state and might prefer to use their own persistence mechanism that, for example, uses a custom database.

The purpose of this post is to demonstrate how to create a new Session State Locator Service, and wire everything up so the StateValue injection occurs with your custom state persistence mechanism.

Implementation

1) Create a class that implements the IHttpSessionState interface. In this example, the session information is stored in a database.

public class MySessionState : IHttpSessionState
{
    private DatabaseHelper _dbHelper;
    private string _userName;

    public MySessionState()
    {
        _dbHelper = new DatabaseHelper(/* connection string */);
        _userName = HttpContext.Current.User.Identity.Name;
    }

    #region IHttpSessionState Members
    public object this[string name]
    {
        get { return dbHelper.GetValue(_userName, name); }
        set { dbHelper.SetValue(_userName, name, value); }
    }

    /// …
    /// Our IHttpSessionState implementation
    /// …
    #endregion
}

2) Create a class that implements the Microsoft.Practices.CompositeWeb.Interfaces.ISessionStateLocatorService interface. This service must return an instance of the class that you implemented in the previous step. The Composite Web Application Block uses this service to inject an instance of IHttpSessionState to StateValue objects.

public class MySessionStateLocatorService : ISessionStateLocatorService
{
    #region ISessionStateLocatorService Members

    public System.Web.SessionState.IHttpSessionState GetSessionState()
    {
        return new MySessionState();
    }

    #endregion
}

3) Create a class that inherits from WebClientApplication class. In this class you will register your custom ISessionStateLocatorService.

public class MyWebApplication : WebClientApplication
{
}

4) Override the AddRequiredServices method, and add code that removes the SessionStateLocatorService service and registers the custom one.

public class MyWebApplication : WebClientApplication
{
    protected override void AddRequiredServices()
    {
        base.AddRequiredServices();

        base.RootContainer.Services.Remove();
        this.RootContainer.Services.AddNew();
    }
}

Using the Custom Implementation

To use the custom implementation you have to update the Global.asax file to specify the custom global application class.

<%@ Application Language=“C#” Inherits=“MyCustomSessionState.MyWebApplication” %>

After that, you can use StateValue objects to manage state across requests in the same way as always:

1) Add a public field of type StateValue to your class, where T is the type of the object you want to persist across requests (in this case, the Customer class)

public StateValue _currentCustomer;

2) To access the info, use the Value property of the StateValue class.

// Set the value
_currentCustomer.Value = new Customer();

// Get the value
Customer customer = _currentCustomer.Value;

You can find more information about the StateValue class in the topic Developing Web Client Applications | How to: Use Session State with Unit Testing from the WCSF Documentation.

Important: The code available for download is provided “as is” with no warranties of any kind.

Attachment(s): MyCustomSessionState.zip