Step by Step Installation Guide – SharePoint 2013 On-Premises Provider Hosted High Trust Configuration

Last December, I had the privilege to walk through SharePoint Fest Chicago attendees detailed step by step process of building end-to-end SharePoint High-Trust Provider Hosted Add-ins environment.

The information I had presented has been scattered around on web or MSDN or on Office 365 PnP, but I am yet to see full detailed end-to-end guidance on add-ins configuration even though add-ins model has been released since July 2012. One of the main reasons why SharePoint provider hosted add-ins isn’t popular because it takes lots of skills to stand up add-ins development environment.  This guide is intended to walk you through key steps requires designing SharePoint 2013 high trust provider hosted add-in environment.

As an overview, my SharePoint Lab consists of 2 VMs for SharePoint 2013 on-premises environment – All-up SharePoint 2013 VM with AD and SQL & Provider Hosted Add-ins VM. Some of the key goals I have with this article are:

  • Provide practical guidance to build real world environment. Even though I don’t have the load-balanced environment, you can repeat most of the configuration to configure the load-balanced environment. The configuration of load balancers and DNS routing are out of the scope for this article.
  • Provide secure SSL communication between SharePoint and Add-ins environment. This article still applies to a non-SSL environment and various steps for non-SSL has been called out in the article.
  • Support for SharePoint hosted add-ins in addition to high trust provider hosted add-ins. This is my personal preference. There is complexity in infrastructure configuration due to SharePoint hosted add-ins. If you are planning to support only provider-hosted add-ins, you will able to find steps which you can ignore.

Provider hosted add-ins

Here are high-level steps one needs to take to configure SharePoint high-trust provider hosted add-ins in SharePoint on-premises environment.

