Fork me on GitHub

Apache Shiro Logo Simple. Java. Security. Apache Software Foundation Event Banner

Handy Hint
Shiro v1 version notice

As of February 28, 2024, Shiro v1 was superseded by v2.

Table of Contents


The simplest way to integrate Shiro into any web application is to configure a Servlet ContextListener and Filter in web.xml that understands how to read Shiro’s INI configuration. The bulk of the INI config format itself is defined in the Configuration pages’s INI Sections section, but we’ll cover some additional web-specific sections here.

Example 1. Using Jakarta EE?

The below configuration is not required if using Jakarta EE integration or basic CDI integration module.

Example 2. Using Spring?

Spring Framework users will not perform this setup. If you use Spring, you will want to read about Spring-specific web configuration instead.


Shiro 1.2 and later

In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to web.xml:


<!-- ... -->



This assumes a Shiro INI Configuration file is located at either of the following two locations, using whichever is found first:

  1. /WEB-INF/shiro.ini

  2. shiro.ini file at the root of the classpath.

Here is what the above config does:

  • The EnvironmentLoaderListener initializes a Shiro WebEnvironment instance (which contains everything Shiro needs to operate, including the SecurityManager) and makes it accessible in the ServletContext. If you need to obtain this WebEnvironment instance at any time, you can call WebUtils.getRequiredWebEnvironment(servletContext).

  • The ShiroFilter will use this WebEnvironment to perform all necessary security operations for any filtered request.

  • Finally, the filter-mapping definition ensures that all requests are filtered by the ShiroFilter, recommended for most web applications to ensure that any request can be secured.

ShiroFilter filter-mapping

It is usually desirable to define the ShiroFilter filter-mapping before any other filter-mapping declarations to ensure that Shiro can function in those filters as well.

Example 3. ShiroFilter default encoding

The shiro filter is a standard servlet filter, with a default encoding of ISO-8859-1 according to the servlet specification. However, the client can choose to send authentication data with a different encoding using the charset attribute of the Content-Type header.

Custom WebEnvironment Class

By default, the EnvironmentLoaderListener will create an IniWebEnvironment instance, which assumes Shiro’s INI-based Configuration. If you like, you may specify a custom WebEnvironment instance instead by specifying a ServletContext context-param in web.xml:


This allows you to customize how a configuration format is parsed and represented as a WebEnvironment instance. You could subclass the existing IniWebEnvironment for custom behavior, or support different configuration formats entirely. For example, if someone wanted to configure Shiro in XML instead of INI, they could create an XML-based implementation, e.g.

Custom Configuration Locations

The IniWebEnvironment class expects to read and load INI configuration files. By default, this class will automatically look in the following two locations for the Shiro .ini configuration (in order):

  1. /WEB-INF/shiro.ini

  2. classpath:shiro.ini

It will use whichever is found first.

However, if you wish to place your config in another location, you may specify that location with another context-param in web.xml:


By default, the param-value is expected to be resolvable by the rules defined by ServletContext.getResource method. For example, /WEB-INF/some/path/shiro.ini

But you may also specify specific file-system, classpath or URL locations by using an appropriate resource prefix supported by Shiro’s ResourceUtils class, for example:

  • file:/home/foobar/myapp/shiro.ini

  • classpath:com/foo/bar/shiro.ini

  • url:

Shiro 1.1 and earlier

The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a filter-mapping:


<!-- ... -->

