Correlate your services logging with Spring Boot

Posted on April 11, 2017 by Peterst

In a modern service landscape, especially when using containers, you are probably using something like the ELK stack (Elasticsearch, Logstash, Kibana) to flow all the logging into.
But how to find from all those loglines what caused the nasty bug after a innocent buttonpress?
One of the easy answers to this is what’s called a correlation id – basically a unique number assigned to that buttonpress which gets carried around between the services and added to every logline.
Sounds good you say? it is so let’s see how to do this.
Continue reading →

Spring Sweets: Access Application Arguments With ApplicationArguments Bean

Posted on March 21, 2017 by mrhaki

When we start a Spring Boot application and pass arguments to the application, Spring Boot will capture those arguments and creates a Spring bean of type ApplicationArguments and puts it in the application context. We can use this Spring bean to access the arguments passed to the application. We could for example auto wire the bean in another bean and use the provided argument values. The ApplicationArguments interface has methods to get arguments values that are options and plain argument values. An option argument is prefixed with --, for example --format=xml is a valid option argument. If the argument value is not prefixed with -- it is a plain argument.

Continue reading →

Spring Sweets: Custom Exit Code From Exception

Posted on March 20, 2017 by mrhaki

When we write a Spring Boot application a lot of things are done for us. For example when an exception in the application occurs when we start our application, Spring Boot will exit the application with exit code 1. If everything goes well and the we stop the application the exit code is 0. When we use the run method of SpringApplication and an exception is not handled by our code, Spring Boot will catch it and will check if the exception implements the ExitCodeGenerator interface. The ExitCodeGenerator interface has one method getExitCode() which must return a exit code value. This value is used as input argument for the method System.exit() that is invoke by Spring Boot to stop the application.

Continue reading →

Spring Sweets: Add (Extra) Build Information To Info Endpoint

Posted on January 17, 2017 by mrhaki

With Spring Boot Actuator we get some useful endpoints in our application to check on our application when it is running. One of the endpoints is the /info endpoint. We can add information about our application if Spring Boot finds a file META-INF/build-info.properties in the classpath of our application. With the Gradle Spring Boot plugin we can generate the build-info.properties file. When we apply the Gradle Spring Boot plugin to our project we get a Gradle extension springBoot in our build file. With this extension we can configure Spring Boot for our project. To generate project information that is used by the /info endpoint we must add the method statement buildInfo() inside the springBoot extension. With this method statement the Gradle Spring Boot plugin generates a file build/main/resources/META-INF/build-info.properties..

// File: build.gradle
plugins {
    id 'org.springframework.boot' version '1.4.2.RELEASE'
}
...
springBoot {
    // This statement tells the Gradle Spring Boot plugin
    // to generate a file 
    // build/resources/main/META-INF/build-info.properties
    // that is picked up by Spring Boot to display
    // via /info endpoint.
    buildInfo()
}
...

// File: build.gradle

plugins {

id 'org.springframework.boot' version '1.4.2.RELEASE'

}

...

springBoot {

// This statement tells the Gradle Spring Boot plugin

// to generate a file

// build/resources/main/META-INF/build-info.properties

// that is picked up by Spring Boot to display

// via /info endpoint.

buildInfo()

}

...

Let’s run our application and send a request for /info:

$ http -b localhost:8080/info
{
    "build": {
        "artifact": "spring-boot-sample",
        "group": "mrhaki.spring",
        "name": "sample-mrhaki",
        "time": 1482139076000,
        "version": "0.3.0"
    }
}
$

$ http -b localhost:8080/info

