Security in SharePoint Apps - Part 3

Previous:  Security in SharePoint Apps - Part 2 

In the first two parts of this series we looked at what an App Principal is and what the security context is that we use when a request comes into SharePoint.  Now that we have those basic components of the framework defined, let’s talk a little about the types of trust we use for Apps in SharePoint.  We have two types of trusts for apps in SharePoint, which we call Low Trust and High Trust (sometimes also known as S2S).  Now that you know about App Principals and security contexts, how do these things differ between the two trust models?

In the low trust model, SharePoint provides a context token, that includes a refresh token, that has information about who the user is what the App is.  The App can use the refresh token to get an access token, and the access token is what’s actually presented to SharePoint when the request is made.  Remember in Part 1 when I described handing SharePoint a “note” that said what the App is and what it could do?  That is the role of the access token.

In a high trust model, the App tells SharePoint who the App AND who the user is.  How your App comes up with the user identity is completely up to you – but we will talk about this more in the part on high trust apps.

We can use either low trust or high trust with on-premises applications.  For purposes of our discussions you can use only low trust Apps when they are deployed to Office 365.  Each one uses different plumbing to work though, and we’ll look a little at the low trust plumbing for an on-premises SharePoint farm next (there’s no point in looking at it for Office 365 because it’s already configured for you there).

When you use low trust Apps on-premises, you’re deferring to ACS to act as a trust broker.  I would define ACS for you, but the acronym keeps changing on me…to me it will always mean Access Control Services but now it’s Azure something something.  J  Remember I mentioned the “trust broker” concept in Part 1.  You can think of the trust broker as the intermediary between SharePoint and your App.  SharePoint and your App both trust the trust broker, and it becomes something like a transitive trust in Windows Server – A trusts B and C trusts B, so therefore A trusts C.  So in a low trust app ACS is the trust broker; when we talk about high trust apps we’ll see how a simple certificate can become a trust broker.

To configure your on-premises farm to be able to use low trust apps, there are a few steps you need to take:

1. Create an Office 365 tenant.  You don’t need to add user licenses and pay for them to use SharePoint and Exchange and Lync or anything like that.  You just need to have a tenant in Office 365 so that you can have a reference point for your on-premises farm to create a trust with ACS.
2. Replace the token signing certificate for the on-premises SharePoint STS.  ACS needs to be able to trust the token signing certificate used by the SharePoint STS because they will mutually handshake over SSL when they go about exchange tokens with one another.  In the simplest case you can just create a new self-signed certificate and use that.  Beware though that by default self-signed certificates expire after one year.  When your certificate expires you will need to update your STS and also your trust relationship.  You can use a certificate issued by a public certificate root authority like Go Daddy, Verisign, Thawte, DigiCert (who does a GREAT job by the way), and many others.  What you CANNOT do is use a domain issued certificate.  It won’t work because there isn’t a public root authority for it that we can trust to.
3. Set up an Azure Service Application Proxy, SPTrustedSecurityTokenIssuer, and SPNs for the MsolServicePrincipal.  The service application proxy is how the farm is going to communicate with ACS, and an SPTrustedSecurityTokenIssuer is where we define the trust brokers that are going to be used in our farm.  The Service Principal is like an App Principal, only it’s for the ACS service instead of one specific application, and the SPNs (Service Principal Names) define on which host Urls the Service Principal should be allowed to operate.

Okay, so on the previous two steps here I did not give you a lot of detail about how to do them, but there’s a reason for that.  We have a nice document already prepared that includes more details and a PowerShell script to take care of this for you.  All you have to do is go to http://msdn.microsoft.com/en-us/library/dn155905.aspx to more details and download the script from there.  A couple of other things worth noting about this:

1. You need to create an SPN for every web application where you want to deploy apps!  Remember I mentioned above that the collection of SPNs determines where the Service Principal can be used.  The good news is that the link I provided above includes a PowerShell script that takes care of this for you as well, so you don’t have to worry about hunting that down.
2. You should really reboot your SharePoint server(s) after making these changes.  I’ve found the functionality to be a little hit and miss when you do not do that.

Once you’ve done these steps – which when you think about it are really pretty simple; open a browser and create a tenant, copy some PowerShell script and run it, then reboot your server – you’re ready to write your first low trust app on-premises.  Doing so is actually quite simple:

1. Open Visual Studio 2012 (with the Office Developer Tools installed) and create a new SharePoint App.
2. When the wizard starts type in the Url to your SharePoint site where you want to deploy the app and choose a hosting option like Provider-hosted App, then click Next.
3. Select the option to use a client secret and click Finish.
4. Press F5 to run, deploy and test.

 Here’s how it looks running through the wizard:

 And that’s all there is too it.  If it all doesn’t “just work” for you though, here are a few troubleshooting tips:

• If you get an error like “token request error” and/or “400 – bad request” this typically means that your SPN is not registered with the MsolServicePrincipal
• If you get an error about “parameter 'token' cannot be a null or empty string”, you are probably not getting an app token; see this for more details:  http://blogs.technet.com/b/speschka/archive/2013/05/28/missing-context-token-in-low-trust-app-with-sharepoint-2013.aspx

 That wraps up this post.  In the next post we’ll look at the context token from SharePoint in a little more detail and see what you can do with it.