Session Management

• Using Sessions
• The SessionManager

  • Session Timeout

    • Per-Session Timeout

  • Session Listeners

  • Session Storage

    • EHCache SessionDAO

      • EHCache Session Cache Configuration
      • EHCache Session Cache Name

    • Custom Session IDs

  • Session Validation & Scheduling

    • Default SessionValidationScheduler
    • Custom SessionValidationScheduler
    • Disabling Session Validation
    • Invalid Session Deletion

• Session Clustering

  • EnterpriseCacheSessionDAO
  • Ehcache + Terracotta
  • Zookeeper

• Sessions and Subject State

  • Stateful Applications (Sessions allowed)
  • Stateless Applications (Sessionless)

    • Disabling Subject State Session Storage

  • A Hybrid Approach

    • SessionStorageEvaluator

      • Subject Inspection

    • Configuration

  • Web Applications

Apache Shiro offers something unique in the world of security frameworks: a complete enterprise-grade Session solution for any application, from the simplest command-line and smart phone applications to the largest clustered enterprise web applications.

This has large implications for many applications - until Shiro, if you required session support, you were required to deploy your application in a web container or use EJB Stateful Session Beans. Shiro’s Session support is much simpler to use and manage than either of these two mechanisms, and it is available in any application, regardless of container.

And even if you deploy your application in a Servlet or EJB container, there are still compelling reasons to use Shiro’s Session support instead of the container’s. Here is a list of the most desirable features provided by Shiro’s session support:

Features

• POJO/J2SE based (IoC friendly) - Everything in Shiro (including all aspects of Sessions and Session Management) is interface-based and implemented with POJOs. This allows you to easily configure all session components with any JavaBeans-compatible configuration format, like JSON, YAML, Spring XML or similar mechanisms. You can also easily extend Shiro’s components or write your own as necessary to fully customize session management functionality.

• Easy Custom Session Storage - Because Shiro’s Session objects are POJO-based, session data can be easily stored in any number of data sources. This allows you to customize exactly where your application’s session data resides - for example, the file system, in memory, in a networked distributed cache, a relational database, or proprietary data store.

• Container-Independent Clustering! - Shiro’s sessions can be easily clustered using any of the readily-available networked caching products, like Ehcache + Terracotta, Coherence, GigaSpaces, et. al. This means you can configure session clustering for Shiro once and only once, and no matter what container you deploy to, your sessions will be clustered the same way. No need for container-specific configuration!

• Heterogeneous Client Access - Unlike EJB or Web sessions, Shiro sessions can be ‘shared’ across various client technologies. For example, a desktop application could ‘see’ and ‘share’ the same physical session used by the same user in a web application. We are unaware of any framework other than Shiro that can support this.

• Event Listeners - Event listeners allow you to listen to lifecycle events during a session’s lifetime. You can listen for these events and react to them for custom application behavior - for example, updating a user record when their session expires.

• Host Address Retention – Shiro Sessions retain the IP address or host name of the host from where the session was initiated. This allows you to determine where the user is located and react accordingly (often useful in intranet environments where IP association is deterministic).

• Inactivity/Expiration Support – Sessions expire due to inactivity as expected, but they can be prolonged via a touch() method to keep them ‘alive’ if desired. This is useful in Rich Internet Application (RIA) environments where the user might be using a desktop application, but may not be regularly communicating with the server, but the server session should not expire.

• Transparent Web Use - Shiro’s web support fully implements and supports the Servlet 2.5 specification for Sessions (HttpSession interface and all of it’s associated APIs). This means you can use Shiro sessions in existing web applications and you don’t need to change any of your existing web code.

• Can be used for SSO - Because Shiro session’s are POJO based, they are easily stored in any data source, and they can be ‘shared’ across applications if needed. We call this ‘poor man’s SSO’, and it can be used to provide a simple sign-on experience since the shared session can retain authentication state.

Using Sessions

Like almost everything else in Shiro, you acquire a Session by interacting with the currently executing Subject:

Subject currentUser = SecurityUtils.getSubject();

Session session = currentUser.getSession();
session.setAttribute( "someKey", someValue);

The currentUser.getSession() method is a shortcut for calling currentUser.getSession(true).

For those familiar with HttpServletRequest API, the Subject.getSession(boolean create) method functions the same way as the HttpServletRequest.getSession(boolean create) method:

• If the Subject already has a Session, the boolean argument is ignored and the Session is returned immediately
• If the Subject does not yet have a Session and the create boolean argument is true, a new session will be created and returned.
• If the Subject does not yet have a Session and the create boolean argument is false, a new session will not be created and null is returned.