Preparing Infrastructure for High-Trust Provider Hosted Add-ins

  • Prepare SharePoint On-Premises Environment
    • SharePoint Network Infrastructure – Make a note of SharePoint Domain (e.g. Niks.local), valid SharePoint DNS (e.g. intranet.niks.local), and Wildcard Cert (e.g. with friendly name – *.Niks.Local)
    • SharePoint Wildcard SSL certs are optional but recommended.
    • Install SharePoint Environment – SP2013 RTM + Latest Service Pack + Latest CU
      Provision a primary web application with SSL and NTLM authentication. SSL is optional for Add-ins configuration if your SharePoint environment isn’t on SSL, but it is recommended.
    • Configure User Profile Service Application and Profiles Sync. This is required for Add-ins User Profile hydration for Auth Tokens.
  • Configure Add-ins Domain
    • Determine Add-ins Domain Strategy – You can have only one Add-in domain is used per farm..Determine the domain name to use – either unique domain (e.g. NiksApps.local) or Subdomain (e.g. Apps.Niks.local) – for security reasons, plan to have different domain because cookies can be modified or read across different domains that are under the same domain.
    • Configure Add-ins Domain and a Wildcard DNS entries for SharePoint Add-ins – Wildcard DNS entry is not used by Provider hosted Add-ins. Wildcard DNS entry is required for SharePoint Add-ins if you are deploying. Add-ins as entirely isolated App webs. 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. I  would recommend configuring wildcard DNS entries for SharePoint Add-ins as a pre-requisites for provider hosted add-ins. Plan to review Mirjam Van Olst’s classic article.
  • Request a Wildcard Certificate for SharePoint Add-ins
    • There are two things to remember about Add-ins SSL – One is SSL certificate is optional if you aren’t using secure communication and second is it’s not required for the Provider Hosted Add-ins.
    • Add-ins Wildcard certificate is required for the SharePoint Add-ins for SSL. Since recommendation here is we will be building provider hosted add-ins for both SSL, and SharePoint hosted apps, you will need a wildcard SSL certificate for your add-in domain.
    • A valid wildcard SSL ad-ins cert can be issued by public CA, corporate CA, or Self-SSL utilities. (e.g. *.apps.niks.local or *.niksapps.local)
    • Verify wildcard certificate for both SharePoint and Add-in URLs are added to SharePoint boxes. There are two places to check – Verify if certificate is available on both personal and certificate root authorities store using Manage Certificates utilities and verify these certificates are imported and available on the IIS
  • Configure Routing Web App for SharePoint Hosted Add-ins
    • It is important to note that this step is NOT required for the provider hosted add-ins. This is required for SharePoint Add-ins only if you have SharePoint web applications are using host headers.
    • Provision Add-ins Routing web app – Create New SharePoint Web App – Port-80, Non-SSL, NTLM, Application Pool – SP_farm, and Content Database – WSS_Content, provision root site collection based on team site template and make sure Routing web app don’t have any host header, an idea here is to catch all. Add HTTPS binding with Add-ins wildcard cert on the default web app, remove HTTP binding for SSL.
    • Routing web app is not required for the host header site collections.
    • Best Practice – Disable Default IIS website from the IIS Manager and IIS RESET
    • Without this – You may encounter 404 error – Jereme Thake’s article
  • Configure Required Services and Service Proxies – App Management and Subscription Settings
    • Both App Management Service and Subscription Settings Service must be started.
    • The App Management service application is primarily responsible for licensing information, for example, its database is accessed each time an add-in is used to verify the validity of the request.
    • The Subscription Settings service application is historically only relevant for multi-tenancy scenarios, but it is a prerequisite when implementing Add-ins because it is used to generate and keep track of the App IDs.
    • One key thing to note is that both service applications must be in the same service application proxy group. Otherwise, the Add-ins infrastructure will fail to work.
    • How to configure?
      • Start App Management and Subscription Settings Services from Central Administration or Windows PowerShell.
      • Configure the App Management Service application by using Central Administration or Windows PowerShell.
      • Configure Subscription Settings Service Application by using Windows PowerShell.
    • Required PowerShell script to automate some of the steps discussed in this section is available as part of presentation attached to this article.
  • Configure App Prefix, App Hosting Domain, and App Catalog
    • Create App host domain (e.g. apps.niks.local) and App URL prefix (e.g. app) using PowerShell or from Central Admin
    • Create App Catalog site collection from Central Admin site and configure permission – You can have one App Catalog per web application. You can’t add add-ins in consumer sites unless you have visitor access to this site collection. Configuring Store settings such as whether users can install Add-ins from the Office Marketplace.
    • Required PowerShell script to automate some of the steps discussed in this section is available as part of presentation attached to this article.
  • Prepare Provider Hosted Add-ins Servers
    • Prepare for IIS and Application hosting – Install/Configure Web Server Role and Application Server Role -.NET Framework 3.5.1 features, Windows Process Activation Feature, Web DEV, ASP.NET, etc.
    • Prepare for.NET framework hosting mode – Install/Configure.NET Framework 4.5 and later, Note – Windows 2008 R2 installs only.NET Framework 3.5
    • Prepare for App Web Deployment using command line – Download and Install web deploy tool –
      Web Deploy (msdeploy.exe) must be installed on the computer that runs the .cmd file for appsweb. For information about how to install Web Deploy, see the following URL:
    • Add DNS entries to resolve provider hosted add-in URL – Import a High Trust certificate on Add-ins Host Servers, if you don’t have PFX and CER files from the external/internal CA, one way to obtain is exporting with private key (e.g. NiksHighTrustCert.pfx) and with public key (e.g. NiksHighTrustCert.cer) for all the certs including root CAs and other parent certs in chain (RootCAHighTrustCert.cer) from the SharePoint servers. CER format requires to register cert with SharePoint, PFX format requires for Add-ins. Usually, high trust certificate would be same as wildcard cert used for the SharePoint web applications if high trust Add-ins and SharePoint shares same domain.
    • Configure BUILTIN\IIS_IUSRS access to the High Trust cert – For the separate IIS server hosting Add-ins, configure BUILTIN\IIS_IUSRS users to the full control permission to cert. This allows apps running on IIS to access cert for high-trust SharePoint communication. On Windows Server 2012 R2, Use command line tool – Windows HTTP Services Certificate Configuration Tool – WinHttpCertCfg.exe. On Windows Server 2008 R2, you can use Microsoft WSE 2.0 SP3 GUI tool, look up wildcard cert (e.g. *.niks.local) and gave full control IIS_IUSRS from the machine, restart the IIS
      If IIS_IUSERs don’t have permission, it will throw Keyset doesn’t exist error –
  • Verification Steps
    • One of my best practices while configuring any kind of complex environment is break it down into chunks to help me troubleshoot or verify as needed. Once the initial infrastructure is configured, this is the best time to test various pieces of configuration. Here are different areas you can check.
    • Provider hosted Add-ins URL domain and DNS entries are requested. Ping to test.
    • SharePoint Add-ins domain and wildcard DNS entries are requested. Ping DNS entry to check. e.g. anything.apps.niks.local.
    • Valid Wildcard Certificate is issued for SharePoint Add-ins and uploaded on the local certificate store and imported in IIS.
    • Add Management and Subscription Settings Services and Application Proxies are provisioned.
    • App domain is configured, and App Prefix is created for SharePoint.
    • App Catalog site collection for App hosting web application is provisioned with appropriate permissions.

