Shiro User Manual-Web Support

1. Configuration
将Shiro集成到web应用中非常简单，只需要在web.xml中配置ContextListener和Filter即可。需要注意的是，如果是Spring web应用，请参考Shiro与Spring集成那节。
a. web.xml
Shiro1.2及其以后版本，在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>

这种配置，可以将INI文件放到以下任意一处：
1. /WEB-INF/shiro.ini
2. shiro.ini在classpath下
上面的配置会执行以下操作：
1. EnvironmentLoaderListener初始化WebEnvironment(此接口包含了Shiro所有的操作)接口，并将它设置到ServletContext，之后，就可以通过WebUtils.getRequiredWebEnvironment(servletContext)获取WebEnvironment实例。
2. 对所有的请求，ShiroFilter将使用WebEnvironment执行所有的安全操作。
3. filter-mapping的配置使得所有的请求都要经过ShiroFilter，以保证请求的安全性。
建议将ShiroFilter filter-mapping配到其他Filter filter-mapping之前以确保Shiro好用。

b. Custom WebEnvironment Class
默认情况下，EnvironmentLoaderListener会创建IniWebEnvironment实例(即配置文件为INI格式)。可以通过设置ServletContext的context-param参数自定义WebEnvironment实例：

<context-param>
    <param-name>shiroEnvironmentClass</param-name>
    <param-value>com.foo.bar.shiro.MyWebEnvironment</param-value>
</context-param>

自定义WebEnvironment实例允许你以其他方式解析配置文件。还可以继承IniWebEnvironment进行一些其他的操作，甚至支持不同的文件配置。比如，如果想通过XML方式配置Shiro，就可以创建基于XML形式的XmlWebEnvironment实现。

c. Custom Configuration Locations
在web.xml中，添加context-param参数，以改变配置文件的存放位置：

<context-param>
    <param-name>shiroConfigLocations</param-name>
    <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value>
</context-param>

默认使用ServletContext.getResource加载配置文件，即相对于应用根路径"/"。可以使用资源前缀将配置指向文件系统,类路径，URL:

file:/home/foobar/myapp/shiro.ini
classpath:com/foo/bar/shiro.ini
url:http://confighost.mycompany.com/myapp/shiro.ini

Shiro1.1及其以前版本的配置：

<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>

这个配置，需要你的Shiro配置文件为INI格式，且需要放在classpath下(比如: classpath:shiro.ini)。
如果你想替换默认的文件(/WEB-INF/shiro.ini or classpath:shiro.ini),可以通过指定init-param参数：

<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>

不指定资源前缀的话，就使用默认的ServletContext.getResource加载配置文件。需要注意的是：ServletContext资源路径是1.2及其以后版本的功能，1.2以后版本配置configPath，必须指定资源前缀classpath:, file: 或 url: 。
通过指定资源前缀配置文件：

<init-param>
    <param-name>configPath</param-name>
    <param-value>url:http://configHost/myApp/shiro.ini</param-value>
</init-param>

也可以把INI文件中的内容直接写在web.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

    </param-value></init-param>
</filter>

2. Web INI configuration
在Configuation那章，我们已经讲述了[main], [users] and [roles]的配置，这里我们只讲述[urls]的配置。

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

[urls]
这部分允许你为不同URL定义专门的过滤器。定义格式：

URL_Ant_Path_Expression = Path_Specific_Filter_Chain

下面是一个例子：

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

a. URL Path Expressions
等号左边是相对于应用根路径的Ant风格路径表达式，比如：

