We just released a major upgrade of our Java SDK, which now includes Java Webapp (Servlet 3.0+) 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 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.
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, CSRF protection, XSS attacks, and more.
Stormpath hooks into typical Java web applications and gives developers all that “user stuff” 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 20 minute tutorial 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
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 a new user account with email and password
Validate the new user account’s registered email address
Login to your new account with email and password
Display a 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 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 that are likely to exist in real applications.
Sound good? Great! Let’s get started!
What You’ll Need
About 20 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 you’re already familiar with.
Start 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.
Get an API Key
All communication with Stormpath must be authenticated with an API Key.
If you haven’t already, sign up for Stormpath for free. You’ll be sent a verification email.
Click the link in the verification email.
Log in to the Stormpath Admin Console using the email address and password you used during registration.
Click the Manage API Keys link on the middle-right of the dashboard.
Under Security Credentials, click Create API Key.
This will generate your API Key and download it to your computer as an apiKey.properties file.
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
Change the file permissions to ensure only you can read this file. For example:
bash
chmod go-rwx ~/.stormpath/apiKey.properties
To be safe, you might also want to prevent yourself from accidentally writing/modifying the file:
bash
chmod u-w ~/.stormpath/apiKey.properties
On Windows, you can set file permissions similarly.
Build With Maven
Choose a directory that you wish to use for your project. Within that directory, create the following maven pom.xml file:
pom.xml
Build With Gradle
Choose a directory that you wish to use for your project. Within that directory, create the following build.gradle file:
build.gradle
Skip The Basics
Add the dependency to your web app (.war) project:
Maven:
Gradle:
Build the App
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:
Page Template
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:
src/main/webapp/WEB-INF/tags/page.tag
This is just a standard JSP file with a .tag extension instead of a .jsp extension. The <jsp:doBody/> element will be replaced with the page content for any page that uses this template.
Home Page
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:
src/main/java/tutorial/HomeController.java:
src/main/webapp/WEB-INF/jsp/home.jsp:
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:
src/main/webapp/WEB-INF/web.xml
Try it!
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:
Maven:
Gradle:
Open up a browser and visit http://localhost:8080. You’ll see the home page we just created above:
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!
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:
That’s right! A login page with best practice 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!
New User Registration Page
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:
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.
Email Verification
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
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.
Forgot Password, Change Password, etc.
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.
Access Control
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:
src/main/java/tutorial/DashboardController.java
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:
src/main/webapp/WEB-INF/jsp/dashboard.jsp
And we’ll need to update web.xml to tell the Servlet Container about our new view. web.xml should now look like this:
src/main/webapp/WEB-INF/web.xml
Stormpath Config
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:
src/main/webapp/WEB-INF/stormpath.properties
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.
Try it!
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:
Maven:
Gradle:
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!
Summary
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.