SharePoint Hosting & Authentication Options for LightSwitch (Brian Moore)

One of the many awesome things about LightSwitch is its flexible deployment model. When you design a LightSwitch application you are actually building a multi-tier application.

Because of this multi-tier design, you can deploy a LightSwitch application in a variety of ways. Since LightSwitch apps are just web apps, you can host them on your own IIS box, third-party ISPs, or even Azure. This plays well into the new app model of SharePoint 2013 where apps are now isolated from the SharePoint server. When you install a SharePoint app, a manifest is installed into SharePoint that has information on where your app runs (among other things). Client-side code can be run from SharePoint but any apps that contain server-side code, like all LightSwitch apps, must run on a separate server outside of SharePoint. This isolation provides better stability of the SharePoint farm.

When you enable SharePoint in your LightSwitch apps, you are telling LightSwitch to do a few things:

• Create a SharePoint project with a manifest that tells SharePoint how to communicate with your app
• Add references to the SharePoint client-side object model (CSOM) so you can access SharePoint via code
• Use SharePoint to control Authentication via OAuth

There are three ways you can host a SharePoint 2013 app. Provider-hosted, Autohosted and SharePoint hosted. SharePoint hosted apps do not have a middle-tier / database backend – they are simply client-side JavaScript/HTML apps so this type of hosting does not apply to LightSwitch. Since LightSwitch apps are multi-tier web apps there are a couple ways you can host these.

Autohosted

With Autohosted apps, the web site and database are provisioned automatically into Azure each time app is installed. The data is provisioned into SQL Azure and the middle-tier into an Azure website. This means that each instance of your LightSwitch app that is installed into SharePoint is isolated from all other instances on other SharePoint sites.

While autohosting is a very quick and easy way to get a app running there are a few downsides.  One is that you don’t have access to the LightSwitch web app or data outside of SharePoint and if you remove the app from SharePoint, everything is deleted – even the data.  Also, autohosting is not yet available for the Office Store, though it works fine for a private app catalog in Office 365.

If any of that concerns you, not to worry, you can still host your LightSwitch app for SharePoint just as you always have with the other option.

Provider-hosted

Provider-hosted apps give you the flexibility of hosting the web application and database wherever you want. However, with flexibility comes responsibility. With this model, all SharePoint app instances share the same middle-tier and data so you will need to provide your own tenant isolation (multi-tenancy).  You also need to manage availability – if your server goes down, all your SharePoint apps stop working.

However, the benefit is that you own the data and have access and control over the entire application. LightSwitch supports row level filtering and access control so you can design your database appropriately.  You could also deploy separate instances of your app for each installation.  Essentially, this is the same thing you would do today taking into account your need for multi-tenancy.

App Authentication

Because your app runs outside of SharePoint we need to have a way to authenticate the app so not just any ol’ app can go communicate with your SharePoint site and data.  Again, LightSwitch makes it easy for you to take advantage of the options SharePoint offers and just like hosting, you can change them whenever you need to.  You can set these options when you enable SharePoint and also when you publish.

ACS

ACS is short for “Access Control Service” which is another server that brokers authentication between your app and SharePoint.  Your app will have a “secret” known to SharePoint and can use it to authenticate via ACS.

High-Trust or Server-to-Server

In this configuration, a certificate is installed on the SharePoint server and the server running your app.  The app needs to know where the cert is installed on the server (i.e. where is the pfx file) and the password.  Then the app can use that cert to prove to SharePoint who it really is…  There is a fair bit of manual configuration to enable this and you can find that on MSDN.

So that’s great info – a very terse description (trust me you want it to be terse), but what should you use?  For starters, it depends on where you want to host your app (On-prem or Cloud) and where SharePoint is running (On-prem or Cloud).  This will make some decisions for you.  I’ll give you my personal preference as well but first here’s the matrix… 

¹ ACS on-prem is also known as a “hybrid” mode which requires the farm be configured for ACS
² Autohosting is not yet available on-premise 

So you you don't have spend a lot of time deciding because it may be decided for you – if you’re running in the cloud, you must use ACS and this doesn’t actually require you do do anything other than tell LightSwitch that’s what you want to use.  On-premise you have the option, but my personal preference is to use ACS whenever possible, simply because you never have to worry about anything related to app auth – LightSwitch will take care of it for you.

