Ever wondered how to configure SharePoint to use ADFS for user authentication? Googled it and found it confusing? Me too! Don’t despare though… the Powershell is pretty straightforward and it only gets easier the more often you do it…
Export ADFS Signing Certificate
First of all log in to the ADFS server and export the signing certificate. The following powershell should be ran as administrator and will export the certificate to c:\ADFSSigning.cer.
$certBytes=(Get-AdfsCertificate -CertificateType Token-Signing)[0].Certificate.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)
[System.IO.File]::WriteAllBytes("c:\ADFSSigning.cer", $certBytes)
If your ADFS signing certificate was issued by a certificate authority and not self-signed by ADFS, you must ensure the entire certificate chain is trusted by SharePoint as well. I won’t cover this process here, but you can refer to another post on the topic here.
Add ADFS Relying Party Trust
While you are on your ADFS server, you may as well create the relying party trust in, you guessed it, powershell. But first you need to make a txt file with the following contents. For ease, lets say c:\rules.txt. These are the transformation rules for the relying party. I find this is all that is really required to start with as User Profile Sync will grab the rest.
@RuleTemplate = "PassThroughClaims"
@RuleName = "SharePoint Attributes"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"), query = ";mail,mail,sn,givenName;{0}", param = c.Value);
Then edit the variables in the powershell below and execute it. Here a quick explanation of the variables.
$rules – The path to the rules.txt files you have just created.
$name – The name of the relying party trust.
$urn – If you don’t know what this is, just leave it.
$webapp – The URL for the first web application you are going to use. I’ll show you how to add another application later. Don’t put a trailing slash on the URL.
$rules = "c:\rules.txt" $name = "SharePoint Site 1" $urn = "urn:sharepoint:site1" $webapp = "https://site1.domain.local" $endpoint = $webapp + "/_trust/" [string[]] $urnCollection = $urn, $webapp Add-AdfsRelyingPartyTrust -Name $name -ProtocolProfile WSFederation -WSFedEndpoint $endpoint -Identifier $urnCollection -IssuanceTransformRulesFile $rules
You can now go and check in the ADFS console and yor new trust should be listed under Relying Party Trusts.
Add Token Signing Certificate to SharePoint
Log in to the SharePoint server that hosts central admin and copy the ADFSSigning.cer file to the C drive then open the SharePoint Management Shell as administrator. The following powershell will import the certificate so that SharePoint trusts it.
$path = “C:\ADFSSigning.cer” $root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($path) New-SPTrustedRootAuthority -Name "ADFS Token Signing Cert" -Certificate $cert //Keep this window open for the next step
Again, of your ADFS signing certificate was issued by a Certificate Authority instead of being self-signed by ADFS, you must make sure SharePoint trusts all other certificates in the chain.
Create The Authentication Provider In SharePoint
To add ADFS as a Authentication Provider to SharePoint, use the following powershell in the same windows that you imported the certificate in:
//Map the email address, UPN, Group Memberships and SID from ADFS $emailClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming $upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" -IncomingClaimTypeDisplayName "UPN" -SameAsIncoming $roleClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming $roleClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming //Update the following to match the details entered earlier if you changed them $realm = "urn:sharepoint:site1" $signInURL = "https://adfs.domain.local/adfs/ls" $ap = New-SPTrustedIdentityTokenIssuer -Name ADFS -Description ADFS -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $emailClaimMap,$upnClaimMap,$roleClaimMap,$sidClaimMap -SignInUrl $signInURL -IdentifierClaim $emailClaimmap.InputClaimType
Providing you don’t get any error, SharePoint should now be able to use ADFS as a authentication provider.
Change SharePoint Application to Claims Based
Now you need to make one of your SharePoint web applications use ADFS for authentication. There are a number of caveats with this though:
- You will lose access to the web application as your permission is set on the account SharePoint knows of from windows authentication. I’ll show you how to fix this soon.
- Your user profile will not be associated with your account any more. This is again because the User Profile Service has synced your profile with Active Directory using your windows account.
- Search will be unable to crawl the SharePoint site as it doesn’t support claims based authentication.
I’ll show you how to fix these things in a future post, otherwise this post will end up being a monster.
For now, I’d recommend performing these steps on a newly created SharePoint Web Application of your choosing. The commands assume a site called https://site1.domain.local.
Open up the SharePoint management shell as administrator and run the following commands:
$webApp = Get-SPWebApplication -Identity "https://site1.domain.local" $sts = Get-SPTrustedIdentityTokenIssuer "ADFS" Set-SPWebApplication -Identity $webApp -AuthenticationProvider $sts -Zone "Default"
If you now try to access the site you should be redirected to your ADFS sign-in page. Once you login, you will probably get the “This site hasn’t been shared with you” message. Keep reading for a fix.
Changing More SharePoint Applications to Claims Based
The above powershell will certainly allow you to change another web application across to claims based authentication, but with one little issue. Upon doing so, every time you try to access the second web application you will end up back at the first one after you login. This is because the realm of the second web app is different, and ADFS will just send you straight to the first site configured. Luckily thought there is no need to mess on with certificates for the second site.
On the SharePoint server, open the SharePoint Management Shell as admin and use the following commands to add another realm to the authentication provider:
$urn = "urn:sharepoint:site2"
$ap = Get-SPTrustedIdentityTokenIssuer
$uri = new-object System.Uri("https://site2.domain.local")
$ap.ProviderRealms.Add($uri, $urn)
$ap.Update()
Then you need to add another Relying Party Trust in ADFS to handle requests for the second SharePoint site. To do this, follow the steps in the section of this post Add ADFS Relying Party Trust, but remember to update the strings in the powershell commands to represent your second site.
Regain Access to Site With Claims Based Authentication
Now that your site(s) are claims based authentication enabled, you need to re-add yourself as a site collection administrator. The following powershell will set your ADFS formatted account as the secondary site collection owner. You can also do this in central admin but I won’t go into that route in this post.
Set-SPSite –Identity "https://site1.domain.local" –SecondaryOwnerAlias "emailaddress@domain.local"
Updating the Signing Certificate in SharePoint
For whatever reason Microsoft hasn’t given, SharePoint can’t use the Federation Metadata issued by ADFS to update the Signing Certificate when it is renewed at the end of its validity period, leaving it up to the administrator to do this manually.
The process of updating the certificate isn’t particularly complex. It’s basically export the new certificate, then install it and import it on the SharePoint server before updating the Trusted Token Issuer in SharePoint to use the new certificate. The problem is though that if you forget to update the certificate in the brief period between the ADFS server renewing it’s certificate and the old certificate expiring, nobody will be able to login to SharePoint. And trust me, you WILL forget at least once.
Fortunately, Jesus Fernandez has a solution over on MSDN in the form of a powershell script that can be scheduled to run on the SharePoint server. The script reads the afor mentioned Federation Metadata from ADFS and downloads the current token signing certificate. If it is different to the one SharePoint is using, it adds it to SharePoint and updates the Token Issuer in SharePoint to use the new certificate. Nifty huh? I’d strongly recommend this as a solid option.
Dan McIntyre 