Session configuration

Overview of Lime CRM Sessions¶

All access to Lime CRM, whether interactive or non-interactive, begins and ends with a session. Sessions are a fundamental part of Lime CRM’s user authentication and activity management system, stored in the Lime CRM database.

Interactive Access¶

Interactive access includes scenarios like users logging in to the web client or desktop client. When users log in through the web server, a new Lime Session is created, recorded in the database, and maintained through a session cookie sent to the user's browser.

Non-Interactive Access¶

Non-interactive access refers to cases such as external applications utilizing the REST API or background tasks triggered by a web client user.

Session Authentication Methods¶

Access to Lime CRM is achieved through:

API Key: Included in a web request to the web server.
Session Cookie: Sent with a request to the web server and used for browser-based sessions.
Lime CRM Session ID: Used for background tasks and system jobs.

Session Metadata¶

A session contains metadata, such as the user accessing the application, the originating application, workstation details, and other relevant information. Sessions are stored within the Lime CRM application database.

Session Lifecycle¶

Session Creation: A new session is initiated upon successful authentication. If the user already has an active session, the existing session is reused.
Extending Session Lifetime: Active interaction with the system extends the session lifetime, preventing premature termination.
Session Termination: Sessions end when a user logs out, after a configurable period of inactivity, or when a user account is deactivated (e.g., via SCIM provisioning).
Session Deletion: Terminated sessions are deleted after a configurable retention period.

Session Timeout¶

The default Lime CRM session timeout is 24 hours, configurable in the setting table of the Lime CRM database. For password-based authentication, a timeout of 24 hours or longer is recommended to minimize frequent credential requests.

The session cookie links the browser session to the Lime CRM session. By default, it expires after 31 days. The cookie expiration can be configured to.

If the session cookie expires, users must log in again. External login providers (e.g., Microsoft Entra ID) may redirect users back to Lime CRM and issue a new session without requiring reauthentication, depending on the provider’s configuration.

Warning

To prevent session fixation, sessions are regenerated whenever a user logs in.

Automatic Session Extension¶

For seamless user experience, Lime CRM automatically extends the session lifetime for active users. This ensures uninterrupted access even if the session_timeout value is 24 hours.

To disable automatic session extension, update the configuration:

session:
    automatic_session_extension: False

Session Retention and Deletion¶

The Lime CRM session retention period defines how long session data is kept in the database after termination. By default, the retention period is 90 days. During this time, session data remains stored in the database before being permanently deleted.

Sessions with External Identity Providers (IDPs)¶

When users authenticate via external IDPs (e.g., Entra ID), Lime CRM creates an independent Lime Session. These sessions are managed separately from IDP sessions.

If a Lime Session remains active, users may access Lime CRM even if their IDP session has expired or been revoked.
To enforce frequent reauthentication, disable automatic session extension and set the session_timeout value to 1, ensuring sessions expire hourly.

Deprecation of Session Token-Based Authentication¶

Warning

Session token-based authentication is deprecated in favor of API key and session-based authentication methods (e.g., form-based login, Microsoft Entra ID, OpenID).

Session token-based authentication, previously used for action pads in the Desktop Client and integrations, is considered insecure and should not be enabled.

To re-enable it for legacy integrations (not recommended):

security:
    enable_sessionid_request_header_auth: True

Upgrading Legacy Applications¶

For legacy applications (e.g., LBS Apps), remove session ID-based code as shown below:

// Example 1: Remove session ID retrieval
var sessionId = lbs.limeDataConnection.Database.SessionID; // Remove

// Example 2: Remove session ID usage in AJAX headers
$.ajax({
    url: 'https://your-lime-crm.com/api/1.0/your-endpoint',
    headers: {
        'sessionId': sessionId // Remove
    }
});

The Desktop Client will now handle authentication automatically.