High-Trust Apps in SharePoint 2013

In this article I will cover a less-known app model for SharePoint 2013 called “high-trust apps”.

Low-Trust SharePoint Apps

The most usual model of SharePoint 2013 cloud applications is the so-called “low-trust application” model. It is the app model that needs an intermediate entity, in this case Access Control Service or ACS, which acts as a trusted authentication mechanism between SharePoint and the remote app. In low-trust apps, SharePoint sends a context token to the app when the browser is redirected to it. The app exchanges that context token for an access token, using ACS as the broker.

The name of “low-trust” is given to this model because the app is a mere token conduit that takes the context token and receives an access token. The app can’t add or remove any token information and passes it to ACS verbatim as it has been received from SharePoint. It is a very useful feature for the applications that we don’t control, such as the apps purchased from the SharePoint Store. Also, that’s the reason why only low-trust apps are allowed in the store in the first place.

However, in the corporate world with on-premise SharePoint farms, the low-trust model has two requirements that are hard to implement from the security standpoint. It requires Internet connectivity between the SharePoint farm and the ACS servers in Office 365. Many corporate datacenters don’t allow for their servers to access Internet. Furthermore, if the access is granted, we still have to establish a trust relationship between on-premise SharePoint and ACS service, that involves registering ACS public key in the farm.

For these on-premise environments we can still use the app model, but without these restrictions. Welcome to “high-trust” apps!

Why Should I Use Apps for On-Premise SharePoint 2013?

A very valid question! Why, indeed?

Well, the answer in my case is for a couple of reasons. Cloud-app model simplifies authentication for my developments. From the remote app server I don’t have to ask for explicit credentials nor be limited to using Windows authentication only. My development can follow established best practices without being shoehorned into SharePoint model. I can also migrate my development to a cloud-friendly model while still being in control of my server farm. Finally, I can grant the apps fine-grained permissions on different SharePoint services and with different access levels (Read, Write, Manage).

High-Trust App Model

High-trust apps, also known as S2S apps (Server to Server) don’t rely on a broker to authenticate them, but they establish a trust relationship with SharePoint and do their own access tokens.

Don’t be confused by the name. High-trust isn’t full trust either. Full trust is the code that runs on the SharePoint server, and consequently has the same permissions as the application pool within which it runs. So, why the high-trust moniker then? It’s because the app itself is trusted by SharePoint, and SharePoint trusts the app to build its own access token with the user identity in it. A high-trust app will never have more permissions than the ones granted by the user who has installed it.
In order to have a working high-trust app, we have to establish a trust between the app and the SharePoint. This trust is established using a digital certificate. The public certificate key is registered with SharePoint as a “Trusted Token Issuer”. The private key will be used by the app to sign the access tokens the apps issues. Note that in low-trust apps, the only trusted token issuer is the ACS.

As SharePoint trusts the app for issuing the tokens, SharePoint will accept the tokens made by the app. It will first validate them using the app certificate public key, which ensures that they haven’t been tampered with. Then, it will “rehydrate” the user from the identifier included in the access token and then it will check the app and user permissions for the operation. The app can make a token for any user. This is the part where SharePoint “trusts” the app to behave as a good citizen. The app can use any user identity, even the system account username, but it won’t have any extra permissions as SharePoint will restrict them to at most the permissions granted to the app. That’s one big change from the full-trust code that uses UserToken or RunWithElevatedPrivileges to execute code with system account privileges.

Let’s see the “dance” of the messages between SharePoint and a high-trust app when the app is accessed from a browser.

High-Trust Apps

  1. The user opens a SharePoint page and clicks on the app link.
  2. SharePoint redirect to the app URL (using HTTP 302 response). No context token is provided in the redirection, as opposed to low-trust apps.
  3. The browser is redirected to the MyApp.com URL as the response to SharePoint redirection.
  4. The app receives an HTTP request. In order to access SharePoint CSOM or REST API, the app needs an access token. The app builds the access token and signs it with its own certificate private key. This token is added to the SharePoint API request.
  5. SharePoint validates the access token using the private key of the app certificate, checks the permissions for both the app and the user and then returns the information the app has asked for.
  6. The app renders the HTML and returns it to the browser as a response.

Access Tokens Demystified

We have seen that high-trust apps build they own access tokens. We will now see how they are able to do it.
High-trust apps use the same TokenHelper class that is built by Visual Studio when we make a new SharePoint 2013 provider-hosted app project. TokenHelper contains the code that works with low-trust as well as high-trust apps. If we look in the source code of TokenHelper.cs file, we will see two methods with S2S in their names:

• GetS2SAccessTokenWithWindowsIdentity

• GetS2SClientContextWithWindowsIdentity

The first method returns an access token for a Windows user that is passed as a parameter. The token is signed by the app certificate. The second method uses the access token to return an instance of ClientContext SharePoint CSOM object that will be initialised for a single user and a single site URL. The Windows user that is passed as a parameter is internally converted into a ClaimsIdentity using the Windows security identifier (SID) or the profile name (UPN). By default, TokenHelper relies on the app web application to use Windows authentication in order to get the Windows identity. But, as it uses ClaimsIdentity internally, we can override this behaviour to use custom claims identities or even federated identities, as long as they use standard SAML protocol.

But, how does TokenHelper know which certificate it should use to sign the token? Well, we have to provide the certificate location and the certificate private key password in the web.config file of the app web project. Also, the app application pool needs read permissions for the certificate itself.

Caveats

The high-trust app model is not without quirks. The most restrictive one is that we must have user profile service running and it must contain the application users as profiles. It has to do with the SharePoint rehydrating the user identity when the app token is read. SharePoint trusts the app, but needs to find the appropriate user. The only way it can find the user is for the user to be present in the profile store.

The user profile must match the identifier (SID for the Windows identities, email or username for other types of identities) and must be unique. For example, if we use email as the user identifier in the token, we can’t have more than one user profile with the same email. It will return “Access Denied” when the request to the API is made, which is a non-obvious error and we have to parse the ULS logs to find the culprit. Luckily, this part of SharePoint is very verbose in its ULS messages and it helps to identify the issues.

High-trust apps also require the app infrastructure to be set before deploying them, same as the low-trust apps. It involves starting the app infrastructure services, registering app domain and provisioning an app catalog site.

Summary

High-trust apps simplify the authentication and authorisation for on-premise SharePoint environments, keeping our custom developments in line with the preferred cloud app model. Instead of relying on a broker, they build their own access tokens and can be customised to use a variety of authentication mechanisms.
The best way of getting our feet wet with high-trust apps is to follow the MSDN tutorial and build one. Happy coding!

Planet Of Apps

Edin Kapic _BW

About the Author: I have spoken on several international SharePoint conferences such as European SharePoint Conference 2011 in Berlin, SharePoint Evolutions Conference 2013 in London, SharePoint Saturday Belgium 2012 and Microsoft NetWork Conference 2012 in Bosnia-Herzegovina.I will deliver this presentation in SharePoint Summit 2013 in Vancouver, Canada in October.

Follow Edin on Twitter!

Share this on...

Rate this Post:

Share: