|
-
-
-Related Content- -Web Apps with Shiro-Learn more about integrating Shiro into web applications. Read More >> - -Web App Tutorial-Step-by-step tutorial for securing a web application with Shiro. Read More >> - -Session Management-Shiro enables sessions for any application environment. Learn more! Read More >> - -Permissions-Learn more about Shiro's powerful and intuitive permission syntax. Read More >> - -Java Authentication Guide-Learn how Authentication in Java is performed in Shiro. Read More >> - -Java Authorization Guide-Learn how Shiro handles access control in Java. Read More >> - - |
-
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.
- -#info('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.') - -In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to web.xml:
- --<listener> - <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class> -</listener> - -... - -<filter> - <filter-name>ShiroFilter</filter-name> - <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class> -</filter> - -<filter-mapping> - <filter-name>ShiroFilter</filter-name> - <url-pattern>/*</url-pattern> - <dispatcher>REQUEST</dispatcher> - <dispatcher>FORWARD</dispatcher> - <dispatcher>INCLUDE</dispatcher> - <dispatcher>ERROR</dispatcher> -</filter-mapping> --
This assumes a Shiro INI Configuration file is located at either of the following two locations, using whichever is found first:
-Here is what the above config does:
- -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:
- --<context-param> - <param-name>shiroEnvironmentClass</param-name> - <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value> -</context-param> --
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. com.foo.bar.shiro.XmlWebEnvironment.
- -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):
- -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:
- --<context-param> - <param-name>shiroConfigLocations</param-name> - <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value> -</context-param> --
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:
-The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a filter-mapping:
- --<filter> - <filter-name>ShiroFilter</filter-name> - <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class> -</filter> - -... - -<!-- 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: --> -<filter-mapping> - <filter-name>ShiroFilter</filter-name> - <url-pattern>/*</url-pattern> - <dispatcher>REQUEST</dispatcher> - <dispatcher>FORWARD</dispatcher> - <dispatcher>INCLUDE</dispatcher> - <dispatcher>ERROR</dispatcher> -</filter-mapping> --
This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. classpath:shiro.ini).
- -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:
- --<filter> - <filter-name>ShiroFilter</filter-name> - <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class> - <init-param> - <param-name>configPath</param-name> - <param-value>/WEB-INF/anotherFile.ini</param-value> - </init-param> -</filter> - -... --
Unqualified (schemeless or 'non-prefixed') configPath values are assumed to be ServletContext resource paths, resolvable via the rules defined by the
-ServletContext.getResource method.
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:
- --... -<init-param> - <param-name>configPath</param-name> - <param-value>url:http://configHost/myApp/shiro.ini</param-value> -</init-param> -... --
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:
- --<filter> - <filter-name>ShiroFilter</filter-name> - <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class> - <init-param><param-name>config</param-name><param-value> - - # INI Config Here - - </param-value></init-param> -</filter> -... --
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:
- -It is up to you - use what makes sense for your project.
-
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 -... -[urls] -... --
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:
- --... -[urls] - -/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.
- -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 it's 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, www.somehost.com/myapp and then later deploy it to www.anotherhost.com (no 'myapp' sub-path), the pattern matching will still work. All paths are relative to the HttpServletRequest.getContextPath() value.
- - -#warning('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 asume that there are the following chain definitions: - --/account/** = ssl, authc -/account/signup = anon --
If an incoming request is intended to reach /account/signup/index.html (accessible by all ''anon''ymous users), it will never be handled!. The reason is that the /account/** pattern matched the incoming request first and ''short-circuited'' all remaining definitions.
- -Always remember to define your filter chains based on a FIRST MATCH WINS policy!
') - -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]
-where:
-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.
- -#tip('Tip', '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
') - -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:
- --[main] -... -myFilter = com.company.web.some.FilterImplementation -myFilter.property1 = value1 -... - -[urls] -... -/some/path/** = myFilter --
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:
- -
-[main]
-...
-# Notice how we didn't define the class for the FormAuthenticationFilter ('authc') - it is instantiated and available already:
-authc.loginUrl = /login.jsp
-...
-
-[urls]
-...
-# 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:
- -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.
- -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:
- --[main] -... -# configure Shiro's default 'ssl' filter to be disabled while testing: -ssl.enabled = false - -[urls] -... -/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 of the URL paths or maintaining two Shiro configurations.
- -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.
- -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.
- - -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.
- -If using the default servlet container support, you configure session timeout as expected in your web application's web.xml file. For example:
- --<session-config> - <!-- web.xml expects the session timeout in minutes: --> - <session-timeout>30</session-timeout> -</session-config> --
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:
- --[main] -... -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.
- -After configuring the DefaultWebSessionManager instance, session timeout is configured as described in Session Management: Session Timeout
- -The DefaultWebSessionManager supports two web-specific configuration properties:
-The DefaultWebSessionManager's sessionIdCookie default instance is a SimpleCookie. This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.
- -For example, you could set the Cookie domain:
- --[main] -... -securityManager.sessionManager.sessionIdCookie.domain = foo.com --
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 flag. The sessionIdCookie sets HttpOnly to true by default for extra security.
- -#info('Note', '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:
- -
-[main]
-...
-securityManager.sessionManager.sessionIdCookieEnabled = false
-
-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.
- -#tip('UsernamePasswordToken and RememberMe', 'The frequently-used UsernamePasswordToken already implements the RememberMeAuthenticationToken interface and supports rememberMe logins.') - -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); - -token.setRememberMe(true); - -SecurityUtils.getSubject().login(token); -... --
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:
- -- -[main] -authc.loginUrl = /login.jsp - -[urls] - -# 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? - ... -</form> --
By default, the FormAuthenticationFilter will look for request parameters named username, password and rememberMe. If these are different than 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:
- --[main] -... -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:
- --[main] -... - -securityManager.rememberMeManager.cookie.name = foo -securityManager.rememberMeManager.cookie.maxAge = blah -... --
See the CookieRememberMeManager and the supporting SimpleCookie JavaDoc for configuration properties.
- -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:
- --[main] -... -rememberMeManager = com.my.impl.RememberMeManager -securityManager.rememberMeManager = $rememberMeManager --
Apache Shiro provides a Subject-aware JSP/GSP tag library that allows you to control your JSP, 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.
-
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="http://shiro.apache.org/tags" %> --
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 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.
- -Example:
- --<shiro:guest> - Hi there! Please <a href="login.jsp">Login</a> or <a href="signup.jsp">Signup</a> today! -</shiro:guest> --
The guest tag is the logical opposite of 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.
- -Example:
- --<shiro:user> - Welcome back John! Not John? Click <a href="login.jsp">here<a> to login. -</shiro:user> --
The user tag is the logical opposite of the guest 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.
- -Example:
- --<shiro:authenticated> - <a href="updateAccount.jsp">Update your contact information</a>. -</shiro:authenticated> --
The authenticated tag is the logical opposite of the notAuthenticated tag.
-
The notAuthenticated tag will display its wrapped content if the current Subject has NOT yet successfully authenticated during the current session.
- -Example:
- --<shiro:notAuthenticated> - Please <a href="login.jsp">login</a> in order to update your credit card information. -</shiro:notAuthenticated> --
The notAuthenticated tag is the logical opposite of the authenticated tag.
-
The principal tag will output the Subject's 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?
-
-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 {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() %>
-
-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="com.foo.User" property="firstName"/>, how are you today?
-
-this is largely equivalent to the following:
- -
-Hello, <%= SecurityUtils.getSubject().getPrincipals().oneByType(com.foo.User.class).getFirstName().toString() %>, how are you today?
-
-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> -</shiro:hasRole> --
The hasRole tag is the logical opposite of 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. -</shiro:lacksRole> --
The lacksRole tag is the logical opposite of the hasRole tag.
-
The hasAnyRole 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. -</shiro:lacksRole> --
The hasAnyRole tag does not currently have a logically opposite 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> -</shiro:hasPermission> --
The hasPermission tag is the logical opposite of 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. -</shiro:hasPermission> --
The lacksPermission tag is the logical opposite of the hasPermission tag.
- -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 corrected, 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 send it to the User Forum or the User Mailing List.
diff --git a/web.md.vtl b/web.md.vtl new file mode 100644 index 0000000000..010e09811b --- /dev/null +++ b/web.md.vtl @@ -0,0 +1,914 @@ +#mdStyle() + + +Apache Shiro Web Support +======================== + +|
+
+
+Related Content+ +Web Apps with Shiro+Learn more about integrating Shiro into web applications. Read More >> + +Web App Tutorial+Step-by-step tutorial for securing a web application with Shiro. Read More >> + +Session Management+Shiro enables sessions for any application environment. Learn more! Read More >> + +Permissions+Learn more about Shiro's powerful and intuitive permission syntax. Read More >> + +Java Authentication Guide+Learn how Authentication in Java is performed in Shiro. Read More >> + +Java Authorization Guide+Learn how Shiro handles access control in Java. Read More >> + + |
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:
+
+``` xml
+...
+
+/account/** = ssl, authc
+/account/signup = anon
+If an incoming request is intended to reach /account/signup/index.html (accessible by all ''anon''ymous users), it will never be handled!. The reason is that the /account/** pattern matched the incoming request first and ''short-circuited'' all remaining definitions.
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: + +``` ini +filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN] +``` + +where: + +* _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. + +#tip('Tip', '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
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.')
+
+
+#[[######Session Cookie Configuration]]#
+
+The DefaultWebSessionManager's `sessionIdCookie` default instance is a [`SimpleCookie`](static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html). This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.
+
+For example, you could set the Cookie domain:
+
+``` ini
+[main]
+...
+securityManager.sessionManager.sessionIdCookie.domain = foo.com
+```
+
+See the [SimpleCookie JavaDoc](static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html) for additional properties.
+
+The cookie's default name is `JSESSIONID` in accordance with the servlet specification. Additionally, Shiro's cookie supports the [`HttpOnly`](https://en.wikipedia.org/wiki/HTTP_cookie#HttpOnly_cookie) flag. The `sessionIdCookie` sets `HttpOnly` to `true` by default for extra security.
+
+#info('Note', '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).')
+
+
+#[[######Disabling the Session Cookie]]#
+
+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**
+
+``` ini
+[main]
+...
+securityManager.sessionManager.sessionIdCookieEnabled = false
+```
+
+
+
+Remember Me Services
+--------------------
+
+Shiro will perform 'rememberMe' services if the `AuthenticationToken` implements the [`org.apache.shiro.authc.RememberMeAuthenticationToken`](static/current/apidocs/org/apache/shiro/authc/RememberMeAuthenticationToken.html) interface. This interface specifies a method:
+
+``` java
+boolean isRememberMe();
+```
+
+If this method returns `true`, Shiro will remember the end-user's identity across sessions.
+
+#tip('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`:
+
+``` java
+UsernamePasswordToken token = new UsernamePasswordToken(username, password);
+
+token.setRememberMe(true);
+
+SecurityUtils.getSubject().login(token);
+...
+```
+
+
+#[[###Form-based Login]]#
+
+For web applications, the `authc` filter is by default a [`FormAuthenticationFilter`](static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html). 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:
+
+``` ini
+[main]
+authc.loginUrl = /login.jsp
+
+[urls]
+
+# your login form page here:
+login.jsp = authc
+```
+
+And in your web form, have a checkbox named 'rememberMe':
+
+``` html
+
+```
+
+By default, the `FormAuthenticationFilter` will look for request parameters named `username`, `password` and `rememberMe`. If these are different than 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`:
+
+``` ini
+[main]
+...
+authc.loginUrl = /whatever.jsp
+authc.usernameParam = somethingOtherThanUsername
+authc.passwordParam = somethingOtherThanPassword
+authc.rememberMeParam = somethingOtherThanRememberMe
+...
+```
+
+
+#[[###Cookie configuration]]#
+
+You can configure how the `rememberMe` cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:
+
+``` ini
+[main]
+...
+
+securityManager.rememberMeManager.cookie.name = foo
+securityManager.rememberMeManager.cookie.maxAge = blah
+...
+```
+
+See the [`CookieRememberMeManager`](static/current/apidocs/org/apache/shiro/web/mgt/CookieRememberMeManager.html) and the supporting [`SimpleCookie`](static/current/apidocs/src-html/org/apache/shiro/web/servlet/SimpleCookie.html) 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:
+
+``` ini
+[main]
+...
+rememberMeManager = com.my.impl.RememberMeManager
+securityManager.rememberMeManager = $rememberMeManager
+```
+
+
+JSP / GSP Tag Library
+---------------------
+
+Apache Shiro provides a `Subject`-aware JSP/GSP tag library that allows you to control your JSP, 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):
+
+``` html
+<%@ taglib prefix="shiro" uri="http://shiro.apache.org/tags" %>
+```
+
+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.
+
+Example:
+
+``` html
+