/account/** = ssl, authc

这行表示，对于请求路径是/account或其子路劲(/account/foo, /account/bar/baz等)将触发'ssl, authc'过滤器链。需要注意，所有表达式都是相对应用根路径(/)。
1. Order Matters!
URL定义的顺序很重要，对于传入的请求，它会按顺序依次匹配，最先匹配的即使用这个过滤器链。比如：

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

如果一个请求的路径是/account/signup/index.html(可被匿名用户访问)，请求将不能被处理。因为/account/**匹配请求的路径，并将短路所有其他路径。
b. Filter Chain Definitions
等号右边是以逗号","分隔的过滤器定义，如果和请求路径匹配，将使用这些过滤器进行处理。它必须符合以下格式：

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

  1. filterN是定义在[main]部分的过滤器。
  2. [optional_configN]选填内容，用于特殊过滤器的配置，如果过滤器对URL没有特殊的配置，简写为filterN。
需要注意，过滤器的配置顺序即为调用顺序。当请求的执行条件不满足时，过滤器可以对response进行任何操作，比如执行跳转，返回HTTP错误码等。如果请求条件满足，会进入下一个过滤器，直至到最后的视图。
如果想自定义过滤器，继承org.apache.shiro.web.filter.PathMatchingFilter即可。
c. Available Filters
[main]定义的过滤器都可以在此处引用：

[main]
...
myFilter = com.company.web.some.FilterImplementation
myFilter.property1 = value1
...

[urls]
...
/some/path/** = myFilter

3. Default Filters
对于web应用，Shiro会默认创建一些过滤器，并可以在[main]部分引用。

[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

默认的过滤器实例都是通过枚举DefaultFilter类定义的，枚举的name字段即为过滤器的名字：

Filter Name	Class
anon	org.apache.shiro.web.filter.authc.AnonymousFilter
authc	org.apache.shiro.web.filter.authc.FormAuthenticationFilter
authcBasic	org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter
logout	org.apache.shiro.web.filter.authc.LogoutFilter
noSessionCreation	org.apache.shiro.web.filter.session.NoSessionCreationFilter
perms	org.apache.shiro.web.filter.authz.PermissionsAuthorizationFilter
port	org.apache.shiro.web.filter.authz.PortFilter
rest	org.apache.shiro.web.filter.authz.HttpMethodPermissionFilter
roles	org.apache.shiro.web.filter.authz.RolesAuthorizationFilter
ssl	org.apache.shiro.web.filter.authz.SslFilter
user	org.apache.shiro.web.filter.authc.UserFilter

4. Enabling and Disabling Filters
如果某个过滤器不使用的话，我们可以直接删除掉。Shiro1.2版本，通过父类OncePerRequestFilter支持，可以将不使用的过滤器关闭，那么请求就不会经过这个过滤器。Shiro默认的所有过滤器都继承了这个类，所以，这些过滤器都可以进行打开和关闭操作。
a. General Enabling/Disabling
OncePerRequestFilter可控制过滤器对请求的打开和关闭，也可基于每次请求进行打开和关闭。通过设置过滤器的enabled属性即可，默认为true：

[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]

b. Request-specific Enabling/Disabling
OncePerRequestFilter实际上通过filter的isEnabled方法判断过滤器是否打开或关闭。该方法默认返回enabled属性值。如果你想基于请求条件决定其打开与否，可覆写isEnabled(request,response)方法。
c. Path-specific Enabling/Disabling
PathMatchingFilter可以根据配置的特殊路径进行过滤。就是说，可以依据配置的路径决定打开还是关闭过滤器。如果你想通过这种方式，需要覆写PathMatchingFilter的PathMatchingFilter isEnabled(request,response,path,pathConfig)方法。

5. Session Management
a. Servlet Container Sessions
在web环境下，ServletContainerSessionManager为SessionManager的实现类。它把所有session的管理全部委托给了容器，好的一面是，对于当前的session配置，完全有效。不好的一面是，session的行为依赖容器，比如说，你想做集群，如果测试用Jetty，但是生产环境是Tomcat，那么移植会很麻烦。
b. Servlet Container Session Timeout
如果使用容器支持的session管理，配置session的超时如下：

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

c. Native Sessions
如果想让session的配置和集群可在容器间移植，或者想定义session的特性，可以使用Shiro自带的session管理，即native session management。
d. DefaultWebSessionManager
如果想使用自带的session管理器，需要在ini文件中，将DefaultWebSessionManager实例配置到SecurityManager：

[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

当配置了DefaultWebSessionManager后，可以进行相应属性的设置。具体请参考 Session Management那节。
e. Native Session Timeout
对于自带session的超时设置，请查看Session Management那节。
f. Session Cookie
DefaultWebSessionManager有两个和web相关的属性：

sessionIdCookieEnabled (a boolean)
sessionIdCookie, a Cookie instance

如果配置了Cookie实例，可通过sessionIdCookie属性将session ID设置到HTTP Cookie的头信息里。
g. Session Cookie Configuration
DefaultWebSessionManager的sessionIdCookie默认为SimpleCookie。可通过SimpleCookie属性设置任何值到HTTP Cookie里：

[main]
...
securityManager.sessionManager.sessionIdCookie.domain = foo.com

默认使用JSESSIONID为cookie的名。在Servlet2.4和2.5环境下，支持HttpOnly。
h. Disabling the Session Cookie
如果不想使用cookie，可将sessionIdCookieEnabled设置为false：

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

6. Remember Me Services
如果AuthenticationToken实现了org.apache.shiro.authc.RememberMeAuthenticationToken接口，就具有了rememberMe服务。RememberMeAuthenticationToken接口有一个方法：

boolean isRememberMe();

如果方法返回true，Shiro就会在本次会话中记住用户的标识。UsernamePasswordToken实现了这个接口并具有rememberMe功能。

6.1 Programmatic Support
对实现了org.apache.shiro.authc.RememberMeAuthenticationToken接口的类，只需要设置其setRememberMe发true即可。

UsernamePasswordToken token = new UsernamePasswordToken(username, password);

token.setRememberMe(true);

SecurityUtils.getSubject().login(token);

6.2 Form-based Login
对于web应用，过滤器authc的默认实现为FormAuthenticationFilter，它通过将rememberMe字段设置到请求参数里，以开启Remember Me服务：

[main]
authc.loginUrl = /login.jsp

[urls]

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

在login.jsp页面中加一个复选框：

<form ...>

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

过滤器FormAuthenticationFilter默认使用username, password和rememberMe作为参数名。可通过如下设置重新定义参数名：

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

6.3 Cookie configuration
可以通过RememberMeManager设置cookie相关的属性：

[main]
...

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

6.4 Custom RememberMeManager
如果默认的RememberMeManager不能满足你的需求，可以自定义RememberMeManager 实现：

[main]
...
rememberMeManager = com.my.impl.RememberMeManager
securityManager.rememberMeManager = $rememberMeManager

7. JSP / GSP Tag Library
Shiro提供了JSP/GSP标签库，可以根据当前Subject的状态，控制JSP,JSTL,GSP的内容输出。

7.1 Tag Library Configuration
  在页面中引入如下配置即可(TLD文件绑定在shiro-web.jar的META-INF/shiro.tld里)：

<%@ taglib prefix="shiro" uri="http://shiro.apache.org/tags" %>

7.2 The guest tag
guest标签中的内容只能被Guest用户所看到。(guest用户指没有登录或没有从Remember Me服务中获取标识身份的Subject)。

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

7.3 The user tag
user标签和guest标签正好相反。user标签中的内容必须为登录或者从Remember Me服务中获取标识的用户所看到。需要注意，它和authenticated有语义上的不同。

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

7.4 The authenticated tag
authenticated标签表示当前的用户必须被本次会话所认证过。

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

7.5 The notAuthenticated tag
notAuthenticated标签语义正好和authenticated相反，表示当前用户还没有被当前会话所认证过：

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

7.6 The principal tag
principal标签会输出当前用户(Subject)的标识:

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

如果当前用户没有任何表示信息，会输出toString方法值。相当于：

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

7.7 Typed principal
principal标签默认输出subject.getPrincipal()的值，如果你不想输出主要的标识信息，可以通过查找标识的类型，输出其他值：

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

等同于：

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

7.8 Principal property
如果标识的信息不单单是字符串，而是一个引用类型，又想使用引用类型的属性，可使用property属性：

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

等同于：

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

还可以和type组合起来使用：

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

等同于：

Hello, <%= SecurityUtils.getSubject().getPrincipals().oneByType(com.foo.User.class).getFirstName().toString() %>, how are you today?

7.9 The hasRole tag
hasRole标签表示当前的用户必须具有指定的角色：

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

7.10 The lacksRole tag
和hasRole相反，lacksRole标签表示当前用户不具有指定的角色：

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

7.11 The hasAnyRole tag
hasAnyRole标签表示，当前用户必须具有任意角色列表中的一项。角色列表使用逗号分隔：

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

7.12 The hasPermission tag
hasPermission标签表示当前用户必须具有指定的权限：

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

7.13 The lacksPermission tag
和hasPermission相反，lacksPermission标签表示，当前用户不具有指定的权限：

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