Java Microservices, Micronaut, Microservices

Micronaut OAuth2 Keycloak Example That Works


This post shows how to use Micronaut applications that use OAuth2 with Keycloak in a Microservice context. Furthermore, it uses two Micronaut applications. The first application allows users (or programs) to log in and acquire JWT tokens. On the other hand, the second application allows users (or programs) to access its secure resources using valid JWT tokens acquired from the first program.


The following are the items we used for this post.

  • JDK 14 ( AdoptOpenJDK 14.0.2 64-bit for Windows)
  • Micronaut 2.4.2
  • IntelliJ IDEA 2021.3 ( Build #IU-211.6693.111)
  • KeyCloak 12.0.4 Docker Image
    • NOTE: Version 12.0.2 has an issue wherein the container keeps on restarting after the machine rebooted
  • Windows 10
  • Docker for Windows

Start A KeyCloak Docker Container Up

Before we generate Micronaut applications in IntelliJ, let’s start up a KeyClock instance. We’ll use the following docker-compose.yml file.

First, we save this file in some directory. Second, open a command-line window and change to that directory. Then, run the following command.

Once the KeyCloak is up and running, as shown below, open a browser and go to http://localhost:8280/auth/.

Then, we configure some stuff in KeyCloak.

Configure KeyCloak For Micronaut OAuth2 Authentication And Authorization

As an Identity server, KeyCloak authenticates and authorizes users who access our Micronaut applications. Therefore, we need to configure KeyCloak and add initial users to test our OAuth2 locally. We proceed by creating a new Realm called


Next, we create a client. Fill in the Client ID and Valid Redirect URIs; set Access Type to confidential, and Direct Access Grants Enabled to On.

Micronaut OAuth2 Keycloak


Then, save it and switch to the Credentials tab to copy the Secret value. We will use this value in our Micronaut applications.

Create Users and Roles in KeyCloak

Then, we create some users and roles in KeyCloak to test OAuth2 with our Micronaut application.

Micronaut OAuth2 Keycloak

NOTE: Don’t forget to see the users’ passwords, e.g., password12345. Also, make sure the Required User Actions field is empty. Lastly, map the admin role to user_admin and map viewer role to user_viewer.

Micronaut OAuth2 Keycloak

NOTE: Map user user_admin to admin role; and user user_viewer to viewer role.

Then, we update the Realm Roles as follows. Set Token Claim Name to roles.

Create The First Micronaut Application and Configure OAuth2 Configuration To Use KeyCloak

Once we’re done with KeyCloak, we can generate and configure the Micronaut application to use OAuth2 with KeyCloak. It will act as our central log-in/log-out service. First, fill in information for Group and Artifact.

Micronaut Keycloak


Then, include the following features – Netty Server, Micronaut HTTP Client, Micronaut Security, Micronaut Security JWT, Micronaut Security OAuth 2.0, and Project Lombok. We will also use these dependencies later for the second Micronaut application.

Micronaut Keycloak


Click Finish to generate the project and create two new files, as shown below.


This class represents a KeyCloak user but with not sensitive information.

Create Another File

We use the KeycloakUserDetailsMapper to map the information received from KeyCloak to an instance of KeycloakUser after successful authentication. The information includes username, roles, and access token. Then, the code returns the user details to the client.

Update The application.yml File

Finally, update the application.yml file as follows.

Testing With Micronaut And KeyCloak With Postman

Create a new request that uses HTTP POST, and supply JSON data with username and password fields. Then, send the request.


Testing With Micronaut And KeyCloak With Curl

Run the following command on the Window command-line terminal.

Then, we get the following result.

This is all good, but the application returns an HTTP 303 (Redirect). We would expect an HTTP 200. Moreover, when we send invalid user credentials, the server returns HTTP 500 instead of HTTP 401.


Next, we’re going to create the second Micronaut application. Keep the first application and KeyCloak running.

Create The Second Micronaut Application and Configure OAuth2 Configuration To Use KeyCloak

Create a new Micronaut application as follows and use the same set of dependencies previously used. The new application runs on post 8081.

Next, we create some source code files. However, we can reuse the KeycloakUser and KeycloakUserDetailsMapper classes in this new application.

The following is the content of SampleController class.

Finally, we update the application.yml file.

Then, start this second Micronaut application up! Next, we retrieve the access token from the first application and access a secured URI in the second application.

Copy the access token and use it in HTTP GET request to the second Micronaut application, as shown below.

We can still improve these basic examples and their configuration. For example, we could use Distributed Configuration, Service Registration, and Discovery with Consul, and even run all the applications in Docker containers.

You Might Also Like