4.第一个Apache Shiro应用

如果您是ApacheShiro的新手，这个简短的教程将向您展示如何设置基于Apache Shiro的初始的且非常简单的安全应用。我们将一路讨论Shiro的核心概念，以帮助您熟悉Shiro的设计和API。

如果您不想按照本教程进行实际的文件编辑，则可从如下位置获取几乎相同的示例应用并参考它：

1）Apache Shiro的Git仓库中：

https://github.com/apache/shiro/tree/master/samples/quickstart

2）源码发行包：在Apache Shiro的源代码发行包的samples/quickstart目录中。源代码发行包可从"这里"（http://shiro.apache.org/download.html）页面获得。

4.1、设置

在这个简单的例子中，我们将创建一个非常简单的命令行应用程序，它将运行并快速退出，这样只是让您体会Shiro的API。

提示：

对任何应用——Apache Shiro的设计从一开始就支持任何应用程序，无论从最小的命令行应用程序还是到最大的集群Web应用程序。尽管我们为本教程创建了一个简单的应用程序，但请注意，无论您的应用程序的创建方式或部署方式如何，都会应用相同的使用模式。

本教程需要Java 1.5或更高版本。我们也将使用Apache Maven作为我们的构建工具，但当然这不是使用Apache Shiro所必需的。您可能会获取Shiro的所有.jars包，并将它们以您喜欢的任何方式整合到您的应用程序中，例如使用Apache Ant和Ivy。

对于本教程，请确保您使用的是Maven 2.2.1或更高版本。您应该能够在命令提示符下键入mvn --version并查看与以下类似的内容。

1- 检查Maven安装情况

在不同的平台上，打开命令行终端，输入如下命令：

Apache Shiro 安全框架快速入手（第二部分）

mvn –-version或者mvn –v回车，可以看到类似如下信息：

现在，在文件系统上创建一个新目录，例如shiro-tutorial，并将以下Mavenpom.xml文件保存在该目录中。

2- 构建pom.xml

我这里在window平台创建目录如下：E:myTestshiro-tutorial。

在shiro-tutorial目录下创建pom.xml文件，此maven的xml文件内容如下：


    
    
    
     4.0.0
     
    
     org.apache.shiro.tutorials
     
    
     shiro-tutorial
     
    
     1.0.0-SNAPSHOT
     
    
     First Apache Shiro Application
     
    
     jar
     
     
     
      UTF-8
      
     
     
      
       
       
        org.apache.maven.plugins
        
       
        maven-compiler-plugin
        
       
        2.0.2
        
        
        1.5 
        
         1.5
         
        
         ${project.build.sourceEncoding}
         
        
       
       
       
       
        org.codehaus.mojo
        
       
        exec-maven-plugin
        
       
        1.1
        
        
         
          
          
           java
           
          
         
        
        
        
         test
         
        
         Tutorial
         
        
       
      
     
     
      
      
       org.apache.shiro
       
      
       shiro-core
       
      
       1.1.0
       
      
      
      
      
       org.slf4j
       
      
       slf4j-simple
       
      
       1.6.1
       
      
       test

3- 构建类

我们将运行一个简单的命令行应用程序，因此我们需要创建一个Java类，其拥有公开静态方法void main（String args）方法。

在包含pom.xml文件的同一目录中（上文创建的目录），创建一个* src/main/java子目录。在src/main/java中创建一个包含以下内容的Tutorial.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); }}

现在不要担心import语句问题，我们很快就会理解它们。但现在，我们已经有了一个典型的命令行'shell'程序。这些程序要做的就是打印出"My First Apache Shiro Application"并退出。

4- 测试运行

为测试我们的教程应用程序，请在命令行模式下，进入到教程项目的根目录（例如shiro-tutorial）下，在命令提示符中执行以下命令：mvn compile exec:java

你会看到我们的小教程"应用程序"运行并退出。您应该看到类似以下内容（注意粗体文本，表示我们的输出）：

Apache Shiro 安全框架快速入手（第二部分）

注意，在执行上述命令时，mvn会执行一下必要的初始化工作，如下载相关组建包等，下次再运行时，就不会再下载了J

我们已验证应用程序成功运行 - 现在让我们启用Apache Shiro。继续本教程时，您可以在每次添加更多代码后运行mvn compile exec：java，以查看更改后运行结果。

4.2、启用Shio

在应用程序中启用Shiro首先要了解的是，Shiro中的几乎所有内容都与称为SecurityManager的中央/核心组件有关。对于那些熟悉Java安全性的人来说，这是Shiro的SecurityManager概念 - 它与java.lang.SecurityManager不同。

