shiro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bdem...@apache.org
Subject svn commit: r1750979 - in /shiro/site/publish: 10-minute-tutorial.html webapp-tutorial.html
Date Fri, 01 Jul 2016 16:28:25 GMT
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&rsquo;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&rsquo;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&rsquo;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>&lt;listener&gt;
     &lt;listener-class&gt;org.apache.shiro.web.env.EnvironmentLoaderListener&lt;/listener-class&gt;
 &lt;/listener&gt;
@@ -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
&ldquo;For any of Shiro&rsquo;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>.&rdquo;</p><p>This
allows Shiro&rsquo;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&rsquo;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&rsquo;re interested.</p><p>For now, we&rsquo;ll
cover the two lines that were added:</p>
+</code></pre><p>This is a special configuration directive that tells Shiro
&ldquo;For any of Shiro&rsquo;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>.&rdquo;</p><p>This
allows Shiro&rsquo;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&rsquo;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&rsquo;re interested.</p><p>For now, we&rsquo;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 &lsquo;checked&rsquo;
state can be a &lsquo;truthy&rsquo; 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 &lsquo;Login&rsquo;. 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&rsquo;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&rsquo;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 &lsquo;private&rsquo;
or &lsquo;authenticated only&rsquo; 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 &lsquo;home account&rsquo; 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



Mime
View raw message