SharePoint claims based authentication with Thinktecture identity server – Walkthrough

This article describes how to setup claims based authentication for SharePoint using the Thinktecture Identity Server. If you don’t know about the Thinktecture identity server, it’s a great open source identity provider (IP-STS) available via codeplex: http://identityserver.codeplex.com

For brevity I’ll be referring to the Thinktecture identity server as the IP-STS and SharePoint as the RP-STS in the remainder of this article. Additionally, this setup is for demonstration purposes only, in a production environment you would probably not want to use self-signed certificates as I do here and you’re web applications should be secured with SSL.

To setup claims based authentication, the following steps need to be completed:

• Create Certificates
• Configure Identity Store
• Create Trust between IP-STS and RP-STS
• Test Authentication

So lets begin with creating certificates.

 

Create Certificates

Before the RP-STS can trust the IP-STS, the IP-STS must be able to prove it’s authority – this is done via certificates. We’ll need to create a certificate for the IP-STS to use to sign the tokens it sends the the RP-STS. These tokens contain the claims about the identities the IP-STS authenticates and the RP-STS will only accept these claims when they are signed with a trusted certificate. Therefore, there are three steps involved in the certificate management:

• Create the certificate
• Register the certificate with the IP-STS
• Register the certificate with the RP-STS

In this demo, I’m using self-signed certificates which you probably wouldn’t want to do in a production environment. To create a self signed certificate, open a Visual Studio command prompt and enter the following:

makecert -r -pe -n CN=idp.bc01.com -ss my -sr localmachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 idp.bc01.com.cer

The above will create a certificate for the “idp.bc01.com” domain and save the certificate to a idp.bc01.com.cer file. This will also install the certificate on local machine’s Personal Certificates store, ready to be assigned to a site in IIS configuration.

 TIP: if you want to make a client browser trust it, run mmc and add the certificates snap-in and choose Local Computer as the account. Then import it into Trusted Root Certificates.

Next, we are going to add the certificate to the RP-STS. To do this, open Central Admin –> Security –> Manage Trust and select ‘New’ from the ribbon. Import the certificate you just created and assign it a name, press OK:

Once the certificate is imported, you can review it’s properties:

At this point, you’ve configured the RP-STS to trust this certificate but we need to get the IP-STS to use this certificate when it signs tokens. I’m assuming you’ve already downloaded the Thinktecture identity server project and built the solution, if not you’ll need to complete the following steps:

• Build the Thinktecture identity server project
• Create a new IIS web site and point it’s root directory at the ‘website’ project directory of the Thinktecture solution.
• Set the App Pool for the new web site to use .NET 4 Framework
• Assign the certificate you created above to the IIS web site – typically in a production environment you would use a separate certificate for the IP-STS site and the actual signing of tokens

 

Configure Identity Store

Now we have the basic IP-STS site configured, we need to create an identity store for the IP-STS to use. the Thinktecture identity server uses a pluggable model to connect to a variety of identity stores or you can create your own. In this example I’ll be using the ASP.NET SQL Server Registration Tool to create a database to store and manage my identities. To create your identity store you use aspnet_regsql.exe, full details of this command can be found here: http://msdn.microsoft.com/en-us/library/ms229862(VS.80).aspx

Note: although this is the same identity store that can be used with SharePoint forms based authentication, this store will be connected to the IP-STS and SharePoint will not directly connect to it.

Once you have your identity store created, I typically create another IIS web site to manage the identities via the IIS Manager UI. To do this, create another IIS web site (that is neither the IP-STS web site nor a SharePoint site) and create a connection string to point to your newly created identity store database:

Now create the following .NET Roles:

The ‘Milkman’ role is optional but you could use this as a claim presented to the RP-STS later. Finally, create some users and assign them to these roles – ensuring you assign at least one user to the IdentityServerAdministrators role:

Lastly, open the Thinktecture solution in Visual Studio and locate the connectionString.config file in the WebSite project:

Update the connection string in this file to point to your identity store database:

In my example this database is called SharePoint_FBA but again, this is nothing to do with FBA in SharePoint and SharePoint never directly connects to this database – I’m just reusing an identity store I already had created for another project.

Now run rebuild the Thinktecture solution and access the IP-STS web site – in my example http://idp.bc01.com and you should see:

Sign into the site with the user credentials you added to the IdentityServerAdministrators role. Once signed in click on the [administration] link and you should see the following menu:

Now we need to configure the IP-STS. First, starting at My Claims, you can view the current claims available for the logged on user:

I’ve highlighted in red the claim we’re going to be using as our identity when we sign into the RP-STS. In green I’ve highlighted the additional claim the IP-STS has added for the current user as this user was also a member of the Milkman role in the identity store.

