UPDATED: How To Add ADFS 2.0 as a Federated Identity Provider in SharePoint 2010

NOTE: This blog is based on a post originally written at the end of 2009 when both SharePoint 2010 and AD FS 2.0 were in Release Candidate stage. The version you are reading here has been updated it to correct some important omissions related to the RTW bits.

========================

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

This example covers a single server that is used as a development / “proof-of-concept” virtual machine. It is a Domain Controller and is running SharePoint 2010 and SQL Server 2008 R2. You should be able to follow this walkthrough if you’re testing in a multi-server environment as well. Just keep in mind that some of my instructions may not apply.

Step 1: Create a Claims-Enabled Web Application

The IT Leader's Guide to Multicloud Readiness

This guide provides practical key insights and important factors to consider to make informed decisions in your multicloud journey.

Download the Guide

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. In this example, I’m giving the web application the hostname of “fabrikam”.

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, with the “OriginalIssuer” being, for the most part, “Windows”.

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:

After all this is done, you should be able to 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 had pre-configured a certificate that uses the fully qualified domain name of my test server: sp2010.pbdev.local. If necessary, you can change up this certificate to match the one bound to the site by selecting Set Service Communications Certificate… on the right pane.
NOTE: In this example, I’m using a fully qualified domain name. If you’re doing the same, you may need to add the URL to the “Trusted Sites” zone in Internet Explorer. Otherwise, you may be prompted to authenticate to ADFS when redirected to it from SharePoint. Keep this in mind for your deployment planning.
Make any changes necessary to ensure the Service Communications certificate and SSL binding in IIS is fully operational and you have what you want.
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

In SharePoint 2010, the creation and management of a federated identity provider is done in PowerShell. The following commands must be customized to fit your environment and executed:
$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/upn” -IncomingClaimTypeDisplayName “Account ID” –SameAsIncoming
$map2 = New-SPClaimTypeMapping “http://schemas.microsoft.com/ws/2008/06/identity/claims/role” -IncomingClaimTypeDisplayName “Role” –SameAsIncoming
$map3 = New-SPClaimTypeMapping “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress” -IncomingClaimTypeDisplayName “Email Address” –SameAsIncoming
$realm = “urn:sp2010:adfs”
$signinurl = “https://[YOUR_SERVER_NAME]/adfs/ls/”
$ap = New-SPTrustedIdentityTokenIssuer -Name “ADFS20” -Description “ADFS 2.0 Federated Server” -Realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map1, $map2, $map3 -SignInUrl $signinurl -IdentifierClaim $map1.InputClaimType
This script maps three claims that may be received by the ADFS SAML token (inbound claims) to SharePoint claims. Recall in the screenshot from Step 1 that SharePoint always issues its own claims. Hence, the requirement to map values from inbound tokens. In the last line, the first mapping (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn) is defined as the identifier claim. This means the claim uniquely identifies the user to SharePoint and therefore may never be empty. All other claims (role and email) are optional. This is very important to keep in mind when you proceed to integrate with ADFS in later steps. In this example, I’m basically using the UPN claim as a global “Account ID”.
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.
Next, we need to create a trust relationship between SharePoint and AD FS. This is done by opening Central Admin and selecting Security on the left hand navigation. At the next page, select Manage Trust in the General Security section. Then, click “New” in the upper left hand corner and supply a name and specify the ADFS token signing certificate (end of Step 2 above) as seen in the following screenshot.

Step 4: Prepare the Web Application

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.

In order for ADFS to work with SharePoint, the web application must be enabled for SSL. Since I’m using a custom DNS name for my site (fabrikam), I’m going to use SelfSSL, which is part of the IIS 6,0 Resource Kit Tools. Creating a self-signed certificate is pretty straightforward:
selfssl.exe /N:CN=[your site hostname] /K:1024 /V:730 /S:[your site IIS ID] /P:443 /T
…where the value for S: is the ID of the site in IIS and the value just behind the “CN=” for the /N switch is the host name of your Web App.
FOR SINGLE SERVER ENVIRONMENTS: Note that on Windows, an IP address can only be bound to a single certificate. This means your Web Application should be bound to a specific, dedicated IP address. I’m working on a single-server environment, so the bindings for the site look like this:

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.
The final step for SSL is to update the Default zone in Alternate Access Mappings so that https is enabled and users are redirected, if necessary.

When you create a claims aware application, you’ll have to grant claims users some sort of permissions to access you’re the site. 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 add all authenticated ADFS users to the site “Visitor” SharePoint group. This is done in the standard way, but when the user picker control loads, you’ll need to leave the content of the “Find” field blank and click the magnifying glass icon. You will then see an “All Users (ADFS20)” group listed.

You can also assign users with certain claims values with special permissions in SharePoint. I’ll go ahead and add ADFS users with an “Account ID” (upn) claim value of: administrator@pbdev.local to the Site Collection Administrators group. Recall that we had mapped the inbound claim “upn” earlier in the PowerShell script and configured it as our Identifier claim.

In this example, we’ll need to check and be sure that the Administrator account actually has the specific User Principal Name value 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:

You should notice the above rules map exactly to what we specified in the PowerShell script in Step 3. And remember that the outgoing claim of UPN must never be null. Otherwise, there will be an authentication failure.

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 (OriginalIssuer) for ‘emailaddress’, ‘role’, and ‘upn’ claim types: ADFS20. The rest of the claims originate from the SharePoint STS.
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.