Tivoli Federated Identity Manager Business Gateway and ASP.NET authentication

Using the Federated Identity Manager plug-in for IIS to perform a federated single sign-on to your ASP.NET application

In this article we show you how to enable your ASP.NET applications for federated single sign-on utilizing the Tivoli® Federated Identity Manager Business Gateway (FIM-BG) and the plug-in it provides for Microsoft® Internet Information Server Version 6 (IIS). Your existing forms-based authentication mechanism can be expanded to include support for participating in a federated single sign-on using the SAML 1.0, 1.1 or 2.0 protocols. Here, we take a sample ASP.NET application through the process of federated single sign-on enablement using FIM-BG and the plug-in for IIS.


Shane B. Weeden, Senior Software Engineer, IBM

Shane WeedenShane Weeden is a senior software engineer with the IBM Federated Identity Manager development team. He has worked in IT security for 13 years, and has spent the last seven years working with Tivoli Security products. Shane has been with the Federated Identity Manager development team since its conception, and now divides his time between customer-focused engagements and core product development activities. He holds a Bachelor of Information Technology from the University of Queensland in Australia.

developerWorks Professional author

Peter Cogill (pcogill@au1.ibm.com), Senior Software Engineer, IBM

Peter Cogill is a software engineer on the IBM Tivoli Access Manager team. He joined this team in 2003 after graduating from the University of Queensland with a Bachelor of Engineering (Software).

Gavin Bray (gavbray@au1.ibm.com), Software Engineer, IBM

Gavin Bray is an Advisory Software Engineer in the Tivoli Federated Identity Manager product development team. Gavin is the lead developer on TFIM's web service security management component. Gavin is based in the IBM Australia Development Laboratory.

12 September 2008 (First published 27 February 2007)


This article requires that you are familiar with FIM Enterprise or FIM-BG and the SAML 1.0/1.1/2.0 federated single sign-on technologies. You should be comfortable with configuring a federation using the FIM management console, and have a basic understanding of the role of the FIM plug-in for IIS V6 that ships with FIM-BG. For background material on FIM-BG and the FIM plug-in for IIS, please see the FIM-BG product documentation, which is also linked from the Resources section.

Solution overview

We begin with a simple ASP.NET application, which supports forms-based authentication to display information about the logged-on user and the HTTP request. The article describes how to expand the authentication capabilities of this application to include accepting SAML 1.0, 1.1 or 2.0 single sign-on requests from an identity provider partner.

We utilize the FIM-BG Runtime and the FIM plug-in for IIS to intercept and process requests to a Web site carrying single sign-on information. The FIM plug-in determines the identity of the authenticated user from the FIM-BG runtime response, and sets this username as an HTTP header in the request to the application. This is standard behavior of the FIM plug-in for IIS, and is demonstrated in Figure 1.

Figure 1. FIM Plug-in for IIS processing
FIM Plug-in for IIS processing
  1. The user authenticates to the identity provider environment.
  2. The identity provider's federated SSO system returns a security token to the user. The security token contains the user's identity and other attributes that the identity provider is willing to assert to the service provider.
  3. The user presents the security token to the service provider's FIM-BG runtime.
  4. The FIM-BG runtime validates the security token, extracts the user's identity and related attributes from the security token and stores them in an encrypted and signed LTPA cookie.
  5. The FIM plug-in intercepts the request to the target application, decrypts and verifies the LTPA cookie containing the user attributes, and maps these attributes to HTTP headers or server variables. This mapping is configurable but in this example the user's identity is mapped to the iv-user HTTP header.
  6. The target application detects the iv-user header and establishes a session with the browser (typically via a cookie).

Our solution introduces and provides sample code for an ASP.NET HTTP module which detects the iv-user username header and authenticates the user to the application. This corresponds to step 6 from the description in Figure 1. In the ASP.NET application environment this authentication has the same effect as if the user had logged into the application locally with a user name and password. A session cookie is established for the user session, and the authenticated user can now proceed to use the application.

Our article will not cover use of the FIM-BG administration console to configure your federation or its partners. This is standard product behavior that you should be familiar with as a pre-requisite to this article.

The sample application

The sample application used for this article is a very basic ASP.NET application. It comprises a main page that displays information about the current user's session. The application also contains a log-in form that is used for forms-based authentication. The standard ASP.NET authentication API is used to authenticate the user based on the details supplied in the form. Authorization is handled by the ASP.NET environment. The screenshots in Figure 2 and Figure 3 show the application as seen by the user.