<!-- Make sure any request you want accessible to Shiro is filtered. /* catches all -->
<!-- requests.  Usually this filter mapping is defined first (before all others) to -->
<!-- ensure that Shiro works in subsequent filters in the filter chain:             -->

This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. classpath:shiro.ini).

Custom Path

If you do not want to place your INI config in /WEB-INF/shiro.ini or classpath:shiro.ini, you may specify a custom resource location as necessary. Add a configPath init-param and specify a resource location:



Unqualified (schemeless or 'non-prefixed') configPath values are assumed to be ServletContext resource paths, resolvable via the rules defined by the ServletContext.getResource method.

ServletContext resource paths - Shiro 1.2+

ServletContext resource paths are available in Shiro 1.2 and later. In 1.1 and earlier, all configPath definitions must specify a classpath:, file: or url: prefix.

You may also specify other non-ServletContext resource locations by using classpath:, url:, or file: prefixes indicating classpath, url, or filesystem locations respectively. For example:

Inline Config

Finally, it is also possible to embed your INI configuration inline in web.xml without using an INI file at all. You do this by using the config init-param instead of configPath:


    # INI Config Here


Inline config is often fine for small or simple applications, but it is usually more convenient to externalize it in a dedicated shiro.ini file for the following reasons:

  • You might edit security configuration a lot and don’t want to add revision control 'noise' to the web.xml file

  • You might want to separate security config from the rest of web.xml config

  • Your security configuration might become large, and you want to keep web.xml lean and easier to read

  • You have a complex build system where the same shiro config might need to be referenced in multiple places

It is up to you - use what makes sense for your project.

Web INI configuration

In addition to the standard [main], [users] and [roles] sections already described in the main Configuration chapter, you can additionally specify a web-specific [urls] section in your shiro.ini file:

# [main], [users] and [roles] above here

The [urls] section allows you to do something that doesn’t exist in any web framework that we’ve seen yet: the ability to define ad-hoc filter chains for any matching URL path in your application!

This is far more flexible, powerful and concise than how you define filter chains normally in web.xml: even if you never used any other feature that Shiro provided and used only this, it alone would make it worth using.


The format of each line in the urls section is as follows:

_URL_Ant_Path_Expression_ = _Path_Specific_Filter_Chain_

For example:


/index.html = anon
/user/create = anon
/user/** = authc
/admin/** = authc, roles[administrator]
/rest/** = authc, rest
/remoting/rpc/** = authc, perms["remote:invoke"]

Next we’ll cover exactly what these lines mean.

URL Path Expressions

The token on the left of the equals sign (=) is an Ant-style path expression relative to your web application’s context root.

For example, let’s say you had the following [urls] line:

/account/** = ssl, authc

This line states that "Any request to my application’s path of /account or any of its sub paths (/account/foo, /account/bar/baz, etc.) will trigger the 'ssl, authc' filter chain". We’ll cover filter chains below.

Note that all path expressions are relative to your application’s context root. This means that if you deploy your application one day to, say, and then later deploy it to (no 'myapp' sub-path), the pattern matching will still work. All paths are relative to the HttpServletRequest.getContextPath() value.

Order Matters!

URL path expressions are evaluated against an incoming request in the order they are defined and the FIRST MATCH WINS. For example, let’s assume that there are the following chain definitions:

/account/** = ssl, authc
/account/signup = anon

Always remember to define your filter chains based on a FIRST MATCH WINS policy!

Filter Chain Definitions

The token on the right of the equals sign (=) is comma-delimited list of filters to execute for a request matching that path. It must match the following format:

filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]


  • filterN is the name of a filter bean defined in the [main] section and

  • [optional_configN] is an optional bracketed string that has meaning for that particular filter for that particular path (per-filter, path-specific configuration!). If the filter does not need specific config for that URL path, you may discard the brackets so filterN[] just becomes filterN.

And because filter tokens define chains (aka a List), remember that order matters! Define your comma-delimited list in the order that you want the request to flow through the chain.

Finally, each filter is free to handle the response however it wants if its necessary conditions are not met (e.g. perform a redirect, respond with an HTTP error code, direct rendering, etc). Otherwise, it is expected to allow the request to continue through the chain on to the final destination view.


Being able to react to path specific configuration, i.e. the [optional_configN] part of a filter token, is a unique feature available to Shiro filters.

If you want to create your own javax.servlet.Filter implementation that can also do this, make sure your filter subclasses org.apache.shiro.web.filter.PathMatchingFilter.

Available Filters

The 'pool' of filters available for use in filter chain definitions are defined in the [main] section. The name assigned to them in the main section is the name to use in the filter chain definitions. For example:

myFilter =
myFilter.property1 = value1

/some/path/** = myFilter

Default Filters

When running a web-app, Shiro will create some useful default Filter instances and make them available in the [main] section automatically. You can configure them in main as you would any other bean and reference them in your chain definitions. For example:

# Notice how we didn't define the class for the FormAuthenticationFilter ('authc') - it is instantiated and available already:
authc.loginUrl = /login.jsp

# make sure the end-user is authenticated.  If not, redirect to the 'authc.loginUrl' above,
# and after successful authentication, redirect them back to the original account page they
# were trying to view:
/account/** = authc

The default Filter instances available automatically are defined by the DefaultFilter enum and the enum’s name field is the name available for configuration. They are:

Filter Name Class



























Enabling and Disabling Filters

As is the case with any filter chain definition mechanism (web.xml, Shiro’s INI, etc.), you enable a filter just by including it in the filter chain definition, and you disable it by removing it from the chain definition.

But a new feature added in Shiro 1.2 is the ability to enable or disable filters without removing them from the filter chain. If enabled (the default setting), then a request will be filtered as expected. If disabled, then the filter will allow the request to pass through immediately to the next element in the FilterChain. You can trigger a filter’s enabled state generally based on a configuration property, or you can even trigger it on a per-request basis.

This is a powerful concept because it is often more convenient to enable or disable a filter based on certain requirements than to change the static filter chain definition, which would be permanent and inflexible.

Shiro accomplishes this via its OncePerRequestFilter abstract parent class. All of Shiro’s out-of-the-box Filter implementations subclass this one and therefore are able to be enabled or disabled without removing them from the filter chain. You can subclass this class for your own filter implementations if you need this functionality as well*.

*[SHIRO-224] will hopefully enable this feature for any filter, not just those subclassing OncePerRequestFilter. If this is important to you, please vote for the issue.

General Enabling/Disabling

The OncePerRequestFilter (and all of its subclasses) supports enabling/disabling across all requests as well as on a per-request basis.

General enabling or disabling of a filter for all requests is done by setting its enabled property to true or false. The default setting is true since most filters inherently need to execute if they are configured in a chain.

For example, in shiro.ini:

# configure Shiro's default 'ssl' filter to be disabled while testing:
ssl.enabled = false

/some/path = ssl, authc
/another/path = ssl, roles[admin]

This example shows that potentially many URL paths can all require that a request must be secured by an SSL connection. Setting up SSL while in development can be frustrating and time-consuming. While in development, you can disable the ssl filter. When deploying to production, you can enable it with one configuration property - something that is much easier than manually changing all the URL paths or maintaining two Shiro configurations.

Request-specific Enabling/Disabling

OncePerRequestFilter actually determines if the filter is enabled or disabled based on its isEnabled(request, response) method.

This method defaults to returning the value of the enabled property, which is used for generally enabling/disabling all requests as mentioned above. If you wanted to enable or disable a filter based on request specific criteria, you can override the OncePerRequestFilter isEnabled(request,response) method to perform more specific checks.

Path-specific Enabling/Disabling

Shiro’s PathMatchingFilter (a subclass of OncePerRequestFilter has the ability to react to configuration based on a specific path being filtered. This means you can enable or disable a filter based on the path and the path-specific configuration in addition to the incoming request and response.

If you need to be able to react to the matching path and the path-specific configuration to determine if a filter is enabled or disabled, instead of overriding OncePerRequestFilter isEnabled(request,response) method, you would override the PathMatchingFilter isEnabled(request,response,path,pathConfig) method instead.

Global Filters

Starting with Shiro 1.6 the ability to define global filters has been added. Adding "global filters" will add additional filters to ALL routes, this includes previously configured filter chains as well as unconfigured paths.

By default, the global filters contains the invalidRequest filter. This filter blocks known malicious attacks, see below for configuration details.

Global filters can be customized or disabled, for example

# disable Global Filters
filterChainResolver.globalFilters = null

Define the list of global filters:

filterChainResolver.globalFilters = invalidRequest, port

The invalidRequest filter blocks requests with non-ascii characters, semicolons, and backslashes, each of these can be disabled independently to allow for backward compatibility.

invalidRequest.blockBackslash = true
invalidRequest.blockSemicolon = true
invalidRequest.blockNonAscii = true

If you’re currently allowing URL rewriting to allow for a <code>jsessionid</code> in the URL, you must set blockSemicolon to false.

URL rewriting for jsessionid is defined in section "7.1.3" of the Java Servlet Specification, but it is generally NOT recommended.

HTTP Strict Transport Security (HSTS)

The SslFilter (and all of its subclasses) supports enabling/disabling HTTP Strict Transport Security (HSTS).

For example, in shiro.ini:

# configure Shiro's default 'ssl' filter to enabled HSTS:
ssl.enabled = true
ssl.hsts.enabled = true
ssl.hsts.includeSubDomains = true

/some/path = ssl, authc
/another/path = ssl, roles[admin]

Session Management

Servlet Container Sessions

In web environments, Shiro’s default session manager SessionManager implementation is the ServletContainerSessionManager. This very simple implementation delegates all session management duties (including session clustering if the servlet container supports it) to the runtime Servlet container. It is essentially a bridge for Shiro’s session API to the servlet container and does little else.

A benefit of using this default is that apps that work with existing servlet container session configuration (timeout, any container-specific clustering mechanisms, etc.) will work as expected.

A downside of this default is that you are tied to the servlet container’s specific session behavior. For example, if you wanted to cluster sessions, but you used Jetty for testing and Tomcat in production, your container-specific configuration (or code) would not be portable.

Servlet Container Session Timeout

If using the default servlet container support, you configure session timeout as expected in your web application’s web.xml file. For example:

  <!-- web.xml expects the session timeout in minutes: -->

Native Sessions

If you want your session configuration settings and clustering to be portable across servlet containers (e.g. Jetty in testing, but Tomcat or JBoss in production), or you want to control specific session/clustering features, you can enable Shiro’s native session management.

The word 'Native' here means that Shiro’s own enterprise session management implementation will be used to support all Subject and HttpServletRequest sessions and bypass the servlet container completely. But rest assured - Shiro implements the relevant parts of the Servlet specification directly so any existing web/http related code works as expected and never needs to 'know' that Shiro is transparently managing sessions.


To enable native session management for your web application, you will need to configure a native web-capable session manager to override the default servlet container-based one. You can do that by configuring an instance of DefaultWebSessionManager on Shiro’s SecurityManager. For example, in shiro.ini:

shiro.ini native web session management

sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager
# configure properties (like session timeout) here if desired

# Use the configured native session manager:
securityManager.sessionManager = $sessionManager

Once declared, you can configure the DefaultWebSessionManager instance with native session options like session timeout and clustering configuration as described in the Session Management section.

Native Session Timeout

After configuring the DefaultWebSessionManager instance, session timeout is configured as described in Session Management: Session Timeout

The DefaultWebSessionManager supports two web-specific configuration properties:

  • sessionIdCookieEnabled (a boolean)

  • sessionIdCookie, a Cookie instance.

Example 4. Cookie as a template

The sessionIdCookie property is essentially a template - you configure the Cookie instance properties, and this template will be used to set the actual HTTP Cookie header at runtime with an appropriate session ID value.

The DefaultWebSessionManager’s sessionIdCookie default instance is a SimpleCookie. This simple implementation allows JavaBeans-style property configuration for all the relevant properties you would want to configure on an http Cookie.

For example, you could set the Cookie domain:

securityManager.sessionManager.sessionIdCookie.domain =

See the SimpleCookie JavaDoc for additional properties.

The cookie’s default name is JSESSIONID in accordance with the servlet specification. Additionally, Shiro’s cookie supports the HttpOnly and SameSite flags. The sessionIdCookie sets HttpOnly to true and SameSite to LAX by default for extra security.

Shiro’s Cookie concept supports the HttpOnly flag even in Servlet 2.4 and 2.5 environments (whereas the Servlet API only supports it natively in 2.6 or later).

If you do not want session cookies to be used, you can disable their use by configuring the sessionIdCookieEnabled property to false. For example:

Disabling native session cookies

securityManager.sessionManager.sessionIdCookieEnabled = false

Remember Me Services

Shiro will perform 'rememberMe' services if the AuthenticationToken implements the org.apache.shiro.authc.RememberMeAuthenticationToken interface. This interface specifies a method:

boolean isRememberMe();

If this method returns true, Shiro will remember the end-user’s identity across sessions.

UsernamePasswordToken and RememberMe

The frequently-used UsernamePasswordToken already implements the RememberMeAuthenticationToken interface and supports rememberMe logins.

Programmatic Support

To use rememberMe programmatically, you can set the value to true on a class that supports this configuration. For example, using the standard UsernamePasswordToken:

UsernamePasswordToken token = new UsernamePasswordToken(username, password);



Form-based Login

For web applications, the authc filter is by default a FormAuthenticationFilter. This supports reading the 'rememberMe' boolean as a form/request parameter. By default, it expects the request param to be named rememberMe. Here is an example shiro.ini config supporting this:

authc.loginUrl = /login.jsp


# your login form page here:
login.jsp = authc

And in your web form, have a checkbox named 'rememberMe':

<form ...>

   Username: <input type="text" name="username"/> <br/>
   Password: <input type="password" name="password"/>
   <input type="checkbox" name="rememberMe" value="true"/>Remember Me?

By default, the FormAuthenticationFilter will look for request parameters named username, password and rememberMe. If these are different from the form field names that you use in your form, you’ll want to configure the names on the FormAuthenticationFilter. For example, in shiro.ini:

authc.loginUrl = /whatever.jsp
authc.usernameParam = somethingOtherThanUsername
authc.passwordParam = somethingOtherThanPassword
authc.rememberMeParam = somethingOtherThanRememberMe

You can configure how the rememberMe cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:

... = foo
securityManager.rememberMeManager.cookie.maxAge = blah

See the CookieRememberMeManager and the supporting SimpleCookie JavaDoc for configuration properties.

Custom RememberMeManager

It should be noted that if the default cookie-based RememberMeManager implementation does not meet your needs, you can plug in any you like in to the securityManager like you would configure any other object reference:

rememberMeManager =
securityManager.rememberMeManager = $rememberMeManager

JSP / Jakarta Faces (JSF) / GSP Tag Library

Apache Shiro provides a Subject-aware JSP/Jakarta Faces/GSP tag library that allows you to control your JSP, Faces/JSF, JSTL or GSP page output based on the current Subject’s state. This is quite useful for personalizing views based on the identity and authorization state of the current user viewing the web page.

Tag Library Configuration

The Tag Library Descriptor (TLD) file is bundled in shiro-web.jar in the META-INF/shiro.tld file. To use any of the tags, add the following line to the top of your JSP page (or wherever you define page directives):

<%@ taglib prefix="shiro" uri="" %>
Jakarta Faces (JSF):
<html xmlns=""

We’ve used the shiro prefix to indicate the shiro tag library namespace, but you can assign whatever name you like.

Now we’ll cover each tag and show how it might be used to render a page.

The guest tag

The guest tag will display its wrapped content only if the current Subject is considered a 'guest'. A guest is any Subject that does not have an identity. That is, we don’t know who the user is because they have not logged in, and they are not remembered (from Remember Me services) from a previous site visit.


    Hi there!  Please <a href="login.jsp">Login</a> or <a href="signup.jsp">Signup</a> today!

The guest tag is the logical opposite of the user tag.

The user tag

The user tag will display its wrapped content only if the current Subject is considered a 'user'. A 'user' in this context is defined as a Subject with a known identity, either from a successful authentication or from 'RememberMe' services. Note that this tag is semantically different from the authenticated tag, which is more restrictive than this tag.


    Welcome back John!  Not John? Click <a href="login.jsp">here<a> to login.

The user tag is the logical opposite of the guest tag.

The authenticated tag

Displays body content only if the current user has successfully authenticated during their current session. It is more restrictive than the 'user' tag. It is logically opposite to the 'notAuthenticated' tag.

The authenticated tag will display its wrapped content only if the current Subject has successfully authenticated during their current session. It is a more restrictive tag than the user, which is used to guarantee identity in sensitive workflows.


    <a href="updateAccount.jsp">Update your contact information</a>.

The authenticated tag is the logical opposite of the notAuthenticated tag.

The notAuthenticated tag

The notAuthenticated tag will display its wrapped content if the current Subject has NOT yet successfully authenticated during the current session.


    Please <a href="login.jsp">login</a> in order to update your credit card information.

The notAuthenticated tag is the logical opposite of the authenticated tag.

The principal tag

The principal tag will output the Subject’s [#]#getPrincipal--[principal] (identifying attribute) or a property of that principal.

Without any tag attributes, the tag will render the toString() value of the principal. For example (assuming the principal is a String username):

Hello, <shiro:principal/>, how are you today?

This is (mostly) equivalent to the following:

Hello, <%= SecurityUtils.getSubject().getPrincipal().toString() %>, how are you today?

Typed principal

The principal tag assumes by default that the principal to print is the subject.getPrincipal() value. But if you wanted to print a value that is not the primary principal, but another in the Subject’s {[#]#getPrincipals--[principal collection], you can acquire that principal by type and print that value instead.

For example, printing the Subject’s user ID (and not the username), assuming the ID was in the principal collection:

User ID: <principal type="java.lang.Integer"/>

This is (mostly) equivalent to the following:

User ID: <%= SecurityUtils.getSubject().getPrincipals().oneByType(Integer.class).toString() %>

Principal property

But what if the principal (either the default primary principal or 'typed' principal above) is a complex object and not a simple string, and you wanted to reference a property on that principal? You can use the property attribute to indicate the name of the property to read (must be accessible via a JavaBeans-compatible getter method). For example (assuming the primary principal is a User object):

Hello, <shiro:principal property="firstName"/>, how are you today?

This is (mostly) equivalent to the following:

Hello, <%= SecurityUtils.getSubject().getPrincipal().getFirstName().toString() %>, how are you today?

Or, combined with the type attribute:

Hello, <shiro:principal type="" property="firstName"/>, how are you today?

this is largely equivalent to the following:

Hello, <%= SecurityUtils.getSubject().getPrincipals().oneByType( %>, how are you today?

The hasRole tag

The hasRole tag will display its wrapped content only if the current Subject is assigned the specified role.

For example:

<shiro:hasRole name="administrator">
    <a href="admin.jsp">Administer the system</a>

The hasRole tag is the logical opposite of the lacksRole tag.

The lacksRole tag

The lacksRole tag will display its wrapped content only if the current Subject is NOT assigned the specified role.

For example:

<shiro:lacksRole name="administrator">
    Sorry, you are not allowed to administer the system.

The lacksRole tag is the logical opposite of the hasRole tag.

The hasAnyRoles tag

The hasAnyRoles tag will display its wrapped content if the current Subject is assigned any of the specified roles from a comma-delimited list of role names.

For example:

<shiro:hasAnyRoles name="developer, project manager, administrator">
    You are either a developer, project manager, or administrator.

The hasAnyRoles tag does not currently have a logically opposite tag.

The hasPermission tag

The hasPermission tag will display its wrapped content only if the current Subject 'has' (implies) the specified permission. That is, the user has the specified ability.

For example:

<shiro:hasPermission name="user:create">
    <a href="createUser.jsp">Create a new User</a>

The hasPermission tag is the logical opposite of the lacksPermission tag.

The lacksPermission tag

The lacksPermission tag will display its wrapped content only if the current Subject DOES NOT have (imply) the specified permission. That is, the user DOES NOT have the specified ability.

For example:

<shiro:lacksPermission name="user:delete">
    Sorry, you are not allowed to delete user accounts.

The lacksPermission tag is the logical opposite of the hasPermission tag.

Lend a hand with documentation

While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider correcting, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro.

The easiest way to contribute your documentation is to submit a pull-request by clicking on the Edit link below, or send it to the User Mailing List.