How To Configure SharePoint 2013 On-Premises Deployments for Apps

Summary: Chris Whitehead, Microsoft Certified Master (SharePoint 2010) and Premier Field Engineer based in the UK provides us with pointers to the best content and additional information that IT Pros need which is not well documented in one place. It serves as an end-to-end guide and reference point to all the information you need in order to configure SharePoint on-premise deployments for Apps. A great and comprehensive read. Enjoy!

So now that you know what SharePoint Apps are, you will likely want to configure your own on-premises deployment(s) to provide support for Apps. Of course if you are using Office 365, a lot of this is already done for you.

There are a number of configuration steps that you’ll need to complete, along with a number of additional considerations to be aware of. This article will speak through these.

Configuration Steps for Deploying SharePoint Apps

At a high level the configuration steps are as follows:

Infrastructure Configuration:

Determine your App Domain.

Configure domain name in DNS.

Create a new wildcard SSL certificate.

Farm Configuration:

Create SharePoint Service Applications and enable services.

Configure App settings in SharePoint

·App Auth Configuration:

Configure SharePoint for low-trust Apps

Configure SharePoint for high-trust Apps

Rather than provide a step-by-step guide for each of these steps (and repeat much of TechNet and what is already blogged about out there), I am going to provide you with pointers to the best content and additional information that you may need which is not well documented in one place. This will hopefully serve as an end-to-end guide and reference point to all the information you need in order to configure SharePoint on-premises deployments for Apps.

Infrastructure Configuration

Part 1 of this post covered the architectural design decisions implemented in SharePoint 2013 to support Apps, and ensure that each App instance is self-contained with a unique URL in order to enforce isolation and prevent cross domain JavaScript calls through same origin policy in Web browsers. It also covered the format of this URL. As a reminder, the App domain shown in red below is the domain name portion of the URL that we must configure along with the App Prefix (shown in orange):

Determine your App Domain

One App domain is used per farm and, once configured in DNS, it is configured in the App Settings for the farm. When choosing your App domain for each farm, you have 2 options:

Create a new unique domain to host your SharePoint-hosted Apps in, or

Create a sub-domain of the existing domain.

The recommendation is to create a new unique domain such as contosoapps.com rather than a sub-domain such as apps.contoso.com. The reason for this is that use of a sub-domain could lead to cookie attacks (depending on the browser in use) on other non-SharePoint Web based applications in the same domain namespace. A malicious SharePoint App developer could write an App that could read or set cookies across other websites such as a PHP site hosted at portal.contoso.com, provided the developer of that site hasn’t protected the cookies correctly.

Therefore the recommendation to create a new unique domain is a ‘belt and braces’ approach to prevent other websites from potentially being attacked by using a SharePoint App as the attack vector. If you have audited all other websites in the domain and are happy that they are suitably secure, then you may choose to take the sub-domain approach.

Configure domain name in DNS

Once you have determined your App domain, it will need creating in DNS (obviously if your farm is externally facing, you will also need to purchase and register this domain name). Since all App webs have a unique host name (App prefix and App ID above), a wildcard DNS entry is required. Without this, you would need a new entry in DNS for every App instance, this would not scale and is not a feasible solution. There is also no way of determining what the App ID would be in advance of creating an App.

Create a new wildcard SSL certificate

Further to this, you will of course need a wildcard SSL certificate for your app domain if you are using SSL for your SharePoint environment. Which of course you should be, especially when implementing Apps since OAuth access tokens for Apps will be in plain text otherwise and could be replayed by a malicious user or code.

If you have multiple farms that you would like to configure to host and consume Apps, then yes you will need to do this for each one, along with all the steps below.

Farm Configuration

Before you can use Apps in your farm, you will need to complete some farm configuration steps, the first of which is creating Subscription Settings and App Management service applications, and enabling the relevant services.

Create SharePoint Service Applications and enable services

The Subscription Settings service application is historically only relevant for multi-tenancy scenarios, but it is a prerequisite when implementing Apps because it is used to generate and keep track of the App IDs (shown in green above). The internals of how this is generated is not important, but without this service application, the steps required to generate these App IDs cannot occur.

