You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by bd...@apache.org on 2016/07/01 16:28:25 UTC
svn commit: r1750979 - in /shiro/site/publish: 10-minute-tutorial.html
webapp-tutorial.html
Author: bdemers
Date: Fri Jul 1 16:28:25 2016
New Revision: 1750979
URL: http://svn.apache.org/viewvc?rev=1750979&view=rev
Log:
publishing site with changes from SHIRO-527
Modified:
shiro/site/publish/10-minute-tutorial.html
shiro/site/publish/webapp-tutorial.html
Modified: shiro/site/publish/10-minute-tutorial.html
URL: http://svn.apache.org/viewvc/shiro/site/publish/10-minute-tutorial.html?rev=1750979&r1=1750978&r2=1750979&view=diff
==============================================================================
--- shiro/site/publish/10-minute-tutorial.html (original)
+++ shiro/site/publish/10-minute-tutorial.html Fri Jul 1 16:28:25 2016
@@ -111,7 +111,7 @@
<p>What can Apache Shiro do?</p>
-<p>A lot <img align="middle" class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/smile.gif"
+<p>A lot <img align="middle" class="emoticon" src="https://cwiki.apache.org/confluence/images/icons/emoticons/smile.png"
height="20" width="20" alt="" border="0">. But we don't want to bloat the QuickStart. Please check out our
<a href="features.html" title="Features">Features</a> page if you'd like to see what it can do for you. Also, if
you're curious on how we got started and why we exist, please see the <a href="what-is-shiro.html"
@@ -128,7 +128,7 @@
</colgroup>
<tr>
<td colspan="1" rowspan="1" valign="top"><img align="middle"
- src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"
+ src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.png"
width="16" height="16" alt="" border="0"></td>
<td colspan="1" rowspan="1">Shiro can be run in any environment, from the simplest command line application
to the biggest enterprise web and clustered applications, but we'll use the simplest possible example in
@@ -300,7 +300,7 @@ session.setAttribute( <span class="code-
</colgroup>
<tr>
<td colspan="1" rowspan="1" valign="top"><img align="middle"
- src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"
+ src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.png"
width="16" height="16" alt="" border="0"></td>
<td colspan="1" rowspan="1"><b>Handy Hint</b><br clear="none">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
Modified: shiro/site/publish/webapp-tutorial.html
URL: http://svn.apache.org/viewvc/shiro/site/publish/webapp-tutorial.html?rev=1750979&r1=1750978&r2=1750979&view=diff
==============================================================================
--- shiro/site/publish/webapp-tutorial.html (original)
+++ shiro/site/publish/webapp-tutorial.html Fri Jul 1 16:28:25 2016
@@ -97,7 +97,7 @@
<li>Java SDK 7</li>
<li>Maven 3</li>
<li>Your favorite IDE, like IntelliJ IDEA or Eclipse, or even a simple text editor to view files and make changes.</li>
-</ul><h3>Tutorial Format</h3><p>This is a step-by-step tutorial. The tutorial, and all of its steps, exist as a Git repository. When you clone the git repository, the <code>master</code> branch is your starting point. Each step in the tutorial is a separate branch. You can follow along simply by checking out the git branch that reflects the tutorial step you are reviewing.</p><h3>The Application</h3><p>The web application we will build is a super webapp that can be used as a starting point for your own application. It will demonstrate user login, logout, user-specific welcome messages, access control to certain parts of the web application, and integration with a plugglable security data store.</p><p>We will start by setting up the project, including the build tool and declaring dependencies, as well as configuring the servlet <code>web.xml</code> file to launch the web application and the Shiro environment.</p><p>Once we complete setup, we will then layer in individual pieces of fu
nctionality, including integration with a security data store, then enabling user login, logout, and access control.</p><p><a id="project-setup"></a></p><h2>Project Setup</h2><p>Instead of having to manually set up a directory structure and initial set of basic files, we’ve done this for you in a git repository.</p><h3>1. Fork the tutorial project</h3><p>On GitHub, visit the <a href="https://github.com/lhazlewood/apache-shiro-tutorial-webapp">tutorial project</a> and click the <code>Fork</code> button on the upper right.</p><h3>2. Clone your tutorial repository</h3><p>Now that you have forked the repository to your own GitHub account, clone it on your local machine:</p>
+</ul><h3>Tutorial Format</h3><p>This is a step-by-step tutorial. The tutorial, and all of its steps, exist as a Git repository. When you clone the git repository, the <code>master</code> branch is your starting point. Each step in the tutorial is a separate branch. You can follow along simply by checking out the git branch that reflects the tutorial step you are reviewing.</p><h3>The Application</h3><p>The web application we will build is a super webapp that can be used as a starting point for your own application. It will demonstrate user login, logout, user-specific welcome messages, access control to certain parts of the web application, and integration with a pluggable security data store.</p><p>We will start by setting up the project, including the build tool and declaring dependencies, as well as configuring the servlet <code>web.xml</code> file to launch the web application and the Shiro environment.</p><p>Once we complete setup, we will then layer in individual pieces of fun
ctionality, including integration with a security data store, then enabling user login, logout, and access control.</p><p><a id="project-setup"></a></p><h2>Project Setup</h2><p>Instead of having to manually set up a directory structure and initial set of basic files, we’ve done this for you in a git repository.</p><h3>1. Fork the tutorial project</h3><p>On GitHub, visit the <a href="https://github.com/lhazlewood/apache-shiro-tutorial-webapp">tutorial project</a> and click the <code>Fork</code> button on the upper right.</p><h3>2. Clone your tutorial repository</h3><p>Now that you have forked the repository to your own GitHub account, clone it on your local machine:</p>
<pre><code>$ git clone git@github.com:$YOUR_GITHUB_USERNAME/apache-shiro-tutorial-webapp.git
</code></pre><p>(where <code>$YOUR_GITHUB_USERNAME</code> is your own GitHub username of course)</p><p>You can now <code>cd</code> into the cloned directory and see the project structure:</p>
<pre><code>$ cd apache-shiro-tutorial-webapp
@@ -152,7 +152,7 @@ securityManager.cacheManager = $cacheMan
<ul>
<li>It defines a new <code>cacheManager</code> instance. Caching is an important part of Shiro’s architecture - it reduces constant round-trip communications to various data stores. This example uses a <code>MemoryConstrainedCacheManager</code> which is only really good for single JVM applications. If your application is deployed across multiple hosts (e.g. a clustered webserver farm), you will want to use a clustered CacheManager implementation instead.</li>
<li>It configures the new <code>cacheManager</code> instance on the Shiro <code>securityManager</code>. A Shiro <a href="http://shiro.apache.org/architecture.html"><code>SecurityManager</code></a> instance always exists, so it did not need to be defined explicitly.</li>
-</ul><h3>1b: Enable Shiro in <code>web.xml</code></h3><p>While we have a <code>shiro.ini</code> configuration, we need to actually <em>load</em> it and start a new Shiro environment and make that environment avaiable to the web application.</p><p>We do all of this by adding a few things to the existing <code>src/main/webapp/WEB-INF/web.xml</code> file:</p>
+</ul><h3>1b: Enable Shiro in <code>web.xml</code></h3><p>While we have a <code>shiro.ini</code> configuration, we need to actually <em>load</em> it and start a new Shiro environment and make that environment available to the web application.</p><p>We do all of this by adding a few things to the existing <code>src/main/webapp/WEB-INF/web.xml</code> file:</p>
<pre><code><listener>
<listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
</listener>
@@ -298,7 +298,7 @@ shiro.loginUrl = /login.jsp
/logout = logout
</code></pre><h4><code>shiro.*</code> lines</h4><p>At the top of the <code>[main]</code> section, there is a new line:</p>
<pre><code>shiro.loginUrl = /login.jsp
-</code></pre><p>This is a special configuration directive that tells Shiro “For any of Shiro’s <a href="http://shiro.apache.org/web.html#Web-DefaultFilters">default filters</a> that have a <code>loginUrl</code> property, I want that property value to be set to <code>/login.jsp</code>.”</p><p>This allows Shiro’s default <code>authc</code> filter (by default, a <a href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html"><code>FormAuthenticationFilter</code></a>) to know about the login page. This is necessary for the <code>FormAuthenticationFilter</code> to work correctly.</p><h4>The <code>[urls]</code> section</h4><p>The <code>[urls]</code> section is a new <a href="http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D">web-specific INI section</a>.</p><p>This section allows you to use a very succinct name/value pair syntax to tell shiro how to filter request for any given URL path. All paths i
n <code>[urls]</code> are relative to the web application’s [HttpServletRequest.getContextPath()](<a href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/http/HttpServletRequest.html#getContextPath()">http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/http/HttpServletRequest.html#getContextPath()</a>) value.</p><p>These name/value pairs offer an extremely powerful way to filter requests, allowing for all sorts of security rules. A deeper coverage of urls and filter chains is outside the scope of this document, but please do <a href="http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D">read more about it</a> if you’re interested.</p><p>For now, we’ll cover the two lines that were added:</p>
+</code></pre><p>This is a special configuration directive that tells Shiro “For any of Shiro’s <a href="http://shiro.apache.org/web.html#Web-DefaultFilters">default filters</a> that have a <code>loginUrl</code> property, I want that property value to be set to <code>/login.jsp</code>.”</p><p>This allows Shiro’s default <code>authc</code> filter (by default, a <a href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html"><code>FormAuthenticationFilter</code></a>) to know about the login page. This is necessary for the <code>FormAuthenticationFilter</code> to work correctly.</p><h4>The <code>[urls]</code> section</h4><p>The <code>[urls]</code> section is a new <a href="http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D">web-specific INI section</a>.</p><p>This section allows you to use a very succinct name/value pair syntax to tell shiro how to filter request for any given URL path. All paths i
n <code>[urls]</code> are relative to the web application’s [<code>HttpServletRequest.getContextPath()</code>](<a href="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/http/HttpServletRequest.html#getContextPath()">http://java.sun.com/j2ee/sdk_1.3/techdocs/api/javax/servlet/http/HttpServletRequest.html#getContextPath()</a>) value.</p><p>These name/value pairs offer an extremely powerful way to filter requests, allowing for all sorts of security rules. A deeper coverage of urls and filter chains is outside the scope of this document, but please do <a href="http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D">read more about it</a> if you’re interested.</p><p>For now, we’ll cover the two lines that were added:</p>
<pre><code>/login.jsp = authc
/logout = logout
</code></pre>
@@ -311,7 +311,7 @@ shiro.loginUrl = /login.jsp
<li>There is a <code>username</code> form field. The Shiro <code>authc</code> filter will automatically look for a <code>username</code> request parameter during login submission and use that as the value during login (many Realms allow this to be an email or a username).</li>
<li>There is a <code>password</code> form field. The Shiro <code>authc</code> filter will automatically look for a <code>password</code> request parameter during login submission.</li>
<li>There is a <code>rememberMe</code> checkbox whose ‘checked’ state can be a ‘truthy’ value (<code>true</code>, <code>t</code>, <code>1</code>, <code>enabled</code>, <code>y</code>, <code>yes</code>, or <code>on</code>).</li>
-</ol><p>Our login.jsp form just uses the default <code>username</code>, <code>password</code>, and <code>rememberMe</code> form field names. They naems are configurable if you wish to change them - see the <a href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html"><code>FormAuthenticationFilter</code> JavaDoc</a> for information.</p><h3>Step 3c: Run the webapp</h3><p>After making the changes as specified in Step 2b and 2c, go ahead and run the web app:</p>
+</ol><p>Our login.jsp form just uses the default <code>username</code>, <code>password</code>, and <code>rememberMe</code> form field names. These names are configurable if you wish to change them - see the <a href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/filter/authc/FormAuthenticationFilter.html"><code>FormAuthenticationFilter</code> JavaDoc</a> for information.</p><h3>Step 3c: Run the webapp</h3><p>After making the changes as specified in Step 2b and 2c, go ahead and run the web app:</p>
<pre><code>$ mvn jetty:run
</code></pre><h3>Step 3d: Try to Login</h3><p>With your web browser, navigate to <a href="http://localhost:8080/login.jsp">localhost:8080/login.jsp</a> and you will see our new shiny login form.</p><p>Enter in a username and password of the account you created at the end of Step 2, and hit ‘Login’. If the login is successful, you will be directed to the home page! If the login fails, you will be shown the login page again.</p><p>Tip: If you want a successful login to redirect the user to a different page other than the home page (context path <code>/</code>), you can set the <code>authc.successUrl = /whatever</code> in the INI’s <code>[main]</code> section.</p><p>Hit <code>ctl-C</code> (or <code>cmd-C</code> on a mac) to shut down the web app.</p><p><a id="step4"></a></p><h2>Step 4: User-specific UI changes</h2><p>It’s usually a requirement to change a web user interface based on who the user is. We can do that easily because Shiro supports a JSP tag library
to do things based on the currently logged-in Subject (user).</p><p>Perform the following git checkout command to load the <code>step4</code> branch:</p>
<pre><code>$ git checkout step4
@@ -351,7 +351,7 @@ shiro.loginUrl = /login.jsp
</code></pre><p>Step 5 introduces the following 3 changes:</p>
<ol>
<li>We added a new section (url path) of the webapp that we want to restrict to only authenticated users.</li>
- <li>We changed <code>shiro.ini</code> to tell shiro to only allow authenticated users to that part of the web app.</li>
+ <li>We changed <code>shiro.ini</code> to tell Shiro to only allow authenticated users to that part of the web app.</li>
<li>We modified the home page to change its output based on if the current <code>Subject</code> is authenticated or not.</li>
</ol><h3>Step 5a: Add a new restricted section</h3><p>A new <code>src/main/webapp/account</code> directory was added. This directory (and all paths below it) simulates a ‘private’ or ‘authenticated only’ section of a website that you might want to restrict to only logged in users. The <code>src/main/webapp/account/index.jsp</code> file is just a placeholder for a simulated ‘home account’ page.</p><h3>Step 5b: Configure <code>shiro.ini</code></h3><p><code>shiro.ini</code> was modified by adding the following line at the end of the <code>[urls]</code> section:</p>
<pre><code>/account/** = authc