subject.getSession(false) can be used to good effect when developing framework code to ensure a Session isn’t created unnecessarily.

Once you acquire a Subject’s Session you can do many things with it, like set or retrieve attributes, set its timeout, and more. See the Session JavaDoc to see what is possible with an individual session.

The SessionManager

The SessionManager, as its name might imply, manages Sessions for all subjects in an application - creation, deletion, inactivity and validation, etc. Like other core architectural components in Shiro, the SessionManager is a top-level component maintained by the SecurityManager.

The default SecurityManager implementation defaults to using a DefaultSessionManager out of the box. The DefaultSessionManager implementation provides all of the enterprise-grade session management features needed for an application, like Session validation, orphan cleanup, etc. This can be used in any application.

Like all other components managed by the SecurityManager, the SessionManager can be acquired or set via JavaBeans-style getter/setter methods on all of Shiro’s default SecurityManager implementations (getSessionManager()/setSessionManager()). Or for example, if using shiro.ini Configuration:

Configuring a new SessionManager in shiro.ini

[main]
...
sessionManager = com.foo.my.SessionManagerImplementation
securityManager.sessionManager = $sessionManager

But creating a SessionManager from scratch is a complicated task and not something that most people will want to do themselves. Shiro’s out-of-the-box SessionManager implementations are highly customizable and configurable and will suit most needs. Most of the rest of this documentation assumes that you will be using Shiro’s default SessionManager implementations when covering configuration options, but note that you can essentially create or plug-in nearly anything you wish.

Session Timeout

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

[main]
...
# 3,600,000 milliseconds = 1 hour
securityManager.sessionManager.globalSessionTimeout = 3600000

Per-Session Timeout

The above globalSessionTimeout value is the default for all newly created Sessions. You can control session timeout on a per-Session basis by setting the individual Session’s timeout value. Like the above globalSessionTimeout, the value is time in milliseconds (not seconds).

Session Listeners

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

[main]
...
aSessionListener = com.foo.my.SessionListener
anotherSessionListener = com.foo.my.OtherSessionListener

securityManager.sessionManager.sessionListeners = $aSessionListener, $anotherSessionListener, etc.

Session Storage

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

[main]
...
sessionDAO = com.foo.my.SessionDAO
securityManager.sessionManager.sessionDAO = $sessionDAO

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.

[main]
...
sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
securityManager.sessionManager = $sessionManager

# Configure a SessionDAO and then set it:
securityManager.sessionManager.sessionDAO = $sessionDAO

EHCache SessionDAO

EHCache is not enabled by default, but if you do not plan on implementing your own SessionDAO, it is highly recommended that you enable the EHCache support for Shiro’s SessionManagement. The EHCache SessionDAO will store sessions in memory and support overflow to disk if memory becomes constrained. This is highly desirable for production applications to ensure that you don’t randomly ‘lose’ sessions at runtime.

Enabling EHCache for sessions is very easy. First, ensure that you have the shiro-ehcache-<version>.jar file in your classpath (see the Download page or use Maven or Ant+Ivy).

Once in the classpath, this first shiro.ini example shows you how to use EHCache for all of Shiro’s caching needs (not just Session support):

Configuring EHCache for all of Shiro’s caching needs in shiro.ini

[main]

sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
securityManager.sessionManager.sessionDAO = $sessionDAO

cacheManager = org.apache.shiro.cache.ehcache.EhCacheManager
securityManager.cacheManager = $cacheManager

The final line, securityManager.cacheManager = $cacheManager, configures a CacheManager for all of Shiro’s needs. This CacheManager instance will propagate down to the SessionDAO automatically (by nature of EnterpriseCacheSessionDAO implementing the CacheManagerAware interface).

Then, when the SessionManager asks the EnterpriseCacheSessionDAO to persist a Session, it will use an EHCache-backed Cache implementation to store the Session data.

EHCache Session Cache Configuration

By default, the EhCacheManager uses a Shiro-specific ehcache.xml file that sets up the Session cache region and the necessary settings to ensure Sessions are stored and retrieved properly.

However, if you wish to change the cache settings, or configure your own ehcache.xml or EHCache net.sf.ehcache.CacheManager instance, you will need to configure the cache region to ensure that Sessions are handled correctly.

If you look at the default ehcache.xml file, you will see the following shiro-activeSessionCache cache configuration:

