Modernizing SharePoint? – My thoughts on SharePoint Online Document Library Experience Updates

Update on May 5th – Drawbacks mentioned in this article are no longer drawbacks if you are using new SharePoint Online experiences. New SharePoint Online experiences announced as “Future of SharePoint” event on May 4th spans not only document libraries but throughout SharePoint including new SharePoint Team Site experiences. See Updates herehere, and here. I never had a blog article invalidates itself in few weeks. It’s a power of modern product updates & release cycle. I still think communication and feature rollout could have been better.

Microsoft has pushed out one more “Sneaky” release in Office 365 relating to SharePoint Online document library experiences. If you have “First Release” tenant, you will start noticing the new banner on SharePoint online document library page stating – “Check out new document library look!”.

Doc library UX Banner

I call this “Sneaky” release. Even though this is a huge change in SharePoint (first significant Document Library UI change since SharePoint 2003/2007 days, almost 10-12 years ago), it was never announced on Microsoft Office blogs. I have heard this news on Twitter after seeing few posts from MVPs and other community leaders regarding this release.

Unlike MVPs or other community leaders, my thoughts on this change are bitter-sweet. On the one hand, I love this new modern experience with lots of core features stands out in UI for end-users. On the other hand, I hate the navigation experience from SharePoint Online document library UI to One Drive for Business document library UI. More on navigation concerns later.

If you have never seen new SPO document library experience, here is the preview:

This is a classic SharePoint Online document library experience with the invitation to try out new experience:

SPO OLD Doc Library UX

This is how new SharePoint Online document library experience looks like (with an ability to rollback to classic view for the time being):

SPO New Doc Library List View UX

SPO New Doc Library Grid View UX

Let’s first talk about Pros. I hugely welcome modern UI of new SharePoint Online user experiences. Not only Microsoft had bubbled up many key features like easy actions but modernized the UI along with it.

Here are some of the highlights of new features and I must say – I love them all.

  • Library Level Features
    1. Ability to Pin documents as Highlights above the library view
    2. Ability to “Alert Me” from quick action bar
    3. Ability to have Grid view with previews, rather than traditional list view
  • Document Level Actions
    1. Ability to see “History” on the right bar
    2. Document Action Bar – Ability to get a link, ability to Move to another location (one of the long standing issues with traditional UI)

Now, let’s talk about major drawback. With all the love for new UI, one of the major downside of this new update is what happens to the existing collaboration sites. Even though Office 365 have new workloads rolling out every few months to tackle modern collaboration like Yammer Groups, Office 365 Groups, Planner, Delve, many of our customers are still using SharePoint team sites for document collaboration.

Along with SharePoint team sites, they are accustomed to using “Blue” SharePoint/Office 365 global OOB UI and SharePoint Online ribbon bar. One of the major issues with new UI is end-users will require traversing back and forth between SharePoint Online UI (Blue Globar bar with Ribbon) and OneDrive for Business UI (Black Global bar without Ribbon) while using document libraries and that’s where the challenge is.

Many of us additionally apply SharePoint online themes (recommended by Office 365 PnP as supported version of branding), which would affect seamless UI experience and navigation as users are accessing team sites, document libraries, and documents. My only hope here is Microsoft have further plans to roll out SPO changes to reflect this new UI in SPO to match overall Office 365 experience.

But, Wait – There is a solution to all these – Having all said that, Microsoft didn’t leave us with this as forced update. You have the option to use old or new experience depending on your organization’s appetite for change. Each document library has the option to use new or old experience. This would allow document library owners to use whatever experience they like. Additionally, there is a global SharePoint Online administrative setting to apply this change to all document libraries in SharePoint online team sites. Few tips here – library-level settings will definitely affect the governance policies and how organizations want to standardize the document library experiences. Few more things to worry about as you trying to govern your environment. 🙂

You can manage list document library experiences settings from library’s advanced settings page. There are three options here:

SPO Library Admin Settings

  • Default experience set by my administrator – Configured at the SharePoint Online Administrative page.
  • New experience – New experience with OD4B UI
  • Classic experience – Classic Old and Gold SharePoint document library view

Here is the screenshot of SharePoint Online Admin Setting.

SPO Admin Settings

Here are my initial reactions on Twitter. I am hoping to have more positive reactions and better document library experience stories as we go through initial period.

Nik's reaction 0.PNG

Nik's reaction 1.PNG

Nik's reaction 2.PNG

SharePoint Online is changing!!! Good luck SPO!!!

Additional Resources and Community Reactions

Posted in Office 365, SP2013 Online | Leave a comment

Nik’s SharePoint Saturday Chicago Suburbs 2016 Session Deck on Modern Intranet Development on SharePoint and Office365 is Available

Thanks to everyone who was able to attend my session at the SharePoint Saturday Chicago Suburbs 2016. It was a great to see familiar faces and old friends in a reasonably attended session.

I had a fantastic fun walking attendees lessons I have learned while developing Intranets on SharePoint and Office 365 last few years. It’s great to share some of the best practices I have compiled and how I would design intranet on these platforms in future.

Title: Best Practices for Intranet Development on SharePoint and Office 365 Platforms
Session Abstract – Development of successful Intranets on ever changing SharePoint and Office 365 platform requires an understanding of available options and how to apply them. Nik Patel from Slalom Consulting has designed and built four different intranets in four years with various best practices each with unique flavors and customization options available at that time. Nik will take attendees through architecture options in past and future and provide practical guidance for future Intranet development on SharePoint and Office 365 platform. This session is for both beginners and advanced level developers and architects.

As promised, here is my session deck available through Slide Share. Feel free to download and reach out to me if you have any questions.

I have recently posted few SharePoint development best practices articles. These can be used as additional sources along with Office 365 PnP to make the decision in tricky architectural trade-offs.


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

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 | 3 Comments

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