One of the most intriguing of the many new features that SharePoint 2010 brings to the table is a completely new mechanism handle user identity.  This mechanism is based on the Windows Identity Foundation (formerly known as “Geneva”) and it opens the door to many new possibilities for securely and seamlessly integrating SharePoint with partner organizations, Internet social networking applications (think Twitter and Facebook), 3rd party identity providers (Yahoo!, Windows Live, Google), other SharePoint farms, and line-of-business applications somewhere on the corporate network.  Many of these benefits are explained in Venky Veeraraghavan’s presentation on SharePoint and identity at PDC 2009.  If you haven’t seen it, I highly recommend you check it out before reading further.

This article is intended to help fill some gaps in the existing documentation to help you get your SharePoint 2010 environment working in “Claims Mode” in conjunction with an instance of Active Directory Federation Services (ADFS) 2.0. Its not a terribly difficult process, but it can be pretty intimidating for those not versed in all the jargon associated with it.

The Design

We’re actually going to closely follow the instructions already provided in this TechNet article: Configure the Security Token Service. These instructions basically help you create a custom Federated Identity Provider to work with SharePoint. In this case, that will be an ADFS 2.0 server. Instead of connecting to SharePoint and authenticating directly to Active Directory, unauthenticated users will instead get redirected by SharePoint to a page hosted by ADFS 2.0. Users will authenticate to ADFS 2.0 using Windows Authentication, have various attributes about them packaged up as claims, and get re-directed back to SharePoint as an authenticated security principal. There’s actually a bit more going on than that, but as an introduction (and description of the end-user experience), that’ll suffice for now. Implementing this with ADFS 2.0 will provide the foundation for some pretty cool stuff down the road, which I’ll be posting in the near future.

The steps outlined in the TechNet article use mostly PowerShell.  I’ll be using a combination of PowerShell and Central Admin here.

The Setup

You can accomplish this using a single server. It’s assumed here you have SharePoint 2010 running against a local instance of SQL 2008 or SQL 2008 R2 CTP. If this server happens to be a Domain Controller, that’s fine. In my case, I’m using Windows 2008 R2 (64-bit, of course!).

Step 1: Create a Claims-Enabled Web Application

All you have to do here is run through the standard process in Central Administrator. Simply click “Create new Web Application” and select the “Claims Based Authentication” radio-button in the Authentication section.

Once the web application is created, you’ll need to create a site collection as well.  In my case, I just created one at the root “/”. When all this is done, you won’t notice anything is different at all. Indeed, I believe Microsoft is looking at making Claims Based Authentication the default mode of authentication when SharePoint 2010 RTMs. Behind the scenes, the SPUser object accessing SharePoint is actually based on a series of claims.

NOTE: The above screenshot displays claims using a custom web part. Check out my earlier blog for instructions on how to create and deploy it. This is highly recommended since it provides full visibility into the claims that make up a user identity in a claims mode web application. Needless to say, seeing and understanding these claims is fundamental to understanding how this stuff works within SharePoint.

Its worth stopping here to point out a few things. For starters, SharePoint Foundation ships with a fully functional Security Token Service (STS). When you install SharePoint 2010, the STS is operational and configured to use the local Active Directory instance to authenticate users and provide SharePoint a formal description each identity as a series of claims. When used in this way, the STS acts as an Identity Provider (IP-STS).  You can see this in the above screenshot. Some claims like group membership are provided by Active Directory. Other claims like ‘name’ and ‘userid’ are manufactured by the SharePoint STS. In IIS, you’ll find the web services associated with the STS in the SecurityTokenService application under “SharePoint Web Services”. A very good description of all this can be found in this TechNet article: http://technet.microsoft.com/en-us/library/ee428302(office.14).aspx.

So you don’t need to do anything to leverage the built-in STS as an Identity Provider. Indeed, this is the default setting. However, you can configure the SharePoint STS to trust a different IP-STS and thus act as a relying party (RP-STS). This is how you can extend SharePoint to leverage other systems to provide user identity and will be the focus for the rest of this article.

Step 2: Install and Configure ADFS 2.0

