Architecture models for SharePoint provider hosted add-ins in on-premises

Now that the SharePoint 2016 is also arriving relatively soon, we are getting more and more questions around the on-premises setup around the SharePoint add-in/app model. Target of this blog post is to address some of the most common questions around the infrastructural setup for on-premises and to clarify what are the options from the infrastructure perspective. We will continue providing additional information for these topics also from MSDN based on community demand, which clearly is growing.

Let’s start with few common clarifications for top questions around hosting provider hosted environments in on-premises for SharePoint 2013 and SharePoint 2016

  • You do not need to have wildcard domain setup for your provider hosted environment. In fact, you do not need to setup it either for SP hosted add-ins, but that’s another topic. Wild card domain is needed to provide full isolation for app web in the case of SP hosted add-ins, if full isolation is required based on your company policy. You do not need to have app web with provider hosted add-ins and in provider hosted add-ins it really not the right model anyway due numerous reasons.
  • You do need to register own domain or network routing in general for your provider hosted add-ins. This can be something like or it can be using any other pattern as long as needed DNS entries are available for your provider hosted add-in so that traffic between SharePoint farm and your application flows without issues.
  • Using Secure Sockets Layer (SSL) whilst strongly recommended, is not mandatory for using Provider Hosted Add-ins with SharePoint. If your SharePoint Web Applications do not use SSL then there is no security value in configuring your provider hosted apps to use SSL. For OAuth2 based authorization mechanisms to be considered secure, both ends of the communication should be protected by SSL. Also note that if your SharePoint Web Applications are not SSL, the SharePoint Farm must be configured to allow OAuth over HTTP using Windows PowerShell. If you choose not to use SSL for both SharePoint Web Applications and the Provider Hosted add-ins environment be aware that the bearer tokens used by OAuth have no protection and applications are at risk of spoofing, information disclosure and repudiation vulnerabilities.
  • Using high trust OAuth model for on-premises does not require third party certificates and you can create the needed certificate used for “hand-shaking” between SharePoint and provider hosted add-in without third party providers. This is not used for securing traffic in the network, it’s used for “hand-shaking” between SharePoint and provider hosted add-in. Using SSL in your web application is completely different discussion.
  • There’s no “default hardware recommendations” for provider hosted add-ins since requirements are so heavily dependent on the exact use cases and scenarios what the provider hosted add-ins are providing. In general, would recommend to virtualize your hardware and increase the environment capacity based on the actual load, so that you do not need to over engineer your initial deployment.
  • You should not host your provider hosted add-ins in SharePoint farm servers. This will cause tightly coupled dependency from the operation perspective for the provider hosted add-ins and the SharePoint deployment which will impact your operational flexibility and in worst case scenario, issues with provider hosted add-ins will impact directly stability of the SharePoint. This also makes scaling of the provider hosted add-ins much more difficult since hardware changes impacts also directly your SharePoint farm.
  • SharePoint 2016 does not change the add-in architectural models for the provider hosted or SharePoint hosted add-ins
  • If your SharePoint is designed to be high available, it’s absolutely recommended to have your add-in model also as high available. You can use whatever network load balancing mechanism to achieve this, so this is again based on your company policies.
  • You can use exactly the same code in both on-premises and in cloud. You can in fact use also exactly the same authorization model for OAuth for this as well, which is called low trust model where your on-premises SharePoint farm is connected to Office 365 tenant for OAuth purposes. This requires that your SharePoint farm has internet connectivity, but key advantage is that you do not then need to deal with certificates for high trust model.

Provider hosted add-in environment is basically just a typical web application hosting environment without any additional technical requirements. In fact, you do not need to use even Microsoft platform to make this work, since just as well your provider hosted environment could be hosted in Linux. Only difference between technical hosting environment is the requirements for actual add-in implementation. There are ready to use templates for Microsoft platform, so any other technical platform would require additional work for the developers.

I do understand that some of the above statement could need more additional information and we’ll address them more detailed in the future in blog posts either in or in MSDN guidance in general.

What’s the right model for your provider hosted add-in architecture?

This is one of those questions which depends on numerous factors, like how many add-ins you are planning to host and who will operate or administer these add-ins. Some of the considerations for the overall architecture would be for example following.

  • How many add-ins will be hosted in your deployment?
  • Are add-ins operated and administrated by the same team?
  • Are servers operated and administrated by the same team?
  • What are disaster recovery requirements for planned add-ins?
  • What are performance requirements for the planned add-ins?
  • What are network requirements for planned add-ins or what kind of resources they need to access (SQL, AD, other)?
  • What are the standard server layouts available from your IT service provider or organization?
  • What kind of quality requirements are there based on the company policies?

