Wednesday, May 18, 2016

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;


  1. I have problem with upload sugar7.7 detailview dashlet with contacts module. Have you solution for this?

    1. What exactly is the problem? Are you getting an error? Please elaborate.

  2. Why would you make the max_session_lifetime shorter rather that just refresh_token_lifetime shorter? What is the use case where they want tokens to potentially outlive sessions?

    1. You typically wouldn't do that. To your point, you'd want to make the refresh shorter.

  3. Also, there is at least one if not two config settings that are confusing, misnamed, and our documentation totally gets their purpose and usage wrong. Gimmie a few and I'll provide links.

  4. Last but not least! You are impossible to find in LinkedIn! Is that intentional? I thought it would be cool if all TAMs were in my network, and aside from the head of all TAMs, you were my top TAM to add. You laying low?

    1. Well, it is only intentional from the standpoint that I don't use LinkedIn. :)

  5. I want to fire my custom dependency on a specific custom add button click(as it amends the view by adding rows to it), not on loading page which is Sugar by default behavior. Any way to do it?

  6. Hi Angel, do these session tokens also affect the way Sugar mobile works in 7.x? And would there be any possibility for further controlling the loss of a token when working in offline mode? Thanks - James.

    1. Hey James,

      I haven't tested it, but I would assume that it does affect Mobile in the same way. However, it is possible that a distinction is made by way of the "platform" parameter used to obtain a token via the API, which is used by both the web app and Mobile.

      As far as I am aware, those are the only methods available for controlling token lifetimes.

  7. Sugarcrm recommnds access_token_lifetime to be 1800
    and refresh toekn to be 3600.
    It means the refresh token expires for every 1 hour and the user needs to login again


Your comments, feedback and suggestions are welcome, but please refrain from using offensive language and/or berating others. Thank you in advance.