Micronaut JWT Authentication Learn how to secure a Micronaut app using JWT (JSON Web Token) Authentication. Authors: Sergio del Amo Micronaut Version: 2.0.0.RC1

1 Getting Started

Improve this doc

This guide uses Micronaut 2.x. You can read this tutorial for Micronaut 1.x.

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:

1.1 What you will need

Improve this doc

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

1.2 Solution

Improve this doc

We recommend you to 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

or

Clone the Git repository: git clone https://github.com/micronaut-guides/micronaut-security-jwt.git

Then, cd into the complete folder which you will find in the root project of the downloaded/cloned project.

2 Writing the Application

Improve this doc

Create an App with the Command Line Interface Create an app using the Micronaut Command Line Interface. mn create-app example.micronaut.complete --test=spock The previous command creates a micronaut app with the default package example.micronaut in a folder named complete . By default, create-app creates a Java Micronaut app that uses the Gradle build system. However, you could use other build tools such as Maven or other programming languages such as Groovy or Kotlin .

Create an App with Micronaut Launch You can create the app using Micronaut Launch If you are using Java or Kotlin and IntelliJ IDEA make sure you have enabled annotation processing.

2.1 Security Dependency

Improve this doc

Add Micronaut’s security-jwt dependency to your build file.

build.gradle dependencies { ... .. . annotationProcessor "io.micronaut.security:micronaut-security-annotations" implementation "io.micronaut.security:micronaut-security-jwt" }

2.2 Configuration

Improve this doc

Create the a new application.yml configuration file:

src/main/resources/application.yml micronaut: security: authentication: bearer (1) token: jwt: signatures: secret: generator: (2) secret: pleaseChangeThisSecretForANewOne (3)

1 Set authentication to bearer to receive a JSON response from the login endpoint. 2 You can create a SecretSignatureConfiguration named generator via configuration as illustrated above. The generator signature is used to sign the issued JWT claims. 3 Change this by your own secret and keep it safe (do not store this in your VCS).

2.3 Authentication Provider

Improve this doc

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

