Modified: shiro/site/publish/web.html URL: http://svn.apache.org/viewvc/shiro/site/publish/web.html?rev=1766414&r1=1766413&r2=1766414&view=diff ============================================================================== --- shiro/site/publish/web.html (original) +++ shiro/site/publish/web.html Mon Oct 24 14:33:52 2016 @@ -78,12 +78,23 @@ <div id="content"> - <h1><a name="Web-ApacheShiroWebSupport"></a>Apache Shiro Web Support</h1> + <style> -<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"> - -<tr> -<td> + table, th, td { + border: 1px solid black; + border-collapse: collapse; + border-color: #ccc; + } + th { + background-color: #f0f0f0 + } + th, td { + padding: 8px; + } +</style> +<a name="Web-ApacheShiroWebSupport"></a> +<h1><a href="#apache-shiro-web-support" name="apache-shiro-web-support">Apache Shiro Web Support</a></h1> +<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"><tr><td> <div id="border"> <h2>Related Content</h2> @@ -106,17 +117,125 @@ <p>Learn how Shiro handles access control in Java. </br><span style="font-size:11"><a href="java-authorization-guide.html">Read More >></a></span></p> </div> -</td> -</tr> -</table> -<div class="toc"> -<ul><li><a href="#Web-Configuration">Configuration</a></li><ul><li><a href="#Web-%7B%7Bweb.xml%7D%7D"> <tt>web.xml</tt></a></li><ul><li><a href="#Web-Shiro1.2andlater">Shiro 1.2 and later</a></li><ul><li><a href="#Web-Custom%7B%7BWebEnvironment%7D%7DClass">Custom <tt>WebEnvironment</tt> Class</a></li><li><a href="#Web-CustomConfigurationLocations">Custom Configuration Locations</a></li></ul><li><a href="#Web-Shiro1.1andearlier">Shiro 1.1 and earlier</a></li><ul><li><a href="#Web-CustomPath">Custom Path</a></li><li><a href="#Web-InlineConfig">Inline Config</a></li></ul></ul><li><a href="#Web-WebINIconfiguration">Web INI configuration</a></li><ul><li><a href="#Web-%7B%7B%5Curls%5C%7D%7D"> <tt>[urls]</tt></a></li><ul><li><a href="#Web-URLPathExpressions">URL Path Expressions</a></li><li><a href="#Web-FilterChainDefinitions">Filter Chain Definitions</a></li><ul><li><a href="#Web-AvailableFilters">Available Filters</a></li></ul></ul></ul></ul><li><a href="#Web-DefaultFilters">Default Fil ters</a></li><li><a href="#Web-EnablingandDisablingFilters">Enabling and Disabling Filters</a></li><ul><li><a href="#Web-GeneralEnabling%2FDisabling">General Enabling/Disabling</a></li><li><a href="#Web-RequestspecificEnabling%2FDisabling">Request-specific Enabling/Disabling</a></li><li><a href="#Web-PathspecificEnabling%2FDisabling">Path-specific Enabling/Disabling</a></li></ul><li><a href="#Web-SessionManagement">Session Management</a></li><ul><li><a href="#Web-ServletContainerSessions">Servlet Container Sessions</a></li><ul><li><a href="#Web-ServletContainerSessionTimeout">Servlet Container Session Timeout</a></li></ul><li><a href="#Web-NativeSessions">Native Sessions</a></li><ul><li><a href="#Web-%7B%7BDefaultWebSessionManager%7D%7D"> <tt>DefaultWebSessionManager</tt></a></li><ul><li><a href="#Web-NativeSessionTimeout">Native Session Timeout</a></li><li><a href="#Web-SessionCookie">Session Cookie</a></li><ul><li><a href="#Web-SessionCookieConfiguration">Session Cookie Configurat ion</a></li><li><a href="#Web-DisablingtheSessionCookie">Disabling the Session Cookie</a></li></ul></ul></ul></ul><li><a href="#Web-RememberMeServices">Remember Me Services</a></li><ul><li><a href="#Web-ProgrammaticSupport">Programmatic Support</a></li><li><a href="#Web-FormbasedLogin">Form-based Login</a></li><li><a href="#Web-Cookieconfiguration">Cookie configuration</a></li><li><a href="#Web-Custom%7B%7BRememberMeManager%7D%7D">Custom <tt>RememberMeManager</tt></a></li></ul><li><a href="#Web-JSP%2FGSPTagLibrary">JSP / GSP Tag Library</a></li><ul><li><a href="#Web-TagLibraryConfiguration">Tag Library Configuration</a></li><li><a href="#Web-The%7B%7Bguest%7D%7Dtag">The <tt>guest</tt> tag</a></li><li><a href="#Web-The%7B%7Buser%7D%7Dtag">The <tt>user</tt> tag</a></li><li><a href="#Web-The%7B%7Bauthenticated%7D%7Dtag">The <tt>authenticated</tt> tag</a></li><li><a href="#Web-The%7B%7BnotAuthenticated%7D%7Dtag">The <tt>notAuthenticated</tt> tag</a></li><li><a href="#Web-The%7B%7Bprinci pal%7D%7Dtag">The <tt>principal</tt> tag</a></li><ul><li><a href="#Web-Typedprincipal">Typed principal</a></li><li><a href="#Web-Principalproperty">Principal property</a></li></ul><li><a href="#Web-The%7B%7BhasRole%7D%7Dtag">The <tt>hasRole</tt> tag</a></li><li><a href="#Web-The%7B%7BlacksRole%7D%7Dtag">The <tt>lacksRole</tt> tag</a></li><li><a href="#Web-The%7B%7BhasAnyRole%7D%7Dtag">The <tt>hasAnyRole</tt> tag</a></li><li><a href="#Web-The%7B%7BhasPermission%7D%7Dtag">The <tt>hasPermission</tt> tag</a></li><li><a href="#Web-The%7B%7BlacksPermission%7D%7Dtag">The <tt>lacksPermission</tt> tag</a></li></ul><li><a href="#Web-Lendahandwithdocumentation">Lend a hand with documentation</a></li></ul></div> - -<p><a name="Web-configuration"></a></p> -<h2><a name="Web-Configuration"></a>Configuration</h2> - -<p>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 <a href="configuration.html#Configuration-INISections">INI Sections</a> section, but we'll cover some additional web-specific sections here.</p> - +</td></tr></table> +<ul> + <li> + <p><a href="#Web-Configuration">Configuration</a></p> + <ul> + <li> + <p><a href="#Web-%7B%7Bweb.xml%7D%7D"><code>web.xml</code></a></p> + <ul> + <li> + <p><a href="#Web-Shiro1.2andlater">Shiro 1.2 and later</a></p> + <ul> + <li><a href="#Web-Custom%7B%7BWebEnvironment%7D%7DClass">Custom <code>WebEnvironment</code> Class</a></li> + <li><a href="#Web-CustomConfigurationLocations">Custom Configuration Locations</a></li> + </ul> + </li> + <li> + <p><a href="#Web-Shiro1.1andearlier">Shiro 1.1 and earlier</a></p> + <ul> + <li><a href="#Web-CustomPath">Custom Path</a></li> + <li><a href="#Web-InlineConfig">Inline Config</a></li> + </ul> + </li> + </ul> + </li> + <li> + <p><a href="#Web-WebINIconfiguration">Web INI configuration</a></p> + <ul> + <li> + <p><a href="#Web-%7B%7B%5Curls%5C%7D%7D"><code>[urls]</code></a></p> + <ul> + <li><a href="#Web-URLPathExpressions">URL Path Expressions</a></li> + <li><a href="#Web-FilterChainDefinitions">Filter Chain Definitions</a> + <ul> + <li> + <p><a href="#Web-AvailableFilters">Available Filters</a></p></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <p><a href="#Web-DefaultFilters">Default Filters</a></p></li> + <li><a href="#Web-EnablingandDisablingFilters">Enabling and Disabling Filters</a> + <ul> + <li><a href="#Web-GeneralEnabling%2FDisabling">General Enabling/Disabling</a></li> + <li><a href="#Web-RequestspecificEnabling%2FDisabling">Request-specific Enabling/Disabling</a></li> + <li><a href="#Web-PathspecificEnabling%2FDisabling">Path-specific Enabling/Disabling</a></li> + </ul> + </li> + <li> + <p><a href="#Web-SessionManagement">Session Management</a></p> + <ul> + <li> + <p><a href="#Web-ServletContainerSessions">Servlet Container Sessions</a></p> + <ul> + <li> + <p><a href="#Web-ServletContainerSessionTimeout">Servlet Container Session Timeout</a></p></li> + </ul> + </li> + <li> + <p><a href="#Web-NativeSessions">Native Sessions</a></p> + <ul> + <li> + <p><a href="#Web-%7B%7BDefaultWebSessionManager%7D%7D"><code>DefaultWebSessionManager</code></a></p> + <ul> + <li><a href="#Web-NativeSessionTimeout">Native Session Timeout</a></li> + <li><a href="#Web-SessionCookie">Session Cookie</a> + <ul> + <li><a href="#Web-SessionCookieConfiguration">Session Cookie Configuration</a></li> + <li><a href="#Web-DisablingtheSessionCookie">Disabling the Session Cookie</a></li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <p><a href="#Web-RememberMeServices">Remember Me Services</a></p> + <ul> + <li><a href="#Web-ProgrammaticSupport">Programmatic Support</a></li> + <li><a href="#Web-FormbasedLogin">Form-based Login</a></li> + <li><a href="#Web-Cookieconfiguration">Cookie configuration</a></li> + <li><a href="#Web-Custom%7B%7BRememberMeManager%7D%7D">Custom <code>RememberMeManager</code></a></li> + </ul> + </li> + <li> + <p><a href="#Web-JSP%2FGSPTagLibrary">JSP / GSP Tag Library</a></p> + <ul> + <li><a href="#Web-TagLibraryConfiguration">Tag Library Configuration</a></li> + <li><a href="#Web-The%7B%7Bguest%7D%7Dtag">The <code>guest</code> tag</a></li> + <li><a href="#Web-The%7B%7Buser%7D%7Dtag">The <code>user</code> tag</a></li> + <li><a href="#Web-The%7B%7Bauthenticated%7D%7Dtag">The <code>authenticated</code> tag</a></li> + <li><a href="#Web-The%7B%7BnotAuthenticated%7D%7Dtag">The <code>notAuthenticated</code> tag</a></li> + <li><a href="#Web-The%7B%7Bprincipal%7D%7Dtag">The <code>principal</code> tag</a> + <ul> + <li><a href="#Web-Typedprincipal">Typed principal</a></li> + <li><a href="#Web-Principalproperty">Principal property</a></li> + </ul> + </li> + <li> + <p><a href="#Web-The%7B%7BhasRole%7D%7Dtag">The <code>hasRole</code> tag</a></p></li> + <li><a href="#Web-The%7B%7BlacksRole%7D%7Dtag">The <code>lacksRole</code> tag</a></li> + <li><a href="#Web-The%7B%7BhasAnyRole%7D%7Dtag">The <code>hasAnyRole</code> tag</a></li> + <li><a href="#Web-The%7B%7BhasPermission%7D%7Dtag">The <code>hasPermission</code> tag</a></li> + <li><a href="#Web-The%7B%7BlacksPermission%7D%7Dtag">The <code>lacksPermission</code> tag</a></li> + </ul> + </li> + <li> + <p><a href="#Web-Lendahandwithdocumentation">Lend a hand with documentation</a></p></li> +</ul> +<a name="Web-configuration"></a> +<a name="Web-Configuration"></a> +<h2><a href="#configuration" name="configuration">Configuration</a></h2> +<p>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 <a href="configuration.html#Configuration-INISections">INI Sections</a> section, but we’ll cover some additional web-specific sections here.</p> <div class="panelMacro"> <table class="infoMacro"> <colgroup span="1"> @@ -140,50 +259,45 @@ </tbody> </table> </div> - -<h3><a name="Web-%7B%7Bweb.xml%7D%7D"></a><tt>web.xml</tt></h3> - -<h4><a name="Web-Shiro1.2andlater"></a>Shiro 1.2 and later</h4> - -<p>In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to <tt>web.xml</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><listener></span> - <span class="code-tag"><listener-class></span>org.apache.shiro.web.env.EnvironmentLoaderListener<span class="code-tag"></listener-class></span> -<span class="code-tag"></listener></span> +<a name="Web-%7B%7Bweb.xml%7D%7D"></a> +<h3><a href="#web-xml" name="web-xml">web.xml</a></h3> +<a name="Web-Shiro1.2andlater"></a> +<h4>Shiro 1.2 and later</h4> +<p>In Shiro 1.2 and later, standard web applications initialize Shiro by adding the following XML chunks to <code>web.xml</code>:</p> +<pre><code class="xml"><listener> + <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class> +</listener> ... -<span class="code-tag"><filter></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><filter-class></span>org.apache.shiro.web.servlet.ShiroFilter<span class="code-tag"></filter-class></span> -<span class="code-tag"></filter></span> - -<span class="code-tag"><filter-mapping></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><url-pattern></span>/*<span class="code-tag"></url-pattern></span> - <span class="code-tag"><dispatcher></span>REQUEST<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>FORWARD<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>INCLUDE<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>ERROR<span class="code-tag"></dispatcher></span> -<span class="code-tag"></filter-mapping></span> -</pre> -</div></div> - +<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> +</code></pre> <p>This assumes a Shiro INI <a href="configuration.html" title="Configuration">Configuration</a> file is located at either of the following two locations, using whichever is found first:</p> -<ol><li><tt>/WEB-INF/shiro.ini</tt></li><li><tt>shiro.ini</tt> file at the root of the classpath.</li></ol> - - +<ol> + <li><code>/WEB-INF/shiro.ini</code></li> + <li><code>shiro.ini</code> file at the root of the classpath.</li> +</ol> <p>Here is what the above config does:</p> - -<ul><li>The <tt>EnvironmentLoaderListener</tt> initializes a Shiro <tt>WebEnvironment</tt> instance (which contains everything Shiro needs to operate, including the <tt>SecurityManager</tt>) and makes it accessible in the <tt>ServletContext</tt>. If you need to obtain this <tt>WebEnvironment</tt> instance at any time, you can call <tt>WebUtils.getRequiredWebEnvironment(servletContext)</tt>. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>The <tt>ShiroFilter</tt> will use this <tt>WebEnvironment</tt> to perform all necessary security operations for any filtered request. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>Finally, the <tt>filter-mapping</tt> definition ensures that all requests are filtered by the <tt>ShiroFilter</tt>, recommended for most web applications to ensure that any request can be secured.</li></ul> - - +<ul> + <li> + <p>The <code>EnvironmentLoaderListener</code> initializes a Shiro <code>WebEnvironment</code> instance (which contains everything Shiro needs to operate, including the <code>SecurityManager</code>) and makes it accessible in the <code>ServletContext</code>. If you need to obtain this <code>WebEnvironment</code> instance at any time, you can call <code>WebUtils.getRequiredWebEnvironment(servletContext)</code>.</p></li> + <li> + <p>The <code>ShiroFilter</code> will use this <code>WebEnvironment</code> to perform all necessary security operations for any filtered request.</p></li> + <li> + <p>Finally, the <code>filter-mapping</code> definition ensures that all requests are filtered by the <code>ShiroFilter</code>, recommended for most web applications to ensure that any request can be secured.</p></li> +</ul> <div class="panelMacro"> <table class="tipMacro"> <colgroup span="1"> @@ -197,105 +311,80 @@ <td colspan="1" rowspan="1"> <b>ShiroFilter filter-mapping</b> <br clear="none"> - It is usually desirable to define the <tt>ShiroFilter filter-mapping</tt> before any other <tt>filter-mapping</tt> declarations to ensure that Shiro can function in those filters as well. + 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. </td> </tr> </tbody> </table> </div> - -<h5><a name="Web-Custom%7B%7BWebEnvironment%7D%7DClass"></a>Custom <tt>WebEnvironment</tt> Class</h5> - -<p>By default the <tt>EnvironmentLoaderListener</tt> will create an <tt>IniWebEnvironment</tt> instance, which assumes Shiro's INI-based <a href="configuration.html" title="Configuration">Configuration</a>. If you like, you may specify a custom <tt>WebEnvironment</tt> instance instead by specifying a <tt>ServletContext</tt> <tt>context-param</tt> in <tt>web.xml</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><context-param></span> - <span class="code-tag"><param-name></span>shiroEnvironmentClass<span class="code-tag"></param-name></span> - <span class="code-tag"><param-value></span>com.foo.bar.shiro.MyWebEnvironment<span class="code-tag"></param-value></span> -<span class="code-tag"></context-param></span> -</pre> -</div></div> - -<p>This allows you to customize how a configuration format is parsed and represented as a <tt>WebEnvironment</tt> instance. You could subclass the existing <tt>IniWebEnvironment</tt> 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. <tt>com.foo.bar.shiro.XmlWebEnvironment</tt>.</p> - -<h5><a name="Web-CustomConfigurationLocations"></a>Custom Configuration Locations</h5> - -<p>The <tt>IniWebEnvironment</tt> class expects to read and load INI configuration files. By default, this class will automatically look in the following two locations for the Shiro <tt>.ini</tt> configuration (in order):</p> - -<ol><li><tt>/WEB-INF/shiro.ini</tt></li><li><tt>classpath:shiro.ini</tt></li></ol> - - +<a name="Web-Custom%7B%7BWebEnvironment%7D%7DClass"></a> +<h5>Custom <code>WebEnvironment</code> Class</h5> +<p>By default the <code>EnvironmentLoaderListener</code> will create an <code>IniWebEnvironment</code> instance, which assumes Shiro’s INI-based <a href="configuration.html" title="Configuration">Configuration</a>. If you like, you may specify a custom <code>WebEnvironment</code> instance instead by specifying a <code>ServletContext</code> <code>context-param</code> in <code>web.xml</code>:</p> +<pre><code class="xml"><context-param> + <param-name>shiroEnvironmentClass</param-name> + <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value> +</context-param> +</code></pre> +<p>This allows you to customize how a configuration format is parsed and represented as a <code>WebEnvironment</code> instance. You could subclass the existing <code>IniWebEnvironment</code> 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. <code>com.foo.bar.shiro.XmlWebEnvironment</code>.</p> +<a name="Web-CustomConfigurationLocations"></a> +<h5><a href="#custom-configuration-locations" name="custom-configuration-locations">Custom Configuration Locations</a></h5> +<p>The <code>IniWebEnvironment</code> class expects to read and load INI configuration files. By default, this class will automatically look in the following two locations for the Shiro <code>.ini</code> configuration (in order):</p> +<ol> + <li><code>/WEB-INF/shiro.ini</code></li> + <li><code>classpath:shiro.ini</code></li> +</ol> <p>It will use whichever is found first.</p> - -<p>However, if you wish to place your config in another location, you may specify that location with another <tt>context-param</tt> in <tt>web.xml</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><context-param></span> - <span class="code-tag"><param-name></span>shiroConfigLocations<span class="code-tag"></param-name></span> - <span class="code-tag"><param-value></span>YOUR_RESOURCE_LOCATION_HERE<span class="code-tag"></param-value></span> -<span class="code-tag"></context-param></span> -</pre> -</div></div> - -<p>By default, the <tt>param-value</tt> is expected to be resolvable by the rules defined by <tt>ServletContext.</tt><tt><a class="external-link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource(java.lang.String)" rel="nofollow">getResource</a></tt> method. For example, <tt>/WEB-INF/some/path/shiro.ini</tt> </p> - -<p>But you may also specify specific file-system, classpath or URL locations by using an appropriate resource prefix supported by Shiro's <a class="external-link" href="static/current/apidocs/org/apache/shiro/io/ResourceUtils.html">ResourceUtils class</a>, for example:</p> -<ul><li><tt>file:/home/foobar/myapp/shiro.ini</tt></li><li><tt>classpath:com/foo/bar/shiro.ini</tt></li><li><tt>url:http://confighost.mycompany.com/myapp/shiro.ini</tt></li></ul> - - -<h4><a name="Web-Shiro1.1andearlier"></a>Shiro 1.1 and earlier</h4> - -<p>The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a <tt>filter-mapping</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><filter></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><filter-class></span>org.apache.shiro.web.servlet.IniShiroFilter<span class="code-tag"></filter-class></span> -<span class="code-tag"></filter></span> +<p>However, if you wish to place your config in another location, you may specify that location with another <code>context-param</code> in <code>web.xml</code>:</p> +<pre><code class="xml"><context-param> + <param-name>shiroConfigLocations</param-name> + <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value> +</context-param> +</code></pre> +<p>By default, the <code>param-value</code> is expected to be resolvable by the rules defined by <code>ServletContext.</code><a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource-java.lang.String-";><code>getResource</code></a> method. For example, <code>/WEB-INF/some/path/shiro.ini</code></p> +<p>But you may also specify specific file-system, classpath or URL locations by using an appropriate resource prefix supported by Shiro’s <a href="static/current/apidocs/org/apache/shiro/io/ResourceUtils.html">ResourceUtils class</a>, for example:</p> +<ul> + <li><code>file:/home/foobar/myapp/shiro.ini</code></li> + <li><code>classpath:com/foo/bar/shiro.ini</code></li> + <li><code>url:http://confighost.mycompany.com/myapp/shiro.ini</code></li> +</ul> +<a name="Web-Shiro1.1andearlier"></a> +<h4>Shiro 1.1 and earlier</h4> +<p>The simplest way to enable Shiro in a 1.1 or earlier web application is to define the IniShiroFilter and specify a <code>filter-mapping</code>:</p> +<pre><code class="xml"><filter> + <filter-name>ShiroFilter</filter-name> + <filter-class>org.apache.shiro.web.servlet.IniShiroFilter</filter-class> +</filter> ... -<span class="code-tag"><span class="code-comment"><!-- Make sure any request you want accessible to Shiro is filtered. /* catches all --></span></span> -<span class="code-tag"><span class="code-comment"><!-- requests. Usually this filter mapping is defined first (before all others) to --></span></span> -<span class="code-tag"><span class="code-comment"><!-- ensure that Shiro works in subsequent filters in the filter chain: --></span></span> -<span class="code-tag"><filter-mapping></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><url-pattern></span>/*<span class="code-tag"></url-pattern></span> - <span class="code-tag"><dispatcher></span>REQUEST<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>FORWARD<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>INCLUDE<span class="code-tag"></dispatcher></span> - <span class="code-tag"><dispatcher></span>ERROR<span class="code-tag"></dispatcher></span> -<span class="code-tag"></filter-mapping></span> -</pre> -</div></div> - -<p>This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. <tt>classpath:shiro.ini</tt>).</p> - -<h5><a name="Web-CustomPath"></a>Custom Path</h5> - -<p>If you do not want to place your INI config in <tt>/WEB-INF/shiro.ini</tt> or <tt>classpath:shiro.ini</tt>, you may specify a custom resource location as necessary. Add a <tt>configPath init-param</tt> and specify a resource location:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><filter></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><filter-class></span>org.apache.shiro.web.servlet.IniShiroFilter<span class="code-tag"></filter-class></span> - <span class="code-tag"><init-param></span> - <span class="code-tag"><param-name></span>configPath<span class="code-tag"></param-name></span> - <span class="code-tag"><param-value></span>/WEB-INF/anotherFile.ini<span class="code-tag"></param-value></span> - <span class="code-tag"></init-param></span> -<span class="code-tag"></filter></span> +<!-- 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> +</code></pre> +<p>This definition expects your INI configuration to be in a shiro.ini file at the root of the classpath (e.g. <code>classpath:shiro.ini</code>).</p> +<a name="Web-CustomPath"></a> +<h5><a href="#custom-path" name="custom-path">Custom Path</a></h5> +<p>If you do not want to place your INI config in <code>/WEB-INF/shiro.ini</code> or <code>classpath:shiro.ini</code>, you may specify a custom resource location as necessary. Add a <code>configPath init-param</code> and specify a resource location:</p> +<pre><code class="xml"><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> ... -</pre> -</div></div> - -<p>Unqualified (schemeless or 'non-prefixed') <tt>configPath</tt> values are assumed to be <tt>ServletContext</tt> resource paths, resolvable via the rules defined by the<br clear="none"> -<tt>ServletContext.</tt><tt><a class="external-link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource(java.lang.String)" rel="nofollow">getResource</a></tt> method.</p> - +</code></pre> +<p>Unqualified (schemeless or ‘non-prefixed’) <code>configPath</code> values are assumed to be <code>ServletContext</code> resource paths, resolvable via the rules defined by the<br/><code>ServletContext.</code><a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html#getResource-java.lang.String-";><code>getResource</code></a> method.</p> <div class="panelMacro"> <table class="noteMacro"> <colgroup span="1"> @@ -311,111 +400,76 @@ <td colspan="1" rowspan="1"> <b>ServletContext resource paths - Shiro 1.2+</b> <br clear="none"> - ServletContext resource paths are available in Shiro 1.2 and later. In 1.1 and earlier, all <tt>configPath</tt> definitions must specify a <tt>classpath:</tt>, <tt>file:</tt> or <tt>url:</tt> prefix. + ServletContext resource paths are available in Shiro 1.2 and later. In 1.1 and earlier, all <code>configPath</code> definitions must specify a <code>classpath:</code>, <code>file:</code> or <code>url:</code> prefix. </td> </tr> </tbody> </table> </div> - -<p>You may also specify other non-<tt>ServletContext</tt> resource locations by using <tt>classpath:</tt>, <tt>url:</tt>, or <tt>file:</tt> prefixes indicating classpath, url, or filesystem locations respectively. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -... -<span class="code-tag"><init-param></span> - <span class="code-tag"><param-name></span>configPath<span class="code-tag"></param-name></span> - <span class="code-tag"><param-value></span>url:http://configHost/myApp/shiro.ini<span class="code-tag"></param-value></span> -<span class="code-tag"></init-param></span> -... -</pre> -</div></div> - -<h5><a name="Web-InlineConfig"></a>Inline Config</h5> - -<p>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 <tt>config init-param</tt> instead of <tt>configPath</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><filter></span> - <span class="code-tag"><filter-name></span>ShiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><filter-class></span>org.apache.shiro.web.servlet.IniShiroFilter<span class="code-tag"></filter-class></span> - <span class="code-tag"><init-param></span><span class="code-tag"><param-name></span>config<span class="code-tag"></param-name></span><span class="code-tag"><param-value></span> +<p>You may also specify other non-<code>ServletContext</code> resource locations by using <code>classpath:</code>, <code>url:</code>, or <code>file:</code> prefixes indicating classpath, url, or filesystem locations respectively. For example:</p> +<pre><code class="xml">... +<init-param> + <param-name>configPath</param-name> + <param-value>url:http://configHost/myApp/shiro.ini</param-value> +</init-param> +... +</code></pre> +<a name="Web-InlineConfig"></a> +<h5><a href="#inline-config" name="inline-config">Inline Config</a></h5> +<p>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 <code>config init-param</code> instead of <code>configPath</code>:</p> +<pre><code class="xml"><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 - <span class="code-tag"></param-value></span><span class="code-tag"></init-param></span> -<span class="code-tag"></filter></span> + </param-value></init-param> +</filter> ... -</pre> -</div></div> - +</code></pre> <p>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:</p> - -<ul><li>You might edit security configuration a lot and don't want to add revision control 'noise' to the web.xml file</li><li>You might want to separate security config from the rest of web.xml config</li><li>Your security configuration might become large and you want to keep web.xml lean and easier to read</li><li>You have a complex build system where the same shiro config might need to be referenced in multiple places</li></ul> - - -<p>It is up to you - use what makes sense for your project.<br clear="none"> -<a name="Web-webini"></a></p> -<h3><a name="Web-WebINIconfiguration"></a>Web INI configuration</h3> - -<p>In addition to the standard <tt>[main]</tt>, <tt>[users]</tt> and <tt>[roles]</tt> sections already described in the main <a href="configuration.html" title="Configuration">Configuration</a> chapter, you can additionally specify a web-specific <tt>[urls]</tt> section in your <tt>shiro.ini</tt> file:</p> - -<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> -<pre># [main], [users] and [roles] above here +<ul> + <li>You might edit security configuration a lot and don’t want to add revision control ‘noise’ to the web.xml file</li> + <li>You might want to separate security config from the rest of web.xml config</li> + <li>Your security configuration might become large and you want to keep web.xml lean and easier to read</li> + <li>You have a complex build system where the same shiro config might need to be referenced in multiple places</li> +</ul> +<p>It is up to you - use what makes sense for your project.</p> +<a name="Web-webini"></a> +<a name="Web-WebINIconfiguration"></a> +<h3><a href="#web-ini-configuration" name="web-ini-configuration">Web INI configuration</a></h3> +<p>In addition to the standard <code>[main]</code>, <code>[users]</code> and <code>[roles]</code> sections already described in the main <a href="configuration.html" title="Configuration">Configuration</a> chapter, you can additionally specify a web-specific <code>[urls]</code> section in your <code>shiro.ini</code> file:</p> +<pre><code class="ini"># [main], [users] and [roles] above here ... [urls] ... -</pre> -</div></div> - -<p>The <tt>[urls]</tt> 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!</p> - -<p>This is <em>far</em> more flexible, powerful and concise than how you define filter chains normally in <tt>web.xml</tt>: even if you never used any other feature that Shiro provided and used only this, it alone would make it worth using.</p> - -<h4><a name="Web-%7B%7B%5Curls%5C%7D%7D"></a><tt>[urls]</tt></h4> - -<p>The format of each line in the <tt>urls</tt> section is as follows:</p> - -<div class="panel" style="border-width: 1px;"><div class="panelContent"> -<p><tt><em>URL_Ant_Path_Expression</em></tt> <tt>=</tt> <tt><em>Path_Specific_Filter_Chain</em></tt></p> -</div></div> - +</code></pre> +<p>The <code>[urls]</code> 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!</p> +<p>This is <em>far</em> more flexible, powerful and concise than how you define filter chains normally in <code>web.xml</code>: even if you never used any other feature that Shiro provided and used only this, it alone would make it worth using.</p> +<a name="Web-%7B%7B%5Curls%5C%7D%7D"></a> +<h4><a href="#urls-" name="urls-">[urls]</a></h4> +<p>The format of each line in the <code>urls</code> section is as follows:</p> +<pre><code class="ini">_URL_Ant_Path_Expression_ = _Path_Specific_Filter_Chain_ +</code></pre> <p>For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -... +<pre><code class="ini">... [urls] /index.html = anon /user/create = anon /user/** = authc /admin/** = authc, roles[administrator] -/<span class="code-keyword">rest</span>/** = authc, <span class="code-keyword">rest</span> -/remoting/rpc/** = authc, perms[<span class="code-quote">"remote:invoke"</span>] -</pre> -</div></div> - -<p>Next we'll cover exactly what these lines mean.</p> - -<h5><a name="Web-URLPathExpressions"></a>URL Path Expressions</h5> - -<p>The token on the left of the equals sign (=) is an <a class="external-link" href="http://ant.apache.org";>Ant</a>-style path expression relative to your web application's context root.</p> - -<p>For example, let's say you had the following <tt>[urls]</tt> line:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -/account/** = ssl, authc -</pre> -</div></div> - -<p>This line states that "Any request to my application's path of <tt>/account</tt> or any of it's sub paths (<tt>/account/foo</tt>, <tt>/account/bar/baz</tt>, etc) will trigger the 'ssl, authc' filter chain". We'll cover filter chains below.</p> - -<p>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, <tt>www.somehost.com/myapp</tt> and then later deploy it to <tt>www.anotherhost.com</tt> (no 'myapp' sub-path), the pattern matching will still work. All paths are relative to the <a class="external-link" href="http://docs.oracle.com/javaee/1.3/api/javax/servlet/http/HttpServletRequest.html#getContextPath()" rel="nofollow">HttpServletRequest.getContextPath()</a> value.</p> - - +/rest/** = authc, rest +/remoting/rpc/** = authc, perms["remote:invoke"] +</code></pre> +<p>Next we’ll cover exactly what these lines mean.</p> +<p>The token on the left of the equals sign (=) is an <a href="http://ant.apache.org";>Ant</a>-style path expression relative to your web application’s context root.</p> +<p>For example, let’s say you had the following <code>[urls]</code> line:</p> +<pre><code class="ini">/account/** = ssl, authc +</code></pre> +<p>This line states that “Any request to my application’s path of <code>/account</code> or any of it’s sub paths (<code>/account/foo</code>, <code>/account/bar/baz</code>, etc) will trigger the ‘ssl, authc’ filter chain”. We’ll cover filter chains below.</p> +<p>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, <code>www.somehost.com/myapp</code> and then later deploy it to <code>www.anotherhost.com</code> (no ‘myapp’ sub-path), the pattern matching will still work. All paths are relative to the <a href="http://docs.oracle.com/javaee/1.3/api/javax/servlet/http/HttpServletRequest.html#getContextPath--";>HttpServletRequest.getContextPath()</a> value.</p> <div class="panelMacro"> <table class="noteMacro"> <colgroup span="1"> @@ -433,38 +487,29 @@ <br clear="none"> URL path expressions are evaluated against an incoming request in the order they are defined and the <em>FIRST MATCH WINS</em>. For example, let's asume that there are the following chain definitions: -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> +<pre><code class="ini"> /account/** = ssl, authc /account/signup = anon -</pre> -</div></div> - -<p>If an incoming request is intended to reach <tt>/account/signup/index.html</tt> (accessible by all 'anon'ymous users), <em>it will never be handled!</em>. The reason is that the <tt>/account/**</tt> pattern matched the incoming request first and 'short-circuited' all remaining definitions.</p> - +</code></pre> +<p>If an incoming request is intended to reach <code>/account/signup/index.html</code> (accessible by all 'anon'ymous users), <em>it will never be handled!</em>. The reason is that the <code>/account/**</code> pattern matched the incoming request first and 'short-circuited' all remaining definitions.</p> <p>Always remember to define your filter chains based on a <em>FIRST MATCH WINS</em> policy!</p> </td> </tr> </tbody> </table> </div> - -<h5><a name="Web-FilterChainDefinitions"></a>Filter Chain Definitions</h5> - -<p>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:</p> - -<div class="panel" style="border-width: 1px;"><div class="panelContent"> -<p><tt>filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]</tt></p> -</div></div> - +<a name="Web-FilterChainDefinitions"></a> +<h5><a href="#filter-chain-definitions" name="filter-chain-definitions">Filter Chain Definitions</a></h5> +<p>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:</p> +<pre><code class="ini">filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN] +</code></pre> <p>where:</p> -<ul class="alternate" type="square"><li><em>filterN</em> is the name of a filter bean defined in the <tt>[main]</tt> section and</li><li><tt>[optional_configN]</tt> is an optional bracketed string that has meaning for that particular filter for <em>that particular path</em> (per-filter, <em>path-specific</em> configuration!). If the filter does not need specific config for that URL path, you may discard the brackets so <tt>filterN[]</tt> just becomes <tt>filterN</tt>.</li></ul> - - -<p>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.</p> - -<p>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.</p> - +<ul> + <li><em>filterN</em> is the name of a filter bean defined in the <code>[main]</code> section and</li> + <li><code>[optional_configN]</code> is an optional bracketed string that has meaning for that particular filter for <em>that particular path</em> (per-filter, <em>path-specific</em> configuration!). If the filter does not need specific config for that URL path, you may discard the brackets so <code>filterN[]</code> just becomes <code>filterN</code>.</li> +</ul> +<p>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.</p> +<p>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.</p> <div class="panelMacro"> <table class="tipMacro"> <colgroup span="1"> @@ -478,21 +523,17 @@ <td colspan="1" rowspan="1"> <b>Tip</b> <br clear="none"> - Being able to react to path specific configuration, i.e. the <tt>[optional_configN]</tt> part of a filter token, is a unique feature available to Shiro filters. -<p>If you want to create your own <tt>javax.servlet.Filter</tt> implementation that can also do this, make sure your filter subclasses <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html">org.apache.shiro.web.filter.PathMatchingFilter</a></p> + Being able to react to path specific configuration, i.e. the <code>[optional_configN]</code> part of a filter token, is a unique feature available to Shiro filters. +<p>If you want to create your own <code>javax.servlet.Filter</code> implementation that can also do this, make sure your filter subclasses <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html">org.apache.shiro.web.filter.PathMatchingFilter</a></p> </td> </tr> </tbody> </table> </div> - -<h6><a name="Web-AvailableFilters"></a>Available Filters</h6> - -<p>The 'pool' of filters available for use in filter chain definitions are defined in the <tt>[main]</tt> section. The name assigned to them in the main section is the name to use in the filter chain definitions. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +<a name="Web-AvailableFilters"></a> +<h6><a href="#available-filters" name="available-filters">Available Filters</a></h6> +<p>The ‘pool’ of filters available for use in filter chain definitions are defined in the <code>[main]</code> section. The name assigned to them in the main section is the name to use in the filter chain definitions. For example:</p> +<pre><code class="ini">[main] ... myFilter = com.company.web.some.FilterImplementation myFilter.property1 = value1 @@ -501,144 +542,155 @@ myFilter.property1 = value1 [urls] ... /some/path/** = myFilter -</pre> -</div></div> -<p><a name="Web-defaultfilters"></a></p> -<h2><a name="Web-DefaultFilters"></a>Default Filters</h2> - -<p>When running a web-app, Shiro will create some useful default <tt>Filter</tt> instances and make them available in the <tt>[main]</tt> section automatically. You can configure them in <tt>main</tt> as you would any other bean and reference them in your chain definitions. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +</code></pre> +<a name="Web-defaultfilters"></a> +<a name="Web-DefaultFilters"></a> +<h2><a href="#default-filters" name="default-filters">Default Filters</a></h2> +<p>When running a web-app, Shiro will create some useful default <code>Filter</code> instances and make them available in the <code>[main]</code> section automatically. You can configure them in <code>main</code> as you would any other bean and reference them in your chain definitions. For example:</p> +<pre><code class="ini">[main] ... -# Notice how we didn't define the class <span class="code-keyword">for</span> the FormAuthenticationFilter ('authc') - it is instantiated and available already: +# 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, +# 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 ... -</pre> -</div></div> - -<p>The default Filter instances available automatically are defined by the <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/mgt/DefaultFilter.html">DefaultFilter enum</a> and the enum's <tt>name</tt> field is the name available for configuration. They are:</p> - -<div class="table-wrap"> -<table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"> Filter Name </th><th colspan="1" rowspan="1" class="confluenceTh"> Class </th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> anon </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/AnonymousFilter.html">org.apache.shiro.web.filter.authc.AnonymousFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> authc </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html">org.apache.shiro.web.filter.authc.FormAuthenticationFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> authcBasic </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/BasicHttpAuthentica tionFilter.html">org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> logout </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/LogoutFilter.html">org.apache.shiro.web.filter.authc.LogoutFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> noSessionCreation </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/session/NoSessionCreationFilter.html">org.apache.shiro.web.filter.session.NoSessionCreationFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> perms </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authz/PermissionsAuthorizationFilter.html">org.apache.shiro.web.filter.authz.PermissionsAuthorizatio nFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> port </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authz/PortFilter.html">org.apache.shiro.web.filter.authz.PortFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> rest </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authz/HttpMethodPermissionFilter.html">org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> roles </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authz/RolesAuthorizationFilter.html">org.apache.shiro.web.filter.authz.RolesAuthorizationFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> ssl </td><td colspan="1" r owspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html">org.apache.shiro.web.filter.authz.SslFilter</a> </td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> user </td><td colspan="1" rowspan="1" class="confluenceTd"> <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/UserFilter.html">org.apache.shiro.web.filter.authc.UserFilter</a> </td></tr></tbody></table> -</div> - - -<h2><a name="Web-EnablingandDisablingFilters"></a>Enabling and Disabling Filters</h2> - -<p>As is the case with any filter chain definition mechanism (<tt>web.xml</tt>, 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.</p> - -<p>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 <tt>FilterChain</tt>. You can trigger a filter's enabled state generally based on a configuration property, or you can even trigger it on a <em>per request</em> basis.</p> - +</code></pre> +<p>The default Filter instances available automatically are defined by the <a href="static/current/apidocs/org/apache/shiro/web/filter/mgt/DefaultFilter.html">DefaultFilter enum</a> and the enum’s <code>name</code> field is the name available for configuration. They are:</p> +<table> + <thead> + <tr> + <th>Filter Name </th> + <th>Class </th> + </tr> + </thead> + <tbody> + <tr> + <td>anon </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authc/AnonymousFilter.html">org.apache.shiro.web.filter.authc.AnonymousFilter</a> </td> + </tr> + <tr> + <td>authc </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html">org.apache.shiro.web.filter.authc.FormAuthenticationFilter</a> </td> + </tr> + <tr> + <td>authcBasic </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authc/BasicHttpAuthenticationFilter.html">org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter</a> </td> + </tr> + <tr> + <td>logout </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authc/LogoutFilter.html">org.apache.shiro.web.filter.authc.LogoutFilter</a> </td> + </tr> + <tr> + <td>noSessionCreation </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/session/NoSessionCreationFilter.html">org.apache.shiro.web.filter.session.NoSessionCreationFilter</a> </td> + </tr> + <tr> + <td>perms </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authz/PermissionsAuthorizationFilter.html">org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter</a> </td> + </tr> + <tr> + <td>port </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authz/PortFilter.html">org.apache.shiro.web.filter.authz.PortFilter</a> </td> + </tr> + <tr> + <td>rest</td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authz/HttpMethodPermissionFilter.html">org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter</a> </td> + </tr> + <tr> + <td>roles </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authz/RolesAuthorizationFilter.html">org.apache.shiro.web.filter.authz.RolesAuthorizationFilter</a> </td> + </tr> + <tr> + <td>ssl </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authz/SslFilter.html">org.apache.shiro.web.filter.authz.SslFilter</a> </td> + </tr> + <tr> + <td>user </td> + <td><a href="static/current/apidocs/org/apache/shiro/web/filter/authc/UserFilter.html">org.apache.shiro.web.filter.authc.UserFilter</a> </td> + </tr> + </tbody> +</table> +<a name="Web-EnablingandDisablingFilters"></a> +<h2><a href="#enabling-and-disabling-filters" name="enabling-and-disabling-filters">Enabling and Disabling Filters</a></h2> +<p>As is the case with any filter chain definition mechanism (<code>web.xml</code>, 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.</p> +<p>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 <code>FilterChain</code>. You can trigger a filter’s enabled state generally based on a configuration property, or you can even trigger it on a <em>per request</em> basis.</p> <p>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.</p> - -<p>Shiro accomplishes this via its <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html">OncePerRequestFilter</a> 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*.</p> - -<p>*<a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO-224";>SHIRO-224</a> will hopefully enable this feature for any filter, not just those subclassing <tt>OncePerRequestFilter</tt>. If this is important to you, please vote for the issue.</p> - -<h3><a name="Web-GeneralEnabling%2FDisabling"></a>General Enabling/Disabling</h3> - -<p>The <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html">OncePerRequestFilter</a> (and all of its subclasses) supports enabling/disabling across all requests as well as on a per-request basis.</p> - -<p>General enabling or disabling of a filter for all requests is done by setting its <tt>enabled</tt> property to true or false. The default setting is <tt>true</tt> since most filters inherently need to execute if they are configured in a chain.</p> - +<p>Shiro accomplishes this via its <a href="static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html">OncePerRequestFilter</a> 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*.</p> +<p>*<a href="https://issues.apache.org/jira/browse/SHIRO-224";>SHIRO-224</a> will hopefully enable this feature for any filter, not just those subclassing <code>OncePerRequestFilter</code>. If this is important to you, please vote for the issue.</p> +<a name="Web-GeneralEnabling%2FDisabling"></a> +<h3><a href="#general-enabling-disabling" name="general-enabling-disabling">General Enabling/Disabling</a></h3> +<p>The <a href="static/current/apidocs/org/apache/shiro/web/servlet/OncePerRequestFilter.html">OncePerRequestFilter</a> (and all of its subclasses) supports enabling/disabling across all requests as well as on a per-request basis.</p> +<p>General enabling or disabling of a filter for all requests is done by setting its <code>enabled</code> property to true or false. The default setting is <code>true</code> since most filters inherently need to execute if they are configured in a chain.</p> <p>For example, in shiro.ini:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +<pre><code class="ini">[main] ... -# configure Shiro's <span class="code-keyword">default</span> 'ssl' filter to be disabled <span class="code-keyword">while</span> testing: -ssl.enabled = <span class="code-keyword">false</span> +# configure Shiro's default 'ssl' filter to be disabled while testing: +ssl.enabled = false [urls] ... /some/path = ssl, authc /another/path = ssl, roles[admin] ... -</pre> -</div></div> - -<p>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.</p> - -<h3><a name="Web-RequestspecificEnabling%2FDisabling"></a>Request-specific Enabling/Disabling</h3> - -<p><tt>OncePerRequestFilter</tt> actually determines if the filter is enabled or disabled based on its <tt>isEnabled(request, response)</tt> method.</p> - -<p>This method defaults to returning the value of the <tt>enabled</tt> property, which is used for generally enabling/disabling all requests as mentioned above. If you wanted to enable or disable a filter based on <em>request specific</em> criteria, you can override the <tt>OncePerRequestFilter</tt> <tt>isEnabled(request,response)</tt> method to perform more specific checks.</p> - -<h3><a name="Web-PathspecificEnabling%2FDisabling"></a>Path-specific Enabling/Disabling</h3> - -<p>Shiro's <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html">PathMatchingFilter</a> (a subclass of <tt>OncePerRequestFilter</tt> has the ability to react to configuration based on a <em>specific path</em> 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.</p> - -<p>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 <tt>OncePerRequestFilter</tt> <tt>isEnabled(request,response)</tt> method, you would override the <tt>PathMatchingFilter</tt> <tt>isEnabled(request,response,path,pathConfig)</tt> method instead.</p> - -<p><a name="Web-sessionManagement"></a></p> -<h2><a name="Web-SessionManagement"></a>Session Management</h2> - -<h3><a name="Web-ServletContainerSessions"></a>Servlet Container Sessions</h3> - -<p>In web environments, Shiro's default session manager <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/session/mgt/SessionManager.html">SessionManager</a></tt> implementation is the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/web/session/mgt/ServletContainerSessionManager.html">ServletContainerSessionManager</a></tt>. 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.</p> - -<p>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. </p> - -<p>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.</p> - -<h4><a name="Web-ServletContainerSessionTimeout"></a>Servlet Container Session Timeout</h4> - -<p>If using the default servlet container support, you configure session timeout as expected in your web application's <tt>web.xml</tt> file. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<session-config> +</code></pre> +<p>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.</p> +<a name="Web-RequestspecificEnabling%2FDisabling"></a> +<h3>Request-specific Enabling/Disabling</h3> +<p><code>OncePerRequestFilter</code> actually determines if the filter is enabled or disabled based on its <code>isEnabled(request, response)</code> method.</p> +<p>This method defaults to returning the value of the <code>enabled</code> property, which is used for generally enabling/disabling all requests as mentioned above. If you wanted to enable or disable a filter based on <em>request specific</em> criteria, you can override the <code>OncePerRequestFilter</code> <code>isEnabled(request,response)</code> method to perform more specific checks.</p> +<a name="Web-PathspecificEnabling%2FDisabling"></a> +<h3>Path-specific Enabling/Disabling</h3> +<p>Shiro’s <a href="static/current/apidocs/org/apache/shiro/web/filter/PathMatchingFilter.html">PathMatchingFilter</a> (a subclass of <code>OncePerRequestFilter</code> has the ability to react to configuration based on a <em>specific path</em> 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.</p> +<p>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 <code>OncePerRequestFilter</code> <code>isEnabled(request,response)</code> method, you would override the <code>PathMatchingFilter</code> <code>isEnabled(request,response,path,pathConfig)</code> method instead.</p> +<a name="Web-sessionManagement"></a> +<a name="Web-SessionManagement"></a> +<h2><a href="#session-management" name="session-management">Session Management</a></h2> +<a name="Web-ServletContainerSessions"></a> +<h3><a href="#servlet-container-sessions" name="servlet-container-sessions">Servlet Container Sessions</a></h3> +<p>In web environments, Shiro’s default session manager <a href="static/current/apidocs/org/apache/shiro/session/mgt/SessionManager.html"><code>SessionManager</code></a> implementation is the <a href="static/current/apidocs/org/apache/shiro/web/session/mgt/ServletContainerSessionManager.html"><code>ServletContainerSessionManager</code></a>. 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.</p> +<p>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.</p> +<p>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.</p> +<a name="Web-ServletContainerSessionTimeout"></a> +<h4><a href="#servlet-container-session-timeout" name="servlet-container-session-timeout">Servlet Container Session Timeout</a></h4> +<p>If using the default servlet container support, you configure session timeout as expected in your web application’s <code>web.xml</code> file. For example:</p> +<pre><code class="xml"><session-config> <!-- web.xml expects the session timeout in minutes: --> <session-timeout>30</session-timeout> </session-config> -</pre> -</div></div> - -<h3><a name="Web-NativeSessions"></a>Native Sessions</h3> - -<p>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. </p> - -<p>The word 'Native' here means that Shiro's own enterprise session management implementation will be used to support all <tt>Subject</tt> and <tt>HttpServletRequest</tt> 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.</p> - -<h4><a name="Web-%7B%7BDefaultWebSessionManager%7D%7D"></a><tt>DefaultWebSessionManager</tt></h4> - -<p>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 <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/web/session/mgt/DefaultWebSessionManager.html">DefaultWebSessionManager</a></tt> on Shiro's <tt>SecurityManager</tt>. For example, in <tt>shiro.ini</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>shiro.ini native web session management</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +</code></pre> +<a name="Web-NativeSessions"></a> +<h3><a href="#native-sessions" name="native-sessions">Native Sessions</a></h3> +<p>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.</p> +<p>The word ‘Native’ here means that Shiro’s own enterprise session management implementation will be used to support all <code>Subject</code> and <code>HttpServletRequest</code> 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.</p> +<a name="Web-%7B%7BDefaultWebSessionManager%7D%7D"></a> +<h4><a href="#defaultwebsessionmanager" name="defaultwebsessionmanager">DefaultWebSessionManager</a></h4> +<p>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 <a href="static/current/apidocs/org/apache/shiro/web/session/mgt/DefaultWebSessionManager.html"><code>DefaultWebSessionManager</code></a> on Shiro’s <code>SecurityManager</code>. For example, in <code>shiro.ini</code>:</p> +<p><strong>shiro.ini native web session management</strong></p> +<pre><code class="ini">[main] ... sessionManager = org.apache.shiro.web.session.mgt.DefaultWebSessionManager -# configure properties (like session timeout) here <span class="code-keyword">if</span> desired +# configure properties (like session timeout) here if desired -# Use the configured <span class="code-keyword">native</span> session manager: +# Use the configured native session manager: securityManager.sessionManager = $sessionManager -</pre> -</div></div> - -<p>Once declared, you can configure the <tt>DefaultWebSessionManager</tt> instance with native session options like session timeout and clustering configuration as described in the <a href="session-management.html" title="Session Management">Session Management</a> section.</p> - -<h5><a name="Web-NativeSessionTimeout"></a>Native Session Timeout</h5> - -<p>After configuring the <tt>DefaultWebSessionManager</tt> instance, session timeout is configured as described in <a href="session-management.html#SessionManagement-sessionTimeout">Session Management: Session Timeout</a></p> - -<h5><a name="Web-SessionCookie"></a>Session Cookie</h5> - -<p>The <tt>DefaultWebSessionManager</tt> supports two web-specific configuration properties: </p> -<ul class="alternate" type="square"><li><tt>sessionIdCookieEnabled</tt> (a boolean)</li><li><tt>sessionIdCookie</tt>, a <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/Cookie.html">Cookie</a> instance.</li></ul> - +</code></pre> +<p>Once declared, you can configure the <code>DefaultWebSessionManager</code> instance with native session options like session timeout and clustering configuration as described in the <a href="session-management.html" title="Session Management">Session Management</a> section.</p> +<a name="Web-NativeSessionTimeout"></a> +<h5><a href="#native-session-timeout" name="native-session-timeout">Native Session Timeout</a></h5> +<p>After configuring the <code>DefaultWebSessionManager</code> instance, session timeout is configured as described in <a href="session-management.html#SessionManagement-sessionTimeout">Session Management: Session Timeout</a></p> +<a name="Web-SessionCookie"></a> +<h5><a href="#session-cookie" name="session-cookie">Session Cookie</a></h5> +<p>The <code>DefaultWebSessionManager</code> supports two web-specific configuration properties:</p> +<ul> + <li><code>sessionIdCookieEnabled</code> (a boolean)</li> + <li><code>sessionIdCookie</code>, a <a href="static/current/apidocs/org/apache/shiro/web/servlet/Cookie.html">Cookie</a> instance.</li> +</ul> <div class="panelMacro"> <table class="infoMacro"> <colgroup span="1"> @@ -656,31 +708,22 @@ securityManager.sessionManager = $sessio <td colspan="1" rowspan="1"> <b>Cookie as a template</b> <br clear="none"> - The <tt>sessionIdCookie</tt> property is essentially a template - you configure the <tt>Cookie</tt> instance properties, and this template will be used to set the actual HTTP <tt>Cookie</tt> header at runtime with an appropriate session ID value. + The <code>sessionIdCookie</code> property is essentially a template - you configure the <code>Cookie</code> instance properties, and this template will be used to set the actual HTTP `Cookie` header at runtime with an appropriate session ID value. </td> </tr> </tbody> </table> </div> - -<h6><a name="Web-SessionCookieConfiguration"></a>Session Cookie Configuration</h6> - -<p>The DefaultWebSessionManager's <tt>sessionIdCookie</tt> default instance is a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html">SimpleCookie</a></tt>. This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.</p> - +<a name="Web-SessionCookieConfiguration"></a> +<h6><a href="#session-cookie-configuration" name="session-cookie-configuration">Session Cookie Configuration</a></h6> +<p>The DefaultWebSessionManager’s <code>sessionIdCookie</code> default instance is a <a href="static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html"><code>SimpleCookie</code></a>. This simple implementation allows JavaBeans-style property configuration for all of the relevant properties you would want to configure on an http Cookie.</p> <p>For example, you could set the Cookie domain:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +<pre><code class="ini">[main] ... securityManager.sessionManager.sessionIdCookie.domain = foo.com -</pre> -</div></div> - -<p>See the <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html">SimpleCookie JavaDoc</a> for additional properties.</p> - -<p>The cookie's default name is <tt>JSESSIONID</tt> in accordance with the servlet specification. Additionally, Shiro's cookie supports the <tt><a class="external-link" href="https://en.wikipedia.org/wiki/HTTP_cookie#HttpOnly_cookie"; rel="nofollow">HttpOnly</a></tt> flag. The <tt>sessionIdCookie</tt> sets <tt>HttpOnly</tt> to <tt>true</tt> by default for extra security.</p> - +</code></pre> +<p>See the <a href="static/current/apidocs/org/apache/shiro/web/servlet/SimpleCookie.html">SimpleCookie JavaDoc</a> for additional properties.</p> +<p>The cookie’s default name is <code>JSESSIONID</code> in accordance with the servlet specification. Additionally, Shiro’s cookie supports the <a href="https://en.wikipedia.org/wiki/HTTP_cookie#HttpOnly_cookie";><code>HttpOnly</code></a> flag. The <code>sessionIdCookie</code> sets <code>HttpOnly</code> to <code>true</code> by default for extra security.</p> <div class="panelMacro"> <table class="infoMacro"> <colgroup span="1"> @@ -698,38 +741,27 @@ securityManager.sessionManager.sessionId <td colspan="1" rowspan="1"> <b>Note</b> <br clear="none"> - Shiro's <tt>Cookie</tt> concept supports the <tt>HttpOnly</tt> flag even in Servlet 2.4 and 2.5 environments (whereas the Servlet API only supports it natively in 2.6 or later). + Shiro's <code>Cookie</code> concept supports the <code>HttpOnly</code> flag even in Servlet 2.4 and 2.5 environments (whereas the Servlet API only supports it natively in 2.6 or later). </td> </tr> </tbody> </table> </div> - -<h6><a name="Web-DisablingtheSessionCookie"></a>Disabling the Session Cookie</h6> - -<p>If you do not want session cookies to be used, you can disable their use by configuring the <tt>sessionIdCookieEnabled</tt> property to false. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Disabling native session cookies</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -[main] -... -securityManager.sessionManager.sessionIdCookieEnabled = <span class="code-keyword">false</span> -</pre> -</div></div> - -<p><a name="Web-rememberme"></a></p> -<h2><a name="Web-RememberMeServices"></a>Remember Me Services</h2> - -<p>Shiro will perform 'rememberMe' services if the <tt>AuthenticationToken</tt> implements the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/RememberMeAuthenticationToken.html">org.apache.shiro.authc.RememberMeAuthenticationToken</a></tt> interface. This interface specifies a method:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">boolean</span> isRememberMe(); -</pre> -</div></div> - -<p>If this method returns <tt>true</tt>, Shiro will remember the end-user's identity across sessions.</p> - +<a name="Web-DisablingtheSessionCookie"></a> +<h6><a href="#disabling-the-session-cookie" name="disabling-the-session-cookie">Disabling the Session Cookie</a></h6> +<p>If you do not want session cookies to be used, you can disable their use by configuring the <code>sessionIdCookieEnabled</code> property to false. For example:</p> +<p><strong>Disabling native session cookies</strong></p> +<pre><code class="ini">[main] +... +securityManager.sessionManager.sessionIdCookieEnabled = false +</code></pre> +<a name="Web-rememberme"></a> +<a name="Web-RememberMeServices"></a> +<h2><a href="#remember-me-services" name="remember-me-services">Remember Me Services</a></h2> +<p>Shiro will perform ‘rememberMe’ services if the <code>AuthenticationToken</code> implements the <a href="static/current/apidocs/org/apache/shiro/authc/RememberMeAuthenticationToken.html"><code>org.apache.shiro.authc.RememberMeAuthenticationToken</code></a> interface. This interface specifies a method:</p> +<pre><code class="java">boolean isRememberMe(); +</code></pre> +<p>If this method returns <code>true</code>, Shiro will remember the end-user’s identity across sessions.</p> <div class="panelMacro"> <table class="tipMacro"> <colgroup span="1"> @@ -743,350 +775,211 @@ securityManager.sessionManager.sessionId <td colspan="1" rowspan="1"> <b>UsernamePasswordToken and RememberMe</b> <br clear="none"> - The frequently-used <tt>UsernamePasswordToken</tt> already implements the <tt>RememberMeAuthenticationToken</tt> interface and supports rememberMe logins. + The frequently-used <code>UsernamePasswordToken</code> already implements the <code>RememberMeAuthenticationToken</code> interface and supports rememberMe logins. </td> </tr> </tbody> </table> </div> +<a name="Web-ProgrammaticSupport"></a> +<h3><a href="#programmatic-support" name="programmatic-support">Programmatic Support</a></h3> +<p>To use rememberMe programmatically, you can set the value to <code>true</code> on a class that supports this configuration. For example, using the standard <code>UsernamePasswordToken</code>:</p> +<pre><code class="java">UsernamePasswordToken token = new UsernamePasswordToken(username, password); -<h3><a name="Web-ProgrammaticSupport"></a>Programmatic Support</h3> - -<p>To use rememberMe programmatically, you can set the value to <tt>true</tt> on a class that supports this configuration. For example, using the standard <tt>UsernamePasswordToken</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -UsernamePasswordToken token = <span class="code-keyword">new</span> UsernamePasswordToken(username, password); - -token.setRememberMe(<span class="code-keyword">true</span>); +token.setRememberMe(true); SecurityUtils.getSubject().login(token); ... -</pre> -</div></div> - -<h3><a name="Web-FormbasedLogin"></a>Form-based Login</h3> - -<p>For web applications, the <tt>authc</tt> filter is by default a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html">FormAuthenticationFilter</a></tt>. This supports reading the 'rememberMe' boolean as a form/request parameter. By default, it expects the request param to be named <tt>rememberMe</tt>. Here is an example shiro.ini config supporting this:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - -[main] +</code></pre> +<a name="Web-FormbasedLogin"></a> +<h3>Form-based Login</h3> +<p>For web applications, the <code>authc</code> filter is by default a <a href="static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html"><code>FormAuthenticationFilter</code></a>. This supports reading the ‘rememberMe’ boolean as a form/request parameter. By default, it expects the request param to be named <code>rememberMe</code>. Here is an example shiro.ini config supporting this:</p> +<pre><code class="ini">[main] authc.loginUrl = /login.jsp [urls] # your login form page here: login.jsp = authc -</pre> -</div></div> - -<p>And in your web form, have a checkbox named 'rememberMe':</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-html"> -<span class="code-tag"><form ...></span> - - Username: <span class="code-tag"><input type=<span class="code-quote">"text"</span> name=<span class="code-quote">"username"</span>/></span> <span class="code-tag"><br/></span> - Password: <span class="code-tag"><input type=<span class="code-quote">"password"</span> name=<span class="code-quote">"password"</span>/></span> +</code></pre> +<p>And in your web form, have a checkbox named ‘rememberMe’:</p> +<pre><code class="html"><form ...> + + Username: <input type="text" name="username"/> <br/> + Password: <input type="password" name="password"/> + ... + <input type="checkbox" name="rememberMe" value="true"/>Remember Me? ... - <span class="code-tag"><input type=<span class="code-quote">"checkbox"</span> name=<span class="code-quote">"rememberMe"</span> value=<span class="code-quote">"true"</span>/></span>Remember Me? - ... -<span class="code-tag"></form></span> -</pre> -</div></div> - -<p>By default, the <tt>FormAuthenticationFilter</tt> will look for request parameters named <tt>username</tt>, <tt>password</tt> and <tt>rememberMe</tt>. If these are different than the form field names that you use in your form, you'll want to configure the names on the <tt>FormAuthenticationFilter</tt>. For example, in <tt>shiro.ini</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +</form> +</code></pre> +<p>By default, the <code>FormAuthenticationFilter</code> will look for request parameters named <code>username</code>, <code>password</code> and <code>rememberMe</code>. If these are different than the form field names that you use in your form, you’ll want to configure the names on the <code>FormAuthenticationFilter</code>. For example, in <code>shiro.ini</code>:</p> +<pre><code class="ini">[main] ... authc.loginUrl = /whatever.jsp authc.usernameParam = somethingOtherThanUsername authc.passwordParam = somethingOtherThanPassword authc.rememberMeParam = somethingOtherThanRememberMe ... -</pre> -</div></div> - -<h3><a name="Web-Cookieconfiguration"></a>Cookie configuration</h3> - -<p>You can configure how the <tt>rememberMe</tt> cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +</code></pre> +<a name="Web-Cookieconfiguration"></a> +<h3><a href="#cookie-configuration" name="cookie-configuration">Cookie configuration</a></h3> +<p>You can configure how the <code>rememberMe</code> cookie functions by setting the default {{RememberMeManager}}s various cookie properties. For example, in shiro.ini:</p> +<pre><code class="ini">[main] ... securityManager.rememberMeManager.cookie.name = foo securityManager.rememberMeManager.cookie.maxAge = blah ... -</pre> -</div></div> - -<p>See the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/web/mgt/CookieRememberMeManager.html">CookieRememberMeManager</a></tt> and the supporting <tt><a class="external-link" href="static/current/apidocs/src-html/org/apache/shiro/web/servlet/SimpleCookie.html">SimpleCookie</a></tt> JavaDoc for configuration properties.</p> - -<h3><a name="Web-Custom%7B%7BRememberMeManager%7D%7D"></a>Custom <tt>RememberMeManager</tt></h3> - -<p>It should be noted that if the default cookie-based <tt>RememberMeManager</tt> implementation does not meet your needs, you can plug in any you like in to the <tt>securityManager</tt> like you would configure any other object reference:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -[main] +</code></pre> +<p>See the <a href="static/current/apidocs/org/apache/shiro/web/mgt/CookieRememberMeManager.html"><code>CookieRememberMeManager</code></a> and the supporting <a href="static/current/apidocs/src-html/org/apache/shiro/web/servlet/SimpleCookie.html"><code>SimpleCookie</code></a> JavaDoc for configuration properties.</p> +<a name="Web-Custom%7B%7BRememberMeManager%7D%7D"></a> +<h3>Custom <code>RememberMeManager</code></h3> +<p>It should be noted that if the default cookie-based <code>RememberMeManager</code> implementation does not meet your needs, you can plug in any you like in to the <code>securityManager</code> like you would configure any other object reference:</p> +<pre><code class="ini">[main] ... rememberMeManager = com.my.impl.RememberMeManager securityManager.rememberMeManager = $rememberMeManager -</pre> -</div></div> - -<p><a name="Web-taglibrary"></a></p> -<h2><a name="Web-JSP%2FGSPTagLibrary"></a>JSP / GSP Tag Library</h2> - -<p>Apache Shiro provides a <tt>Subject</tt>-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.<br clear="none"> -<a name="Web-taglibrary"></a></p> - -<h3><a name="Web-TagLibraryConfiguration"></a>Tag Library Configuration</h3> - -<p>The Tag Library Descriptor (TLD) file is bundled in <tt>shiro-web.jar</tt> in the <tt>META-INF/shiro.tld</tt> file. To use any of the tags, add the following line to the top of your JSP page (or wherever you define page directives):</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<%@ taglib prefix=<span class="code-quote">"shiro"</span> uri=<span class="code-quote">"http:<span class="code-comment">//shiro.apache.org/tags"</span> %></span> -</pre> -</div></div> - -<p>We've used the <tt>shiro</tt> prefix to indicate the shiro tag library namespace, but you can assign whatever name you like.</p> -
[... 356 lines stripped ...]
