Micronaut JWT Authentication

Learn how to secure a Micronaut app using JWT (JSON Web Token) Authentication.

Authors: Sergio del Amo

Micronaut Version: 2.5.0

1. Getting Started

Micronaut ships with security capabilities based on Json Web Token (JWT). JWT is an IETF standard which defines a secure way to encapsulate arbitrary data that can be sent over unsecure URL’s.

In this guide you are going to create a Micronaut app and secure it with JWT.

The following sequence illustrates the authentication flow:

2. What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE
JDK 1.8 or greater installed with JAVA_HOME configured appropriately

3. Solution

We recommend that you follow the instructions in the next sections and create the app step by step. However, you can go right to the completed example.

Download and unzip the source

4. Writing the application

4.1. Create an App with the Command Line Interface

Create an app using the Micronaut Command Line Interface.

mn create-app example.micronaut.micronautguide --build=maven --lang=kotlin

The previous command creates a micronaut app with the default package example.micronaut in a folder named micronautguide.

If you are using Java or Kotlin and IntelliJ IDEA, make sure you have enabled annotation processing.

4.2. Security Dependency

Add Micronaut’s security-jwt dependency.

pom.xml

<!-- Add the following to your annotationProcessorPaths element -->
<annotationProcessorPath>
    <groupId>io.micronaut.security</groupId>
    <artifactId>micronaut-security-annotations</artifactId>
</annotationProcessorPath>
<dependency>
    <groupId>io.micronaut.security</groupId>
    <artifactId>micronaut-security-jwt</artifactId>
    <scope>compile</scope>
</dependency>

4.3. Configuration

Add the following to application.yml:

src/main/resources/application.yml

micronaut:
  security:
    authentication: bearer (1)
    token:
      jwt:
        signatures:
          secret:
            generator:
              secret: '"${JWT_GENERATOR_SIGNATURE_SECRET:pleaseChangeThisSecretForANewOne}"' (2)

1	Set `authentication` to `bearer` to receive a JSON response from the login endpoint.
2	Change this by your own secret and keep it safe (do not store this in your VCS).

4.4. Authentication Provider

To keep this guide simple, create a naive AuthenticationProvider to simulate user’s authentication.

src/main/kotlin/example/micronaut/AuthenticationProviderUserPassword.kt

package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.security.authentication.AuthenticationException
import io.micronaut.security.authentication.AuthenticationFailed
import io.micronaut.security.authentication.AuthenticationProvider
import io.micronaut.security.authentication.AuthenticationRequest
import io.micronaut.security.authentication.AuthenticationResponse
import io.micronaut.security.authentication.UserDetails
import io.reactivex.BackpressureStrategy
import io.reactivex.Flowable
import io.reactivex.FlowableEmitter
import org.reactivestreams.Publisher
import javax.inject.Singleton

@Singleton (1)
class AuthenticationProviderUserPassword : AuthenticationProvider { (2)

    override fun authenticate(
        httpRequest: HttpRequest<*>?,
        authenticationRequest: AuthenticationRequest<*, *>
    ): Publisher<AuthenticationResponse> {
        return Flowable.create({ emitter: FlowableEmitter<AuthenticationResponse> ->
            if (authenticationRequest.identity == "sherlock" && authenticationRequest.secret == "password") {
                emitter.onNext(UserDetails(authenticationRequest.identity as String, ArrayList()))
                emitter.onComplete()
            } else {
                emitter.onError(AuthenticationException(AuthenticationFailed()))
            }
        }, BackpressureStrategy.ERROR)
    }
}

1	To register a Singleton in Micronaut’s application context, annotate your class with `javax.inject.Singleton`
2	A Micronaut’s Authentication Provider implements the interface `io.micronaut.security.authentication.AuthenticationProvider`

4.5. Controller

Create a file named HomeController which resolves the base URL /:

src/main/kotlin/example/micronaut/HomeController.kt

package example.micronaut

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Produces
import io.micronaut.security.annotation.Secured
import java.security.Principal

@Secured("isAuthenticated()") (1)
@Controller("/") (2)
class HomeController {

    @Produces(MediaType.TEXT_PLAIN) (3)
    @Get("/")  (4)
    fun index(principal: Principal): String {  (5)
        return principal.name
    }
}