{

"build": {

"artifact": "spring-boot-sample",

"group": "mrhaki.spring",

"name": "sample-mrhaki",

"time": 1482139076000,

"version": "0.3.0"

}

To override the default properties or to add new properties we must provide a configuration closure to the buildInfo method. If we a built-in key as the name of the property it is overridden with a new value, otherwise the key is added as a new property. In the following example we add some extra properties and override the properties time and name:

// File: build.gradle
...
springBoot {
    buildInfo {
        // Generate extra build info.
        additionalProperties = [
                by: System.properties['user.name'],
                operatingSystem: "${System.properties['os.name']} (${System.properties['os.version']})",
                continuousIntegration: System.getenv('CI') ? true: false,
                machine: InetAddress.localHost.hostName,
                // Override buildInfo property time
                time: buildTime(),
                // Override name property
                name: 'sample-springboot-app'
        ]
    }
}
...

// File: build.gradle

...

springBoot {

buildInfo {

// Generate extra build info.

additionalProperties = [

by: System.properties['user.name'],

operatingSystem: "${System.properties['os.name']} (${System.properties['os.version']})",

continuousIntegration: System.getenv('CI') ? true: false,

machine: InetAddress.localHost.hostName,

// Override buildInfo property time

time: buildTime(),

// Override name property

name: 'sample-springboot-app'

]

}

...

We restart the application and invoke the /info endpoint to get more results for the build:

$ http -b localhost:8080/info
{
    "build": {
        "artifact": "spring-boot-sample",
        "by": "mrhaki",
        "continuousIntegration": "false",
        "group": "mrhaki.spring",
        "machine": "mrhaki-laptop-2015.local",
        "name": "sample-springboot-app",
        "operatingSystem": "Mac OS X (10.12.2)",
        "time": "2016-12-19 09:16:50+0000",
        "version": "0.3.0"
    }
}
$

$ http -b localhost:8080/info

{

"build": {

"artifact": "spring-boot-sample",

"by": "mrhaki",

"continuousIntegration": "false",

"group": "mrhaki.spring",

"machine": "mrhaki-laptop-2015.local",

"name": "sample-springboot-app",

"operatingSystem": "Mac OS X (10.12.2)",

"time": "2016-12-19 09:16:50+0000",

"version": "0.3.0"

}

Written with Spring Boot 1.4.2.RELEASE.

Original blog post

Spring Sweets: Add Git Info To Info Endpoint

Posted on January 16, 2017 by mrhaki

With Spring Boot Actuator we get some endpoints that display information about our application. One of the endpoints is the /info endpoint. If our project uses Git we can add information about Git to the /info endpoint. By default Spring Boot will look for a file git.properties in the classpath of our application. The file is a Java properties file with keys that start with git. and have values like the branch name, commit identifier and commit message. Spring Boot uses this information and when we request the /info endpoint we get a response with the information. This can be very useful to check the Git information that was used to build the application. To create the git.properties file we can use a Gradle (or Maven) plugin that will do the work for us.

Continue reading →

Angular2 and Spring Boot: Getting Started

Posted on December 13, 2016 by Jeroen Bruinink

213

Combining Angular2 and Spring Boot is a great way of getting up and running quickly with a new web application. However, it can be challenging to fit all the different pieces together in the beginning. In this blog post we will create a new project that is easy to build and run across different environments. The goal is to create a minimal, but runnable, application with as little dependencies and setup as possible. You can then start expanding the application however you see fit.

We will create the Angular2 application using angular-cli. This allows us to easily generate a new project with a clear structure. This will also make it easy to add new elements to our Angular2 application. When adding new elements with angular-cli, we will maintain the same structure and wire the new elements together automatically. Angular-cli is an npm module, so it requires Node and npm to install and run. Make sure to install a recent version of both of these applications before continuing with the steps below. We will use Maven as the overall build manager for our application.

The steps should be easy to follow and will not require a lot of work. However, you can get the result directly in this GitHub repository if you want to. There is a seperate commit for every step.

Step 1: Generate a new Spring Boot project

The first step is to generate a new Spring Boot project at https://start.spring.io. I’ve used the values in the screenshot below. Of course you can use your own group and artifact ids. We need at least the Web plugin to let Spring Boot serve the Angular2 application. If you already know you need more dependencies for your project, feel free to add them.

Click on Generate Project to download the zip file with your new Spring Boot project. Extract the zip file somewhere on your computer. Then open a command prompt and go to the newly created project directory.

Step 2: Split the project into seperate modules

We will want to use seperate Maven modules for the frontend and backend. Let’s start by creating the correct directory structure and copying the pom file.

Microsoft Windows [Version 10.0.14393]
(c) 2016 Microsoft Corporation. Alle rechten voorbehouden.

C:\Users\Jeroen>cd c:\ng2boot

C:\ng2boot>mkdir backend frontend\src\main

C:\ng2boot>move src backend
        1 dir(s) moved.

C:\ng2boot>copy pom.xml backend
        1 file(s) copied.

C:\ng2boot>

Microsoft Windows [Version 10.0.14393]

C:\Users\Jeroen>cd c:\ng2boot

C:\ng2boot>mkdir backend frontend\src\main

C:\ng2boot>move src backend

1 dir(s) moved.

C:\ng2boot>copy pom.xml backend

1 file(s) copied.

C:\ng2boot>

Edit pom.xml in the top level project directory and make it look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.jdriven.ng2boot</groupId>
    <artifactId>parent</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>pom</packaging>

    <name>parent</name>
    <description>The ng2boot parent project</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <modules>
        <module>frontend</module>
        <module>backend</module>
    </modules>
</project>

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<groupId>com.jdriven.ng2boot</groupId>

<artifactId>parent</artifactId>

<version>0.0.1-SNAPSHOT</version>

<name>parent</name>

<description>The ng2boot parent project</description>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.5.2.RELEASE</version>

</parent>

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

<java.version>1.8</java.version>

</properties>

<module>frontend</module>

<module>backend</module>

</modules>

</project>

Next, edit pom.xml in the backend directory and make it look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <artifactId>backend</artifactId>

    <name>backend</name>
    <description>The ng2boot backend project</description>

    <parent>
        <groupId>com.jdriven.ng2boot</groupId>
        <artifactId>parent</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<artifactId>backend</artifactId>

<name>backend</name>

<description>The ng2boot backend project</description>

<groupId>com.jdriven.ng2boot</groupId>

<artifactId>parent</artifactId>

<version>0.0.1-SNAPSHOT</version>

</parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-test</artifactId>

</dependency>

</dependencies>

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

</project>

Finally, copy the pom.xml from the backend directory to the frontend directory and edit it to look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <artifactId>frontend</artifactId>

    <name>frontend</name>
    <description>The ng2boot frontend project</description>

    <parent>
        <groupId>com.jdriven.ng2boot</groupId>
        <artifactId>parent</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>

    <build>
        <plugins>
        </plugins>
    </build>
</project>

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<artifactId>frontend</artifactId>

<name>frontend</name>

<description>The ng2boot frontend project</description>

<groupId>com.jdriven.ng2boot</groupId>

<artifactId>parent</artifactId>

<version>0.0.1-SNAPSHOT</version>

</parent>

<build>

</plugins>

</build>

</project>

Step 3: Add the Angular2 application to the project

If angular-cli is not installed on your system already, use npm to install it now.

C:\ng2boot>npm install -g @angular/cli

1	C:\ng2boot>npm install -g @angular/cli

To keep the blog post readable, I’m not showing the output of the command. You can ignore any warnings about optional dependencies. The -g flag tells npm to install it globally. This means you can run the command ng from the command line anywhere on your computer. Let’s use angular-cli to generate our Angular2 application in the frontend\src\main\frontend directory.

C:\ng2boot\frontend\src\main>ng new --skip-git --directory frontend ng2boot
installing ng
 create .editorconfig
 create README.md
 create src\app\app.component.css
 create src\app\app.component.html
 create src\app\app.component.spec.ts
 create src\app\app.component.ts
 create src\app\app.module.ts
 create src\assets\.gitkeep
 create src\environments\environment.prod.ts
 create src\environments\environment.ts
 create src\favicon.ico
 create src\index.html
 create src\main.ts
 create src\polyfills.ts
 create src\styles.css
 create src\test.ts
 create src\tsconfig.app.json
 create src\tsconfig.spec.json
 create src\typings.d.ts
 create .angular-cli.json
 create e2e\app.e2e-spec.ts
 create e2e\app.po.ts
 create e2e\tsconfig.e2e.json
 create karma.conf.js
 create package.json
 create protractor.conf.js
 create tsconfig.json
 create tslint.json
Installing packages for tooling via npm.
Installed packages for tooling via npm.
Project 'ng2boot' successfully created.

C:\ng2boot\frontend\src\main>

C:\ng2boot\frontend\src\main>ng new --skip-git --directory frontend ng2boot

installing ng

create .editorconfig

create README.md

create src\app\app.component.css

create src\app\app.component.html

create src\app\app.component.spec.ts

create src\app\app.component.ts

create src\app\app.module.ts

create src\assets\.gitkeep

create src\environments\environment.prod.ts

create src\environments\environment.ts

create src\favicon.ico

create src\index.html

create src\main.ts

create src\polyfills.ts

create src\styles.css

create src\test.ts

create src\tsconfig.app.json

create src\tsconfig.spec.json

create src\typings.d.ts

create .angular-cli.json

create e2e\app.e2e-spec.ts

create e2e\app.po.ts

create e2e\tsconfig.e2e.json

create karma.conf.js

create package.json

create protractor.conf.js

create tsconfig.json

create tslint.json

Installing packages for tooling via npm.

Installed packages for tooling via npm.

Project 'ng2boot' successfully created.

C:\ng2boot\frontend\src\main>

We just told angular-cli to generate a new project. We let it skip creating a git repository, because we are not in the top level directory of our project. We specified that the output directory should be frontend and called the new application ng2boot. We chose src\main\frontend to prevent maven from putting the source files, including the node_modules directory, in our jar.

Step 4: Configure Maven to build the Angular2 application

We will use the frontend-maven-plugin to build the Angular 2 application with Maven. First, let’s add the plugin to the fronted pom in the build/plugins section.

        <plugins>
            <plugin>
                <groupId>com.github.eirslett</groupId>
                <artifactId>frontend-maven-plugin</artifactId>
                <version>1.3</version>

                <configuration>
                    <nodeVersion>v6.10.1</nodeVersion>o
                    <npmVersion>4.4.1</npmVersion>
                    <workingDirectory>src/main/frontend</workingDirectory>
                </configuration>

                <executions>
                    <execution>
                        <id>install node and npm</id>
                        <goals>
                            <goal>install-node-and-npm</goal>
                        </goals>
                    </execution>

                    <execution>
                        <id>npm install</id>
                        <goals>
                            <goal>npm</goal>
                        </goals>
                    </execution>

                    <execution>
                        <id>npm run build</id>
                        <goals>
                            <goal>npm</goal>
                        </goals>

                        <configuration>
                            <arguments>run build</arguments>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>

<groupId>com.github.eirslett</groupId>

<artifactId>frontend-maven-plugin</artifactId>

<nodeVersion>v6.10.1</nodeVersion>o

<workingDirectory>src/main/frontend</workingDirectory>

</configuration>

<id>install node and npm</id>

<goals>

<goal>install-node-and-npm</goal>

</goals>

</execution>

<id>npm install</id>

<goals>

</goals>

</execution>

<id>npm run build</id>

<goals>

</goals>

<arguments>run build</arguments>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

We specify the node and npm versions and the working directory in the configuration section. We also add three executions. The first execution downloads and installs node and npm to the directories node and node_modules. Npm will download a lot of packages, so add both directories to the ignore list of your version control system. The second execution runs npm install in the working directory to download all npm dependencies of our project. The third execution runs npm run build in the working directory to build the Angular2 application.

By default, angular-cli will write the final Angular2 application in the src\main\frontend\dist directory. We can adhere to the Maven standard directory layout better by configuring angular-cli to write it to the target directory. This will also delete the built application, along with all other build artifacts, when we run mvn clean. Edit .angular-cli.json and change the outDir in the apps section.

"apps": [
  {
    "root": "src",
    "outDir": "../../../target/frontend",
    "assets": [
      "assets",
      "favicon.ico"
    ],
    "index": "index.html",
    "main": "main.ts",
    "polyfills": "polyfills.ts",
    "test": "test.ts",
    "tsconfig": "tsconfig.app.json",
    "testTsconfig": "tsconfig.spec.json",
    "prefix": "app",
    "styles": [
      "styles.css"
    ],
    "scripts": [],
    "environmentSource": "environments/environment.ts",
    "environments": {
      "dev": "environments/environment.ts",
      "prod": "environments/environment.prod.ts"
    }
  }
]

"apps": [

{

"root": "src",

"outDir": "../../../target/frontend",

"assets": [

"assets",

"favicon.ico"

"index": "index.html",

"main": "main.ts",

"polyfills": "polyfills.ts",

"test": "test.ts",

"tsconfig": "tsconfig.app.json",

"testTsconfig": "tsconfig.spec.json",

"prefix": "app",

"styles": [

"styles.css"

"scripts": [],

"environmentSource": "environments/environment.ts",

"environments": {

"dev": "environments/environment.ts",

"prod": "environments/environment.prod.ts"

}

]

Step 5: Let Spring Boot serve the Angular2 application

Maven will now build (and clean) the Angular2 application, but it will not end up in our final jar. Spring Boot will serve static content from a number of directories on the Java classpath. So we have to make sure that the Angular2 application ends up in one of those directories. Files on the classpath that are not Java classes, are known as resources. Maven copies all resources (normally found in src\main\resources) into the final jar. Add the packaged Angular2 application to the resources by adding the snippet below to the build section in pom.xml. The given targetPath will put it in /static on the classpath and Spring Boot will serve it from there.

        <resources>
            <resource>
                <directory>target/frontend</directory>
                <targetPath>static</targetPath>
            </resource>
        </resources>

<directory>target/frontend</directory>

<targetPath>static</targetPath>

</resource>

</resources>

Because the Spring Boot backend is in another module, we will need to add a dependency to the Angular2 application. Edit the backend pom file and add the following to the list of dependencies.

        <dependency>
            <groupId>com.jdriven.ng2boot</groupId>
            <artifactId>frontend</artifactId>
            <version>${project.version}</version>
            <scope>runtime</scope>
        </dependency>

<groupId>com.jdriven.ng2boot</groupId>

<artifactId>frontend</artifactId>

<version>${project.version}</version>

<scope>runtime</scope>

</dependency>

Step 6: Fire it up!

We are now ready to build and run our application. From the top level directory of our project, run:

mvn clean install
cd backend
mvn spring-boot:run

mvn clean install

cd backend

mvn spring-boot:run

Wait for the application to start and then point your browser to http://localhost:8080

If you have configured everything properly, your application should look just like the above image. If it doesn’t, have a look at the GitHub repository which has the finished application in it. And of course, don’t hesitate to leave a reply if you’re having trouble getting the application to build or start.

Step 7: Using the angular-cli development server with your Spring Boot backend

One of many nice features of angular-cli is the development server. It will serve the Angular2 application, just like Spring Boot. However, every time we save a source file, it will automatically rebuild the application and refresh the browser.

There is one problem though. Maven (running our backend) and the development server (running our frontend) are seperate processes listening on seperate ports. This prevents Angular2 from making backend requests because it violates the Same Origin Policy of our web browser. Web browsers only allow backend requests to the same origin that the web application making the requests was downloaded from.

Thankfully, we can let angular-cli act as a proxy for our Spring Boot backend. The Angular2 application will send backend requests to thedevelopment server, which will forward them to Spring Boot. Now, the Angular2 application can make backend requests to the same origin it came from.

Edit package.json and change the start script to add the proxy configuration.

"scripts": {
  "ng": "ng",
  "start": "ng serve --proxy-config proxy.conf.json",
  "build": "ng build",
  "test": "ng test",
  "lint": "ng lint",
  "e2e": "ng e2e"
}

"scripts": {

"ng": "ng",

"start": "ng serve --proxy-config proxy.conf.json",

"build": "ng build",

"test": "ng test",

"lint": "ng lint",

"e2e": "ng e2e"

}

The start script now references proxy.conf.json. Create that file, with the following content:

{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false
  }
}

{

"/api": {

"target": "http://localhost:8080",

"secure": false

}

This configuration assumes all backend requests will be made to (sub paths of) /api. You can of course choose any url you like. Now, when you run npm start in the frontend\src\main\frontend directory, the development server will run your Angular2 application. It can be reached at http://localhost:4200. Don’t forget you have to start your backend seperately. You can do this by running mvn spring-boot:run in the backend directory.

I hope you enjoyed this blog post. If you found it useful, or if you have any questions, please let me know by leaving a reply. Happy coding!

Handling YAML format in your REST with Spring Boot

Posted on November 30, 2016 by Willem Cheizoo

In general a REST service serves JSON document formats. In Spring Boot it is even the standard without having to configure anything.
Over HTTP we have the ability to send a Content-Type as header to instruct the server to return a certain document format (Mime type).
Besides handling JSON, XML is another common document format. But what if we want to serve or read a YAML document format?

This tutorial provides the required steps to be able to handle objects in YAML format. To be able to send a YAML Content-Type with the header, and to be able to serialize and deserialize with the existing ObjectMappers of Jackson. This tutorial will use Spring Boot, Jackson and a YAML dataformat extension library for Jackson.

Continue reading →

Integrate Angular in Spring Boot with Gradle

Posted on October 14, 2016 by Willem Cheizoo

Having a Angular HTML5 single page application and a Spring Boot application, we would like to serve the complete Angular app from Spring Boot. This blog shows you a couple simple steps to get everything up and running: run NPM from Gradle, integrate the Gradle frontend build in the main build and support HTML5 mode in the ResourceHandler of Spring Boot.

Run NPM from Gradle

Create a subdirectory called frontend with the frontend code and build scripts (webpack, npm). Let’s assume our npm start and npm run watch output to the /frontend/dist/ directory.

First we need to make sure the frontend code is build when we run gradle build on our project. We can use the plugin gradle-node-plugin for this. Go ahead and create a /frontend/build.gradle file.

plugins {
  id "com.moowork.node" version "0.12"
}

version '0.0.1'

node {
  version = '6.8.0'
  npmVersion = '3.10.8'
  download = true
  workDir = file("${project.buildDir}/node")
  nodeModulesDir = file("${project.projectDir}")
}

task build(type: NpmTask) {
  args = ['run', 'build']
}

build.dependsOn(npm_install)

plugins {

id "com.moowork.node" version "0.12"

}

version '0.0.1'

node {

version = '6.8.0'

npmVersion = '3.10.8'

download = true

workDir = file("${project.buildDir}/node")

nodeModulesDir = file("${project.projectDir}")

}

task build(type: NpmTask) {

args = ['run', 'build']

}

build.dependsOn(npm_install)

Now, if we run a gradle build from our frontend subdirectory:

node will be downloaded
npm install will be executed
npm run build will be executed

Run integrated Gradle build

To run the frontend submodule integrated from our root project, all we need to do is include a settings.gradle at the root of the project.

include 'frontend'

rootProject.name = 'my-project-name'

include 'frontend'

rootProject.name = 'my-project-name'

Go ahead and run gradle build from the root of our project and see that npm is downloaded and the expected npm tasks are run.

We need to include the distribution of the frontend build in the JAR. Thus the frontend:build task needs to be run before we process the resources of the JAR. Go ahead and add the following snippet to /build.gradle.

jar {
    from('frontend/dist') {
        //Public is a default supported Spring Boot resources directory.
        into 'public'
    }
}

//frontend:build will be run before the processResources
processResources.dependsOn('frontend:build')

jar {

from('frontend/dist') {

//Public is a default supported Spring Boot resources directory.

into 'public'

}

//frontend:build will be run before the processResources

processResources.dependsOn('frontend:build')

Support Angular HTML5 mode

Now all we need to do is create support for HTML5 mode in Angular. Angular is a single page application and subroutes of the application are default served with a ‘#’ hashtag separator. If we want to have regular paths, we can enable HTML5 mode. The problem in serving this Angular HTML5 application from Spring Boot is that the Spring Boot ResourceHandler cannot find these resources, since the real resources is the index.html with the JavaScript files. With the next code snippet we instruct Spring Boot to look for the index.html as well. This is inspired by http://stackoverflow.com/questions/24837715/spring-boot-with-angularjs-html5mode

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.web.ResourceProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.Resource;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import org.springframework.web.servlet.resource.PathResourceResolver;

import java.io.IOException;
import java.util.Arrays;

@Configuration
@EnableConfigurationProperties({ResourceProperties.class})
public class StaticResourcesConfiguration extends WebMvcConfigurerAdapter {

    static final String[] STATIC_RESOURCES = new String[]{
        "/**/*.css",
        "/**/*.html",
        "/**/*.js",
        "/**/*.json",
        "/**/*.bmp",
        "/**/*.jpeg",
        "/**/*.jpg",
        "/**/*.png",
        "/**/*.ttf",
        "/**/*.eot",
        "/**/*.svg",
        "/**/*.woff",
        "/**/*.woff2"
    };

    @Autowired
    private ResourceProperties resourceProperties = new ResourceProperties();

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //Add all static files
        Integer cachePeriod = resourceProperties.getCachePeriod();
        registry.addResourceHandler(STATIC_RESOURCES)
            .addResourceLocations(resourceProperties.getStaticLocations())
            .setCachePeriod(cachePeriod);

        //Create mapping to index.html for Angular HTML5 mode.
        String[] indexLocations = getIndexLocations();
        registry.addResourceHandler("/**")
            .addResourceLocations(indexLocations)
            .setCachePeriod(cachePeriod)
            .resourceChain(true)
            .addResolver(new PathResourceResolver() {
                @Override
                protected Resource getResource(String resourcePath, Resource location) throws IOException {
                    return location.exists() && location.isReadable() ? location : null;
                }
            });
    }

    private String[] getIndexLocations() {
        return Arrays.stream(resourceProperties.getStaticLocations())
            .map((location) -> location + "index.html")
            .toArray(String[]::new);
    }
}

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.boot.autoconfigure.web.ResourceProperties;

import org.springframework.boot.context.properties.EnableConfigurationProperties;

import org.springframework.context.annotation.Configuration;

import org.springframework.core.io.Resource;

import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import org.springframework.web.servlet.resource.PathResourceResolver;

import java.io.IOException;

import java.util.Arrays;

@Configuration

@EnableConfigurationProperties({ResourceProperties.class})

public class StaticResourcesConfiguration extends WebMvcConfigurerAdapter {

static final String[] STATIC_RESOURCES = new String[]{

"/**/*.css",

"/**/*.html",

"/**/*.js",

"/**/*.json",

"/**/*.bmp",

"/**/*.jpeg",

"/**/*.jpg",

"/**/*.png",

"/**/*.ttf",

"/**/*.eot",

"/**/*.svg",

"/**/*.woff",

"/**/*.woff2"

};

@Autowired

private ResourceProperties resourceProperties = new ResourceProperties();

@Override

public void addResourceHandlers(ResourceHandlerRegistry registry) {

//Add all static files

Integer cachePeriod = resourceProperties.getCachePeriod();

registry.addResourceHandler(STATIC_RESOURCES)

.addResourceLocations(resourceProperties.getStaticLocations())

.setCachePeriod(cachePeriod);

//Create mapping to index.html for Angular HTML5 mode.

String[] indexLocations = getIndexLocations();

registry.addResourceHandler("/**")

.addResourceLocations(indexLocations)

.setCachePeriod(cachePeriod)

.resourceChain(true)

.addResolver(new PathResourceResolver() {

@Override

protected Resource getResource(String resourcePath, Resource location) throws IOException {

return location.exists() && location.isReadable() ? location : null;

}

});

}

private String[] getIndexLocations() {

return Arrays.stream(resourceProperties.getStaticLocations())

.map((location) -> location + "index.html")

.toArray(String[]::new);

}

Happy coding!

Securing your application landscape with Spring Cloud Security – Part 1

Posted on September 2, 2016 by Riccardo Lippolis

Securing an application is difficult. Securing an entire application landscape is even more difficult! In this modern era of blazing fast microservices we do not want the additional complexity of having to secure it all manually. This is where Spring Cloud Security comes in. By combining proven technologies, it helps us achieve performant, configurable end-to-end security across multiple applications.

So what technologies are being combined? Well, a lot… We will not mention them all here, but the foundation relies on Spring Boot and Spring Security OAuth.

OAuth, or, in our case, OAuth2 is basically an authorization delegation protocol. To quote Wikipedia, OAuth:

[…] specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

In our context, the resource owners are the users of our applications, server resources are the data we store about our users (e.g. the list of shop orders), and third-parties are the applications (or services) in our landscape which perform actions on the user data.

A common mistake people make is thinking that OAuth also provides authentication. It doesn’t, but that’s where Spring Security kicks in. For more information about the difference between authentication and authorization in an OAuth context, we refer you to this article.

Basically, the picture below visualizes the type of application landscape we want to achieve with this series of articles.

An overview of the type of application landscape we want to achieve

In the following series of articles, we will build a concrete implementation of the above displayed application landscape from the ground up, with as little code and configuration as possible. We will make some concessions regarding complexity and functionality, mainly to enable us to focus on the basic principles.

The project source code is available on Bitbucket, so feel free to clone the Git repository:

git clone https://bitbucket.org/rlippolis/cloud-security-example.git

1	git clone https://bitbucket.org/rlippolis/cloud-security-example.git

The master branch contains the complete solution. Each article in this series will represent a separate step in the development of the solution. Several Git tags have been created in the repository to be able to follow along with each step.

How to run it

To be able to run the applications, the following software is required:

Gradle (tested with version 2.12)
Java 8 Development Kit

All three applications in the Git repository can be run from the command line, by executing the following command from the root directory of the application to run:

gradle bootRun

1	gradle bootRun

Alternatively, it is possible to run the main method in the relevant Spring Boot Application class (MyAuthServerApplication / MyWebsiteApplication / MyRestApiApplication) from an IDE or command line.

It does not matter in which order the applications are started.

Securing a basic website with a separate Identity Provider

As a starting point, we have created a Spring Boot application, called My Website. The application is bootstrapped using Spring Initializr, with the Web and Thymeleaf dependencies.

The application is pretty straightforward, containing a single Spring MVC Controller, to render a web page which displays the current time (like mentioned before, the functionality of the application is irrelevant, so we keep this simple). For now, the application is not secured in any way.

Tip To see the application in its initial state (not secured), checkout the Git tag insecure-website from the repository. To see the end result of this step (the website is secured using an Identity Provider), checkout the tag secure-website.

To view the current time, run the My Website application (see How to run it), and navigate to: http://localhost:8080/time

Creating the Identity Provider

The first step in securing My Website involves creating My Auth Server. This application will function as an Identity Provider for My Website. To achieve this, we will be using Spring Cloud Security, in combination with Spring Security OAuth2.

In OAuth2, the role of Identity Provider is split in two parts. The first part, the Authorization Server, verifies the identity of a resource owner (the user) and provides some kind of access token to applications wanting to act as the user. The second part, the Resource Server, provides resources (e.g. information about the user), based on the given token.

Important

The OAuth2 specification doesn’t state anything about authentication. It basically defines how to delegate authorizations to access protected resources to third parties. In our context: the Authorization Server tells our application(s) that it may act as some user (resource owner), and thus access their data (resources). So how does the Authorization Server know which user it concerns? That’s where Spring Security enters the picture. Spring Security will handle the authentication part, and Spring Security OAuth2 will do the rest. For more general information about user authentication with OAuth2, see here.

With Spring Security OAuth2 it is possible to create two separate applications, one acting as Authorization Server and one as Resource Server. But it is also possible to combine the two parts into one application, which is what we will be doing.

Again, we will use Spring Initializr to bootstrap the application, with the Web and Thymeleaf dependencies, but this time we also add the Cloud OAuth2 dependency. We configure the application to run at http://localhost:9090/auth (see the properties in my-auth-server/src/main/resources/application.yml).

My Auth Server application is configured as both an Authorization Server and Resource Server, and is secured with Spring Security, with the help of a few Spring configurer adapters. These are explained below.

Authorization Server configuration

The AuthorizationServerConfigurer allows you to modify the default configuration (enabled by the annotation @EnableAuthorizationServer) to be able to act as an OAuth2 Authorization Server. Furthermore, we configure the client details service. This service specifies details about the way ‘clients’ (== other applications) interact with the Authorization Server.

...
@Override
public void configure(ClientDetailsServiceConfigurer clients) throws Exception {
    clients.inMemory()                                  // (1)
            .withClient("myauthserver")
            .secret("verysecretpassword")               // (2)
            .redirectUris("http://localhost:8080/")     // (3)
            .authorizedGrantTypes("authorization_code") // (4)
            .scopes("myscope")                          // (5)
            .autoApprove(true);                         // (6)
}
...

...

@Override

public void configure(ClientDetailsServiceConfigurer clients) throws Exception {

clients.inMemory() // (1)

.withClient("myauthserver")

.secret("verysecretpassword") // (2)

.redirectUris("http://localhost:8080/") // (3)

.authorizedGrantTypes("authorization_code") // (4)

.scopes("myscope") // (5)

.autoApprove(true); // (6)

}

...

We configure everything in-memory for simplicity, but it is also possible to get the details from e.g. a database
The client authenticates with the credentials myauthserver / verysecretpassword
Specify the allowed redirect URI patterns, this prevents random parties from gaining an access token (e.g. XSRF attacks)
OAuth2 supports different grant types, of which the Authorization Code type is the most known. For more information about grant types, see here
When a client (application) authorizes with the Authorization Server, the server can assign one or more scopes to the client. In simple terms, a client scope can be seen as a specific permission for this client. With client scopes, it is possible to allow some applications to have more access rights to user resources than other applications. This is out of scope (pun intended) for this article.
It is possible to make the Authorization Server ask the user permission for the client to obtain rights to access their resources. In our case we automatically approve the request.

Resource Server configuration

An application acting as an OAuth2 client to My Auth Server may need to be able to fetch information about a user, given a valid OAuth2 access token. To serve this information, we add a REST Controller, and secure this resource by configuring the My Auth Server as an OAuth2 Resource Server.

The REST Controller is a standard Spring @RestController, with one request mapping:

...
@RequestMapping(value = { "/user" }, produces = "application/json")
public Map<String, Object> user(OAuth2Authentication user) {              // (1)
    Map<String, Object> userDetails = new HashMap<>();
    userDetails.put("user", user.getUserAuthentication().getPrincipal()); // (2)
    userDetails.put("authorities", AuthorityUtils.authorityListToSet(
            user.getUserAuthentication().getAuthorities()));              // (3)
    return userDetails;
}
...

...

@RequestMapping(value = { "/user" }, produces = "application/json")

public Map<String, Object> user(OAuth2Authentication user) { // (1)

Map<String, Object> userDetails = new HashMap<>();

userDetails.put("user", user.getUserAuthentication().getPrincipal()); // (2)

userDetails.put("authorities", AuthorityUtils.authorityListToSet(

user.getUserAuthentication().getAuthorities())); // (3)

return userDetails;

}

...

The currently logged in user is injected by Spring as an OAuth2Authentication object. This is basically a standard Java Principal, with some added OAuth2-specific details.
We return a map containing the current username,
and a set of user roles.

This is the minimal set of details required for a Spring-enabled OAuth2 client to reconstruct its own OAuth2 Principal object. It is possible to add more details here, if needed. Instead of a Map, some examples on the internet just return the Principal object directly. Although this saves you the overhead of creating a map, we feel it exposes too much unnecessary information. With our approach, we are in control of what information is shared about the user.

The next step is to secure this resource. Of course, we can only provide valid user information, if we have a logged in user. Therefore, we configure My Auth Server as an OAuth2 Resource Server, which basically is a server hosting protected resources, capable of serving these resources when presented with a valid access token. In this case, the protected resource is information about the logged in user. The Resource Server security configuration is defined in ResourceServerConfigurer, using the @EnableResourceServer annotation.

...
@Override
public void configure(HttpSecurity http) throws Exception {
    http.antMatcher("/user")     // (1)
            .authorizeRequests()
            .anyRequest()
            .authenticated();    // (2)
}
...

...

@Override

public void configure(HttpSecurity http) throws Exception {

http.antMatcher("/user") // (1)

.authorizeRequests()

.anyRequest()

.authenticated(); // (2)

}

...

We match our security configuration on the URL /user, matching the request mapping in our ResourceController.
Only authenticated access is allowed.

Spring Security configuration

The last step for My Auth Server is to configure the application security, to define how we want our users to authenticate themselves. We use a pretty standard Spring Security setup, but for the sake of completeness, we describe the configuration below.

The WebSecurityConfigurer modifies the default Spring Security configuration (enabled by the annotation @EnableWebSecurity annotation). We configure the URLs to secure, enable Cross-Site Request Forgery protection, setup a login form, and add some user credentials.

...
@Override
protected void configure(HttpSecurity http) throws Exception {
    http
            .authorizeRequests()
                .antMatchers("/login**").permitAll() // (1)
                .anyRequest().authenticated()        // (2)
            .and().csrf()                            // (3)
            .and().formLogin().loginPage("/login");  // (4)
}

@Override
protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    auth
            .inMemoryAuthentication()                // (5)
                .withUser("user").password("password").roles("USER")
            .and()
                .withUser("admin").password("admin").roles("USER", "ADMIN");
}
...

...

@Override

protected void configure(HttpSecurity http) throws Exception {

http

.authorizeRequests()

.antMatchers("/login**").permitAll() // (1)

.anyRequest().authenticated() // (2)

.and().csrf() // (3)

.and().formLogin().loginPage("/login"); // (4)

}

@Override

protected void configure(AuthenticationManagerBuilder auth) throws Exception {

auth

.inMemoryAuthentication() // (5)

.withUser("user").password("password").roles("USER")

.and()

.withUser("admin").password("admin").roles("USER", "ADMIN");

}

...

The login page is located at /login, and should be publicly available.
All other requests should be authenticated.
Enable Cross-Site Request Forgery (CSRF) protection.
Configure the form login page at /login.
For simplicity, we use an in-memory user database with two users: a normal user and an administrator.

The login form is a simple html form, generated using a Thymeleaf template. The template is located at my-auth-server/src/main/resources/templates/login.html, and made available using a Spring MVC View Controller, defined in my-auth-server/src/main/java/com/jdriven/example/cloudsecurity/config/WebMvcConfigurer.java.

Using the Identity Provider to secure My Website

Now that we have set up our Identity Provider (My Auth Server), we need to configure My Website to use it. This is a very easy task, consisting of three parts.

Spring Cloud Starter OAuth2

We add a dependency in the My Website project to Spring Cloud Starter OAuth2.

...
dependencies {
	compile('org.springframework.cloud:spring-cloud-starter-oauth2')
	...
}
...

...

dependencies {

compile('org.springframework.cloud:spring-cloud-starter-oauth2')

...

}

...

Spring Security Configuration

We configure the security in WebSecurityConfigurer (which is a Spring Web Security Configurer Adapter), using the @EnableOAuth2Sso annotation to enable OAuth2. The security configuration itself is pretty straightforward.

...
@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            .antMatchers("/").permitAll()   // (1)
            .anyRequest().authenticated();  // (2)
}
...

...

@Override

protected void configure(HttpSecurity http) throws Exception {

http.authorizeRequests()

.antMatchers("/").permitAll() // (1)

.anyRequest().authenticated(); // (2)

}

...

Allow navigating to the index page at /.
Secure all the other URLs.

Application configuration

The last step is to add some properties to our application configuration in application.yml. These properties configure My Website to use the URLs provided by My Auth Server.

...
security:
  oauth2:
    client:
      accessTokenUri: http://localhost:9090/auth/oauth/token           // (1)
      userAuthorizationUri: http://localhost:9090/auth/oauth/authorize // (2)
      clientId: myauthserver                                           // (3)
      clientSecret: verysecretpassword                                 // (4)
    resource:
      userInfoUri: http://localhost:9090/auth/user                     // (5)
...

...

security:

oauth2:

client:

accessTokenUri: http://localhost:9090/auth/oauth/token // (1)

userAuthorizationUri: http://localhost:9090/auth/oauth/authorize // (2)

clientId: myauthserver // (3)

clientSecret: verysecretpassword // (4)

resource:

userInfoUri: http://localhost:9090/auth/user // (5)

...

The URL used by an OAuth2 client to acquire an OAuth2 access token.
The URL to which the user will be redirected to authorize access to a resource.
The client ID specified earlier in the Authorization Server configuration.
The client password specified earlier in the Authorization Server configuration.
The user info resource URL, specified earlier in the Resource Server configuration.

Tip To see the resulting source code at this point, checkout the Git tag secure-website.

That’s it! If we run both the My Auth Server application and the My Website application (see How to run it), and navigate to http://localhost:8080/time, we will see that the URL is now secured, and we need to login first. Congratulations, your website is now secure!

Up next

In the next articles in this series, we will discuss the following topics:

After having secured a single application, we will add a new application, a REST service, which we will also secure through My Auth Server in a Single Sign On (SSO) configuration.
We will call the REST service from the browser using client side Javascript, proxying the service calls through My Website using Netflix Zuul.
Then, we will make the REST service stateless (no sessions), remaining secure by using JSON Web Tokens (JWT).
Finally, we will add the ability to login using a Google account.

Spicy Spring: Customize error JSON response with ErrorAttributes

Posted on June 29, 2016 by Willem Cheizoo

The default JSON error body of Spring Boot can be customized or extended by defining our own ErrorAttributes implementation. In Spring Boot we get an error response JSON format for free. Any thrown Exception is automatically translated to this JSON format and returned with a corresponding HTTP status.

Default implementation

As soon as we throw an Exception in a @RequestMapping annotated method of a @Controller, the thrown Exception is translated to a HTTP status and a JSON error body.

The default JSON error body looks like:

{
  "timestamp": 1467191865498,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "java.lang.IllegalStateException",
  "message": "This is my exception message",
  "path": "/myendpoint"
}

{

"timestamp": 1467191865498,

"status": 500,

"error": "Internal Server Error",

"exception": "java.lang.IllegalStateException",

"message": "This is my exception message",

"path": "/myendpoint"

}

Write your own ErrorAttributes implementation

What if we want extra attributes in this JSON error body?

Just define an implementation for ErrorAttributes and register it as a Spring @Component. The following example will result in a customized JSON error response body with the cause of the exception included.

import org.springframework.boot.autoconfigure.web.DefaultErrorAttributes;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestAttributes;

import java.util.HashMap;
import java.util.Map;

@Component
public class MyCustomErrorAttributes extends DefaultErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(RequestAttributes requestAttributes, boolean includeStackTrace) {
        Map<String, Object> errorAttributes = super.getErrorAttributes(requestAttributes, includeStackTrace);

        Throwable throwable = getError(requestAttributes);
        Throwable cause = throwable.getCause();
        if (cause != null) {
            Map<String, Object> causeErrorAttributes = new HashMap<>();
            causeErrorAttributes.put("exception", cause.getClass().getName());
            causeErrorAttributes.put("message", cause.getMessage());
            errorAttributes.put("cause", causeErrorAttributes);
        }
        return errorAttributes;
    }
}

import org.springframework.boot.autoconfigure.web.DefaultErrorAttributes;

import org.springframework.stereotype.Component;

import org.springframework.web.context.request.RequestAttributes;

import java.util.HashMap;

import java.util.Map;

@Component

public class MyCustomErrorAttributes extends DefaultErrorAttributes {

@Override

public Map<String, Object> getErrorAttributes(RequestAttributes requestAttributes, boolean includeStackTrace) {

Map<String, Object> errorAttributes = super.getErrorAttributes(requestAttributes, includeStackTrace);

Throwable throwable = getError(requestAttributes);

Throwable cause = throwable.getCause();

if (cause != null) {

Map<String, Object> causeErrorAttributes = new HashMap<>();

causeErrorAttributes.put("exception", cause.getClass().getName());

causeErrorAttributes.put("message", cause.getMessage());

errorAttributes.put("cause", causeErrorAttributes);

}

return errorAttributes;

}

Our resulting body will now look like:

{
  "timestamp": 1467191865498,
  "status": 500,
  "error": "Internal Server Error",
  "exception": "java.lang.IllegalStateException",
  "message": "This is my exception message",
  "path": "/myendpoint",
  "cause": {
    "exception": "java.lang.IllegalArgumentException",
    "message": "This is the cause...."
  }
}

{

"timestamp": 1467191865498,

"status": 500,

"error": "Internal Server Error",

"exception": "java.lang.IllegalStateException",

"message": "This is my exception message",

"path": "/myendpoint",

"cause": {

"exception": "java.lang.IllegalArgumentException",

"message": "This is the cause...."

}

Happy developing!