Author: echatellier Date: 2012-10-18 16:27:48 +0200 (Thu, 18 Oct 2012) New Revision: 220 Url: http://nuiton.org/repositories/revision/nuiton-web/220 Log: Add documentation Added: branches/nuiton-web-1.11-security/nuiton-security/src/site/ branches/nuiton-web-1.11-security/nuiton-security/src/site/apt/ branches/nuiton-web-1.11-security/nuiton-security/src/site/apt/index.apt branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/ branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/ branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/permissions.png branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/roles.png branches/nuiton-web-1.11-security/nuiton-security/src/site/site.xml Added: branches/nuiton-web-1.11-security/nuiton-security/src/site/apt/index.apt =================================================================== --- branches/nuiton-web-1.11-security/nuiton-security/src/site/apt/index.apt (rev 0) +++ branches/nuiton-web-1.11-security/nuiton-security/src/site/apt/index.apt 2012-10-18 14:27:48 UTC (rev 220) @@ -0,0 +1,181 @@ +~~~ +~~ #%L +~~ Nuiton Web :: Nuiton Security +~~ +~~ $Id: index.apt 152 2011-12-01 17:16:59Z athimel $ +~~ $HeadURL: http://svn.nuiton.org/svn/nuiton-web/trunk/nuiton-struts2/src/site/apt/index... $ +~~ %% +~~ Copyright (C) 2012 CodeLutin, Chatellier Eric +~~ %% +~~ This program is free software: you can redistribute it and/or modify +~~ it under the terms of the GNU Lesser General Public License as +~~ published by the Free Software Foundation, either version 3 of the +~~ License, or (at your option) any later version. +~~ +~~ This program is distributed in the hope that it will be useful, +~~ but WITHOUT ANY WARRANTY; without even the implied warranty of +~~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +~~ GNU General Lesser Public License for more details. +~~ +~~ You should have received a copy of the GNU General Lesser Public +~~ License along with this program. If not, see +~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. +~~ #L% +~~~ + + ---- + Nuiton Web Security + ---- + ---- + 2012-10-18 + ---- + + This document decribe how to add nuiton-web security module in an existing + web application. + +Application Config + + Module configuration is based on {{{http://maven-site.nuiton.org/nuiton-utils/nuiton-utils/apidocs/org/nuiton/util/ApplicationConfig.html}ApplicationConfig}} + class. An instance of this class must be set into ServletContext in order + to security module to use it. + + For example, on your application ServletContextListener, just add this kind + of code: + +-------------------------------------------------------------------------------- +@Override +public void contextInitialized(ServletContextEvent sce) { + + // add application config in servlet context for security module filter + ApplicationConfig config = ...; + sce.getServletContext().setAttribute(SecurityShiroFilter.APP_CONFIG_CONTEXT, config); +} +-------------------------------------------------------------------------------- + +Filter + + This next step to do is it add a Filter into the web.xml file: + +-------------------------------------------------------------------------------- +<filter> + <filter-name>ShiroFilter</filter-name> + <filter-class>org.nuiton.web.security.SecurityShiroFilter</filter-class> +</filter> + +<filter-mapping> + <filter-name>ShiroFilter</filter-name> + <url-pattern>/*</url-pattern> + <dispatcher>REQUEST</dispatcher> + <dispatcher>FORWARD</dispatcher> + <dispatcher>INCLUDE</dispatcher> + <dispatcher>ERROR</dispatcher> +</filter-mapping> +-------------------------------------------------------------------------------- + +ToPIA configuration + + The security module use ToPIA as his persistence layer. The configuration + must contains the hibernate configuration used to connect to database. + + For example for a PostgreSQL database: + +-------------------------------------------------------------------------------- +hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect +hibernate.connection.url=jdbc:postgresql://localhost/mydbname +hibernate.connection.username=myuser +hibernate.connection.password=mypass +-------------------------------------------------------------------------------- + +Permission configuration + + The last step to do is to configure the permissions list and urls used by the + application. + + Here is the syntax: + +-------------------------------------------------------------------------------- +topia.security.loginurl=/security/login.action +topia.security.logouturl=/security/logout.action + +topia.security.permission.<category>=categoryname +topia.security.permission.<category>.<permission>.name=permissionname +topia.security.permission.<category>.<permission>.perm=permission, urlpermissions +-------------------------------------------------------------------------------- + + The configuration define two url, loginurl and logouturl used to redirect user + when he is not authenticated or he want to unlog. + + Next, there is the permission list divided by category. Each category has + a display name and a permissions list. Each permissions has also a display + name and a list of shiro permission. + + Shiro permission are composed of normal shiro permission and url permissions + used by module to filter access to requested page for current authentified + shiro subject. + + Here is an example of configuration: + +-------------------------------------------------------------------------------- +topia.security.loginurl=/security/login.action +topia.security.logouturl=/security/logout.action + +topia.security.permission.global=Global +topia.security.permission.global.index.name=Index +topia.security.permission.global.index.perm=index:read, url:/, url:index.action +topia.security.permission.global.search.name=Rechercher +topia.security.permission.global.search.perm=search:read, url:user:search.action +topia.security.permission.global.placesread.name=Emplacements +topia.security.permission.global.placesread.perm=places:read, url:user:places.action + +topia.security.permission.misc=Divers +topia.security.permission.misc.deco.name=Decoration +topia.security.permission.misc.deco.perm=url:css, url:images, url:js +topia.security.permission.misc.admin.name=Admin +topia.security.permission.misc.admin.perm=* +-------------------------------------------------------------------------------- + +Screenshots + + Here is a couple of screenshot showing how library permission and role + management look like: + +* Role management + +[img/roles.png] Roles management + +* Permissions management + +[img/permissions.png] Permissions management + +Maven + + As of 1.12 version, this module comes with his own jsp, your don't have to + write it yourself. This jsps can be extracted during build using maven with + following plugin configuration: + +-------------------------------------------------------------------------------- +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-dependency-plugin</artifactId> + <executions> + <execution> + <phase>generate-resources</phase> + <goals> + <goal>unpack</goal> + </goals> + <configuration> + <artifactItems> + <artifactItem> + <groupId>org.nuiton.web</groupId> + <artifactId>nuiton-security</artifactId> + <version>1.12</version> + <type>jar</type> + </artifactItem> + </artifactItems> + <includes>WEB-INF/security/*</includes> + <outputDirectory>${project.build.directory}/${project.build.finalName}</outputDirectory> + </configuration> + </execution> + </executions> +</plugin> +-------------------------------------------------------------------------------- \ No newline at end of file Added: branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/permissions.png =================================================================== (Binary files differ) Property changes on: branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/permissions.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/roles.png =================================================================== (Binary files differ) Property changes on: branches/nuiton-web-1.11-security/nuiton-security/src/site/resources/img/roles.png ___________________________________________________________________ Added: svn:mime-type + image/png Added: branches/nuiton-web-1.11-security/nuiton-security/src/site/site.xml =================================================================== (Binary files differ) Property changes on: branches/nuiton-web-1.11-security/nuiton-security/src/site/site.xml ___________________________________________________________________ Added: svn:mime-type + application/xml