Cheat Sheet to Troubleshoot SharePoint Provider hosted High-Trust Add-ins – 401, 403, 404, and Misc Errors

Anyone who has worked on provider hosted high-trust add-ins for SharePoint 2013 on-premises environment knows if an environment works, it works like a charm. If it fails, it’s worst thing as IT Pro you may encounter. Most of the errors while troubleshooting provider hosted high-trust configuration are mostly related to authentication and add-ins & SharePoint communication. Many of these errors are so generic like 401, 403, and 404 errors that it can quickly raise the frustration level along with the waste of hundreds of hours.

With this cheat sheet, I am planning to share my usual suspects and hoping to keep it updated as I encounter more weird errors in SharePoint provider-hosted high-trust add-ins configuration.

Microsoft Resources for Troubleshooting Apps

Usual Suspect Areas to look at

  • Expired certs on IIS, local Windows cert store, and SharePoint trust store (including all the chain certs)
  • Invalid Get-SPTrustedSecurityTokenIssuer
  • Invalid Get-SPTrustedRootAuthority
  • Invalid Cert Serial Number or Certs information in web.config
  • Invalid Alternate Access Mapping
  • Invalid HTTP or HTTPS binding in IIS
  • Missing DNS entries
  • Depending on your needs, you would need to set App permission in App Manifest
  • Validate Provider Hosted App IIS site – Enable Windows Auth, NTLM as preferred provider, App pool runs under 4.0 and ApplicationPoolIdentity

Myths – Invalid Causes called out in blogosphere

  • Certs Chain must be installed and imported in both local Cert store and IIS on both SharePoint and Provider Hosted Apps servers.
    • Removing RootCA & High Trust cert from SharePoint trust store (accessible from central admin) not affecting how Provider-hosted apps work, it works regardless.
    • According to API cert expert, Brian… IIS should have only lowest level cert what’s needed for binding, all parent chain certs shouldn’t be in IIS.
  • No Routing Web App on SharePoint Servers – This throws 404 error for SharePoint hosted, and Store hosted apps but works fine for Provider-hosted apps, routing web app is required for SharePoint hosted app.
  • You need to disable Anonymous Authentication on Provider hosted app IIS website – no reason to do this unless you want to do this as best practice.
  • NTLM has to be preferred provider (above Kerberos) for Windows Auth on Provider hosted app IIS website – no reason to do this unless you want to do this as best practice.
  • To get the title of the site, you would need to set App permission in App Manifest Depending – No need for this for title info.
  • SharePoint and App hosting servers should be in same time zone. No need for this either.

Error – An Unexpected error has occurred while installing app

  • This may happen if App was already installed with upper version and you are redeploying app using lower version to the same site. e.g. I had a site collection where I deployed an app with version. I have uninstalled an app and repackaged with version and deployed to the App Catalog. This caused an error while installing an app to the same site collection again. New version app would work fine with new site collection where this app never been installed earlier.
  • Myth – Many blogs and forum say – cleanup App Catalog recycle bin and that didn’t fix my issue.

Error – Blank Page while accessing installed app

Error – 401 Error – Unauthorized while accessing installed app


  • Possible Causes:
    • No Windows Auth is enabled on the Provider Hosted App IIS website.

Error – 401 Error – Unauthorized while running app, SharePoint-App communication issue

401-Unauthorized 2.PNG

  • Possible Causes:
    • Issuer ID is invalid or has uppercase letters or Issuer ID has space in Appweb web.config file.

Error – 403 Error – Forbidden while accessing installed app, SharePoint-App communication issue


  • Possible Causes:
    • Client ID is invalid, or Client ID has space in Appweb web.config file.
    • Get-SPSecurityTokenServiceConfig AllowOAuthOverHttp setting is invalid. It must be true if one of the SharePoint web application or Provider hosted App IIS website have HTTP binding. If both SharePoint and Add-ins using SSL, it should be false. In many cases, if you have HTTP binding on SharePoint in addition to SSL and if Add-ins using SSL with AllowOAuthOverHttp=false, may cause an error.

Error – 404 Error – While accessing installed app


404 2

  • Possible Causes:
    • DNS Entry Issue – Either Wrong or NO DNS entries – Try to ping the app URL to see if it reaches to correct server IP or F5 App Pool IP.