1	Annotate with `io.micronaut.security.Secured` to configure secured access. The `isAuthenticated()` expression will allow access only to authenticated users.
2	Annotate with `io.micronaut.http.annotation.Controller` to designate a class as a Micronaut’s controller.
3	You can specify the HTTP verb that a controller’s action responds to. To respond to a GET request, use the `io.micronaut.http.annotation.Get` annotation.
4	If a user is authenticated, Micronaut will bind the user object to an argument of type `java.security.Principal` (if present).

5. Tests

Create a test to verify a user is able to login and access a secured endpoint.

src/test/kotlin/example/micronaut/JwtAuthenticationTest.kt

package example.micronaut

import com.nimbusds.jwt.JWTParser
import com.nimbusds.jwt.SignedJWT
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.MediaType
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.security.authentication.UsernamePasswordCredentials
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertNotNull
import org.junit.jupiter.api.Assertions.assertThrows
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.function.Executable
import javax.inject.Inject

@MicronautTest (1)
class JwtAuthenticationTest {

    @Inject
    @field:Client("/")
    lateinit var client: HttpClient (2)

    @Test
    fun accessingASecuredUrlWithoutAuthenticatingReturnsUnauthorized() {
        val e = Executable {
            client.toBlocking().exchange<Any, Any>(HttpRequest.GET<Any>("/").accept(MediaType.TEXT_PLAIN)) (3)
        }
        val thrown = assertThrows(HttpClientResponseException::class.java, e)
        assertEquals(thrown.status, HttpStatus.UNAUTHORIZED) (3)
    }

    @Test
    fun uponSuccessfulAuthenticationAJsonWebTokenIsIssuedToTheUser() {
        val creds = UsernamePasswordCredentials("sherlock", "password")
        val request: HttpRequest<Any> = HttpRequest.POST("/login", creds) (4)
        val rsp: HttpResponse<BearerAccessRefreshToken> =
            client.toBlocking().exchange(request, BearerAccessRefreshToken::class.java) (5)
        assertEquals(HttpStatus.OK, rsp.status)

        val bearerAccessRefreshToken: BearerAccessRefreshToken = rsp.body()!!
        assertEquals("sherlock", bearerAccessRefreshToken.username)
        assertNotNull(bearerAccessRefreshToken.accessToken)
        assertTrue(JWTParser.parse(bearerAccessRefreshToken.accessToken) is SignedJWT)

        val accessToken: String = bearerAccessRefreshToken.accessToken
        val requestWithAuthorization = HttpRequest.GET<Any>("/")
            .accept(MediaType.TEXT_PLAIN)
            .bearerAuth(accessToken) (6)
        val response: HttpResponse<String> = client.toBlocking().exchange(requestWithAuthorization, String::class.java)
        assertEquals(HttpStatus.OK, rsp.status)
        assertEquals("sherlock", response.body()!!) (7)
    }
}

1	Annotate the class with `@MicronautTest` to let Micronaut starts the embedded server and inject the beans. More info: https://micronaut-projects.github.io/micronaut-test/latest/guide/index.html.
2	Inject the `HttpClient` bean in the application context.
3	When you include the security dependencies, security is considered enabled and every endpoint is secured by default.
4	To login, do a POST request to `/login` with your credentials as a JSON payload in the body of the request.
5	Micronaut makes it easy to bind JSON responses into Java objects.
6	Micronaut supports RFC 6750 Bearer Token specification out-of-the-box. We supply the JWT token in the `Authorization` HTTP Header.
7	Use `.body()` to retrieve the parsed payload.

5.1. Use Micronaut’s HTTP Client and JWT

If you want to access a secured endpoint, you can also use Micronaut’s HTTP Client and supply the JWT token in the Authorization header.

First create a @Client with a method home which accepts an Authorization HTTP Header.

src/test/kotlin/example/micronaut/AppClient.kt

package example.micronaut

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Header
import io.micronaut.http.annotation.Post
import io.micronaut.http.client.annotation.Client
import io.micronaut.security.authentication.UsernamePasswordCredentials
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken

@Client("/")
interface AppClient {

    @Post("/login")
    fun login(@Body credentials: UsernamePasswordCredentials): BearerAccessRefreshToken

    @Consumes(MediaType.TEXT_PLAIN)
    @Get("/")
    fun home(@Header("authorization") authorization: String): String
}

Create a test which uses the previous @Client

