Configuring the Realm – Using SharePoint 2010 with ADFSv2 to Retrieve Claims

When configuring SharePoint 2010 for claims based authentication or authorization you typically need to connect to an identity provider to retrieve user attributes as claims. To really see all the benefits of claims in the enterprise, we need to ensure that our SharePoint Server trusts the claims its receiving, and that often means configuring it to connect to a “trusted identity provider”. One such server application that can act as a trusted identity provider is Microsoft Active Directory Federation Services version 2.0 (ADFSv2). ADFSv2 is often also referred to as a ’secure token server’ because it plays the role of retrieving user attributes from Active Directory (or some other LDAP directory or data store), wrapping them up in a SAML token, digitally signing that token and returning it to the calling application – in this case SharePoint 2010. Configuring ADFSv2 in such scenarios can be tricky and unforgiving, and this article focuses on 1 particular part of that configuration – the Realm.

If you attended my session at the Microsoft SharePoint Conference a couple of weeks ago, called “Using Claims for Authorization in SharePoint 2010″, you would have seen my demonstration of SharePoint 2010 connecting to ADFSv2 to retrieve claims in a trusted manner, and then TITUS Metadata Security automatically applying authorization policies to documents in SharePoint based on a user’s claims and document metadata. During the demonstration, one person questioned the value I had configured for the “realm” variable. They very astutely noticed that it was configured to the following:

urn:sp-server-2010.sp.local:sharepoint2010

The portion of the realm which reads “sp-server-2010.sp.local” actually matches the domain of the SharePoint server I was using during my demo, and I think this implied the realm variable was doing more than it actually is, so I think this topic is worth a little clarification.

I’ll back up for a second to describe at a high level how I configured ADFSv2 and SharePoint, and then focus specifically on exactly how the realm variable is used.

High-Level Configuration of SharePoint 2010 and ADFSv2

When configuring SharePoint 2010 to authenticate through ADFSv2 and retrieve claims, the following is the process at a high level that you’ll typically follow in a very simple base case:

1. Download ADFSv2 from the Microsoft ADFS web site (its free) and after starting the setup program select to install it as a Federation Server.
2. On the ADFSv2 server, go into the IIS Management Console and create a self-signed certificate.
3. Within the ADFS 2.0 Management application, create a New Federation Service – there is a great wizard provided for this. Take note of the “Federation Service Name” (in my case it is https://sp-server-2010.sp.local) as its used a little later on.
4. Expand the Service node, and under the Claims Descriptions node add a new claims description for any custom claims you wish to return – there are 21 claims already there by default like Email. Here we are selecting claims to be sent back to SharePoint, but we are not yet mapping them to AD attributes. For any custom Claims Descriptions you’ve added, take note of claims type URL.
5. Expand the Trust Relationships node, and under the Relying Party Trusts node add a new relying party trust – there is a great wizard for this as well.  There are several options to choose here, but some of the critical ones are the following:
   - Select “WS-Federation Passive” as the protocol
   - For the Relying Party URL use the ‘Federation Service Name’ from above plus ‘/_trust/’ (so in my case its https://sp-server-2010.sp.local/_trust/)
   - For the Relying Party Trust Identifier here is where we need to specify a realm and where the confusion came in.  More on this point a little lower in this article.
6. Create Claims Rules for the Relying Party Trust you just configured. Here is where we map AD attributes to Claim Descriptions. For complex scenarios, consider using the Claims Rule Language built into ADFSv2.
7. View and Export ADFSv2 Token Signing Certificate – c:\adfs20Certificate.cer. You will need to copy this to the SharePoint 2010 server. We need to use this certificate when configuring SharePoint 2010.
8. In SharePoint you are now going to create a new web application. You’ll select that it uses Claims Based Authentication over NTLM to start, ensuring that it uses port 443 and SSL. Ensure the public URL of the web app matches the one in the ADFSv2 certificate – this is where we start to establish trust between this web app and the ADFSv2 server. Do not create a site collection yet.
9. You will then run a PowerShell script on the SharePoint server in order to map the claims being retrieved, set the realm and set the certificate that SharePoint should use to validate the claims received (the c:\adfs20Certificate.cer file described above). The PowerShell script is included below.
10. Finally, in SharePoint 2010 you will now log into Central Admin, access the Authentication Providers page for the web application you just created, click Default and check on “Trusted Identity Providers” and the ADFSv2 Provider you just configured. You can optionally uncheck the NTLM provider you configured earlier. You can now create a new site collection, site and libraries.

Now, there are a lot of details in each step and as mentioned the process can be unforgiving if mistakes are made. For a detailed end to end description of the entire process I encourage you to visit Steve Peschka’s Share-n-dipity blog.

The Realm

Now, getting back to the discussion on the realm – when creating a Relying Party Trust within ADFSv2, you are establishing a trust relationship between ADFSv2 and a calling application. In our case the calling application is SharePoint. When creating this trust, you need to specify a Relying Party Trust Identifier which is a realm. The realm can in fact be anything you want, as long as it follows the specific format:

urn:something:something_else

In my case, because the calling application was my SharePoint 2010 server I chose to use the URL associated with that server so it ended up looking like this:

urn:sp-server-2010.sp.local:sharepoint2010

…but I could have used anything I wanted after the “urn:” and after the second “:”. I would recommend avoiding spaces here though.

The realm is associated with the claims aware web application that’s making a request to ADFSv2 (again, in our case the SharePoint web application). When ADFSv2 receives a login request from SharePoint, it is uses the realm to map the request to one of the relying party trusts that has been configured. With that relying party trust, once the user has been authenticated, ADFSv2 then knows which attributes to retrieve, how to map or manipulate them and what protocol to use in returning them to SharePoint.

So, in our case, when I navigate to SharePoint at https:\\sp-server-2010.sp.local I’ll be redirected to ADFSv2 and it will receive the realm “urn:sp-server-2010.sp.local:sharepoint2010″ with the login request. Once I’ve been authenticated and ADFSv2 has retrieved, mapped, wrapped and signed my claims, ADFSv2 will redirect me to https:\\sp-server-2010.sp.local\_trust\ because that’s the WS Federation passive protocol URL that I configured with the relying party trust. Its important to note that the realm is simply used to map the calling app that’s making the login request to a configured relying party trust so that ADFSv2 knows how to deal with the request. The realm is not used at all to to redirect the user to any URL.

This realm value is also used in the step mentioned above which requires running a PowerShell script on the SharePoint server. That step configures the SharePoint web application with the realm to use in making its login request to ADFSv2 – so its important to use the same value configured in your relying party trust. Here is a sample of that PowerShell:


# Make sure the claim types are properly defined in the ADFS server
$map = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
$map3 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.sp.local/EmployeeStatus" -IncomingClaimTypeDisplayName "EmployeeStatus" -SameAsIncoming
 
# The realm will identify the web app in ADFS. It is generally created in the form "urn:something:something_else"
$realm = "urn:sp-server-2010.sp.local:sharepoint2010"
 
# Use the certificate that has been exported from the ADFS server
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("c:\adfs20Certificate.cer")
 
# The url below will tell SharePoint where to redirect to in order to authenticate with the STS
# so this should have the ADFS url, plus the protocol (Windows integrated security - "/adfs/ls")
$signinurl = "https://adfs20.sp.local/adfs/ls"
 
# Adds the STS (AD FS 2.0) to SharePoint
$ap = New-SPTrustedIdentityTokenIssuer -Name "ADFS20 Provider" -Description "SharePoint secured by ADFS20" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map,$map2,$map3 -SignInUrl $signinurl -IdentifierClaim $map.InputClaimType
 
# The certificate imported from the ADFS should be added to the trusted store
New-SPTrustedRootAuthority -Name "ADFS Token Signing Root Authority" -Certificate $cert


Again, the script must be run on the SharePoint 2010 server. There is a lot going on in it including:

- mapping claim types
- configuring the realm which SharePoint will use in the login request
- specifying the certificate to use in validating the token received from ADFSv2
- adding the trusted identity provider to SharePoint – named “ADFS20″ Provider here
- adding the certificate from ADFSv2 to the trusted certificate store

I’ll mention one more time that its very important to ensure that you’ve included the correct realm and all the correct URLs in your PowerShell script. If you run it with typos it can often mean starting the whole process over again. Hopefully this helps to clarify any questions about how the realm is used in configuring SharePoint with ADFSv2.

More importantly, hopefully this post helps to clarify how trust is established between SharePoint 2010 and a trusted identity provider like Microsoft Active Directory Federation Services 2.0, because only when user attributes in SharePoint are trusted is the enterprise really going to fully benefit from Claims through Claims Based Authentication and Authorization.

-Antonio