Build Native Java Apps with Micronaut, Quarkus, and Spring Boot

Java has been able to invoke native programs on an operating system for decades. Invoking native programs is often done using JNI (Java Native Interface) and JNA (Java Native Access). In the last few years, Java has also gained the ability to run JVM apps as native apps. That is, they’re binary executables that have no dependency on the Java runtime.

This is huge! Mostly because it gives Java apps the ability to start up in milliseconds (as opposed to seconds). If you’re scaling up to handle millions of requests and using a serverless environment to save costs, this is a game-changer. Developers have enjoyed using Node.js, Python, and Go on serverless environments for years. The ability to use Java (or Kotlin) opens this world up to a massive swath of the developer community.

This post will show you how to run a secure, OAuth 2.0-protected, Java REST API that allows JWT authentication. I’ll showcase the three leading Java frameworks: Micronaut, Quarkus, and Spring Boot. First, I’ll show you how to run them with Java and access their data. Then, I’ll show you how to build and test native images with each framework. I’ll mention a few gotchas I ran into along the way.

Prerequisites

Get Started with Native Java Frameworks

I created a GitHub repository you can clone and run to get started with all three frameworks quickly.

git clone https://github.com/oktadev/native-java-examples.git

This project has directories with the latest versions of Micronaut, Quarkus, and Spring Boot (at the time of this writing). I’ll show you how I created them in individual sections below.

Open the native-java-examples directory in your favorite IDE, so you have easy access to each framework’s project files.

If you want to see how to build native images in each framework, skip to the build native images for Micronaut, Quarkus, and Spring Boot section.

Install a JDK with GraalVM

You will need a JDK with GraalVM and its native-image compiler. Using SDKMAN, run the following command and set it as the default:

sdk install java 21.1.0.r11-grl

Add the native extension to the JDK:

gu install native-image

Launch a Micronaut Java API

In a terminal window, cd into the micronaut directory and run mn:run to start it.

cd micronaut
./mvn mn:run

If you open another terminal window and try to access it with HTTPie, you’ll get a 401 Unauthorized error.

$ http :8080/hello

HTTP/1.1 401 Unauthorized
connection: keep-alive
transfer-encoding: chunked

To make it so you can access this endpoint, you’ll need to generate an OAuth 2.0 access token and update the JWKS (JSON Web Key Sets) URL to yours (in this project’s application.yml).

If you’re unsure what OIDC and OAuth 2.0 are, see our Illustrated Guide to OAuth and OpenID Connect.

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create. Select the default app name, or change it as you see fit. Choose Single-Page App and press Enter.

Use https://oidcdebugger.com/debug for the Redirect URI and set the Logout Redirect URI to https://oidcdebugger.com.

What does the Okta CLI do?

The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for https://oidcdebugger.com. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a Single-Page App for more information.

Take note of the clientId and issuer values. You’ll need those to get an access token and to configure each framework for JWT authentication.

Open micronaut/src/main/resources/application.yml and change the Okta URL to match yours.

micronaut:
  application:
    name: app
  security:
    enabled: true
    token:
      jwt:
        enabled: true
        claims-validators:
          issuer: https://{yourOktaDomain}/oauth2/default
        signatures:
          jwks:
            okta:
              url: https://{yourOktaDomain}/oauth2/default/v1/keys

Stop your Micronaut app with Ctrl+C and restart it with ⬆️+Return.

./mvn mn:run

Generate an OAuth 2.0 Access Token

An easy way to get an access token is to generate one using OpenID Connect Debugger. First, you must configure your application on Okta to use OpenID Connect’s implicit flow.

Run okta login and open the resulting URL in your browser. Go to the Applications section and select the application you just created. Edit its General Settings and add Implicit (Hybrid) as an allowed grant type, with access token enabled. Then, make sure it has https://oidcdebugger.com/debug in its Login redirect URIs. Click Save and copy the client ID for the next step.

Now, navigate to the OpenID Connect Debugger website. Fill in your client ID, and use https://{yourOktaDomain}/oauth2/default/v1/authorize for the Authorize URI. The state field must be filled but can contain any characters. Select token for the response type.

OIDC Debugger

Click Send Request to continue.

