SharePoint 2013 Apps and Host Headers

Until recently, I was blissfully unaware of an issue that exists when deploying SharePoint 2013 apps in a likely production environment.  That issue is the use of host headers while serving a SharePoint app.  Since I don’t know of any production environment that doesn’t use a host header, this could be quite the issue and Microsoft has no guidance for this on their site.  I’ll give a real world example and then go in-depth on what’s actually happening and what you need to do to fix it.

A Real Example

A couple of colleagues and I have been playing around with a SharePoint 2010 solution and looking at what it would take to convert it to a SharePoint 2013 app.  We mocked it all up outside of SharePoint 2013 and had everything working.  It’s a standard AJAX web page with a web service back-end.  Anyway, we went to deploy it to our test server, which has a hostname of dev.lulz.local (because we do stuff for kicks and giggles).  The app deployed correctly, so we made sure that the HOSTs entries were present and clicked on the app…and ran straight into a 404 Not Found.

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

To be honest, I was stumped.  I had no idea what was going on and everything appeared to be working correctly (there was absolutely nothing in the SharePoint logs).  So I called our resident SharePoint Master Amol Ajgaonkar, and we started talking.  Amol hadn’t come across this issue personally, but he had come across this blog post: Setting Up Your App Domain for SharePoint 2013.  Lo and behold, buried at the very end (which I had skipped), is a section that talks about host headers.

What’s Happening?

SharePoint 2013 serves apps in a very complex fashion, relying on a host header-less site collection at the root of a header-less web application on the server to provide the machinations to make apps come to life.  If you don’t have this web application you’ll likely see a 404 coming from Default Web Site.  This web application is even more important when you have web applications with host headers or site collections with host headers because the host header certainly won’t match your isolated app domain.

The solution

So if you have a host header (like dev.lulz.local) on your web application or a site collection where you want to host a SharePoint 2013 app, then you need an empty SharePoint 2013 web application at your server’s name (devsp15.lulz.local in my case) with a root-level site collection.  This site collection just has to exist but there’s nothing special about it other than its location.  Once I created that site collection, everything literally started to just work.

What about SSL?

You may be thinking, that’s great, but my site is protected by SSL and that makes everything difficult.  That’s true, it does make things more difficult, but not incredibly so.  If you have a secured web application, then your host header-less web application needs to be secured as well.  Also, if you’re following Microsoft’s advice and creating a completely separate domain to host your apps (like lulzapps.local in my case) then the certificate on your host header-less web application must also have a wildcard for your subject alternative name (SAN) (*.lulzapps.local in my case) so that your certificate appears valid in the browser.

Anyone having any issues with this that I can help solve?  I have to say that once you’ve got it set up, it works pretty well, but getting to done can be trying.