Securing Web Applications with Apache Shiro

The following tools are expected to be installed on your local development machine in order to follow along with this tutorial.

This is a step-by-step tutorial. The tutorial and all of its steps, exist as a Git repository. When you clone the git repository, the main branch is your starting point. Each step in the tutorial is a separate branch. You can follow along simply by checking out the git branch that reflects the tutorial step you are reviewing.

The web application we will build is a super webapp that can be used as a starting point for your own application. It will demonstrate user login, logout, user-specific welcome messages, access control to certain parts of the web application, and integration with a pluggable security data store.

We will start by setting up the project, including the build tool and declaring dependencies, as well as configuring the servlet web.xml file to launch the web application and the Shiro environment.

Once we complete setup, we will then layer in individual pieces of functionality, including integration with a security data store, then enabling user login, logout, and access control.

On GitHub, visit the tutorial project and click the Fork button on the upper right.

Now that you have forked the repository to your own GitHub account, clone it on your local machine:

(where $YOUR_GITHUB_USERNAME is your own GitHub username of course)

You can now cd into the cloned directory and see the project structure:

After cloning the repo, your current main branch will have the following structure:

Here is what each means:

Now that you’ve cloned the project, you can run the web application by executing the following on the command line:

Next, open your web browser to localhost:8080, and you’ll see the home page with a Hello, World! greeting.

Hit ctl-C to shut down the web app.

Shiro can be configured in many different ways in a web application, depending on the web and/or MVC framework you use. For example, you can configure Shiro via Spring, Guice, Tapestry, and many more.

To keep things simple for now, we’ll start a Shiro environment by using Shiro’s default (and very simple) INI-based configuration.

If you checked out the step1 branch, you’ll see the contents of this new src/main/webapp/WEB-INF/shiro.ini file (header comments removed for brevity):

This .ini contains simply a [main] section with some minimal configuration:

While we have a shiro.ini configuration, we need to actually load it and start a new Shiro environment and make that environment available to the web application.

We do all of this by adding a few things to the existing src/main/webapp/WEB-INF/web.xml file:

After checking out the step1 branch, go ahead and run the web app:

This time, you will see log output similar to the following, indicating that Shiro is indeed running in your webapp:

Hit ctl-C to shut down the web app.

In the spirit of keeping this tutorial as simple as possible, without introducing complexity or scope that distracts us from the purpose of learning Shiro, we’ll use one of the simplest realms we can: a Stormpath realm.

Stormpath is a cloud hosted user management service, totally free for development purposes. This means that after enabling Stormpath, you’ll have the following ready to go:

For the purposes of this tutorial, Stormpath is much simpler than setting up a separate RDBMS server and worrying about SQL or password encryption issues. So we’ll use that for now.

Of course, Stormpath is only one of many back-end data stores that Shiro can communicate with. We’ll cover more complicated data stores and application-specific configuration of them later.

Once you choose at least one user store to connect to for Shiro’s needs, we’ll need to configure a Realm that represents that data store and then tell the Shiro SecurityManager about it.

If you’ve checked out the step2 branch, you’ll notice the src/main/webapp/WEB-INF/shiro.ini file’s [main] section now has the following additions:

Note the optional lines:

After making the changes as specified in Step 2b and 2c, go ahead and run the web app:

This time, you will see log output similar to the following, indicating that Shiro and the new Realm are configured properly in your webapp:

Hit ctl-C to shut down the web app.

The step3 branch’s src/main/webapp/WEB-INF/shiro.ini file contains the following 2 additions:

Since Step 3a enabled login and logout support, now we need to ensure there is actually a /login.jsp page to display a login form.

The step3 branch contains a new src/main/webapp/login.jsp page. This is a simple enough bootstrap-themed HTML login page, but there are four important things in it:

Our login.jsp form just uses the default username, password, and rememberMe form field names. These names are configurable if you wish to change them - see the FormAuthenticationFilter JavaDoc for information.

After making the changes as specified in Step 2b and 2c, go ahead and run the web app:

With your web browser, navigate to localhost:8080/login.jsp, and you will see our new shiny login form.

Enter a username and password of the account you created at the end of Step 2, and hit 'Login'. If the login is successful, you will be directed to the home page! If the login fails, you will be shown the login page again.

Tip: If you want a successful login to redirect the user to a different page other than the home page (context path /), you can set the authc.successUrl = /whatever in the INI’s [main] section.

Hit ctl-C to shut down the web app.

The home.jsp file was modified to include two lines at the top:

These two JSP page directives allow the Core (c:) and Shiro (shiro:) taglibraries in the page.

The home.jsp file was further modified in the page body (right after the <h1> welcome message) to include both the <shiro:guest> and <shiro:user> tags:

It’s a little hard to read given the formatting, but two tags are used here:

The above code snippet will render the following if the Subject is a guest:

where 'Log in' is a hyperlink to /login.jsp

It will render the following if the Subject is a 'user':

Assuming 'jsmith' is the username of the account logged in. 'Log out' is a hyperlink to the '/logout' url handled by the Shiro logout filter.

As you can see, you can turn off or on entire page sections, features and UI components. In addition to <shiro:guest> and <shiro:user>, Shiro supports many other useful JSP tags that you can use to customize the UI based on various things known about the current Subject.

After checking out the step4 branch, go ahead and run the web app:

Try visiting localhost:8080 as a guest, and then login. After successful login, you will see the page content change to reflect that you’re now a known user!

Hit ctl-C to shut down the web app.

A new src/main/webapp/account directory was added. This directory (and all paths below it) simulates a 'private' or 'authenticated only' section of a website that you might want to restrict to only logged-in users. The src/main/webapp/account/index.jsp file is just a placeholder for a simulated 'home account' page.