ADFS 2.0, formerly known as “Geneva Server” is now in Release Candidate stage at the time this article is being written. It can be downloaded here. There are a couple of “gotchas” you should be aware of before installing it:

1. By default, ADFS 2.0 installs into the Default Web Site. It also sets up a self-signed certificate for that site so be sure you understand the impact to anything else you may have running in Default Web Site before you move forward.
2. After the installer completes, you must run a configuration wizard to set the ADFS instance up. The GUI version of the this wizard will create a new instance of SQL 2008 Express Edition to store all configuration data. I already had a full instance of SQL 2008 R2 CTP running, so I wanted to leverage that instead of adding more software to my test virtual machine. The only way to specify an existing SQL instance is to use the command line version of the configuration wizard: http://technet.microsoft.com/en-us/library/dd727952(WS.10).aspx 

After configuration is complete, launch the ADFS 2.0 Management console and validate the certificate being used for Service Communications. This should be the same certificate that is bound to the Default Web Site. In my case, I chose to use a fully qualified domain name (pbdev.com). Make any changes necessary to ensure the Service Communications certificate and SSL binding in IIS is fully operational.

As a test, you should now be able to browse to the FederationMetadata.xml file at the following URL: https://<<SERVERNAME>>/FederationMetadata/2007-06/federationmetadata.xml

Now, export your Token-Signing Certificate to the c:\ drive. The quickest way to do this is to right-click the certificate in the ADFS 2.0 Management Console and select “View Certificate…”

Then, navigate to the Details tab and click the button labeled Copy to File…  This will launch the Certificate Export Wizard. Follow the wizard to export the certificate as a DER encoded binary X.509 (.CER) file.  For simplicity, I recommend saving the certificate to the C:\ drive. You will need this file in the following PowerShell script.

Step 3: Add ADFS 2.0 as a Federated Identity Provider in SharePoint

This is the part where we whip out some PowerShell. As far as I know, the current SharePoint 2010 Beta does not provide a place in Central Administration to do this add a federated identity provider. Fortunately, the commands are quite straightforward.

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\[YOUR_STS_SIGNING_CERT].cer")
$map1 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$realm = "urn:" + $env:ComputerName + ":adfs"
$signinurl = "https://[YOUR_SERVER_NAME]/adfs/ls/"
$ap = New-SPTrustedIdentityTokenIssuer -Name "ADFS20Server" -Description "ADFS 2.0 Federated Server" -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map1 -SignInUrl $signinurl -IdentifierClaim $map1.InputClaimType

HINT: You can copy and paste the above PowerShell commands into a text file. Save the text file with the .ps1 extension and you will be able to execute the file from within PowerShell. Be sure to launch “SharePoint 2010 Management Shell” as this will load all the SharePoint related extensions.

You should now be able add the Federated Identity Provider in Central Administration. Navigate to Web Applications Management, highlight the web application, and click the Authentication Providers button in the ribbon. You should now see your new provider in the Federated Identity Provider section of the Edit Authentication window.

SIDE NOTE: Its interesting to see in this screenshot how multiple identity providers can be added to the same zone. That’s a big change from MOSS 2007!

At this point, if you browse to your claims-enabled SharePoint site you’ll find a new screen where you need to specify what Identity Provider to use for access. This happens because we have both our Federated Identity Provider and Windows Authentication enabled for this zone. It should be noted that this screen can be customized with logic to automatically determine the correct provider based on the client IP address (for example). For now, we need to stick with Windows Authentication because ADFS 2.0 isn’t configured yet to work with SharePoint.

Step 4: Create a Second Web Application for Testing with ADFS 2.0

I’ve had issues getting claims-enabled web applications that have both a custom Federated Identity Provider and standard Windows Authentication provider enabled. When starting out, I recommend creating a new web application from scratch with only the custom identity provider selected in the Identity Providers section. These are the instructions provided in the aforementioned TechNet article. You can either delete and re-create the web application you created in Step 1 or create an entirely new web application.

