For users that prefer to use forums over mailing lists, we use the Nabble forum/email/archive service. Nabble ensures that its forums remain synchronized with the mailing lists, so feel free to use whichever mechanism you like.
- - - - - -For those that may prefer mailing lists, please see the Mailing Lists information.
\ No newline at end of file diff --git a/forums.md b/forums.md new file mode 100644 index 0000000000..4590bf1af5 --- /dev/null +++ b/forums.md @@ -0,0 +1,12 @@ + +#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/) + + +##Mailing Lists + +For those that may prefer mailing lists, please see the [Mailing Lists](mailing-lists.html) information. \ No newline at end of file diff --git a/guides.html b/guides.html deleted file mode 100644 index d078f03bde..0000000000 --- a/guides.html +++ /dev/null @@ -1,13 +0,0 @@ -Here are some basic guides on how to use Shiro.
- -Please post any errata to the user or dev mailing lists.
- - - - - - - - diff --git a/guides.md b/guides.md new file mode 100644 index 0000000000..1ca77b872e --- /dev/null +++ b/guides.md @@ -0,0 +1,12 @@ + +#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 diff --git a/issues.html b/issues.html deleted file mode 100644 index 80d7435eef..0000000000 --- a/issues.html +++ /dev/null @@ -1,13 +0,0 @@ -Apache Shiro uses Atlassian Jira for tracking tasks, feature requests, bugs, and other issues related to the project development.
- -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 page.
- -Prior to using Jira, we ask that:
-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.
- -For Spring, you can look into our Spring Integration documentation.
- -Once you have AOP enabled in our application, you can use Shiro's set of annotations found in the Java Annotations List
- -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 or the User Mailing List.
\ No newline at end of file diff --git a/java-annotations.md b/java-annotations.md new file mode 100644 index 0000000000..0f47cd8023 --- /dev/null +++ b/java-annotations.md @@ -0,0 +1,20 @@ + +#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. + + +##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") + + +##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 diff --git a/spring.html b/spring.html deleted file mode 100644 index 96b2b3ffc1..0000000000 --- a/spring.html +++ /dev/null @@ -1,225 +0,0 @@ -|
-
-
-
-Web Apps with Shiro-Detailed support for integrating Shiro into web applications. Read More >> - -Web App Tutorial-Step-by-step tutorial for securing a web application with Shiro. Read More >> - - |
-
This page covers the ways to integrate Shiro into Spring-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.
- -Here is the simplest way to enable an application singleton SecurityManager in Spring applications:
- --<!-- 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> --
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:
- -In addition to your other Spring web.xml elements (ContextLoaderListener, Log4jConfigListener, etc), define the following filter and filter mapping:
- --<!-- 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> --
In your applicationContext.xml file, define the web-enabled SecurityManager and the 'shiroFilter' bean that will be referenced from web.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> --
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:
- --<!-- 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> --
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.
- -When a remote method invocation comes in to a Shiro-enabled server, the 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:
- --<!-- 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 on defining Exporter beans.
- -For example, if using HTTP-based remoting (notice the property reference to the secureRemoteInvocationExecutor bean):
- --<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> --
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:
- -
-<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):
- --<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> --
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 or the User Mailing List.
diff --git a/spring.md b/spring.md new file mode 100644 index 0000000000..e5a6a4e7c8 --- /dev/null +++ b/spring.md @@ -0,0 +1,214 @@ + +#Integrating Apache Shiro into Spring-based Applications + +|
+
+
+
+Web Apps with Shiro+Detailed support for integrating Shiro into web applications. Web App Tutorial+Step-by-step tutorial for securing a web application with Shiro. |
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.
- -The existing AuthenticationInfo name is less intuitive and is essentially the same thing.
- -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.
- -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.
- -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. This enables ideal loose coupling/high cohesion plugins/integration/customization.
- -Package: org.apache.shiro.event
- -Potential classes:
- --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; - } -} --
-public interface Publisher { - - void publish(Object event); -} --
- -/** Marker annotation for a method that wishes to receive a particular event instance. */ -public @interface Subscribe { -} --
- -/** - * 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) { - ... - } -} - --
-public interface SubscriberRegistry { - - void register(Object subscriber); - - void unregister(Object subscriber); -} --
An EventBus can be created based on Publisher + SubscriberRegistry:
- --public class SynchronousEventBus implements Publisher, SubscriberRegistry { - ... -} --
Convert this to be a sub-interface of Map with additional per-Realm utility methods.
- -See the PrincipalMap concept for ideas (experimental, not referenced in Shiro 1.x at the moment).
- -Maybe rename this to 'attributes'? i.e. subject.getAttributes()?
- -Change classes named FooDAO to FooStore instead.
- -Ideally, we can have a single annotation:
- --@Secured("authz expression here") -public void someMethod(){...} --
Where the 'authz expression here' is authorization assertion statement backed by an ANTLR lexer/parser, for example:
- -
-@Secured("(role(admin) || role(developer)) || perm(account:12345:open)")
-
-This would translate the expression into the relevant hasRole/isPermitted calls.
- -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:
- --AuthorizationRequest request = //create request w/ expression -AuthorizationResponse response = subject.authorize(authorizationRequest); -if (response.isAuthorized()) { -... -} else { -... -} --
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:
- --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:
- -
-AuthenticationResult authenticate(AuthenticationRequest) throws AuthenticationException;
-
-Captcha support would assist in human being verification (during login, during form submission, etc).
- -
-SHIRO-256 is opened for this and Tynamo.org already has an implementation for it. This would both simplify the filter logic and result in better performance.
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.*