Project Description
This sample provides implementation of Active Directory based STS (Security Token Service) for web applications.

Overview
Security is a major concern today for an application, it is very cumbersome and error prone to write a security validation logic for each and every application. It will be very efficient if the validation logic can be decoupled from application, in this scenario the application can rely on third party to valdate the users and return their identity. The objective here is to build a security validator that will authenticate the application user from a authentication store (in this case Active Directory) and provide the necessary claims.

Solution Approach
Create security STS (Security token service) provider for authenticating the application users on behalf of the application. Custom validation logic will be written to validate the users from the enterprise active directory. After the application user gets validated, the STS will fetch the required information and generate the user claims using WIF (Windows identity foundation).

The metadata and authentication settings of the application relying on STS will need to be modified to accept Tokens from the STS provider. The application will use the tokens received from the token provider for validating the user and controlling his access to the specific areas of application.

High Level Overview

Context Diagram

Prerequisites

Microsoft® Windows® Vista SP2 (32-bits or 64-bits) , Microsoft® Windows Server 2008 SP2 (32-bit or 64-bit), Microsoft® Windows Server 2008 R2, Microsoft® Windows® 7 RTM (32-bits or 64-bits)
Microsoft® Internet Information Services (IIS) 7.0
Microsoft® .NET Framework 3.5 SP2
Microsoft® Visual Studio 2008 SP1
Microsoft® Windows Identity Foundation Runtime
Microsoft® Windows Identity Foundation SDK

By default the STS will look for the certificate in the user personal store “My” in the LocalMachine. So you need to install the certificate in the user local machine store so that the STS can find the certificate.

A sample certificate utility is present in the deployment “script for certificate\Scripts”,you have to run the “SetupCertificates.cmd”in scripts folder with Administrator permissions to install the default “STSTest” certificate. “capicomdcsdk” also needs to be installed on your system to run the attached script.This can be downloaded from “http://www.microsoft.com/downloads/details.aspx?FamilyID=860EE43A-A843-462F-ABB5-FF88EA5896F6”
if you want to change the certificate you have to change the configuration parametres as discussed in the tool configuration section below and you also need the certificate Thumbprint in the Application configiguration file , the certificate thumbprint can be obtained from the certificate properties.

<issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
<trustedIssuers>
	<add thumbprint="0E2A9EB75F1AFC321790407FA4B130E0E4E223E2" name="http://localhost:54780/TestWebSite_STS/"/>
</trustedIssuers>
</issuerNameRegistry>

STS Configuration
The STS configuration parameter needs to be configured in web.config before the STS can be used:

Signing Certificate name: The signing certificate is used to sign the STS generated tokens. The signing certificate needs to be installed in the trusted root certificates in personal store before the certificate name can be given as signing certificate; this is required by the STS

ex: ststestcert

<add key="SigningCertificateName" value="CN=*********"/>

Encrypting Certificate name: The encrypting certificate is used to encrypt the STS generated tokens, The Encrypting certificate needs to be installed in the trusted root certificates in personal store before the certificate name can be given as signing certificate. This is optional and needs only when you want to encrypt your tokens.

<add key="EncryptingCertificateName" value="********"/>

DefaultDomain: The Default domain where the STS will validate the user and fetch the user information from active directory, If the user gives the domain name in the username this setting will be ignored Ex: domainname.

<add key="DefaultDomain" value="*********"/>

StsUrl: This is the STS endpoint URL, this needs to be configured with the hosting location of the URL, else the STS will not work.

<add key="StsUrl" value="https://servername/virtualdirectory"/>

ClaimTypes: These are the activedirectory mapping which will return the required information. We recommand not to change this information unless your active directory has different parameters.

Host Server: By default the STS will reply to requests from “localhost”, if you want to allow the STS to reply to other domain, you can configure the Hostserver in the Hostserver key ex: testserver

<add key="HostServer" value=" testserver "/>

<add key="ClaimTypes" value="physicaldeliveryofficename,mail,name,company"/>

STS usage with Web application
You can directly use the federation utility if you want to use the tool with an on premise application like an asp.net website or web application.

Step 1: Now we have to add a reference to STS by using the Fedaration tool

If you have the WIF installed there will be an option of “Add STS reference” when you right click the Web application.

This will launch the federation utility

In application URL you have the give the actual hosting path of the application

Step 2: In the next screen select “Use an existing STS” you need to give the path where you hosted the Validator STS.

Give the full path of the metadata handler ex:
https://hostserver/loginvalidation_STS/federationmetadata/2007-06/federationmetadata.ashx
Before the next step you may be asked to validate the certificate, just accept the certificate.

Step 3: In the next step you will be asked to enable/disable encryption, here select “No encryption”, only select the “Enable encryption” if you have set a certificate in the “EncryptingCertificateName”

Step 4: In the next screen you will see the claims offered by the “Security token service” we hosted earlier.

Step 5: Finally you will be asked to review the settings, select finish and you will be done. The site is now configured with the security STS.

Now if you run the site you will be presented with the security validation screen as below.

Step 6: Input your network username and password and you will be validated either from the default domain you have configured in the STS configuration or the domain you have used with the username.

To fetch the tokens into your website put the following code

IClaimsPrincipal icp = Thread.CurrentPrincipal as IClaimsPrincipal;
         IClaimsIdentity ici = icp.Identity as IClaimsIdentity;
         Response.Write("Welcome to test website <br/><br/>:Claims:<br/>");
         foreach (Claim c in ici.Claims)
            Response.Write(c.ClaimType + "-" + c.Value + "<br/>");

c.ClaimType will represent the claim type and c.Value will represent the claim value.
You will also need to reference the following namespaces in your page

using Microsoft.IdentityModel.Claims;
using System.Threading;

Now follow step 1-5 for the web application for adding the STS reference to your windows azure application.

Final steps
Now you are ready to run your application with validation from STS validator, you have to make sure that the STS valuator is accessible from the location where you are trying to access the application

References
http://msdn.microsoft.com/en-us/security/aa570351.aspx
http://msdn.microsoft.com/en-us/evalcenter/dd440951.aspx
http://technet.microsoft.com/en-us/library/cc776617(WS.10).aspx
http://searchwindowsserver.techtarget.com/generic/0,295582,sid68_gci1050336,00.html