Tamper-Evident Configuration Files in ASP.NET

A couple weeks ago someone sent a message to one of our internal mailing lists. His message was pretty straightforward: how do you prevent modifications to a configuration file for an application [while the user has administrative rights on the machine]?

There were a couple responses including mine, which was to cryptographically sign the configuration file with an asymmetric key. For a primer on digital signing, take a look here. Asymmetric signing is one possible way of signing a file. By signing it this way the configuration file could be signed by an administrator before deploying the application, and all the application needed to validate the signature was the public key associated with the private key used to sign the file. This separated the private key from the application, preventing the configuration from being re-signed maliciously. It’s similar in theory to how code-signing works.

In the event that validation of the configuration file failed, the application would not load, or would gracefully fail and exit the next time the file was checked (or the application had an exclusive lock on the configuration file so it couldn’t be edited while running).

We are also saved the problem of figuring out the signature format because there is a well-respected XML signature schema: http://www.w3.org/2000/09/xmldsig#. WCF uses this format to sign messages. For a good code-walkthrough see Barry Dorrans’ Beginning ASP.NET Security. More on the code later here though.

Technically, this won’t prevent changes to the file, but it will prevent the application from accepting those changes. It’s kind of like those tamper-evident tags manufacturers stick on the enclosures of their equipment. It doesn’t prevent someone from opening the thing, but they will get caught if someone checks it. You’ll notice I didn’t call them “tamper-resistance” tags.

Given this problem, I went one step further and asked myself: how would I do this with a web application? A well-informed ASP.NET developer might suggest using aspnet_regiis to encrypt the configuration file. Encrypting the configuration does protect against certain things, like being able to read configuration data. However, there are a couple problems with this.

  • If I’m an administrator on that server I can easily decrypt the file by calling aspnet_regiis
  • If I’ve found a way to exploit the site, I can potentially overwrite the contents of the file and make the application behave differently
  • The encryption/decryption keys need to be shared in web farms

Consider our goal. We want to prevent a user with administrative privileges from modifying the configuration. Encryption does not help us in this case.  Signing the configuration will help though (As an aside, for more protection you encrypt the file then sign it, but that’s out of the scope of this) because the web application will stop working if a change is made that invalidates the signature.

Of course, there’s one little problem. You can’t stick the signature in the configuration file, because ASP.NET will b-itch complain about the foreign XML tag. The original application in question was assumed to have a custom XML file for it’s configuration, but in reality it doesn’t, so this problem applies there too.

There are three possible solutions to this:

  • Create a custom ConfigurationSection class for the signature
  • Create a custom configuration file and handler, and intercept all calls to web.config
  • Stick the signature of the configuration file into a different file

The first option isn’t a bad idea, but I really didn’t want to muck about with the configuration classes. The second option is, well, pretty much a stupid idea in almost all cases, and I’m not entirely sure you can even intercept all calls to the configuration classes.

I went with option three.

The other file has two important parts: the signature of the web.config file, and a signature for itself. This second signature prevents someone from modifying the signature for the web.config file. Our code becomes a bit more complicated because now we need to validate both signatures.

This makes us ask the question, where is the validation handled? It needs to happen early enough in the request lifecycle, so I decided to stick it into a HTTP Module, for the sake of modularity.

Hold it, you say. If the code is in a HTTP Module, then it needs to be added to the web.config. If you are adding it to the web.config, and protecting the web.config by this module, then removing said module from the web.config will prevent the validation from occurring.

Yep.

There are two ways around this:

  • Add the validation call into Global.asax
  • Hard code the addition of the HTTP Module

It’s very rare that I take the easy approach, so I’ve decided to hard code the addition of the HTTP Module, because sticking the code into a module is cleaner.

In older versions of ASP.NET you had to make some pretty ugly hacks to get the module in because it needs to happen very early in startup of the web application. With ASP.NET 4.0, an assembly attribute was added that allowed you to call code almost immediately after startup:

[assembly: PreApplicationStartMethod(typeof(Syfuhs.Security.Web.Startup), "Go")]

 

Within the Startup class there is a public static method called Go(). This method calls the Register() within an instance of my HttpModule. This module inherits from an abstract class called DynamicallyLoadedHttpModule, which inherits from IHttpModule. This class looks like:

public abstract class DynamicallyLoadedHttpModule : IHttpModule
{
    public void Register()
    {
        DynamicHttpApplication.RegisterModule(delegate(HttpApplication app) { return this; });
    }

    public abstract void Init(HttpApplication context);

    public abstract void Dispose();
}

 

The DynamicHttpApplication class inherits from HttpApplication and allows you to load HTTP modules in code. This code was not written by me. It was originally written by Nikhil Kothari:

using HttpModuleFactory = System.Func<System.Web.HttpApplication, System.Web.IHttpModule>;

