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

Introduction

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:

/users
/staff
/admin

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 permissionsecuritywithtags.zip 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 ([email protected], [email protected], and [email protected]). When you're logged in as [email protected] 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 [email protected] 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:

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 LoginUser.java 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.

Summary

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.

References

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/permissionsecuritywithtags_mvn.zip
4. Apache Shiro http://shiro.apache.org/
5. Apache Shiro API, http://shiro.apache.org/static/current/apidocs/
6. Apache Shiro Tags API, http://shiro.apache.org/static/current/apidocs/org/apache/shiro/web/tags/package-summary.html
7. Apache Shiro Mailing Lists, http://shiro.apache.org/mailing-lists.html
8. Shiro Custom Tags TLD, /jsecurity_examples/ki%20(jsecurity)%20tld.pdf
9. Using Custom Tags, J2EE Tutorial, http://java.sun.com/javaee/5/docs/tutorial/doc/bnaiy.html
10. Apache Derby, http://db.apache.org/derby/
11. Apache Tomcat, http://tomcat.apache.org/
12. Jetty, http://jetty.mortbay.org/jetty5/index.html
tp://incubator.apache.org/projects/ki.html
13. Maven: The Definitive Guide, http://www.sonatype.com/books/maven-book/reference/public-book.html
14. Developing with Eclipse and Maven, http://www.sonatype.com/books/m2eclipse-book/reference/index.html