Once you have an access token, set it as a TOKEN environment variable in a terminal window.

TOKEN=eyJraWQiOiJYa2pXdjMzTDRBYU1ZSzNGM...
You might want to keep OpenID Connect <debugger/> open to copy your access tokens. It allows you to quickly start over and regenerate a new access token if it expires.

Test Your Micronaut API with HTTPie

Use HTTPie to pass the JWT in as a bearer token in the Authorization header.

http :8080/hello Authorization:"Bearer $TOKEN"

You should get a 200 response with your email in it.

HTTPie call to Micronaut’s /hello with bearer token

Build a Native Micronaut App

To compile this Micronaut app into a native binary, run:

./mvnw package -Dpackaging=native-image

This command will take a few minutes to complete. My 2019 MacBook Pro with a 2.4 GHz 8-Core Intel Core i9 processor and 64 GB of RAM took 1 min. 28 s. to finish.

Start it with ./target/app:

$ ./target/app
 __  __ _                                  _
|  \/  (_) ___ _ __ ___  _ __   __ _ _   _| |_
| |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
| |  | | | (__| | | (_) | | | | (_| | |_| | |_
|_|  |_|_|\___|_|  \___/|_| |_|\__,_|\__,_|\__|
  Micronaut (v2.5.6)

17:20:23.980 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 25ms. Server Running: http://localhost:8080

You can see it starts pretty darn quick (25ms)! Test it with HTTPie and an access token. You may have to generate a new JWT with oidcdebugger.com if yours has expired.

http :8080/hello Authorization:"Bearer $TOKEN"

Make a Micronaut App from Scratch

You might be wondering, "how did you build a secure Micronaut app"? Did I just hide the complexity? No, it only takes five steps to create the same app.

  1. Use SDKMAN! to install Micronaut’s CLI:

    sdk install micronaut
  2. Create an app using the mn create-app command and rename the project’s directory:

    mn create-app com.okta.rest.app --build maven
    mv app micronaut
  3. Add Micronaut’s libraries for JWT security:

    <dependency>
        <groupId>io.micronaut.security</groupId>
        <artifactId>micronaut-security</artifactId>
    </dependency>
    <dependency>
        <groupId>io.micronaut.security</groupId>
        <artifactId>micronaut-security-jwt</artifactId>
    </dependency>
  4. Add a HelloController in src/main/java/com/okta/rest/controller:

    package com.okta.rest.controller;
    
    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;
    
    @Controller("/hello")
    public class HelloController {
    
        @Get
        @Secured(SecurityRule.IS_AUTHENTICATED)
        @Produces(MediaType.TEXT_PLAIN)
        public String hello(Principal principal) {
            return "Hello, " + principal.getName() + "!";
        }
    
    }
  5. Enable and configure JWT security in src/main/resources/application.yml:

    micronaut:
      ...
      security:
        enabled: true
        token:
          jwt:
            enabled: true
            claims-validators:
              issuer: https://{yourOktaDomain}/oauth2/default
            signatures:
              jwks:
                okta:
                  url: https://{yourOktaDomain}/oauth2/default/v1/keys

That’s it! Now you can start the app or build the native image as shown above.

Now let’s take a look at Quarkus.

Run a Quarkus Java API

Open a terminal, cd into the quarkus directory, and run quarkus:dev to start the app.

cd quarkus
./mvnw quarkus:dev

Update the URLs in quarkus/src/main/resources/application.properties to use your Okta domain.

mp.jwt.verify.publickey.location=https://{yourOktaDomain}/oauth2/default/v1/keys
mp.jwt.verify.issuer=https://{yourOktaDomain}/oauth2/default

Test Your Quarkus API with HTTPie

Generate or copy an access token from OpenID Connect <debugger/> and use it to test your Quarkus API.

http :8080/hello Authorization:"Bearer $TOKEN"

You should see your email in the response.

HTTPie call to Quarkus’s /hello with bearer token

Did you notice that Quarkus hot-reloaded your application.properties file updates? Pretty slick, eh?!

Build a Native Quarkus App

To compile this Quarkus app into a native binary, run:

./mvnw package -Pnative

The native compilation step will take a bit to complete. On my 2019 MacBook Pro, it took 1 min. 9 s.

Start it with ./target/quarkus-1.0.0-SNAPSHOT-runner:

$ ./target/quarkus-1.0.0-SNAPSHOT-runner
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2021-06-15 17:35:23,886 INFO  [io.quarkus] (main) quarkus 1.0.0-SNAPSHOT native (powered by Quarkus 1.13.7.Final) started in 0.014s. Listening on: http://0.0.0.0:8080
2021-06-15 17:35:23,888 INFO  [io.quarkus] (main) Profile prod activated.
2021-06-15 17:35:23,889 INFO  [io.quarkus] (main) Installed features: [cdi, mutiny, resteasy, security, smallrye-context-propagation, smallrye-jwt, vertx, vertx-web]

Supersonic Subatomic Java (in 14ms)! Test it with HTTPie and an access token.

http :8080/hello Authorization:"Bearer $TOKEN"

Create a Quarkus App from Scratch

You can create the same Quarkus app used in this example in five steps.

  1. Use Maven to generate a new Quarkus app with JWT support:

    mvn io.quarkus:quarkus-maven-plugin:1.13.7.Final:create \
        -DprojectGroupId=com.okta.rest \
        -DprojectArtifactId=quarkus \
        -DclassName="com.okta.rest.quarkus.HelloResource" \
        -Dpath="/hello" \
        -Dextensions="smallrye-jwt"
  2. Edit src/java/com/okta/rest/quarkus/HelloResource.java and add user information to the hello() method:

    package com.okta.rest.quarkus;
    
    import io.quarkus.security.Authenticated;
    
    import javax.ws.rs.GET;
    import javax.ws.rs.Path;
    import javax.ws.rs.Produces;
    import javax.ws.rs.core.Context;
    import javax.ws.rs.core.MediaType;
    import javax.ws.rs.core.SecurityContext;
    import java.security.Principal;
    
    @Path("/hello")
    public class HelloResource {
    
        @GET
        @Path("/")
        @Authenticated
        @Produces(MediaType.TEXT_PLAIN)
        public String hello(@Context SecurityContext context) {
            Principal userPrincipal = context.getUserPrincipal();
            return "Hello, " + userPrincipal.getName() + "!";
        }
    
    }
  3. Add your Okta endpoints to src/main/resources/application.properties:

    mp.jwt.verify.publickey.location=https://{yourOktaDomain}/oauth2/default/v1/keys
    mp.jwt.verify.issuer=https://{yourOktaDomain}/oauth2/default
  4. Modify the HelloResourceTest to expect a 401 instead of a 200:

    package com.okta.rest.quarkus;
    
    import io.quarkus.test.junit.QuarkusTest;
    import org.junit.jupiter.api.Test;
    
    import static io.restassured.RestAssured.given;
    
    @QuarkusTest
    public class HelloResourceTest {
    
        @Test
        public void testHelloEndpoint() {
            given()
                .when().get("/hello")
                .then()
                .statusCode(401);
        }
    
    }
  5. Add HTTPS support to the native profile at the bottom of pom.xml with the quarkus.native.additional-build-args property:

    <properties>
      <quarkus.package.type>native</quarkus.package.type>
      <quarkus.native.additional-build-args>
        --enable-url-protocols=https
      </quarkus.native.additional-build-args>
    </properties>

The last step is not necessary if you’re running with Maven, but it is for the native image. Quarkus includes SSL for many extensions, but not for SmallRye JWT. The good news is Quarkus will enable SSL by default for SmallRye JWT in Quarkus 2.0.0.Final.

Last but certainly not least, let’s look at Spring Boot.

Start a Spring Boot Java API

In your IDE, update the issuer in spring-boot/src/main/resources/application.properties to use your Okta domain.

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://{yourOktaDomain}/oauth2/default

Then, start your app from your IDE or using a terminal:

./mvnw spring-boot:run

Test Your Spring Boot API with HTTPie

Generate an access token using ttps://oidcdebugger.com[oidcdebugger.com] and use it to test your Spring Boot API.

http :8080/hello Authorization:"Bearer $TOKEN"

You should see a response like the following.

HTTPie call to Spring Boot’s /hello with bearer token

But wait, doesn’t Okta have a Spring Boot starter? Yes, we do—however, it doesn’t work with GraalVM yet.

However, we’re calling in an expert to help us fix it! Join us next Tuesday, June 22, 2021, on twitch.tv/oktadev for a session with Josh Long. We’ll attempt to fix things live!

Build a Native Spring Boot App

To compile this Spring Boot app into a native executable, you can use the Spring Boot Maven plugin:

./mvnw spring-boot:build-image

The native compilation step will take a bit to complete. On my 2019 MacBook Pro, it took 2 min. 56 s.

Start it using Docker:

$ docker run -p 8080:8080 docker.io/library/demo:0.0.1-SNAPSHOT
2021-06-16 02:21:24.193  INFO 1 --- [           main] o.s.nativex.NativeListener               : This application is bootstrapped with code generated with Spring AOT

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v2.5.1)
...
2021-06-16 02:21:24.970  INFO 1 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2021-06-16 02:21:24.971  INFO 1 --- [           main] com.okta.rest.DemoApplication            : Started DemoApplication in 0.06 seconds (JVM running for 0.063)

Bootiful! Test your API with HTTPie and an access token.

http :8080/hello Authorization:"Bearer $TOKEN"

Start a Spring Boot App from Scratch

To create the Spring Boot app used in this example, it’s just five steps.

  1. Use HTTPie to generate a new Spring Boot app with OAuth 2.0 support:

    http https://start.spring.io/starter.zip \
         bootVersion==2.5.1 \
         dependencies==web,oauth2-resource-server,native \
         packageName==com.okta.rest \
         name==spring-boot \
         type==maven-project \
         baseDir==spring-boot | tar -xzvf -
  2. Add a HelloController class that returns the user’s information:

    package com.okta.rest.controller;
    
    import org.springframework.security.core.annotation.AuthenticationPrincipal;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.security.Principal;
    
    @RestController
    public class HelloController {
    
        @GetMapping("/hello")
        public String hello(Principal principal) {
            return "Hello, " + principal.getName() + "!";
        }
    }
  3. Configure the app to be an OAuth 2.0 resource server by adding an issuer to application.properties:

    spring.security.oauth2.resourceserver.jwt.issuer-uri=https://{yourOktaDomain}/oauth2/default
  4. Add a SecurityConfiguration class to configure JWT authentication:

    package com.okta.rest;
    
    import org.springframework.security.config.annotation.web.builders.HttpSecurity;
    import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
    import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
    import org.springframework.security.config.annotation.web.configurers.oauth2.server.resource.OAuth2ResourceServerConfigurer;
    
    @EnableWebSecurity
    public class SecurityConfiguration extends WebSecurityConfigurerAdapter {
    
        @Override
        protected void configure(HttpSecurity http) throws Exception {
            http
                .authorizeRequests(request -> request.anyRequest().authenticated())
                .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
        }
    }
  5. Enable HTTPS for native builds by adding a @NativeHint annotation to the DemoApplication class.

    import org.springframework.nativex.hint.NativeHint;
    
    @SpringBootApplication
    @NativeHint(options = "--enable-url-protocols=https")

You can build and test a Spring Boot native image using the steps I outlined above.

Build Native Images for Micronaut, Quarkus, and Spring Boot

To recap, Micronaut, Quarkus, and Spring Boot all support building native executables with GraalVM. Yes, there are other frameworks, but these three seem to be the most popular.

The commands to build each app are similar but not quite the same.

  • Micronaut: ./mvnw package -Dpackaging=native-image

  • Quarkus: ./mvnw package -Pnative

  • Spring Boot: ./mvnw spring-boot:build-image

Of course, they all support Gradle too.

Startup Time Comparison

Performance comparisons are complex, but I’m going to do one anyway. Since this post is all about native Java, below is the data I gathered that shows the average milliseconds to start each native executable. I ran each image three times before I started recording the numbers. I then ran each command five times.

These numbers are from a 2019 MacBook Pro with a 2.4 GHz 8-Core Intel Core i9 processor and 64 GB of RAM. I think it’s important to note that my WiFi connection was 340 Mbps down and 246 Mbps up (according to the Speedtest app).

Table 1. Native Java Startup times in milliseconds
Framework Command executed Milliseconds to start

Micronaut

./target/app

20.4

Quarkus

./target/quarkus-1.0.0-SNAPSHOT-runner

13.4

Spring Boot

docker run -p 8080:8080 docker.io/library/demo:0.0.1-SNAPSHOT

60.6

The chart below should help you visualize this comparison.

The Spring Boot startup times looked a little long, so I contacted my friend Josh Long. We did a debugging session over Zoom and discovered the longer startup times are because Spring Security is doing OIDC discovery with the issuer.

Spring Boot’s "initialization completed" time seemed to be right around 30ms. The duration between that and the "Started in …​" time is the time it takes to make the call to Okta. We tried optimizing it by just using the JWKS URI. For example:

spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://dev-133337.okta.com/oauth2/default/v1/keys

This only improved the startup time by 1.6ms (59ms on average).

We also experimented with using ./mvnw package -Pnative for Spring Boot. This allows you to create a native binary and run it with ./target/demo. There’s no need for Docker with this command. Startup times are relatively the same in my and Josh’s experience.

Our hypothesis is Micronaut and Quarkus do the JWKS lookup on the first request rather than at startup. That’s how they achieve faster startup times.

We later confirmed this hypothesis with Jason Schindler (from Micronaut) and Sergey Beryozkin (from Quarkus).

If I just take the value of the "initialization completed" time from Spring Boot, the numbers look a little more even.

I also tested the startup times on a Linux laptop with 64 GB of RAM. I used the value the framework displays for startup time and did not make the "initialization complete" adjustment for Spring Boot.

If you disagree with these numbers and think X framework should be faster, I encourage you to clone the repo and run these tests yourself. If you get faster startup times for Spring Boot, do you get faster startup times for Micronaut and Quarkus too?

Testing Native Images

When building native images, it’s essential to test them as part of an integration testing process. This post is already long enough, so I won’t explain how to test native images in this post. We’ll publish a post in the future that covers this topic.

I do like how Quarkus generates a NativeHelloResourceIT that’s designed specifically for this, though.

package com.okta.rest.quarkus;

import io.quarkus.test.junit.NativeImageTest;

@NativeImageTest
public class NativeHelloResourceIT extends HelloResourceTest {

    // Execute the same tests but in native mode.
}

However, this test did not help me detect an issue with my Quarkus native image when writing this post. That’s because I was lazy in writing my test and changed it to confirm a 401 instead of testing it with Quarkus' OIDC testing support.

Learn More About Java and GraalVM

In this post, you learned how to develop, build, and run native Java apps with Micronaut, Quarkus, and Spring Boot. You learned how to secure them with OpenID Connect and access them with a JWT access token.

If you’re a Spring Boot aficionado, I recommend you watch Josh Long’s Spring Tips: Spring Native 0.10.0 video.

You can find the source code for all the examples used in this post on GitHub in the native-java-examples repository.

Server-side apps that serve up REST APIs aren’t the only thing that’s gone native in Java. Gluon has done a lot of work in recent years to make JavaFX apps work on iOS and Android using GraalVM. See Gail Anderson's Creating Mobile Apps with JavaFX – Part 1 to learn more about this emerging technology.

In the beginning, I mentioned JNI and JNA. Baeldung has some tutorials about both:

If you liked this post, chances are you’ll like others we’ve published:

Got questions? Leave them in the comments below! You can also hit us up on our social channels: @oktadev on Twitter, Okta for Developers on LinkedIn, Twitch, and YouTube.

Matt Raible is a well-known figure in the Java community and has been building web applications for most of his adult life. For over 20 years, he has helped developers learn and adopt open source frameworks and use them effectively. He's a web developer, Java Champion, and Developer Advocate at Okta. Matt has been a speaker at many conferences worldwide, including Devoxx Belgium, Devoxx France, Jfokus, and Devnexus. He is the author of The JHipster Mini-Book, Spring Live, and contributed to Pro JSP. He is frequent contributor to open source and a member of the JHipster development team. You can find him online @mraible and raibledesigns.com.