Updated TokenHelper classes in VS2013

Posted on 8/28/2014 @ 2:39 PM in #SharePoint by | Feedback | 5990 views

People, looks like Microsoft isn’t giving up on the App Model, so better learn it sooner or later. It will undergo additions and improvements, and looks like Office 365 especially is going to benefit hugely from it, but on prem or not, you’ve gotta learn it.

Anyway, in that vein, one of the things that doesn’t get enough attention, are the huge improvements that happened in the TokenHelper classes between VS2013 and VS2012.

Before I describe those improvements, let me first give a little background on OAuth. No you don’t need to understand the full flow of how Microsoft has implemented it, but you DO need to understand the following basic things,

  1. Context Token – is what tells the App about the context, where is it running, what version etc. SharePoint has to pass enough information as a context token to the app to get this.
  2. Access Token – is what your app needs to pass to SharePoint to make authenticated calls. This is passed as a Authorization header, with value “Bearer <accessToken>”. SharePoint uses JWT tokens which can optionally contain claims identifying the user.
  3. Refresh Token – is longer lived, and can be used to generate access tokens without having to go through the entire authentication chain.

SharePoint Access Tokens are valid for 12 hours. SharePoint refresh tokens are valid for 6 months. To be honest, access tokens should be valid for 30 mins, 12 hours is a bit long, but we can’t change that.

Anyway, now back to what this blogpost is about. The improvements in VS2013 app templates.

VS2012 shipped with a class called TokenHelper.cs. That class was a “first cut” – it left a lot of responsibility on you, with no guidance. It didn’t work very well if people bookmarked app URLs for instance. It left the access token renewal on you. It didn’t understand different authentication modes. Etc. etc.
VS 2013 now has 3 files, TokenHelper.cs, SharePointContext.cs and SharePointContextFilterAttribute.cs, which does a better job at handling these tokens, less responsibility on you but not zero responsibility.

Here is what you need to know about the new classes,

#1 – Everything is now available as a Nuget package

       Install-Package AppForSharePointWebToolkit



#2 – Unified way of writing code for ACS (Office 365) or High Trust (S2S/OnPrem).

There are four main classes you need to know,

  1. SharePointAcsContext : SharePointContext
  2. SharePointAcsContextProvider : SharePointContextProvider
  3. SharePointHighTrustContext : SharePointContext
  4. SharePointHighTrustContextProvider: SharePointContextProvider

This means, now you can get client context like this -

   1:  var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);
   2:  using (var clientContext = spContext.CreateUserClientContextForSPHost()) { }

Note, there is no change in code whether you are using ACS or S2S (high trust). The internals of the classes detect how you are running and will automatically fire the right logic for you.

#3 – Extensible authentication model

You may need to support authentication types other than windows (duh!). You can register custom providers using SharePointContextProvider.Register(). You just have to make sure that you call SharePointContextProvider.Register() in Startup.cs or Application_Init

#4 – Bookmarking App URLs now works

SharePointContextProvider.CheckRedirectionStatus() method checks if the current user has authenticated with SharePoint. If the user has not authenticated, it will automatically create a redirect URL to let the browser navigate the user to the SharePoint host site to authenticate first – this way you get the new Context Token nicely, and then the app logic can take over.

#5 – Works with both WebForms and MVC

To use it with MVC, simply decorate your actions with SharePointContextFilter attribute.
To use it with WebForms, use the following code,

   1:  protected void Page_PreInit(object sender, EventArgs e)
   2:  {
   3:      Uri redirectUrl;
   4:      switch (SharePointContextProvider.CheckRedirectionStatus(Context, out redirectUrl))
   5:      {
   6:          case RedirectionStatus.Ok:
   7:              return;
   8:          case RedirectionStatus.ShouldRedirect:
   9:              Response.Redirect(redirectUrl.AbsoluteUri, endResponse: true);
  10:              break;
  11:          case RedirectionStatus.CanNotRedirect:
  12:              Response.Write("Error occurred while processing your request.");
  13:              Response.End();
  14:              break;
  15:      }
  16:  }

And then you can grab the SPContext.

#6 – Automatic handling of tokens

SharePoint Access Tokens are valid for 12 hours. SharePoint refresh tokens are valid for 6 months. With these new helper classes,

  • The SharePointContext (ACS or HighTrust) is stored in Session State, which means as you navigate from page to page, you don’t need to manage tokens
  • When the Access Token has less than 5 minutes left on it, it silently renews the access token. This means, you don’t have to write logic for it.

#7. Now for the gotchas you need to know,

  1. This automatic handling of tokens, does not work with WebAPI. If you intend to use WebAPI, you need to revert back to VS2012 sort of behavior and manage tokens and token lifetimes yourself.
  2. The helper classes are designed to work on a in-memory session state on a single machine. If you are leveraging Windows Azure cloud services, or web farms in general, you need to either
    1. Override the implementation of LoadSharePointContext and SaveSharePointContext, OR
    2. use an out of process implementation of session state. I am personally a fan of Redis Cache which is now available in Azure, so I’d just use that.
  3. The Helper classes don’t make full use of RefreshTokens. I wish the RefreshTokens weren’t such a blackbox as they can open further customization opportunities for developers.
  4. The classes still work with only Windows Authentication, luckily now they have gone towards a provider model but you still need to write your own context classes to support other authentication types such as ADFS/SAML or whatever.

Sound off but keep it civil:

Older comments..