I'm not sure if this is really a beginners article but what the heck, we're on a roll, having fun and I'm writing so I get to say what it is and isn't (at least to a certain extent anyway).
If you've been following along and have read through the first 4 articles in this series you know we have installed and configured AD FS 3.0 in our S7Gear domain. Now, users should be able to login to SharePoint in S7Gear domain using SAML claims.
If you haven't read the series from start to finish... now is your chance:
To refresh your memory the claims authentication process is 7 steps as shown below.
- The end user hits the SharePoint site generating an HTTP (GET) request.
- SharePoint redirects the user to the Identity Provider to get a security token.
- The end user is prompted for credentials by the Identity Provider.
- The Identity Provider validates the provided credentials with the authentication provider (in this case AD DS) and if successful provides the client a security token.
- The Identity Provider sends the end user a SAML security token.
- The end user submits a new request to SharePoint with the SAML token.
- The SharePoint STS generates the SharePoint security token, the FedAuth cookie and the requested SharePoint site.
This scenario works great for my internal (S7Gear) domain users but what if I have an organization I want to partner with on a project? How easy would it be to allow those users to log into my SharePoint farm using their own (current organizations) credentials?
It actually turned out to be a lot easier than I thought. You also won't find it difficult if you know how to set up AD FS to authenticate SharePoint users (if not, see my first 4 blogs on this subject). The goal in this article will be to take our existing SharePoint farm in the S7Gear domain and make it accessible to users in the S7Lab domain. To do this I have had to make some networking changes on my VMWare setup which I will explain briefly.
I used VMWare Workstation 10 for the labs. For this series of blog posts I started with the S7Gear domain shown below (this is a very simplistic view, but you get the idea).
For the purposes of this article we'll add a second domain named S7Lab.com on the network 192.168.126.0/24 (it isn't a real test if they're on the same network, now, is it?). In order for the two networks to "talk" to each other I had to add a second NIC to each server in both forests. Once the second NIC was added I configured them with static IP addresses, one NIC on each network (192.168.239.x and 192.168.126.x). To work around having to set up DNS in each domain I've made HOST file entries for portal.s7gear.com and myportal.s7gear.com on the ADFS server in the S7Lab domain (9 VMs is kind of pushing it so I used the AD FS server in S7Lab.com to access the S7Gear SharePoint site).
For this lab to work I have created and configured an AD FS server in the S7Lab domain to facilitate communications between forests. More on that in a bit…
When I finished the network configuration it looks more like the following. As you can see each server has two network connections and I have verified that I can ping servers and addresses across the connections.
NOTE: I could have set up a RRAS (Routing and Remote Access) server but there have been some changes in that with 2012 R2 and I didn't feel like digging into it just yet.
Now that we've gotten this all out of the way we can get to the fun stuff which, as I mentioned before, was really far easier than I thought it was.
The authentication concept working across multiple forests or domains is essentially the same with one or two additional steps. Our S7 Lab user is going to access the S7Gear SharePoint site from his, or her, desktop in the S7Lab domain and select which trusted identity provider they want to authenticate with. They will be prompted for credentials and if they have access to the SharePoint site being requested they will authorized and allowed access.
Before our users in the S7Lab domain can do that we have to establish a line of communications between the two forests. We'll do that by taking the following steps on the AD FS server in the S7Gear domain (where my SharePoint farm resides):
- We will add the *.S7Lab.com self-signed certificate to the trusted root store on the AD FS server in the S7Gear domain. If you fail to do this you will not be able to update, or validate, the claim provider's federation metadata URL.
- We will add a claim provider trust (similar to a relying party trust).
- We will import information about our relying claim provider.
- We will create a rule for each claim being presented by the claim provider to allow them to pass to SharePoint.
- We will add pass through claims rules to our existing SharePoint relying party trust.
Once we have completed those actions on the S7Gear AD FS server we will take the following actions on the S7Lab AD FS server.
- We will add a relying party trust.
- We will import information about the claims provider.
- We will add rules to send LDAP attributes as claims.
Before any of that can happen we need to verify that AD FS is configured and accessible in both forests. I'm going to step through it once because some of the steps here are also very good for troubleshooting problems when you have them later.
To verify that the AD FS service is operational we'll open the federationmetadata.xml on the S7Lab AD FS server which in this case is the "Identity Provider". The default location of the file on the server is https://sts.s7lab.com/federationmetadata/2007-06/federationmetadata.xml.
NOTE: You will notice that I didn't use the server name in the AD FS service URL, I'm not a big fan of server names in URLs so I created a DNS "A" record pointing sts.s7lab.com at the IP address of the AD FS server.
Copying and pasting that URL into the address bar of a browser on the S7Lab AD FS server should take you to the federation metadata XML page with no errors. If you get an untrusted certificate warning error you need to make sure that you have added the token-signing and decrypting certificate(s) to the trusted root certificate store of the server. Certificate errors may cause authentication attempts to fail.
Repeat this process on the on the S7Gear AD FS server using sts.s7gear.com as the root of that URL. Once this is complete we will start the configuration process.
Import the S7Lab.com SSL certificate into the Trusted Root Certificate store
I'm not going to walk through all the steps to put the SSL certificate in the trusted root certificate store. If you need guidance on how to do this you can see the instructions HERE.
Create the Claim Provider Trust
We will start the configuration on the S7Gear AD FS server, opening the AD FS Management console and in the left hand window expanding the Trust Relationships heading and selecting "Claims Provider Trust".
Right click and select "Add Claims Provider Trust" to start the Add Claims Provider Trust wizard. We'll click through the welcome panel to the Select Data Source panel and on that panel we will select the "Import data about the claims provider published online or on a local network". In the text field we will past the URL of the federation metadata XML file on the S7Lab AD FS server as show below. This how the Claim Provider Trust will import data about the S7Lab AD FS configuration.
Click "Next" to continue and if everything is able to communicate with each other the wizard should advance to the next panel showing you the root URL of your federation metadata XML file as shown in the following screenshot. I'm going to change that display name to S7 Lab AD FS Login and then click "Next" to continue.
At this point we should get the Ready to Add Trust panel, I would suggest that you take a look through the settings in each of the tabs on this panel until you are familiar with the process. It's good to know what it looks like by default when you're desperately searching for the solution to a problem you're having.
We'll click "next" and "finish" to complete the wizard and open the "Edit Claims Rules" dialog box. Here we are going to add our rules to pass our incoming claims to the S7Gear domain AD FS instance.
Now we are going to create our pass through claims rules. If you think back to when we created the claims rules for our relying party trust back in Part IV, we used the "Send LDAP Attributes as Claims" claim rule template. This time we are going to use the "Pass through or filter and incoming claim", this rule will tell the AD FS service to pass incoming claims that match the rule to SharePoint.
Remember, we must create a rule for EACH incoming claim we expect to accept. For this lab we will create rules to pass the UPN and Common Name claims.
On the "Choose Claim Rule" panel we will give our rule a name and then define the incoming claim type.
I want to stop for a second and point a couple of things out here before we go on. Please note that we have several options regarding how we want to handle, or filter incoming claims. We can pass through all claims, pass through only claims with a specific value, pass through claims that match a specific email suffix and pass through claims that start with a specific value. For this lab I am passing through all claims although that might not be advisable in a production configuration.
Now that our two claims rules have been created we will close the dialog box and continue.
Configure the S7Gear Relying Party Trust
Now that we have rules in place defining how the S7Gear AD FS server will handle incoming claims we will make some minor configuration changes to our existing relying party trusts for our SharePoint farm. Not only do we have to tell AD FS that there is an organization we trust and that they are going to be sending us some claims but we have to tell SharePoint how to handle them as well.
We're going to do that by adding an additional rules for each incoming claim to our relying party trust on the S7Gear AD FS server. We'll select the relying party trust in the AD FS Management console and then click the "Edit Claims Rules" link to add our new rules. On the "Issuance Transform Rules" tab click the "Add Rule" button to open the Add Transform Claim Rule wizard.
We are going to use the Pass Through or Filter an Incoming Claim rule template and create a rule to match each rule created for our Claims Provider Trust.
Now, just like with the Claims Provider Trust rules we will create a rule to pass through the UPN claim and common name claims.
Once those are done the Edit Claim Rules for "Portal" (my SharePoint Relying Party Trust) will look like the following:
Configuring the S7Lab AD FS Server
Now we'll move on to the last part of the process and configure the AD FS instance on S7Lab to tell S7Gear what claims we are sending. We will do that by creating a relying party trust in AD FS on S7Lab but we are going to do it slightly differently than we have previously.
We'll start the process by opening the AD FS Management Console and expanding the Relying Party Trusts node. Right click on Relying Party Trusts and select the Add relying party trust wizard, clicking through the Welcome panel to arrive at the "Select Data Source" panel (look familiar?).
This time we are going to enter the URL of the S7Gear federation metadata address, https://sts.s7gear.com/federationmetadata/2007-06/federationmetadata.xml.
We'll click "Next" and then give our new Relying Party Trust a name before skipping the Configure Multi-factor Authentication panel and taking the default setting on the Choose Issuance Authorization Rules panel. At this point we can click finish to complete adding the trust.
At this point all of our configuration steps are complete, we should be able to open Internet Explorer on the S7Lab AD FS server and access the S7Gear SharePoint Farm. Let's see how it works. We'll enter the URL in our browser address bar and get the default sign in page.
I'll click the drop down menu and select the SAML for SharePoint trusted identity provider.
Now that I have selected the trusted identity provider I am prompted for authentication, make sure you look at the URL displayed in the login prompt.
I'll enter my administrator account credentials as shown in the following screenshot and hit enter to continue.
If you watch the address bar closely after you click the Ok button you'll see it hit the S7Lab AD FS service first.
If that connection is successful and tokens are created and passed you should see the S7Gear AD FS service come up in the address bar first.
Next we'll see AD FS being queried for the Portal realm.
If SharePoint authorizes my user the next thing I should see is the S7 Gear Portal home page.
If you look in the upper right hand corner you'll see that you are logged in as firstname.lastname@example.org.
And that is all there is to it, I now have users in two forests that can log into the S7Gear SharePoint farm and do their thing.
This post concludes this series of Beginners type articles. I will be posting more AD FS related content over the next few weeks as I dig deeper into the stack.
I hope everyone has found these articles informative and helpful. As always please leave your comments in the comments section and THANKS for reading…
Want to read the full series from start to finish?