http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/developer-resources.html.vtl ---------------------------------------------------------------------- diff --git a/developer-resources.html.vtl b/developer-resources.html.vtl new file mode 100644 index 0000000..72971dd --- /dev/null +++ b/developer-resources.html.vtl @@ -0,0 +1,34 @@ +<h1><a name="DeveloperResources-ApacheShiroDeveloperResources"></a>Apache Shiro Developer Resources</h1> + +<p>This page and its children are dedicated for reference information used by the Apache Shiro development team when performing tasks as a committer or contributor</p> + +<h2><a name="DeveloperResources-WritingDocumentation"></a>Writing Documentation</h2> + +<p>All non-JavaDoc documentation is written in our <a class="external-link" href="http://cwiki.apache.org/confluence/display/SHIRO/";>Apache Shiro Confluence Wiki Space</a>. This space is converted into the public website by the <a href="confluence-auto-export.html" title="Confluence Auto Export">Confluence Auto Export Process</a>.</p> + +<h2><a name="DeveloperResources-SourceCodeRepository"></a>Source Code Repository</h2> + +<p>We use a Git repository located at <a class="external-link" href="git://git.apache.org/shiro.git">git://git.apache.org/shiro.git</a>.</p> + +<p>Active development is done in the <tt>master</tt> branch, and maintenance typically on the <tt>1.2.x</tt> branch.</p> + +<h3><a name="DeveloperResources-BuildingfromGit"></a>Building from Git</h3> + +<p>For Shiro cutting-edge development, you can clone the code from Git and build it using <a class="external-link" href="http://maven.apache.org";>Maven</a> 2.2+:</p> + +<ol><li>Check out the code: +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +git clone https:<span class="code-comment">//github.com/apache/shiro.git</span> +</pre> +</div></div></li><li>Build the project using <a class="external-link" href="http://maven.apache.org";>Maven</a> 2.2+: +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +cd shiro +mvn install +</pre> +</div></div> +<p>The resulting artifacts will be in your local M2 Repo under the org.apache.shiro group.</p></li></ol> + + +#danger('Cutting-edge development', 'When building from <tt>master</tt> or any branches, use the generated artifacts at your own risk! Current and previous stable releases will always be available via the <a href="download.html" title="Download">Download</a> page.') \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/guice.html ---------------------------------------------------------------------- diff --git a/guice.html b/guice.html deleted file mode 100644 index 2fcdf6d..0000000 --- a/guice.html +++ /dev/null @@ -1,184 +0,0 @@ -<h1><a name="Guice-IntegratingApacheShirointoGuicebasedApplication"></a>Integrating Apache Shiro into Guice based Application</h1> - -<p>Shiro <a class="external-link" href="http://code.google.com/p/google-guice/"; rel="nofollow">Guice</a> integration was added in Shiro 1.2. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be a least somewhat familiar with Guice.</p> - -<h2><a name="Guice-Overview"></a>Overview</h2> - -<p>shiro-guice provides three Guice modules that can be included in your application.</p> - -<ul><li>ShiroModule - <ul><li>Provides basic integration for setting up the <tt>SecurityManager</tt>, any <tt>Realms</tt>, and any other Shiro configuration.</li><li>This module is used by extending it and adding your own custom configuration.</li></ul> - </li></ul> - - -<ul><li>ShiroWebModule - <ul><li>Extension of <tt>ShiroModule</tt> that sets up the web environment and also allows for filter chain configuration. This uses the <a class="external-link" href="http://code.google.com/p/google-guice/wiki/ServletModule"; rel="nofollow">Guice Servlet Module</a> to configure the filters, and so requires that to be setup.</li><li>Like the <tt>ShiroModule</tt>, this module is used by extending it and adding your own custom configuration.</li></ul> - </li></ul> - - -<ul><li>ShiroAopModule - <ul><li>Uses <a class="external-link" href="http://code.google.com/p/google-guice/wiki/AOP"; rel="nofollow">Guice AOP</a> to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro <tt>AnnotationMethodInterceptors</tt> to the Guice method interceptor model.</li><li>This module is typically used by simply installing it. However, if you have your own <tt>AnnotationMethodInterceptors</tt> written for Shiro, they can be easily incorporated by extending it.</li></ul> - </li></ul> - - -<h2><a name="Guice-GettingStarted"></a>Getting Started</h2> - -<p>The most simple configuration is to extend <tt>ShiroModule</tt> to install your own <tt>Realm</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroModule <span class="code-keyword">extends</span> ShiroModule { - <span class="code-keyword">protected</span> void configureShiro() { - <span class="code-keyword">try</span> { - bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); - } <span class="code-keyword">catch</span> (NoSuchMethodException e) { - addError(e); - } - } - - @Provides - Ini loadShiroIni() { - <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); - } - } -</pre> -</div></div> - -<p>In this case, user and role configuration would go in the <tt>shiro.ini</tt> file.</p> - -<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>shiro.ini usage in Guice</b><br clear="none">It is important to note that, in this above configuration, only the <tt>users</tt> and <tt>roles</tt> sections from the ini file are used.</td></tr></table></div> - -<p>Then, the module is used to create a Guice injector, and the injector is used to obtain a <tt>SecurityManager</tt>. The following example serves the same purpose as the first three lines in the <a class="external-link" href="10-minute-tutorial.html#10MinuteTutorial-Quickstart.java">Quickstart</a> example.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule()); - <span class="code-object">SecurityManager</span> securityManager = injector.getInstance(<span class="code-object">SecurityManager</span>.class); - SecurityUtils.setSecurityManager(securityManager); -</pre> -</div></div> - -<h2><a name="Guice-AOP"></a>AOP</h2> - -<p>Shiro includes several annotations and method interceptors useful for performing authorization via AOP. It also provides a simple API for writing Shiro-specific method interceptors. shiro-guice supports this with the <tt>ShiroAopModule</tt>.</p> - -<p>To use it, simply instantiate and install the module alongside your application module and your <tt>ShiroModule</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule(), <span class="code-keyword">new</span> ShiroAopModule(), <span class="code-keyword">new</span> MyApplicationModule()); -</pre> -</div></div> - -<p>If you have written custom interceptors that conform to Shiro's api, you may find it useful to extend the <tt>ShiroAopModule</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroAopModule <span class="code-keyword">extends</span> ShiroAopModule { - <span class="code-keyword">protected</span> void configureInterceptors(AnnotationResolver resolver) - { - bindShiroInterceptor(<span class="code-keyword">new</span> MyCustomAnnotationMethodInterceptor(resolver)); - } - } -</pre> -</div></div> - -<h2><a name="Guice-Web"></a>Web</h2> - -<p>shiro-guice's web integration is designed to integrate Shiro and its filter paradigm with Guice's servlet module. If you are using Shiro in a web environment, and using Guice's servlet module, then you should extend ShiroWebModule rather than ShiroModule. Your web.xml should be setup exactly as Guice's servlet module recommends.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - class MyShiroWebModule <span class="code-keyword">extends</span> ShiroWebModule { - MyShiroWebModule(ServletContext sc) { - <span class="code-keyword">super</span>(sc); - } - - <span class="code-keyword">protected</span> void configureShiroWeb() { - <span class="code-keyword">try</span> { - bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); - } <span class="code-keyword">catch</span> (NoSuchMethodException e) { - addError(e); - } - - addFilterChain(<span class="code-quote">"/<span class="code-keyword">public</span>/**"</span>, ANON); - addFilterChain(<span class="code-quote">"/stuff/allowed/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"yes"</span>)); - addFilterChain(<span class="code-quote">"/stuff/forbidden/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"no"</span>)); - addFilterChain(<span class="code-quote">"/**"</span>, AUTHC_BASIC); - } - - @Provides - Ini loadShiroIni() { - <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); - } - } -</pre> -</div></div> - -<p>In the previous code, we have bound an <tt>IniRealm</tt> and setup four filter chains. These chains would be equivalent to the following ini configuration. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - [urls] - /<span class="code-keyword">public</span>/** = anon - /stuff/allowed/** = authcBasic, perms[<span class="code-quote">"yes"</span>] - /stuff/forbidden/** = authcBasic, perms[<span class="code-quote">"no"</span>] - /** = authcBasic -</pre> -</div></div> - -<p>In shiro-guice, the filter names are Guice keys. All of the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - Key customFilter = Key.get(MyCustomFilter.class); - - addFilterChain(<span class="code-quote">"/custom/**"</span>, customFilter); -</pre> -</div></div> - -<p>We still have to tell guice-servlets about our Shiro filter. Since the <tt>ShiroWebModule</tt> is private, and guice-servlets does not give us a way to expose a filter mapping, we have to bind it manually. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - ShiroWebModule.guiceFilterModule() -</pre> -</div></div> - -<p>Or, from within an application module, </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - ShiroWebModule.bindGuiceFilter(binder()) -</pre> -</div></div> - -<h2><a name="Guice-Properties"></a>Properties</h2> - -<p>A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for <tt>@Named("shiro.{propName}")</tt>. For instance, to set the session timeout, you could do the following. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.globalSessionTimeout"</span>)).to(30000L); -</pre> -</div></div> - -<p>If this paradigm doesn't work for you, you may also consider using a provider to instantiate the object and invoking the setters directly.</p> - -<h2><a name="Guice-InjectionofShiroObjects"></a>Injection of Shiro Objects</h2> - -<p>shiro-guice uses a Guice <tt>TypeListener</tt> to perform injection on native Shiro classes (any class in a subdirectory of <tt>org.apache.shiro</tt> but not <tt>org.apache.shiro.guice</tt>). However, Guice only considers explicitly bound types as candidates for <tt>TypeListeners</tt>, so if you have a Shiro object that you want injected, you have to declare it explicitly. For instance, to set the <tt>CredentialsMatcher</tt> for a realm, we would need to add the following bindings:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - bind(CredentialsMatcher.class).to(HashedCredentialsMatcher.class); - bind(HashedCredentialsMatcher.class); - bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.hashAlgorithmName"</span>)).to(Md5Hash.ALGORITHM_NAME); -</pre> -</div></div> - -<h2><a name="Guice-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> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/guice.html.vtl ---------------------------------------------------------------------- diff --git a/guice.html.vtl b/guice.html.vtl new file mode 100644 index 0000000..b8fae6b --- /dev/null +++ b/guice.html.vtl @@ -0,0 +1,184 @@ +<h1><a name="Guice-IntegratingApacheShirointoGuicebasedApplication"></a>Integrating Apache Shiro into Guice based Application</h1> + +<p>Shiro <a class="external-link" href="http://code.google.com/p/google-guice/"; rel="nofollow">Guice</a> integration was added in Shiro 1.2. This page covers the ways to integrate Shiro into Guice-based applications using standard Guice conventions and mechanisms. Prior to reading this integration document, you should be a least somewhat familiar with Guice.</p> + +<h2><a name="Guice-Overview"></a>Overview</h2> + +<p>shiro-guice provides three Guice modules that can be included in your application.</p> + +<ul><li>ShiroModule + <ul><li>Provides basic integration for setting up the <tt>SecurityManager</tt>, any <tt>Realms</tt>, and any other Shiro configuration.</li><li>This module is used by extending it and adding your own custom configuration.</li></ul> + </li></ul> + + +<ul><li>ShiroWebModule + <ul><li>Extension of <tt>ShiroModule</tt> that sets up the web environment and also allows for filter chain configuration. This uses the <a class="external-link" href="http://code.google.com/p/google-guice/wiki/ServletModule"; rel="nofollow">Guice Servlet Module</a> to configure the filters, and so requires that to be setup.</li><li>Like the <tt>ShiroModule</tt>, this module is used by extending it and adding your own custom configuration.</li></ul> + </li></ul> + + +<ul><li>ShiroAopModule + <ul><li>Uses <a class="external-link" href="http://code.google.com/p/google-guice/wiki/AOP"; rel="nofollow">Guice AOP</a> to implement the Shiro AOP annotations. This module is primarily concerned with adapting Shiro <tt>AnnotationMethodInterceptors</tt> to the Guice method interceptor model.</li><li>This module is typically used by simply installing it. However, if you have your own <tt>AnnotationMethodInterceptors</tt> written for Shiro, they can be easily incorporated by extending it.</li></ul> + </li></ul> + + +<h2><a name="Guice-GettingStarted"></a>Getting Started</h2> + +<p>The most simple configuration is to extend <tt>ShiroModule</tt> to install your own <tt>Realm</tt>. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + class MyShiroModule <span class="code-keyword">extends</span> ShiroModule { + <span class="code-keyword">protected</span> void configureShiro() { + <span class="code-keyword">try</span> { + bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); + } <span class="code-keyword">catch</span> (NoSuchMethodException e) { + addError(e); + } + } + + @Provides + Ini loadShiroIni() { + <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); + } + } +</pre> +</div></div> + +<p>In this case, user and role configuration would go in the <tt>shiro.ini</tt> file.</p> + +#warning('shiro.ini usage in Guice', 'It is important to note that, in this above configuration, only the <tt>users</tt> and <tt>roles</tt> sections from the ini file are used.') + +<p>Then, the module is used to create a Guice injector, and the injector is used to obtain a <tt>SecurityManager</tt>. The following example serves the same purpose as the first three lines in the <a class="external-link" href="10-minute-tutorial.html#10MinuteTutorial-Quickstart.java">Quickstart</a> example.</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule()); + <span class="code-object">SecurityManager</span> securityManager = injector.getInstance(<span class="code-object">SecurityManager</span>.class); + SecurityUtils.setSecurityManager(securityManager); +</pre> +</div></div> + +<h2><a name="Guice-AOP"></a>AOP</h2> + +<p>Shiro includes several annotations and method interceptors useful for performing authorization via AOP. It also provides a simple API for writing Shiro-specific method interceptors. shiro-guice supports this with the <tt>ShiroAopModule</tt>.</p> + +<p>To use it, simply instantiate and install the module alongside your application module and your <tt>ShiroModule</tt>. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + Injector injector = Guice.createInjector(<span class="code-keyword">new</span> MyShiroModule(), <span class="code-keyword">new</span> ShiroAopModule(), <span class="code-keyword">new</span> MyApplicationModule()); +</pre> +</div></div> + +<p>If you have written custom interceptors that conform to Shiro's api, you may find it useful to extend the <tt>ShiroAopModule</tt>. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + class MyShiroAopModule <span class="code-keyword">extends</span> ShiroAopModule { + <span class="code-keyword">protected</span> void configureInterceptors(AnnotationResolver resolver) + { + bindShiroInterceptor(<span class="code-keyword">new</span> MyCustomAnnotationMethodInterceptor(resolver)); + } + } +</pre> +</div></div> + +<h2><a name="Guice-Web"></a>Web</h2> + +<p>shiro-guice's web integration is designed to integrate Shiro and its filter paradigm with Guice's servlet module. If you are using Shiro in a web environment, and using Guice's servlet module, then you should extend ShiroWebModule rather than ShiroModule. Your web.xml should be setup exactly as Guice's servlet module recommends.</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + class MyShiroWebModule <span class="code-keyword">extends</span> ShiroWebModule { + MyShiroWebModule(ServletContext sc) { + <span class="code-keyword">super</span>(sc); + } + + <span class="code-keyword">protected</span> void configureShiroWeb() { + <span class="code-keyword">try</span> { + bindRealm().toConstructor(IniRealm.class.getConstructor(Ini.class)); + } <span class="code-keyword">catch</span> (NoSuchMethodException e) { + addError(e); + } + + addFilterChain(<span class="code-quote">"/<span class="code-keyword">public</span>/**"</span>, ANON); + addFilterChain(<span class="code-quote">"/stuff/allowed/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"yes"</span>)); + addFilterChain(<span class="code-quote">"/stuff/forbidden/**"</span>, AUTHC_BASIC, config(PERMS, <span class="code-quote">"no"</span>)); + addFilterChain(<span class="code-quote">"/**"</span>, AUTHC_BASIC); + } + + @Provides + Ini loadShiroIni() { + <span class="code-keyword">return</span> Ini.fromResourcePath(<span class="code-quote">"classpath:shiro.ini"</span>); + } + } +</pre> +</div></div> + +<p>In the previous code, we have bound an <tt>IniRealm</tt> and setup four filter chains. These chains would be equivalent to the following ini configuration. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + [urls] + /<span class="code-keyword">public</span>/** = anon + /stuff/allowed/** = authcBasic, perms[<span class="code-quote">"yes"</span>] + /stuff/forbidden/** = authcBasic, perms[<span class="code-quote">"no"</span>] + /** = authcBasic +</pre> +</div></div> + +<p>In shiro-guice, the filter names are Guice keys. All of the default Shiro filters are available as constants, but you are not limited to those. In order to use a custom filter in a filter chain, you would do </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + Key customFilter = Key.get(MyCustomFilter.class); + + addFilterChain(<span class="code-quote">"/custom/**"</span>, customFilter); +</pre> +</div></div> + +<p>We still have to tell guice-servlets about our Shiro filter. Since the <tt>ShiroWebModule</tt> is private, and guice-servlets does not give us a way to expose a filter mapping, we have to bind it manually. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + ShiroWebModule.guiceFilterModule() +</pre> +</div></div> + +<p>Or, from within an application module, </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + ShiroWebModule.bindGuiceFilter(binder()) +</pre> +</div></div> + +<h2><a name="Guice-Properties"></a>Properties</h2> + +<p>A number of Shiro classes expose configuration parameters via setter methods. shiro-guice will inject these if it finds a binding for <tt>@Named("shiro.{propName}")</tt>. For instance, to set the session timeout, you could do the following. </p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.globalSessionTimeout"</span>)).to(30000L); +</pre> +</div></div> + +<p>If this paradigm doesn't work for you, you may also consider using a provider to instantiate the object and invoking the setters directly.</p> + +<h2><a name="Guice-InjectionofShiroObjects"></a>Injection of Shiro Objects</h2> + +<p>shiro-guice uses a Guice <tt>TypeListener</tt> to perform injection on native Shiro classes (any class in a subdirectory of <tt>org.apache.shiro</tt> but not <tt>org.apache.shiro.guice</tt>). However, Guice only considers explicitly bound types as candidates for <tt>TypeListeners</tt>, so if you have a Shiro object that you want injected, you have to declare it explicitly. For instance, to set the <tt>CredentialsMatcher</tt> for a realm, we would need to add the following bindings:</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> + bind(CredentialsMatcher.class).to(HashedCredentialsMatcher.class); + bind(HashedCredentialsMatcher.class); + bindConstant().annotatedWith(Names.named(<span class="code-quote">"shiro.hashAlgorithmName"</span>)).to(Md5Hash.ALGORITHM_NAME); +</pre> +</div></div> + +<h2><a name="Guice-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> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/ddea166c/java-authentication-guide.html ---------------------------------------------------------------------- diff --git a/java-authentication-guide.html b/java-authentication-guide.html deleted file mode 100644 index d80cda4..0000000 --- a/java-authentication-guide.html +++ /dev/null @@ -1,168 +0,0 @@ -<h1><a name="JavaAuthenticationGuide-JavaAuthenticationGuidewithApacheShiro"></a>Java Authentication Guide with Apache Shiro</h1> - -<p><br clear="none" class="atl-forced-newline"> -Authentication is the process of identity verification-- you are trying to prove a user is who they say they are. To do so, a user needs to provide some sort of proof of identity that your system understands and trust.</p> - -<p>The goal of this guide is to walk you through how Authentication in Java is performed in Shiro. If you haven't already please take moment and go through Shiro's <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a> so that you get a basic understanding of how to work with Shiro.</p> - -<h2><a name="JavaAuthenticationGuide-Terminologyyou%27llneed"></a>Terminology you'll need</h2> - -<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="authentication-features.html">Authentication Features</a></h3> - <p>Quick overview of easy, subject-based authentication in Shiro. </br><span style="font-size:11"><a href="authentication-features.html">Read More >></a></span></p> - - <h3><a href="authentication.html">Authentication Docs</a></h3> - <p>Full documentation on Apache Shiro's Authentication functionality. </br><span style="font-size:11"><a href="authentication.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> - -<ul><li><b>Subject</b> - Security specific user 'view' of an application user. It can be a human being, a third-party process, a server connecting to you application application, or even a cron job. Basically, it is anything or anyone communicating with your application.</li></ul> - - -<ul><li><b>Principals</b> - A subjects identifying attributes. First name, last name, social security number, username</li></ul> - - -<ul><li><b>Credentials</b> - secret data that are used to verify identities. Passwords, Biometric data, x509 certificates,</li></ul> - - -<ul><li><b>Realms</b> - Security specific DAO, data access object, software component that talkts to a backend data source. If you have usernames and password in LDAP, then you would have an LDAP Realm that would communicate with LDAP. The idea is that you would use a realm per back-end data source and Shiro would know how to coordinate with these realms together to do what you have to do.</li></ul> - - -<h2><a name="JavaAuthenticationGuide-HowtoAuthenticateinJavawithShiro"></a>How to Authenticate in Java with Shiro</h2> - -<p>In Shiro's framework, and most every other framework for that matter, the Java authentication process can be broken up into three distinct steps.</p> - -<h3><a name="JavaAuthenticationGuide-Steps"></a>Steps</h3> - -<ol><li>Collect the subject's principals and credentials</li><li>Submit the principals and credentials to an authentication system.</li><li>Allow access, retry authentication, or block access</li></ol> - - -<p>Here is some code on how you do this in Shiro Specifically.</p> - -<h3><a name="JavaAuthenticationGuide-Step1Collectthesubject%27sprincipalsandcredentials"></a>Step 1 - Collect the subject's principals and credentials</h3> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//Example using most common scenario: -</span><span class="code-comment">//<span class="code-object">String</span> username and password. Acquire in -</span><span class="code-comment">//system-specific manner (HTTP request, GUI, etc) -</span> -UsernamePasswordToken token = - <span class="code-keyword">new</span> UsernamePasswordToken( username, password ); - -<span class="code-comment">//”Remember Me” built-in, just <span class="code-keyword">do</span> <span class="code-keyword">this</span>: -</span>token.setRememberMe(<span class="code-keyword">true</span>); - -</pre> -</div></div> - -<p>In this particular case, we’re using a class called <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a>. It is the most common authentication token used in the framework.</p> - -<p>We use this token to bundle the username and password we acquired in someway in our Java application. Maybe they were submitted via a user web form, an HTTP header, or a command line. In Shiro, it does not matter how you acquire them-- it is protocol agnostic.</p> - -<p>In this example, we have decided that we want the application to remember users when they return. So once the token is created, we use Shiro's built-in "Remember-me" feature by setting it to true on the token. This is done using the token's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html#setRememberMe(boolean)">setRememberMe()</a></tt> method</p> - -<h3><a name="JavaAuthenticationGuide-Step2Submittheprincipalsandcredentialstoanauthenticationsystem."></a>Step 2 - Submit the principals and credentials to an authentication system.</h3> -<p>So we’ve collected the information in a token and set it to remember returning users. The next step is in the Authentication process is to submit the token to an authentication system. Your authentication system is represented in Shiro by security-specific DAOs, that are referred to as <a class="external-link" href="static/current/apidocs/">Realms</a>. For more information on realms please check out the <a class="external-link" href="realm.html">Shiro Realm Guide</a>.</p> - -<p>In Shiro we try to make this part as quick and easy as humanly possible. We have it down to one line of Java code!</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//With most of Shiro, you'll always want to make sure you're working with the currently executing user, referred to as the subject -</span>Subject currentUser = SecurityUtils.getSubject(); - -<span class="code-comment">//Authenticate the subject by passing -</span><span class="code-comment">//the user name and password token -</span><span class="code-comment">//into the login method -</span>currentUser.login(token); -</pre> -</div></div> - -<p>First, we need to acquire the currently executing user, referred to as the subject. A subject is just a security specific view of the user----it can be a human, a process, cron job, doesn’t matter. In Shiro, there is always a subject instance available to the currently executing thread. The concept of a subject is core to Shiro and most of the framework is centered around working with subjects. In this example, we will name this instance of subject currentUser.</p> - -<p>To acquire the subject, we use the <a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html">SecurityUtils</a> class which is also a core pat of Shiro's API. It will acquire the currently executing user via the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html#getSubject()">getsubject()</a></tt> method call. And we get back a subject instance that is representing who the current user is who is interacting with the system. At this point in the example, the subject currentUser is anonymous. There is no identity associated with them.</p> - -<p>Now with the user representation in hand, we authenticate them by just calling the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#login(org.apache.shiro.authc.AuthenticationToken))">login()</a></tt> method and submit the token we just constructed a second ago.</p> - -<h3><a name="JavaAuthenticationGuide-Step3Allowaccess%2Cretryauthentication%2Corblockaccess"></a>Step 3 - Allow access, retry authentication, or block access</h3> -<p>Again really, really easy, single method call. If the <tt>login()</tt> method call is successful, then the user is logged in and associated with a user account or identity. From here, the user can go about using your application and retain their identity through their session or longer since we have set the "Remember Me" in our example.</p> - -<p>But what happens if something fails in the authentication attempt? What if they give you the wrong password or they accessed the system too many times, maybe their account is locked? In this case, Shiro will throw an exception. This is where Shiro's rich exception hierarchy comes into play.</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-keyword">catch</span> ( UnknownAccountException uae ) { ... -} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice ) { ... -} <span class="code-keyword">catch</span> ( LockedAccountException lae ) { ... -} <span class="code-keyword">catch</span> ( ExcessiveAttemptsException eae ) { ... -} ... <span class="code-keyword">catch</span> your own ... -} <span class="code-keyword">catch</span> ( AuthenticationException ae ) { - <span class="code-comment">//unexpected error? -</span>} -<span class="code-comment">//No problems, show authenticated view…</span> -</pre> -</div></div> - -<p>You can take that method call and wrap it in a try/catch block and you can catch all sort of exceptions if you want to handle them and react accordingly. In addition to a rich set of exceptions that Shiro offers, you can create your own if you need custom functionality. For more information, follow this link documentation on <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException</a>.</p> - -<div class="panelMacro"><table class="tipMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Security Tip</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 system.</td></tr></table></div> - -<h2><a name="JavaAuthenticationGuide-%22RememberMe%22Support"></a>"Remember Me" Support</h2> - -<p>As shown in the example above, Shiro supports the notion of "remember me" in adition to the normal login process.  </p> - -<p>In Shiro, the Subject object supports two methods : <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isRemembered()">isRemembered()</a></tt> and <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isAuthenticated()">isAuthenticated()</a></tt>.</p> - -<p>A "remembered" subject has an identity (it is not anonymous) and their identifying attributes,referred to as principals, are remembered from a successful authentication during a previous session.</p> - -<p>An authenticated subject has proved their identity <em>during their current session</em>.</p> - -<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1"><b>Warning</b><br clear="none">If a subject is remembered, it DOES NOT mean they are authenticated.</td></tr></table></div> - -<h3><a name="JavaAuthenticationGuide-RememberedvsAuthenticated"></a>Remembered vs Authenticated</h3> -<p>In shiro it is very important to note that a remembered subject is not an authenticated subject. A check against <tt>isAuthenticated()</tt> is a much more strict check because authentication is the process of proving you are who you say you are. When a user is only remembered, the remembered identity gives the system an idea who that user probably is, but in reality, has no way of absolutely guaranteeing if the remembered Subject represents the user currently using the application. Once the subject is authenticated, they are no longer considered only remembered because their identity would have been verified during the current session.</p> - -<p>So although many parts of the application can still perform user-specific logic based on the remembered principals, such as customized views, it should never perform highly-sensitive operations until the user has legitimately verified their identity by executing a successful authentication attempt.</p> - -<p>For example, a check to see if a subject can access financial information should almost always depend on <tt>isAuthenticated()</tt>, not <tt>isRemembered()</tt>, to guarantee a verified identity.</p> - -<p>He is a scenario to help illustrate why the the distinction between isAuthenticated and isRemembered is important.</p> - -<p>Let's say you're using Amazon.com. You log in and you add some books to your shopping cart. A day goes by. Of course your user session has expired and you've been logged out. But Amazon "remembers" you, greets you by name, and is still giving you personalized book recommendations. To Amazon, <tt>isRemembered()</tt> would return <tt>TRUE</tt>. What happens if you try to use one of the credit cards on file or change your account information? While Amazon "remembers" you, <tt>isRemembered() = TRUE</tt>, it is not certain that you are in fact you, <tt>isAuthenticated()=FALSE</tt>. So before you can perform a sensitive action Amazon needs to verify your identity by forcing an authentication process which it does through a login screen. After the login, your identity has been verified and <tt>isAuthenticated()=TRUE</tt>.</p> - -<p>This scenario happens very often over the web so the functionality is built into Shiro helping you easily make the distinction yourself.</p> - -<h2><a name="JavaAuthenticationGuide-LoggingOut"></a>Logging Out</h2> -<p>Finally, when the user is done using the application, they can log out. And in Shiro, we make logging out quick and easy with a single method call.</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> - -<p>When you log out in Shiro it will close out the user session and removes any associated identity from the subject instance. If you're using RememberMe in a web environment, then <tt>.logout()</tt> will, by default, also delete the RememberMe cookie from the browser.</p> - -<h2><a name="JavaAuthenticationGuide-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/ddea166c/java-authentication-guide.html.vtl ---------------------------------------------------------------------- diff --git a/java-authentication-guide.html.vtl b/java-authentication-guide.html.vtl new file mode 100644 index 0000000..d34137c --- /dev/null +++ b/java-authentication-guide.html.vtl @@ -0,0 +1,168 @@ +<h1><a name="JavaAuthenticationGuide-JavaAuthenticationGuidewithApacheShiro"></a>Java Authentication Guide with Apache Shiro</h1> + +<p><br clear="none" class="atl-forced-newline"> +Authentication is the process of identity verification-- you are trying to prove a user is who they say they are. To do so, a user needs to provide some sort of proof of identity that your system understands and trust.</p> + +<p>The goal of this guide is to walk you through how Authentication in Java is performed in Shiro. If you haven't already please take moment and go through Shiro's <a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a> so that you get a basic understanding of how to work with Shiro.</p> + +<h2><a name="JavaAuthenticationGuide-Terminologyyou%27llneed"></a>Terminology you'll need</h2> + +<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="authentication-features.html">Authentication Features</a></h3> + <p>Quick overview of easy, subject-based authentication in Shiro. </br><span style="font-size:11"><a href="authentication-features.html">Read More >></a></span></p> + + <h3><a href="authentication.html">Authentication Docs</a></h3> + <p>Full documentation on Apache Shiro's Authentication functionality. </br><span style="font-size:11"><a href="authentication.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> + +<ul><li><b>Subject</b> - Security specific user 'view' of an application user. It can be a human being, a third-party process, a server connecting to you application application, or even a cron job. Basically, it is anything or anyone communicating with your application.</li></ul> + + +<ul><li><b>Principals</b> - A subjects identifying attributes. First name, last name, social security number, username</li></ul> + + +<ul><li><b>Credentials</b> - secret data that are used to verify identities. Passwords, Biometric data, x509 certificates,</li></ul> + + +<ul><li><b>Realms</b> - Security specific DAO, data access object, software component that talkts to a backend data source. If you have usernames and password in LDAP, then you would have an LDAP Realm that would communicate with LDAP. The idea is that you would use a realm per back-end data source and Shiro would know how to coordinate with these realms together to do what you have to do.</li></ul> + + +<h2><a name="JavaAuthenticationGuide-HowtoAuthenticateinJavawithShiro"></a>How to Authenticate in Java with Shiro</h2> + +<p>In Shiro's framework, and most every other framework for that matter, the Java authentication process can be broken up into three distinct steps.</p> + +<h3><a name="JavaAuthenticationGuide-Steps"></a>Steps</h3> + +<ol><li>Collect the subject's principals and credentials</li><li>Submit the principals and credentials to an authentication system.</li><li>Allow access, retry authentication, or block access</li></ol> + + +<p>Here is some code on how you do this in Shiro Specifically.</p> + +<h3><a name="JavaAuthenticationGuide-Step1Collectthesubject%27sprincipalsandcredentials"></a>Step 1 - Collect the subject's principals and credentials</h3> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//Example using most common scenario: +</span><span class="code-comment">//<span class="code-object">String</span> username and password. Acquire in +</span><span class="code-comment">//system-specific manner (HTTP request, GUI, etc) +</span> +UsernamePasswordToken token = + <span class="code-keyword">new</span> UsernamePasswordToken( username, password ); + +<span class="code-comment">//”Remember Me” built-in, just <span class="code-keyword">do</span> <span class="code-keyword">this</span>: +</span>token.setRememberMe(<span class="code-keyword">true</span>); + +</pre> +</div></div> + +<p>In this particular case, we’re using a class called <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html">UsernamePasswordToken</a>. It is the most common authentication token used in the framework.</p> + +<p>We use this token to bundle the username and password we acquired in someway in our Java application. Maybe they were submitted via a user web form, an HTTP header, or a command line. In Shiro, it does not matter how you acquire them-- it is protocol agnostic.</p> + +<p>In this example, we have decided that we want the application to remember users when they return. So once the token is created, we use Shiro's built-in "Remember-me" feature by setting it to true on the token. This is done using the token's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/UsernamePasswordToken.html\#setRememberMe(boolean)">setRememberMe()</a></tt> method</p> + +<h3><a name="JavaAuthenticationGuide-Step2Submittheprincipalsandcredentialstoanauthenticationsystem."></a>Step 2 - Submit the principals and credentials to an authentication system.</h3> +<p>So we’ve collected the information in a token and set it to remember returning users. The next step is in the Authentication process is to submit the token to an authentication system. Your authentication system is represented in Shiro by security-specific DAOs, that are referred to as <a class="external-link" href="static/current/apidocs/">Realms</a>. For more information on realms please check out the <a class="external-link" href="realm.html">Shiro Realm Guide</a>.</p> + +<p>In Shiro we try to make this part as quick and easy as humanly possible. We have it down to one line of Java code!</p> + +<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> +<pre class="code-java"> +<span class="code-comment">//With most of Shiro, you'll always want to make sure you're working with the currently executing user, referred to as the subject +</span>Subject currentUser = SecurityUtils.getSubject(); + +<span class="code-comment">//Authenticate the subject by passing +</span><span class="code-comment">//the user name and password token +</span><span class="code-comment">//into the login method +</span>currentUser.login(token); +</pre> +</div></div> + +<p>First, we need to acquire the currently executing user, referred to as the subject. A subject is just a security specific view of the user----it can be a human, a process, cron job, doesn&\#8217;t matter. In Shiro, there is always a subject instance available to the currently executing thread. The concept of a subject is core to Shiro and most of the framework is centered around working with subjects. In this example, we will name this instance of subject currentUser.</p> + +<p>To acquire the subject, we use the <a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html">SecurityUtils</a> class which is also a core pat of Shiro's API. It will acquire the currently executing user via the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/SecurityUtils.html\#getSubject()">getsubject()</a></tt> method call. And we get back a subject instance that is representing who the current user is who is interacting with the system. At this point in the example, the subject currentUser is anonymous. There is no identity associated with them.</p> + +<p>Now with the user representation in hand, we authenticate them by just calling the <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html\#login(org.apache.shiro.authc.AuthenticationToken))">login()</a></tt> method and submit the token we just constructed a second ago.</p> + +<h3><a name="JavaAuthenticationGuide-Step3Allowaccess%2Cretryauthentication%2Corblockaccess"></a>Step 3 - Allow access, retry authentication, or block access</h3> +<p>Again really, really easy, single method call. If the <tt>login()</tt> method call is successful, then the user is logged in and associated with a user account or identity. From here, the user can go about using your application and retain their identity through their session or longer since we have set the "Remember Me" in our example.</p> + +<p>But what happens if something fails in the authentication attempt? What if they give you the wrong password or they accessed the system too many times, maybe their account is locked? In this case, Shiro will throw an exception. This is where Shiro's rich exception hierarchy comes into play.</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-keyword">catch</span> ( UnknownAccountException uae ) { ... +} <span class="code-keyword">catch</span> ( IncorrectCredentialsException ice ) { ... +} <span class="code-keyword">catch</span> ( LockedAccountException lae ) { ... +} <span class="code-keyword">catch</span> ( ExcessiveAttemptsException eae ) { ... +} ... <span class="code-keyword">catch</span> your own ... +} <span class="code-keyword">catch</span> ( AuthenticationException ae ) { + <span class="code-comment">//unexpected error? +</span>} +<span class="code-comment">//No problems, show authenticated view…</span> +</pre> +</div></div> + +<p>You can take that method call and wrap it in a try/catch block and you can catch all sort of exceptions if you want to handle them and react accordingly. In addition to a rich set of exceptions that Shiro offers, you can create your own if you need custom functionality. For more information, follow this link documentation on <a class="external-link" href="static/current/apidocs/org/apache/shiro/authc/AuthenticationException.html">AuthenticationException</a>.</p> + +#tip('Security Tip', '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.') + +<h2><a name="JavaAuthenticationGuide-%22RememberMe%22Support"></a>"Remember Me" Support</h2> + +<p>As shown in the example above, Shiro supports the notion of "remember me" in adition to the normal login process.  </p> + +<p>In Shiro, the Subject object supports two methods : <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html\#isRemembered()">isRemembered()</a></tt> and <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html\#isAuthenticated()">isAuthenticated()</a></tt>.</p> + +<p>A "remembered" subject has an identity (it is not anonymous) and their identifying attributes,referred to as principals, are remembered from a successful authentication during a previous session.</p> + +<p>An authenticated subject has proved their identity <em>during their current session</em>.</p> + +#danger('Warning', 'If a subject is remembered, it DOES NOT mean they are authenticated.') + +<h3><a name="JavaAuthenticationGuide-RememberedvsAuthenticated"></a>Remembered vs Authenticated</h3> +<p>In shiro it is very important to note that a remembered subject is not an authenticated subject. A check against <tt>isAuthenticated()</tt> is a much more strict check because authentication is the process of proving you are who you say you are. When a user is only remembered, the remembered identity gives the system an idea who that user probably is, but in reality, has no way of absolutely guaranteeing if the remembered Subject represents the user currently using the application. Once the subject is authenticated, they are no longer considered only remembered because their identity would have been verified during the current session.</p> + +<p>So although many parts of the application can still perform user-specific logic based on the remembered principals, such as customized views, it should never perform highly-sensitive operations until the user has legitimately verified their identity by executing a successful authentication attempt.</p> + +<p>For example, a check to see if a subject can access financial information should almost always depend on <tt>isAuthenticated()</tt>, not <tt>isRemembered()</tt>, to guarantee a verified identity.</p> + +<p>He is a scenario to help illustrate why the the distinction between isAuthenticated and isRemembered is important.</p> + +<p>Let's say you're using Amazon.com. You log in and you add some books to your shopping cart. A day goes by. Of course your user session has expired and you've been logged out. But Amazon "remembers" you, greets you by name, and is still giving you personalized book recommendations. To Amazon, <tt>isRemembered()</tt> would return <tt>TRUE</tt>. What happens if you try to use one of the credit cards on file or change your account information? While Amazon "remembers" you, <tt>isRemembered() = TRUE</tt>, it is not certain that you are in fact you, <tt>isAuthenticated()=FALSE</tt>. So before you can perform a sensitive action Amazon needs to verify your identity by forcing an authentication process which it does through a login screen. After the login, your identity has been verified and <tt>isAuthenticated()=TRUE</tt>.</p> + +<p>This scenario happens very often over the web so the functionality is built into Shiro helping you easily make the distinction yourself.</p> + +<h2><a name="JavaAuthenticationGuide-LoggingOut"></a>Logging Out</h2> +<p>Finally, when the user is done using the application, they can log out. And in Shiro, we make logging out quick and easy with a single method call.</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> + +<p>When you log out in Shiro it will close out the user session and removes any associated identity from the subject instance. If you're using RememberMe in a web environment, then <tt>.logout()</tt> will, by default, also delete the RememberMe cookie from the browser.</p> + +<h2><a name="JavaAuthenticationGuide-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/ddea166c/java-authorization-guide.html ---------------------------------------------------------------------- diff --git a/java-authorization-guide.html b/java-authorization-guide.html deleted file mode 100644 index b84a641..0000000 --- a/java-authorization-guide.html +++ /dev/null @@ -1,234 +0,0 @@ -<h1><a name="JavaAuthorizationGuide-JavaAuthorizationGuidewithApacheShiro"></a>Java Authorization Guide with Apache Shiro</h1> - -<p><br clear="none" class="atl-forced-newline"> -Authorization, or access control, is the function of specifying access rights to resources. In other words, <em>who</em> has access to <em>what</em>.</p> - -<p>Examples of authorization checks are: Is the user allowed to look at this webpage, edit this data, view this button, or print to this printer? Those are all decisions determining what a user has access to.</p> - -<h2><a name="JavaAuthorizationGuide-ElementsofAuthorization"></a>Elements of Authorization</h2> -<p>Authorization has three core elements that we reference quite a bit in Shiro-- permissions, roles, and users. </p> - -<h3><a name="JavaAuthorizationGuide-PermissionsDefined"></a>Permissions Defined</h3> - -<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="authorization-features.html">Authorization Features</a></h3> - <p>Quick overview of permissions, roles, and users in Shiro. </br><span style="font-size:11"><a href="authorization-features.html">Read More >></a></span></p> - - <h3><a href="authorization.html">Authorization Docs</a></h3> - <p>Full documentation on Apache Shiro's Authorization functionality. </br><span style="font-size:11"><a href="authorization.html">Read More >></a></span></p> - - <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> - -<p>Permissions are the most atomic level of a security policy and they are statements of functionality. Permissions represent what can be done in your application. A well formed permission describes a resource types and what actions are possible when you interact with those resources. Can you <em>open</em> a <em>door</em>? Can you <em>read</em> a <em>file</em>? Can you <em>delete</em> a <em>customer record</em>? Can you <em>push</em> a <em>button</em>? </p> - -<p>Common actions for data-related resources are create, read, update, and delete, commonly referred to as CRUD.</p> - -<p>It is important to understand that permissions do not have knowledge of <em>who</em> can perform the actions-- they are just statements of <em>what</em> actions can be performed.</p> - -<h4><a name="JavaAuthorizationGuide-Levelsofpermissiongranularity"></a>Levels of permission granularity</h4> -<p>The permissions above all specify an actions (open, read, delete, etc) on a resource (door, file, customer record, etc). In Shiro, you can define a permission to any depth you like. Here are a few common permission levels in order of granularity.</p> - -<ul><li>Resource Level - This is the broadest and easiest to build. A user can edit customer records or open doors. The resource is specified but not a specific instance of that resource.</li><li>Instance Level - The permission specifies the instance of a resource. A user can edit the customer record for IBM or open the kitchen door.</li><li>Attribute Level - The permission now specifies an attribute of an instance or resource. A user can edit the address on the IBM customer record.</li></ul> - - -<p>For more information on Permissions please check out the <a href="permissions.html" title="Permissions">Permissions Documentation</a></p> - -<h3><a name="JavaAuthorizationGuide-RolesDefined"></a>Roles Defined</h3> -<p>In the context of Authorization, Roles are effectively a collection of permissions used to simplify the management of permissions and users. So users can be assigned roles instead of being assigned permissions directly, which can get complicated with larger user bases and more complex applications. So, for example, a bank application might have an <em>administrator</em> role or a <em>bank teller</em> role.</p> - -<p>There are two types of roles that you need to be aware of and Shiro will support both.</p> - -<h4><a name="JavaAuthorizationGuide-ImplicitRoles"></a>Implicit Roles</h4> -<p>Most people view roles as what we define as an implicit role where your application <em>implies</em> a set of permissions because a user has a particular role as opposed to the role explicitly being assigned permissions or your application checking for those permissions. Role checks in code are generally a reflection of an implicit role. You can view patient data because you have the <em>administrator</em> role. You can create an account because you have the <em>bank teller</em> role. The fact that these names exist does not have a correlation to what the software can actually do. Most people use roles in this manner. It is easiest but it can create a lot of maintenance and management problems for all the but the simplest application.</p> - -<h4><a name="JavaAuthorizationGuide-ExplicitRoles"></a>Explicit Roles</h4> -<p>An explicit role has permissions <em>explicitly</em> assigned to it and therefore is an <em>explicit</em> collection of permissions. Permission checks in code are a reflection of an explicit role. You can view patient data because because you have the <em>view patient data</em> permission as part of your <em>administrator</em> role. You can create an account because you have the <em>create account</em> permission as part of your <em>bank teller</em> role. You can perform these actions, not because of some implicit role name based on a string but because the corresponding permission was explicitly assigned to your role.</p> - -<p>The big benefits of explicit roles are easier manageability and lower maintenance of your application. If you ever need to add, remove, or change a role, you can do so without touching your source code. And in Shiro, you'll also be able to dynamically add, remove, or change roles at runtime and your authorization checks will always have up to date values. This means you won't have to force users to log out and log back in order to get their new permissions.</p> - -<h3><a name="JavaAuthorizationGuide-UsersDefined"></a>Users Defined</h3> -<p>A user is the "who" of an application. In Shiro, though, the concept of a user is really the <a href="subject.html" title="Subject">Subject</a> instance. We use word Subject instead of user because user usually implies a human being and in Shiro a Subject can be anything interacting with your application-- whether it be a human or a service. </p> - -<p>Users are allowed to perform certain actions in your application through their association with roles or direct permissions. So you are able to open a customer record because you've been assigned the <em>open customer record</em> permission, either through a role you've been assigned or through a direct permission assignment.</p> - -<p>For more information on Users, aka Subjects, please check out the <a href="subject.html" title="Subject">Subject Documentation</a>.</p> - -<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1" valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"; width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">Ultimately, your <a href="realm.html" title="Realm">Realm</a> implementation is what communicates with your data source (RDBMS, LDAP, etc). So your realm is what will tell Shiro whether or not roles or permissions exist. You have full control over how your authorization model works.</td></tr></table></div> - -<h2><a name="JavaAuthorizationGuide-HowtoperformAuthorizationinJavawithShiro"></a>How to perform Authorization in Java with Shiro</h2> -<p>Authorization in Shiro can be handled in four ways.</p> - -<ul><li>Programmatically - You can perform authorization checks in your java code with structures like <tt>if</tt> and <tt>else</tt> blocks.</li><li>JDK annotations - You can attach an authorization annotation to your Java methods</li><li>JSP/GSP TagLibs - You can control jsp or gsp page output based on roles and permissions</li></ul> - - -<h3><a name="JavaAuthorizationGuide-ProgrammaticAuthorization"></a>Programmatic Authorization</h3> -<p>Checking for permissions and roles, programmatically in your Java code is the traditional way of handling authorization. Here's how you can perform a permission check or role check in Shiro.</p> - -<h4><a name="JavaAuthorizationGuide-RoleCheck"></a>Role Check</h4> -<p>This is an example of how you do a role check programmatically in your application. We want to check if a user has the <em>administrator</em> role and if they do, then we'll show a special button, otherwise we won't show it.</p> - -<p>First we get access to the current user, the <a href="subject.html" title="Subject">Subject</a>. Then we pass the <em>adminstrator</em> to the Subject's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#hasRole(java.lang.String)">.hasRole()</a></tt> method. It will return <tt>TRUE</tt> or <tt>FALSE</tt>. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//get the current Subject -</span>Subject currentUser = - SecurityUtils.getSubject(); - -<span class="code-keyword">if</span> (currentUser.hasRole(“administrator”)) { - <span class="code-comment">//show a special button‏ -</span>} <span class="code-keyword">else</span> { - <span class="code-comment">//don’t show the button?)‏ -</span>} -</pre> -</div></div> - -<p>Now a role based check is quick and easy to implement but it has a major drawback. It is implicit.</p> - -<p>What if you just want to add, remove, or redefine a role later? You'll have to crack open your source code and change all your role checks to reflect the change in your security model. You'll have to shut down the application, crack open the code, test it, and then restart it everytime. </p> - -<p>In very simple applications this is probably good enough but for larger apps this can be a major problem throughout the life of your application and drive a large maintenance cost for your software. </p> - -<h4><a name="JavaAuthorizationGuide-PermissionCheck"></a>Permission Check</h4> -<p>This is an example of how you do security checks by permission. We want to check if a user has permission to print to laserjet3000n and if they do, then we'll show a print button, otherwise we won't show it. This is an example of an instance level permission or instance level authorization.</p> - -<p>Again, first you get access to the current user, the <a href="subject.html" title="Subject">Subject</a>. Then you construct a <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permission</a></tt> object or an instance that represents an action on a resource. In this case, the instance is named <tt>printerPermission</tt>, the resource is <em>laserjet3000n</em>, and the action is <em>print</em>. Then we pass <tt>printerPermission</tt> to the Subject's <tt><a class="external-link" href="static/current/apidocs/org/apache/shiro/subject/Subject.html#isPermitted(java.util.List)">.isPermitted()</a></tt> method. It will return true or false. </p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -Subject currentUser = - SecurityUtils.getSubject(); - -Permission printPermission = -<span class="code-keyword">new</span> PrinterPermission(“laserjet3000n”,“print”); - -If (currentUser.isPermitted(printPermission)) { - <span class="code-comment">//<span class="code-keyword">do</span> one thing (show the print button?)‏ -</span>} <span class="code-keyword">else</span> { - <span class="code-comment">//don’t show the button? -</span>} -</pre> -</div></div> - -<h4><a name="JavaAuthorizationGuide-PermissionCheck%28Stringbased%29"></a>Permission Check (String-based)</h4> -<p>You can also a permission check using a simple string instead of a permission class.</p> - -<p>So, if you don't want to implement our <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">permission interface</a> then you just pass in a String. In this example, we pass the <tt>.isPermitted()</tt> method a string, <tt>printer:print:LaserJet4400n</tt></p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-object">String</span> perm = “printer:print:laserjet4400n”; - -<span class="code-keyword">if</span>(currentUser.isPermitted(perm)){ - <span class="code-comment">//show the print button? -</span>} <span class="code-keyword">else</span> { - <span class="code-comment">//don’t show the button? -</span>} -</pre> -</div></div> - -<p>You can construct the permission string the way you want so long as your <a href="realm.html" title="Realm">Realm</a> knows how to work with it. In this example we use Shiro's optional permission syntax, <a href="permissions.html" title="Permissions">WildCardPermissions</a>. WildCardPermissions are powerful and intuitive. If you'd like to learn more about them then check out the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permissions Documentation</a>.</p> - -<p>With string-based permission checks, you get the same functionality as the example before. The benefit is that you are not forced to implement a permission interface and you can construct the permission via a simple string. The downside is that you don't have type safety and if you needed more complicated permission capabilitues that are outside the scope of what this represents, you're going to want to implement your own permission objects based on the permission interface.</p> - -<h3><a name="JavaAuthorizationGuide-AnnotationAuthorization"></a>Annotation Authorization</h3> - -<p>If you don't want to do code level authorization checks, then you can use Java Annotations as well. Shiro offers a number of <a href="java-annotations-list.html" title="Java Annotations List">Java annotations</a> that allow you to annotate methods. </p> - -<h4><a name="JavaAuthorizationGuide-EnablingAnnotationSupport"></a>Enabling Annotation Support</h4> -<p>Before you can use Java annotations, you'll need to enable AOP support in your application. There are a number of different AOP frameworks so, unfortunately, there is no standard way to enable AOP in an application.</p> - -<p>For AspectJ, you can review our <a class="external-link" href="https://github.com/apache/shiro/tree/master/samples/aspectj";>AspectJ sample application</a>.</p> - -<p>For Spring, you can look into our <a href="spring.html" title="Spring">Spring Integration</a> documentation.</p> - -<p>For Guice, you can look into our <a href="guice.html" title="Guice">Guice Integration</a> documentation.</p> - -<h4><a name="JavaAuthorizationGuide-PermissionCheck"></a>Permission Check</h4> -<p>In this example, we want to check that a user has the <tt>account:create</tt> permission before they can invoke the <tt>openAccount</tt> method. If they do, then the method is called as expected, and if they don't, then an exception is thrown. </p> - -<p>Like programmatic checks, you can use the <a class="external-link" href="static/current/apidocs/org/apache/shiro/authz/Permission.html">Permission</a> objects or the simple string methods with this annotation.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//Will <span class="code-keyword">throw</span> an AuthorizationException <span class="code-keyword">if</span> none -</span><span class="code-comment">//of the caller’s roles imply the Account -</span><span class="code-comment">//'create' permission� -</span>@RequiresPermissions(“account:create”)‏ -<span class="code-keyword">public</span> void openAccount( Account acct ) { - <span class="code-comment">//create the account -</span>} -</pre> -</div></div> - -<h4><a name="JavaAuthorizationGuide-RoleCheck"></a>Role Check</h4> -<p>In this example, we want to check that a user has the <tt>teller</tt> role before they can invoke the <tt>openAccount</tt> method. If they do, then the method is called as expected, and if they don't, then an exception is thrown.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-comment">//Throws an AuthorizationException <span class="code-keyword">if</span> the caller -</span><span class="code-comment">//doesn’t have the ‘teller’ role: -</span> -@RequiresRoles( “teller” ) -<span class="code-keyword">public</span> void openAccount( Account acct ) { - <span class="code-comment">//<span class="code-keyword">do</span> something in here that only a teller -</span> <span class="code-comment">//should <span class="code-keyword">do</span> -</span>} -</pre> -</div></div> - -<h3><a name="JavaAuthorizationGuide-JSPTagLibAuthorization"></a>JSP TagLib Authorization</h3> -<p>For JSP/GSP based web applications, Shiro also offers a <a href="jsp-tag-library.html" title="JSP Tag Library">tag library</a> for you to use. </p> - -<p>In this example, we're going to show users with the <em>users:manage</em> permission a link to the Manage Users page. If they do not have the permission, then we'll show them a nice message.</p> - -<p>First, we'll need to add the Shiro taglib to our web application. Next, we add the <tt><shiro:hasPermission></tt> tag with a check for <em>users:manage</em>. Within the <tt><shiro:hasPermission></tt> tags we will place the code we want to execute if the user has the permission we're checking for. If we want to take an action if the user lacks the permission, then we need to also add the <tt><shiro:lacksPermission></tt> tag, again checking for <em>users:manage</em>. And any code we want to excute if the user lacks the permission will need to be placed within the <tt><shiro:lacksPermission></tt> tags.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<%@ taglib prefix=“shiro” uri=http:<span class="code-comment">//shiro.apache.org/tags %> -</span><html> -<body> - <shiro:hasPermission name=“users:manage”> - <a href=“manageUsers.jsp”> - Click here to manage users - </a> - </shiro:hasPermission> - <shiro:lacksPermission name=“users:manage”> - No user management <span class="code-keyword">for</span> you! - </shiro:lacksPermission> -</body> -</html> -</pre> -</div></div> - -<p>Of course, there also tags for checking roles and other user data and states.</p> - -<p>For more information on JSP/GSP Tags please check out the <a href="jsp-tag-library.html" title="JSP Tag Library">JSP Tag Library</a> and for more information on integration your application in your web application, please read the <a href="web.html" title="Web">Web Integration Documentation</a></p> - -<h2><a name="JavaAuthorizationGuide-CachingAuthorization"></a>Caching Authorization</h2> -<p>TBD</p> - -<h2><a name="JavaAuthorizationGuide-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>
![https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"){kind=link}
![https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"](https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"){kind=link}