REST API with JWT authentication using Jersey and Spring Security

This sample application demonstrates how to perform token-based authentication using:

• Spring Boot: Framework for creating standalone Java applications.
• Spring Security: Framework for authentication and authorization.
• Spring Data JPA: Framework for implementing JPA repositories.
• H2: In memory relational database.
• Jersey: JAX-RS reference implementation for creating RESTful web services in Java.
• Jackson: JSON parser for Java.
• JJWT: Library for creating and parsing JSON Web Tokens (JWTs) in Java.

Note: For a CDI and JAX-RS approach without Spring (Boot, Data and Security), have a look at the jersey-jwt project.

How token-based authentication works?

In a token-based authentication, the client exchanges hard credentials (such as username and password) for a piece of data called token. Instead of sending the hard credentials in every request, the client will send the token to the server to perform authentication and authorisation.

In a few words, an authentication scheme based on tokens follow these steps:

1. The client sends their credentials (username and password) to the server.
2. The server authenticates the credentials and issues a token.
3. The server can store the previously generated token in some storage along with the user identifier.
4. The server sends the generated token in the response.
5. In each request, the client sends the token to the server.
6. The server, in each request, extracts the token from the incoming request. With the token, the server looks up the user details to perform authentication and authorisation.
   1. If the token is valid, the server accepts the request.
   2. If the token is invalid, the server refuses the request.
7. The server can provide an endpoint to refresh tokens.

What tokens can be like?

A token can be opaque which reveals no details other than the value itself (like a random string) or can be self-contained (like JWT, which is used in this example).

JWT stands for JSON Web Token. It's a standard method for representing claims securely between two parties, defined in the RFC 7519. JWT is a self-contained token and enables you to store a user identifier, an expiration date and whatever you want (but don't store passwords) in a payload, which is a JSON encoded as Base64. The payload can be read by the client and the integrity of the token can be easily checked by verifying its signature on the server.

To find some great resources to work with JWT, have a look at http://jwt.io.

JWT allows you to perform stateless authentication, that is, you won't need to persist JWT tokens if you don't need to track them. Although, by persisting the tokens, you will have the possibility of invalidating and revoking the access of them. To keep the track of JWT tokens, instead of persisting the whole token, you could persist the token identifier (the jti claim) and some metadata (the user you issued the token for, the expiration date, etc) if you need.

Your application can provide some functionality to revoke the tokens, but always consider revoking the tokens when the users change their password. When persisting tokens, consider removing the old ones in order to prevent your database from growing indefinitely.

Building and running this application

To build and run this application, follow these steps:

1. Open a command line window or terminal.
2. Navigate to the root directory of the project, where the pom.xml resides.
3. Compile the project: mvn clean compile.
4. Package the application: mvn package.
5. Change into the target directory: cd target
6. You should see a file with the following or a similar name: jersey-jwt-springsecurity-1.0.jar.
7. Execute the JAR: java -jar jersey-jwt-springsecurity-1.0.jar.
8. The application should be available at http://localhost:8080/api.

When the application starts up, the database will be populated with the following users:

Application overview

Find below a quick description of the most relevant classes of this application:

• WebSecurityConfig: Spring Security configuration class.

• AuthenticationResource: REST endpoint for exchanging hard credentials for a JWT token.

• JwtAuthenticationToken: Authentication implementation designed for presentation of a JWT token.

• JwtAuthenticationTokenFilter: OncePerRequestFilter for extracting the authentication token from the Authorization header of the HTTP request.

• JwtAuthenticationProvider: AuthenticationProvider used to authenticate the JWT token.

• JwtAuthenticationEntryPoint: AuthenticationEntryPoint implementation that simply returns error details related to authentication failures.

• DefaultUserDetailsService: UserDetailsService implementation.

REST API overview

See the curl scripts below with the REST API supported operations:

Exchange hard credentials for an authentication token

Valid credentials must be sent in the request payload to be exchanged for a token.

curl -X POST \
  'http://localhost:8080/api/auth' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "<username>",
  "password": "<password>"
}'

Get a public greeting

No authentication is required to perform this operation.

curl -X GET \
  'http://localhost:8080/api/greetings/public' \
  -H 'Accept: text/plain'

Get a greeting for the user

Authentication and USER role are required to perform this operation.

curl -X GET \
  'http://localhost:8080/api/greetings/protected' \
  -H 'Accept: text/plain' \
  -H 'Authorization: Bearer <authentication-token>'

Get all users

Authentication and ADMIN role are required to perform this operation.

curl -X GET \
  'http://localhost:8080/api/users' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <authentication-token>'

Get a user by id

Authentication and ADMIN role are required to perform this operation.

curl -X GET \
  'http://localhost:8080/api/users/<user-id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <authentication-token>'

Get the current user

No authentication is required to perform this operation. However, if the request is performed with a valid token, the server will return details for the current user.

curl -X GET \
  'http://localhost:8080/api/users/me' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <authentication-token>'

Targeting the REST API with Postman

Alternatively to curl, you can use Postman to target the REST API. The Postman collection files are available in the src/main/postman directory.