As you can see from many of the above questions, this is more around the overall IT governance of your deployments and is highly dependent on the hosting model of these servers.

Let’s move to the actual meat of the blog post. Following chapters are clarifying the different models for the provider hosted environment architectures. These are relatively simple setups, but whole point is to reduce the confusion on supported models. Notice that especially in larger deployments you will see mixture of these models based on the types of provider hosted add-ins which are actually hosted in the environment.

Shared provider hosted environment

In this model you are sharing same hardware for multiple different provider hosted add-ins. This is the most typical setup for on-premises SharePoint due the simplicity and cost efficiency. It basically means that you have few servers in high available mode hosting the needed provider hosted add-ins. Provider hosted add-ins are load balanced between servers and you are hosting multiple add-ins in same platform.


  1. End user requests coming to provider hosted add-ins
  2. Load balancing the requests for high availability purposes using software or hardware network load balancing
  3. Shared provider hosted servers hosting all the same provider hosted add-ins
  4. Actual provider hosted add-ins which are hosted in own IIS applications
  5. Different services used by provider hosted add-ins, like databases or access to other systems


Dedicated provider hosted environment

In this model you have dedicated servers for specific provider hosted add-in, meaning that provider hosted add-in has dedicated hardware to host them in the environment. This is really rarely used model, since typically there’s no performance or resource requirements for this kind of setup. This is relatively theoretical setup which could be used when you have really performance intensive operations performed in the provider hosted add-in.



  1. End user requests coming to provider hosted add-ins
  2. Load balancing the requests for high availability purposes using software or hardware network load balancing
  3. Servers handling requests and hosting provider hosted add-ins are dedicated per specific web application
  4. Actual IIS applications hosting provider hosted add-ins
  5. Different services used by provider hosted add-ins, like databases or access to other systems


Isolated provider hosted environment

In this model we have isolation in the server levels in a way that for example organizational add-ins are hosted in dedicated servers or that add-ins which are coming from specific provider are hosted in dedicated servers. This kind of setup is relatively typical when you want to isolate organization add-ins or alternatively add-ins which are managed or operated by specific providers or partners.


  1. End user requests coming to provider hosted add-ins
  2. Load balancing the requests for high availability purposes using software or hardware network load balancing
  3. Requests are load balanced between high available servers, which are isolated based on organization or operational reasons
  4. Servers are hosting multiple IIS web applications for specific organization or provider
  5. Different services used by provider hosted add-ins, like databases or access to other systems


Office 365 Developer Patterns and Practices

Office365PnPLogoRed_thumb1Techniques showed in this blog post are part of the Office 365 Developer Patterns and Practices guidance, which contains guidance and reusable solutions for demonstrating different patterns and practices related on the add-in/app model development for Office 365 and SharePoint on-premises.

Check the details around PnP from at Please join us on sharing patterns and practices for the community for the benefit of the community. If you have any questions, comments or feedback related on this sample, blog post or anything on PnP, please use the Office 365 Developer Patterns and Practices Yammer group at

If you are interested on using above graphics in your presentations, they are included in the PnP presentation graphics deck available from Office 365 Dev PnP section at Feel free to re-use these graphics anyway you want in your own presentations.

“Sharing is caring”

