converted a few more pages
Project: http://git-wip-us.apache.org/repos/asf/shiro-site/repo Commit: http://git-wip-us.apache.org/repos/asf/shiro-site/commit/585f8465 Tree: http://git-wip-us.apache.org/repos/asf/shiro-site/tree/585f8465 Diff: http://git-wip-us.apache.org/repos/asf/shiro-site/diff/585f8465 Branch: refs/heads/master Commit: 585f846553b63ad55b410e918b57d235646aa29a Parents: 26d6e78 Author: Brian Demers <[email protected]> Authored: Sat Oct 22 19:37:58 2016 -0500 Committer: Brian Demers <[email protected]> Committed: Sat Oct 22 19:37:58 2016 -0500 ---------------------------------------------------------------------- forums.html | 10 -- forums.md | 12 ++ guides.html | 13 --- guides.md | 12 ++ issues.html | 13 --- issues.md | 20 ++++ java-annotations.html | 15 --- java-annotations.md | 20 ++++ spring.html | 225 -------------------------------------- spring.md | 214 ++++++++++++++++++++++++++++++++++++ version-2-brainstorming.html | 199 --------------------------------- version-2-brainstorming.md | 205 ++++++++++++++++++++++++++++++++++ 12 files changed, 483 insertions(+), 475 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/forums.html ---------------------------------------------------------------------- diff --git a/forums.html b/forums.html deleted file mode 100644 index d73bfa9..0000000 --- a/forums.html +++ /dev/null @@ -1,10 +0,0 @@ -<h1><a name="Forums-ApacheShiroCommunityForums"></a>Apache Shiro Community Forums</h1> - -<p>For users that prefer to use forums over mailing lists, we use the <a class="external-link" href="http://www.nabble.com"; rel="nofollow">Nabble</a> forum/email/archive service. Nabble ensures that its forums remain synchronized with the mailing lists, so feel free to use whichever mechanism you like.</p> - - -<ul class="alternate" type="square"><li><a class="external-link" href="http://shiro-user.582556.n2.nabble.com/"; rel="nofollow">Shiro User Forum</a></li><li><a class="external-link" href="http://shiro-developer.582600.n2.nabble.com/"; rel="nofollow">Shiro Developer Forum</a></li></ul> - - -<h2><a name="Forums-MailingLists"></a>Mailing Lists</h2> -<p>For those that may prefer mailing lists, please see the <a href="mailing-lists.html" title="Mailing Lists">Mailing Lists</a> information.</p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/forums.md ---------------------------------------------------------------------- diff --git a/forums.md b/forums.md new file mode 100644 index 0000000..4590bf1 --- /dev/null +++ b/forums.md @@ -0,0 +1,12 @@ +<a name="Forums-ApacheShiroCommunityForums"></a> +#Apache Shiro Community Forums + +For users that prefer to use forums over mailing lists, we use the [Nabble](http://www.nabble.com) forum/email/archive service. Nabble ensures that its forums remain synchronized with the mailing lists, so feel free to use whichever mechanism you like. + +* [Shiro User Forum](http://shiro-user.582556.n2.nabble.com/) +* [Shiro Developer Forum](http://shiro-developer.582600.n2.nabble.com/) + +<a name="Forums-MailingLists"></a> +##Mailing Lists + +For those that may prefer mailing lists, please see the [Mailing Lists](mailing-lists.html) information. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/guides.html ---------------------------------------------------------------------- diff --git a/guides.html b/guides.html deleted file mode 100644 index d078f03..0000000 --- a/guides.html +++ /dev/null @@ -1,13 +0,0 @@ -<h1><a name="Guides-ApacheShiroGuides"></a>Apache Shiro Guides</h1> - -<p>Here are some basic guides on how to use Shiro.</p> - -<p>Please post any errata to the user or dev mailing lists.</p> - -<ul><li><b><a href="10-minute-tutorial.html" title="10 Minute Tutorial">10 Minute Tutorial</a></b></li></ul> - - -<ul><li><b><a href="java-authentication-guide.html" title="Java Authentication Guide">Authentication Guide</a></b></li></ul> - - -<ul><li><b><a href="java-authorization-guide.html" title="Java Authorization Guide">Authorization Guide</a></b></li></ul> http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/guides.md ---------------------------------------------------------------------- diff --git a/guides.md b/guides.md new file mode 100644 index 0000000..1ca77b8 --- /dev/null +++ b/guides.md @@ -0,0 +1,12 @@ +<a name="Guides-ApacheShiroGuides"></a> +#Apache Shiro Guides + +Here are some basic guides on how to use Shiro. + +Please post any errata to the user or dev mailing lists. + +* **[10 Minute Tutorial](10-minute-tutorial.html "10 Minute Tutorial")** + +* **[Authentication Guide](java-authentication-guide.html "Java Authentication Guide")** + +* **[Authorization Guide](java-authorization-guide.html "Java Authorization Guide")** \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/issues.html ---------------------------------------------------------------------- diff --git a/issues.html b/issues.html deleted file mode 100644 index 80d7435..0000000 --- a/issues.html +++ /dev/null @@ -1,13 +0,0 @@ -<h2><a name="Issues-ApacheShiroBug%26IssueTracking"></a>Apache Shiro Bug & Issue Tracking</h2> - -<p>Apache Shiro uses Atlassian Jira for tracking tasks, feature requests, bugs, and other issues related to the project development.</p> - -<h2><a name="Issues-UsageGuidelines"></a>Usage Guidelines</h2> - -<p>Jira is provided as a Shiro software development resource. It is meant to be for managing bugs, tasks and improvements in the software itself - it is not a support portal to ask for advice or help. For community advice and help in using Apache Shiro, please visit the <a href="support.html" title="Support">Support</a> page.</p> - -<p><b>Prior to using Jira, we ask that:</b></p> -<ul><li>You do your due diligence to ensure a suspected error is actually a bug.</li><li>You search the issue tracker to ensure what you want to report has not already been reported by someone else.</li><li>If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem so we can fix it as fast as possible.</li><li>If a unit test is not available (please really try to make one!), attach a stack trace and Shiro's TRACE or DEBUG log output.</li><li>If you've already fixed the problem, please submit a patch and we'll likely include it in the next release.</li></ul> - - -<h2><a name="Issues-ClickheretovisittheApacheShiroJiraissuetrackerhttps%3A%2F%2Fissues.apache.org%2Fjira%2Fbrowse%2FSHIRO"></a><a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO";>Click here to visit the Apache Shiro Jira issue tracker</a> </h2> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/issues.md ---------------------------------------------------------------------- diff --git a/issues.md b/issues.md new file mode 100644 index 0000000..b5fffed --- /dev/null +++ b/issues.md @@ -0,0 +1,20 @@ +<a name="Issues-ApacheShiroBug%26IssueTracking"></a> +##Apache Shiro Bug & Issue Tracking + +Apache Shiro uses Atlassian Jira for tracking tasks, feature requests, bugs, and other issues related to the project development. + +<a name="Issues-UsageGuidelines"></a> +##Usage Guidelines + +Jira is provided as a Shiro software development resource. It is meant to be for managing bugs, tasks and improvements in the software itself - it is not a support portal to ask for advice or help. For community advice and help in using Apache Shiro, please visit the [Support](support.html "Support") page. + +**Prior to using Jira, we ask that:** + +* You do your due diligence to ensure a suspected error is actually a bug. +* You search the issue tracker to ensure what you want to report has not already been reported by someone else. +* If your problem is actually a bug, we would appreciate it if you could attach a simple JUnit test case that allows us to repeat the problem so we can fix it as fast as possible. +* If a unit test is not available (please really try to make one!), attach a stack trace and Shiro's TRACE or DEBUG log output. +* If you've already fixed the problem, please submit a patch and we'll likely include it in the next release. + +<a name="Issues-ClickheretovisittheApacheShiroJiraissuetrackerhttps%3A%2F%2Fissues.apache.org%2Fjira%2Fbrowse%2FSHIRO"></a> +##[Click here to visit the Apache Shiro Jira issue tracker](https://issues.apache.org/jira/browse/SHIRO) \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/java-annotations.html ---------------------------------------------------------------------- diff --git a/java-annotations.html b/java-annotations.html deleted file mode 100644 index 670722b..0000000 --- a/java-annotations.html +++ /dev/null @@ -1,15 +0,0 @@ -<h1><a name="JavaAnnotations-JavaAnnotationSupport"></a>Java Annotation Support</h1> -<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> - -<h2><a name="JavaAnnotations-Shiro%27sJavaAnnotations."></a>Shiro's Java Annotations.</h2> -<p>Once you have AOP enabled in our application, you can use Shiro's set of annotations found in the <a href="java-annotations-list.html" title="Java Annotations List">Java Annotations List</a></p> - -<h2><a name="JavaAnnotations-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/585f8465/java-annotations.md ---------------------------------------------------------------------- diff --git a/java-annotations.md b/java-annotations.md new file mode 100644 index 0000000..0f47cd8 --- /dev/null +++ b/java-annotations.md @@ -0,0 +1,20 @@ +<a name="JavaAnnotations-JavaAnnotationSupport"></a> +#Java Annotation Support + +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. + +For AspectJ, you can review our [AspectJ sample application](https://github.com/apache/shiro/tree/master/samples/aspectj). + +For Spring, you can look into our [Spring Integration](spring.html "Spring") documentation. + +<a name="JavaAnnotations-Shiro%27sJavaAnnotations."></a> +##Shiro's Java Annotations. + +Once you have AOP enabled in our application, you can use Shiro's set of annotations found in the [Java Annotations List](java-annotations-list.html "Java Annotations List") + +<a name="JavaAnnotations-Lendahandwithdocumentation"></a> +##Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/spring.html ---------------------------------------------------------------------- diff --git a/spring.html b/spring.html deleted file mode 100644 index 96b2b3f..0000000 --- a/spring.html +++ /dev/null @@ -1,225 +0,0 @@ -<h1><a name="Spring-IntegratingApacheShirointoSpringbasedApplications"></a>Integrating Apache Shiro into Spring-based Applications</h1> - -<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"> - -<tr> -<td> -<div id="border"> - - <h3><a href="web.html">Web Apps with Shiro</a></h3> - <p>Detailed support for integrating Shiro into web applications. </br><span style="font-size:11"><a href="web.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>This page covers the ways to integrate Shiro into <a class="external-link" href="http://spring.io"; rel="nofollow">Spring</a>-based applications.</p> - -<p>Shiro's JavaBeans compatibility makes it perfectly suited to be configured via Spring XML or other Spring-based configuration mechanisms. Shiro applications need an application singleton <tt>SecurityManager</tt> instance. Note that this does not have to be a <em>static</em> singleton, but there should only be a single instance used by the application, whether its a static singleton or not.</p> - -<h2><a name="Spring-StandaloneApplications"></a>Standalone Applications</h2> - -<p>Here is the simplest way to enable an application singleton <tt>SecurityManager</tt> in Spring applications:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><span class="code-comment"><!-- Define the realm you want to use to connect to your back-end security datasource: --></span></span> -<span class="code-tag"><bean id=<span class="code-quote">"myRealm"</span> class=<span class="code-quote">"..."</span>></span> -... -<span class="code-tag"></bean></span> - -<span class="code-tag"><bean id=<span class="code-quote">"securityManager"</span> class=<span class="code-quote">"org.apache.shiro.mgt.DefaultSecurityManager"</span>></span> - <span class="code-tag"><span class="code-comment"><!-- Single realm app. If you have multiple realms, use the 'realms' property instead. --></span></span> - <span class="code-tag"><property name=<span class="code-quote">"realm"</span> ref=<span class="code-quote">"myRealm"</span>/></span> -<span class="code-tag"></bean></span> -<span class="code-tag"><bean id=<span class="code-quote">"lifecycleBeanPostProcessor"</span> class=<span class="code-quote">"org.apache.shiro.spring.LifecycleBeanPostProcessor"</span>/></span> - -<span class="code-tag"><span class="code-comment"><!-- For simplest integration, so that all SecurityUtils.* methods work in all cases, --></span></span> -<span class="code-tag"><span class="code-comment"><!-- make the securityManager bean a static singleton. DO NOT do this in web --></span></span> -<span class="code-tag"><span class="code-comment"><!-- applications - see the 'Web Applications' section below instead. --></span></span> -<span class="code-tag"><bean class=<span class="code-quote">"org.springframework.beans.factory.config.MethodInvokingFactoryBean"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"staticMethod"</span> value=<span class="code-quote">"org.apache.shiro.SecurityUtils.setSecurityManager"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"arguments"</span> ref=<span class="code-quote">"securityManager"</span>/></span> -<span class="code-tag"></bean></span> -</pre> -</div></div> - - -<h2><a name="Spring-WebApplications"></a>Web Applications</h2> - -<p>Shiro has first-rate support for Spring web applications. In a web application, all Shiro-accessible web requests must go through a master Shiro Filter. This filter itself is extremely powerful, allowing for <br clear="none"> -ad-hoc custom filter chains to be executed based on any URL path expression.</p> - -<p>Prior to Shiro 1.0, you had to use a hybrid approach in Spring web applications, defining the Shiro filter and<br clear="none"> -all of its configuration properties in web.xml but define the <tt>SecurityManager</tt> in Spring XML. This was a little frustrating since you couldn't 1) consolidate your configuration in one place and 2) leverage the configuration power of the more advanced Spring features, like the <tt>PropertyPlaceholderConfigurer</tt> or abstract beans to consolidate common configuration.</p> - -<p>Now in Shiro 1.0 and later, all Shiro configuration is done in Spring XML providing access to the more robust Spring configuration mechanisms.</p> - -<p>Here is how to configure Shiro in a Spring-based web application:</p> - -<h3><a name="Spring-web.xml"></a>web.xml</h3> - -<p>In addition to your other Spring web.xml elements (<tt>ContextLoaderListener</tt>, <tt>Log4jConfigListener</tt>, etc), define the following filter and filter mapping:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><span class="code-comment"><!-- The filter-name matches name of a 'shiroFilter' bean inside applicationContext.xml --></span></span> -<span class="code-tag"><filter></span> - <span class="code-tag"><filter-name></span>shiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><filter-class></span>org.springframework.web.filter.DelegatingFilterProxy<span class="code-tag"></filter-class></span> - <span class="code-tag"><init-param></span> - <span class="code-tag"><param-name></span>targetFilterLifecycle<span class="code-tag"></param-name></span> - <span class="code-tag"><param-value></span>true<span class="code-tag"></param-value></span> - <span class="code-tag"></init-param></span> -<span class="code-tag"></filter></span> - -... - -<span class="code-tag"><span class="code-comment"><!-- Make sure any request you want accessible to Shiro is filtered. /* catches all --></span></span> -<span class="code-tag"><span class="code-comment"><!-- requests. Usually this filter mapping is defined first (before all others) to --></span></span> -<span class="code-tag"><span class="code-comment"><!-- ensure that Shiro works in subsequent filters in the filter chain: --></span></span> -<span class="code-tag"><filter-mapping></span> - <span class="code-tag"><filter-name></span>shiroFilter<span class="code-tag"></filter-name></span> - <span class="code-tag"><url-pattern></span>/*<span class="code-tag"></url-pattern></span> -<span class="code-tag"></filter-mapping></span> -</pre> -</div></div> - -<h3><a name="Spring-applicationContext.xml"></a>applicationContext.xml</h3> - -<p>In your applicationContext.xml file, define the web-enabled <tt>SecurityManager</tt> and the 'shiroFilter' bean that will be referenced from <tt>web.xml</tt>.</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><bean id=<span class="code-quote">"shiroFilter"</span> class=<span class="code-quote">"org.apache.shiro.spring.web.ShiroFilterFactoryBean"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/></span> - <!-- override these for application-specific URLs if you like: - <span class="code-tag"><property name=<span class="code-quote">"loginUrl"</span> value=<span class="code-quote">"/login.jsp"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"successUrl"</span> value=<span class="code-quote">"/home.jsp"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"unauthorizedUrl"</span> value=<span class="code-quote">"/unauthorized.jsp"</span>/></span> --> - <span class="code-tag"><span class="code-comment"><!-- The 'filters' property is not necessary since any declared javax.servlet.Filter bean --></span></span> - <span class="code-tag"><span class="code-comment"><!-- defined will be automatically acquired and available via its beanName in chain --></span></span> - <span class="code-tag"><span class="code-comment"><!-- definitions, but you can perform instance overrides or name aliases here if you like: --></span></span> - <span class="code-tag"><!-- <property name=<span class="code-quote">"filters"</span>></span> - <span class="code-tag"><util:map></span> - <span class="code-tag"><entry key=<span class="code-quote">"anAlias"</span> value-ref=<span class="code-quote">"someFilter"</span>/></span> - <span class="code-tag"></util:map></span> - <span class="code-tag"></property></span> --> - <span class="code-tag"><property name=<span class="code-quote">"filterChainDefinitions"</span>></span> - <span class="code-tag"><value></span> - # some example chain definitions: - /admin/** = authc, roles[admin] - /docs/** = authc, perms[document:read] - /** = authc - # more URL-to-FilterChain definitions here - <span class="code-tag"></value></span> - <span class="code-tag"></property></span> -<span class="code-tag"></bean></span> - -<span class="code-tag"><span class="code-comment"><!-- Define any javax.servlet.Filter beans you want anywhere in this application context. --></span></span> -<span class="code-tag"><span class="code-comment"><!-- They will automatically be acquired by the 'shiroFilter' bean above and made available --></span></span> -<span class="code-tag"><span class="code-comment"><!-- to the 'filterChainDefinitions' property. Or you can manually/explicitly add them --></span></span> -<span class="code-tag"><span class="code-comment"><!-- to the shiroFilter's 'filters' Map if desired. See its JavaDoc for more details. --></span></span> -<span class="code-tag"><bean id=<span class="code-quote">"someFilter"</span> class=<span class="code-quote">"..."</span>/></span> -<span class="code-tag"><bean id=<span class="code-quote">"anotherFilter"</span> class=<span class="code-quote">"..."</span>></span> ... <span class="code-tag"></bean></span> -... - -<span class="code-tag"><bean id=<span class="code-quote">"securityManager"</span> class=<span class="code-quote">"org.apache.shiro.web.mgt.DefaultWebSecurityManager"</span>></span> - <span class="code-tag"><span class="code-comment"><!-- Single realm app. If you have multiple realms, use the 'realms' property instead. --></span></span> - <span class="code-tag"><property name=<span class="code-quote">"realm"</span> ref=<span class="code-quote">"myRealm"</span>/></span> - <!-- By default the servlet container sessions will be used. Uncomment this line - to use shiro's native sessions (see the JavaDoc for more): --> - <span class="code-tag"><span class="code-comment"><!-- <property name=<span class="code-quote">"sessionMode"</span> value=<span class="code-quote">"native"</span>/></span> --></span> -<span class="code-tag"></bean></span> -<span class="code-tag"><bean id=<span class="code-quote">"lifecycleBeanPostProcessor"</span> class=<span class="code-quote">"org.apache.shiro.spring.LifecycleBeanPostProcessor"</span>/></span> - -<span class="code-tag"><span class="code-comment"><!-- Define the Shiro Realm implementation you want to use to connect to your back-end --></span></span> -<span class="code-tag"><span class="code-comment"><!-- security datasource: --></span></span> -<span class="code-tag"><bean id=<span class="code-quote">"myRealm"</span> class=<span class="code-quote">"..."</span>></span> -... -<span class="code-tag"></bean></span> -</pre> -</div></div> - -<h2><a name="Spring-EnablingShiroAnnotations"></a>Enabling Shiro Annotations</h2> - -<p>In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, <tt>@RequiresRoles</tt>, <tt>@RequiresPermissions</tt>, etc. This requires Shiro's Spring AOP integration to scan for the appropriate annotated classes and perform security logic as necessary. </p> - -<p>Here is how to enable these annotations. Just add these two bean definitions to <tt>applicationContext.xml</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><span class="code-comment"><!-- Enable Shiro Annotations for Spring-configured beans. Only run after --></span></span> -<span class="code-tag"><span class="code-comment"><!-- the lifecycleBeanProcessor has run: --></span></span> -<span class="code-tag"><bean class=<span class="code-quote">"org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"</span> depends-on=<span class="code-quote">"lifecycleBeanPostProcessor"</span>/></span> -<span class="code-tag"><bean class=<span class="code-quote">"org.apache.shiro.spring.security.interceptor.AuthorizationAttributeSourceAdvisor"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/></span> -<span class="code-tag"></bean></span> -</pre> -</div></div> - -<h2><a name="Spring-SecureSpringRemoting"></a>Secure Spring Remoting</h2> - -<p>There are two parts to Shiro's Spring remoting support: Configuration for the client making the remoting call and configuration for the server receiving and processing the remoting call.</p> - -<h3><a name="Spring-ServersideConfiguration"></a>Server-side Configuration</h3> - -<p>When a remote method invocation comes in to a Shiro-enabled server, the <a href="subject.html" title="Subject">Subject</a> associated with that RPC call must be bound to the receiving thread for access during the thread's execution. This is done by defining Shiro's <tt>SecureRemoteInvocationExecutor</tt> bean in <tt>applicationContext.xml</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><span class="code-comment"><!-- Secure Spring remoting: Ensure any Spring Remoting method invocations --></span></span> -<span class="code-tag"><span class="code-comment"><!-- can be associated with a Subject for security checks. --></span></span> -<span class="code-tag"><bean id=<span class="code-quote">"secureRemoteInvocationExecutor"</span> class=<span class="code-quote">"org.apache.shiro.spring.remoting.SecureRemoteInvocationExecutor"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"securityManager"</span> ref=<span class="code-quote">"securityManager"</span>/></span> -<span class="code-tag"></bean></span> -</pre> -</div></div> - -<p>Once you have defined this bean, you must plug it in to whatever remoting <tt>Exporter</tt> you are using to export/expose your services. <tt>Exporter</tt> implementations are defined according to the remoting mechanism/protocol in use. See Spring's <a class="external-link" href="http://docs.spring.io/spring/docs/2.5.x/reference/remoting.html"; rel="nofollow">Remoting chapter</a> on defining <tt>Exporter</tt> beans.</p> - -<p>For example, if using HTTP-based remoting (notice the property reference to the <tt>secureRemoteInvocationExecutor</tt> bean):</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><bean name=<span class="code-quote">"/someService"</span> class=<span class="code-quote">"org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"service"</span> ref=<span class="code-quote">"someService"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"serviceInterface"</span> value=<span class="code-quote">"com.pkg.service.SomeService"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"remoteInvocationExecutor"</span> ref=<span class="code-quote">"secureRemoteInvocationExecutor"</span>/></span> -<span class="code-tag"></bean></span> -</pre> -</div></div> - -<h3><a name="Spring-ClientsideConfiguration"></a>Client-side Configuration</h3> - -<p>When a remote call is being executed, the <tt>Subject</tt> identifying information must be attached to the remoting payload to let the server know who is making the call. If the client is a Spring-based client, that association is done via Shiro's <tt>SecureRemoteInvocationFactory</tt>:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><bean id=<span class="code-quote">"secureRemoteInvocationFactory"</span> class=<span class="code-quote">"org.apache.shiro.spring.remoting.SecureRemoteInvocationFactory"</span>/></span> -</pre> -</div></div> - -<p>Then after you've defined this bean, you need to plug it in to the protocol-specific Spring remoting <tt>ProxyFactoryBean</tt> you're using.</p> - -<p>For example, if you were using HTTP-based remoting (notice the property reference to the <tt>secureRemoteInvocationFactory</tt> bean defined above):</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-xml"> -<span class="code-tag"><bean id=<span class="code-quote">"someService"</span> class=<span class="code-quote">"org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean"</span>></span> - <span class="code-tag"><property name=<span class="code-quote">"serviceUrl"</span> value=<span class="code-quote">"http://host:port/remoting/someService";</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"serviceInterface"</span> value=<span class="code-quote">"com.pkg.service.SomeService"</span>/></span> - <span class="code-tag"><property name=<span class="code-quote">"remoteInvocationFactory"</span> ref=<span class="code-quote">"secureRemoteInvocationFactory"</span>/></span> -<span class="code-tag"></bean></span> -</pre> -</div></div> - -<h2><a name="Spring-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/585f8465/spring.md ---------------------------------------------------------------------- diff --git a/spring.md b/spring.md new file mode 100644 index 0000000..e5a6a4e --- /dev/null +++ b/spring.md @@ -0,0 +1,214 @@ +<a name="Spring-IntegratingApacheShirointoSpringbasedApplications"></a> +#Integrating Apache Shiro into Spring-based Applications + +<table align="right" width="275" style="margin-left: 20px; margin-bottom: 20px; border-style: solid; border-width: 2px; border-color: navy" cellpadding="10px"><tbody><tr><td> +<div id="border"> + + <h3><a href="web.html">Web Apps with Shiro</a></h3> + <p>Detailed support for integrating Shiro into web applications. <br><span style="font-size:11"><a href="web.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></tbody></table> + +This page covers the ways to integrate Shiro into [Spring](http://spring.io)-based applications. + +Shiro's JavaBeans compatibility makes it perfectly suited to be configured via Spring XML or other Spring-based configuration mechanisms. Shiro applications need an application singleton `SecurityManager` instance. Note that this does not have to be a _static_ singleton, but there should only be a single instance used by the application, whether its a static singleton or not. + +## <a name="Spring-StandaloneApplications"></a>Standalone Applications + +Here is the simplest way to enable an application singleton `SecurityManager` in Spring applications: + + +``` xml +<!-- Define the realm you want to use to connect to your back-end security datasource: --> +<bean id="myRealm" class="..."> + ... +</bean> + +<bean id="securityManager" class="org.apache.shiro.mgt.DefaultSecurityManager"> + <!-- Single realm app. If you have multiple realms, use the 'realms' property instead. --> + <property name="realm" ref="myRealm"/> +</bean> + +<bean id="lifecycleBeanPostProcessor" class="org.apache.shiro.spring.LifecycleBeanPostProcessor"/> + +<!-- For simplest integration, so that all SecurityUtils.* methods work in all cases, --> +<!-- make the securityManager bean a static singleton. DO NOT do this in web --> +<!-- applications - see the 'Web Applications' section below instead. --> +<bean class="org.springframework.beans.factory.config.MethodInvokingFactoryBean"> + <property name="staticMethod" value="org.apache.shiro.SecurityUtils.setSecurityManager"/> + <property name="arguments" ref="securityManager"/> +</bean> +``` + +<a name="Spring-WebApplications"></a> +## Web Applications + +Shiro has first-rate support for Spring web applications. In a web application, all Shiro-accessible web requests must go through a master Shiro Filter. This filter itself is extremely powerful, allowing for +ad-hoc custom filter chains to be executed based on any URL path expression. + +Prior to Shiro 1.0, you had to use a hybrid approach in Spring web applications, defining the Shiro filter and +all of its configuration properties in web.xml but define the `SecurityManager` in Spring XML. This was a little frustrating since you couldn't 1) consolidate your configuration in one place and 2) leverage the configuration power of the more advanced Spring features, like the `PropertyPlaceholderConfigurer` or abstract beans to consolidate common configuration. + +Now in Shiro 1.0 and later, all Shiro configuration is done in Spring XML providing access to the more robust Spring configuration mechanisms. + +Here is how to configure Shiro in a Spring-based web application: + +<a name="Spring-web.xml"></a> +### web.xml + +In addition to your other Spring web.xml elements (`ContextLoaderListener`, `Log4jConfigListener`, etc), define the following filter and filter mapping: + +``` xml +<!-- The filter-name matches name of a 'shiroFilter' bean inside applicationContext.xml --> +<filter> + <filter-name>shiroFilter</filter-name> + <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> + <init-param> + <param-name>targetFilterLifecycle</param-name> + <param-value>true</param-value> + </init-param> +</filter> + +... + +<!-- Make sure any request you want accessible to Shiro is filtered. /* catches all --> +<!-- requests. Usually this filter mapping is defined first (before all others) to --> +<!-- ensure that Shiro works in subsequent filters in the filter chain: --> +<filter-mapping> + <filter-name>shiroFilter</filter-name> + <url-pattern>/*</url-pattern> +</filter-mapping> +``` + +<a name="Spring-applicationContext.xml"></a> +###applicationContext.xml + +In your applicationContext.xml file, define the web-enabled `SecurityManager` and the 'shiroFilter' bean that will be referenced from `web.xml`. + +``` xml +<bean id="shiroFilter" class="org.apache.shiro.spring.web.ShiroFilterFactoryBean"> + <property name="securityManager" ref="securityManager"/> + <!-- override these for application-specific URLs if you like: + <property name="loginUrl" value="/login.jsp"/> + <property name="successUrl" value="/home.jsp"/> + <property name="unauthorizedUrl" value="/unauthorized.jsp"/> --> + <!-- The 'filters' property is not necessary since any declared javax.servlet.Filter bean --> + <!-- defined will be automatically acquired and available via its beanName in chain --> + <!-- definitions, but you can perform instance overrides or name aliases here if you like: --> + <!-- <property name="filters"> + <util:map> + <entry key="anAlias" value-ref="someFilter"/> + </util:map> + </property> --> + <property name="filterChainDefinitions"> + <value> + # some example chain definitions: + /admin/** = authc, roles[admin] + /docs/** = authc, perms[document:read] + /** = authc + # more URL-to-FilterChain definitions here + </value> + </property> +</bean> + +<!-- Define any javax.servlet.Filter beans you want anywhere in this application context. --> +<!-- They will automatically be acquired by the 'shiroFilter' bean above and made available --> +<!-- to the 'filterChainDefinitions' property. Or you can manually/explicitly add them --> +<!-- to the shiroFilter's 'filters' Map if desired. See its JavaDoc for more details. --> +<bean id="someFilter" class="..."/> +<bean id="anotherFilter" class="..."> ... </bean> +... + +<bean id="securityManager" class="org.apache.shiro.web.mgt.DefaultWebSecurityManager"> + <!-- Single realm app. If you have multiple realms, use the 'realms' property instead. --> + <property name="realm" ref="myRealm"/> + <!-- By default the servlet container sessions will be used. Uncomment this line + to use shiro's native sessions (see the JavaDoc for more): --> + <!-- <property name="sessionMode" value="native"/> --> +</bean> +<bean id="lifecycleBeanPostProcessor" class="org.apache.shiro.spring.LifecycleBeanPostProcessor"/> + +<!-- Define the Shiro Realm implementation you want to use to connect to your back-end --> +<!-- security datasource: --> +<bean id="myRealm" class="..."> + ... +</bean> +``` + +<a name="Spring-EnablingShiroAnnotations"></a> +##Enabling Shiro Annotations + +In both standalone and web applications, you might want to use Shiro's Annotations for security checks (for example, `@RequiresRoles`, `@RequiresPermissions`, etc. This requires Shiro's Spring AOP integration to scan for the appropriate annotated classes and perform security logic as necessary. + +Here is how to enable these annotations. Just add these two bean definitions to `applicationContext.xml`: + +``` xml +<!-- Enable Shiro Annotations for Spring-configured beans. Only run after --> +<!-- the lifecycleBeanProcessor has run: --> +<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator" depends-on="lifecycleBeanPostProcessor"/> + <bean class="org.apache.shiro.spring.security.interceptor.AuthorizationAttributeSourceAdvisor"> + <property name="securityManager" ref="securityManager"/> +</bean> +``` + +<a name="Spring-SecureSpringRemoting"></a> +##Secure Spring Remoting + +There are two parts to Shiro's Spring remoting support: Configuration for the client making the remoting call and configuration for the server receiving and processing the remoting call. + +<a name="Spring-ServersideConfiguration"></a> +###Server-side Configuration + +When a remote method invocation comes in to a Shiro-enabled server, the [Subject](subject.html "Subject") associated with that RPC call must be bound to the receiving thread for access during the thread's execution. This is done by defining Shiro's `SecureRemoteInvocationExecutor` bean in `applicationContext.xml`: + +``` xml +<!-- Secure Spring remoting: Ensure any Spring Remoting method invocations --> +<!-- can be associated with a Subject for security checks. --> +<bean id="secureRemoteInvocationExecutor" class="org.apache.shiro.spring.remoting.SecureRemoteInvocationExecutor"> + <property name="securityManager" ref="securityManager"/> +</bean> +``` + +Once you have defined this bean, you must plug it in to whatever remoting `Exporter` you are using to export/expose your services. `Exporter` implementations are defined according to the remoting mechanism/protocol in use. See Spring's [Remoting chapter](http://docs.spring.io/spring/docs/2.5.x/reference/remoting.html) on defining `Exporter` beans. + +For example, if using HTTP-based remoting (notice the property reference to the `secureRemoteInvocationExecutor` bean): + +``` xml +<bean name="/someService" class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter"> + <property name="service" ref="someService"/> + <property name="serviceInterface" value="com.pkg.service.SomeService"/> + <property name="remoteInvocationExecutor" ref="secureRemoteInvocationExecutor"/> +</bean> +``` + +<a name="Spring-ClientsideConfiguration"></a> +###Client-side Configuration + +When a remote call is being executed, the `Subject` identifying information must be attached to the remoting payload to let the server know who is making the call. If the client is a Spring-based client, that association is done via Shiro's `SecureRemoteInvocationFactory`: + +``` xml +<bean id="secureRemoteInvocationFactory" class="org.apache.shiro.spring.remoting.SecureRemoteInvocationFactory"/> +``` + +Then after you've defined this bean, you need to plug it in to the protocol-specific Spring remoting `ProxyFactoryBean` you're using. + +For example, if you were using HTTP-based remoting (notice the property reference to the `secureRemoteInvocationFactory` bean defined above): + +``` xml +<bean id="someService" class="org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean"> + <property name="serviceUrl" value="http://host:port/remoting/someService"/> + <property name="serviceInterface" value="com.pkg.service.SomeService"/> + <property name="remoteInvocationFactory" ref="secureRemoteInvocationFactory"/> +</bean> +``` + +<a name="Spring-Lendahandwithdocumentation"></a> +##Lend a hand with documentation + +While we hope this documentation helps you with the work you're doing with Apache Shiro, the community is improving and expanding the documentation all the time. If you'd like to help the Shiro project, please consider corrected, expanding, or adding documentation where you see a need. Every little bit of help you provide expands the community and in turn improves Shiro. + +The easiest way to contribute your documentation is to send it to the [User Forum](http://shiro-user.582556.n2.nabble.com/) or the [User Mailing List](mailing-lists.html "Mailing Lists"). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/version-2-brainstorming.html ---------------------------------------------------------------------- diff --git a/version-2-brainstorming.html b/version-2-brainstorming.html deleted file mode 100644 index 763b0a4..0000000 --- a/version-2-brainstorming.html +++ /dev/null @@ -1,199 +0,0 @@ -<div> -<ul><li><a href="#Version2Brainstorming-RenameAuthenticationInfotoAccount">Rename AuthenticationInfo to Account</a></li><li><a href="#Version2Brainstorming-Realmrefactoring">Realm refactoring</a></li><li><a href="#Version2Brainstorming-Splitshirocoreintomodules">Split shiro-core into modules</a></li><li><a href="#Version2Brainstorming-Eventdrivendesign">Event-driven design</a></li><li><a href="#Version2Brainstorming-SubjectPrincipalCollection">Subject PrincipalCollection</a></li><li><a href="#Version2Brainstorming-ComponentNames">Component Names</a></li><li><a href="#Version2Brainstorming-AuthorizationANTLRGrammar">Authorization ANTLR Grammar</a></li><li><a href="#Version2Brainstorming-AuthorizationRequest%2FResponse">AuthorizationRequest/Response</a></li><li><a href="#Version2Brainstorming-ReinforcecustomizationviaOODelegation%28compositionoverinheritance%29">Reinforce customization via OO Delegation (composition over inheritance)</a></li><li><a href="#Version2Brainstorming-MultiSt ageAuthenticationviarequest%2Fresponse">Multi-Stage Authentication via request/response</a></li><li><a href="#Version2Brainstorming-CaptchaSupport">Captcha Support</a></li><li><a href="#Version2Brainstorming-Configurationperfilterinstanceandnopathmatching">Configuration per filter instance and no path matching</a></li><li><a href="#Version2Brainstorming-Webmodulerepackaging.">Web module repackaging.</a></li></ul></div> - -<p>There is currently no timeline for a version 2, but this space represents any brainstorming efforts that the community wishes to address that may be major feature enhancements that can't be backwards compatible. Typically discussions from the dev list resulting in some form of consensus will probably make it into this page. Actionable items will go into Jira, potentially referencing this page for clarity.</p> - -<ul class="alternate" type="square"><li>(I know this isn't a feature but its equally is not more important) Deeper and more accessible documentation and how-tos.</li><li>management system for long lived hashes</li><li>token/ticket system</li><li>more generalized way to handle unauthorized exceptions</li><li>lower level crypto toolkit to facilitate customizations</li><li>unauthorizedUrl per path filter</li></ul> - - -<h3><a name="Version2Brainstorming-RenameAuthenticationInfotoAccount"></a>Rename AuthenticationInfo to Account</h3> - -<p>The existing <tt>AuthenticationInfo</tt> name is less intuitive and is essentially the same thing.</p> - -<h3><a name="Version2Brainstorming-Realmrefactoring"></a>Realm refactoring</h3> - -<p>Most Realms differ little in their implementations - mostly by the protocols they use. Create a 'DefaultRealm' implementation (or something similar) that allows pluggable AccountResolver and AuthorizationResolver interfaces that abstract away interaction with the data stores and the rest of the internal Realm logic (e.g. authc and authz caching, etc) can be shared by most Realm implementation.</p> - -<h3><a name="Version2Brainstorming-Splitshirocoreintomodules"></a>Split shiro-core into modules</h3> - -<p>Maybe shiro-core should be split up into separate modules (e.g. shiro-crypto, shiro-authc, shiro-authz, etc) if possible. This may or may not be possible due to the tight integration of APIs (e.g. Shiro authentication depends on shiro hashing (crypto) etc). A cursory investigation should be made if possible.</p> - -<h3><a name="Version2Brainstorming-Eventdrivendesign"></a>Event-driven design</h3> -<p><b>This can be in 1.3+ as these would be all new packages/classes and do not require signature changes to existing code</b></p> - -<p>Utilize events significantly and more effectively. Base on Akka's event model and <a class="external-link" href="http://code.google.com/p/guava-libraries/wiki/EventBusExplained"; rel="nofollow">Guava's EventBus</a>. This enables ideal loose coupling/high cohesion plugins/integration/customization.</p> - -<p>Package: <tt>org.apache.shiro.event</tt></p> - -<p>Potential classes:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class ShiroEvent <span class="code-keyword">extends</span> EventObject { - - <span class="code-keyword">private</span> <span class="code-keyword">final</span> <span class="code-object">long</span> timestamp; <span class="code-comment">//millis since Epoch (UTC time zone). -</span> - <span class="code-keyword">public</span> ShiroEvent(<span class="code-object">Object</span> source) { - <span class="code-keyword">super</span>(source); - <span class="code-keyword">this</span>.timestamp = <span class="code-keyword">new</span> Date().getTime(); - } - - <span class="code-keyword">public</span> <span class="code-object">long</span> getTimestamp() { - <span class="code-keyword">return</span> timestamp; - } -} -</pre> -</div></div> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-keyword">interface</span> Publisher { - - void publish(<span class="code-object">Object</span> event); -} -</pre> -</div></div> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - -/** Marker annotation <span class="code-keyword">for</span> a method that wishes to receive a particular event instance. */ -<span class="code-keyword">public</span> @<span class="code-keyword">interface</span> Subscribe { -} -</pre> -</div></div> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> - -/** - * Listener implementations just annotate a method as @Subscribe. - * The single method argument determines the type of event received. - */ -<span class="code-keyword">public</span> class MyListener { - - @Subscribe - <span class="code-keyword">public</span> void doSomething(SomeEvent event) { - ... - } -} - -</pre> -</div></div> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> <span class="code-keyword">interface</span> SubscriberRegistry { - - void register(<span class="code-object">Object</span> subscriber); - - void unregister(<span class="code-object">Object</span> subscriber); -} -</pre> -</div></div> - -<p>An EventBus can be created based on Publisher + SubscriberRegistry:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -<span class="code-keyword">public</span> class SynchronousEventBus <span class="code-keyword">implements</span> Publisher, SubscriberRegistry { - ... -} -</pre> -</div></div> - -<h3><a name="Version2Brainstorming-SubjectPrincipalCollection"></a>Subject PrincipalCollection</h3> - -<p>Convert this to be a sub-interface of Map with additional per-Realm utility methods.</p> - -<p>See the <a class="external-link" href="https://github.com/apache/shiro/blob/master/core/src/main/java/org/apache/shiro/subject/PrincipalMap.java";>PrincipalMap</a> concept for ideas (experimental, not referenced in Shiro 1.x at the moment).</p> - -<p>Maybe rename this to 'attributes'? i.e. <tt>subject.getAttributes()</tt>?</p> - -<h3><a name="Version2Brainstorming-ComponentNames"></a>Component Names</h3> - -<p>Change classes named FooDAO to FooStore instead.</p> - -<h3><a name="Version2Brainstorming-AuthorizationANTLRGrammar"></a>Authorization ANTLR Grammar</h3> - -<p>Ideally, we can have a single annotation:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Secured(<span class="code-quote">"authz expression here"</span>) -<span class="code-keyword">public</span> void someMethod(){...} -</pre> -</div></div> - -<p>Where the 'authz expression here' is authorization assertion statement backed by an ANTLR lexer/parser, for example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -@Secured(<span class="code-quote">"(role(admin) || role(developer)) || perm(account:12345:open)"</span>) -</pre> -</div></div> - -<p>This would translate the expression into the relevant hasRole/isPermitted calls.</p> - -<h3><a name="Version2Brainstorming-AuthorizationRequest%2FResponse"></a>AuthorizationRequest/Response</h3> - -<p>Employing the same grammar as mentioned above, instead of multiple subject.isPermitted/hasRole calls, the same thing could be achieved with an AuthorizationRequest/Response scheme. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -AuthorizationRequest request = <span class="code-comment">//create request w/ expression -</span>AuthorizationResponse response = subject.authorize(authorizationRequest); -<span class="code-keyword">if</span> (response.isAuthorized()) { -... -} <span class="code-keyword">else</span> { -... -} -</pre> -</div></div> - -<h3><a name="Version2Brainstorming-ReinforcecustomizationviaOODelegation%28compositionoverinheritance%29"></a>Reinforce customization via OO Delegation (composition over inheritance)</h3> - -<ul class="alternate" type="square"><li>Any of the features provided by PathMatchingFilter would be provided for any configured filter via a proxy mechanism. The proxy would likely support the PathMatchingFilter features, setting request attributes as necessary for the wrapped filter to react to. This eliminates the need to subclass PathMatchingFilter to utilize these features.</li><li>The same principal would be probably be applied for realms. A DefaultRealm could be created that delegates to an AuthenticationInfoAccessor and AuthorizationInfoAccessor (or whatever we want to call them) that performs the same behavior as AuthenticatingRealm#doGetAuthenticationInfo and AuthorizingRealm#doGetAuthorizationInfo. The end result is no more subclassing realms for 95% of use cases, and instead providing accessors.</li></ul> - - -<h3><a name="Version2Brainstorming-MultiStageAuthenticationviarequest%2Fresponse"></a>Multi-Stage Authentication via request/response</h3> - -<p>In applications that need to authenticate via multiple mechanisms (e.g. multi-factor authentication), a Request/Response protocol for login would probably be easier to use to support such workflows. For example:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -LoginRequest request = <span class="code-comment">//create login request -</span>LoginResponse response = subject.login(request); -<span class="code-keyword">if</span> (!response.isComplete()) { - LoginRequest secondRequest = response.nextRequest(); - <span class="code-comment">//populate w/ data <span class="code-keyword">for</span> 2nd phase -</span> response = subject.login(secondRequest); -} -<span class="code-keyword">if</span> (response.hasException()) { - <span class="code-keyword">throw</span> response.getException(); -} -... -</pre> -</div></div> - -<p>Additionally probably change the Authenticator signature to be as follows:</p> - -<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> -<pre class="code-java"> -AuthenticationResult authenticate(AuthenticationRequest) <span class="code-keyword">throws</span> AuthenticationException; -</pre> -</div></div> - -<h3><a name="Version2Brainstorming-CaptchaSupport"></a>Captcha Support</h3> - -<p>Captcha support would assist in human being verification (during login, during form submission, etc).</p> - -<h3><a name="Version2Brainstorming-Configurationperfilterinstanceandnopathmatching"></a>Configuration per filter instance and no path matching</h3> -<p><a name="Version2Brainstorming-filterperinstance"></a><br clear="none"> -<a class="external-link" href="https://issues.apache.org/jira/browse/SHIRO-256";>SHIRO-256</a> is opened for this and <a class="external-link" href="http://tynamo.org"; rel="nofollow">Tynamo.org</a> already has an implementation for it. This would both simplify the filter logic and result in better performance.</p> - -<h3><a name="Version2Brainstorming-Webmodulerepackaging."></a>Web module repackaging.</h3> - -<p>The Web module is largely Servlet-specific at the moment. As such, its packaging should reflect this, in the same way that all other support modules are named, e.g. <br clear="none"> -module name: <tt>shiro-servlet</tt><br clear="none"> -package base: <tt>org.apache.shiro.servlet.*</tt></p> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/shiro-site/blob/585f8465/version-2-brainstorming.md ---------------------------------------------------------------------- diff --git a/version-2-brainstorming.md b/version-2-brainstorming.md new file mode 100644 index 0000000..eba4219 --- /dev/null +++ b/version-2-brainstorming.md @@ -0,0 +1,205 @@ + +* [Rename AuthenticationInfo to Account](#Version2Brainstorming-RenameAuthenticationInfotoAccount) +* [Realm refactoring](#Version2Brainstorming-Realmrefactoring) +* [Split shiro-core into modules](#Version2Brainstorming-Splitshirocoreintomodules) +* [Event-driven design](#Version2Brainstorming-Eventdrivendesign) +* [Subject PrincipalCollection](#Version2Brainstorming-SubjectPrincipalCollection) +* [Component Names](#Version2Brainstorming-ComponentNames) +* [Authorization ANTLR Grammar](#Version2Brainstorming-AuthorizationANTLRGrammar) +* [AuthorizationRequest/Response](#Version2Brainstorming-AuthorizationRequest%2FResponse) +* [Reinforce customization via OO Delegation (composition over inheritance)](#Version2Brainstorming-ReinforcecustomizationviaOODelegation%28compositionoverinheritance%29) +* [Multi-Stage Authentication via request/response](#Version2Brainstorming-MultiStageAuthenticationviarequest%2Fresponse) +* [Captcha Support](#Version2Brainstorming-CaptchaSupport) +* [Configuration per filter instance and no path matching](#Version2Brainstorming-Configurationperfilterinstanceandnopathmatching) +* [Web module repackaging.](#Version2Brainstorming-Webmodulerepackaging.) + +There is currently no timeline for a version 2, but this space represents any brainstorming efforts that the community wishes to address that may be major feature enhancements that can't be backwards compatible. Typically discussions from the dev list resulting in some form of consensus will probably make it into this page. Actionable items will go into Jira, potentially referencing this page for clarity. + +* (I know this isn't a feature but its equally is not more important) Deeper and more accessible documentation and how-tos. +* management system for long lived hashes +* token/ticket system +* more generalized way to handle unauthorized exceptions +* lower level crypto toolkit to facilitate customizations +* unauthorizedUrl per path filter + +<a name="Version2Brainstorming-RenameAuthenticationInfotoAccount"></a> +###Rename AuthenticationInfo to Account + +The existing `AuthenticationInfo` name is less intuitive and is essentially the same thing. + +<a name="Version2Brainstorming-Realmrefactoring"></a> +###Realm refactoring + +Most Realms differ little in their implementations - mostly by the protocols they use. Create a 'DefaultRealm' implementation (or something similar) that allows pluggable AccountResolver and AuthorizationResolver interfaces that abstract away interaction with the data stores and the rest of the internal Realm logic (e.g. authc and authz caching, etc) can be shared by most Realm implementation. + +<a name="Version2Brainstorming-Splitshirocoreintomodules"></a> +###Split shiro-core into modules + +Maybe shiro-core should be split up into separate modules (e.g. shiro-crypto, shiro-authc, shiro-authz, etc) if possible. This may or may not be possible due to the tight integration of APIs (e.g. Shiro authentication depends on shiro hashing (crypto) etc). A cursory investigation should be made if possible. + +<a name="Version2Brainstorming-Eventdrivendesign"></a> +###Event-driven design + +**This can be in 1.3+ as these would be all new packages/classes and do not require signature changes to existing code** + +Utilize events significantly and more effectively. Base on Akka's event model and [Guava's EventBus](http://code.google.com/p/guava-libraries/wiki/EventBusExplained). This enables ideal loose coupling/high cohesion plugins/integration/customization. + +Package: `org.apache.shiro.event` + +Potential classes: + +``` java +public class ShiroEvent extends EventObject { + + private final long timestamp; //millis since Epoch (UTC time zone). + public ShiroEvent(Object source) { + super(source); + this.timestamp = new Date().getTime(); + } + + public long getTimestamp() { + return timestamp; + } +} +``` + +``` java + +public interface Publisher { + + void publish(Object event); +} +``` + +``` java +/** Marker annotation for a method that wishes to receive a particular event instance. */ +public @interface Subscribe { +} +``` + +``` java +/** + * Listener implementations just annotate a method as @Subscribe. + * The single method argument determines the type of event received. + */ +public class MyListener { + + @Subscribe + public void doSomething(SomeEvent event) { + ... + } +} +``` + +``` java +public interface SubscriberRegistry { + + void register(Object subscriber); + + void unregister(Object subscriber); +} +``` + +An EventBus can be created based on Publisher + SubscriberRegistry: + +``` java +public class SynchronousEventBus implements Publisher, SubscriberRegistry { + ... +} +``` + +<a name="Version2Brainstorming-SubjectPrincipalCollection"></a> +###Subject PrincipalCollection + +Convert this to be a sub-interface of Map with additional per-Realm utility methods. + +See the [PrincipalMap](https://github.com/apache/shiro/blob/master/core/src/main/java/org/apache/shiro/subject/PrincipalMap.java) concept for ideas (experimental, not referenced in Shiro 1.x at the moment). + +Maybe rename this to 'attributes'? i.e. `subject.getAttributes()`? + +<a name="Version2Brainstorming-ComponentNames"></a> +###Component Names + +Change classes named FooDAO to FooStore instead. + +<a name="Version2Brainstorming-AuthorizationANTLRGrammar"></a> +###Authorization ANTLR Grammar + +Ideally, we can have a single annotation: + +``` java +@Secured("authz expression here") +public void someMethod(){...} +``` + +Where the 'authz expression here' is authorization assertion statement backed by an ANTLR lexer/parser, for example: + +``` java +@Secured("(role(admin) || role(developer)) || perm(account:12345:open)") +``` + +This would translate the expression into the relevant hasRole/isPermitted calls. + +<a name="Version2Brainstorming-AuthorizationRequest%2FResponse"></a> +###AuthorizationRequest/Response + +Employing the same grammar as mentioned above, instead of multiple subject.isPermitted/hasRole calls, the same thing could be achieved with an AuthorizationRequest/Response scheme. For example: + +``` java +AuthorizationRequest request = //create request w/ expression +AuthorizationResponse response = subject.authorize(authorizationRequest); +if (response.isAuthorized()) { +... +} else { +... +} +``` + +<a name="Version2Brainstorming-ReinforcecustomizationviaOODelegation%28compositionoverinheritance%29"></a> +###Reinforce customization via OO Delegation (composition over inheritance) + +* Any of the features provided by PathMatchingFilter would be provided for any configured filter via a proxy mechanism. The proxy would likely support the PathMatchingFilter features, setting request attributes as necessary for the wrapped filter to react to. This eliminates the need to subclass PathMatchingFilter to utilize these features. +* The same principal would be probably be applied for realms. A DefaultRealm could be created that delegates to an AuthenticationInfoAccessor and AuthorizationInfoAccessor (or whatever we want to call them) that performs the same behavior as AuthenticatingRealm#doGetAuthenticationInfo and AuthorizingRealm#doGetAuthorizationInfo. The end result is no more subclassing realms for 95% of use cases, and instead providing accessors. + +<a name="Version2Brainstorming-MultiStageAuthenticationviarequest%2Fresponse"></a> +###Multi-Stage Authentication via request/response + +In applications that need to authenticate via multiple mechanisms (e.g. multi-factor authentication), a Request/Response protocol for login would probably be easier to use to support such workflows. For example: + +``` java +LoginRequest request = //create login request +LoginResponse response = subject.login(request); +if (!response.isComplete()) { + LoginRequest secondRequest = response.nextRequest(); + //populate w/ data for 2nd phase + response = subject.login(secondRequest); +} +if (response.hasException()) { + throw response.getException(); +} +... +``` + +Additionally probably change the Authenticator signature to be as follows: + +``` java +AuthenticationResult authenticate(AuthenticationRequest) throws AuthenticationException; +``` + +<a name="Version2Brainstorming-CaptchaSupport"></a> +###Captcha Support + +Captcha support would assist in human being verification (during login, during form submission, etc). + +<a name="Version2Brainstorming-Configurationperfilterinstanceandnopathmatching"></a> +###Configuration per filter instance and no path matching + +<a name="Version2Brainstorming-filterperinstance"></a> +[SHIRO-256](https://issues.apache.org/jira/browse/SHIRO-256) is opened for this and [Tynamo.org](http://tynamo.org) already has an implementation for it. This would both simplify the filter logic and result in better performance. + +<a name="Version2Brainstorming-Webmodulerepackaging."></a> +###Web module repackaging. + +The Web module is largely Servlet-specific at the moment. As such, its packaging should reflect this, in the same way that all other support modules are named, e.g. +module name: `shiro-servlet` +package base: `org.apache.shiro.servlet.*` \ No newline at end of file
