Apache Shiro Web Support

1. 配置

将 Shiro 整合到 Web 应用中的最简单方式是在 web.xml 的 Servlet ContextListener 和 Filter 中添加 shiro 的 ini 配置。

与 Spring 的整合（Spring-specific web configuration）在文末说明

1.1 web.xml

Shiro 1.2 and later（Shiro 1.1及早期版本参照官方页面）

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

上述配置假定 shiro.ini 配置文件位于下列地址之一，使用最先获取到的文件：

1. /WEB_INF/shiro.ini

2. classpath 根目录下的 shiro.ini

上述配置的作用：

-  EnvironmentLoaderListener 初始化 Shiro的 WebEnvironment 实例(包括SecurityManager)，并使其可在 ServletContext 中访问。如果需要获取 WebEnvironment 实例，可调用 WebUtils.getRequiredWebEnvironment(servletContext)

- ShiroFilter 将使用 WebEnvironment 来对所有被过滤的请求执行必要的安全操作.

- filter-mapping定义保证了所有请求都将被 ShiroFilter 过滤，这是保证任意请求都是安全的的推荐配置。

通常将 ShiroFilter filter-mapping 配置在其他 filter-mapping 之前，以确保 Shiro 在其他 过滤器中也能起作用。

自定义 WebEnvironment 类配置

EnvironmentLoaderListener 默认会创建一个 IniWebEnvironment 实例，其假定Shiro是采用的 ini 配置。如需要修改默认ini配置或采用其他格式的配置（如 xml），可在 web.xml 中配置自定义的 WebEnvironment

<context-param>

    <param-name>shiroEnvironmentClass</param-name>

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

</context-param>

自定义配置文件位置

若配置文件不是存放在默认目录下，则需在 web.xml 中进行配置：

<context-param>

    <param-name>shiroConfigLocations</param-name>

    <param-value>YOUR_RESOURCE_LOCATION_HERE</param-value>

</context-param>

param-value的值可以是 /WEB-INF/some/path/shiro.ini的形式，或者是其他Shiro的ResourceUtils类支持的形式，如

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

classpath:com/foo/bar/shiro.ini

url:http://confighost.mycompany.com/myapp/shiro.ini

1.2 Web INI 配置

请参考： Apache Shiro学习-1-ini 配置

2. Session 管理

2.1 Servlet 容器 Sessions

Web环境中，Shiro的默认Session管理器SessionManager的实现是 ServletContainerSessionManager.

这个简单默认的实现的好处是采用servlet容器的session配置的应用程序能够正常工作，而缺点是与容器相关的配置不具有通用性，如Jetty和Tomcat的配置不能互用。

Servlet 容器 Session 超时（Timeout）

如果默认的servlet容器支持，这可以在web.xml中配置session超时

<session-config>

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

  <session-timeout>30</session-timeout>

</session-config>

2.2 本地session（Native Sessions）

如果需要session配置能够跨servlet容器使用（如开发时使用Jetty，而生产环境使用Tomcat），或者需要控制特定的session/集群 （session/clustering features）特征，可以启用Shiro的本地session管理。

此处的“本地”（Native）意味着Shiro的企业级Session管理实现完全绕过了容器被用于支持所有的Subject和HttpServletRequest session。但Shiro的session管理实现时透明的，已存在的 web/http 相关代码照样能够正常工作。

2.2.1 DefaultWebSessionManager

要启用本地session管理器，需要进行配置以便覆盖默认的基于容器的session管理。通过在 SecurityManager 中配置一个 DefaultWebSessionManager 实例可以达到此目的。

