Spring Security and Angular JS

A Secure Single Page Application

In this section we show some nice features of Spring Security, Spring Boot and Angular JS working together to provide a pleasant and secure user experience. It should be accessible to beginners with Spring and Angular JS, but there also is plenty of detail that will be of use to experts in either. This is actually the first in a series of sections on Spring Security and Angular JS, with new features exposed in each one successively. We’ll improve on the application in the second and subsequent installments, but the main changes after this are architectural rather than functional.

Spring and the Single Page Application

HTML5, rich browser-based features, and the "single page application" are extremely valuable tools for modern developers, but any meaningful interactions will involve a backend server, so as well as static content (HTML, CSS and JavaScript) we are going to need a backend server. The backend server can play any or all of a number of roles: serving static content, sometimes (but not so often these days) rendering dynamic HTML, authenticating users, securing access to protected resources, and (last but not least) interacting with JavaScript in the browser through HTTP and JSON (sometimes referred to as a REST API).

Spring has always been a popular technology for building the backend features (especially in the enterprise), and with the advent of Spring Boot things have never been easier. Let’s have a look at how to build a new single page application from nothing using Spring Boot, Angular JS and Twitter Bootstrap. There’s no particular reason to choose that specific stack, but it is quite popular, especially with the core Spring constituency in enterprise Java shops, so it’s a worthwhile starting point.

Create a New Project

We are going to step through creating this application in some detail, so that anyone who isn’t completely au fait with Spring and Angular can follow what is happening. If you prefer to cut to the chase, you can skip to the end where the application is working, and see how it all fits together. There are various options for creating a new project:

• Using curl on the command line

• Using Spring Boot CLI

• Using the Spring Initializr website

• Using Spring Tool Suite

The source code for the complete project we are going to build is in Github here, so you can just clone the project and work directly from there if you want. Then jump to the next section.

Using Curl

The easiest way to create a new project to get started is via the Spring Boot Initializr. E.g. using curl on a UN*X like system:

$ mkdir ui && cd ui
$ curl https://start.spring.io/starter.tgz -d style=web \
-d style=security -d name=ui | tar -xzvf -

You can then import that project (it’s a normal Maven Java project by default) into your favourite IDE, or just work with the files and "mvn" on the command line. Then jump to the next section.

Using Spring Boot CLI

You can create the same project using the Spring Boot CLI, like this:

$ spring init --dependencies web,security ui/ && cd ui

Then jump to the next section.

Using the Initializr Website

If you prefer you can also get the same code directly as a .zip file from the Spring Boot Initializr. Just open it up in your browser and select dependencies "Web" and "Security", then click on "Generate Project". The .zip file contains a standard Maven or Gradle project in the root directory, so you might want to create an empty directory before you unpack it. Then jump to the next section.

Using Spring Tool Suite

In Spring Tool Suite (a set of Eclipse plugins) you can also create and import a project using a wizard at File->New->Spring Starter Project. Then jump to the next section.

Add a Home Page

The core of a single page application is a static "index.html", so let’s go ahead and create one (in "src/main/resources/static" or "src/main/resources/public"):

index.html

 href="css/angular-bootstrap.css" rel="stylesheet">
 type="text/css">
[ng\:cloak], [ng-cloak], .ng-cloak {
  display: none !important;
}



 ng-app="hello">
   class="container">
    
Greeting
     ng-controller="home" ng-cloak class="ng-cloak">
      
The ID is {{greeting.id}}
      
The content is {{greeting.content}}
    

src="js/angular-bootstrap.js" type="text/javascript"> src="js/hello.js">

It’s pretty short and sweet because it is just going to say "Hello World".

Features of the Home Page

Salient features include:

• Some CSS imported in the , one placeholder for a file that doesn’t yet exist, but is named suggestively ("angular-bootstrap.css") and one inline stylesheet defining the "ng-cloak" class.

• The "ng-cloak" class is applied to the content

  so that dynamic content is hidden until Angular JS has had a chance to process it (this prevents "flickering" during the initial page load).

• The is marked as ng-app="hello" which means we need to define a JavaScript module that Angular will recognise as an application called "hello".

• All the CSS classes (apart from "ng-cloak") are from Twitter Bootstrap. They will make things look pretty once we get the right stylesheets set up.

• The content in the greeting is marked up using handlebars, e.g. {{greeting.content}} and this will be filled in later by Angular (using a "controller" called "home" according to the ng-controller directive on the surrounding

  ).

• Angular JS (and Twitter Bootstrap) are included at the bottom of the so that the browser can process all the HTML before it gets processed.

• We also include a separate "hello.js" which is where we are going to define the application behaviour.

We are going to create the script and stylesheet assets in a minute, but for now we can ignore the fact that they don’t exist.

Running the Application

Once the home page file is added, your application will be loadable in a browser (even though it doesn’t do much yet). On the command line you can do this

$ mvn spring-boot:run

and go to a browser at http://localhost:8080. When you load the home page you should get a browser dialog asking for username and password (the username is "user" and the password is printed in the console logs on startup). There’s actually no content yet, so you should get a blank page with a "Greeting" header once you successfully authenticate.

