Export (0) Print
Expand All

Choose patterns for developing and hosting your SharePoint Add-in

SharePoint Add-ins

Learn about the different ways that you can host the components of apps for SharePoint.

Last modified: March 09, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

The SharePoint 2013 app model introduces a wide range of hosting and development patterns. Some of these patterns can be used in combination with each other. For example, your apps can mix SharePoint-hosted and remotely hosted components. The most useful way to determine which patterns you’ll want to use is to start with your own requirements, technologies, and goals and match them with the options and possibilities that are enabled by apps for SharePoint.

Apps for SharePoint widen the range of possible programming languages and technology stacks that you can use when you work with SharePoint resources and services. The precise range of options depends on both the type of app and the hosting pattern that you choose. It’s also possible to mix patterns.

SharePoint-hosted apps

Start with the simplest option: SharePoint-hosted apps, or apps where all components are hosted on either an on-premises or Office 365 SharePoint farm. SharePoint-hosted apps are installed on a SharePoint 2013 website, called the host web. They have their resources hosted on an isolated subsite of a host web, called the app web. It’s important to know the difference between host webs and app webs. Figure 1 illustrates the basic architecture of a SharePoint-hosted app.

Figure 1. SharePoint-hosted app architecture

The components of a SharePoint-hosted app are hosted on the appweb of a SharePoint farm.

You can combine a SharePoint-hosted app with apps that have remotely hosted components, but any app or portion of an app that runs on an app web has the following set of requirements for three key components: where the app is hosted, how the app gets authorization, and what language it can use.


SharePoint-hosted app requirement

Where the app components are hosted

In the isolated app domain of your SharePoint farm

How the app gets authorized

The privileges of the signed-in user

What language the app can use

JavaScript (with the SharePoint 2013 JSOM library) + HTML

This pattern is the easiest to deploy, and you can use the Create a basic SharePoint-hosted SharePoint Add-ins by using Napa Office 365 Development Tools. You’ll want to consider the following before deciding to create a SharePoint-hosted app.

Get these benefits

But consider this

Reuse common SharePoint items, like lists and Web Parts.

You can use only JavaScript in the app—you can’t use any server-side code.

Relatively easy to create and deploy, so they are good for small team productivity apps and business process automation, with lower complexity business rules.

Your app has only the authorization privileges of the signed-in user.

Get started creating SharePoint-hosted SharePoint Add-ins

Provider-hosted apps

Provider-hosted apps for SharePoint include components that are deployed and hosted outside the SharePoint farm. They are installed to the host web, but their remote components are hosted on another server. Figure 2 illustrates the basic architecture of a provider-hosted app.

Figure 2. Provider-hosted app architecture

The components of a provider-hosted app are hosted on any web server or hosting service.

The following table shows how the requirements for hosting location, app authorization, and languages are much less fixed for provider-hosted apps than they are for SharePoint-hosted apps.


Provider-hosted app requirement

Where the app components are hosted

Any web server or hosting service

How the app gets authorized

OAuth or the JavaScript cross-domain library

What language the app can use

Any language supported by your web server or hosting service

A provider-hosted app interacts with a SharePoint site but also uses resources and services that are located on the remote site. You’ll want to consider the following before deciding to create a provider-hosted app.

Get these benefits

But consider this

Host the app on Microsoft Azure or any remote web platform, including non-Microsoft platforms.

You are responsible for creating the installation, upgrade, and uninstallation logic of the remote components.

Use one of the SharePoint client object models, the JavaScript cross-domain library, or the SharePoint 2013 REST/OData-based web service to interact with SharePoint.

Each way of interacting with SharePoint has corresponding options for approaches to data access.

Gain authorization to SharePoint data using one of the three authorization systems.

You need to decide between OAuth and the cross-domain library to authorize your app’s access to SharePoint.

In addition to considering the technical advantages and constraints of each option, you’ll also need to think about your development goals when deciding on a hosting pattern. You can use the following table to help sort out which hosting pattern best fits your needs.

Your requirements

Recommended Hosting pattern


Work with and provision new SharePoint entities exclusively


An app that includes a people picker control and that stores information about SharePoint users in a SharePoint list

Use existing SharePoint entities and interact with external (non-SharePoint) web services


An app that gets customer addresses from an existing SharePoint list in the host web and uses a mapping service in a web application to display their locations

