Now that you understand what
application identities are and how to create and set them up in
SharePoint, you can take a look at how those identities are used as
part of the authentication between applications and SharePoint.
Whenever an app that is subject to external
authentication needs to make an API call into SharePoint it must first
confirm it has a valid and usable set of authentication tokens to do
so. The two key tokens are:
- Context token
- Access token
The context token
is passed when an application is launched. It contains information
about who the calling user is and details about the SharePoint site
where the application was launched. The access token is used when an application makes a call to a SharePoint API.
Several steps make up the authentication flow
when these two tokens are issued and used, but there are five main
occurrences that make up high-level flow when a user launches an app in
SharePoint:
1. User logs into SharePoint.
2. SharePoint gets a context token for the user.
3. Context token is passed to the app when launched.
4. App uses the context token to request an access token.
5. Access token is passed with API calls.
The full process for app authentication is slightly more complex, as shown in Figure 1. This detailed, step-by-step version of process is explained in the following steps:
1. User requests a SharePoint page with an App Part included.
2. SharePoint
requests a context token from ACS for the user, including context
information about the user and a refresh token that can be used for
requesting access tokens.
3. ACS returns the signed context token to SharePoint.
4. SharePoint
returns the page with an iFrame for the App Part, including the content
token as a query string parameter on the URL for the iFrame source.
5. The browser
renders the page and iFrame, and a request to the remote app is made to
render the App Part iFrame contents. The context token is passed on the
URL.
6. The app
code validates the content token to ensure its authenticity using a
shared secret that only the app and SharePoint/ACS know. The app then
uses the refresh token to request an access token from ACS.
7. ACS returns
an access token. These can be cached and used multiple times. The
expiry time is provided in the token so the app knows when to request a
new one.
8. The app
makes an API call to SharePoint such as a CSOM call or REST API
request. The access token is included in the authorization HTTP header.
9. The SharePoint API call returns the data requested.
10. The app renders the page content and the result is returned.
NOTE
Both the context token and access tokens are Base64-encoded JavaScript
Object Notation (JSON) objects that follow the JSON Web Token (JWT)
format. If you are interested in viewing the full structure of the
tokens you can Base64-decode the tokens, which gives you the
JSON-formatted token.
In the case of SharePoint Online Azure Control
Services (ACS), the STS is involved in creating both the context token
and access tokens. In purely on-premises situations, SharePoint acts as
the STS.
To assist with the various token-centric
processes, such as validating tokens and requesting new ones from code,
the default Visual Studio 2012 SharePoint application templates provide
a helper class called TokenHelper. It wraps up the calls to ACS and so on to simplify the process for you.
The best way to illustrate some of the helper functions and classes that TokenHelper.cs provides is to walk through an example exercise, as follows.
TRY IT OUT: Using TokenHelper (Tokens.zip)
In this exercise you create a simple SharePoint Autohosted application and use the TokenHelper class to access the ContextToken passed.
1. Create a
new SharePoint app project in Visual Studio by choosing File ⇒ New ⇒
Project. Pick the App for SharePoint 2013 project template.
2. Name your app SharePointApp and click OK.
3. If required, specify the URL of your SharePoint online site for the site to use for debugging.
4. Ensure Autohosted is selected in the hosting type drop-down menu.
5. Click Finish.
6. Locate and open the TokenHelper.cs file.
7. Find the
CreateJsonWebSecurityTokenHandler function and make the function public instead of private as follows:
public static JsonWebSecurityTokenHandler CreateJsonWebSecurityTokenHandler()
8. Locate and open the Default.aspx.cs file.
9. Replace the
Page_Load function with the following code:
protected void Page_Load(object sender, EventArgs e)
{
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);
Response.Write("<b>Context Token:</b> " + contextToken);
Response.Write("<b>STS:</b> " + token.SecurityTokenServiceUri);
}
10. Press F5 to run and debug the project.
11. If prompted to trust the application, click Trust It.
12. When presented with the list of apps in your site, locate and click your new application.
13. A Web page
appears that contains the Base64-encoded context token and the URL of
the STS that issued the token. In the case of ACS it is as follows:
https://accounts.accesscontrol.windows.net/tokens/OAuth/2
14. Copy the ContextToken value to the clipboard.
15. In a new window, navigate to www.base64decode.org and paste the ContextToken into the Value to decode box.
16. Click Decode to decode the Base64-encoded string. A JSON representation of your ContextToken appears, and you can see where all the values passed are included.
How It Works
In this exercise you created a new application that accepted the ContextToken from SharePoint. You used the TokenHelper class to assist with decoding and parsing out the SharePointContextToken
object. Contained within the decoded context token is information about
the token, including the issuing party — in this case, Azure Access
Control Services acting as the STS.