src/test/kotlin/example/micronaut/DeclarativeHttpClientWithJwtTest.kt

package example.micronaut

import com.nimbusds.jwt.JWTParser
import com.nimbusds.jwt.SignedJWT
import io.micronaut.security.authentication.UsernamePasswordCredentials
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertNotNull
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
import javax.inject.Inject

@MicronautTest
class DeclarativeHttpClientWithJwtTest {

    @Inject
    lateinit var appClient: AppClient (1)

    @Test
    fun verifyJwtAuthenticationWorksWithDeclarativeClient() {
        val creds: UsernamePasswordCredentials = UsernamePasswordCredentials("sherlock", "password")
        val loginRsp: BearerAccessRefreshToken = appClient.login(creds) (2)

        assertNotNull(loginRsp)
        assertNotNull(loginRsp.accessToken)
        assertTrue(JWTParser.parse(loginRsp.accessToken) is SignedJWT)

        val msg = appClient.home("Bearer ${loginRsp.accessToken}") (3)

        assertEquals("sherlock", msg)
    }
}

1	Inject `AppClient` bean from application context.
2	To login, do a POST request to `/login` with your credentials as a JSON payload in the body of the request.
3	Supply the JWT to the HTTP `Authorization` header value to the `@Client` method.

6. Issuing a Refresh Token

Access tokens expire. You can control the expiration with micronaut.security.token.jwt.generator.access-token-expiration. In addition to the access token, you can configure your login endpoint to also return a refresh token. You can use the refresh token to obtain a new access token.

First, add the following configuration:

src/main/resources/application.yml

micronaut:
  security:
    token:
      jwt:
        generator:
          refresh-token:
            secret: '"${JWT_GENERATOR_SIGNATURE_SECRET:pleaseChangeThisSecretForANewOne}"' (1)

1 To generate a refresh token your app must have beans of type: RefreshTokenGenerator, RefreshTokenValidator. RefreshTokenPersistence. We will deal with the latter in the next section. For the generator and validator, Micronaut Security ships with SignedRefreshTokenGenerator. It creates and verifies a JWS (JSON web signature) encoded object whose payload is a UUID with a hash-based message authentication code (HMAC). You need to provide secret to use SignedRefreshTokenGenerator which implements both RefreshTokenGenerator and RefreshTokenValidator.

Create a test to verify the login endpoint responds both access and refresh token:

src/test/kotlin/example/micronaut/LoginIncludesRefreshTokenTest.kt

package example.micronaut

import com.nimbusds.jwt.JWTParser
import com.nimbusds.jwt.SignedJWT
import io.micronaut.http.HttpRequest
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.security.authentication.UsernamePasswordCredentials
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.Test
import java.text.ParseException
import javax.inject.Inject

@MicronautTest
class LoginIncludesRefreshTokenTest {

    @Inject
    @field:Client("/")
    var client: RxHttpClient? = null

    @Test
    @Throws(ParseException::class)
    fun uponSuccessfulAuthenticationUserGetsAccessTokenAndRefreshToken() {
        val creds = UsernamePasswordCredentials("sherlock", "password")
        val request: HttpRequest<Any> = HttpRequest.POST("/login", creds)
        val rsp: BearerAccessRefreshToken =
            client!!.toBlocking().retrieve(request, BearerAccessRefreshToken::class.java)
        Assertions.assertEquals("sherlock", rsp.username)
        Assertions.assertNotNull(rsp.accessToken)
        Assertions.assertNotNull(rsp.refreshToken) (1)
        Assertions.assertTrue(JWTParser.parse(rsp.accessToken) is SignedJWT)
    }
}

1	A refresh token is returned.

6.1. Save Refresh Token

We may want to save refresh token issued by the application. For example, to be revoked a user’s refresh tokens. So that a particular user can not obtain a new access token, and thus access the application’s endpoints.

Persist the refresh tokens with help of Micronaut Data.

Micronaut Data is a database access toolkit that uses Ahead of Time (AoT) compilation to pre-compute queries for repository interfaces that are then executed by a thin, lightweight runtime layer.

In particular, use Micronaut JDBC

Micronaut Data JDBC is an implementation that pre-computes native SQL queries (given a particular database dialect) and provides a repository implementation that is a simple data mapper between a JDBC ResultSet and an object.

Add the following dependencies:

pom.xml

<!-- Add the following to your annotationProcessorPaths element -->
<annotationProcessorPath> (1)
    <groupId>io.micronaut</groupId>
    <artifactId>micronaut-data-processor</artifactId>
</annotationProcessorPath>
<dependency> (2)
    <groupId>io.micronaut.data</groupId>
    <artifactId>micronaut-data-jdbc</artifactId>
    <scope>compile</scope>
</dependency>
<dependency> (3)
    <groupId>io.micronaut.sql</groupId>
    <artifactId>micronaut-jdbc-hikari</artifactId>
    <scope>compile</scope>
</dependency>
<dependency> (4)
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

1	Micronaut data is a build time tool. You need to add the build time annotation processor
2	Add the Micronaut Data JDBC dependency
3	Add a Hikari connection pool
4	Add a JDBC driver. Add H2 driver

Create an entity to save the issued Refresh Tokens.

src/main/kotlin/example/micronaut/RefreshTokenEntity.kt

package example.micronaut

import io.micronaut.data.annotation.DateCreated
import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity
import java.time.Instant
import javax.validation.constraints.NotBlank

@MappedEntity (1)
data class RefreshTokenEntity(
    @field:Id (2)
    @GeneratedValue (3)
    var id: Long? = null,

    @NotBlank
    var username: String,

    @NotBlank
    var refreshToken: String,

    var revoked: Boolean,

    @DateCreated (4)
    var dateCreated: Instant? = null,

)

1	Specifies the entity is mapped to the database
2	Specifies the ID of an entity
3	Specifies that the property value is generated by the database and not included in inserts
4	Allows assigning a data created value (such as a `java.time.Instant`) prior to an insert

Create a CrudRepository to include methods to peform Create, Read, Updated and Delete operations with the RefreshTokenEntity.

src/main/kotlin/example/micronaut/RefreshTokenRepository.kt

package example.micronaut

import io.micronaut.data.jdbc.annotation.JdbcRepository
import io.micronaut.data.model.query.builder.sql.Dialect
import io.micronaut.data.repository.CrudRepository
import java.util.Optional
import javax.transaction.Transactional
import javax.validation.constraints.NotBlank
import javax.validation.constraints.NotNull

@JdbcRepository(dialect = Dialect.H2) (1)
interface RefreshTokenRepository : CrudRepository<RefreshTokenEntity?, Long?> { (2)

    @Transactional
    fun save(username: @NotBlank String,
             refreshToken: @NotBlank String,
             revoked: @NotNull Boolean): RefreshTokenEntity? (3)

    fun findByRefreshToken(refreshToken: @NotBlank String): Optional<RefreshTokenEntity> (4)

    fun updateByUsername(username: @NotBlank String,
                         revoked: @NotNull Boolean): Long (5)
}

1	The interface is annotated with @JdbcRepository and specifies a dialect of H2 used to generate queries
2	The CrudRepository interface take 2 generic arguments, the entity type (in this case `RefreshTokenEntity`) and the ID type (in this case `Long`)
3	When a new refresh token is issued we will use this method to persist it
4	Before issuing a new access token, we will use this method to see if the supplied refresh token exists
5	We can revoke the refresh tokens of a particular user with this method

6.2. Refresh Controller

To enable the Refresh Controller, you have to enable it via configuration and provide an implementation of RefreshTokenPersistence.

To enable the refresh controller you need to create a bean of type RefreshTokenPersistence which leverages the Micronaut Data repository we coded in the previous section:

src/main/kotlin/example/micronaut/CustomRefreshTokenPersistence.kt

package example.micronaut;

import io.micronaut.runtime.event.annotation.EventListener;
import io.micronaut.security.authentication.UserDetails;
import io.micronaut.security.token.event.RefreshTokenGeneratedEvent;
import io.micronaut.security.token.refresh.RefreshTokenPersistence;
import io.micronaut.security.errors.OauthErrorResponseException;
import io.micronaut.security.errors.IssuingAnAccessTokenErrorCode;
import io.reactivex.BackpressureStrategy;
import io.reactivex.Flowable;
import io.reactivex.FlowableEmitter
import org.reactivestreams.Publisher;

import javax.inject.Singleton;

@Singleton (1)
class CustomRefreshTokenPersistence : RefreshTokenPersistence {

    private var refreshTokenRepository: RefreshTokenRepository