In order to federate with ADFS 2.0, the web application will require an SSL certificate. Since you’ll likely be doing this for a full URL (domain.com), you should look at using SSL Diagnostics Version 1.1 to generate the certificate. A good blog that covers steps for creating a self-signed certificate can be found here. An alternate approach would be to add the Active Directory Certificate Services role to your server and request a web server certificate from within IIS. Either way works fine.

Also, assuming you’re working with a single server or virtual machine I strongly recommend disabling loopback authentication checking. Otherwise, you’re likely to experience authentication issues going forward.

When you create the site collection, you’ll have to grant an account rights to administer it. Otherwise, you will end up with Error: Access Denied….even when authenticated with an administrative account. Keep in mind, we’re no longer using Windows Integrated authentication here, so we need assign permissions to identities with certain claims.

In this example, I’m going to grant administrator rights to user identities where the EmailAddress claim equals: admin@pbdev.com. This is done via the user picker, but with a bit of a twist as you can see from the following screenshot.

As you can see from the above screenshot, claim mappings that were configured in Step 3 are available in the user picker.

You need to be sure your administrative account actually has this email address configured in the E-Mail field in Active Directory.

Once this is done, we are ready to set up ADFS to authenticate users and provide claims to our new SharePoint web application.

Step 5: Add SharePoint as a Relying Party in ADFS 2.0

Now we need to create the trust relationship with SharePoint 2010 in ADFS.  This involves launching the ADFS 2.0 Management console, right-clicking the Relying Party Trusts folder, and selecting Add Replying Party Trust…   As you can imagine, this invokes the “Add Relying Party Trust Wizard”.

At Select Data Source, be sure to specify the radio button for “Enter data about the relying party manually” and click Next

At Specify Display Name, enter the display name and any helpful notes about the Relying Party and click Next.

At Choose Profile, select AD FS 2.0 profile.

At Configure Certificate, click Next.  We will not be encrypting the SAML tokens in this example and this is not a requirement.

At Configure URL, select the checkbox for “Enable support for the WS-Federation Passive protocol” and specify the URL for your site collection with /_trust/ appended to the end.  NOTE: SSL is a requirement here.

At Configure Identifiers, remove the default value and enter in the value stored in the “ProviderRealm” attribute of the SPTrustedIdentityTokenIssuer object.  This was provided in Line 3 of the earlier PowerShell script. You can also get this by running Get-SPTrustedIdentityTokenIssuer in PowerShell.

At Choose Issuance Authorization Rules, ensure the radio button for “Permit all users to access this relying party” and click Next.

At Ready to Add Trust, you can then review the configuration information and complete the Wizard.

We now have one final step to take.  Right-click the Relying Party Trust and select Edit Claim Rules.

At Choose Rule Type, select Send LDAP Attributes as Claims and click Next.

Create the new rule as follows:

Step 6: Test Access to SharePoint

We should now be at a point where we can log into SharePoint via ADFS.  Browse to your site collection and with any luck, you should now get passed directly into SharePoint.  If you’re the curious type, I’d recommend tracing the redirects using Fiddler.  Assuming you have the claims viewer web part installed in your root site collection, you should see something similar to the following.

Its interesting to compare these claims with those listed in Step 1 of this article. And note the source for the Email Address claim type is TrustedProvider: ADFS20Server.

Step 7: Grant Read Access to ADFS Authenticated Users

Next, we’re going to add any user who has been authenticated by ADFS 2.0 to have read access to our site collection.  This is done in a similar fashion as the end of Step 4 above.  When signed into the site with an administrative account, go to Site Actions > Site Permissions. Select the Viewers group and click New > Add Users.  At the next pop-up window, simply click the magnifying glass at the top.  This will result in the following screen:

Double-click “All Users (ADFS20Server)” to add these users to the group.

You should now be able to sign into the claims-enabled web application using a different, non-administrative account.

OK, I fully admit this isn’t the most exciting thing to see in the world. But as I mentioned earlier, this configuration is the foundation for doing some powerful things like plugging in various 3rd party identity providers. In an upcoming article, I’ll show you how to add a custom STS to ADFS 2.0 as a Claims Provider and use that STS to gain access to SharePoint. That Claims Provider will happen to be OpenID.