Provision new SharePoint entities and interact with external web services

Combined SharePoint-hosted and provider-hosted

A mapping app that provisions a SharePoint list on the appweb so that it can store latitude and longitude coordinates for addresses that are supplied by the user or pulled from an existing SharePoint list

SharePoint-hosted apps have a fixed hosting pattern, since they are hosted on the app web. Provider-hosted apps provide more flexibility for hosting the various components of your app, so if you choose to create one, you’ll need to match your goals and requirements to the appropriate hosting pattern.

OAuth or the cross-domain library

One of the most important questions you need to ask when considering provider-hosted apps and how you’ll build them is how the app will get authorization to interact with SharePoint. Provider-hosted apps give you two choices: the JavaScript cross-domain library and OAuth.

The cross-domain library lets you interact with more than one domain from the remote components of your app through a proxy. If client-side code and the permissions of a user who is signed in to SharePoint are sufficient, the cross-domain library is a good option. The cross-domain library is also convenient whenever you are making remote calls through a firewall.

OAuth is an open protocol for authorization that enables secure authorization from client applications (desktop, web, and mobile applications) in an easily manageable way. If you plan to build an app for SharePoint that runs in a remote web application and communicates back to SharePoint 2013, you will often need to use OAuth. OAuth is required whenever you are calling into SharePoint from a remotely hosted web application that can’t use client-side code (HTML + JavaScript) exclusively. Learn more about how OAuth works in apps for SharePoint.

Data access options for SharePoint Add-ins and Three authorization systems for SharePoint Add-ins 2013 explain the choice between OAuth and the cross-domain library more thoroughly.

OAuth with on-premises SharePoint farms

If you are using an on-premises deployment of SharePoint 2013, you can use OAuth, but you will have to choose between creating high-trust apps and using an Office 365 tenancy. Office 365 uses Microsoft Azure Access Control Service (ACS) as the trust broker, and if you do not have access to an Office 365 tenancy, you’ll need to use Create high-trust SharePoint Add-ins 2013, which uses certificates to establish trust between your app and SharePoint. You can add high trust apps to the app catalog of your SharePoint farm, but you can’t sell them in the Office Store. If you do have access to an Office 365 tenancy, you can link it to your on-premises installation of SharePoint 2013 and use ACS as the trust broker for apps that are installed to your on-premises SharePoint.

The following table lists all of the possible patterns for hosting both the SharePoint components and the remote components of your app, along with the trust brokers that are available to you if you’re using OAuth. Note that you’ll need access to an Office 365 tenant in order to use ACS to establish trust between SharePoint and an app for SharePoint that is installed to an on-premises installation of SharePoint 2013.

SharePoint component location

Remote component location

Trust broker

On premises

In cloud

ACS, certificate

On premises

On premises

ACS, certificate

Office 365 SharePoint site

In cloud


Office 365 SharePoint site

On premises


You can also build apps that include both SharePoint-hosted and cloud-hosted components. For example, you can create a cloud-hosted app that includes a custom SharePoint list and content type. If you choose to use this architecture, your design and approach must account for security limitations that are built into the model. You can use only JavaScript in the code components that are hosted by SharePoint, and the remotely hosted components must use either OAuth or the cross-domain library to interact with the SharePoint website. When considering this approach, make sure that you understand how app authorization works in SharePoint 2013. Figure 4 shows you how this architecture works if you use Microsoft Azure to host the remote components of your app, and you use OAuth.

Figure 4. SharePoint app server-to-server communication when you use OAuth and Windows Azure

Server to server communication restrictions

Learn how to create an app that combines cloud hosting and SharePoint hosting.

Here are some things to think about when you’re considering a combination of provider hosting and SharePoint hosting.

Get these benefits

But consider this

All the benefits of the two approaches.

More complex architecture requires careful planning around server-to-server communication and cross-site scripting restrictions.

Your apps for SharePoint will often open from inside your SharePoint 2013 site, but you may want to interact with SharePoint 2013 resources without having to create an app that originates from SharePoint. For example, you may be working on an app that runs on a mobile device or an app for Office that needs to interact with SharePoint 2013 without forcing the user to visit the SharePoint site. In this case, you’ll need to create a provider-hosted app that gets access to SharePoint resources on the fly.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft