如果您是Apache Shiro的新手，這個簡短的教程將向您展示如何使用Apache Shiro構建一個最初步的，簡單的應用程式。我們將一路上討論Shiro的核心概念，以幫助您熟悉Shiro的設計和API。

如果您不想在學習本教程時實際編輯檔案，則可以獲得幾乎相同的示例應用程式並隨時引用它。選擇一個位置：

1、搭建

在這個簡單的例子中，我們將建立一個非常簡單的命令列應用程式，它將執行並快速退出，這樣您就可以瞭解Shiro的API。

Apache Shiro的最初設計，就是支援任何應用程式 - 從最小的命令列應用程式到最大的叢集Web應用程式。即使我們正在為本教程建立一個簡單的應用程式，但要知道無論您的應用程式如何建立或部署，shiro都是以同樣的方式使用。

搭建前置條件

• JDK版本在1.5及以上
• Maven 2.2.1及以上（maven並非是shiro要求的，只是示例使用了而已。您可以獲得Shiro的jars並以您喜歡的方式將它們合併到您的應用程式中，例如使用Apache Ant和Ivy）

例如，現在建立一個maven專案，shiro-tutorial並將以下Maven 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>
 

我們將執行一個簡單的應用程式，因此我們需要使用public static void main(String[] args)方法建立一個Java類。

在包含您的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);
    }
}
 

測試執行

執行main方法，你會看到我們的小教程“應用程式”執行並退出。您應該看到類似於以下內容的東西（注意粗體文字，指示我們的輸出）：

執行應用程式
[Tutorial.main()] INFO Tutorial - My First Apache Shiro Application
我們已經驗證了應用程式執行成功 - 現在讓我們啟用Apache Shiro。

在應用程式中啟用Shiro時要首先要理解的是，Shiro中的幾乎所有內容都與稱為的中心/核心元件相關SecurityManager有關係。對於那些熟悉Java安全性的人來說，這是Shiro關於SecurityManager的概念 - 它與java.lang.SecurityManager不是一回事。

雖然我們將在架構章節中詳細介紹Shiro的設計，現階段只需要瞭解Shiro SecurityManager是應用程式中Shiro環境的核心，並且每個應用程式都必須存在一個獨立的SecurityManager。因此，我們在Tutorial應用程式中必須做的第一件事是設定SecurityManager例項。

配置

雖然我們可以直接例項化一個SecurityManager類，但是Shiro的SecurityManager實現有足夠多的配置選項和內部元件，這使得直接用Java程式碼例項化變得很麻煩 - SecurityManager使用靈活的基於文字的配置格式配置會容易得多。

為此，Shiro提供基於INI文字的預設的配置解決方案。人們現在已經厭倦了使用龐大的XML檔案，INI易於閱讀，易於使用，並且需要很少的依賴性。

Shiro的SecurityManager實現和所有支援元件都相容JavaBeans。這使得Shiro可以通過任何配置格式進行配置，如XML（Spring，JBoss，Guice等），YAML，JSON，Groovy Builder等。INI只是Shiro在任何其他配置方式不可用的環境下提供的最基礎的配置格式。

So we’ll use an INI file to configure the Shiro SecurityManager for this simple application. First, create a src/main/resources directory starting in the same directory where the pom.xml is. Then create a shiro.ini file in that new directory with the following contents:

因此，我們將在這個簡單的應用程式中使用INI檔案來配置SecurityManager。首先，建立一個與pom.xml檔案同級的目錄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等。

引用配置

Now that we have an INI file defined, we can create the SecurityManager instance in our Tutorial application class. Change the main method to reflect the following updates:

現在我們已經定義了一個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);
}

在添加了3行程式碼後，我們的示例應用程式中啟用了Shiro！

執行main方法，你會看到一切仍然執行成功（由於Shiro的預設日誌等級是debug或者更低，所以你不會看到任何Shiro日誌訊息 - 如果它啟動並執行沒有錯誤，那麼說明一切都正常）。

那麼上述3行程式碼具體做了什麼呢？

1. 我們使用Shiro的IniSecurityManagerFactory實現來載入位於類路徑根目錄下的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容器例項中）

現在我們的SecurityManager已經準備就緒，現在我們可以開始做我們真正關心的事情 - 執行安全操作。

在保護我們的應用程式時，我們自問的最相關的問題可能是“誰是當前使用者？”或“當前使用者是否允許執行X”？在我們編寫程式碼或設計使用者介面時，通常會問這些問題：應用程式通常是基於使用者需求構建的，並且您希望根據每一個使用者來展示不同功能。因此，我們在應用程式中考慮安全性的最自然方式是基於當前使用者。Shiro的API從根本上用Subject概念代表了“當前使用者” 的概念。

在幾乎所有環境中，您都可以通過以下呼叫獲取當前正在執行的使用者：

Subject currentUser = SecurityUtils.getSubject();

用getSubject（），我們可以獲取當前正在執行的Subject。Subject是一個安全術語，基本上是指“當前正在執行的使用者的特定於安全性的檢視”。它不被稱為“使用者”，因為“使用者”這個詞通常與人類相關聯。在安全領域，術語“主體”可以指人類，也可以指第三方流程，定時任務，守護程式帳戶或任何類似的行為。它只是意味著“當前與軟體互動的東西”。但是，為了理解，您可以將其Subject視為Shiro的“使用者”概念。

在獨立應用程式中呼叫getSubject()可以返回攜帶特定位置的使用者資料的Subject物件，並且在伺服器環境（例如，web應用程式）中，它會獲取基於與當前執行緒或傳入請求相關聯的使用者資料的Subject。

現在你有了Subject，你能用它做什麼？

如果您希望在當前會話中獲取資訊，則可以獲取其會話：

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

這session是shiro下的特定的例項，它提供了常規httpSession所用的大部分內容，但是同樣也提供了很多其他東西，並且還有一個很大的區別是，它不需要HTTP環境！

當shiro整合在web應用中，預設情況下，session會基於httpSession構建。但是在非Web環境，像我們的示例中，shiro會預設自動使用企業session管理，這意味著在不同的環境下，你可以通使用同樣的API。這打開了一個全新的應用程式世界，因為任何需要會話的應用程式都不需要被強制使用HttpSession或EJB有狀態會話Bean。而且，任何客戶端技術現在都可以共享會話資料。

所以現在你可以獲得一個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.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");

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