1. Your First Apache Shiro Application
如果对Shiro很陌生,这篇简短的教程将教你如何搭建一个基于Shiro的简单应用,同时在应用中讲解Shiro的核心概念,以帮助你熟悉和理解API。
2. Setup
我们通过简单的命令行应用让你体会一下Shiro的API。这篇教程需要Java1.5及其以后版本,使用Maven作为构建工具。对于这篇教程,需要Maven2.2.1及其以后版本的支持。可以通过mvn --version查看maven版本信息:
创建shiro-tutorial目录,并将下面的pom.xml文件保存到目录里。
在shiro-tutorial目录下创建src/main/java子目录,在src/main/java目录下,创建Tutorial.java:
3. Test Run
进入到应用的根目录(shiro-tutorial目录),执行以下命令:
会看到应用执行后,退出了:
4. Enable Shiro
添加Shiro的支持,首先需要理解的就是其核心组件SecurityManager,每个应用只能存在一个SecurityManager实例。所以,我们需要先创建一个SecurityManager实例。
5. Configuration
可以通过Java代码创建SecurityManager,并进行一些属性的设置,但是还有一种更简洁的方式,那就是通过INI文件。INI文件以文本的方式配置Shiro,简单易用。首先,在根目录(shiro-tutorial)下创建src/main/resources子目录,然后创建shiro.ini文件,内容如下:
可以看出,只配置了几个静态用户。后面的章节,我们会使用关系型数据库,LADP等方式配置更为复杂的用户信息。
6. Referencing the Configuration
更改Tutorial类,创建SecurityManager实例:
就这么简单,添加了3行代码,加入了Shiro的支持。然后运行:
会看到程序运行正常。下面,对添加的代码进行说明:
1. 通过IniSecurityManagerFactory类加载根路径下的shiro.ini文件,这个类支持工厂方法设计模式。"classpath:"为资源前缀,指明从哪里加载ini文件。(其他资源前缀, "url:"和"file:" )
2. 调用factory.getInstance()方法,解析INI文件并返回SecurityManager实例(SecurityManager代表着配置本身)。
3. 在这个简单的例子中,我们设置SecurityManager为静态单例。需要注意的是,如果JVM中有多个Shiro的应用,就不能这样配置。但对于这个例子,是可以的。对于那些复杂的应用,需要把SecurityManager设置到应用相关的内存(比如,把它设置到ServletContext属性里,Spring, Guice, Jboss 依赖反转容器里等)。
7. Using Shiro
配置好SecurityManager后,我们需要执行安全操作了。当我们编码或设计用户接口时,要保护我们的应用,都会问,"当前的用户是谁","当前的用户有权执行某项操作?"。应用是建立在用例上的,功能也是基于用户的。所以,对于应用的安全,我们也就自然的想到当前的用户。在Shiro API中,用Subject代表当前的用户。在大部分环境中,可以通过以下调用获取当前的用户:
调用SecurityUtils.getSubject()方法,我们可以获取Subject。Subject是一个安全相关的术语,表示"当前执行用户的安全视图"。之所以没有使用"User",是因为User通常和人相关。在安全领域,Subject可以指人,也可以是第三方进程,定时服务,后台账户或其他相关事物。某种程度上,可以把Subject理解为Shiro用户的概念。
getSubject()方法在单应用中,返回的Subject表示应用指定位置的用户信息,在服务环境下,返回的是绑定了当前线程或请求信息相关的用户信息。
还可以获取用户的session,进行属性的设置:
这个Session是Shiro创建的,它和HttpSessions具有一样的功能,唯一不同的是:它不需要HTTP环境。
如果将应用部署在web环境下,这个Session就基于HttpSession,即具有HttpSession的功能。如果在非web环境下,Shiro将使用默认的企业级Session管理器维护这个Session。这意味着,你可以在任何环境下使用相同的Session API。
现在,我们拿到Subject和其关联的Session了,需要做一些检查角色或验证权限的操作了:
如果登陆失败,可以根据异常的不同进行不同的操作:
Shiro提供了很多异常类型,如果不能满足你的需求,可以自定义异常。
用户成功登陆后,我们可以记录信息:
还可以检查其是否具有指定角色:
还可以检查其是否具有某项操作的权限:
或更细粒度的实例级权限检查:
最后,用户执行完操作后,可以注销:
8. Final Tutorial class
通过对以上代码的添加,Tutorial类最终修改为:
9. Summary
希望这篇教程在指导你如何搭建一个简单的Shiro应用基础上,帮助你深刻理解Shiro的核心概念-Subject和SecurityManager。
如果对Shiro很陌生,这篇简短的教程将教你如何搭建一个基于Shiro的简单应用,同时在应用中讲解Shiro的核心概念,以帮助你熟悉和理解API。
2. Setup
我们通过简单的命令行应用让你体会一下Shiro的API。这篇教程需要Java1.5及其以后版本,使用Maven作为构建工具。对于这篇教程,需要Maven2.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目录,并将下面的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>
在shiro-tutorial目录下创建src/main/java子目录,在src/main/java目录下,创建Tutorial.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);
}
}
3. Test Run
进入到应用的根目录(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\$
4. Enable Shiro
添加Shiro的支持,首先需要理解的就是其核心组件SecurityManager,每个应用只能存在一个SecurityManager实例。所以,我们需要先创建一个SecurityManager实例。
5. Configuration
可以通过Java代码创建SecurityManager,并进行一些属性的设置,但是还有一种更简洁的方式,那就是通过INI文件。INI文件以文本的方式配置Shiro,简单易用。首先,在根目录(shiro-tutorial)下创建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
可以看出,只配置了几个静态用户。后面的章节,我们会使用关系型数据库,LADP等方式配置更为复杂的用户信息。
6. Referencing the Configuration
更改Tutorial类,创建SecurityManager实例:
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);
}
就这么简单,添加了3行代码,加入了Shiro的支持。然后运行:
mvn compile exec:java
会看到程序运行正常。下面,对添加的代码进行说明:
1. 通过IniSecurityManagerFactory类加载根路径下的shiro.ini文件,这个类支持工厂方法设计模式。"classpath:"为资源前缀,指明从哪里加载ini文件。(其他资源前缀, "url:"和"file:" )
2. 调用factory.getInstance()方法,解析INI文件并返回SecurityManager实例(SecurityManager代表着配置本身)。
3. 在这个简单的例子中,我们设置SecurityManager为静态单例。需要注意的是,如果JVM中有多个Shiro的应用,就不能这样配置。但对于这个例子,是可以的。对于那些复杂的应用,需要把SecurityManager设置到应用相关的内存(比如,把它设置到ServletContext属性里,Spring, Guice, Jboss 依赖反转容器里等)。
7. Using Shiro
配置好SecurityManager后,我们需要执行安全操作了。当我们编码或设计用户接口时,要保护我们的应用,都会问,"当前的用户是谁","当前的用户有权执行某项操作?"。应用是建立在用例上的,功能也是基于用户的。所以,对于应用的安全,我们也就自然的想到当前的用户。在Shiro API中,用Subject代表当前的用户。在大部分环境中,可以通过以下调用获取当前的用户:
Subject currentUser = SecurityUtils.getSubject();
调用SecurityUtils.getSubject()方法,我们可以获取Subject。Subject是一个安全相关的术语,表示"当前执行用户的安全视图"。之所以没有使用"User",是因为User通常和人相关。在安全领域,Subject可以指人,也可以是第三方进程,定时服务,后台账户或其他相关事物。某种程度上,可以把Subject理解为Shiro用户的概念。
getSubject()方法在单应用中,返回的Subject表示应用指定位置的用户信息,在服务环境下,返回的是绑定了当前线程或请求信息相关的用户信息。
还可以获取用户的session,进行属性的设置:
Session session = currentUser.getSession();
session.setAttribute( "someKey", "aValue" );
这个Session是Shiro创建的,它和HttpSessions具有一样的功能,唯一不同的是:它不需要HTTP环境。
如果将应用部署在web环境下,这个Session就基于HttpSession,即具有HttpSession的功能。如果在非web环境下,Shiro将使用默认的企业级Session管理器维护这个Session。这意味着,你可以在任何环境下使用相同的Session API。
现在,我们拿到Subject和其关联的Session了,需要做一些检查角色或验证权限的操作了:
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?
}
Shiro提供了很多异常类型,如果不能满足你的需求,可以自定义异常。
用户成功登陆后,我们可以记录信息:
//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!");
}
最后,用户执行完操作后,可以注销:
urrentUser.logout(); //removes all identifying information and invalidates their session too.
8. Final Tutorial class
通过对以上代码的添加,Tutorial类最终修改为:
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);
}
}
9. Summary
希望这篇教程在指导你如何搭建一个简单的Shiro应用基础上,帮助你深刻理解Shiro的核心概念-Subject和SecurityManager。