Figure 2. Test application initial log-in page
Test application initial log-in page
Figure 3. Test application main page
Test application main page

Figure 3 shows that the value "Alice" has been authenticated using a forms-based authentication mechanism. The FIMTestAuthenticationCookie is a session cookie used by the ASP.NET environment to maintain the user's identity and session between requests to the application. The name of the user's cookie, in this case FIMTestAuthenticationCookie, is controlled by the application's Web.Config file, as shown in Listing 1.

Listing 1. Initial Web.Config
<?xml version="1.0"?>
    <compilation debug="true" />
    <authentication mode="Forms">
      <forms name="FIMTestAuthenticationCookie" 
             protection="All" timeout="30">
        <!-- The credentials here are the users authorized to perform a local log-on -->
        <credentials passwordFormat="Clear">
          <user name="Alice" password="password"/>
          <user name="Bob" password="password"/>
    <!-- Only allow authenticated users to access pages in the application -->
      <deny users="?" />

There are two main sections to this Web.Config file: the authentication section and the authorization section. The authentication section defines how the ASP.NET environment challenges the user to prove their identity when a protected page is accessed. In this case, the only defined method is the Forms authentication method. The name attribute defines the name of the session cookie (as seen in Figure 3). The loginUrl attribute defines the URL of the log-in page that challenges the user to authenticate. (This is the URL of the log-in page shown in Figure 2.) Finally, the credentials section defines the credentials of the users that can access the application - this application has two users, Alice and Bob, and they both have the same password. The authorization section defines which users have access to the application. In this case, the only rule defined denies access to all unauthenticated users. If an unauthenticated user attempts to access the application, the ASP.NET environment challenges the user for authentication.

The FIM Authenticator HTTP module

Now that we have described our test application, we need to start the process of integrating it with the FIM plug-in for IIS. As mentioned above, the FIM plug-in for IIS can provide identity information about the user, in the form of an HTTP header. We want to take this information and create an ASP.NET session for that user. Listing 2 shows a pseudo-code representation of what we want to do in order to perform federated single sign-on into the demonstration application. This is implemented within the ASP.NET framework with an HTTP module.

Listing 2. Authentication pseudo-code
if the request is not already authenticated then
    if the 'iv-user' header is present and not empty then
        specify that an authentication cookie for the user specified in the
            'iv-user' header should be set in the response from IIS
        redirect the user to the currently requested location to force the cookie
            to take effect
    end if
end if

As a part of the ASP.NET architecture, HTTP modules allow third-party modules to be called at various points in the ASP.NET processing cycle. HTTP modules can register to be invoked at the AuthenticateRequest event. An HTTP module that registers for this event will be called when the ASP.NET environment is attempting to authenticate the user making the request. For those readers familiar with WebSphere® development, this model is very similar to the concept of WebSphere Trust Association Interceptors. We will develop an HTTP module called "FIM Authenticator", which will detect the presence of the iv-user header and use it to authenticate a user into ASP.NET. Figure 4 illustrates how the FIM Authenticator HTTP Module fits within the ASP.NET authentication process.

Figure 4. ASP.NET authentication processing
ASP.NET authentication processing

Listing 3 presents the code for the FIM Authenticator HTTP module in its entirety. This implementation is written in Microsoft C#, but an equivalent module could be written using any language that can target the Microsoft Common Language Runtime. This code is compiled into a DLL which can be bundled with your application or installed as a global handler affecting all applications.

Listing 3. FIM Authenticator implementation
using System;
using System.Configuration;
using System.Web;
using System.Web.Security;

namespace IBM.Tivoli.FIM
     * FIMAuthenticator is a class that implements the IHttpModule interface
     * to provide federated single sign-on into an ASP.NET application, authenticating
     * the request based on the value in the 'iv-user' header that has been set
     * by the FIM plug-in for IIS.
    public class FIMAuthenticator : IHttpModule
        public FIMAuthenticator()

         * Register which events we want to be invoked for. The only event that the
         * FIMAuthenticator handles is the AuthenticateRequest event.
        public void Init(HttpApplication app)
            app.AuthenticateRequest += new EventHandler(this.FIM_AuthenticateRequest);

        public void Dispose()

        private void FIM_AuthenticateRequest(Object sender, EventArgs e)
             * If the request is not yet authenticated, check if the iv-user header
             * is present, and if so authenticate based on that.
            HttpApplication app = (HttpApplication)sender;
            HttpContext ctx = app.Context;

            if (!ctx.Request.IsAuthenticated)
                string[] ivusers = ctx.Request.ServerVariables.GetValues("HTTP_IV_USER");
                if (ivusers != null && ivusers.Length > 0)
                     * Authenticate the user, then send them back to this page
                     * authenticated with the user cookie
                    FormsAuthentication.SetAuthCookie(ivusers[0], false);