Configuring High-Trust for Provider Hosted Add-ins

  • Run this step from SharePoint Servers – Please note that these steps need to be executed on SharePoint servers for high-trust setup between SharePoint and Add-in servers.
  • Remove existing SPTrustedSecurityTokenIssuer if exists
    • On the SP Server, Log in as Setup account to run PowerShell script and check if any previously registered SPTrustedSecurityTokenIssuer exists. If there is a malfunctioned one and if the –IsTrustBroker switch was used then the bad token issuer might be getting called. If this is the first time you are configuring the high trust add-in, then you can skip this step.
    • Run Get-SPTrustedSecurityTokenIssuer. If no Azure workflow is configured, then this command should return empty. If you get any issue other than the workflow, then run the Remove-SPTrustedSecurityTokenIssuer (pass the Id value from the above output) to delete it.
  • Configure the High Trust using Certificates
    • Run the PowerShell script from the SP Server to register cert with SharePoint by using a public (cer) key to set trust for your add-in. Please see attached PowerPoint presentation for a detailed script.
    • Each certificate in the chain is added to SharePoint’s list of trusted root authorities with a call of the New-SPTrustedRootAuthority cmdlet.
    • It is important that IssuerID is needed each time you create add-ins in Visual Studio so put it somewhere safe (e.g. 9F0FF6C4-0DA6-429B-959A-07847DF6BF37)
    • Get the Serial Number from the App Cert – ‎6114c562000000000005 (here are the steps –
  • Configure valid settings for AllowOAuthOverHTTP if needed
    • Configure AllowOAuthOverHTTP to FALSE for SSL communication between SharePoint and Provider Hosted Add-ins.
    • If any of your IIS web (either SharePoint or Provider hosted web add-in) has HTTP bindings, then you must have AllowOAuthOverHTTP to TRUE otherwise you will get 403 error

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false

High-Trust Provider Hosted Add-ins Deployment

  • High Level App Publishing and Deployment Process
    • On the DNS Servers – Make sure DNS entry is available for Add-ins URL, PING to verify.
    • On Provider Hosted Server – Create IIS Web Site and Virtual Directories to host Add-ins.
    • App Deployment
      • Develop Add-in using Visual Studio predefined templates
      • Register the High Trust Add-in in SharePoint farm using /_layouts/15/appregnew.aspx
      • Update the Web.Config file of App Web with new client Id
      • Publish the App web (remote web)
      • Use App in the SharePoint (App App to App Catalog, Install Add-in to a Site, Add App Part to the site)
  • Create Remote web to host Provider Add-in
    • Remote web can be deployed on IIS, make sure is included as features
      • Web Site Name (e.g. ProviderHostedProdApp) and local folder (e.g. C:\inetpub\wwwroot\phprodapp)
      • Add New DNS entry for remote web add-in (e.g. phprodapp.niks.local to server or load-balancer IP) and see if you can ping it
      • Bind this cert with SSL (e.g. *.niks.local), Host Header (e.g. phprodapp.niks.local), and IP (e.g.
      • Ensure .NET 4.0 framework is selected as target framework – Make sure Application Pool is using v4.0 otherwise you will get error while deploying code
    • Configure Authentication of the Remote Web on IIS
      • Disable Anonymous Authentication for the IIS site hosting Remote Web
      • Enable Windows Authentication for the IIS site hosting remote web and plan to have Provider NTLM is selected above Negotiate
    • Add Virtual Directories to host Add-ins
      • Alias (e.g. prodphapp), Path – (e.g. C:\inetpub\wwwroot\phprodapp\prodphapp)
  • Register the High Trust App in SharePoint farm using /_layouts/15/appregnew.aspx
  • Creating Provider Hosted App using VS Template
    • Visual Studio allows you to create provider hosted add-in projects using predefined templates.
  • Update Visual Studio Project to Publish App Package (Debug/Test)
    • Update the Web.Config file of App Web – VS adds ClientSigningCertificatePath and ClientSigningCertificatePassword. This requires certificate downloaded and stored on the local file system.
    • Sample Web.config: <appSettings>
      <add key=”ClientId” value=”f5b99211-2f48-4747-8af0-bdfbbcf1b1b5″ />
      <add key=”ClientSigningCertificatePath” value=”C:\Certs\NiksHighTrustCert.pfx” />
      <add key=”ClientSigningCertificatePassword” value=”pass@word1″ />
      <add key=”IssuerId” value=”9f0ff6c4-0da6-429b-959a-07847df6bf37″ />
    • No changes in the Token Issuer file in VS project – Visual studio template for Provider hosted add-in contains code to create access token based on certificate location.
  • Update Visual Studio Project to Publish App Package (Release/Prod)
    • Update the Web.Config file of App Web – VS adds ClientSigningCertificatePath and ClientSigningCertificatePassword. This shouldn’t be used for production add-ins. Instead use ClientSigningCertificateSerialNumber. Find the ClientSigningCertificateSerialNumber from the cert binded to the provider hosted add-in (e.g. *.niks.local)
    • Sample Web.config: <appSettings>
      <add key=”ClientId” value=”f5b99211-2f48-4747-8af0-bdfbbcf1b1b5″ />
      <add key=”ClientSigningCertificateSerialNumber” value=”6114c562000000000005″ />
      <add key=”IssuerId” value=”9f0ff6c4-0da6-429b-959a-07847df6bf37″ />
    • Update Token Issuer file in VS project – Since you are using on Serial Number instead of cert path and password for authorization, you need to update code to retrieve cert based on serial number – See Token Issuer section here –
  • Publish the App web and App Packages
    • Provider Hosted Add-ins are consists of two projects in Visual Studio
    • Publishing App Web Package
      • Publishing App web copies files are remote web server and deployed on IIS
      • Create AppWeb package from the Visual Studio using publish approach
        • Create Profile (e.g. NiksRemote)
        • Connection – Publish Method – Web deploy package
        • Package Location (e.g. C:\Deploy\ProdProviderHostedAppWeb\
        • Remote IIS Web Site Name (e.g. ProviderHostedProdApp/prodphapp)
        • Click Next – Release and Publish Package
    • Publishing Add-ins Package
      • Publishing App produces App file (.app extension) and that needs to be uploaded on App Catalog site to make it available for SharePoint sites
      • Create App package from the Visual Studio using publish approach
  • Deploy the App web and App Packages
    • Deploying App Web Package
      • Copy the Package to the Remote Add-ins server, make sure webdeploy is installed on the additional server
      • Open cmd file and run Appweb deployment command (e.g. C:\Deploy\ProdProviderHostedAppWeb>ProdProviderHostedAppWeb.deploy.cmd /y)
      • Verify all the contents are getting published on the IIS virtual directory
    • Deploy App Package to App Catalog
      • Navigate to App Catalog and select New App and upload .app file
      • Make sure uploaded App package is valid.
  • Use App in the SharePoint
    • Add an App to a Site – Navigate to Add App page and add App to the site – trust the add-in
    • Add App Part to the site – App client web part to App project, this should add page to the AppWeb project, upgrade Add-ins and redeploy it to the site, and you should see the App parts

Hopefully, you would be able to navigate steps mentioned in this article. For more detailed step by step guidance, please review my SharePoint Fest presentation.



This entry was posted in SharePoint 2013, SharePoint Apps, VM Scripts. Bookmark the permalink.

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s