Comments (12)
  1. Greg says:

    You mention that you do not need a wildcard domain for SP Hosted Add-Ins. I consult for the federal Government. They really don't like wildcard certs. So, I've been tasked with researching how to setup SharePoint Hosted Add-Ins without a wildcard cert. Every article we find from MS says you need one. We even brought MS (from our premier support) and they said we need one. I was wondering if you can point us to any article or anything from Microsoft that shows how to setup SP Hosted Add-Ins, in an https environment, without wildcard certs? Thanks in advance.

  2. Spence says:


    The wildcard domain is a mechanism to allow for the routing of requests to the PHA environment (or indeed SPH Apps). This is entirely separate from a wildcard certificate used to secure that traffic.

    You cannot practically implement SPH Apps without a wildcard certificate because due to the approach for addressing, as one cannot know the address of the apps before they are provisioned. As the Common name of the certificate must match the url of the request, a wildcard cert is the only practical approach. Technically it is possible not not use wildcards, but that then means you need a certificate for each app – that is possible to configure but it is a huge and unworkable management overhead and thus it is not something that is likely to ever be documented.

    This requirement really should be considered a fundamental flaw in the design of SPH. But it is (sadly) what it is.


    Spence –

  3. How to interpret the following sentence: "You do not need to have app web with provider hosted add-ins and in provider hosted add-ins it really not the right model anyway due numerous reasons." ?

    Even in PnP there are samples which require an add-in web (like people picker or taxonomy picker). How should cases like these solved without an add-in web?

  4. Oliver says:

    "You can use exactly the same code in both on-premises and in cloud." Does that mean i can use the SharePoint online client sdk assemblies to target onprem when 2016 is out? So i can use the exactly same app that i wrote for SPO to run onprem using the low-trust model? Or do i have to change the assemblies and use the onprem assemblies for my solution?

  5. Sergei says:

    "How to interpret the following sentence: "You do not need to have app web with provider hosted add-ins and in provider hosted add-ins it really not the right model anyway due numerous reasons." ? "

    Also interesting what does that mean?

  6. Vesa Juvonen says:

    Hi Pascal and Sergei,

    that refers to much longer discussion around the limitations on using app web. There are valid scenairos where it might be needed or useful, like when people picker is needed, since we have not yet build a component together with community, which would not require app web. This will be possible with Office 365 APIs/Microsoft graph, but currently PnP contains sample where we use cross domain library for handling the cross-origin challenge in the browser.

    Second dimension for this discussion is the add web usage as the storage location. When you are creating a provider hosted add-ins, it would be much better NOT to store information on the add-in web, since that can be tricky to operate. What I mean with that is that end users could accidently delete valuable data when they remove add-in without understanding the impact. Also each provider hosted add-in instance has it's own add-in web, which can be considered as advantage or disadvantage depending on perspective.

    We are more and more moving to direction where we build web applications, which are connected to the Office 365 services using Azure AD permission model. This can be considered as a evolution for the add-in model, but has also numerous advantages, like that you can access these services also directly, not through SharePoint Online. You would lose the add part capability, which could be disadvantage depending on the used model.

  7. Vesa Juvonen says:

    Hi Oliver,

    technically any add-in implemented to the SharePoint Online will work in on-premises even without compiling as long as you do not access properties which are only available in the SharePoint Online. There are some differences on the CSOM side from property and capability perspective. This difference will get significantly reduced with SharePoint 2016.

    With the PnP Core component we do compile the same code automatically as part of our automated daily build system with 15 and 16 version of the CSOM. Code is exactly the same, but with build settings we are dynamically changing the reference assemblies and also drop the code from the source which would not work in the on-premises.

    You can have a look on this model from the PnP Core component source code at…/PnP-sites-core

  8. Oliver says:

    Hey Vesa,

    Thank you for your answer. I am aware of the PnP Core component and the concept behind this. But I am thinking more about a hybrid app that runs in Azure and the same app can target o365 as well as onprem. Onprem I would be using Azure ACS (low trust app). This currently works when using the 15 assemblies. Those actually work against o365 as well, but of course does not offer all capabilities and properties.

    So I am wondering if it is possible to target the same app without recompiling against o365 and onprem with SharePoint 2016 since both use 16 Version assemblies

  9. Vesa Juvonen says:

    Hi Oliver.

    technically you can use newer CSOM in older version. SP2016 is using CSOM 16.0 version and SPO is using 16.1 version. There are small differences between the capabilities, but as long as you do not call an API which does not exist in the on-premises, this does work fine. So – technically you could use the exact same version of the add-in without re-compiling between different environments.

  10. Joseph Irvine says:

    Does port 443 need to be open to the NLB?

    I am tasked with setting up a High-Trust Provider Hosted App Model. We have two separate servers that we have procured to provide high availability. We will use the shared model. I am wondering if these need to be placed in the DMZ and have port 443 open from the Internet – or, if all the communication will be server-to-server, thus negating the need for DMZ placement and opening the firewall for communication from the web. Appreciate any clarifications.

  11. A Chuvash Guy says:

    In the beginning of SP2013 there was a misunderstanding: would use "a completely different domain name – What you are saying in this post, makes more sense. I agree that using (still having "") is better. I have seen many companies who really invested in additional second-level domains, like, and so on. Thank you for clarifications, Vesa, they will be useful in my work.

  12. MsSPJ says:

    Hi Vesa,

    If it is the recommended way to host multiple Add-ins in a single App Web ?


Comments are closed.

Skip to main content