The Downloads section contains a complete Microsoft Visual Studio® .NET 2005 solution for the FIM Authenticator, including a compiled dll that is ready to use.

With the FIM Authenticator module written, all that remains is to modify the application so that it makes use of this module to achieve federated single sign-on.

Integrating FIM Authenticator into the application

The final step is to integrate the FIM Authenticator into the sample application. We recommend two steps for the enablement:

  • Modify the application's Web.Config file to use the FIM Authenticator
  • (Optionally) update the log-in page to better accommodate federated single sign-on users

Note that the only thing that needed to be changed in the application to enable federated single sign-on was the application's configuration file - Web.Config. As a courtesy to our FSSO users we also updated the log-in page. The sample application itself did not need to be modified at all.

The use of HTTP modules within the ASP.NET application is controlled by the httpModules configuration section. This configuration section can be defined at the computer, site, or application level. The httpModules configuration defined at higher levels will be inherited by lower levels. In our illustration, we only enable our sample application for federated single sign-on (not other applications hosted in the environment). We add the FIM Authenticator into the httpModules configuration section for the application's Web.Config only. Listing 4 shows the httpModules configuration section and its position within the Web.Config file. For brevity, the rest of the configuration file is omitted, however it remains the same as in Listing 1.

Listing 4. Web.Config httpModules section
<?xml version="1.0"?>
      <add type="IBM.Tivoli.FIM.FIMAuthenticator,FIMAuthenticator" 

The syntax for adding an HTTP module into the application's configuration is <add type="[Class],[Assembly]" name="[ModuleName]" />. In Listing 3, we specified that our class was called FIMAuthenticator and it was defined in the IBM.Tivoli.FIM namespace, therefore the [Class] we specify is IBM.Tivoli.FIM.FIMAuthenticator. The [Assembly] is the name of the CLR assembly that our class is defined in. This is the name of the Dynamic Link Library (DLL) file that the [Class] is found in. In the sample projects, we have compiled the FIMAuthenticator module into the FIMAuthenticator.dll file, so this is the value used for the [Assembly]. When defined as part of the application configuration, the ASP.NET environment attempts to locate the assembly in the Global Assembly Cache or in the bin subdirectory of the application. Our example uses the FIM Authenticator module in the application's bin subdirectory.

The other (optional) task is to update the log-in page to accommodate federated single sign-on users. We do this by adding a link to the "Where are you from?" (WAYF) page for the FIM SAML federation on the service provider. This link is a standard feature of the Tivoli Federated Identity Manager product although the exact URL depends upon the log-in URL of your configured FIM federation. More information on this and other parts of FIM (such as creating the federation) are contained in the Resources section.

Adding the link to the WAYF page allows federated single sign-on users who are presented with the log-in page (because their session expired or they accessed the application directly) to navigate to their identity provider and perform the federated single sign-on operation. Figure 5 shows the user's view of the final version of the login screen. For the implementation of this page, see the final version of the sample application in the Downloads section.

Figure 5. Test application final login page
Test application final login page

Configuration notes for the FIM plug-in for IIS

The configuration settings for the FIM plug-in for IIS are contained in the itfimwebpi.xml file in the FIM installation directory. Detailed information about the various parameters is available in the FIM-BG product documentation for configuring IIS plug-in.


FIM-BG ASP.NET Authentication Integration Code1tfimbg_aspnet_fimauthenticator.zip11KB
FIM-BG ASP.NET Initial Demonstration Application2tfimbg_aspnet_demoapp_initial.zip2KB
FIM-BG ASP.NET Final Demonstration Application3tfimbg_aspnet_demoapp_final.zip4KB


  1. tfimbg_aspnet_fimauthenticator.zip - the FIMAuthenticator HTTP module for authenticating to ASP.NET applications via the FIM IIS plug-in
  2. tfimbg_aspnet_demoapp_initial.zip - the sample application in its original state before enabling it for federated single sign-on authentication with FIM-BG
  3. tfimbg_aspnet_demoapp_final.zip - the sample application after being enabled for federated single sign-on authentication with FIM-BG



Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks

Zone=Tivoli (service management), Security, Tivoli, Web development
ArticleTitle=Tivoli Federated Identity Manager Business Gateway and ASP.NET authentication