【翻译】Apache Shiro10分钟教程

本文为翻译文，原文地址：http://shiro.apache.org/10-minute-tutorial.html

介绍

欢迎来到Apache Shiro的10分钟教程！

经过这个教程，你会明白一个开发人员如何在他们的应用中使用Shiro，而且你也可以在10分钟内作到。

概述

什么是Apache Shiro？

Apache Shiro是一个强大、易用的Java安全框架，它在身份验证、受权、加密、会话管理方面，为开发人员提供直观、全面的解决方案。

Apache Shiro能作什么事情？

它能作不少事情。不过咱们不想在入门阶段就所有展开。若是你想知道它能帮你作什么，请查阅咱们专门描述特性的网页。若是你好奇咱们的起源和为何咱们存在，请查阅描述咱们的历史和任务的网页。

好了，如今咱们开始吧。

请注意：
Shiro能运行在任何环境，不管简单的命令行，抑或大型的Web应用集群，不过咱们在此快速入门会用最简单的例子，好比Java的main方法。这样，你就能了解这些API。

下载

1. 保证已经安装JDK1.6+、Maven3.0.3+
2. 在下载页下载最新的“Source Code Distribution”。在本例中，咱们使用1.3.2 release distribution。
3. 解压

$ unzip shiro-root-1.3.2-source-release.zip

1. 进入quickstart目录

$ cd shiro-root-1.3.2/samples/quickstart

1. 运行QuickStart

$ mvn compile exec:java

它的目标只是打印一些日志信息让咱们知道这过程当中发生了什么，而后退出。在阅读本快速入门，随时查阅代码samples/quickstart/src/main/java/Quickstart.java。尝试改变文件，再运行以上的命令mvn compile exec:java，观察修改的效果。

Quickstart.java

上述的Quickstart.java文件包含咱们须要熟悉的API，如今咱们分块来看，使咱们更容易理解这究竟发生了什么。

在几乎全部的环境中，你能经过如下代码获取当前执行操做用户：

Subject currentUser = SecurityUtils.getSubject();

使用SecurityUtils.getSubject()，咱们能获取当前执行操做的Subject。Subject可看做只是一个应用程序的用户的视图。其实咱们想叫它“用户”，这样显得更“有意义”，但咱们最后仍是没这么作。由于太多的应用存在他们本身的User类或框架，咱们不想与之发生冲突。另外，在安全的领域里，这个词其实是公认的术语。

在独立的应用中使用getSubject()，它可能返回一个相应应用的用户，若是在一个服务器环境（好比Web应用），它在当前线程或传入的请求中查找关联的用户。

如今，你有了Subject实例，你可以作什么事情呢？

若是你想使某些东西在应用的当前会话中均可用的，你能够先获取Session，把需使用的东西放入Session中，使用时再取出来：

Session session = currentUser.getSession();
session.setAttribute( "someKey", "aValue" );

Session是Shiro指定的实例，它提供了大部分咱们经常使用的HttpSession的功能，但它还会有一些额外的好处，和一个重大的区别：它不须要一个HTTP环境！

若是部署在Web应用中，默认状况下Session就是HttpSession。可是，若是在非Web应用中，好比上面的Quickstart.java，Shiro会自动地使用它企业级会话管理。这意味着，不管在任何环境，你均可以使用相同的API操做Session。这打开了一个全新的世界，由于任何应用程序须要会话，不须要强制使用HttpSession或EJB有状态的Session Bean。而且，任何客户端技术能够共享会话数据。

如今咱们能获取用户和会话了。有真正有用的事情吗？好比检查他们是否被容许作这个事情？好比检查角色和权限？

好，咱们对用户作这些检查。咱们上述的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.
    //(do you know what movie this is from? ;)
    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.

这是开发人员使用Apache Shiro的核心的基础的知识，虽然一些很复杂的逻辑隐藏在引擎盖下面。

你可能会问本身，在登陆时，谁负责获取用户的数据（用户名、密码、角色、权限等）？在程序运行时谁执行这些检查？恩，你作，经过实现Shiro中称为Realm的东西，并注册该Realm到Shiro的配置中。

然而，如何配置一个Realm很大程度上依赖于运行环境。好比，若是你运行一个独立的应用，或者是Web应用，又或者是Spring应用，或J2EE应用，再或者它们的合并体。这种类型的配置在此快速入门的范围以外，由于此快速入门的目的仅是让咱们熟悉API和Shiro的概念。

当你准备跳入更多细节，你必定会想要阅读身份验证指南和受权指南。而后能够移动到其它文档，特别是参考手册，去了解各类其它问题。你可能会想加入用户邮件列表，你会发现咱们有一个热情的社区。

感谢您的阅读。咱们但愿你享受使用Apache Shiro！