Session Management

By default, Shiro’s SessionManager implementations default to a 30-minute session timeout. That is, if any Session created remains idle (unused, where its lastAccessedTime isn’t updated) for 30 minutes or more, the Session is considered expired and will not be allowed to be used anymore.

You can set the default SessionManager implementation’s globalSessionTimeout property to define the default timeout value for all sessions. For example, if you wanted the timeout to be an hour instead of 30 minutes:

Setting the Default Session Timeout in shiro.ini

=

Shiro supports the notion of a SessionListener to allow you to react to important session events as they occur. You can implement the SessionListener interface (or extend the convenience SessionListenerAdapter) and react to session operations accordingly.

As the default SessionManager sessionListeners property is a collection, you can configure the SessionManager with one or more of your listener implementations like any other collection in shiro.ini:

SessionListener Configuration in shiro.ini

Whenever a session is created or updated, its data needs to persisted to a storage location, so it is accessible by the application at a later time. Similarly, when a session is invalid and longer being used, it needs to be deleted from storage so the session data store space is not exhausted. The SessionManager implementations delegate these Create/Read/Update/Delete (CRUD) operations to an internal component, the SessionDAO, which reflects the Data Access Object (DAO) design pattern.

The power of the SessionDAO is that you can implement this interface to communicate with any data store you wish. This means your session data can reside in memory, on the file system, in a relational database or NoSQL data store, or any other location you need. You have control over persistence behavior.

You can configure any SessionDAO implementation as a property on the default SessionManager instance. For example, in shiro.ini:

Configuring a SessionDAO in shiro.ini

However, as you might expect, Shiro already has some good SessionDAO implementations that you can use out of the box or subclass for your own needs. <a name="SessionManagement-websessionmanagersessiondao"></a>

Note that web applications use a servlet-container-based SessionManager by default and do not have this issue. This is only an issue when using a Shiro native SessionManager.')

Sessions must be validated so any invalid (expired or stopped) sessions can be deleted from the session data store. This ensures that the data store does not fill up over time with sessions that will never be used again.

For performance reasons, Sessions are only validated to see if they have been stopped or expired at the time they are accessed (i.e. subject.getSession()). This means that without additional regular periodic validation, Session orphans would begin to fill up the session data store.

A common example illustrating orphans is the web browser scenario: Let’s say a user logs in to a web application and a session is created to retain data (authentication state, shopping cart, etc). If the user does not log out and closes their browser without the application knowing about it, their session is essentially just 'lying around' (orphaned) in the session data store. The SessionManager has no way of detecting that the user was no longer using their browser, and the session is never accessed again (it is orphaned).

Session orphans, if they are not regularly purged, will fill up the session data store (which would be bad). So, to prevent orphans from piling up, the SessionManager implementations support the notion of a SessionValidationScheduler. A SessionValidationScheduler is responsible for validating sessions at a periodic rate to ensure they are cleaned up as necessary.

As you might expect, Shiro already provides a SessionDAO implementation that will persist data to an enterprise/distributed Cache. The EnterpriseCacheSessionDAO expects a Shiro Cache or CacheManager to be configured on it, so it can leverage the caching mechanism.

For example, in shiro.ini:

Although you could inject a Cache instance directly to the SessionDAO as shown above, it is usually far more common to configure a general CacheManager to use for all of Shiro’s caching needs (sessions as well as authentication and authorization data). In this case, instead of configuring a Cache instance directly, you would tell the EnterpriseCacheSessionDAO the name of the cache in the CacheManager that should be used for storing active sessions.

For example:

But there’s something a bit strange about the above configuration. Did you notice it?

The interesting thing about this config is that nowhere in the config did we actually tell the sessionDAO instance to use a Cache or CacheManager! So how does the sessionDAO use the distributed cache?

When Shiro initializes the SecurityManager, it will check to see if the SessionDAO implements the CacheManagerAware interface. If it does, it will automatically be supplied with any available globally configured CacheManager.

So when Shiro evaluates the securityManager.cacheManager = $cacheManager line, it will discover that the EnterpriseCacheSessionDAO implements the CacheManagerAware interface and call the setCacheManager method with your configured CacheManager as the method argument.

Then at runtime, when the EnterpriseCacheSessionDAO needs the activeSessionsCache it will ask the CacheManager instance to return it, using the activeSessionsCacheName as the lookup key to get a Cache instance. That Cache instance (backed by your distributed/enterprise caching product’s API) will be used to store and retrieve sessions for all of the SessionDAO CRUD operations.

