Token Persistence

Token persistence refers to storing and utilizing the authentication tokens that are provided by Zoho. Token persistence enables the SDK to automatically refresh the access token after initialization using the refresh token without the need for user intervention. There are three ways provided by the SDK in which persistence can be applied. They are file persistence, DB persistence and Custom persistence. Please note that the default method of token persistence provided by the Zoho CRM SDK is File persistence.

Implementing OAuth Persistence

Once the application is authorized, OAuth access and refresh tokens can be used for subsequent user data requests to Zoho CRM. Hence, they need to be persisted by the client app.

The persistence is achieved by writing an implementation of the inbuilt TokenStore interface, which has the following callback methods.

• getToken($user, $token) - invoked before firing a request to fetch the saved tokens. This method should return implementation Token interface object for the library to process it.

• saveToken($user, $token)- invoked after fetching access and refresh tokens from Zoho.

• deleteToken( $token) - invoked before saving the latest tokens.

• getTokens() - The method to retrieve all the stored tokens.

• deleteTokens() - The method to delete all the stored tokens.

• getTokenById($id, $token) - The method to retrieve the user's token details based on unique ID.

There are three ways provided by the SDK in which you can achieve persistence. They are:

Database Persistence

Database persistence is a technique that involves storing and retrieving data from a database. In case the user prefers to use the default DataBase persistence, MySQL can be used.

• The database name should be zohooauth.

• There must be a table oauthtoken with columns

  • id(varchar(255))

  • user_mail (varchar(255))

  • client_id (varchar(255))

  • client_secret (varchar(255)

  • refresh_token (varchar(255))

  • grant_token (varchar(255))

  • access_token (varchar(255))

  • expiry_time(varchar(20))

  • redirect_url(varchar(255)

MySQL Query

Copy to Clipboard

CREATE TABLE oauthtoken (
  id varchar(255) NOT NULL,
  user_mail varchar(255) NOT NULL,
  client_id varchar(255),
  client_secret varchar(255),
  refresh_token varchar(255),
  access_token varchar(255),
  grant_token varchar(255),
  expiry_time varchar(20),
  redirect_url varchar(255),
  primary key (id)
);

Here is the code to create a DBStore object:

Copy to Clipboard
/*
* Create an instance of TokenStore.
* host -> DataBase host name. Default "jdbc:mysql://localhost"
* databaseName -> DataBase name. Default "zohooauth"
* userName -> DataBase user name. Default "root"
* tableName -> DataBase table name. Default "oauthtoken"
* password -> DataBase password. Default ""
* portNumber -> DataBase port number. Default "3306"
*/
// $tokenstore = (new DBBuilder())->build();
$tokenstore = (new DBBuilder())
->host("hostName")
->databaseName("databaseName")
->userName("userName")
->portNumber("portNumber")
->tableName("tableName")
->password("password")
->build();

File Persistence

File persistence is a simple approach for storing and retrieving data that is saved to a file on local drive. In case of default File Persistence, the user can persist tokens in the local drive, by providing the the absolute file path to the FileStore object. This file must contain the following:

• id

• user_mail

• client_id

• client_secret

• refresh_token

• access_token

• grant_token

• expiry_time

• redirect_url

Here is the code to create a FileStore object:

Copy to Clipboard
//Parameter containing the absolute file path to store tokens
$tokenstore = new FileStore("/Users/username/Documents/php_sdk_token.txt");

Custom Persistence

Users can create their own logic for storing and retrieving authentication tokens using the custom persistence technique. To use Custom Persistence, the user must implement TokenStore interface (com\zoho\api\authenticator\store\TokenStore) and override the methods.

Here is the code:

Copy to Clipboard
namespace store;

use com\zoho\api\authenticator\Token;

use com\zoho\crm\api\exception\SDKException;

use com\zoho\crm\api\UserSignature;

use com\zoho\api\authenticator\store\TokenStore;

class CustomStore implements TokenStore
{
    /**
      * @param user A UserSignature class instance.
      * @param token A Token (com\zoho\api\authenticator\OAuthToken) class instance.
      * @return A Token class instance representing the user token details.
      * @throws SDKException if any problem occurs.
    */
    public function getToken($user, $token)
    {
      // Add code to get the token
      return null;
    }

    /**
      * @param user A UserSignature class instance.
      * @param token A Token (com\zoho\api\authenticator\OAuthToken) class instance.
      * @throws SDKException if any problem occurs.
    */
    public function saveToken($user, $token)
    {
      // Add code to save the token
    }

    /**
      * @param token A Token (com\zoho\api\authenticator\OAuthToken) class instance.
      * @throws SDKException if any problem occurs.
    */
    public function deleteToken($token)
    {
      // Add code to delete the token
    }

    /**
      * @return array  An array of Token (com\zoho\api\authenticator\OAuthToken) class instances
    */
    public function getTokens()
    {
      //Add code to retrieve all the stored tokens
    }

    public function deleteTokens()
    {
      //Add code to delete all the stored tokens.
    }

    /**
      * @param id A string.
      * @param token A Token (com\zoho\api\authenticator\OAuthToken) class instance.
      * @return A Token class instance representing the user token details.
      * @throws SDKException if any problem occurs.
    */
    public function getTokenById($id, $token)
    {
      // Add code to get the token using unique id
      return null;
    }
}