Understanding OAuth tokens and their lifetime

I received a question in email the other day – what is the lifetime of a SharePoint OAuth token? Interesting question, so I did some research.

First, go read Kirk's post on the content of SharePoint's app tokens: Inside SharePoint 2013 OAuth Context Tokens

So, the token is just a string in JSON format that contains relevant properties. The property that we want to understand is the expiration value. (Well, actually the delta between "Not valid before" and "Expires.") To find out the answer, I followed Kirk's post to grab a token from Fiddler. Then, I used some NuGet goodness to look at the token. Microsoft has published a NuGet package that contains a helper library for JWT tokens: System.IdentityModel.Tokens.JWT

Using this library, you can perform basic operations on the token:

var at = new JwtSecurityToken(accessToken);
var lifetime = at.ValidTo - at.ValidFrom;
Console.WriteLine("Access Token lifetime: {0}", lifetime);

Turns out that the answer to the question is 1 hour. (Actually 65 minutes.)

There are some interesting methods in the System.IdentityModel.Tokens.JWT namespace, things like ValidateToken. I mention this because if you are processing tokens in your code, you really should make sure that they are valid. So, instead of just using the JwtSecurityToken constructor to create the token, use the JwtSecurityTokenHandler class:

var h = new JwtSecurityTokenHandler();
SecurityToken at = null;
h.ValidateToken(accessToken, new TokenValidationParameters(), out at);

To learn more about token validation, read Vittorio's post: http://www.cloudidentity.com/blog/2014/03/03/principles-of-token-validation/

But, I didn't stop there. What about refresh tokens?

Using the JwtSecurityToken class did not work with the refresh token. Thinking I knew more than Microsoft, I manually tried to decode the token, with no luck. So, when all else fails, read the manual, right?

RFC 6749 OAuth 2.0 October 2012

1.5. Refresh Token

Refresh tokens are credentials used to obtain access tokens. Refresh
tokens are issued to the client by the authorization server and are
used to obtain a new access token when the current access token
becomes invalid or expires, or to obtain additional access tokens
with identical or narrower scope (access tokens may have a shorter
lifetime and fewer permissions than authorized by the resource
owner). Issuing a refresh token is optional at the discretion of the
authorization server. If the authorization server issues a refresh
token, it is included when issuing an access token (i.e., step (D) in
Figure 1).
   
A refresh token is a string representing the authorization granted to
the client by the resource owner. ==The string is usually opaque to
the client.== The token denotes an identifier used to retrieve the
authorization information. Unlike access tokens, refresh tokens are
intended for use only with authorization servers and are never sent
to resource servers.

http://tools.ietf.org/html/rfc6749

Opaque to the client means that the token is not intended to be decoded/decrypted. You just cache it and use it necessary to get an access token as needed. Since the refresh token is at the discretion of the authorization server, the authoritative source for SharePoint refresh tokens is Microsoft. And their description of the refresh tokens is not necessarily clear on the matter:

Handling Refresh Tokens

Refresh tokens do not have specified lifetimes. Typically, the lifetimes of refresh tokens are relatively long. However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. The client application needs to expect and handle errors returned by the token issuance endpoint correctly. When you receive a response with a refresh token error, discard the current refresh token and request a new authorization code or access token. In particular, when using a refresh token in the Authorization Code Grant flow, if you receive a response with the interaction_required or invalid_grant error codes, discard the refresh token and request a new authorization code.

From http://msdn.microsoft.com/en-us/library/azure/dn645536.aspx

So, what do we do about refresh tokens? One thing to keep in mind is that every time you get an access token from SharePoint, you also get a refresh token. So, whenever your application uses the refresh token to get a new access token, you should replace the refresh token you have stored with the new refresh token received with the access token. In most scenarios, this should suffice.