SugarCRM: Working with Sugar 7 Sessions

One of the changes that was introduced in Sugar 7 relates to the manner in which user sessions are managed. 

In older versions of Sugar, the length of a user session was determined by a PHP parameter that controls the lifetime of a PHP session. For all intents and purposes, a Sugar session was equivalent to a PHP session and deleting the latter would in turn cause your Sugar session to also be destroyed.

For the Sugar 7 release, this process was changed and a Sugar user session is now primarily controlled by means of a series of OAuth tokens. Those of you that have worked with the REST v10 API should be familiar with the topic, but even if you have not, the information contained herein should still be of help. 

A common question that is asked in relation to sessions in Sugar 7 is: how does one change the lifetime of an OAuth token? 

By default, the access_token has a lifespan of 1 hour and the refresh_token, used to obtain a new access_token, lives for 2 weeks.

A brief description of the manner in which the tokens are used follows...

Sugar will continually use the access_token to complete user requests. Upon exceeding the 1 hour mark, Sugar will respond to any subsequent request(s) with a status code of 401. This effectively means that the user session has expired. Normally, a user would be booted off the system, but instead, Sugar will transparently request a new access_token by sending the refresh_token. This process will repeat itself until such time that the refresh_token expires (2 weeks) and it is the pattern we recommend others follow when communicating with the REST v10 API. Upon the refresh_token expiring, the user would then be prompted to provide their Sugar user and password.

For some scenarios, it is helpful to manipulate the lifespan of either token. To manipulate their lifespan, you can add either setting to your config_override.php file:

//Manipulating the access_token lifetime
$sugar_config['oauth2']['access_token_lifetime'] = 3600;

//Manipulating the refresh_token lifetime
$sugar_config['oauth2']['refresh_token_lifetime'] = 1209600;

Note that both settings are specified in seconds. 

Lastly, if you wish to ensure that users are logged off the system after a given period of time, regardless of the refresh_token, you can control the overall session lifetime by way of the following setting, also specified in seconds:

$sugar_config['oauth2']['max_session_lifetime'] = 1209600;