public abstract class DynamicHttpApplication : HttpApplication
{
    private static readonly Collection<HttpModuleFactory> Factories 
= new Collection<HttpModuleFactory>(); private static object _sync = new object(); private static bool IsInitialized = false; private List<IHttpModule> modules; public override void Init() { base.Init(); if (Factories.Count == 0) return; List<IHttpModule> dynamicModules = new List<IHttpModule>(); lock (_sync) { if (Factories.Count == 0) return; foreach (HttpModuleFactory factory in Factories) { IHttpModule m = factory(this); if (m != null) { m.Init(this); dynamicModules.Add(m); } } } if (dynamicModules.Count != 0) modules = dynamicModules; IsInitialized = true; } public static void RegisterModule(HttpModuleFactory factory) { if (IsInitialized) throw new InvalidOperationException(Exceptions.CannotRegisterModuleLate); if (factory == null) throw new ArgumentNullException("factory"); Factories.Add(factory); } public override void Dispose() { if (modules != null) modules.ForEach(m => m.Dispose()); modules = null; base.Dispose(); GC.SuppressFinalize(this); }

 

Finally, to get this all wired up we modify the Global.asax to inherit from DynamicHttpApplication:

public class Global : DynamicHttpApplication

{ … }

Like I said, you could just add the validation code into Global (but where’s the fun in that?)…

So, now that we’ve made it possible to add the HTTP Module, lets actually look at the module:

public sealed class SignedConfigurationHttpModule : DynamicallyLoadedHttpModule
{
    public override void Init(HttpApplication context)
    {
        if (context == null)
            throw new ArgumentNullException("context");

        context.BeginRequest += new EventHandler(context_BeginRequest);
        context.Error += new EventHandler(context_Error);
    }

