http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f37b5848/testing.html.vtl ---------------------------------------------------------------------- diff --git a/testing.html.vtl b/testing.html.vtl deleted file mode 100644 index 1c99db6..0000000 --- a/testing.html.vtl +++ /dev/null @@ -1,240 +0,0 @@ -<h1><a name="Testing-TestingwithApacheShiro"></a>Testing with Apache Shiro</h1> - -<p>This part of the documentation explains how to enable Shiro in unit tests.</p> - -<h2><a name="Testing-Whattoknowfortests"></a>What to know for tests</h2> - -<p>As we've already covered in the <a href="subject.html" title="Subject">Subject reference</a>, we know that a Subject is security-specific view of the 'currently executing' user, and that Subject instances are always bound to a thread to ensure we know <em>who</em> is executing logic at any time during the thread's execution.</p> - -<p>This means three basic things must always occur in order to support being able to access the currently executing Subject:</p> - -<ol><li>A <tt>Subject</tt> instance must be created</li><li>The <tt>Subject</tt> instance must be <em>bound</em> to the currently executing thread.</li><li>After the thread is finished executing (or if the thread's execution results in a <tt>Throwable</tt>), the <tt>Subject</tt> must be <em>unbound</em> to ensure that the thread remains 'clean' in any thread-pooled environment.</li></ol> - - -<p>Shiro has architectural components that perform this bind/unbind logic automatically for a running application. For example, in a web application, the root Shiro Filter performs this logic when <a class="external-link" href="static/current/apidocs/org/apache/shiro/web/servlet/AbstractShiroFilter.html#[[#]]#doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)">filtering a request</a>. But as test environments and frameworks differ, we need to perform this bind/unbind logic ourselves for our chosen test framework.</p> - -<h2><a name="Testing-TestSetup"></a>Test Setup</h2> - -<p>So we know after creating a <tt>Subject</tt> instance, it must be <em>bound</em> to thread. After the thread (or in this case, a test) is finished executing, we must <em>unbind</em> the Subject to keep the thread 'clean'.</p> - -<p>Luckily enough, modern test frameworks like JUnit and TestNG natively support this notion of 'setup' and 'teardown' already. We can leverage this support to simulate what Shiro would do in a 'complete' application. We've created a base abstract class that you can use in your own testing below - feel free to copy and/or modify as you see fit. It can be used in both unit testing and integration testing (we're using JUnit in this example, but TestNG works just as well):</p> - -<h3><a name="Testing-AbstractShiroTest"></a>AbstractShiroTest</h3> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -<span class="code-keyword">import</span> org.apache.shiro.UnavailableSecurityManagerException; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.apache.shiro.subject.support.SubjectThreadState; -<span class="code-keyword">import</span> org.apache.shiro.util.LifecycleUtils; -<span class="code-keyword">import</span> org.apache.shiro.util.ThreadState; -<span class="code-keyword">import</span> org.junit.AfterClass; - -/** - * Abstract test <span class="code-keyword">case</span> enabling Shiro in test environments. - */ -<span class="code-keyword">public</span> <span class="code-keyword">abstract</span> class AbstractShiroTest { - - <span class="code-keyword">private</span> <span class="code-keyword">static</span> ThreadState subjectThreadState; - - <span class="code-keyword">public</span> AbstractShiroTest() { - } - - /** - * Allows subclasses to set the currently executing {@link Subject} instance. - * - * @param subject the Subject instance - */ - <span class="code-keyword">protected</span> void setSubject(Subject subject) { - clearSubject(); - subjectThreadState = createThreadState(subject); - subjectThreadState.bind(); - } - - <span class="code-keyword">protected</span> Subject getSubject() { - <span class="code-keyword">return</span> SecurityUtils.getSubject(); - } - - <span class="code-keyword">protected</span> ThreadState createThreadState(Subject subject) { - <span class="code-keyword">return</span> <span class="code-keyword">new</span> SubjectThreadState(subject); - } - - /** - * Clears Shiro's thread state, ensuring the thread remains clean <span class="code-keyword">for</span> <span class="code-keyword">future</span> test execution. - */ - <span class="code-keyword">protected</span> void clearSubject() { - doClearSubject(); - } - - <span class="code-keyword">private</span> <span class="code-keyword">static</span> void doClearSubject() { - <span class="code-keyword">if</span> (subjectThreadState != <span class="code-keyword">null</span>) { - subjectThreadState.clear(); - subjectThreadState = <span class="code-keyword">null</span>; - } - } - - <span class="code-keyword">protected</span> <span class="code-keyword">static</span> void setSecurityManager(<span class="code-object">SecurityManager</span> securityManager) { - SecurityUtils.setSecurityManager(securityManager); - } - - <span class="code-keyword">protected</span> <span class="code-keyword">static</span> <span class="code-object">SecurityManager</span> getSecurityManager() { - <span class="code-keyword">return</span> SecurityUtils.getSecurityManager(); - } - - @AfterClass - <span class="code-keyword">public</span> <span class="code-keyword">static</span> void tearDownShiro() { - doClearSubject(); - <span class="code-keyword">try</span> { - <span class="code-object">SecurityManager</span> securityManager = getSecurityManager(); - LifecycleUtils.destroy(securityManager); - } <span class="code-keyword">catch</span> (UnavailableSecurityManagerException e) { - <span class="code-comment">//we don't care about <span class="code-keyword">this</span> when cleaning up the test environment -</span> <span class="code-comment">//(<span class="code-keyword">for</span> example, maybe the subclass is a unit test and it didn't -</span> <span class="code-comment">// need a <span class="code-object">SecurityManager</span> instance because it was using only -</span> <span class="code-comment">// mock Subject instances) -</span> } - setSecurityManager(<span class="code-keyword">null</span>); - } -} -</pre> -</div></div> - -#warning('Testing & Frameworks', 'The code in the <tt>AbstractShiroTest</tt> class uses Shiro''s <tt>ThreadState</tt> concept and a static SecurityManager. These techniques are useful in tests and in framework code, but rarely ever used in application code. -<p>Most end-users working with Shiro who need to ensure thread-state consistency will almost always use Shiro''s automatic management mechanisms, namely the <tt>Subject.associateWith</tt> and the <tt>Subject.execute</tt> methods. These methods are covered in the reference on <a href="subject.html#[[#]]#Subject-ThreadAssociation">Subject thread association</a>.</p>') - -<h2><a name="Testing-UnitTesting"></a>Unit Testing</h2> - -<p>Unit testing is mostly about testing your code and only your code in a limited scope. When you take Shiro into account, what you really want to focus on is that your code works correctly with Shiro's <em>API</em> - you don't want to necessarily test that Shiro's implementation is working correctly (that's something that the Shiro development team must ensure in Shiro's code base).</p> - -<p>Testing to see if Shiro's implementations work in conjunction with your implementations is really integration testing (discussed below).</p> - -<h3><a name="Testing-ExampleShiroUnitTest"></a>ExampleShiroUnitTest</h3> - -<p>Because unit tests are better suited for testing your own logic (and not any implementations your logic might call), it is a great idea to <em>mock</em> any APIs that your logic depends on. This works very well with Shiro - you can mock the <tt>Subject</tt> interface and have it reflect whatever conditions you want your code under test to react to. We can leverage modern mock frameworks like <a class="external-link" href="http://easymock.org/"; rel="nofollow">EasyMock</a> and <a class="external-link" href="http://site.mockito.org"; rel="nofollow">Mockito</a> to do this for us. </p> - -<p>But as stated above, the key in Shiro tests is to remember that any Subject instance (mock or real) must be bound to the thread during test execution. So all we need to do is bind the mock Subject to ensure things work as expected.</p> - -<p>(this example uses EasyMock, but Mockito works equally as well):</p> -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.junit.After; -<span class="code-keyword">import</span> org.junit.Test; - -<span class="code-keyword">import</span> <span class="code-keyword">static</span> org.easymock.EasyMock.*; - -/** - * Simple example test class showing how one may perform unit tests <span class="code-keyword">for</span> code that requires Shiro APIs. - */ -<span class="code-keyword">public</span> class ExampleShiroUnitTest <span class="code-keyword">extends</span> AbstractShiroTest { - - @Test - <span class="code-keyword">public</span> void testSimple() { - - <span class="code-comment">//1. Create a mock authenticated Subject instance <span class="code-keyword">for</span> the test to run: -</span> Subject subjectUnderTest = createNiceMock(Subject.class); - expect(subjectUnderTest.isAuthenticated()).andReturn(<span class="code-keyword">true</span>); - - <span class="code-comment">//2. Bind the subject to the current thread: -</span> setSubject(subjectUnderTest); - - <span class="code-comment">//perform test logic here. Any call to -</span> <span class="code-comment">//SecurityUtils.getSubject() directly (or nested in the -</span> <span class="code-comment">//call stack) will work properly. -</span> } - - @After - <span class="code-keyword">public</span> void tearDownSubject() { - <span class="code-comment">//3. Unbind the subject from the current thread: -</span> clearSubject(); - } - -} -</pre> -</div></div> - -<p>As you can see, we're not setting up a Shiro <tt>SecurityManager</tt> instance or configuring a <tt>Realm</tt> or anything like that. We're simply creating a mock <tt>Subject</tt> instance and binding it to the thread via the <tt>setSubject</tt> method call. This will ensure that any calls in our test code or in the code we're testing to <tt>SecurityUtils.getSubject()</tt> will work correctly.</p> - -<p>Note that the <tt>setSubject</tt> method implementation will bind your mock Subject to the thread and it will remain there until you call <tt>setSubject</tt> with a different <tt>Subject</tt> instance or until you explicitly clear it from the thread via the <tt>clearSubject()</tt> call.</p> - -<p>How long you keep the subject bound to the thread (or swap it out for a new instance in a different test) is up to you and your testing requirements. </p> - -<h4><a name="Testing-tearDownSubject%28%29"></a>tearDownSubject()</h4> - -<p>The <tt>tearDownSubject()</tt> method in the example uses a Junit 4 annotation to ensure that the Subject is cleared from the thread after every test method is executed, no matter what. This requires you to set up a new <tt>Subject</tt> instance and set it (via <tt>setSubject</tt>) for every test that executes.</p> - -<p>This is not strictly necessary however. For example, you could just bind a new Subject instance (via <tt>setSujbect</tt>) at the beginning of every test, say, in an <tt>@Before</tt>-annotated method. But if you're going to do that, you might as well have the <tt>@After tearDownSubject()</tt> method to keep things symmetrical and 'clean'.</p> - -<p>You can mix and match this setup/teardown logic in each method manually or use the @Before and @After annotations as you see fit. The <tt>AbstractShiroTest</tt> super class will however unbind the Subject from the thread after all tests because of the <tt>@AfterClass</tt> annotation in its <tt>tearDownShiro()</tt> method.</p> - -<h2><a name="Testing-IntegrationTesting"></a>Integration Testing</h2> - -<p>Now that we've covered unit test setup, let's talk a bit about integration testing. Integration testing is testing implementations across API boundaries. For example, testing that implementation A works when calling implementation B and that implementation B does what it is supposed to.</p> - -<p>You can easily perform integration testing in Shiro as well. Shiro's <tt>SecurityManager</tt> instance and things it wraps (like Realms and SessionManager, etc) are all very lightweight POJOs that use very little memory. This means you can create and tear down a <tt>SecurityManager</tt> instance for every test class you execute. When your integration tests run, they will be using 'real' <tt>SecurityManager</tt> and <tt>Subject</tt> instances like your application will be using at runtime.</p> - -<h3><a name="Testing-ExampleShiroIntegrationTest"></a>ExampleShiroIntegrationTest</h3> - -<p>The example code below looks almost identical to the Unit Test example above, but the 3 step process is slightly different:</p> - -<ol><li>There is now a step '0', which sets up a 'real' SecurityManager instance.</li><li>Step 1 now constructs a 'real' Subject instance with the <tt>Subject.Builder</tt> and binds it to the thread.</li></ol> - - -<p>Thread binding and unbinding (steps 2 and 3) function the same as the Unit Test example.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.apache.shiro.util.Factory; -<span class="code-keyword">import</span> org.junit.After; -<span class="code-keyword">import</span> org.junit.BeforeClass; -<span class="code-keyword">import</span> org.junit.Test; - -<span class="code-keyword">public</span> class ExampleShiroIntegrationTest <span class="code-keyword">extends</span> AbstractShiroTest { - - @BeforeClass - <span class="code-keyword">public</span> <span class="code-keyword">static</span> void beforeClass() { - <span class="code-comment">//0. Build and set the <span class="code-object">SecurityManager</span> used to build Subject instances used in your tests -</span> <span class="code-comment">// This typically only needs to be done once per class <span class="code-keyword">if</span> your shiro.ini doesn't change, -</span> <span class="code-comment">// otherwise, you'll need to <span class="code-keyword">do</span> <span class="code-keyword">this</span> logic in each test that is different -</span> Factory<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:test.shiro.ini"</span>); - setSecurityManager(factory.getInstance()); - } - - @Test - <span class="code-keyword">public</span> void testSimple() { - <span class="code-comment">//1. Build the Subject instance <span class="code-keyword">for</span> the test to run: -</span> Subject subjectUnderTest = <span class="code-keyword">new</span> Subject.Builder(getSecurityManager()).buildSubject(); - - <span class="code-comment">//2. Bind the subject to the current thread: -</span> setSubject(subjectUnderTest); - - <span class="code-comment">//perform test logic here. Any call to -</span> <span class="code-comment">//SecurityUtils.getSubject() directly (or nested in the -</span> <span class="code-comment">//call stack) will work properly. -</span> } - - @AfterClass - <span class="code-keyword">public</span> void tearDownSubject() { - <span class="code-comment">//3. Unbind the subject from the current thread: -</span> clearSubject(); - } -} -</pre> -</div></div> - -<p>As you can see, a concrete <tt>SecurityManager</tt> implementation is instantiated and made accessible for the remainder of the test via the <tt>setSecurityManager</tt> method. Test methods can then use this <tt>SecurityManager</tt> when using the <tt>Subject.Builder</tt> later via the <tt>getSecurityManager()</tt> method.</p> - -<p>Also note that the <tt>SecurityManager</tt> instance is set up once in a <tt>@BeforeClass</tt> setup method - a fairly common practice for most test classes. But if you wanted to, you could create a new <tt>SecurityManager</tt> instance and set it via <tt>setSecurityManager</tt> at any time from any test method - for example, you might reference two different .ini files to build a new <tt>SecurityManager</tt> depending on your test requirements. </p> - -<p>Finally, just as with the Unit Test example, the <tt>AbstractShiroTest</tt> super class will clean up all Shiro artifacts (any remaining <tt>SecurityManager</tt> and <tt>Subject</tt> instance) via its <tt>@AfterClass tearDownShiro()</tt> method to ensure the thread is 'clean' for the next test class to run.</p> - -<h2><a name="Testing-Lendahandwithdocumentation"></a>Lend a hand with documentation </h2> - -<p>While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. </p> - -<p>The easiest way to contribute your documentation is to send it to the <a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">User Forum</a> or the <a href="mailing-lists.html" title="Mailing Lists">User Mailing List</a>.</p>
http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f37b5848/testing.md.vtl ---------------------------------------------------------------------- diff --git a/testing.md.vtl b/testing.md.vtl new file mode 100644 index 0000000..2cb6af5 --- /dev/null +++ b/testing.md.vtl @@ -0,0 +1,253 @@ +<a name="Testing-TestingwithApacheShiro"></a> +Testing with Apache Shiro +========================= + +This part of the documentation explains how to enable Shiro in unit tests. + +<a name="Testing-Whattoknowfortests"></a> +What to know for tests +---------------------- + +As we've already covered in the [Subject reference](subject.html "Subject"), we know that a Subject is security-specific view of the 'currently executing' user, and that Subject instances are always bound to a thread to ensure we know _who_ is executing logic at any time during the thread's execution. + +This means three basic things must always occur in order to support being able to access the currently executing Subject: + +1. A `Subject` instance must be created +2. The `Subject` instance must be _bound_ to the currently executing thread. +3. After the thread is finished executing (or if the thread's execution results in a `Throwable`), the `Subject` must be _unbound_ to ensure that the thread remains 'clean' in any thread-pooled environment. + +Shiro has architectural components that perform this bind/unbind logic automatically for a running application. For example, in a web application, the root Shiro Filter performs this logic when [filtering a request](http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/servlet/AbstractShiroFilter.html#doFilterInternal-javax.servlet.ServletRequest-javax.servlet.ServletResponse-javax.servlet.FilterChain-). But as test environments and frameworks differ, we need to perform this bind/unbind logic ourselves for our chosen test framework. + +<a name="Testing-TestSetup"></a> +Test Setup +---------- + +So we know after creating a `Subject` instance, it must be _bound_ to thread. After the thread (or in this case, a test) is finished executing, we must _unbind_ the Subject to keep the thread 'clean'. + +Luckily enough, modern test frameworks like JUnit and TestNG natively support this notion of 'setup' and 'teardown' already. We can leverage this support to simulate what Shiro would do in a 'complete' application. We've created a base abstract class that you can use in your own testing below - feel free to copy and/or modify as you see fit. It can be used in both unit testing and integration testing (we're using JUnit in this example, but TestNG works just as well): + +<a name="Testing-AbstractShiroTest"></a> +#[[###AbstractShiroTest]]# + +``` java +import org.apache.shiro.SecurityUtils; +import org.apache.shiro.UnavailableSecurityManagerException; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.subject.Subject; +import org.apache.shiro.subject.support.SubjectThreadState; +import org.apache.shiro.util.LifecycleUtils; +import org.apache.shiro.util.ThreadState; +import org.junit.AfterClass; + +/** + * Abstract test case enabling Shiro in test environments. + */ +public abstract class AbstractShiroTest { + + private static ThreadState subjectThreadState; + + public AbstractShiroTest() { + } + + /** + * Allows subclasses to set the currently executing {@link Subject} instance. + * + * @param subject the Subject instance + */ + protected void setSubject(Subject subject) { + clearSubject(); + subjectThreadState = createThreadState(subject); + subjectThreadState.bind(); + } + + protected Subject getSubject() { + return SecurityUtils.getSubject(); + } + + protected ThreadState createThreadState(Subject subject) { + return new SubjectThreadState(subject); + } + + /** + * Clears Shiro's thread state, ensuring the thread remains clean for future test execution. + */ + protected void clearSubject() { + doClearSubject(); + } + + private static void doClearSubject() { + if (subjectThreadState != null) { + subjectThreadState.clear(); + subjectThreadState = null; + } + } + + protected static void setSecurityManager(SecurityManager securityManager) { + SecurityUtils.setSecurityManager(securityManager); + } + + protected static SecurityManager getSecurityManager() { + return SecurityUtils.getSecurityManager(); + } + + @AfterClass + public static void tearDownShiro() { + doClearSubject(); + try { + SecurityManager securityManager = getSecurityManager(); + LifecycleUtils.destroy(securityManager); + } catch (UnavailableSecurityManagerException e) { + //we don't care about this when cleaning up the test environment + //(for example, maybe the subclass is a unit test and it didn't + // need a SecurityManager instance because it was using only + // mock Subject instances) + } + setSecurityManager(null); + } +} +``` + +#warning('Testing & Frameworks', 'The code in the <code>AbstractShiroTest</code> class uses Shiro''s <code>ThreadState</code> concept and a static SecurityManager. These techniques are useful in tests and in framework code, but rarely ever used in application code. +<p>Most end-users working with Shiro who need to ensure thread-state consistency will almost always use Shiro''s automatic management mechanisms, namely the `Subject.associateWith` and the `Subject.execute` methods. These methods are covered in the reference on <a href="subject.html#Subject-ThreadAssociation">Subject thread association</a>).</p>') + +<a name="Testing-UnitTesting"></a> +Unit Testing +------------ + +Unit testing is mostly about testing your code and only your code in a limited scope. When you take Shiro into account, what you really want to focus on is that your code works correctly with Shiro's _API_ - you don't want to necessarily test that Shiro's implementation is working correctly (that's something that the Shiro development team must ensure in Shiro's code base). + +Testing to see if Shiro's implementations work in conjunction with your implementations is really integration testing (discussed below). + +<a name="Testing-ExampleShiroUnitTest"></a> +#[[###ExampleShiroUnitTest]]# + +Because unit tests are better suited for testing your own logic (and not any implementations your logic might call), it is a great idea to _mock_ any APIs that your logic depends on. This works very well with Shiro - you can mock the `Subject` interface and have it reflect whatever conditions you want your code under test to react to. We can leverage modern mock frameworks like [EasyMock](http://easymock.org/) and [Mockito](http://site.mockito.org) to do this for us. + +But as stated above, the key in Shiro tests is to remember that any Subject instance (mock or real) must be bound to the thread during test execution. So all we need to do is bind the mock Subject to ensure things work as expected. + +(this example uses EasyMock, but Mockito works equally as well): + +``` java +import org.apache.shiro.subject.Subject; +import org.junit.After; +import org.junit.Test; + +import static org.easymock.EasyMock.*; + +/** + * Simple example test class showing how one may perform unit tests for + * code that requires Shiro APIs. + */ +public class ExampleShiroUnitTest extends AbstractShiroTest { + + @Test + public void testSimple() { + + //1. Create a mock authenticated Subject instance for the test to run: + Subject subjectUnderTest = createNiceMock(Subject.class); + expect(subjectUnderTest.isAuthenticated()).andReturn(true); + + //2. Bind the subject to the current thread: + setSubject(subjectUnderTest); + + //perform test logic here. Any call to + //SecurityUtils.getSubject() directly (or nested in the + //call stack) will work properly. + } + + @After + public void tearDownSubject() { + //3. Unbind the subject from the current thread: + clearSubject(); + } + +} +``` + +As you can see, we're not setting up a Shiro `SecurityManager` instance or configuring a `Realm` or anything like that. We're simply creating a mock `Subject` instance and binding it to the thread via the `setSubject` method call. This will ensure that any calls in our test code or in the code we're testing to `SecurityUtils.getSubject()` will work correctly. + +Note that the `setSubject` method implementation will bind your mock Subject to the thread and it will remain there until you call `setSubject` with a different `Subject` instance or until you explicitly clear it from the thread via the `clearSubject()` call. + +How long you keep the subject bound to the thread (or swap it out for a new instance in a different test) is up to you and your testing requirements. + +<a name="Testing-tearDownSubject%28%29"></a> +#[[####tearDownSubject()]]# + +The `tearDownSubject()` method in the example uses a Junit 4 annotation to ensure that the Subject is cleared from the thread after every test method is executed, no matter what. This requires you to set up a new `Subject` instance and set it (via `setSubject`) for every test that executes. + +This is not strictly necessary however. For example, you could just bind a new Subject instance (via `setSujbect`) at the beginning of every test, say, in an `@Before`-annotated method. But if you're going to do that, you might as well have the `@After tearDownSubject()` method to keep things symmetrical and 'clean'. + +You can mix and match this setup/teardown logic in each method manually or use the @Before and @After annotations as you see fit. The `AbstractShiroTest` super class will however unbind the Subject from the thread after all tests because of the `@AfterClass` annotation in its `tearDownShiro()` method. + +<a name="Testing-IntegrationTesting"></a> +Integration Testing +------------------- + +Now that we've covered unit test setup, let's talk a bit about integration testing. Integration testing is testing implementations across API boundaries. For example, testing that implementation A works when calling implementation B and that implementation B does what it is supposed to. + +You can easily perform integration testing in Shiro as well. Shiro's `SecurityManager` instance and things it wraps (like Realms and SessionManager, etc) are all very lightweight POJOs that use very little memory. This means you can create and tear down a `SecurityManager` instance for every test class you execute. When your integration tests run, they will be using 'real' `SecurityManager` and `Subject` instances like your application will be using at runtime. + +<a name="Testing-ExampleShiroIntegrationTest"></a> +#[[###ExampleShiroIntegrationTest]]# + +The example code below looks almost identical to the Unit Test example above, but the 3 step process is slightly different: + +1. There is now a step '0', which sets up a 'real' SecurityManager instance. +2. Step 1 now constructs a 'real' Subject instance with the `Subject.Builder` and binds it to the thread. + +Thread binding and unbinding (steps 2 and 3) function the same as the Unit Test example. + +``` java +import org.apache.shiro.config.IniSecurityManagerFactory; +import org.apache.shiro.mgt.SecurityManager; +import org.apache.shiro.subject.Subject; +import org.apache.shiro.util.Factory; +import org.junit.After; +import org.junit.BeforeClass; +import org.junit.Test; + +public class ExampleShiroIntegrationTest extends AbstractShiroTest { + + @BeforeClass + public static void beforeClass() { + //0. Build and set the SecurityManager used to build Subject instances used in your tests + // This typically only needs to be done once per class if your shiro.ini doesn't change, + // otherwise, you'll need to do this logic in each test that is different + Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:test.shiro.ini"); + setSecurityManager(factory.getInstance()); + } + + @Test + public void testSimple() { + //1. Build the Subject instance for the test to run: + Subject subjectUnderTest = new Subject.Builder(getSecurityManager()).buildSubject(); + + //2. Bind the subject to the current thread: + setSubject(subjectUnderTest); + + //perform test logic here. Any call to + //SecurityUtils.getSubject() directly (or nested in the + //call stack) will work properly. + } + + @AfterClass + public void tearDownSubject() { + //3. Unbind the subject from the current thread: + clearSubject(); + } +} +``` + +As you can see, a concrete `SecurityManager` implementation is instantiated and made accessible for the remainder of the test via the `setSecurityManager` method. Test methods can then use this `SecurityManager` when using the `Subject.Builder` later via the `getSecurityManager()` method. + +Also note that the `SecurityManager` instance is set up once in a `@BeforeClass` setup method - a fairly common practice for most test classes. But if you wanted to, you could create a new `SecurityManager` instance and set it via `setSecurityManager` at any time from any test method - for example, you might reference two different .ini files to build a new `SecurityManager` depending on your test requirements. + +Finally, just as with the Unit Test example, the `AbstractShiroTest` super class will clean up all Shiro artifacts (any remaining `SecurityManager` and `Subject` instance) via its `@AfterClass tearDownShiro()` method to ensure the thread is 'clean' for the next test class to run. + +<a name="Testing-Lendahandwithdocumentation"></a> +Lend a hand with documentation +------------------------------ + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/f37b5848/tutorial.html.vtl ---------------------------------------------------------------------- diff --git a/tutorial.html.vtl b/tutorial.html.vtl deleted file mode 100644 index 91cfe33..0000000 --- a/tutorial.html.vtl +++ /dev/null @@ -1,513 +0,0 @@ -<h1><a name="Tutorial-ApacheShiroTutorial"></a>Apache Shiro Tutorial</h1> - -<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"> - -<tr> -<td> -<div id="border"> - <h2>Related Content</h2> - - <h3><a href="get-started.html">Getting Started</a></h3> - <p>Resources, guides and tutorials for new Shiro users. </br><span style="font-size:11"><a href="get-started.html">Read More >></a></span></p> - - <h3><a href="10-minute-tutorial.html">10-Minute Shiro Tutorial</a></h3> - <p>Try Apache Shiro for yourself in under 10 minutes. </br><span style="font-size:11"><a href="10-minute-tutorial.html">Read More >></a></span></p> - - <h3><a href="webapp-tutorial.html">Web App Tutorial</a></h3> - <p>Step-by-step tutorial for securing a web application with Shiro. </br><span style="font-size:11"><a href="webapp-tutorial.html">Read More >></a></span></p> - -</div> -</td> -</tr> -</table> - -<h2><a name="Tutorial-YourFirstApacheShiroApplication"></a>Your First Apache Shiro Application</h2> - -<p>If you're new to Apache Shiro, this short tutorial will show you how to set up an initial and very simple application secured by Apache Shiro. We'll discuss Shiro's core concepts along the way to help familiarize you with Shiro's design and API.</p> - -<p>If you don't want to actually edit files as you follow this tutorial, you can obtain a nearly identical sample application and reference it as you go. Choose a location:</p> -<ul><li>In Apache Shiro's Git repository: <a class="external-link" href="https://github.com/apache/shiro/tree/master/samples/quickstart";>https://github.com/apache/shiro/tree/master/samples/quickstart</a></li><li>In Apache Shiro's source distribution's <tt>samples/quickstart</tt> directory. The source distribution is available from the <a href="download.html" title="Download">Download</a> page.</li></ul> - -<h3><a name="Tutorial-Setup"></a>Setup</h3> - -<p>In this simple example, we'll create a very simple command-line application that will run and quickly exit, just so you can get a feel for Shiro's API.</p> -<br/><br/> - -#info('Any Application', 'Apache Shiro was designed from day one to support <em>any</em> application - from the smallest command-line applications to the largest clustered web applications. Even though we''re creating a simple app for this tutorial, know that the same usage patterns apply no matter how your application is created or where it is deployed.') -<p>This tutorial requires Java 1.5 or later. We'll also be using Apache <a class="external-link" href="http://maven.apache.org";>Maven</a> as our build tool, but of course this is not required to use Apache Shiro. You may acquire Shiro's .jars and incorporate them in any way you like into your application, for example maybe using Apache <a class="external-link" href="http://ant.apache.org";>Ant</a> and <a class="external-link" href="http://ant.apache.org/ivy";>Ivy</a>.</p> - -<p>For this tutorial, please ensure that you are using Maven 2.2.1 or later. You should be able to type <tt>mvn --version</tt> in a command prompt and see something similar to the following:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Testing Maven Installation</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -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: /<span class="code-object">System</span>/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home -Default locale: en_US, platform encoding: MacRoman -OS name: <span class="code-quote">"mac os x"</span> version: <span class="code-quote">"10.6.7"</span> arch: <span class="code-quote">"x86_64"</span> Family: <span class="code-quote">"mac"</span> -</pre> -</div></div> - -<p>For now, create a new directory on your filesystem, for example, <b><tt>shiro-tutorial</tt></b> and save the following Maven <b><tt>pom.xml</tt></b> file in that directory:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?></span> -<project xmlns=<span class="code-quote">"http://maven.apache.org/POM/4.0.0";</span> - <span class="code-keyword">xmlns:xsi</span>=<span class="code-quote">"http://www.w3.org/2001/XMLSchema-instance";</span> - xsi:schemaLocation=<span class="code-quote">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd";</span>> - - <span class="code-tag"><modelVersion></span>4.0.0<span class="code-tag"></modelVersion></span> - <span class="code-tag"><groupId></span>org.apache.shiro.tutorials<span class="code-tag"></groupId></span> - <span class="code-tag"><artifactId></span>shiro-tutorial<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>1.0.0-SNAPSHOT<span class="code-tag"></version></span> - <span class="code-tag"><name></span>First Apache Shiro Application<span class="code-tag"></name></span> - <span class="code-tag"><packaging></span>jar<span class="code-tag"></packaging></span> - - <span class="code-tag"><properties></span> - <span class="code-tag"><project.build.sourceEncoding></span>UTF-8<span class="code-tag"></project.build.sourceEncoding></span> - <span class="code-tag"></properties></span> - - <span class="code-tag"><build></span> - <span class="code-tag"><plugins></span> - <span class="code-tag"><plugin></span> - <span class="code-tag"><groupId></span>org.apache.maven.plugins<span class="code-tag"></groupId></span> - <span class="code-tag"><artifactId></span>maven-compiler-plugin<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>2.0.2<span class="code-tag"></version></span> - <span class="code-tag"><configuration></span> - <span class="code-tag"><source></span>1.5<span class="code-tag"></source></span> - <span class="code-tag"><target></span>1.5<span class="code-tag"></target></span> - <span class="code-tag"><encoding></span>${project.build.sourceEncoding}<span class="code-tag"></encoding></span> - <span class="code-tag"></configuration></span> - <span class="code-tag"></plugin></span> - - <!-- This plugin is only to test run our little application. It is not - needed in most Shiro-enabled applications: --> - <span class="code-tag"><plugin></span> - <span class="code-tag"><groupId></span>org.codehaus.mojo<span class="code-tag"></groupId></span> - <span class="code-tag"><artifactId></span>exec-maven-plugin<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>1.1<span class="code-tag"></version></span> - <span class="code-tag"><executions></span> - <span class="code-tag"><execution></span> - <span class="code-tag"><goals></span> - <span class="code-tag"><goal></span>java<span class="code-tag"></goal></span> - <span class="code-tag"></goals></span> - <span class="code-tag"></execution></span> - <span class="code-tag"></executions></span> - <span class="code-tag"><configuration></span> - <span class="code-tag"><classpathScope></span>test<span class="code-tag"></classpathScope></span> - <span class="code-tag"><mainClass></span>Tutorial<span class="code-tag"></mainClass></span> - <span class="code-tag"></configuration></span> - <span class="code-tag"></plugin></span> - <span class="code-tag"></plugins></span> - <span class="code-tag"></build></span> - - <span class="code-tag"><dependencies></span> - <span class="code-tag"><dependency></span> - <span class="code-tag"><groupId></span>org.apache.shiro<span class="code-tag"></groupId></span> - <span class="code-tag"><artifactId></span>shiro-core<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>1.1.0<span class="code-tag"></version></span> - <span class="code-tag"></dependency></span> - <!-- Shiro uses SLF4J for logging. We'll use the 'simple' binding - in this example app. See http://www.slf4j.org for more info. --> - <span class="code-tag"><dependency></span> - <span class="code-tag"><groupId></span>org.slf4j<span class="code-tag"></groupId></span> - <span class="code-tag"><artifactId></span>slf4j-simple<span class="code-tag"></artifactId></span> - <span class="code-tag"><version></span>1.6.1<span class="code-tag"></version></span> - <span class="code-tag"><scope></span>test<span class="code-tag"></scope></span> - <span class="code-tag"></dependency></span> - <span class="code-tag"></dependencies></span> - -<span class="code-tag"></project></span> -</pre> -</div></div> - -<h4><a name="Tutorial-TheTutorialclass"></a>The Tutorial class</h4> - -<p>We'll be running a simple command-line application, so we'll need to create a Java class with a <tt>public static void main(String[] args)</tt> method. </p> - -<p>In the same directory containing your <tt>pom.xml</tt> file, create a *<tt>src/main/java</tt> sub directory. In <tt>src/main/java</tt> create a <tt>Tutorial.java</tt> file with the following contents:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>src/main/java/Tutorial.java</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -<span class="code-keyword">import</span> org.apache.shiro.authc.*; -<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.session.Session; -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.apache.shiro.util.Factory; -<span class="code-keyword">import</span> org.slf4j.Logger; -<span class="code-keyword">import</span> org.slf4j.LoggerFactory; - -<span class="code-keyword">public</span> class Tutorial { - - <span class="code-keyword">private</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-keyword">transient</span> Logger log = LoggerFactory.getLogger(Tutorial.class); - - <span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) { - log.info(<span class="code-quote">"My First Apache Shiro Application"</span>); - <span class="code-object">System</span>.exit(0); - } -} -</pre> -</div></div> - -<p>Don't worry about the import statements for now - we'll get to them shortly. But for now, we've got a typical command line program 'shell'. All this program will do is print out the text "My First Apache Shiro Application" and exit.</p> - -<h3><a name="Tutorial-TestRun"></a>Test Run</h3> - -<p>To try our Tutorial application, execute the following in a command prompt in your tutorial project's root dirctory (e.g. <tt>shiro-tutorial</tt>), and type the following:</p> - -<p><tt>mvn compile exec:java</tt></p> - -<p>And you will see our little Tutorial 'application' run and exit. You should see something similar to the following (notice the bold text, indicating our output):</p> - -<div class="panel" style="background-color: white;border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;background-color: white;"><b>Run the Application</b></div><div class="panelContent" style="background-color: white;"> -<p><tt>lhazlewood:~/projects/shiro-tutorial$ mvn compile exec:java</tt></p> - -<p><tt>... a bunch of Maven output ...</tt></p> - -<p><b><tt>1 [Tutorial.main()] INFO Tutorial - My First Apache Shiro Application</tt></b><br clear="none"> -<tt>lhazlewood:~/projects/shiro-tutorial\$</tt></p> -</div></div> - -<p>We've verified the application runs successfully - now let's enable Apache Shiro. As we continue with the tutorial, you can run <tt>mvn compile exec:java</tt> after each time we add some more code to see the results of our changes.</p> - -<h3><a name="Tutorial-EnableShiro"></a>Enable Shiro</h3> - -<p>The first thing to understand in enabling Shiro in an application is that almost everything in Shiro is related to a central/core component called the <tt>SecurityManager</tt>. For those familiar with Java security, this is Shiro's notion of a SecurityManager - it is <em>NOT</em> the same thing as the <tt>java.lang.SecurityManager</tt>.</p> - -<p>While we will cover Shiro's design in detail in the <a href="architecture.html" title="Architecture">Architecture</a> chapter, it is good enough for now to know that the Shiro <tt>SecurityManager</tt> is the core of a Shiro environment for an application and one <tt>SecurityManager</tt> must exist per application. So, the first thing we must do in our Tutorial application is set-up the <tt>SecurityManager</tt> instance.</p> - -<h4><a name="Tutorial-Configuration"></a>Configuration</h4> - -<p>While we could instantiate a <tt>SecurityManager</tt> class directly, Shiro's <tt>SecurityManager</tt> implementations have enough configuration options and internal components that make this a pain to do in Java source code - it would be much easier to configure the <tt>SecurityManager</tt> with a flexible text-based configuration format. </p> - -<p>To that end, Shiro provides a default ‘common denominator’ solution via text-based <a class="external-link" href="https://en.wikipedia.org/wiki/INI_file"; rel="nofollow">INI</a> configuration. People are pretty tired of using bulky XML files these days, and INI is easy to read, simple to use, and requires very few dependencies. You’ll also see later that with a simple understanding of object graph navigation, INI can be used effectively to configure simple object graphs like the SecurityManager. </p> - -#tip('Many Configuration Options', 'Shiro''s <tt>SecurityManager</tt> implementations and all supporting components are all JavaBeans compatible. This allows Shiro to be configured with practically any configuration format such as XML (Spring, JBoss, Guice, etc), <a class="external-link" href="http://www.yaml.org/"; rel="nofollow">YAML</a>, JSON, Groovy Builder markup, and more. INI is just Shiro''s ''common denominator'' format that allows configuration in any environment in case other options are not available.') - -<h5><a name="Tutorial-%7B%7Bshiro.ini%7D%7D"></a><tt>shiro.ini</tt></h5> - -<p>So we'll use an INI file to configure the Shiro <tt>SecurityManager</tt> for this simple application. First, create a <b><tt>src/main/resources</tt></b> directory starting in the same directory where the <tt>pom.xml</tt> is. Then create a <tt>shiro.ini</tt> file in that new directory with the following contents:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>src/main/resources/shiro.ini</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -# ============================================================================= -# Tutorial INI configuration -# -# Usernames/passwords are based on the classic Mel Brooks' film <span class="code-quote">"Spaceballs"</span> :) -# ============================================================================= - -# ----------------------------------------------------------------------------- -# 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 -</pre> -</div></div> - -<p>As you see, this configuration basically sets up a small set of static user accounts, good enough for our first application. In later chapters, you will see how we can use more complex User data sources like relational databases, LDAP an ActiveDirectory, and more.</p> - -<h4><a name="Tutorial-ReferencingtheConfiguration"></a>Referencing the Configuration</h4> - -<p>Now that we have an INI file defined, we can create the <tt>SecurityManager</tt> instance in our Tutorial application class. Change the <tt>main</tt> method to reflect the following updates:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) { - - log.info(<span class="code-quote">"My First Apache Shiro Application"</span>); - - <span class="code-comment">//1. -</span> Factory<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:shiro.ini"</span>); - - <span class="code-comment">//2. -</span> <span class="code-object">SecurityManager</span> securityManager = factory.getInstance(); - - <span class="code-comment">//3. -</span> SecurityUtils.setSecurityManager(securityManager); - - <span class="code-object">System</span>.exit(0); -} -</pre> -</div></div> - -<p>And there we go - Shiro is enabled in our sample application after adding only 3 lines of code! How easy was that? </p> - -<p>Feel free to run <tt>mvn compile exec:java</tt> and see that everything still runs successfully (due to Shiro's default logging of debug or lower, you won't see any Shiro log messages - if it starts and runs without error, then you know everything is still ok).</p> - -<p>Here is what the above additions are doing:</p> - -<ol><li>We use Shiro's <tt>IniSecurityManagerFactory</tt> implementation to ingest our <tt>shiro.ini</tt> file which is located at the root of the classpath. This implementation reflects Shiro's support of the <a class="external-link" href="https://en.wikipedia.org/wiki/Factory_method_pattern"; rel="nofollow">Factory Method Design Pattern</a>. The <tt>classpath:</tt> prefix is an resource indicator that tells shiro where to load the ini file from (other prefixes, like <tt>url:</tt> and <tt>file:</tt> are supported as well). -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>The <tt>factory.getInstance()</tt> method is called, which parses the INI file and returns a <tt>SecurityManager</tt> instance reflecting the configuration. -<br clear="none" class="atl-forced-newline"> -<br clear="none" class="atl-forced-newline"></li><li>In this simple example, we set the <tt>SecurityManager</tt> to be a <em>static</em> (memory) singleton, accessible across the JVM. Note however that this is not desireable if you will ever have more than one Shiro-enabled application in a single JVM. For this simple example, it is ok, but more sophisticated application environments will usually place the <tt>SecurityManager</tt> in application-specific memory (such as in a web app's <tt>ServletContext</tt> or a Spring, Guice or JBoss DI container instance).</li></ol> - - -<h3><a name="Tutorial-UsingShiro"></a>Using Shiro</h3> - -<p>Now that our SecurityManager is set-up and ready-to go, now we can start doing the things we really care about - performing security operations.</p> - -<p>When securing our applications, probably the most relevant questions we ask ourselves are “Who is the current user?” or “Is the current user allowed to do X”? It is common to ask these questions as we're writing code or designing user interfaces: applications are usually built based on user stories, and you want functionality represented (and secured) based on a per-user basis. So, the most natural way for us to think about security in our application is based on the current user. Shiro’s API fundamentally represents the notion of 'the current user' with its <tt>Subject</tt> concept. </p> - -<p>In almost all environments, you can obtain the currently executing user via the following call:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject currentUser = SecurityUtils.getSubject(); -</pre> -</div></div> - -<p>Using <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html">SecurityUtils</a>.<a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html#getSubject()">getSubject()</a></tt>, we can obtain the currently executing <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html">Subject</a></tt>. <em>Subject</em> is a security term that basically means "a security-specific view of the currently executing user". It is not called a 'User' because the word 'User' is usually associated with a human being. In the security world, the term 'Subject' can mean a human being, but also a 3rd party process, cron job, daemon account, or anything similar. It simply means 'the thing that is currently interacting with the software'. For most intents and purposes though, you can think of the <tt>Subject</tt> as Shiro’s ‘User’ concept.</p> - -<p>The <tt>getSubject()</tt> call in a standalone application might return a <tt>Subject</tt> based on user data in an application-specific location, and in a server environment (e.g. web app), it acquires the <tt>Subject</tt> based on user data associated with current thread or incoming request.</p> - -<p>Now that you have a <tt>Subject</tt>, what can you do with it?</p> - -<p>If you want to make things available to the user during their current session with the application, you can get their session:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Session session = currentUser.getSession(); -session.setAttribute( <span class="code-quote">"someKey"</span>, <span class="code-quote">"aValue"</span> ); -</pre> -</div></div> - -<p>The <tt>Session</tt> is a Shiro-specific instance that provides most of what you're used to with regular HttpSessions but with some extra goodies and one <b>big</b> difference: it does not require an HTTP environment!</p> - -<p>If deploying inside a web application, by default the <tt>Session</tt> will be <tt>HttpSession</tt> based. But, in a non-web environment, like this simple tutorial application, Shiro will automatically use its Enterprise Session Management by default. This means you get to use the same API in your applications, in any tier, regardless of deployment environment! This opens a whole new world of applications since any application requiring sessions does not need to be forced to use the <tt>HttpSession</tt> or EJB Stateful Session Beans. And, any client technology can now share session data.</p> - -<p>So now you can acquire a <tt>Subject</tt> and their <tt>Session</tt>. What about the <em>really</em> useful stuff like checking if they are allowed to do things, like checking against roles and permissions?</p> - -<p>Well, we can only do those checks for a known user. Our <tt>Subject</tt> instance above represents the current user, but <em>who</em> is the current user? Well, they're anonymous - that is, until they log in at least once. So, let's do that:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( !currentUser.isAuthenticated() ) { - <span class="code-comment">//collect user principals and credentials in a gui specific manner -</span> <span class="code-comment">//such as username/password html form, X509 certificate, OpenID, etc. -</span> <span class="code-comment">//We'll use the username/password example here since it is the most common. -</span> UsernamePasswordToken token = <span class="code-keyword">new</span> UsernamePasswordToken(<span class="code-quote">"lonestarr"</span>, <span class="code-quote">"vespa"</span>); - - <span class="code-comment">//<span class="code-keyword">this</span> is all you have to <span class="code-keyword">do</span> to support 'remember me' (no config - built in!): -</span> token.setRememberMe(<span class="code-keyword">true</span>); - - currentUser.login(token); -} -</pre> -</div></div> - -<p>That's it! It couldn't be easier.</p> - -<p>But what if their login attempt fails? You can catch all sorts of specific exceptions that tell you exactly what happened and allows you to handle and react accordingly:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">try</span> { - currentUser.login( token ); - <span class="code-comment">//<span class="code-keyword">if</span> no exception, that's it, we're done! -</span>} <span class="code-keyword">catch</span> ( UnknownAccountException uae ) { - <span class="code-comment">//username wasn't in the system, show them an error message? -</span>} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice ) { - <span class="code-comment">//password didn't match, <span class="code-keyword">try</span> again? -</span>} <span class="code-keyword">catch</span> ( LockedAccountException lae ) { - <span class="code-comment">//account <span class="code-keyword">for</span> that username is locked - can't login. Show them a message? -</span>} - ... more types exceptions to check <span class="code-keyword">if</span> you want ... -} <span class="code-keyword">catch</span> ( AuthenticationException ae ) { - <span class="code-comment">//unexpected condition - error? -</span>} -</pre> -</div></div> - -<p>There are many different types of exceptions you can check, or throw your own for custom conditions Shiro might not account for. See the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException JavaDoc</a> for more. </p> - -#tip('Handy Hint', 'Security best practice is to give generic login failure messages to users because you do not want to aid an attacker trying to break into your system.') - -<p>Ok, so by now, we have a logged in user. What else can we do?</p> - -<p>Let's say who they are:</p> - -<p></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//print their identifying principal (in <span class="code-keyword">this</span> <span class="code-keyword">case</span>, a username): -</span>log.info( <span class="code-quote">"User ["</span> + currentUser.getPrincipal() + <span class="code-quote">"] logged in successfully."</span> ); -</pre> -</div></div> - -<p>We can also test to see if they have specific role or not:</p> - -<p></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.hasRole( <span class="code-quote">"schwartz"</span> ) ) { - log.info(<span class="code-quote">"May the Schwartz be with you!"</span> ); -} <span class="code-keyword">else</span> { - log.info( <span class="code-quote">"Hello, mere mortal."</span> ); -} -</pre> -</div></div> - -<p>We can also see if they have a permission to act on a certain type of entity:</p> - -<p></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"lightsaber:weild"</span> ) ) { - log.info(<span class="code-quote">"You may use a lightsaber ring. Use it wisely."</span>); -} <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, lightsaber rings are <span class="code-keyword">for</span> schwartz masters only."</span>); -} -</pre> -</div></div> - -<p>Also, we can perform an extremely powerful <em>instance-level</em> permission check - the ability to see if the user has the ability to access a specific instance of a type:</p> - -<p></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">if</span> ( currentUser.isPermitted( <span class="code-quote">"winnebago:drive:eagle5"</span> ) ) { - log.info(<span class="code-quote">"You are permitted to 'drive' the 'winnebago' with license plate (id) 'eagle5'. "</span> + - <span class="code-quote">"Here are the keys - have fun!"</span>); -} <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, you aren't allowed to drive the 'eagle5' winnebago!"</span>); -} -</pre> -</div></div> - -<p>Piece of cake, right?</p> - -<p>Finally, when the user is done using the application, they can log out:</p> - -<p></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -currentUser.logout(); <span class="code-comment">//removes all identifying information and invalidates their session too.</span> -</pre> -</div></div> - -<h4><a name="Tutorial-FinalTutorialclass"></a>Final Tutorial class</h4> - -<p>After adding in the above code examples, here is our final Tutorial class file. Feel free to edit and play with it and change the security checks (and the INI configuration) as you like:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Final src/main/java/Tutorial.java</b></div><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">import</span> org.apache.shiro.SecurityUtils; -<span class="code-keyword">import</span> org.apache.shiro.authc.*; -<span class="code-keyword">import</span> org.apache.shiro.config.IniSecurityManagerFactory; -<span class="code-keyword">import</span> org.apache.shiro.mgt.<span class="code-object">SecurityManager</span>; -<span class="code-keyword">import</span> org.apache.shiro.session.Session; -<span class="code-keyword">import</span> org.apache.shiro.subject.Subject; -<span class="code-keyword">import</span> org.apache.shiro.util.Factory; -<span class="code-keyword">import</span> org.slf4j.Logger; -<span class="code-keyword">import</span> org.slf4j.LoggerFactory; - -<span class="code-keyword">public</span> class Tutorial { - - <span class="code-keyword">private</span> <span class="code-keyword">static</span> <span class="code-keyword">final</span> <span class="code-keyword">transient</span> Logger log = LoggerFactory.getLogger(Tutorial.class); - - - <span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) { - log.info(<span class="code-quote">"My First Apache Shiro Application"</span>); - - Factory<<span class="code-object">SecurityManager</span>> factory = <span class="code-keyword">new</span> IniSecurityManagerFactory(<span class="code-quote">"classpath:shiro.ini"</span>); - <span class="code-object">SecurityManager</span> securityManager = factory.getInstance(); - SecurityUtils.setSecurityManager(securityManager); - - - <span class="code-comment">// get the currently executing user: -</span> Subject currentUser = SecurityUtils.getSubject(); - - <span class="code-comment">// Do some stuff with a Session (no need <span class="code-keyword">for</span> a web or EJB container!!!) -</span> Session session = currentUser.getSession(); - session.setAttribute(<span class="code-quote">"someKey"</span>, <span class="code-quote">"aValue"</span>); - <span class="code-object">String</span> value = (<span class="code-object">String</span>) session.getAttribute(<span class="code-quote">"someKey"</span>); - <span class="code-keyword">if</span> (value.equals(<span class="code-quote">"aValue"</span>)) { - log.info(<span class="code-quote">"Retrieved the correct value! ["</span> + value + <span class="code-quote">"]"</span>); - } - - <span class="code-comment">// let's login the current user so we can check against roles and permissions: -</span> <span class="code-keyword">if</span> (!currentUser.isAuthenticated()) { - UsernamePasswordToken token = <span class="code-keyword">new</span> UsernamePasswordToken(<span class="code-quote">"lonestarr"</span>, <span class="code-quote">"vespa"</span>); - token.setRememberMe(<span class="code-keyword">true</span>); - <span class="code-keyword">try</span> { - currentUser.login(token); - } <span class="code-keyword">catch</span> (UnknownAccountException uae) { - log.info(<span class="code-quote">"There is no user with username of "</span> + token.getPrincipal()); - } <span class="code-keyword">catch</span> (IncorrectCredentialsException ice) { - log.info(<span class="code-quote">"Password <span class="code-keyword">for</span> account "</span> + token.getPrincipal() + <span class="code-quote">" was incorrect!"</span>); - } <span class="code-keyword">catch</span> (LockedAccountException lae) { - log.info(<span class="code-quote">"The account <span class="code-keyword">for</span> username "</span> + token.getPrincipal() + <span class="code-quote">" is locked. "</span> + - <span class="code-quote">"Please contact your administrator to unlock it."</span>); - } - <span class="code-comment">// ... <span class="code-keyword">catch</span> more exceptions here (maybe custom ones specific to your application? -</span> <span class="code-keyword">catch</span> (AuthenticationException ae) { - <span class="code-comment">//unexpected condition? error? -</span> } - } - - <span class="code-comment">//say who they are: -</span> <span class="code-comment">//print their identifying principal (in <span class="code-keyword">this</span> <span class="code-keyword">case</span>, a username): -</span> log.info(<span class="code-quote">"User ["</span> + currentUser.getPrincipal() + <span class="code-quote">"] logged in successfully."</span>); - - <span class="code-comment">//test a role: -</span> <span class="code-keyword">if</span> (currentUser.hasRole(<span class="code-quote">"schwartz"</span>)) { - log.info(<span class="code-quote">"May the Schwartz be with you!"</span>); - } <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Hello, mere mortal."</span>); - } - - <span class="code-comment">//test a typed permission (not instance-level) -</span> <span class="code-keyword">if</span> (currentUser.isPermitted(<span class="code-quote">"lightsaber:weild"</span>)) { - log.info(<span class="code-quote">"You may use a lightsaber ring. Use it wisely."</span>); - } <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, lightsaber rings are <span class="code-keyword">for</span> schwartz masters only."</span>); - } - - <span class="code-comment">//a (very powerful) Instance Level permission: -</span> <span class="code-keyword">if</span> (currentUser.isPermitted(<span class="code-quote">"winnebago:drive:eagle5"</span>)) { - log.info(<span class="code-quote">"You are permitted to 'drive' the winnebago with license plate (id) 'eagle5'. "</span> + - <span class="code-quote">"Here are the keys - have fun!"</span>); - } <span class="code-keyword">else</span> { - log.info(<span class="code-quote">"Sorry, you aren't allowed to drive the 'eagle5' winnebago!"</span>); - } - - <span class="code-comment">//all done - log out! -</span> currentUser.logout(); - - <span class="code-object">System</span>.exit(0); - } -} -</pre> -</div></div> - -<h3><a name="Tutorial-Summary"></a>Summary</h3> - -<p>Hopefully this introduction tutorial helped you understand how to set-up Shiro in a basic application as well Shiro's primary design concepts, the <tt>Subject</tt> and <tt>SecurityManager</tt>.</p> - -<p>But this was a fairly simple application. You might have asked yourself, "What if I don't want to use INI user accounts and instead want to connect to a more complex user data source?"</p> - -<p>To answer that question requires a little deeper understanding of Shiro's architecture and supporting configuration mechanisms. We'll cover Shiro's <a href="architecture.html" title="Architecture">Architecture</a> next.</p>
