Authentication and Authorization: Refresh Tokens

This is the seventh and final post in our topical series on Authentication and Authorization for OCLC web services. In our previous two posts, we discussed two different OAuth flows for obtaining Access Tokens: the Explicit Authorization Code flow and the User Agent Mobile flow. In this post, we'll discuss the concept of Refresh Tokens and how they can be used to obtain an Access Token without requiring user authentication.

A Refresh token is a string that represents an authorization that was granted to a client to use a particular set of web services on behalf of a user to access data for a particular institution. Refresh Tokens are issued to the client by the authorization server upon request of an Access Token. Refresh Token are typically longer lived than Access Tokens and used to request a new Access Token without forcing user authentication. Unlike Access Tokens, Refresh Tokens are only used with the Authorization Server and are never sent to a web service.

Requesting a Refresh Token

Our Explicit Authorization flow allows clients to request a Refresh Token when a request for an Access Token is made. In our implementation, Refresh Tokens last for a specific amount of time, typically 1 day. To request a Refresh Token as part of the request for an access token, the client needs to specify refresh_token as one of the scopes being requested.

Example:

https://authn.sd00.worldcat.org/oauth2/authorizeCode?
client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa
&authenticatingInstitutionId=128807&contextInstitutionId=128807
&redirect_uri=http%3A%2F%2Flibrary.worldshare.edu%2Ftest.php&response_type=token&scope=platformConfig+refresh_token

If a Refresh Token is requested, then the following fields are also returned in the Authorization server response:

• refresh_token
• refresh_token_expires_in
• refresh_token_expires_at

Example:

{
"access_token":"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
"token_type":"bearer",
"expires_in":"3599",
"principalID":"cpe4c7f6-f5a4-41fa-35c9-9d59443f544p",
"principalIDNS":"urn:oclc:platform:128807"
"contextInstitutionId": "128807",
"expires_at": "2013-08-23 18:45:29Z"
"refresh_token": "rt_ZrigZXPJQnB1l2DxF1dCratGNxUHpGLjMw8z",
"refresh_token_expires_in": "604799",
"refresh_token_expires_at": "2013-08-30 18:25:29Z"
}

Using a Refresh Token

To use a refresh token to get a new Access Token, a client needs to make a request to the Access Token endpoint of the Authorization server. The request needs to include the following parameters:

• grant_type – this will be set to “refresh_token”
• refresh_token – a valid refresh token

The request must also be signed using an HMAC Signature generated using the client’s WSKey and secret.

Example:

POST /oauth2/accessToken?grant_type=refresh_token&refresh_token=rt_4393983 HTTP/1.1
Host: https://authn.sd00.worldcat.org
Accept: application/json
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 
clientId="jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa ",
timestamp="1361911277", nonce="5368c00b", signature="CG+ENonHuWQ657pKGfpkFHb0MZgz7SWlL+A4902O5bA="
Content-Length: 0

If the request for an Access Token is successful, then the Authorization Server will return a JSON response that contains the Access Token information. You cannot get a new refresh token using a refresh token. Getting a new refresh token requires the client to request an Access Token using one of the other flows.

Why would I use a Refresh Token?

Refresh Tokens are useful because they allow applications to get new Access Tokens without forcing users to login to the system repeatedly. Typically our Access Tokens last for 20 minutes. This means after 20 minutes the user would have to re-authenticate in order to continue to use the application interacting with the web service. This may be undesirable if the user is used to a scenario where they are logged into the system until they explicitly log out or close their browser window. To deal with this scenario, we have implemented Refresh Tokens which allow the application to request a new Access Token, "behind the scenes", and maintain the user's session beyond the length of the life of the Access Token.

If you missed any posts in the Authentication and Authorization series, information can also be found in our updated Authentication and Authorization documentation.