Error – An error occurred while processing your request – while accessing installed app

  • Background Note – This error gets generated by Visual Studio boilerplate code for SharePoint Context and TokenHelper.
  • Possible Causes:
    • Certificate Serial Number is invalid in Appweb web.config file.

Error – Keyset does not exist – while accessing installed app

Background Note – This error is related to SharePoint app running in IIS can’t access High Trust configured on Provider hosted cert store to initiate communication to SharePoint.

Possible Cause – If IIS_IUSERs don’t have permission to high trust on local cert store, it will throw Keyset doesn’t exist error – 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.

Error – Sorry, Something went wrong – while adding/installing an app to the site – App differs from another App with the same version and product ID

Sorry something wrong

This is worst kind of error where it’s really hard to troubleshoot. In most cases – you have to look into ULS logs to troubleshoot as this isn’t a glaring mistake. Luckily, that mistake does provide you ULS correlation ID which you can use to troubleshoot.

In my case – I had come across this error in ULS log.

Issue – 11/03/2015 14:44:28.00   w3wp.exe (0x1C28)                       0x0548  SharePoint Foundation                 General                                       ajlz0       High       Getting Error Message for Exception System.Web.HttpUnhandledException (0x80004005): Exception of type ‘System.Web.HttpUnhandledException’ was thrown. —> System.InvalidOperationException: The provided App differs from another App with the same version and product ID.     at Microsoft.SharePoint.Lifecycle.SprocWrappers.CreateApp(SqlSession dbSessionWrapper, Byte[] fingerprint, Guid siteId, Guid productId, Version version, String title, String contentMarket, String assetId, SPAppSource source, String tempIconUrl)     at Microsoft.SharePoint.Administration.SPApp.CreateAppAndCommitPackage(SqlSession session, Byte[] fingerprint, String path, Guid siteId, String assetId, String contentMarket, SPAppSource source)     at Microsoft.SharePoint.Administration.SPApp.CreateAppUsingPackageMetadata(Stre… 4d143e9d-3578-6086-1f97-858d6df686c1

There are various online articles and places this error has been discussed and folks have solved many different ways –

Have you come across any other scenarios not discussed here? Plan to post in the comments section to increase awareness of your particular situation. You never know – it may help someone out there.


Posted in SharePoint 2013, SharePoint Apps | 1 Comment

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.



Posted in SharePoint 2013, SharePoint Apps, VM Scripts | Leave a comment

Reviving SharePoint Hybrid Lab by Restoring Expired Certificates

Over Christmas break, I had to revive my SharePoint hybrid lab after it was ideal for few months and during that period ironically all the certs were expired which gave out the end-to-end SharePoint hybrid configuration.

As an overview, my SharePoint Hybrid Lab consists of Microsoft Azure-hosted SharePoint 2013 On-premises environment with Office 365 hybrid trust.

I have 3 VMs in Microsoft Azure for SharePoint 2013 on-premises environment – All-up SharePoint 2013 VM with AD and SQL, ADFS+Azure AD Sync VM for SAML provider, and WAP VM acting as a reverse proxy. This environment is trusted by Office 365 tenant syncing on-premises users in Office 365 and configured with both inbound and outbound SharePoint search.

Hybrid lab

Here are the high-level steps one needs to take to renew certs and revive the SharePoint 2013 on-premises and SharePoint Hybrid environment. Please note – these steps excludes Office Web Apps and Provider Hosted Apps configuration.

Fix On-Premises First

Fix SharePoint SSL

  • Symptoms – Verify that NTLM or SAML SharePoint SSL URL doesn’t work from the server itself or internal domain machines
  • The first request updated SSN URL cert – New cert from cert provider, log on to SP Serer, create CSR from IIS, send CSR and request new cert, cert providers will issue cert, download cert, import cert into IIS (cleanup old one).
  • Fix on-premises SharePoint SSL – bind cert in IIS, test with NTLM (may error out if STS cert is expired, remember hybrid requires replacing OOB STS cert), will error out in SAML for ADFS especially if any of ADFS communication/token signing certs are expired.
  • Fix SP STS cert – Regenerate STS self-signed cert from IIS (or request from third-party same as URL cert similar as 2nd bullet), export both PFX and CER files, update the STS provider cert using Set-SPSecurityTokenServiceConfig, this should return NTLM SP site
  • This should allow users internally login to SharePoint w/NTML Auth

Fix ADFS Integration

  • Symptoms – SharePoint w/NTLM Auth works fine, but w/SAML auth doesn’t work yet.
  • Fix ADFS communication certs (might be same as SSN URL cert) – copy ADFS communication cert to ADFS server, import cert in local store (cleanup old one), add new cert as communication cert, update ADFS SSL cert using Set-AdfsSslCertificate PowerShell, validate if ADFS signing works otherwise signing certs may be expired
  • Fix ADFS token signing certs & SP trust – Use PowerShell to refresh the token signing cert, export token signing certs to SP servers, add token signing certs on SP local cert stores, Update SP identity issuer with new token cert using Set-SPTrustedIdentityTokenIssuer, Update certs on central admin trust, validate if ADFS redirect/trust works.
  • This should allow users internally login to both ADFS sign in and SharePoint w/SAML Auth

Fix WAP – ADFS Proxy Integration and Startup Issues

  • Symptoms – ADFS sign in should work fine from WAP server but won’t work outside of WAP server from the public internet.
  • There are two certs – ADFS Proxy Trust and ADFS Communication Certs – One of them or both may be expired.
  • Fix ADFS communication certs (might be same as SSN URL cert) – this is for both client and server authentication – copy ADFS communication cert to WAP server, import cert in local store (cleanup old one), update WAP SSL cert using Set-WebApplicationProxySslCertificate PowerShell, validate if ADFS signing works from outside otherwise WAP trust may have been broken, easiest way to check is ADFS trust cert in local cert store may have expired.
  • Fix ADFS Proxy Trust cert – this is for client authentication – You need to run through these steps if ADFS proxy trust cert is expired or if you renewing ADFS communication cert to establish trust with ADFS server – Usually this cert gets renewed for 2 weeks if server is running, reestablish WAP-ADFS trust by running Install-WebApplicationProxy, it should update ADFS Proxy cert, remove old one.
  • ADFS signing should work fine from outside.

Fix WAP – Published SP App rules

  • Symptoms – SharePoint NTLM & SAML should work fine from WAP server but won’t work outside of WAP server from public internet
  • Update certificates for WAP published application rules using Set-WebApplicationProxyApplication command. Usually, there are two external entry points for SharePoint hybrid – one for the end user (ADFS SAML-based) and second is for Office 365 service call (NTLM/Cert based). Both WAP entry points certs needs to be updated. For ADFS, update only ExternalCertificateThumbprint. For NTLM/Cert based, you need to update both ExternalCertificateThumbprint & ClientCertificatePreauthenticationThumbprint (without this you will get 403 error)
  • Intranet SharePoint SAML should work fine w/ADFS auth, and IntranetExt NTLM should work with fine w/cert based authentication from outside.

Fix Office 365 Hybrid Configuration

Fix Office 365 Federation

  • Symptoms – You may get warning on Office 365 admin center regarding federation cert renewals, this would affect Azure AD Sync and users no longer able to login in Office 365 using on-premises IDs
  • From ADFS server, Run Update-MSOLFederatedDomain –DomainName to update the cert using Azure AD PowerShell Window
  • You should no longer receive any alerts, and you should be able to login to the SharePoint site using on-prem ID

Fix Hybrid ACS Trust & Outbound Search

  • Symptoms – You won’t be able to search SharePoint Online data from SharePoint on-premises Search Center
  • From SP server, Run New-MsolServicePrincipalCredential to upload new valid STS cert, you may want to use Remove-MsolServicePrincipalCredential to delete the expired one
  • No need to update SPO SPN using Set-MsolServicePrincipal, No need to reregister App Principal using Register-SPAppPrincipal, No need to set Realm using Set-SPAuthenticationRealm, No need to recreate ACS Proxy & Token Issuer New-SPAzureAccessControlServiceApplicationProxy & New-SPTrustedSecurityTokenIssuer
  • You should be able to search SharePoint Online data from SharePoint on-premises Search Center

Fix Inbound Search

  • Symptoms – You won’t be able to search SharePoint On-Premises data from SharePoint Online Search Center
  • Upload updated communication cert for EXT URL in Secure Store App which is used by SharePoint Online result source.
  • You should able to search SharePoint On-Premises data from SharePoint Online Search Center


Posted in ADFS, Office 365, SharePoint 2013, SharePoint 2016, SP2013 Admin, VM Scripts | Leave a comment

Hiding SharePoint 2013 Recent Menu on Left Hand Navigation

Every product has useless features. SharePoint isn’t an exception. There are various features like pesky “default send an email option while sharing sites with the users.” Every one of us has invited “everyone” and left that check box on to send an email to all 40,000 people in the organization in one lifetime or other. Another big one is annoying “recent” menu option added every time someone adds new document library or app in the left-hand navigation.

Hiding “Recent” Menu is one of those features I have to tackle every time I have to design custom UI for the SharePoint especially for the Intranets. Although this is well documented on the MSDN, this is a self-note for me.

Plan to have this in master Custom JavaScript file which gets called from the master pages or page layouts (if there are no custom master page). Please note this code requires jQuery loaded before this javascript.

Here is the code from Master Page.

<head runat="server">

<!-- jQuery -->
<script type="text/javascript" src="<asp:Literal runat='server' Text='<%$SPUrl:~sitecollection/Style Library/App/SiteBranding/Scripts/jquery-1.10.2.min.js%>' />"></script>
<!-- Main App JS-->
<script type="text/javascript" src="<asp:Literal runat='server' Text='<%$SPUrl:~sitecollection/Style Library/App/SiteBranding/Scripts/app-master.min.js%>' />"></script>


Here is the code from app-master.js

(function (window) {
$(document).ready(function () {

//hide annoying recent menu items-


Hope this saves someone time. As I mentioned above, this is reference article for me rather than researching again.

Posted in SharePoint 2013 | Leave a comment

Master List of SharePoint 2013 On-Premises and SharePoint Online Custom Development Best Practices

Few years ago, I have posted master list of SharePoint 2010 custom development best practices which was focused on the full trust and sandbox SharePoint customization models. To date, it’s been one of the most popular articles on this site.

Over the last year, as I have been leading few SharePoint intranet implementations, I have compiled list of best practices for modern SharePoint development which would be applicable to SharePoint 2013 on-premises, SharePoint 2016 on-premises, and SharePoint Online. This article lists various best practices I have applied and can be enforced in the team based SharePoint custom development.

  1. Customize for Cloud in Mind – Plan to write customization for future upgrade to SharePoint Online even though you have invested in SharePoint On-premises as of now. Be cloud-ready even though you are on on-premises.
  2. Avoid Full Trust Model – Avoid Full trust code model (aka features and solutions framework). No code should be deployed to the SharePoint servers. Avoid IISReset and deployment downtime. Plan to use add-ins model remote provisioning approach rather than features and solutions framework.
  3. Avoid Sandbox Model – Avoid both declarative and code based sandbox solutions model even though declarative model is supported by Microsoft as of now. You never know when Microsoft shuts down Sandbox code service in the Office 365. Plan to use add-ins model remote provisioning approach rather than features and solutions framework.
  4. Use Office 365 Patterns and Practices – You must have heard about this unless you live under the rock. Plan to use Office 365 PnP Github project for source code and Nuget packages to reference from your projects to use Office 365 patterns and practices framework which contains open source patterns to replace existing full trust model functionalities. It is important to note that even though PnP is focused on Office 365, it can be tweaked to use for SharePoint On-Premises. This is must have in SharePoint developer’s armory.
  5. SharePoint Artifacts Provisioning Approach – Provider hosted add-ins vs Console Applications vs PowerShell – Plan to use provider hosted add-ins or console applications remote provisioning approach to deploy common SharePoint artifacts like custom columns, content types, list instances, web parts, master pages, or page layouts which we used to deploy using Full Trust or Sandbox feature schema model. This is code based approach to deploy SharePoint artifacts from remote server using CSOM APIs. As far as either using Provider hosted add-ins model vs console applications, my personal preference would be console applications to deploy artifacts which would lessen the overhead of Provider hosted add-in infrastructure. Additionally, Office 365 PnP team has additional approaches like PowerShell to deploy artifacts remotely.
  6. Site Provisioning Approach – Plan to avoid any provisioning approaches introduced during SharePoint 2010 and earlier including Save as Site Template, Site Definitions, Web Templates, or full trust code based models. Best way to approach site provisioning is using remote provisioning code based model (provider hosted add-in or console applications) which would allow you select any OOB or predefined site templates for base site creation and apply additional features or provision artifacts as necessary to flush out fully functional sites.
  7. SharePoint Hosted vs Provider Hosted Add-ins Model – My main criteria here is whether you will require server side code or not. If you won’t and can get away with HTML, JS, CSS, REST/JSOM client side approach, plan to use SharePoint hosted model. There are many patterns introduced in Office 365 PnP for remote provisioning will require provider hosted add-in model.
  8. Provider Hosted Add-in Model vs ASP.NET standalone applications for SharePoint On-premises – For the full blown custom applications like timesheet or dashboard, it would make sense to avoid SharePoint as container for application entry point. Depending on your need, it may make sense to have standalone ASP.NET application if you can get away with complex certificate based High trust infrastructure to have SharePoint access token to access SharePoint APIs. Otherwise, plan to use Provider hosted Add-in model approach for the standalone applications to use the benefits of SharePoint security model and high trust authorization tokens. My personal preference here to use Provider Hosted Model to make security configuration easier.
  9. Provider Hosted Add-in Model vs Office 365 Apps/ASP.NET standalone applications for SharePoint Online – For the full blown custom applications like timesheet or dashboard, it would make sense to avoid SharePoint as container for application entry point. Depending on your need, it may make sense to have standalone ASP.NET applications/Office 365 Apps hosted in Azure using ADAL API to authenticate against SharePoint online and Office 365 APIs to build custom standalone applications rather than provider hosted model. Additionally, you can make Office 365 Apps available through Office 365 App Launcher. My personal preference here to use Azure Standalone applications with ADAL APIs.
  10. High Trust vs Low Trust Provider Hosted Add-in Model – If you have 100% full investment on the on-premises, you have no other choice but apply High Trust provider hosted add-in model for the remote provisioning, custom widgets or stand-alone application. If you have invested or planning to invest in cloud and afford hosting customization in Azure, it would make sense to start with Low Trust provider hosted model for both SharePoint on-premises and SharePoint online.
  11. Custom Master Pages in SharePoint On-Premises vs SharePoint Online – This is extremely controversial guideline from the Office365 PnP team. PnP best practices are around avoiding custom master pages where Microsoft may push out future upgrades to OOB master pages which may not exist in your custom master pages which further break the application customization. I am not in 100% agreement with one law to rule them all. My take here is it depends. Unfortunately there are many scenarios like publishing intranets may require branding where you can’t avoid custom master pages. If you are branding in SharePoint Online, plan to avoid custom master pages if you can get away with themes or other UI approaches where you can alter the page layouts on fly. If you can’t avoid custom master pages, plan to document what changes have made in custom master pages and be ready to make future changes in master pages applied by Microsoft. If you have SharePoint On-premises, you have full control over the upgrade and testing any new funtionalities introduced by the Microsoft. Having custom master pages in the SharePoint on-premises don’t have same risk or urgency as SharePoint Online where you have no control over upgraded features pushed out without validation.
  12. SharePoint HTML Tag IDs References in SharePoint On-Premises vs SharePoint Online – This is much similar as Master Pages. Plan to avoid referencing HTML Tags with IDs in your client side code especially in the SharePoint Online. Due to any future update in SharePoint Online may change HTML IDs, it’s safe to avoid them all together. SharePoint On-premises story is little bit different since organizations have full control over their upgrade timeline and enough time to test in the staging environment. Even though risk is lower especially if you document them, I would still avoid referencing HTML IDs on the on-premises as well.
  13. REST vs CSOM – Plan to use REST over CSOM while retrieving SharePoint data from custom applications or web parts. REST is lightweight even if its chatty and provides faster performance in most cases especially when you are waiting for sp.js to load to make SharePoint calls.
  14. REST Query best practices – This is classic SQL days best practice. Query only what you need. Specify only fields you would need in your REST and CSOM calls.
  15. Content Search vs Content Query Web Part – Plan to use Content Search web parts over  Content query web parts in most cases especially if you aren’t require to present results or roll-ups in the real time. Content Search web part would perform better and easy to customize with preferred web based technologies like HTML5, CSS3, and JavaScript rather than complicated slow-performing XSLT. Only downside of Content Search web parts are it’s dependency on freshness of Search Index. Read here for more details.
  16. Content Editor and Script Editor Web Parts vs Add-in App Parts – Plan to use content editor and script editor web parts as a starting point for most of the custom widgets rather than Add-in based App Parts. App Parts have huge limitation of rendering widgets in IFrames and complex infrastructure to support add-ins tokens. Unless you are packaging your widgets for the store and some of other reasons mentioned here, in most cases OOB web parts would provide more benefits. They would allow you to build custom UI using HTML5, CSS3, JavaScript frameworks, and CSOM/JSOM/REST APIs.
  17. App Script Part Pattern for Responsive Sites – This is best of both worlds mentioned above. Plan to use App Script Part pattern rather than standard Add-in model App Parts for responsive sites. App Script Part is nothing but script editor web part deployed by Add-in model. Since App Script part is based on HTML, CSS, and JS, it’s easy to make it responsive rather than App Parts which are relying on unresponsive IFrame technologies. You can learn further here.
  18. JS Link to Alter Lists UI – This feature introduced in the SharePoint 2013 to alter how list data or list forms displayed without any server side code changes. This is must have in developers armory. Look out for Wes Preston’s blog or Office 365 PnP for detailed samples.
  19. Avoid Suite Bar customization in SharePoint Online – This is part of hard lessons learned by many organizations over the last few years. As Microsoft slowly and slowly standardized the Office 365 suite bar, it’s increasingly isolated from SharePoint Online codebase. Plan to avoid any customization to avoid runtime errors due to any future Microsoft design changes, rather use Office 365 themes to customize.
  20. Standardize Provider Hosted High-Trust Certs and Registered Add-in IDs in a Team Based Development – Standardize Apps cert location, password, app ids in multi-developer team environment to avoid overwriting web.config while checking in and out from the source control envrionment. In a team based development, it is common to have developers with their individual SharePoint VM instances. Since High-trust code base requires certificate location and password for add-in tokens, plan to have all developer high trust certs with same name, same password, and same location to avoid multiple AppWeb web.config files for each developers. In addition, plan to have same add-in registration IDs (App Secret can be different since it’s not used by TokenHelper class) to avoid different AppWeb web.config files for each developers. Usually best practice should be first developer generates AppIDs and pass that information to the other developers to ensure web.config files are same for all developers.
  21. Use High Trust Certificate Serial Number for the Production Environment – Plan to use certificate serial number for the production high trust token helper rather than visual studio generated certificate location and password information. It isn’t a good idea to have a certificate downloaded to the servers and password stored in the web.config in the production environment. It’s OK to be dependent on VS tokenhelper class for certificate location based authorization in the development or staging environment. You should rather change your TokenHelper code to look up high trust certificate using serial number for the SharePoint access tokens in the production release. Plan to use Technet article for the code and how to publish provider hosted high-trust add-ins in the production with the best practice.
  22. Avoid Collaboration and OneDrive for Business Sites Branding – Avoid applying custom master pages and branding on collaboration and OneDrive for Business sites. Major use case for these sites are real-time file collaboration and usually there are no need for file collaboration branding. You may apply organization logo or custom theme to personalize environment but there are no need for full blown branding which usually requires for the intranets or publishing sites.
  23. Minify JS and Use CDNs wherever applicable – This is standard client side best practices especially your browser would be relying on cached version of smaller JavaScript for better performances.
  24. Must have CodePlex Tools
    • SharePoint Manager 2013 – Plan to install SharePoint Manager 2013 from the codeplex on your SharePoint developer VM. It is a SharePoint object model explorer and enables you to browse every site properties on the local farm by browsing through SharePoint Server Side Internals.(
    • SharePoint Client Browser for SharePoint Online and SharePoint On-premises – Plan to install SharePoint client browser on your machine to browse site properties without having dependent on the SharePoint VM. This tool can be installed on any machine and allows you to learn SharerPoint internals using client APIs. (
    • SharePoint 2013 Search Query Tool – Allows you to validate and debug search queries against the SharePoint 2013 Search REST API. This is incresingly important as we build custom rollup applications using Content Search Web Parts. (

I will continue update this article based on lessons I will learn and new guidelines recommended by Microsoft and Community. In addition to this, please plan to follow Office 365 Patterns and Practices and brilliant Vesa for latest guidelines.

Last but not least, please let me know if I have missed any of your best practices or if you aren’t agree on any of these best practices especially my take on custom master pages. Enjoy!!!

Posted in Office 365, SharePoint 2013, SharePoint 2016, SharePoint Apps | Leave a comment