Shiro User Manual-Tutorial

1. Your First Apache Shiro Application
如果对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。