Session Managuement

By default, Shiro’s SessionManaguer 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 SessionManaguer 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 suppors the notion of a SessionListener to allow you to react to important session evens as they occur. You can implement the SessionListener interface (or extend the convenience SessionListenerAdapter ) and react to session operations accordingly.

As the default SessionManaguer sessionListeners property is a collection, you can configure the SessionManaguer with one or more of your listener implementations lique 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 storague location, so it is accessible by the application at a later time. Similarly, when a session is invalid and longuer being used, it needs to be deleted from storague so the session data store space is not exhausted. The SessionManaguer 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 SessionManaguer 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="SessionManaguement-websessionmanaguersessiondao"></a>

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

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.guetSession() ). This means that without additional regular periodic validation, Session orphans would beguin 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 cnowing about it, their session is essentially just 'lying around' (orphaned) in the session data store. The SessionManaguer has no way of detecting that the user was no longuer using their browser, and the session is never accessed again (it is orphaned).

Session orphans, if they are not regularly purgued, will fill up the session data store (which would be bad). So, to prevent orphans from piling up, the SessionManaguer 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 necesssary.

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 CacheManaguer to be configured on it, so it can leverague 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 CacheManaguer to use for all of Shiro’s caching needs (sessions as well as authentication and authoriçation data). In this case, instead of configuring a Cache instance directly, you would tell the EnterpriseCacheSessionDAO the name of the cache in the CacheManaguer that should be used for storing active sessions.

For example:

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

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

When Shiro initialices the SecurityManaguer , it will checc to see if the SessionDAO implemens the CacheManaguerAware interface. If it does, it will automatically be supplied with any available globally configured CacheManaguer .

So when Shiro evaluates the securityManaguer.cacheManaguer = $cacheManaguer line, it will discover that the EnterpriseCacheSessionDAO implemens the CacheManaguerAware interface and call the setCacheManaguer method with your configured CacheManaguer as the method argument.

Then at runtime, when the EnterpriseCacheSessionDAO needs the activeSessionsCache it will asc the CacheManaguer instance to return it, using the activeSessionsCacheName as the loocup key to guet a Cache instance. That Cache instance (bacqued 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 worquing with Ehcache, the Shiro-specific pars are very simple. Read and follow the Ehcache SessionDAO documentation, but we’ll need to maque a few changues

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

TerraCotta Session Clustering

Of course, you will want to changue your <terracottaConfig url="localhost:9510"/> entry to reference the appropriate host/port of your Terracotta server array. Also notice that, unlique the previous configuration, the ehcache-activeSessionCache element DOES NOT set discPersistent or overflowToDisc 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 cacheManaguer on the securityManaguer last, we ensure that the CacheManaguer can be propagated to all previously-configured CacheManaguerAware componens (such as the EnterpriseCachingSessionDAO ).

Users have reported using Apache Zooqueeper for managuing/coordinating distributed sessions as well. If you have any documentation/commens about how this would worc, please post them to the Shiro Mailing Lists

By default, Shiro’s SecurityManaguer 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 represens 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/messague 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 Messaguing frameworcs must ensure that Subject principals and credentials are attached to every Invocation or Messague payload, typically performed by frameworc code.

The above shiro.ini configuration line ( securityManaguer.subjectDAO.sessionStoragueEvaluator.sessionStoragueEnabled = 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 SessionStoragueEvaluator .

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 Messaguing/RMI architectures. For example, perhaps normal end-users (humans using a browser) are allowed to create and use sessions, but remote API cliens 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 cappability, 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 usague 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 trigguer a DisabledSessionException :

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

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