REST API with JWT authentication using Jersey and CDI

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

• Jersey: JAX-RS reference implementation for creating RESTful web services in Java.
• Jackson: JSON parser for Java.
• Undertow: Servlet container.
• Weld: CDI reference implementation.
• Hibernate ORM: Persistence framework for relational databases (JPA implementation).
• Arquillian: Testing framework.
• JJWT: Library for creating and parsing JSON Web Tokens (JWTs) in Java.
• jBCrypt: Implementation for the bcrypt password hashing function in Java.
• H2: In memory relational database.

This example is inspired in my Stack Overflow best answer about token-based authentication in Jersey.

Note: For an implementation using Spring Security, have a look at the jersey-jwt-springsecurity 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-1.0.jar.
7. Execute the JAR: java -jar jersey-jwt-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:

Quick words on Undertow and uber-jars

This application is packed as an uber-jar, making it easy to run, so you don't need to be bothered by installing a servlet container such as Tomcat and then deploy the application on it. Just execute java -jar <jar-file> and the application will be up and running.

This application uses Undertow, a lighweight Servlet container designed to be fully embeddable. It's used as the default web server in the WildFly Application Server.

The uber-jar is created with the Apache Maven Shade Plugin, that provides the capability to create an executable jar including its dependencies.

Application overview

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

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

• AuthenticationFilter: ContainerRequestFilter implementation for extracting the authentication token from the Authorization header of the HTTP request.

• AuthorizationFilter: ContainerRequestFilter implementation for performing role-based authorization using Java Security annotations such as @RolesAllowed, @PermitAll and @DenyAll. This implementation uses the Jersey's RolesAllowedDynamicFeature as reference and should work with other JAX-RS implementations.

• TokenBasedSecurityContext: SecurityContext implementation for token-based authentication.

• AuthenticatedUserDetails: Principal implementation that holds details about the authenticated user. Used in the TokenBasedSecurityContext.

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.