src/main/java/example/micronaut/AuthenticationProviderUserPassword.java package example.micronaut; import edu.umd.cs.findbugs.annotations.Nullable; 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 org.reactivestreams.Publisher; import javax.inject.Singleton; import java.util.ArrayList; @Singleton (1) public class AuthenticationProviderUserPassword implements AuthenticationProvider { (2) @Override public Publisher<AuthenticationResponse> authenticate(@Nullable HttpRequest<?> httpRequest, AuthenticationRequest<?, ?> authenticationRequest) { return Flowable.create(emitter -> { if (authenticationRequest.getIdentity().equals("sherlock") && authenticationRequest.getSecret().equals("password")) { emitter.onNext(new UserDetails((String) authenticationRequest.getIdentity(), new ArrayList<>())); emitter.onComplete(); } else { emitter.onError(new AuthenticationException(new 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

2.4 Controllers

Improve this doc

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

src/main/java/example/micronaut/HomeController.java 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 io.micronaut.security.rules.SecurityRule; import java.security.Principal; @Secured(SecurityRule.IS_AUTHENTICATED) (1) @Controller (2) public class HomeController { @Produces(MediaType.TEXT_PLAIN) @Get (3) public String index(Principal principal) { (4) return principal.getName(); } }

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).

3 Tests

Improve this doc

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

src/test/groovy/example/micronaut/JwtAuthenticationSpec.groovy 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.RxHttpClient 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.annotation.MicronautTest import spock.lang.Specification import javax.inject.Inject @MicronautTest (1) class JwtAuthenticationSpec extends Specification { @Inject @Client("/") RxHttpClient client (2) void 'Accessing a secured URL without authenticating returns unauthorized'() { when: client.toBlocking().exchange(HttpRequest.GET('/', )) (3) then: HttpClientResponseException e = thrown() e.status == HttpStatus.UNAUTHORIZED } void "upon successful authentication, a Json Web token is issued to the user"() { when: 'Login endpoint is called with valid credentials' UsernamePasswordCredentials creds = new UsernamePasswordCredentials("sherlock", "password") HttpRequest request = HttpRequest.POST('/login', creds) (4) HttpResponse<BearerAccessRefreshToken> rsp = client.toBlocking().exchange(request, BearerAccessRefreshToken) (5) then: 'the endpoint can be accessed' rsp.status == HttpStatus.OK when: BearerAccessRefreshToken bearerAccessRefreshToken = rsp.body() then: bearerAccessRefreshToken.username == 'sherlock' bearerAccessRefreshToken.accessToken and: 'the access token is a signed JWT' JWTParser.parse(bearerAccessRefreshToken.accessToken) instanceof SignedJWT when: 'passing the access token as in the Authorization HTTP Header with the prefix Bearer allows the user to access a secured endpoint' String accessToken = bearerAccessRefreshToken.accessToken HttpRequest requestWithAuthorization = HttpRequest.GET('/' ) .accept(MediaType.TEXT_PLAIN) .bearerAuth(accessToken) (6) HttpResponse<String> response = client.toBlocking().exchange(requestWithAuthorization, String) then: response.status == HttpStatus.OK response.body() == 'sherlock' (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.

3.1 Use Micronaut's HTTP Client and JWT

Improve this doc

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/groovy/example/micronaut/AppClient.groovy 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") BearerAccessRefreshToken login(@Body UsernamePasswordCredentials credentials) @Consumes(MediaType.TEXT_PLAIN) @Get String home(@Header String authorization) }

Create a test which uses the previous @Client

src/test/groovy/example/micronaut/DeclarativeHttpClientWithJwtSpec.groovy 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.annotation.MicronautTest import spock.lang.Specification import javax.inject.Inject @MicronautTest class DeclarativeHttpClientWithJwtSpec extends Specification { @Inject AppClient appClient (1) def "Verify JWT authentication works with declarative @Client"() { when: 'Login endpoint is called with valid credentials' UsernamePasswordCredentials creds = new UsernamePasswordCredentials("sherlock", "password") BearerAccessRefreshToken loginRsp = appClient.login(creds) (2) then: loginRsp loginRsp.accessToken JWTParser.parse(loginRsp.accessToken) instanceof SignedJWT when: String msg = appClient.home("Bearer ${loginRsp.accessToken}") (3) then: msg == 'sherlock' } }

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.

4 Issuing a Refresh Token

Improve this doc

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: pleaseChangeThisSecretForANewOne (1)

1 To generate a refresh token you 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/groovy/example/micronaut/LoginIncludesRefreshTokenSpec.groovy 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.annotation.MicronautTest import spock.lang.Specification import javax.inject.Inject @MicronautTest class LoginIncludesRefreshTokenSpec extends Specification { @Inject @Client("/") RxHttpClient client void "upon successful authentication, the user gets an access token and a refresh token"() { when: 'Login endpoint is called with valid credentials' UsernamePasswordCredentials creds = new UsernamePasswordCredentials("sherlock", "password") HttpRequest request = HttpRequest.POST('/login', creds) BearerAccessRefreshToken rsp = client.toBlocking().retrieve(request, BearerAccessRefreshToken) then: rsp.username == 'sherlock' rsp.accessToken rsp.refreshToken (1) and: 'access token is a JWT' JWTParser.parse(rsp.accessToken) instanceof SignedJWT } }

1 A refresh token is returned.

4.1 Save Refresh Token

Improve this doc

We may want to save refresh token issued by the application. For example, to be revoke 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:

build.gradle dependencies { ... .. . annotationProcessor("io.micronaut.data:micronaut-data-processor") (1) implementation("io.micronaut.data:micronaut-data-jdbc") (2) runtime("com.h2database:h2") (3) runtime("io.micronaut.sql:micronaut-jdbc-hikari") (4) }

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 JDBC driver. Add H2 driver. 4 Add a Hikari connection pool

Create an entity to save the issued Refresh Tokens.

src/main/java/example/micronaut/RefreshTokenEntity.groovy package example.micronaut; import edu.umd.cs.findbugs.annotations.NonNull; 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 javax.validation.constraints.NotBlank; import javax.validation.constraints.NotNull; import java.time.Instant; @MappedEntity (1) public class RefreshTokenEntity { @Id (2) @GeneratedValue (3) @NonNull private Long id; @NonNull @NotBlank private String username; @NonNull @NotBlank private String refreshToken; @NonNull @NotNull private Boolean revoked; @DateCreated (4) @NonNull @NotNull private Instant dateCreated; public RefreshTokenEntity() { } // Getters and Setters ... .. . }

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/java/example/micronaut/RefreshTokenRepository.groovy package example.micronaut; import edu.umd.cs.findbugs.annotations.NonNull; import io.micronaut.data.jdbc.annotation.JdbcRepository; import io.micronaut.data.model.query.builder.sql.Dialect; import io.micronaut.data.repository.CrudRepository; import javax.transaction.Transactional; import javax.validation.constraints.NotBlank; import javax.validation.constraints.NotNull; import java.util.Optional; @JdbcRepository(dialect = Dialect.H2) (1) public interface RefreshTokenRepository extends CrudRepository<RefreshTokenEntity, Long> { (2) @Transactional RefreshTokenEntity save(@NonNull @NotBlank String username, @NonNull @NotBlank String refreshToken, @NonNull @NotNull Boolean revoked); (3) Optional<RefreshTokenEntity> findByRefreshToken(@NonNull @NotBlank String refreshToken); (4) long updateByUsername(@NonNull @NotBlank String username, @NonNull @NotNull Boolean revoked); (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.

4.2 Refresh Controller

Improve this doc

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/java/example/micronaut/CustomRefreshTokenPersistence.groovy 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 org.reactivestreams.Publisher; import javax.inject.Singleton; import java.util.ArrayList; import java.util.Optional; @Singleton (1) public class CustomRefreshTokenPersistence implements RefreshTokenPersistence { private final RefreshTokenRepository refreshTokenRepository; public CustomRefreshTokenPersistence(RefreshTokenRepository refreshTokenRepository) { (2) this.refreshTokenRepository = refreshTokenRepository; } @Override @EventListener (3) public void persistToken(RefreshTokenGeneratedEvent event) { if (event != null && event.getRefreshToken() != null && event.getUserDetails() != null && event.getUserDetails().getUsername() != null) { String payload = event.getRefreshToken(); refreshTokenRepository.save(event.getUserDetails() .getUsername(), payload, Boolean.FALSE); (4) } } @Override public Publisher<UserDetails> getUserDetails(String refreshToken) { return Flowable.create(emitter -> { Optional<RefreshTokenEntity> tokenOpt = refreshTokenRepository.findByRefreshToken(refreshToken); if (tokenOpt.isPresent()) { RefreshTokenEntity token = tokenOpt.get(); if (token.getRevoked()) { emitter.onError(new OauthErrorResponseException(IssuingAnAccessTokenErrorCode.INVALID_GRANT, "refresh token revoked", null)); (5) } else { emitter.onNext(new UserDetails(token.getUsername(), new ArrayList<>())); (6) emitter.onComplete(); } } else { emitter.onError(new 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.

4.3 Test Refresh Token

Improve this doc

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/groovy/example/micronaut/UnsignedRefreshTokenSpec.groovy 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.annotation.MicronautTest import spock.lang.Specification import javax.inject.Inject @MicronautTest class UnsignedRefreshTokenSpec extends Specification { @Inject @Client("/") RxHttpClient client void 'Accessing a secured URL without authenticating returns unauthorized'() { given: String unsignedRefreshedToken = "foo" (1) when: Argument<BearerAccessRefreshToken> bodyArgument = Argument.of(BearerAccessRefreshToken) Argument<Map> errorArgument = Argument.of(Map) client.toBlocking().exchange(HttpRequest.POST("/oauth/access_token", new TokenRefreshRequest(unsignedRefreshedToken)), bodyArgument, errorArgument) then: HttpClientResponseException e = thrown() e.status == HttpStatus.BAD_REQUEST when: Optional<Map> mapOptional = e.response.getBody(Map) then: mapOptional.isPresent() when: Map m = mapOptional.get() then: m.error == 'invalid_grant' m.error_description == 'Refresh token is invalid' } } } 1 Use an unsigned token

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/groovy/example/micronaut/RefreshTokenNotFoundSpec.groovy 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.annotation.MicronautTest import spock.lang.Specification import javax.inject.Inject @MicronautTest class RefreshTokenNotFoundSpec extends Specification { @Inject @Client("/") RxHttpClient client @Inject RefreshTokenGenerator refreshTokenGenerator void 'Accessing a secured URL without authenticating returns unauthorized'() { given: UserDetails user = new UserDetails("sherlock", []) when: String refreshToken = refreshTokenGenerator.createKey(user) Optional<String> refreshTokenOptional = refreshTokenGenerator.generate(user, refreshToken) then: refreshTokenOptional.isPresent() when: String signedRefreshToken = refreshTokenOptional.get() (1) Argument<BearerAccessRefreshToken> bodyArgument = Argument.of(BearerAccessRefreshToken) Argument<Map> errorArgument = Argument.of(Map) HttpRequest req = HttpRequest.POST("/oauth/access_token", new TokenRefreshRequest(signedRefreshToken)) client.toBlocking().exchange(req, bodyArgument, errorArgument) then: HttpClientResponseException e = thrown() e.status == HttpStatus.BAD_REQUEST when: Optional<Map> mapOptional = e.response.getBody(Map) then: mapOptional.isPresent() when: Map m = mapOptional.get() then: m.error == 'invalid_grant' m.error_description == 'refresh token not found' } } } 1 Supply a signed token which was never saved.

Test Refresh Token Revocation Generate a valid refresh token, save it but flag it as revoked. Expect a 400. src/test/groovy/example/micronaut/RefreshTokenRevokedSpec.groovy 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 spock.lang.AutoCleanup import spock.lang.Shared import spock.lang.Specification class RefreshTokenRevokedSpec extends Specification { @AutoCleanup @Shared EmbeddedServer embeddedServer = ApplicationContext.run(EmbeddedServer, [:]) @Shared HttpClient client = embeddedServer.applicationContext.createBean(HttpClient, embeddedServer.URL) @Shared RefreshTokenGenerator refreshTokenGenerator = embeddedServer.applicationContext.getBean(RefreshTokenGenerator) @Shared RefreshTokenRepository refreshTokenRepository = embeddedServer.applicationContext.getBean(RefreshTokenRepository) void 'Accessing a secured URL without authenticating returns unauthorized'() { given: UserDetails user = new UserDetails("sherlock", []) when: String refreshToken = refreshTokenGenerator.createKey(user) Optional<String> refreshTokenOptional = refreshTokenGenerator.generate(user, refreshToken) then: refreshTokenOptional.isPresent() when: String signedRefreshToken = refreshTokenOptional.get() refreshTokenRepository.save(user.username, refreshToken, Boolean.TRUE) (1) then: refreshTokenRepository.count() == old(refreshTokenRepository.count()) + 1 when: Argument<BearerAccessRefreshToken> bodyArgument = Argument.of(BearerAccessRefreshToken) Argument<Map> errorArgument = Argument.of(Map) client.toBlocking().exchange(HttpRequest.POST("/oauth/access_token", new TokenRefreshRequest(signedRefreshToken)), bodyArgument, errorArgument) then: HttpClientResponseException e = thrown() e.status == HttpStatus.BAD_REQUEST when: Optional<Map> mapOptional = e.response.getBody(Map) then: mapOptional.isPresent() when: Map m = mapOptional.get() then: m.error == 'invalid_grant' m.error_description == 'refresh token revoked' cleanup: refreshTokenRepository.deleteAll() } } } 1 Save the token but flag it as revoked

Test Access Token Refresh Login, obtain both access token and refresh token, with the refresh token obtain a different access token: src/test/groovy/example/micronaut/OauthAccessTokenSpec.groovy 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.annotation.MicronautTest import spock.lang.Shared import spock.lang.Specification import spock.util.concurrent.PollingConditions import javax.inject.Inject @MicronautTest(rollback = false) (1) class OauthAccessTokenSpec extends Specification { @Inject @Client("/") RxHttpClient client (2) @Shared @Inject RefreshTokenRepository refreshTokenRepository def "Verify JWT access token refresh works"() { given: String username = 'sherlock' when: 'login endpoint is called with valid credentials' def creds = new UsernamePasswordCredentials(username, "password") HttpRequest request = HttpRequest.POST('/login', creds) BearerAccessRefreshToken rsp = client.toBlocking().retrieve(request, BearerAccessRefreshToken) then: 'the refresh token is saved to the database' new PollingConditions().eventually { assert refreshTokenRepository.count() == old(refreshTokenRepository.count()) + 1 } and: 'response contains an access token token' rsp.accessToken and: 'response contains a refresh token' rsp.refreshToken when: sleep(1_000) // sleep for one second to give time for the issued at `iat` Claim to change AccessRefreshToken refreshResponse = client.toBlocking().retrieve(HttpRequest.POST('/oauth/access_token', new TokenRefreshRequest(rsp.refreshToken)), AccessRefreshToken) (1) then: refreshResponse.accessToken refreshResponse.accessToken != rsp.accessToken (2) cleanup: 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.

5 Testing the Application

Improve this doc

To run the tests:

$ ./gradlew test $ open build/reports/tests/test/index.html

6 Running the Application

Improve this doc

To run the application use the ./gradlew run command which will start the application on port 8080.

7 Generate a Micronaut app's Native Image with GraalVM

Improve this doc

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.

7.1 Micronaut + GraalVM changes

Improve this doc

Micronaut itself does not rely on reflection or dynamic classloading so works automatically with GraalVM native.

First, add Micronaut Graal’s annotation processor that helps to handle generating the reflection-config.json metadata that is automatically picked up by the native-image tool:

build.gradle dependencies { ... .. . annotationProcessor "io.micronaut:micronaut-graal" }

GraalVM Native Image allows you to ahead-of-time compile Java code to a standalone executable, called a native image. This executable includes the application, the libraries, the JDK and does not run on the Java VM, but includes necessary components like memory management and thread scheduling from a different virtual machine, called “Substrate VM”. Substrate VM is the name for the runtime components (like the deoptimizer, garbage collector, thread scheduling etc.). The resulting program has faster startup time and lower runtime memory overhead compared to a Java VM.

We need to add a dependency to svm :

build.gradle dependencies { ... .. . compileOnly("org.graalvm.nativeimage:svm") }

To simplify building the image you need to create a native-image.properties file. The convention is to use the folder src/main/resources/META-INF/native-image and then a folder following the maven coordinates of the application. For our example example.micronaut/micronautguide .

Add a native-image.properties inside src/main/resources/META-INF/native-image/example.micronaut/micronautguide folder.

src/main/resources/META-INF/native-image/example.micronaut/micronautguide/native-image.properties Args = -H:Name=micronautguide \ -H:Class=example.micronaut.Application

The -H:Name argument specifies the name of the native image that will be generated.

The -H:Class argument specifies the entry point of your application (the class that defines a static void main method.

7.2 Native Image generation

Improve this doc

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

$ sdk list java ================================================================================ Available Java Versions ================================================================================ Vendor | Use | Version | Dist | Status | Identifier -------------------------------------------------------------------------------- .... GraalVM | | 20.1.0.r11 | grl | installed | 20.1.0.r11-grl | | 20.1.0.r8 | grl | | 20.1.0.r8-grl | | 20.0.0.r11 | grl | | 20.0.0.r11-grl | | 20.0.0.r8 | grl | installed | 20.0.0.r8-grl | | 19.3.1.r11 | grl | installed | 19.3.1.r11-grl | | 19.3.1.r8 | grl | | 19.3.1.r8-grl .... # For Java 8 $ sdk install java 20.1.0.r8-grl # For Java 11 $ sdk install java 20.1.0.r11-grl

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

$ gu install native-image

To generate the native image you need to generate the FAT JAR first.

$ ./gradlew assemble

Invoke native-image . It may take a minute to complete.

$ which java /Users/sdelamo/.sdkman/candidates/java/20.1.0.r11-grl/bin/java

$ native-image --no-server -cp build/libs/complete-0.1-all.jar [micronautguide:28833] classlist: 3,459.84 ms, 0.96 GB [micronautguide:28833] (cap): 2,622.25 ms, 0.96 GB [micronautguide:28833] (clinit): 1,306.37 ms, 5.48 GB [micronautguide:28833] (typeflow): 14,735.93 ms, 5.48 GB [micronautguide:28833] (objects): 21,228.62 ms, 5.48 GB [micronautguide:28833] (features): 2,722.65 ms, 5.48 GB [micronautguide:28833] analysis: 42,115.37 ms, 5.48 GB [micronautguide:28833] universe: 1,348.45 ms, 5.48 GB [micronautguide:28833] (parse): 2,717.52 ms, 5.48 GB [micronautguide:28833] (inline): 4,520.18 ms, 5.64 GB [micronautguide:28833] (compile): 20,724.72 ms, 5.90 GB [micronautguide:28833] compile: 30,636.91 ms, 5.90 GB [micronautguide:28833] image: 5,010.54 ms, 5.66 GB [micronautguide:28833] write: 1,399.49 ms, 5.66 GB [micronautguide:28833] [total]: 90,218.13 ms, 5.66 GB

--no-server options tells to not use server-based image building.

You can invoke the generated native image micronautguide . Startup will be really fast.

$ ./micronautguide -Xmx68m 07:42:20.792 [main] INFO io.micronaut.runtime.Micronaut - Startup completed in 21ms. Server Running: http://localhost:8080

You can execute the login endpoint exposed by the native image:

curl -X "POST" "http://localhost:8080/login" -H 'Content-Type: application/json; charset=utf-8' -d $'{"username": "sherlock","password": "password"}' {"username":"sherlock","access_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaGVybG9jayIsIm5iZiI6MTU3NTY0NTcwNCwicm9sZXMiOltdLCJpc3MiOiJtaWNyb25hdXQiLCJleHAiOjE1NzU2NDkzMDQsImlhdCI6MTU3NTY0NTcwNH0.4muCnr7ztVp1DisyGWNKkV2QC9qtIt_WyS6ubbAbt_c","refresh_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaGVybG9jayIsIm5iZiI6MTU3NTY0NTcwNCwicm9sZXMiOltdLCJpc3MiOiJtaWNyb25hdXQiLCJpYXQiOjE1NzU2NDU3MDR9._MnTiFN1ifKJEqXE6B1--srPkOeNW5cDNtMymN3qG48","token_type":"Bearer","expires_in":3600}

7.3 Native Image generation with Docker

Improve this doc

Alternatively, you can use Dockerfile to construct the native image and a script docker-build.sh to run it:

Dockerfile FROM oracle/graalvm-ce:20.1.0-java8 as graalvm RUN gu install native-image COPY . /home/app/complete WORKDIR /home/app/complete RUN native-image --no-server -cp build/libs/complete-*-all.jar FROM frolvlad/alpine-glibc RUN apk update && apk add libstdc++ EXPOSE 8080 COPY --from=graalvm /home/app/complete/complete /app/complete ENTRYPOINT ["/app/complete"]

docker-build.sh #!/bin/sh docker build . -t micronautguide echo echo echo "To run the docker container execute:" echo " $ docker run -p 8080:8080 micronautguide"

$ ./gradlew assemble $ % ./docker-build.sh Sending build context to Docker daemon 127MB Step 1/10 : FROM oracle/graalvm-ce:20.1.0-java11 as graalvm ---> 2adef7aab8f9 Step 2/10 : RUN gu install native-image ---> Using cache ---> a52c98379916 Step 3/10 : COPY . /home/app/complete ---> 7b5d8708feb7 Step 4/10 : WORKDIR /home/app/complete ---> Running in 52615dd2ceed Removing intermediate container 52615dd2ceed ---> fe6e67e150b6 Step 5/10 : RUN native-image --no-server -cp build/libs/complete-*-all.jar ---> Running in b0cca1a82c2c [micronautguide:24] classlist: 4,224.09 ms, 0.96 GB [micronautguide:24] (cap): 557.93 ms, 0.96 GB WARNING: Could not resolve io.netty.channel.epoll.EpollChannelOption for reflection configuration. WARNING: Could not resolve io.netty.channel.kqueue.KQueueChannelOption for reflection configuration. [micronautguide:24] setup: 1,840.06 ms, 0.96 GB WARNING GR-10238: VarHandle for static field is currently not fully supported. Static field private static volatile java.lang.System$Logger jdk.internal.event.EventHelper.securityLogger is not properly marked for Unsafe access! [micronautguide:24] (clinit): 1,383.94 ms, 3.42 GB [micronautguide:24] (typeflow): 16,198.26 ms, 3.42 GB [micronautguide:24] (objects): 20,293.44 ms, 3.42 GB [micronautguide:24] (features): 2,859.27 ms, 3.42 GB [micronautguide:24] analysis: 43,474.70 ms, 3.42 GB [micronautguide:24] universe: 1,783.90 ms, 3.38 GB [micronautguide:24] (parse): 4,345.14 ms, 3.68 GB [micronautguide:24] (inline): 2,786.82 ms, 3.52 GB [micronautguide:24] (compile): 18,459.86 ms, 4.32 GB [micronautguide:24] compile: 28,292.51 ms, 4.32 GB [micronautguide:24] image: 5,348.95 ms, 4.33 GB [micronautguide:24] write: 804.47 ms, 4.33 GB [micronautguide:24] [total]: 86,008.19 ms, 4.33 GB Removing intermediate container b0cca1a82c2c ---> 31e41f3f3306 Step 6/10 : FROM frolvlad/alpine-glibc ---> 3a1c752f649f Step 7/10 : RUN apk update && apk add libstdc++ ---> Using cache ---> 536cd2f06071 Step 8/10 : EXPOSE 8080 ---> Using cache ---> 1e011af81857 Step 9/10 : COPY --from=graalvm /home/app/complete/micronautguide /app/complete ---> 921480edd9b7 Step 10/10 : ENTRYPOINT ["/app/complete"] ---> Running in a61b95562776 Removing intermediate container a61b95562776 ---> 56c8fff02b03 Successfully built 56c8fff02b03 Successfully tagged complete:latest To run the docker container execute: $ docker run -p 8080:8080 complete

You can use docker to run the image with the app’s native-image:

sdelamo@Sergios-iMac-Pro complete % docker run -p 8080:8080 complete /app/complete: /usr/lib/libstdc++.so.6: no version information available (required by /app/complete) 05:06:22.567 [main] INFO io.micronaut.runtime.Micronaut - Startup completed in 40ms. Server Running: http://35bc084914f6:8080

8 Help with Micronaut

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

OCI is Home to Micronaut.

Meet the Team