One such distributed caching solution that people have had success with while using Shiro is the Ehcache + Terracotta pairing. See the Ehcache-hosted Distributed Caching With Terracotta documentation for full details of how to enable distributed caching with Ehcache.

Once you’ve got Terracotta clustering working with Ehcache, the Shiro-specific parts are very simple. Read and follow the Ehcache SessionDAO documentation, but we’ll need to make a few changes

The Ehcache Session Cache Configuration referenced previously will not work - a Terracotta-specific configuration is needed. Here is an example configuration that has been tested to work correctly. Save its contents in a file and save it in an ehcache.xml file:

TerraCotta Session Clustering

Of course, you will want to change your <terracottaConfig url="localhost:9510"/> entry to reference the appropriate host/port of your Terracotta server array. Also notice that, unlike the previous configuration, the ehcache-activeSessionCache element DOES NOT set diskPersistent or overflowToDisk attributes to true. They should both be false as true values are not supported in clustered configuration.

After you’ve saved this ehcache.xml file, we’ll need to reference it in Shiro’s configuration. Assuming you’ve made the terracotta-specific ehcache.xml file accessible at the root of the classpath, here is the final Shiro configuration that enables Terracotta+Ehcache clustering for all of Shiro’s needs (including Sessions):

shiro.ini for Session Clustering with Ehcache and Terracotta

And remember, ORDER MATTERS. By configuring the cacheManager on the securityManager last, we ensure that the CacheManager can be propagated to all previously-configured CacheManagerAware components (such as the EnterpriseCachingSessionDAO).

Users have reported using Apache Zookeeper for managing/coordinating distributed sessions as well. If you have any documentation/comments about how this would work, please post them to the Shiro Mailing Lists

By default, Shiro’s SecurityManager implementations will use a Subject’s Session as a strategy to store the Subject’s identity (PrincipalCollection) and authentication state (subject.isAuthenticated()) for continued reference. This typically occurs after a Subject logs-in or when a Subject’s identity is discovered via RememberMe services.

There are a few benefits to this default approach:

While the above default strategy is fine (and often desirable) for most applications, this would not be desirable in applications that try to be stateless whenever possible. Many stateless architectures mandate that no persistent state can exist between requests, in which case Sessions would not be allowed (a Session by its very nature represents durable state).

But this requirement comes at a convenience cost - Subject state cannot be retained across requests. This means that applications with this requirement must ensure Subject state can be represented in some other way for every request.

This is almost always achieved by authenticating every request/invocation/message handled by the application. For example, most stateless web applications typically support this by enforcing HTTP Basic authentication, allowing the browser to authenticate every request on behalf of an end user. Remoting or Messaging frameworks must ensure that Subject principals and credentials are attached to every Invocation or Message payload, typically performed by framework code.

The above shiro.ini configuration line (securityManager.subjectDAO.sessionStorageEvaluator.sessionStorageEnabled = false) will disable Shiro from using the Session as an implementation strategy for all Subjects.

But what if you wanted a hybrid approach? What if some Subjects should have sessions and others should not? This hybrid approach can be beneficial for many applications. For example:

If you need this hybrid approach, you can implement a SessionStorageEvaluator.

Often web applications wish to simply enable or disable session creation on a per-request basis, regardless of which Subject is executing a request. This is often used to good effect in supporting REST and Messaging/RMI architectures. For example, perhaps normal end-users (humans using a browser) are allowed to create and use sessions, but remote API clients use REST or SOAP and shouldn’t have sessions at all (because they authenticate on every request, as is common in REST/SOAP architectures).

To support this hybrid/per-request capability, a noSessionCreation filter has been added to Shiro’s 'pool' of default filters enabled for web applications. This filter will prevent new sessions from being created during a request to guarantee a stateless experience. In shiro.ini [urls] section, you typically define this filter in front of all others to ensure a session will never be used.

For example:

shiro.ini - Disable Session Creation per request

This filter allows session usage for any existing session, but will not allow new sessions to be created during the filtered request. That is, any of the four following method calls on a request or subject that do not already have an existing session will automatically trigger a DisabledSessionException:

If a Subject already has a session prior to visiting the noSessionCreation-protected-URL, the above 4 calls will still work as expected.

Finally, the following calls will always be allowed in all cases: