An Introduction to Shiro (formerly JSecurity) – A Beginner’s Tutorial Part 5


NOTE: Updated in December 2013.

In part 4 of this series, I explained how you can use Shiro's tag library to control what is rendered in the JSPs. In part 3 of this series, I explained how you can use a users role to control access to specific parts of a web application. In this part of the series, I demonstrate how you can add another level of security to your web application by using permissions. Each role (e.g. admin, user) can have one or more permissions associated with it. Using Shiro you can restrict what someone can access based upon permission.

Using Permission to Control Access

In this example, our web application has three areas needing to be secured:


Our business rules for securing each area are:

/users – user is authenticated and has role of user
/staff – user is authenticated and has role of staff or role of admin
/admin – user is authenticated and has role of admin

Since roles staff and admin both need to access the staff area, we can use permissions to control access to that area. We can assign the same permission to both the staff and admin role. We'll call that permission "secure." Any user with permission of "secure" can access the pages in the staff area. If in the future we add additional roles that need to access the staff area, we can give those new roles the "secure" permission also.

So our revised security business rules for each area are:

/users – user is authenticated and has role of user
/staff – user is authenticated and has permission of secure
/admin – user is authenticated and has role of admin

Here are our three users, their roles, and their permissions:














Applying our security business rules to these users we can identify who will be able to access which areas:

/user – only sue
/staff – both bruce and jack but not sue
/admin - only bruce

Example Application

You can download an example application (an archived Eclipse dynamic web project using Maven). You'll also need to download a new version of the securityDB Derby database that includes the roles_permissions table.

After downloading the securityDB Derby database, unzip it to the folder c:/derby. It's OK to overwrite the database that was there as this new version of the securityDB database should work for the previous example applications.

Be sure to update the path to the securityDB in context.xml before building the .war file or running the Maven goal described below.

You can use the Maven Tomcat plugin (see reference below for how to install Maven if you've don't already have Maven) to run the web application if you're not using Eclipse and Tomcat. Just open a command window and navigate to where you unzipped the download. Make sure you're in the permissionsecuritywithtags directory. Then do the following:

mvn -e clean tomcat7:run-war

Once you see [INFO] Started Servlet Engine in the command window, open your web browser and go to this URL: http://localhost:8080/ permissionsecuritywithtags/ . You should see the contents of the index.jsp. To stop the Tomcat server type control-c in the command window.

Login as each user (,, and When you're logged in as try to go to either http://localhost:8080/permissionsecuritywithtags/staff/index.jsp or http://localhost:8080/permissionsecuritywithtags/admin/index.jsp. You should be redirected to the unauthorized web page. When you're logged in as try to go to the http://localhost:8080/permissionsecuritywithtags/admin/index.jsp page.

Implementing Permission Security in Shiro

So how do we implement security that uses permissions in Shiro? When you attempt to authenticate a user, Shiro will look for any permissions associated with the role that is associated with that user. To use Shiro's default configuration you just need a table named roles_permissions with a column named role_name and a column named permission. The default permissions query is specified in class JdbcRealm, which my class RoleSecurityJdbcRealm extended. In web.xml I specified this class as the value for the IniShiroFilter's realm (a realm is a resource that Shiro will use to authenticate users).

If your project cannot follow Shiro's defaults, you can configure Shiro to use your projects conventions (see the Shiro references below).

In Servlet class LoginUser I created a Subject object and call the Subject class's login method passing it the UsernamePasswordToken object that has the user's username and password. If Shiro can successfully authenticate this user by querying the users table, Shiro will then query the user_roles table for roles associated with this username, and then query the roles_permissions table for permissions associated with each role_name associated with this username. All of this information will be stored in the Subject object and placed into session scope. For more information on interfaces Subject and its associated interfaces AuthenticationInfo and and AuthorizationInfo see the Shiro API.

If you examine the web.xml you'll see the following statements in the configuration for the IniShiroFilter:

realmA = name.brucephillips.somesecurity.dao.RoleSecurityJdbcRealm

roles.unauthorizedUrl = /unauthorized.jsp
perms.unauthorizedUrl = /unauthorized.jsp

#only let authenticated users
#with the appropriate role or permission
#view the web pages in the staff, user,
#and admin areas
/staff/** = authc, perms[secure]
/admin/** = authc, roles[admin]
/user/** = authc, roles[user]

Under the [main] section the realmA.permissionsLookupEnabled=true configures Shiro to also lookup the permissions associated with a role. By default permissions lookup is false.

The statement perms.unauthorizedUrl = /unauthorized.jsp tells the filter to redirect people who attempt to view a web page in an area of the site for which they don't have the correct permission to the unauthorized.jsp web page.

The statement /staff/** = authc, perms[secure] means only allow people who have logged in successfully and have a permission of secure to view pages in the /staff folder.

In the Servlet you'll find this statement around line number 134:

if (subject.isPermitted("secure") )

This statement uses the isPermitted method of the Subject class. This method returns true if the Subject object has the permission sent as the argument, otherwise the isPermitted method returns false.

Shiro also has a tag you can use to check a user's permission. In the JSP /index.jsp I use the hasPermission tag (around line 21) to render content for only those users with the secure permission.


Shiro is a comprehensive security library that gives you control over all aspects of your web application. By using permissions you can enable more specific access rules.


  1. An Introduction to Shiro (formerly JSecurity) – A Beginner's Tutorial Part 4, /blog/index.cfm/2009/4/5/An-Introduction-to-Ki-formerly-JSecurity--A-Beginners--Tutorial-Part-4
  2. An Introduction to Shiro (formerly JSecurity) – A Beginner's Tutorial Part 3, /blog/index.cfm/2009/4/5/An-Introduction-to-Ki-formerly-JSecurity--A-Beginners--Tutorial-Part-3
  3. Permission Security With Tags Example Application, /jsecurity_examples/
  4. Apache Shiro
  5. Apache Shiro API,
  6. Apache Shiro Tags API,
  7. Apache Shiro Mailing Lists,
  8. Shiro Custom Tags TLD, /jsecurity_examples/ki%20(jsecurity)%20tld.pdf
  9. Using Custom Tags, J2EE Tutorial,
  10. Apache Derby,
  11. Apache Tomcat,
  12. Jetty,
  13. tp://
  14. Maven: The Definitive Guide,
  15. Developing with Eclipse and Maven,

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
I downloaded the sample project and found it misspelled as "persmissionsecuritywithtags". To get this to run you will need to use http://localhost:8080/persmissionsecuritywithtags/...
# Posted By Gordon Dickens | 5/5/09 2:12 PM
Gordon - thank you for letting me know about the problem.

I uploaded a new archived project with the correct artifactID in the pom.xml. You should be able to download that project, unzip, and run the mvn commands as specified in the article.

Then load the application using this URL:

# Posted By Bruce | 5/5/09 7:25 PM
I wanted to convert the demo over to use the Apache Ki classes (replacing the former JSecurity) and had to make the following changes:
1. changed the pom.xml to import the following dependencies:

2. Changed the tag URL in the jsp pages to:
<%@ taglib prefix="jsec" uri=""; %>

3. Changed the JSecurityFilter in web.xml

4. Modified all the Java classes to use the classes from package:*

Hope this helps.
# Posted By Gordon Dickens | 5/8/09 10:22 AM
Gordon - thank you for posting how to convert an application to use the Apache Ki classes. I need to do this for a project at my job so what you've done is very helpful.
# Posted By Bruce | 5/8/09 11:33 AM
can you please provide DDL to define shiro database tables?
# Posted By Larry | 6/19/12 8:54 AM
Gordon - try generating the DDL from the securityDB database, which is a Derby database. Most IDE's have a database plugin that will work with Derby databases.

I don't have the DDL handy.

# Posted By Bruce | 6/19/12 10:23 AM
Hi. Thanks to the tutorials again.
When I run the project with jetty-run, I am able to view the home page then following login page. But I can't pass the the login page, caused "LOGIN NOT SUCCESSFUL".
Here are the exceptions I get:
javax.naming.NoInitialContextException: Need to specify class name in environment or system property, or as an applet parameter, or in an application resource file: java.naming.factory.initial
   at javax.naming.spi.NamingManager.getInitialContext(
   at javax.naming.InitialContext.getDefaultInitCtx(
   at javax.naming.InitialContext.getURLOrDefaultInitCtx(
   at javax.naming.InitialContext.lookup(
   at name.brucephillips.somesecurity.dao.RoleSecurityJdbcRealm.<init>(
   at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
   at sun.reflect.NativeConstructorAccessorImpl.newInstance(
   at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(
   at java.lang.reflect.Constructor.newInstance(
   at java.lang.Class.newInstance(
   at org.apache.shiro.util.ClassUtils.newInstance(
   at org.apache.shiro.util.ClassUtils.newInstance(
   at org.apache.shiro.config.ReflectionBuilder.createNewInstance(
   at org.apache.shiro.config.ReflectionBuilder.buildObjects(
   at org.apache.shiro.config.IniSecurityManagerFactory.buildInstances(
   at org.apache.shiro.config.IniSecurityManagerFactory.createSecurityManager(
   at org.apache.shiro.config.IniSecurityManagerFactory.createSecurityManager(
   at org.apache.shiro.config.IniSecurityManagerFactory.createInstance(
   at org.apache.shiro.config.IniSecurityManagerFactory.createInstance(
   at org.apache.shiro.config.IniFactorySupport.createInstance(
   at org.apache.shiro.util.AbstractFactory.getInstance(
   at org.apache.shiro.web.servlet.IniShiroFilter.applySecurityManager(
   at org.apache.shiro.web.servlet.IniShiroFilter.configure(
   at org.apache.shiro.web.servlet.IniShiroFilter.init(
   at org.apache.shiro.web.servlet.AbstractShiroFilter.onFilterConfigSet(
   at org.apache.shiro.web.servlet.AbstractFilter.init(
   at org.mortbay.jetty.servlet.FilterHolder.doStart(
   at org.mortbay.component.AbstractLifeCycle.start(
   at org.mortbay.jetty.servlet.ServletHandler.initialize(
   at org.mortbay.jetty.servlet.Context.startContext(
   at org.mortbay.jetty.webapp.WebAppContext.startContext(
   at org.mortbay.jetty.handler.ContextHandler.doStart(
   at org.mortbay.jetty.webapp.WebAppContext.doStart(
   at org.mortbay.component.AbstractLifeCycle.start(
   at org.mortbay.jetty.handler.HandlerWrapper.doStart(
   at org.mortbay.jetty.Server.doStart(
   at org.mortbay.component.AbstractLifeCycle.start(
   at runjettyrun.Bootstrap.main(
2013-12-10 19:42:46.499:INFO::Started SelectChannelConnector@
# Posted By Ça?r? | 12/10/13 8:48 AM
I updated tutorial 5 to now use the Tomcat 7 Maven plugin. Please visit tutorial 5 again and review the changes. There is a new download.

# Posted By Bruce | 12/10/13 9:29 AM
Thanks for update Bruce. But although I added dependencies and configured all the changes needed, still I am getting error with additional TLD exception a little different than the old one. I think it is because of the Shiro filter. Here is the output:
INFO: Server startup in 6840 ms
Ara 13, 2013 7:50:33 AM org.apache.jasper.compiler.TldLocationsCache tldScanJar
INFO: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that were scanned but no TLDs were found in them. Skipping unneeded JARs during scanning can improve startup time and JSP compilation time.
org.apache.shiro.authc.AuthenticationException: Authentication failed for token submission [org.apache.shiro.authc.UsernamePasswordToken -, rememberMe=false]. Possible unexpected error? (Typical or expected login exceptions should extend from AuthenticationException).
   at org.apache.shiro.authc.AbstractAuthenticator.authenticate(
   at org.apache.shiro.mgt.AuthenticatingSecurityManager.authenticate(
   at org.apache.shiro.mgt.DefaultSecurityManager.login(
   at name.brucephillips.somesecurity.servlet.LoginUser.doPost(
   at javax.servlet.http.HttpServlet.service(
   at javax.servlet.http.HttpServlet.service(
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(
   at org.apache.tomcat.websocket.server.WsFilter.doFilter(
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(
   at org.apache.shiro.web.servlet.AbstractShiroFilter.executeChain(
   at org.apache.shiro.web.servlet.AbstractShiroFilter$
   at org.apache.shiro.web.servlet.AbstractShiroFilter.doFilterInternal(
   at org.apache.shiro.web.servlet.OncePerRequestFilter.doFilter(
   at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(
   at org.apache.catalina.core.ApplicationFilterChain.doFilter(
   at org.apache.catalina.core.StandardWrapperValve.invoke(
   at org.apache.catalina.core.StandardContextValve.invoke(
   at org.apache.catalina.authenticator.AuthenticatorBase.invoke(
   at org.apache.catalina.core.StandardHostValve.invoke(
   at org.apache.catalina.valves.ErrorReportValve.invoke(
   at org.apache.catalina.valves.AccessLogValve.invoke(
   at org.apache.catalina.core.StandardEngineValve.invoke(
   at org.apache.catalina.connector.CoyoteAdapter.service(
   at org.apache.coyote.http11.AbstractHttp11Processor.process(
   at org.apache.coyote.AbstractProtocol$AbstractConnectionHandler.process(
   at java.util.concurrent.ThreadPoolExecutor.runWorker(
   at java.util.concurrent.ThreadPoolExecutor$
Caused by: java.lang.IllegalStateException: Connection factory returned null from createConnection
   at org.apache.tomcat.dbcp.dbcp.PoolableConnectionFactory.makeObject(
   at org.apache.tomcat.dbcp.dbcp.BasicDataSource.validateConnectionFactory(
   at org.apache.tomcat.dbcp.dbcp.BasicDataSource.createPoolableConnectionFactory(
   at org.apache.tomcat.dbcp.dbcp.BasicDataSource.createDataSource(
   at org.apache.tomcat.dbcp.dbcp.BasicDataSource.getConnection(
   at org.apache.shiro.realm.jdbc.JdbcRealm.doGetAuthenticationInfo(
   at org.apache.shiro.realm.AuthenticatingRealm.getAuthenticationInfo(
   at org.apache.shiro.authc.pam.ModularRealmAuthenticator.doSingleRealmAuthentication(
   at org.apache.shiro.authc.pam.ModularRealmAuthenticator.doAuthenticate(
   at org.apache.shiro.authc.AbstractAuthenticator.authenticate(
   ... 34 more
Thanks again.
# Posted By Ça?r? | 12/12/13 9:01 PM
double check the path to the securityDB file that is in context.xml to ensure it matches where you put the securityDB folder.
# Posted By Bruce | 12/13/13 7:13 AM
BlogCFC was created by Raymond Camden. This blog is running version Contact Blog Owner