Next, click view My Token to see the token the IP-STS has issued to the current user in XML format:

This can be useful screen for reviewing and debugging claims based authentication.

Next, under Global configuration, we need to adjust a few setting:

Set the Default Token Type to:

and switch on the following options:

Next, under Certificate Configuration, ensure that the Current SSL and Current Signing certificates are set to the certificate you created earlier:

Lastly, under Relying Parties we need to create an entry for our RP-STS (SharePoint). Set the Relying Party Name, Realm URI and ReplyTo URL (assumes you’ll create a web application with the URL http://claims.bc01):

NOTE: Strictly speaking the Realm URI does not need to be the same as the ReplyTo URL but for to simplify configuration these are set to the same address.

Your IP-STS is all done.

IMPORTANT: Be sure to sign out of the IP-STS site before you continue.

 

Create Trust between IP-STS and RP-STS

Next we are going to configure SharePoint to act as a RP-STS and use the IP-STS we’ve just configured. We do this via PowerShell.

First we create a certificate object from the certificate file we created earlier:

$root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\idp.bc01.com.cer")

Next we create a new Trusted Root Authority that uses the certificate:

New-SPTrustedRootAuthority -Name "idp Signing Cert" -Certificate $root

Next we create a claim mapping. In this example we are creating a single claim mapping based on emailaddress:

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

Next we create a realm, this needs to be exactly the same as the realm URI specified in the Thinktecture Relying Party configuration:

$realm = http://claims.bc01/_trust

Lastly we create Trusted Identity Token Issuer that uses the certificate, claims mappings and realm we just created. Additionally, it specifies which claim is the identifier claim, in this example it’s the emailaddress. The following PowerShell creates a new Trusted Identity Token Issuer called “idp SAML Provider”:

$ap = New-SPTrustedIdentityTokenIssuer -Name "idp SAML Provider" -Description "Thinktecture IDP (SAML)" -Realm $realm -ImportTrustCertificate $root -ClaimsMappings $map -SignInUrl "https://idp.bc01.com/account/signin" -IdentifierClaim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

NOTE: the SignInUrl for the command is what redirects the user to the IP-STS to authenticate.

With all that PowerShell configuration complete, we can go ahead and create a new Web application. Be sure to use claims based authentication for the authentication mode and select the new Trusted Identity Provider as the claims authentication type:

…also be sure to leave NTLM authentication for the web app enabled.

With this in place we are ready to test authentication.

 

Test Authentication

To test authentication we need to ensure the user we access the site with has at least view permissions to the web app (I’m assuming you also created a root site collection in the web app you created in the previous step) and is a member of the IdentityServerUsers role within the identity store.

Access the new web application and when prompted to pick the type of credentials used to logon to the SharePoint site, choose Windows Authentication:

NOTE: You now get prompted to choose the authentication provider when you access the site because the web app support both claims based authentication via our new Trusted Identity Provider and NTLM authentication.

Enter valid windows credentials for a user who has Site Collection admin privileges. Once logged on, select Site Actions – > Site Permissions –> Members Group (the actual name of the group will depend on the name of your site collection). Now from the ribbon, select New and enter the email address of a user you created in the identity store earlier, again this user must be a member of the IdentityServerUsers role in the identity store:

NOTE: type the users email address very carefully as by default anything you type will be validated as a valid claim (see Claims Provider – http://msdn.microsoft.com/en-us/library/ee535894.aspx for more details on this default behaviour).

Add the user to the SharePoint group and log off the SharePoint site.

Now we are going to log on again but this time select the trusted identity provider as the authentication type. When we do so we will be redirected to the IP-STS to authenticate:

Enter the credentials of a user you entered into your identity store earlier who is a member of the IdentityServerUsers role and press Sign In. the IP-STS will authenticate your credentials and build you a SAML token. The SAML token will be returned to your browser as a cookie and your browser will be instructed to redirect to the SharePoint site (to the /_trust virtual directory):

This should culminate in you being signed into SharePoint with your claims based identity:

You can verify you are signed into you RP-STS (SharePoint) via claims based authentication by selecting My Settings from your sign in name:

When you do this, you’ll see the account name displayed includes the trusted identity provider:

Finally, the codeplex project http://claimsid.codeplex.com/ contains a useful web part you can drop on any web part page that will display the details of the current claim you’re signed in with. In my example, it looks like this:

 

Summary

Hopefully this has given you a few pointers to setting up claims based authentication with SharePoint. I would recommend checking out the Thinktecture codeplex project – it a great basis for deploying or developing a custom IP-STS.

Enjoy!

UPDATE: My next article shows how to add additional claims to the SharePoint RP-STS: http://sharepintblog.com/2011/10/26/adding-additional-claims-to-a-trusted-identity-token-issuer/