    constructor(refreshTokenRepository: RefreshTokenRepository) {  (2)
        this.refreshTokenRepository = refreshTokenRepository;
    }

    @EventListener (3)
    override fun persistToken(event: RefreshTokenGeneratedEvent?) {
        if (event?.refreshToken != null &&
            event.userDetails != null &&
            event.userDetails.username != null) {
            val payload = event.refreshToken;
            refreshTokenRepository.save(event.userDetails.username, payload, false); (4)
        }
    }

    override fun getUserDetails(refreshToken: String) : Publisher<UserDetails> {
        return Flowable.create({ emitter: FlowableEmitter<UserDetails> ->
            val tokenOpt = refreshTokenRepository.findByRefreshToken(refreshToken);
            if (tokenOpt.isPresent) {
                val token = tokenOpt.get();
                if (token.revoked) {
                    emitter.onError(OauthErrorResponseException(IssuingAnAccessTokenErrorCode.INVALID_GRANT, "refresh token revoked", null)); (5)
                } else {
                    emitter.onNext(UserDetails(token.username, listOf())); (6)
                    emitter.onComplete();
                }
            } else {
                emitter.onError(OauthErrorResponseException(IssuingAnAccessTokenErrorCode.INVALID_GRANT, "refresh token not found", null)); (7)
            }
        }, BackpressureStrategy.ERROR);
    }
}

1	To register a Singleton in Micronaut’s application context annotate your class with `javax.inject.Singleton`
2	Constructor injection of `RefreshTokenRepository`.
3	When a new refresh token is issued, the app emits an event of type RefreshTokenGeneratedEvent. We listen to it and save it in the database.
4	The event contains both the refresh token and the user details associated to the token.
5	Throw an exception if the token is revoked.
6	Return the user details associated to the refresh token. E.g. username, roles, attributes…
7	Throw an exception if the token is not found.

6.3. Test Refresh Token

6.3.1. Test Refresh Token Validation

Refresh tokens issued by SignedRefreshTokenGenerator, the default implementation of RefreshTokenGenerator, are signed.

SignedRefreshTokenGenerator implements both RefreshTokenGenerator and RefreshTokenValidator.

The bean of type RefreshTokenValidator is used by the Refresh Controller to ensure the refresh token supplied is valid.

Create a test for this:

src/test/kotlin/example/micronaut/UnsignedRefreshTokenTest.kt

package example.micronaut

import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpStatus
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.security.token.jwt.endpoints.TokenRefreshRequest
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.Test
import java.util.Optional
import javax.inject.Inject

@MicronautTest
internal class UnsignedRefreshTokenTest {

    @Inject
    @field:Client("/")
    var client: RxHttpClient? = null

    @Test
    fun accessingSecuredURLWithoutAuthenticatingReturnsUnauthorized() {
        val unsignedRefreshedToken = "foo" (1)
        val bodyArgument = Argument.of(BearerAccessRefreshToken::class.java)
        val errorArgument = Argument.of(Map::class.java)
        val e = Assertions.assertThrows(HttpClientResponseException::class.java) {
            client!!.toBlocking().exchange(
                HttpRequest.POST("/oauth/access_token", TokenRefreshRequest(unsignedRefreshedToken)),
                bodyArgument,
                errorArgument
            )
        }
        Assertions.assertEquals(HttpStatus.BAD_REQUEST, e.status)

        val mapOptional: Optional<Map<*, *>> = e.response.getBody(Map::class.java)
        Assertions.assertTrue(mapOptional.isPresent)

        val m = mapOptional.get()
        Assertions.assertEquals("invalid_grant", m["error"])
        Assertions.assertEquals("Refresh token is invalid", m["error_description"])
    }
}

1	Use an unsigned token

6.3.2. Test Refresh Token Not Found

Create a test which verifies a that sending a valid refresh token but which was not persisted returns HTTP Status 400.

src/test/kotlin/example/micronaut/RefreshTokenNotFoundTest.kt

package example.micronaut

import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpStatus
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.security.authentication.UserDetails
import io.micronaut.security.token.generator.RefreshTokenGenerator
import io.micronaut.security.token.jwt.endpoints.TokenRefreshRequest
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.Test
import java.util.Optional
import javax.inject.Inject

@MicronautTest
internal class RefreshTokenNotFoundTest {

    @Inject
    @field:Client("/")
    var client: RxHttpClient? = null

