How to Check if an OAuth Token is Valid? - PHP OAuth API package blog

Contents

Checking if an Access Token is Valid

Checking if an Access Token is Valid Without Redirecting the User

What if the Token is Retrieved but is Not Valid?

Conclusion

Checking if an Access Token is Valid

Once in a while I get requests from users of this PHP OAuth client class to have the possibility check if the class already retrieved the OAuth access token and if it is still valid.

In the beginning, the class only had the Process function to perform that check. The idea was to make it simple, so there was only one function (besides Initialize and Finalize) that would do all you need without requiring the users to learn more about the OAuth protocol than they could care.

If the Process function determines that it does not have a valid access token, it will redirect the user to the OAuth server authorization page. Since this class users did not want the redirect to happen, my first approach was to allow overriding the Redirect function in a sub-class, so it does nothing. It would work but that is not a nice solution, as it requires the class users to create sub-classes.

Checking if an Access Token is Valid Without Redirecting the User

Since the previous solution was not obvious to all users, I kept getting requests to have a solution that is more evident.

What many users want is to do something like, if a token was not yet retrieved, show a login button. Otherwise, show some information about their account in the OAuth server. So there should be a way to show the login button without redirecting the user to the OAuth server authorization page right away.

The Process function does two things: 1) check if there is a valid token already and 2) redirect the user if there is no valid token. So the more obvious solution is to split these two things.

The Process function was split in two parts. The CheckAccessToken function was just introduced to implement the first part. The Process function calls the CheckAccessToken function, and if necessary, it redirects the user to the OAuth server authorization page.

The CheckAccessToken function returns the redirection URL in parameter variable passed by reference. So it is up to the calling code to decide what to do with that URL. The user can be redirected to the authorization or just show the login button with a link to the authorization page.

So now you may call the CheckAccessToken function instead of the Process function if you do not want to immediately redirect the user when there is no valid token. Your typical login with OAuth server now should look more like below. Take a look at the login_check_with_facebook.php for a full example script.

 $client = new oauth_client_class;
 $client->server = 'Facebook';
 $client->redirect_uri = 'http://' . $_SERVER['HTTP_HOST'].
  dirname( strtok( $_SERVER['REQUEST_URI'], '?' ) ).
  '/login_check_with_facebook.php';

  /* Other class settings may go here
   * like the application client id and secret
   */

 /* The initial page to redirect is not set;
  */
 $redirect_url = null;
 
 if(($success = $client->Initialize()))
 {
  if(($success = $client->CheckAccessToken( $redirect_url )))
  {

   /*
    * Is there a valid access token or shall we need to 
    * redirect the user to the OAuth server authorization page?
    */

   if(IsSet($redirect_url))
   {

    /*
     * It seems the access token was not yet retrieved
     * or it was expired and could not be renewed
     */

   }
   elseif(strlen($client->access_token))
   {

    // Call the API or do something else with the access token

   }
  }
  $success = $client->Finalize($success);
 }

 if($success)
 {

  /*
   * Check if the redirect URL is set, so the user needs to authorize
   * to obtain the access token
   */

  if(IsSet($redirect_url))
  {

   // Show the redirect URL as a link button

   echo '<h1><a href="',
    HtmlSpecialChars( $redirect_url ).
    '">Login with Facebook</a></h1>';
  }
  else
  {

    // Show something useful to the user

  }
 }
 else
 {
   // Show the error message
 }

What if the Token is Retrieved but is Not Valid?

The CheckAccessToken function checks if a token was already retrieved. However, for some reason that token may have expired or was revoked by the OAuth server.

If the token has expired, the CheckAccessToken function will attempt to renew it retrieving a fresh token. This happens if the server has initially provided a refresh token.

Some OAuth servers like Facebook set the tokens to expire after some time (60 days?) but do not provide means to refresh the token. So the user needs to be redirected to the authorization page again to restart the process to get a new token.

Some APIs may provide means to check if a token is still valid. However, if a token was revoked, in general, the only way to know that is no longer valid is to perform an API call with the CallAPI function. If that call fails, you need to prompt the user to come to your application Web site and restart the authorization process.

Conclusion

OAuth is not a trivial protocol to handle. There are plenty of situations that you need to take care. This class attempts to make it simple for all developers that do not have the time nor the patience to learn about the whole OAuth protocol in all versions that the class supports (1.0, 1.0a and 2.0).

This new feature to check the access token without redirecting the users to the OAuth authorization page is yet another step to simplify situations that many developers deal with in their OAuth based applications.

If you have questions or other comments, please post a comment here, so explanations can be given or otherwise the class can be improved further.