Update 5/12/2016: Watch Stormpath CTO Les Hazlewood’s presentation on REST + JSON API design best practices.

Java SDK w/ Servlet Support

We just released a major upgrade of our Java SDK, which now includes Java Webapp (Servlet 3.1+) support with a ton of user automation. Just drop our Servlet plugin into your Java web application and boom – instant user management with little to no coding required.

This post is a quick tutorial, including Java and JSP code templates, to show you just how quickly you can build a Java web app with a complete set authentication and user management features and user interfaces with Stormpath.

If you’ve built a Java web application, you know the time and pain involved in building out proper authentication and user management.

Even if you use a great framework like Apache Shiro or Spring Security, there’s still a lot of boring UI work and high risk backend work.

At a minimum, you have to build UI screens for registration, login, and forgot password in addition to controllers processing each view, logout handlers, etc.

And then you have to worry about security issues like password hashing schemes, updating hashing algorithms as computation improves, cross-site request forgery (CSRF) protection, cross-site scripting (xss) attacks, and more.

Stormpath hooks into typical Java web applications and gives developers all the authentication, authorization, and user security out-of-the-box so you can get on with what you really care about – your application. In fact, you get full user interfaces without writing a single line of code. Awesome.

By the time you’re done with this tutorial (less than 15 minutes from now), you’ll have a fully-working Java web application. We will focus on our Stormpath-Servlet plugin that has a ton of user automation. You just drop a plugin into your web application and boom – instant user management with little to no coding required.

What You’ll Build in this Java Servlet Web App Tutorial:

You’ll build a simple Java web application using the standard Servlet 3+ and JSP APIs. When you’re done, you’ll be able to:

  • Create (register) a new user account with email and password
  • Validate the new user account’s registered email address
  • Login (authenticate) to your new account with email and password
  • Display a customizable user account dashboard after login, only accessible to logged-in users
  • Redirect unauthenticated users who try to access the dashboard to the login page
  • Allow a logged-in user to logout
  • Allow a user to reset their password via an email-based forgot password workflow

And here’s the best part – for all of the above, you won’t have to write a single line of code – just some configuration!

But, just for fun, we will code a simple welcome page and a user account dashboard page (in JSP) that are likely to exist in real applications.

All the code for this example is in the Stormpath Java SDK project.

Sound good? Great! Let’s get started!

What You’ll Need: Stormpath, JDK, Maven or Gradle

  • About 15 minutes of time
  • A Stormpath API Key to communicate with Stormpath
  • JDK 1.6 or later
  • Maven 3.0+ or Gradle 2.2+

How to Complete this Guide

You can start from scratch and complete each step or you can skip the basic setup steps, if you’re already set up with a Stormpath API Key and built your project with Maven/Gradle.

Start the Tutorial from Scratch

If you’d like to start from scratch, you’ll need to first get a Stormpath API Key.

Then you’ll need to Build With Maven or Build With Gradle, depending on your preferences.

Download a Stormpath API Key

All communication with Stormpath must be authenticated with an API Key.

  1. If you haven’t already, sign up for Stormpath for free. You’ll be sent a verification email.

  2. Click the link in the verification email

  3. Log in to the Stormpath Admin Console using the email address and password you used during registration

  4. Click the Manage API Keys link on the middle-right of the dashboard

  5. Under Security Credentials, click Create API Key

    This will generate your API Key and download it to your computer as an apiKey.properties file.

  6. Save the file in your home directory in the following location:

    ~/.stormpath/apiKey.properties on Unix, Linux and Mac OS
    C:\Users\YOUR_USERNAME\.stormpath\apiKey.properties on Windows

  7. Change the file permissions to ensure only you can read this file. For example:

  8. To be safe, you might also want to prevent yourself from accidentally writing/modifying the file:

On Windows, you can set the API Key file permissions similarly.

Build the project With Maven

Choose a directory that you wish to use for your project. Within that directory, create the following maven pom.xml file:


Build the project With Gradle

Choose a directory that you wish to use for your project. Within that directory, create the following build.gradle file:


Skip The Tutorial Basics

Add the dependency to your web app (.war) project:



Build the App’s Directory Structure

We’ll need to create some files in various directories. Ensure the following directory structure exists under your project directory:

For example, on *nix operating systems:

Create a Page Template for your App with JSP tags

We’ll likely want our web app’s pages to have the same look and feel. We can do this easily using a page template. And because JSP 2.0 supports page templates automatically via JSP Tags, there is no need to pull in additional template libraries. Let’s create a new template tag file with the following contents:


This is just a standard JSP file with a .tag extension instead of a .jsp extension. The element will be replaced with the page content for any page that uses this template.

Write a Home Controller

For security reasons, we like to ensure that JSP files themselves are never directly accessible during a request. Instead, we want a Controller to process the request and then render the JSP to the request. To do this, we’ll create a simple ‘Home’ controller that renders the internal home.jsp page:



Finally, we’ll need to add a web.xml file to tell the servlet container to invoke our Home Controller when the web app’s default path is accessed:


Start Up Your Webapp with Maven or Gradle

Can you believe that after adding a single home page, you’d have a functional web application with full user management capability?