<cache name="shiro-activeSessionCache"
       maxElementsInMemory="10000"
       overflowToDisk="true"
       eternal="true"
       timeToLiveSeconds="0"
       timeToIdleSeconds="0"
       diskPersistent="true"
       diskExpiryThreadIntervalSeconds="600"/>

If you wish to use your own ehcache.xml file, ensure that you have defined a similar cache entry for Shiro’s needs. Most likely you might change the maxElementsInMemory attribute value to meet your needs. However, it is very important that at least the following two attributes exist (and are not changed) in your own configuration:

• overflowToDisk="true" - this ensures that if you run out of process memory, sessions won’t be lost and can serialized to disk
• eternal="true" - ensures that cache entries (Session instances) are never expired or expunged automatically by the cache. This is necessary because Shiro does its own validation based on a scheduled process (see “Session Validation & Scheduling” below). If we turned this off, the cache would likely evict Sessions without Shiro knowing about it, which could cause problems.

EHCache Session Cache Name

By default, the EnterpriseCacheSessionDAO asks the CacheManager for a Cache named “shiro-activeSessionCache”. This cache name/region is expected to be configured in ehcache.xml, as mentioned above.

If you want to use a different name instead of this default, you can configure that name on the EnterpriseCacheSessionDAO, for example:

Configuring the cache name for Shiro’s active session cache in shiro.ini<

...
sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
sessionDAO.activeSessionsCacheName = myname
...

Just ensure that a corresponding entry in ehcache.xml matches that name and you’ve configured overflowToDisk="true" and eternal="true" as mentioned above.

Custom Session IDs

Shiro’s SessionDAO implementations use an internal SessionIdGenerator component to generate a new Session ID every time a new session is created. The ID is generated, assigned to the newly created Session instance, and then the Session is saved via the SessionDAO.

The default SessionIdGenerator is a JavaUuidSessionIdGenerator, which generates String IDs based on Java UUIDs. This implementation is suitable for all production environments.

If this does not meet your needs, you can implement the SessionIdGenerator interface and configure the implementation on Shiro’s SessionDAO instance. For example, in shiro.ini:

Configuring a SessionIdGenerator in shiro.ini

[main]
...
sessionIdGenerator = com.my.session.SessionIdGenerator
securityManager.sessionManager.sessionDAO.sessionIdGenerator = $sessionIdGenerator

Session Validation & Scheduling

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.

Default SessionValidationScheduler

The default SessionValidationScheduler usable in all environments is the ExecutorServiceSessionValidationScheduler which uses a JDK ScheduledExecutorService to control how often the validation should occur.

By default, this implementation will perform validation once per hour. You can change the rate at which validation occurs by specifying a new instance of ExecutorServiceSessionValidationScheduler and specifying a different interval (in milliseconds):

ExecutorServiceSessionValidationScheduler interval in shiro.ini

[main]
...
sessionValidationScheduler = org.apache.shiro.session.mgt.ExecutorServiceSessionValidationScheduler
# Default is 3,600,000 millis = 1 hour:
sessionValidationScheduler.interval = 3600000

securityManager.sessionManager.sessionValidationScheduler = $sessionValidationScheduler

Custom SessionValidationScheduler

If you wish to provide a custom SessionValidationScheduler implementation, you can specify it as a property of the default SessionManager instance. For example, in shiro.ini:

Configuring a custom SessionValidationScheduler in shiro.ini

[main]
...
sessionValidationScheduler = com.foo.my.SessionValidationScheduler
securityManager.sessionManager.sessionValidationScheduler = $sessionValidationScheduler

Disabling Session Validation

In some cases, you might wish to disable session validation entirely because you have set up a process outside of Shiro’s control to perform the validation for you. For example, maybe you are using an enterprise Cache and rely on the cache’s Time To Live setting to automatically expunge old sessions. Or maybe you’ve set up a cron job to auto-purge a custom data store. In these cases you can turn off session validation scheduling:

Disabling Session Validation Scheduling in shiro.ini

[main]
...
securityManager.sessionManager.sessionValidationSchedulerEnabled = false

Sessions will still be validated when they are retrieved from the session data store, but this will disable Shiro’s periodic validation.

Invalid Session Deletion

As we’ve stated above, the purpose of periodic session validation is mainly to delete any invalid (expired or stopped) sessions to ensure they do not fill up the session data store.

By default, whenever Shiro detects an invalid session, it attempts to delete it from the underlying session data store via the SessionDAO.delete(session) method. This is good practice for most applications to ensure the session data storage space is not exhausted.