The App Management service application is largely responsible for licensing information, for example its database is accessed each time an app is used to verify the validity of the request.

One key thing to note is that both service applications must be in the same service application proxy group, otherwise the Apps infrastructure will fail to work.

Configure App settings in SharePoint

Finally, you must configure some App settings in Central Administration or via Windows PowerShell cmdlets. These include specifying the App prefix and App domain for the farm; specifying the location of the App Catalog, which is the site used to distribute Apps in our environment; and configuring Store settings such as whether users can install Apps from the Office Marketplace.

Apps do not support Kerberos – since each App runs in its own isolated domain, for Kerberos to work we would need to configure SPNs for every App – which is not feasible! Therefore even with Kerberos enabled for your Web Applications, SharePoint Apps rely on being able to fall back to NTLM.

SharePoint-hosted Apps do not support SAML auth – currently SharePoint-hosted Apps will not be redirected to correctly when using SAML auth. This is because most identity providers (ADFS 2.0 included), do not support wildcards for return URLs – which would be needed due to the isolated domain model implemented for SharePoint-hosted Apps. However, Azure hosted, or provider-hosted Apps will work when SharePoint is configured to use SAML auth – but there is some configuration required, which Steve Peschka covers off in quite some detail here: Using SharePoint Apps with SAML and FBA Sites in SharePoint 2013.

Apps do not support multiple zones – all requests will only ever be served out of the default zone. If you need multiple URLs for SharePoint, you should consider using host header site collections with multiples URLs – a new feature in SharePoint 2013 – rather than multiple zones and Alternate Access Mappings (AAMs). Check out the Set-SPSiteUrl cmdlet for more detail.

A routing Web Application may be needed – imagine the multiple Web application scenario and remember that we have 1 App domain per farm. If we install Apps in each Web application, bearing in mind the separate App domain that will host App Webs for these Apps, how is the request to our App Web going to be routed to the correct hosting Web application? How does SharePoint differentiate between an instance of an App Web that lives in the ‘my sites’ Web application, and an instance that lives in the ‘intranet’ Web Application? The section below explains this in more depth.

Update: One of the feature updates of the March 2013 Public Update for SharePoint 2013 enables you to use multiple app domains in SharePoint 2013 environments with alternate access mapping or host-header web application configurations. Before the Public Update, you could only host one app domain and it had to be in the Default zone. You could not use the app domain on alternate access mappings or host-header web application configurations. The Public Update enables you to configure an app domain for each web application zone and use alternate access mapping and host-header web application configuration. More information about configuring apps in AAM or host-header environments can be found at: http://technet.microsoft.com/en-us/library/dn144963.aspx.

Routing Web Application

Consider the scenario where a request is made to http://app-bdf2016ea7dacb.contosoapps.com/sites/SPC/Poll. The App Web itself lives in the ‘intranet’ Web application, but how does SharePoint determine that?

In the above diagram, the request for the App Web comes in from a client and a DNS lookup is performed. DNS resolves contosoapps.com to our NLB device which in turn routes to our SP farm. However, the host header for this request is not matched to any of our Web applications so SharePoint won’t know how to handle this.

To get around this we could try to configure SharePoint and IIS so that application requests go to one of our existing Web applications (and in theory this may work because SharePoint will do some clever routing which is covered in more detail in a second). But when using SSL, it will break because we can’t have an SSL certificate that contains multiple wildcards such as *.contoso.com and *.contosoapps.com, and we can’t bind two to the same site.

So to get around this we need an additional Web application that will act as a catch all routing Web application. This Web application must either have its own dedicated IP address, or must have no host header if sharing an IP address – that way it will serve all requests that don’t match host headers for the IIS sites of the existing Web applications. Internally the SharePoint HTTP module will know where to route this request by using the App Management Service Application to work out which Web Application hosts the App Web. This can be seen below:

This approach allows us to bind our App Domain wildcard certificate to the IIS site for our catch all routing Web Application, and also bind wildcard certificates to IIS sites for our existing Web Applications.

