Troubleshooting Sugar Logging Out Unexpectedly

Overview

While utilizing Sugar, users may be unexpectedly logged out of the system. This article covers several reasons that the browser may automatically log a user out as well as some high-level troubleshooting tips.

Resolution

Multiple Sessions Under the Same Username

Sugar only permits a username to be logged in under one session, and any additional user sessions started using the same username will log out the previous session. This behavior is for your security as Sugar does not allow multiple sessions for the same username from different computers or browsers. If any additional user session is detected, the user will be automatically logged out of the system and will have to log back into Sugar. To prevent situations like this, please do not share your login credentials (username and password) with others. This will ensure that only one session is active with each username.

Idle in Sugar for a Certain Period of Time

When a user does not perform any actions in Sugar for a period of time, the user is automatically logged out. 

When a user logs in to Sugar, an access token and a refresh token are returned which regulate the user's session timeouts in Sugar. If the access token expires during an active user session, Sugar will automatically pull for another access token as long as the refresh token is not expired. This allows the current session to be active indefinitely.

The default settings for Sugar are as follows:

• refresh_token_lifetime: The default value is 2 weeks.
• access_token_lifetime: The default value is 1 hour.

Please note that you can configure the Refresh Token Lifetime and Access Token Lifetime settings to best meet your organization's needs.  

Note: Automatic notification queries are made to the server on a user's behalf at a default interval of every 5 minutes. Sugar interprets these queries as user activity and will cause the current session to remain active without actual user input. For more information, please refer to the Setting Sugar's Notification Delay section below.

Configuring the Refresh Token Lifetime and Access Token Lifetime

The access token lifetime and refresh token lifetime settings can be configured via code-level customizations for instances that do not use SugarIdentity and in SugarIdentity for instances that use SugarIdentity. For more information, please refer to one of the appropriate sections below. 

For instances That Do Not Use SugarIdentity

You can set up your instance to utilize a custom inactivity timeout via code-level customizations. The oauth2.access_token_lifetime setting controls how often Sugar will check to see if the user's token has expired. It is recommended to set the oauth2.access_token_lifetime value (e.g., 1800) to be half of the oauth2.refresh_token_lifetime (e.g., 3600). 

Note: Theoauth2.access_token_lifetime cannot exceed the maximum PHP session timeout, which is configured by PHP setting session.gc_maxlifetime. In SugarCloud the maximum session timeout is set to 7200s (2 hours).

You can change the default refresh and access token lifetime values by adding the following lines to the ./config_override.php file in the root directory of Sugar. An example is shown below:

              $sugar_config['oauth2']['refresh_token_lifetime'] = 3600; //do not exceed 2147220
$sugar_config['oauth2']['access_token_lifetime'] = 1800;

Note: We recommend the oauth2.refresh_token_lifetime remains at 1209600 seconds (2 weeks) or less for security. Should you increase this number, do not exceed 2147220 seconds.

These config settings restrict Sugar from refreshing a user's authentication. Once the change has been made, navigate to Admin > Repair and execute a "Quick Repair and Rebuild" action.

For Instances That Use SugarIdentity

For instances that use SugarIdentity, you can configure the access token and refresh token lifetimes in SugarIdentity by clicking "Token Lifetimes" in the home page. By default, the Access Token Lifetime is set to 60 minutes and the Refresh Token Lifetime is set to 20160 minutes on the Advanced Settings page.

To update your token lifetime values, simply enter the whole number value (e.g., 90) in the desired field (e.g., Access Token Lifetime), keeping in mind the following guidelines:

• The access token lifetime must be less than the refresh token lifetime.
• The access token lifetime must be at least 5 minutes.
• The refresh token lifetime must not exceed 20160 minutes.

After entering your desired value, click "Save" to preserve your changes. Please keep in mind that the new access and refresh token lifetimes will not take effect until the user's current access token expires in their user session. Once expired, Sugar will then renew the user's access and refresh tokens using the new values configured in SugarIdentity.

Setting Sugar's Notification Delay

Once the refresh and access token lifetimes are set, you should address the default Sugar notification system. Sugar's notification utilizes the OAuth token to query Sugar and see if there are any notifications to display to the current user. This query resets the time on the user's token, which causes their inactivity time to start over. To work around this, set the notification delay to be greater than the oauth2.refresh_token_lifetime setting.

The oauth2.refresh_token_lifetime setting controls the user inactivity timeout limit once Sugar's notification delay is altered as follows:

1. Create a new file ./custom/clients/base/views/notifications/notifications.php.
2. Add the following line of code to the file:

   <?php
   
   require 'clients/base/views/notifications/notifications.php';
   $viewdefs['base']['view']['notifications']['delay'] = 65; //should not exceed 35791

Note: Enter the value in minutes (e.g., 65) making sure that it is longer than the refresh_token_lifetime (1 hour) of your instance. The delay should not exceed 35791 minutes.

Once the change has been made, navigate to Admin > Repair and execute a "Quick Repair and Rebuild" action. Users must then clear their browser cache for the change to take effect.

Please note that this customization will change the default behavior of Sugar as it will query for potential notifications significantly less frequently than it normally does. For more information regarding Sugar notifications, please refer to the User Interface documentation.

Client IP Change

A user's IP address may change for a number of reasons. If a user's IP address changes while they are logged into Sugar the system, by default, will log the user out and force the user to log back in. The Client IP verification will return the error "You have been logged out because your session has expired." as well as logging "IP Address mismatch: SESSION IP: CLIENT IP: " in the Sugar log.

Disable client IP verification using the following steps:
Note: Beginning with version 10.1.0, the "Validate user IP address" setting is disabled by default in Admin > System Settings. 

1. Navigate to Admin > System Settings.
2. Scroll to the Advanced section at the bottom of the page.
3. Uncheck "Validate user IP address".
4. Click "Save" to preserve the change.

Once this update has been made, Sugar will no longer log out a user if their IP address changes.

Clearing Browser Cache and Cookies

Sugar uses your internet browser's cache to optimize page-load speeds and general performance by saving and reloading visited pages instead of pulling the same data over and over again each time you revisit a page. Beginning with version 10.0.0, when a user first logs into Sugar, they must accept the use of cookies in the application to help provide a better user experience. Occasionally, users may need to clear their browser's cache and cookies, and the methods used to perform this action will vary depending on the browser and operating system they use. Please note that performing this action can remove cookies from Sugar, which will end the user's current session and automatically log them out of the system. The user will need to log back into Sugar to access their account again.

Browser Tabs Closed

When a user is logged on to a Windows computer, they will be automatically logged out of Sugar if they close their browser including all Sugar tabs. When the user reopens their browser to access Sugar, they must log in to the instance again. Please note that all active Sugar browser tabs must be closed for you to get logged out of the system, so if you still have some other Sugar windows open, then you will still be logged in.

Using Mac OS X, this behaves slightly differently. A user must quit the browser process completely for Sugar to automatically log them out. Simply closing the browser tabs will not log the user out of Sugar. Furthermore, the end user's browser must be configured to allow this setting to log them out. Network Administrators may choose to enforce a browser security policy on their networked machines to verify that this setting is not modified by the end-user.

For example, to adjust this setting on a user's Chrome browser, navigate to Settings > Privacy and security > Site Settings > Cookies and site data then enable the "Clear cookies and site data when you quit Chrome" option. If this option is not enabled, then the user's session will remain active in Sugar until their token expires via other means.

Note: This setting will clear a user's stored info for all sites every time a browser session ends.