10 Minute Tutorial on Apache Shiro

Introduction

By going through this quick and simple tutorial you should fully understand how a developer uses Shiro in their
application. And you should be able to do it in under 10 minutes.

Overview

What is Apache Shiro?

Apache Shiro is a powerful and easy to use Java security framework that offers developers an intuitive yet
comprehensive solution to authentication, authorization, cryptography, and session management.

In practical terms, it achieves to manage all facets of your application's security, while keeping out of the way as
much as possible. It is built on sound interface-driven design and OO principles, enabling custom behavior wherever
you can imagine it. But with sensible defaults for everything, it is as "hands off" as application security can be.
At least that's what we strive for.

What can Apache Shiro do?

A lot . But we don't want to bloat the QuickStart. Please check out our
Features page if you'd like to see what it can do for you. Also, if
you're curious on how we got started and why we exist, please see the Shiro History and
Mission page.

Ok. Now let's actually do something!

Shiro can be run in any environment, from the simplest command line application
to the biggest enterprise web and clustered applications, but we'll use the simplest possible example in
a simple main method for this QuickStart so you can get a feel for the API.

Download

Ensure you have JDK 1.5+ and Maven 2.2+ installed.

Download the lastest "Source Code Distribution" from the Download
page. In this example, we're using the 1.1.0 release distribution.

Unzip the source package:

> unzip shiro-root-1.2.0-source-release.zip

Enter the quickstart directory:

> cd shiro-root-1.2.0/samples/quickstart

Run the QuickStart:

> mvn compile exec:java

This target will just print out some log messages to let you know what is going on and then exit. While
reading this quickstart, feel free to look at the code found under samples/quickstart/src/main/java/Quickstart.java.
Change that file and run the above mvn compile exec:java command as often as you like.

Quickstart.java

The Quickstart.java file referenced above contains all the code that will get you familiar with the API. Now
lets break it down in chunks here so you can easily understand what is going on.

In almost all environments, you can obtain the currently executing user via the following call:

Subject currentUser = SecurityUtils.getSubject();

Using SecurityUtils.getSubject(),
we can obtain the currently executing Subject.
A Subject is just a security-specific "view" of an application User. We actually wanted to call it 'User'
since that "just makes sense", but we decided against it: too many applications have existing APIs that already have
their own User classes/frameworks, and we didn't want to conflict with those. Also, in the security world, the term
Subject is actually the recognized nomenclature. Ok, moving on...

The getSubject() call in a standalone application might return a Subject based on user data in an
application-specific location, and in a server environment (e.g. web app), it acquires the Subject based on
user data associated with current thread or incoming request.

Now that you have a Subject, what can you do with it?

If you want to make things available to the user during their current session with the application, you can get their
session:

The Session is a Shiro-specific instance that provides most of what you're used to with regular HttpSessions
but with some extra goodies and one big difference: it does not require an HTTP environment!

If deploying inside a web application, by default the Session will be HttpSession based. But, in a
non-web environment, like this simple Quickstart, Shiro will automatically use its Enterprise Session Management by
default. This means you get to use the same API in your applications, in any tier, regardless of deployment
environment. This opens a whole new world of applications since any application requiring sessions does not need to
be forced to use the HttpSession or EJB Stateful Session Beans. And, any client technology can now share
session data.

So now you can acquire a Subject and their Session. What about the really useful stuff
like checking if they are allowed to do things, like checking against roles and permissions?

Well, we can only do those checks for a known user. Our Subject instance above represents the current user,
but who is the current user? Well, they're anonymous - that is, until they log in at least once. So, let's
do that:

if ( !currentUser.isAuthenticated() ) {
//collect user principals and credentials in a gui specific manner
//such as username/password html form, X509 certificate, OpenID, etc.
//We'll use the username/password example here since it is the most common.
//(do you know what movie this is from? ;)
UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa");
//this is all you have to do to support 'remember me' (no config - built in!):
token.setRememberMe(true);
currentUser.login(token);
}

That's it! It couldn't be easier.

But what if their login attempt fails? You can catch all sorts of specific exceptions that tell you exactly what
happened and allows you to handle and react accordingly:

Finally, when the user is done using the application, they can log out:

currentUser.logout(); //removes all identifying information and invalidates their session too.

Well, that's the core to using Apache Shiro at the application-developer level. And although there is some pretty
sophisticated stuff going on under the hood to make this work so elegantly, that's really all there is to it.

But you might ask yourself, "But who is responsible for getting the user data during a login (usernames and
passwords, role and permissions, etc), and who actually performs those security checks during runtime?" Well, you
do, by implementing what Shiro calls a Realm and plugging that Realm
into Shiro's configuration.

However, how you configure a Realm is largely dependent upon your runtime
environment. For example, if you run a standalone application, or if you have a web based application, or a Spring
or JEE container-based application, or combination thereof. That type of configuration is outside the scope of this
QuickStart, since its aim is to get you comfortable with the API and Shiro's concepts.