Don’t believe me? Let’s try it!

Using your build tool of choice, let’s start up the web application. For example:



Open up a browser and visit http://localhost:8080. You’ll see the home page we just created above:

Stormpath Java Webapp Sample Home Page Screenshot

Pretty cool! Now, to be honest, this isn’t wildly exciting. That is what is supposed to happen after all. But the awesome features – the part you have been waiting for – is all the automatic stuff. For example, the login page!

Try the Stormpath User Login Page

Click the Login button at the top right of the page, or manually visit http://localhost:8080/login, and you’ll see this:

Stormpath Java Webapp Plugin Login Page Screenshot

That’s right! A login page with best practice cross-site request forgery (CSRF)-protection built right
in, and you didn’t have to write a single line of it. Now that is awesome! You can customize which fields are displayed in which order, as well as the entire look and feel if you wanted, with full internationalization (i18n) capabilities. That’s out of scope for this article, but you can read about customizing views later if you wanted.

It doesn’t stop there of course – you get all sorts of goodies, like user account registration, email verification and forgot password automation, token authentication and much more!

Register a New User with Stormpath

Now you can’t login until you create a user account, so go ahead and click the ‘Create Account’ link or manually visit the http://localhost:8080/register page and you’ll see this:

Stormpath Java Webapp Plugin Register Page Screenshot

Go ahead and fill out and submit the form – you’ll be given a new user account that you can use to log in right away.

Verify User Email Addresses

Now, what about email verification? Many web applications want to ensure that newly registered users must verify their email address before they can login to the application. This helps ensure that:

  • Email addresses cannot be abused by people that do not own them
  • The application has a way of communicating with the user if necessary
  • The registration process was completed by a human being (and not a ‘bot’ performing automatic registration, which could be used for malicious purposes).

This is covered too! You just have to enable email verification as described in the documentation. Since this is a shorter tutorial, we’ll move on, but feel free to turn that on if you like and try it out.

Logout your User

If you are still logged in, click the logout button on the upper right. This will visit /logout, which will automatically log you out and then redirect you back to the web app’s context root page (/) by default (you can customize this next URI later).

We’ll also make one more change to the web app, so go ahead and shut down the application by pressing CTRL-C.

Implement Views for Forgot Password, Change Password and More

The plugin supports other views out of the box as well, which you can read about in the documentation. But we want to show you one more thing before we wrap up this tutorial: access control.

Enforce Access Control (Authorization) with Stormpath

The Stormpath Java Webapp Plugin also has the ability to enforce access control based on URI path. For example, you
can ensure that only authenticated users may visit the /account URI within your application. Or that maybe only
accounts within the admin group can visit the /admin URI.

To demonstrate this, we’ll create a /dashboard view that only authenticated users should be able to see. This represents a common ‘landing page’ that a user might be shown immediately after login.

Let’s create a ‘Dashboard’ controller:


The DashboardController demonstrates a really nice Stormpath feature: the ability to ‘attach’ your own custom data directly to Stormpath REST resources, such as a user account’s birthday or favorite color.

Let’s create the view file that will be rendered by the controller:


And we’ll need to update web.xml to tell the Servlet Container about our new view. web.xml should now look like this:


Configure the Java Servlet Plugin for your App

Notice that, until now, we did not need to configure the plugin itself at all: everything ‘just works’. But now that we have some application-specific enforcement rules, we’ll need to tell the plugin what to do via a simple stormpath.properties configuration file. Let’s create this file:


  • The first line means “After the user successfully logs in, I want the next URI they visit to be /dashboard“. The plugin’s login controller will automatically redirect the newly authenticated user to this location.

  • The second line means “in order for anyone to visit the /dashboard URI, they must be authenticated (‘authc’ is short for ‘authenticated’). This enforces all requests to be authenticated by a valid user account before being allowed to continue. If they are not, they will be redirected to the login page to login first, and then automatically be redirected back to their originally requested URI.

Run the Updated Java Web Application

Now that we’ve added a dashboard view and controller, and a simple stormpath.properties file, let’s try it out!

If you haven’t already, shut down the application by pressing CTRL-C.

Now start it up:



Now try to visit http://localhost:8080/dashboard – you will be redirected to login as expected. Log in with a user account you created previously and then it will automatically redirect you back to the dashboard. Nice!

Stormpath Java Webapp Plugin Dashboard Page Screenshot

Stormpath Java Servlet Plugin — Advanced Features

Congratulations! You now have a complete web application, with automatic user registration, login, forgot password/reset workflows, logout, custom data editing, and access control enforcement!

But we’ve just scratched the surface of what you can do. Also supported:

  • Full default view customization with internationalization (i18n) support.
  • Authorization assertions (based on account data, like username, which groups they belong to, etc)
  • Token Authentication for Javascript and mobile clients (we implemented OAuth for you)
  • HTTP Basic Authentication for both username/password and API Keys
  • Event listeners to react to login, logout, registration, etc events.
  • Caching for enhanced performance.
  • Convienent filter chain definitions for custom authentication or authorization rules.
  • Easy Stormpath SDK Client configuration and request access
  • and more!

Please see the complete Stormpath Java Servlet Plugin Documentation for full information.