Claims Based Authentication with SharePoint 2007

I was recently tasked with enabling our SharePoint farm with Claims Based Authentication. It was a fun challenge as I never worked with the technology before.  There is a lot to Claims and I don’t want to go into too much depth on the benefit as there are plenty of good blogs already out there.  If you are completely new to Claims then this article should be a good starting point.

Microsoft has released both a Step-by-Step Guide to get SharePoint 2007 working with Claims as well as a MSDN article.  Personally, I found both of these lacking in detail for my situation and the goal of this post is to fills in the gaps left by these two other articles.  A lot of the Microsoft documentation focused on either Windows 2008 or in single server farm, which didn’t fit my environment.  Hopefully this posting will help others who would like to try Claims out.

Prerequisites

There are several prerequisites that are required before we get started. They are.

1. ADFS v2 running on Windows 2008 R2. I didn’t set this up but my co-worker followed the Step-By-Step Guide linked above
2. SharePoint 2007 SP2 or SharePoint Services 3.0 SP2 or later
3. Windows 2003 R2 SP2
4. .NET Framework 3.5 SP1
5. An extended Web Application that is either in the Internet or Extranet Zone
6. A SSL certificate for the extended Web Application installed on all WFE servers and in IIS.
7. winhttpcertcfg.exe – http://www.microsoft.com/downloads/details.aspx?familyid=c42e27ac-3409-40e9-8667-c748e422833f&displaylang=en
8. The STS Signing Certificate for the resource domain. You need to get this from your ADFS/Domain Admin.  Install this into the Local Machine’s Trusted People store on all Web Front End servers.
9. The URL of the STS server, typically the ADFSv2 system. Obtain exact location from your friendly ADFS/Domain Administrator

One of the most frustrated things with Claims is that the Windows Identity Foundation client that is a required component is not built for a scaled out SharePoint farm.  To fix this, Microsoft provides source code for the RSACookieTransformLibrary.  The issue is that their link in their MSDN article doesn’t work. I had to track down our TAM to get me the code.  I am not sure if I can redistribute it or not (I need to ask our TAM) so in the mean time, you can always post a comment on this blog and I’ll try to get it to you. 

After you get the code you have to change only one line, enable Assembly Signing (so it can be placed into the GAC), and Compile.  You will need the WIF Client and the WIF SDK in order to compile. My exact steps were:

1. Download and install WIF Client (for Windows 2003 x86 only) on system
2. Download and install WIF SDK on system
3. Download RsaCookieTransformLibrary Zip File
4. Extract Zip File
5. Open in Visual Studio
6. Select the Common name for the Claim’s enable WebApplication SSL certificate , created earlier
7. Open the file RSAEncryptedSessionSecurityTokenHandler.cs
8. Replace ‘YourUniqueCertificateSubjectName to with Common Name copied from Step 6
   1. Be aware. At first, I only thought this would be something like “CN=claims.example.com”. But it turns out for my certificate, the subject name was something like "CN=claims.example.com, OU=Example, O=Example, L=Chicago, S=IL, C=US"
   2. I had to write a small console application to walk through what the Subject was
9. Go to the Property Page of the Project
10. Select the Signing Tab > Check the Sign the Assembly box
11. Click New for strong name > Key Name: RsAEncryptedSessionSecurityTokenHandler > Deselect Protect my key file . . .
12. Compile the code
13. Save the dll for later use

There is one more piece of code that you must write before you can start configuring Claims. By default, ADFSv2 signs all of their messages with a SHA-256 bit key.  Windows 2003 by default doesn’t support that but you can enable it.  To do so, you have to create a console based application that calls one function. Why Microsoft didn’t include this by default is beyond me.

The console code is something like:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Security.Cryptography;

namespace RegisterSHA256_Hashing
{
    class RegisterSHA256
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Going to regiter SHA-256 on this computer . . .");
            Oid2.RegisterSha2OidInformationForRsa();
            Console.WriteLine("Done . . .");
        }
    }
}

Create a new console application, code the code, compile and xcopy it to all of your Web Front End Servers.

PHEW! Finally, we are not ready to install and configure Claims-Based authentication. Each of the steps below need to be run on each SharePoint web front end server so do one then rinse and repeat.

Install Windows Identity Foundation Client