虽然我们在体系结构章节中详细介绍Shiro的设计，但现在知道ShiroSecurityManager是应用程序的Shiro环境核心,并且每个应用程序必须存在一个SecurityManager,这就足够好了。因此，我们必须在我们的教程应用程序中做的第一件事是设置SecurityManager实例。

1- 配置

虽然我们可以直接实例化SecurityManager类，但Shiro的SecurityManager实现具有足够的配置选项和内部组件，这使得在Java源代码中很难做到这一点，因此使用灵活的基于文本格式文件来配置SecurityManager会容易得多。

为此，Shiro通过基于文本的INI配置提供默认的"公分母"解决方案。现在人们对使用庞大的XML文件感到厌倦，INI易于阅读、使用简单，并且只需很少的依赖关系。稍后您将会看到，通过对对象图导航的简单了解，INI可以有效地用于配置像SecurityManager这样的简单对象图。

注意：SecurityManager有很多配置项。

Shiro的SecurityManager实现和所有支持组件都与JavaBean兼容。这使得Shiro可以使用几乎任意配置格式进行配置，如XML（Spring，JBoss，Guice等），YAML，JSON，GroovyBuilder标记等等。 INI只是Shiro的'公分母'格式，允许在任何环境下进行配置，以防其他选项无法使用。

2- 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等等。

3- 引用配置

现在我们已经定义了一个INI文件，可以在我们的教程应用程序类中创建SecurityManager实例。更改main方法如下：

