ADFS v2 is our Identity Provider, also known as an IP-STS (Security Token Service).
We need to configure ADFS with information about our Relying Party, or RP. In this case, SharePoint is our RP – it’s depending on ADFS to do the authentication and provide the claims.
From the SharePoint perspective, we have to configure it to trust the IP-STS that is sending us claims, and then we have to set up a web application and site that’s going to consume those claims.
We’ll begin by creating the relying party in ADFS. Note that it really doesn’t matter which order you do these things in, but as a matter of practice I generally configure ADFS first. So go to the server on which ADFS is installed and open the AD FS 2.0 Management application. Expand the Trust Relationships node and click on the Relying Party Trusts node.
Switch over to the SharePoint server and we will begin configuring it. Before we start configuring SharePoint I recommend that you create a new web application now. Create it to use claims authentication, but select Integrated Windows authentication – NTLM for the Authentication Settings. Make sure you configure the web application to use Port 443 and you select the radio button that says Use Secure Sockets Layer (SSL). Once you’ve created your web application remember to go into the IIS Manager and edit the bindings for the new virtual server so you can assign the appropriate SSL certificate. These steps are outside the scope of this posting, but are well-documented in many places around the Internet. To recap, for our scenario then there is a web application I’ve created that uses Port 443 and SSL and the Url for that web application is https://seo14.
The first thing I’m going to do on the SharePoint side is to add the token signing certificate I copied from the ADFS server. Before I do that though, I need to look at the certificate. The token signing certificate may have one or more parent certificates in its chain. If it does, I need to add every certificate in that chain to SharePoint’s list of trusted root authorities. To figure that out, I’ll find the token signing certificate I copied over from ADFS and double-click on it; that brings up the certificate properties window. If you click on the Certification Path tab you can see if there are any other certificates in the chain. In my scenario my token signing certificate DOES have a parent – it is the root certificate authority certificate
What I need to do now, is for each certificate in the chain above my token signing certificate, I need to save a copy of each one locally. I can do that by clicking on the certificate, which enables the View Certificate button in the dialog. If I click on that it will open a separate properties dialog for that certificate. I can then follow the same process I described earlier to save a copy of the certificate to disk: click on the Details tab, click on the Copy to File… button, then save the certificate locally as a .CER file. In my case I did this and saved it to C:\adfsParent.cer. So now on my SharePoint server I have two certificates:
· C:\adfs.cer, which is the token signing certificate I copied from my ADFS server
· C:\adfsParent.cer, which is the parent certificate to my token signing certificate
Now that I have both of these certificates, I need to add them to my list of trusted root authorities. I’m going to do that in PowerShell with this script:
$root = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\adfsParent.cer")
New-SPTrustedRootAuthority -Name "Token Signing Cert Parent" -Certificate $root
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\adfs.cer ")
New-SPTrustedRootAuthority -Name "Token Signing Cert" -Certificate $cert
After I execute those commands in PowerShell the output looks something like this:
Next I’m going to create the claim mappings that SharePoint is going to use. If you recall from earlier in this article I said that I was going to use email address and role claims in SharePoint. Here’s the PowerShell that I’ll use to create those mappings:
$map = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
$map2 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" -SameAsIncoming
Next I’m going to create a variable for the realm that I want SharePoint to use. For this scenario I said I was going to use the realm urn:seo:sharepoint. Here’s the PowerShell to create my realm variable:
$realm = "urn:seo:sharepoint"
Now I’m ready to create my SPTrustedIdentityTokenIssuer. This is where I tie together all of the configuration information so SharePoint knows how to connect and work with the IP-STS. I’ll show the PowerShell here and then explain the important parts:
$ap = New-SPTrustedIdentityTokenIssuer -Name "SAML Provider" -Description "SharePoint secured by SAML" -realm $realm -ImportTrustCertificate $cert -ClaimsMappings $map,$map2 -SignInUrl "https://congen1.contoso.local/adfs/ls" -IdentifierClaim "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
The “Name” attribute is what is going to show up in your web application when you configure what authentication provider it should use. The “realm” attribute is where we plug in the realm that we want SharePoint to use with this trusted identity token issuer. The “ImportTrustCertificate” attribute is where we pass it the token signing certificate that we copied from the ADFS server. The “ClaimsMappings” attribute is where we tell it what the claims are that we want this trusted identity token issuer to use. The “SignInUrl” is the Url that users should be redirected to in order to authenticate with the IP-STS. In this case we want users to authenticate with the ADFS server using Windows integrated security, so we send them to the /adfs/ls subdirectory. Finally, the “IdentifierClaim” attribute tells SharePoint which of the claims is going to be thee claim that is used to identify users. In this case we’re saying email address is how you identify a person.
Once that last PowerShell command has executed, we have an SPTrustedIdentityTokenIssuer that can be used with our SharePoint web application. So now we’ll open up the browser and navigate to Central Administration. Click on the Manage Web Applications link, then click on the web application in the list that’s going to use ADFS to authenticate, then click the Authentication Providers button in the ribbon. Click the link in the dialog that corresponds to the zone in which you are going to use ADFS to authenticate. Scroll down to the Authentication Types section. You can now de-select NTLM, and you should see a new provider called “SAML Provider” in the list of trusted providers
Check the box next to it and click the Save button to save your changes. Now you can go and create a site collection for the web application. Again, describing that process step-by-step is not in scope for this posting, but there is one important thing to remember when you do this. When you add the Site Collection Administrator, remember to enter the name in the format of your identity claim. For example, in this scenario the identity claim is email address. So when I added the Site Collection Administrator the name I used was administrator@contoso.local, because that’s the email address of the person I want to be the Site Collection Administrator.
Now I’m ready to try and go to my new site collection. I open up the browser and type in https://seo14 and hit enter. The first thing that happens is my redirected to the SignInUrl for the SPTrustedIdentityTokenIssuer that’s associated with my web application. If you recall from the PowerShell that was used to create the SPTrustedIdentityTokenIssuer, that Url is https://congen1.contoso.local/adfs/ls. So here’s what I see after typing the Url to my SharePoint site in the browser:
You can see the Url in the browser window now points to my ADFS server and you can see the graphic in the background behind the login dialog is for the ADFS server. You may also notice that I’m signing in using my Windows credentials, i.e. domain\user. Remember I’m able to do this because I’m authenticating on the ADFS server, not on SharePoint. SharePoint is configured to use email address as my identity, but what is going to happen is that I’ll authenticate over on ADFS, and then it will use the claim rule we created to pull out my email address and groups and put them into claims that will be sent back to SharePoint. So then after I’ve authenticated I’m redirected back to SharePoint at https://seo14/_trust/, as I configured in the relying party I set up in ADFS. At that point SharePoint will complete the authentication process on its side as it takes the claims it got in the SAML token and converts it into an SPUser. Then I finally arrive at the home page for the site:
No comments:
Post a Comment