The Convert-SPWebApplication command cannot convert from Windows claims to SAML in SharePoint Server 2013

Symptoms

Consider the following scenario:

• You use Windows-claims authentication (through Windows Challenge/Response [NTLM] or Kerberos) in a Microsoft SharePoint Server 2013 web application.

• You decide to switch to Trusted Provider claims by using a Secure Application Markup Language (SAML)-based provider such as Active Directory Federation Services (AD FS).

• You review the steps in the Migration of Windows claims authentication to SAML-based claims authentication in SharePoint Server 2013 topic on the Microsoft Developer Network (MSDN) website.

• You run the following command:
  
  

  Convert-SPWebApplication -id $wa -To CLAIMS-TRUSTED-DEFAULT -From CLAIMS-WINDOWS -TrustedProvider $tp -SourceSkipList $csv -RetainPermissions

In this scenario, you receive the following error message:

Cause

This problem occurs because the Trusted Identity Token Issuer was not created by using the default configuration. The default configuration must be used for the Convert-SPWebApplication command to work correctly.

The Convert-SPWebApplication command requires a specific configuration for the Trusted Provider for it to be compatible with conversion from Windows claims to SAML or vice versa.

Specifically, the Trusted Identity Token Issuer must be created by using the UseDefaultConfiguration and IdentifierClaimIs parameters.

You can check whether your Trusted Identity Token Issuer was created by using the UseDefaultConfiguration parameter by running the following Windows PowerShell scripts.

Note: These scripts assume that you have only one Trusted Identity Provider created within the current farm.

$tp = Get-SPTrustedIdentityTokenIssuer
$tp.claimtypes 

The claim types that this script should output are as follows:

• http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

• http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid

• http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid

• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

#Get the Identity claim:
$tp = Get-SPTrustedIdentityTokenIssuer
$tp.IdentityClaimTypeInformation 

The Identity Claim must be one of the following:

• WindowAccountName

• EmailAddress

• UPN
  

Example output for $tp.IdentityClaimTypeInformation: 
DisplayName : Email
InputClaimType : http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
MappedClaimType : http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress#IsIdentityClaim : True


There should be a custom claim provider with the same name as the token issuer, and it should be of type SPTrustedBackedByActiveDirectoryClaimProvider.
Run this to see whether the claim provider is present and compatible:

            
$tp = Get-SPTrustedIdentityTokenIssuer
$name = $tp.name
$cp = Get-SPClaimProvider $name
if($cp.typename -match "SPTrustedBackedByActiveDirectoryClaimProvider")
{write-host "Claim provider is present and has TypeName of " $cp.typename " it should be valid"}
else{write-host "Claim provider is not present. Trusted Identity Token Issuer" $tp.name " is not compatible with convert-spwebapplication"}

Resolution

To resolve this problem, delete and then re-create the Trusted Identity Token Issuer. To do this, follow these steps:

1. Run the following script:
   
   

   $tp = Get-SPTrustedIdentityTokenIssuer
   $tp | fl
   $tp.name
   $tp.IdentityClaimTypeInformation

   
   Make a copy of the output of this script for future reference. In particular, we need the value for the Name property so that the new Token Issuer can be created by using the same name, and we need the identity claim so that the new claim provider can be created by using the same identity claim. As long as the same name is used for the token issuer and the same claim is used as the identity claim, all users will maintain their permissions within the web application after the token issuer is re-created.
   
   

2. Remove the current Trusted Identity Provider from Authentication Providers for any web application that is currently using it.

3. Delete the token issuer by running the following command:
   
   

   Remove-SPTrustedIdentityTokenIssuer -Identity "TheNameOfYourTokenIssuer"

   
   

4. Re-create the token issuer. To do this, follow the steps in the Implement SAML-based authentication in SharePoint Server 2013 topic on the Microsoft TechNet website for more information.
   
   Important When you run the New-SPTrustedIdentityTokenIssuer command, you must use the UseDefaultConfiguration and IdentifierClaimIs parameters. The UseDefaultConfiguration parameter is just a switch. Possible values for the IdentifierClaimIs parameter are as follows:

   • ACCOUNT-NAME

   • EMAIL

   • USER-PRINCIPAL-NAME

   
   
   Example script:
   
   

   $ap = New-SPTrustedIdentityTokenIssuer 
   -Name $tokenIdentityProviderName 
   -Description $TrustedIdentityTokenIssuerDescription 
   -realm $siteRealm 
   -ImportTrustCertificate $adfsCert
   -SignInUrl $signInUrl 
   -UseDefaultConfiguration 
   -IdentifierClaimIs EMAIL 
   -RegisteredIssuerName $siteRealm

5. In Central Administration, add your new Trusted Identity Token Issuer back to the authentication providers for the web application you are trying to convert. The web application must have both Windows authentication and the target Trusted Identity Provider selected.

More Information

Additional tips for successful conversion:

If the EMAIL value is used for the Identifier claim (that is, for the IdentifierClaimIs parameter), only those users whose email addresses are populated in Active Directory will be converted.

Any user accounts that are listed in the .csv file that is defined in the SourceSkipList parameter will not be converted to SAML. For conversion from Windows claims to SAML, the user account names can be listed with or without the claims notation. For example, either "contoso\user1" or "i:0#.w|contoso\user1" is acceptable. You should add to that .csv file any user accounts that you do not want converted. These should include service accounts and administrator accounts.