If you’re working on-prem and have the option – a few pros/cons.  ACS will require domain admin involvement to get this up and running.  Trust needs to be established between Azure and your internal network.  There’s more to it than that (again being terse) but once that’s done, it’s done.

For High-Trust apps, you have to manage the cert, install it on the SharePoint server, install it on your dev box and install it on the server the LightSwitch app will run on when deployed.  You might have different certs for dev and production, different certs for each app (meaning you have to track all these) or you might have one cert for everything which can be a pain if you ever have to revoke that cert because everything using it will need to be updated.

Now you also may have some “internal restrictions”.  For example, since running ACS on-prem requires some domain admin involvement to setup ACS with your on-prem SharePoint server, you might have to wait to get started.  If so, you can configure you app to use High-Trust while you wait for ACS.  Remember that LightSwitch will let you change this setting whenever you want and it won’t affect your code.  You could also sign-up for a trial of Office 365 and develop against that while you’re waiting.  Hopefully, by the time your trial is done, you’re either hooked or ACS is configured ;)

I’ve used both for months now and you likely won’t notice the difference between on-prem and cloud, you *will* notice the difference between ACS and High-Trust.  ACS is the way this stuff should be done, just in case you have a say in the matter…. 

The LightSwitch Publish Wizard

So you’re done with your app…  You might have had to go through some other blogs to get here, but let’s walk through how the LightSwitch Publish Wizard works.

Those options covered above come into play when publishing.  The options may be determined by your customer’s environment, for example if they’re using Office 365, but in any case, here’s what you’ll come across when publishing.

The first option is how you want to host your app.  If you autohost your app, then you just need to provide the data connection information, if you have it, and you’re done.  Remember that when autohosted, you app will be provisioned in Azure automatically by SharePoint so that’s all there is to publishing an autohosted app. 

When your app is provider-hosted, you need to specify how you want your app to authenticate.  This is the “ACS vs. High Trust” choice you make when you start developing with SharePoint.  In most cases, this is likely to be the same during development and publish but it doesn’t have to be.  Also, even if the type of authentication is the same, the values or artifacts used are likely different between a dev and production environment.  So we have the option to configure those things during publish.

If your SharePoint server or farm is using ACS then all that’s required is a ClientID and Secret that’s shared between your application and SharePoint.  You can get those values by from your SharePoint site where the app will be installed.  You get them by visiting a page on the SharePoint site – found at http://mysite.sharepoint.com/_layouts/15/appregnew.aspx.  Just add _layouts/15/appregnew.aspx to the end of the url for your site.  Here you can generate both the Client ID (or App Id as it’s referred to at times) as well as the App Secret – these values apply to your server farm, not just the site you collect them from.  Once generated, you need to keep this information in a safe location so that another app doesn’t get the ability to impersonate your app.  You also need to supply the App Domain for your app, which is where the app will be hosted (e.g. yoursite.azurewebsites.net).  So it’s not just a matter of stealing the App ID and Secret in case you were wondering.  Finally, if you ever need to retrieve or change some of these settings with SharePoint you can do that by visiting appinv.aspx but you need to know the App Id to retrieve anything.

Once you have those values, you can complete the publish wizard. 

Now if you’re running in a High Trust configuration, you don’t need the client secret, but you do need the App ID and the certificate information as you did during development.  Ideally, this information is different than what you used during development since the production server should have a different certificate…  It doesn’t have to be different of course, but it should be ;)

Also, you might be wondering why you never needed a secret (or ID for that matter) before publishing.  That’s because Visual Studio handles all of that for you during development.  Your app still uses an id and secret, but you never have to worry about it until you’re ready to publish your app.

The last thing you need then is the Client ID or App ID.  This also comes from the appregnew page and you need this whether you’re using ACS or High Trust. 

Now, the LightSwitch publish wizard will put this information into web.config for the app to use at run-time.  Once you’re done with the publish, you’ll need to install your app package file that’s generated by publishing into the SharePoint catalog -- but we’ll cover that in another post.

-Brian Moore, Program Manager LightSwitch Team