If you don’t like scraping the console log for the password just add this to the "application.properties" (in "src/main/resources"): security.user.password=password (and choose your own password). We did this in the sample code using "application.yml".

In an IDE, just run the main() method in the application class (there is only one class, and it is called UiApplication if you used the "curl" command above).

To package and run as a standalone JAR, you can do this:

$ mvn package
$ java -jar target/*.jar

Front End Assets

Entry-level tutorials on Angular and other front end technologies often just include the library assets directly from the internet (e.g. the Angular JS website itself recommends downloading from Google CDN). Instead of doing that we are going to generate the "angular-bootstrap.js" asset by concatenating several files from such libraries. This is not strictly necessary to get the application working, but it is best practice for a production application to consolidate scripts to avoid chatter between the browser and the server (or content delivery network). Since we aren’t modifying or customizing the CSS stylesheets it is also unecessary to generate the "angular-bootstrap.css", and we could just use static assets from Google CDN for that as well. However, in a real application we almost certainly would want to modify the stylesheets and we wouldn’t want to edit the CSS sources by hand, so we would use a higher level tool (e.g. Less or Sass), so we are going to use one too.

There are many different ways of doing this, but for the purposes of this section, we are going to use wro4j, which is a Java-based toolchain for preprocessing and packaging front end assets. It can be used as a JIT (Just in Time) Filter in any Servlet application, but it also has good support for build tools like Maven and Eclipse, and that is how we are going to use it. So we are going to build static resource files and bundle them in our application JAR.

Aside: Wro4j is probably not the tool of choice for hard-core front end developers - they would probably be using a node-based toolchain, with bower and/or grunt. These are definitely excellent tools, and covered in great detail all over the internet, so please feel free to use them if you prefer. If you just put the outputs from those toolchains in "src/main/resources/static" then it will all work. I find wro4j comfortable because I am not a hard-core front end developer and I know how to use Java-based tooling.

To create static resources at build time we add some magic to the Maven pom.xml (it’s quite verbose, but boilerplate, so it could be extracted into a parent pom in Maven, or a shared task or plugin for Gradle):

pom.xml

  
    
      org.springframework.boot
      spring-boot-maven-plugin
    
    
      maven-resources-plugin
      
        
          
          copy-resources
          validate
          
            copy-resources
          
          
            ${basedir}/target/wro
            
              
                src/main/wro
                true
              
            
          
        
      
    
    
      ro.isdc.wro4j
      wro4j-maven-plugin
      1.7.6
      
        
          generate-resources
          
            run
          
        
      
      
        ro.isdc.wro.maven.plugin.manager.factory.ConfigurableWroManagerFactory
        ${project.build.directory}/classes/static/css
        ${project.build.directory}/classes/static/js
        ${project.build.directory}/wro/wro.xml
        ${basedir}/src/main/wro/wro.properties
        ${basedir}/src/main/wro
      
      
        
          org.webjars
          jquery
          2.1.1
        
        
          org.webjars
          angularjs
          1.3.8
        
        
          org.webjars
          bootstrap
          3.2.0
        
      
    
  

You can copy that verbatim into your POM, or just scan it if you are following along from the source in Github. The main points are:

• We are including some webjars libraries as dependencies (jquery and bootstrap for CSS and styling, and Angular JS for business logic). Some of the static resources in those jar files will be included in our generated "angular-bootstrap.*" files, but the jars themselves don’t need to be packaged with the application.

• Twitter Bootstrap has a dependency on jQuery, so we include that as well. An Angular JS application that didn’t use Bootstrap wouldn’t need that since Angular has its own version of the features it needs from jQuery.

• The generated resources will go in "target/classes", so they will be packaged in the output JAR from the project, and also available on the classpath in the IDE (as long as we are using Maven tooling, e.g. m2e in Eclipse).

• The wro4j-maven-plugin has some Eclipse integration features and you can install it from the Eclipse Marketplace (try it later if this is your first time - it’s not needed to complete the application). If you do that then Eclipse will watch the source files and re-generate the outputs if they change. If you run in debug mode then changes are immediately re-loadable in a browser.

• Wro4j is controlled from an XML configuration file that doesn’t know about your build classpath, and only understand absolute file paths, so we have to create an absolute file location and insert it in wro.xml. For that purpose we use Maven resource filtering and that is why there is an explicit "maven-resources-plugin" declaration.

That’s all of the changes we are going to need to the POM. It remains to add the wro4j build files, which we have specified are going to live in "src/main/wro".

Wro4j Source Files

If you look in the source code in Github you will see there are only 3 files (and one of those is empty, ready for later customization):

• wro.properties is a configuration file for the preprocessing and rendering engine in wro4j. You can use it to switch on and off various parts of the toolchain. In this case we use it to compile CSS from Less and to minify JavaScript, ultimately combining the sources from all the libraries we need in two files.

  wro.properties

  preProcessors=lessCssImport
  postProcessors=less4j,jsMin

• wro.xml declares a single "group" of resources called "angular-bootstrap", and this ends up being the base name of the static resources that are generated. It includes references to and elements in the webjars we added, and also to a local source file main.less.

  wro.xml

   xmlns="http://www.isdc.ro/wro">
     name="angular-bootstrap">
    webjar:bootstrap/3.2.0/less/bootstrap.less
      file:${project.basedir}/src/main/wro/main.less
      webjar:jquery/2.1.1/jquery.min.js
      webjar:angularjs/1.3.8/angular.min.js
    
  

• main.less is empty in the sample code, but could be used to customise the look and feel, changing the default settings in Twitter Bootstrap. E.g. to change the colours from default blue to light pink you could add a single line:

  main.less

  @brand-primary: #de8579;

Copy those files to your project and run "mvn package" and you should see the "bootstrap-angular.*" resources show up in your JAR file. If you run the app now, you should see the CSS take effect, but the business logic and navigation is still missing.

Create the Angular Application

Let’s create the "hello" application (in "src/main/resources/static/js/hello.js" so that the src="js/hello.js">

It’s not much different than the original in fact. Salient features:

• There is a

  for the navigation bar. All the links come straight back to the home page, but in a way that Angular will recognize once we get it set up with "routes".

  • All the content is going to be added as "partials" in the

    labelled "ng-view".

  • The "ng-cloak" has been moved up to the body because we want to hide the whole page until Angular can work out which bits to render. Otherwise the menus and content can "flicker" as they are moved around when the page loads.

  • As in the first section, the front end assets "angular-bootstrap.css" and "angular-bootstrap.js" are generated from JAR libraries at build time.

Add Navigation to the Angular Application

Let’s modify the "hello" application (in "src/main/resources/public/js/hello.js") to add some navigation features. We can start by adding some configuration for routes, so that the links in the home page actually do something. E.g.

hello.js

angular.module('hello', [ 'ngRoute' ])
  .config(function($routeProvider, $httpProvider) {

    $routeProvider.when('/', {
      templateUrl : 'home.html',
      controller : 'home',
      controllerAs: 'controller'
    }).when('/login', {
      templateUrl : 'login.html',
      controller : 'navigation',
      controllerAs: 'controller'
    }).otherwise('/');

    $httpProvider.defaults.headers.common["X-Requested-With"] = 'XMLHttpRequest';

  })
  .controller('home', function($http) {
    var self = this;
    $http.get('/resource/').then(function(response) {
      self.greeting = response.data;
    })
  })
  .controller('navigation', function() {});

We added a dependency on an Angular module called "ngRoute" and this allowed us to inject a magic $routeProvider into the config function (Angular does dependency injection by naming convention, and recognizes the names of your function parameters). The $routeProvider is then used inside the function to set up links to "/" (the "home" controller) and "/login" (the "login" controller). The "templateUrls" are relative paths from the root of the routes (i.e. "/") to "partial" views that will be used to render the model created by each controller.

The custom "X-Requested-With" is a conventional header sent by browser clients, and it used to be the default in Angular but they took it out in 1.3.0. Spring Security responds to it by not sending a "WWW-Authenticate" header in a 401 response, and thus the browser will not pop up an authentication dialog (which is desirable in our app since we want to control the authentication).

In order to use the "ngRoute" module, we need to add a line to the "wro.xml" configuration that builds the static assets (in "src/main/wro"):

wro.xml

 xmlns="http://www.isdc.ro/wro">
   name="angular-bootstrap">
    ...
    webjar:angularjs/1.3.8/angular-route.min.js
   

The Greeting

The greeting content from the old home page can go in "home.html" (right next to the "index.html" in "src/main/resources/static"):

home.html

Greeting
 ng-show="authenticated">
    
The ID is {{controller.greeting.id}}
    
The content is {{controller.greeting.content}}

ng-show="!authenticated">

Login to see your greeting

Note that we are binding to the controller as "controller" because that is how it was declared in the route provider configuration.

Since the user now has the choice whether to login or not (before it was all controlled by the browser), we need to distinguish in the UI between content that is secure and that which is not. We have anticipated this by adding references to an (as yet non-existent) authenticated variable.

The Login Form

The login form goes in "login.html":

login.html

 class="alert alert-danger" ng-show="controller.error">
    There was a problem logging in. Please try again.

role="form" ng-submit="controller.login()"> class="form-group"> for="username">Username: type="text" class="form-control" id="username" name="username" ng-model="controller.credentials.username"/>

class="form-group"> for="password">Password: type="password" class="form-control" id="password" name="password" ng-model="controller.credentials.password"/>

type="submit" class="btn btn-primary">Submit

This is a very standard login form, with 2 inputs for username and password and a button for submitting the form via ng-submit. You don’t need an action on the form tag, so it’s probably better not to put one in at all. There is also an error message, shown only if the angular model contains an error. The form controls use ng-model to pass data between the HTML and the Angular controller, and in this case we are using a credentials object to hold the username and pasword. According to the routes we defined the login form is linked with the "navigation" controller, which is so far empty, so let’s head over to that to fill in some gaps.