    @Inject
    var refreshTokenGenerator: RefreshTokenGenerator? = null

    @Test
    fun accessingSecuredURLWithoutAuthenticatingReturnsUnauthorized() {
        val user = UserDetails("sherlock", emptyList())
        val refreshToken = refreshTokenGenerator!!.createKey(user)
        val refreshTokenOptional = refreshTokenGenerator!!.generate(user, refreshToken)
        Assertions.assertTrue(refreshTokenOptional.isPresent)

        val signedRefreshToken = refreshTokenOptional.get() (1)
        val bodyArgument = Argument.of(BearerAccessRefreshToken::class.java)
        val errorArgument = Argument.of(MutableMap::class.java)
        val req: HttpRequest<Any> = HttpRequest.POST("/oauth/access_token", TokenRefreshRequest(signedRefreshToken))
        val e = Assertions.assertThrows(HttpClientResponseException::class.java) {
            client!!.toBlocking().exchange(req, bodyArgument, errorArgument)
        }
        Assertions.assertEquals(HttpStatus.BAD_REQUEST, e.status)

        val mapOptional: Optional<Map<*, *>> = e.response.getBody(Map::class.java)
        Assertions.assertTrue(mapOptional.isPresent)

        val m = mapOptional.get()
        Assertions.assertEquals("invalid_grant", m["error"])
        Assertions.assertEquals("refresh token not found", m["error_description"])
    }
}

1	Supply a signed token which was never saved.

6.3.3. Test Refresh Token Revocation

Generate a valid refresh token, save it but flag it as revoked. Expect a 400.

src/test/kotlin/example/micronaut/RefreshTokenRevokedTest.kt

package example.micronaut

import io.micronaut.context.ApplicationContext
import io.micronaut.core.type.Argument
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpStatus
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.runtime.server.EmbeddedServer
import io.micronaut.security.authentication.UserDetails
import io.micronaut.security.token.generator.RefreshTokenGenerator
import io.micronaut.security.token.jwt.endpoints.TokenRefreshRequest
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.Test
import java.util.Optional

internal class RefreshTokenRevokedTest {
    var embeddedServer = ApplicationContext.run(EmbeddedServer::class.java, emptyMap())
    var client = embeddedServer.applicationContext.createBean(HttpClient::class.java, embeddedServer.url)
    var refreshTokenGenerator = embeddedServer.applicationContext.getBean(RefreshTokenGenerator::class.java)
    var refreshTokenRepository = embeddedServer.applicationContext.getBean(RefreshTokenRepository::class.java)

    @Test
    fun accessingSecuredURLWithoutAuthenticatingReturnsUnauthorized() {
        val user = UserDetails("sherlock", emptyList())
        val refreshToken = refreshTokenGenerator.createKey(user)
        val refreshTokenOptional = refreshTokenGenerator.generate(user, refreshToken)
        Assertions.assertTrue(refreshTokenOptional.isPresent)

        val oldTokenCount = refreshTokenRepository.count()
        val signedRefreshToken = refreshTokenOptional.get()
        refreshTokenRepository.save(user.username, refreshToken, true) (1)
        Assertions.assertEquals(oldTokenCount + 1, refreshTokenRepository.count())

        val bodyArgument = Argument.of(BearerAccessRefreshToken::class.java)
        val errorArgument = Argument.of(Map::class.java)
        val e = Assertions.assertThrows(HttpClientResponseException::class.java) {
            client.toBlocking().exchange(
                HttpRequest.POST("/oauth/access_token", TokenRefreshRequest(signedRefreshToken)),
                bodyArgument,
                errorArgument
            )
        }
        Assertions.assertEquals(HttpStatus.BAD_REQUEST, e.status)

        val mapOptional: Optional<Map<*, *>> = e.response.getBody(Map::class.java)
        Assertions.assertTrue(mapOptional.isPresent)

        val m = mapOptional.get()
        Assertions.assertEquals("invalid_grant", m["error"])
        Assertions.assertEquals("refresh token revoked", m["error_description"])
        refreshTokenRepository.deleteAll()
    }
}

1	Save the token but flag it as revoked

6.3.4. Test Access Token Refresh

src/test/kotlin/example/micronaut/OauthAccessTokenTest.kt

package example.micronaut