    private void context_BeginRequest(object sender, EventArgs e)
    {
        HttpApplication app = (HttpApplication)sender;

        SignatureValidator validator 
= new SignatureValidator(app.Request.PhysicalApplicationPath); validator.ValidateConfigurationSignatures(
CertificateLocator.LocateSigningCertificate()); } private void context_Error(object sender, EventArgs e) { HttpApplication app = (HttpApplication)sender; foreach (var exception in app.Context.AllErrors) { if (exception is XmlSignatureValidationFailedException) { // Maybe do something // Or don't... break; } } } public override void Dispose() { } }

 

Nothing special here. Just hooking into the context.BeginRequest event so validation occurs on each request. There would be some performance impact as a result.

The core validation is contained within the SignatureValidator class, and there is a public method that we call to validate the signature file, ValidateConfigurationSignatures(…). This method accepts an X509Certificate2 to compare the signature against.

The specification for the schema we are using for the signature will actually encode the public key of the private key into the signature element, however we want to go one step further and make sure it’s signed by a particular certificate. This will prevent someone from modifying the configuration file, and re-signing it with a different private key. Validation of the signature is not enough; we need to make sure it’s signed by someone we trust.

The validator first validates the schema of the signature file. Is the XML well formed? Does the signature file conform to a schema we defined (the schema is defined in a Constants class)? Following that is validates the signature of the file itself. Has the file been tampered with? Following that it validates the signature of the web.config file. Has the web.config file been tampered with?

Before it can do all of this though, it needs to check to see if the signature file exists. The variable passed into the constructor is the physical path of the web application. The validator knows that the signature file should be in the App_Data folder within the root. This file needs to be here because the folder by default will not let you access anything in it, and we don’t want anyone downloading the file. The path is also hardcoded specifically so changes to the configuration cannot bypass the signature file validation.

Here is the validator:

internal sealed class SignatureValidator
{
    public SignatureValidator(string physicalApplicationPath)
    {
        this.physicalApplicationPath = physicalApplicationPath;
        this.signatureFilePath = Path.Combine(this.physicalApplicationPath, 
"App_Data\\Signature.xml"); } private string physicalApplicationPath; private string signatureFilePath; public void ValidateConfigurationSignatures(X509Certificate2 cert) { Permissions.DemandFilePermission(FileIOPermissionAccess.Read, this.signatureFilePath); if (cert == null) throw new ArgumentNullException("cert"); if (cert.HasPrivateKey) throw new SecurityException(Exceptions.ValidationCertificateHasPrivateKey); if (!File.Exists(signatureFilePath)) throw new SecurityException(Exceptions.CouldNotLoadSignatureFile); XmlDocument doc = new XmlDocument() { PreserveWhitespace = true }; doc.Load(signatureFilePath); ValidateXmlSchema(doc); CheckForUnsignedConfig(doc); if (!X509CertificateCompare.Compare(cert, ValidateSignature(doc))) throw new XmlSignatureValidationFailedException(
Exceptions.SignatureFileNotSignedByExpectedCertificate); List<XmlSignature> signatures = ParseSignatures(doc); ValidateSignatures(signatures, cert); } private void CheckForUnsignedConfig(XmlDocument doc) { List<string> signedFiles = new List<string>(); foreach (XmlElement file in doc.GetElementsByTagName("File")) { string fileName = Path.Combine(this.physicalApplicationPath,
file["FileName"].InnerText); signedFiles.Add(fileName.ToUpperInvariant()); } CheckConfigFiles(signedFiles); } private void CheckConfigFiles(List<string> signedFiles) { foreach (string file in Directory.EnumerateFiles(
this.physicalApplicationPath, "*.config", SearchOption.AllDirectories)) { string path = Path.Combine(this.physicalApplicationPath, file); if (!signedFiles.Contains(path.ToUpperInvariant())) throw new XmlSignatureValidationFailedException(
string.Format(CultureInfo.CurrentCulture, Exceptions.ConfigurationFileWithoutSignature, path)); } } private void ValidateXmlSchema(XmlDocument doc) { using (StringReader fileReader = new StringReader(Constants.SignatureFileSchema)) using (StringReader signatureReader = new StringReader(Constants.SignatureSchema)) { XmlSchema fileSchema = XmlSchema.Read(fileReader, null); XmlSchema signatureSchema = XmlSchema.Read(signatureReader, null); doc.Schemas.Add(fileSchema); doc.Schemas.Add(signatureSchema); doc.Validate(Schemas_ValidationEventHandler); } } void Schemas_ValidationEventHandler(object sender, ValidationEventArgs e) { throw new XmlSignatureValidationFailedException(Exceptions.InvalidSchema, e.Exception); } public static X509Certificate2 ValidateSignature(XmlDocument xml) { if (xml == null) throw new ArgumentNullException("xml"); XmlElement signature = ExtractSignature(xml.DocumentElement); return ValidateSignature(xml, signature); } public static X509Certificate2 ValidateSignature(XmlDocument doc, XmlElement signature) { if (doc == null) throw new ArgumentNullException("doc"); if (signature == null) throw new ArgumentNullException("signature"); X509Certificate2 signingCert = null; SignedXml signed = new SignedXml(doc); signed.LoadXml(signature); foreach (KeyInfoClause clause in signed.KeyInfo) { KeyInfoX509Data key = clause as KeyInfoX509Data; if (key == null || key.Certificates.Count != 1) continue; signingCert = (X509Certificate2)key.Certificates[0]; } if (signingCert == null) throw new CryptographicException(Exceptions.SigningKeyNotFound); if (!signed.CheckSignature()) throw new CryptographicException(Exceptions.SignatureValidationFailed); return signingCert; } private static void ValidateSignatures(List<XmlSignature> signatures, X509Certificate2 cert) { foreach (XmlSignature signature in signatures) { X509Certificate2 signingCert
= ValidateSignature(signature.Document, signature.Signature); if (!X509CertificateCompare.Compare(cert, signingCert)) throw new XmlSignatureValidationFailedException( string.Format(CultureInfo.CurrentCulture,
Exceptions.SignatureForFileNotSignedByExpectedCertificate, signature.FileName)); } } private List<XmlSignature> ParseSignatures(XmlDocument doc) { List<XmlSignature> signatures = new List<XmlSignature>(); foreach (XmlElement file in doc.GetElementsByTagName("File")) { string fileName
= Path.Combine(this.physicalApplicationPath, file["FileName"].InnerText); Permissions.DemandFilePermission(FileIOPermissionAccess.Read, fileName); if (!File.Exists(fileName)) throw new FileNotFoundException(
string.Format(CultureInfo.CurrentCulture, Exceptions.FileNotFound, fileName)); XmlDocument fileDoc = new XmlDocument() { PreserveWhitespace = true }; fileDoc.Load(fileName); XmlElement sig = file["FileSignature"] as XmlElement; signatures.Add(new XmlSignature() { FileName = fileName, Document = fileDoc, Signature = ExtractSignature(sig) }); } return signatures; } private static XmlElement ExtractSignature(XmlElement xml) { XmlNodeList xmlSignatureNode = xml.GetElementsByTagName("Signature"); if (xmlSignatureNode.Count <= 0) throw new CryptographicException(Exceptions.SignatureNotFound); return xmlSignatureNode[xmlSignatureNode.Count - 1] as XmlElement; } }

 

You’ll notice there is a bit of functionality I didn’t mention. Checking that the web.config file hasn’t been modified isn’t enough. We also need to check if any *other* configuration file has been modified. It’s no good if you leave the root configuration file alone, but modify the <authorization> tag within the administration folder to allow anonymous access, right?

So there is code looks through the site for any files that have the “config” extension, and if that file isn’t in the signature file, it throws an exception.

There is also a check done at the very beginning of the validation. If you pass an X509Certificate2 with a private key it will throw an exception. This is absolutely by design. You sign the file with the private key. You validate with the public key. If the private key is present during validation that means you are not separating the keys, and all of this has been a huge waste of time because the private key is not protected. Oops.

Finally, it’s important to know how to sign the files. I’m not a fan of generating XML properly, partially because I’m lazy and partially because it’s a pain to do, so mind the StringBuilder:

public sealed class XmlSigner
{
    public XmlSigner(string appPath)
    {
        this.physicalApplicationPath = appPath;
    }

    string physicalApplicationPath;

    public XmlDocument SignFiles(string[] paths, X509Certificate2 cert)
    {
        if (paths == null || paths.Length == 0)
            throw new ArgumentNullException("paths");

        if (cert == null || !cert.HasPrivateKey)
            throw new ArgumentNullException("cert");

        XmlDocument doc = new XmlDocument() { PreserveWhitespace = true };
        StringBuilder sb = new StringBuilder();

        sb.Append("<Configuration>");
        sb.Append("<Files>");

        foreach (string p in paths)
        {
            sb.Append("<File>");

            sb.AppendFormat("<FileName>{0}</FileName>", 
p.Replace(this.physicalApplicationPath, "")); sb.AppendFormat("<FileSignature><Signature xmlns=\"http://www.w3.org/2000/09/xmldsig#\">{0}</Signature></FileSignature>",
SignFile(p, cert).InnerXml); sb.Append("</File>"); } sb.Append("</Files>"); sb.Append("</Configuration>"); doc.LoadXml(sb.ToString()); doc.DocumentElement.AppendChild(doc.ImportNode(SignXmlDocument(doc, cert), true)); return doc; } public static XmlElement SignFile(string path, X509Certificate2 cert) { if (string.IsNullOrWhiteSpace(path)) throw new ArgumentNullException("path"); if (cert == null || !cert.HasPrivateKey) throw new ArgumentException(Exceptions.CertificateDoesNotContainPrivateKey); Permissions.DemandFilePermission(FileIOPermissionAccess.Read, path); XmlDocument doc = new XmlDocument(); doc.PreserveWhitespace = true; doc.Load(path); return SignXmlDocument(doc, cert); } public static XmlElement SignXmlDocument(XmlDocument doc, X509Certificate2 cert) { if (doc == null) throw new ArgumentNullException("doc"); if (cert == null || !cert.HasPrivateKey) throw new ArgumentException(Exceptions.CertificateDoesNotContainPrivateKey); SignedXml signed = new SignedXml(doc) { SigningKey = cert.PrivateKey }; Reference reference = new Reference() { Uri = "" }; XmlDsigC14NTransform transform = new XmlDsigC14NTransform(); reference.AddTransform(transform); XmlDsigEnvelopedSignatureTransform envelope = new XmlDsigEnvelopedSignatureTransform(); reference.AddTransform(envelope); signed.AddReference(reference); KeyInfo keyInfo = new KeyInfo(); keyInfo.AddClause(new KeyInfoX509Data(cert)); signed.KeyInfo = keyInfo; signed.ComputeSignature(); XmlElement xmlSignature = signed.GetXml(); return xmlSignature; } }

 

To write this to a file you can call it like this:

XmlWriter writer = XmlWriter.Create(
@"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\App_Data\Signature.xml"); XmlSigner signer = new XmlSigner(Request.PhysicalApplicationPath); XmlDocument xml = signer.SignFiles(new string[] { @"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\Web.config", @"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\Web.debug.config", @"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\Web.release.config", @"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\Account\Web.config", @"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\test.config" }, new X509Certificate2(
@"C:\Dev\Projects\Syfuhs.Security.Web\Syfuhs.Security.Web.WebTest\cert.pfx", "1")); xml.WriteTo(writer); writer.Flush();

 

Now within this code, you have to pass in a X509Certificate2 with a private key, otherwise you can’t sign the files.

These processes should occur on different machines. The private key should never be on the server hosting the site. The basic steps for deployment would go something like:

1. Compile web application.
2. Configure site and configuration files on staging server.
3. Run application that signs the configuration and generates the signature file.
4. Drop the signature.xml file into the App_Data folder.
5. Deploy configured and signed application to production.

There is one final note (I think I’ve made that note a few times by now…) and that is the CertificateLocator class. At the moment it just returns a X509Certificate2 from a particular path on my file system. This isn’t necessarily the best approach because it may be possible to overwrite that file. You should store that certificate in a safe place, and make a secure call to get it. For instance a web service call might make sense. If you have a Hardware Security Module (HSM) to store secret bits in, even better.

Concluding Bits

What have we accomplished by signing our configuration files? We add a degree of trust that our application hasn’t been compromised. In the event that the configuration has been modified, the application stops working. This could be from malicious intent, or careless administrators. This is a great way to prevent one-off changes to configuration files in web farms. It is also a great way to prevent customers from mucking up the configuration file you’ve deployed with your application.

This solution was designed in a way mitigate quite a few attacks. An attacker cannot modify configuration files. An attacker cannot modify the signature file. An attacker cannot view the signature file. An attacker cannot remove the signature file. An attacker cannot remove the HTTP Module that validates the signature without changing the underlying code. An attacker cannot change the underlying code because it’s been compiled before being deployed.

Is it necessary to use on every deployment? No, probably not.

Does it go a little overboard with regard to complexity? Yeah, a little.

Does it protect against a real problem? Absolutely.

Unfortunately it also requires full trust.

Overall it’s a fairly robust solution and shows how you can mitigate certain types of risks seen in the real world.

And of course, it works with both WebForms and MVC.

You can download the full source here.

Plugging Application Authentication Leaks in ADFS

When you set up ADFS as an IdP for SAML relying parties, you are given a page that allows you to log into the relying parties.  There is nothing particularly interesting about this fact, except that it could be argued that the page allows for information leakage.  Take a look at it:

image

There are two important things to note:

  • I'm not signed in
  • I can see every application that uses this IdP

I'm on the fence about this one.  To some degree I don't care that people know we use ADFS to log into Salesforce.  Frankly, I blogged about it.  However, this could potentially be bad because it can tell an attacker about the applications you use, and the mechanisms you use to authenticate into them.

This is definitely something you should consider when developing your threat models.

Luckily, if you do decide that you don't want the applications to be visible, you can make a quick modification to the IdpInitiatedSignOn.aspx.cs page.

There is a method called SetRpListState:

protected void SetRpListState( object sender, EventArgs e )
{
    RelyingPartyDropDownList.Enabled = OtherRpRadioButton.Checked;
    ConsentDropDownList.Enabled = OtherRpRadioButton.Checked;
}

To get things working I made two quick modifications.  First I added the following line of code to that method:

OtherRpPanel.Visible = this.IsAuthenticated;

Then I added a line to the Page_Init method:

SetRpListState(null, null);

Now unauthenticated users just see this:

image

And authenticated users see everything as expected:

image

You could extend this further and add some logic to look into the App Settings in the web.config to quickly and easily switch between modes.

The Basics of Building a Security Token Service

Last week at TechDays in Toronto I ran into a fellow I worked with while I was at Woodbine.  He works with a consulting firm Woodbine uses, and he caught my session on Windows Identity Foundation.  His thoughts were (essentially—paraphrased) that the principle of Claims Authentication was sound and a good idea, however implementing it requires a major investment.  Yes.  Absolutely.  You will essentially be adding a new tier to the application.  Hmm.  I’m not sure if I can get away with that analogy.  It will certainly feel like you are adding a new tier anyway.

What strikes me as the main investment is the Security Token Service.  When you break it down, there are a lot of moving parts in an STS.  In a previous post I asked what it would take to create something similar to ADFS 2.  I said it would be fairly straightforward, and broke down the parts as well as what would be required of them.  I listed:

  • Token Services
  • A Windows Authentication end-point
  • An Attribute store-property-to-claim mapper (maps any LDAP properties to any claim types)
  • An application management tool (MMC snap-in and PowerShell cmdlets)
  • Proxy Services (Allows requests to pass NAT’ed zones)

These aren’t all that hard to develop.  With the exception of the proxy services and token service itself, there’s a good chance we have created something similar to each one if user authentication is part of an application.  We have the authentication endpoint: a login form to do SQL Authentication, or the Windows Authentication Provider for ASP.NET.  We have the attribute store and something like a claims mapper: Active Directory, SQL databases, etc.  We even have an application management tool: anything you used to manage users in the first place.  This certainly doesn’t get us all the way there, but they are good starting points.

Going back to my first point, the STS is probably the biggest investment.  However, it’s kind of trivial to create an STS using WIF.  I say that with a big warning though: an STS is a security system.  Securing such a system is NOT trivial.  Writing your own STS probably isn’t the best way to approach this.  You would probably be better off to use an STS like ADFS.  With that being said it’s good to know what goes into building an STS, and if you really do have the proper resources to develop one, as well as do proper security testing (you probably wouldn’t be reading this article on how to do it in that case…), go for it.

For the sake of simplicity I’ll be going through the Fabrikam Shipping demo code since they did a great job of creating a simple STS.  The fun bits are in the Fabrikam.IPSts project under the Identity folder.  The files we want to look at are CustomSecurityTokenService.cs, CustomSecurityTokenServiceConfiguration.cs, and the default.aspx code file.  I’m not sure I like the term “configuration”, as the way this is built strikes me as factory-ish.

image

The process is pretty simple.  A request is made to default.aspx which passes the request to FederatedPassiveSecurityTokenServiceOperations.ProcessRequest() as well as a newly instantiated CustomSecurityTokenService object by calling CustomSecurityTokenServiceConfiguration.Current.CreateSecurityTokenService().

The configuration class contains configuration data for the STS (hence the name) like the signing certificate, but it also instantiates an instance of the STS using the configuration.  The code for is simple:

namespace Microsoft.Samples.DPE.Fabrikam.IPSts
{
    using Microsoft.IdentityModel.Configuration;
    using Microsoft.IdentityModel.SecurityTokenService;

    internal class CustomSecurityTokenServiceConfiguration
: SecurityTokenServiceConfiguration
    {
        private static CustomSecurityTokenServiceConfiguration current;

        private CustomSecurityTokenServiceConfiguration()
        {
            this.SecurityTokenService = typeof(CustomSecurityTokenService);
            this.SigningCredentials =
new X509SigningCredentials(this.ServiceCertificate);
            this.TokenIssuerName = "https://ipsts.fabrikam.com/";
        }

        public static CustomSecurityTokenServiceConfiguration Current
        {
            get
            {
                if (current == null)
                {
                    current = new CustomSecurityTokenServiceConfiguration();
                }

                return current;
            }
        }
    }
}

It has a base type of SecurityTokenServiceConfiguration and all it does is set the custom type for the new STS, the certificate used for signing, and the issuer name.  It then lets the base class handle the rest.  Then there is the STS itself.  It’s dead simple.  The custom class has a base type of SecurityTokenService and overrides a couple methods.  The important method it overrides is GetOutputClaimsIdentity():

protected override IClaimsIdentity GetOutputClaimsIdentity(
IClaimsPrincipal principal, RequestSecurityToken request, Scope scope)
{
    var inputIdentity = (IClaimsIdentity)principal.Identity;

    Claim name = inputIdentity.Claims.Single(claim =>
claim.ClaimType == ClaimTypes.Name);
    Claim email = new Claim(ClaimTypes.Email,
Membership.Provider.GetUser(name.Value, false).Email);
    string[] roles = Roles.Provider.GetRolesForUser(name.Value);

    var issuedIdentity = new ClaimsIdentity();
    issuedIdentity.Claims.Add(name);
    issuedIdentity.Claims.Add(email);

    foreach (var role in roles)
    {
        var roleClaim = new Claim(ClaimTypes.Role, role);
        issuedIdentity.Claims.Add(roleClaim);
    }

    return issuedIdentity;
}

It gets the authenticated user, grabs all the roles from the RolesProvider, and generates a bunch of claims then returns the identity.  Pretty simple.

At this point you’ve just moved the authentication and Roles stuff away from the application.  Nothing has really changed data-wise.  If you only cared about roles, name, and email you are done.  If you needed something more you could easily add in the logic to grab the values you needed. 

By no means is this production ready, but it is a good basis for how the STS creates claims.

Token Request Validation in ASP.NET

Earlier this week during my TechDays presentation on Windows Identity Foundation, there was a part during the demo that I said would fail miserably after the user was authenticated and the token was POST’ed back to the relying party.  Out of the box, ASP.NET does request validation.  If a user has submitted content through request parameters it goes through a validation step, and by default this step is to break on anything funky such as angle brackets.  This helps to deter things like cross site scripting attacks.  However, we were passing XML so we needed to turn off this validation.  There are two approaches to doing this.

The first approach, which is what I did in the demo, was to set the validation mode to “2.0”.  All this did was tell ASP.NET to use a less strict validation scheme.  To do that you need to add a line to the web.config file:

<system.web>
<httpRuntime requestValidationMode=”2.0” />
</system.web>

This is not the best way to do things though.  It creates a new vector for attack, as you’ve just allowed an endpoint to accept trivial data.  What is more preferred is to create a custom request validator.  You can find a great example in the Fabrikam Shipping demo.

It’s pretty straightforward to create a validator.  First you create a class that inherits System.Web.Util.RequestValidator, and then you override the method IsValidRequestString(…).  At that point you can do anything you want to validate, but the demo code tries to build a SignInResponseMessage object from the wresult parameter.  If it creates the object successfully the request is valid.  Otherwise it passes the request to the base implementation of IsValidRequestString(…).

The code to handle this validation is pretty straightforward:

    public class WSFederationRequestValidator : RequestValidator
    {
        protected override bool IsValidRequestString(HttpContext context,
            string value, RequestValidationSource requestValidationSource, 
            string collectionKey, out int validationFailureIndex)
        {
            validationFailureIndex = 0;

            if (requestValidationSource == RequestValidationSource.Form
                && collectionKey.Equals(WSFederationConstants.Parameters.Result, 
                   StringComparison.Ordinal))
            {
                SignInResponseMessage message =
                     WSFederationMessage.CreateFromFormPost(context.Request) 
                     as SignInResponseMessage;

                if (message != null)
                {
                    return true;
                }
            }

            return base.IsValidRequestString(context, value, requestValidationSource,
                   collectionKey, out validationFailureIndex);
        }
    }

Once you’ve created your request validator, you need to update the web.config file to tell .NET to use the validator.  You can do that by adding the following xml:

<system.web>
<httpRuntime requestValidationType="Microsoft.Samples.DPE.FabrikamShipping.Web.Security.WSFederationRequestValidator" />
</system.web>

You can find the validation code in FabrikamShipping.Web\Security\WSFederationRequestValidator.cs within the FabrikamShipping solution.

Managing Identity in SharePoint

Yet another presentation on the docket!  I submitted an abstract to SharePoint Summit 2011 and they accepted!  I will be presenting on SharePoint and how it manages Identity.  More specifically, how SharePoint 2010 uses WIF to handle Claims based authentication and Federation.

Here are the details

Event: SharePoint Summit 2011, January 31st 2011 – February 2nd, 2011

When: 11:30 a.m. - 12:45 p.m. February 1st, 2011

Where: Four Seasons Hotel, Toronto

Abstract: Managing identities within an organization is relatively easy. However, as business changes, we need to be able to adapt quickly. Identity is something that often gets overlooked in adaptation. In this session we will discuss the Windows Identity Foundation and how SharePoint uses it to adapt easily to change.

Link: http://www.sharepointsummit2011.com/Toronto/conference_day2.htm#session_7_3

Presenting a TechDays Local Flavours Track Session!

Earlier this morning I got an email from John Bristowe congratulating me on being selected to present a session for the local flavours track at TechDays in Toronto!  This bumps up my count to 2.  Needless to say I am REALLY excited.

I was a little disappointed to find out there weren’t any sessions on the Windows Identity Foundation, so that just meant I had to submit my own to the local flavours track…and they accepted it!  Here are the details:

October 27, 3:40 PM to 4:45 PM

Breakout | LFT330: Windows Identity Foundation Simplified: All the Scary Things Made Un-Scary

The Windows Identity Foundation helps simplify user access for developers by externalizing user access from applications via claims and reducing development effort with pre-built security logic and integrated .NET tools. This presentation is an intimate discussion on the basics of the Windows Identity Foundation and its claims model. In this session, you’ll learn how to refactor an existing sample set of applications to use WIF, to connect identities to the Cloud, and to remove the burden of managing multiple disparate user stores.

Location: Metro Toronto Convention Centre - South Building (255 Front Street West, Toronto)

Room: TBA

image

Using Claims Based Identities with SharePoint 2010

When SharePoint 2010 was developed, Microsoft took extra care to include support for a claims-based identity model.  There are quite a few benefits to doing it this way, one of which is that it simplifies managing identities across organizational structures.  So lets take a look at adding a Secure Token Service as an Authentication Provider to SharePoint 2010.

First, Some Prerequisites

  • You have to use PowerShell for most of this.  You wouldn’t/shouldn’t be adding too many Providers to SharePoint all that often so there isn’t a GUI for this.
  • The claims that SharePoint will know about must be known during setup.  This isn’t that big a deal, but…

Telling SharePoint about the STS

Once you’ve collected all the information you need, open up PowerShell as an Administrator and add the SharePoint snap-in on the server.

Add-PSSnapin Microsoft.SharePoint.PowerShell

Next we need to create the certificate and claim mapping objects:

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("d:\path\to\adfsCert.cer")

$claim1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" –SameAsIncoming

$claim2 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" –SameAsIncoming

There should be three lines.  They will be word-wrapped.

The certificate is pretty straightforward.  It is the public key of the STS.  The claims are also pretty straightforward.  There are two claims: the roles of the identity, and the email address of the identity.  You can add as many as the STS will support.

Next is to define the realm of the Relying Party; i.e. the SharePoint server.

$realm = "urn:" + $env:ComputerName + ":adfs"

By using a URN value you can mitigate future changes to addresses.  This becomes especially useful in an intranet/extranet scenario.

Then we define the sign-in URL for the STS.  In this case, we are using ADFS:

$signinurl = https://[myAdfsServer.fullyqualified.domainname]/adfs/ls/

Mind the SSL.

And finally we put it all together:

New-SPTrustedIdentityTokenIssuer -Name "MyDomainADFS2" -Description "ADFS 2 Federated Server for MyDomain" -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $claim1,$claim2 -SignInUrl $signinurl -IdentifierClaim $claim2.InputClaimType

This should be a single line, word wrapped.  If you wanted to you could just call New-SPTrustedIdentityTokenIssuer and then fill in the values one at a time.  This might be useful for debugging.

At this point SharePoint now knows about the STS but none of the sites are set up to use it.

Authenticating SharePoint sites using the STS

For a good measure restart SharePoint/IIS.  Go into SharePoint Administration and create a new website and select Claims Based Authentication at the top:

image

Fill out the rest of the details and then when you get to Claims Authentication Types select Trusted Identity Provider and then select your STS.  In this case it is my ADFS Server:

image

Save the site and you are done.  Try navigating to the site and it should redirect you to your STS.  You can then manage users as you would normally with Active Directory accounts.

Modifying and Securing the ADFS 2 Web Application

When you install an instance of Active Directory Federation Services v2, amongst other things it will create a website within IIS to use as it’s Secure Token Service.  This is sort of fundamental to the whole design.  There are some interesting things to note about the situation though.

When Microsoft (or any ISV really) releases a new application or server that has a website attached to it, they usually deliver it in a precompiled form, so all we do is point IIS to the binaries and config files and we go from there.  This serves a number of purposes usually along the lines of performance, Intellectual Property protection, defense in depth protection, etc.  Interestingly though, when the installer creates the application for us in IIS, it drops source code instead of a bunch of assemblies.

There is a valid reason for this.

It gives us the opportunity to do a couple things.  First, we can inspect the code.  Second, we can easily modify the code.  Annoyingly, they don’t give us a Visual Studio project to do so.  Let’s create one then.

First off, lets take a look at what was created by the installer.  By default it drops the files in c:\inetpub\adfs\ls.  We are given a few files and folders:

image

There isn’t much to it.  These files only contain a few lines of code.  Next we create the actual project.

DISCLAIMER:  I will not be held responsible if things break or the server steals your soul.  Please do NOT (I REPEAT) do NOT do this with production servers please!  (Notice I said please twice?)

Since we want to create a Visual Studio project, and since ADFS cannot be installed on a workstation, we have two options:

  1. Install Visual Studio on the server running ADFS
  2. Copy the files to your local machine

Each options have their tradeoffs.  The first requires a bit of a major overhaul of your development environment.  It’s very similar to SharePoint 2007 development.  The second option makes developing a lot easier, but testing is a pain because the thing won’t actually work properly without the Windows Services running.  You would need to deploy the code to a test server with ADFS installed.

Since I have little interest in rebuilding my development box, I went with the second option.

Okay, back to Visual Studio.  The assemblies referenced were all built on Framework 3.5, so for the sake of simplicity lets create a 3.5 Web Application:

image

I haven’t tested 4.0 yet.

Since this is a Web Application and not a Web Site within Visual Studio, we need to generate the *.designer.cs files for all the *.aspx pages.  Right-click your project and select Convert to Web Application:

image

At this point if you tried to compile the application it wouldn’t work.  We are missing a few assembly references.  First, add Microsoft.IdentityModel.  This should be in the GAC or the Reference Assemblies folder in Program Files.  Next, go back to the ADFS server and navigate to C:\Program Files\Active Directory Federation Services 2.0 and copy the following files:

  • Microsoft.IdentityServer.dll
  • Microsoft.IdentityServer.Compression.dll

Add these assemblies as references.  The web application should compile successfully.

Next we need to sign the web application’s assemblies.  If you have internal policies on assembly signing, follow those.  Otherwise double-click the properties section in Solution Explorer and navigate to Signing:

image

Choose a key file or create a new one.  Rebuild the web application.

So far we haven’t touched a line of code.  This is all general deployment stuff.  You can deploy the web application back to the ADFS server and it should work as if nothing had changed.  You have a few options for this.  The Publishing Features in Visual Studio 2010 are awesome.  Right click the project and Publish it:

image

Since I set up a test box for ADFS development, I’m just going to overwrite the files on the server:

image

Pro Tip: If you do something terrible and need to revert back to original code (what part of don’t do this on a production box didn’t make sense? Winking smile) you can access the original files from C:\Program Files\Active Directory Federation Services 2.0\WSFederationPassive.Web.

At this point we haven’t done much, but we now have a stepping point to modify the default behavior of ADFS.  This could range from simple theme changes to better suit corporate policy, or to completely redefine the authentication workflow.

This also gives us the ability to better protect our code in the event that IIS craps out and shows contents of files, not to mention the (albeit minor) performance boost we get because the website doesn’t need to be recompiled.

Have fun!

Installing ADFS 2 and Federating an Application

From Microsoft Marketing, ADFS 2.0 is:

Active Directory Federation Services 2.0 helps IT enable users to collaborate across organizational boundaries and easily access applications on-premises and in the cloud, while maintaining application security. Through a claims-based infrastructure, IT can enable a single sign-on experience for end-users to applications without requiring a separate account or password, whether applications are located in partner organizations or hosted in the cloud.

So, it’s a Token Service plus some.  In a previous post I had said:

In other words it is a method for centralizing user Identity information, very much like how the Windows Live and OpenID systems work.  The system is reasonably simple.  I have a Membership data store that contains user information.  I want (n) number of websites to use that membership store, EXCEPT I don’t want each application to have direct access to membership data such as passwords.  The way around it is through claims.

The membership store in this case being Active Directory.

I thought it would be a good idea to run through how to install ADFS and set up an application to use it.  Since we already discussed how to federate an application using FedUtil.exe, I will let you go through the steps in the previous post.  I will provide information on where to find the Metadata later on in this post.

But First: The Prerequisites

  1. Join the Server to the Domain. (I’ve started the installation of ADFS three times on non-domain joined systems.  Doh!)
  2. Install the latest .NET Framework.  I’m kinda partial to using SmallestDotNet.com created by Scott Hanselman.  It’s easy.
  3. Install IIS.  If you are running Server 2008 R2 you can follow these steps in another post, or just go through the wizards.  FYI: The post installs EVERY feature.  Just remember that when you move to production.  Surface Area and what not…
  4. Install PowerShell.
  5. Install the Windows Identity Foundation: http://www.microsoft.com/downloads/details.aspx?FamilyID=eb9c345f-e830-40b8-a5fe-ae7a864c4d76&displaylang=en
  6. Install SQL Server.  This is NOT required.  You only need to install it if you want to use a SQL Database to get custom Claims data.  You could also use a SQL Server on another server…
  7. Download ADFS 2.0 RTW: http://www.microsoft.com/downloads/details.aspx?familyid=118c3588-9070-426a-b655-6cec0a92c10b&displaylang=en

The Installation

image

Read the terms and accept them.  If you notice, you only have to read half of what you see because the rest is in French.  Maybe the lawyers are listening…these things are getting more readable.

image

Select Federation Server.  A Server Proxy allows you to use ADFS on a web server not joined to the domain.

image

We already installed all of these things.  When you click next it will check for latest hotfixes and ask if you want to open the configuration MMC snap-in.  Start it.

image

We want to start the configuration Wizard and then create a new Federation Service:

image

Next we want to create a Stand-alone federation server:

image

We need to select a certificate for ADFS to use.  By default it uses the SSL certificate of the default site in IIS.  So lets add one.  In the IIS Manager select the server and then select Server Certificates:

image

We have a couple options when it comes to adding a certificate.  For the sake of this post I’ll just create a self-signed certificate, but if you have a domain Certificate Authority you could go that route, or if this is a public facing service create a request and get a certificate from a 3rd party CA.

image

Once we’ve created the certificate we assign it to the web site.  Go to the website and select Bindings…

image

Add a site binding for https:

image

Now that we’ve done that we can go back to the Configuration Wizard:

image

Click next and it will install the service.  It will stop IIS so be aware of that.

image

You may receive this error if you are installing on Server 2008:

image

The fix for this is here: http://www.syfuhs.net/2010/07/23/ADFS20WindowsServiceNotStartingOnServer2008.aspx

You will need to re-run the configuration wizard if you do this.  It may complain about the virtual applications already existing.  You two options: 1) delete the applications in IIS as well as the folder C:\inetpub\adfs; 2) Ignore the warning.

Back to the installation, it will create two new Virtual Applications in IIS:

image

Once the wizard finishes you can go back to the MMC snap-in and fiddle around.  The first thing we need to do is create an entry for a Relying Party.  This will allow us to create a web application to work with it.

image

When creating an RP we have a couple options to provide configuration data.

image

Since we are going to create a web application from scratch we will enter in manual data.  If you already have the application built and have Federation Metadata available for it, by all means just use that.

We need a name:

image

Very original, eh?

Next we need to decide on what profile we will be using.  Since we are building an application from scratch we can take advantage of the 2.0 profile, but if we needed backwards compatibility for a legacy application we should select the 1.0/1.1 profile.

image

Next we specify the certificate to encrypt our claims sent to the application.  We only need the public key of the certificate.  When we run FedUtil.exe we can specify which certificate we want to use to decrypt the incoming tokens.  This will be the private key of the same certificate.  For the sake of this, we’ll skip it.

image

The next step gets a little confusing.  It asks which protocols we want to use if we are federating with a separate STS.  In this case since we aren’t doing anything that crazy we can ignore them and continue:

image

We next need to specify the RP’s identifying URI.

image

Allow anyone and everyone, or deny everyone and add specific users later?  Allow everyone…

image

When we finish we want to edit the claim rules:

image

This dialog will allow us to add mappings between claims and the data within Active Directory:

image

So lets add a rule.  We want to Send LDAP Attributes as Claims

image

First we specify what data in Active Directory we want to provide:

image

Then we specify which claim type to use:

image

And ADFS is configured!  Lets create our Relying Party.  You can follow these steps: Making an ASP.NET Website Claims Aware with the Windows Identity Foundation.  To get the Federation Metadata for ADFS navigate to the URL that the default website is mapped to + /FederationMetadata/2007-06/FederationMetadata.xml.  In my case it’s https://web1.nexus.internal.test/FederationMetadata/2007-06/FederationMetadata.xml.

Once you finish the utility it’s important that we tell ADFS that our new RP has Metadata available.  Double click on the RP to get to the properties.  Select Monitoring:

image

Add the URL for the Metadata and select Monitor relying party.  This will periodically call up the URL and download the metadata in the event that it changes.

At this point we can test.  Hit F5 and we will redirect to the ADFS page.  It will ask for domain credentials and redirect back to our page.  Since I tested it with a domain admin account I got this back:

image

It works!

For more information on ADFS 2.0 check out http://www.microsoft.com/windowsserver2008/en/us/ad-fs-2-overview.aspx or the WIF Blog at http://blogs.msdn.com/b/card/

Happy coding!

Making an ASP.NET MVC Application Claims Aware with Windows Identity Foundation

A couple posts back I had discussed how you would make an ASP.NET webforms application claims aware. It was reasonably detailed an hopefully it was clear.  I say that because to make an MVC application Claims aware, you follow the exact same procedure.

The only difference is the small little chunk of code to see what claims were returned.  Just drop this little snipped into a view and you can muck about:

<ul>
    <%
    var claimsIdentity 
        = (System.Threading.Thread.CurrentPrincipal 
	   as Microsoft.IdentityModel.Claims.IClaimsPrincipal)
	  .Identities[0];
    foreach (var claim in claimsIdentity.Claims)
    {%>
    <li>
       <%: claim.ClaimType %>
    --
    <%: claim.Value %>
    
    <% } %>
    </li>
</ul>