Well, we’ve installed and configured AD FS 3.0 and we have created the first relying party trust for our SharePoint 2013 farm. All that remains now is to complete the configuration of our new Trusted Identity Token Provider and configure SharePoint to use it, which we will be doing in this article.
Before we begin: want to read the full series from start to finish?
To finish the configuration of our new Trusted Identity Provider, we need to complete 4 steps. When these steps are completed, we will be able to log into our test SharePoint farm using claims-based authentication.
In this article we will perform the following tasks:
- We will add the *.s7gears.com SSL certificate that we exported in my last post to the Trusted Root Certification Authorities certificate store on all the servers in the farm.
- We will add the certificate to the SharePoint Trusted Root Store using PowerShell.
- We will create the Trusted Identity Provider within SharePoint using PowerShell.
- We will configure our SharePoint web application to accept our Trusted Identity Provider as its authentication source.
- We will configure the trusted Identity Provider for multiple URLs.
Along the way I will try and add some of the lessons I have learned in the field and the lab that you may find helpful.
Import the SSL Certificate
Please remember the reason for this step is that I am doing this in a test/development environment and do not have access to certificates issued by a commercial CA (Digicert, Verisign, etc). I have created self-signed SSL certificates for use in this test environment and to avoid certificate errors am deploying these certificates to the Trusted Root Authorities store. Could I PowerShell this? Yes, I am sure I could figure it out if I had to :)
I have saved the exported .cer file on a network share that is available to all the servers in my SharePoint farm. I’m going to access the file share through Windows Explorer and open the .cer file from there and click the “Details” tab. Before I do that I want you to take a look at the following screenshot, as you can see in the Certificate Information section at the top there is a red “X” and a message indicating that the certificate is not trusted. We are about to address that error message in the next step.
To start the process we will click the “Install Certificate” button, which starts the Certificate Import Wizard, then select “Local Machine” as the Store Location.
On the next panel of the wizard we will manually select what certificate store we want to use for this certificate import. First we will select the radio button for “Place all certificates in the following store” and then click the “Browse” button to open the Select Certificate Store dialog. In that dialog, we’ll select the certificate store we want to use for this import and then click Next to continue.
On the Completing the Certificate Import Wizard click the “Finish” button to complete the wizard. If the import has been successful you will see a popup message stating that the import succeeded. As you can see in the following screenshot, however, there is still an error message in the Certificate Information section.
If you close and reopen the certificate you will see that the error message is now gone.
Configure the SharePoint Trusted Root Authority
You’ve seen the word “trust” mentioned throughout this series of blog posts. Remember that the whole premise of claims-based authentication is the underlying trusts that have to be established for it to work. If any one part of the trust is not working then authentication will fail.
In this section we will add our SSL certificate to the SharePoint Trusted Root Authorities using PowerShell.
- First we are going to assign a variable to the identity of the certificate we want to import. This certificate must be in a .cer format and can be stored locally or on the network. In our case the .cer file is stored on the network.
$cert = New-Object System.Security.Cryptography.x509Certificates.x509Certificate2 ("\\adfs01\sp2013\adfscert.cer")
- Next we will create the SharePoint Trusted Root Authority with the identified certificate.
New-SPTrustedRootAuthority -Name "Token Signing Cert" -Certificate $cert
Once the PowerShell command has completed you can run Get-SPTrustedRootAuthority to see a list of the available Trusted Root Authorities. By default you will see an authority named “local” and any others you have created including the “Token Signing Cert” we just created, that screen should look something like the following:
Create the SharePoint Trusted Identity Token Issuer
Now that we have established the certificate trusts the next step is to create the SharePoint Trusted Identity Token Issuer. This involves creating claim type mappings, assigning a realm, and identifying the signin URL to be used.
There are a number of different incoming claim types, plus you can create custom claim types. For this exercise, we are using the CommonName and UPN claim types.
We will create our two claim type mappings with the following lines of PowerShell (all on one line please).
The first line of PowerShell will create the UPN claim mapping type.
$upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType
-IncomingClaimTypeDisplayName "UPN" -SameAsIncoming
The second line of PowerShell will create the CommonName claim mapping type.
$cnNameMap = New-SPClaimTypeMapping -IncomingClaimType
-IncomingClaimTypeDisplayName "Display Name" -SameAsIncoming
Now that we have created the Claim Type Mappings we will configure the trusted identity token issuer to work with the “realm” we created when we created the relying party trust. I know you don’t remember doing that because we didn’t call it a realm at the time.
The realm is the name of the relying party trust identifier we specified when we created our relying party trust. To refresh your memories, that identifier is the Uniform Resource Name (URN) we specified; urn:portal:sp2013.
VERY IMPORTANT: the relying party trust identifier MUST be entered EXACTLY as it is displayed in the AD FS Manager. That means the identifier is CASE SENSITIVE, if the two do not match SharePoint and the trusted identity provider will NOT communicate.
To configure our SharePoint farm to talk to the trusted identity token issuer we proceed by configuring the realm in PowerShell. To do that we start by assigning the realm to a variable, that variable being the Relying Party Trust Provider Identifier we were just talking about.
$realm = "urn:portal:sp2013"
Next we have to tell SharePoint what URL will be responding to authentication requests. The value for this URL is the federation service name that we identified when we ran the AD FS Services Configuration Wizard.
$signInURL = https://sts.s7gear.com/adfs/ls
Now we are ready to complete the configuration of the trusted identity token issuer. To do this we will run the following script.
$ap = New-SPTrustedIdentityTokenIssuer
-Name "SAML Provider for SharePoint" -description “SAML secured SharePoint"
-ClaimsMappings $upnClaimMap, $cnNameMap
-SignInURL $signInURL -IdentifierClaim $upnClaimMap.InputClaimType
A few explanations about this section of script:
- The "Name" value is what you will see in your SharePoint web application as the Trusted Identity Token Issuer.
- The realm is the relying party trust identifier we want to use with this particular provider. Note that each web application or host named site collection you create will have its own realm.
- The "ImportTrustCertificate" parameter is where the token signing certificate we copied off of the AD FS server is passed to the application.
- The "SignInURL" is the URL end users should be redirected to in order to authenticate to the IP-STS.
- The "IdentifierClaim" parameter tells SharePoint which of the claims being submitted by the user is the one that will be used for identification of end users.
So the PowerShell script to complete the configuration of the trusted identity token issuer will look like the following. For your environment you will need to replace the values for the path to the certificate you are going to use.
$cert = New-Object System.Security.Cryptography.x509Certificates.x509Certificate2 ("\\adfs01\sp2013\adfscert.cer")
New-SPTrustedRootAuthority –Name "Token Signing Cert" –Certificate $cert
$upnClaimMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" -IncomingClaimTypeDisplayName "UPN" –SameAsIncoming
$cnNameMap = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/claims/CommonName" -IncomingClaimTypeDisplayName "Display Name" -SameAsIncoming
$realm = “urn:portal:sp2013”
$signInURL = https://sts.s7gear.com/adfs/ls
$ap = New-SPTrustedIdentityTokenIssuer –Name “SAML Provider for SharePoint” –description “SAML secured SharePoint” –realm $realm -ImportTrustCertificate $cert –ClaimsMappings $upnClaimMap, $cnNameMap –SignInURL $signInURL -IdentifierClaim $upnClaimMap.InputClaimType
Now that we have the trusted identity token issuer created, we will repeat the process (although I’m not going to show it again) to create a relying party trust for the MySites web application.
Once the relying party trust has been created we will need to add the realm for that trust to the SharePoint Trusted Identity Token Issuer. To do that we go back to PowerShell!
First we’ll set the variable identifying the specific trusted identity token issuer we are going to use.
$ap = Get-SPTrustedIdentityTokenIssuer "SAML for SharePoint"
Next we set the variable for the endpoint URL.
$uri = https://myportal.s7gear.com
Next we set the variable specifying the identity of the relying party trust we are connecting to. Remember, this entry is case sensitive.
$id = "urn:myportal:sp2013"
Finally we tell the authentication provider to add the variables defining the new realms.
NOTE: when you areauthenticating against ADFS every time you add a web application, OR a host named site collection to the farm, you will have to create an associated relying party trust for that new object.
Now when you run the Get-SPTrustedIdentityTokenIssuer cmdlet you should see something similar to the following screen.
As you can see, the command outputs the configuration information for the trusted identity token issuer including:
- Provider URI: these are unique identifiers used to identify configuration objects in this case the claim type.
- Default provider realm: this was the first of the two realms we created.
- Provider realms: these are any additional realms you may have configured for your environment. REMEMBER: you MUST have a realm and an associated relying party trust for every web application or host named site collection in your farm.
- ClaimTypes: these are the claims types this trusted identity provider supports.
- ClaimTypeInformation: the attributes the claim types are mapped to.
- Thumbprint: this is the certificate thumbprint of the signing certificate. This can be a good place to start if you think you are having certificate issues.
- Name: the name of the trusted identity provider.
- DisplayName: This is what you will see in SharePoint when you configure a web application to use a trusted identity provider.
That’s a lot of work so far, and we still haven’t configured SharePoint to use our trusted identity provider. We’ll take care of that and then see if all of this work has been worth the effort!
Configuring SharePoint to use the SAML for SharePoint Trusted Identity Provider
At long last we have arrived at our SharePoint destination and are finally ready to see if our SharePoint farm will talk to our AD FS server and authenticate our users. We’ll start that process by navigating through Central Administration > Application Management > Manage web applications. Once there we’ll select the portal web application and open the “Authentication Providers” control as shown below.
In the “Edit Authentication” dialog box that pops up you will see a section for “Claims Authentication Types.” Inside that section, we will uncheck the “Integrated Windows authentication” checkbox and check both the Trusted Identity Provider and SAML for SharePoint checkboxes. Click save to continue.
Just a couple of more things to do before we can access our SharePoint site!
First we have to change the site collection administrator’s accounts to claims-based accounts that will be accepted by the trusted identity provider.
Before we get to that let’s look at something else first: the default value of the user-principal-name (UPN). To do this we’ll open the Forefront Identity Manager console (miisclient.exe) on my App server and look at the properties of the profiles being imported by my user profile service.
As you can see in this screenshot the value of the userPrincipalName attribute is my email address. This is important because this impacts how we add users to SharePoint. In the past we have searched for users in the people picker using a domain\username format. Because I have identified the userPrincipalName (UPN) attribute as my identity claim we will now use firstname.lastname@example.org to add users to SharePoint (users will still login using the domain\username format).
Before we change site collection administrators, here’s an important word about claims and the people picker. By default the people picker will validate ANY value that you type into it and search for. Kirk Evans has a great blog post on how to address this over at MSDN that is far beyond anything I can even attempt to do: Fixing People Picker for SAML Claims Users Using LDAP
For now we’ll focus on making sure that anyone we try and add to SharePoint actually exists and we get their email correct.
Now let’s add a new site collection administrator to my portal web application. To do this we’ll navigate to Central Administration > Application Management > Site Collections > Change site collection administrators and add a new site collection administrator. The first thing you’ll notice is that the people picker looks a little different and contains 3 additional fields on the left hand side, including not only our trusted identity provider but the individual claim as well.
I am going to add the S7Gear administrator account as a site collection administrator so I’ll type in the email address email@example.com and click search. As you can see in the following screenshot my search returned two results: one is my organizational display name (Common Name anyone?) and the other is my UPN, which displays as my email address.
We can’t give permissions using the display name so we will select the SAML for SharePoint group on the left, and then in the display field the firstname.lastname@example.org account.
We click OK to finish adding the administrator account and, as you can see, the primary site collection administrator of the portal site collection is now email@example.com.
Wow! Finally we are ready to test our web application and see if we can authenticate successfully and access our SharePoint site. We’ll start by opening Internet Explorer and going to https://portal.s7gear.com, where we are immediately redirected to the default SharePoint signin page. As you can see on this page there is a drop down menu that lists the available authentication providers. In this case Windows Authentication and our trusted identity provider “SAML for SharePoint” both appear
Selecting the SAML for SharePoint authentication provider brings up the Windows Security login box. It is VERY IMPORTANT when you enter your credentials here that you enter them in the traditional domain\username format.
If you watch the address bar you will see that after submitting your credentials you are redirected back to the trusted identity provider to request the SAML token. The trusted identity token issuer looks up the identifier (the URN) of the web application the request is coming from and then passes the identifier to the external token issuer in the wtrealm parameter seen in the screenshot below.
The external token issuer returns the SAML token and the SharePoint trusted identity token issuer verifies the signature, applies any mapping rules, and drops the SAML token into the SharePoint token cache. SharePoint checks if a user has a valid SAML token, then uses the claims in that token to perform any authorization validation.
Now if we have successfully been authenticated by AD FS and authorized by SharePoint we should see the portal home page.
I hope you found this useful. As always, if you have any questions please leave them in the comments section.
In my next post I’ll give you some tips on troubleshooting AD FS as well as some insight into some of the issues I have run into and the solutions I found.
Thanks for reading….
Part 2: Installing and Configuring AD FS 3.0