1. Get the appropriate WIF client for your platform from http://www.microsoft.com/downloads/details.aspx?FamilyID=be4db6a0-b76d-446d-810c-ea3c25b3969a&displaylang=en#filelist
2. Run the downloaded exe
3. Next > Accept EULA > Finish

Install Federation Extensions for SharePoint 3.0

1. Download Microsoft-Federation-Extensions-For-SharePoint3.0.msi from http://www.microsoft.com/downloads/details.aspx?FamilyID=8e7b6d99-991e-44fc-a74e-9adb152ddc37
2. Run the downloaded MSI
3. Agree to EULA > Install

Register SHA256

1. Copy the RegisterSH256_Hashing command line application to the server created earlier
2. Double click on the icon

RSA Cookie Transform Library

1. Copy the RSACookieTransformLibrary.dll to the GAC
2. Note the Public Key Token

Federation Utility for SharePoint 3.0

1. Run the Federation Utility from the Start Menu
2. Select Browse > Select the web.config file for the Central Administration ( C:\inetpub\wwwroot\wss\VirtualDirectories\%SiteId\web.conifg )
3. If this server is not hosting the Central Administration Web Site, select the web.config for the extended Web Application’s default zone
4. Next
5. Application Configuration Location > Browse > Select the web.config for the extended application create way up in the Prerequisites
6. Application URL : Enter the Url of the Extended Web Application
7. SharePoint Security Zone : Internet or Extranet depending on how the Web Application was configured
8. Select Cookie Expiration
9. Enter your STS location in the form of something similar to https://sts.example.com/FederationMetadata/2007-06/FederationMetadata.xml
10. Click Test Location to confirm.
11. Select ‘Schedule a task to perform daily …’ then Next. This will contact the STS server for any updates to its configuration
12. Enable certificate chain if this is for production, otherwise leave this as the default > Next
13. Select ‘No Encryption’ if using SSL > Next > Next > Finish
14. Enter a password of the user account to run your scheduled task. This is just a standard Windows Task so it can be updated later

Last Steps

1. Allow your application pool account for the web application access to the certificate key store. You do this by using winhttpcertcfg as such – cmd.exe /c Winhttpcertcfg -g -A Example\$appPoolAccount -c LOCAL_MACHINE\My -s $subject_of_certificate
2. Add  the following  to the <Microsoft.IdentityModel><service> section of Web.config file of the extended web application

<securityTokenHandlers>
<remove type="Microsoft.IdentityModel.Tokens.SessionSecurityTokenHandler, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
<add type="RsaCookieTransform.RsaEncryptedSessionSecurityTokenHandler, RsaCookieTransformLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=&lt;tobefilledin>" />
</securityTokenHandlers>

• Replace <tobefilledin> with Public Key Token copied that you copied when you installed the dll to the GAC

After all that, you can now follow the Step-by-Step guide. The guide will walk you through how to add users from the accounts domain to your SharePoint site. Typically this is done by using an email address.  Once you get everything setup, its pretty sweet. Its just a long and winding road to get that.

 

Common Errors

One last thing before I wrap up.  There were a few errors that I encountered when installing this that I wanted to post with my solutions to assist others as they work their way through this.

1. Error ID2002. Stsadm failed – I received this when I ran the Federation Utility on my second WFE.  This is because the Provisioning timer job wasn’t deleted after the utility ran on the first WFE.  The solution was to use the Central Administration to delete the ‘Provisioning Web Application timer job’ before running the utility on the second WFE
2. Unexpected Error has occurred – [CryptographicException: The system cannot find the file specified.]. I received this error before I ran the winhttpcertcfg utility.  This is due to the AppPool service account not being able to load its profile. It needs its profile loaded so it can read the certificate store so that it can encrypt/decrypt/hash messages back and forth to ADFS
3. Failed to Execute URL System.Web.Hosting.ISAPIWorkerRequestInProcForIIS6.BeginExecuteUrl(String url, String method, String childHeaders, Boolean sendHeaders – This was a nasty error that took me a while to figure out the cause. There isn’t a lot of information on the Internet concerning this error and what little is out there, mainly concerns either IIS7 or a custom ASP.NET application. Turns out this error doesn’t have anything to do with your SharePoint setup. At least in my cause it was because ADFS was mapping claims from the account domain to unused roles in our resource domain. After we went back to the Step-By-Step guide and followed their ADFS setups it fixed our last issue.