Secure a Micronaut app with Cognito

Learn how to create Micronaut app and secure it with an Authorization Server provided by Cognito.

Authors: Sergio del Amo

Micronaut Version: 1.2.7

1 Getting Started

In this guide we are going to create a Micronaut app written in Java.

1.1 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

1.2 Solution

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.


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

2 Writing the App

Create an app using the Micronaut Command Line Interface.

mn create-app example.micronaut.complete

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.

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



Although Micronaut is primarily designed around message encoding / decoding, there are occasions where it is convenient to render a view on the server side.

To use the view rendering features, add the following dependency on your classpath. For example, in build.gradle

dependencies {
    implementation "io.micronaut:micronaut-views-thymeleaf"

To use Thymeleaf Java template engine, add the thymeleaf dependency:

dependencies {
    runtime "org.thymeleaf:thymeleaf:3.0.11.RELEASE"

2.2 OAuth 2.0

To provide authentication, sign in to your AWS account and go to AWS Cognito.

With the Amazon Cognito SDK, you just write a few lines of code to enable your users to sign-up and sign-in to your mobile and web apps.

Standards-based authentication

Amazon Cognito uses common identity management standards including OpenID Connect, OAuth 2.0, and SAML 2.0.

First, create an Amazon Cognito User Pool:

Amazon Cognito User Pools - A directory for all your users

You can quickly create your own directory to sign up and sign in users, and to store user profiles using Amazon Cognito User Pools. User Pools provide a user interface you can customize to match your app. User Pools also enable easy integration with social identity providers such as Facebook, Google, and Amazon, and enterprise identity providers such as Microsoft Active Directory through SAML.

aws cognito 1
aws cognito 2

Amazon Cognito Pools are regional. Thus, annotate the region you are using.

While you setup the Amazon Cognito User Pool, you will need to save the pool id:

aws cognito 3

Configure the appropriate callback, make sure you allow Authorization code grant OAuth Flow, and also the scopes openid and email are selected.

aws cognito 5

Save the client id and client secret:

aws cognito 4

To use OAuth 2.0 integration, add the next dependency:
dependencies {
    implementation "io.micronaut.configuration:micronaut-security-oauth2"

Add also JWT Micronaut’s JWT support dependencies:

dependencies {
    annotationProcessor "io.micronaut:micronaut-security"
    implementation "io.micronaut:micronaut-security-jwt"

Add the following Oauth2 Configuration:

    enabled: true (1)
      enabled: true
        cognito: (2)
          client-secret: '${OAUTH_CLIENT_SECRET}' (3)
          client-id: '${OAUTH_CLIENT_ID}' (4)
            issuer: 'https://cognito-idp.${COGNITO_REGION}${COGNITO_POOL_ID}/' (5)
        enabled: true (6)
          enabled: true (7)
              secret: pleaseChangeThisSecretForANewOne
        enabled: true (8)
        get-allowed: true (9)
1 Enable security
2 The provider identifier should match the last part of the url you entered as a redirect url /oauth/callback/cognito
3 Client Secret. See previous screenshot.
4 Client ID. See previous screenshot.
5 issuer url. It allows micronaut to discover the configuration of the OpenID Connect server. Note: we will use the pool id and region mentioned previously.
6 ID Token is a JWT token. We need to enable Micronaut’s JWT support to validate it.
7 Once validated, we are going to save the ID Token in a Cookie. To read in subsequent requests, enable Cookie Token Reader.
8 Enable Logout Controller
9 Accept GET request to the /logout endpoint.

The previous configuration uses several placeholders. You will need to setup OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, COGNITO_REGION and COGNITO_POOL_ID environment variables.

export COGNITO_REGION=eu-west-1

Although undocumented in the Amazon Cognito User Pools Auth API Reference, Cognito provides an openid-configuration endpoint which is used by Micronaut to configure your app.


We want to use an Authorization Code grant type flow which it is described in the following diagram:


2.3 Home

Create a controller to handle the requests to /. You are going to display the email of the authenticated person if any. Annotate the controller endpoint with @View since we are going to use a Thymeleaf template.

package example.micronaut;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.views.View;

import java.util.HashMap;
import java.util.Map;

@Controller (1)
public class HomeController {

    @Secured(SecurityRule.IS_ANONYMOUS) (2)
    @View("home") (3)
    @Get (4)
    public Map<String, Object> index() {
        return new HashMap<>();
1 The class is defined as a controller with the @Controller annotation mapped to the path /.
2 Annotate with to configure secured access. The SecurityRule.IS_ANONYMOUS expression will allow access without authentication.
3 Use View annotation to specify which template would you like to render the response against.
4 The @Get annotation is used to map the index method to GET / requests.

Create a thymeleaf template:

<!DOCTYPE html>
<html xmlns:th="">
<h1>Micronaut - Cognito example</h1>

<h2 th:if="${security}">username: <span th:text="${security.attributes.get('email')}"></span></h2>
<h2 th:unless="${security}">username: Anonymous</h2>

        <li th:unless="${security}"><a href="/oauth/login/cognito">Enter</a></li>
        <li th:if="${security}"><a href="/oauth/logout">Logout</a></li>

Also, note that we return an empty model in the controller. However, we are accessing security in the thymeleaf template.

3 Running the Application

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


4 Learn More

Read Micronaut OAuth 2.0 documentation to learn more.

5 Help with Micronaut

OCI sponsored the creation of this Guide. OCI offers several Micronaut services:

Free consultation

The OCI Micronaut Team includes Micronaut co-founders, Jeff Scott Brown and Graeme Rocher. Check our Micronaut courses and learn from the engineers who developed, matured and maintain Micronaut.

Micronaut OCI Team