Overview of Oauth in Sharepoint 2013 : Application Authentication (part 2) - Managing Tokens in Your Application

App and User Context in API Calls

SharePoint provides the ability for apps to make calls to SharePoint with access tokens that are either on behalf of a user or without user context, also known as app-only context. When an access token is used that is on behalf of a user, SharePoint treats the call as if the user is making the call. This means it is subject to the same permissions that user has. Additionally, an app can make an app-only call to SharePoint, which means no user context is passed and only the permissions that the app has been granted apply.

The TokenHelper class provides helper methods for getting each of these types of tokens. To get an access token that includes the calling user’s context, use the following method:

TokenHelper.GetAccessToken

To get an app-only access token, use the following method:

TokenHelper.GetAppOnlyAccessToken

Managing Tokens in Your Application

When an application is launched by a user a context token is passed to it. After this has happened it is up to the application to handle the tokens and potentially store them for future use or pass between app pages. These tasks are left to the application to manage because SharePoint has no knowledge of the inner workings of the application. The developer must decide how she wants to manage these tokens when the application passes them after it is launched. Some basic options are available, including the following:

• Cache the token for a period of time.
• Pass the token around as needed but don’t store it.

To assist with caching, the tokens provide a CacheKey and an expiry that can make caching more straightforward for the developer. The CacheKey is a property on the token that is unique to that particular token. It can be used, as the name suggests, as a primary key for that token in a cache of the developer’s choosing, such as ASP.NET application state. Additionally, the expiry time can be used in the application to flush the old tokens from the cache after they have expired.

The following exercise walks through a simple example of how to use ASP.NET application state to cache the appropriate tokens so that they can be used between page requests.

public static JsonWebSecurityTokenHandler CreateJsonWebSecurityTokenHandler()

<asp:Button ID="Button1" runat="server" Text="Process" OnClick="Button1_Click"/>

using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.IdentityModel.S2S.Tokens;
 
namespace SharePointTokenCacheAppWeb.Pages
{
    public partial class Default : System.Web.UI.Page
    {
 
        protected void Page_Load(object sender, EventArgs e)
        {
            if (!this.IsPostBack)
            {
                var contextToken = 
                TokenHelper.GetContextTokenFromRequest(Page.Request);
                var hostWeb = Page.Request["SPHostUrl"];
 
                JsonWebSecurityTokenHandler tokenHandler = 
                TokenHelper.CreateJsonWebSecurityTokenHandler();
                SecurityToken securityToken = tokenHandler.ReadToken(contextToken);
                JsonWebSecurityToken jsonToken = 
                securityToken as JsonWebSecurityToken;
                SharePointContextToken token = 
                SharePointContextToken.Create(jsonToken);
 
                Application[token.CacheKey] = contextToken;
 
                Button1.CommandArgument = token.CacheKey;
 
            }
        }
 
        protected void Button1_Click(object sender, EventArgs e)
        {
            var contextToken = 
            (string)Application[((Button) sender).CommandArgument];
            var hostWeb = Page.Request["SPHostUrl"];
 
            using (var clientContext = 
            TokenHelper.GetClientContextWithContextToken(hostWeb, contextToken, 
            Request.Url.Authority))
            {
                clientContext.Load(clientContext.Web, web => web.Title);
                clientContext.ExecuteQuery();
                Response.Write(clientContext.Web.Title);
                clientContext.ToString();
            }
        } 
    }
}