As ever, there is an additional caveat. The identity that the application pool for the routing Web Application is using, must have rights to all the content databases for all of the Web Applications that are being routed to. The easiest way to achieve this is to use the same application pool for all Web applications, or use the same identity for all application pools.

App Auth Configuration

The topic of App authorisation and authentication is a vast one, so I will only touch on a few key points here at quite a high level, and provide additional reading for those that want to know more.

In general as an IT Pro, you need to be aware that cloud-hosted Apps (those outside of SharePoint) won’t just work out-of-the-box with an on-premise SharePoint 2013 deployment. When you think about it, this kind of makes sense, our externally hosted Apps need to be able to call into SharePoint to request data, by default no trust is going to be in place to allow this – so we need to hook that trust up somehow.

In SharePoint 2013, OAuth is used to establish this ‘trust’ – OAuth enables users to grant a third-party site access to information that is stored with another service provider (in this case, SharePoint), without sharing their user name and password and without sharing all the data that they have in SharePoint. At a really high level, this looks something like the following:

A user signs in to SharePoint 2013 and is authenticated. The authenticated user then uses a cloud-hosted App which uses the SharePoint client object model (CSOM) or REST endpoints with CSOM to make calls to SharePoint. The App is granted permission by the user to access SharePoint resources on the user's behalf. When the App launches, it loads from another location and calls back to SharePoint to access the resources on behalf of the user by using an access token.

The method of generating the access token mentioned above is a key differentiator to the auth flow. In SharePoint 2013, OAuth is used for Apps that fall in two differing scenarios which are known as “low-trust” and “high-trust.”

Configure SharePoint for low-trust Apps

Low-trust Apps are those that use an authentication provider to act as a common authentication broker or trust broker between SharePoint and the App. This will be Windows Azure Access Control Services (ACS), and as such will of course require an Office 365 subscription.

There is a fair amount of configuration required to allow SharePoint on-premises farms to communicate with ACS. Josh Gavant (a fellow PFE), has a great post detailing all of the steps, along with some handy PowerShell helper functions here: SharePoint Low-Trust Apps for On-Premises.

Configure SharePoint for high-trust Apps

High-trust Apps are those where you are not using ACS as the trust broker, so there is no context token. Instead, you are using a certificate to establish trust and generating your own access token by using the server-to-server security token service that is part of SharePoint 2013. This type of trust is known as a server-to-server trust relationship and is between the SharePoint farm and the App, therefore it must be done for each high-trust App that uses different certificates which a SharePoint farm must trust. High-trust does not mean "full trust", a high-trust app must still request App permissions. The app is considered high-trust because it is trusted to use any user identity that the App needs, because the App is responsible for creating the user portion of the access token.

When an App is not SharePoint-hosted and requires some server-side processing logic, this is the approach in-house apps should take most of the time.

Summary

The new App model for SharePoint is a big paradigm shift that not only affects developers, but also affects IT Pros that manage and maintain SharePoint 2013 on-premise. Having an understanding of all the working parts and how to configure them will become more and more important as the App model becomes more prevalent. Hopefully this blog series (including the first post on Understanding SharePoint Apps as an IT Pro) helps you on the way with this – best of luck!

Thanks for sharing the link, Devendra. Note that credit for authoring this particular post belongs to Chris Whitehead, one of our ever-so-esteemed Microsoft Premier Field Engineers and Microsoft Certified Master on SharePoint.

Note: there are some changes coming that enable apps in AAM or host-header environments. Additionally the requirement for a routing Web application will be removed. This post will be updated shortly to reflect this new change!

If I understand you correctly, it means that a SharePoint hosted app can get by without server-to-Server authentication or OAuth. I believe that under the Hood this is dealt with using an "internal" Principal. However, I haven't been able to Access data outside of the App or Host web neither in another SharePoint list/library nor in a custom SharePoint WCF Data Service. Such calls (made using Client side script e.g. JavaScript or CSOM) never get authorized. Since I've granted the App as well as the user enough permissions, I feel that the internal principal is lacking sufficient permissions (even though i would have guessed it would do some Kind of impersonation – even though this might proof difficult using client-side techniques). Any ideas on this?

