Intro
This is blog is broken up into a 2 part series covering the following areas:
Part 1: Setting up the infrastructure for Provider Hosted Apps + Development (review this first)
Part 2: Create a basic Provider Hosted App in Visual Studio 2013, Package, and Deploy
This is a guide for On Premise SharePoint 2013 environments. I decided to write this blog because I believe a complete guide should exists that gives clarity to building the infrastructure for provider hosted apps for on premise deployments. Before diving into the steps, it’s worthwhile to quickly recap what are Provider Hosted Apps. While SharePoint 2013 on premise will still support fully trusted solutions, the strong recommendation is to leverage the app model and start building apps. The reasons are plentiful but mainly the code itself will run client side and not server side. This frees up resources on the SharePoint boxes since the custom code processing now happens on the client. When everything is on premise including the servers hosting the apps you have two different app models to choose from.
SharePoint Hosted Apps
With SharePoint Hosted Apps, everything including the app files are stored within SharePoint. When an app is installed to a site from the app catalog, a sub- site (sub-web) is created that stores the files that make up the app. This is usually referred to as an appweb. Things like pages, java script, etc… When a user leverages the app within SharePoint, the client will automatically fetch the app contents from the sub-web and client processing occurs to render whatever the app does. In this case, it’s not possible to run servers side code and app processing occurs client side.
Provider Hosted Apps
Provider Hosted App is one where the app is hosted outside of SharePoint. For Example, a server hosting IIS can host the app contents in a site. This is referred to as a remoteweb. This is more of a hybrid in that it can run a mix of both client and server side code. Plenty of documentation exists diving into the differences between both app models. Feel free to read up here for more details.
Question: Why use Provider Hosted Apps and not SharePoint Hosted Apps?
Answer: I see two answers to this question. The first is you need to run some server side code which is not possible with a SharePoint hosted app. The second is if SAML Claims authentication provider is setup with ADFS 2.0. This isn’t compatible with SharePoint hosted apps so you must use Provider Hosted Apps.
Note: If customer is using ADFS 3.0, they can leverage and use SharePoint Hosted Apps. See the following blog here for more information.
Part 1 walks one through setting up S2S authentication, Remote Web, Visual Studio 2013, and SharePoint prerequisites. I don’t cover setting up the App Domain although it’s still a requirement to have setup for Provider Hosted Apps. This guide is to illustrate and walk you through hooking up the foundational pieces in order to author, deploy, and use Provider hosted apps. The app in this guide does nothing special and simply redirects to a page on the remote web. The point of this guide isn’t to show you how to do x and y with apps but rather to ensure one is developing on a solid platform and understands the basics with building, packaging, and deploying provider hosted apps. When we talk about deploying Apps you have two different approaches.
Approach 1
A site with the Developer Site template is created. This site is used by a developer to deploy and debug his/her app. When starting a new app project in Visual Studio, it prompts you with the following:
Approach 2
After testing the app using approach 1, the app is ready to be packaged and deployed. This involves packaging both the app package and appweb (remote web) package and steps one through deploying both packages making the app available in the app catalog and ready for production use. This blog series will focus on Approach 2 only.
SharePoint Central Admin Prerequisites
SharePoint you must have the following service applications provisioned and started:
- Subscription Service Application with proxy
- Subscription Settings Service instance started
- Application Management Service Application and proxy
- App Management Service instance started
- Must have User Profile Service started
Setup Remote Web
1. Remote Web can be a Windows 2008/2012 box running IIS. (Ensure you include asp.net or apps won’t work)
2. Need to download and install web deploy from here.
3. Configure Authentication for the default site – (Note these steps came from MSDN)
a. When a new web application is installed in IIS, it is initially configured for anonymous access, but almost all high-trust app for SharePoint are designed to require authentication of users, so you need to change it. In IIS Manager, highlight the web application in the Connections pane. It will be either a peer website of the Default Web Site or a child of the Default Web Site.
b. Double-click the Authentication icon in the center pane to open the Authentication pane.
c. Highlight Anonymous Authentication and then click Disable in the Actions pane.
d. Highlight the authentication system that the web application is designed to use and click Enable in the Actions pane. If the web application’s code uses the generated code in the TokenHelper and SharePointContext files without modification, then the web application is using Windows Authentication, so that is the option you should enable.
e. If you are using the generated code files unmodified, you also need to configure the authentication provider with the following steps:
i. Highlight Windows Authentication in the Authentication pane.
ii. Click Providers.
iii. In the Providers dialog, ensure that NTLM is listed above Negotiate.
iv. Click OK.
Remote Web Certificate and Bindings Setup
It’s possible to use a self-signed certificate but this isn’t a common practice in production environments. Instead I setup AD Certificate Services and leverage that to obtain a certificate. It’s a fairly simple process to set it up and plenty of documentation exists which walks one through it. For this reason, I won’t include it in the steps. Assuming you have it setup, go to the servers hosting the remote web and perform the following steps:
1. Grab a domain certificate.
Steps are the following:
a) On the Remote Web, Go to IIS and click the server object and double-click on certificates
b) On the right, click on Create Domain Certificate
d) Click next, and click Select and choose the AD Certificate authority and click OK
e) Type in a Friendly name for the Cert
f) Click Finish and your cert should be present:
2. Finish Setting up Default IIS Site (I assume you know how to do this)
a) Set the Default IIS Site for SSL and set new certificate by going to into Site Bindings
b) While in Site Bindings, Export the certificate to CER by going to View\Details tab and click “Copy to File”
c) Drop the exported file in the c:\certs folder
d) Copy the c:\certs folder to SharePoint box
SharePoint Token Issuer Setup
At this point, the certificate is now copied over. This certificate we will need to register to the root authority as well as register it as an official token issuer. If the app hosted in IIS as a remote web needs to call into SharePoint, it uses the certificate to retrieve an access token from SharePoint. It then uses that access token to retrieve data within SharePoint assuming that is how the app is authored. Without the SharePoint Token Issuer, this functionality wouldn’t exists.
The following PowerShell should be run on SharePoint:
##Grab the cert and create the object##
$publicCertPath = “C:\Certs\remotewebapps.cer”
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
##Certificate treated as root authority##
New-SPTrustedRootAuthority -Name “remoteweb” -Certificate $certificate
##Setup token issuer which is the certificate itself##
$realm = Get-SPAuthenticationRealm
$specificIssuerId = [System.Guid]::NewGuid().ToString()
$fullIssuerIdentifier = $specificIssuerId + ‘@’ + $realm
New-SPTrustedSecurityTokenIssuer -Name “IssuerforRemoteWeb” -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier –IsTrustBroker
Very Important: The IssuerID is needed each time you create apps in Visual Studio so put it somewhere safe.
In my case its: 8cb8c3db-5bfd-4a7a-8b18-189000065ad0
Visual Studio 2013 Setup
Install Visual Studio 2013 Professional or later on a SharePoint box.
Ensure you check web developer tools when you install
After installing Visual Studio 2013, download and install the Office Developer Tools for Visual Studio 2013 – May 2014 Update.
In addition, you’ll need the SharePoint 2013 Client Components SDK but that comes included in the update above!
For Example here is what installed after I applied the update:
Other important MISC guidance regarding Visual Studio 2013 setup
· When you install Visual Studio 2013, check web developer tools option.
· Install the Office Developer Tools for Visual Studio 2013 – May 2014 Update. The download link is found here.
· When app is deployed from Visual Studio, you must do so with an account other than the system account. Next, you must drop the saved project in a generic directly and give this non system account full control perms.
· In order to debug apps from Visual Studio 2013, you must create a development site and target that when creating the VS project.
Create a New Web App and Developer Site
In SharePoint 2013 Central Administrator, I created a new web app and set it to 443 (create IP, host header, and dns record) and updated IIS Bindings. I assume you know how to do this. Finally, I created a Site Collection using the Developer Site template. The Developer Site is used by Visual Studio to test and debug an app and doesn’t facilitate what so ever with deployment of app package to the app catalog. These are additional steps you must perform in Visual Studio. I outline those in Part 2.
To continue to Part 2 in this blog series, please click here.
Resources
http://msdn.microsoft.com/en-us/library/fp179901(v=office.15).aspx
http://msdn.microsoft.com/en-us/library/fp179923(v=office.15).aspx
http://msdn.microsoft.com/en-us/library/office/jj860570(v=office.15).aspx
Thanks,
Russ Maxwell, MSFT