[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

Native Session Timeout

声明sessionManager之后，就可以依据Shiro Session Management中的选项配置session管理器，如timeout等

[main]

...

# 3,600,000 milliseconds = 1 hour

securityManager.sessionManager.globalSessionTimeout = 3600000

Session Cookie

DefaultWebSessionManager 支持两个web相关的配置属性

- sessionIdCookieEnabled （布尔值）

- sessionIdCookie （Cookie实例）

sessionIdCookie本质上是一个模板——设置的Cookie实例属性，会被用来在运行时用合适的session id 值设置真正的 http cookie头

Session Cookie 配置

 DefaultWebSessionManager的默认 sessionIdCookie 实例是SimpleCookie。这个简单实现容许采用JavaBean样式来对相关的http Cookie属性进行配置。

 如设置cookie域（domain）（更多设置参考SimpleCookie的javadoc）

 [main]

securityManager.sessionManager.sessionIdCookie.domain = foo.com

与servlet规范一样，cookie的默认名称是 JSESSIONID。此外，Shiro的cookie支持 HttpOnly标记（flag）。为了额外的安全考虑，sessionIdCookie 默认设置 HttpOnly 为 true.

取消 Session Cookie

[main]

securityManager.sessionManager.sessionIdCookieEnabled = false

3. Remember Me 服务

如果 AuthenticationToken 实现了org.apache.shiro.authc.RememberMeAuthenticationToken接口，Shiro将支持rememberMe服务

接口中有一个boolean isRememberMe();方法，如果返回true，Shiro将会通过session记住终端用户的身份。

UsernamePasswordToken 实现了 RememberMeAuthenticationToken，支持 RememberMe 服务。

3.1 代码支持

在代码中使用 RememberMe， 可以在支持此配置的类中设置其值为 true。如标准的 UsernamePasswordToken：

UsernamePasswordToken token = new UsernamePasswordToken(username, password);

token.setRememberMe(true);

SecurityUtils.getSubject().login(token);

3.2 表单登录

在web应用中， authc 过滤器默认是 FormAuthenticationFilter。这支持读取'rememberMe' 的布尔值作为表单请求的参数。默认情况下，请求参数的 name 为 rememberMe。如：

[main]

authc.loginUrl = /login.jsp

[urls]

# your login form page here:

login.jsp = authc

登录表单,其中有一个 checkbox 的 name 为'rememberMe':

<form ...>

   Username: <input type="text" name="username"/> <br/>

   Password: <input type="password" name="password"/>

   <input type="checkbox" name="rememberMe" value="true"/>Remember Me?

</form>

默认情况下, FormAuthenticationFilter 将查找 name 为 username, password 和 rememberMe 的请求参数. 如果不是默认的name值，那么需要配置FormAuthenticationFilter. 如在 shiro.ini中:

[main]

authc.loginUrl = /whatever.jsp

authc.usernameParam = somethingOtherThanUsername

authc.passwordParam = somethingOtherThanPassword

authc.rememberMeParam = somethingOtherThanRememberMe

3.3 Cookie 配置

通过设置默认的 RememberMeManager 的各个 cookie 属性可以配置 rememberMe cookie 如何起作用 . 如在shiro.ini中:

[main]

securityManager.rememberMeManager.cookie.name = foo

securityManager.rememberMeManager.cookie.maxAge = blah

更多设置参考CookieRememberMeManager和SimpleCookie的javadoc

4 JSP/GSP 标签库

Shiro提供了基于当前Subject状态的 JSP/GSP 标签库。

4.1 标签库配置

Tag Library Descriptor (TLD) 是位于 shiro-web.jar 中 META-INF 下的 shiro.tld 文件。使用时，在jsp文件顶部添加：

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

guest标签：当当前用户（subject）是访客（guest，没有身份 identity 的用户）时展现其包含的内容（与 user 相反）

<shiro:guest>

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

</shiro:guest>

user标签：当当前用户（subject）具有identity（通过认证或rememberMe服务）时展现其包含的内容

<shiro:user>

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

</shiro:user>

authenticated标签：当当前用户（subject）具有identity（在当前session通过认证，不包括通过 rememberMe 服务进入的用户）时展现其包含的内容（与notAuthenticated 标签相反）（在线支付场景）

principal标签：输出subject的身份信息（如用户名）

    Hello, <shiro:principal/>将展现用户名字符串，对应 Hello, <%= SecurityUtils.getSubject().getPrincipal().toString() %>

- Typed principal：principal 标签默认输出subject.getPrincipal() 的值。但如果要输出其他值，则可以通过其类型来获取：

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

- Principal 属性：如果principal 是一个复杂的对象而非简单的字符串，则可以通过 property 属性名或获取：

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

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

hasRole标签：若当前的Subject具有某种角色，hasRole标签将展现其包含的内容. 对应lacksRole标签.

<shiro:hasRole name="administrator">

    <a href="admin.jsp">Administer the system</a>

</shiro:hasRole>

hasAnyRole标签：任意指定的角色

<shiro:hasAnyRoles name="developer, project manager, administrator">

    You are either a developer, project manager, or administrator.

</shiro:lacksRole>

hasPermission标签：权限，对应lacksPermission

<shiro:hasPermission name="user:create">

    <a href="createUser.jsp">Create a new User</a>

</shiro:hasPermission>