Apache Shiro入门指南
你的第一个Apache Shiro应用
如果你是第一次接触Apache Shiro，这个简短的教程将向你展示如何创建并初始化一个非常简单的Apache Shiro应用。在这个过程中我们将讨论Shiro的核心概念，以此来帮助你熟悉Shiro的设计和API。
如果你并不想编写这个教程接下来的代码，你可以通过下面两种方式得到一个简单例子：
- Apache Shiro的Git仓库：https://github.com/apache/shiro/tree/master/samples/quickstart
- Apache Shiro源代码目录下的
samples/quickstart目录，下载页面
Setup
在这个简单的例子中，我们将创建一个非常简单的命令行应用，它将运行并很快的退出，让你领略下Shiro的API。
任何应用
Apache Shiro从设计的第一天起就支持任何应用，从最小的命令行应用到最大的web集群应用。尽管在这个教程中我们创建了一个简单的app，但这些方式也在其他地方也同样适用。
这个教程需要Java 1.5以上，我们也将会使用Apache Maven作为我们的构建工具，当然这并不是使用Apache Shiro所必须的。你也可以使用任何你喜欢的方式获得Shiro的jar包并将它们合并到你的应用中，例如使用Apache Ant和Ivy。
在这个教程中，请确保你使用的Maven版本是2.2.1或更高。在命令行输入mvn --version，你将会看到如下类似的信息：
测试Maven安装
hazlewood:~/shiro-tutorial$ mvn --version
Apache Maven 2.2.1 (r801777; 2009-08-06 12:16:01-0700)
Java version: 1.6.0_24
Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.7" arch: "x86_64" Family: "mac"
现在，在你的文件系统上创建一个新的目录，例如，shiro-tutorial然后保存下面Maven的pom.xml文件到这个目录：
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.apache.shiro.tutorials</groupId>
<artifactId>shiro-tutorial</artifactId>
<version>1.0.0-SNAPSHOT</version>
<name>First Apache Shiro Application</name>
<packaging>jar</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version>
<configuration>
<source>1.5</source>
<target>1.5</target>
<encoding>${project.build.sourceEncoding}</encoding>
</configuration>
</plugin>
<!-- This plugin is only to test run our little application. It is not
needed in most Shiro-enabled applications: -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.1</version>
<executions>
<execution>
<goals>
<goal>java</goal>
</goals>
</execution>
</executions>
<configuration>
<classpathScope>test</classpathScope>
<mainClass>Tutorial</mainClass>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.apache.shiro</groupId>
<artifactId>shiro-core</artifactId>
<version>1.1.0</version>
</dependency>
<!-- Shiro uses SLF4J for logging. We'll use the 'simple' binding
in this example app. See http://www.slf4j.org for more info. -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.6.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
class
我们将运行一个简单的命令行应用，因此我们需要创建一个包含public static void main(String[] args)方法的java类。
在包含pom.xml文件的目录中创建一个src/main/java的子目录，在src/main/java目录中创建Tutorial.java文件并输入下面内容：
src/main/java/Tutoral.java
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.*;
import org.apache.shiro.config.IniSecurityManagerFactory;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.session.Session;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Tutorial {
private static final transient Logger log = LoggerFactory.getLogger(Tutorial.class);
public static void main(String[] args) {
log.info("My First Apache Shiro Application");
System.exit(0);
}
}
先不要担心import部分，后面我们会讲到。现在，我们得到了一个典型的命令行应用，这个应用将会在控制台输出“My First Apache Shiro Application”然后退出。
Test Run
打开一个命令行窗口，切换到你的tutorial项目的根目录下（例如：shiro-tutorial）并执行下面代码：
mvn compile exec:java
你将看到我们的小应用运行起来并退出。你应该看到类似下面的内容：
Run The Application
lhazlewood:~/projects/shiro-tutorial$ mvn compile exec:java
... a bunch of Maven output ...
1 [Tutorial.main()] INFO Tutorial - My First Apache Shiro Application
lhazlewood:~/projects/shiro-tutorial\$
此时，我们已经确认应用正常运行了，现在让我们集成Apache Shiro。当我们继续这个教程，你可以运行mvn compile exec:java这个命令来查看我们每次添加代码后的结果。
Enable Shiro
在应用中使用Shiro，我们首先要明白的是在Shiro中的所有组件都和一个核心组件相关，这个组件就是SecurityManager。对于那些熟悉Java安全的人来说，这个是Shiro概念里的SecurityManager。它和java.lang.SecurityManager不是同一回事
我们将会在Shiro架构章节详细讲述Shiro的设计细节，现在我们只要知道Shiro SecurityManager是所有使用Shiro的应用的核心，并且每个应用都需要一个SecurityManager就已经足够了。因此，第一件事就是我们必须在我们的应用中获取一个SecurityManager实例。
配置
虽然我们可以直接实例化一个SecurityManager类，但是Shiro的SecurityManager有很多的配置选项和内部组件，使得用Java源代码来配置非常痛苦。更容易和灵活的方式是通过基于文本的配置。
为实现这个目标，Shiro提供了一个默认“common denominator”来实现基于文本 INI 的配置。人们已经厌倦了使用笨重的XML文件，在加上INI文件容易阅读，易于使用，并且依赖较少。你将看到一个简单的对象图，可以有效的使用INI配置简单对象图，就像SecurityManager。
配置选项
Shiro的SecurityManager实现和所有支持的组件都和JavaBeans兼容。事实上任何格式的配置文件都可以配置Shiro的SecurityManager，例如XML（Spring，JBoss，Guice等）、YAML、JSON、Groovy Builder markup等其他格式。INI是Shiro“common denominator”的格式，允许在任何环境中使用以防止其他的格式不可用。
shiro.ini
因此，我们将使用一个INI文件来配置我们这个简单应用的Shiro SecurityManager。首先，在pom.xml所在目录创建src/main/resources子目录。然后，在刚才创建的目录里面创建一个shiro.ini文件并输入一下内容：
src/main/resources/shiro.ini
# =============================================================================
# Tutorial INI configuration
#
# Usernames/passwords are based on the classic Mel Brooks' film "Spaceballs" :)
# =============================================================================
# -----------------------------------------------------------------------------
# Users and their (optional) assigned roles
# username = password, role1, role2, ..., roleN
# -----------------------------------------------------------------------------
[users]
root = secret, admin
guest = guest, guest
presidentskroob = 12345, president
darkhelmet = ludicrousspeed, darklord, schwartz
lonestarr = vespa, goodguy, schwartz
# -----------------------------------------------------------------------------
# Roles with assigned permissions
# roleName = perm1, perm2, ..., permN
# -----------------------------------------------------------------------------
[roles]
admin = *
schwartz = lightsaber:*
goodguy = winnebago:drive:eagle5
如你所见，这个文件设置了一些静态的用户账号和角色，对于我们第一个应用已经足够了。在后面的章节，你讲看到我们如何使用更复杂的用户数据，如关系型数据库、LDAP、ActiveDirectory、等等。
配置引用
现在我们定义好了INI文件，我们可以为我们的应用创建SecurityManager实例，按照下面的代码修改main方法：
public static void main(String[] args) {
log.info("My First Apache Shiro Application");
//1.
Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:shiro.ini");
//2.
SecurityManager securityManager = factory.getInstance();
//3.
SecurityUtils.setSecurityManager(securityManager);
System.exit(0);
}
到此，我们添加了三行代码将Shiro集成到我们的例子应用中，是不是很简单？
现在在命令行执行mvn compile exec:java，你将会看到所有代码都运行成功（由于Shiro的日志级别为debug或更低，因此你不会看到任何Shiro的日志信息。如果运行没有出现任何错误信息，那么就说明一起都正常）。
上面添加的代码做了下面几件事情：
- 我们使用Shiro的
IniSecurityManagerFactory来实现对classpath根目录下的shiro.ini文件的提取。这是通过工厂模式来实现的。classpath:前缀是一个资源指示器，它告诉Shiro到什么地方去找ini文件（还有一些其他前缀，比如url:和file:都支持的很好） - 调用
factory.getInstance()方法，将解析INI文件并返回一个``SecuriManager`实例。 - 在这个例子中，我们将
SecurityManager设置为单例，在JVM范围内访问。
使用Shiro
现在我们的SecurityManager已经设置好并且可以运行了，现在我们可以添加一些安全相关的操作了。
在思考应用安全性的时候，我们可能最关心的事情是“当前用户是谁？”或者“当前用户是否允许做X？”，我们在写代码或者设计用户接口的时候通常会问这些问题。通常构建应用程序是基于用户故事,和你基于用户需求想要的功能。因此，思考应用安全问题最自然的方式便是基于当前用户。在Shiro API里面使用Subject这个概念来代表当前用户。
几乎在所有环境下，你可以使用通过下面的代码获取当前用户：
Subject currentUser = SecurityUtils.getSubject();
使用SecurityUtils.getSubject()我们可以得到当前执行的得Subject。Subject是一个安全术语，意思是当前执行用户的一个特定安全视图（原文使用security-specific view）。我们不称之为“用户”是因为“用户”这个词通常代表一个人类。在安全的世界里，“Subject”可以代表一个真实的人，也可以代表一个第三方处理、cron任务、守护进程或其他类似的东西，简单来说就是和当前软件系统交互的主体。在大多数情况下你可以认为Subject就是Shiro的“用户”概念。
在独立应用中调用getSubject()可以从指定位置的用户数据返回一个Subject，在服务器环境下（例如 web app），将基于当前线程或收到的请求返回一个Subject。
现在你已经有了一个Subject，通过它可以做什么呢？
如果你想让用户在当前会话中使用该应用程序，你可以得到他们的session：
Session session = currentUser.getSession();
session.setAttribute( "someKey", "aValue" );
Session是一个特定的Shiro实例，它不仅代表最常用的普通HttpSesstion，而且还带有一些额外的东西，其中最大的区别是：Shiro Session并不需要HTTP环境！
如果在web应用中使用，默认情况下Session就是HttpSession。但是在非web环境下，例如在我们教程中创建的这个应用里，Shiro将自动默认使用企业级会话管理。也就是说在你的应用中你可以使用同一套API而不用关心你应用的发布环境。这就为那些需要使用会话却不想强制使用HttpSession或则EJB会话的应用打开了一个新的世界。而且，客户端还可以分享会话数据。
现在你可以获得一个Subject和它的Session。但那些真正有用的事情如果做到呢？比如检查它们是否被允许做一些事情，比如检查角色和权限。
好吧，我们只能对一个已知的用户做这些事情。我们的Subject实例代表着当前用户，但是谁才是当前用户呢？用户必须至少登陆一次我们才知道，否则就是一个匿名用户。现在，让我们来做个登录操作：
if ( !currentUser.isAuthenticated() ) {
//collect user principals and credentials in a gui specific manner
//such as username/password html form, X509 certificate, OpenID, etc.
//We'll use the username/password example here since it is the most common.
UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa");
//this is all you have to do to support 'remember me' (no config - built in!):
token.setRememberMe(true);
currentUser.login(token);
}
就这样了吗？并不是这样简单，如果他们登录失败了怎么办？你可以捕获各种特定的异常，这些异常可以准确的告诉你发生了什么，并允许你做出相应的处理和反应。例如：
try {
currentUser.login( token );
//if no exception, that's it, we're done!
} catch ( UnknownAccountException uae ) {
//username wasn't in the system, show them an error message?
} catch ( IncorrectCredentialsException ice ) {
//password didn't match, try again?
} catch ( LockedAccountException lae ) {
//account for that username is locked - can't login. Show them a message?
}
... more types exceptions to check if you want ...
} catch ( AuthenticationException ae ) {
//unexpected condition - error?
}
你还可以检查其他不同的异常类型，或则抛出你自定义的异常类型。更多异常类型请查看文档
现在我们已经有了一个登陆用户，我们还可以做些什么呢？
我们来打印出他们是谁：
//print their identifying principal (in this case, a username):
log.info( "User [" + currentUser.getPrincipal() + "] logged in successfully." );
我们也可以查看他们是否有指定的角色：
if ( currentUser.hasRole( "schwartz" ) ) {
log.info("May the Schwartz be with you!" );
} else {
log.info( "Hello, mere mortal." );
}
我们还可以查看他们是否有某些权限
if ( currentUser.isPermitted( "lightsaber:weild" ) ) {
log.info("You may use a lightsaber ring. Use it wisely.");
} else {
log.info("Sorry, lightsaber rings are for schwartz masters only.");
}
同样，我们可以执行一个非常强大的实例级权限检查，检查用户是否有权限访问特定类型的实例：
if ( currentUser.isPermitted( "winnebago:drive:eagle5" ) ) {
log.info("You are permitted to 'drive' the 'winnebago' with license plate (id) 'eagle5'. " +
"Here are the keys - have fun!");
} else {
log.info("Sorry, you aren't allowed to drive the 'eagle5' winnebago!");
}
最后，当用户使用完应用，他们可以退出登录：
currentUser.logout(); //removes all identifying information and invalidates their session too.
最终的Tutorial类
Final src/main/java/Turorial
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.*;
import org.apache.shiro.config.IniSecurityManagerFactory;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.session.Session;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Tutorial {
private static final transient Logger log = LoggerFactory.getLogger(Tutorial.class);
public static void main(String[] args) {
log.info("My First Apache Shiro Application");
Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:shiro.ini");
SecurityManager securityManager = factory.getInstance();
SecurityUtils.setSecurityManager(securityManager);
// get the currently executing user:
Subject currentUser = SecurityUtils.getSubject();
// Do some stuff with a Session (no need for a web or EJB container!!!)
Session session = currentUser.getSession();
session.setAttribute("someKey", "aValue");
String value = (String) session.getAttribute("someKey");
if (value.equals("aValue")) {
log.info("Retrieved the correct value! [" + value + "]");
}
// let's login the current user so we can check against roles and permissions:
if (!currentUser.isAuthenticated()) {
UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa");
token.setRememberMe(true);
try {
currentUser.login(token);
} catch (UnknownAccountException uae) {
log.info("There is no user with username of " + token.getPrincipal());
} catch (IncorrectCredentialsException ice) {
log.info("Password for account " + token.getPrincipal() + " was incorrect!");
} catch (LockedAccountException lae) {
log.info("The account for username " + token.getPrincipal() + " is locked. " +
"Please contact your administrator to unlock it.");
}
// ... catch more exceptions here (maybe custom ones specific to your application?
catch (AuthenticationException ae) {
//unexpected condition? error?
}
}
//say who they are:
//print their identifying principal (in this case, a username):
log.info("User [" + currentUser.getPrincipal() + "] logged in successfully.");
//test a role:
if (currentUser.hasRole("schwartz")) {
log.info("May the Schwartz be with you!");
} else {
log.info("Hello, mere mortal.");
}
//test a typed permission (not instance-level)
if (currentUser.isPermitted("lightsaber:weild")) {
log.info("You may use a lightsaber ring. Use it wisely.");
} else {
log.info("Sorry, lightsaber rings are for schwartz masters only.");
}
//a (very powerful) Instance Level permission:
if (currentUser.isPermitted("winnebago:drive:eagle5")) {
log.info("You are permitted to 'drive' the winnebago with license plate (id) 'eagle5'. " +
"Here are the keys - have fun!");
} else {
log.info("Sorry, you aren't allowed to drive the 'eagle5' winnebago!");
}
//all done - log out!
currentUser.logout();
System.exit(0);
}
}