shiro.ini was modified by adding the following line at the end of the [urls] section:

This Shiro filter chain definition means "Any requests to /account (or any of its sub-paths) must be authenticated".

But what happens if someone tries to access that path or any of its children paths?

Do you remember in Step 3 when we added the following line to the [main] section:

This line automatically configured the authc filter with our webapp’s login URL.

Based on this line of config, the authc filter is now smart enough to know that if the current Subject is not authenticated when accessing /account, it will automatically redirect the Subject to the /login.jsp page. After successful login, it will then automatically redirect the user back to the page they were trying to access (/account). Convenient!

The final change for Step 5 is to update the /home.jsp page to let the user know they can access the new part of the website.

These lines were added below the welcome message:

The <shiro:authenticated> tag will only display the contents if the current Subject has already logged in (authenticated) during their current session. This is how the Subject knows they can go visit a new part of the website.

The <shiro:notAuthenticated> tag will only display the contents if the current Subject is not yet authenticated during their current session.

But did you notice that the notAuthenticated content still has a URL to the /account section? That’s ok - our authc filter will handle the login-and-then-redirect flow as described above.

Fire up the webapp with the new changes and try it out!

After checking out the step5 branch, go ahead and run the web app:

Try visiting localhost:8080. Once there, click the new /account link and watch it redirect you to force you to log in. Once logged in, return to the home page and see the content change again now that you’re authenticated. You can visit the account page and the home page as often as you want, until you log out. Nice!

Hit ctl-C to shut down the web app.

In order to perform Role-Based Access Control, we need Roles to exist.

The fastest way to do that in this tutorial is to populate some Groups within Stormpath (in Stormpath, a Stormpath Group can serve the same purpose of a Role).

To do this, log in to the UI and navigate as follows:

Directories > My Application Directory > Groups

Add the following three groups:

(to keep with our Star-Trek account theme :) )

Once you’ve created the groups, add the Jean-Luc Picard account to the Captains and Officers groups. You might want to create some ad-hoc accounts and add them to whatever groups you like. Make sure some of the accounts don’t overlap groups, so you can see changes based on separate Groups assigned to user accounts.

We update the /home.jsp page to let the user know what roles they have and which ones they don’t. These messages are added in a new <h2>Roles</h2> section of the home page:

The <shiro:hasRole> tag will only display the contents if the current Subject has been assigned the specified role.

The <shiro:lacksRole> tag will only display the contents if the current Subject has not been assigned the specified role.

An exercise left to the reader (not a defined step) is to create a new section of the website and restrict URL access to that section of the website based on what role is assigned to the current user.

Hint: Create a filter chain definition for that new part of the webapp using the roles filter

After checking out the step6 branch, go ahead and run the web app:

Try visiting localhost:8080 and log in with different user accounts that are assigned different roles and watch the home page’s Roles section content change!

Hit ctl-C to shut down the web app.

Shiro `Realm`s are read-only components: every data store models roles, groups, permissions, accounts, and their relationships differently, so Shiro doesn’t have a 'write' API to modify these resources. To modify the underlying the model objects, you just modify them directly via whatever API you desire. Your Shiro Realm then knows how to read this information and represent it in a format Shiro understands.

As such, since we’re using Stormpath in this sample app, we’ll assign permissions to an account and group in a Stormpath API-specific way.

Let’s execute a cURL request to add some permissions to our previously created Jean-Luc Picard account. Using that account’s href URL, we’ll post some apacheShiroPermissions to the account via custom data:

where $JLPICARD_ACCOUNT_ID matches the uid of the Jean-Luc Picard you created at the beginning of this tutorial.

This adds two permissions directly to the Stormpath Account:

These use Shiro’s WildcardPermission syntax.

The first basically means the ability to 'command' the 'ship' with identifier 'NCC-1701-D'. This is an example of an instance-level permission: controlling access to a specific instance NCC-1701-D of a resource ship. The second is also an instance-level permission that states the ability to edit the user with identifier `jlpicard`.

How permissions are stored in Stormpath, as well as how to customize storage and access options in Stormpath is out of scope for this document, but this is explained in the Shiro Stormpath plugin documentation.

Just as we have JSP tags for role checks, parallel tags exist for permission checks as well. We update the /home.jsp page to let the user know if they’re allowed to do something or not based on the permissions that are assigned to them. These messages are added in a new <h2>Permissions</h2> section of the home page:

When you visit the home page the first time, before you log in, you will see the following output:

But after you log in with your Jean-Luc Picard account, you will see this instead:

You can see that Shiro resolved that the authenticated user had permissions, and the output was rendered in an appropriate way.

You can also use the <shiro:hasPermission> tag for affirmative permission checks.

Finally, we’ll call to attention an extremely powerful feature with permission checks. Did you see how the second permission check used a runtime generated permission value?

The ${account.username} value is interpreted at runtime and forms the final user:aUsername:edit value, and then the final String value is used for the permission check.

This is extremely powerful: you can perform permission checks based on who the current user is and what is currently being interacted with. These runtime-based instance-level permission checks are a foundational technique for developing highly customizable and secure applications.

After checking out the step7 branch, go ahead and run the web app:

Try visiting localhost:8080 and log in and out of the UI with your Jean-Luc Picard account (and other accounts), and see the page output change based on what permissions are assigned (or not)!

Hit ctl-C to shut down the web app.

Please send any fixes for errata as a GitHub Pull Request to the https://github.com/lhazlewood/apache-shiro-tutorial-webapp repository. We appreciate it!!!