I am a SharePoint admin for the University of Colorado and saw your presentation at SPC2012 regarding SharePoint Apps. At that time I had not done much work in SP13 but am now very deep into it and have a question. I have setup SharePoint Apps as you outline and as I saw in some tech net articles and am getting a simple app to display on a page, however; I am having an issue that I hope you can help me with. I am being prompted for a login for each app occurring on the page. If I login they display if I do not login they do not display. I started an MSDN ticket to see if I have misconfigured. The tech told me that this is expected behavior and I can change settings in IE to do automatic login with windows credentials. I am having a hard time believing that this is correct. So my question to you is, Is this in fact expected behavior?? If it is, is there a work around??

@Steven: If their proposed solution works, it's probably because you're using multiple hostnames (for eg, one per app?) which IE perceives as being non-local.

There are a few KB articles on how IE resolves which zone to put something in, but ideally, you want anything within your organization (and thus eligible for transparent authentication) to be included in the Local Intranet Zone.

Anything with dots in it won't be considered internal, by default. So any FQDN is treated by IE as being an Internet site. This is by far the most common reason for prompts being seen when they're not intuitively expected.

If you use a PAC file (or WPAD), anything which goes DIRECT is considered internal (again, by default) and anything which uses a Proxy is considered Internet Zone. If you're using a manual proxy setup and the hostnames you're connecting to don't appear in the Bypass list, again, prompting. If you've edited your Local Intranet Zone settings and disabled the default inclusion options, again, that's a problem.

For testing purposes, I'd suggest explicitly adding the site names to the Local Intranet Zone.

Note also that a common knee-jerk reaction is to put things in Trusted Sites, but by default it doesn't allow automatic logons either – Local Intranet Zone is where the automatic transparent authentication is at!

Now, I've rambled on for a bit, and I didn't check whether this is actually your problem – so if this doesn't address your problem, I'd suggest continuing with the MSDN ticket!

Great post – you mentioned “The app is considered high-trust because it is trusted to use any user identity that the App needs…”

How does one actually do this? I mean, I’m using managed CSOM, and I have a Principal object for an arbitrary user – how do I then convert that to a ClientContext to allow me to execute on behalf of that user? The TokenHelper file is a bit confusing, because it seems to mix the terms ‘access token’ and ‘context token’ and I’m a bit lost.

Can’t we use our same Domain name as APPs domain? Like my Domain is SSA.com and i want to use same SSA.com domain for APPs is it allowed? what different problem can i face? What if i want to use same domain in Internet site or Intranet site?

This was/is a very helpful article and it helped me get on the right track for adding apps into my environment. One spot where I ran into issues was that I have a physical load balancer and this required me to make sure I was using a separate IP address so I could handle/manage the NAT requirements for a separate domain.

Has anyone configured apps in a load balanced environment? We’re currently configured with F5 load balancers doing port redirections for SSL. I know the articles on configuring apps note that the apps web app needs to be listening on 443, but we currently
have it set up on 8449. When adding an app to a site, the app site is being created on the apps web app, but the configuration looks incomplete – the ribbon renders as text and none of the admin pages for the app are available. Has anyone encountered this
before? Is it possible this is related to the port redirections, or is something else going on?

This post is very helpful. what are the hardware and software required to setup single server enviorment as lastest technology. How do you setup workflow manager as a part of Provider host? what do I do to change on-premise provider hosted app to Clound
Provider hosted apps? thanks.

The post mentions a routing web application with no host header and allows to bind the app domain SSL certificate however what if you have an environment where host named site collections are in use and therefore the parent web application contains no host header for this to work? As you’re aware you cannot have 2 IIS sites, both with out hostheaders bound to the same IP and port.

I have created a SharePoint provider hosted app but I am a bit confused the way it is working.
So The provider hosted app is consist of a asp.net web application which is hosted in IIS server(remote app). And the SharePoint app web, running on SharePoint server.

The remote asp.net application is bound to a certificate running on 443 port. But I didn’t configure SharePoint server with the certificate or issuer ID. But when I install the app it’s running just fine. I’m so surprised how it is running without configuring certificate as a high trust app. Is it because both server is under same Domain controller ?