Introduction
SharePoint 2013 (and earlier versions) allows you to use alternative authentication “sources” than Windows. We can part from the different options with Windows login, use Forms Based Authentication (FBA) or use a federated/trusted identity provider. Forms based authentication is a good approach if you don’t want to manage your users in Active Directory or if you don’t want to use Windows Login. The downside with FBA is that you must manually do some web.config modifications, there isn’t any UI for managing the users (yes, I know you can use LDAP or just download something from the tubez, but you get my point). Using a federated approach is more interesting, that allows you to get the identity management and authentication away from your SharePoint farm (and this is a really good thing, SharePoint admins are generally not identity management people!). A trusted identity provider is a service such as Active Directory Federation Services (AD FS), Microsoft Azure Access Control Services (ACS) or any other SAML 1.1 compatible Identity Provider (IdP).
I generally don’t like using FBA, due to the issues above. In this post I will show you how to do forms based authentication without using FBA, but instead using a trusted identity provider called Thinktecture IdentityServer 2. IdentityServer 2 is an awesome implementation of an identity provider and supports a plethora of standards. And it comes as open source, with a web based UI, is very configurable and is just one of the best options for you when you need to set up your SharePoint with users not in Active Directory.
Thinktecture IdentityServer 2
Without describing the Thinktecture IdentityServer 2 in my own words I think the official overview says enough:
IdentityServer is a light-weight security token service built using .NET 4.5, ASP.NET MVC4, WCF and Web API. It has out-of-the-box support for user management using the ASP.NET membership and roles provider, but provides extensibility points to integrate arbitrary user databases. Futhermore almost any aspect of token issuance and data management can be customized using a plugin model.
The really cool thing with it is that it supports SAML 1.1 and can be used as a SharePoint 2013 (or 2010) trusted identity provider with a few lines of PowerShell. Secondly if you already has SharePoint hooked up to AD FS (or another similar service) you can add IdentityServer 2 as Claims Provider Trust.
Installing IdentityServer 2
The first thing we should do is to get our hands on IdentityServer 2 and set it up in our environment. You have two options; either make a github clone if you need to modify the source (https://github.com/thinktecture/Thinktecture.IdentityServer.v2) or download it directly (http://thinktecture.github.io/Thinktecture.IdentityServer.v2/downloads/). In this post I assume you don’t want to do any development and do it the lazy way and just downloads it. Ok, the official link above will only give you a 404 when you click on the download link at the moment, so use this page instead to download the .zip file for version 2.2: https://github.com/thinktecture/Thinktecture.IdentityServer.v2/releases/v2.2.0.
Now create a folder called IdSrv (or whatever you prefer) on one of your local disks, for instance d:\IdSrv\, and extract the ZIP file there. Next we need to create an IIS Web Site that uses this directory. Before proceeding with that we need to create a web server certificate – remember, always use certificates for these kind of services! You could use a self signed, but as always if you can use a domain/real CA that is preferred. Also you might need to set up a DNS entry, which is what I will use (idsrv.contoso.com). Once you have the certificate and hostname then you can proceed to the IIS configuring.
We’ll create a new IIS site pointing at the folder we unpacked IdentityServer to. We also need to specify the binding to use https and select our certificate, image on the left below. When we click OK this will create a new application pool for us in IIS, for that application pool we need to switch the identity to use a domain account or if we’re doing a single server install use the Network Service, image on the right below.
Since we now told IdentityServer to run as Network Service we also need to modify the folder permissions of the App_Data catalog and give the Network Service Modify permissions on that catalog. The App_Data catalog is where IdentityServer by default stores its database.
Once we have done this we can browse to the binding specified in IIS and start using IdentityServer 2.
Since this is a fresh installation and IdentityServer has no database we will be presented by a configuration screen. On that screen you should enter a site name, you must specify the Issuer URI (which uniquely identifies this issuer) as well as choose a signing certificate (this could be the one you created for the web site or a different one). Then you also need to specify an administrator username and password.
Before you click save you must make sure that the account running the application pool (Network Service in this sample) has permissions to read the private key of the certificate that you use as signing certificate.
Once you have done that you are all set to go!
Users and roles
To create users and roles you log in as the administrator and go to the administration menu and select users and/or roles. If you want to extend the user profile with more properties you need to modify the profile.config file under /Configuration in the IdentityServer folder. For this sample I add an additional property called “Title”, which I will use in a bit.
Before proceeding create at least one user and add that user to the “IdentityServerUsers” role, that is by default the role that is needed to use IdentityServer for authentication federation.
Final identity server tweaks
Ok, now have an awesome identity system up and running. We need to tweak a few things in IdentityServer before doing the SharePoint stuff. We need to add a Relying Party (RP) to IdentityServer, and the Relying Party in this case is SharePoint. As the administrator in IdentityServer choose to add a new Relying Party. This RP needs a display name, a realm and a redirect URL. The display name is whatever you prefer, the realm must be a URI and the Redirect URL should be you SharePoint site with “/_trust/” appended, like in the screenshot below.
Another tweak we need to do is to tell identity server to use SAML 1.1 instead of SAML 2.0, since SharePoint does not support SAML 2.0. That is done under General Configuration of IdentityServer and the “Default WS* Token” property should be set to “urn:oasis:names:tc:SAML:1.0:assertion”.
Adding IdentityServer 2 as a trusted identity provider
Now it is time to head on over to SharePoint and fire up a PowerShell prompt! The first thing we will do is to define a couple of properties:
## PROPERTIES
$realm = "uri:identityserver:sp03"
$signinurl = "https://idsrv.contoso.com/issue/wsfed"
$description ="Provide description here"
$url = "https://rootsite.sp03.contoso.com"
$metadataurl = "https://idsrv.contoso.com/FederationMetadata/2007-06/FederationMetadata.xml"
The realm must be the same realm that we configured in IdentityServer for the Relying Party. The signinurl can be found on the home page > application integration in IdentityServer and it’s the URL called WS-federation. Description is just some description that you provide and url is the URL to the Web Application where you want to add this identity provider. Finally metadataurl is the WS-federation metadata end-point for identity server and that URL can be found on the same page as where we located the sign in URL.
We’ll use this WS-federation metadata end-point to do some discovery from the SharePoint side:
## LOAD FEDERATION METADATA
$fedmd = Invoke-WebRequest -Uri $metadataurl
$fedmdXml = New-Object Xml
$fedmdXml.LoadXml($fedmd.Content)
$base64 = $fedmdXml.EntityDescriptor.RoleDescriptor.KeyDescriptor.KeyInfo.X509Data.X509Certificate
$base64| Out-File -FilePath temp.cer -Append:$false
$cert = Get-PfxCertificate -FilePath temp.cer
Remove-Item temp.cer
By invoking the end-point we can retrieve the signing certificate, and other metadata. We grab that certificate and temporary stores it as a .cer file before loading it up in a certificate variable which will be used to install it in SharePoint.
## ADD TRUST IN SP
asnp *sh*
$name = $fedmdXml.EntityDescriptor.RoleDescriptor.GetAttribute("ServiceDescription")
New-SPTrustedRootAuthority -Name $name -Certificate $cert | Out-Null
We use the certificate variable to create a trust in SharePoint, together with the name of the service, retrieved from the metadata endpoint.
Next up is to create some claims mappings and the trusted identity token issuer in SharePoint.
## CREATE TRUSTED IDENTITY TOKEN ISSUER
$map1 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" `
-IncomingClaimTypeDisplayName "Email" –SameAsIncoming
$map2 = New-SPClaimTypeMapping "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" `
-IncomingClaimTypeDisplayName "Role" -SameAsIncoming
$map3 = New-SPClaimTypeMapping "http://identityserver.thinktecture.com/claims/profileclaims/title" `
-IncomingClaimTypeDisplayName "Title" -SameAsIncoming
$tit = New-SPTrustedIdentityTokenIssuer -Name $name -Description $description -Realm $realm `
-ImportTrustCertificate $cert -ClaimsMappings $map1,$map2,$map3 -SignInUrl $signinurl `
-IdentifierClaim $map1.InputClaimType
We create three claims mappings in this case; the first one is the e-mail claim, the second one is a role claim and the third one is our custom claim using the user property Title we created. We can get the claims identifiers from the XML in the metadata endpoint. We’ll use the first claim, e-mail, as our identity claim when we finally create the trusted identity token issuer also passing in the realm and sign-in URL.
Once this is done all we need to do is update our Web Application(s) to use this new identity provider. This can be done in the UI in Central Administration per Web Application or using PowerShell like this:
## UPDATE WEB APPLICATION WITH NEW IDP
$wa = Get-SPWebApplication $url
$ap = Get-SPAuthenticationProvider -WebApplication $wa -Zone Default
if($ap.Count -eq 1) {
$aps = New-Object System.Collections.ArrayList
$aps.Add($ap) | Out-Null
}
else {
$aps = $ap
}
$ap = New-SPAuthenticationProvider -TrustedIdentityTokenIssuer $name
$aps.Add($ap) | Out-Null
Set-SPWebApplication -AuthenticationProvider $aps -Zone Default -Identity $wa
First we retrieve the current authentication providers for the web application, then we create a new one from our just recently created trusted identity token issuer and then we add them all (as an array) to the web application.
That’s it! Time for a test ride…
Browse to a site on the web application where you enabled the IdentityServer authentication. You should be presented with the awesome standard SharePoint login selector page. In the drop down you will see two options; Windows Authentication and our IdentityServer option:
Select to log in using IdentityServer. This will take you to the log in page of identity server, where you present your credentials. If you log in using that user you created in identity server you will after a successful login see an access denied page from SharePoint. That’s because that user doesn’t have permissions yet.
It is now we can take advantage of that we added the role or title claims. Open up a new browser and log in using Windows Authentication and give permissions to either a role or a title. Unfortunately the default claims people picker in SharePoint is a bit stupid when it comes to working with claims. You need to write the name of the group or title and then pick the correct claim. Hover the cursor over the alternatives to see which identity provider and which claim is which one. In this case we see three (our three different claims).
Once you have given permissions to a role, title or directly to the e-mail of the user, you should be able to log in properly and see the site.
Summary
In this post I’ve shown you how to use Thinktecture IdentityServer 2 as an identity provider to SharePoint 2013. IdentityServer is a great alternative to using FBA when you need a custom user and role store and it’s way easier and more manageable to set up, no fiddling with web.configs or installing full trust code you download from the interwebs in your SharePoint farm. Enjoy!