Many farms are moving from Windows Authentication(NTLM or Kerberos) to SAML. This migration and change requires a lot of planning. This guide is only to give a frame work of migrating some of the simpler farms. This guide also assumes that the ADFS server is already setup and just needs to be configured.
The difference of this guide and other guides are two things. We will be using the -UseDefaultConfiguration when created the trusted identity token issuer. This will give us an OOB claims provider instead of having your farm fending for itself with the people picker/claim provider. The next difference is the user and group migrations. We will be using Convert-SPWebapplication instead of developing a script to use Move-SPUser. More details later in the post about both of these.
Requirements:
- The SharePoint farm has to be at June 2014 CU (or higher) for SharePoint 2013(15.0.4623.1001).
- The web applications must be Windows Claims. SAML is not supported on classic.
- ADFS must be backed with the same Active Directory used in Windows Claims.
Steps to be completed:
- Configure ADFS
- Creating Trusted Identity Provider
- Migrate Users and Groups
Config ADFS
As stated above we assume the ADFS server is setup and connected to AD and ready to configure the Relying Party Trusts.
-
In AD FS, right click Relying Party Trusts and select Add Relying Party Trust.
-
This will bring up Add Relying Party Trust Wizard. Click Start
-
Click Enter data about the relying party manually, Next.
-
Type in a display name and description(optional). Click Next.
-
We want to select AD FS 1.0 and 1.1 profile since SharePoint does not support anything but SAML 1.1.
-
We will need to enter in the web application with /_trust. This will need to be HTTPS.
-
We will need to add in the realm for an identifier. I entered in urn:sp13:contoso. We will be using this on the SharePoint side.
-
I’m not using Multi-factor so just clicking Next
-
We’re permitting everybody through. Click Next
-
Click Next
-
Click Close and leave the box checked. We will be mapping claims.
-
In the Issuance Transform Rules, click Add Rule…
-
Leave the drop down value at Send LDAP Attributes as Claims. Click Next
-
Give the claim rule a name. Select Active Directory from the dropdown.
-
We will only be mapping the required fields here. The first one we will map is your identifier claim. This is the claim that a user needs to have in AD to sign in. The only choices Account-Name, Email or USER-PRINCIPAL-NAME. Adjust your guide as needed. I will be using Email. The only other Claim is for security groups.
| LDAP Attribute | Outgoing Claim Type |
| User-Principal-Name | UPN |
| E-Mail-Address | E-Mail Address |
| SAM-Account-Name | Windows account name |
| Token-Groups as SIDs | Group SID |
-
We will need the Token-sign certificate from ADFS. Click on Certificates, then click on the token-signing certificate, then View Certificate
-
Click on Details tab and Copy to File…
-
DER .CER is the file format we want. Click Next
-
Give the file a name and location. Click Next
-
Click Finish. Copy the certificate to the SharePoint server.
Creating Trusted Identity Provider
-
On the SharePoint server, open PowerShell ISE. We will be loading the SharePoint module using Add-PSSnapin *sharepoint*
- This is to set the path of the token signing certificate we got from ADFS
$adfscertPath = “c:\adfstoken.cer” $adfscert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($adfsCertPath)
3. We want SharePoint to trust the certificate.
New-SPTrustedRootAuthority -Name “ADFS Token Signing Cert” -Certificate $adfscert
4. The script to create the trusted provider in SharePoint.
The -Realm is what we put in as an identifier for ADFS(urn:sp13:contoso)
The -IdentifierClaimIs can only be ACCOUNT-NAME, EMAIL, or USER-PRINCIPAL-NAME.
$ap = New-SPTrustedIdentityTokenIssuer -Name “ADFS” -Description “ADFS provider” -Realm “urn:sp13:contoso” -ImportTrustCertificate $adfscert -signInURL “https://adfs.contoso.com/adfs/ls” -UseDefaultConfiguration -IdentifierClaimIs EMAIL
We can add in more claims after the trusted provider is created. Example is below of adding a role claim.
$ap = Get-SPTrustedIdentityTokenIssuer “ADFS” $ap.ClaimTypes.Add(“http://schemas.microsoft.com/ws/2008/06/identity/claims/role”) $map = New-SPClaimTypeMapping “http://schemas.microsoft.com/ws/2008/06/identity/claims/role” -IncomingClaimTypeDisplayName “Role” -SameAsIncoming $ap.AddClaimTypeInformation($map) $ap.Update()
5. Associate the new trusted provider to your web application(s). In central admin, select Application Management, then Manage web applications. Select your web application, then Authentication Providers. For each zone, select Windows Authentication and Trust Identity provider. Both are required for the migration.
Migrate Users and Groups
The migration of users and groups are very similar to the migration scripts with a difference of the groups. The groups will change from Windows claim + SID to ADFS + SID. Other migrations are passing the unqualified name through the SAML token. The claim provider that is provisioned will not show you the SID just like Windows does either.
The PowerShell we will be running is Convert-SPWebApplication.
$wa = get-spwebapplication https://contoso Convert-SPWebApplication -Identity $wa -From CLAIMS-WINDOWS -To CLAIMS-TRUSTED-DEFAULT -TrustedProvider $ap -RetainPermissions
This will need to be run on each web application. After the conversion is done, you can disable the Windows Authentication.
People picker will have two results for all users that have an Email address in Active Directory. The ADFS results is the one we would want to select.
Resources
The Convert-SPWebApplication command cannot convert from Windows claims to SAML in SharePoint Server 2013 – https://support.microsoft.com/en-us/help/3042604/the-convert-spwebapplication-command-cannot-convert-from-windows-claim
Configure SAML-based claims authentication with AD FS in SharePoint 2013 – https://technet.microsoft.com/en-us/library/hh305235.aspx