Session Configuration
This page tells you how to set the timeout period for a session token and how to enable/disable in-memory token storage.
Session Timeout
When a successful authentication occurs, for either an application or a user, a unique token is assigned. Tokens are valid for the period of time specified as the 'Session Timeout' attribute.
The session timeout determines how long a session will be considered valid during any period of inactivity. This value is specified in minutes and must be greater than 0.
To specify the session timeout,
- Log in to the Crowd Administration Console.
- Click the 'Administration' tab in the top navigation bar.
- Click 'Session Config' in the left-hand menu.
- The 'Session Config' screen will appear, as shown below. Type the new value into the 'Session Timeout' field, then click the 'Update' button.
Require Consistent Client IP Address
(Available since Crowd 2.5.2.)
Authenticated sessions can be tied to the IP address they were created from. This means that an attempt to use that session from another machine will fail, which will force mobile clients to reauthenticate when their IP address changes.
This setting can be disabled to relax that requirement, so a session can be used from any IP address. Note that changing this setting will invalidate any existing sessions, so you will be logged out after making this change.
To allow sessions to be used from any IP address,
- Log in to the Crowd Administration Console.
- Click the 'Administration' tab in the top navigation bar.
- Click 'Session Config' in the left-hand menu.
- The 'Session Config' screen will appear, as shown below. Check or uncheck 'Require Consistent Client IP Address' as required, then click the 'Update' button.
Authentication Token Storage
Authentication tokens are used to validate application and user sessions. A token is stored for each active session. By default, they're kept in the Crowd database. Storing these tokens in memory can benefit performance, but with some significant drawbacks:
- Sessions will not be saved across Crowd restarts. If you restart Crowd, all your users will have to log in again.
- Clustering will not be possible. Atlassian does not officially support clustering Crowd, but a number of our customers are successfully using it in this manner. See this knowledge-base article.
Switching from database to in-memory token management does not require a restart of Crowd; nor will sessions be lost or validations failed. However, if you have lots of active sessions, and therefore lots of tokens, it can take some time to copy the token information. During this time, validation requests will be queued and Crowd will appear unresponsive to client applications.
As a guide, below are some benchmarks of time taken to switch from one form of token storage to the other. The measurements were taken on a quad-core Mac Pro, using a lightly-loaded PostgreSQL database:
Number of Tokens: | 100 | 500 | 1000 | 5000 | 10000 |
|---|---|---|---|---|---|
Database -> Memory | 0.1s | 0.7s | 1.2s | 4.2s | 8.2s |
Memory -> Database | 1.2s | 4.8s | 9.2s | 45s | 90s |
To switch the token storage location,
- Log in to the Crowd Administration Console.
- Click the 'Administration' tab in the top navigation bar.
- Click 'Session Config' in the left-hand menu.
- The 'Session Config' screen will appear, as shown below. Select one of the radio buttons next to Authentication Token Storage:
- 'Database Cache' — This is the default option. Select it to store your tokens in the Crowd database. We recommend this option unless performance problems require in-memory storage.
- 'Memory Cache' — Select this option to store your tokens in memory.
- Click the 'Update' button.
Screenshot: 'Session Config'
In-memory cache size
The size of the in-memory token cache is defined in the crowd-webapp/WEB-INF/classes/crowd-ehcache.xml file. The default should be acceptable for most cases. If you require more than 2048 concurrent sessions in memory you may increase the size of the '-hash-cache' caches.