import io.micronaut.http.HttpRequest
import io.micronaut.http.client.RxHttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.security.authentication.UsernamePasswordCredentials
import io.micronaut.security.token.jwt.endpoints.TokenRefreshRequest
import io.micronaut.security.token.jwt.render.AccessRefreshToken
import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken
import io.micronaut.test.extensions.junit5.annotation.MicronautTest
import org.junit.jupiter.api.Assertions
import org.junit.jupiter.api.Test
import javax.inject.Inject

@MicronautTest(rollback = false)
internal class OauthAccessTokenTest {

    @Inject
    @field:Client("/")
    var client: RxHttpClient? = null

    @Inject
    var refreshTokenRepository: RefreshTokenRepository? = null

    @Test
    @Throws(InterruptedException::class)
    fun verifyJWTAccessTokenRefreshWorks() {
        val username = "sherlock"
        val creds = UsernamePasswordCredentials(username, "password")
        val request: HttpRequest<Any> = HttpRequest.POST("/login", creds)
        val oldTokenCount = refreshTokenRepository!!.count()
        val rsp: BearerAccessRefreshToken =
            client!!.toBlocking().retrieve(request, BearerAccessRefreshToken::class.java)
        Thread.sleep(3000)
        Assertions.assertEquals(oldTokenCount + 1, refreshTokenRepository!!.count())
        Assertions.assertNotNull(rsp.accessToken)
        Assertions.assertNotNull(rsp.refreshToken)

        Thread.sleep(1000) // sleep for one second to give time for the issued at `iat` Claim to change
        val refreshResponse = client!!.toBlocking().retrieve(
            HttpRequest.POST(
                "/oauth/access_token",
                TokenRefreshRequest(rsp.refreshToken)
            ), AccessRefreshToken::class.java (1)
        )

        Assertions.assertNotNull(refreshResponse.accessToken)
        Assertions.assertNotEquals(rsp.accessToken, refreshResponse.accessToken) (2)
        refreshTokenRepository!!.deleteAll()
    }
}

1	Make a POST request to `/oauth/access_token` with the refresh token in the JSON payload to get a new access token
2	A different access token is retrieved.

7. Testing the Application

To run the tests:

$ ./mvnw test

8. Running the Application

To run the application use the ./mvnw mn:run command which will start the application on port 8080.

Send a request to the login endpoint:

$ curl -X "POST" "http://localhost:8080/login" -H 'Content-Type: application/json' -d $'{"username": "sherlock","password": "password"}'

{"username":"sherlock","access_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaGVybG9jayIsIm5iZiI6MTYxNDc2NDEzNywicm9sZXMiOltdLCJpc3MiOiJjb21wbGV0ZSIsImV4cCI6MTYxNDc2NzczNywiaWF0IjoxNjE0NzY0MTM3fQ.cn8bOjlccFqeUQA7x7MnfacMNPjSVAtWP65z1c8eaJc","refresh_token":"eyJhbGciOiJIUzI1NiJ9.NDI1ZjAxZTktYTRmYS00MmU5LTllYjctOWU2ZTNhNTI5YmQ1.RUc2iCfZdPQdwg2U0Nw_LLzZQIIDp5_Is2UWeHVZT7E","token_type":"Bearer","expires_in":3600}

9. Generate a Micronaut app’s Native Image with GraalVM

We are going to use GraalVM, the polyglot embeddable virtual machine, to generate a Native image of our Micronaut application.

Native images compiled with GraalVM ahead-of-time improve the startup time and reduce the memory footprint of JVM-based applications.

Use of GraalVM’s native-image tool is only supported in Java or Kotlin projects. Groovy relies heavily on reflection which is only partially supported by GraalVM.

9.1. Native Image generation

The easiest way to install GraalVM is to use SDKMan.io.

# For Java 8
$ sdk install java 21.1.0.r8-grl

# For Java 11
$ sdk install java 21.1.0.r11-grl

You need to install the native-image component which is not installed by default.

$ gu install native-image

To generate a native image using Maven run:

$ ./mvnw package -Dpackaging=native-image

The native image will be created in target/application and can be run with ./target/application.

Send the same curl request as before to test that the native image application works.

10. Next steps

Learn more about JWT Authentication in the official documentation.

11. Help with Micronaut

Object Computing, Inc. (OCI) sponsored the creation of this Guide. A variety of consulting and support services are available.

Meet the Team.

Table of Contents