Groovy / Maven

Client Credentials Flow with Micronaut and Auth0

Learn how to use Client Credentials Flow between Micronaut microservices with an Authorization Server provided by Auth0.

Sergio del Amo

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Groovy.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately
An Auth0 account.

Solution

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

Download and unzip the source

Application Diagram

Download the complete solution of the guide. You will use the sample app as a starting point. The application contains three microservices:

bookcatalogue - This returns a list of books. It uses a domain consisting of a book name and an ISBN.
bookinventory - This exposes an endpoint to check whether a book has sufficient stock to fulfil an order. It uses a domain consisting of a stock level and an ISBN.
bookrecommendation - This consumes previous services and exposes an endpoint that recommends book names that are in stock.

The bookcatalogue service consumes endpoints exposed by the other services. The following image illustrates the original application flow:

A request to bookrecommendation (http://localhost:8080/books) triggers several requests through our microservices mesh.

In this guide, you are going to secure the communication between the microservices. You will use a client credentials flow and obtain an access token from an Auth0 authorization server.

OAuth 2.0

To provide authentication, sign in to your Auth0 account.

Create an application

Obtain client id and client secret

You can obtain the application’s domain, client id, and secret in the Auth0 console.

Obtain API audience

Go to Applications → APIs and copy the API Audience:

Authorize application

In the API Settings, authorize the application in the Machine to Machine Applications tab:

Writing the application

Setup IntelliJ IDEA to develop Micronaut Applications.

Dependencies

Modify every application (bookcatalogue, bookinventory, and bookrecommendation). Add Micronaut JWT and Micronaut OAuth 2.0 dependencies:

pom.xml

<dependency>
    <groupId>io.micronaut.security</groupId>
    <artifactId>micronaut-security-oauth2</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.security</groupId>
    <artifactId>micronaut-security-jwt</artifactId>
    <scope>compile</scope>
</dependency>

Changes to Book Inventory service

Annotate the controller’s method with @Secured:

bookinventory/groovy/src/main/groovy/example/micronaut/BooksController.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.Produces
import jakarta.validation.constraints.NotBlank
import static io.micronaut.http.MediaType.TEXT_PLAIN
import static io.micronaut.security.rules.SecurityRule.IS_AUTHENTICATED;
import io.micronaut.security.annotation.Secured

@CompileStatic
@Controller("/books")
class BooksController {

    @Produces(TEXT_PLAIN)
    @Get("/stock/{isbn}")
    @Secured(IS_AUTHENTICATED) // 
    Boolean stock(@NotBlank String isbn) {
        bookInventoryByIsbn(isbn).map(bi -> bi.stock > 0).orElse(null)
    }

    private Optional<BookInventory> bookInventoryByIsbn(String isbn) {
        if (isbn == "1491950358") {
            return Optional.of(new BookInventory(isbn, 4))
        }
        if (isbn == "1680502395") {
            return Optional.of(new BookInventory(isbn, 0))
        }
        Optional.empty()
    }
}

1	Annotate with `io.micronaut.security.Secured` to configure secured access. The `SecurityRule.IS_AUTHENTICATED` expression allows only access to authenticated users.

To validate the tokens issued by Auth0, configure Validation with Remote JWKS:

bookinventory/src/main/resources/application.properties

micronaut.security.token.jwt.signatures.jwks.auth0.url=${OAUTH_JWKS:`https://micronautguides.eu.auth0.com/.well-known/jwks.json`}

You can obtain the JWKS URL in the .well-known/openid-configuration endpoint.

Changes to Book Catalogue service

Annotate the controller’s method with @Secured:

bookcatalogue/groovy/src/main/groovy/example/micronaut/BooksController.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.security.annotation.Secured
import static io.micronaut.security.rules.SecurityRule.IS_AUTHENTICATED

@CompileStatic
@Controller("/books")
class BooksController {

    @Get
    @Secured(IS_AUTHENTICATED) // 
    List<Book> index() {
        [
            new Book("1491950358", "Building Microservices"),
            new Book("1680502395", "Release It!"),
            new Book("0321601912", "Continuous Delivery:")
        ]
    }
}

1	Annotate with `io.micronaut.security.Secured` to configure secured access. The `SecurityRule.IS_AUTHENTICATED` expression allows only access to authenticated users.

To validate the tokens issued by Auth0, configure Validation with Remote JWKS:

bookcatalogue/src/main/resources/application.properties

micronaut.security.token.jwt.signatures.jwks.auth0.url=${OAUTH_JWKS:`https://micronautguides.eu.auth0.com/.well-known/jwks.json`}

You can obtain the JWKS URL in the .well-known/openid-configuration endpoint.

Changes to Book Recommendations service

Books Controller Security

The GET /books endpoint in the bookrecommendation service is open.

Annotate the controller’s method with @Secured:

bookrecommendation/groovy/src/main/groovy/example/micronaut/BookController.groovy

package example.micronaut

import groovy.transform.CompileStatic
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import org.reactivestreams.Publisher
import reactor.core.publisher.Flux
import static io.micronaut.security.rules.SecurityRule.IS_ANONYMOUS
import io.micronaut.security.annotation.Secured

@CompileStatic
@Controller("/books")
class BookController {

    private final BookCatalogueOperations bookCatalogueOperations
    private final BookInventoryOperations bookInventoryOperations

    BookController(BookCatalogueOperations bookCatalogueOperations,
                   BookInventoryOperations bookInventoryOperations) {
        this.bookCatalogueOperations = bookCatalogueOperations
        this.bookInventoryOperations = bookInventoryOperations
    }

    @Get
    @Secured(IS_ANONYMOUS) // 
    Publisher<BookRecommendation> index() {
        Flux.from(bookCatalogueOperations.findAll())
                .flatMap(b -> Flux.from(bookInventoryOperations.stock(b.isbn))
                        .filter(Boolean::booleanValue)
                        .map(rsp -> b)
                ).map(book -> new BookRecommendation(book.name))
    }
}

1	Annotate with `io.micronaut.security.Secured` to configure secured access. The `SecurityRule.IS_ANONYMOUS` expression will allow access without authentication.

Configuration of HTTP Services URLs

Modify application-dev.properties to point the declarative HTTP clients to the other microservice URLs.

bookrecommendation/src/main/resources/application-dev.properties

micronaut.http.services.bookcatalogue.url=http://localhost:8081
micronaut.http.services.bookinventory.url=http://localhost:8082

Configuration

Add the following OAuth2 configuration:

bookrecommendation/src/main/resources/application.properties

# 
micronaut.security.oauth2.clients.auth0.client-id=${OAUTH_CLIENT_ID:xxx} 
micronaut.security.oauth2.clients.auth0.client-secret=${OAUTH_CLIENT_SECRET:yyy} 
micronaut.security.oauth2.clients.auth0.grant-type=client_credentials 
micronaut.security.oauth2.clients.auth0.token.url=${OAUTH_TOKEN_URL:`https://micronautguides.eu.auth0.com/oauth/token`} 
micronaut.security.oauth2.clients.auth0.token.auth-method=client_secret_post 
micronaut.security.oauth2.clients.auth0.client-credentials.service-id-regex=bookcatalogue|bookinventory 
micronaut.security.oauth2.clients.auth0.client-credentials.additional-request-params.audience=${AUTH0_API_IDENTIFIER:`https://micronautguides.eu.auth0.com/api/v2/`}

1	OAuth 2.0 client name.
2	Client ID. See previous screenshot.
3	Client secret. See previous screenshot.
4	Specify GrantType#CLIENT_CREDENTIALS `client-credentials` as grant type for this OAuth 2.0 client.
5	Specify the token endpoint URL. You can obtain the token endpoint URL in the `.well-known/openid-configuration`.
6	Specify AuthenticationMethod#CLIENT_SECRET_POST as the authentication method. This means the client id and client secret are specified in the body of the HTTP request sent to the token endpoint.
7	Propagate the access token obtained from Auth0 to requests sent to the services `bookinventory` and `bookcatalogue`. This uses the Micronaut Client Credentials HTTP Client Filter.
8	Auth0 requires the API Identifier with an audience key in the token endpoint request for the client credentials flow.

The previous configuration uses several placeholders with default values. You will need to set up OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, and OAUTH_TOKEN_URL environment variables in your Auth0 application.

export OAUTH_CLIENT_ID=XXXXXXXXXX
export OAUTH_CLIENT_SECRET=YYYYYYYYYY
export OAUTH_TOKEN_URL=https://micronautguides.eu.auth0.com/oauth/token

Running the Application

Run `bookcatalogue` microservice

To run the application, execute ./mvnw mn:run.

...
14:28:34.034 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 499ms. Server Running: http://localhost:8081

Run `bookinventory` microservice

To run the application, execute ./mvnw mn:run.

...
14:31:13.104 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 506ms. Server Running: http://localhost:8082

Run `bookrecommendation` microservice

To run the application, execute ./mvnw mn:run.

...
14:31:57.389 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 523ms. Server Running: http://localhost:8080

You can run a cURL command to test the whole application:

curl http://localhost:8080/books

[{"name":"Building Microservices"}]

Next Steps

Read Micronaut OAuth 2.0 Documentation to learn more.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).

Getting Started

What you will need

Solution

Application Diagram

OAuth 2.0

Create an application

Obtain client id and client secret

Obtain API audience

Authorize application

Writing the application

Dependencies

Changes to Book Inventory service

Changes to Book Catalogue service

Changes to Book Recommendations service

Books Controller Security

Configuration of HTTP Services URLs

Configuration

Running the Application

Run bookcatalogue microservice

Run bookinventory microservice

Run bookrecommendation microservice

Next Steps

Help with the Micronaut Framework

License

Run `bookcatalogue` microservice

Run `bookinventory` microservice

Run `bookrecommendation` microservice