However, some applications may not wish for Shiro to automatically delete sessions. For example, if an application has provided a SessionDAO that backs a queryable data store, perhaps the application team wishes old or invalid sessions to be available for a certain period of time. This would allow the team to run queries against the data store to see, for example, how many sessions a user has created over the last week, or the average duration of a user’s sessions, or similar reporting-type queries.

In these scenarios, you can turn off invalid session deletion entirely. For example, in shiro.ini:

Disabling Invalid Session Deletion in shiro.ini

[main]
...
securityManager.sessionManager.deleteInvalidSessions = false

But be careful! If you turn this off, you are responsible for ensuring that your session data store doesn’t exhaust its space. You must delete invalid sessions from you data store yourself!

Note also that even if you prevent Shiro from deleting invalid sessions, you still should enable session validation somehow - either via Shiro’s existing validation mechanisms or via a custom mechanism you provide yourself (see the above “Disabling Session Validation” section above for more). The validation mechanism will update your session records to reflect the invalid state (e.g. when it was invalidated, when it was last accessed, etc), even if you will delete them manually yourself at some other time.

#This implementation would use your preferred distributed caching product's APIs:
activeSessionsCache = my.org.apache.shiro.cache.CacheImplementation

sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
sessionDAO.activeSessionsCache = $activeSessionsCache

securityManager.sessionManager.sessionDAO = $sessionDAO

# This implementation would use your caching product's APIs:
cacheManager = my.org.apache.shiro.cache.CacheManagerImplementation

# Now configure the EnterpriseCacheSessionDAO and tell it what
# cache in the CacheManager should be used to store active sessions:
sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
# This is the default value.  Change it if your CacheManager configured a different name:
sessionDAO.activeSessionsCacheName = shiro-activeSessionsCache
# Now have the native SessionManager use that DAO:
securityManager.sessionManager.sessionDAO = $sessionDAO

# Configure the above CacheManager on Shiro's SecurityManager
# to use it for all of Shiro's caching needs:
securityManager.cacheManager = $cacheManager

<ehcache>
    <terracottaConfig url="localhost:9510"/>
    <diskStore path="java.io.tmpdir/shiro-ehcache"/>
    <defaultCache
            maxElementsInMemory="10000"
            eternal="false"
            timeToIdleSeconds="120"
            timeToLiveSeconds="120"
            overflowToDisk="false"
            diskPersistent="false"
            diskExpiryThreadIntervalSeconds="120">
        <terracotta/>
    </defaultCache>
    <cache name="shiro-activeSessionCache"
           maxElementsInMemory="10000"
           eternal="true"
           timeToLiveSeconds="0"
           timeToIdleSeconds="0"
           diskPersistent="false"
           overflowToDisk="false"
           diskExpiryThreadIntervalSeconds="600">
        <terracotta/>
    </cache>
    <!-- Add more cache entries as desired, for example,
         Realm authc/authz caching: -->
</ehcache>

sessionDAO = org.apache.shiro.session.mgt.eis.EnterpriseCacheSessionDAO
# This name matches a cache name in ehcache.xml:
sessionDAO.activeSessionsCacheName = shiro-activeSessionsCache
securityManager.sessionManager.sessionDAO = $sessionDAO

# Configure The EhCacheManager:
cacheManager = org.apache.shiro.cache.ehcache.EhCacheManager
cacheManager.cacheManagerConfigFile = classpath:ehcache.xml

# Configure the above CacheManager on Shiro's SecurityManager
# to use it for all of Shiro's caching needs:
securityManager.cacheManager = $cacheManager

[main]
...
securityManager.subjectDAO.sessionStorageEvaluator.sessionStorageEnabled = false
...

public interface SessionStorageEvaluator {

    public boolean isSessionStorageEnabled(Subject subject);

}

...
    public boolean isSessionStorageEnabled(Subject subject) {
        boolean enabled = false;
        if (WebUtils.isWeb(Subject)) {
            HttpServletRequest request = WebUtils.getHttpRequest(subject);
            //set 'enabled' based on the current request.
        } else {
            //not a web request - maybe a RMI or daemon invocation?
            //set 'enabled' another way...
        }

        return enabled;
    }

[main]
...
sessionStorageEvaluator = com.mycompany.shiro.subject.mgt.MySessionStorageEvaluator
securityManager.subjectDAO.sessionStorageEvaluator = $sessionStorageEvaluator

...

[urls]
...
/rest/** = noSessionCreation, authcBasic, ...