Spring Security Addon for JWT

Providing a simple way to integrate JWT into your spring boot application.

This project is split into multiple parts:

• base: Basic integration of JWT into spring security (without refresh tokens)
• internal: Support for an in-memory cache (ExpiringMap) for refresh tokens
• memcache: Support for memcache to store refresh tokens
• hibernate: Support for hibernate to store refresh tokens
• redis: Support for redis to store refresh tokens
• files: Support for filesystem to store refresh tokens

Simply use the dependencies within your build script, spring boot takes care of the rest. The default configuration should be sufficient for the most use cases.

Contents

• base:
  • JWT Integration into Spring Security (including some REST-Controllers to authenticate against)
  • A CryptPasswordEncoder to generate / use linux system crypt(1)-hashes (supporting the newer $5$ and $6$ hashes and rounds)
  • Full support for Swagger 2 documentation (REST Controller and DTO are annotated and described)
• module internal:
  • Refresh token support through an internal, in-memory map
• module memcache:
  • Refresh token support through an external memcache server
• module hibernate:
  • Refresh token support using hibernate and a database table
• module redis:
  • Refresh token support using a redis server
• module files:
  • Refresh token support using a json file
• various *-spring-boot-starter:
  • Spring boot starter modules to integrate into the autoconfiguration ecosystem

Dependencies

<dependencies>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-base</artifactId>
        <version>5.0.2</version>
    </dependency>
    <!-- or -->
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-base-spring-boot-starter</artifactId>
        <version>5.0.2</version>
    </dependency>
</dependencies>

When you want to add refresh token support, then choose one of the following dependencies:

<dependencies>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-internal</artifactId>
        <version>5.0.2</version>
    </dependency>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-memcache</artifactId>
        <version>5.0.2</version>
    </dependency>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-hibernate</artifactId>
        <version>5.0.2</version>
    </dependency>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-redis</artifactId>
        <version>5.0.2</version>
    </dependency>
    <dependency>
        <groupId>eu.fraho.spring</groupId>
        <artifactId>security-jwt-files</artifactId>
        <version>5.0.2</version>
    </dependency>
</dependencies>

For details on the usage of the plugins please see the README within the relevant module directories.

Usage

Starting with version 1.0.0 there are two ways on how to use these libraries.

The old way is by directly using the libraries as dependencies and doing some manual configuration. The newer way used spring boot autoconfiguration and reduced the needed configuration a lot.

To see this library "in action", please take a look at the examples.

Spring boot and library versions

The minimum supported spring boot version and java version changed during the lifetime of this library and sadly wasn't always aligned to the semantic versioning scheme. Take the following table of supported versions as reference prior updating this library in your project.

Spring Boot Autoconfig (recommended):

• Use any *-spring-boot-starter dependency you like
• Bouncycastle will be automagically loaded and installed if on classpath
• My enhanced PasswordEncoder (using Unix-Crypt-Style hashes) will be used as default

Manual configuration (legacy):

• Add the dependencies to your build script
• Configure your boot application to pick up our components (add "eu.fraho.spring.securityJwt" to the scanBasePackages field of your @SpringBootApplication)
• Optionally add the BouncyCastle Provider (e.g. within the main-Method)
  • Hint: This is required if you would like to use the ECDSA signature algorithm!
• Optionally use my enhanced PasswordEncoder as a @Bean
• Optionally choose a refresh token store implementation and set it as fraho.jwt.refresh.cache-impl

General steps for both methods:

• Create an implementation of UserDetailsService that returns an instance of JwtUser
• By default, this service creates a random hmac secret for signatures on each startup. To stay consistent accross service restarts and not kicking clients out please either change the algorithm (recommended) or specifiy at least an hmac keyfile.

Usage for clients

• Request new tokens by sending an authentication request to /auth/login
• Somehow store the received token(s)
  • Or use the cookie flow so the browser can store the tokens safely
• To access a secured controller set the retrieved token as Authorization: <TokenType> <Token>
  • When using cookies this is done automatically by your browser

Configuration

This library will run out-of the box, but you should at least take a look at the different configuration properties. I tried to make them reasonable secure, but if you're really paranoid you can change them as you like.

By default, this library creates an hmac secret on startup. As this is no problem for testing and running your application you are strongly adviced to define a static key. Otherwise you will render all access tokens invalid upon service restart, thus requiring your clients to login again.

I recommend using ECDSA for tokens (you can use this class for that) and setting the algorithm field to something like ES256.

Token configuration (Prefix fraho.jwt.token)

Refresh configuration (Prefix fraho.jwt.refresh)

Other configuration properties

Building

# on linux:
./gradlew assemble
# on windows:
gradlew.bat assemble

Hacking

• This repository uses the git flow layout
• Changes are welcome, but please use pull requests with separate branches
• TravisCI has to pass before merging
• Code coverage should stay about the same level (please write tests for new features!)
• When writing new modules please use my abstract testclasses which provide a great base ( see internal for an example)

Releasing

Releasing is done with the default gradle tasks:

# to local repository:
./gradlew publishToMavenLocal
# to central:
./gradlew publish

JWT Request Flow

UML (with headers)

UML (with cookies)

HTTP-Requests

Request a token (login):

> POST /auth/login HTTP/1.1
> Host: localhost:8080
> Content-Type: application/json
> Content-Length: 63
>
> {
>   "username": "userA",
>   "password": "userA"
> }
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Content-Length: 491
<
< {
<   "accessToken": {
<     "token": "eyJhbGciOiJFUzI1NiJ9.<some more token code>",
<     "expiresIn": 3600,
<     "type": "Bearer"
<   },
<   "refreshToken": {
<     "token": "5bYNdXEGQRzz6xD4yFmw2wNPjXAh+wMc",
<     "expiresIn": 604800
<   }
< }

Usage of token to access some (secured) data:

> GET /users HTTP/1.1
> Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Content-Length: 42
<
< (some json content, result of request)

Use refresh token when token expired:

> POST /auth/refresh HTTP/1.1
> Content-Type: application/json
> Content-Length: 56
>
> {
>   "refreshToken": "5bYNdXEGQRzz6xD4yFmw2wNPjXAh+wMc"
> }
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Content-Length: 491
< Date: Fri, 19 May 2017 08:05:19 GMT
<
< {
<   "accessToken": {
<     "token": "eyJhbGciOiJFUzI1NiJ9.<some more token code>",
<     "expiresIn": 3600,
<     "type": "Bearer"
<   },
<   "refreshToken": {
<     "token": "U3LFL8dVZAeAp8Js6db2zrHGPfGslIeQ",
<     "expiresIn": 604800
<   }
< }