public static void main(String[] args) { log.info("My First Apache Shiro Application"); //1. Factory
   
     factory = new IniSecurityManagerFactory("classpath:shiro.ini"); //2. SecurityManager securityManager = factory.getInstance(); //3. SecurityUtils.setSecurityManager(securityManager); System.exit(0); }

我们在初始代码中添加了3行代码后，Shiro在示例应用程序中启用！这是多容易是吧？

随意运行mvncompile exec：java，并看到所有东西仍然能够成功运行（由于Shiro默认的调试日志记录或更低日志等级，所以你不会看到任何Shiro日志消息 - 如果它启动并且没有错误地运行，那么你就了解到一切都是正常的）。

这是上述补充内容的描述：

1.我们使用Shiro的IniSecurityManagerFactory实现来获取位于classpath根目录下的shiro.ini文件。这种实现反映了Shiro对工厂方法设计模式的支持。 classpath：前缀是一个资源指示符，告诉shiro从哪里加载ini文件（其他前缀，如url：和file：也受支持）。

2.调用factory.getInstance()方法，该方法解析INI文件并返回反映配置的SecurityManager实例。

3.在这个简单的例子中，我们将SecurityManager设置为一个可以通过JVM访问的静态（内存）单例。但是请注意，如果您将在单个JVM中拥有多个支持Shiro的应用程序，那么这是不可取的。对于这个简单的例子，这是可以的，但更复杂的应用程序环境通常会将SecurityManager放置在特定于应用程序的内存中（例如在Web应用程序的ServletContext或Spring，Guice或JBoss DI容器实例中）

4.3、使用Shiro

我们的SecurityManager已经准备就绪，现在可以开始做我们真正关心的事情 - 执行安全操作。

在确保我们的应用程序安全时，我们自问最相关的问题可能是"谁是当前用户？"或"当前用户是否允许执行X？"？在我们编写代码或设计用户接口时，常常会提出这些问题：应用程序通常基于用户故事而构建，并且您希望基于每个用户来展现（和保护）功能。因此，我们在应用程序中考虑安全性的最自然方式是基于当前用户。 Shiro的API从根本上代表了"目前用户"主张与其主体概念。

几乎在所有环境中，您都可以通过以下调用获取当前正在执行的用户：

Subject currentUser = SecurityUtils.getSubject();

使用SecurityUtils.getSubject()，我们可以获得当前正在执行的Subject。主体是一个安全术语，基本上意味着"当前正在执行的用户的特定安全视图"。它不被称为"用户"，因为"用户"一词通常与人类相关联。在安全领域，"主体"这个术语可能意味着一个人，也可能是一个第三方进程、cron作业、守护进程帐户或任何类似的东西。它只是意味着"当前与软件交互的东西"。不过，对于大多数意图和目的，您可以将主体视为Shiro的"用户"概念。

独立应用程序中的getSubject()调用,其可能会根据特定于应用程序的位置中的用户数据以及服务器环境（例如Web应用程序）返回Subject，并根据与当前线程或传入请求关联的用户数据获取Subject 。

现在你有一个主体，你可以用它做什么？

如果您想在应用程序的当前会话期间向用户提供可用的内容，则可以获得他们的会话：

Session session = currentUser.getSession();

session.setAttribute( "someKey", "aValue" );

此Session是一个Shiro特定的实例，它提供了大多数你习惯的常规HttpSession的实例，但有一些额外的好处和一个很大的区别：它不需要HTTP环境！

如果在Web应用程序内部署，默认情况下会话将基于HttpSession。但是，在非Web环境中，像这个简单的教程应用程序，Shiro默认会自动使用其企业会话管理。这意味着无论部署环境如何，您都可以在任何层中的应用程序中使用相同的API！这将打开一个全新的应用程序世界，因为任何需要会话的应用程序都不需要强制使用HttpSession或EJB Stateful Session Beans。而且，任何客户端技术现在都可以共享会话数据。

所以现在你可以获得一个Subject主体和Session会话。但那些真正有用的，如检查是否允许他们做事、检查角色和权限等是关于什么的？

其实，我们只能对已知的用户进行这些检查。上面的Subject实例代表当前用户，但是谁是当前用户？那么，他们是匿名的——也就是说，直到他们至少登录一次。所以，让我们来这样做：

if ( !currentUser.isAuthenticated() ) { //以gui特定方式收集用户主体和凭证-principals and credentials //如html表单的用户名/密码，X509证书，OpenID等。 //我们将在这里使用用户名/密码示例，因为它是最常见的。 //(你知道这是什么电影吗？;) UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa"); //这就是你需要做的所有事情以便来支持'记住我'（没有配置 - 内置！） token.setRememberMe(true); currentUser.login(token);}

就这么简单！

但是，如果他们的登录尝试失败呢？你可以捕捉各种具体的例外情况，告诉你到底发生了什么，并允许你相应地处理和做出反应：

try { currentUser.login( token ); //如果没有例外，就是这样，搞定！} catch ( UnknownAccountException uae ) { //用户名不在系统中，如何向他们显示错误消息？} catch ( IncorrectCredentialsException ice ) { //密码不匹配，是否再试？} catch ( LockedAccountException lae ) { //该用户名的帐户被锁定 - 无法登录。如何显示一条消息？} ... 更多类型的异常检查——如果你想要 ...} catch ( AuthenticationException ae ) { //意外情况 - 怎么处理?}

您可以检查许多不同类型的例外情况，或者根据Shiro可能无法解释的自定义条件抛出自己的例外情况。有关更多信息，请参阅AuthenticationExceptionJavaDoc（http://shiro.apache.org/static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html）。

【顺便一提：安全最佳做法是为用户提供通用登录失败消息，因为您不希望帮助攻击者试图进入系统。】

那么，到现在为止，我们有一个登录用户。我们还能做什么？

让我们看看他们是谁：

//print theiridentifying principal (in this case, a username): log.info( "User [" +currentUser.getPrincipal() + "] logged in successfully." );也可以测试它们是否具有特定的角色：if ( currentUser.hasRole( "schwartz" ) ) { log.info("May theSchwartz be with you!" ); } else { log.info( "Hello, meremortal." ); }

还可以看到他们是否有权对某种类型的实体采取行动：

if (currentUser.isPermitted( "lightsaber:weild" ) ) { log.info("You may use alightsaber ring. Use it wisely."); } else { log.info("Sorry,lightsaber rings are for schwartz masters only."); }

另外，我们可以执行非常强大的实例级权限检查 - 查看用户是否有权访问特定类型实例的功能：

if (currentUser.isPermitted( "winnebago:drive:eagle5" ) ) { log.info("You arepermitted to 'drive' the 'winnebago' with license plate (id) 'eagle5'. " + "Here are thekeys - have fun!"); } else { log.info("Sorry, youaren't allowed to drive the 'eagle5' winnebago!"); }

是不是感觉小菜一碟，是吧？确实。

最后，当用户完成使用应用程序时，他们可以注销：

currentUser.logout(); //removes allidentifying information and invalidates their session too.

4.4、最终Tutorial类

在添加上面的代码示例之后，这里是我们最终的Tutorial类文件。可随意编辑并使用它，并根据需要更改安全检查（和INI配置）。完整教程示例代码如下：

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
   
     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); }}

4.5、示例小结

希望这篇入门教程能帮助您了解如何在基本应用程序中设置Shiro以及Shiro的主要设计概念Subject和SecurityManager。

但这是一个相当简单的应用程序。您可能会问自己，"如果我不想使用INI用户帐户，而想连接到更复杂的用户数据源，该怎么办？"

要回答这个问题，需要对Shiro的体系结构和配置支持机制有更深入的了解。后续我们将介绍Shiro的架构。下一篇，我将来讲一讲框架。敬请期待。

Apache Shiro 安全框架快速入手（第二部分）