This is a topic that’s generated a lot of interest over the last couple of months and I’m happy to report that I was recently able to utilize the new Web Application Proxy (WAP) features of Windows Server 2012 R2 to act as a reverse proxy for the SharePoint 2013 hybrid features. Specifically I configured it for use with the 2-way hybrid search features between SharePoint on premises and Office 365. In all likelihood this will be the first level of support Microsoft will offer for using WAP with SharePoint hybrid, and then other hybrid features will likely follow suit afterwards. For now let’s walk through getting this working in your environment.
To begin with, I’m going to assume that you have all of the other hybrid components in place, and really all we are doing at this point is getting the reverse proxy part of the solution configured. That means that you have an on premises SharePoint farm, an Office 365 tenant, and dirsync and SSO configured already. I’m also assuming that you’ve configured a result source with a Remote SharePoint Index and a query rule that uses that result source so you can retrieve search results from either farm. What we’re going to do here is just add the reverse proxy piece to it so you can do it securely (versus having an open endpoint to your on premises farm laying wide open out on the Internet).
Getting WAP is really a multi-part process:
- Get Server 2012 R2 and ADFS installed and configured
- Get Server 2012 R2 and WAP installed and configured
- Create a WAP application
The first thing to note is that you cannot install both AFDS and WAP on the same server, so you will need at add least two servers to your farm, and of course more if you are adding fault tolerance. Ironically I found the most difficult thing in this whole process to be configuring ADFS, which was a surprise given how smoothly it went in previous versions. But new things bring new opportunities, so it’s probably just a matter of getting used to how these things work. So let’s start with ADFS, and I’ll try and call out the things that would have helped me move along more smoothly.
To begin with, you will go to the Add Roles and Features option in Server Manager to get started. Once you select your server, check the box for Active Directory Federation Services. You can complete the wizard to get the service installed, and that part should be completely painless and worry free. Once the installation is complete you should notice a yellow warning icon in Server Manager, and that’s your indication that you have something to do; in this case, that “something” is configuring ADFS. Click on the warning icon to see the status information, and then click on the link to configure the federation service on this server.
Since this is our first server we’ll accept the default option to create the first federation server and click the Next button to continue. On the next page you select an account with AD domain admin permissions and then click Next. The next page of the wizard is where I ended up messing myself up the first time, so hopefully a little explanation here will help you.
The first thing you need to do is select the SSL certificate that you will use for connection to ADFS. One thing worth pointing out right away is that ADFS does not use IIS in Server 2012 R2, so don’t bother looking around for it in the IIS Manager. This also leads to a potential irritating point of confusion that I’ll explain a bit later. So select a certificate (typically a wildcard or SAN certificate) that you will use for your SSL connection to ADFS. If you’re like me, you have a wildcard certificate that you use for these purposes. If you Import it (or choose it from the drop down), it automatically places the CN (i.e. subject name) of the certificate in the Federation Service Name – this is where you need to be careful.
Basically what you should put in the Federation Service Name is the Url you want to use for ADFS requests. So in mine it put “*.vbtoys.com” because that was my certificate’s subject name, and instead I had to put something like “adfs.vbtoys.com”. Don’t forget to add an entry in DNS for the Federation Service Name. Finally, the Federation Service Display Name can be whatever you want it to be, then click Next to continue the wizard.
On the next page you select the service account you are going to use, and then click Next. On the next page of the wizard you’ll have the option of either creating a new Windows database for the service or using an existing SQL Server database. Make your selection and click the Next button. The next page is where you can review your selections or view the PowerShell script it will execute to create the service. Once you’ve taken a look go ahead and click Next to validate all of your selections. Assuming all the pre-requisite checks pass, you can now click the Configure button to begin configuring the service.
One final point on this – EVERY single time I’ve ever run this wizard, it has ALWAYS given me a message about an error setting the SPN for the specified service account. It should be setting a “HOST” SPN for the ADFS service account for the endpoint you defined for the ADFS service. I believe the net of this is that if you are setting up a single server for your ADFS farm, then when you create the ADFS service you make the service name the same as your server name. For example, if your server name is “adfs.foo.com”, it appears that at some point in the installation of features that Windows creates an SPN for “host/adfs.foo.com” and assigns it to the computer “adfs.foo.com”. When you configure ADFS to use the service name "adfs.foo.com" it wants to assign that same SPN of “host/adfs.foo.com” to the ADFS service account. Now, if you are using multiple servers (so you have a load balanced name for your ADFS endpoint), or if you just use some other name besides the name of the computer for the ADFS endpoint, you should not have this problem. If for some reason you get turned sideways, you can always open adsiedit.msc and use the servicePrinicpalName attribute on a user or computer to edit the SPNs directly. In my experience, if you are just using a single server then there really isn’t anything to worry about.
So with that long-winded bit of Kerberos trivia out the way, you should have completed the configuration of your ADFS server. Now the logical thing to do is to test it to make sure it is working. This is the potentially irritating point of confusion I mentioned earlier. If you read http://technet.microsoft.com/en-us/library/dn528854.aspx it provides a couple of Urls that you can try to validate your ADFS installation. What it doesn’t tell you is that if you try and run any of these tests on the ADFS server itself, they will fail. So your big takeaway here is find another server to test this on, and then I recommend just trying to download the federation metadata Xml file, for example https://fs.contoso.com/federationmetadata/2007-06/federationmetadata.xml. The article above explains this in more detail.
Okay, well the good news is that we got through hard part, the rest of this is all downhill from here. For step 2 you need to install WAP on another Windows Server 2012 R2 machine. One quick distinction worth making here is that the ADFS server must be joined to your domain; your WAP server on the other hand should not be. The process is much simpler here – before you get started though, copy over the SSL certificate you used on your ADFS servers to the WAP server; you will use that later when running the WAP wizard. You can now begin by opening up the Server Manager and go into to add roles and features again. Once you’ve selected your server, check the Remote Access role then continue with the wizard. A few steps later it will ask you what Remote Access services you want to install and then check the Web Application Proxy service. You’ll see a pop up with a few other features that it requires and you can just click the Add Features button to continue. After you finish the wizard, like before, you’ll see a warning icon in the Server Manager application. Just like before, click on it then select the option to open the Web Application Proxy wizard.
In the wizard you’ll finally get to enter your Federation Service Name, which is the same as you entered above when you ran the ADFS configuration wizard. You also provide a set of credentials for a local admin on the ADFS server(s) and then click Next in the wizard. On the next page you need to select the certificate that you use for SSL to your ADFS server(s). Unfortunately this step in the wizard does not include a button to import a certificate, so you need to open the Certificates snap-in in MMC and add it to the Local Computer’s Personal certificate store. If you didn’t do this previously, you’ll need to click the Previous button after you add the certificate, then click the Next button again and your certificate should show up in the drop down list. Click the Next button in the wizard one last time, then you can review the PowerShell it is going to run. Click the Configure button to complete the process.
There’s one last gotcha that you might see at this point. You may get an error that says “AD FS proxy could not be configured” and then some further details about failing to establish a trust relationship for the SSL/TLS secure channel. Remember that if you are using domain issued certificates, and the WAP server is not joined to the domain, then it does not automatically trust the root certificate authority (i.e the “root CA”) for your SSL certificate. If that is the case, you need to get a copy of the root CA certificate and add it to the Trusted Root Authority store for your local computer on the WAP server. You can get the root CA certificate in a variety of ways; I just copied it out of the SSL certificate that I used for the ADFS server. Once you add that you can click the Previous button in the wizard then click the Configure button again and have it do its thing. At this point you should be good to go, the wizard completes, and the Remote Access Management Console pops up, with pretty much nothing in it.
As I mentioned before, things get progressively easier as we go. The final step now is to create a new WAP application. This just means we’re going to publish an endpoint for our on premises SharePoint farm, and Office 365 is going to send the hybrid search queries to that endpoint, where they will get passed back to our on premises farm. The genius part of what the WAP folks did is boil all of this down to a single line of PowerShell and then – Kaboom! – you got hybrid.
I’m going to borrow here from some documentation around the WAP feature that will be published soon to describe the PowerShell that you execute (sorry for stealing here UA team):
Add-WebApplicationProxyApplication -ExternalPreauthentication ClientCertificate -ExternalUrl <external URL> -BackendServerUrl <bridging URL> -name <friendly endpoint name> -ExternalCertificateThumbprint <certificate thumbprint> -ClientCertificatePreauthenticationThumbprint <certificate thumbprint> -DisableTranslateUrlInRequestHeaders:$False -DisableTranslateUrlInResponseHeaders:$False
- Where <external Url> is the external address for the web application.
- Where <bridging URL> is the internal or bridging URL you defined for the web application in your on-premises SharePoint Server 2013 farm.
- Where <friendly endpoint name> is a name you choose to identify the endpoint in Web Application Proxy.
- Where <certificate thumbprint> is the certificate thumbprint, as a string, of the certificate to use for the address specified by the ExternalUrl parameter. This value should be entered twice, once for the ExternalCertificateThumbprint parameter and again for the ClientCertificatePreauthenticationThumbprint parameter.
I will say that I found a couple of these parameters a little confusing myself when I first looked at them so let me provide an example:
- I have a web application with a default zone of https://www.sphybridlab.com
- I use a wildcard certificate for that web application, and that certificate has a thumbprint of 6898d6e24a441e7b73f18ecc9b6a72b742cf4ee0
- I uploaded that same wildcard certificate to a Secure Store Application in Office 365 to use for client authentication on my hybrid queries
So the PowerShell I use to create my WAP application is this:
Add-WebApplicationProxyApplication -ExternalPreauthentication ClientCertificate -ExternalUrl "https://www.sphybridlab.com" -BackendServerUrl "https://www.sphybridlab.com" -name "SphybridLab.Com Hybrid Search" -ExternalCertificateThumbprint "6898d6e24a441e7b73f18ecc9b6a72b742cf4ee0" -ClientCertificatePreauthenticationThumbprint "6898d6e24a441e7b73f18ecc9b6a72b742cf4ee0" -DisableTranslateUrlInRequestHeaders:$False -DisableTranslateUrlInResponseHeaders:$False
That’s it – we’re golden after this. Here are a few more details about the implementation to clarify things:
- I have added that same exact wildcard certificate to a Secure Store Service application in my Office 365 tenant; I call that application “HybridCert”.
- In Office 365 I have a result source that points to my on premises SharePoint farm at https://www.sphybridlab.com. It is also configured to use the SSO Id of “HybridCert”.
- I followed the design principles for hybrid search that I previously described in my blog here: http://blogs.technet.com/b/speschka/archive/2013/10/11/architecture-design-recommendation-for-sharepoint-2013-hybrid-search-features.aspx. The net of it is that I configured the WAP server to use an external IP address like 201.80.100.80 (I just made that address up, it's not real). In my external DNS on GoDaddy, I configured www.sphybridlab.com to point to 201.80.100.80.
When Office 365 attempts to issue a hybrid query to https://www.sphybridlab.com, it finds the IP address in GoDaddy to be 201.80.100.80. It submits the query and includes the certificate from the “HybridCert” SSS application as certificate authentication for the request. WAP is listening on that IP address and requires certificate authentication. It gets the request, it finds a certificate presented for authentication and that certificate has the thumbprint that we configured it to look for in our WAP application. It’s all goodness at that point so it passes the request back to https://www.sphybridlab.com, and away we go. The final results then look like this:
As I mentioned above, look for expanding coverage and support on WAP and SharePoint hybrid features in the coming months.